Vocabulary v1 · stable IRIs · machine-readable contract

JouleClaw vocabulary, v1.
A globally unambiguous IRI for every field.

The JouleClaw wire forms — cascade receipt, policy receipt, workspace manifest, agent identity, policy actions and decisions — are stable across three byte-equal reference implementations. This vocabulary maps every field to a stable IRI so a JSON-LD parser, a SPARQL store, or a generic third-generation agent client can read JouleClaw output as RDF without bespoke integration. It is purely additive: existing consumers keep working unchanged.

Quickstart

Add one field to any JouleClaw receipt. JSON-LD readers expand it into typed RDF triples; existing JSON readers ignore it. 

{
  "@context": "https://jouleclaw.transaction.science/vocab/v1.jsonld",
  "jc_receipt": "1",
  "id": "rcpt-0001",
  "closed_at": "2026-06-02T12:00:00Z",
  "tier": "L3",
  "joules_uj": 3500000,
  "energy_provenance": "ModelBased",
  "steward": "did:key:zAlpha"
}
application/ld+json
v1.jsonld →
JSON-LD context (term → IRI mapping).
text/turtle
v1.ttl →
Turtle ontology (RDFS + OWL classes, properties, enums).
SHACL Core
v1.shapes.ttl →
SHACL shape graph — validate Receipt / PolicyReceipt / Workspace before sending. Spec §15.
canonical source
repo /vocab →
All three files plus README. CC-BY-4.0.

Classes

Each class has a stable IRI under https://jouleclaw.transaction.science/vocab/v1#. Classes that align with W3C PROV-O subclass it (ClaimProvenance → prov:Entity, AuditEvent → prov:Activity, AgentIdentity → prov:Agent) so PROV-O consumers reason about JouleClaw output without any JouleClaw-specific knowledge beyond this vocabulary.

jc:Receipt #

One signed thermodynamic record per cascade walk; schema id "1". See SPEC.md §2.

jc:PolicyReceipt #

One signed audit record per policy evaluation; schema id "policy/1". See SPEC.md §10.

jc:WorkspaceManifest #

Content-addressed manifest of a persistent agent workspace; schema id "workspace/1". See SPEC.md §11.

jc:WorkspaceEntry #

One named entry inside a WorkspaceManifest — path, content_hash, size, kind.

jc:AgentIdentity #

did:key-bound Ed25519 identity. Subclass of prov:Agent. See SPEC.md §8.

jc:ToolTouch #

One tool invocation observed during a cascade walk.

jc:ToolReceipt #

HMAC-signed gateway attestation that a tool was invoked, observed by the gateway, not the model.

jc:ClaimProvenance #

Provenance of one retrieved claim that fed the cascade resolution. Subclass of prov:Entity.

jc:Citation #

Span-level grounding linking an output byte range to a retrieval chunk.

jc:TextSpan #

Half-open byte range [start, end) over an output text.

jc:TokenAttribution #

Per-token attribution row produced by a TokenAttributor.

jc:IntentVerdict #

Query-intent classification verdict (six-variant taxonomy).

jc:Action #

What a JouleClaw agent is about to do — filesystem, network, or process. See SPEC.md §9.

jc:FsAction #

Filesystem action subclass of Action.

jc:NetAction #

Network action subclass of Action.

jc:ProcAction #

Process action subclass of Action.

jc:Decision #

Output of one policy evaluation — Allow or Deny.

jc:Allow #

Decision subclass — permitted by a named rule.

jc:Deny #

Decision subclass — refused; carries a DenyReason.

jc:AuditEvent #

Append-only record of one policy evaluation. Subclass of prov:Activity.

jc:ValidationContract #

Planning artifact a multi-step JouleClaw run is judged against. Authored before code, lives independently of the implementation; schema id "contract/1". See SPEC.md §16.

jc:Assertion #

One falsifiable claim with a stable id, a priority, and an AssertionCheck.

