Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 15 Packages Wiki Activity Actions 79
open-standards/sandbox/README.md
Transaction Science 490a592223 sandbox-exec-microvm, sandbox-exec-wasm, sandbox-meter: grade nominal-cost figures Estimator 
Three reference estimators priced work by a coefficient no host
calibrated and graded the figure ModelBased:
- sandbox-exec-microvm: with no live CPU counter, vCPU-seconds × the
  reference 12,000 µJ/vCPU-second (a nominal work-unit cost), and the
  accelerator's "coarse proxy" (that cost × 10);
- sandbox-exec-wasm: fuel × the reference 20,000 µJ per million fuel;
- sandbox-meter StorageActivity (from_samples, from_volume): ops and
  bytes × nominal NVMe-class pJ coefficients documented as "calibrated".
By the family's ladder (JCP SPEC §5.1) a model earns ModelBased by a
calibration on the host; a nominal coefficient is the whole of such a
model, so the figure is an estimate.

- MicroVmConfig.calibrated and WasmConfig.fuel_cost_calibrated (both
  false by default) keep a ModelBased path for a cost the operator
  calibrated on the host, as spec/receipts.md's "calibrated table"
  describes; the accelerator proxy is Estimator either way. Neither config
  is constructed outside its crate.
- Tests that pinned the over-claim now pin Estimator:
  cpu_only_run_meters_modelbased (renamed ..._an_estimate),
  a_cpu_counter_that_held_across_a_run_is_not_a_measured_zero, power.rs's
  two RAPL fallback tests, runs_a_unit_and_meters_cpu_energy,
  storage_globs_enforced_through_execution, contention_is_loaded_minus_
  baseline. New tests: a fallback is a model only at a host-calibrated
  cost (CPU) and never for the proxy (accelerator); the same for the fuel
  cost; both storage constructors are estimates.
- boot_microvm example's 15 W/vCPU fallback is Estimator too.
- SPEC §6.3, spec/receipts.md, SECURITY.md, README and sandbox-meter's
  Provenance docs say a nominal or assumed coefficient is Estimator.
No vector changes: sandbox-conformance passes every class, file-backed
vectors included, and conformance/v1 is untouched (its builders use
fixed constructors, none of these estimators).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-11 10:11:54 -04:00

