# Sandbox v1 decisions (append-only ADR log)

> Companion to [`sandbox-v1-cutover-contracts.md`](/staging/llms/platform/reference/plans/sandbox-v1-cutover-contracts/index.md)
> (normative invariants C1–C10) and [`sandbox-v1-scaffold.md`](/staging/llms/platform/reference/plans/sandbox-v1-scaffold/index.md).
>
> Issue: [#489](https://github.com/0xCAB0/fouria/issues/489) · Epic:
> [#380](https://github.com/0xCAB0/fouria/issues/380)

## Rule: entries are appended, never rewritten

- **Append only.** Entries and index rows are added at the end (newest last,
  ascending IDs). Existing text is never edited, reordered, or deleted — not to
  fix a typo, not to update a status, not to record that reality changed.
- **Supersede, don't revise.** To change a decision, add a new entry whose
  **Supersedes** column cites the superseded ID(s) and explains what changed.
  The old entry keeps saying what was decided and why.
- **The Supersedes column holds IDs, never phrases.** When a decision supersedes
  something that has no ADR ID — a lane branch topology, a lost document — write
  `— (<what>)`, for example `— (lane queue topology)` or `— (dead plan link)`, so
  the column cannot be mistaken for a competing ID or a new record type.
- **Status values** are `Accepted`, `Superseded`, `Rejected`, `Proposed`. Only a
  _new_ entry may move an old one to `Superseded`; the old row's other cells stay
  untouched.
- **Evidence is a path or a verifiable fact**, not an assertion. Where a claim
  cannot be verified on `develop`, say so in the entry.
- **Normative impact.** An entry that changes an invariant must be accompanied by
  the corresponding amendment to the contract document in the same PR (contract
  §7).

## Index

| ID          | Date       | Decision                                                                                                    | Status     | Supersedes              | Evidence                                                                                                                                                    |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------- | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ADR-SV1-001 | 2026-10-21 | Restart the migration as develop-targeted slices; the `sandbox-v1-validation` lane will not merge           | Superseded | —                       | Epic #380 "Execution model (2026-10-21)"; PRs #446/#427 closed as not planned; lane review against `98078dcd`                                               |
| ADR-SV1-002 | 2026-10-21 | Lane branches are read-only history: reference only, never a merge source, never force-pushed or deleted    | Accepted   | —                       | Epic #380 restart section; retained refs `test/p2-owner-boundary-red` @ `08a2be90`, `test/p7a-sandbox-v1-e2e-gate` @ `9f888133`                             |
| ADR-SV1-003 | 2026-10-21 | Re-land as four portable modules (identity, serving+conversion, owner ops, migration coordination)          | Accepted   | —                       | Epic #380 slice/ownership model; closed PR #446 test titles (operator-only cutover, DO-owned conversion, no-fallback)                                       |
| ADR-SV1-004 | 2026-10-21 | One central Dispatch consumer; tenant Workers are producers only                                            | Accepted   | — (lane queue topology) | Epic #380 restart findings ("invalid queue topology: a consumer per tenant Worker for one physical queue"); `apps/fouria/wrangler.jsonc` `queues.consumers` |
| ADR-SV1-005 | 2026-10-21 | Migration is authorized only by `WORKER_PLATFORM === 'staging'` from trusted env (C1)                       | Accepted   | —                       | Issue #489 I1; `WORKER_PLATFORM` has no reference on `develop` @ `7b39044d`                                                                                 |
| ADR-SV1-006 | 2026-10-21 | Conservative intent boundary: intent present **or unreadable** is the point of no return (C5, C6)           | Accepted   | —                       | Issue #489 I5/I6; contract C5/C6                                                                                                                            |
| ADR-SV1-007 | 2026-10-21 | Repair the dead epic link: `sandbox-v1-client-opt-in.md` → scaffold + contracts                             | Accepted   | — (dead plan link)      | `git log --all -- docs/plans/sandbox-v1-client-opt-in.md` is empty; issue #489 item 3                                                                       |
| ADR-SV1-008 | 2026-10-21 | No numeric SLA/SLO/RTO/RPO claim; the lease TTL is a liveness bound; S7 evidence is qualitative             | Accepted   | —                       | Contract §6; epic #380 "Out of scope for this restart"; #377 owns durability                                                                                |
| ADR-SV1-009 | 2026-10-21 | First migration target is a new non-production tenant; the reserved `client` slug never migrates            | Accepted   | —                       | Contract §6/C2; epic #380 S7 (#496)                                                                                                                         |
| ADR-SV1-010 | 2026-11-12 | Integrate the `v1-sandbox` track into `develop` as one reviewed PR; integration is not a production cutover | Accepted   | ADR-SV1-001             | PR #565 base `develop` @ `ee338d59`; divergence `1/103`; production gates in `platform.ts`, `SandboxV1`, `Instance`, `TenantProvisioner`                    |

---

## ADR-SV1-001 — Restart as develop-targeted slices

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** The `sandbox-v1-validation` lane (`9170e6fb`) accumulated a
long-lived fork of the migration. An independent review against `develop` @
`98078dcd` found 75 files changed on both sides, semantic reverts of work that
had landed after the fork (freeze, `access.tf`, Telegram ingress queue), a
missing `convertToV1`, no WebSocket v1 forwarding, an invalid queue topology, a
duplicate identity resolver, no operator surface, and no rehearsal. Merging it
would revert `develop`.

**Decision.** The lane will not merge. The migration re-lands as eight
develop-targeted slices (S0–S7, issues #489–#496), one PR per slice, each
branching from `origin/develop` at the time work starts. The lane's commits are
retained as reference material only.

**Consequences.** The migration's definition of "done" moves from "the lane is
green" to "each slice satisfies the contract and ships its own evidence". The
old P-issues (#382–#391) stay open as historical problem statements; their scope
is absorbed by the slices. Every PR carries a changeset and targets `develop`.

**Evidence.** Epic #380, section "Execution model (2026-10-21)"; PRs #446 and
#427 closed as not planned.

---

## ADR-SV1-002 — Lane branches are read-only history

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** After ADR-SV1-001, the lane's branches still contained the only
written form of several invariants (notably in closed PR #446's test titles), so
they remain useful as documentation of intent while being unusable as merge
sources.

**Decision.** Lane branches and their commits are read-only history. They MUST
NOT be merged, force-pushed, or deleted, and nothing in the repository may
describe lane code as present on `develop`. Reused material is carried across as
requirements and tests, not as code.

**Consequences.** The contracts document (C1–C10) becomes the single normative
reference; the lane is cited only as prior art. Reviewers MUST NOT accept "it
worked on the lane" as evidence.

**Evidence.** Epic #380 restart section; retained refs
`test/p2-owner-boundary-red` @ `08a2be90` and `test/p7a-sandbox-v1-e2e-gate` @
`9f888133`.

---

## ADR-SV1-003 — Four portable modules instead of a lane merge

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** Re-landing file-by-file from a 75-file, both-sides-divergent branch
reintroduces the same drift one conflict at a time. The review also showed the
lane's problems clustered at module boundaries (identity, serving/conversion,
owner operations, coordination), not at individual files.

**Decision.** Carry the migration across as four file-disjoint, independently
testable modules, each portable to `develop` on its own and each rebasable
without the others:

| Module                        | Scope                                                            | Slice(s) |
| ----------------------------- | ---------------------------------------------------------------- | -------- |
| **M1 Identity + authority**   | canonical tenant slug, platform gate, runtime selection          | S1       |
| **M2 Serving + conversion**   | `convertToV1`, write-ahead intent/state, HTTP/WS forwarding      | S2, S3   |
| **M3 Owner operations**       | freeze, backup, checkpoint, restore-settled, process-scoped stop | S4       |
| **M4 Migration coordination** | one central consumer, per-tenant lease, enqueue-only reaper      | S5       |

**Consequences.** Slices own disjoint files (contract §5), so no two open PRs in
a wave edit the same file. Each module must be provable alone; a module that only
works when another unreviewed module is present is rejected. The ≤600 production
LOC per PR rule applies per module slice.

**Evidence.** Epic #380 slice map and file-ownership table; closed PR #446's
test titles (operator-only cutover, reserved `client`, DO-owned
`convertToV1`/`stopGateway`, no-fallback).

---

## ADR-SV1-004 — One central Dispatch consumer; tenants are producers

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** The lane wired a queue consumer per tenant Worker for a single
physical queue — an invalid topology with Cloudflare Queues and the reason the
lane's migration could not be reasoned about (one queue, N competing consumer
configurations across per-tenant deployments).

**Decision.** Durable migration work is produced by each tenant Worker and
consumed by a single central consumer in the Dispatch Worker
(`workers/fouria-dispatch`). Tenant Workers MUST NOT declare a consumer for the
migration queue. The phase a message carries is the bounded unit of work (C3);
the reaper may only enqueue (C9).

**Consequences.** Queue topology is reviewable in one place
(`apps/fouria/wrangler.jsonc` producers +
`workers/fouria-dispatch/wrangler.jsonc` consumer). Any slice that adds a
tenant-side consumer contradicts this ADR and must supersede it first.

**Evidence.** Epic #380 restart findings ("invalid queue topology"); today's
`apps/fouria/wrangler.jsonc` `queues` block, which declares producers and the
existing task/ingress consumers only — no migration queue exists yet.

---

## ADR-SV1-005 — Staging-only migration, gated by `WORKER_PLATFORM`

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** Multiple plausible "is this staging?" signals exist and several are
caller-controlled (request `Host`, `X-FourIA-*` headers), derivable (slug prefix,
`-dev` suffix, `WORKER_URL`), or unrelated (`DEV_MODE`, `OPENCLAW_DEV_MODE`). The
environment already derives container TTLs from the instance hostname, which
makes a hostname-based migration gate look natural — and dangerous.

**Decision.** The only authorization to migrate is a trusted, non-secret,
Lerma-provisioned `WORKER_PLATFORM` binding equal to `staging`; everything else
is refused before any write (contract C1). Hostname derivation stays confined to
non-migration concerns and MUST be computed by a separate predicate.

**Consequences.** S1 must add the binding (Lerma provisioning + the staging
environment's `vars`), a single `canMigrate`-style predicate, and refusal tests
including the "request says staging, binding says nothing" case. `WORKER_PLATFORM`
has no reference on `develop` yet, so no existing behavior changes until S1.

**Evidence.** Issue #489 I1; verified absence of `WORKER_PLATFORM` on `develop` @
`7b39044d`.

---

## ADR-SV1-006 — Conservative intent is the point of no return

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** The failure mode that costs the most is not a failed conversion — it
is a half-converted tenant that keeps serving legacy because a marker read
failed, or because the code chose a "safe" fallback after conversion artifacts
already existed. That produces two divergent sources of truth and a recovery
point that cannot be interpreted.

**Decision.** The write-ahead conversion intent is the point of no return. Once
it is **present or unreadable**, no automatic legacy fallback is permitted in
routing, serving, gateway start, freeze, backup, checkpoint, or abort; recovery
is operator-driven and auditable (contract C5). "Unreadable" is treated as
present, not absent (contract C6).

**Consequences.** Every decision surface consumes one tri-state reader; a shared
helper with unproven call sites is not acceptance evidence. Operator tooling (S6)
must expose the intent state and the recovery options, because the system will no
longer self-heal past the boundary. Fail-soft rendering remains allowed for
display only.

**Evidence.** Issue #489 I5/I6; contract C5, C6, and the fail-closed summary in
§4.

---

## ADR-SV1-007 — Repair the epic's dead plan link

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** Epic #380 pointed at `docs/plans/sandbox-v1-client-opt-in.md` as the
authoritative plan. That path exists on no ref:
`git log --all -- docs/plans/sandbox-v1-client-opt-in.md` returns nothing. The
document's intent (a client-facing opt-in plan) would otherwise be dropped
silently when the link is replaced.

**Decision.** The epic links
[`sandbox-v1-scaffold.md`](/staging/llms/platform/reference/plans/sandbox-v1-scaffold/index.md) as the current foundation
and this contract document as the normative reference (once #489 lands). This
entry records the replacement so the loss is explicit.

**Consequences.** No file is created at the dead path — resurrecting a name
without its content would be worse than the broken link. The scaffold doc now
declares the contract normative and itself reference-only, so a reader cannot
mistake foundation notes for acceptance criteria.

**Evidence.** Verified empty `git log --all` history for the lost path; issue
#489 item 3; epic #380 body.

---

## ADR-SV1-008 — No numeric SLA/RPO claim; TTL is liveness; S7 is qualitative

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** A lease TTL is easy to misread as a completion or recovery-time
guarantee, and a rehearsal on one tenant invites "we migrated a tenant in N
minutes" claims that the epic explicitly excludes.

**Decision.** The contract makes **no** numeric SLA, SLO, RTO, or RPO claim. The
per-tenant lease TTL bounds liveness only: expiry means "ask again", never
"failed" or "incomplete" (contract C4). S7's observation window is qualitative
(~15 minutes) and must be reported as an observation. Durability remains owned by
#377.

**Consequences.** PRs and docs MUST NOT introduce numeric recovery guarantees for
v1. A test MUST NOT assert a timing outcome as an acceptance criterion.

**Evidence.** Contract §6; epic #380 "Out of scope for this restart".

---

## ADR-SV1-009 — New non-production tenant first; `client` never migrates

**Date:** 2026-10-21 · **Status:** Accepted

**Context.** The migration rewrites a tenant's data layout and recovery pointer.
The cheapest possible first target is a tenant whose loss is bounded, and the
most expensive possible mistake is the shared reserved tenant.

**Decision.** The first migrated tenant is a **new, non-production** tenant,
created for the rehearsal in S7. The reserved `client` slug is excluded from
migration permanently for this epic (contract C2) while keeping its other control
actions unchanged.

**Consequences.** S7 proves the conversion on a disposable tenant before any
existing customer is considered. Lifting the `client` exclusion or designating an
existing customer as the first target requires a superseding ADR and a separate
issue, not a PR comment.

**Evidence.** Contract §6 and C2; epic #380 S7 (#496).

---

## ADR-SV1-010 — Integrate the `v1-sandbox` track into `develop`; no production cutover

**Date:** 2026-11-12 · **Status:** Accepted · **Supersedes:** ADR-SV1-001

**Context.** ADR-SV1-001 stopped the old `sandbox-v1-validation` lane from
merging and chose eight develop-targeted slices. The implementation then
converged on a different reality: the S0 foundation/scaffold landed on `develop`
(#331, #394), while S1–S7 and their follow-up fixes were built and live-verified
on the independent `v1-sandbox` track (PR #565). At `ee338d59` the
track is **103 commits / 196 files ahead** of `develop` and **1 commit behind**
(`e62f5a37`, the Agent Studio change from #572). Re-splitting the integrated,
already-live-tested track into eight fresh develop-targeted slices would discard
the per-slice evidence and the interactions the staging drills exercised; it is
not a realistic integration path. The old `sandbox-v1-validation` lane
(`9170e6fb`) remains frozen and is **not** the merge source (ADR-SV1-002).

**Decision.**

1. The `v1-sandbox` track is the integration source. It merges into `develop` as
   **one reviewed PR** (a merge commit, never a squash, so the per-slice SHAs the
   migration report cites remain reachable) once the gates in this entry pass.
2. Integration is **not** a production cutover. Contract C1 is unchanged:
   `WORKER_PLATFORM === "staging"` is the only migration authority
   (`apps/fouria/src/sandbox-migration/platform.ts`). C2 is unchanged: the
   reserved `client` slug never migrates. Lerma keeps v1 provisioning
   **staging-platform and `dev`-environment only**
   (`Lerma.Cloudflare.SandboxV1.enabled?/0`,
   `Instance.validate_sandbox_runtime_environment/1`,
   `TenantProvisioner.validate_v1_runtime/1`,
   `InstanceController.validate_sandbox_runtime/1`). No production tenant is
   converted by the merge.
3. The v1 deploy surface (the `SandboxV1` DO binding and the
   `fouria-sandbox-v1` `durable_object` container application) stays on the
   **local and staging** `wrangler.jsonc` environments and is **removed from the
   production environment**, so a production worker deploy builds no v1 image or
   application and production stays byte-identical. The `SandboxV1` class and the
   append-only `v7` migration remain (migrations are append-only; the class stays
   dormant and unbound in production).
4. Reaching v1 **in production** is a separate program, not a consequence of
   this integration. It requires a superseding ADR to C1 plus: a production
   image publish/pin path (`v1-<calver>`, not `v1-unstable-*`), Lerma production
   gating for selected tenants, a production-safe conversion and rollback plan,
   security/capacity review, and an approved first target after the S7 rehearsal.
   None of that is authorized here.

**Consequences.** The track stops being a long-lived fork at merge;
`scripts/sync-v1-sandbox.sh` is retired (or reduced to a historical helper)
afterwards. `develop` carries the v1 code, but production behavior is unchanged
because every production path refuses to select v1. Reviewers review the whole
track (196 files) as one change; the migration report is the QA guide. The old
`sandbox-v1-validation` lane stays frozen.

**Gates before merge.** (a) `develop` merged into the track and the conflicts
resolved; (b) the full repository gate green (`format:check`, `lint`,
`typecheck`, `test`, `mix precommit`, `mix license_audit`, business-rules); (c)
the manual E2E workflow (`workflow_dispatch`, `run_e2e=true`) green; (d) the S7
rehearsal on a disposable tenant and the SEC-2/BIL-2/BIL-3 observations recorded,
or explicitly deferred; (e) a human review and the changesets present.

**Evidence.** PR #565 (base `develop`, head `ee338d59`);
`git rev-list --left-right --count origin/develop...origin/v1-sandbox` → `1 103`;
`bun run plan:sandbox-v1:check` → 166 features / 14 milestones; the production
gates above; `docs/plans/sandbox-v1-staging-observations.md` for the live
evidence.
