ixoworld · mintlify · Jul 16, 2026 · Jul 16, 2026
diff --git a/articles/claim-evaluation-protocol.mdx b/articles/claim-evaluation-protocol.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Claim evaluation protocol"
 description: "How Claims, evidence, rubrics, Agentic Oracles, and UDID records fit together in accountable IXO evaluation workflows."
 icon: "clipboard-check"
 ---

@@ -36,9 +36,9 @@

 ## Why this matters

 Claims often represent real-world work, identity, compliance, impact, delivery, or eligibility. Without a governed evaluation model, verification can drift into screenshots, emails, spreadsheets, ad hoc chat messages, and opaque expert judgment.

 Agentic Oracles can help with evidence review and decision support, but automation introduces its own risks:

 - the agent may act outside delegated authority
 - evidence may be incomplete, stale, or forged
@@ -55,7 +55,7 @@

 ## System model

 The evaluation pattern connects IXO Protocol, IXO Graph, Qi Intelligent Cooperating System, and Agentic Oracles.

 <Steps>
  <Step title="A Claim enters a governed context">
@@ -71,7 +71,7 @@
  </Step>

  <Step title="The rubric evaluates the facts">
    A governed rubric applies ordered checks, thresholds, disqualifiers, escalation rules, and reason codes to the typed facts. The rubric should be explicit, ordered, and reason-coded.
  </Step>

  <Step title="A UDID records the determination">
@@ -99,7 +99,7 @@
  </Accordion>

  <Accordion title="Agentic Oracle" icon="robot">
    An autonomous or semi-autonomous evaluator that operates with identity, scoped authority, permitted tools, and auditable output. An Agentic Oracle should not become the sole final authority for high-value or irreversible decisions. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
  </Accordion>

  <Accordion title="Evaluation kit" icon="toolbox">
@@ -107,7 +107,7 @@
  </Accordion>

  <Accordion title="Rubric" icon="table">
    The governed rulebook used to evaluate typed facts. A practical rubric defines required evidence, disqualifiers, thresholds, escalation rules, reason codes, and allowed outcomes. The rubric should be explicit, ordered, and reason-coded.
  </Accordion>

  <Accordion title="Fact ledger" icon="list-check">
@@ -141,7 +141,7 @@

  <Accordion title="Agentic Oracles" icon="robot">
    - **Owns:** Evidence review, fact production, rubric application, recommendations, and Evaluation Claims.
    - **Does not own:** Unbounded authority to approve, pay, issue credentials, or update high-value state. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
  </Accordion>

  <Accordion title="IXO Matrix" icon="comments">
@@ -163,7 +163,7 @@

 <CardGroup cols={2}>
  <Card title="Shared runtime artifacts" icon="gears">
    Claim loader, context resolver, evidence resolver, fact-ledger validator, rubric interpreter, trace store, UDID compiler, signing adapter, and human-review notifier.
  </Card>

  <Card title="Domain-specific kit artifacts" icon="boxes-stacked">