58 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Sandbox
A sandbox for the heterogeneous compute fabric. Isolate, capability-gate, meter, and attest — owned by no one.
Sandbox is the **isolated-execution substrate** of the Transaction Science open standards. Where [Smart Byte](../smart-byte/) carries value, [EOC](../eoc/) carries compute, and [Joule Code](../joule-code/) carries coding work, Sandbox carries the **place those operations run**: a bounded environment in which an untrusted unit of work executes, sees only what it was granted, and leaves behind a signed account of what it did and what it cost.
Every other sandbox in the field isolates a **CPU process** — a container, a microVM, a Linux process pinned to a core. The accelerator, where present, is an opaque passthrough that nobody meters and nobody attests. But agentic and AI work does not run on a CPU. It runs across a **fabric** — CPU, GPU, NPU, TPU, photonic, quantum. So in this standard the unit of isolation is not a process; it is a **heterogeneous unit of work**, and the accelerator is a first-class citizen of the isolation boundary: a capability you grant, a resource you meter in joules, and a line item you attest.
A Sandbox run carries exactly four guarantees: **isolation** (the unit runs at the lowest tier of an eight-rung ladder, S0–S7, that satisfies its needs, and cannot reach past it), **capability** (every resource the unit touches — each device class included — was explicitly granted; ungranted access is denied), **metering** (the run emits a signed energy receipt with per-device-class joule attribution and an honest provenance tag on every reading — and the reference meter reads vendor energy counters: Apple Silicon's energy model via IOReport, Intel/AMD RAPL via powercap, NVIDIA's total-energy counter via NVML. A reading is tagged `HwShunt` only while its counter is demonstrably live: each vendor counter is used only if every rail of it that the meter sums into one figure keeps advancing while the meter's probe burns CPU — in at least 5 sample intervals, at least 4 of every 5, over at least 300 ms — every IOReport CPU energy rail (the rail itself, one per die on a multi-die part), every RAPL package and every NVML GPU; and a span across which the CPU counter held is never a reading. A counter that is absent, or present but not live — frozen, or republished in lumps, as the IOReport CPU rails are on macOS 27 — yields no hardware-graded figure: the span degrades to the labeled `Estimator` (wall-clock × TDP), never a fabricated measurement, and `ioreport_status()`, `rapl_status()` and `nvml_status()` say why a host is estimated. For work on the meter's own process there is one more source, kept out of the default meter: on macOS, the CPU energy the kernel attributes to the process's own threads (`proc_pid_rusage`), read through `PowerMeter::detect_in_process()` under the same liveness rule, the reading thread taken off its core before each read and the read taken only once the thread's own energy count shows it was folded (a process's read of itself does not fold the thread reading, so a short span would otherwise read nothing, or energy spent before it; and a sleep does not always take a thread off its core, so the fold is checked, and a read whose thread was not seen to fold leaves the span estimated) — never for a subprocess, which it does not cover, nor whole for work that calls a system service, whose share the kernel bills to the process beside that count and this meter does not read; a single-process child's own figure is read from the exited child instead, a partial figure, since a process's exit does not fold its last time on a core into its count. For work in another live process of this user — a server, and its descendants — `TreeMeter` reads that same count for every process of its tree over a span, each end read once no thread of the tree is on a core and confirmed by a second walk that finds the tree's processes unchanged, and lists beside the figure every way it was seen to differ from the tree's energy over the span — short of it (a descendant reaped or exited in the span, a GPU client held, in-process Neural Engine memory, a member unreadable or still running at the stop, work a system service did for a member), or holding energy from outside the span (a member still running at the start; a bill for a service's work done before the span that was credited inside it; a member credited with service to other processes, which is subtracted, and need not be the span's own service, so the figure may be short of the span's energy or over it). Work a service does on a member's behalf, on a message that carries the member's voucher, is billed to the member by the kernel: the figure counts that billed CPU energy, less what members did for processes outside the tree, and lists it as delegated, because the bill over a span is not the span's delegated work: it carries none of the service's GPU or Neural Engine energy, none of its work on threads that never took the voucher, no credit landing after the span (the stop waits briefly for the billed counts to hold, which catches only a credit that lands within it), and it can hold a late credit for work done before the span — so the figure can be short of the delegated work or over it. Work the tree hands outside itself with no bill — over a socket, to a remote API — is not visible to any reader, so whether there is any is for the caller's operator to declare, never the reading's to claim; and a bill seen outweighs that declaration: such a span is partial whatever the operator said. Because a live counter reports the whole SoC, the meter can **attribute** it to a single process tree by CPU-time apportionment — tagged `ModelBased`, since the reading is a measurement but the split is a model), and **attestation** (a signed statement of *what image ran, at what tier, under what grants, on what hardware, for what cost*, with a deterministic-replay journal hash where one was produced).
The substrate is intentionally **ownerless**: no protocol-level token, permissive licensing on spec text and reference code, and conformance vectors so any implementer can verify canonicity without a trust relationship with the authors. A conforming host runs a unit, enforces its grants, meters its energy, and seals its attestation **without contacting any single steward's servers as a condition of operation**. Transaction Science is one steward: it publishes the spec, ships a reference implementation, and operates commercial services around the substrate — not its proprietor.
## The doctrine
**Isolation per joule, across the whole fabric.** The durable layer of a sandbox is not fast container boot or a managed control plane — both are commoditized. It is the boundary itself, made honest: the lowest isolation tier that satisfies the work, every resource gated by an explicit capability, and a signed receipt that attributes energy to each device class it touched. "Run it safely" and "don't waste energy" are the same optimization: an over-isolated run burns joules it did not need, and an unmetered accelerator is exactly where the energy hides.
Three consequences, normative in [`SPEC.md`](SPEC.md):
1. **The ladder.** A host **MUST** run a unit at the lowest isolation tier of `S0:Bare → S1:Capability → S2:Sandbox → S3:Partition → S4:Unikernel → S5:MicroVM → S6:Confidential → S7:Sovereign` that satisfies the unit's capability set, and **MUST NOT** escalate beyond what the grants require. Escalation is the escape hatch, not the entry point — the same discipline the cascade applies to inference, applied to isolation.
2. **The grant.** Every resource a unit can touch — network, storage, key-value, and **each compute device class** (`Cpu | Simd | Gpu | Npu | Tpu | Lpu | Photonic | Quantum`) — **MUST** be explicitly granted. Access to an ungranted resource **MUST** be denied. Each compute grant carries a joule budget.
3. **The attested receipt.** Every completed run **MUST** emit an energy receipt accounting joules **per device class** — `measured + estimated`, integer microjoules — each reading tagged `HwShunt | ModelBased | Estimator`, sealed as a [JCR-1](../jouleclaw/) envelope; and **MUST** emit an attestation binding the unit, image, tier, grants, hardware, and receipt, signed Ed25519 over JCS-canonicalized JSON — the same attestation primitive the [ARL Sandbox (ARL-S)](../arl/) uses, so the two interoperate at the attestation layer.
## Contents
- [`SPEC.md`](SPEC.md) — the normative specification (RFC 2119): the unit of work, the S0–S7 isolation ladder, the capability-grant model, the per-device energy receipt, the attestation, and the conformance contract.
- [`spec/`](spec/) — sub-specifications: [`tiers.md`](spec/tiers.md) (the ladder), [`capabilities.md`](spec/capabilities.md) (the grant model), [`receipts.md`](spec/receipts.md) (per-device energy), [`attestation.md`](spec/attestation.md) (the signed claim + replay journal), [`conformance.md`](spec/conformance.md) (test obligations).
- [`conformance/`](conformance/) — signed wire vectors. An implementation is conformant if it round-trips these.
- [`proof/`](proof/) — the **proof matrix**: a ledger of signed proof cells, each a real run of the conformance pack + a sealed workload on a real target (substrate × OS × arch × cloud × hardware × tier). A green cell is a signature over a real run, not a claim.
- [`sandbox-rs/`](sandbox-rs/) — the Rust reference library: content addressing and tiers (`sandbox-schema`), the capability model and deny-by-default enforcer (`sandbox-capability`), the per-device receipt and JCR-1 sealing (`sandbox-meter`), the attestation and replay journal (`sandbox-attest`), the reference host — tier minimization plus sealed-run assembly (`sandbox-runtime`), a real **S2 (WASM) executor** on wasmtime with fuel→joule metering and a brokered, Enforcer-gated host-call surface that journals every nondeterministic input for replay (`sandbox-exec-wasm`), a real **S5 (microVM) executor** driving Firecracker — both an API-socket driver and a supervised-child lifecycle driver — with pluggable per-device power metering (`sandbox-exec-microvm`), the **S6 confidential-tier** TEE layer — SEV-SNP report model, policy + real ECDSA-P384/SHA-384 verification, and a `configfs-tsm` hardware provider with a software-grounded test provider (`sandbox-tee`), the conformance harness with the `gen_vectors` generator (`sandbox-conformance`), the **proof-matrix harness** that runs the pack + a sealed run on a target and emits a signed proof cell (`sandbox-proof`), the `sandbox` reference checker/runner (`sandbox-cli`), and the **JCP gate** (`sandbox-jcp`) — execution as a JCP consumer: a metered Grant bound to the unit's image *by content address* is decided by the JCP runtime before the executor is ever invoked, the declared energy ceiling is debited from the delegation chain pre-run, and the decision (allow and deny alike) seals as a JCR-1 receipt alongside the sandbox's own sealed run.
## Heterogeneity is normative, not an extension
The clause that distinguishes this standard from a process sandbox is in [`SPEC.md`](SPEC.md) §2.3 and §6.2: where a unit is granted an accelerator capability, a conforming host **MUST** attribute energy to that device class separately in the receipt, **MUST** record the device identity (class, model, driver) in the attestation, and at tiers S5 and above **MUST** report the measurement provenance honestly (`HwShunt` where the device exposes a live energy interface — NVML, RAPL, ROCm SMI, Level Zero — `ModelBased` or `Estimator` otherwise). A host that runs accelerated work but reports a single undifferentiated CPU energy figure is **not conformant**.
## Lineage
Sandbox draws its design from two Transaction Science runtimes and generalizes a third standard:
- The **isolation ladder** and the **capability-grant model** follow the layered, hardware-rooted isolation and the per-resource grant set proven in the invisible-infrastructure runtime — capabilities first, WASM and microVM tiers above, TEE and sovereign tiers at the top, accelerators as explicit device capabilities throughout.
- The **per-device energy receipt** and its **provenance discipline** follow the picojoule receipt and measurement-quality model of the JouleDB substrate, sealed in the family's shared JCR-1 envelope.
- The **attestation** generalizes the SUT / Harness / Supervisor separation and the signed-telemetry model of the [ARL Sandbox](../arl/) out of a measurement-only role into a standalone substrate that ARL-S, [JouleClaw](../jouleclaw/), [EOC](../eoc/), and [Joule Code](../joule-code/) can target instead of each re-specifying isolation.
## Status
v0.1.0 draft. Specification core published (the unit, the ladder, the grant model, the per-device receipt, the attestation); the reference library lands the schema, capability, meter, attest, runtime, and conformance crates with the `sandbox` CLI, plus two **real tier executors**: a wasmtime-backed S2 executor that runs untrusted WASM under fuel and memory caps, meters fuel→joules, and brokers every capability the guest exercises (kv, clock, randomness) through the deny-by-default `Enforcer` — journaling each nondeterministic input so the run's attestation carries a replay-journal root; and a Firecracker-driver S5 executor that boots a microVM (API-socket or supervised-child lifecycle) and meters CPU and an assigned accelerator **separately** through pluggable power meters (RAPL/NVML-class, with an honest fallback: `Estimator` at the reference per-vCPU-second cost, `ModelBased` only at a cost calibrated on the host). Energy receipts seal as **JCR-1** envelopes (canonical det-CBOR + COSE_Sign1, EdDSA), the signed-receipt format shared across the family; attestations sign Ed25519 over JCS-canonicalized JSON, interoperable with ARL-S. The conformance vectors in [`conformance/v1/`](conformance/v1/) are real, cryptographically computed values — including a committed pack of adversarial **negatives** a conformant host must reject — regenerated by `gen_vectors` and verified by the harness (in-code and file-backed).
Readiness is classified per component (Solid / Engineering / Research / Theory) in [`SPEC.md`](SPEC.md) §9 and respected when sequencing work. The S2 (WASM) executor runs and meters real guests; the S4–S5 (microVM) driver is real Firecracker integration (it boots a guest on Linux+KVM); and the **S6/S7 confidential and sovereign tiers** are implemented end-to-end — the host obtains a TEE report, verifies it (real ECDSA-P384/SHA-384 signature + measurement/TCB/debug/report-data policy), seals the evidence into the attestation, binds a locality, and links the run into a tamper-evident audit chain. The single honest caveat (SPEC §9): *generating* a genuine vendor-signed report requires the CPU's security processor — the `configfs-tsm` provider does so on real confidential hardware and reports `Unavailable` elsewhere, while a tagged software-grounded provider, which never claims a hardware root, covers wiring and tests.
## Related
- [ARL](../arl/) — the AI Readiness Level standard; its **ARL Sandbox (ARL-S)** is the measurement-specialized profile of this substrate. The attestation primitive (Ed25519 over JCS) is shared, so an ARL-S session attestation and a Sandbox run attestation verify under the same tooling.
- [JouleClaw](../jouleclaw/) — the energy-optimised AI runtime; a JouleClaw agent's tool execution runs **inside** a Sandbox, and the receipt provenance discipline (`HwShunt | ModelBased | Estimator`) and the JCR-1 envelope are JouleClaw's.
- [Joule Code](../joule-code/) — a coding operation that executes generated code (a test run, a build) runs that code inside a Sandbox; the joule receipt composes.
- [EOC](../eoc/) — the energy-optimised compute substrate; the discipline of stopping at the cheapest tier that closes the request is EOC's, applied here to isolation tiers.
## Licence
Reference code (everything under [`sandbox-rs/`](sandbox-rs/)) is **Apache-2.0** ([`LICENSE`](LICENSE)). Specification text (`SPEC.md`, `spec/`) is **CC-BY-4.0** ([`LICENSE-SPEC`](LICENSE-SPEC)). The wire format and the right to fork are public.
Reference in a new issue View git blame Copy permalink