coulomb/sand-boxer
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update SCOPE, gap analysis, and propose SAND-WP-0004

Browse Source 
Refresh SCOPE.md for v0 operational state after WP-0002/0003/0008.
Add history/ INTENT↔SCOPE assessment and ready workplan for the-custodian
e2e shim to close the e2e-framework migration arc.
This commit is contained in:
Bernd Worsch
2026-06-23 21:40:43 +02:00
parent e7d31b7f55
commit 6473fa78d7
3 changed files with 434 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
SCOPE.md
View File

@@ -1,68 +1,63 @@
--- ---
domain: infotech domain: infotech
repo: sand-boxer repo: sand-boxer
updated: "2026-06-22" updated: "2026-06-23"
--- ---
# SCOPE # SCOPE
> This file helps you quickly understand what this repository is about, > This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not. > when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete until implementation lands.
--- ---
## One-liner ## One-liner
Sandbox provisioning and profile catalog for Custodian — isolated execution Coulomb meta-framework for **establishing sandboxes** — profile-based provision,
environments where agents and automations can develop, build, and test without extension routing, lifecycle registration, and host telemetry — so agents and
depending on the workstation filesystem or blast radius. automations run in isolated venues without workstation blast radius.
--- ---
## Core Idea ## Core Idea
sand-boxer is the **execution isolation and provisioning service** for agentic sand-boxer is the **sandbox establishment service** (OpenRouter for sandboxes).
development and related workloads in the Custodian ecosystem. It answers where It answers which recipe applies, which backend fulfills it, where it runs, and
work can run safely, how isolation is enforced, how sandboxes phone home, and what happened during lifecycle. It is **self-sustained** — it does not depend on
what happened during their lifecycle. wise-validator or other sibling projects.
A **sandbox profile** is a named, versioned recipe (compose stack, VM image, A **profile** is a named, versioned recipe bound to an **extension** (backend
future cluster worker) with documented inputs, outputs, host placement, TTL, adapter). Consumers request `create`; sand-boxer provisions on a placement host,
and teardown guarantees. Operators and agents request a profile; sand-boxer confirms reachability (`ready`), emits State Hub lifecycle events, and tears down
provisions an isolated environment on a registered host, exposes reachability on destroy or operator reap.
through ops-bridge (without owning tunnels), registers lifecycle state with
State Hub, and tears down on expiry or explicit release.
The repo consolidates patterns today split across `the-custodian`: **wise-validator** (separate repo) consumes sand-boxer for cross-repo e2e
`e2e-framework/` (SSH + compose sandboxes for cross-repo e2e) and validation; sand-boxer does not run health checks or test commands.
`infra/build-machines/` (Packer VMs with build-agent self-registration).
Lineage: provision/teardown extracted from `the-custodian/e2e-framework/`;
`infra/build-machines/` remains future `ext.vm-packer` work.
--- ---
## In Scope ## In Scope
- **Sandbox profile catalog** — versioned definitions for compose-based e2e - **Unified establishment API** — CLI v0 + HTTP stub (`create`, `get`, `list`,
stacks, VM images, and future worker patterns; inputs, outputs, and teardown `destroy`, `recreate`); fuller surface (`extend_ttl`, `snapshot`) planned
contracts documented per profile - **Profile catalog** — `profile.compose-e2e`, `profile.sandbox-canary`; more
- **Provision / wait / teardown lifecycle** — TTL, idempotent cleanup, port and profiles and extensions over time
network conventions, observable states (create → ready → active → expired → - **Extension platform** — `ext.compose-ssh` (SSH + compose); plugin contract in
destroyed) `docs/meta-framework.md`
- **Host placement policy** — which profiles run on sandboxer01, CoulombCore - **Host placement** — profile `placement` + `SANDBOXER_HOST` overrides;
interim, or other registered hosts; blast-radius isolation from Railiance01 sandboxer01 preferred, CoulombCore interim
production - **Lifecycle + State Hub** — transitions emit progress events; JSON store at
- **CLI and/or API** — request, inspect, and release sandboxes for operators `~/.local/share/sandboxer/sandboxes.json`
(`adm`), agents (`agt`), and automations (`atm`) - **Host telemetry** — canary self-deploy, `inspect host` / `inspect stale`,
- **State Hub registration contract** — extend the `build-agent` self-register `reap-stale` (SAND-WP-0008)
pattern to generic sandbox identities and lifecycle events - **Capability registry** — `capability.execution.sandbox-provision` (draft)
- **Capability registry entries** in `registry/` for federation via - **Sibling integration contracts** — `docs/integrations/` (glas-harness,
reuse-surface (e.g. `capability.execution.sandbox-provision`) wise-validator, snuggle-inventor)
- **Runbooks, templates, and tests** — Packer/compose bundles, operator - **Runbooks and smoke** — compose-e2e, sandbox-canary; remote smoke scripts
runbooks, and automated tests for profile lifecycle - **Workplans and charter** — ADR-001 files in `workplans/`, `INTENT.md`
- **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
--- ---
@@ -70,92 +65,90 @@ The repo consolidates patterns today split across `the-custodian`:
| Concern | Owner | | Concern | Owner |
|---------|--------| |---------|--------|
| Workstream, task, and progress state | `state-hub` | | E2e health checks, test execution, validation results | **wise-validator** |
| Cron and event-triggered orchestration | `activity-core` | | Agent gateway, tools, memory | **glas-harness** |
| SSH reverse tunnels and tunnel health | `ops-bridge` | | Code generation, tech specs | **snuggle-inventor** |
| Workstream / task state | `state-hub` |
| Scheduling | `activity-core` |
| SSH tunnels | `ops-bridge` |
| SSH certificate issuance | `ops-warden` | | SSH certificate issuance | `ops-warden` |
| Canon, charters, agent instruction canon | `the-custodian` | | Canon and agent instruction canon | `the-custodian` |
| Capability index federation hub | `reuse-surface` | | Capability federation hub | `reuse-surface` |
| Production service deployment on Railiance01 | `railiance-apps` / domain repos | | Production on Railiance01 | `railiance-apps` / domain repos |
| Railiance01 cluster operations | `railiance-cluster` / `railiance-infra` | | SaaS sandbox metering / payments | Future SAND-WP-0006 |
| ADR-001 workplan ↔ DB reconciliation | `state-hub` (`consistency_check.py`) |
sand-boxer may **consume** connectivity (ops-bridge) and certificates sand-boxer **consumes** ops-bridge and ops-warden for reachability; it does not
(ops-warden); it must not duplicate or subsume those authorities. own tunnels or CAs.
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
--- ---
## Relevant When ## Relevant When
- An agent or automation needs an isolated environment for coding, building, or - Provisioning an isolated compose stack on CoulombCore / sandboxer01
testing without laptop filesystem dependence - Canary self-deploy or host inventory before placing workloads
- Cross-repo e2e tests need a remote compose sandbox with guaranteed teardown - activity-core, CI, glas-harness, or wise-validator need a sandbox handle
- A build or verification workload should run on dedicated hardware - Discovering sandbox capability via `registry/`
(sandboxer01) rather than Railiance01 production or the workstation - Migrating off `the-custodian/e2e-framework` provision path
- activity-core or CI needs a bounded execution venue with State Hub visibility
- Planning reuse of sandbox provisioning across repos (registry-first discovery)
--- ---
## Not Relevant When ## Not Relevant When
- All work runs locally with acceptable blast radius - Running repo e2e tests end-to-end (use **wise-validator** `validate run`)
- Only tunnel connectivity is needed (use `ops-bridge` directly) - Local-only work with acceptable blast radius
- Only task/workstream state is needed (use `state-hub`) - Tunnel or cert operations alone (ops-bridge / ops-warden)
- Only scheduling or rule evaluation is needed (use `activity-core`) - Task/workstream tracking alone (state-hub)
- Deploying or operating production services on Railiance01
--- ---
## Current State ## Current State
- **Status:** bootstrap — repo registered with State Hub; charter written; - **Status:** v0 operational — self-hosted compose path proven on CoulombCore
implementation not started - **Workplans finished:** SAND-WP-0001 (bootstrap), 0002 (meta-framework +
- **Implementation:** v0 — CLI, profiles, `ext.compose-ssh`, State Hub events, HTTP stub `ext.compose-ssh`), 0003 (wise-validator extraction, sibling repo), 0008 (host
- **Docs:** `INTENT.md` (charter, 2026-06-21); `README.md` (one-liner); telemetry / self-canary)
`AGENTS.md` and `.custodian-brief.md` (State Hub integration, generated) - **Package:** `src/sandboxer/` — CLI, manager, extensions, telemetry, HTTP API
- **Registry:** scaffold present (`registry/indexes/capabilities.yaml` empty; - **Profiles:** `profile.compose-e2e`, `profile.sandbox-canary`
`registry/capabilities/` placeholder); domain in index still `helix_forge` - **Extensions:** `ext.compose-ssh` only
from scaffold — needs alignment to `infotech` - **Registry:** `capability.execution.sandbox-provision` indexed (draft)
- **Workplans:** `SAND-WP-0001`–`0002` finished; `SAND-WP-0008` finished - **Tests:** 26 pytest cases; `make check` green
(host telemetry / self-canary) - **Sibling:** wise-validator ships `validate run` (SAND-WP-0003)
- **Lineage (external, not yet migrated):** `the-custodian/e2e-framework/`
(CUST-WP-0028, completed) and `infra/build-machines/` (CUST-WP-0032) Latest gap analysis: `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md`
--- ---
## What Is Possible Now ## What Is Possible Now
- Read the charter (`INTENT.md`) and integration instructions (`AGENTS.md`) ```bash
- Track bootstrap tasks via `workplans/SAND-WP-0001-statehub-bootstrap.md` make setup && make install # sandboxer CLI
- Log progress and decisions to State Hub when the hub is reachable sandboxer create # canary self-deploy (no args)
- Use **interim** sandbox execution via `the-custodian` directly: sandboxer create --profile profile.compose-e2e --input repo=/path/to/repo
- `make e2e REPO=<repo>` (e2e-framework on railiance01/CoulombCore) sandboxer destroy <id>
- `infra/build-machines/` Packer VMs with build-agent registration 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 ## What Is Not Possible Yet
- Request a sandbox through sand-boxer CLI or API - `make e2e REPO=` in the-custodian delegating to sand-boxer (SAND-WP-0004)
- Select a named, versioned profile from this repo's catalog - TTL auto-expiry / `extend_ttl` enforcement
- Register `capability.execution.sandbox-provision` (index entry absent) - `ext.vm-packer` / build-machines migration (SAND-WP-0005)
- Automatic lifecycle registration of generic sandbox identities in State Hub - SaaS extensions (E2B, Modal) or payments layer (SAND-WP-0006)
- Host placement on sandboxer01 via sand-boxer policy (host may not exist yet) - Snapshot / restore / checkpoint profiles (SAND-WP-0007)
- activity-core or agents invoking sand-boxer without workstation repo paths - Formal ops-bridge tunnel attachment in reachability descriptor
- Local install/test/lint/build commands documented for this repo (no package - Dedicated sandboxer01 host (CoulombCore interim only today)
layout yet) - `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 ```mermaid
flowchart LR flowchart LR
AC[activity-core] -->|when| SB[sand-boxer] WV[wise-validator] -->|create/destroy| SB[sand-boxer]
AGT[agents / atm] -->|request sandbox| SB GH[glas-harness] -->|create| SB
SB -->|provision / teardown| HOST[sandboxer01 / interim host] AC[activity-core] -->|when| WV
SB -->|lifecycle events| SH[state-hub] AC -->|venue request| SB
SB -->|reachability| OB[ops-bridge] SB -->|provision| HOST[CoulombCore / sandboxer01]
SB -->|SSH identity| OW[ops-warden] SB -->|lifecycle| SH[state-hub]
RS[reuse-surface] -->|federate| REG[registry/] SB -->|SSH reachability| OB[ops-bridge]
TC[the-custodian e2e + build-machines] -.->|migrate from| SB 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 ## Terminology
- **Profile** — named, versioned sandbox type with provision/teardown contract - **Profile** — named sandbox recipe (extension binding, placement, TTL metadata)
- **Sandbox** — a running isolated environment instance of a profile - **Extension** — backend adapter (`provision`, `wait_ready`, `teardown`)
- **Host placement** — policy mapping profiles to sandboxer01, CoulombCore, etc. - **Establishment** — create through `ready` (distinct from validation pass/fail)
- **TTL** — time-to-live; sandboxes are disposable by default - **Canary** — `profile.sandbox-canary` self-deploy with host telemetry
- **Phone home** — reachability and registration via ops-bridge + State Hub - Actor types: `adm`, `agt`, `atm`
- Actor types (consumers): `adm` (operator), `agt` (LLM agent), `atm` (automation)
--- ---
## Related / Overlapping ## Related / Overlapping
- `the-custodian` — current home of e2e-framework and build-machines; governance - **wise-validator** — validation orchestration; one-way consumer of sand-boxer
canon; sand-boxer extracts reusable execution platform from here - **the-custodian** — legacy `e2e-framework/`; shim migration pending
- `ops-bridge` — SSH reverse tunnels; sand-boxer orchestrates reachability, does - **ops-bridge** / **ops-warden** — connectivity and identity consumers
not run tunnel daemons - **state-hub** — lifecycle visibility
- `ops-warden` — SSH CA and certificate issuance - **reuse-surface** — capability federation target
- `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
--- ---
## Provided Capabilities ## Provided Capabilities
*Planned — not yet registered in `registry/indexes/capabilities.yaml`.* Registered (draft): `capability.execution.sandbox-provision` —
see `registry/capabilities/execution.sandbox-provision.md`.
```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).
--- ---
## Getting Oriented ## Getting Oriented
- Start with: `INTENT.md` (meta-framework charter) | Path | Purpose |
- Research: `research/` (landscape, reference systems, design synthesis) |------|---------|
- Agent instructions: `AGENTS.md` (State Hub session protocol) | `INTENT.md` | Charter and sibling boundaries |
- Offline brief: `.custodian-brief.md` | `docs/meta-framework.md` | API, lifecycle, extension contract |
- Workplans: `workplans/` (bootstrap: `SAND-WP-0001`) | `docs/host-telemetry.md` | Canary and inventory |
- Registry authoring: `registry/README.md` | `docs/migration-gaps.md` | Legacy cutover status |
- Lineage reference (external): `the-custodian/e2e-framework/RUNBOOK.md`, | `docs/integrations/` | Consumer contracts |
`the-custodian/infra/build-machines/README.md` | `workplans/` | ADR-001 work structure |
| `history/` | INTENT ↔ SCOPE assessments |
| `AGENTS.md` | Session protocol |

198
history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md Normal file
View File

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

115
workplans/SAND-WP-0004-the-custodian-e2e-shim.md Normal file
View File

@@ -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 <repo>` 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=<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 |