docs: refresh SCOPE.md for v0 post SAND-WP-0007

Reflect finished workplans 0001–0008, full profile/extension catalog,
routing/payments/snapshots surface, 54 tests, and current gaps.

SCOPE.md

@@ -14,8 +14,9 @@ updated: "2026-06-24"
 ## One-liner
 
 Coulomb meta-framework for **establishing sandboxes** — profile-based provision,
-extension routing, lifecycle registration, and host telemetry — so agents and
-automations run in isolated venues without workstation blast radius.
+extension routing, workspace checkpoints, lifecycle registration, and host
+telemetry — so agents and automations run in isolated venues without workstation
+blast radius.
 
 ---
 
@@ -35,7 +36,8 @@ on destroy or operator reap.
 validation; sand-boxer does not run health checks or test commands.
 
 Lineage: provision/teardown extracted from `the-custodian/e2e-framework/`;
-`infra/build-machines/` remains future `ext.vm-packer` work.
+`ext.vm-packer` attach mode covers build-machine workspaces; full Packer build
+orchestration from `create` remains deferred.
 
 ---
 
@@ -43,15 +45,19 @@ Lineage: provision/teardown extracted from `the-custodian/e2e-framework/`;
 
 - **Unified establishment API** — CLI v0 + HTTP stub (`create`, `get`, `list`,
   `destroy`, `recreate`, `snapshot`, `restore`); `extend_ttl` planned
-- **Profile catalog** — `profile.compose-e2e`, `profile.compose-checkpoint`,
-  `profile.sandbox-canary`; more
-  profiles and extensions over time
-- **Extension platform** — `ext.compose-ssh` (SSH + compose); plugin contract in
-  `docs/meta-framework.md`
+- **Profile catalog** — six profiles: compose e2e/checkpoint, sandbox canary,
+  vm-haskell-build, saas-stub, burst-sandbox
+- **Extension platform** — `ext.compose-ssh`, `ext.vm-packer`, `ext.saas-stub`;
+  plugin contract in `docs/meta-framework.md` and `docs/extension-sdk.md`
+- **Routing engine** — `RouteSpec` strategies (`prefer-self-hosted`, `lowest-cost`,
+  `lowest-latency`, `explicit`); see `docs/routing.md`
+- **Payments v0** — credits store, pre-create balance check, post-destroy debit
+  for metered extensions; see `docs/payments.md`
+- **Workspace checkpoints** — snapshot index + extension hooks; see `docs/snapshots.md`
 - **Host placement** — profile `placement` + `SANDBOXER_HOST` overrides;
   sandboxer01 preferred, CoulombCore interim
-- **Lifecycle + State Hub** — transitions emit progress events; JSON store at
-  `~/.local/share/sandboxer/sandboxes.json`
+- **Lifecycle + State Hub** — transitions emit progress events; JSON stores at
+  `~/.local/share/sandboxer/sandboxes.json` and `snapshots.json`
 - **Host telemetry** — canary self-deploy, `inspect host` / `inspect stale`,
   `reap-stale` (SAND-WP-0008)
 - **Capability registry** — `capability.execution.sandbox-provision` (draft)
@@ -76,7 +82,8 @@ Lineage: provision/teardown extracted from `the-custodian/e2e-framework/`;
 | Canon and agent instruction canon | `the-custodian` |
 | Capability federation hub | `reuse-surface` |
 | Production on Railiance01 | `railiance-apps` / domain repos |
-| SaaS sandbox metering / payments | Future SAND-WP-0006 |
+| Real E2B / Modal / Daytona cloud APIs | Future adapters (stub in-repo) |
+| fin-hub billing export | Future |
 
 sand-boxer **consumes** ops-bridge and ops-warden for reachability; it does not
 own tunnels or CAs.
@@ -86,6 +93,9 @@ own tunnels or CAs.
 ## Relevant When
 
 - Provisioning an isolated compose stack on CoulombCore / sandboxer01