jc:AssertionCheck #

How an assertion is verified — Tool / Artifact / Command / Checker.

jc:Feature #

One unit of work that claims one or more assertion ids.

jc:ContractVerdict #

Result of running the verifier — passed flag, coverage matrix, blocking-gap list; schema id "verdict/1". See SPEC.md §16.5.

jc:WorkerHandoff #

Structured record an agent emits at end of a unit of work: what got done, what was left undone, commands run, issues discovered, procedures followed. See SPEC.md §17.

jc:HandoffCommand #

One command observed during the handoff window.

Enumerations

jc:Cascade #

Five energy-class cascade tiers.

  • jc:Cache (L0)
  • jc:Lawful (L1)
  • jc:Embed (L2)
  • jc:Model (L3)
  • jc:Wire (L4)
jc:Provenance #

Honesty tier of an energy counter; the breaker enforces at the worst counter seen.

  • jc:HwShunt
  • jc:ModelBased
  • jc:Estimator
jc:FsMode #

Filesystem access modes.

  • jc:FsRead
  • jc:FsWrite
  • jc:FsExecute
  • jc:FsList
jc:NetMethod #

Network method.

  • jc:NetConnect
  • jc:NetListen
  • jc:NetResolve
jc:DenyReason #

Why a Deny decision was returned.

  • jc:NoMatchingAllow
  • jc:ExplicitDeny
jc:EntryKind #

Workspace entry type tag.

  • jc:Blob
  • jc:Text
  • jc:Structured
jc:SensitivityLevel #

Four-level data sensitivity taxonomy used by the privacy-classifier route filter; numerically ordered.

  • jc:Public
  • jc:Internal
  • jc:Confidential
  • jc:Restricted
jc:Priority #

Assertion priority in a ValidationContract.

  • jc:MustHave
  • jc:ShouldHave
  • jc:NiceToHave
jc:CheckKind #

How an assertion's check is discharged.

  • jc:ToolCheck
  • jc:ArtifactCheck
  • jc:CommandCheck
  • jc:CheckerCheck
jc:CellState #

State of one cell in a ContractVerdict coverage matrix.

  • jc:Verified
  • jc:ClaimedUnverified
  • jc:Failed
  • jc:Unclaimed
  • jc:Gap

Properties

Every property in the JouleClaw data model. The JSON field is what appears in receipts on the wire today; the IRI is what a JSON-LD parser produces when the v1 context is in scope; the range is the typed shape the value MUST take.

