Sandbox v1 decisions (append-only ADR log)
On this page
- Rule: entries are appended, never rewritten
- Index
- ADR-SV1-001 — Restart as develop-targeted slices
- ADR-SV1-002 — Lane branches are read-only history
- ADR-SV1-003 — Four portable modules instead of a lane merge
- ADR-SV1-004 — One central Dispatch consumer; tenants are producers
- ADR-SV1-005 — Staging-only migration, gated by WORKER_PLATFORM
- ADR-SV1-006 — Conservative intent is the point of no return
- ADR-SV1-007 — Repair the epic’s dead plan link
- ADR-SV1-008 — No numeric SLA/RPO claim; TTL is liveness; S7 is qualitative
- ADR-SV1-009 — New non-production tenant first; client never migrates
- ADR-SV1-010 — Integrate the v1-sandbox track into develop; no production cutover
Companion to
sandbox-v1-cutover-contracts.md(normative invariants C1–C10) andsandbox-v1-scaffold.md.
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 toSuperseded; 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 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.
- The
v1-sandboxtrack is the integration source. It merges intodevelopas 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. - 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 reservedclientslug never migrates. Lerma keeps v1 provisioning staging-platform anddev-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. - The v1 deploy surface (the
SandboxV1DO binding and thefouria-sandbox-v1durable_objectcontainer application) stays on the local and stagingwrangler.jsoncenvironments and is removed from the production environment, so a production worker deploy builds no v1 image or application and production stays byte-identical. TheSandboxV1class and the append-onlyv7migration remain (migrations are append-only; the class stays dormant and unbound in production). - 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>, notv1-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.