| Filename | Latest commit message | Latest commit date |
|---|---|---|
4def92aac1
Four precision primitives for multi-day, multi-agent runs.
- jouleclaw-contract: ValidationContract / Assertion / Feature /
Evidence / verify() -> ContractVerdict. Authored before code,
lives independently of implementation. Typed coverage matrix
with per-assertion rollup; must-have gaps block ship.
- jouleclaw-graph: RunEvent::HandoffRecorded variant +
WorkerHandoffEvent + HandoffCommand (BLAKE3 over NUL-joined
argv). Forces every agent to write down what happened; hash
chain protects against post-hoc edits.
- jouleclaw-mission: three-role Mission { contract, run,
evidence } with async Worker trait. Orchestrator authors,
Worker does, Validator judges. Serial-by-default dispatch;
validate() is a pure function of (contract, evidence).
- jouleclaw-hydra-client: ValueReport companion to CallReport.
Tracks closure rate (delivered / attempted) per call;
mean_closure_rate aggregates across a run. The activity-vs-
value gap closed at the dispatch layer.
Spec gains normative sections 16 (contract) / 17 (handoff) /
18 (mission) / 19 (value report). Vocab v1.jsonld + v1.ttl +
v1.shapes.ttl extended with the new classes, enumerations,
properties, and SHACL shapes.
Drive-by: jouleclaw-stack had jouleclaw-prov as a dev-dep while
using it in library code; promoted to [dependencies].
Tests: contract 17/17, graph 40/40 (+2 new), mission 6/6,
hydra-client 20/20 (+4 new). Two runnable examples
(missions_pass, three_role_demo).
Co-Authored-By: Claude Opus 4.7 <[email protected]>
|
||
| .. | ||
| README.md | ||
| v1.jsonld | ||
| v1.shapes.ttl | ||
| v1.ttl | ||
JouleClaw vocabulary (v1)
Stable IRIs for the JouleClaw open-standard data model. Adopting the third-generation interoperability stance: every JouleClaw field gets a globally unambiguous IRI, every JouleClaw enum gets a typed class, and JSON-LD / SPARQL / OWL consumers can reason about a JouleClaw deployment without bespoke integration code.
Namespace
https://jouleclaw.transaction.science/vocab/v1#
By convention prefix: jc:.
Files
| File | Format | What |
|---|---|---|
v1.jsonld |
JSON-LD @context |
The term-to-IRI mapping that lets a JouleClaw receipt JSON document be read as RDF without changing its wire form. |
v1.ttl |
Turtle (RDF) | The full vocabulary — classes, enumerations, properties, ranges. The canonical semantic definition. |
README.md |
Markdown | This file. |
The website at https://jouleclaw.transaction.science/vocab/v1 serves the human-readable index of the same terms.
Why this exists
The JouleClaw wire forms (cascade Receipt, PolicyReceipt,
WorkspaceManifest, the policy Action / Decision, the energy
Provenance enum, etc.) are already stable, signed, and
conformance-verified across three independent implementations
(Rust + Python + Go). What was missing: a machine-readable
contract a consumer outside the JouleClaw ecosystem could ground
on. Without one, every integration is bespoke — the
"snowflake-schemas-everywhere" pathology Marcus Lanthaler's 2014
dissertation identified as the load-bearing failure mode of
generation-2 web APIs.
This vocabulary fixes that. It is purely additive:
- Existing JouleClaw consumers ignore
@contextand read receipts exactly as they did before. No wire-form change. No signed-bytes change. - JSON-LD-aware consumers add
@context: "https://jouleclaw.transaction.science/vocab/v1.jsonld"to a receipt (or fetch the context out-of-band) and gain typed RDF semantics for every field. - SPARQL consumers shred receipts into a triple store using
v1.ttlas the schema and query across cascade + policy + workspace + identity in one query.
What it covers
The vocabulary defines IRIs for every term in the JouleClaw open-standards data model:
- Classes:
Receipt,PolicyReceipt,WorkspaceManifest,WorkspaceEntry,AgentIdentity,ToolTouch,ToolReceipt,ClaimProvenance,Citation,TextSpan,TokenAttribution,IntentVerdict,Action(withFsAction/NetAction/ProcActionsubclasses),Decision(withAllow/Denysubclasses),AuditEvent. - Enumerations:
Cascade(L0:Cache…L4:Wire),Provenance(HwShunt/ModelBased/Estimator),FsMode,NetMethod,DenyReason,EntryKind,SensitivityLevel. - Properties: every public field of every JouleClaw wire type
(
jc:closedAt,jc:joulesMicrojoules,jc:tier,jc:policyVersion,jc:contentHash, …).
The vocabulary subclasses W3C PROV-O where the alignment is exact:
jc:ClaimProvenance is a prov:Entity, jc:AuditEvent is a
prov:Activity, jc:AgentIdentity is a prov:Agent. PROV-O
consumers can therefore reason about a JouleClaw deployment as a
provenance graph without any JouleClaw-specific knowledge beyond
this one IRI mapping.
Conformance with existing wire forms
The vocabulary is designed so that a v1 JouleClaw receipt is a
valid JSON-LD document by adding a single @context field:
{
"@context": "https://jouleclaw.transaction.science/vocab/v1.jsonld",
"jc_receipt": "1",
"id": "rcpt-0001",
"closed_at": "2026-06-02T12:00:00Z",
"input_hash": "b1883b...",
"tier": "L3",
"joules_uj": 3500000,
"energy_provenance": "ModelBased",
"steward": "did:key:zAlpha"
}
A JSON-LD parser expands the above into typed RDF triples
referencing this vocabulary. The tier: "L3" becomes
<rcpt-0001> jc:tier jc:Model ., the energy_provenance: "ModelBased" becomes <rcpt-0001> jc:energyProvenance jc:ModelBased ., etc. Same bytes, same signature, but now the
output is queryable.
Versioning
A future major version of the vocabulary publishes under
https://jouleclaw.transaction.science/vocab/v2#. v1 IRIs remain
resolvable forever — the open-standard's "names are final" rule
(per [[feedback-open-standards-framing]]) applies here too.
Licence
CC-BY-4.0 (consistent with the JouleClaw specification text).