Module workflow 

The agent-safe workflow commands (harness #140): fz plan, fz deploy --plan <digest>, fz add, fz init and fz verify. They work on the venture manifest — the desired composition — and two on-disk records: the migration lockfile (.harness-lock.json) and the deploy record (.harness-deploy.json) that fz deploy writes. They never run wrangler, never touch a database and never prompt: turning the recorded composition into a running Worker stays with worker-build and wrangler deploy, and applying migrations stays with fz migrations collect / wrangler d1 migrations apply — the same needs-human boundary fz build draws.

Every command speaks the two disciplines fz doctor --json established (harness #140). With --json it prints exactly one JSON object on stdout — schema 1, ok, the failures each carrying a stable code from crate::codes — and nothing else. Without it the output is prose for the operator. --non-interactive is accepted on every command: the workflow never prompts by construction, so the flag’s one effect is suppressing the human next: steps from prose output; anything that would need a human is a coded refusal, never a blocked process.

PlanContent is the whole normalised plan; its sha256 (fz plan --json’s digest) is the approval token. fz deploy recomputes the plan from the current inputs and refuses any other digest — a stale approval cannot deploy — and records the plan it applied. fz verify diffs that record against the manifest and reports the drift as coded failures in the doctor’s JSON shape.

Structs

AddOutcome

The outcome of fz add.

Baseline

What the plan diffed against, and the slugs it saw there.

Capability

What one added module needs, as the catalog declares it.

Consent

The two consents fz deploy can require, kept apart on purpose.

DeployOutcome

The outcome of fz deploy.

DeployRecord

A recorded deployment. plan is the full PlanContent that was applied, so fz verify can name precisely which part of the manifest drifted, and a stale fz deploy can name what moved.

MigrationState

Migration status, read from the lockfile. The manifest world cannot know whether a module ships migrations at all — only what has been collected — so not_collected means “no locked migration exists”, phrased exactly that way in output.

PlanContent

The full plan: the destination (PlanState, flattened on the wire, the only part the digest hashes) plus the deltas against the current baseline — the deploy record when one exists, else the modules the migration lockfile knows. Every list is sorted and every map ordered, so output is a pure function of the inputs.

PlanOutcome

The outcome of fz plan: the normalised content and its digest.

PlanState

The destination a plan describes: what the venture will become, independent of what it is now. The sha256 over this struct’s JSON is the plan digest — the approval token — because an approval is of the destination, not of the journey: the baseline-dependent deltas (PlanContent’s added/removed lists) describe the journey and change the moment a deployment is recorded, so hashing them would make every deploy stale by its own success.

SelectedModule

One manifest module reference, normalised: the slug and its per-module config (empty for the bare-slug form).

VerifyOutcome

The outcome of fz verify: the doctor-shaped report plus the recomputed digest when the manifest resolved far enough to compute one.

Constants

RECORD_FILE

The deploy record fz deploy writes next to the manifest: the plan it applied, bound to the digest that approved it.

SCHEMA

The schema field of every workflow JSON object — the same wire contract fz doctor --json carries (crate::doctor::REPORT_SCHEMA).

Functions

add

fz add <module>: adds a module to the manifest’s desired composition and nothing else — it never deploys, never provisions and never touches a database. Adding a module the manifest already lists is a no-op that succeeds with changed: false.

add_cli

The fz add CLI entry: both output disciplines.

deploy

fz deploy --plan <digest>: applies exactly the approved plan — by recording it, bound to its digest, in .harness-deploy.json beside the manifest. It refuses:

deploy_cli

The fz deploy CLI entry: both output disciplines.

init

fz init: writes a new venture manifest — name and host, no modules yet. Refuses to overwrite an existing manifest unless --force.

init_cli

The fz init CLI entry: both output disciplines.

plan

fz plan: describes what the manifest would change, and nothing else. Read-only by construction — nothing here touches the disk beyond reading its inputs.

plan_cli

The fz plan CLI entry: both output disciplines.

verify

fz verify: diffs the recorded deployment against the manifest and reports every drift as a coded failure in the doctor’s shape — composition, config, environment, and (when nothing narrower explains it) the recorded digest no longer matching a recomputed plan.

verify_cli

The fz verify CLI entry: both output disciplines. The JSON shape is the doctor’s, byte for byte.