F FourIA staging 2026.10.29 GitHub ↗

Sandbox v1 cutover contracts (S0)

On this page

Status: normative contract, no implementation. Nothing in this document is implemented on develop at the time of writing (base 7b39044d). Every statement below is a requirement a slice must satisfy and a reviewer must be able to test — not a description of shipped behavior.

Issue: #489 · Epic: #380

Companion: sandbox-v1-decisions.md (append-only ADR log). Reference implementation note: sandbox-v1-scaffold.md.

The sandbox-v1-validation lane is frozen and will not merge (ADR-SV1-001, ADR-SV1-002). The separate v1-sandbox track is the integration source for develop (ADR-SV1-010); that integration is not a production cutover and does not relax C1 or C2. This document replaces “re-derive the invariants from six divergent branches” with one written, reviewable definition that the seven implementation slices are graded against.

1. Scope and reading rules

  • Normative language. MUST, MUST NOT, SHOULD, and MAY are used in their RFC 2119 sense. A slice that cannot satisfy a MUST MUST change this document through the ADR log first (see §7), not silently relax it.
  • Enforcement is owned, not implied. Each invariant names the slice that owns it and the module expected to enforce it. “Expected module” means the file does not necessarily exist yet; if a slice chooses a different file, it updates the table in the same PR.
  • Proof is a gate, not a claim. Each invariant names the gate that proves it. Where no such test exists today, the document says so. grep assertions prove wiring only and never substitute for a behavior assertion.
  • No slice may claim another slice’s invariant wholesale. The slice map in §5 is the only ownership record, and ownership is exclusive at the aspect level: where one invariant is enforced by several slices, §5.1 names the disjoint aspect each slice owns. Moving an aspect to a different slice, or adding a new sharing arrangement, requires an ADR.

2. Terms

TermMeaning in this document
Trusted envValues the Worker receives from its own deployment configuration (bindings/vars/secrets), never from a request.
Platform bindingWORKER_PLATFORM, a non-secret, deployment-provisioned string identifying the environment (staging, production, …). It does not exist on develop yet.
Tenant slugThe canonical, validated tenant identity resolved from trusted env (tenantSlugFromEnv). Never 'default', never empty.
Conversion intentThe write-ahead record that states “this tenant is being converted to v1”. Its presence is the point of no return (C5).
Conversion recordThe durable v1 artifact produced by the DO-owned conversion (C7). Distinct from the intent.
Stable pointerThe DO-owned pointer naming the committed conversion record (the recovery point).
PhaseOne bounded unit of migration work (a queue message / job delivery performs exactly one).
LeaseA per-tenant R2 object granting exclusive write authority for a bounded time. Liveness only (C4).
Absent / present / unknownThe three-valued read result defined in C6. Only an explicit, successful negative read yields absent.

3. Invariants

C1 — Migration is staging-only, gated by the trusted WORKER_PLATFORM binding

Issue #489: I1.

Statement. The only accepted authority to migrate is the trusted, non-secret, deployment-provisioned WORKER_PLATFORM binding whose value is exactly staging. A deployment MUST refuse to migrate — before any write, any lease acquisition, and any DO or container addressing — when the binding is absent, empty, whitespace, unrecognized, or any value other than staging (including production, dev, and case variants such as STAGING).

The following MUST NOT be accepted as platform signals: the request Host header, WORKER_URL, any X-FourIA-* request header (role, customer slug, name), a slug prefix such as staging- or a -dev suffix, DEV_MODE, OPENCLAW_DEV_MODE, SANDBOX_RUNTIME, the tenant name, or the presence of an operator role.

Hostname derivation remains permitted where it is already contractual for non-migration concerns (for example the container inactivity TTL derived in resolveSleepAfter). It MUST NOT be reused as the migration gate; the two decisions MUST be computed separately so a future change to one cannot silently enable the other.

Prevents. A production tenant migrating because someone requested a staging-* host, a caller supplied a header, or an operator’s browser hit the wrong instance — an irreversible data-layout change authorized by an untrusted input.

