@ixo/decision-oracle 0.2.23 → 0.2.25

package/dist/routes/v1/shared.js

@@ -5,8 +5,8 @@
 import { eq, getTableColumns, sql } from "drizzle-orm";
 import { watchedCollections, } from "../../db/schema.js";
 import { AppError } from "../../lib/errors.js";
-import { hasEvaluateGrant } from "../../lib/ixo/authz.js";
-import { getClaimById, getCollection, getEntityOwner } from "../../lib/ixo/blocksync/index.js";
+import { hasEvaluateGrant, isIxoAccountAddress } from "../../lib/ixo/authz.js";
+import { getClaimById, getCollection, getEntityOwner, hasLiveGrantBetween, } from "../../lib/ixo/blocksync/index.js";
 import { readCache } from "../../lib/metrics.js";
 import { liveReviewerGrants } from "../../lib/review/reviewer-grant.js";
 import { sanitise } from "../../lib/sanitise.js";
@@ -14,6 +14,8 @@ import { sanitise } from "../../lib/sanitise.js";
 const OWNER_CACHE_TTL_SEC = 300;
 /** A claim's submitter never changes on chain, so its read is cached long (a portal polls it). */
 const AGENT_CACHE_TTL_SEC = 86_400;
+/** An authz link between two accounts can be revoked, so it is trusted like the grant read. */
+const LINK_CACHE_TTL_SEC = 300;
 /**
  * Who may READ (and scan) a watched collection — the same surface that may register it, as the
  * chain says it is NOW (ownership review F2): the current chain owner (who pays the fees), or any
@@ -121,6 +123,9 @@ async function assertReader(c, watched, { reviewers, agentOf }) {
  * Blocksync read, KV-cached by claim since the submitter is immutable. The cache holds the claim's
  * own collection, compared here at read time, so it never depends on the request that filled it. A
  * claim Blocksync does not know is not cached: it may just not be indexed yet.
+ * An agent key that files for a person is the claim's on-chain agent, not the person: so the
+ * submitter is also anyone a LIVE authz grant links to that agent, either way round (the person who
+ * granted the agent, or a key the agent granted) — `isAgentLinked`.
  */
 async function isClaimAgent(c, claimId, collectionId) {
     const key = `claim-agent:${claimId}`;
@@ -136,8 +141,30 @@ async function isClaimAgent(c, claimId, collectionId) {
         }).catch(() => { });
     }
     const { did, address } = c.get("principal");
