generated from coulomb/repo-seed
docs: charter meta-framework vision, research, and SAND-WP-0002
Rewrite INTENT.md as the sand-boxer meta-framework charter (OpenRouter-style sandbox API, extensions, payments, Coulomb sibling boundaries). Add research under research/, update SCOPE.md, bootstrap workplans SAND-WP-0001/0002, and State Hub integration files from the bootstrap pass.
This commit is contained in:
56
workplans/SAND-WP-0001-statehub-bootstrap.md
Normal file
56
workplans/SAND-WP-0001-statehub-bootstrap.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: SAND-WP-0001
|
||||
type: workplan
|
||||
title: "Bootstrap State Hub integration"
|
||||
domain: infotech
|
||||
repo: sand-boxer
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
created: "2026-06-22"
|
||||
updated: "2026-06-22"
|
||||
status: active
|
||||
---
|
||||
|
||||
# Bootstrap State Hub integration
|
||||
|
||||
Sandboxing for agentic coding facility.
|
||||
|
||||
## Review Generated Integration Files
|
||||
|
||||
```task
|
||||
id: SAND-WP-0001-T01
|
||||
status: done
|
||||
priority: high
|
||||
```
|
||||
|
||||
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
|
||||
Replace generated placeholders with repo-specific facts where needed.
|
||||
|
||||
## Verify Local Developer Workflow
|
||||
|
||||
```task
|
||||
id: SAND-WP-0001-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Identify the repo's install, test, lint, build, and run commands. Add or refine
|
||||
those commands in the agent instructions so future coding sessions can verify
|
||||
changes confidently.
|
||||
|
||||
## Seed First Real Workplan
|
||||
|
||||
```task
|
||||
id: SAND-WP-0001-T03
|
||||
status: done
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Create the first implementation workplan for the repository's most important
|
||||
next change. Created `workplans/SAND-WP-0002-meta-framework-foundation.md`.
|
||||
After workplan file updates, run from `~/state-hub`:
|
||||
|
||||
```bash
|
||||
make fix-consistency REPO=sand-boxer
|
||||
```
|
||||
246
workplans/SAND-WP-0002-meta-framework-foundation.md
Normal file
246
workplans/SAND-WP-0002-meta-framework-foundation.md
Normal file
@@ -0,0 +1,246 @@
|
||||
---
|
||||
id: SAND-WP-0002
|
||||
type: workplan
|
||||
title: "Meta-framework foundation and first extension"
|
||||
domain: infotech
|
||||
repo: sand-boxer
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: custodian
|
||||
created: "2026-06-22"
|
||||
updated: "2026-06-22"
|
||||
---
|
||||
|
||||
# Meta-framework foundation and first extension
|
||||
|
||||
Establish sand-boxer as a meta-framework: unified API contract, profile catalog,
|
||||
extension platform, and the first self-hosted backend (`ext.compose-ssh`) migrated
|
||||
from `the-custodian/e2e-framework/`.
|
||||
|
||||
**Charter:** `INTENT.md`
|
||||
**Research:** `research/03-meta-framework-synthesis.md`
|
||||
**Predecessor:** SAND-WP-0001 (bootstrap; T02 dev workflow should complete in
|
||||
parallel or before T03 here)
|
||||
|
||||
## Design meta-framework contracts
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Author `docs/meta-framework.md` (or `specs/meta-framework.md`) defining:
|
||||
|
||||
- Resource model: Profile, Extension, Host, Sandbox, Snapshot, Route, Meter
|
||||
- Lifecycle states and State Hub event mapping
|
||||
- Core API operations: `create`, `get`, `list`, `extend_ttl`, `recreate`,
|
||||
`destroy` (snapshot/restore deferred to SAND-WP-0003)
|
||||
- Consumer attribution schema (`adm` / `agt` / `atm`, calling project id)
|
||||
- Extension interface: `provision`, `wait_ready`, `teardown`, optional
|
||||
`estimate_cost`
|
||||
- Routing policy vocabulary (`prefer-self-hosted`, `lowest-cost`, `explicit`)
|
||||
- Security limits statement (blast-radius vs intent — per research)
|
||||
|
||||
Derive from `research/03-meta-framework-synthesis.md`; do not duplicate harness,
|
||||
validator, or codegen concerns.
|
||||
|
||||
## Define profile and extension schemas
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T02
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Add machine-readable schemas (JSON Schema or Python pydantic models) for:
|
||||
|
||||
- `Profile` — extension binding, isolation, network, workspace mode, scope,
|
||||
TTL, resources, setup metadata, placement, reachability, cost class
|
||||
- `Extension` — id, capabilities, isolation levels, pricing model, regions
|
||||
- `SandboxCreateRequest` / `SandboxStatus` response shapes
|
||||
|
||||
Ship `profiles/profile.compose-e2e.yaml` as the reference profile (successor to
|
||||
`e2e/e2e.yml` inputs; validation semantics stay with wise-validator).
|
||||
|
||||
Register extension stub `extensions/ext.compose-ssh.yaml` with capability
|
||||
metadata.
|
||||
|
||||
## Scaffold package and developer workflow
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T03
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Create Python package layout (aligned with e2e-framework lineage):
|
||||
|
||||
```
|
||||
src/sandboxer/ # or sandboxer/ at repo root — pick one, document in AGENTS.md
|
||||
api/
|
||||
profiles/
|
||||
extensions/
|
||||
lifecycle/
|
||||
tests/
|
||||
pyproject.toml
|
||||
```
|
||||
|
||||
Document in `AGENTS.md`: install (`uv sync` or equivalent), test, lint, format,
|
||||
and CLI entry point. Satisfies SAND-WP-0001-T02 if not already done.
|
||||
|
||||
## Implement extension registry and loader
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T04
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Implement extension discovery and registration:
|
||||
|
||||
- Load extension definitions from `extensions/`
|
||||
- Plugin entry-point or explicit registry for `ext.compose-ssh`
|
||||
- Validate extension declares required capability fields before registration
|
||||
- Unit tests for load failures and duplicate ids
|
||||
|
||||
No SaaS extensions in this workplan — self-hosted only.
|
||||
|
||||
## Implement ext.compose-ssh (e2e-framework lineage)
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T05
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Extract and adapt provision/teardown from `the-custodian/e2e-framework/`:
|
||||
|
||||
- SSH to configured host; isolated directory per sandbox id
|
||||
- Unique compose project name; `compose up` / `compose down` (idempotent)
|
||||
- Default-deny network posture per profile (document host-side requirements)
|
||||
- Host placement: read `placement.prefer` / `fallback` from profile
|
||||
- **Do not** port test execution, health polling, or State Hub result reporting
|
||||
— those are wise-validator responsibilities
|
||||
|
||||
Provide a compatibility note in extension README for interim `make e2e` callers.
|
||||
|
||||
## Implement API v0 and CLI
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T06
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Ship minimal establishment surface:
|
||||
|
||||
**CLI** (primary for v0):
|
||||
|
||||
```bash
|
||||
sandbox create --profile profile.compose-e2e --input repo=/path/to/repo
|
||||
sandbox get <id>
|
||||
sandbox list
|
||||
sandbox recreate <id>
|
||||
sandbox destroy <id>
|
||||
```
|
||||
|
||||
**HTTP** (optional in v0; stub acceptable if CLI calls core library directly):
|
||||
|
||||
- `POST /v1/sandboxes`, `GET /v1/sandboxes/{id}`, `DELETE /v1/sandboxes/{id}`
|
||||
|
||||
Core library must be harness-agnostic — glas-harness, wise-validator, and
|
||||
snuggle-inventor call the same functions.
|
||||
|
||||
## State Hub lifecycle registration
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T07
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
On sandbox state transitions, emit State Hub progress events (or dedicated
|
||||
registration endpoint when available):
|
||||
|
||||
- `requested`, `provisioning`, `ready`, `active`, `destroying`, `destroyed`
|
||||
- Include: `sandbox_id`, `profile_id`, `extension_id`, `host`, `consumer`,
|
||||
`actor_type`, timestamps
|
||||
|
||||
Extend the `build-agent` self-register pattern sketch for generic sandbox
|
||||
identities. Document contract in meta-framework spec.
|
||||
|
||||
## Document sibling integration contracts
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T08
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Add `docs/integrations/` with one page per planned sibling:
|
||||
|
||||
| Doc | Contents |
|
||||
|-----|----------|
|
||||
| `glas-harness.md` | Sandbox handle + reachability; harness owns exec |
|
||||
| `wise-validator.md` | `profile.compose-e2e`; validator owns e2e.yml + health + tests |
|
||||
| `snuggle-inventor.md` | Setup metadata + secret_refs; no codegen in sand-boxer |
|
||||
|
||||
Each doc: example request, response fields, ownership table, out-of-scope list.
|
||||
Cross-link from `INTENT.md` Coulomb boundaries section.
|
||||
|
||||
## Register capability and fix registry scaffold
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T09
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
- Author `registry/capabilities/execution.sandbox-provision.md`
|
||||
- Add row to `registry/indexes/capabilities.yaml` (`domain: infotech`)
|
||||
- Run `reuse-surface validate` when CLI available
|
||||
- Notify operator: `make fix-consistency REPO=sand-boxer` from `~/state-hub`
|
||||
|
||||
## Verification and migration smoke test
|
||||
|
||||
```task
|
||||
id: SAND-WP-0002-T10
|
||||
status: todo
|
||||
priority: medium
|
||||
```
|
||||
|
||||
End-to-end proof on CoulombCore or sandboxer01 (when reachable):
|
||||
|
||||
1. `sandbox create` with `profile.compose-e2e` for a repo with `e2e/` layout
|
||||
2. Confirm `ready` state and reachability descriptor
|
||||
3. Manual or scripted compose health check (not wise-validator — just proves
|
||||
environment exists)
|
||||
4. `sandbox destroy` — confirm idempotent cleanup (no leftover compose projects
|
||||
or `/tmp` dirs)
|
||||
5. Document runbook in `docs/runbooks/profile-compose-e2e.md`
|
||||
|
||||
Record gaps for wise-validator migration (SAND-WP-0003) and `the-custodian`
|
||||
shim (SAND-WP-0004).
|
||||
|
||||
---
|
||||
|
||||
## Out of scope (follow-on workplans)
|
||||
|
||||
| Item | Target workplan |
|
||||
|------|-----------------|
|
||||
| wise-validator extraction + e2e test orchestration | SAND-WP-0003 |
|
||||
| `the-custodian` Makefile shim + deprecation timeline | SAND-WP-0004 |
|
||||
| `ext.vm-packer` (build-machines) | SAND-WP-0005 |
|
||||
| SaaS extensions + payments layer | SAND-WP-0006 |
|
||||
| Snapshot / restore / checkpoint profiles | SAND-WP-0007 |
|
||||
| Coulomb-native runtime (phase 5) | Backlog |
|
||||
|
||||
## Completion criteria
|
||||
|
||||
- Meta-framework spec and schemas merged
|
||||
- `ext.compose-ssh` provisions and tears down a compose sandbox via CLI
|
||||
- State Hub receives lifecycle events for at least one full create→destroy cycle
|
||||
- Sibling integration docs published
|
||||
- `capability.execution.sandbox-provision` registered and validated
|
||||
- All tasks `done`; workplan `status: finished`; operator runs fix-consistency
|
||||
Reference in New Issue
Block a user