Trusted merge and production release#

This is the normative normal Forge infrastructure-release contract. Its machine-readable form is ../../config/forge-release-system.json. It does not govern ordinary Forge Deploy application activation or an authorized direct Wrangler repair of Forge's own impaired release machinery; those boundaries are defined in ../operations/production-deployment.md.

Preview, merge, build, publish#

Pull requests are serialized through one dedicated fpv-cell-* platform stack with preview-only D1, R2, dispatch, analytics, and container resources. A D1 owner row grants exactly one active validation a monotonic cell generation. Candidate D1 migrations run before version upload; provider versions, deployments, bindings, and probe receipts remain bound to the exact validation SHA and cell generation even though the Worker names are stable. Interrupted attempts may perform one bounded readback of their exact provider identity; they never blindly republish or resume a resource rollout.

The trusted base probe contract always requires /health and /health/dependencies to return { "ok": true } at status 200 and /register to contain the invite-code marker. Repository configuration may add probes but cannot remove or weaken those requirements. Runner Dockerfile, Wrangler container configuration, and toolchain changes build inside the rootless-DinD preview runner. The exact image digest is attached to a private attempt-derived preview host/application, read back from Cloudflare, and selected by the stable preview runner Worker binding before deep health. A partial or mismatching existing host fails that attempt and is never repaired in place; a new attempt derives a new write-once artifact set.

RepoLock serializes merges. Its final D1 transaction rechecks current preview configuration and every immutable validation/probe fact, appends one forge_main_generations row, advances the target ref with compare-and-swap, and marks the pull request and queue entry merged. This transaction never queries Cloudflare production readiness.

The resulting main push invokes Production Builder. The builder materializes only the exact merged main SHA, installs dependencies, compiles, and uploads a zero-traffic immutable version for each project affected by that direct main update. Projects build independently. The signed upload broker is stateless and may persist build evidence, but cannot change traffic.

For runner, the complete build includes a digest-pinned image and one private write-once host/application derived from SHA, main generation, workflow run, and workflow attempt. The stable runner version has no local container application; its external Sandbox binding selects that host. The builder may create and read these unreferenced artifacts, but only ProductionDeployer may publish or restore the stable runner deployment. There is no host/application lane, current pointer, repair loop, or D1 authority.

Each ready row contains project/environment, full source SHA, main generation, workflow run and attempt, exact-main release manifest, provider script/version and tag, manifest/artifact/content/binding/upload-receipt digests, state, and timestamps. A failed sibling does not discard ready versions.

Per-project lifecycle#

requested -> building -> ready -> publishing -> published
                 |          |          |
                 +----------+----------+-> failed
                            +------------> superseded

Retries create a new immutable attempt. Ready versions are never silently deleted. The publication lane always selects the newest eligible ready main generation, not the build that finishes last. Once generation N publishes, any older requested or ready row in that lane becomes explicitly superseded.

Each Worker is an independent deployment unit. There is no global platform candidate, component operation, dependency wave, cumulative production baseline, or controller ceremony. Services that cannot be versioned independently must be combined into one Worker.

The ProductionDeployer boundary#

One Durable Object per environment/project stores only its monotonic fence, published-generation floor, and exact in-flight deployment ID. It does not store source, manifests, provider credentials, health, build phases, or an active-version pointer.

For the selected ready row, the deployer:

1. verifies the stored exact-main manifest and immutable Cloudflare version;
2. reads and records the exact current 100% deployment/version immediately before mutation;
3. rechecks expected current under the exclusive stable-deployment writer, creates a target-only 100% deployment, and reads it back exactly;
4. verifies exhaustive bindings plus only manifest-declared generic identity, /health, and /health/dependencies observations;
5. atomically marks the row terminal and appends its receipt; or
6. after a post-traffic failure, restores the recorded prior version only while the failed deployment remains current, verifies the restore, and appends the truthful rollback receipt.

Cloudflare's active deployment is runtime truth. D1 is a deployment/read model, not a competing authority. Cloudflare has no conditional deployment-create API, so this is an expected-current guard—not provider CAS—and deployment credentials are exclusive to this path. Exact pre-read and post-readback checks are mandatory. Ambiguity retains the same in-flight identity for reconciliation; it never permits a different ready row to run.

Data and operator safety#

The release schema is additive through the rollback window. Accounts, credentials, sessions, repositories, projects, releases, publications, and content are not rewritten or deleted. A schema contraction requires recovery evidence plus compatibility with both live and rollback binaries.

An expedited invocation of this normal lane may attach operator and reason metadata to the newest eligible ready row; it still enforces ordering, expected-current checks, evidence, health, receipts, rollback, and the ten-minute stop-loss. Do not confuse that invocation mode with the independent operator-repair lane. When this lane or one of its dependencies is unavailable, degraded, or implicated in an incident, an authorized Forge operator may repair exactly one infrastructure component through direct Wrangler using recorded current state, rollback, focused checks, binding verification, health, and the original reproduction. Forge metadata reconciliation follows the repair and does not block it. Direct provider deployment remains forbidden as a silent substitute for a Forge Deploy application release.