08faf05ff0
Replace drift-prone test/crate counts with shape descriptions in map/ROADMAP.md and three jouleclaw crate READMEs so the repo passes scripts/check-no-vanity-metrics.sh (the "describe the shape, not the size" rule). No content meaning lost — "green / zero warnings" signals retained. Co-Authored-By: Claude Opus 4.8 <[email protected]>
44 lines
1.9 KiB
Markdown
44 lines
1.9 KiB
Markdown
# jouleclaw-sandbox-tier
|
|
|
|
**Scope**: In-process closure isolation for cascade `Tier`
|
|
wrappers. `TierIsolation::run_with(grants, label, body)` runs a
|
|
Rust closure under capability grants + emits a sandbox
|
|
attestation alongside the cascade `Answer`.
|
|
|
|
## Relation to `jouleclaw-sandbox-protocol`
|
|
|
|
These two crates coexist because they operate at different
|
|
layers:
|
|
|
|
| Crate | Layer | Surface |
|
|
|---|---|---|
|
|
| **`jouleclaw-sandbox-protocol`** | Subprocess lifecycle | async `SandboxRuntime`: `create / start / exec(argv, stdin) / kill / destroy`. Implementations: Docker, K8s, gVisor, Firecracker, OpenSandbox. |
|
|
| **`jouleclaw-sandbox-tier`** (this crate) | In-process closure wrap | sync `TierIsolation`: `run_with<F: FnOnce() -> T>(grants, label, body)`. Implementations: `PassthroughRuntime` reference. |
|
|
|
|
The wave-56 trait was originally named `SandboxRuntime` —
|
|
renamed to `TierIsolation` to avoid the conceptual collision
|
|
with the protocol crate's trait of the same name.
|
|
|
|
## When to use which
|
|
|
|
- **`jouleclaw-sandbox-protocol`** — you have a binary or
|
|
argv-shaped workload that must run in a real container /
|
|
microVM. Backends marshall the args across the process
|
|
boundary.
|
|
- **`jouleclaw-sandbox-tier`** (this crate) — you have a
|
|
cascade `Tier` impl that runs in-process Rust code; you want
|
|
to record what device-class grants it ran under +
|
|
emit a typed [`SandboxAttestation`] for the receipt.
|
|
|
|
Neither replaces the other. A production stack typically uses
|
|
both: the cascade walks tiers (some `TierIsolation`-wrapped),
|
|
and tools the agent invokes that need subprocess execution go
|
|
through `jouleclaw-sandbox-protocol`.
|
|
|
|
## What ships
|
|
|
|
- `TierIsolation` trait + `Sandboxed<T: Tier, R: TierIsolation>` wrapper
|
|
- `PassthroughRuntime` reference impl
|
|
- `SandboxGrants` { device_classes, joule_budget_uj, timeout }
|
|
- `SandboxAttestation` { receipt_id, tier, used_devices, joules_uj, outcome, content_hash }
|
|
- All tests pass.
|