# JouleClaw v1 — Energy-Optimised AI Runtime Status: **Draft Standard**. Reference implementation: [`jouleclaw-rs/`](jouleclaw-rs/) (Rust workspace, Apache-2.0). Spec text: CC-BY-4.0. Keywords **MUST**, **MUST NOT**, **SHOULD**, **MAY** are RFC 2119. --- ## 1. Scope and doctrine JouleClaw is a runtime + harness + agentic-layer standard for energy-optimised AI. It applies to: - text and code generation (LLMs, SSMs, state-space hybrids) - multimodal understanding and generation (vision, audio, video, 3D) - diffusion-based image / video synthesis (DDPM / LCM / Euler / Heun / DPM++ / CFG++ / Rectified Flow and friends) - speech recognition (Whisper-class) - the developer-facing harness that drives the above The **doctrine** is one sentence: capability per joule, not capability per parameter. Three normative consequences follow from the doctrine. ### 1.1 The cascade A conforming runtime **MUST** dispatch every resolution through an explicit energy-tiered cascade and **MUST** stop at the first tier that closes the query. The tiers are: | Tier | Wire tag | Named tag | Joule class | What it is | |------|----------|-----------|-------------------|--------------------------------------------------| | L0 | `L0` | Cache | picojoules | content-addressed cache hit | | L1 | `L1` | Lawful | nanojoules | deterministic primitive (text / code only) | | L2 | `L2` | Embed | sub-millijoules | embedding + hybrid retrieval | | L3 | `L3` | Model | joules | local SSM / ternary / multimodal / diffusion | | L4 | `L4` | Wire | tens of joules | remote frontier RPC (escape hatch) | L1 (Lawful) is meaningful only for text and code modalities. For image / audio / video / 3D generation the cascade collapses to {L0, L2, L3, L4} — there is no deterministic compute path that produces a high-quality image from "draw me a cat". A conforming runtime **MUST NOT** invoke a higher-cost tier before the lower-cost tiers have returned `Unresolvable`. Inference is the **last resort**, not the entry point. ### 1.2 Recent knowledge over frozen weights A conforming runtime **MUST** prefer fresh, provenance-stamped retrieval over synthesis from frozen model weights whenever: - the cost of the fetch + extract is below the cost of the inference, AND - the retrieved source's trust tier is above the operator's configured threshold. This is the L3.5 stage in the cascade implementation — between L2 (local index) and L3 (local model). The retriever **MUST** emit a `ClaimProvenance` envelope (see §4) for every fact that contributes to the resolution. ### 1.3 Honest energy provenance Every energy reading **MUST** carry a `Provenance` tag declaring how the value was obtained: | Provenance | Meaning | |----------------|--------------------------------------------------------| | `HwShunt` | Real hardware shunt / coulomb counter (RAPL MSR, NVML cumulative-energy counter, Jetson INA3221) | | `ModelBased` | Vendor-provided estimate from freq / voltage / utilisation (Apple IOReport, ROCm SMI, NVML `power.draw`) | | `Estimator` | JouleClaw static cost model from arch × precision × batch tables | The thermodynamic circuit breaker **MUST** enforce at the granularity of the **worst** counter in the request's span. Implementations **MUST** surface `resolution_uj()` and `min_window_ns()` so callers can refuse to claim microjoule accuracy on platforms that cannot deliver it. Realistic floors: - Intel / AMD x86 RAPL: ~1 μJ, ~10 ms window. `HwShunt`. - Jetson INA3221: ~10 mW (integrate for energy). `HwShunt`. - NVIDIA discrete (NVML cumulative-energy): ~1 mJ, ~50 ms. `HwShunt`. - Apple Silicon IOReport: ~1 mJ, ~10 ms. **Model-based**, not measured. Marketing claims of microjoule precision on Apple Silicon are sales talk; the spec is honest about this. - Consumer AMD GPU, ARM PMU: no usable counter. Use a calibrated `Estimator` and surface the wider tolerance band. --- ## 2. The receipt Every cascade walk **MUST** produce one [`Receipt`][prov]: ```json { "jc_receipt": "1", "id": "", "closed_at": "", "input_hash": "", "tier": "L3", "joules_uj": 3500000, "energy_provenance": "ModelBased", "tools_touched": [ { "tool_id": "model:gemma4-9b-q5_k_m", "joules_uj": 3500000, "energy_provenance": "ModelBased" } ], "claims": [ { "source": "https://en.wikipedia.org/wiki/Gemma_(model)", "content_hash": "", "fetched_at": "", "trust_tier": 9 } ], "eoc_stage": null } ``` Receipts are shaped to seal cleanly inside a Smart Byte signed envelope (see the sibling [Smart Byte standard](../smart-byte/)). The Smart Byte signature attests to receipt integrity; the receipt itself is the auditable thermodynamic record. A receipt's `energy_provenance` is the **worst** counter seen across all `tools_touched` — not the best. This is normative. [prov]: jouleclaw-rs/crates/jouleclaw-prov/src/lib.rs --- ## 3. The `.jc.toml` sidecar A model file on disk (GGUF / safetensors / MLX) tells you tensor shapes and quant schemes. It does NOT tell you what one forward pass costs in joules on real hardware. The cascade auction cannot pick the cheapest backend if every backend lies about its cost. A `.jc.toml` sidecar travels next to the model file and declares the energy contract. See [`jouleclaw-pack`][pack] for the schema. Backends loading a model with a `.jc.toml` are bound to honour the declared cost within the per-measurement `drift_factor` tolerance; the runtime trips `CostDrift` and down-weights the backend in future auctions when measured > declared × drift_factor. Without a declared-cost contract, "energy-optimised inference" is marketing. With one, it is an engineering claim a third party can verify against the published reference-hardware corpus (see §6). [pack]: jouleclaw-rs/crates/jouleclaw-pack/src/lib.rs --- ## 4. Provenance Every retrieved claim that contributes to a resolution **MUST** carry a `ClaimProvenance` envelope: ```json { "source": "", "content_hash": "", "fetched_at": "", "trust_tier": 9 } ``` `trust_tier` is 0..10. Bootstrap data comes from the Wikipedia perennial-sources list (machine-readable via the Wikimedia Enterprise parsed-references endpoint); operators **MAY** extend the table. A retriever **MUST NOT** present a synthesised fact as a retrieved claim. If the runtime falls back to model inference because no retrieval closed the query, the receipt's `claims` array **MUST** remain empty for that tier and the resolution carries the `L3:Model` tag, not `L2:Embed`. --- ## 5. The MCP tool surface The standard tool dispatch protocol is MCP (Model Context Protocol). A conforming runtime **SHOULD** speak MCP for interop with the Claude Code / Codex / Goose ecosystem. Every MCP tool call **MUST** be wrapped in `jouleclaw-mcp::dispatch_metered`, which brackets the call with energy counter reads and pushes a `ToolTouch` entry onto the running receipt's `tools_touched` ledger. ### 5.1 The `joule-mcp` profile Two JouleClaw-aware endpoints **MAY** opt into a CBOR transport profile by advertising the capability tag `x-jouleclaw/joule-mcp@1` in their handshake. When both sides advertise it, the wire encoding switches from JSON-RPC to length-prefixed CBOR (~30–50% lower serialisation tax per call). When either side does not advertise, the encoding **MUST** fall back to standard MCP JSON-RPC. Non-JouleClaw MCP clients (Claude Code, Codex, etc.) see plain JSON-RPC. The CBOR profile is a negotiated extension, never a replacement. --- ## 6. Conformance A conforming runtime **MUST** produce a `Receipt` for every published conformance vector in [`conformance/v1/`](conformance/v1/) that matches the canonical receipt's `tier`, `tools_touched[].tool_id`, and `claims[].content_hash`. The `joules_uj` field in a conforming receipt **MUST** fall within the platform-specific drift band declared in the `.jc.toml` sidecar for each tool / model touched. Drift beyond the band is a non-conformance signal, not a hard failure — the runtime **SHOULD** emit `DriftAlert` and let the operator decide whether to demote the backend or pause the deployment. Conformance vectors are signed at release time. Implementations self-certify by round-tripping the public vectors and publishing their receipts. --- ## 7. Wire format versioning - The cascade tier wire tags (`L0`–`L4`) are stable across versions. A future major version **MAY** add tiers (e.g. `L5:Quantum`) but **MUST NOT** renumber existing ones. - The `jc_receipt` field on a receipt is the schema version. This document defines `"1"` (the cascade receipt of §2) and `"policy/1"` (the policy receipt of §10). Unknown major → reject. Unknown minor → accept by ignoring unknown fields. New `jc_receipt` schemas are added under their own prefixed namespace (`"/"`); the bare numeric form `"N"` is reserved for the cascade-walk receipt. - The `jc_pack` field on a `.jc.toml` sidecar follows the same rule. - The `jc_workspace` field on a workspace manifest (§11) follows the prefixed-namespace rule (`"workspace/1"`). --- ## 8. Agent identity A long-running JouleClaw agent is identified by a stable handle bound to an Ed25519 public key. The canonical derivation is W3C `did:key` over multicodec Ed25519: ``` handle = "did:key:z" || base58btc(0xed 0x01 || raw_public_key_32) ``` A conforming `AgentIdentity` carries `(handle, public_key, optional EAT attestation, optional created_at)`. A verifier **MUST** confirm that `handle == did:key_handle(public_key)` before accepting any signed material from that identity. Attestation envelopes (RATS / EAT per RFC 9711) **MAY** be bound to the identity by placing the same `handle` in the EAT `cti` claim. Where this identity flows: - `Receipt.steward` (§2): the cascade-receipt steward identity is the `handle` form when self-describing. - `PolicyReceipt.steward` (§10): same handle, same key. - `WorkspaceManifest.owner` (§11): same handle, same key, with the pubkey embedded so a third-party verifier needs no external mapping. - COSE_Sign1 `kid` header on any signed envelope: same handle. Identity rotation is out of scope for v1. KERI-based AID rotation is the recommended substrate; this spec does not normatively constrain the rotation mechanism. --- ## 9. The policy engine JouleClaw runtimes **MAY** consult an out-of-process policy engine before executing an `Action`. When they do, the engine MUST be deny-by-default and operate at filesystem / network / process granularity. A conforming engine exposes the following surface: - **`Action`** — `Filesystem { path, mode }` | `Network { host, port, method }` | `Process { binary, argv }`. - **`Decision`** — `Allow { rule }` | `Deny { reason }`, where `DenyReason` is `NoMatchingAllow` (deny-by-default) or `ExplicitDeny { rule }`. - **`Policy`** — ordered list of rules, plus a monotonic `version`. A `Rule` is `(effect, agent_scope, action_predicate, name)`. - **Evaluation rule** — explicit `Deny` rules short-circuit before any `Allow`. First matching `Allow` wins. No matching `Allow` ⇒ deny-by-default. **MUST** record an `AuditEvent` per evaluation. - **`AuditEvent`** — `(sequence, policy_version, agent, action, decision)`. Sequence is monotonic within the engine instance. - **Live policy update** — `install_policy(new)` accepts only when `new.version > current.version`. A conforming **out-of-process transport** is line-delimited JSON over a duplex byte stream. One request per line, one response per line. Operations: `evaluate`, `audit`, `audit_since`, `policy_version`, `install_policy`. The server treats a malformed line as an error response and keeps the stream open. The reference engine is `jouleclaw-policy::InMemoryPolicyEngine` (in-process) plus `jouleclaw-policy-ipc::PolicyClient` / `jclaw-policyd` (out-of-process). --- ## 10. The policy receipt A `PolicyReceipt` is the signed audit record for one policy decision. It is a **sibling** of the cascade receipt in §2: same COSE_Sign1 envelope (alg = -8 EdDSA over canonical det-CBOR), same steward identity, but its own schema id (`"policy/1"`) and its own wire shape. ```json { "jc_receipt": "policy/1", "id": "", "closed_at": "", "steward": "", "engine_id": "", "audit_sequence": 7, "policy_version": 2, "agent": "", "action": { "kind": "filesystem", "path": "/workspace/x", "mode": "read" }, "decision": { "kind": "allow", "rule": "read-workspace" } } ``` - The canonical signed core is the det-CBOR (RFC 8949 §4.2.1 length-first map ordering) of the receipt as JSON. - The COSE_Sign1 envelope is identical in shape to the JCR-1 v1 envelope on the cascade receipt: `protected = {1: -8, 4: steward}`, `unprotected = {}`, `payload = canonical signed core`, `signature = Ed25519(Sig_structure)`. - Verifiers reject envelopes whose `kid` (in the protected header) disagrees with the embedded `steward`. - Conforming implementations **MUST** byte-match the three reference vectors in [`jouleclaw-rs/crates/jouleclaw-policy-receipt/conformance/vectors-policy.json`](jouleclaw-rs/crates/jouleclaw-policy-receipt/conformance/vectors-policy.json). Reference verifiers in Rust, Python, and Go ship alongside the vectors; all three produce byte-identical canonical bytes for the same receipt. Policy receipts and cascade receipts share the same JSONL "unified log" file format: readers dispatch on the `jc_receipt` schema tag (`"1"` → cascade, `"policy/1"` → policy, unknown → forward-compat skip). --- ## 11. The agent workspace A persistent, content-addressed workspace **MAY** be attached to a long-running agent. The workspace's wire form is a `WorkspaceManifest`: ```json { "jc_workspace": "workspace/1", "owner": { "handle": "", "public_key": "" }, "entries": [ { "path": "notes/x.md", "content_hash": "", "size": 17, "kind": "text" }, ... ] } ``` - **Path normalisation** — paths are relative `/`-joined segments. Absolute paths, empty paths, empty segments, `.` and `..` segments, and NUL bytes are **MUST** rejected on write. - **Content addressing** — `content_hash` is BLAKE3 hex of the bytes; the underlying backend stores bytes keyed by `content_hash` so identical content is deduplicated. - **Entry order** — entries in the manifest are sorted lexically by `path`. - **Manifest content-address** — the manifest's own content hash is BLAKE3 over its canonical JSON serialisation. Identical workspace state → identical manifest hash → identical signature. - **Signing** — a `SignedWorkspaceManifest` carries an Ed25519 signature over the canonical manifest bytes. Verifiers MUST check both that the embedded `owner.handle` matches the embedded `owner.public_key` under §8 derivation, AND that the signature verifies. The workspace deliberately does NOT specify encryption, conflict resolution, or multi-writer merge. Backends are single-writer; if multi-writer is needed it composes behind a future `WorkspaceBackend` impl with a lock service. Encryption is the caller's job — the manifest signature covers what is observable, not what is decrypted. --- ## 12. Skill interoperability — `SKILL.md` JouleClaw skills are portable to the broader open-skills ecosystem (Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, et al.) via the agentskills.io `SKILL.md` format. Conformance: - A JouleClaw-emitted `SKILL.md` MUST carry the agentskills.io required frontmatter (`name` ≤ 64 chars matching `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`; `description` ≤ 1024 chars). - The deterministic JouleClaw procedure (the `Template` and `Procedure` that let a JouleClaw cascade resolve the skill at lookup energy) travels under `metadata.jouleclaw` as a vendor extension. Non-JouleClaw consumers treat the Markdown body as natural-language instructions; JouleClaw-aware consumers reconstruct the typed Skill. - The `body` is required by emitters — empty bodies are rejected unless the caller opts in explicitly via a `_with_default_body` helper (intended only for drafts). - Unknown vendor metadata keys are preserved on round-trip. --- ## 13. Vocabulary (JSON-LD + Turtle) JouleClaw publishes a stable IRI vocabulary so a JSON-LD parser, a SPARQL store, or a generic third-generation agent client can read any JouleClaw receipt as RDF without bespoke integration. - **Namespace:** `https://jouleclaw.transaction.science/vocab/v1#` (prefix `jc:` by convention). - **JSON-LD context:** `https://jouleclaw.transaction.science/vocab/v1.jsonld` (every field name in §§2, 10, 11 maps to a `jc:`-prefixed IRI with the typed range below). - **Turtle ontology:** `https://jouleclaw.transaction.science/vocab/v1.ttl` (classes, enumerations, properties, ranges; CC-BY-4.0). - **Human index:** [`https://jouleclaw.transaction.science/vocab/v1`](https://jouleclaw.transaction.science/vocab/v1). - **Canonical source:** [`jouleclaw/vocab/`](vocab/) in this repository. The vocabulary is **purely additive**: - A v1 cascade or policy receipt remains a valid JouleClaw receipt on the wire with or without an `@context` field. - Adding `"@context": "https://jouleclaw.transaction.science/vocab/v1.jsonld"` to a receipt expands it into typed RDF triples (e.g. `tier: "L3"` becomes ` jc:tier jc:Model`, `energy_provenance: "ModelBased"` becomes ` jc:energyProvenance jc:ModelBased`) without changing any other field. - The canonical signed core of a JCR-1 envelope **MUST NOT** include `@context` — the JSON-LD context is metadata, not payload. Producers that want to publish a JSON-LD form alongside the signed receipt SHOULD do so in a separate field, or fetch the context out-of-band from the published URL. **Production default.** Conformant producers `SHOULD` emit `@context` set to the v1 vocabulary URL on every receipt by default, so any downstream JSON-LD parser treats the document as typed RDF without configuration. The reference implementations do this in [`ReceiptBuilder::seal`][rb-seal] and [`PolicyReceiptBuilder::build`][pb-build]; the `without_context()` opt-out is reserved for conformance-vector regeneration and backward-compatible wire-form replay. [rb-seal]: jouleclaw-rs/crates/jouleclaw-prov/src/lib.rs [pb-build]: jouleclaw-rs/crates/jouleclaw-policy-receipt/src/lib.rs The vocabulary subclasses W3C PROV-O where the alignment is exact: - `jc:ClaimProvenance &rsubeq; prov:Entity` - `jc:AuditEvent &rsubeq; prov:Activity` - `jc:AgentIdentity &rsubeq; prov:Agent` PROV-O consumers can therefore reason about a JouleClaw deployment as a provenance graph using this one IRI mapping — no JouleClaw-specific code beyond the standard PROV-O semantics. **Versioning.** A future major bump publishes under `/vocab/v2#`. v1 IRIs remain resolvable forever per the open-standards "names are final" rule. --- ## 14. Hydra ApiDocumentation A JouleClaw service publishing a tool surface (MCP server, the out-of-process policy daemon, an HTTP endpoint) **SHOULD** serve a [Hydra Core Vocabulary][hydra] `hydra:ApiDocumentation` document at a stable discovery endpoint. Hydra is the W3C CG draft that solved the "tool schemas live in the client's context window" pathology for the third-generation web: the API describes itself in a machine-readable form, a generic client reads the description once, and the client calls every operation without ever loading a schema into its context. A conforming ApiDocumentation: - Is JSON-LD using both the Hydra Core Vocabulary namespace (`http://www.w3.org/ns/hydra/core#`) and the JouleClaw vocabulary namespace from §13 (`jc:` prefix). - Carries `@type: "ApiDocumentation"` at the root, a stable `@id`, a human-readable `title` + `description`, and a `supportedClass` list. - Each `Class` in `supportedClass` carries `supportedOperation` — one `Operation` per published verb. An `Operation` declares `method`, `expects` (input class IRI; `owl:Nothing` for parameterless), `returns` (output class IRI), and `statusCodes`. - The JouleClaw extension fields `jc_tool_id` (stable tool id) and `jc_mutating` (mirror of MCP's mutation flag) MAY appear on each operation. They reference the JouleClaw vocabulary from §13 so a receipt emitted by that tool cross-links back to its Hydra description. Default mappings the reference emitter uses: | Source field | Hydra field | Default value | |------------------------|-----------------------|------------------------------| | `mutating: false` | `method` | `"GET"` | | `mutating: true` | `method` | `"POST"` | | (none) | `expects` | `owl:Nothing` | | (none) | `returns` | `jc:ToolResponse` | | (none) | `statusCodes` | 200, 400, 500 | | `name` | `jc_tool_id` | `"jouleclaw:"` | The reference emitter is `jouleclaw-hydra::ApiDocumentationBuilder` in the workspace; the `mcp-adapter` feature provides `From<&McpToolSchema> for ToolDescription` so an existing MCP server emits a Hydra doc in one chained call. A generic third-generation agent client fetches the ApiDocumentation, validates the `@context`, and is then free to call every tool by following the typed contract — no out-of-band tool prompts, no schema-per-tool context bloat. **This is the structural fix for the generation-2 "72% of context window on tool schemas" pathology.** [hydra]: https://www.hydra-cg.com/spec/latest/core/ --- ## 15. SHACL shapes A JouleClaw service **SHOULD** publish [SHACL][shacl] Core shapes for every input/output class its Hydra ApiDocumentation (§14) references. The shapes let an agent validate a candidate payload **before** calling a tool — locally, without any model invocation, with deterministic results. The canonical JouleClaw v1 shape graph lives at [`https://jouleclaw.transaction.science/vocab/v1.shapes.ttl`](https://jouleclaw.transaction.science/vocab/v1.shapes.ttl) and covers every class in §§2, 8, 10, 11 (Receipt, PolicyReceipt, WorkspaceManifest, WorkspaceEntry, AgentIdentity, Action with the three subclasses, Decision with Allow and Deny subclasses, ToolTouch, ClaimProvenance). The shapes use only SHACL Core constraints — no SPARQL, no qualified value shapes — so: - A full SHACL validator (pyshacl, Apache Jena) accepts the file directly and produces a `sh:ValidationReport` against any candidate document. - A lightweight in-tree validator (the reference impl is `jouleclaw-shacl::ShapeGraph::jouleclaw_v1()`) covers the same constraints in ~600 lines of Rust with no SPARQL engine. Compiles to WASM so an in-browser agent can validate locally. Constraints in use: `sh:minCount` / `sh:maxCount`, `sh:datatype` (xsd:string, xsd:integer, xsd:nonNegativeInteger, xsd:dateTime, xsd:double, xsd:boolean), `sh:nodeKind` (sh:IRI, sh:Literal), `sh:in` (enumerations), `sh:pattern` (regex), `sh:minInclusive` / `sh:maxInclusive`, and `sh:node` (nested shape delegation). The shape file is the contract a JouleClaw operator publishes alongside their Hydra ApiDocumentation; the lightweight validator is the agent-side counterpart. A tool input that fails validation **MUST NOT** be sent to the tool. [shacl]: https://www.w3.org/TR/shacl/ --- ## 16. Validation contract A **validation contract** is the planning artifact a multi-step JouleClaw run is judged against. It is authored *before* any implementation work begins, lives independently of the code, and is the only thing that decides whether a mission succeeded. ### 16.1 Shape A contract is a JSON document with the fields: - `jc_contract`: `"contract/1"` (this version). - `@context`: optional JSON-LD context, defaults to `https://jouleclaw.transaction.science/vocab/v1.jsonld`. - `title`: free-form mission name. - `authored_by`: `did:key:…` of the agent or person who sealed the contract. May be empty for unsigned drafts. - `assertions`: an ordered list of [`Assertion`](#162-assertion). Ids **MUST** be unique within the contract. - `features`: an ordered list of [`Feature`](#163-feature). Ids **MUST** be unique. Each feature's `claims` **MUST** reference only assertion ids that exist in the contract. - `acceptance`: optional metadata controlling ship-gate rules. The contract's content hash is BLAKE3 over the canonical JSON serialisation; identical contracts → identical hashes. The content hash is what a [JCR-1 receipt](#2-the-receipt) binds to when it claims to have run against this contract. ### 16.2 Assertion Each assertion is one falsifiable claim: - `id`: stable string (e.g., `"A-001"`). - `title`: one-line summary. - `rationale`: free-form *why*. Optional. - `priority`: one of `must_have` | `should_have` | `nice_to_have`. - `check`: one of: - `{ "kind": "tool", "tool_id": "…", "args_hash": "…"? }` - `{ "kind": "artifact", "path": "…", "expected_hash": "…"? }` - `{ "kind": "command", "command_hash": "…", "expected_exit": N }` - `{ "kind": "checker", "checker_id": "…" }` A `must_have` assertion that does not roll up to `verified` **MUST** block ship. A `should_have` assertion that does not roll up to `verified` **MUST NOT** block ship unless `acceptance.block_on_should_have` is true. ### 16.3 Feature Each feature is one unit of work that *claims* one or more assertion ids it intends to satisfy: - `id`: stable string (e.g., `"F-001"`). - `title` + optional `description`. - `claims`: list of assertion ids this feature covers. A worker dispatched against a feature **SHOULD** emit [evidence](#164-evidence) for every assertion that feature claims; the verifier surfaces missing evidence as a gap. ### 16.4 Evidence The verifier consumes a bag of evidence items the run produced: - `tool_result { tool_id, args_hash?, passed }` - `artifact_present { path, hash }` - `command_run { command_hash, exit_code }` - `checker_result { checker_id, passed }` An evidence item matches an assertion when its discriminants match the assertion's check. A matching item with `passed: true` (or, for `command`, `exit_code == expected_exit`; for `artifact`, `hash == expected_hash` when supplied) raises the assertion to `verified`. Any matching failure raises the assertion to `failed`; the verifier surfaces the disagreement rather than silently allowing a later success to mask it. ### 16.5 Verification The verifier is a pure function over `(contract, evidence)`. It emits a `ContractVerdict`: - `jc_verdict`: `"verdict/1"`. - `contract_hash`: hex BLAKE3 of the contract. - `passed`: boolean. - `summary`: human-readable one-liner. - `coverage`: a typed matrix with one row per assertion, one column per feature, plus a per-assertion rollup (`verified` | `claimed_unverified` | `failed` | `gap`). - `blocking_gaps`: must-have assertion ids not rolled up to `verified`. - `should_have_gaps`: should-have assertion ids not rolled up to `verified`. Same inputs → same verdict. The verdict is the artifact a receipt links to when reporting a multi-day run's outcome. ### 16.6 Conformance A conforming **producer** of a contract MUST: - Set `jc_contract` to `"contract/1"`. - Reject duplicate assertion ids and duplicate feature ids. - Reject features whose `claims` reference unknown assertion ids. A conforming **verifier** of a contract MUST: - Implement the rollup rules in §16.5 exactly: any matching failure → `failed`; otherwise any matching pass → `verified`; otherwise any claim → `claimed_unverified`; otherwise → `gap`. - Block ship on any `must_have` non-`verified` rollup. - Block ship on `should_have` non-`verified` rollups iff `acceptance.block_on_should_have` is true. Reference: [`crates/jouleclaw-contract`](./jouleclaw-rs/crates/jouleclaw-contract/). SHACL shape: `jc:ValidationContractShape` at [`vocab/v1.shapes.ttl`](./vocab/v1.shapes.ttl). ### 16.7 Verdict receipt The §16.5 verifier emits a [`ContractVerdict`](#165-verification) as plain JSON. To land that verdict on the unified auditable log alongside cascade receipts (`"1"`) and policy receipts (`"policy/1"`), wrap it in a **verdict receipt** — sibling schema `"verdict-receipt/1"`, same canonical det-CBOR + COSE_Sign1 envelope every other JouleClaw sibling receipt uses, under the same steward identity. ```json { "jc_receipt": "verdict-receipt/1", "id": "", "closed_at": "", "steward": "", "engine_id": "", "audit_sequence": 7, "contract_hash": "", "verdict": { /* ContractVerdict, verbatim */ } } ``` Wire-format rules: - The canonical signed core carries the verdict as a **JSON-string** field named `verdict_json` (not a nested object), with a sibling `verdict_hash` field set to hex BLAKE3 of the `verdict_json` bytes. This keeps the signed core inside the JCR-1 canonical-CBOR subset (which forbids bools and nulls) while still binding the verdict to the signature. The wire-form JSON object surfaced to consumers MAY carry `verdict` as a nested object for ergonomics; the signed core is normative. - The COSE_Sign1 envelope is identical in shape to JCR-1 v1: `protected = {1: -8, 4: steward}`, `unprotected = {}`, `payload = canonical signed core`, `signature = Ed25519(Sig_structure)`. - `contract_hash` MUST equal the BLAKE3 content hash of the [`ValidationContract`](#161-shape) the verdict was produced against. Verifiers consuming the unified log MAY index by `contract_hash` without parsing the inner verdict. Conforming producers + verifiers SHOULD reuse the existing JCR-1 envelope tooling (verifiers reject envelopes whose `kid` disagrees with the embedded `steward`, etc.). Reference: [`crates/jouleclaw-contract-receipt`](./jouleclaw-rs/crates/jouleclaw-contract-receipt/). --- ## 17. Worker handoff A **worker handoff** is the structured wire form an agent emits at end-of-feature-work. The handoff is what makes a multi-day run readable to the next worker (or the next session of the same worker) — it forces the agent to write down what actually happened rather than relying on conversational context. ### 17.1 Shape A handoff is recorded as a `RunEvent::HandoffRecorded` variant on the [run journal](#2-the-receipt): - `worker`: stable worker id (typically `did:key:…`). - `node_id`: optional graph node this handoff closes. - `feature_id`: optional contract feature id this handoff claims to satisfy. - `closed_at`: epoch-seconds wall-clock. - `completed`: list of items reported done. - `undone`: list of items reported left undone. - `commands`: list of `{ command_hash, argv, exit_code }` entries observed during the work window. - `issues_found`: list of issues the worker discovered. - `procedures_followed`: list of skills / runbooks the worker applied. `command_hash` MUST be hex BLAKE3 over `argv.join("\0")`. The hash, not the argv array, is the command's identity; the argv is carried for human inspection only. The handoff hash is part of the journal entry's hash chain, so editing handoff fields after the fact breaks chain verification. ### 17.2 Conformance A conforming **producer** of a handoff MUST: - Set every field that is non-empty in the run; empty lists are acceptable but the discriminator MUST be present. - Compute `command_hash` as specified. A conforming **consumer** of a handoff MUST: - Accept additive fields (the variant set is open under semver-compatible extension). - Verify the journal's hash chain before trusting the handoff's contents. Reference: [`crates/jouleclaw-graph`](./jouleclaw-rs/crates/jouleclaw-graph/) (`WorkerHandoffEvent`, `HandoffCommand`, `RunEvent::HandoffRecorded`). SHACL shape: `jc:WorkerHandoffShape` at [`vocab/v1.shapes.ttl`](./vocab/v1.shapes.ttl). --- ## 18. Mission orchestrator The **mission** primitive composes [§16 contracts](#16-validation-contract) + [§17 handoffs](#17-worker-handoff) + the run journal into a three-role pipeline: **Orchestrator** authors, **Worker** does, **Validator** judges. ### 18.1 Roles - The **Orchestrator** authors a `ValidationContract` and a feature plan. It does NOT execute work; it composes the plan and the validator's expectation in one artifact. - A **Worker** is dispatched per feature. It performs whatever work it does (opaque to this spec) and returns a `WorkerOutcome { handoff, evidence }`. Workers MAY be backed by any cascade tier — deterministic tools, models, or humans-in-the-loop. - The **Validator** runs the §16.5 verifier over the accumulated evidence and emits a `ContractVerdict`. The validator's only input is `(contract, evidence)` — pure data — so its verdict is reproducible and reviewable. ### 18.2 Dispatch Workers MUST be dispatched in feature order, serially, when the features mutate shared state. Read-only fan-out (parallel search, parallel verifiers) MAY be parallel; the implementation is the caller's choice and the spec does not require it. Each worker's handoff MUST be recorded on the run journal before the next worker is dispatched, so the chain stays chronological. ### 18.3 Strictness A `strict_workers` mode MAY refuse worker outcomes that produce no evidence for at least one assertion the worker's feature claims, failing fast rather than letting the validator surface the gap later. The default behaviour is non-strict (let the validator rollup decide). Reference: [`crates/jouleclaw-mission`](./jouleclaw-rs/crates/jouleclaw-mission/). --- ## 19. Value report Where a JCR-1 receipt records *what happened* (the activity), a **value report** records *what landed* against the agent's declared intent. The two together close the activity-vs-value gap: activity is easy to count; value is what the user paid for. ### 19.1 Shape A value report is a JSON document: - `intent`: free-form natural-language intent the agent was acting on. - `tool_id`: tool id the call addressed. - `checks`: per-check verdicts, each `{ check, passed, reason? }`. - `closure_rate`: `passed_count / checks.len()` ∈ [0, 1]. `0.0` when `checks` is empty. - `fully_closed`: true iff `checks` is non-empty AND every check passed. ### 19.2 Check kinds - `status { codes }` — status code MUST appear in `codes`. - `status_matches_contract` — status MUST be in the operation's declared `statusCodes` menu (the Hydra contract). - `output_hash_equals { hash }` — canonical-JSON BLAKE3 of the body MUST equal `hash`. - `json_pointer_equals { pointer, expected }` — RFC 6901 pointer MUST resolve to `expected`. Implementations MAY define additional check kinds; consumers MUST tolerate unknown kinds and treat them as `passed: false` with a `reason` that names the unknown kind. ### 19.3 Aggregation The mean closure rate across a set of value reports is the system's honest "delivered / attempted" metric — denominated in user intent rather than joules. Reports with no checks declared MUST be skipped in the aggregate (they convey no value information). Reference: [`crates/jouleclaw-hydra-client`](./jouleclaw-rs/crates/jouleclaw-hydra-client/) (`ValueReport`, `ValueCheck`, `ValueCheckResult`, `mean_closure_rate`). --- ## 20. What this spec deliberately does not say - **How to build the model.** That's the model-author's concern. JouleClaw measures and dispatches; it doesn't train. - **Which retrieval API to use.** Brave / Tavily / Exa / Serper all plug in through the `SearchProvider` trait. Pick whichever your deployment permits. - **How to ship receipts.** The receipt is produced. Transport (HTTP / lockstep / message queue) is the deployer's choice. Smart Byte's signed-envelope replication is the recommended substrate. - **A specific signing key topology.** Bring your own. Smart Byte's KERI-based AID rotation is the recommended path. --- ## 21. Adjacent techniques This section names the architectural pattern JouleClaw implements and lists the research communities that have, separately, solved parts of it. The intent is not novelty-claiming. It is to make the assembly visible so an engineer arriving from any one of those communities can locate their work inside the cascade. ### 9.1 The architectural pattern An LLM inference call is a render pass. A token is a frame. A reasoning chain is a sequence of frames. A context window is a scene graph. An agent loop is an NPC control loop. RAG is texture streaming. A model checkpoint is a level asset. The pipeline from prompt to response is — structurally — exactly the work a game engine does between input poll and presented frame. The game-engine industry was forced to solve this problem under a fixed 150–200 W power budget twenty years ago. The five JouleClaw cascade tiers are direct translations of game-engine architectural primitives: | JouleClaw tier | Game-engine primitive | What the engine actually does | |-----------------|--------------------------------|-------------------------------| | `L0:Cache` | texture / asset cache | Content-addressed; cheap to check; valid until invalidated | | `L1:Lawful` | pre-baked geometry, LUTs | The work the engine *refuses to run* because the answer is already in the format | | `L2:Embed` | BVH / spatial query | Find the closest match; do not compute from first principles | | `L3:Model` | procedural / runtime synthesis | Invoked only when nothing baked or streamed will do | | `L4:Wire` | server-streamed asset / CDN | The escape hatch when the local box cannot satisfy | Each game-engine technique listed below has a near-exact counterpart in modern AI inference that the AI industry has, so far, declined to deploy at the same architectural rigor: Every lever below now has a **shipped** JouleClaw realization — the frame is no longer rhetorical; each row points at in-tree code: | Game-engine technique | AI counterpart | JouleClaw component (shipped) | |--------------------------------|-------------------------------------------------------------|---------------------| | Frustum culling | Skip tiers whose `estimate_cost` returns `None` | `jouleclaw-cascade::Tier::estimate_cost` | | Level-of-detail (LOD) | Route to the cheapest sufficient model — SLM before frontier | `jouleclaw-dispatch::ModelBankTier` (cheapest *capable* slot by measured J) | | Deferred rendering | Do not forward-pass through 175B parameters for a token a 7B would produce identically | `jouleclaw-dispatch` cost-table over backends declaring their `J/op` | | Physically-based rendering | One foundation model, derive specializations — not 12 full fine-tunes | (consumer concern; the spec doesn't dictate) | | Virtual texturing | Retrieve only the context this token will attend to, not the whole 128k window | `jouleclaw-stack` RAG pipeline (`retrieve → enrich → rerank → read`, top-k only) + `jouleclaw-fresh` | | Temporal upsampling | Reuse prior verified work; reconstruct from a small delta, not by re-running | `jouleclaw-promote` (exact yang→yin) + `jouleclaw-skill` (whole query class) | | Nanite-style mesh streaming | Activate only the reasoner the input actually needs | `jouleclaw-dispatch` routes to the one slot, not the whole bank | | Hardware ray tracing + denoiser | A few high-quality forward passes plus a verifier beats one large unconstrained pass | `jouleclaw-verify` (`OutputVerifier`) + `jouleclaw-approve` gate before the pass | | Agent / NPC control loop | Bounded multi-step recursion — fan-out capped, depth bounded by the joule budget | `jouleclaw-agent` (`max_steps` + per-branch budget clamp) | | Frame budget | `JouleBudget` walks the cascade like a render budget walks the scene graph | `jouleclaw-energy::EnergyQuota` + breaker, `jouleclaw-governor` (global), `jouleclaw-agent` (nested) | The pattern is not new. The assembly — and the fact that every lever is a shipped, tested crate rather than a slogan — is. ### 9.2 Five communities, one architecture Five research communities currently hold one face each of this architecture. They publish at different venues and do not, by and large, talk to one another. A conforming JouleClaw runtime composes all five of their primitives — that composition is the standard's contribution. | Community | Representative work | JouleClaw component | |---|---|---| | **Constrained decoding** | Outlines (Willard & Louf), XGrammar (Dong et al. 2024), Guidance, LMQL, Pre³, OpenAI/Anthropic structured-output APIs | `jouleclaw-decode` *(shipped)* — pure-Rust regex / CFG / JSON-schema → token-vocabulary mask | | **Compound AI systems / DSPy** | DSPy (Khattab et al., Stanford → MIT; CAIS 2026 inaugural ACM conference, May 2026) | `jouleclaw-program` *(shipped)* — typed signatures + module compiler — and `jouleclaw-skill`, its deterministic skill-compilation realization | | **Small / specialist models** | NVIDIA Research (Belcak & Heinrich, 2025), Microsoft Phi team, TinyML, llama.cpp | `jouleclaw-cascade` router + `jouleclaw-pack` declared-cost contracts | | **Neurosymbolic / verifier-in-the-loop** | Lean + LLM provers, BMC + LLM (LaM4Inv), SymCode, ProofNet++, VIRF, Eidoku | `jouleclaw-verify` (`OutputVerifier` trait + `VerifierChain` + receipt integration) | | **Energy measurement / Green Software** | Patterson et al., ML.ENERGY Leaderboard, MDPI Sensors edge-computing surveys, GSF SCI specification, AI Energy Score | `jouleclaw-energy` + the `Provenance` honesty contract + `.jc.toml` measured-cost rows | A conforming runtime **SHOULD** be able to point at concrete in-tree code or a registered adapter for each of the five primitives above. A runtime that solves only one face is a research project, not a JouleClaw implementation. ### 9.3 The three-lever ceiling Energy reduction from a fully-naive monolithic baseline (~10¹⁸ above the Landauer floor for current generative inference per output bit) composes multiplicatively across three independent levers: | Lever | Reduces by | What does it | |-------|-----------|---------------| | **Route to the right cell** | 10⁸–10¹⁰× | The cascade itself — `L0 / L1 / L2` close most queries without invoking a model | | **Cache the prior work** | 10²–10⁴× | Content-addressed cache (`L0`), prior-resolution history, MRL embeddings (`L2`) | | **Align silicon to primitive** | 10²–10⁴× | The `.jc.toml` declared-cost contract is the input data hardware co-design needs | Stacked total: **10¹²–10¹⁸×** below the naive baseline. The "90 % reduction" figure quoted on the marketing surface is the conservative floor of what the three levers permit when composed honestly. The ceiling is not the Landauer bound — reaching the bound requires reversible logic and zero-impedance interconnect that nobody can engineer today. The ceiling is how disciplined the routing and the hardware choices are. ### 9.4 The receipt is the proof, not the marketing A runtime that produces lower receipts than the conformance vectors demand without the per-tool-touch `Provenance` to back them is non-conformant. JouleClaw refuses the receipts-as-marketing failure mode that has accumulated around carbon offsets and software sustainability claims more broadly. Every `joules_uj` figure in a conforming receipt must trace back to either a real hardware counter (`Provenance::HwShunt`), a documented vendor model (`Provenance::ModelBased`), or a calibrated static estimator (`Provenance::Estimator`) with a wider tolerance band. The breaker enforces at the granularity of the worst counter in the span. This is normative. --- ## 22. References - [JouleClaw Charter](../CHARTER.md) — stewardship pattern (shared across all five open standards) - [Smart Byte open standard](../smart-byte/) — signed envelopes - [EOC open standard](../eoc/) — the four-stage memoising cascade pattern JouleClaw embodies - [WAI open standard](../wai/) — media transport + capability dispatch - [OpenPay open standard](../openpay/) — the typestate-enforced lifecycle pattern adopted by JouleClaw's cascade - W3C PROV-O — provenance vocabulary - RFC 9449 — DPoP (sender-constrained tokens, recommended for ClaimProvenance envelopes that carry a fetch credential) - Landauer, R. (1961). "Irreversibility and Heat Generation in the Computing Process." The thermodynamic floor under everything in this spec.