diff --git a/SCOPE.md b/SCOPE.md index b7dee8a..0e849e2 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,68 +1,63 @@ --- domain: infotech repo: sand-boxer -updated: "2026-06-22" +updated: "2026-06-23" --- # SCOPE > This file helps you quickly understand what this repository is about, > when it is relevant, and when it is not. -> It is intentionally lightweight and may be incomplete until implementation lands. --- ## One-liner -Sandbox provisioning and profile catalog for Custodian — isolated execution -environments where agents and automations can develop, build, and test without -depending on the workstation filesystem or blast radius. +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. --- ## Core Idea -sand-boxer is the **execution isolation and provisioning service** for agentic -development and related workloads in the Custodian ecosystem. It answers where -work can run safely, how isolation is enforced, how sandboxes phone home, and -what happened during their lifecycle. +sand-boxer is the **sandbox establishment service** (OpenRouter for sandboxes). +It answers which recipe applies, which backend fulfills it, where it runs, and +what happened during lifecycle. It is **self-sustained** — it does not depend on +wise-validator or other sibling projects. -A **sandbox profile** is a named, versioned recipe (compose stack, VM image, -future cluster worker) with documented inputs, outputs, host placement, TTL, -and teardown guarantees. Operators and agents request a profile; sand-boxer -provisions an isolated environment on a registered host, exposes reachability -through ops-bridge (without owning tunnels), registers lifecycle state with -State Hub, and tears down on expiry or explicit release. +A **profile** is a named, versioned recipe bound to an **extension** (backend +adapter). Consumers request `create`; sand-boxer provisions on a placement host, +confirms reachability (`ready`), emits State Hub lifecycle events, and tears down +on destroy or operator reap. -The repo consolidates patterns today split across `the-custodian`: -`e2e-framework/` (SSH + compose sandboxes for cross-repo e2e) and -`infra/build-machines/` (Packer VMs with build-agent self-registration). +**wise-validator** (separate repo) consumes sand-boxer for cross-repo e2e +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. --- ## In Scope -- **Sandbox profile catalog** — versioned definitions for compose-based e2e - stacks, VM images, and future worker patterns; inputs, outputs, and teardown - contracts documented per profile -- **Provision / wait / teardown lifecycle** — TTL, idempotent cleanup, port and - network conventions, observable states (create → ready → active → expired → - destroyed) -- **Host placement policy** — which profiles run on sandboxer01, CoulombCore - interim, or other registered hosts; blast-radius isolation from Railiance01 - production -- **CLI and/or API** — request, inspect, and release sandboxes for operators - (`adm`), agents (`agt`), and automations (`atm`) -- **State Hub registration contract** — extend the `build-agent` self-register - pattern to generic sandbox identities and lifecycle events -- **Capability registry entries** in `registry/` for federation via - reuse-surface (e.g. `capability.execution.sandbox-provision`) -- **Runbooks, templates, and tests** — Packer/compose bundles, operator - runbooks, and automated tests for profile lifecycle -- **Migration path** — documented cutover from `the-custodian/e2e-framework` - and `infra/build-machines` callers to sand-boxer profiles -- **Agent and workplan metadata** — `INTENT.md`, `AGENTS.md`, `workplans/`, - and State Hub progress/decision logging per ADR-001 +- **Unified establishment API** — CLI v0 + HTTP stub (`create`, `get`, `list`, + `destroy`, `recreate`); fuller surface (`extend_ttl`, `snapshot`) planned +- **Profile catalog** — `profile.compose-e2e`, `profile.sandbox-canary`; more + profiles and extensions over time +- **Extension platform** — `ext.compose-ssh` (SSH + compose); plugin contract in + `docs/meta-framework.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` +- **Host telemetry** — canary self-deploy, `inspect host` / `inspect stale`, + `reap-stale` (SAND-WP-0008) +- **Capability registry** — `capability.execution.sandbox-provision` (draft) +- **Sibling integration contracts** — `docs/integrations/` (glas-harness, + wise-validator, snuggle-inventor) +- **Runbooks and smoke** — compose-e2e, sandbox-canary; remote smoke scripts +- **Workplans and charter** — ADR-001 files in `workplans/`, `INTENT.md` --- @@ -70,92 +65,90 @@ The repo consolidates patterns today split across `the-custodian`: | Concern | Owner | |---------|--------| -| Workstream, task, and progress state | `state-hub` | -| Cron and event-triggered orchestration | `activity-core` | -| SSH reverse tunnels and tunnel health | `ops-bridge` | +| E2e health checks, test execution, validation results | **wise-validator** | +| Agent gateway, tools, memory | **glas-harness** | +| Code generation, tech specs | **snuggle-inventor** | +| Workstream / task state | `state-hub` | +| Scheduling | `activity-core` | +| SSH tunnels | `ops-bridge` | | SSH certificate issuance | `ops-warden` | -| Canon, charters, agent instruction canon | `the-custodian` | -| Capability index federation hub | `reuse-surface` | -| Production service deployment on Railiance01 | `railiance-apps` / domain repos | -| Railiance01 cluster operations | `railiance-cluster` / `railiance-infra` | -| ADR-001 workplan ↔ DB reconciliation | `state-hub` (`consistency_check.py`) | +| 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 | -sand-boxer may **consume** connectivity (ops-bridge) and certificates -(ops-warden); it must not duplicate or subsume those authorities. - -Additional boundaries: - -- **Scheduling** — activity-core decides *when* work runs; sand-boxer decides - *where* isolated execution happens -- **Workstation as runtime** — the laptop/WSL anchor is interim control plane, - not the target execution surface -- **Irreversible operational decisions** — host provisioning, production - cutovers, and CA policy changes require human approval +sand-boxer **consumes** ops-bridge and ops-warden for reachability; it does not +own tunnels or CAs. --- ## Relevant When -- An agent or automation needs an isolated environment for coding, building, or - testing without laptop filesystem dependence -- Cross-repo e2e tests need a remote compose sandbox with guaranteed teardown -- A build or verification workload should run on dedicated hardware - (sandboxer01) rather than Railiance01 production or the workstation -- activity-core or CI needs a bounded execution venue with State Hub visibility -- Planning reuse of sandbox provisioning across repos (registry-first discovery) +- Provisioning an isolated compose stack on CoulombCore / sandboxer01 +- 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/` +- Migrating off `the-custodian/e2e-framework` provision path --- ## Not Relevant When -- All work runs locally with acceptable blast radius -- Only tunnel connectivity is needed (use `ops-bridge` directly) -- Only task/workstream state is needed (use `state-hub`) -- Only scheduling or rule evaluation is needed (use `activity-core`) -- Deploying or operating production services on Railiance01 +- Running repo e2e tests end-to-end (use **wise-validator** `validate run`) +- Local-only work with acceptable blast radius +- Tunnel or cert operations alone (ops-bridge / ops-warden) +- Task/workstream tracking alone (state-hub) --- ## Current State -- **Status:** bootstrap — repo registered with State Hub; charter written; - implementation not started -- **Implementation:** v0 — CLI, profiles, `ext.compose-ssh`, State Hub events, HTTP stub -- **Docs:** `INTENT.md` (charter, 2026-06-21); `README.md` (one-liner); - `AGENTS.md` and `.custodian-brief.md` (State Hub integration, generated) -- **Registry:** scaffold present (`registry/indexes/capabilities.yaml` empty; - `registry/capabilities/` placeholder); domain in index still `helix_forge` - from scaffold — needs alignment to `infotech` -- **Workplans:** `SAND-WP-0001`–`0002` finished; `SAND-WP-0008` finished - (host telemetry / self-canary) -- **Lineage (external, not yet migrated):** `the-custodian/e2e-framework/` - (CUST-WP-0028, completed) and `infra/build-machines/` (CUST-WP-0032) +- **Status:** v0 operational — self-hosted compose path proven on CoulombCore +- **Workplans finished:** SAND-WP-0001 (bootstrap), 0002 (meta-framework + + `ext.compose-ssh`), 0003 (wise-validator extraction, sibling repo), 0008 (host + telemetry / self-canary) +- **Package:** `src/sandboxer/` — CLI, manager, extensions, telemetry, HTTP API +- **Profiles:** `profile.compose-e2e`, `profile.sandbox-canary` +- **Extensions:** `ext.compose-ssh` only +- **Registry:** `capability.execution.sandbox-provision` indexed (draft) +- **Tests:** 26 pytest cases; `make check` green +- **Sibling:** wise-validator ships `validate run` (SAND-WP-0003) + +Latest gap analysis: `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md` --- ## What Is Possible Now -- Read the charter (`INTENT.md`) and integration instructions (`AGENTS.md`) -- Track bootstrap tasks via `workplans/SAND-WP-0001-statehub-bootstrap.md` -- Log progress and decisions to State Hub when the hub is reachable -- Use **interim** sandbox execution via `the-custodian` directly: - - `make e2e REPO=` (e2e-framework on railiance01/CoulombCore) - - `infra/build-machines/` Packer VMs with build-agent registration +```bash +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 +make smoke-remote # CoulombCore compose smoke (SANDBOXER_HOST) -Nothing in **this repo** provisions or manages sandboxes yet. +# Full e2e validation (wise-validator, separate install): +validate run ~/activity-core +``` + +- State Hub lifecycle events on create/destroy (when hub reachable) +- HTTP API via `uvicorn sandboxer.api.app:app` +- Operator runbooks under `docs/runbooks/` --- ## What Is Not Possible Yet -- Request a sandbox through sand-boxer CLI or API -- Select a named, versioned profile from this repo's catalog -- Register `capability.execution.sandbox-provision` (index entry absent) -- Automatic lifecycle registration of generic sandbox identities in State Hub -- Host placement on sandboxer01 via sand-boxer policy (host may not exist yet) -- activity-core or agents invoking sand-boxer without workstation repo paths -- Local install/test/lint/build commands documented for this repo (no package - layout yet) +- `make e2e REPO=` in the-custodian delegating to sand-boxer (SAND-WP-0004) +- TTL auto-expiry / `extend_ttl` enforcement +- `ext.vm-packer` / build-machines migration (SAND-WP-0005) +- SaaS extensions (E2B, Modal) or payments layer (SAND-WP-0006) +- Snapshot / restore / checkpoint profiles (SAND-WP-0007) +- 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) --- @@ -163,74 +156,55 @@ Nothing in **this repo** provisions or manages sandboxes yet. ```mermaid flowchart LR - AC[activity-core] -->|when| SB[sand-boxer] - AGT[agents / atm] -->|request sandbox| SB - SB -->|provision / teardown| HOST[sandboxer01 / interim host] - SB -->|lifecycle events| SH[state-hub] - SB -->|reachability| OB[ops-bridge] - SB -->|SSH identity| OW[ops-warden] - RS[reuse-surface] -->|federate| REG[registry/] - TC[the-custodian e2e + build-machines] -.->|migrate from| SB + WV[wise-validator] -->|create/destroy| SB[sand-boxer] + GH[glas-harness] -->|create| SB + AC[activity-core] -->|when| WV + AC -->|venue request| SB + 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 ``` -- **Upstream dependencies:** ops-bridge (tunnels), ops-warden (certs, optional), - State Hub (registration API), registered sandbox hosts (SSH + Docker/Packer) -- **Downstream consumers:** LLM agents, activity-core instructions, CI hooks, - cross-repo e2e callers migrating off `the-custodian` -- **Often used with:** `activity-core` (orchestration), `state-hub` (visibility), - `reuse-surface` (capability discovery) - --- ## Terminology -- **Profile** — named, versioned sandbox type with provision/teardown contract -- **Sandbox** — a running isolated environment instance of a profile -- **Host placement** — policy mapping profiles to sandboxer01, CoulombCore, etc. -- **TTL** — time-to-live; sandboxes are disposable by default -- **Phone home** — reachability and registration via ops-bridge + State Hub -- Actor types (consumers): `adm` (operator), `agt` (LLM agent), `atm` (automation) +- **Profile** — named sandbox recipe (extension binding, placement, TTL metadata) +- **Extension** — backend adapter (`provision`, `wait_ready`, `teardown`) +- **Establishment** — create through `ready` (distinct from validation pass/fail) +- **Canary** — `profile.sandbox-canary` self-deploy with host telemetry +- Actor types: `adm`, `agt`, `atm` --- ## Related / Overlapping -- `the-custodian` — current home of e2e-framework and build-machines; governance - canon; sand-boxer extracts reusable execution platform from here -- `ops-bridge` — SSH reverse tunnels; sand-boxer orchestrates reachability, does - not run tunnel daemons -- `ops-warden` — SSH CA and certificate issuance -- `state-hub` — workstream/task state and sandbox lifecycle visibility -- `activity-core` — schedules work; may request sandboxes as execution venue -- `reuse-surface` — federates `registry/` capability entries -- `railiance-cluster` / `railiance-apps` — production layer; explicitly not - sandbox execution surface +- **wise-validator** — validation orchestration; one-way consumer of sand-boxer +- **the-custodian** — legacy `e2e-framework/`; shim migration pending +- **ops-bridge** / **ops-warden** — connectivity and identity consumers +- **state-hub** — lifecycle visibility +- **reuse-surface** — capability federation target --- ## Provided Capabilities -*Planned — not yet registered in `registry/indexes/capabilities.yaml`.* - -```capability -type: execution -title: Sandbox provisioning -description: Isolated execution environments for agentic development, e2e testing, and bounded automations — profile-based provision, TTL teardown, and State Hub lifecycle registration. -keywords: [sandbox, isolation, provision, e2e, agentic, execution, profile] -``` - -Target registry id: `capability.execution.sandbox-provision` (or equivalent per -reuse-surface naming). +Registered (draft): `capability.execution.sandbox-provision` — +see `registry/capabilities/execution.sandbox-provision.md`. --- ## Getting Oriented -- Start with: `INTENT.md` (meta-framework charter) -- Research: `research/` (landscape, reference systems, design synthesis) -- Agent instructions: `AGENTS.md` (State Hub session protocol) -- Offline brief: `.custodian-brief.md` -- Workplans: `workplans/` (bootstrap: `SAND-WP-0001`) -- Registry authoring: `registry/README.md` -- Lineage reference (external): `the-custodian/e2e-framework/RUNBOOK.md`, - `the-custodian/infra/build-machines/README.md` \ No newline at end of file +| Path | Purpose | +|------|---------| +| `INTENT.md` | Charter and sibling boundaries | +| `docs/meta-framework.md` | API, lifecycle, extension contract | +| `docs/host-telemetry.md` | Canary and inventory | +| `docs/migration-gaps.md` | Legacy cutover status | +| `docs/integrations/` | Consumer contracts | +| `workplans/` | ADR-001 work structure | +| `history/` | INTENT ↔ SCOPE assessments | +| `AGENTS.md` | Session protocol | \ No newline at end of file diff --git a/history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md b/history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md new file mode 100644 index 0000000..e09c90a --- /dev/null +++ b/history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md @@ -0,0 +1,198 @@ +# INTENT ↔ SCOPE Gap Analysis — Post SAND-WP-0003 + +**Date:** 2026-06-23 +**Author:** codex +**Trigger:** SAND-WP-0003 finished (wise-validator extraction); SAND-WP-0001/0002/0008 +already complete. SCOPE.md stale (still described bootstrap / not-started state). +**Prior assessment:** none (first `history/` entry for sand-boxer) + +--- + +## 1. Executive summary + +sand-boxer has crossed from **bootstrap** to **v0 operational** for the self-hosted +compose path. The establishment half of `the-custodian/e2e-framework/` is migrated +(`ext.compose-ssh`); the validation half lives in **wise-validator** (`validate run`). +Host telemetry and canary self-deploy (SAND-WP-0008) make the repo self-sustained per +INTENT. + +Remaining distance to INTENT is **migration completion** (the-custodian shim), +**extension breadth** (vm-packer, SaaS), **lifecycle depth** (TTL enforcement, +snapshots), and **operational maturity** (sandboxer01, reuse-surface publish, +security runbooks). + +**Vector movement:** `D4/A1/C1/R1` (bootstrap) → **`D5/A3/C3/R3`** + +| Dimension | Was (SCOPE 2026-06-22) | Now | Notes | +| --- | --- | --- | --- | +| Discovery | D4 | **D5** | INTENT, research, meta-framework spec, integration docs | +| Availability | A1 | **A3** | CLI + HTTP v0; CoulombCore remote smoke proven | +| Completeness | C1 | **C3** | Pillar 1–2 partial; pillars 3–4 (extensions breadth, payments) absent | +| Reliability | R1 | **R3** | Remote smoke, telemetry, stale inventory; no TTL auto-reap scheduler | + +--- + +## 2. Workplan deliverables (cumulative) + +| Workplan | Status | Key deliverable | +| --- | --- | --- | +| SAND-WP-0001 | finished | Python scaffold, AGENTS.md, dev workflow | +| SAND-WP-0002 | finished | Meta-framework, `ext.compose-ssh`, CLI, HTTP stub, registry | +| SAND-WP-0003 | finished | wise-validator sibling (`validate run`, schema/runner/reporter) | +| SAND-WP-0008 | finished | `profile.sandbox-canary`, telemetry, `inspect` / `reap-stale` | + +--- + +## 3. INTENT — four pillars + +### Pillar 1: Unified establishment API + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| `create` / `get` / `list` / `destroy` / `recreate` | Required v0 | **Done** | CLI + HTTP | +| `extend_ttl` | API shape | **Stub only** | No implementation | +| `snapshot` / `restore` | Later completeness | **Absent** | SAND-WP-0007 | +| `active` state transition | Lifecycle | **Absent** | Optional; not wired | +| Consumer attribution | `adm`/`agt`/`atm` + project | **Done** | — | +| Full HTTP surface | Parallel to CLI | **Partial** | No `recreate`, host query param only on create | + +### Pillar 2: Profile catalog + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| `profile.compose-e2e` | Reference profile | **Done** | Remote-verified | +| `profile.sandbox-canary` | Self-dogfood | **Done** | SAND-WP-0008 | +| Agent-dev / health-probe profiles | Future consumers | **Absent** | glas-harness / wise-validator profiles | +| `ext.vm-packer` lineage | build-machines | **Absent** | SAND-WP-0005 | +| Registry + reuse-surface federation | Registry-first | **Draft only** | No `reuse-surface validate` publish | +| Setup metadata / secret refs | Blitzy pattern | **Schema only** | No resolution at provision boundary | + +### Pillar 3: Extension platform + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| `ext.compose-ssh` | First self-hosted | **Done** | podman-compose on CoulombCore | +| Extension SDK / author contract | Near-term outcome #7 | **Absent** | Documented in meta-framework only | +| vm-packer, Daytona OSS, OpenShell | Self-hosted class | **Absent** | SAND-WP-0005 | +| E2B, Modal, SaaS adapters | SaaS class | **Absent** | SAND-WP-0006 | +| `estimate_cost` optional hook | Extension interface | **Absent** | — | +| Routing policy engine | Multi-backend | **Deferred** | Explicit profile→extension today | + +### Pillar 4: Payments and metering + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| Credits / usage accounting | SaaS extensions | **Absent** | SAND-WP-0006 | +| BYOK for provider keys | SaaS | **Absent** | — | +| Self-hosted allocation metering | Host/duration | **Partial** | Telemetry deltas only; no billing export | + +--- + +## 4. INTENT — governing principle (seven questions) + +| # | Question | Status | Evidence / gap | +| --- | --- | --- | --- | +| 1 | Which sandbox recipe? | **Met** | Profile loader, two profiles | +| 2 | Which backend? | **Partial** | Single extension; no routing engine | +| 3 | Where does it run? | **Partial** | Placement env vars; sandboxer01 not live | +| 4 | How is isolation enforced? | **Partial** | Compose project isolation; network default-deny declarative only | +| 5 | How reachable? | **Partial** | SSH direct; ops-bridge/warden not integrated in descriptor | +| 6 | What happened? | **Met** | State Hub events + local store | +| 7 | What did it cost? | **Not met** | Payments layer absent | + +**Score: 2 met, 4 partial, 1 not met** + +--- + +## 5. Self-sufficiency and sibling boundaries + +| Criterion | Status | Notes | +| --- | --- | --- | +| Operates without wise-validator | **Met** | `sandboxer create` / canary / smoke | +| wise-validator optional consumer | **Met** | SAND-WP-0003; one-way dependency documented | +| sand-boxer does not validate | **Met** | Health/test in wise-validator | +| glas-harness / snuggle-inventor contracts | **Partial** | Integration docs only; no consumer smoke | +| Monolith not recreated | **Met** | Provision vs validation split holds | + +--- + +## 6. Near-term outcomes (INTENT § Near-term) + +| # | Outcome | Status | +| --- | --- | --- | +| 1 | Charter and research | **Done** | +| 2 | First self-hosted extension | **Done** | +| 3 | Unified API v0 | **Done** | +| 4 | Profile catalog start | **Done** | +| 5 | Registry entry | **Done** (draft) | +| 6 | Sibling integration notes | **Done** | +| 7 | Extension SDK sketch | **Open** | +| 8 | wise-validator | **Done** (sibling repo) | + +--- + +## 7. Maturity target gaps + +| Maturity statement | Status | Track | +| --- | --- | --- | +| glas-harness requests sandboxes without backend choice | **Not yet** | Extension SDK + agent-dev profile | +| wise-validator may request validation environments | **Met** | `validate run` uses `profile.compose-e2e` | +| snuggle-inventor build sandboxes with setup metadata | **Not yet** | Secret boundary + profile inputs | +| activity-core / CI bounded venues + visibility | **Partial** | Lifecycle events; no activity-core wiring | +| Operators route self-hosted vs SaaS spend | **Not yet** | SAND-WP-0006 | +| Workstation optional for runtime | **Partial** | Remote path works; custodian shim still default for some | + +--- + +## 8. SCOPE.md drift (corrected 2026-06-23) + +| SCOPE claim (2026-06-22) | Actual state | +| --- | --- | +| "implementation not started" | v0 shipped | +| "Nothing in this repo provisions sandboxes" | `sandboxer create` provisions | +| "registry empty / helix_forge" | indexed `infotech` capability | +| "wise-validator migration not complete" | SAND-WP-0003 done | +| Interim `make e2e` only path | Still true until SAND-WP-0004 | + +--- + +## 9. Remaining gaps (prioritized) + +| Prio | Gap | Owner / repo | Proposed track | +| --- | --- | --- | --- | +| **P1** | `the-custodian` `make e2e REPO=` → `validate run` shim | the-custodian + wise-validator | **SAND-WP-0004** | +| **P2** | Extension SDK sketch + `ext.vm-packer` / build-machines | sand-boxer | **SAND-WP-0005** (INTENT near-term #7 + WP-0002 follow-on) | +| **P3** | TTL enforcement + `extend_ttl` + activity-core reap hook | sand-boxer + activity-core | New workplan after 0005 | +| **P5** | `.repo-classification.yaml` + reuse-surface validate | sand-boxer | Ad hoc or WP task | +| **P6** | Security runbook (blast-radius vs intent enforcement) | sand-boxer docs | Ad hoc | +| **P7** | sandboxer01 dedicated host + placement live | infra / operator | Outside repo | +| **P8** | SaaS extensions + payments | sand-boxer | **SAND-WP-0006** | +| **P9** | Snapshot / restore profiles | sand-boxer | **SAND-WP-0007** | +| **P10** | wise-validator remote smoke sign-off (T09) | wise-validator | Operator verification | + +**Note:** SAND-WP-0002 follow-on numbering reserves 0004–0007. Next workplan should be +**SAND-WP-0004** (custodian shim) to close the e2e-framework migration arc. + +--- + +## 10. Recommended next workplan + +**SAND-WP-0004 — the-custodian e2e shim and deprecation** + +Closes P1: operators keep `make e2e REPO=` while implementation delegates to +`validate run` (wise-validator + sand-boxer). Updates RUNBOOK pointers; adds +deprecation notice on `python -m e2e_framework`. + +Subsequent: **SAND-WP-0005** (`ext.vm-packer` + extension SDK), then operational +hardening (TTL, reuse-surface publish). + +--- + +## 11. Evidence references + +- `workplans/SAND-WP-0002-meta-framework-foundation.md` (finished) +- `workplans/SAND-WP-0003-wise-validator-extraction.md` (finished) +- `workplans/SAND-WP-0008-host-telemetry-and-self-canary.md` (finished) +- `docs/migration-gaps.md` +- `wise-validator/docs/runbooks/validate-compose-e2e.md` +- CoulombCore smoke: `scripts/smoke-compose-e2e.sh` (SAND-WP-0002-T10) \ No newline at end of file diff --git a/workplans/SAND-WP-0004-the-custodian-e2e-shim.md b/workplans/SAND-WP-0004-the-custodian-e2e-shim.md new file mode 100644 index 0000000..8a5ecb2 --- /dev/null +++ b/workplans/SAND-WP-0004-the-custodian-e2e-shim.md @@ -0,0 +1,115 @@ +--- +id: SAND-WP-0004 +type: workplan +title: "the-custodian e2e shim and deprecation" +domain: infotech +repo: sand-boxer +status: ready +owner: codex +topic_slug: custodian +created: "2026-06-23" +updated: "2026-06-23" +--- + +# the-custodian e2e shim and deprecation + +Complete the `e2e-framework/` migration arc: operators keep `make e2e REPO=` in +`the-custodian`, but execution delegates to **wise-validator** (`validate run`) +and **sand-boxer** (provision via `profile.compose-e2e`). Retire embedded +provision/validation in `e2e-framework/` with deprecation notices. + +**Charter:** `INTENT.md` (lineage), `docs/migration-gaps.md` +**Predecessor:** SAND-WP-0003 (wise-validator extraction — finished) +**Gap analysis:** `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md` (P1) + +Primary implementation touches `the-custodian`; sand-boxer owns coordination, +doc pointers, and verification runbook updates. + +## Shim Makefile target + +```task +id: SAND-WP-0004-T01 +status: todo +priority: high +``` + +In `the-custodian/Makefile` (or documented wrapper), replace `e2e` target body: + +- Resolve `REPO` path (`~/REPO` or `REPO_ROOT/REPO`) +- Invoke `validate run ` with env passthrough: + `HOST` → `SANDBOXER_HOST`, `KEEP`, `WORKSTREAM_ID`, `SANDBOXER_COMPOSE_CMD` +- Preserve exit code semantics (0 pass / 1 fail) +- Document prerequisites: `sandboxer` + `validate` on PATH + +## Deprecate e2e_framework module + +```task +id: SAND-WP-0004-T02 +status: todo +priority: high +``` + +`the-custodian/e2e-framework/`: + +- `cli.py` / `__main__.py`: print deprecation warning; delegate to + `validate run` via subprocess (thin wrapper for backward compat) +- `sandbox.py`: mark module deprecated — provision owned by sand-boxer +- Keep files until one release cycle; no new features + +## Runbook and doc migration + +```task +id: SAND-WP-0004-T03 +status: todo +priority: medium +``` + +- Update `the-custodian/e2e-framework/RUNBOOK.md` — banner pointing to + `wise-validator/docs/runbooks/validate-compose-e2e.md` and + `sand-boxer/docs/runbooks/profile-compose-e2e.md` +- Update `sand-boxer/docs/migration-gaps.md` — mark SAND-WP-0004 delivered +- Update `SCOPE.md` "What Is Possible Now" if needed + +## Verification + +```task +id: SAND-WP-0004-T04 +status: todo +priority: high +``` + +- Document verification steps (CoulombCore): `make e2e REPO=sand-boxer` and + `make e2e REPO=activity-core` with `SANDBOXER_HOST` + `podman-compose` +- Optional: add `scripts/verify-e2e-shim.sh` in the-custodian +- wise-validator T09 remote smoke can satisfy sand-boxer path; activity-core + run is stretch goal (Temporal slow start) + +## activity-core scheduling pointer (optional) + +```task +id: SAND-WP-0004-T05 +status: wait +priority: low +``` + +Document how activity-core instructions should invoke `validate run` instead of +`make e2e` — no activity-core code changes in this workplan unless a ready +instruction template exists. + +--- + +## Success criteria + +- `make e2e REPO=` from `the-custodian` uses wise-validator + sand-boxer +- No new code paths call `e2e_framework.sandbox.provision()` directly +- Deprecation visible on legacy `python -m e2e_framework` entry +- Migration gaps doc shows e2e-framework arc complete + +## Follow-ons (from gap analysis) + +| Item | Workplan | +|------|----------| +| Extension SDK + `ext.vm-packer` | SAND-WP-0005 | +| TTL enforcement + scheduled reap | TBD (extend telemetry or new WP) | +| SaaS extensions + payments | SAND-WP-0006 | +| Snapshot / restore | SAND-WP-0007 | \ No newline at end of file