@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/skills/reference/engine-contract.md

@@ -0,0 +1,222 @@
+# The decision engine's contract (what the package codes against)
+
+Background, not an interface you write code against. The package owns every call below; a
+provider's handlers never see the engine except through `tools.agreement()` (the buyer statement)
+and `bunx decision-oracle facts run --preview` (a decision, nothing persisted or billed). Read this when
+you need to understand an error the oracle logged, or what the engine does with the facts you
+produce.
+
+## Auth + preconditions
+
+- Every call is a UCAN invocation: `X-Auth-Type: ucan` + `Authorization: Bearer <invocation>`,
+  audience = the engine's `did:web` (`EVAL_ENGINE_HOSTNAME`). Issuer = `did:web:<ORACLE_HOSTNAME>`
+  — this oracle's own did:web key, self-signed, so no on-chain IID key is needed.
+- Once, before the first decision (and again whenever the chain address changes), the oracle calls
+  `POST /v1/oracles/register` with `{ address, pubKey, signature, ownerDelegation }`:
+  - `address` — `ORACLE_ADDRESS`, the grantee of the collection's `EvaluateClaimAuthorization` and
+    the key that signs `MsgEvaluateClaim`;
+  - `signature` — an ADR-36 `sign/MsgSignData` by that secp256k1 key over the exact string
+    `decision-engine:register:<principal.did>:<address>`. The engine verifies it, checks
+    pubKey → address, and upserts the row keyed by the DID. Because `principal.address` is
+    meaningless for a did:web, this proof is what binds DID ⇄ chain address.
+  - `ownerDelegation` — `OWNER_DELEGATION_CAR`, forwarded verbatim: the oracle OWNER's
+    `subscriptions/read` on `ixo:subscriptions` plus `billing/pay` bound to THIS oracle's did:web,
+    the two capabilities the engine needs to find and bill the owner's subscription. Nothing renews
+    it, so `bunx decision-oracle delegation --for engine` defaults to 100 years — an expired CAR is a
+    refusal, not a retry: mint a short one with `--days` only if you will re-mint and re-register
+    before it lapses.
+- Everything downstream keys on what registration bound: the decided-once row is
+  (claimId, registered DID), the per-decision grant check uses the PROVEN address, and the receipt
+  names `{ did, address, factsDigest }`.
+- Per decision the engine checks this oracle holds the on-chain `EvaluateClaimAuthorization` for the
+  collection. Decided once per (claimId, oracleDid): re-POSTing returns the stored row, which is what
+  makes the call safe inside a durable workflow step.
+
+## POST /v1/decisions — the request
+
+```text
+{ subject: { kind: "claim", claimId, collectionId, protocolDid },
+  rubric:  { id: <sha256 hex pin, read off the protocol's #rub proof> },
+  facts:   <FactSet v1>,
+  payout?: { version: 1, amountPath, currency | currencyPath | asset+decimals },
+  claimContent }                                                     — REQUIRED
+```
+
+- `claimContent` binds the decision to the claim it judged:
+  `{ kind: "chain", cid, document? }` (`document` = base64 of the EXACT stored bytes, sent only when
+  the read lane CID-verified them) or `{ kind: "api", body }` (the content as stored at accept).
+  The engine checks the CID, the bytes, the answers and the attachments against the FactSet. A
+  claim read only from the Matrix claim bot, or a document over 256 KiB, goes without `document`.
+- `payout` is sent for a protocol in `OracleConfig.payouts` (outside the facts); the payee is derived
+  by the engine, never sent.
+
+FactSet v1 is a STRICT object (an unknown key is a 400):
+
+```text
+version: 1
+frozenAt: ISO                    — the ONE clock read; MUST equal ctx.now
+answers: {…credentialSubject…}
+attachments: [{ question, name, mediaType, cid|null, size|null }]
+ctx: { now: ISO, collection: { startDate|null, endDate|null },
+       claim: { submitter|null, submitterAddress|null, submissionDate|null, useIntent? } }
+ext:  { name → { status:"ok", value: boolean|number, reason: string|null, confidence?, transcript? }
+             | { status:"error", onError:"review"|"reject", detail, transcript? } }
+ai:   { name → { status:"ok", value: boolean, reason: string|null, failedRules: string[], score: 0..100, confidence?, transcript? }
+             | { status:"error", onError, detail, transcript? } }
+unique?: {…}  frequency?: {…}
+settings: { allowAiChecks: boolean, allowImageChecks: boolean }   — REQUIRED
+```
+
+`derived` and `formProof` are never sent — the engine computes both from chain. Those `ext`/`ai`
+entries are exactly what a handler returns, after the runner normalized it.
+
+## Errors
+
+| code | meaning | what the package does |
+| --- | --- | --- |
+| 403 `NOT_REGISTERED` | never registered | register (ADR-36 proof) once, retry |
+| 400 `INVALID_ADDRESS_PROOF` | register proof bad | non-retryable; `ORACLE_SECP_MNEMONIC` ≠ `ORACLE_ADDRESS` — a config bug |
+| 403 `NO_EVALUATE_GRANT` | not hired for this collection | retry once (a grant may have just landed), then pause the collection |
+| 402 `INSUFFICIENT_CREDITS` | the OWNER's credits are exhausted | pause every watched collection, log `details.manageSubscriptionUrl`; the cron resumes when `/me` says ok |
+| 402 `NO_SUBSCRIPTION` (register) | the delegated owner has no subscription | non-retryable; the owner subscribes in the portal, then register again |
+| 403 `DELEGATION_NOT_FOR_ORACLE` (register) | the CAR's `billing/pay` names a different oracle | non-retryable; re-mint with `--oracle did:web:<this host>` |
+| 400 `BAD_REQUEST` (register, naming `ownerDelegation`) | the CAR is malformed, mis-addressed or expired | non-retryable; re-mint, then register again |
+| 409 `RUBRIC_PIN_MISMATCH` | our pin ≠ the chain's `#rub` proof | invalidate the cached manifest, re-read, rebuild, retry once |
+| 409 `STALE_REVIEW` | the review answered against a stale digest | refetch the decision, ask the reviewer again |
+| 409 `CONTENT_MISMATCH` | `claimContent` doesn't match the claim (`details.reason` names the check) | non-retryable. Decide: a `decisions` row `status: content_mismatch`, `chainStatus: skipped`, the ingest fails and alerts. Fold: `foldError` |
+| 413 `PAYLOAD_TOO_LARGE` | the body (6 MiB) or the decoded `document` (2 MiB) is over the cap | non-retryable. Decide: a `decisions` row `status: payload_too_large`, `chainStatus: skipped`, the ingest fails and alerts. Fold: `foldError` |
+| 400 `REVIEWER_GRANT_INVALID` | the fold's `reviewerGrant` is absent (the decision has a company), malformed, mis-signed, expired or mis-scoped | non-retryable; `foldError` — the reviewer answers again with a valid grant (the chain reviewer-grant routes land with CA-M5a) |
+| 403 `REVIEWER_NOT_AUTHORIZED` | the grant's root is not a current controller, or an oracle/evaluator is in the chain | non-retryable; `foldError` — ask a company reviewer |
+| 400 `VALIDATION` | the facts' shape is wrong | non-retryable; a producer bug — fails loudly |
+| 429 `RATE_LIMITED` | the engine's per-IP limiter | retryable; the step backs off (`Retry-After` honoured) |
+| 503 `UNAVAILABLE` | a Blocksync/chain blip | retry (the step retries) |
+
+An unusable rubric is NOT an error: `200` with `decision.status = "unusable"`.
+
+## Billing
+
+The engine bills a **flat rate per decision** from its live rate card; it runs no AI, so a decision's
+price never depends on what the facts cost this oracle to produce. It bills the oracle OWNER's
+credits — never the collection owner's, never this oracle's own wallet: one fee claim per decision,
+into the owner's oracle claims collection (the subscription
+`ownerDelegation` proved at register). Folds are free. `GET /v1/oracles/me`'s `billingStatus` says
+when a paused oracle is `ok` again; the scan cron asks once per tick while anything is paused
+`engine-credits` and resumes them all. `admin-unfunded` (the collection admin's chain account cannot
+pay the evaluation leg) is package-side only — the engine never sees it.
+
+## Response
+
+```text
+{ subject, rubricId,
+  decision: { status, verdict, class, evaluationStatus, action, totalBps, gates, criteria, pendingTasks, reasons },
+  explanation, factsDigest, resultDigest,
+  receipt: { cid, jws } | null,        // approved + a payout block ⇒ also a DecisionToPayCredential with decision.binding
+  decisionToPayRefused?: "NO_PAYEE",   // a payout scope with no derivable payee: still 200, no binding
+  traceId,
+  billing: { totalMicroUsd } | null,   // the flat rate for this decision; null on preview, verify and folds
+  preferences: { id, digest } | null }  // the engine-side preferences it applied; the oracle sends none
+```
+
+`decision.status` is one of `decided` / `pending_review` / `unusable`. `receipt` is null ONLY for
+`pending_review` (it is minted after the fold); `decided` and `unusable` both carry one — an
+`unusable` receipt proves the engine refused and why, in codes. The package stores both `cid` and
+`jws` on the decision row, signs `MsgEvaluateClaim` only for `decided`, and puts the receipt CID in
+`verification_proof`. Receipts resolve publicly at the engine's `GET /v1/receipts/:cid`.
+
+## Human review
+
+The engine cannot fold from its stored trace alone (answers are never persisted), so the package
+re-pulls the claim body by CID — byte-identical from a CID-verified store; a bot-lane re-pull goes
+without `document` — and posts `POST /v1/reviews/:claimId` with
+`{ answeredAgainst, answers, reviewerDid, attestation, claim: { answers }, payout?, claimContent, reviewerGrant? }`.
+`claimContent` is required and must name the decision's content (else `409 CONTENT_MISMATCH`);
+`reviewerGrant` (a base64 CAR of the reviewer's delegation chain) is required when the decision has a
+company.
+The engine rebuilds the wire FactSet from its trace plus those answers and requires `factsDigest` to
+match. **No fact handler runs again, and nothing is re-bought**: a fold is the same frozen facts with
+the reviewer's answers folded in. Deterministic refusals (`404`, `403`, `409 STALE_REVIEW`,
+`400 BAD_REQUEST`, `409 FACTS_MISMATCH`, `422 REVIEW_INCOMPLETE`) are surfaced as `foldError`, never
+retried. A fold can itself come back `unusable` when the claim form drifted since the decision.
+
+`attestation` is the reviewer's own `ClaimReviewAttestation` credential (a compact JWS) over those
+answers, taken by the package's `POST /v1/reviews/:claimId`, verified there against the keys the
+chain publishes for the invoking principal, stored verbatim on `claim_reviews.attestationJws` and
+forwarded unchanged — the engine verifies it again, because `reviewerDid` alone is only the
+oracle's word. **It is required**: a review or fold without one is `ATTESTATION_REQUIRED` (400)
+before any lookup or write, and there is no flag. A failed check refuses the review with
+`ATTESTATION_INVALID` (400), `ATTESTATION_KEY_UNKNOWN` (400 — no such key, no such document, no
+Ed25519 method, or a 4xx naming the did:web URL fetched: deterministic),
+`ATTESTATION_ISSUER_MISMATCH` (403, checked before anything resolves), `ATTESTATION_MISMATCH` (400)
+or `ATTESTATION_UNRESOLVABLE` (503 — the resolver could not reach its source, including a 4xx that
+names no URL and any 408/429; retryable). Replacing a stored answer therefore takes another
+signature. A fold's receipt names the attestation in `evidence` by CID, and the fold's Matrix card
+edit says "Signed by \<did\>".
+
+**Deploy order:** portal first (an older package's review body schema is not strict, so the extra
+field is harmless), then engine and package TOGETHER — both require it, and the engine's fold body
+schema is strict, so forwarding `attestation` to an older engine 400s every fold into `foldError`.
+
+## Dev lane
+
+`POST /v1/decisions/preview` — the same request, with `rubric` allowed as `{ doc }` and
+`form { doc, proof }` inline. Nothing is persisted, billed or grant-checked. This is what
+`bunx decision-oracle facts run --preview` calls, and what `bunx decision-oracle rubric validate` builds on.
+
+## Agreements — the buyer statement
+
+The engine stores a buyer statement per collection (and optionally per counterparty) and serves it
+to hired oracles; it never interprets the document. `tools.agreement(counterparty?)` is that read:
+omit the argument for the claim's own agent, pass an explicit `null` for the collection's own terms.
+
+- `GET /v1/collections/:collectionId/agreements?counterparty=<address>` → the latest snapshot for
+  that counterparty, falling back to the collection-wide one; 404 if none (the tool returns `null`).
+- Authorization is strict: the caller must be the collection owner or a registered oracle holding
+  the on-chain `EvaluateClaimAuthorization` for THAT collection.
+- `counterparty` is compared as an exact lowercase bech32 string; the package lowercases for you.
+- At decision time the engine records which snapshot was current on the trace and the receipt —
+  which is why a handler reads the agreement LAST, right before returning the fact it feeds.
+
+## Fact coverage + the manifest
+
+- **The engine is the sole validator of rubric ↔ form ↔ facts.** Right after binding it requires
+  every declared `ext` name in `facts.ext` and every `ai` name in `facts.ai` (ok or error), with ok
+  values of the declared kind: `expect: "boolean"` ⇒ a JS boolean, `expect: "score"` ⇒ an INTEGER
+  0..10000 basis points (rejected, never clamped). A miss is `200` + `status: "unusable"`, billed
+  zero, with `FACT_MISSING` / `FACT_KIND` in `decision.reasons`. Never a 400.
+- `decide()` reads only `status`, `value` and `onError` of a fact; `score` / `reason` /
+  `failedRules` feed the trace and the explanation, and `transcript` is never read — which is why an
+  `ai.*` fact may come from any producer at all (a vendor model, OCR, a person).
+- **The work order is the manifest**, public and unauthenticated:
+  `GET /v1/rubrics/manifest?protocol=<did>` (`bunx decision-oracle manifest <did>` prints it).
+
+  ```ts
+  { rubricId, formProof: { pinned, live, drifted },
+    ext: Record<name, { expect, onError, endpoint, audience, capability?, send, timeoutMs?, usedBy }>,
+    ai:  Record<name, { expect: "boolean", onError, instructions, send, usedBy }>,
+    hasAiChecks, ctx: string[], fields: { path, kind }[], derived: { name, expression }[],
+    review: { tasks, taskDetails? },
+    unique: { ruleId } | null, frequency: { ruleId } | null,
+    sizeProbes: { path, maxSizeMB }[] }
+  ```
+
+  An unbindable rubric answers `200 { status: "unusable", issues }` (`RUBRIC_UNRESOLVED` for a
+  missing `#rub`, `BIND_FORM_DRIFT` for a drifted `#vct`, else the binder's own issues). `onError` is
+  always present (the format's absent-means-review default is resolved by the engine); `ctx` lists
+  only the tokens the rules name; `fields[].path` are resolved catalog paths. The package caches a
+  usable manifest per protocol for 5 minutes and re-reads it on `RUBRIC_PIN_MISMATCH`; an unusable
+  one is never cached — it pauses the collection instead, so one broken rubric costs no claims.
+- `POST /v1/rubrics/manifest` is the same answer for a rubric that is not on chain yet: post
+  `{ rubric: { doc }, form: { doc, proof } }`. That is how `bunx decision-oracle rubric validate` binds a
+  draft.
+
+## Who calls out
+
+1. **The engine never calls a rubric's `endpoint` and never calls a model.** `runDecision` is pure.
+   A missing `ext.*` / `ai.*` is `unusable`, never fetched.
+2. **The engine's only per-decision outbound reads are deterministic inputs**: Blocksync for the
+   protocol's linked resources and the collection admin, the byte fetch of `#rub` / `#vct` (verified
+   against the on-chain proof), and the chain read of the oracle's `EvaluateClaimAuthorization`.
+3. **A rubric's `endpoint` / `audience` / `send` / `instructions` are the protocol owner's
+   documentation of how a fact is expected to be produced.** Only a producer acts on them — the
+   stock lane, or your handler. The engine validates only that the fact exists with the declared
+   kind.

package/skills/write-facts/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: write-facts
+description: Use when an oracle built on @ixo/decision-oracle needs a fact handler — "write the handler for ext.X / ai.Y", a protocol review that says a name needs custom code, wiring a vendor API or the buyer statement into a fact, testing handlers with runFacts/fakeTools, or debugging FACT_MISSING / FACT_KIND / a fact that came back error.
+---
+
+# Writing fact handlers
+
+## Overview
+
+A rubric asks for named facts; the engine publishes that list as a **manifest** (the work order);
+this oracle produces one value per name and the engine decides. A handler is one function per name:
+
+```ts
+// src/facts/deliveryConfirmed.ts
+import { type ExtHandler, fact } from "@ixo/decision-oracle/facts";
+
+export const deliveryConfirmed: ExtHandler = async ({ send }, tools) => {
+  const res = await tools.http.json<{ status?: string }>(
+    `https://courier.example/deliveries/${send.reference}`,
+  );
+  if (!res.ok) return fact.error(`courier responded ${res.status}`);
+  return res.body?.status === "delivered";        // a plain boolean ⇒ an `ok` fact
+};
+```
+
+Everything a handler needs is handed to it: the claim, the resolved `send` map, the declaration for
+this name, and `tools` — the package's own machinery (the stock lane, HTTP with retries and a
+transcript, the AI judge, attachment bytes, C2PA, the chain reads, the buyer statement). A handler
+imports nothing but types and `fact`, and runs in plain node under test.
+
+**Core principle: a handler answers, it never decides.** It says what is true, or says it could not
+find out. What a "could not find out" MEANS is the rubric's `onError`, stamped by the runner — never
+the handler's to choose, and never quietly upgraded to a pass.
+
+## When to use
+
+- "Write the handler for `ext.<name>` / `ai.<name>`" — the `create-oracle` pipeline's step 3
+- A `protocol review` that lists a name as needing custom code (a vendor API, a `~derived` ref, a
+  judge that is not the stock AI check)
+- Testing handlers (`runFacts`, `fakeTools`), or a fact that came back `error` in a real run
+- The engine answered `unusable` with `FACT_MISSING` / `FACT_KIND`
+
+Not for: authoring the rubric that declares these names (`create-rubric`), or the surrounding
+project setup — identity, register, deploy (`create-oracle`).
+
+## The loop — one manifest entry at a time
+
+### 1. Read the work order
+
+```bash
+bunx decision-oracle protocol review <protocol did> [--network devnet|testnet|mainnet] [--json]
+```
+
+It prints every declared `ext` source and `ai` check with its `expect`, `onError`, `endpoint`,
+`send` and instructions, and says which names the stock lanes already cover. **If the manifest comes
+back `unusable`, stop** — the rubric does not bind to its form, so there is nothing to answer yet
+(hand back to `create-rubric`).
+
+### 2. Decide stock vs custom, per name
+
+| Lane | Stock covers it when… | Write a handler when… |
+| --- | --- | --- |
+| `ext.<name>` | the declared endpoint accepts a self-signed UCAN POST (the resolved `send` + the claim body; audience the endpoint's own did:web, capability `ixo:external-source` — the rubric's `capability` is ignored) and answers the strict `{ valid: boolean }` / `{ score: 0..10000 }` contract | it is a vendor API with different auth or a different shape, it needs YOUR system or a secret, it is answered from the CHAIN (`tools.chain`) rather than an endpoint at all, or its `send` reads a `~derived` value (the stock lane always answers that `error`) |
+| `ai.<name>` | a plain stock AI judgment against the rubric's own `instructions` is what the author meant | a different model or vision vendor is required, the inputs need re-slicing or pre-checking, or `send` reads a `~derived` value |
+| `unique` | always — this oracle's D1 registries, perceptual hashing, near-text and the gray-zone judge | only a wholly different duplicate strategy (rare); the `UniqueFact` shape is still fixed |
+| `frequency` | always — one Blocksync submission count | same as above |
+| `sizeProbes` | always — the package probes the named roots itself | never; not a handler's concern |
+| `derived[]` | the ENGINE computes these; no fact is ever produced for a `~name` | a `send` naming one forces a handler on whichever `ext`/`ai` reads it — `manifest.derived[].expression` is there for you |
+
+Ask the provider the judgment calls, don't guess them: do you control that endpoint (can you make
+it speak the stock contract), and is a stock AI check the judge the author meant?
+
+### 3. Scaffold, then fill
+
+```bash
+bunx decision-oracle facts scaffold <protocol did> [--all] [--dir src/facts]
+```
+
+Writes `src/facts/<name>.ts` for every name that needs a handler (`--all` for every declared name)
+plus `test/facts/<name>.test.ts` beside it, and never overwrites a file that already exists. Add
+each export to the table in `src/facts/index.ts` yourself. **Every stub returns
+`fact.error("not implemented: <name>")`** — a visible failure that routes to the rubric's own
+`onError`. Leave it that way until the real call works; never a placeholder `true`.
+
+Fill one in with `reference/facts-api.md` open — it has every input field, every `tools` member with
+a one-line example, and the return table. Two worked handlers to copy the shape of:
+
+- `reference/examples/http-vendor.ts` — a vendor HTTP source: read `send`, call the declared
+  endpoint, map only what you understand, `fact.error` for the rest, `retryLater` on a 5xx.
+- `reference/examples/price-matches-agreement.ts` — the buyer statement: guard the inputs, read
+  `tools.agreement()` LAST, tell a checked "no" (`ok(false)`) from an unanswerable one (`error`).
+
+### 3b. One call, many facts
+
+When several declared sources come out of **one** call — four criteria judged by a single
+structured model call is the case — write them as a group, not as four handlers that each buy their
+own completion:
+
+```ts
+// src/facts/index.ts
+export const facts = defineFacts({
+  ext: { speed },                                             // answered on its own
+  groups: [group(["quality", "price", "reliability", "trust"], workScores)],
+});
+
+// src/facts/workScores.ts
+export const workScores: GroupHandler = async ({ names, answers }, tools) => {
+  const res = await tools.http.json<Scores>(JUDGE_URL, { method: "POST", body: { …answers } });
+  // One call, one failure: every name it owed gets an error. Never a neutral score for a judgment
+  // that was never made.
+  if (!res.ok) return Object.fromEntries(names.map((n) => [n, fact.error(`judge ${res.status}`)]));
+  return { quality: …, price: …, reliability: …, trust: … };   // one fact per name
+};
+```
+
+The runner calls it **once** per claim (one slot in the fan-out cap) and holds every name it answers
+to the same rules a single handler's fact meets: each carries its own declaration's `onError`, each
+is cached on its own, and a throw freezes every name the call owed. Plus: a name you leave out
+becomes that name's own `handler returned no fact for <name>` error (silence is not an answer), a
+name nobody asked for is dropped with a `facts.group-extra-fact` warning, `tools.stock()` throws
+inside a group (it names none of the group's sources), and one name answered by both a single and a
+group — or by two groups — throws at **boot**.
+
+A group is the sanctioned way to share one call between facts. A private cache inside a handler
+still is not: the runner's own fact cache is the only cache (see the rules below).
+
+### 4. Test in plain node
+
+```bash
+bun run test        # vitest, node environment — no Worker, no network
+```
+
+```ts
+const out = await runFacts(facts, {
+  claim: sampleClaim({ reference: "ABC" }),
+  manifest: sampleManifest({ ext: { deliveryConfirmed: { expect: "boolean", onError: "review" } } }),
+  tools: fakeTools({ http: { "https://courier.example/deliveries/ABC": { status: "delivered" } } }),
+});
+expect(out.issues).toEqual([]);
+expect(out.ext.deliveryConfirmed).toMatchObject({ status: "ok", value: true });
+```
+
+`runFacts` is the same runner production runs, followed by the same `validateFacts` — `issues: []`
+means the engine would accept this FactSet. Cover both halves of every handler: the answer, and the
+failure it is most likely to meet (an unmatched URL in `fakeTools` is a network failure; an
+`httpResponse(503, …)` is a bad status). A handler with only a happy-path test is not tested.
+
+### 5. Run them against a real claim
+
+```bash
+bunx decision-oracle facts run --protocol <protocol did> --claim protocol/sample-claim.json \
+  [--collection <id>] [--preview] [--facts src/facts/index.ts] [--network devnet] [--json]
+```
+
+Pulls the live manifest, runs your table over that claim, and prints the facts plus any validation
+issue (exit 1 if there are issues). `--preview` sends them to the engine's preview lane and prints
+the decision they would produce — nothing persisted, nothing billed, no grant needed.
+
+`--claim` takes either a flat answers object (the same file `submit-claim --answers` posts — the
+passport example's `protocol/sample-claim.json` is one) or the `{ answers, attachments?: [...] }`
+envelope. A flat file has no attachments, so a handler that reads one fails closed: run the passport
+example against its sample claim and the AI fact comes back `error` (the guard's path), not a stock
+verdict. To exercise a lane that needs files, hand `--claim` an envelope whose `attachments` entry
+points at a local photo.
+
+## The rules a handler must never break
+
+- **Never fake an ok.** A fact you could not establish is `fact.error(detail)`. Returning `false`
+  says "I checked, and it is false" — a different claim about the world, and the rubric may reject on
+  it. A stub is `fact.error("not implemented: <name>")`, visibly.
+- **Never choose `onError`.** There is no argument for it and no way to pass one: the runner stamps
+  the manifest's own value over whatever a handler produced. Do not try to route around it by
+  returning a different verdict instead.
+- **Never decide.** No thresholds, no gates, no rubric parsing, no reading `rubric.json`. The
+  manifest is the only work order, and the engine is the only judge.
+- **Read the agreement last.** `tools.agreement()` right before returning the fact it feeds — the
+  engine records the snapshot current at decision time on its receipt.
+- **Read the chain through `tools.chain`, never by hand.** `linkedResources(entityDid)` for what an
+  entity anchors (and each resource's `proof`), `messages(filter)` for what an account did on chain
+  and when, `query()` for chain RPC. An empty answer is a FACT ("nothing anchored", "no such
+  message"); an unreachable Blocksync throws, and the step retries.
+- **One clock, one fan-out.** Use `ctx.now`, never `Date.now()`. Don't spawn your own concurrency:
+  the runner already caps ext+ai at 4 in flight and caches every answer so a step retry never
+  re-buys it.
+- **No secrets in code or commits.** A vendor key is a `wrangler.jsonc` binding / `.dev.vars` secret,
+  read as `tools.env.<NAME>`.
+- **A handler never imports the worker.** `@ixo/decision-oracle/facts` and `@ixo/decision-oracle/testing`
+  only — both must keep loading in plain node, which is what makes the tests fast and real.
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| A stub (or an unreachable vendor) returning `true` so a run looks green | `fact.error("not implemented: <name>")` — a loud failure routed by the rubric beats a wrong value that passes shape validation |
+| Passing an `onError` into `fact.error(...)`, or picking `reject` "because it's safer" | the manifest's own `onError` is stamped by the runner; the rubric author already made that call |
+| Calling the declared endpoint AND `tools.stock()` | two calls, two charges, one fact — wrap the stock lane or replace it, never both |
+| A handler named for something the manifest doesn't declare | it is ignored with a `facts.handler-unused` warning — copy the name from `protocol review`, exactly |
+| Returning `0.82` for a `score` source | basis points, an integer 0..10000 (`8200`) — the engine rejects a float, it never clamps |
+| `throw` used as a retry signal | any other throw is an `error` fact; only `throw fact.retryLater(detail)` retries the step |
+| Reading `rubric.json` to work out what to produce | read the manifest (`protocol review` / `bunx decision-oracle manifest <did>`) — this oracle never parses a rubric |
+| A test that only asserts the happy path | test the failure the handler will actually meet — an unmatched URL, a 503, a missing attachment |
+| `Date.now()` / a second HTTP client / a private cache inside a handler | `ctx.now`, `tools.http.json`, and the runner's own fact cache — and `group([...], handler)` when several names share ONE call |
+| Four handlers each buying the same model call, or a group that answers only the names it liked | one `group([...])` per shared call, returning a fact for EVERY name it was given (`names`) |
+| Hand-rolling a GraphQL POST at `config.BLOCKSYNC_GRAPHQL_URL`, or treating a chain read that FAILED as an empty result | `tools.chain` — parsed, retried, and loud when the indexer is down; `[]` means "nothing there", which is a different fact |
+
+## Output contract
+
+Per name handled: the file (`src/facts/<name>.ts`), its entry in `src/facts/index.ts`, and its test
+(both halves). Then `bun run check` green, `bunx decision-oracle facts run …` printing the facts with no
+issues, and — said plainly — every name still on a stub, what it needs (a vendor endpoint, a key, a
+decision from the provider), and which names are deliberately left to the stock lanes.
+
+## Reference
+
+- `node_modules/@ixo/decision-oracle/docs/api.md` — the COMPLETE reference: every export, every option,
+  every default and cap, the wire shapes, the `FACT_*` codes, the testing helpers in full.
+- `reference/facts-api.md` — inputs, `tools`, returns, the runner's rules, the testing helpers.
+- `reference/examples/` — the two worked handlers.
+- `../reference/engine-contract.md` — what the engine does with these facts (fact coverage, the
+  manifest, `tools.agreement()`'s route, the error table). Background, not an interface to code
+  against.

package/skills/write-facts/reference/examples/http-vendor.ts

@@ -0,0 +1,88 @@
+import { type ExtHandler, fact } from "@ixo/decision-oracle/facts";
+
+/**
+ * `ext.deliveryConfirmed` — the common case: the rubric names an endpoint, but the real system
+ * behind it is a vendor API with its own auth and its own response shape, so the stock lane (a
+ * UCAN-signed POST answering `{ valid }` / `{ score }`) cannot speak to it.
+ *
+ * The shape to copy:
+ *  1. read the declared `send` — never the raw claim body, and never a field the rubric did not
+ *     declare for this source;
+ *  2. call the endpoint the rubric declares (`expected.endpoint`), not a URL of your own — if you
+ *     must call somewhere else, say so in the reason so the trace shows it;
+ *  3. map only the answers you actually understand;
+ *  4. everything else is `fact.error(...)` with the transcript attached — an unknown status, an
+ *     unparseable body, a vendor that has never heard of this reference. Never a fake pass.
+ *  5. transient trouble (no response at all, a 5xx) is `throw fact.retryLater(...)`: the workflow
+ *     step retries later and the facts already answered are kept, instead of freezing a verdict on
+ *     a blip.
+ *
+ * Do NOT also call `tools.stock()` here: that would be two calls, and two charges, for one fact.
+ */
+
+interface VendorDelivery {
+  status?: unknown;
+  signed_by?: unknown;
+}
+
+export const deliveryConfirmed: ExtHandler = async ({ send, expected }, tools) => {
+  const reference = send.reference;
+  if (typeof reference !== "string" || reference.length === 0) {
+    // The claim genuinely has nothing to look up — a checked answer, not a failure to check.
+    return fact.ok(false, { reason: "the claim carries no delivery reference" });
+  }
+
+  // Your own bindings ride on `tools.env` beside the package's; name them where you read them.
+  const { COURIER_API_KEY } = tools.env as typeof tools.env & { COURIER_API_KEY?: string };
+  if (!COURIER_API_KEY) return fact.error("COURIER_API_KEY is not configured on this oracle");
+
+  const res = await tools.http.json<VendorDelivery>(expected.endpoint, {
+    method: "POST",
+    headers: { authorization: `Bearer ${COURIER_API_KEY}` },
+    body: { reference },
+    timeoutMs: expected.timeoutMs ?? 5000,
+    // For a source that authenticates THIS oracle instead of a bearer key:
+    // ucan: true,  (signed as this oracle for THIS URL's host, instead of the bearer header)
+    // — your own capability, if your API checks one, is `ucan: { capability }` set HERE in code,
+    // never `expected.capability` (the rubric's, which the oracle ignores)
+  });
+
+  if (res.status === null || res.status >= 500) {
+    throw fact.retryLater(`courier API unavailable (status ${res.status ?? "none"})`);
+  }
+  if (res.status === 404) {
+    return fact.ok(false, {
+      reason: `courier API has no delivery for ${reference}`,
+      transcript: res.transcript,
+    });
+  }
+  if (!res.ok) {
+    return fact.error(`courier API answered ${res.status}`, { transcript: res.transcript });
+  }
+
+  // ---- Replace everything below with your courier API's real response shape. ----
+  const status = res.body?.status;
+  if (typeof status !== "string") {
+    return fact.error("courier API answered a body with no status field", {
+      transcript: res.transcript,
+    });
+  }
+  if (status === "delivered") {
+    const signedBy = typeof res.body?.signed_by === "string" ? res.body.signed_by : "unknown";
+    return fact.ok(true, { reason: `courier recorded delivery, signed by ${signedBy}` });
+  }
+  if (status === "in_transit" || status === "returned" || status === "lost") {
+    return fact.ok(false, { reason: `courier status is ${status}` });
+  }
+  // A status this handler has never seen is NOT a "no" — it is an unanswered fact.
+  return fact.error(`unrecognised courier status: ${status}`, { transcript: res.transcript });
+};
+
+/**
+ * A `score` source (`expected.expect === "score"`) returns an INTEGER 0..10000 instead of a
+ * boolean — basis points, never a float and never clamped by the engine:
+ *
+ *   const onTimePct = res.body?.on_time_pct;                       // 0..100 from the vendor
+ *   if (typeof onTimePct !== "number") return fact.error("no on_time_pct in the vendor's answer");
+ *   return fact.ok(Math.round(onTimePct * 100), { reason: `${onTimePct}% on time` });
+ */

package/skills/write-facts/reference/examples/price-matches-agreement.ts

@@ -0,0 +1,67 @@
+import { type ExtHandler, fact } from "@ixo/decision-oracle/facts";
+
+/**
+ * `ext.priceMatchesAgreement` — "is the claimed service, at the claimed price, what the buyer
+ * agreed to?" The worked shape for a handler that reads the BUYER STATEMENT: guard the inputs
+ * first (a claim with nothing to compare needs no read at all), then the ONE `tools.agreement()`
+ * call, as late as possible — the engine records the snapshot that was current at decision time on
+ * its receipt, so reading it last is what makes the receipt name the version these facts came from.
+ *
+ * Note which failures are `ok(false)` and which are `error`: "the claim named a service the
+ * agreement does not list" is a real, checked answer (false); "there is no agreement on file" or
+ * "the agreement is a document shape I do not understand" is an error — the rubric's own `onError`
+ * decides what that means. Neither is ever an invented `true`.
+ */
+
+interface AgreedService {
+  id: string;
+  name: string;
+  priceUsd: number;
+}
+
+/** The one document shape this handler understands — anything else is a miss, never a guess. */
+function agentServices(doc: unknown): AgreedService[] | null {
+  if (typeof doc !== "object" || doc === null) return null;
+  const { kind, services } = doc as { kind?: unknown; services?: unknown };
+  if (kind !== "agent-services/v1" || !Array.isArray(services)) return null;
+  const parsed: AgreedService[] = [];
+  for (const entry of services) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const { id, name, priceUsd } = entry as { id?: unknown; name?: unknown; priceUsd?: unknown };
+    if (typeof id !== "string" || typeof name !== "string" || typeof priceUsd !== "number") {
+      return null;
+    }
+    parsed.push({ id, name, priceUsd });
+  }
+  return parsed;
+}
+
+/** USD compared in whole cents — money is integers, never float equality. */
+const cents = (usd: number): number => Math.round(usd * 100);
+
+export const priceMatchesAgreement: ExtHandler = async ({ answers }, tools) => {
+  const { serviceId, priceUsd } = answers;
+  if (typeof serviceId !== "string" || typeof priceUsd !== "number") {
+    return fact.ok(false, { reason: "claim carries no serviceId / priceUsd to compare" });
+  }
+
+  // Last: the engine's receipt names the snapshot current at this moment.
+  const agreement = await tools.agreement();
+  if (!agreement) return fact.error("no agreement on file for this claim's counterparty");
+
+  const services = agentServices(agreement.doc);
+  if (!services)
+    return fact.error(`agreement ${agreement.id} is not an agent-services/v1 document`);
+
+  const agreed = services.find((service) => service.id === serviceId);
+  if (!agreed) {
+    return fact.ok(false, { reason: `service ${serviceId} is not in agreement ${agreement.id}` });
+  }
+
+  const matches = cents(agreed.priceUsd) === cents(priceUsd);
+  return fact.ok(matches, {
+    reason: matches
+      ? `${agreed.name} at $${agreed.priceUsd} as agreed`
+      : `${agreed.name} claimed at $${priceUsd}, agreed at $${agreed.priceUsd}`,
+  });
+};