-    return (agent.collectionId === collectionId &&
-        ((!!agent.did && agent.did === did) || (!!agent.address && agent.address === address)));
+    if (agent.collectionId !== collectionId)
+        return false;
+    if ((!!agent.did && agent.did === did) || (!!agent.address && agent.address === address)) {
+        return true;
+    }
+    return !!agent.address && (await isAgentLinked(c, address, agent.address));
+}
+/**
+ * A live authz grant links `address` and `agentAddress`, either direction, any message type —
+ * Blocksync's `authzGrants` (live rows only), KV-cached `LINK_CACHE_TTL_SEC` per pair, both
+ * answers: a revoked grant closes the door within the TTL. Not an account (a did:key, a group
+ * DID's "wasm") means no link, decided without a read.
+ */
+async function isAgentLinked(c, address, agentAddress) {
+    if (!isIxoAccountAddress(address) || !isIxoAccountAddress(agentAddress))
+        return false;
+    const key = `agent-link:${address}:${agentAddress}`;
+    const cached = await readCache("agent-link", () => c.env.CACHE_KV.get(key));
+    if (cached !== null)
+        return cached === "1";
+    const deps = { config: c.get("config"), trace: c.get("trace") };
+    const linked = await hasLiveGrantBetween(deps, address, agentAddress);
+    await c.env.CACHE_KV.put(key, linked ? "1" : "0", { expirationTtl: LINK_CACHE_TTL_SEC }).catch(() => { });
+    return linked;
 }
 /** The collection entity's owner address on chain, cached `OWNER_CACHE_TTL_SEC`; null = none. */
 async function liveOwner(c, collectionId) {

package/dist/routes/v1/shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/routes/v1/shared.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/routes/v1/shared.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -38,6 +38,7 @@ export type { Database } from "./db/client.js";
 export { getDb } from "./db/client.js";
 export type { DecisionRow, WatchedCollection } from "./db/schema.js";
 export { decisions, watchedCollections } from "./db/schema.js";
+export { claimFailureReason } from "./lib/claim-failure.js";
 export { AppError } from "./lib/errors.js";
 export type { BlocksyncDeps, CollectionNode } from "./lib/ixo/blocksync/index.js";
 export { getCollection } from "./lib/ixo/blocksync/index.js";

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAIxB,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,iBAAiB,CAAC,CA4B5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1F;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC,CAIxE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,EACpD,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAOrE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EACL,KAAK,iBAAiB,EAEvB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAIxB,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,iBAAiB,CAAC,CA4B5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY1F;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC,CAIxE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,EACpD,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAOrE"}

package/dist/runtime.js

@@ -43,6 +43,8 @@ import { getOracle } from "./oracle.js";
 export { loadConfig } from "./config.js";
 export { getDb } from "./db/client.js";
 export { decisions, watchedCollections } from "./db/schema.js";
+// A failed ingest's claimant-safe sentence — what the claim read says, for a provider's own "why".
+export { claimFailureReason } from "./lib/claim-failure.js";
 export { AppError } from "./lib/errors.js";
 export { getCollection } from "./lib/ixo/blocksync/index.js";
 // --- plumbing, verbatim from the modules that assemble it, for a provider's own Workflow ---------

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/docs/api.md

@@ -218,6 +218,7 @@ import type {
 import {
   AppError,
   broadcastAsOracle,
+  claimFailureReason,
   decisions,
   getCollection,
   getDb,
@@ -257,6 +258,7 @@ and the database handle from it exactly as the cron does (`cron/scan.ts`'s `cron
 | `registerCollection` | function | `(env, input: RegisterInput) => Promise<WatchedCollection>` — the SAME four gates (WHO/HIRED/PROTOCOL/PAID), delegation resolution, upsert and paused→active notice `POST /v1/collections/register` runs (`lib/register.ts`), as a function. `input.cursor` is the one thing the HTTP body schema never exposes: applied on FIRST registration only — a re-register can never rewind it (it is not in the upsert's conflict `set`). `null` scans the collection from claim zero (the existing NULL-cursor path, blocksync `CLAIMS_FROM_START`) for a collection whose claims may predate this oracle's registration; absent seeds the cursor to now, the HTTP route's own behaviour, unchanged | Your own Workflow registering a collection AS the oracle's own principal, after minting its own evaluate grant — there is no inbound request to authenticate or a body to validate |
 | `broadcastAsOracle` | function | `(env, msgs, memo?) => Promise<{ code, transactionHash, rawLog? }>` — signs and broadcasts arbitrary messages as THIS oracle's account, the same sequence-managed signer the act lane uses (`getOracleSigner`, `lib/ixo/chain.ts`). Memo defaults to your oracle's own `name`. Does **not** inspect `res.code` — unlike `signEvaluation` this is a raw broadcast primitive, not a decision lane, so a non-zero code is yours to interpret. Throws `AppError.unavailable` when `ORACLE_SECP_MNEMONIC` is unset, before the signer is ever built | Composing your own `MsgExec` around kit-issued messages |
 | `rehireOpenhands` | function | `(env, collectionId) => Promise<"started" \| "existing" \| "restarted" \| "throttled" \| "failed">` — starts the OpenHands hire for a collection, or reruns its ended instance (spending the collection's backstop restart budget: three a day). A rerun mints only when the chain says the grant is stale or below 50 verdicts | `openhands` on, and your own `act` policy counts verdicts and sees an ask running low before the backstop's next visit |
+| `claimFailureReason` | function | `(error: string \| null) => string` — a failed ingest (`claim_ingests.status = "failed"`) in a sentence a claimant may read, from its stored `error`: an owner-billing cause (`OWNER_DELEGATION_CAR` unset, the owner's delegation refused, no IXO subscription) is "The oracle isn't set up to bill this check yet — the operator has been told.", anything else "The check couldn't run; the operator has been told." Never the stored text itself (env var names, RPC detail) | Your own claimant-facing "why" route, so a failed claim says failed — the same words `GET /v1/claims/:claimId` gives its submitter |
 | `AppError` | class | The kit's typed error — `.notFound()`, `.forbidden()`, `.conflict()`, `.unavailable()`, `.internal()`, … (§13) | Catching/rethrowing what the four functions above throw, in your own error handling |
 | `ChainWriteOutcome` | type | `"submitted" \| "skipped" \| "blocked" \| "held" \| "owner_submitted"` — what `signEvaluation` resolves to, and (alongside `"pending"`, the row's initial state before any write is attempted) the full `decisions.chainStatus` enum. A decision the act lane can never sign (an engine `unusable`, a `decided` review verdict) starts `"skipped"` instead; a `pending_review` starts `"pending"` and its fold acts | Branching on the result, or reading `chainStatus` off `GET /v1/claims/:claimId` |
 | `RegisterInput` | type | `{ collectionId, principal: { did, address }, contactEmail?, delegationCar?, cursor? }`. No `contactEmail` sent and none stored ⇒ the row takes the `contactEmail` of the oldest-activated `active` Decision API source whose `companyEntityDid` is the collection's COMPANY as the engine derives it (`GET /v1/collections/:id/company`, UCAN `collection/company-read`: the collection's entity, or the org a deed is linked to both ways); a `disputed` company, a collection the engine does not know, or none such source ⇒ stays empty. Its `503` or any other failure never fails the register (logged `register.company-unavailable`, the row stays empty for a later register to fill). An explicit or stored contact is never overwritten. The SAME answer (one engine read per register) also links the collection to every `active` source of that company (`api_source_collections`, `linkedBy` = the company's entity DID, audit `source.collection_linked` by `system:company-link`; idempotent — an existing link is left alone); only the engine's `ok` links. The engine is asked only when no contact is sent or stored, or an `active` source is not yet linked to the collection. | Building the input to `registerCollection` |
@@ -464,8 +466,11 @@ collection gets at most three hire reruns a day from the backstop and three from
 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.
+three minute ticks, and no webhook scan moves the collection's place in the rotation. The third
+route, `GET /openhands/claims/<claimId>/why`, tells the claim's own submitter why it was decided
+the way it was — the per-check reasons the public receipt leaves out (§7 has its auth and body);
+the OpenHands app shows it beside the receipt. `GET /v1/info` advertises the three paths under
+`openhands` (`hire`, `scan`, `why`), which is how the OpenHands app tells a checker from any other oracle.
 
 `OpenhandsOptions` (all optional):
 
@@ -477,7 +482,7 @@ both paths under `openhands`, which is how the OpenHands app tells a checker fro
 
 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
+answer `503` and the why route `429` (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
@@ -1602,7 +1607,7 @@ it("bands a vendor score against the rule's own thresholds", async () => {
 | `CLAIM_WORKFLOW` | `Workflow` | `ClaimIngest` — one instance per claim |
 | `REVIEW_WORKFLOW` | `Workflow` | `ReviewComplete` — the review fold |
 | `HIRE_WORKFLOW` | `Workflow` (optional) | `OpenhandsHire` — one instance per hired OpenHands collection. Required with `openhands` on |
-| `OPENHANDS_RATE_LIMITER` | `RateLimit` (optional) | The OpenHands webhooks' limit, spent per caller address (an IPv6 caller by its /64) and per collection. Required with `openhands` on outside `ENVIRONMENT=development` (unbound ⇒ `503`) |
+| `OPENHANDS_RATE_LIMITER` | `RateLimit` (optional) | The OpenHands routes' limit, spent per caller address (an IPv6 caller by its /64) and per collection (the webhooks) or per issuer (the why route). Required with `openhands` on outside `ENVIRONMENT=development` (unbound ⇒ `503`) |
 | `SEQUENCE_MANAGER` | `DurableObjectNamespace` | The SDK's `SequenceManagerDO`: one instance per signer, allocating account sequence numbers so concurrent chain writes never race |
 
 Your own bindings ride alongside — the type is open (`OracleEnv & YourEnv`); only the names above
@@ -1779,9 +1784,10 @@ check.**
 | `GET /health/ready` | public, **rate-limited** (per IP) | `{ ok }` only — `200` when every critical check passes, `503` otherwise. Checks `d1`, `kv`, `engine` (its `/.well-known/did.json`) and, with `API_LANE` and `API_PAYMENTS` on, `facilitator` (`X402_FACILITATOR_URL/supported`), in parallel, 2 s each, plus `identity` (a config read: fails when `ORACLE_ENTITY_DID` is unset on a non-local `ORACLE_HOSTNAME`) and `owner-delegation` (fails when `OWNER_DELEGATION_CAR` is set but is not a UCAN delegation; unset passes); the settled answer is cached per isolate for 15 s. A failure before the route runs (a config that does not load) is also `503 { ok: false }`. Names no check — the detail is `/v1/admin/status`'s |
 | `GET /.well-known/did.json` | public, rate-limit exempt | Needs `SERVICE_ED25519_MNEMONIC` |
 | `GET /.well-known/oauth-protected-resource/v1/mcp` | public, rate-limit exempt, `Access-Control-Allow-Origin: *`, `cache-control: public, max-age=300` | RFC 9728 metadata for the MCP server: `{ resource: "https://<ORACLE_HOSTNAME>/v1/mcp", authorization_servers: [AUTH_HUB_URL], scopes_supported: ["claims:write", "claims:read"], bearer_methods_supported: ["header"] }`. `404` unless `API_LANE` is on. Outside the `/v1/api` contract |
-| `GET /v1/info` | **public** (the only public `/v1` path) | —. The marketplace listing: `name`, `description`, `did`, `address`, `entityDid` (the on-chain oracle entity from `ORACLE_ENTITY_DID`, `null` when unset), `serviceDid`, `supportedProtocols`, `protocols` (the same list readably: `[{ did, name, fee }]` — `name` the protocol's `#pro` profile name, else its claim form's title, cached 1 h, `null` when neither reads; `fee` the `{ denom, minAmount }` register charges for it), `pricing`, `policies`, `earnings: { address, baseWallet }` (the operator's `EARNINGS_ADDRESS` / `EARNINGS_BASE_WALLET`, `null` when unset — read-only, set in the oracle's config), `payouts: { decisionToPay, operatorAmount }` — how a payout amount is chosen, for a portal to show before a company opts in: `decisionToPay` is the config's `payouts` map verbatim (per protocol DID, `{ amount: <answer path>, currency: <ISO 4217 code> | { path } | { asset, decimals } }`; `{}` when none, and a protocol absent from it gets no decision to pay), `operatorAmount` is `{ summary }` from `policies.actSummary` when an `act` policy is configured, else `null` (`actSummary` is served only here, never under `policies`), and `reviewBilling: { mode, pricePerReview }` — how a collection pays for its reviews: `mode: "x402"` (per-review billing ACTIVE: IXO's plan for the oracle allows it — the engine's `GET /v1/oracles/me` `reviewBilling`, KV-cached 5 min — on an oracle running `API_LANE`: per review from the company's credits, an empty evaluation leg) with `pricePerReview: { denom: "upay", amount }` the published per-review price (the one the supported protocols share, else `pricing.api.amountMicroUsd` / `API_PRICE_USD_CENTS`; `null` when none is published), or `mode: "escrow"` (the collection's on-chain evaluation payment, `pricing`) with `pricePerReview: null`. `cache-control: public, max-age=300`. With `openhands` set, also `openhands: { hire: "/openhands/hire/:collectionId", scan: "/openhands/scan/:collectionId" }` — absent on any other oracle. A portal is built against these exact field names |
+| `GET /v1/info` | **public** (the only public `/v1` path) | —. The marketplace listing: `name`, `description`, `did`, `address`, `entityDid` (the on-chain oracle entity from `ORACLE_ENTITY_DID`, `null` when unset), `serviceDid`, `supportedProtocols`, `protocols` (the same list readably: `[{ did, name, fee }]` — `name` the protocol's `#pro` profile name, else its claim form's title, cached 1 h, `null` when neither reads; `fee` the `{ denom, minAmount }` register charges for it), `pricing`, `policies`, `earnings: { address, baseWallet }` (the operator's `EARNINGS_ADDRESS` / `EARNINGS_BASE_WALLET`, `null` when unset — read-only, set in the oracle's config), `payouts: { decisionToPay, operatorAmount }` — how a payout amount is chosen, for a portal to show before a company opts in: `decisionToPay` is the config's `payouts` map verbatim (per protocol DID, `{ amount: <answer path>, currency: <ISO 4217 code> | { path } | { asset, decimals } }`; `{}` when none, and a protocol absent from it gets no decision to pay), `operatorAmount` is `{ summary }` from `policies.actSummary` when an `act` policy is configured, else `null` (`actSummary` is served only here, never under `policies`), and `reviewBilling: { mode, pricePerReview }` — how a collection pays for its reviews: `mode: "x402"` (per-review billing ACTIVE: IXO's plan for the oracle allows it — the engine's `GET /v1/oracles/me` `reviewBilling`, KV-cached 5 min — on an oracle running `API_LANE`: per review from the company's credits, an empty evaluation leg) with `pricePerReview: { denom: "upay", amount }` the published per-review price (the one the supported protocols share, else `pricing.api.amountMicroUsd` / `API_PRICE_USD_CENTS`; `null` when none is published), or `mode: "escrow"` (the collection's on-chain evaluation payment, `pricing`) with `pricePerReview: null`. `cache-control: public, max-age=300`. With `openhands` set, also `openhands: { hire: "/openhands/hire/:collectionId", scan: "/openhands/scan/:collectionId", why: "/openhands/claims/:claimId/why" }` — absent on any other oracle. A portal is built against these exact field names |
 | `POST /openhands/hire/:collectionId` | public, **`OPENHANDS_RATE_LIMITER`** (per caller and per collection; unbound outside development ⇒ `503`), `openhands` on only | Starts the collection's hire (`202 { started: true }`) after reading that it exists and its admin granted this oracle a live meta-grant: `404` no such collection (not cached), `409` no meta-grant (cached 10 min). A hire in flight, or an ended one the chain says is healthy, is `200 { existing: true }` (the healthy answer cached 1 min); an ended one the chain says is stale or low is rerun from the webhook's own budget (`200 { restarted: true, reason }`, three a day, then `{ throttled: true }`). `400` a malformed id, `405` not POST, `503` when the chain or Blocksync cannot answer |
 | `POST /openhands/scan/:collectionId` | public, **`OPENHANDS_RATE_LIMITER`**, `openhands` on only | Scans one watched collection now: `200 { started }`, `202 { coalesced: true }` within a minute of the last (scanned on the next minute tick), `404` not watched, `409` paused. A `200 { started: 0 }` (or a failed scan) is retried on the next three minute ticks |
+| `GET /openhands/claims/:claimId/why` | **the claim's own submitter**: a UCAN invocation (`Authorization: Bearer <token>`, `X-Auth-Type: ucan`) carrying exactly `{ can: "claims/why", with: "ixo:claim:<claimId>" }`, addressed to this oracle's did:web, self-issued (no delegation), expiring at most 10 min out, whose issuer is the claim's on-chain `agentDid`. **`OPENHANDS_RATE_LIMITER`** per caller address before the token is checked and per issuer after (`429`; unbound outside development ⇒ `429`). `openhands` on only | Why the claim was decided: `200 { outcome, summary, reasons[], evidenceGrade?, reviewNote?, receiptCid? }` — `outcome` is `approved` (approve or partial) / `rejected` / `review` (held for a person) / `pending`; each reason is `{ code, label, result: pass \| fail \| error \| review, detail, value?, threshold?, unit? }`, one per gate or criterion, explained through the one fact it reads and labelled by the pinned rubric (`#rub`, read for its public sentences only, hash-checked, cached 7 days; unreadable ⇒ codes without labels). An `ext` fact's reason is never echoed (only the stock geo handlers' distances and evidence grade), an AI sentence only scrubbed of identifiers, and no AI instruction is ever read. A claim queued, or on a watched collection and not yet seen, is `pending`; a **failed ingest** is `pending` with a fixed sentence (`claimFailureReason`) — never the stored error. Anyone but the agent, or a claim this oracle never saw, gets the same `404 NOT_FOUND`; `401` no or a bad token, `400` a malformed id, `405` not GET, `503` when Blocksync or the DID resolver cannot answer |
 | `POST /v1/collections/register` | UCAN `collections/register` | The four gates, in order: **who** (the collection entity's chain owner, or a holder of an active on-chain `EvaluateClaimAuthorization` — read uncached) · **hired** (this oracle's `ORACLE_ADDRESS` holds that grant too, else `409`) · **protocol** (in `supportedProtocols`, else `409` — checked before payment) · **paid** (`Payments.evaluation` matches `pricing`, else `402`; while per-review billing is active (IXO's plan), the collection's company — ONE engine read, `GET /v1/collections/:id/company`, its blip or a `disputed` company `503 company_unavailable` — holding a live review-billing delegation on its Decision API source, still signed by the organisation's current chain owner, with a published price and cap left, registers with an EMPTY evaluation leg (`billingSourceId` set, never billed twice) once the payer's credits cover one review: `GET /v1/balances` with the stored delegation in `X-Payment-Delegation`, both `available` and `delegationRemaining` ≥ the price, else `402 insufficient_credits` (`details.price`, `details.fundingUrl`), an unreadable answer `503 credits_unavailable`; no usable delegation ⇒ the escrow gate as before, its refusal `402 no_review_billing` naming both ways in). Body: `{ collectionId, delegationCar?, contactEmail? }`. No `contactEmail` sent and none stored ⇒ the row takes the `contactEmail` of the oldest-activated `active` Decision API source whose `companyEntityDid` is the collection's COMPANY as the engine derives it (`GET /v1/collections/:id/company`, UCAN `collection/company-read`: the collection's entity, or the org a deed is linked to both ways); a `disputed` company, a collection the engine does not know, or none such source ⇒ stays empty. Its `503` or any other failure never fails the register (logged `register.company-unavailable`, the row stays empty for a later register to fill). An explicit or stored contact is never overwritten. The SAME answer (one engine read per register) links the collection to every `active` Decision API source of that company, so its chain claims read with the source's (contracts 1.21.0: `LinkedCollection.linkedBy` = the company's entity DID, audit `source.collection_linked` by `system:company-link`, re-checked hourly against the engine and dropped `not_company` when it names another company or `disputed`; only such a positive finding hides a link — an unreachable engine keeps it in the reads, contracts 1.23.0); idempotent, and only the engine's `ok` links. The engine is asked only when no contact is sent or stored, or an `active` source is not yet linked to the collection. Every refusal carries a stable machine code in `details.reason` beside the human message: `404 collection_not_found`, `403 owner_unresolvable` · `not_owner_or_grantee` · `contact_change_forbidden` · `resume_forbidden`, `409 not_hired` · `unsupported_protocol`, `402 evaluation_underpaid` · `no_review_billing` · `insufficient_credits`, `503 company_unavailable` · `credits_unavailable`. |
 | `GET /v1/collections` | UCAN `collections/read` | The rows the caller owns or enrolled |
 | `POST /v1/collections/:id/pause` | UCAN `collections/pause` + read gate + owner, enroller (while it holds a live grant) or `ORACLE_ADMIN_DIDS` (a plain grant holder is `403`) | Sets `status: paused`, clears the reason — the cron enqueues nothing |
@@ -1793,7 +1799,7 @@ check.**
 | `POST /v1/collections/:id/reviewers` | UCAN `collections/reviewers-grant` (never `*`) + a **current controller** of the collection's entity (read live off Blocksync), who must be the grant's issuer | `{ delegation }` — a base64 CAR the controller signed: a reviewer grant (below). Checked as the review gate checks it (no revocation step), then filed in `collection_reviewers`. A controller may name **themselves**, and a grant to the collection's owner is filed like any other: one person may post an ask and review it (the owner's seat in the review room only lets them see reviews; answering always takes a grant). `201` + the grant row (`memberDid`, `rootDid`, `delegationCid`, `delegation`, `expiresAt`, `revokedAt`, `createdAt`). The same CAR again answers the same row; a revoked one is `409` (sign a new one). `400 REVIEWER_GRANT_INVALID` / `403 REVIEWER_NOT_AUTHORIZED` as the gate, `404` unwatched |
 | `GET /v1/collections/:id/reviewers` | UCAN `collections/reviewers-read` (never `*`) | A current controller: `{ reviewers: [...] }`, every grant on the collection; a reviewer: only their own, CAR included (the Portal sends it with an answer); anyone else `403` |
 | `POST /v1/collections/:id/reviewers/:delegationCid/revoke` | UCAN `collections/reviewers-revoke` (never `*`) + a current controller | Stamps `revokedAt` (once) and kicks the reviewer from the collection's review room. Every later answer and every pending fold under that grant is refused. `404` for an unknown grant |
-| `GET /v1/claims/:claimId` | UCAN `claims/read` + read gate, or a live reviewer of the claim's collection (a filed, unrevoked grant inside its window whose root is still a controller — read live, so Blocksync down is `503`), or the claim's own submitter (matched by EITHER the claim's on-chain agent DID or its agent address, invoking as themselves; one Blocksync claim read, cached a day — a claim Blocksync does not know yet is not cached — tried only after the other doors; Blocksync down is `503`) | The full record: ingest ⟕ decision ⟕ review. The submitter sees the decision and its public receipt (which names who reviewed), but never the review's answers: `review.answers` and `review.reviewerDid` come back `null`, and so do the internal failure texts `ingest.error`, `decision.chainError` and `decision.erroredFacts`. `404` when this oracle has not seen the claim. The submitter gets no other read: not the list, not `/v1/reviews`, not another claim. Plus `checks` — the breakdown: every check the decision was made on, `[{ name, status, value, reason }]` (`reason` the checker's own words, a passed AI check's included; an error's detail), never a transcript or a prompt, `null` when the claim has no decision or its row has no facts. The submitter's copy is **cleaned**: URLs, emails, DIDs, CIDs and other identifiers, exact coordinates, phone-shaped and long numbers, plate-shaped tokens and long quotes become `[hidden]`, capped at 280 characters — they read why, not another claim's ids or someone's details. Plus `reviewerNote` (`policies.reviewerNote`) for every reader but the submitter, who gets `null` |
+| `GET /v1/claims/:claimId` | UCAN `claims/read` + read gate, or a live reviewer of the claim's collection (a filed, unrevoked grant inside its window whose root is still a controller — read live, so Blocksync down is `503`), or the claim's own submitter (matched by EITHER the claim's on-chain agent DID or its agent address, invoking as themselves; one Blocksync claim read, cached a day — a claim Blocksync does not know yet is not cached — tried only after the other doors; Blocksync down is `503`), or an account a LIVE on-chain authz grant links to that agent, either direction and any message type (the person who granted an agent key that files for them, or a key the agent granted; both `ixo1…` accounts; one Blocksync `authzGrants` read, cached 5 min per pair, yes or no) — read as the submitter | The full record: ingest ⟕ decision ⟕ review. The submitter sees the decision and its public receipt (which names who reviewed), but never the review's answers: `review.answers` and `review.reviewerDid` come back `null`, and so do the internal failure texts `decision.chainError` and `decision.erroredFacts`. `ingest.error` is `null` too, except on a failed ingest (`ingest.status: "failed"`), where it is a safe sentence instead of the stored text (`claimFailureReason`, `/runtime`): "The oracle isn't set up to bill this check yet — the operator has been told." for an owner-billing cause, else "The check couldn't run; the operator has been told." `404` when this oracle has not seen the claim. The submitter gets no other read: not the list, not `/v1/reviews`, not another claim. Plus `checks` — the breakdown: every check the decision was made on, `[{ name, status, value, reason }]` (`reason` the checker's own words, a passed AI check's included; an error's detail), never a transcript or a prompt, `null` when the claim has no decision or its row has no facts. The submitter's copy is **cleaned**: URLs, emails, DIDs, CIDs and other identifiers, exact coordinates, phone-shaped and long numbers, plate-shaped tokens and long quotes become `[hidden]`, capped at 280 characters — they read why, not another claim's ids or someone's details. Plus `reviewerNote` (`policies.reviewerNote`) for every reader but the submitter, who gets `null` |
 | `DELETE /v1/claims/:claimId/body` | UCAN `claims/erase` (never `*`) + the collection's **current** chain owner (read live off Blocksync; the enroller, grant holders and `ORACLE_ADMIN_DIDS` are `403`) — `404` when this oracle has not seen the claim or it is a Decision API claim, `503` on chain trouble | `204`; `409 CONFLICT` while the claim is still `queued` or `processing` (erase it once it is decided). Erases the claim's answer copies now: strips every `transcript` from `decisions.facts` (the AI prompts and HTTP payloads; the fact values stay), nulls the duplicate registry's `normalizedText`, drops its fact-cache rows, and stamps `claim_ingests.erasedAt`. The decision, its receipt and the registry digests stay, so the receipt still verifies and duplicates are still caught. Idempotent: `204` again, the first `erasedAt` kept. Logged `claims.erased`, counted `claims.erased` (`op: chain`). The CLI's `decision-oracle erase` loops over it The reviewer note (`reviewerNote`) is erased with them |
 | `GET /v1/reviews/:claimId` | UCAN `reviews/read` + read gate, or a live reviewer of the claim's collection | The pending tasks, the stored answers, why a fold failed, `erroredFacts` (below; null when none errored), and `checks` — every frozen `ext` / `ai` fact the decision was made on, `[{ name: "ai.judge", status: "ok" \| "error", value, reason }]`, `reason` the checker's own words (a passed AI check's reasoning included; an error's `detail`), never a transcript or a prompt; `null` on a row with no facts (a facts-lane outcome). What a reviewer reads before deciding (the same list `GET /v1/claims/:claimId` serves). Plus `reviewerNote` — `{ says, checkThese[], model, createdAt }` (`policies.reviewerNote`), `null` when none was made |
 | `GET /v1/admin/status` | UCAN `admin/status` + `ORACLE_ADMIN_DIDS` or `STATUS_READER_DIDS` (`403` otherwise — everyone, while both are unset) | `{ readiness: { ok, checks: { <name>: { ok, ms, critical, detail? } } }, backlog: { review: { pending }, collections: { paused: { total, <reason>: n } }, sources?: { paused }, webhooks?: { due, oldestAgeS } }, engine: { billingStatus, manageSubscriptionUrl } \| null }` — `sources`/`webhooks` only with `API_LANE` on; `engine` is the engine's `GET /v1/oracles/me`, `null` when it did not answer within 2 s; `detail` is set only on a failed `identity` or `owner-delegation` check and names the command to run. Outside the `/v1/api` contract |
@@ -1897,8 +1903,8 @@ collection entity's current chain owner (read off Blocksync, cached 5 min), or a
 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.
+opens to that claim's submitter (its on-chain agent DID or agent address, or an account a live
+authz grant links to that agent, either way round) — 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.

package/docs/guide.md

@@ -1043,9 +1043,15 @@ oracle the right to authorize itself on the new collection, and the app calls
 own evaluate grant under it, registers the collection through the same four gates above, and scans
 it. A grants feed every minute catches a call that never arrived (it follows the meta-grants
 made to your oracle on Blocksync), and a backstop every five minutes keeps every hired ask
-topped up. `GET /v1/info` lists the two webhooks under `openhands` — that is how the app knows
+topped up. `GET /v1/info` lists the two webhooks (and the why route below) under `openhands` — that is how the app knows
 you are an OpenHands checker. (api.md §2, "The OpenHands add-on", has every step and answer.)
 
+The add-on also answers the people who submit: `GET /openhands/claims/<claimId>/why` tells a
+claim's own submitter (a UCAN their app signs as the claim's on-chain agent) which checks passed,
+which failed and why, in the rubric's words — the reasons the public receipt leaves out — and the
+OpenHands app shows it on the claim. A claim still running, or one whose check could not run, reads
+"pending"; the second with a fixed sentence, never your logs' error text. Nothing to configure.
+
 Three things to decide:
 
 - **Your protocols.** With `supportedProtocols` set, the app offers your oracle for asks on those
@@ -1185,7 +1191,11 @@ human review. Both are UCAN-guarded and gated to the collection's current chain
 evaluate-grant holder — the registrant only while it still holds its grant — and the single-claim
 read to the collection's live reviewers too, and to the claim's own submitter (its on-chain agent DID or
 address, who sees the decision and its public receipt — which names who reviewed — but never the
-review's answers). `chainStatus` is `pending` / `submitted` / `owner_submitted` / `blocked` / `skipped`
+review's answers). An agent key filing for a person is the claim's on-chain agent, so the submitter's
+read also opens to an account a live authz grant links to that agent, either way round — the person
+who granted it, or a key it granted. A failed ingest tells the submitter so in a safe sentence
+(`ingest.error`, never the stored text; `claimFailureReason` in `/runtime` gives your own "why"
+route the same words). `chainStatus` is `pending` / `submitted` / `owner_submitted` / `blocked` / `skipped`
 (a decision nothing will ever sign: an engine `unusable`, or a `decided` review verdict with no review
 held for a person), or
 **`held`** when your own `policies.act` hook chose to keep a decided verdict back instead of signing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "license": "Apache-2.0",
   "description": "Run an IXO evaluation oracle: pull claims, produce facts with your handlers, let the decision engine decide, sign on chain",
   "keywords": [