@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/skills/create-rubric/reference/format-cheatsheet.md

@@ -0,0 +1,186 @@
+# Rubric format cheatsheet
+
+Condensed from the engine's own spec, and never the authority: **the engine's `GET /v1/rubric-schema`
+is what parses, and `bunx decision-oracle rubric validate` binds a draft against the real form.** Where
+this page and the engine disagree, the engine wins — validate, don't argue. Older prose about the
+format still shows `constants` / `@const` refs; those do not exist (inline literals, or use
+`derived`).
+
+## Envelope + top level
+
+```jsonc
+{
+  "@context": { "ixo": "https://w3id.org/ixo/ns/protocol/", "@id": "@type", "type": "@type", "@protected": true },
+  "type": "ixo:entity#rubric",
+  "rubric": {
+    "@type": "Rubric",
+    "title": "…", "description": "…",                        // display-only
+    "claimSchema": { "@type": "ClaimSchemaBinding", "protocol": "did:ixo:entity:…", "resource": "#vct",
+                     "proof": "<the protocol's #vct LinkedResource proof, VERBATIM — a CID, compared as a string>" },
+    "derived":   [ … ],   "gates": [ … ],   "scoring": { … },   "review": { … },   "settlement": { … },
+    "sources":   [ … ],   "aiChecks": [ … ],   "unique": { … },   "frequency": { … }
+  }
+}
+```
+
+Required: envelope keys, `@type`, `claimSchema`, and at least one of `gates` / `scoring`. Everything else optional.
+**Unknown keys anywhere = schema error.** The rubric's id is `sha256(raw file bytes)`.
+
+## Field refs and kinds
+
+`$name` a top-level answer · `$ixo:name` namespaced · `$q.row.col` matrixdropdown cell · `$rows[*].col` a column over
+repeating rows · `$q.key` multipletext · `.col` row-relative (inside `forEach` only) · `~name` derived · `ctx.now`,
+`ctx.collection.startDate|endDate`, `ctx.claim.submitter|submissionDate` · `ext.<source>.<field>` · `ai.<check>.valid|reason`.
+
+| SurveyJS question | kind | notes |
+| --- | --- | --- |
+| `text` (default/email/url/tel), `comment` | text | |
+| `text` `inputType:"number"`, `rating`, `slider` | number | |
+| `text` `inputType:"date"` / `"datetime-local"` | date | ISO string |
+| `dropdown`, `radiogroup`, `imagepicker` | choice | rules compare against choice `value`, not `text` |
+| `checkbox`, `tagbox`, `ranking` | multichoice | string[] |
+| `boolean` | boolean | |
+| `file` | file | `[{name,type,content}]` — content is human-only |
+| `signaturepad` | signature | human-only |
+| `matrix` / `matrixdropdown` / `matrixdynamic`, `paneldynamic` / `multipletext` | keyed choice / cells / rows / keyed text | |
+| `html`, `expression` | — | not submitter input; cannot be referenced |
+
+A string literal that starts with `$ @ ~` or `ctx.` must be written `{"@value": "…"}`.
+
+## Operators by kind
+
+| kinds | operators |
+| --- | --- |
+| all | `present`, `empty` |
+| text, number, date, choice, boolean | `==`, `!=` |
+| number, date | `>` `>=` `<` `<=`, `between` `[min,max]` |
+| number | `approx` (+ `tolerance`) |
+| text, number, choice | `in`, `notIn` (array) |
+| text | `matches` (safe regex), `startsWith`, `endsWith` (literal only), `lengthBetween` |
+| multichoice | `contains`, `containsAll`, `containsAny`, `subsetOf`, `countBetween` |
+| multichoice, rows | `countBetween` |
+| boolean | `isTrue`, `isFalse` |
+| date | `before`, `after` (literal, `$field`, `ctx.*`), `withinWindow` (collection period), `withinDays` (n vs `ctx.now`), `notInFuture` |
+| file, signature | `mediaTypeIn` (MIME globs), `maxSizeMB` |
+| geo | `withinBoundary`, `withinRadius` |
+
+Any `value` may be a `$field` of a compatible kind (cross-field checks), except `startsWith`/`endsWith`.
+
+## Conditions (the one composable node)
+
+```jsonc
+{ "@type": "Condition", "field": "$clinicId", "op": "in", "value": ["CL-A", "CL-B"] }
+{ "@type": "Condition", "all": [ … ] }   { "@type": "Condition", "any": [ … ] }
+{ "@type": "Condition", "not": { … } }   { "@type": "Condition", "atLeast": 2, "of": [ … ] }
+{ "@type": "Condition", "forEach": "$readings", "every": { "@type": "Condition", "field": ".celsius", "op": "between", "value": [2, 8] } }
+```
+
+**Null rule:** a missing answer makes `present` false, `empty` true, and every other operator **false** — never an
+error. "Optional, but valid if given" = `appliesWhen: {field, op: "present"}` on the gate/criterion.
+
+## Gates — must-pass, in document order, first failure terminates
+
+```jsonc
+{ "@type": "Gate", "code": "MED-201-CLINIC", "reason": "Not one of our clinics",
+  "appliesWhen": { … optional … },
+  "when": { "@type": "Condition", "field": "$clinicId", "op": "in", "value": ["CL-A", "CL-B", "CL-C"] },
+  "onFail": "reject",                 // "reject" (default) | "review"
+  "class": "out_of_authority" }       // reject: refuted | invalid_evidence | out_of_authority · review: insufficient_evidence | requires_human_review
+```
+
+Codes: `^[A-Z0-9]+-[0-9]+-[A-Z0-9-]+$`, unique per rubric. `reason` is what the claimant reads — write it like a human.
+
+## Scoring
+
+```jsonc
+"scoring": { "@type": "Scoring", "method": "weighted_average",   // | all_pass | minimum | quorum (+ "quorum": {need, of})
+  "approveAt": 7000, "partialFloor": 4000, "reviewFloor": 4000,  // bps; approveAt > partialFloor ≥ reviewFloor
+  "criteria": [
+    { "@type": "Criterion", "code": "MED-301-QTY", "reason": "Units delivered vs target",
+      "weight": 3,                       // 1..5, read ONLY under weighted_average
+      "critical": true, "min": 2500,     // optional: below min ⇒ reject on its own
+      "appliesWhen": { … }, "requireSource": "server_verified", "trustCap": 8000,   // all optional
+      "score": { … exactly one node … } } ] }
+```
+
+The 7 score nodes (all points in bps 0–10000):
+
+```jsonc
+{ "@type": "BooleanScore", "when": { … }, "onTrue": 10000, "onFalse": 0 }
+{ "@type": "BandsScore", "value": "$score", "bands": [ { "op": ">=", "value": 90, "points": 10000 }, { "else": true, "points": 0 } ] }
+{ "@type": "LinearScore", "value": "$quantity", "zeroAt": 0, "fullAt": 200, "clamp": true }      // anchors may be numbers or ~derived
+{ "@type": "LevelsScore", "levels": [ { "name": "ok", "when": { … }, "points": 10000 }, { "name": "bad", "else": true, "points": 0 } ] }
+{ "@type": "MapScore", "value": "$rating", "map": { "low": 10000, "high": 0 }, "default": 0 }
+{ "@type": "DeductionsScore", "start": 10000, "floor": 0, "deduct": [ { "when": { … }, "points": 2000, "code": "MED-311-LATE" } ] }
+{ "@type": "ManualScore", "field": "$deliveryPhoto", "whenMissing": 0, "reviewTask": "MED-RT-PHOTO" }
+```
+
+`ManualScore`: a human scores it, but ONLY when the field is present; missing ⇒ `whenMissing`, nobody is asked. **File
+content is never machine-judged** — anything about what a photo/document shows is `ManualScore` + a `ReviewTask`.
+
+Decision order: gates → any critical criterion below `min` ⇒ reject → total vs thresholds → pending manual
+tasks downgrade approve/partial to review → verdict → action.
+
+## Human review
+
+```jsonc
+"review": { "@type": "HumanReview",
+  "assignTo": { "role": "reviewer" },                 // add "assigneeDid": "did:…" to name ONE person
+  "route": { "matrixRoom": "!room:server" },          // optional: a REAL Matrix room id/alias
+  "slaHours": 48, "onTimeout": "reject",              // fail closed
+  "tasks": [ { "@type": "ReviewTask", "id": "MED-RT-PHOTO", "forCriterion": "MED-401-PHOTO",
+               "prompt": "Does the photo clearly show the supplies at the clinic?",
+               "show": ["$deliveryPhoto", "$clinicId", "$deliveryDate"],
+               "answer": { "type": "boolean" },        // | { "type": "enum", "options": [ … ] } — nothing else
+               "map": { "true": "approve", "false": "reject" } } ] }   // EVERY possible answer mapped
+```
+
+## Derived values
+
+```jsonc
+{ "@type": "Derived", "name": "deliveredPct", "expr": "clamp($quantity / 200, 0, 1)" }
+```
+
+Grammar: `+ - * /`, numbers, `$refs`, `~earlier`, `ctx.*`, calls from `min max clamp abs floor ceil round sum avg count
+countWhere daysBetween hoursBetween yearsBetween distanceMeters length`. `countWhere($rows[*].col, "==", "SKU_1")` is the
+only place a string/boolean literal is legal. Division by zero ⇒ null.
+
+## Settlement
+
+```jsonc
+"settlement": { "@type": "Settlement", "onApprove": { "pay": "approval" },
+                "onPartial": { "pay": "approval", "prorateBy": "~deliveredPct" } }   // | "total" | "none"
+```
+
+Proration exists on **partial** only; a full approve pays in full. Whether anything moves on chain is the
+collection's setting, never the rubric's.
+
+## External sources and AI checks (facts the ORACLE produces; the manifest tells it to)
+
+```jsonc
+"sources": [ { "@type": "ExternalSource", "name": "batchCheck", "endpoint": "https://verify.example/batch",
+  "audience": "did:web:verify.example",                               // MUST be did:web:<endpoint host>
+  "send": { "batch": "$batchNumber" }, "expect": "boolean",        // | "score"
+  "provenance": "attested", "onError": "review", "timeoutMs": 5000 } ]     // referenced as ext.batchCheck.valid
+"aiChecks": [ { "@type": "AiCheck", "name": "photoLooksReal", "send": { "photo": "$deliveryPhoto" },
+  "instructions": ["Shows medical supplies inside a clinic", "Is not a stock image"],
+  "expect": "boolean", "onError": "review" } ]                       // referenced as ai.photoLooksReal.valid
+```
+
+No secrets in a rubric (it is public). `send` carries declared refs only, never the whole claim.
+`audience` must be the endpoint's own did:web (`did:web:<host>`, a port as `%3A<port>`) or no
+oracle's stock lane calls the source. Leave `capability` out: the schema accepts it, but an oracle
+ignores it — what an oracle's key grants is its developer's choice, never the protocol's.
+
+## Duplicate and rate rules (declared here, detected by the oracle)
+
+```jsonc
+"unique":    { "@type": "Unique", "id": "MED-DUP-1", "by": ["$clinicId", { "ref": "$deliveryDate", "granularity": "day" }],
+               "countPrior": ["approved", "pending_review", "queued"], "attachments": true,
+               "ai": { "enabled": true, "maxPairs": 3 }, "thresholds": { "rejectAtBps": 9000, "reviewAtBps": 5000 } }
+"frequency": { "@type": "Frequency", "id": "MED-FREQ-1", "max": 5, "per": "day", "onBreach": "reject" }   // per: day|week|month|year; onBreach defaults to reject, and a breach is a FINAL REJECT whichever it says (schema.ts Frequency.onBreach)
+```
+
+`id` is any non-empty string (a code-style id is a convention, not the gate/criterion pattern). `by` absent ⇒ the
+whole canonical claim body is the identity. Every `unique` field but `id` has a default; a
+`frequency` needs `max` + `per`. Both surface to the oracle through the manifest with defaults applied.

