Sandbox v1 migration — evaluation plan
On this page
Machine-readable source of truth:
sandbox-v1-evaluation-plan.jsonSchema:sandbox-v1-evaluation-plan.schema.jsonGenerated from:docs/releases/V1-RELEASE-NOTES.md(673b1cdc) + the S0 contractsandbox-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
| Property | Value |
|---|---|
| Branch | v1-sandbox |
| Base | origin/develop @ 07312136 |
| Worktree | /home/varo/development/elixir/phoenix/fouria-v1-sandbox |
| Direction | Independent track. Never merged into develop from this branch. |
| Sync | bun run plan:sandbox-v1:sync (fetch + merge origin/develop) |
| Sync check | scripts/sync-v1-sandbox.sh --check |
| Conflict policy | Resolve 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:
| Role | Hostname |
|---|---|
| Dev | staging-client-sandbox-v1-dev.fouria.io |
| Production | staging-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
| Domain | Milestone | Title | Slices | Features | Dispositions |
|---|---|---|---|---|---|
| — | M0 | Migration control plane and staging lane | S0 | 0 | — |
| OpenClaw Management | OCM-1 | Serving parity: proxy, health and admin RPC | S1–S3 | 13 | 4 rewrite, 9 verify |
| OpenClaw Management | OCM-2 | Gateway lifecycle, boot and repair | S2, S4 | 7 | 5 rewrite, 2 verify |
| OpenClaw Management | OCM-3 | Agents, channels, automation, knowledge and tooling | S2, S3 | 29 | 6 rewrite, 22 verify, 1 keep |
| OpenClaw Management | OCM-4 | Provisioning, rollout, promotion and release | S4, S6 | 27 | 3 rewrite, 13 verify, 11 keep |
| Persistence | PER-1 | Conversion intent and legacy data migration | S2 | 12 | 11 rewrite, 1 verify |
| Persistence | PER-2 | Snapshots, restore and retention (v1 records) | S2, S4 | 6 | 4 rewrite, 1 verify, 1 keep |
| Persistence | PER-3 | Durable jobs, lease usage and queue coordination | S5 | 3 | 3 rewrite |
| Billing | BIL-1 | Billable-action emission and OTel transport | S3, S4 | 11 | 7 verify, 4 keep |
| Billing | BIL-2 | Credits, plans and freeze semantics | S4 | 12 | 12 keep |
| Billing | BIL-3 | Cost observability and development expense | S6 | 4 | 4 verify |
| Security | SEC-1 | Authority, identity and platform gate | S1 | 19 | 3 verify, 16 keep |
| Security | SEC-2 | Isolation, secrets and the no-content boundary | S1–S3 | 17 | 2 rewrite, 8 verify, 7 keep |
| Security | SEC-3 | Owner operations, audit and rollout park | S4, S6 | 6 | 3 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:
prerequisites—read,find_replace(file/find/replace),expected_result.e2e_suitability—verdict(suitable/partial/unsuitable),existing,gaps,requirednew tests.execute—docsto follow and ordered implementationsteps.verify— runnablecommandsand acceptance assertions.staging—target,deploy,observe,abort_criteriaforclient-sandbox-v1.
The protocol is also encoded once at protocol.steps, with the milestone-level
definition of done.
Dispositions
| Disposition | Meaning |
|---|---|
preserve | No runtime change expected; keep the behavior and re-run its suite. |
verify | Logic is runtime-independent, but must be proven on the v1 path. |
rewrite | Runtime coupling requires an adapter/implementation change. |
deprecate | The 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)
- Persistence —
createBackup()/restoreBackup()and the.sqshformat becomeDirectoryBackuprecords; the conversion intent is the point of no return (C5) and must run in theSandboxV1DO (C7). PER-1/PER-2 own 18 of the 41 rewrites. - Serving —
containerFetch/wsConnect/listProcesses/isRuntimeActiveare replaced by the v1 DO transport and lifecycle. OCM-1/OCM-2 own the proxy, health and boot path. - Bridges — leads/docs/software/OTLP/CDP outbound handlers must be
registered on the v1 DO and scoped by
tenantSlugFromEnv, neverctx.containerId(C10). - Owner operations —
stopGatewaymust stay process-scoped; freeze remains the only destructive lifecycle action (C7). SEC-3/PER-3. - 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 observationChange 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.