flows: flows deploy — publish immutable bundle to a bucket + pin trigger to digest (SURFACE §4 follow-up to #298)

[kjgbot]

SURFACE.md §4 quote (lines 435-438)

flows build seals a flow into a content-addressed, immutable bundle: canonical spec JSON, compiled TS with pinned deps, helper/plugin lockfile, assets, preflight declaration, identity signature — flow@sha256:…, pushed to a bucket/registry. flows deploy points a trigger at a digest; flows run flow@sha256:… executes from the bucket on any cell, no checkout. Preflight runs at build time for everything build-provable and again at deploy time for environment facts (credentials, workers, MCP servers). The working tree is for authoring; production only ever runs digests.

Depends on

• flows: content-addressed immutable bundle (flows build) — SURFACE §4 #298 (slice A, flows build) merged (2026-09-11). Bundle format is defined; this issue makes it deployable.

Scope

1. flows deploy <flow-name>@<digest> --to <bucket-uri> — uploads the local bundle to a content-addressed bucket.
   • First-slice URI schemes: file:// (local filesystem) + one S3-compatible URI (e.g. s3://bucket/prefix). Additional schemes are follow-ups.
   • Deploy is idempotent: re-deploying the same digest is a no-op with a deploy_noop diagnostic on stderr.
   • Deploy-time preflight runs (environment facts: bucket writable, credentials present).
2. flows run <flow-name>@sha256:<hex> — fetches the bundle from the configured bucket by digest, verifies its identity signature, executes.
   • --bucket <uri> explicit override; else uses flows.json deploy.bucket field.
   • Bundle is cached locally under $XDG_CACHE_HOME/flows/bundles/<digest>/ so a second run doesn't re-fetch.
3. Trigger executor accepts a digest as its target. Configuration:

   # flows.json or a trigger declaration
   trigger:
     kind: webhook
     digest: sha256:abc...

   Locks the run to that content — no working-tree fallback.

Not in scope

• Content-signing key rotation (out-of-band ops task)
• Multi-bucket replication
• GC of old digests
• Bucket lifecycle policies
• The registry side of "bucket/registry" (SURFACE line 437 leaves that split ambiguous — start with pure bucket)

Acceptance

• flows deploy hello@sha256:abc --to file:///tmp/bucket copies the bundle to /tmp/bucket/hello/sha256/abc/ with a verifiable layout.
• flows run hello@sha256:abc --data-dir /tmp/dir fetches from file:///tmp/bucket, verifies signature, executes to completionReason: success.
• An invalid or tampered digest fails with bundle_signature_invalid refusal (exit 2) before any journal write.
• flows.json with deploy.bucket: file:///tmp/bucket and a trigger config digest: sha256:abc locks the run to that content — attempting to run at a different digest is refused.

Files (likely)

• packages/sdk/src/cli/deploy.ts (new)
• packages/sdk/src/bundle-transport.ts (new — file:// + s3:// scheme handlers)
• packages/sdk/src/cli.ts (wire deploy verb; wire run <flow>@sha256:... digest input path)
• packages/sdk/src/cli/run.ts (add digest input handling parallel to <flow.yaml|spec.json> + <flow.ts>)
• packages/sdk/tests/deploy.test.ts (new)
• packages/sdk/tests/run-from-digest.test.ts (new)

Written by codex agent spec-Adep-flows-deploy — deployed after slice A's #316 merge.

[kjgbot]

Signing scheme decision — ed25519

Choosing ed25519 over HMAC for bundle signing:

• Asymmetric: verifiers hold public key only. HMAC would require the shared secret at every verifier, which doesn't scale beyond a single trust boundary and leaks the sign capability if any verifier is compromised.
• Standard for content-addressed distribution: git commit signing, minisign, cosign, SSH keys, Signal, WireGuard — the entire class of "publish once, verify many" uses asymmetric signatures. Match the ecosystem.
• Small keys, small signatures: 32-byte public key, 64-byte signature. Cheap for the bundle manifest.
• Deterministic signing: same input → same signature, matching the content-addressed contract.

Concretely for this slice:

• Signing key generated per publisher (e.g. flows keygen), stored at ~/.flows/keys/<name>.
• flows deploy signs manifest.json's canonical form + writes manifest.json.sig beside it in the bundle.
• flows run <flow>@sha256:<hex> fetches bundle + verifies signature against a declared trust set (initially ~/.flows/trusted-keys/).
• Signature failure = refusal bundle_signature_invalid.
• Key rotation deferred to a follow-up (a signed successor manifest via chain-of-signatures).

Fine to proceed with this shape.