open-standards/jouleclaw/jouleclaw-rs/crates/jouleclaw-jcr1/docs/JCR-1-v1.1-intent.md

JCR-1 v1.1 — Proposal: query-intent in the signed core

Status: Proposal (draft). Target: Additive bump of JCR-1, jc_receipt: "1" → optional intent field MAY appear in the signed core. v1.0 verifiers ignore it (per §8 additive evolution).

---

1. Why

Priscilla (Sentry) ran 116 of her own Claude sessions through a post-hoc classifier and found 67% comprehension / 2% generation — the rest split across modification / process / review / other. The finding generalises: every workload that uses an LLM-shaped runtime distributes across the same six categories, and the comprehension slice is consistently dominant.

JouleClaw already classifies queries at runtime (jouleclaw-intent::HeuristicClassifier + the LlmFallbackClassifier seam) and tags Receipt.intent on the way to the ledger (jouleclaw-ledger::CostSummary::by_intent). What's missing for a deployment to reproduce Priscilla's analysis on its OWN signed receipts is: the intent verdict needs to sit inside the signed core so it survives across third-party audit. An external grader can then run

"prove to me that ≥60% of your Receipt records carried intent=comprehension and a tier in {L0, L0.x, L1, L2}, signed by the steward I trust."

without trusting the runtime's separate dashboard.

This proposal pins how the intent verdict is canonicalised so the audit is mechanical, not interpretive.

---

2. What's added

One optional top-level field on the JCR-1 receipt:

intent: { intent: enum, classifier_id: string }     // OPTIONAL

2.1 intent.intent — taxonomy (frozen for v1.x)

A stable string enum mirroring jouleclaw_intent::QueryIntent:

Wire form	Meaning	Verifiable-zone?
comprehension	Reading / understanding existing code or state	yes
generation	Producing new artefacts	no
modification	Editing existing artefacts in place	partial
process	Operational / workflow tasks	partial
review	Reviewing a candidate artefact	yes
other	Unclear / refused	n/a

Names are snake_case text strings — not small-int enums — so the det-CBOR form stays human-inspectable and matches the Rust #[serde(rename_all = "snake_case")] already shipping.

2.2 intent.classifier_id — provenance for drift

A stable string identifying the classifier that produced the verdict ("heuristic:v1", "llm:claude-haiku-4-5", "override:operator", …). Required when intent is present.

A receipt grader that sees a dashboard shift from 67% → 50% comprehension over a week needs to know whether the workload moved or the classifier got changed. The classifier_id is that signal. The grader correlates the shift against a classifier_id change in the audit log; if it tracks, the workload didn't change.

2.3 What is NOT added

• confidence is intentionally excluded. IntentVerdict.confidence is a f64; JCR-1 §3.1 already excludes floats from the signed core because they're not reproducible across encoders, and confidence is classifier-specific (no shared scale). Confidence stays on the full Receipt JSON outside the signed core, alongside token_attributions.
• No new intent_categories map or sub-types. The six-variant taxonomy is the wire form. Subdivisions are caller-side concerns.

---

3. Canonical encoding

The intent field, when present, is a 2-entry CBOR map under the top- level receipt map. Both subfields are required when intent is present (omitting either is a structural violation).

Order under RFC 8949 §4.2.1 (length-first then bytewise) places the keys as:

intent (6) → comes between "claims" (6) and "tier" (4)? No — length-first.
  4-byte keys:  tier
  6-byte keys:  claims, intent, ...

"intent" and "claims" both have length 6; bytewise: c (0x63) < i (0x69), so claims comes before intent. The inner map {intent, classifier_id} sorts to intent (6) before classifier_id (13) by length.

Wire example (canonical CBOR, hex):

A2                              # map(2)
   66 69 6E 74 65 6E 74          # text(6) "intent"
   6D 63 6F 6D 70 72 65 68 65    # text(13) "comprehension"
   65 6E 73 69 6F 6E
   6D 63 6C 61 73 73 69 66 69    # text(13) "classifier_id"
   65 72 5F 69 64
   6C 68 65 75 72 69 73 74 69    # text(12) "heuristic:v1"
   63 3A 76 31

(Hand-wrapped above; an encoder MUST sort the inner map's keys length-first → intent before classifier_id.)

---

4. Verification flow change

JCR-1 §6 gains one optional step between step 4 (tool HMACs) and step 5 (honesty consistency):

4.5 — Intent structural. If intent is present, both intent.intent and intent.classifier_id MUST be present; intent.intent MUST be one of the six taxonomy values. Unknown intent values are rejected (the spec is #[non_exhaustive] at the Rust level but the wire enum is frozen for v1.x).

The drift bands of §7.1 are unchanged — intent doesn't enter joule re-validation.

---

5. Backward-compatibility

• v1.0 verifiers: per §8 ("Unknown fields MUST be ignored, never rejected"), v1.0 verifiers see the extra intent field and skip it. The 10 canonical vectors continue to verify under v1.0 verifiers.
• v1.1 receipts produced without intent are valid v1.0 receipts.
• The canonical CBOR re-encode test continues to pass byte-for-byte — intent just adds a new (key, value) pair to the map, with its position determined by RFC 8949 §4.2.1.

This is an additive change. jc_receipt stays "1".

---

6. Conformance vectors

A v1.1-ratifying conformance suite SHOULD add three vectors on top of the existing ten:

11. L0 cache hit + intent=comprehension — verifies the canonical map order with intent present and no tools_touched.
12. L3 model + intent=generation + ModelBased — verifies intent coexists with tools_touched and ModelBased honesty floor.
13. Promoted skill (collapses V5) + intent=comprehension — the Priscilla 67% case: comprehension intent now resolves at L1.

A v1.1 verifier that round-trips vectors 1–13 byte-identically is v1.1 vector-conformant.

---

7. Why not add model_id too?

model_id (also a wave-8 Receipt field) is a candidate but raises distinct questions JCR-1 v1.1 deliberately defers:

• Where does model_id resolve? KERI AID? OCI subject digest? A registry the spec has to pin? A stable identifier scheme is a wider call than adding the intent taxonomy.
• Per-receipt model_id overlaps with the wave-6 jouleclaw-oci + jouleclaw-slsa provenance chain — those already pin the model binary's identity via in-toto Statement subject + ORAS referrer. Carrying it on the cascade receipt may duplicate that surface.

A separate v1.2 proposal (or a sidecar binding) would resolve model_id once the wider model-identity question is settled.

---

8. Implementation in jouleclaw-jcr1

The Rust reference (this crate) implements v1.1 behind an opt-in constructor. The current to_jcr1_wire projection drops intent (v1.0 behaviour). When v1.1 ratifies:

// proposed v1.1 surface
pub fn to_jcr1_wire_v1_1(receipt: &Receipt) -> Result<Value, JcrError>;
pub fn canonical_signed_core_v1_1(receipt: &Receipt) -> Result<Vec<u8>, JcrError>;

Both paths share the canonical CBOR encoder; v1.1 just stops dropping intent during the projection. Roughly five additional lines of code plus three vectors.