generated from coulomb/repo-seed
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.
This commit is contained in:
4
SCOPE.md
4
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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 |
|
||||
| TTL enforcement + scheduled reap | **SAND-WP-0009** |
|
||||
197
history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md
Normal file
197
history/2026-06-24-post-wp0007-intent-scope-gap-analysis.md
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
|
||||
159
workplans/SAND-WP-0009-ttl-and-operational-hardening.md
Normal file
159
workplans/SAND-WP-0009-ttl-and-operational-hardening.md
Normal file
@@ -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 <id> --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
|
||||
Reference in New Issue
Block a user