Enforcement. S1. Expected: a single predicate (for example canMigrate(env) in apps/fouria/src/sandbox-migration/platform.ts, or in apps/fouria/src/sandbox-runtime.ts alongside the existing resolveSandboxRuntime) reading env.WORKER_PLATFORM only. The binding is provisioned by Lerma (apps/lerma/lib/lerma/provisioning/tenant_provisioner.ex) and declared for the staging environment in apps/fouria/wrangler.jsonc. Enforcement points: the cutover control-action entry in apps/fouria/src/index.ts and the DO-side migration handler. Both MUST call the same predicate; neither MAY re-implement it.

Proof / acceptance gate. S1 adds a unit test asserting refusal for: absent, empty, whitespace, production, dev, STAGING, and a request carrying Host: staging-<slug> / X-FourIA-Role: root while the binding is absent. S1 adds a behavior-backed corpus entry (apps/fouria/test/business-rules/sandbox-v1-cutover.txt) asserting the observed refusal status and the absence of any R2 write or DO call. No such test exists today; the invariant is not proven on develop.


C2 — The reserved client slug is migrate-only excluded

Issue #489: I2.

Statement. The reserved slug client MUST be refused for the migrate action only. Every other control action — at minimum freeze, unfreeze, backup, and checkpoint — MUST retain exactly its pre-contract behavior on client. The refusal MUST be a check on the migrate action, not a tenant-level or route-level block, and MUST NOT be implemented by short-circuiting identity resolution (C10) or by treating client as an invalid slug.

Prevents. Two opposite failures: a cutover of the shared reserved tenant (unrecoverable), or an operator losing freeze/backup on that tenant because the guard was placed too high in the stack.

Enforcement. S1 (gate) and S5 (job entry). Expected: the migrate action handler beside the existing action switch in apps/fouria/src/index.ts (/control), and the consumer-side job validation. The constant MUST live in one place next to the other control-action guards.

Proof / acceptance gate. S1 tests assert: migrate on client is refused before any write; freeze, unfreeze, backup, and checkpoint on client still return their existing status codes and effects. Corpus: the refusal and one preserved action must both be observed. No proof exists today.


C3 — One bounded phase per delivery, continuation before ack, expectedPhase is a hint

Issue #489: I3.

Statement. Each migration job/message MUST perform exactly one bounded phase and MUST NOT loop phases inside a single delivery. Before a message is acked, the continuation (next phase + the state needed to run it) MUST be durably written; an ack MUST never be able to lose work. If the durable continuation write fails, the message MUST be retried (or explicitly failed), never acked.

expectedPhase (on a job or message) is a hint only. On mismatch the handler MUST re-read the durable phase and MUST NOT advance twice, MUST NOT coerce the expectation to the stored value, and MUST NOT treat the mismatch as success. A mismatch caused by a concurrent writer is expected during recovery and MUST be a normal, non-fatal path that re-reads.

Prevents. Two writers completing the same phase (double conversion, duplicated restore), and the classic ack-then-crash window where the queue believes the work is done and the state machine has no record of what comes next.

Enforcement. S5. Expected: tenant Worker is a producer only; one central consumer in the Dispatch Worker (workers/fouria-dispatch/src/) runs the phase handlers; the durable phase lives in the migration DO (the per-tenant ActivityScheduler in apps/fouria/src/activity/ or a dedicated migration DO, per ADR-SV1-004).

Proof / acceptance gate. S5 tests assert ordering (continuation write is observed before ack), mismatch re-read without a second advance, and continuation-write failure yields no ack. Corpus asserts an observed phase sequence across at least two deliveries. No proof exists today.


C4 — Per-tenant R2 lease: create-only acquire, etag-CAS takeover, owner-scoped release, fail closed

Issue #489: I4.

