# Sandbox v1 migration — evaluation plan

> **Machine-readable source of truth:** [`sandbox-v1-evaluation-plan.json`](/assets/docs/plans/sandbox-v1-evaluation-plan.json)
> **Schema:** [`sandbox-v1-evaluation-plan.schema.json`](/assets/docs/plans/sandbox-v1-evaluation-plan.schema.json)
> **Generated from:** [`docs/releases/V1-RELEASE-NOTES.md`](https://github.com/0xCAB0/fouria/blob/develop/docs/releases/V1-RELEASE-NOTES.md)
> (`673b1cdc`) + the S0 contract [`sandbox-v1-cutover-contracts.md`](/llms/platform/reference/plans/sandbox-v1-cutover-contracts/index.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:

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

| 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)

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

```bash
# 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.
