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 124
open-standards/jouleclaw/conformance/v1/README.md
Transaction Science 2ff01fcc6a jouleclaw SPEC.md: normative §§8-12 for waves 12-21 
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.
2026-06-02 10:42:25 -04:00

4 KiB
Raw Permalink Blame History

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/:

  • 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.