F FourIA staging 2026.10.29 GitHub ↗

Sandbox v1 migration — evaluation plan

On this page

Machine-readable source of truth: sandbox-v1-evaluation-plan.json Schema: sandbox-v1-evaluation-plan.schema.json Generated from: docs/releases/V1-RELEASE-NOTES.md (673b1cdc) + the S0 contract sandbox-v1-cutover-contracts.md (issue #489).

Regenerate: bun run plan:sandbox-v1 · Validate: bun run plan:sandbox-v1:check

This plan maps every implemented V1 capability (✅ shipped, 🟡 partial, 🧭 operator-only) to one of four domains, one migration milestone, and a v1 disposition. It is deliberately exhaustive: 166 implemented features, 35 excluded rows (🧪/❌) kept in out_of_scope so nothing silently disappears.

Branch model

PropertyValue
Branchv1-sandbox
Baseorigin/develop @ 07312136
Worktree/home/varo/development/elixir/phoenix/fouria-v1-sandbox
DirectionIndependent track. Never merged into develop from this branch.
Syncbun run plan:sandbox-v1:sync (fetch + merge origin/develop)
Sync checkscripts/sync-v1-sandbox.sh --check
Conflict policyResolve in favour of develop for non-migration code; re-apply the migration slice.

Merge develop into v1-sandbox at least once per milestone and before every staging deploy. The script refuses to run on any other branch and never pushes.

Staging target

The validation tenant is the Lerma client client-sandbox-v1 (id 20), which owns 2 instances:

RoleHostname
Devstaging-client-sandbox-v1-dev.fouria.io
Productionstaging-client-sandbox-v1.fouria.io

Migration authority is the trusted WORKER_PLATFORM === "staging" binding only (contract C1). The reserved client slug never migrates (C2). No production cutover is in scope.

Domains and milestones

DomainMilestoneTitleSlicesFeaturesDispositions
—M0Migration control plane and staging laneS00—
OpenClaw ManagementOCM-1Serving parity: proxy, health and admin RPCS1–S3134 rewrite, 9 verify
OpenClaw ManagementOCM-2Gateway lifecycle, boot and repairS2, S475 rewrite, 2 verify
OpenClaw ManagementOCM-3Agents, channels, automation, knowledge and toolingS2, S3296 rewrite, 22 verify, 1 keep
OpenClaw ManagementOCM-4Provisioning, rollout, promotion and releaseS4, S6273 rewrite, 13 verify, 11 keep
PersistencePER-1Conversion intent and legacy data migrationS21211 rewrite, 1 verify
PersistencePER-2Snapshots, restore and retention (v1 records)S2, S464 rewrite, 1 verify, 1 keep
PersistencePER-3Durable jobs, lease usage and queue coordinationS533 rewrite
BillingBIL-1Billable-action emission and OTel transportS3, S4117 verify, 4 keep
BillingBIL-2Credits, plans and freeze semanticsS41212 keep
BillingBIL-3Cost observability and development expenseS644 verify
SecuritySEC-1Authority, identity and platform gateS1193 verify, 16 keep
SecuritySEC-2Isolation, secrets and the no-content boundaryS1–S3172 rewrite, 8 verify, 7 keep
SecuritySEC-3Owner operations, audit and rollout parkS4, S663 rewrite, 3 verify

Totals: 166 features — 52 preserve, 73 verify, 41 rewrite. 15 deprecations are recorded in the JSON (deprecations).

The five-step protocol (every milestone)

Each milestone object in the JSON carries all five steps with machine-readable inputs and outputs:

  1. prerequisites — read, find_replace (file/find/replace), expected_result.
  2. e2e_suitability — verdict (suitable/partial/unsuitable), existing, gaps, required new tests.
  3. execute — docs to follow and ordered implementation steps.
  4. verify — runnable commands and acceptance assertions.
  5. staging — target, deploy, observe, abort_criteria for client-sandbox-v1.

The protocol is also encoded once at protocol.steps, with the milestone-level definition of done.

Dispositions

DispositionMeaning
preserveNo runtime change expected; keep the behavior and re-run its suite.
verifyLogic is runtime-independent, but must be proven on the v1 path.
rewriteRuntime coupling requires an adapter/implementation change.
deprecateThe V1 mechanism is replaced (see deprecations in the JSON).

impact narrows the coupling: control-plane, edge-auth, gateway-api, container-exec, container-lifecycle, backup, outbound, queue, billing, observability, docs, partial.

Highest-risk rewrites (read first)

  1. Persistence — createBackup()/restoreBackup() and the .sqsh format become DirectoryBackup records; the conversion intent is the point of no return (C5) and must run in the SandboxV1 DO (C7). PER-1/PER-2 own 18 of the 41 rewrites.
  2. Serving — containerFetch/wsConnect/listProcesses/isRuntimeActive are replaced by the v1 DO transport and lifecycle. OCM-1/OCM-2 own the proxy, health and boot path.
  3. Bridges — leads/docs/software/OTLP/CDP outbound handlers must be registered on the v1 DO and scoped by tenantSlugFromEnv, never ctx.containerId (C10).
  4. Owner operations — stopGateway must stay process-scoped; freeze remains the only destructive lifecycle action (C7). SEC-3/PER-3.
  5. Billing — the ledger and plan logic is preserved; only the emission transport and the freeze trigger are re-proven (BIL-1/BIL-2).

How to use a milestone

# 1. Sync the track and confirm the plan is current
bun run plan:sandbox-v1:sync
bun run plan:sandbox-v1:check

# 2. Read the milestone in the JSON (or render it)
bun -e "const p=require('./docs/plans/sandbox-v1-evaluation-plan.json');console.log(JSON.stringify(p.milestones.find(m=>m.id==='PER-1'),null,2))"

# 3. Execute step 1 -> 5, recording each required_output in the PR
# 4. Run the milestone verify commands
# 5. Promote to client-sandbox-v1 and record the staging observation

Change control

The plan is generated, not hand-edited. To change an assignment or disposition, edit scripts/generate-sandbox-v1-evaluation-plan.mjs (milestone features lists, FEATURE_META, DEPRECATIONS), regenerate, and run bun run plan:sandbox-v1:check. The validator fails on:

  • any implemented release-note row missing from the plan or unassigned,
  • any excluded row present in features,
  • duplicate feature ownership or a milestone/domain mismatch,
  • a milestone missing any of the five protocol steps or the staging target,
  • a stale summary or an invalid deprecation record.