Statement. The migration lease is a per-tenant R2 object with all of the following properties, all of which are MUST:

  1. Create-only acquire — acquisition is a conditional create (attribute-not- exists / write-if-absent). It MUST NOT overwrite an existing lease.
  2. Etag-CAS takeover — an expired lease may be replaced only by a compare-and- swap on the etag read together with the expiry observation. A blind overwrite is forbidden.
  3. Owner-scoped renew and release — renew and release MUST verify the stored ownership token against the caller’s token, and release MUST use a tombstone marker (an explicit released state) rather than deletion-by-assumption, so a late writer cannot mistake a released lease for a free one.
  4. Fail closed on unreadable lease — a malformed, truncated, or ownership-token-less lease MUST refuse acquire, refuse takeover, and refuse release. It MUST NOT be treated as absent.
  5. TTL is a liveness bound, not an SLA/RPO — expiry means “ask again”, never “the previous owner failed”, “the migration is incomplete”, or “data is lost”. No code path may translate lease expiry into a success or failure verdict, and no document may present the TTL as a durability, recovery-point, or recovery- time guarantee.

Rationale for the shape: the existing persistence path already reasons about a shared R2 lease with crash residue (apps/fouria/src/persistence.ts, backup-lock). The migration lease reuses that discipline but adds explicit ownership, because a migration writer, unlike a snapshot writer, changes a state machine that cannot be replayed from the filesystem.

Prevents. Two conversions writing the same tenant; a resurrected writer completing a phase after ownership moved on; an expired-but-live owner racing a takeover; and the false confidence of reading a liveness timeout as an RPO claim.

Enforcement. S2 (primitive) and S5 (usage). Expected: a new apps/fouria/src/sandbox-migration/lease.ts using the BACKUP_BUCKET binding’s conditional put (onlyIf / etag preconditions). The TTL and any skew tolerance live in that module, not at call sites.

Proof / acceptance gate. S2/S5 unit tests assert: second create fails; takeover succeeds only with the matching etag and observed expiry; renew/release from a non-owner are refused; a corrupt lease fails closed on all three operations. A corpus entry asserts the observed refusal, and the PR states that no timing/SLA assertion is made. No proof exists today.


C5 — Write-ahead conversion intent is the point of no return

Issue #489: I5.

Statement. The conversion intent record MUST be written before the first destructive or converting step. Once the intent is present or unreadable, there MUST be no automatic fallback to the legacy path in any of:

#SurfaceExpected location
1Request routingapps/fouria/src/index.ts (runtime selection)
2Serving / HTTP + WS proxyapps/fouria/src/index.ts proxy path
3Gateway startapps/fouria/src/gateway/process.ts (ensureGateway path)
4Freezeapps/fouria/src/index.ts /control freeze
5Backup / checkpointapps/fouria/src/persistence.ts and the /control handlers
6Abortthe migration abort action (S5)

“Unreadable” includes transport failure, timeout, null, malformed JSON, and a record missing required fields (see C6). Recovery after the point of no return is operator-driven: an explicit, audited operator action (abort-with-restore or resume), never an automatic downgrade. The system MUST NOT invent a second “implicit” point of no return in a lower layer (for example deleting the legacy archive or rewriting the recovery pointer) without recording it here.

Prevents. The most expensive failure class in the lane’s review history: a half-converted tenant silently served from legacy after the conversion artifacts already exist, producing divergent state and a restore that cannot tell which side is authoritative. Also prevents a “helpful” fallback from racing the DO that owns conversion.

Enforcement. S2 owns the intent and the routing/serving/gateway-start surfaces; S4 owns the freeze/backup/checkpoint ops gates; S5 owns abort and the queue path (§5.1). Expected: apps/fouria/src/sandbox-migration/intent.ts exposing a tri-state read (C6) and a single requiresV1(intent) predicate consumed by every surface above. No surface may read the raw object directly.

Proof / acceptance gate. S2 proves the routing, serving/proxy, and gateway-start surfaces refuse legacy once the intent is present, and that an unreadable intent behaves identically to a present one. S4 proves freeze, backup, and checkpoint; S5 proves abort; S7 proves all six end to end on the rehearsal tenant (§5.1). Acceptance is a behavior assertion per surface — a shared helper with six unproven call sites is not proof. No proof exists today.


C6 — Absent ≠ unknown; only an explicit absent state permits pre-write behavior

Issue #489: I6.

Statement. Every migration-relevant read (intent, conversion record, stable pointer, lease, backup catalog entry) MUST resolve to one of three states:

