docs: post-WP-0007 gap analysis and SAND-WP-0009 workplan

Assess remaining INTENT gaps after snapshots; propose TTL enforcement,
platform hygiene, and HTTP parity as the next implementation track.

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