Sandbox v1 cutover contracts (S0)
On this page
Status: normative contract, no implementation. Nothing in this document is implemented on
developat the time of writing (base7b39044d). Every statement below is a requirement a slice must satisfy and a reviewer must be able to test — not a description of shipped behavior.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, andMAYare used in their RFC 2119 sense. A slice that cannot satisfy aMUSTMUST 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.
grepassertions 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:
- Create-only acquire — acquisition is a conditional create (attribute-not- exists / write-if-absent). It MUST NOT overwrite an existing lease.
- 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.
- 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.
- 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.
- 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:
- the DO’s stable/recovery pointer names the committed conversion record, and that record exists and validates; and
- the gateway answers a real readiness probe (the gateway’s own
/healththrough the running process path used by/api/healthreadiness).
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
clientslug 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_CUTOVERMUST default off when it is introduced (S1). The flag does not exist ondevelopat base7b39044d, 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.
SandboxV1remains additive (apps/fouria/wrangler.jsoncmigrationsv7). - 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
- This document is normative and may only be relaxed by adding an ADR entry to
sandbox-v1-decisions.mdthat cites the affected invariant ID, and then amending this document in the same PR. - 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.
- 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.