+- Attaching a workspace on a pre-built VM (`profile.vm-haskell-build`)
+- Saving or restoring a workspace checkpoint (`profile.compose-checkpoint`)
+- Choosing self-hosted vs metered SaaS backend (`profile.burst-sandbox`)
 - Canary self-deploy or host inventory before placing workloads
 - activity-core, CI, glas-harness, or wise-validator need a sandbox handle
 - Discovering sandbox capability via `registry/`
@@ -104,17 +114,26 @@ own tunnels or CAs.
 
 ## Current State
 
-- **Status:** v0 operational — self-hosted compose path proven on CoulombCore
-- **Workplans finished:** SAND-WP-0001–0005, 0008 (see `workplans/`)
-- **Package:** `src/sandboxer/` — CLI, manager, extensions, telemetry, HTTP API
-- **Profiles:** `profile.compose-e2e`, `profile.sandbox-canary`, `profile.vm-haskell-build`
-- **Extensions:** `ext.compose-ssh`, `ext.vm-packer`, `ext.saas-stub` (metered)
-- **Routing + payments:** `docs/routing.md`, `docs/payments.md`, `sandboxer credits`
+- **Status:** v0 operational — self-hosted compose path proven on CoulombCore;
+  routing, payments stub, and snapshots shipped
+- **Workplans finished:** SAND-WP-0001–0008 (all workplans in `workplans/`;
+  0003/0004 delivered in sibling repos wise-validator / the-custodian)
+- **Package:** `src/sandboxer/` — CLI, manager, extensions, routing, payments,
+  snapshots, telemetry, HTTP API
+- **Profiles:** `profile.compose-e2e`, `profile.compose-checkpoint`,
+  `profile.sandbox-canary`, `profile.vm-haskell-build`, `profile.saas-stub`,
+  `profile.burst-sandbox`
+- **Extensions:** `ext.compose-ssh` (compose + tar snapshots),
+  `ext.vm-packer` (attach), `ext.saas-stub` (metered stub + metadata snapshots)
+- **Docs:** `meta-framework`, `extension-sdk`, `host-telemetry`, `routing`,
+  `payments`, `snapshots`, `migration-gaps`, `migration-build-machines`
 - **Registry:** `capability.execution.sandbox-provision` indexed (draft)
-- **Tests:** 26 pytest cases; `make check` green
-- **Sibling:** wise-validator ships `validate run` (SAND-WP-0003)
+- **Tests:** 54 pytest cases; `make check` green
+- **Siblings:** wise-validator `validate run` (SAND-WP-0003); the-custodian
+  `make e2e REPO=` shim (SAND-WP-0004)
 
 Latest gap analysis: `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md`
+(partially superseded by SAND-WP-0005–0007 delivery).
 
 ---
 
@@ -124,8 +143,14 @@ Latest gap analysis: `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.m
 make setup && make install          # sandboxer CLI
 sandboxer create                    # canary self-deploy (no args)
 sandboxer create --profile profile.compose-e2e --input repo=/path/to/repo
-sandboxer destroy <id>
-sandboxer inspect host / inspect stale / reap-stale
+sandboxer create --profile profile.vm-haskell-build --input vm=haskell-build --input repo=/path
+sandboxer create --profile profile.burst-sandbox   # routes to saas-stub when needed
+sandboxer get <id> / list / destroy / recreate
+sandboxer snapshot <id> [--name LABEL]
+sandboxer restore <snapshot_id>
+sandboxer snapshots list / snapshots get <id>
+sandboxer credits show / credits add <amount>
+sandboxer inspect host / inspect stale / reap-stale [--apply]
 make smoke-remote                   # CoulombCore compose smoke (SANDBOXER_HOST)
 
 # Full e2e validation (wise-validator, separate install):
@@ -135,23 +160,23 @@ validate run ~/activity-core
 cd ~/the-custodian && make e2e REPO=activity-core
 ```
 