package/skills/create-rubric/templates/claim-form.example.json

@@ -0,0 +1,60 @@
+{
+  "@context": {
+    "ixo": "https://w3id.org/ixo/ns/protocol/",
+    "@id": "@type",
+    "type": "@type",
+    "@protected": true
+  },
+  "type": "ixo:entity#surveyTemplate",
+  "question": {
+    "pages": [
+      {
+        "name": "delivery",
+        "elements": [
+          {
+            "type": "dropdown",
+            "name": "clinicId",
+            "title": "Clinic",
+            "isRequired": true,
+            "choices": [
+              { "value": "CL-A", "text": "Clinic A" },
+              { "value": "CL-B", "text": "Clinic B" },
+              { "value": "CL-C", "text": "Clinic C" }
+            ]
+          },
+          {
+            "type": "text",
+            "inputType": "datetime-local",
+            "name": "deliveryDate",
+            "title": "Delivery date",
+            "isRequired": true
+          },
+          {
+            "type": "text",
+            "inputType": "number",
+            "name": "quantity",
+            "title": "Units delivered",
+            "isRequired": true
+          },
+          {
+            "type": "file",
+            "name": "deliveryPhoto",
+            "title": "Delivery photo",
+            "acceptedTypes": "image/*"
+          },
+          {
+            "type": "file",
+            "name": "deliveryNote",
+            "title": "Signed delivery note",
+            "acceptedTypes": "application/pdf,image/*"
+          },
+          {
+            "type": "comment",
+            "name": "notes",
+            "title": "Notes"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/decision-api-client/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: decision-api-client
+description: Use when testing a Decision API oracle from the CUSTOMER side — minting a test source, API key and payment delegation on devnet, running the TypeScript SDK (@ixo/decision-oracle-client) or its CLI against a live oracle, connecting Claude Code to an oracle's hosted MCP server (/v1/mcp), running the docs agent test — or when debugging a client-side failure (402 not paid, SCOPE, DELEGATION_EXPIRED, terms_mismatch, a receipt that will not verify).
+---
+
+# The Decision API from the customer side, on devnet
+
+## Overview
+
+A Decision API oracle (`API_LANE` on; set one up with `decision-api-oracle`) is used by customers
+through three doors, all over the same `/v1/api` routes with an API key:
+
+- the SDK and CLI, `@ixo/decision-oracle-client` (`packages/client` in this repo);
+- the hosted MCP server at `https://<oracle>/v1/mcp` (four tools, the same key, or a sign-in
+  through AuthHub with an approval per submit);
+- plain HTTP, with the docs (`site`, and its `llms-full.txt` for agents).
+
+A source in billing mode `x402` answers a submit with `402`. The payer pays it with the
+customer's **payment delegation**, a UCAN to the facilitator carrying a `billing/pay` cap. The
+price is held when the claim is accepted and paid only on the engine's receipt.
+
+The worked target is IXO's devnet example: SwiftDrop, at `https://shipment-delivery-oracle.devnet.ixo.earth`,
+protocol `did:ixo:entity:c2f5a188d28f3d4bf6351873d3d268ea`, price 20¢. Its `/demo/orders?route=<id>`
+issues a fresh courier route per id, with real order ids and delivery codes. Use a new route per
+test claim, so the duplicate lane never sees a repeat.
+
+**Core principle: run it, don't recite it.** Every step below is an action you perform. A test
+claim spends real devnet PAY from the session's deed, so say how many claims you will send before
+sending them.
+
+## When to use
+
+- "Test the SDK / CLI / MCP against devnet", "does the paid flow still work", "mint a test key".
+- Before a client release, or after a facilitator or engine change the payer depends on.
+- Any symptom in the table at the end.
+
+Not for: standing up or deploying the oracle (`decision-api-oracle`), or the chain lane
+(`create-collection`).
+
+## The run: in order
+
+### 0. The session
+
+```bash
+bunx decision-oracle login --network devnet     # once; a browser step for the human (HUMAN)
+```
+
+The session's DID must be in the oracle's `ORACLE_ADMIN_DIDS` to set a source's billing mode and
+protocols. For IXO's example it already is. Its deed needs devnet PAY; top up in the console
+(`decision-console.devnet.ixo.earth`, Credits).
+
+### 1. Credentials: a source, two keys and a delegation
+
+**In this repo** (one command; secrets are written to the file with mode 600 and never printed):
+
+```bash
+cd packages/client
+bun run devnet:credentials -- --oracle https://shipment-delivery-oracle.devnet.ixo.earth \
+  --protocol did:ixo:entity:c2f5a188d28f3d4bf6351873d3d268ea --out ~/.ixo/decision-api-devnet.env
+#   --source src_…      reuse an existing source; --max-pay 2 (PAY); --days 7
+```
+
+It writes `IXO_ORACLE_URL`, `IXO_PROTOCOL_DID`, `IXO_SOURCE_ID`, `IXO_API_KEY` (claims:write,
+claims:read, webhooks:manage), `IXO_API_KEY_READONLY` (claims:read) and `IXO_PAYMENT_DELEGATION`.
+
+**Anywhere else:**
+
+```bash
+eo() { bunx decision-oracle "$@" --kit https://<oracle> --network devnet --json; }
+eo api source create --name <n> --contact <email>        # sourceId + webhookSecret, shown once
+eo api admin billing-mode <sourceId> x402 --yes          # operator only
+eo api admin protocols <sourceId> <protocolDid> --yes    # operator only
+eo api key create --source <sourceId> --scopes claims:write,claims:read --name test
+```
+
+For the delegation, use the console's Keys page ("Payment delegation"), which shows
+`IXO_PAYMENT_DELEGATION` once.
+
+Revoke keys you no longer need: `eo api key revoke --source <id> <8-char prefix> --yes`.
+
+### 2. The SDK smoke (this repo)
+
+```bash
+cd packages/client && bun run build && node dev/devnet-smoke.ts   # --env <file> --photo <jpg>
+```
+
+It runs under plain node, through the BUILT dist. That is what a customer installs. It checks:
+
+- the work order and its price;
+- an upload;
+- a paid submit: a 402, then `PAYMENT-SIGNATURE`, then one resend, with `PAYMENT-RESPONSE` naming the settlement;
+- a decision, and a payment on the record;
+- `verifyReceipt` against the engine's did.json;
+- events;
+- a replay with the same key naming the same claim;
+- `SCOPE` for the read-only key;
+- the CLI reading the claim.
+
+It spends one claim. Every line must read `PASS`. Any verdict counts (`reject` is normal for a
+parcel photo that doesn't match).
+
+### 3. The CLI by hand
+
+```bash
+set -a; . ~/.ixo/decision-api-devnet.env; set +a
+node packages/client/dist/cli/index.js submit claim.json      # waits up to 60 s; pays the 402
+node packages/client/dist/cli/index.js watch apc_…            # the timeline to the decision
+node packages/client/dist/cli/index.js keys                   # the source's keys, masked
+```
+
+Outside this repo: `npx @ixo/decision-oracle-client …` (once published).
+
+### 4. MCP from Claude Code
+
+The route ships with the oracle package, so the oracle must be deployed from a version that has
+`src/routes/v1/mcp`. Check with `curl -s -o /dev/null -w "%{http_code}" -X POST https://<oracle>/v1/mcp`:
+`401` means it is there and wants a key; `404` means it is not deployed.
+
+```bash
+claude mcp add --transport http ixo-devnet https://<oracle>/v1/mcp \
+  --header "Authorization: Bearer $IXO_API_KEY" \
+  --header "X-Payment-Delegation: $IXO_PAYMENT_DELEGATION"
+```
+
+In a Claude Code session, ask it to:
+
+1. list the protocols;
+2. read SwiftDrop's work order (`list_protocols` with the DID);
+3. submit a claim built from a fresh `/demo/orders?route=…` order;
+4. get the decision;
+5. verify its receipt.
+
+All four tools must answer. Refusals come back as `isError` results with a `code`. With the
+read-only key, `submit_claim` must be `SCOPE`. Remove the server afterwards with
+`claude mcp remove ixo-devnet`.
+
+**Signing in instead of a key (OAuth).** Add the server with the URL alone, then run `/mcp` in
+Claude Code and choose *Authenticate*: the browser opens AuthHub (devnet: `dev.auth.ixo.earth`).
+Sign in with the account that owns the test source and allow the app. The oracle's discovery
+document must name AuthHub:
+`curl -s https://<oracle>/.well-known/oauth-protected-resource/v1/mcp` → `authorization_servers`.
+
+```bash
+claude mcp add --transport http ixo-oauth https://<oracle>/v1/mcp
+```
+
+Then ask for a submit. The first `submit_claim` must come back `APPROVAL_REQUIRED` with an
+`approveUrl` — as a normal result, `status: "approval_required"` (not `isError`), its text starting
+`NOT SUBMITTED.`; in Claude desktop it shows as a card with *Approve on IXO*. Open it, check the oracle, protocol and price, and click *Approve*. Ask the AI to call
+`submit_claim` again with the same arguments: it must pay once and return the decision. A second
+call before you approve must be `APPROVAL_PENDING`, and a changed body must be a new approval. An
+account with several sources gets `SOURCE_REQUIRED` (pass `sourceId`); one with none gets
+`NO_SOURCE`. Revoke the app on AuthHub's *Connected apps* page afterwards.
+
+**Auto-approve.** On the approve page, tick "Don't ask again" (verified apps only) with small limits.
+The next claim within them must come back with `autoApproved: true` and `autoApproveRemaining`, and
+no link; one above the per-claim limit must be `APPROVAL_REQUIRED`. Turning it off on AuthHub (or in
+the console) must make the next claim ask again. "Don't ask again" works only on an oracle whose
+`policies.allowStandingApprovals` is `true`; otherwise setting it is refused (`403`, reason
+`standing_approvals_off`) and every claim asks.
+
+### 5. The docs agent test (this repo)
+
+```bash
+(cd site && bun install && bun run build)
+set -a; . ~/.ixo/decision-api-devnet.env; set +a
+bun site/agent-test/run.ts            # exit 0 pass · 1 fail · 2 skipped (no credentials)
+```
+
+A Claude model gets only the site's `llms-full.txt`, the key, the delegation and one
+`http_request` tool locked to the oracle's origin. It must reach a decision it paid for itself.
+The script checks the result, not the model's word. It costs a few cents of model usage plus
+one claim.
+
+### 6. Card scenarios (devnet, Stripe test mode)
+
+Card needs an oracle whose protocol costs **≥ 50¢ per claim** (Stripe's minimum capture; SwiftDrop is
+60¢ for this) and whose plan accepts `card`. Which scenario runs is set on the **facilitator side**:
+the payer's default saved card and default way to pay. Saving a test card and completing 3-D Secure
+need the facilitator's Stripe test key, so that half belongs to whoever owns the facilitator
+(ixo-pay-facilitator `.claude/skills/devnet-card-check`). This half pays:
+
+```bash
+cd packages/client && bun run build
+node dev/devnet-card.ts submit card      # prefer card; `upay` = PAY first; `none` = the console default
+node dev/devnet-card.ts resume           # after a 3-D Secure confirm: the SAME offer, same key
+```
+
+| Payer's default card (facilitator side) | Run | Expect |
+| --- | --- | --- |
+| `pm_card_authenticationRequired` | `submit card` | `CARD_AUTHENTICATION_REQUIRED` + `confirmUrl`; once confirmed, `resume` → paid with the SAME PaymentIntent. Left unconfirmed, the facilitator cancels it ~17 min later, never charged |
+| `pm_card_chargeCustomerFail` | `submit card` | declined at authorize → paid with PAY for the same 402 |
+| `pm_card_createDispute` | `submit card`, then again once the dispute is open | paid by card; then `card_blocked` → PAY (no PaymentIntent created); after the dispute is won, card again |
+| `pm_card_visa`, preference `card` | `submit none` | the SDK reads `/v1/payer/preferences` with the delegation → card |
+
+Every claim's record names the rail: `stripe-manual-capture` / `usd` / cents, or `ixo-pay` / `upay`.
+A run that answers `SPEND_CAP` has used up the delegation's `maxAmount`: mint a new one. Proven end to
+end on 2026-10-01, pre-company-authority (2026-10-10) (SwiftDrop at 60¢; each card capture paid IXO
+its 20% fee).
+
+## Working on the client in this repo (maintainers)
+
+- **`@ixo/x402-ixo-pay` comes from npm** (0.5.2, published from ixo-pay-facilitator
+  `packages/x402-ixo-pay`) as an ordinary runtime dependency; the client's `dist/` imports it. A
+  facilitator wire change means a new version published there, then a bump here.
+- **`packages/client/scripts/pack-test.sh`** (run first by `pack-smoke.sh`) proves the tarball
+  stands alone: every dependency is a registry version (no git, `file:` or workspace spec), it
+  installs with git turned off, and it pays and runs its bin under plain node.
+- **Types come from the OpenAPI.** Run `bun run generate` after the OpenAPI changes. It uses
+  `npx` with TypeScript 5, because TS 7 has no JS compiler API and openapi-typescript needs one.
+
+## When something fails
+
+| Symptom | Cause · fix |
+| --- | --- |
+| `402 PAYMENT_REQUIRED` thrown, never paid | No `paymentDelegation` / `IXO_PAYMENT_DELEGATION` given, or the payer was not configured. |
+| `PaymentError DELEGATION_EXPIRED` / `INVALID_DELEGATION` | The delegation expired or isn't the base64 CAR. Mint a new one (step 1). On testnet/mainnet, `INVALID_DELEGATION` also means it names no oracles. |
+| MCP `SUBMITTER_REQUIRED` | The protocol has a frequency rule (its work order says `facts.frequency: true`), so `submit_claim` needs `submitter`, your stable id for the person (e.g. the courier id). Without it the engine would reject the claim, so it is refused before any approval or charge. |
+| The AI asks you to upload a photo | There is no upload over sign-in. Give it an https link; `submit_claim` attaches `{ question, url }` and the oracle fetches it. No `mediaType` is needed: the oracle reads it from the URL's extension, else a `HEAD`, when it accepts the claim. |
+| Claude Code refuses `submit_claim` ("real-world transaction") | Its safety check is holding back a tool that may spend. Allow only this tool: `/permissions` › Allow › `mcp__<server>__submit_claim`. Never turn the safety check off. Every charge still needs the user's AuthHub approval or their auto-approve limits. |
+| `PaymentError DELEGATION_WRONG_ORACLE` | The delegation is bound to other oracles. Re-sign it naming this oracle's `did:web` (console Keys › Payment delegation; `devnet:credentials` binds to `--oracle`). |
+| `PaymentError CARD_NOT_SAVED` | The payer has no saved card and the 402 took card only (or `prefer: "card"` with no PAY to fall back to). Save a card on the console's card page, or pay with PAY. |
+| `PaymentError CARD_AUTHENTICATION_REQUIRED` | The bank wants 3-D Secure. Open `err.confirmUrl` and confirm within 15 min, then resubmit with `{ idempotencyKey: err.idempotencyKey, resumePayment: err.paymentRequired }` — never a fresh offer. `OFFER_EXPIRED` on the resume: the gate no longer takes that offer; submit afresh. `INVALID_RESUME`: the offer passed is not this oracle's card 402. |
+| `402 INSUFFICIENT_CREDITS` (+ `fundingUrl`) | The session's deed has too little devnet PAY. Top up in the console. |
+| `402 SPEND_CAP` | The key's daily cap or the delegation's `maxAmount` is spent. Mint a delegation with a higher `--max-pay`. |
+| `403 PAYER_NOT_MEMBER` | The delegation's issuer isn't the source's owner or a member. Mint it from the owner's session. |
+| `409 IDEMPOTENCY_MISMATCH` | Same `Idempotency-Key`, different body. Use a new key per new claim. |
+| `terms_mismatch` on the paid resend | `accepted` wasn't the offer entry verbatim. Hand-built headers must copy it byte for byte. |
+| `403 SCOPE` | The key lacks `claims:write`, as intended for the read-only key. |
+| Receipt `untrusted_issuer` | Only IXO's three engines are trusted by default. Pass `issuers` for another. |
+| MCP 404 on `/v1/mcp` | The deployed oracle predates the MCP route. Redeploy (`decision-api-oracle`). |
+| MCP OAuth: the client never opens AuthHub | The oracle predates MCP over OAuth (no `/.well-known/oauth-protected-resource/v1/mcp`, and the `401` has no `resource_metadata`). Redeploy. |
+| MCP `401` with `error="invalid_token"` | The sign-in expired or is for another oracle or network. Reconnect (`/mcp` › *Authenticate*). |
+| `APPROVAL_STALE` | The price changed after the approval; nothing was charged. Approve the new link. |
+| `SPEND_CAP` over OAuth | The app's grant reached $20.00 today. Wait, or use a key. |
+| "Don't ask again" refused: `403`, reason `standing_approvals_off` | The oracle's `policies.allowStandingApprovals` is `false`, so a standing approval never pays there. Approve each claim, or have the operator turn it on and redeploy. |