diff --git a/SCOPE.md b/SCOPE.md index 1962b77..7220c9d 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -132,8 +132,8 @@ own tunnels or CAs. - **Siblings:** wise-validator `validate run` (SAND-WP-0003); the-custodian `make e2e REPO=` shim (SAND-WP-0004) -Latest gap analysis: `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md` -(partially superseded by SAND-WP-0005–0007 delivery). +Latest gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md` +Next workplan: **SAND-WP-0009** (TTL enforcement and operational hardening). --- diff --git a/docs/migration-gaps.md b/docs/migration-gaps.md index 0ce68a6..0ecf10f 100644 --- a/docs/migration-gaps.md +++ b/docs/migration-gaps.md @@ -46,4 +46,4 @@ Deferred: Packer orchestration from API, `make remote-build` shim. | ~~SaaS extensions + payments v0~~ | SAND-WP-0006 — stub + routing + credits | | E2B / Modal real adapters | Post SAND-WP-0006 | | ~~Snapshot / restore~~ | SAND-WP-0007 — `docs/snapshots.md` | -| TTL enforcement + scheduled reap | TBD | \ No newline at end of file +| TTL enforcement + scheduled reap | **SAND-WP-0009** | \ No newline at end of file diff --git a/history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md b/history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md new file mode 100644 index 0000000..45d5467 --- /dev/null +++ b/history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md @@ -0,0 +1,197 @@ +# INTENT ↔ SCOPE Gap Analysis — Post SAND-WP-0007 + +**Date:** 2026-06-24 +**Author:** codex +**Trigger:** SAND-WP-0001–0008 finished; SAND-WP-0007 (snapshots) shipped. +SCOPE.md refreshed 2026-06-24. Prior assessment: +`history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md` (superseded). + +--- + +## 1. Executive summary + +sand-boxer is **v0 feature-complete** for establishment: compose provision, +vm-packer attach, SaaS stub + routing + credits, workspace checkpoints, host +telemetry, and sibling migration arc (wise-validator + the-custodian shim). + +Remaining distance to INTENT is **operational hardening** (TTL enforcement — +the largest functional gap), **registry hygiene** (classification + federation), +**reachability depth** (ops-bridge descriptor), and **extension breadth** +(real cloud adapters, Packer orchestration). Host topology (sandboxer01) and +some sibling sign-offs sit outside this repo. + +**Vector movement:** `D5/A3/C3/R3` (post-WP-0003) → **`D5/A4/C4/R3`** + +| Dimension | Post-WP-0003 | Now (post-WP-0007) | Next target | +| --- | --- | --- | --- | +| Discovery | D5 | **D5** | D6 after registry publish | +| Availability | A3 | **A4** | A5 after TTL + HTTP parity | +| Completeness | C3 | **C4** | C5 after cloud adapters | +| Reliability | R3 | **R3** | R4 after TTL auto-expire | + +--- + +## 2. Workplan deliverables (cumulative) + +| Workplan | Status | Key deliverable | +| --- | --- | --- | +| SAND-WP-0001 | finished | Python scaffold, AGENTS.md | +| SAND-WP-0002 | finished | Meta-framework, `ext.compose-ssh`, CLI, HTTP stub | +| SAND-WP-0003 | finished | wise-validator sibling (`validate run`) | +| SAND-WP-0004 | finished | the-custodian `make e2e` shim | +| SAND-WP-0005 | finished | Extension SDK, `ext.vm-packer` attach | +| SAND-WP-0006 | finished | Routing, payments, `ext.saas-stub` | +| SAND-WP-0007 | finished | Snapshot/restore, `profile.compose-checkpoint` | +| SAND-WP-0008 | finished | Canary telemetry, `inspect` / `reap-stale` | + +**Open deferred tasks in finished workplans:** + +| Task | Workplan | Status | Gap | +| --- | --- | --- | --- | +| T06 Packer orchestration | SAND-WP-0005 | wait | No `create`-triggered builds | +| T06 Real E2B/Modal/BYOK/fin-hub | SAND-WP-0006 | wait | Stub only | +| T09 Remote smoke sign-off | SAND-WP-0003 | wait | wise-validator operator task | + +--- + +## 3. INTENT — four pillars (current) + +### Pillar 1: Unified establishment API + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| `create` / `get` / `list` / `destroy` / `recreate` | v0 | **Done** | CLI; HTTP missing `recreate` | +| `snapshot` / `restore` | Completeness | **Done** | SAND-WP-0007; cross-host deferred | +| `extend_ttl` | API shape | **Absent** | Schema only; no parser, no `expires_at` | +| TTL auto-expiry | Isolation enforcement | **Absent** | `expired` state unused | +| `active` state transition | Optional | **Absent** | Not wired | +| Consumer attribution | Required | **Done** | — | +| HTTP surface parity | Parallel CLI | **Partial** | No `recreate`, `extend_ttl` | + +### Pillar 2: Profile catalog + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| Compose + checkpoint profiles | Reference | **Done** | Remote-verified compose | +| Canary self-deploy | Dogfood | **Done** | SAND-WP-0008 | +| vm-haskell-build | build-machines attach | **Done** | SAND-WP-0005 | +| saas-stub / burst-sandbox | SaaS routing | **Done** | SAND-WP-0006 | +| Agent-dev / glas-harness profile | Consumer | **Absent** | Integration doc only | +| Setup metadata / secret refs | Blitzy pattern | **Schema only** | No resolution at provision | +| Registry federation publish | Registry-first | **Draft** | No `reuse-surface validate` run | + +### Pillar 3: Extension platform + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| `ext.compose-ssh` | Self-hosted | **Done** | + tar snapshots | +| `ext.vm-packer` attach | build-machines | **Done** | Build orchestration deferred | +| `ext.saas-stub` | Metered stub | **Done** | — | +| Extension SDK | Author contract | **Done** | `docs/extension-sdk.md` | +| Routing engine | Multi-backend | **Done** | SAND-WP-0006 | +| E2B / Modal / Daytona | SaaS class | **Absent** | WP-0006-T06 deferred | +| Cross-host snapshot transfer | Checkpoint | **Absent** | Same-host only in v0 | + +### Pillar 4: Payments and metering + +| Capability | INTENT | Status | Gap | +| --- | --- | --- | --- | +| Credits + estimate + debit | SaaS v0 | **Done** | SAND-WP-0006 | +| BYOK for provider keys | SaaS | **Absent** | OpenBao routing only | +| fin-hub billing export | Platform | **Absent** | — | +| Self-hosted duration metering | Host/duration | **Partial** | Telemetry deltas; no billing | + +--- + +## 4. Governing principle scorecard + +| # | Question | Status | Evidence / gap | +| --- | --- | --- | --- | +| 1 | Which sandbox recipe? | **Met** | 6 profiles, loader | +| 2 | Which backend? | **Met** | Routing + 3 extensions | +| 3 | Where does it run? | **Partial** | Placement works; sandboxer01 not live | +| 4 | How is isolation enforced? | **Partial** | Compose isolation; **TTL not enforced** | +| 5 | How reachable? | **Partial** | SSH direct; ops-bridge not in descriptor | +| 6 | What happened? | **Met** | State Hub + stores | +| 7 | What did it cost? | **Partial** | Metered stub; no fin-hub export | + +**Score: 3 met, 4 partial, 0 not met** (was 2/4/1 post-WP-0003) + +--- + +## 5. Self-sufficiency and sibling boundaries + +| Criterion | Status | Notes | +| --- | --- | --- | +| Operates without wise-validator | **Met** | Full CLI surface | +| wise-validator optional consumer | **Met** | One-way dependency | +| sand-boxer does not validate | **Met** | — | +| the-custodian shim complete | **Met** | SAND-WP-0004 | +| glas-harness / snuggle consumer smoke | **Not met** | Docs only | +| activity-core TTL reap hook | **Not met** | No contract or scheduler | + +--- + +## 6. Maturity target gaps + +| Maturity statement | Status | Track | +| --- | --- | --- | +| glas-harness requests sandboxes without backend choice | **Partial** | burst-sandbox routes; no agent-dev profile | +| wise-validator validation environments | **Met** | `validate run` | +| snuggle-inventor build sandboxes + secret refs | **Not met** | Secret boundary open | +| activity-core bounded venues + visibility | **Partial** | Events yes; TTL reap no | +| Operators route self-hosted vs SaaS spend | **Met** | Routing + credits | +| Workstation optional for runtime | **Met** | Remote compose + shim | + +--- + +## 7. Registry and hygiene gaps + +| Item | Status | Impact | +| --- | --- | --- | +| `.repo-classification.yaml` | **Missing** | State Hub C-24 warn | +| `capability.execution.sandbox-provision` maturity | **Stale** | Still cites WP-0002 in-progress | +| `reuse-surface validate` publish | **Not run** | Federation blocked | +| Security runbook (blast-radius honesty) | **Absent** | INTENT design principle undocumented | + +--- + +## 8. Remaining gaps (prioritized) + +| Prio | Gap | Owner | Proposed track | +| --- | --- | --- | --- | +| **P1** | TTL enforcement + `extend_ttl` + `expires_at` | sand-boxer | **SAND-WP-0009** | +| **P2** | TTL reap scheduler / activity-core contract | sand-boxer + activity-core | **SAND-WP-0009** | +| **P3** | `.repo-classification.yaml` + registry refresh | sand-boxer | **SAND-WP-0009** | +| **P4** | HTTP API parity (`recreate`, `extend_ttl`) | sand-boxer | **SAND-WP-0009** | +| **P5** | Real E2B / Modal adapters + BYOK | sand-boxer | SAND-WP-0010 | +| **P6** | ops-bridge tunnel in reachability descriptor | sand-boxer | SAND-WP-0011 | +| **P7** | Consumer profiles (glas-harness, snuggle) | sand-boxer | SAND-WP-0011 | +| **P8** | Packer build orchestration + remote-build shim | sand-boxer | SAND-WP-0012 (WP-0005-T06) | +| **P9** | Cross-host snapshot transfer | sand-boxer | Future | +| **P10** | fin-hub billing export | sand-boxer + platform | With SAND-WP-0010 | +| **P11** | sandboxer01 dedicated host | infra / operator | Outside repo | +| **P12** | wise-validator remote smoke (T09) | wise-validator | Operator | + +--- + +## 9. Recommended next workplan + +**SAND-WP-0009 — TTL enforcement and operational hardening** + +Closes P1–P4: the largest functional gap (disposable-by-default TTL), platform +hygiene (classification, registry), and HTTP parity. Unblocks activity-core +scheduling of expire/reap without implementing activity-core itself. + +Subsequent: **SAND-WP-0010** (real cloud adapters), **SAND-WP-0011** +(reachability + consumer profiles), **SAND-WP-0012** (Packer orchestration). + +--- + +## 10. Evidence references + +- `workplans/SAND-WP-0005` through `SAND-WP-0008` (all finished) +- `SCOPE.md` (updated 2026-06-24) +- `docs/snapshots.md`, `docs/routing.md`, `docs/payments.md` +- `docs/migration-gaps.md` +- 54 pytest cases; `make check` green \ No newline at end of file diff --git a/workplans/SAND-WP-0007-snapshot-restore.md b/workplans/SAND-WP-0007-snapshot-restore.md index c339a78..3684572 100644 --- a/workplans/SAND-WP-0007-snapshot-restore.md +++ b/workplans/SAND-WP-0007-snapshot-restore.md @@ -17,7 +17,7 @@ state_hub_workstream_id: "bb4e0e63-6323-49c1-be4a-cc7691494d24" Workspace checkpoint API for self-hosted compose sandboxes and SaaS stub. **Predecessor:** SAND-WP-0006 (SaaS extensions — finished) -**Follow-on:** TTL enforcement, cross-host snapshot transfer, E2B/Modal persistence +**Follow-on:** SAND-WP-0009 (TTL), cross-host snapshot transfer, E2B/Modal persistence ## Snapshot store and models diff --git a/workplans/SAND-WP-0009-ttl-and-operational-hardening.md b/workplans/SAND-WP-0009-ttl-and-operational-hardening.md new file mode 100644 index 0000000..7d06d19 --- /dev/null +++ b/workplans/SAND-WP-0009-ttl-and-operational-hardening.md @@ -0,0 +1,159 @@ +--- +id: SAND-WP-0009 +type: workplan +title: "TTL enforcement and operational hardening" +domain: infotech +repo: sand-boxer +status: ready +owner: codex +topic_slug: custodian +created: "2026-06-24" +updated: "2026-06-24" +--- + +# TTL enforcement and operational hardening + +Close the largest post-v0 functional gap: **disposable-by-default TTL** with +`extend_ttl`, automated expire/reap, and platform hygiene (classification, +registry, HTTP parity). + +Gap analysis: `history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md` + +**Predecessor:** SAND-WP-0007 (snapshots — finished) +**Follow-on:** SAND-WP-0010 (real cloud adapters), SAND-WP-0011 (reachability + +consumer profiles), SAND-WP-0012 (Packer orchestration) + +--- + +## TTL duration parser + +```task +id: SAND-WP-0009-T01 +status: todo +priority: high +``` + +Module `src/sandboxer/lifecycle/ttl.py`: parse profile `ttl.default` / `ttl.max` +and request override strings (`4h`, `30m`, `1d`). Unit tests for edge cases and +max-cap enforcement. + +## expires_at on create + +```task +id: SAND-WP-0009-T02 +status: todo +priority: high +``` + +Add `expires_at: datetime | None` and optional `ttl: str` on `SandboxStatus`. +`SandboxManager.create` sets expiry from profile default or `SandboxCreateRequest.ttl`. +Persist in `SandboxStore`. Emit expiry in State Hub `detail`. + +## extend_ttl API + +```task +id: SAND-WP-0009-T03 +status: todo +priority: high +``` + +`SandboxManager.extend_ttl(sandbox_id, duration)` — cap at profile `ttl.max`, +reject destroyed/expired sandboxes. CLI: `sandboxer extend-ttl --duration 2h`. +HTTP: `PATCH /v1/sandboxes/{id}/ttl` with body `{"duration": "2h"}`. + +## Expire and TTL reap + +```task +id: SAND-WP-0009-T04 +status: todo +priority: high +``` + +CLI `sandboxer expire` — list sandboxes past `expires_at`; dry-run default; +`--apply` transitions to `expired` then `destroy` (reuse destroy path). Optional +`idle_reap` hook using `updated_at` when profile sets `ttl.idle_reap`. Integrate +with existing `reap-stale` docs (host inventory vs TTL are distinct concerns). + +## activity-core integration contract + +```task +id: SAND-WP-0009-T05 +status: todo +priority: medium +``` + +`docs/integrations/activity-core.md`: how a scheduled job invokes +`sandboxer expire --apply` (or HTTP equivalent); lifecycle events for `expired` +state; no Temporal code in this repo. + +## Repo classification and registry refresh + +```task +id: SAND-WP-0009-T06 +status: todo +priority: medium +``` + +Add `.repo-classification.yaml` (clears State Hub C-24). Update +`registry/capabilities/execution.sandbox-provision.md` maturity to reflect v0 +(A4/C4). Document `reuse-surface validate` operator steps in `registry/README.md`; +run validate if reuse-surface CLI available in environment. + +## HTTP API parity + +```task +id: SAND-WP-0009-T07 +status: todo +priority: medium +``` + +Add `POST /v1/sandboxes/{id}/recreate` and TTL endpoints to `api/app.py`. +Align OpenAPI with CLI surface from SAND-WP-0007. + +## Documentation + +```task +id: SAND-WP-0009-T08 +status: todo +priority: medium +``` + +`docs/ttl.md` — semantics, extend, expire, profile fields. Update +`docs/meta-framework.md`, `SCOPE.md`, `docs/migration-gaps.md`. Brief security +note in `docs/runbooks/` or `docs/security.md`: sandbox limits blast radius, not +intent enforcement (INTENT design principle). + +## Tests + +```task +id: SAND-WP-0009-T09 +status: todo +priority: high +``` + +`tests/test_ttl.py` (parser, extend cap), manager expire flow with mocked +backend, API tests for extend/recreate. `make check` green. + +--- + +## Out of scope (deferred) + +| Item | Track | +|------|-------| +| Real E2B / Modal / BYOK / fin-hub | SAND-WP-0010 (WP-0006-T06) | +| ops-bridge tunnel descriptor | SAND-WP-0011 | +| glas-harness / snuggle consumer profiles | SAND-WP-0011 | +| Packer build from `create` | SAND-WP-0012 (WP-0005-T06) | +| Cross-host snapshot transfer | Future | +| sandboxer01 host provisioning | Operator / infra | +| wise-validator T09 remote smoke | wise-validator repo | + +--- + +## Acceptance criteria + +- Ready sandbox has `expires_at`; `extend_ttl` respects `ttl.max` +- `sandboxer expire --apply` destroys expired sandboxes idempotently +- `.repo-classification.yaml` present; C-24 warn cleared on fix-consistency +- HTTP exposes recreate + extend_ttl +- `docs/ttl.md` published; gap analysis P1–P4 addressed \ No newline at end of file