2ff01fcc6a
Promotes the wave-12..21 surfaces from "shipped in the reference
implementation" to "documented as part of the open standard." A
third party building a JouleClaw-compatible runtime now has a
normative spec to implement against.
New normative sections:
§8 Agent identity — the W3C did:key derivation over multicodec
Ed25519, with the contract that handle MUST equal
did:key_handle(public_key). Flows into Receipt.steward,
PolicyReceipt.steward, WorkspaceManifest.owner, and the
COSE_Sign1 kid header.
§9 The policy engine — deny-by-default at filesystem / network /
process granularity. Explicit Deny short-circuits before any
Allow. Per-evaluation AuditEvent (monotonic sequence). Live
install_policy with monotonic version. LD-JSON wire protocol
for the out-of-process transport (jclaw-policyd).
§10 The policy receipt — sibling of the cascade receipt with
schema "policy/1", same COSE_Sign1 + alg -8 EdDSA envelope.
Same steward identity. Conforming implementations MUST
byte-match the three reference vectors. Same JSONL "unified
log" file format as the cascade receipt; readers dispatch on
the schema tag.
§11 The agent workspace — content-addressed (BLAKE3) entries,
path-normalisation rules, lexically-sorted entries,
Ed25519-signed manifests with the owner identity binding
checked end-to-end on verify.
§12 SKILL.md interoperability — agentskills.io frontmatter
requirements, the metadata.jouleclaw vendor extension for the
deterministic procedure, mandatory authored body.
Plus §7 (versioning) is updated to name "policy/1" alongside "1"
and to spell out the prefixed-namespace rule for new jc_receipt
schemas. The old §§8-10 (does-not-say / adjacent / references)
renumber to §§13-15.
Also extends conformance/v1/README.md with a "Policy-receipt
conformance" subsection pointing at the wave-18 vector suite +
Rust/Python/Go reference verifiers.
Scanner stays clean on every changed surface.
73 lines
4 KiB
Markdown
73 lines
4 KiB
Markdown
# JouleClaw v1 conformance vectors
|
||
|
||
A conforming implementation **MUST** round-trip every vector in this
|
||
directory and produce a `jouleclaw-prov::Receipt` whose `tier`,
|
||
`tools_touched[].tool_id`, and `claims[].content_hash` match the
|
||
canonical receipt.
|
||
|
||
The `joules_uj` field is platform-dependent and **MUST** fall within
|
||
the drift band declared in the relevant `.jc.toml` sidecar. The
|
||
canonical receipts in this directory are the reference-hardware
|
||
baseline (Apple M5 Max running the published `jouleclaw-rs`
|
||
reference impl) — implementations on other hardware should match the
|
||
shape, not the absolute joule count.
|
||
|
||
## Coverage (v1.0.0)
|
||
|
||
| Vector | Cascade tier closed | Why it exercises the spec |
|
||
|---------------------------------------|---------------------|-----------------------------------------------------|
|
||
| `cache-hit/` | L0 | Repeat-query content-addressed cache |
|
||
| `lawful-arithmetic/` | L1 | Deterministic primitive — `gcd`, unit conversion |
|
||
| `embed-hybrid-search/` | L2 | BM25 + ANN fusion against a fixed local corpus |
|
||
| `fresh-retrieval-with-provenance/` | L3.5 | Live fetch, Smart Byte envelope, trust tier |
|
||
| `model-local-ssm/` | L3 | Liquid CfC / Mamba forward pass |
|
||
| `model-local-ternary/` | L3 | Prism / BitNet 1.58 ternary forward pass |
|
||
| `model-local-diffusion-image/` | L3 | SDXL / SD3 / Flux-dev image gen |
|
||
| `wire-frontier-rpc/` | L4 | Remote frontier as the explicit escape hatch |
|
||
| `breaker-trips-on-budget-exhaust/` | (any) | Thermodynamic kill-switch under runaway loop |
|
||
| `joule-mcp-cbor-negotiation/` | (any) | MCP capability handshake elects binary transport |
|
||
|
||
Each vector directory contains:
|
||
|
||
- `input.txt` — the input fed to the runtime
|
||
- `pack.jc.toml` — the declared-cost contract for any model touched
|
||
- `receipt.json` — the canonical receipt the runtime must reproduce
|
||
- `README.md` — what the vector exercises and the acceptance bounds
|
||
|
||
Vectors are signed at release time. The signature lives in
|
||
`SHA256SUMS.sig` next to `SHA256SUMS` — see the JouleClaw release
|
||
documentation for verification instructions.
|
||
|
||
## Policy-receipt conformance (sibling schema)
|
||
|
||
The cascade receipt (`jc_receipt: "1"`) defined in §2 of `SPEC.md`
|
||
is one of two normative receipt families. The other is the
|
||
**policy receipt** (`jc_receipt: "policy/1"`) defined in §10 of
|
||
`SPEC.md`. Its conformance vectors and reference verifiers live
|
||
under the reference implementation at
|
||
[`jouleclaw-rs/crates/jouleclaw-policy-receipt/conformance/`](../../jouleclaw-rs/crates/jouleclaw-policy-receipt/conformance/):
|
||
|
||
- `vectors-policy.json` — three vectors covering Allow with named
|
||
rule, Explicit deny, and No-matching-allow (deny-by-default).
|
||
- `verify.py` — Python reference verifier (cbor2 + cryptography).
|
||
- `verify.go` — Go reference verifier (stdlib only).
|
||
- `README.md` — vector descriptions, regeneration procedure, scope.
|
||
|
||
Conforming implementations of §10 **MUST** reproduce the canonical
|
||
signed-core CBOR and the COSE_Sign1 envelope byte-for-byte for each
|
||
of the three vectors under the published test key.
|
||
|
||
## Adding a vector
|
||
|
||
1. Land the runtime change in `jouleclaw-rs/` that the vector
|
||
exercises.
|
||
2. Generate the canonical receipt by running the reference impl
|
||
against the input.
|
||
3. Hand-curate the `pack.jc.toml` drift band so the platform
|
||
variation is sensible (typically 1.5× for `ModelBased` counters,
|
||
1.2× for `HwShunt`, 3× for `Estimator`).
|
||
4. Add a `README.md` explaining the vector's intent and the
|
||
acceptance bounds.
|
||
5. Refresh `SHA256SUMS` and re-sign.
|
||
|
||
v1.0.0 stub — vector population follows reference-impl maturity.
|