# Sandbox v1 cutover contracts (S0)

> **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](https://github.com/0xCAB0/fouria/issues/489) · Epic:
> [#380](https://github.com/0xCAB0/fouria/issues/380)
>
> Companion: [`sandbox-v1-decisions.md`](/llms/platform/reference/plans/sandbox-v1-decisions/index.md) (append-only
> ADR log). Reference implementation note:
> [`sandbox-v1-scaffold.md`](/llms/platform/reference/plans/sandbox-v1-scaffold/index.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

| Term                           | Meaning in this document                                                                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Trusted env**                | Values the Worker receives from its own deployment configuration (bindings/vars/secrets), never from a request.                                              |
| **Platform binding**           | `WORKER_PLATFORM`, a non-secret, deployment-provisioned string identifying the environment (`staging`, `production`, …). It does not exist on `develop` yet. |
| **Tenant slug**                | The canonical, validated tenant identity resolved from trusted env (`tenantSlugFromEnv`). Never `'default'`, never empty.                                    |
| **Conversion intent**          | The write-ahead record that states "this tenant is being converted to v1". Its presence is the point of no return (C5).                                      |
| **Conversion record**          | The durable v1 artifact produced by the DO-owned conversion (C7). Distinct from the intent.                                                                  |
| **Stable pointer**             | The DO-owned pointer naming the committed conversion record (the recovery point).                                                                            |
| **Phase**                      | One bounded unit of migration work (a queue message / job delivery performs exactly one).                                                                    |
| **Lease**                      | A per-tenant R2 object granting exclusive write authority for a bounded time. Liveness only (C4).                                                            |
| **Absent / present / unknown** | The 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:

| #   | Surface                   | Expected location                                            |
| --- | ------------------------- | ------------------------------------------------------------ |
| 1   | Request routing           | `apps/fouria/src/index.ts` (runtime selection)               |
| 2   | Serving / HTTP + WS proxy | `apps/fouria/src/index.ts` proxy path                        |
| 3   | Gateway start             | `apps/fouria/src/gateway/process.ts` (`ensureGateway` path)  |
| 4   | Freeze                    | `apps/fouria/src/index.ts` `/control` `freeze`               |
| 5   | Backup / checkpoint       | `apps/fouria/src/persistence.ts` and the `/control` handlers |
| 6   | Abort                     | the 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:

| State       | Permitted origin                                                                                                             | Effect                                                                   |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **absent**  | an explicit successful negative (a `404`/no-such-key from a completed read)                                                  | pre-write legacy behavior is permitted                                   |
| **present** | a completed read yielding a shape-valid record                                                                               | v1 path, fail closed (C5)                                                |
| **unknown** | `null`/`undefined`, malformed or truncated body, missing required fields, transport error, timeout, abort, any non-404 error | fail 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:

| Situation                                 | Required 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.

| Slice | Issue | Invariants owned (aspect)                                                                                                     | Expected owned files (additive unless noted)                                                                                                                                                   | Proving gate                                                        |
| ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| S0    | #489  | defines C1–C10                                                                                                                | `docs/plans/sandbox-v1-cutover-contracts.md`, `docs/plans/sandbox-v1-decisions.md`, this doc's index entry                                                                                     | this document; review only                                          |
| S1    | #490  | C1, C2, C10                                                                                                                   | `apps/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 vars | unit tests + `test/business-rules/sandbox-v1-cutover.txt`           |
| S2    | #491  | C4 (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    | #492  | C8 (readiness parity), serving parity                                                                                         | `apps/fouria/src/index.ts` (header rebuild/WS), `apps/fouria/src/routes/**`                                                                                                                    | HTTP + WebSocket parity over the v1 DO fetch                        |
| S4    | #493  | C5 (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.ts`                                                                                | owner-ops gates: freeze/backup/checkpoint/restore-settled + verify  |
| S5    | #494  | C2 (job entry), C3, C4 (usage), C5 (abort/queue), C7 (queue never converts), C9                                               | `workers/fouria-dispatch/src/**` (central consumer), new `apps/fouria/src/sandbox-migration/reaper.ts`                                                                                         | one-phase-per-message, continuation-before-ack, enqueue-only reaper |
| S6    | #495  | C8 (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    | #496  | all (rehearsal proof)                                                                                                         | new `apps/fouria/test/e2e-v1/**`, `apps/fouria/test/business-rules/sandbox-v1-*.txt`                                                                                                           | rehearsal 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.

| Invariant | Slice | Owned aspect (disjoint)                                                                                                                             |
| --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| C2        | S5    | Consumer-side job-entry validation (refuse a job whose migration is not migratable)                                                                 |
| C4        | S2    | The lease **primitive**: create-only acquire, etag-CAS takeover, owner-scoped renew/release, fail-closed parse                                      |
| C4        | S5    | Lease **usage**: every caller goes through the primitive; no call site re-implements acquisition, and none reads expiry as a verdict                |
| C5        | S2    | **Defines and persists** the intent; the tri-state reader; routing, serving, and gateway-start refuse legacy                                        |
| C5        | S4    | **Ops gates**: freeze, backup, and checkpoint refuse legacy after the point of no return                                                            |
| C5        | S5    | **Abort and queue/control**: the abort path never falls back to legacy, and no delivery converts                                                    |
| C5        | S7    | **Proof**: all six surfaces observed refusing legacy on the rehearsal tenant                                                                        |
| C7        | S2    | **v1 conversion, target restore, and the v1 owner restart after verification** run in the `SandboxV1` DO; Worker handlers never call the primitives |
| C7        | S4    | **Owner ops**: `stopGateway` stays process-scoped (no destroy/recreate); the legacy restore path and `gateway/process.ts` integration are unchanged |
| C7        | S5    | **Queue/consumer**: no delivery performs a conversion, restore, or container-addressed step                                                         |
| C8        | S2    | **Barrier and verify input**: the conversion record is written, validates, and is named by the stable pointer                                       |
| C8        | S3    | **Readiness parity**: the v1 serving path is graded by the existing real readiness probe, not a second definition                                   |
| C8        | S4    | **Snapshot settlement and verify step**: observes pointer and readiness independently, and completes only when both hold                            |
| C8        | S6    | **Operator surface**: reports pointer id, record validation, and readiness as distinct fields                                                       |
| C8        | S7    | **Proof**: 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`](/llms/platform/reference/plans/sandbox-v1-decisions/index.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.
