Plans and operations

Cloud work is rarely one atomic transaction. Bahama makes each operation reviewable and recoverable by separating planning from execution and requiring every step to state what success will look like.

Your coding agent handles these mechanics. You see the parts that affect your accounts, resources, data, or production application.

A plan is an exact artifact

bahama plan combines:

• the validated bahama.yaml intent;
• the current bahama.lock identities and binding edges;
• selected provider accounts and read-only live observations;
• migration files and protected provider configuration; and
• ordered provider steps, dependencies, effects, and postconditions.

The result receives a content-derived ID such as plan_7f4c9b21a3d0. Bahama stores the immutable plan locally and verifies its content again before apply. An edited, corrupt, or hand-made plan is rejected.

Routine work and consequential work

Providers describe the effect of each step. Bahama’s central engine decides whether that effect needs approval.

Routine work preserves an already verified setup. Examples include:

• read-only verification;
• a code-only redeployment with an established local baseline; and
• rotating a secret along the exact same recorded binding.

Consequential work includes:

• creating or adopting a resource;
• selecting or changing a provider account;
• applying a database migration;
• the first application deployment;
• adding or rewiring a secret binding;
• changing provider runtime or build configuration;
• correcting a live framework mismatch; and
• any mutation whose effects cannot be classified safely.

Unknown mutations require approval by default. A provider cannot label its own operation routine.

Approval is bound to the plan

When the plan contains consequential steps, your agent shows you their summaries, reasons, and provider accounts. After you approve, it runs:

bahama apply plan_7f4c9b21a3d0 --approved

The approval covers only that plan. A changed manifest, lock, migration, account, or protected provider configuration requires a new plan and review.

Source-code edits do not invalidate an infrastructure plan. Apply packages the source present at execution time and records what was actually deployed.

Deploy has a safe fast path

bahama deploy production compiles a deployment plan and applies it automatically only when every step is routine.

This supports the normal coding loop: ask your agent to make a change, let it test the application, and deploy the update. If the operation contains a new resource, migration, binding, provider-config change, or another consequential effect, deploy stops and gives you a plan to review.

There is no flag that forces consequential deployment through the fast path.

Each step verifies its own result

During apply, Bahama executes steps in dependency order. A provider command returning successfully is not enough: the provider must check the planned live postcondition before the step is complete.

Examples include confirming that a project exists in the planned account, a migration checksum is recorded, an environment-variable name is present, or a production URL responds.

Verified identity is written atomically to bahama.lock. Redaction-safe receipts are appended to .bahama/operations.ndjson for local recovery.

Interrupted work can resume

Only one mutating Bahama operation can run against a project at a time. If an apply fails or is interrupted, the agent first follows the returned recovery guidance.

When the same plan remains valid, applying it again rechecks completed postconditions and resumes at the first unfinished step. It does not blindly create a second copy of a resource after a timeout.

A fully completed plan is not cached forever. Running it later is a fresh, idempotent execution rather than a permanent skip.

Secrets stay out of serialized state

A provider that produces a secret gives Bahama an opaque in-memory reference. The raw value is registered with the redactor and released only to the exact consuming step that needs it.

Plans, locks, receipts, logs, and command results carry at most a secret name and one-way fingerprint. If an interrupted operation needs the value again, Bahama re-derives it from the provider instead of loading it from disk.