Decision oracle API reference

Every export of the package, what it does, what it defaults to, and what it guarantees. If you are starting from zero, read the guide first — it is the narrative; this is the lookup.

The package is four import paths and one CLI. The root is the worker: it pulls the Hono app, the Workflow classes and the chain SDK into your bundle, so it is imported once, from src/index.ts. ./facts and ./testing are node-safe — no cloudflare:*, no wasm, no D1, no KV in their import graph — which is why a handler test is plain vitest with no Workers pool. ./runtime is the other worker-only path: what a provider's own route, cron or Workflow calls when it needs the kit to do something the lanes do not do by themselves (below).

1. Import map

@ixo/decision-oracle — worker only

import { defineOracle, NETWORKS, networkDefaults } from "@ixo/decision-oracle";
import type {
  ActContext,
  ActDecision,
  ActFacts,
  ActPolicy,
  Config,
  IxoNetwork,
  OpenhandsAsk,
  OpenhandsOptions,
  OpenhandsQuota,
  OracleBindings,
  OracleConfig,
  OracleEnv,
  OracleVars,
  OracleWorker,
} from "@ixo/decision-oracle";

@ixo/decision-oracle/facts — node-safe, what a handler imports

import {
  beforeAfter,
  defineFacts,
  fact,
  group,
  haversineMeters,
  located,
  photoFactsFromJpeg,
  linkedDocUrl,
  readAnswer,
  readLinkedDoc,
  RetryLater,
  rootQuestionName,
  withinRadius,
} from "@ixo/decision-oracle/facts";
import type {
  AiHandler,
  AiInput,
  AiResult,
  AiSendEntry,
  AiTools,
  ChainTools,
  ClaimIntent,
  ExtHandler,
  ExtInput,
  ExtResult,
  ExtTools,
  FactErrorDraft,
  FactGroup,
  FactInputBase,
  FactsConfig,
  FactsDeclaration,
  FactTools,
  FrequencyHandler,
  FrequencyInput,
  GroupHandler,
  GroupInput,
  GroupResult,
  HttpJsonInit,
  HttpJsonResult,
  LinkedDocRead,
  LinkedDocRef,
  LinkedResource,
  PhotoFacts,
  ReadLinkedDocOptions,
  UniqueHandler,
  UniqueInput,
} from "@ixo/decision-oracle/facts";

Geo evidence: grades and capturedAt

The geo handlers grade every time and place by who reported it, and write the grade into the fact's reason (so it reaches the trace and the receipt), e.g. 412 m from centre, limit 500 m; evidence: camera (photo EXIF) or after is 600 s after before, 3 m apart; evidence: time browser-reported (capturedAt), place browser-reported (capturedAt.before) / camera (photo EXIF):

capturedAt is the supported form field for per-photo capture metadata: an object keyed by the photo's role — before and after for beforeAfter, photo (else after) for withinRadius / located — each { at: <ISO instant>, lat?, lon?, accuracy? }. A stamp with no zone is read as UTC; accuracy is carried, not used.

{ "capturedAt": {
    "before": { "at": "2026-09-20T09:00:00Z", "lat": 46.05, "lon": 14.50, "accuracy": 12 },
    "after":  { "at": "2026-09-20T09:40:00Z", "lat": 46.05, "lon": 14.50 } } }

Missing evidence is an error, never false: a phone with location off, a photo forwarded through a messenger (EXIF stripped), a screenshot or a canvas resize answer nothing either way, so the rubric's onError decides. false means only "the evidence says no": too far, or out of order. EXIF and capturedAt are both client-supplied; a grade says where a value came from, never that it is true.

@ixo/decision-oracle/testing — node-safe, what a test imports

import {
  fakeTools,
  httpResponse,
  runFacts,
  sampleClaim,
  sampleCtx,
  sampleManifest,
} from "@ixo/decision-oracle/testing";
import type {
  ChainCall,
  ClaimIntentQuery,
  FactIssue,
  FakeChain,
  FakeHttpRoute,
  FakeTools,
  FakeToolsOverrides,
  HttpResponseEnvelope,
  LogRecord,
  ProducedFacts,
  RunFactsInput,
  SampleClaimOptions,
  SampleManifestDecl,
} from "@ixo/decision-oracle/testing";

@ixo/decision-oracle/runtime — worker only, what a route/cron/Workflow calls directly

import {
  AppError,
  broadcastAsOracle,
  decisions,
  getCollection,
  getDb,
  getIxoSdk,
  getOracleSigner,
  getQueryClient,
  loadConfig,
  registerCollection,
  rehireOpenhands,
  scanCollection,
  signEvaluation,
  watchedCollections,
} from "@ixo/decision-oracle/runtime";
import type {
  BlocksyncDeps,
  ChainWriteOutcome,
  CollectionNode,
  Config,
  Database,
  DecisionRow,
  OracleSigner,
  RegisterInput,
  WatchedCollection,
} from "@ixo/decision-oracle/runtime";

Separate from the root because the root is what your entry module imports and /facts//testing are what your node test suite imports; this subpath pulls in D1, the signer and the sequence-manager DO, so it can only ever be loaded inside a Worker. Every function takes env rather than the kit's internal deps — it assembles the config, the logger, the metrics, the trace and the database handle from it exactly as the cron does (cron/scan.ts's cronContext).

Plumbing, verbatim. The chain/db pieces the four functions above are themselves built from, re-exported here with no wrapper and no behaviour change — because the package's exports block only opens the root, /facts, /testing and this subpath, a deep import is not an option:

policies.act, in full. ActPolicy (exported from the package root, §1 above — it's a type-only seam with nothing to validate at registration, so it doesn't live under /runtime):

type ActPolicy = (ctx: ActContext) => Promise<ActDecision> | ActDecision;

ActContext — everything the act lane knows about the claim it is about to sign for, handed once every one of the lane's own guards has passed and immediately before it reads the authz grant:

ActDecision is what the hook returns: { mode: "sign", amount?, reason? } proceeds (amount, when given, replaces what the lane would have sent — denom included — but only on a collection whose owner set operatorAmounts: "allowed" (PATCH /v1/collections/:id/settings) and still owns it — a transfer turns the yes off until the new owner sets it again; while it is "off", the default, the lane pays its own default and logs act.amount-ignored-not-opted-in, and on an intent claim, where the chain overwrites it anyway, it logs act.amount-ignored-intent); { mode: "hold", reason? } parks the row chainStatus: "held" for a later signEvaluation; { mode: "skip", reason? } leaves the row untouched, the same clean no-op as AUTO_SIGN being off. The hook runs inside the act step's own retry, so a throw is a retry — never a silent signature: the lane records the error on the row and rethrows.

Writing one that cannot be gamed by a bad rubric. The lane guarantees only its own half: nothing but an explicit sign reaches the grant read and the broadcast, and an answer it cannot read — a typo, an old shape, undefined — parks the row blocked rather than signing it. The other half is yours, and it turns on two questions.

Is the fact really there? ctx.facts is keyed by the rubric's names, so a name the rubric never declared is simply absent, and a handler that failed leaves status: "error" with no value at all. Written as facts.ext.siteWork?.value === true ? hold : sign, absent, errored and honestly-false all collapse into one branch. Read presence and status before value, and give the unknown case a branch of its own:

const site = ctx.facts.ext.siteWork;
if (!site || site.status !== "ok") { /* the unknown branch — decide it deliberately, below */ }

Which of your modes is the expensive one? There is no universally safe default, because hold means whatever your release pass makes it mean. Where a held row waits for a person to look at it, holding the unknown is the cautious answer. Where a held row is entered into a pooled payout and settles for a share of the whole pot when the group closes, holding is the most expensive thing you can do with the claim you understand least — and if the marker fact is declared on only some asks, "absent" is the normal state of every other ask, so holding it strands ordinary work behind your stale timer. Work out which mode costs more in your design, make the unknown take the cheaper one, and make it loud: log the fact's detail, or sign with a reason naming the value you did not expect. A rubric that has stopped matching its claims shows up first as an unknown you swallowed.

Types you were not given an export for

The published types reference internal shapes (PulledClaim, Manifest, Attachment, …) that have no name on the public surface — deliberately: they belong to the package's internals and are reachable from the handler types by indexed access, which can never drift from them.

import type { AiInput, ExtInput, ExtTools, FactTools, UniqueHandler } from "@ixo/decision-oracle/facts";

type PulledClaim = ExtInput["claim"];
type Manifest = ExtInput["manifest"];
type ManifestExt = ExtInput["expected"];
type ManifestAi = AiInput["check"];
type CtxFacts = ExtInput["ctx"];
type FactSettings = ExtInput["settings"];
type Attachment = ReturnType<FactTools["attachments"]["on"]>[number];
type AttachmentBody = Awaited<ReturnType<FactTools["attachments"]["bytes"]>>;
type Agreement = NonNullable<Awaited<ReturnType<FactTools["agreement"]>>>;
type Provenance = NonNullable<Awaited<ReturnType<FactTools["c2pa"]["screen"]>>>;
type QueryClient = Awaited<ReturnType<FactTools["chain"]["query"]>>;
type ExtFact = Awaited<ReturnType<ExtTools["stock"]>>;
type UniqueFact = Awaited<ReturnType<UniqueHandler>>;

2. defineOracle(config)

// src/index.ts — the whole file
import { defineOracle } from "@ixo/decision-oracle";
import { facts } from "./facts";

const oracle = defineOracle({
  name: "my-oracle",
  description: "Evaluates delivery claims against the collection's rubric.",
  supportedProtocols: [],
  pricing: { evaluation: { denom: "uixo", minAmount: "1000000" } },
  policies: { autoSign: true, allowAiChecks: true, allowImageChecks: true, allowStandingApprovals: false },
  facts,
});

export default oracle;
export const { ClaimIngest, ReviewComplete, SequenceManagerDO } = oracle;

Those three re-exports are mandatory: the Workers runtime instantiates Workflow and Durable Object classes by export name, and the names here must match class_name in your wrangler.jsonc (workflows[].class_name → ClaimIngest / ReviewComplete; durable_objects.bindings[].class_name → SequenceManagerDO). An OpenHands checker (openhands set, below) re-exports a fourth, OpenhandsHire, bound as HIRE_WORKFLOW.

OracleConfig

Card is offered for a protocol only when its price is ≥ 50¢ (500 000 µUSD) per decision. That is Stripe's minimum capture, and the facilitator checks every claim separately, so a batch doesn't lift it. Below that only ixo-pay is offered. Changing the price is a redeploy (the code value, or API_PRICE_USD_CENTS when pricing.api is absent). The facilitator re-reads prices within ~5 min; an offer refused price_mismatch in that window is retried.

