generated from coulomb/repo-seed
Update SCOPE, gap analysis, and propose SAND-WP-0004
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:
268
SCOPE.md
268
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=<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 <id>
|
||||
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`
|
||||
| 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 |
|
||||
198
history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md
Normal file
198
history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md
Normal 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
115
workplans/SAND-WP-0004-the-custodian-e2e-shim.md
Normal 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 |
|
||||
Reference in New Issue
Block a user