-- State Hub lifecycle events on create/destroy (when hub reachable)
-- HTTP API via `uvicorn sandboxer.api.app:app`
+- State Hub lifecycle events on create/destroy/snapshot (when hub reachable)
+- HTTP API via `uvicorn sandboxer.api.app:app` (sandboxes + snapshots)
 - Operator runbooks under `docs/runbooks/`
 
 ---
 
 ## What Is Not Possible Yet
 
-- ~~`make e2e REPO=` shim~~ — done (SAND-WP-0004; delegates to `validate run`)
 - TTL auto-expiry / `extend_ttl` enforcement
-- ~~`ext.vm-packer` attach mode~~ — done (SAND-WP-0005); Packer build orchestration deferred
-- Real E2B / Modal adapters (stub + payments v0 done in SAND-WP-0006)
-- ~~Snapshot / restore / checkpoint profiles~~ — done (SAND-WP-0007)
+- Packer build orchestration from `create` (attach-only today)
+- Real E2B / Modal / Daytona adapters (in-repo stub only)
+- Cross-host snapshot transfer
 - Formal ops-bridge tunnel attachment in reachability descriptor
 - Dedicated sandboxer01 host (CoulombCore interim only today)
 - `reuse-surface validate` / federation publish workflow
 - `.repo-classification.yaml` (State Hub C-24 hygiene)
+- fin-hub billing export for metered usage
 
 ---
 
@@ -166,8 +191,8 @@ flowchart LR
   SB -->|provision| HOST[CoulombCore / sandboxer01]
   SB -->|lifecycle| SH[state-hub]
   SB -->|SSH reachability| OB[ops-bridge]
-  TC[the-custodian e2e-framework] -.->|migrate| WV
-  TC -.->|provision migrate| SB
+  TC[the-custodian] -.->|make e2e shim| WV
+  TC -.->|provision| SB
 ```
 
 ---
@@ -175,8 +200,11 @@ flowchart LR
 ## Terminology
 
 - **Profile** — named sandbox recipe (extension binding, placement, TTL metadata)
-- **Extension** — backend adapter (`provision`, `wait_ready`, `teardown`)
+- **Extension** — backend adapter (`provision`, `wait_ready`, `teardown`; optional
+  `snapshot` / `restore_from_snapshot`)
 - **Establishment** — create through `ready` (distinct from validation pass/fail)
+- **Snapshot** — point-in-time workspace checkpoint; restore creates a new sandbox
+- **Route** — extension selection policy when multiple backends qualify
 - **Canary** — `profile.sandbox-canary` self-deploy with host telemetry
 - Actor types: `adm`, `agt`, `atm`
 
@@ -185,7 +213,8 @@ flowchart LR
 ## Related / Overlapping
 
 - **wise-validator** — validation orchestration; one-way consumer of sand-boxer
-- **the-custodian** — legacy `e2e-framework/`; shim migration pending
+- **the-custodian** — legacy `e2e-framework/`; `make e2e` shim delegates to
+  wise-validator (SAND-WP-0004)
 - **ops-bridge** / **ops-warden** — connectivity and identity consumers
 - **state-hub** — lifecycle visibility
 - **reuse-surface** — capability federation target
@@ -205,7 +234,11 @@ see `registry/capabilities/execution.sandbox-provision.md`.
 |------|---------|
 | `INTENT.md` | Charter and sibling boundaries |
 | `docs/meta-framework.md` | API, lifecycle, extension contract |
+| `docs/extension-sdk.md` | Extension author guide |
 | `docs/host-telemetry.md` | Canary and inventory |
+| `docs/routing.md` | Backend selection strategies |
+| `docs/payments.md` | Credits and metering |
+| `docs/snapshots.md` | Checkpoint snapshot/restore |
 | `docs/migration-gaps.md` | Legacy cutover status |
 | `docs/integrations/` | Consumer contracts |
 | `workplans/` | ADR-001 work structure |