@@ -185,7 +185,7 @@

 The fact ledger is the bridge between messy evidence and repeatable decisions.

 Raw evidence can include PDFs, images, sensor logs, API responses, credentials, signatures, spreadsheets, Matrix events, and external attestations. A rubric should not need to know how each source was parsed. It should receive stable facts with provenance. The fact ledger should be deterministic, reproducible, and cryptographically signed.

 ```json
 {
@@ -290,7 +290,7 @@

 - Claim ID and Claim Collection
 - Claim subject and type
 - evaluator DID or service identity (the Agentic Oracle DID)
 - rubric ID and version (the rubric JSON file)
 - reason code (the reason code for the outcome)
 - evidence references or redacted evidence links (the evidence that was inspected)
@@ -304,11 +304,11 @@

 ## Safety rules

 Use these rules before allowing an Agentic Oracle to affect value, credentials, or state.

 <AccordionGroup>
  <Accordion title="Do not let an LLM directly approve a Claim" icon="triangle-exclamation">
    The model may extract, classify, summarize, or recommend. Approval should pass through governed rubric logic and the workflow authority model. The Agentic Oracle should be able to produce a deterministic, reproducible, and cryptographically signed UDID when a determination is made.
  </Accordion>

  <Accordion title="Do not treat a CID as authenticity proof" icon="link">
@@ -316,7 +316,7 @@
  </Accordion>

  <Accordion title="Do not let the evaluator change its own rubric" icon="lock">
    Rubric changes require proposal, review, versioning, and governance. Runtime optimization should not silently change thresholds, disqualifiers, or reason-code mappings. The rubric should be deterministic, reproducible, and reason-coded.
  </Accordion>

  <Accordion title="Do not commit high-value actions on ambiguous evidence" icon="hand">
@@ -340,7 +340,7 @@
 - one rubric (the rubric JSON file)
 - one evidence schema (the evidence schema JSON file)
 - one fact ledger schema (the fact ledger schema JSON file)
 - one Agentic Oracle or evaluator identity (the Agentic Oracle DID)
 - one human review path (the human review JSON file)
 - one dispute or correction path (the dispute or correction JSON file)
 - one test suite with approval, rejection, ambiguity, and adversarial cases (the test suite JSON file)
@@ -354,6 +354,10 @@
     Design Qi evaluation workflows with UCAN authority, Claims, evidence, rubrics, and UDID records.
   </Card>
 
+  <Card title="Verify UDID receipts" icon="stamp" href="/guides/dev/verify-udid-receipts">
+    Independently verify signed UDID determinations with the `@ixo/udid-verify` package.
+  </Card>
+
   <Card title="Claims management" icon="file-signature" href="/guides/dev/ixo-claims">
     Build Claim workflows while keeping protocol and service responsibilities separate.
   </Card>

diff --git a/docs.json b/docs.json
@@ -110,6 +110,7 @@
                 "pages": [
                   "guides/dev/ixo-claims",
                   "guides/dev/agent-evaluations",
+                  "guides/dev/verify-udid-receipts",
                   "guides/digital-mrv"
                 ]
               },

diff --git a/guides/dev/agent-evaluations.mdx b/guides/dev/agent-evaluations.mdx
@@ -79,7 +79,7 @@
  </Step>

  <Step title="The agent applies the rubric">
    The agent checks the Claim against required fields, evidence rules, protocol constraints, scoring thresholds, disqualifiers, and escalation rules.
  </Step>

  <Step title="The agent emits an Evaluation Claim">
@@ -114,7 +114,7 @@
    Defines where the evaluation happens and which transitions are allowed.
  </Accordion>
  <Accordion title="Rubric" icon="table">
    Defines the rules, scoring, thresholds, disqualifiers, and escalation conditions.
  </Accordion>
  <Accordion title="Evidence reference" icon="paperclip">
    Links the evaluation to documents, measurements, observations, attestations, media, reports, sensor records, or external records.
@@ -219,7 +219,7 @@
 Define:

 - issuer: the human, organization, POD, or service delegating authority
 - audience: the agent or Agentic Oracle DID receiving the authority
 - resource: the POD, Flow instance, Claim Collection, Claim, entity, evidence set, room, or tool
 - capabilities: the exact actions the agent may perform
 - constraints: limits on claim type, time, budget, tool use, output type, state transition, and approval power
@@ -457,7 +457,7 @@
    Claim being evaluated.
  </Accordion>
  <Accordion title="`evaluatorDid`" icon="robot">
    Agentic Oracle, agent, human, or service performing the evaluation.
  </Accordion>
  <Accordion title="`ucanProof`" icon="key">
    Proof that the evaluator had authority.
@@ -569,7 +569,7 @@
    Evaluations used.
  </Accordion>
  <Accordion title="`authority`" icon="key">
    UCANs, credentials, verifier role, or governance authority.
  </Accordion>
  <Accordion title="`rubric`" icon="table">
    Rubric and protocol version applied.
@@ -695,7 +695,7 @@
    Flow rejects previously authorized access.
  </Accordion>
  <Accordion title="Prompt injection in evidence" icon="bug">
    Agent treats evidence content as untrusted input.
  </Accordion>
  <Accordion title="Score below threshold" icon="arrow-trend-down">
    Agent does not recommend approval.
@@ -770,7 +770,7 @@
  </Accordion>

  <Accordion title="The rubric is too vague">
    Convert policy language into checks, thresholds, disqualifiers, and escalation rules. Ambiguity should route to human review.
  </Accordion>

  <Accordion title="The model output is treated as truth">
@@ -795,7 +795,7 @@
 - one Claim type
 - one Claim Collection
 - one Flow
 - one Agentic Oracle or agent DID
 - one UCAN delegation
 - one rubric
 - one Evaluation Claim schema
@@ -850,6 +850,10 @@
     Create, process, evaluate, dispute, and automate verifiable Claims.
   </Card>
 
+  <Card title="Verify UDID receipts" icon="stamp" href="/guides/dev/verify-udid-receipts">
+    Independently verify signed UDID determinations with the `@ixo/udid-verify` package.
+  </Card>
+
   <Card title="Model Context Protocol" icon="plug" href="/mcp/model-context-protocol">
     Connect agents to IXO services through secure, capability-scoped tool interfaces.
   </Card>

diff --git a/guides/dev/verify-udid-receipts.mdx b/guides/dev/verify-udid-receipts.mdx
@@ -0,0 +1,172 @@
+---
+title: "Verify UDID receipts"
+icon: "stamp"
+description: "Verify signed UDID receipts from the IXO Evals Engine end-to-end with the @ixo/udid-verify npm package: JWS signature, audience, canonical bytes."
+---
+
+Use this guide when a third party — a bridge, worker, oracle-to-oracle integration, or any external verifier — needs to check that a presented UDID receipt is authentic, addressed to them, unexpired, byte-canonical, and schema-valid, without running an IXO Evals Engine deployment.
+
+<Info>
+  The verification path described here is a standalone extract of the engine's own acceptance rule. Third-party verifiers run byte-identical code to the engine before it acts on a UDID, so a receipt that verifies for you would also verify for the engine.
+</Info>
+
+## What `@ixo/udid-verify` is
+
+`@ixo/udid-verify` is a publishable npm package (`Apache-2.0`) that verifies **UDID receipts** — the signed determinations issued by the [IXO Evals Engine](/articles/claim-evaluation-protocol) when a claim-evaluation workflow reaches a decision point.
+
+A UDID receipt is a compact JWS (`EdDSA` / Ed25519, algorithm-pinned) over the canonical JSON encoding of a determination payload (`iss`, `aud`, `sub`, `jti`, `act`, `res`, optional `out`). Verifying one correctly means more than checking the signature. The package ships:
+
+- `EdDSA`-pinned compact-JWS verification with `kid` selection.
+- A verification-only `VerifierKeyring` built from the public `GET /v1/issuer-keys` response (kids are recomputed from key bytes and rejected on mismatch — fail-closed).
+- Canonical-JSON helpers (deep key-sorted `canonicalJsonString`) and CID helpers (`cidV1RawSha256`, `cidV1RawSha256Utf8`).
+- Bundled copies of the normative UDID payload schemas.
+- `out` binding / consistency checks (the `out` narrative is descriptive only; `res` is the trusted decision surface).
+- `fetchIssuerKeys` and `parseIssuerKeysResponse` for issuer-key discovery.
+- A one-call `verifyUdidReceipt` that applies the engine's full acceptance rule and returns a list of named failures.
+
+## Who should use it
+
+Reach for `@ixo/udid-verify` when your service consumes UDID receipts but is **not** the engine that issued them.
+
+<AccordionGroup>
+  <Accordion title="Bridges and workers" icon="bridge">
+    An `ixo-bridge` or worker that gates on-chain submissions on a valid UDID should reject anything that fails the same acceptance rule as the engine.
+  </Accordion>
+  <Accordion title="Oracle-to-oracle trust" icon="robot">
+    An Agentic Oracle consuming another oracle's determination should verify the receipt end-to-end before treating `res` as trustworthy.
+  </Accordion>
+  <Accordion title="Third-party integrators" icon="plug">
+    Registries, dashboards, or downstream services that show or act on determinations should verify receipts locally so the decision surface can be inspected without trusting an intermediate transport.
+  </Accordion>
+</AccordionGroup>
+
+If you are building an engine deployment that signs UDIDs, use the engine's internal `udid-validator` package instead — it keeps the issuer-side helpers (secret-to-key derivation, signing `IssuerKeyring`) and delegates verification to `@ixo/udid-verify` so both sides run identical code.
+
+## Install
+
+```sh
+npm install @ixo/udid-verify
+```
+
+Requires Node.js 20.10 or newer.
+
+## One-call verification
+
+For the common case — you have a compact JWS and know the engine that issued it — pass the engine's base URL and the audience the receipt must be addressed to:
+
+```ts
+import { verifyUdidReceipt } from "@ixo/udid-verify";
+
+const { valid, failures, report } = await verifyUdidReceipt(compactJws, {
+  expectedAud: "did:ixo:my-oracle",
+  issuerKeys: "https://evals.example.org",
+});
+
+if (!valid) {
+  throw new Error(`receipt rejected: ${failures.join(", ")}`);
+}
+
+// report.payload.res is the trusted decision surface (outcome, patch, reason).
+const decision = report.payload.res;
+```
+
+`verifyUdidReceipt` resolves the issuer's public keys from `GET /v1/issuer-keys` on the supplied base URL, verifies the compact JWS with `kid`-selected key material, and applies the engine's full acceptance rule. Canonical-byte enforcement is always on: a receipt whose signed bytes are not the canonical encoding of its payload is not a UDID the engine issued.
+
+## Bring your own keys
+
+If the keys are pinned, cached, or resolved out-of-band, pass a raw published-keys array or a pre-built `VerifierKeyring`:
+
+```ts
+import { VerifierKeyring, verifyUdidJws, verificationReportFailures } from "@ixo/udid-verify";
+
+const keyring = VerifierKeyring.fromPublishedKeys(publishedKeys); // the `keys` array
+const report = await verifyUdidJws(compactJws, keyring, {
+  expectedAud: "did:ixo:my-oracle",
+  enforceCanonicalBytes: true,
+});
+
+const failures = verificationReportFailures(report);
+if (failures.length > 0) throw new Error(`receipt rejected: ${failures.join(", ")}`);
+```
+
+`VerifierKeyring.fromPublishedKeys` holds no private material. It maps each JWS header `kid` to an Ed25519 public `KeyObject`, so historically issued UDIDs keep verifying across signing-key rotations. Every listed key is checked: `kid` is recomputed from the raw public key bytes and a mismatch is rejected. An unknown or missing `kid` fails closed as `unknown_kid`.
+
+## Fetch issuer keys manually
+
+If you want to cache the response, share it across verifications, or apply custom TLS or retry behavior, use `fetchIssuerKeys` (or `parseIssuerKeysResponse` when you already have the body):
+
+```ts
+import { fetchIssuerKeys, parseIssuerKeysResponse } from "@ixo/udid-verify";
+
+// Fetch from the engine's base URL.
+const keyring = await fetchIssuerKeys("https://evals.example.org", {
+  signal: controller.signal,
+});
+
+// Or parse a body you already have.
+const cached = parseIssuerKeysResponse(await response.json());
+```
+
+The `GET /v1/issuer-keys` route needs no auth token and is cacheable (`cache-control: public, max-age=300`). Your trust root is the TLS connection to the deployment you already trust to have evaluated the claim. Pin the keys if you need to remove that runtime dependency.
+
+## The acceptance rule
+
+Only trust `report.payload` after **every** check passes. `verificationReportFailures(report)` returns an empty array exactly when the receipt is trustworthy — the same acceptance rule the engine applies before submitting a determination on-chain, and the same one bridges and workers should apply before acting.
+
+The named failures mirror the engine's own gates:
+
+| Failure code | Meaning |
+| --- | --- |
+| `signature_invalid` | The compact JWS signature did not verify with the resolved `kid`. |
+| `audience_mismatch` | `payload.aud` is missing, malformed, or does not match `expectedAud`. |
+| `replay_rejected` | A supplied `replayCheck` reported the `jti` as already seen for this audience. |
+| `expired` | `payload.exp` is in the past (with optional `clockSkewSec`). |
+| `canonical_bytes_mismatch` | Signed bytes are not the deep-key-sorted canonical JSON encoding of the payload. |
+| `payload_schema_invalid` | Payload failed validation against the bundled UDID schemas. |
+| `missing_payload_after_verify` | Payload could not be parsed as a JSON object after signature verification. |
+
+Additional low-level errors — for example `unknown_kid` when the JWS header refers to a `kid` not in the keyring — surface on `report.errors`.
+
+<Warning>
+  Do not gate downstream actions on the JWS signature alone. A receipt with a valid signature but a mismatched audience or a non-canonical payload is not a UDID the engine would act on, and it is not one your service should either.
+</Warning>
+
+## `out` is descriptive, `res` is the decision surface
+
+The optional `out` block in a UDID payload is a human-readable narrative. It should not be treated as the trusted decision. The package exposes helpers to check that `out` stays consistent with `res` — for example, that a summary does not contradict the outcome or claim settlement authority it does not have:
+
+```ts
+import { checkOutConsistency, outIsDescriptiveOnlyNotSettlement } from "@ixo/udid-verify";
+
+const consistency = checkOutConsistency(report.payload);
+if (!consistency.ok) {
+  // Bindings resolve, but `out` conflicts with `res`.
+}
+```
+
+When you extract trusted decision data from a verified receipt, read it from `report.payload.res` — never from `out`.
+
+## Also included
+
+- `canonicalJsonString` / `sortKeysDeep` — the signing canonicalization.
+- `cidV1RawSha256` / `cidV1RawSha256Utf8` — the engine's content-proof convention (CIDv1, `raw` codec, sha2-256, base32) for traces, evidence, and rubric bindings.
+- `validateUdidPayloadSchema` — standalone payload schema validation.
+- `verificationReportMatchesCompactJws` — bind a verification report back to the exact compact bytes it was produced from.
+- `issuerKid` / `issuerPublicKeyFromRaw` — recompute a `kid` from raw Ed25519 public key bytes.
+
+## Related docs
+
+<CardGroup cols={2}>
+  <Card title="Claim evaluation protocol" icon="clipboard-check" href="/articles/claim-evaluation-protocol">
+    The architecture behind Claims, evidence, rubrics, and UDID determinations.
+  </Card>
+  <Card title="Agent evaluations" icon="clipboard-list" href="/guides/dev/agent-evaluations">
+    Design Qi evaluation workflows that issue UDID records.
+  </Card>
+  <Card title="Agentic Oracles" icon="robot" href="/articles/agentic-oracles">
+    Learn how oracle services fit into the IXO stack.
+  </Card>
+  <Card title="Claims management" icon="file-signature" href="/guides/dev/ixo-claims">
+    Build Claim workflows and record evaluations.
+  </Card>
+</CardGroup>