StatePermitted originEffect
absentan explicit successful negative (a 404/no-such-key from a completed read)pre-write legacy behavior is permitted
presenta completed read yielding a shape-valid recordv1 path, fail closed (C5)
unknownnull/undefined, malformed or truncated body, missing required fields, transport error, timeout, abort, any non-404 errorfail closed: no pre-write behavior, no legacy fallback, no state advance

null is not absent. A thrown error is not absent. A non-404 HTTP status is not absent. Fail-soft rendering is permitted for display surfaces (a dashboard may show “unknown”), but it MUST NOT feed a decision: any surface that routes, serves, starts a gateway, freezes, backs up, checkpoints, or aborts MUST treat unknown as “do not proceed automatically”.

Prevents. A dropped R2 read or a null field being read as “no backup” / “not migrated” / “no gateway” — the failure that turns a transient network blip into a fresh onboard over existing tenant data.

Enforcement. S2, in the shared reader used by C5’s six surfaces. Expected: one parser in apps/fouria/src/sandbox-migration/intent.ts (or a shared state.ts) with an explicit result type; the tri-state MUST NOT be flattened to T | null at the boundary.

Proof / acceptance gate. S2 tests assert: 404 → absent; 200 with null → unknown; truncated JSON → unknown; missing required field → unknown; thrown fetch → unknown; and that a caller receiving unknown refuses rather than taking the legacy branch. No proof exists today.


C7 — The SandboxV1 DO owns the v1 conversion and its restore; the Worker never runs them in a request context

Issue #489: I7.

Statement. The v1 conversion and its restore MUST be executed by the tenant’s SandboxV1 Durable Object and its DirectoryBackup wiring, not by the Worker. That covers three steps: converting the tenant’s data, restoring the conversion target, and restarting the gateway afterwards. The Worker MUST NOT run any of the three, MUST NOT call the conversion or restore primitives directly, and MUST NOT perform them inside a request context where an isolate eviction can abort them mid-flight.

Scope. This invariant grades the v1 conversion path only. The legacy restore path — apps/fouria/src/persistence.ts (restoreIfNeeded, restoreBackupById) and the /control snapshot and restore actions — remains S4 and legacy scope: it is not converted by this epic, it is not regraded here, and it is not required to move into a DO.

stopGateway MUST be a process operation: it stops the gateway process and MUST NOT call destroy(), MUST NOT recreate or replace the container, and MUST NOT touch durable storage. It MUST be safe to call while a migration holds the lease — that is its purpose.

This does not change the existing /control freeze action, which is a deliberate lifecycle/billing operation (sandbox.destroy()) and is out of scope here; freeze remains gated on tenant-busy checks and MUST NOT be reachable as a side effect of stopGateway.

Prevents. The DO’s in-memory state being invalidated by a lifecycle operation during conversion; a request-scoped conversion being killed by isolate eviction (observed repeatedly as the reason cold-boot work moved into the DO); and a “stop the gateway” helper that quietly destroys the container.

