F FourIA staging 2026.10.29 GitHub ↗

Sandbox v1 decisions (append-only ADR log)

On this page

Companion to sandbox-v1-cutover-contracts.md (normative invariants C1–C10) and sandbox-v1-scaffold.md.

Issue: #489 · Epic: #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

IDDateDecisionStatusSupersedesEvidence
ADR-SV1-0012026-10-21Restart the migration as develop-targeted slices; the sandbox-v1-validation lane will not mergeSuperseded—Epic #380 “Execution model (2026-10-21)”; PRs #446/#427 closed as not planned; lane review against 98078dcd
ADR-SV1-0022026-10-21Lane branches are read-only history: reference only, never a merge source, never force-pushed or deletedAccepted—Epic #380 restart section; retained refs test/p2-owner-boundary-red @ 08a2be90, test/p7a-sandbox-v1-e2e-gate @ 9f888133
ADR-SV1-0032026-10-21Re-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-0042026-10-21One central Dispatch consumer; tenant Workers are producers onlyAccepted— (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-0052026-10-21Migration 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-0062026-10-21Conservative intent boundary: intent present or unreadable is the point of no return (C5, C6)Accepted—Issue #489 I5/I6; contract C5/C6
ADR-SV1-0072026-10-21Repair the dead epic link: sandbox-v1-client-opt-in.md → scaffold + contractsAccepted— (dead plan link)git log --all -- docs/plans/sandbox-v1-client-opt-in.md is empty; issue #489 item 3
ADR-SV1-0082026-10-21No numeric SLA/SLO/RTO/RPO claim; the lease TTL is a liveness bound; S7 evidence is qualitativeAccepted—Contract §6; epic #380 “Out of scope for this restart”; #377 owns durability
ADR-SV1-0092026-10-21First migration target is a new non-production tenant; the reserved client slug never migratesAccepted—Contract §6/C2; epic #380 S7 (#496)
ADR-SV1-0102026-11-12Integrate the v1-sandbox track into develop as one reviewed PR; integration is not a production cutoverAcceptedADR-SV1-001PR #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:

ModuleScopeSlice(s)
M1 Identity + authoritycanonical tenant slug, platform gate, runtime selectionS1
M2 Serving + conversionconvertToV1, write-ahead intent/state, HTTP/WS forwardingS2, S3
M3 Owner operationsfreeze, backup, checkpoint, restore-settled, process-scoped stopS4
M4 Migration coordinationone central consumer, per-tenant lease, enqueue-only reaperS5

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.


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.

  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.