IRI Range Definition
jc:schemaId xsd:string Schema id ("1", "policy/1", "verdict-receipt/1", "workspace/1", "contract/1", "verdict/1").
jc:receiptId xsd:string Stable receipt id (UUID v4 in production).
jc:closedAt xsd:dateTime Timestamp when the cascade walk or policy evaluation closed.
jc:createdAt xsd:dateTime Timestamp when an artefact was minted.
jc:inputHash xsd:string BLAKE3 hex of the normalised input that initiated a walk.
jc:contentHash xsd:string BLAKE3 hex of a content-addressed artefact.
jc:tier Cascade Which cascade tier closed the resolution.
jc:joulesMicrojoules xsd:nonNegativeInteger Joules spent (microjoules).
jc:energyProvenance Provenance Honesty tier of the worst counter seen.
jc:modelId xsd:string Stable identifier of the L3/L4 model invoked.
jc:steward AgentIdentity (@id) Receipt-emitting steward identity.
jc:agent AgentIdentity (@id) Acting agent identity.
jc:engineId xsd:string Policy-engine instance identifier.
jc:auditSequence xsd:nonNegativeInteger Monotonic sequence within an engine's audit log.
jc:policyVersion xsd:nonNegativeInteger Policy version under which the evaluation ran.
jc:action Action The action a policy was asked to evaluate.
jc:decision Decision The decision the engine returned.
jc:rule xsd:string Named rule that matched (Allow or ExplicitDeny).
jc:reason xsd:string Wire tag of a DenyReason.
jc:fsMode FsMode Filesystem access mode.
jc:netMethod NetMethod Network method.
jc:host xsd:string Network host.
jc:port xsd:nonNegativeInteger Network port.
jc:path xsd:string Filesystem or workspace path.
jc:binary xsd:string Process binary path.
jc:argv list of xsd:string Process arguments.
jc:owner AgentIdentity Workspace owner.
jc:entries list of WorkspaceEntry Workspace entry list (path-sorted).
jc:handle xsd:string (did:key) Canonical agent handle.
jc:publicKey xsd:string (hex) Ed25519 public key (32 bytes hex).
jc:size xsd:nonNegativeInteger Workspace entry byte size.
jc:toolsTouched list of ToolTouch Tools invoked during the walk.
jc:claims list of ClaimProvenance Retrieved claims that fed the resolution.
jc:citations list of Citation Span-level groundings.
jc:toolReceipts list of ToolReceipt HMAC-signed gateway attestations.
jc:tokenAttributions list of TokenAttribution Per-token attribution rows.
jc:toolId xsd:string Stable tool identifier.
jc:gatewayId xsd:string Stable gateway identifier.
jc:hmacSha256Hex xsd:string HMAC-SHA-256 over the canonical tool-receipt payload.
jc:source @id Source IRI of a retrieved claim.
jc:trustTier xsd:nonNegativeInteger Trust tier of a source (Wikipedia RSP-style).
jc:intent IntentVerdict Query-intent classification.
jc:classifierId xsd:string Stable classifier identifier.
jc:confidence xsd:double Confidence in [0, 1].
jc:label xsd:string Free-text label.
jc:eocStage xsd:string EOC-cascade stage tag.
jc:wireTag xsd:string Stable wire tag of a cascade tier ("L0"–"L4").
jc:authoredBy xsd:string (did:key) Agent or person who sealed a validation contract.
jc:assertions list of Assertion Contract assertions, in order; ids unique within the contract.
jc:features list of Feature Contract features, in order; each claims existing assertion ids.
jc:acceptance object Optional acceptance metadata controlling ship-gate rules.
jc:blockOnShouldHave xsd:boolean Block ship on should-have gaps.
jc:assertionId xsd:string Assertion stable id (e.g. "A-001").
jc:featureId xsd:string Feature stable id (e.g. "F-001").
jc:title xsd:string Title.
jc:rationale xsd:string Rationale (free-form why).
jc:description xsd:string Description.
jc:priority Priority Assertion priority.
jc:check AssertionCheck How an assertion is verified.
jc:contractHash xsd:string Contract content hash (hex BLAKE3).
jc:passed xsd:boolean Passed (ship gate).
jc:summary xsd:string Human-readable summary.
jc:coverage object Coverage matrix — one row per assertion, one column per feature, plus a per-assertion rollup.
jc:blockingGaps list of xsd:string Must-have assertion ids not rolled up to verified.
jc:shouldHaveGaps list of xsd:string Should-have assertion ids not rolled up to verified.
jc:worker xsd:string Stable worker id (typically did:key).
jc:completed list of xsd:string Items reported done.
jc:undone list of xsd:string Items reported left undone.
jc:issuesFound list of xsd:string Issues the worker discovered.
jc:proceduresFollowed list of xsd:string Skills / runbooks the worker applied.
jc:commands list of HandoffCommand Commands observed during the handoff window.
jc:commandHash xsd:string Command hash — hex BLAKE3 over argv joined with NUL.
jc:exitCode xsd:integer Exit code.
Versioning

A future major bump of the vocabulary publishes under /vocab/v2#. v1 IRIs remain resolvable forever — per the JouleClaw open-standard "names are final" rule.

Licence

CC-BY-4.0 (consistent with the JouleClaw specification text).