| policies.autoSign | boolean | required | Sign MsgEvaluateClaim on a terminal verdict unattended. The AUTO_SIGN var must be on too — both, or no chain write | | policies.allowAiChecks | boolean | required | false ⇒ every AI fact freezes as error / ai-checks-disabled with no model call, and the rubric's own onError carries. Also disables the duplicate lane's same-event judge (aiOutcome: "skipped") | | policies.allowImageChecks | boolean | required | Screen an AI check's image inputs for C2PA Content Credentials before the model call. Needs the C2PA_IMAGE_CHECK var on too. Fail-safe: it can only ever add a rejection | | policies.actSummary | string | optional, 1–500 chars | How your act policy picks an amount, in your own plain words — published on GET /v1/info as payouts.operatorAmount.summary (only while act is set) so a company sees how it is paid before it opts in to operatorAmounts. The oracle never writes one for you | | policies.allowStandingApprovals | boolean | required | Let an AI app's standing approval (the user's own auto-approve limits on the hosted MCP server) pay for a submit without a per-claim approval. Off ⇒ AuthHub cannot set one (an approval answer with standing, and PUT /v1/oauth/standing/:grantId, are 403 FORBIDDEN, details.reason: standing_approvals_off), a standing already stored never pays, is never read back (GET /v1/oauth/standing/:grantId is 404) and is deleted by the hourly housekeeping sweep, a card payment one parked for 3-D Secure is not resumed (FORBIDDEN, standing_approvals_off; the retry asks for the claim's own approval), and every OAuth submit needs the user's approval of that claim. GET /v1/info shows it under policies | | policies.reviewerNote | boolean | optional | Make a reviewer note for every claim held for a person (pending_review): one AI call, on the same provider as the AI checks, that says in plain words what the answer claims and what no check could verify — { says, checkThese[], model, createdAt }. Outside the decision: never sent to the engine, never in the receipt, never moves a verdict, no recommendation. Served beside checks on GET /v1/reviews/:claimId and GET /v1/claims/:claimId (never the submitter's view), erased with the claim body. Absent ⇒ on for an OpenHands checker (openhands set), off otherwise. Its spend is an ai_calls row (fact: "review.note"). A failed note is just absent (review.note.failed log) | | policies.act | ActPolicy | optional; typed, not validated by Zod (src/act.ts) | Your say over what the act lane does with a decided verdict, once every other guard has passed and just before it reads the authz grant: sign (optionally overriding the amount, where the collection's owner opted in — operatorAmounts), hold (parks the row chainStatus: "held" for a later signEvaluation), or skip (a clean no-op, same as AUTO_SIGN off). Absent ⇒ the lane signs on its own, as today. Full ActContext field list in the @ixo/decision-oracle/runtime section (§1) | | facts | FactsConfig \| FactsProducer | carried through untouched | Absent ⇒ the stock lanes for everything | | archive | ArchiveHooks | optional; typed, not validated by Zod | How the answer archive (ANSWERS_ARCHIVE) reads your asks and answers. describe(ask: ArchiveAsk) => Partial<ArchiveAbout> (may be async): ask is { askId, entity, alsoKnownAs, collection, docs, docsOf(did) } — the chain collection as Blocksync returns it, the entity's LinkedResources and settings as { id, type, json, error? } (up to 12, 256 KB each, proof-checked by readLinkedDoc), and the same read for another entity; return any of title, question, kind (photo · observation · url-check · other), place {name?, lat?, lon?, radiusM?}, reward {amount, denom}, postedBy {name?}, opensAt, closesAt — askId and proof are always the chain's. answer({ body }) => ArchiveAnswerView: { text?, place?: {lat, lon, accuracyM?, at?} }, exact. Absent ⇒ the #pro name (else alsoKnownAs), the collection's window and approval pay, nothing else (guide §12) | | openhands | OpenhandsOptions | optional; typed, not validated by Zod | Present ⇒ this oracle is an OpenHands checker: it answers the OpenHands app's hire and scan webhooks, mints its own evaluate grant under each poster's meta-grant, and keeps every hired ask judging (see "The OpenHands add-on" below). openhands: {} is the default; absent ⇒ none of it runs and /v1/info has no openhands |

Validation runs at module evaluation, not per request: a bad minAmount or an empty name fails the isolate loudly. facts rides through Zod untouched — the TypeScript type is its contract.

defineOracle also registers the config in a one-per-isolate registry. Calling it twice with two different config objects throws defineOracle() was already called — one oracle per worker; re-evaluating the same module (bundlers, test pools) is harmless, because the check is on the identity of the object you passed. Reading the registry before any defineOracle call throws defineOracle() was never called — export it from your worker entry.

The OpenHands add-on

An OpenHands ask is one deed entity plus one claim collection, posted by the OpenHands app for a person or an agent. When the poster picks your oracle, their posting transaction grants your ORACLE_ADDRESS a meta-grant (CreateClaimAuthorizationAuthorization, EVALUATE) — the right to hand itself the collection's EvaluateClaimAuthorization once the collection exists — and the app calls POST https://<your host>/openhands/hire/<collectionId>. With openhands set, the oracle then runs the hire (OpenhandsHire, one durable instance per collection, the instance id = the collection id):

1. verify — the collection on chain, your admit hook, and a live meta-grant the collection's admin signed naming itself (a grant anyone else signed is never minted under). No grant ⇒ the run ends; nothing is signed.
2. mint — MsgExec(MsgCreateClaimAuthorization) as this oracle: the poster's quota (an uncapped grant mints 10 000 verdicts at a time), the poster's payout ceiling verbatim (none ⇒ your maxCustomAmount, else none, so the collection's own approval payment pays), lasting until the ask's end + 90 days (never past the meta-grant). Skipped when the chain already holds a matching grant with ≥ 50 verdicts left.
3. register — the same four gates as POST /v1/collections/register (protocol, fee and all), as the oracle's own principal, scanning from claim zero. A collection already watched is never re-registered (an operator's pause stands).
4. scan — the claims filed before the hire, started now.

A backstop runs every five minutes so a lost webhook never strands an ask: it finds meta-grants whose collections are not watched yet and hires them, re-mints a watched collection whose poster raised the ceiling or whose quota fell below 50, and lifts an engine-no-grant pause once the chain shows quota again (at least 5 min after the last read — the engine's grant cache). Its window reads only the watched collections that can need it — never read, hired or claimed in the last day, quota below a top-up, or not read for a week — so a quiet ask costs one read a week (a raised ceiling on one arrives by the hire webhook, or within that week). Each collection gets at most three hire reruns a day from the backstop and three from the webhook, on separate budgets. POST /openhands/scan/<collectionId> scans a watched collection at once (at most once a minute; extra calls are scanned on the next minute tick). A scan that starts nothing — usually because Blocksync has not indexed the claim yet — is looked at again on each of the next three minute ticks, and no webhook scan moves the collection's place in the rotation. GET /v1/info advertises both paths under openhands, which is how the OpenHands app tells a checker from any other oracle.

OpenhandsOptions (all optional):

Bindings, with openhands on: the HIRE_WORKFLOW workflow (class OpenhandsHire) and, outside ENVIRONMENT=development, the OPENHANDS_RATE_LIMITER ratelimit — unbound there, both webhooks answer 503 (fail closed). decision-oracle init --openhands writes both. State lives in two tables of your DB (openhands_state, openhands_hires, shipped migration 0025_openhands).

The whole-producer escape hatch

facts also accepts a single function, for the one case a per-name table cannot express — you assemble the whole answer yourself:

facts: async (claim, expected, deps) => ({ ext: {…}, ai: {…} }),

It is structural (the type has no exported name): expected is the manifest, deps carries config, logger, ctx, settings, engine, db, env, and the return type is ProducedFacts (nameable from ./testing). A whole-producer replaces the runner's wiring, so none of §7's guarantees apply to it — prefer defineFacts.

3. defineFacts({ ext, ai, groups, unique, frequency })

// src/facts/index.ts
import { defineFacts, group } from "@ixo/decision-oracle/facts";
import { deliveryConfirmed } from "./deliveryConfirmed";
import { workScores } from "./workScores";

export const facts = defineFacts({
  ext: { deliveryConfirmed },          // unlisted ⇒ the STOCK ext lane
  ai: { "*": (_input, tools) => tools.stock() },  // "*" ⇒ every check you did not name
  groups: [group(["quality", "price"], workScores)],  // ONE call answers both names
});

Every field is optional; defineFacts fills the gaps (ext: {}, ai: {}, groups: []) so the runner never branches on undefined.

A table is a DIFF against stock, never a replacement of it. A handler for a name the manifest does not declare produces nothing and logs facts.handler-unused once — a renamed rubric entry shows up as that warning, not as a broken build.

One name, one handler. A name listed in ext and claimed by a group — or claimed by two groups — throws at module evaluation (defineFacts: 'quality' is answered twice …), because the alternative is a fact whose value depends on which lane wrote last.

4. Handlers

type ExtHandler       = (input: ExtInput,       tools: ExtTools)  => Promise<ExtResult>       | ExtResult;
type AiHandler        = (input: AiInput,        tools: AiTools)   => Promise<AiResult>        | AiResult;
type GroupHandler     = (input: GroupInput,     tools: FactTools) => Promise<GroupResult>     | GroupResult;
type UniqueHandler    = (input: UniqueInput,    tools: FactTools) => Promise<UniqueFact>      | UniqueFact;
type FrequencyHandler = (input: FrequencyInput, tools: FactTools) => Promise<FrequencyFact>   | FrequencyFact;

Synchronous handlers are fine — every signature accepts a value or a promise.

What every handler is handed (FactInputBase)

ExtHandler — one external source

ExtInput adds:

Return: boolean · an integer number (basis points 0–10000, for expect: "score") · fact.ok(...) · fact.error(...).

import { type ExtHandler, fact } from "@ixo/decision-oracle/facts";

export const deliveryConfirmed: ExtHandler = async ({ send, expected }, tools) => {
  const res = await tools.http.json<{ status?: string }>(expected.endpoint, {
    method: "POST",
    body: { reference: send.reference },
    timeoutMs: expected.timeoutMs ?? 5000,
  });
  if (res.status === null || res.status >= 500) {
    throw fact.retryLater(`courier unavailable (${res.status ?? "no response"})`);
  }
  if (!res.ok) return fact.error(`courier answered ${res.status}`, { transcript: res.transcript });
  return res.body?.status === "delivered"; // a plain boolean ⇒ an `ok` fact
};

A score source returns integer basis points, never a float and never a percentage:

export const onTimeRate: ExtHandler = async ({ expected }, tools) => {
  const res = await tools.http.json<{ on_time_pct?: unknown }>(expected.endpoint);
  const pct = res.body?.on_time_pct;
  if (!res.ok || typeof pct !== "number") return fact.error(`courier answered ${res.status}`);
  return fact.ok(Math.round(pct * 100), { reason: `${pct}% on time` });
};

AiHandler — one AI check

AiInput adds name, check: ManifestAi (expect: "boolean", onError, instructions, send, usedBy), send, unresolved, and:

Return: boolean · fact.ai.ok(...) · fact.error(...).

The common shape is a guard in front of the stock judge — tools.stock() is typed as this lane's own fact, so it needs no cast:

import { type AiHandler, fact } from "@ixo/decision-oracle/facts";

export const handoverPhotoLooksReal: AiHandler = async (_input, tools) => {
  if (tools.attachments.on("handoverPhoto").length === 0) {
    // Never `false`: that would claim a model looked at a photo and found it fake.
    return fact.error("the claim carries no handoverPhoto attachment");
  }
  return tools.stock();
};

Your own judge, your own rules, your own model:

export const photoShowsHandover: AiHandler = async ({ name, check }, tools) => {
  const images = tools.ai.inputsFor(check).filter((entry) => entry.kind === "attachment");
  if (images.length === 0) return fact.error(`${name}: the claim carries no image to judge`);
  const { JUDGE_MODEL } = tools.env as typeof tools.env & { JUDGE_MODEL?: string };
  return tools.ai.judge(
    [...check.instructions, "The parcel must be in the recipient's hands, not on a doorstep."],
    images,
    JUDGE_MODEL ? { model: JUDGE_MODEL } : {},
  );
};

GroupHandler — several sources, one call

group(["quality", "price"], handler) in defineFacts({ groups: [...] }) takes those ext names over and answers them from one call. The case it exists for: four criteria judged by a single structured model call. As four single handlers that is four completions for one judgment; as a group it is one — and it is the sanctioned way to share a call between facts (a private cache inside a handler still is not; the runner's own fact cache is the only cache).

AI checks cannot currently be grouped; group() answers ext sources only.

GroupInput is FactInputBase plus:

Return: Record<name, ExtResult> — one fact per name, each of them anything a single ext handler may return (boolean · integer basis points · fact.ok(...) · fact.error(...)).

import { type GroupHandler, fact } from "@ixo/decision-oracle/facts";

export const workScores: GroupHandler = async ({ names, answers }, tools) => {
  const res = await tools.http.json<{ quality?: unknown; price?: unknown }>(
    "https://judge.example/score",
    { method: "POST", body: { summary: answers.workSummary }, timeoutMs: 45_000, attempts: 2 },
  );
  // One call, one failure: every name it owed becomes an error carrying the rubric's own `onError`.
  // Never a neutral score for a judgment that was never made.
  if (!res.ok) {
    const failed = `judge answered ${res.status ?? "nothing"}`;
    return Object.fromEntries(names.map((name) => [name, fact.error(failed)]));
  }
  const bps = (v: unknown, what: string) =>
    typeof v === "number" ? fact.ok(Math.round(v * 100)) : fact.error(`judge scored no ${what}`);
  return { quality: bps(res.body?.quality, "quality"), price: bps(res.body?.price, "price") };
};

The runner holds a group to exactly the rules a single handler meets, per name: each fact carries its own declaration's onError, each is cached on its own, and a throw freezes every name the call owed (only fact.retryLater() still gets out). On top of that:

• A name you leave out is that name's own error — handler returned no fact for <name> with the rubric's onError. Silence is not an answer and never reads as one.
• A name nobody asked for is dropped with one facts.group-extra-fact warning: a name the rubric does not declare, or one already answered from the cache. Nothing is overwritten.
• The group is one slot in the fan-out cap, not one per name — the cap counts the call, which is what costs money.
• tools.stock() throws inside a group. It could only mean "the stock lane for which of these names", so a grouped name's lane is the group; leave a name out of the group to keep its stock lane.

UniqueHandler — the duplicate fact

UniqueInput adds rule: UniqueRule, the manifest's declaration with the engine's own defaults already applied:

What the stock lane counts as a prior claim: every claim this oracle registered for the collection before this one (ingest order, so a later copy never flags the original when the original's evaluate step retries), whose verdict countPrior lists, or that is still waiting for one. A claim that never reached a decision (a facts-lane outcome such as invalid_facts, a content refusal, an unusable rubric, an ingest that failed or ran out of retries) is marked void and never counts, so an honest resubmission of the same evidence is not its duplicate. The same filter applies to every lane: exact digest, attachment CID, perceptual hash and near text.

Who submitted it decides the exact-digest score: the SAME submitter repeating a claim scores 10000 (exact_body, the reject band), another submitter's copy 8800 (exact_body_cross_agent, review: a front-run copy is held for a person, never auto-rejected). The submitter is the chain claim's agent address, or the API claim's submitter (keyed as its HMAC digest, the same key the frequency count uses, so it survives erasure). Unknown on either side ⇒ different submitters.

Return the wire shape (§9): ruleId, digest, scoreBps, band are what the engine reads; anything else you add rides loose into its trace. tools.stock() throws here by design — a custom unique handler replaces its lane wholesale.

import type { UniqueHandler } from "@ixo/decision-oracle/facts";

export const unique: UniqueHandler = async ({ rule, claim }, tools) => {
  const res = await tools.http.json<{ digest?: unknown; scoreBps?: unknown }>(
    "https://registry.example/duplicates",
    { method: "POST", body: { claimId: claim.claimId, collectionId: claim.collectionId } },
  );
  const digest = res.body?.digest;
  if (!res.ok || typeof digest !== "string") {
    // A registry we could not reach is never a pass.
    return { ruleId: rule.id, digest: "registry-unavailable", scoreBps: 0, band: "review" };
  }
  const scoreBps = typeof res.body?.scoreBps === "number" ? res.body.scoreBps : 0;
  return {
    ruleId: rule.id,
    digest,
    scoreBps,
    band:
      scoreBps >= rule.thresholds.rejectAtBps
        ? "reject"
        : scoreBps >= rule.thresholds.reviewAtBps
          ? "review"
          : "pass",
    vendor: "registry.example", // extra fields ride into the engine's trace
  };
};

band is the branch the engine takes: pass is silent, review downgrades the decision to a human review, reject fails the claim. It is a closed enum — a typo fails validation here rather than misrouting there.

FrequencyHandler — the submission-rate fact

FrequencyInput adds rule: FrequencyRule | null:

rule is null when the manifest declared the rule without max/per. The stock lane is never asked in that case (the build is refused as FACT_MISSING "manifest lacks max/per"); a custom handler still is, because it may know the limit another way.

import { fact, type FrequencyHandler } from "@ixo/decision-oracle/facts";

export const submissionRate: FrequencyHandler = async ({ rule, manifest, claim }, tools) => {
  const ruleId = rule?.id ?? manifest.frequency?.ruleId ?? "frequency";
  const max = rule?.max ?? 0;
  const per = rule?.per ?? "day";
  const res = await tools.http.json<{ count?: unknown }>(
    `https://ledger.example/claims?agent=${claim.metadata.agentAddress ?? ""}&per=${per}`,
  );
  // An outage is not an answer: `unresolved` is a final reject on the engine, so retry instead.
  if (!res.ok) throw fact.retryLater(`ledger answered ${res.status}`);
  const count = res.body?.count;
  if (typeof count !== "number") {
    // `unresolved` is its own state — the engine fails it closed, never reads it as headroom.
    return {
      ruleId, count: 0, max, per,
      windowStartISO: null, windowEndISO: null,
      breach: false, unresolved: true,
    };
  }
  return { ruleId, count, max, per, breach: count > max };
};

count includes the claim under evaluation (it is on chain by the time it is judged), so breach is count > max. Windows are UTC calendar periods; weeks are ISO weeks (Monday 00:00 UTC), derived from the claim's own on-chain submissionDate — never from evaluation time. The rubric's Frequency declaration has no time-zone field, so there is no local day: "30 a day" means 30 per UTC day by chain submission time (a Sydney courier's working day spans two UTC days).

The stock lane freezes unresolved only when the window cannot be counted at all — the claim has no submitter, or no usable on-chain submissionDate. A count that cannot be read (Blocksync down, a 5xx, a timeout, an error payload) throws unavailable and the workflow step retries: the engine rejects an unresolved fact for good, and an outage is not evidence. A custom handler owes the same: throw fact.retryLater(...) on trouble, unresolved only for a deterministic miss.

What a return becomes

5. fact helpers

fact.ok(
  value: boolean | number,
  extra?: { reason?: string | null; confidence?: number; transcript?: Transcript },
): ExtFact

fact.ai.ok(
  value: boolean,
  extra?: {
    reason?: string | null;
    failedRules?: string[];
    score?: number;
    confidence?: number;
    transcript?: Transcript;
  },
): AiFact

fact.error(detail: string, extra?: { transcript?: Transcript }): FactErrorDraft

fact.retryLater(detail: string): RetryLater   // `throw` it

fact.error takes no onError and there is no way to pass one. The runner stamps the manifest's own value over whatever a handler produced, in both directions. That is the invariant the whole design rests on: a handler can never turn its own failure into an approval.

6. FactTools

Built per fact and injected, so stock() means "the stock lane for this fact". The type parameter is which fact that is: ExtTools = FactTools<ExtFact> in an ext handler, AiTools = FactTools<AiFact> in an ai one — which is why return tools.stock() type-checks with no cast. unique/frequency handlers see the bare union, and there stock() throws.

tools.stock(): Promise<ExtFact | AiFact>

Runs this fact's stock lane with exactly the input the runner would have handed it, and normalizes the answer the same way. Wrap it, fall back to it, or ignore it — but never call it and the declared endpoint yourself: that is two calls, and two charges, for one fact.

In a unique/frequency handler it throws AppError.internal explaining that such a handler replaces the lane wholesale.

const base = await tools.stock();
if (base.status === "error") return fact.error(`stock lane: ${base.detail}`);
return base;

tools.http.json<T>(url, init?): Promise<HttpJsonResult<T>>

interface HttpJsonInit {
  method?: "GET" | "POST";       // default "GET"
  headers?: Record<string, string>;
  body?: unknown;                // POST only — sent as JSON with a content-type
  timeoutMs?: number;            // default 15_000, per attempt
  attempts?: number;             // default 3
  // Sign the call as this oracle, for THE HOST OF `url` (audience did:web:<host>, never named by
  // you): `true` ⇒ { can: "*", with: "ixo:external-source" }; `{ capability }` ⇒ yours
  ucan?: true | { capability: { can: string; with: string } };
}
interface HttpJsonResult<T> {
  ok: boolean;                   // a 2xx on the last attempt
  status: number | null;         // null = NO HTTP response at all on any attempt
  body: T | null;                // the parsed JSON, null when absent or not JSON
  transcript: Transcript;        // hand it back on the fact
}

• Never throws for an HTTP outcome. A 404 and a 500 come back as results, because only the handler knows whether a 404 means "no such batch, so false" or "unanswerable".
• Retry budget: up to attempts, exponential backoff (1 s, 2 s, …), a ~30 s whole-budget cap. A 5xx, a 408 or a 429 burns an attempt and retries; any other 4xx ends the loop on the first answer (the same request gets the same answer, so ok: false, that status, attempts: 1). Pass attempts: 1 for one shot even on a 5xx.
• SSRF guard: the URL is held to assertPublicHttpUrl (http/https only; localhost, private IPv4/IPv6 ranges and internal suffixes refused) because a handler's URL often comes from a claim answer. A refusal is an outcome — { ok: false, status: null, attempts: 0 } — not a throw. Redirects are followed by hand, at most 3, each hop held to the same guard; a hop to a private host, an https → http downgrade or a malformed Location ends the call as status: null, never retried. A hop to another origin carries none of your headers but accept and content-type — no authorization, no vendor key like x-api-key, no idempotency key — so a UCAN minted for one host, or a secret meant for one API, never reaches another. The whole call, redirects included, stays inside the ~30 s budget.
• ucan: signs the call as this oracle (below, "How an external source is called") for the URL's own host. This is the way to call a source that authenticates you: the audience cannot drift from where the token goes.
• Transcript: the last attempt's request and response, the attempt count and elapsed ms. Credentials never reach it. A header is dropped when its name ends in key (x-api-key, apikey, X-RapidAPI-Key, Ocp-Apim-Subscription-Key, api_key …) or contains authorization, token, secret, password, credential or signature (proxy-authorization, cf-aig-authorization, x-auth-token …), and cookie / set-cookie always go; idempotency-key is kept. In the recorded URL, the value of a query parameter whose name contains key, token, secret, password, signature, sig, auth or credential becomes [redacted] (?api_key=[redacted]); the names and the rest of the URL are kept. A response body over 64 KiB is recorded as { truncated: true, bytes, sha256 } — the result's own body is still whole. Name the response type or body is unknown.

Signing a call as this oracle: http.json(url, { ucan })

A self-signed UCAN invocation from this oracle's did:web:<ORACLE_HOSTNAME> to the did:web of the host url names, minted per http.json call (300 s TTL, a nonce, never cached — the same token rides that call's retries and same-origin redirect hops) and sent as authorization: Bearer <token> + x-auth-type: ucan. ucan: true signs { can: "*", with: "ixo:external-source" } — exactly what the stock connector presents, so a handler calling a source by hand looks identical to it. Pass your own capability when your API wants one; it is yours, set in code — never expected.capability (the rubric's, which the oracle ignores; see below).

const res = await tools.http.json(expected.endpoint, {
  method: "POST",
  ucan: true,
  body: { ...send, claimBody: answers },
});

// Your API scopes its callers? Name the capability it checks — in YOUR code:
await tools.http.json("https://api.example/shipments", {
  ucan: { capability: { can: "shipments/read", with: "did:web:api.example" } },
});

An IXO service capability — any ixo: resource other than exactly ixo:external-source, or any resource with whitespace or a control character in it — is refused with a plain Error. The runner freezes that as an error fact carrying the rubric's onError (facts.handler-threw): a deterministic negative, recorded, never a retry.

tools.http.ucanHeaders(audience, capability?): Promise<Record<string, string>>

The same token as a header pair, for a call you make yourself — kept for compatibility. The audience must be the did:web of the host you send it to; nothing checks that for you, so prefer http.json(url, { ucan }), which binds it. The same capability default and the same refusal apply.

How an external source is called

What the stock ext lane (and a handler calling http.json(endpoint, { method: "POST", ucan: true, … })) sends, so the API behind a source knows what to expect:

• Request: POST <endpoint> with a JSON body — the rubric's send map resolved against the claim ($path answers, ctx.* values, literals) plus the whole credentialSubject under the reserved claimBody key (a send entry of that name loses).
• Headers: Authorization: Bearer <UCAN>, X-Auth-Type: ucan, Idempotency-Key: <claimId>:<name> — a retry of the same fact carries the same key.
• The UCAN: issued by this oracle's did:web:<ORACLE_HOSTNAME>, audience the endpoint's own did:web (did:web:<endpoint host>, a :port percent-encoded as %3A), capability { can: "*", with: "ixo:external-source" } by default or the one your handler passes, a 300 s expiry and a nonce (every token is unique).
• Redirects: followed at most 3 times, each hop re-checked against the public-host guard (no https → http downgrade); a hop to another origin carries only accept / content-type — never the Authorization or Idempotency-Key. The token is one per fact's call: its retries and same-origin hops reuse it.
• What the API may verify: the issuer's key from https://<ORACLE_HOSTNAME>/.well-known/did.json, that the audience is itself, and the expiry — and, if it keeps a list, which oracles it answers. It may equally ignore the token and answer anyone; the capability is a label the oracle's developer chose, not a grant anyone else issued.
• Response: 200 with { "valid": boolean } (expect: "boolean") or { "score": 0..10000 } (an integer, expect: "score"), optional reason. A 5xx, 408, 429, network error or contract miss is retried in the call (3 attempts, ~30 s, a Retry-After honoured when the budget allows). Down is not "no": if the last attempt was still a 5xx, 408, 429 or no answer at all, the lane throws unavailable and the workflow step retries (about 4 hours of backoff), so an outage never becomes a decision. Only a definitive answer becomes an error fact carrying the rubric's onError: any other 4xx (one call), or a malformed or off-contract 2xx. On the step's last attempt an outage that is still there freezes as that error fact too, so it is bounded.

The rubric's capability is ignored, and the audience is bound to the endpoint. A rubric belongs to the protocol — written by its owner and shared by every oracle serving it — so it may say where to call and what to send, never what this oracle's key grants. The key's grants are its holder's: the stock lane always signs ixo:external-source, logs ext.source.capability-ignored (warn) when the manifest declares one, and signs only when audience is exactly the endpoint's own did:web. A mismatch signs and sends nothing: the fact is error with the rubric's onError and the detail the source's audience … must be the endpoint's own did:web … (transcript attempts: 0). decision-oracle protocol review and rubric validate print both findings per source, and exit 1 on a refused source; facts scaffold writes no stub for one — the rubric is what has to change.

No IXO service capability ever leaves for an external call. The engine and the payment facilitator accept a token self-signed by this oracle's did:web as this oracle, so a capability on ixo:eval-engine, ixo:ixo-pay-facilitator, ixo:eval-oracle, ixo:oracle/… or any other ixo: resource except ixo:external-source is refused by the stock lane, http.json({ ucan }) and ucanHeaders alike — as an error fact with the rubric's onError, never a crash. The check becomes redundant once those services accept oracle authority only from the oracle itself; it stays until then.

tools.ai.judge(instructions, inputs, opts?): Promise<AiFact>

The stock judge with your rules: the configured AI provider, a static compliance-evaluator prompt with your numbered ruleset appended, the typed inputs last, strict structured output.

• Policy gate: settings.allowAiChecks === false ⇒ returns error / ai-checks-disabled with no model call. Never approve on a check that did not run.
• Strictness is your rules': the prompt judges each rule exactly as its text states it and adds no rule of its own. A rule that says to be lenient (a dim photo is still evidence, let doubt lower the score rather than fail) is judged leniently; a rule that says to fail on doubt fails on doubt; a rule silent on it fails when the inputs do not show what it requires. A check for screens, prints or generated images runs only where one of your rules asks for a real photo.
• Model: opts.model overrides the pinned AI_CHECK_MODEL.
• Images: sent at the pinned AI_IMAGE_DETAIL (default high), and the transcript records it.
• Provider: AI_PROVIDER — the Cloudflare AI Gateway (the AI binding + AI_GATEWAY_ID) by default, OpenRouter with OPENROUTER_API_KEY. Either way the call carries reasoning.effort = AI_REASONING_EFFORT (default low). A missing piece throws AppError.internal — loud, so the step retries rather than freezing a verdict on a config fault.
• Audio/video: sent only with AI_AUDIO_VIDEO=true (OpenRouter only); otherwise each such attachment reaches the model as a "content not sent" descriptor.
• Idempotency: each call is keyed ${claimId}:${factName}#${n}, where n counts calls within one fact's tools. The counter restarts with the tools, so a step retry replays the same keys, and two calls under one name can never collide on the provider's cache.
• Three outcomes per rule: the strict schema is { failed_rules, undeterminable_rules, reason, valid, score }. A rule the readable evidence refutes fails; a rule the model cannot judge either way because an input is too blurred, dark, cropped, truncated or not sent — even read the way your rules say to read it — is undeterminable. Any undeterminable rule makes the fact an error (the rubric's onError, detail undeterminable: R1 (<rule text>) — <model reason>), never valid: false, even when another rule failed: an unreadable photo is not evidence that the work was not done.
• Comparison guidance: when two or more images reach the model (a before/after pair), the prompt adds a COMPARISON section: changes the work or the moment cause (dirt or growth removed, a colour revealed by cleaning, repairs, light, colour cast, angle, crop) are expected and never by themselves mean a different subject; sameness is judged from what the work cannot change (shape, structure, fixed markings, fittings, surroundings). Rubric authors no longer need to write that into each rule.
• Verdict: valid is derived in code from failed_rules (the model's own valid is ignored); score is clamped 0–100; a score below AI_CHECK_MIN_CONFIDENCE (default 60) is the unreachable path (an error fact), never a trusted verdict. So is any non-2xx, unparseable body, schema miss or empty completion. A 5xx, 408, 429, network error, malformed answer or a score below the floor is retried (each attempt a fresh sample, and a fresh paid call); any other 4xx ends the loop after that one call. A 5xx, 408, 429, network error or AI Gateway credits exhausted that is still there after the in-call attempts THROWS unavailable (the workflow step retries; the fact cache keeps every answer already paid for), and freezes as the error fact only on the step's last attempt.
• onError: inherited from the AI check being answered; "review" anywhere else.
• Timeout: 60 s per attempt for image and text inputs, 3 minutes when a PDF, video or audio input rides along (a PDF page is 10–30× an image's tokens), under the same 3-attempt budget. On the gateway an attempt past its deadline is aborted, and the gateway gets its own deadline 2 s sooner (cf-aig-request-timeout), so the provider call ends too.
• The transcript freezes the model id, the recorded request (attachments as CID + digest, never base64), the raw response, the provider's call id as genId (OpenRouter's generation id, or the gateway log id) and usage. usage (tokens + USD) is set only when the provider reports cost at call time (OpenRouter); on the gateway it is null and the USD of every billed attempt (a retry included) lands in the ai_calls table within ~5 minutes (cron ai-cost-backfill, from the gateway's log). A log not found for an hour, or with no price, is closed unavailable; the log API failing pauses the job without closing anything, unless it has refused a row for a day. unique.aiCostUsd is omitted when no judged pair has a known cost — never a fake 0.

return tools.ai.judge(["The photo shows a sealed parcel"], input.inputs);

tools.ai.inputsFor(check): AiSendEntry[]

The declared send map as the judge's typed, ordered entries — what AiInput.inputs already is, exposed so you can re-slice it (drop the text, keep the images, reorder, add your own).

const images = tools.ai.inputsFor(input.check).filter((e) => e.kind === "attachment");

tools.attachments

on(question: string): Attachment[];
bytes(att: Attachment, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<AttachmentBody>;
size(att: Attachment): Promise<number | null>;

• on filters claim.attachments by the root question name — "deliveryPhoto", not "$deliveryPhoto". Use rootQuestionName("$deliveryPhoto.0") to get one from a $ref.
• bytes defaults maxBytes to 10 MiB — the same cap the AI lane uses, deliberately, so a handler reading a file itself never quietly gets a different limit. content-length is checked before the body is read, and the cap holds while it is read: a body streamed without a length (the VFS) stops at the cap, and its size is then maxBytes + 1 — a lower bound, never counted further. Returns { ok: true, bytes } · { ok: false, reason: "too-large", size } · { ok: false, reason: "unfetchable" }. "Too large" and "could not be read" are different answers: the first is a known file you can still describe, the second taught you nothing.
• size reads content-length without consuming the body. A store that answers 200 with no content-length (the VFS streams its files, so the header never arrives) has its body counted instead, up to 25 MiB. null on any failure, an empty body, or past that cap — and null is what the engine's null rule then decides on.
• The store's auth (the bot UCAN, or a fresh single-use VFS token per request) is sent only to that store's host; a data: URL carries its own bytes. bytes and size follow at most 3 redirects, each hop held to the public-host guard (no https → http downgrade), and a hop to another origin carries none of the store's auth; a refused hop is unfetchable / null.

const [photo] = tools.attachments.on("handoverPhoto");
if (!photo) return fact.ok(false, { reason: "no handover photo on the claim" });
const body = await tools.attachments.bytes(photo, { maxBytes: 5_000_000 });
if (!body.ok) return fact.error(`photo could not be read: ${body.reason}`);

tools.c2pa.screen(bytes, mediaType?): Promise<Provenance | null>

Reads C2PA "Content Credentials" off image bytes and verifies the certificate chain against the official trust list. Returns null on anything inconclusive — no manifest (the common case: a screenshot strips it), unreadable bytes, any internal error. Fail-safe by construction: it can only ever add a rejection.

Provenance is { vendor, issuer?, model?, modelVersion?, aiGenerated, watermarked, signedAt?, trusted, failures[] }. trusted is the only thing that makes the rest mean anything — anyone can self-sign a manifest naming any issuer.

Note the asymmetry: policies.allowImageChecks gates the stock AI lane's provenance short-circuit, not this call. A handler that asks for the read gets it.

const provenance = await tools.c2pa.screen(body.bytes, photo.mediaType);
if (!provenance) return fact.ok(true, { reason: "no Content Credentials on the photo" });
return fact.ok(!(provenance.trusted && provenance.aiGenerated));

tools.chain — the chain, read-only

Deep imports are blocked by the package exports, so these reads ARE a handler's access to Blocksync and the chain. Generic on purpose: nothing here knows what an agent card is. The act lane (signing) stays the package's, never a handler's.

interface ChainTools {
  linkedResources(entityDid: string): Promise<LinkedResource[]>;
  claimIntent(params: {
    agentAddress: string;
    collectionId: string;
    before: string;
    after?: string;
  }): Promise<{ time: string; transactionHash: string } | null>;
  query(): Promise<QueryClient>;
}

• linkedResources(entityDid) — what an entity anchors on chain (#vct, #rub, a card…), each with its proof content hash. The same read the package's own rubric lane uses. To read one's bytes, hand it to readLinkedDoc (Vault, IPFS or Matrix, checked against that proof).
• claimIntent({ agentAddress, collectionId, before, after? }) — the newest MsgClaimIntent this agent filed on this collection before before (normally the claim's submission date), bare or authz-wrapped: a delivery clock and the tx hash to cite for it, or null when it filed none. Pass the agreement's consent time as after so an earlier engagement's intent can never become the clock.
• query() — the @ixo/impactxclient-sdk query client for this oracle's network (balances, grants, module state). The SDK is heavy, so it loads on first call and the client is memoised per isolate; a handler that never asks never pays for it.

There is no GENERAL message-history read, and a handler must not build one. claimIntent is the one lookup an oracle gets about what preceded a claim, and it is here so it stays ONE server-side filtered query: Blocksync leaves messages.from NULL on an intent, so the indexer matches the agent and collection inside the message's jsonb value (Postgres @>), bounds the time on the transaction, and returns at most one row. An intent filed through authz — what the portal and the boilerplate chain client both do — is nested inside a /cosmos.authz.v1beta1.MsgExec with an ARRAY value, and @> is type-exact inside the json (the indexer's spelling of collectionId is its own choice too), so each or arm carries its own typeUrl: two shapes × two id spellings, four arms, still one round trip. Paging the chain for anything is a bug, not a fact.

An empty answer is a fact; an unreachable indexer is not. [] means "this entity anchors nothing" and null means "this agent filed no intent" — answer on either. Blocksync being down throws AppError.unavailable, which the runner lets through as the workflow step's retry signal, so a chain outage retries instead of freezing a verdict. Catch it only when "could not read the chain" is genuinely the fact you mean, and then say so with fact.error.

// "Is the offer still the version we agreed to?" — an ext fact answered from the chain, not an
// endpoint. An entity that anchors nothing answers `[]`; a Blocksync outage throws and the step
// retries, so neither can read as a pass.
const cardUnchanged: ExtHandler = async ({ send }, tools) => {
  const { oracleEntityDid, cardProof } = send;
  if (typeof oracleEntityDid !== "string" || typeof cardProof !== "string") {
    return fact.error("the rubric's send map names no oracle entity / card proof to compare");
  }
  const card = (await tools.chain.linkedResources(oracleEntityDid)).find((r) => r.id === "#acard");
  if (!card?.proof) return fact.error(`${oracleEntityDid} anchors no readable #acard`);
  return card.proof === cardProof;
};

tools.agreement(counterparty?): Promise<Agreement | null>

The engine's buyer statement for this collection: { id, digest, counterparty, doc }, where doc is never interpreted by the package beyond its kind.

• Omit counterparty for the claim's own agent (claim.metadata.agentAddress) — the usual question.
• Pass an explicit null for the collection's own terms, the statement that names no counterparty. The two are different questions and do not collapse.
• Returns null (and warns facts.agreement-no-engine once per fact) when the build carries no engine client — tests and CLI dry runs.

Read it LAST, right before returning the fact it feeds: the engine records the snapshot current at decision time on its receipt, so reading it last is what makes the receipt name the version your facts actually used.

The agreement is read once per claim and shared. The kit memoises the read per build, keyed by the counterparty asked for, so five handlers calling tools.agreement() cost ONE engine round trip and — the part that matters — all judge against the same snapshot. That is the kit's cache, not a licence for a handler-private one: the runner's fact cache is still the only place an answer is kept.

tools.logger / tools.config / tools.env

• logger — structured (debug/info/warn/error, child()), landing in the oracle's Workers Logs stream. Never log answer values or claim.media.
• config — the validated Config: IXO_NETWORK, the eight resolved per-network URLs, hostnames, model and policy values. Secrets are on it too; do not log them.
• env — the step's worker env, so a handler can reach its own binding or secret. It is a getter that throws AppError.internal("tools.env: this build carries no worker env") in tests and CLI dry runs, where there is none — loud beats reading a binding off undefined three lines later.

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");

7. What the runner guarantees

One code path runs every handler, stock or yours, so these hold identically for both.

1. Normalization. A plain true / 8200 becomes an ok fact; a fact.error draft becomes a full error fact; a full fact passes through verbatim; anything else becomes an error fact that names the bad return.
2. Fail closed. An error fact carries the manifest's onError, stamped here, overriding whatever the handler put there. A throw is the same thing.
3. One retry signal. Only fact.retryLater() — and the package's own AppErrors, thrown by the stock lanes for a signing/config fault or an outage (the ext and AI lanes' 5xx / 429 / timeout / AI credits exhausted) — get out, as unavailable, so the workflow step retries instead of freezing a verdict. Every other throw is an error fact, logged facts.handler-threw. Bounded: on the evaluate step's last attempt a retryLater or an unavailable freezes as the rubric's onError (still unavailable on the last attempt: …, logged facts.retries-exhausted), so an outage that outlives every retry still ends as a decision, never as a dead ingest.
4. The fact cache. Every resolved ext/ai fact is written to this oracle's D1 as it lands and read back once, before any handler runs, on a later attempt of the same claim under the same rubric: a hit is returned verbatim — transcript, error status and all — and the handler never runs. So a crashed step never re-buys a paid AI or vendor call. A re-anchored #rub is a new work order: its facts run again, even the same-named ones. unique/frequency never cache: registry state and calendar windows must be fresh per attempt. Both sides are fail-soft — a cache error means "no cache", never a failed fact.
5. The fan-out cap. At most 4 ext+ai handlers in flight (MAX_CONCURRENT_CONNECTORS); the isolate allows 6 outbound connections and a 30-check rubric must degrade to "slower", not to a socket storm. unique/frequency run beside the pool, one read each. Do not add your own concurrency.
6. Unused names. A handler for a name the manifest does not declare is skipped with one facts.handler-unused { kind, name } warning — including a unique/frequency handler written for a rubric that declares no such rule.
7. ai["*"]. The wildcard catches every check not named in the table; a named handler wins.
8. Groups. A group([...], handler) runs once per claim and takes one slot in the cap; its grouped names never also run the single/stock lane. Every guarantee above then applies per NAME — own onError, own cache entry, a crash frozen on each — plus: a name the handler omitted is that name's handler returned no fact for <name> error, and a name nobody asked for is dropped with a facts.group-extra-fact warning. Two handlers for one name is a boot error.
9. Derived refs. The stock lanes refuse a send map naming a ~derived ref (an error fact with the rubric's onError, logged stock.derived-unsupported). A custom handler is not short-circuited: it gets the refs in unresolved and the expressions on manifest.derived.
10. Rule-less frequency. A frequency declaration without max/per is warned (stock.frequency-unrunnable) and omitted from the FactSet — unless you wrote a custom handler, which is asked with rule: null.
11. Coverage. validateFacts (§9) runs over the whole answer before anything is frozen.

And around the runner, in the build: ctx is resolved before any handler runs (one clock read, one Blocksync read), and after the FactSet is frozen there is no network, no clock and no AI anywhere downstream. That boundary is the replay guarantee a review fold depends on.

8. The work order — Manifest

What the engine's binder resolved the protocol's rubric to want, read from GET /v1/rubrics/manifest?protocol=<did> (public, KV-cached for 5 minutes). This oracle never parses a rubric — the manifest is the only work order, and bunx decision-oracle protocol review <did> prints it in plain words.

ManifestExt: expect ("boolean" ⇒ the fact's value is a boolean · "score" ⇒ an integer 0–10000), onError ("review" | "reject", always present), endpoint, audience (the source's did:web — it must be the endpoint's own, or the stock lane does not call it), capability? (the rubric's; ignored — the oracle's developer owns the capability), send, timeoutMs?, usedBy ("gate:<code>" / "criterion:<code>" — every rule whose bound deps read this fact).

ManifestAi: expect: "boolean" (v1 checks are yes/no only), onError, instructions (the plain-language rules — all must hold for a true), send, usedBy.

Every object is parsed loosely: the engine may add fields without a wire bump, so an unknown key is tolerated, never fatal.

The unusable answer. A rubric the engine cannot resolve or bind comes back as { status: "unusable", issues: [{ code, message, path }] } — a 200, not an HTTP error. That is recorded as the claim's outcome with no handler run and no decide call, and the collection is paused rubric-unusable. There is nothing to build against until the rubric or its #vct/#rub anchoring is fixed.

9. Wire facts, and what validateFacts refuses

These are the shapes that ride to the engine inside a FactSet v1. The FactSet itself is strict (the engine 400s on an unknown key) and is assembled by the package around your answer: version, frozenAt (identical to ctx.now), answers, attachments, ctx, ext, ai, unique?, frequency?, settings.

Coverage: FactIssue codes

validateFacts mirrors the engine's own fact-coverage check and runs before anything is frozen or sent, so a producer bug is loud here instead of a billed unusable there. runFacts returns the same issues.

A failed validation is recorded as invalid_facts for the claim and fails the ingest loudly. It is never sent.

10. Testing — @ixo/decision-oracle/testing

runFacts is the same runner production uses, minus the fact cache and D1, followed by the same validateFacts. issues: [] means the engine would accept this FactSet.

runFacts(facts, input)

interface RunFactsInput {
  claim: PulledClaim;      // sampleClaim(...)
  manifest: Manifest;      // sampleManifest(...)
  tools?: FactTools;       // default: fakeTools()
  ctx?: CtxFacts;          // default: sampleCtx()
  settings?: FactSettings; // default: { allowAiChecks: true, allowImageChecks: true }
  /** Per-lane replacements for what an unlisted name — and `tools.stock()` — runs instead. */
  stock?: Partial<{
    ext: ExtHandler;
    ai: AiHandler;
    unique: UniqueHandler;
    frequency: FrequencyHandler;
  }>;
}
// → Promise<ProducedFacts & { issues: FactIssue[] }>

Both policy lanes are open by default: a handler under test should run, not be gated by a policy the test never mentioned. Pass settings to exercise the gated path.

The default stock lanes: ext and ai both call tools.stock() (so fakeTools({ stock }) is what answers); unique throws no stock unique lane in tests — pass stock.unique or a facts.unique handler; frequency returns the fail-closed unresolved fact.

runFacts also binds tools.attachments.on and tools.ai.inputsFor to the claim you passed (they are pure functions of it, and fakeTools has no claim). Only the fakeTools stubs are replaced — an implementation you wrote yourself survives.

A groups entry runs here exactly as it does in production: declare every grouped name on the sampleManifest, assert each one's fact, and test the half that matters — the failed call, where one fact.error has to come back for every name the group owed.

fakeTools(overrides?)

Plus, always: logs: LogRecord[] collecting everything the handler logged ({ level, msg, data? }, in order); chainCalls: ChainCall[] collecting every tools.chain call in order ({ call: "linkedResources", entityDid } / { call: "claimIntent", params } / { call: "query" }), so a test can assert on the entity its handler read and on the intent query it asked (ClaimIntentQuery — { agentAddress, collectionId, before, after? }, exported from @ixo/decision-oracle/testing); a real config from the same Zod schema the Worker validates at boot (so tools.config.IXO_NETWORK is "devnet", not a stub with holes); and http.json(url, { ucan }) / http.ucanHeaders producing a readable fake token (Bearer fake-ucan-for-<audience>[-<can>-<with>], the audience did:web:<url host> for ucan) so a test can assert on the audience and capability its handler addressed — an IXO service capability throws there exactly as in production.

httpResponse(status, body) is a branded envelope — it exists precisely so that { body: "hello", sender: "bob" } reads as a body, not a status/body pair.

sampleClaim(answers, opts?)

network is "devnet", lane is "cellnode" and media is null (the no-store posture: nothing to fetch bytes from in a test), and the claim is an ordinary unpaid, non-escrow one.

sampleManifest(decl?)

Only expect (a source) and instructions (a check) must be given; everything else is the call detail the stock lane would need, which a handler under test usually ignores.

rubricId is 64 zeros, formProof is undrifted, hasAiChecks is derived from the ai keys.

sampleCtx(over?)

now: "2026-01-01T00:00:00.000Z", an empty collection window and an empty claim plane — one fixed instant, so digests repeat. Override any field.

Three worked tests

An ext handler over a canned route. Cover both halves — the answer, and the failure it will actually meet:

import { fakeTools, httpResponse, runFacts, sampleClaim, sampleManifest } from "@ixo/decision-oracle/testing";
import { facts } from "../src/facts";

const manifest = sampleManifest({
  ext: {
    deliveryConfirmed: {
      expect: "boolean",
      onError: "review",
      endpoint: "https://courier.example/deliveries",
      send: { reference: "$reference" },
    },
  },
});

it("answers ok when the courier says delivered", async () => {
  const out = await runFacts(facts, {
    claim: sampleClaim({ reference: "ABC" }),
    manifest,
    tools: fakeTools({
      env: { COURIER_API_KEY: "test-key" },
      http: { "https://courier.example/deliveries": { status: "delivered" } },
    }),
  });
  expect(out.issues).toEqual([]);
  expect(out.ext.deliveryConfirmed).toMatchObject({ status: "ok", value: true });
});

it("answers error — never false — when the courier sends a body it cannot read", async () => {
  const out = await runFacts(facts, {
    claim: sampleClaim({ reference: "ABC" }),
    manifest,
    tools: fakeTools({
      env: { COURIER_API_KEY: "test-key" },
      http: { "https://courier.example/deliveries": httpResponse(422, { detail: "bad ref" }) },
    }),
  });
  expect(out.ext.deliveryConfirmed).toMatchObject({ status: "error", onError: "review" });
});

An ai handler that forwards to stock. Can the stock lane, so the forward proves something — and test the guard with a stock lane that would have said yes:

const manifest = sampleManifest({
  ai: {
    handoverPhotoLooksReal: {
      instructions: ["The photo shows an original handover, not a screenshot"],
      onError: "review",
    },
  },
});

it("hands a claim that carries a photo to the stock lane", async () => {
  const out = await runFacts(facts, {
    claim: sampleClaim({ reference: "ABC" }, {
      attachments: [{
        question: "handoverPhoto",
        name: "handover.jpg",
        mediaType: "image/jpeg",
        url: "https://media.example/handover.jpg",
      }],
    }),
    manifest,
    tools: fakeTools({ stock: fact.ai.ok(true, { reason: "reads as original", score: 90 }) }),
  });
  expect(out.issues).toEqual([]);
  expect(out.ai.handoverPhotoLooksReal).toMatchObject({ status: "ok", value: true, score: 90 });
});

it("guards the missing photo before the judge is ever reached", async () => {
  const out = await runFacts(facts, {
    claim: sampleClaim({ reference: "ABC" }),
    manifest,
    tools: fakeTools({ stock: fact.ai.ok(true) }),
  });
  expect(out.ai.handoverPhotoLooksReal).toEqual({
    status: "error",
    onError: "review",
    detail: "the claim carries no handoverPhoto attachment",
  });
});

A custom unique lane. Declaring the rule is what makes the runner ask for the fact:

const manifest = sampleManifest({ unique: { ruleId: "no-double-claims" } });

it("bands a vendor score against the rule's own thresholds", async () => {
  const out = await runFacts(facts, {
    claim: sampleClaim({ reference: "ABC" }),
    manifest,
    tools: fakeTools({
      http: { "https://registry.example/duplicates": { digest: "d1", scoreBps: 6000 } },
    }),
  });
  expect(out.issues).toEqual([]);
  // Defaults from the engine's own schema: reject ≥ 9000, review ≥ 5000.
  expect(out.unique).toMatchObject({ ruleId: "no-double-claims", band: "review" });
});

11. Configuration

Bindings (OracleBindings) — names are the contract, never rename one

Your own bindings ride alongside — the type is open (OracleEnv & YourEnv); only the names above are reserved.

Vars and secrets (OracleVars)

Non-secret vars live in wrangler.jsonc vars, redeclared per named environment (named envs inherit no bindings or vars). Secrets live in .dev.vars locally and wrangler secret put <NAME> once deployed. Every value is validated by Zod at isolate start, so a bad env fails loudly and early.

After any binding or var change: bun run cf-typegen.

The identities behind those vars

Four identities, three of which have on-chain or homeserver state that the vars alone do not create. decision-oracle oracle init is what creates that state, once per network — thirteen idempotent steps (fund, iid, key, matrix, entity, orz, profile, domain, acard, linked, service, backlink, index), a dry run unless --yes, --only <step> for one. Only iid, key and matrix need the oracle's own mnemonics; the rest run on the AuthHub session and the public vars. A full on-chain identity is mandatory: the entity, its #pro profile, its #dmn domain card and its #acard Agent Card (validated against the engine's Agent Card schema). --logo <url> is optional and recommended — without it the portal and the console show a placeholder. --openhands adds a check-openhands service to the Agent Card (the OpenHands app's checker marker), priced in PAY from /v1/info's pricing.api for --protocol, else --price-pay <n> (1 PAY = 1 USD).

Where the documents live. Every document the CLI anchors — oracle init's #orz, #pro, #dmn, #acard, publish-protocol's #vct / #rub / #pro (--name), org create's #pro — is stored on the IXO Vault (POST <vfs>/api/fs/files?public=true under a one-write fs/write UCAN from the AuthHub session's Ed25519 key, the entity owner) and anchored by its public, unauthenticated <vfs>/public/cid/<cid> URL. A Vault refusal prints one ⚠ line and the document goes to the IXO IPFS gateway instead (https://ipfs.gateway.ixo.world/ipfs/<cid>); nothing is uploaded to Matrix media any more. The proof rules are unchanged: sha256 hex for #vct / #rub / #orz, the bafkrei… CID for #pro / #dmn / #acard. An oracle init re-run moves an #orz, #pro, #dmn or #acard still on Matrix media onto the Vault (same content, delete + add in one tx); readers keep reading Matrix media (readLinkedDoc).

Per-network defaults

IXO_NETWORK supplies all of these; any var set explicitly wins. A wrong network still fails loud at the first did.json fetch.

facilitator is the CLI's only (the audience api review-billing enable signs to, as the Decision Console's preset does); the worker's facilitator is X402_FACILITATOR_URL, never this row.

NETWORKS[network] and networkDefaults(network) expose the same row to your code and to the CLI's --network flag.

The policy triangle

Three switches decide what actually runs. Each has a config half (defineOracle) and, for two of them, an env half — both must be on.

12. What the package does at runtime

Everything in this section already exists. Do not rebuild any of it in a handler.

HTTP routes

Middleware order is fixed: observability → database → secureHeaders → cors → rateLimit → bodyLimit → prettyJSON → routes → onError/notFound. The body cap is 1 MiB. Every /v1/* route requires a UCAN invocation addressed to did:web:<ORACLE_HOSTNAME> (never the request Host) unless it is on the explicit public allowlist. It is signed by the caller's own key — a delegated chain (root ≠ invoker) is 401 — and carries exactly ONE capability, { with: "ixo:eval-oracle", can: <action> }, where the action is the route's own, named in the Auth column below (src/middleware/capability.ts ROUTE_ACTIONS; HEAD takes its GET's). A different action is 403, and so is any action on a route with no entry; a can that is none of the table's actions is 401 before it is validated. The legacy can: "*" is still accepted on every route while its callers switch, and each use is logged at info as ucan.wildcard (route, invoker) and counted as the ucan.wildcard metric (route only) — a strict release will refuse it. The package's own CLI (register, scan, relink, erase) signs each route's action; send the route's action from your own clients too. An invocation is short-lived: it must carry an exp at most 600 s ahead, and when it states an nbf, exp − nbf may not exceed 600 s either (an invocation has no issued-at, so a far-future exp would otherwise pass in its last 10 minutes) — each is 401 ("valid for too long — at most 600 s", "it has no expiry"). The CLI signs 120 s. Replay protection is off: a token may be reused within its window, and the verified token is cached (in-isolate and KV) no longer than that window. That proves key possession, audience and the action — authorization is each route's own identity check.

The oracle never deletes an organisation's claim data on its own. Nothing expires a chain claim's transcripts or registry text, nor an API claim's answers, uploads, webhook payloads, events, charges or audit rows: the organisation erases a claim by hand — the collection's owner with DELETE /v1/claims/:claimId/body (above, or decision-oracle erase), an API source with DELETE /v1/api/claims/:claimId/body, which also deletes the claim's uploads; an upload no claim names goes with DELETE /v1/api/uploads/:uploadId (uploads/delete, the same settings/manage say; 409 for a claim's file, 204 for one already gone). Either erase is 409 CONFLICT while the claim is still being decided — a running evaluate would write the transcripts back — so erase it once it is decided. The hourly housekeeping sweep only expires what is not the organisation's data: idempotency answers (24 h), OAuth approvals and auto-approvals past their window, and the objects an organisation's own action marked (an export bundle after its day, a deleted source's files).

Reviewer grants (company authority). Only a reviewer the company named answers a chain collection's reviews. A current controller of the collection's entity (Blocksync entity.controller, did:ixo:ixo1… accounts only) signs them one @ixo/ucan delegation and files it with POST /v1/collections/:id/reviewers; the reviewer sends that grant as reviewerGrant with every answer, the answer stores — and the fold forwards — the bytes the controller filed (not the reviewer's copy), and the engine checks its root again and records it in the receipt (review.root, review.memberDid). The gate (lib/review/reviewer-grant.ts) runs at the answer and again inside the fold, before the re-pull, so a revoke between the two refuses the fold with no engine call:

1. The CAR — standard, padded base64 (decoding and re-encoding gives back the very string; base64url or unpadded is refused, as on every CAR this oracle accepts, the Decision Console's included); exactly one delegation, no proofs, no extra block; its signature verifies against a key the issuer's did:ixo publishes on chain; its capabilities are exactly [{ with: "ixo:oracle/<this oracle's did:web>/collection/<collectionId>", can: "claims/review" }] (no wildcard); issuer and audience are did:ixo:ixo1… accounts (the same one is allowed: a controller may grant themselves); nbf and exp are both set, exp − nbf ≤ 30 days (UCANs carry no issued-at), nbf ≤ now + 60 s (the engine's clock skew) and now < exp.
2. The reviewer — its audience is the invoking principal (= the attestation's issuer).
3. Revocation — its canonical CID is a collection_reviewers row of this collection, not revoked.
4. No oracle — none of ORACLE_DID, did:ixo:<ORACLE_ADDRESS>, the did:web or ORACLE_ENTITY_DID is in it (oracle), nor the oracle's owner — the issuer of OWNER_DELEGATION_CAR, read once per isolate; skipped when it is unset (oracle-owner). The engine refuses the owner's fold, so it is refused at the answer; the message names the owner's DID and says to answer from another account. Register an oracle with an account nobody uses to review its claims.
5. Live root — the issuer is a current controller of the collection's entity (uncached).
6. No evaluator — neither the issuer nor the reviewer holds an EvaluateClaimAuthorization on the collection (read uncached): that power already signs MsgEvaluateClaim and moves the collection's payments, so it never also reviews.

POST /v1/collections/:id/reviewers runs 1, 4, 5 and 6, and requires the caller to be the issuer. Every refusal carries details.reason in the engine's vocabulary — 400 REVIEWER_GRANT_INVALID: absent, unparseable, extra-block, shape, audience, identity, capability, resource, lifetime, not-yet-valid, expired, too-long, signature; 403 REVIEWER_NOT_AUTHORIZED: root-not-controller, oracle, oracle-owner, evaluator, and the oracle's own revoked. A collection with no entity is a 503 (fail closed). A fold refused either way stores foldError as CODE (reason): message. The collection's review room follows the grants that stand (unrevoked, in their window, root still a controller): the hourly pass invites them and kicks the rest — never the owner; Blocksync down skips the pass.

attestation is the reviewer's own signed statement over those answers — a compact JWS ClaimReviewAttestation credential, signed with the key their did:ixo publishes on chain, whose credentialSubject binds { claimId, oracleDid, answeredAgainst, answers }. It is required on every review: a review answer IS a signed statement, and there is no flag and no unsigned path. It is verified before anything is stored (issuer = the invoking principal first, then kid ∈ the issuer's published keys, the signature, and each binding) and refused otherwise — a refused attestation never replaces stored answers, which is what keeps a stored answer signed: replacing one takes another signature. The bytes are kept verbatim and forwarded to the engine, which verifies them again; the review row reports signed: true, and the JWS itself is never returned by a read route. The fold's Matrix card edit then names the reviewer and the attestation's CID.

Deploy order. The portal ships first — an older package's review body schema is not strict, so the extra attestation field rides along harmlessly. The engine and this package then deploy together: both require the field, and the engine's fold body schema is strict, so a package that forwards attestation to an older engine turns every fold into a 400 recorded as foldError. A review row written before this (no stored attestation) cannot fold at all — the workflow says so on the row and the reviewer answers again, signed.

The read gate (assertCanRead) is the chain's answer now, never the row's memory: the collection entity's current chain owner (read off Blocksync, cached 5 min), or any holder of a live evaluate grant for it (cached 5 min) — the same permission surface as the portal's "Grant Role" flow. The enroller passes only while it still holds a grant, and an owner who transferred the entity reads nothing. A collection this oracle does not watch is a 404. One claim's record also opens to that claim's submitter (its on-chain agent DID or agent address) — that claim only, never the collection.

There is deliberately no claim-ingestion endpoint: the chain is truth, so a pushed claimId adds nothing worth trusting.

The Decision API lane's routes (/v1/api/*, API_LANE on) are specified by openapi/decision-api.yaml, shipped in the package and served at GET /v1/api/openapi.json. A console invocation (X-Auth-Type: ucan) carries ONE capability whose can is the operation's own x-ucan-action (API_ACTIONS in src/contracts/capabilities.ts, e.g. claims/read for GET /v1/api/claims); any other can — another operation's action, or the legacy * — is 403 FORBIDDEN, with a message naming the action the route takes. API keys are unaffected.

Console roles (ROLE_CAPABILITIES, src/contracts/capabilities.ts) are the five presets a member grant must match exactly: owner = source/* (covers every capability), developer = claims/read · claims/review · keys/manage · webhooks/manage · spend/read · audit/read, reviewer = claims/read · claims/review, viewer = claims/read · spend/read, and submitter = claims/submit · claims/read (v1.9). claims/submit is what submitting (one claim or a batch), PUT /v1/api/uploads and POST /v1/api/uploads/links require; claims/read covers a claim's record, receipt and report and GET /v1/api/uploads/:uploadId — source-wide, never the answers.

A source's organisation. An organisation IS its on-chain entity, and a source is that organisation's access to this oracle — it never exists without one, and there is no personal root. POST /v1/api/sources takes { name, contactEmail, entityDid } and is 403 unless the invoker is a CURRENT controller of entityDid (Blocksync entity.controller, did:ixo:ixo1… accounts, read live and uncached; 503 when it cannot be read); the creator pays (ownerDid) but gets no membership. The source starts pending-link: it answers its lists, GET /v1/api/me, the sync, revoke/remove and delete, and refuses every other route — claims, uploads, keys (even an existing one, on any route), invites and their acceptance, reviews, settings, webhooks — with 409 SOURCE_PENDING_LINK, checked where the caller is built (console, key, OAuth). Until it is first active (activatedAt, set once; on the Source view since 1.17.0, null for a source that never held claims), only its organisation's controllers can list it — not the operator (/admin/sources) — and its id is in no log line, metric, alert or Sentry event (logs carry sourceIdHash, the first 12 hex of its sha256; /v1/api log lines carry the route pattern, not the path; the D1 audit row keeps the id). The organisation's link lives at the decision engine: a controller signs a SourceCompanyLink, the console PUTs it there, then calls POST /v1/api/sources/:sourceId/company/sync (sources/company-sync), which reads the engine's stored state (company/read) and mirrors it: a link for the source's own entity ⇒ active (a source with a pausedReason stays paused, read in the same statement) with payeeField and the link (verbatim) — a read older than the stored link is ignored; a link for another entity, or the engine's disputed ⇒ disputed (409 SOURCE_DISPUTED on the same routes; the api.company-link.disputed alert); nothing stored ⇒ nothing changes (a source already linked keeps its state — an engine-side transient — with the api.company-link.unlinked alert). The sync never writes pausedReason. Any non-2xx from the engine (a 404 included) is 503 and changes nothing. The oracle never verifies a link JWS. Roots: the entity's current controllers, wherever the API used to say "owner" — a controller invokes any source route as root with no proof and no membership (X-Source-Id, with: ixo:oracle/<did:web>/source/<id>, the route's action; GET /v1/api/me answers caller.kind: "controller"), every member grant must be rooted at one, and a former controller with no membership is a stranger (404) at once. DELETE /v1/api/sources/:sourceId (sources/delete, a controller only) deletes the source and every row hanging off it — the way out of disputed; its uploads and exports are made due at once, so the hourly housekeeping sweep deletes their R2 objects, then the rows. GET /v1/api/organisations/:entityDid/sources (listOrganisationSources, sources/list-organisation, 1.17.0) answers an organisation's sources here in EVERY state — pending-link, active, paused, disputed — newest first, keyset-paged { items, nextCursor }, to a current controller of the entity only (read live; 403 otherwise, 503 when the chain cannot be read). It is how a controller finds a source an abandoned "Add oracle" or a CLI sign-up left pending-link (sync it, or delete it — nothing deletes one automatically). GET /v1/api/sources (sources/list) is the account's memberships alone, each source carrying its companyEntityDid; a stale ?entity= on it is 400 VALIDATION, naming the new route.

Review billing (per-review checker billing for chain claims, contracts 1.22.0). Only while it is active — IXO's plan for the oracle allows it (the engine's GET /v1/oracles/me reviewBilling, IXO-admin only, default false, KV-cached 5 min; an oracle never turns it on by itself, and the facilitator — the real lock — refuses chain-lane reservations otherwise) on an oracle running API_LANE + API_PAYMENTS with a 0.7.0 facilitator — otherwise all three are 404. A collection registered per review while it was active, whose plan no longer allows it, pauses payer-delegation rather than be decided unpaid. PUT /v1/api/source/review-billing (review-billing/set, keys/manage: a member's grant or a controller) stores the source's ONE standing payment delegation: { delegation }, an x402-ixo-pay payment delegation (base64 CAR, ≤ 16 KiB) — one billing/pay on billing:decision-api addressed to the facilitator (X402_FACILITATOR_URL's did:web), nb: { maxAmount, denom: "upay", oracles: [<this oracle's did:web>] } (exactly this oracle), an exp at least 24 h out (any later one, however far), an nbf (if any) not more than 5 min ahead, no proofs, no facts, its signature verified against the issuer's keys on chain. Its issuer must be the organisation's CURRENT chain owner (getEntityOwner on the source's companyEntityDid, uncached): 403 FORBIDDEN reason: not_org_owner otherwise, whoever stores it — the facilitator debits the issuer's subscription deed. Also refused, nothing stored: 409 CONFLICT billing_mode_none (the source is not billed) or review_billing_elsewhere (another source of the same organisation holds a live one; details.sourceId — one paying source per organisation), 503 SOURCE_PAUSED payments-disabled (API_PAYMENTS off or no facilitator), and 400 VALIDATION with reason not_a_payment_delegation · wrong_audience · not_oracle_bound · expires_too_soon · not_yet_valid · cap_below_price (maxAmount below the lowest published price) · bad_signature. Stored sealed in review_billing_delegations (one row per source, v1: under WEBHOOK_ENCRYPTION_KEY; audited source.review_billing_set by CID, payer, maxAmount, expiresAt — never the token); the same CID again keeps its count, a new one starts at 0. GET (review-billing/read, spend/read) answers ReviewBilling — state (active · expired · exhausted · payer_not_owner), payer, delegationCid, maxAmount, spent / remaining (the oracle's own count of what it reserved against maxAmount: the facilitator exposes none, and the delegation names this oracle alone), expiresAt, credits (the payer's facilitator balance, null until readable), pricePerReview, pausedCollections — or 404. DELETE (review-billing/delete, keys/manage) drops it: 200 { deleted, message }, idempotent; the delegation itself stays valid until its exp — a full stop is a revoke in the UCAN store (the Console's). A row is deleted with its source, and 30 days past its exp by the housekeeping sweep.

Who a claim is about (submitter). ctx.claim.submitter on the API lane is the caller's explicit submitter, else the answer the source's organisation link names (answers[payeeField]: a string or finite integer, trimmed, 1–256 characters — the engine's own submitterFor rule, lib/api-lane/submitter.ts), else null — never an oracle-side fill. A protocol whose work order has a frequency rule refuses a claim with neither 400 VALIDATION at submitter — at answers.<payeeField> when the source has one — before any payment (MCP: SUBMITTER_REQUIRED, before any approval). An AI app over OAuth acts for one person: an explicit submitter other than the signed-in user's DID is 400 VALIDATION at submitter. ClaimRecord.submittedBy is who SENT the claim, set server-side from the caller (the OAuth user's DID; null for an API key or a console submit) — never part of the content. ClaimRecord.submittedVia (v1.12.0) is WHICH AI app sent it over OAuth, { name, verified }; null otherwise. name is the client's registered name (the AuthHub token's client_name, else its client_id), trimmed and capped at 100 characters — the app declares it at dynamic registration, so it is a display hint, never an authorisation input. verified is the token's verified claim (exactly true, else false): AuthHub sets it only when every redirect URI the client registered is Claude's or ChatGPT's own callback, so a local app (Claude Code, Codex) is false. Stored as api_claims.submitted_via + submitted_via_verified.

A URL attachment's mediaType is detected at accept when the caller sends none (an AI app over MCP sends a photo as { question, url }). recordApiClaims (lib/api-lane/media-type.ts) reads it from the URL path's extension (jpg/jpeg, png, webp, gif, heic/heif, avif, pdf, mp4, mov, webm), else from one HEAD through the SSRF guard (3 s, at most 6 at once across a batch, Content-Type parameters stripped, a 403/405 left unknown — no GET fallback), and stores it on the claim's attachment, so every evaluate, retry and review fold reads the same value. A declared mediaType always wins; one it cannot tell stays absent and the facts lane's application/octet-stream default applies. Detection never fails the submit, and the Idempotency-Key comparison is still over the caller's own request. An upload's type is the one sniffed at upload.

Who answers an API claim's review (POST /v1/api/claims/:claimId/review, contracts 1.11.0). Every answer carries reviewerGrant, a base64 CAR (≤ 16 KiB): the engine refuses a company decision's fold without one (every source has a company), so a missing one is 400 REVIEWER_GRANT_INVALID (details.reason: "absent") before any read or write. Every link must state nbf and exp with exp − nbf ≤ 30 days, nbf ≤ now + 60 s, now < exp, carry a claims/review capability on ixo:oracle/<did:web>/source/<sourceId>, and no wildcard in any can or with; no identity of this oracle may appear in it — its owner (the issuer of OWNER_DELEGATION_CAR) included: 403 REVIEWER_NOT_AUTHORIZED, details.reason: "oracle-owner", before anything is stored, whether the owner answers as a controller, as a member or is the controller who granted a member's access (contracts 1.15.0).

• A member signs the attestation with the did:key they registered on the source (api_members.reviewerDid) and must hold claims/review over the claim's protocol now (mayReview: the stored grant's capabilities and nb.protocols — the engine does not read nb.protocols, so this is where the protocol limit holds). Its grant is exactly two links: (1) its STORED, unrevoked role grant (matched by canonical CID against api_members.delegationCid — anything else is 403 REVIEWER_NOT_AUTHORIZED, revoked), issued by a current controller of the organisation (403, root-not-controller) to the member's did:ixo; then (2) the member's did:ixo → that registered did:key, exactly { with: <source resource>, can: "claims/review" }, with link 1 its only proof. Each signature is checked against its issuer's IID. A grant reached through a co-owner (three links) or an owner-role grant (source/*, a wildcard) cannot review: the member needs a reviewer or developer grant straight from a controller. So the first link can stand, a role grant carrying claims/review (PUT /v1/api/members/:memberId/delegation) must have nbf and exp at most 30 days apart (else 400 VALIDATION, "reviewer grants last at most 30 days") — re-grant before it runs out.
• A root — a current controller of the source's organisation, invoking as itself — needs no member row: its attestation's issuer is its own did:ixo, the kid a did:key on that DID's document (resolved like the chain lane's), and its grant is ONE delegation from the controller to itself, exactly claims/review on the source, signed by that same kid. Its controller-ness is the console's live root check (no second chain read); the engine records it as root and member (rootKind: company-controller).

Refusals carry the engine's details.reason (absent, unparseable, shape, extra-block, signature, capability, resource, identity, lifetime, too-long, not-yet-valid, expired, audience → 400 REVIEWER_GRANT_INVALID; revoked, root-not-controller, oracle, oracle-owner → 403 REVIEWER_NOT_AUTHORIZED). The review row stores the grant beside reviewerDid. Before it forwards both, the fold re-checks what can change after the answer: a member's row must still review the claim's protocol (not revoked, expired or narrowed) and still name the grant's first link; a root must still be a controller; neither may be the oracle's owner. A miss is a foldError with the same code and reason (revoked, root-not-controller), nothing is sent, and the reviewer answers again. The engine checks the chain again, live.

Telling the console up front (contracts 1.15.0). The review view (GET /v1/api/claims/:claimId/review) carries canAnswer: { ok, reason? } and GET /v1/api/me carries reviewBlocked ("oracle-owner" | "not-reviewer" | null), both for the CALLER and computed only from what is cheap and certain: oracle-owner when the caller's did:ixo is the oracle's owner, not-reviewer when the caller does not sign answers — an API key (it may still relay a member-signed answer), a member without claims/review, or an AI app without it or without the token's claims:write scope. Neither names the owner, and an answer runs every check whatever they said — an owner-granted member's answer is still refused at the answer (oracle-owner) though its hint is ok.

Why it was held (contracts 1.20.0). When an ext/ai fact comes back error with the rubric's onError: review, the engine's reason line is generic ("External check unreachable after retries — held for review") — it is hashed into resultDigest, so it never names the check. The engine also answers erroredFacts: [{ name, detail }] on the decide, its stored-decision read and the fold: one entry per fact that errored, name lane-prefixed (ext.beforeAfter, ai.sameBoat), detail that fact's own error text (what the handler or stock lane wrote — never an answer field), ext then ai. The oracle stores ONLY that list on the decision row (decisions.erroredFacts, each detail capped at 500 chars; never logged), written with the decision, replaced by a fold that carries one, and serves it as ClaimRecord.decision.erroredFacts and the review view's erroredFacts — both omitted when nothing errored or the engine sent no list (an older engine) — and on the chain lane's GET /v1/claims/:claimId (decision.erroredFacts, null for the claim's submitter) and GET /v1/reviews/:claimId, null when none.

What a held duplicate matched (contracts 1.24.0). For each pending unique:<ruleId> task the engine also answers pendingTaskDetails["unique:<ruleId>"] = { kind: "duplicate", ruleId, score?, priorClaimId? } — the frozen unique fact's score in basis points and its winning earlier claim. The oracle stores that map on the decision row (decisions.pendingTaskDetails, with the decision only) and the review view turns it into duplicates: [{ taskId, ruleId, score?, prior }]: prior.outcome is this oracle's decision on the earlier claim (null when it has none); prior.claimId, prior.submittedAt and prior.files only when the earlier claim is the same source's, under the same protocol. The files are the earlier claim's attachments whose CID this claim also registered in the duplicate lane (claim_attachment_cids) — a near-image match shares no CID, and then they are the earlier claim's images — each URL signed like the view's own files. Another organisation's claim never shows its id or files. Omitted when no duplicate task pends. The chain lane's GET /v1/reviews/:claimId does not carry it.

One of the lane's review rules is a payment rule: a paid claim decided review asks the facilitator to extend its x402 reservation (up to 30 days from verify). The review's answerBy is that reservation's expiry — the extended one, else the default 24 h from verify — less 5 minutes (ANSWER_BY_MARGIN_MS: the fold and then the settle still run after the answer), on the claim record's review and on the reviewer view (GET /v1/api/claims/:claimId/review); null for a none-billed source and once the claim no longer awaits review. An answer after it is refused 409 REVIEW_EXPIRED (details.answerBy) before anything is verified or written — the claim could no longer be paid — except the same signed answer re-sent after it first landed in time (a retried 503). The view keeps serving the claim. The review emails and reminders state the deadline ("Answer by 30 Oct 2026, 11:57 UTC, or this claim can't be paid.") only for a claim that has one, and nobody is emailed or posted about a claim already past it.

Who is emailed about a claim waiting for review. Every accepted member whose live grant carries claims/review over the claim's protocol, with an address and notifyReviews on, gets the review-needed email at once — at most one per member per source per 15 minutes: claims that arrive inside the window go out together as one email when it ends — and the 3- and 14-day reminders. The source's contactEmail gets the same three emails, on its own 15-minute window (an organisation admin needs no member row to hear of a claim), unless a member with that same address (case-insensitive) is already sent every claim it would be. The source's Matrix review room takes every review-capable member.

Webhooks go to the registered origin only. A delivery follows at most 3 redirects, each hop https and public, and only within the endpoint's own origin, re-sent as the same signed POST; a redirect to another origin is not followed — the delivery is dead at once, its lastError naming the target's origin — so a source registers the final URL.

Where a webhook goes (contracts 1.16.0). Every active endpoint subscribed to the event type (events: [] = all), each signed with its own secret; and, for claim.*, the claim's own webhookUrl or else the source's default URL (defaultWebhookUrl), signed with the source's secret — whatever endpoints exist, so adding an endpoint never cuts the default receiver off. A default (or claim) URL that is exactly a subscribed endpoint's URL is posted once, as the endpoint's delivery. source.*, payment.settled and balance.low go to endpoints only.

A redeliver re-reads its target (contracts 1.18.0). POST /v1/api/webhooks/deliveries/:deliveryId/redeliver posts the frozen envelope to where the row's target points NOW: an endpoint's row to the endpoint's current URL (its secret); a row without an endpoint to the claim's own webhookUrl, else the source's CURRENT default (the source's secret) — never the URL frozen on the row. It is refused 409 CONFLICT before anything is reset or posted when the endpoint was deleted (details.reason: "endpoint-deleted") or turned off ("endpoint-disabled"), or a default-URL row's source has no default URL ("no-webhook-url"); like any answer, that 409 is stored under its Idempotency-Key, so a retry after the fix sends a new key. A default-URL or claim-URL redeliver always goes to the current target, signed with the SOURCE's secret, even when an endpoint now has that same URL (the enqueue-time de-dupe does not apply to one explicit row); receivers de-duplicate on Oracle-Event-Id. An erased row stays erased and goes dead.

A low balance is told twice. With a facilitator configured, the balance watch (every 5 minutes) reads each active source's payer balance against its refillFloorCents. The first read below the floor sends one balance.low webhook ({ sourceId, balanceCents, floorCents }) and one email to the source's contactEmail: the source's name, the balance and the floor as dollars, and an "Add credits" link to ${CONSOLE_URL}/billing/credits. The webhook goes once per crossing (a recovery above the floor re-arms it). The email goes once per UTC day while the balance stays under the floor (notice_balance_low:<sourceId>:<yyyy-mm-dd>): still low tomorrow is a new email, a balance bobbing around its floor within a day is one, and a send that fails is retried on the next check. No contactEmail, or no EMAIL binding, EMAIL_FROM_ADDRESS or CONSOLE_URL ⇒ the email is a logged skip (email.notice_balance_low.skipped) and the webhook still goes; the email.notice_balance_low metric counts sent / skipped / failed.