From cd746cff7799d7eaba41cfab1d18a7255390bc25 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Jun 2026 08:01:18 +0200 Subject: [PATCH] docs: refresh SCOPE.md for v0 post SAND-WP-0007 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflect finished workplans 0001–0008, full profile/extension catalog, routing/payments/snapshots surface, 54 tests, and current gaps. --- SCOPE.md | 95 ++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index 5f4ba82..1962b77 100644 --- a/SCOPE.md +++ b/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 -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 / list / destroy / recreate +sandboxer snapshot [--name LABEL] +sandboxer restore +sandboxer snapshots list / snapshots get +sandboxer credits show / credits add +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 |