Enforcement. S2 owns the DO-side v1 conversion, the target restore, and the v1 owner restart after verification — the SandboxV1 gateway start/restart primitive is in-DO; S4 owns owner operations — including the process-scoped stopGateway, operator freeze, and the legacy apps/fouria/src/gateway/process.ts integration — and remains the owner of the legacy restore path; S5 owns the guarantee that no queue delivery converts or restores (§5.1). Expected: apps/fouria/src/sandbox-v1.ts for the DO surface and new apps/fouria/src/sandbox-migration/** for phase orchestration; gateway process control in apps/fouria/src/gateway/process.ts. apps/fouria/src/sandbox-migration/ does not exist on develop at base 7b39044d.

Proof / acceptance gate. S2 test asserts Worker-side handlers never call the conversion/restore primitives for the v1 path (mocked primitives, call-graph assertion), and S4 asserts stopGateway performs no destroy and leaves the container addressable. The legacy restore path keeps its existing S4 suites, which this invariant neither regrades nor replaces. No proof for the v1 path exists today.


C8 — Verify = stable pointer equals the committed record AND real readiness

Issue #489: I8.

Statement. A migration is complete only when both conditions hold, and each MUST be independently observed:

  1. the DO’s stable/recovery pointer names the committed conversion record, and that record exists and validates; and
  2. the gateway answers a real readiness probe (the gateway’s own /health through the running process path used by /api/health readiness).

Pointer-written alone is not success. Readiness alone is not success. A non-waking liveness read (isRuntimeActive()) is not readiness and MUST NOT be substituted for it. stopGateway being callable is not readiness. On failure the migration MUST remain un-verified and fail closed (C5); it MUST NOT auto-revert to legacy.

Prevents. Marking a migration done because a pointer write succeeded while the tenant serves nothing (or serves an empty newly-onboarded instance), and the inverse: a warm gateway that is healthy but whose recovery point still names the legacy archive.

Enforcement. S2 owns the conversion-complete barrier (the record is written, validates, and is named by the stable pointer); S3 owns readiness parity, so the v1 serving path is graded by the existing real probe rather than a second definition; S4 owns snapshot settlement and the verify step that observes both conditions; S6 owns the read-only operator status that must surface both inputs separately; S7 proves it on the rehearsal tenant (§5.1). Readiness semantics stay in apps/fouria/src/gateway/health-probes.ts and apps/fouria/src/routes/public.ts (/api/health); the migration layer consumes them and MUST NOT invent a second readiness definition.

Proof / acceptance gate. S4 tests assert two negative cases (pointer without readiness → not complete; readiness without pointer → not complete) and one positive (both → complete). S3 asserts the readiness input is the existing shared probe, not a second definition. S6 exposes pointer id, record validation, and readiness as distinct fields. No proof exists today.


C9 — The reaper is enqueue-only and never addresses a container

Issue #489: I9.

Statement. The reaper (the component that finds stalled migrations and moves them again) MUST only enqueue. It MUST NOT execute migration work inline, MUST NOT mutate conversion state (intent, record, pointer, phase, lease) except its own enqueue bookkeeping, and MUST NOT address SandboxV1, Sandbox, any Durable Object that drives a container, or a container itself. It MUST NOT exec, destroy, fetch a container endpoint, or wake a sleeping tenant.

Prevents. A shared cron reaper becoming a second migration executor: waking tenants, double-advancing phases, and reintroducing the “two writers” failure C4 and C3 exist to prevent.

Enforcement. S5. The reaper lives in apps/fouria/src/sandbox-migration/reaper.ts and is invoked from the tenant’s ActivityScheduler alarm (apps/fouria/src/activity/), publishing through the central queue producer only (ADR-SV1-004). It MUST NOT live in workers/fouria-dispatch/src/: the Dispatch Worker hosts the queue consumer and MUST NOT address a tenant’s container or Durable Object, so a Dispatch-hosted reaper would need exactly the addressing this invariant forbids.

Proof / acceptance gate. S5 test with mocked bindings asserts the only outbound effect is an enqueue, and fails if env.Sandbox / env.SandboxV1 / container addressing is touched at all. Corpus asserts a stalled job is re-enqueued (observed) with no container/DO interaction. No proof exists today.


C10 — Canonical tenant identity comes only from trusted Worker env

Issue #489: I10.

Statement. Exactly one resolver decides the canonical tenant slug: tenantSlugFromEnv in apps/fouria/src/sandbox-tenant.ts, reading trusted env (CUSTOMER_SLUG, WORKER_NAME, WORKER_URL). It MUST return null rather than the 'default' fallback — today only its WORKER_NAME branch enforces that, so S1 completes the resolver itself (see Enforcement). No second resolver MAY be added for migration work, and no migration path MAY use ctx.containerId or resolveTenantSlug’s context fallback as the tenant identity — production provisions the sandbox under the fixed id openclaw, which is not a tenant.

Any migration path (intent read/write, DO addressing, R2 prefix, enqueue) MUST refuse to proceed when resolution returns null. No 'default', empty, whitespace-only, or sentinel identity MAY read a record, address a DO, or enqueue a message.

Prevents. A duplicate identity resolver diverging from the canonical one (the lane’s review finding), and a fixed-id deployment scoping migration state to openclaw/ or default/ — either silently cross-tenant or silently empty.

Enforcement. S1, in apps/fouria/src/sandbox-tenant.ts plus the migration entry points. Existing evidence on develop @ 7b39044d is partial, and the gap is S1’s work: tenantSlugFromEnv and tenantSlugFromWorkerUrl exist and already normalize the staging- prefix / -dev suffix, but the 'default' rejection exists only in tenantSlugFromEnv’s WORKER_NAME branch (derived !== 'default'). CUSTOMER_SLUG=default and WORKER_URL=https://default.fouria.io both resolve to 'default' today, because the shared sanitizer they fall through to (sanitizeCustomerSlug) does not reject that sentinel, and apps/fouria/src/sandbox-tenant.test.ts has no 'default' case. S1 MUST extend the rejection to the shared sanitizer so every branch inherits it, and MUST add the CUSTOMER_SLUG and WORKER_URL cases.

Proof / acceptance gate. S1 tests assert, per resolver branch: an absent or default CUSTOMER_SLUG, WORKER_NAME, and WORKER_URL each → null → refusal, with the refusal observed (no R2 read, no DO address, no enqueue) and not inferred from a return value alone; WORKER_URL=https://<slug>-dev.fouria.io → <slug>. A corpus/static guard asserts migration code imports tenantSlugFromEnv and not a second resolver. The resolver’s existing branches are covered by apps/fouria/src/sandbox-tenant.test.ts; no 'default' case and no migration-side proof exist today.

4. Fail-closed summary

Every “cannot decide” outcome resolves to the same place:

SituationRequired outcome
Platform binding absent/unknown (C1)refuse migrate, no write
Reserved client + migrate (C2)refuse, no write
expectedPhase disagrees (C3)re-read durable phase; never advance twice
Lease unreadable (C4)refuse acquire/takeover/release
Intent present or unreadable (C5, C6)v1 path, no automatic legacy fallback; operator-driven only
State read is unknown (C6)no pre-write behavior, no state advance
Pointer or readiness missing (C8)not complete, remain fail closed
Slug resolution returns null (C10)refuse read/addressing/enqueue

5. Slice map

Ownership is exclusive per aspect. An invariant appearing in more than one row is not a joint claim: each owning slice owns a named, disjoint aspect of it, spelled out in §5.1. C2, C4, C5, C7, and C8 appear in several rows because different slices enforce different surfaces of one rule — never because two slices may both “own the invariant”.

A slice MUST list the invariants — and, for a shared invariant, the aspect — it enforces in its PR body; an invariant, or an aspect of one, changing hands requires an ADR entry.

SliceIssueInvariants owned (aspect)Expected owned files (additive unless noted)Proving gate
S0#489defines C1–C10docs/plans/sandbox-v1-cutover-contracts.md, docs/plans/sandbox-v1-decisions.md, this doc’s index entrythis document; review only
S1#490C1, C2, C10apps/fouria/src/sandbox-tenant.ts, apps/fouria/src/sandbox-runtime.ts, new apps/fouria/src/sandbox-migration/platform.ts, apps/fouria/wrangler.jsonc (vars), Lerma provisioning varsunit tests + test/business-rules/sandbox-v1-cutover.txt
S2#491C4 (lease primitive), C5 (intent + persistence), C6, C7 (conversion + target restore + v1 owner restart), C8 (barrier/verify)new apps/fouria/src/sandbox-migration/{intent,state,lease}.ts, apps/fouria/src/sandbox-v1.ts (convertToV1), apps/fouria/src/index.ts (serving branch)intent tri-state + all-six-surfaces refusal + no-fallback tests
S3#492C8 (readiness parity), serving parityapps/fouria/src/index.ts (header rebuild/WS), apps/fouria/src/routes/**HTTP + WebSocket parity over the v1 DO fetch
S4#493C5 (ops gates), C7 (owner ops + stopGateway + legacy gateway/process.ts integration), C8 (snapshot settlement + verify)apps/fouria/src/index.ts (/control), apps/fouria/src/persistence.ts, apps/fouria/src/gateway/process.tsowner-ops gates: freeze/backup/checkpoint/restore-settled + verify
S5#494C2 (job entry), C3, C4 (usage), C5 (abort/queue), C7 (queue never converts), C9workers/fouria-dispatch/src/** (central consumer), new apps/fouria/src/sandbox-migration/reaper.tsone-phase-per-message, continuation-before-ack, enqueue-only reaper
S6#495C8 (operator surface)apps/lerma/lib/** (read models), apps/lerma/lib/lerma_web/** (read-only status first)operator surface shows pointer + readiness as distinct fields
S7#496all (rehearsal proof)new apps/fouria/test/e2e-v1/**, apps/fouria/test/business-rules/sandbox-v1-*.txtrehearsal on a new non-production tenant, qualitative ~15 min

5.1 Aspect-level ownership of shared invariants

These are the only permitted shared invariants. Each row names one slice’s disjoint responsibility; no slice may implement or grade an aspect listed for another.

InvariantSliceOwned aspect (disjoint)
C2S5Consumer-side job-entry validation (refuse a job whose migration is not migratable)
C4S2The lease primitive: create-only acquire, etag-CAS takeover, owner-scoped renew/release, fail-closed parse
C4S5Lease usage: every caller goes through the primitive; no call site re-implements acquisition, and none reads expiry as a verdict
C5S2Defines and persists the intent; the tri-state reader; routing, serving, and gateway-start refuse legacy
C5S4Ops gates: freeze, backup, and checkpoint refuse legacy after the point of no return
C5S5Abort and queue/control: the abort path never falls back to legacy, and no delivery converts
C5S7Proof: all six surfaces observed refusing legacy on the rehearsal tenant
C7S2v1 conversion, target restore, and the v1 owner restart after verification run in the SandboxV1 DO; Worker handlers never call the primitives
C7S4Owner ops: stopGateway stays process-scoped (no destroy/recreate); the legacy restore path and gateway/process.ts integration are unchanged
C7S5Queue/consumer: no delivery performs a conversion, restore, or container-addressed step
C8S2Barrier and verify input: the conversion record is written, validates, and is named by the stable pointer
C8S3Readiness parity: the v1 serving path is graded by the existing real readiness probe, not a second definition
C8S4Snapshot settlement and verify step: observes pointer and readiness independently, and completes only when both hold
C8S6Operator surface: reports pointer id, record validation, and readiness as distinct fields
C8S7Proof: both conditions observed together, and each negative case rejected, on the rehearsal tenant

S0 proves nothing about runtime behavior and MUST NOT be cited as evidence that any slice is implemented.

6. Explicit constraints

These are part of the contract, not commentary. A slice that contradicts one is out of scope.

  • No numeric SLA, SLO, RTO, or RPO claim. The C4 lease TTL is a liveness bound. Durability is tracked separately (#377). S7’s observation window is qualitative (~15 minutes) and MUST be reported as an observation, not a metric.
  • The reserved client slug never migrates (C2). This is permanent for this epic; lifting it requires a superseding ADR and a separate issue.
  • The first migrated tenant is a new, non-production tenant (S7). No existing customer is the first conversion.
  • SANDBOX_V1_CUTOVER MUST default off when it is introduced (S1). The flag does not exist on develop at base 7b39044d, and nothing in this document claims it does. Unselected tenants remain on the legacy path, byte-identically, proven by the existing suites. No production cutover or flag flip is in scope.
  • No deletion of the legacy class, its container application, or its archive format. SandboxV1 remains additive (apps/fouria/wrangler.jsonc migrations v7).
  • Destructive/recovery actions are explicit. No automatic abort, restore, or rollback after C5’s point of no return; an operator action is required and MUST be auditable.

7. Change control

  1. This document is normative and may only be relaxed by adding an ADR entry to sandbox-v1-decisions.md that cites the affected invariant ID, and then amending this document in the same PR.
  2. Entries in the ADR log are append-only: never rewritten, never reordered. Superseding an entry means adding a new one that cites the superseded ID.
  3. A slice may add acceptance evidence to its gate but MUST NOT redefine an invariant’s statement in its own PR description. If implementation reality forces a change, the ADR lands first.