@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/ixo/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `pullClaim(deps, claimId)` — one call in → the complete claim assembled across all three planes
+ * (chain metadata + off-chain body + every attachment) as a `PulledClaim` (pull-claim-spec §4).
+ *
+ * Backs the durable ClaimIngest workflow; callers build `deps` with `depsFromEnv`. Fails closed via
+ * AppError at every step (§11). A `PulledClaim` is log-safe by construction: attachments are CID
+ * descriptors — the bytes stay in the store the body came from, content-addressed, and are never
+ * copied out (§15).
+ *
+ * The body is read from the FIRST store that has it: the VFS claims lane (under our evaluate grant
+ * — vfs.ts), a VFS public copy, the Matrix claim bot (under the owner's delegation), the IPFS
+ * gateway, and last a cellnode the entity declares (being retired). The order is a cost and
+ * migration choice, not a correctness one: a claim id addresses exactly one set of bytes wherever
+ * they are stored, and every store but the bot is CID-verified (verified-read.ts). Each store
+ * answers found / miss / unavailable, and "nowhere" is a 404 only when every one truly missed — an
+ * outage anywhere makes it a retry, never a permanent no.
+ *
+ * The pull also builds the engine's `claimContent` (ENGINE-CONTRACT "Company authority"): the claim
+ * CID, plus the EXACT bytes a CID-verified store served — the bot's JSON comes back with its keys
+ * sorted, so a bot body is never bound (no `document`). On a payout scope the bot is the last
+ * resort: the walk goes on to the CID-verified stores first, and settles for the bot body only when
+ * none of them has it.
+ *
+ * Delegation resolution (the Matrix lane's) is DB-first (§6): the watched-collection row carries
+ * the owner→oracle delegation persisted at register time, so steady-state pulls make ZERO
+ * UCAN-Store round trips. The store is only consulted to refresh a missing/expiring delegation, and
+ * the refreshed CAR is written back.
+ */
+import type { CoinSDKType } from "@ixo/impactxclient-sdk/types/codegen/cosmos/base/v1beta1/coin.js";
+import { type Config } from "../../config.js";
+import { type WatchedCollection } from "../../db/schema.js";
+import type { OracleEnv } from "../../env.js";
+import type { ClaimContent } from "../engine/types.js";
+import { type Logger } from "../logger.js";
+import { type Metrics } from "../metrics.js";
+import { type TraceContext } from "../tracing.js";
+import { type Attachment, type MediaLane } from "./attachments.js";
+import { type ClaimPayment } from "./payment.js";
+import { type ClaimLane } from "./verified-read.js";
+export interface PullDeps {
+    config: Config;
+    logger: Logger;
+    metrics: Metrics;
+    trace: TraceContext;
+    cache: KVNamespace;
+    /** The watched-collection row (owner DID, stored delegation) — null when we don't watch it. */
+    getWatched: (collectionId: string) => Promise<WatchedCollection | null>;
+    /** Persist a refreshed owner→oracle delegation back onto the row (best-effort). */
+    saveDelegation: (collectionId: string, car: string, expiresAt: Date | null) => Promise<void>;
+    /**
+     * `env.EMAIL` (Cloudflare Email Service) — carried on `PullDeps` so the two
+     * workflows' `depsFromEnv(this.env)` call sites pass a superset of what `workflows/steps.ts`'s
+     * `pauseCollection()` needs, with zero edits to the workflow files themselves. Absent ⇒ the
+     * notice email lane no-ops (lib/email/send.ts), same "unset ⇒ off" contract as `cache`'s siblings.
+     */
+    email?: SendEmail;
+}
+export interface PulledClaim {
+    claimId: string;
+    collectionId: string;
+    network: string;
+    /**
+     * The store the body was read from — and the one a bare-CID file answer resolves to. `api`: the
+     * Decision API's own D1 (`api_claims`, Go Prod §7.1), whose files are https URLs.
+     */
+    lane: ClaimLane | "api";
+    metadata: {
+        agentDid: string | null;
+        agentAddress: string | null;
+        schemaType: string | null;
+        submissionDate: string | null;
+        /** The claim's on-chain payout coins (§4) — echoed into MsgEvaluateClaim on a terminal verdict. */
+        amount: CoinSDKType[];
+        /** Intent/escrow lane (payment.ts) — decides whether we may set the payout at all. */
+        payment: ClaimPayment;
+        evaluation: unknown;
+    };
+    body: Record<string, unknown>;
+    /** CID/URL descriptors only — the bytes stay in the store (§15). */
+    attachments: Attachment[];
+    /**
+     * The body's store, for on-demand attachment reads (connector size probes / byte fetches): where
+     * a CID's bytes are, and the auth for that host alone. NEVER logged. Null on the cellnode lane:
+     * no media store, and no file answers either — their `web3:` refs are static protocol constants,
+     * not per-claim uploads.
+     */
+    media: MediaLane | null;
+}
+/**
+ * A claim as its source pulled it: the facts lane's `PulledClaim` plus the engine's `claimContent`
+ * (chain: the CID and the verified bytes; api: the stored content). The content goes to the engine
+ * and nowhere else — the workflows take it off before the claim reaches a handler — and, like the
+ * body, it never leaves the step that pulled it.
+ */
+export interface SourcedClaim extends PulledClaim {
+    content: ClaimContent;
+}
+export interface PullOptions {
+    /** Is this protocol a payout scope (`OracleConfig.payouts`)? Then the bot body is the last resort. */
+    payoutScope?: (protocolDid: string) => boolean;
+}
+export declare function pullClaim(deps: PullDeps, claimId: string, opts?: PullOptions): Promise<SourcedClaim>;
+/** What a workflow knows about who started it — every key optional, only the known ones logged. */
+export interface Correlation {
+    /** The starter's W3C `traceparent`: continued when valid, else the run roots a fresh trace. */
+    traceparent?: string;
+    requestId?: string;
+    claimId?: string;
+    instanceId?: string;
+    workflow?: string;
+}
+/**
+ * Build pull deps from the Worker env (workflow / scheduled — no request context). The logger's
+ * base carries the run's `traceId` plus whatever `correlation` names, so every line of a claim's
+ * run joins the request that accepted it (observability spec §3 "Correlation").
+ */
+export declare function depsFromEnv(env: OracleEnv, correlation?: Correlation): PullDeps;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/ixo/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kEAAkE,CAAC;AAEpG,OAAO,EAAE,KAAK,MAAM,EAAc,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,KAAK,iBAAiB,EAAsB,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAiB,KAAK,OAAO,EAAa,MAAM,YAAY,CAAC;AACpE,OAAO,EAA0C,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,KAAK,UAAU,EAAY,KAAK,SAAS,EAAsB,MAAM,eAAe,CAAC;AAM9F,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,WAAW,CAAC;AAG5D,OAAO,EACL,KAAK,SAAS,EAIf,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,+FAA+F;IAC/F,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACxE,mFAAmF;IACnF,cAAc,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAWD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC;IACxB,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,mGAAmG;QACnG,MAAM,EAAE,WAAW,EAAE,CAAC;QACtB,sFAAsF;QACtF,OAAO,EAAE,YAAY,CAAC;QACtB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,oEAAoE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,OAAO,EAAE,YAAY,CAAC;CACvB;AAqBD,MAAM,WAAW,WAAW;IAC1B,sGAAsG;IACtG,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,YAAY,CAAC,CA6EvB;AA2PD,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,GAAE,WAAgB,GAAG,QAAQ,CAuCnF"}

package/dist/lib/ixo/index.js

@@ -0,0 +1,395 @@
+/**
+ * `pullClaim(deps, claimId)` — one call in → the complete claim assembled across all three planes
+ * (chain metadata + off-chain body + every attachment) as a `PulledClaim` (pull-claim-spec §4).
+ *
+ * Backs the durable ClaimIngest workflow; callers build `deps` with `depsFromEnv`. Fails closed via
+ * AppError at every step (§11). A `PulledClaim` is log-safe by construction: attachments are CID
+ * descriptors — the bytes stay in the store the body came from, content-addressed, and are never
+ * copied out (§15).
+ *
+ * The body is read from the FIRST store that has it: the VFS claims lane (under our evaluate grant
+ * — vfs.ts), a VFS public copy, the Matrix claim bot (under the owner's delegation), the IPFS
+ * gateway, and last a cellnode the entity declares (being retired). The order is a cost and
+ * migration choice, not a correctness one: a claim id addresses exactly one set of bytes wherever
+ * they are stored, and every store but the bot is CID-verified (verified-read.ts). Each store
+ * answers found / miss / unavailable, and "nowhere" is a 404 only when every one truly missed — an
+ * outage anywhere makes it a retry, never a permanent no.
+ *
+ * The pull also builds the engine's `claimContent` (ENGINE-CONTRACT "Company authority"): the claim
+ * CID, plus the EXACT bytes a CID-verified store served — the bot's JSON comes back with its keys
+ * sorted, so a bot body is never bound (no `document`). On a payout scope the bot is the last
+ * resort: the walk goes on to the CID-verified stores first, and settles for the bot body only when
+ * none of them has it.
+ *
+ * Delegation resolution (the Matrix lane's) is DB-first (§6): the watched-collection row carries
+ * the owner→oracle delegation persisted at register time, so steady-state pulls make ZERO
+ * UCAN-Store round trips. The store is only consulted to refresh a missing/expiring delegation, and
+ * the refreshed CAR is written back.
+ */
+import { eq } from "drizzle-orm";
+import { loadConfig } from "../../config.js";
+import { getDb } from "../../db/client.js";
+import { watchedCollections } from "../../db/schema.js";
+import { AppError } from "../errors.js";
+import { base64Of, sha256Hex } from "../hash.js";
+import { createLogger } from "../logger.js";
+import { createMetrics, readCache } from "../metrics.js";
+import { generateTraceContext, parseTraceparent } from "../tracing.js";
+import { botMedia, resolveAttachments } from "./attachments.js";
+import { getClaimById, getCollection, getEntityServices } from "./blocksync/index.js";
+import { cellnodeUrlFromServices, getCellnodeClaimBody } from "./cellnode.js";
+import { getBotDid, getClaimBody, resolveClaimBotUrl } from "./claim-bot.js";
+import { resolveIssuerKeys } from "./delegation-verify.js";
+import { claimPayment } from "./payment.js";
+import { mintBotInvocation, verifyOwnerDelegation } from "./ucan.js";
+import { fetchOwnerDelegation } from "./ucan-store.js";
+import { readVerifiedClaim, } from "./verified-read.js";
+import { vfsClaimsLane } from "./vfs.js";
+/** Refresh when the stored delegation has less than this long to live. */
+const DELEGATION_EXPIRY_MARGIN_SEC = 60;
+/**
+ * The gateway answers a CID it doesn't hold with a 502 after ~40s — a miss it can't tell from an
+ * outage — so it gets ONE attempt, bounded here, and its silence counts as `unavailable`.
+ */
+const IPFS_TIMEOUT_MS = 15_000;
+/**
+ * The largest document the engine can bind to its claim id: the fleet's ids are `ipfs-only-hash`,
+ * which chunks a payload over 256 KiB into a dag-pb root, so `CIDv1(raw, sha256)` of the bytes only
+ * matches up to here (ENGINE-CONTRACT "Content binding"). Bigger ⇒ no `document`.
+ */
+const MAX_BOUND_DOCUMENT_BYTES = 256 * 1024;
+const MISS = { status: "miss" };
+export async function pullClaim(deps, claimId, opts = {}) {
+    const { logger } = deps;
+    // Step 1 — chain metadata (public). No claim on-chain → fail closed (404).
+    const claim = await timedPull(deps, "blocksync", () => getClaimById(deps, claimId));
+    if (!claim)
+        throw AppError.notFound(`No claim on-chain for id ${claimId}`);
+    const collectionId = claim.collectionId;
+    // Step 2 — the watched row is the authority: who the owner is (the wallet that registered — NOT
+    // `collection.admin`, the entity account) and which delegation authorizes the Matrix read. Not
+    // watched → fail closed.
+    const watched = await deps.getWatched(collectionId);
+    if (!watched)
+        throw AppError.forbidden(`Collection ${collectionId} is not watched`);
+    // The collection's entity (its deed) owns the VFS claims lane and declares any cellnode, exactly
+    // as emerging's own resolver (`getClaimData`) asks it; the protocol resolves the bot (§3.5 / §4.2).
+    const collection = await getCollection(deps, collectionId);
+    const entityDid = collection?.entity;
+    const protocolDid = watched.protocolDid ?? claim.collection?.protocol ?? collection?.protocol;
+    const botEntityDid = protocolDid ?? entityDid;
+    const payoutScope = protocolDid ? (opts.payoutScope?.(protocolDid) ?? false) : false;
+    // Step 3 — the body, from the first store that has it (header). Sequential on purpose: a hit
+    // stops the walk, so no later store is asked for a claim an earlier one holds.
+    const { VFS_URL: vfs, IPFS_GATEWAY_URL: gateway } = deps.config;
+    const lanes = [
+        ["vfs", () => readVfsLane(deps, entityDid, collectionId, claimId)],
+        ["vfs-public", () => readStore(deps, "vfs-public", publicStore(vfs, "/public/cid/"), claimId)],
+        ["matrix", () => readMatrix(deps, watched, botEntityDid, collectionId, claimId)],
+        [
+            "ipfs",
+            () => readStore(deps, "ipfs", publicStore(gateway, "/ipfs/"), claimId, {
+                miss: [404, 410],
+                timeoutMs: IPFS_TIMEOUT_MS,
+            }),
+        ],
+        ["cellnode", () => readCellnode(deps, entityDid ?? botEntityDid, claimId)],
+    ];
+    const down = [];
+    let bot = null;
+    for (const [lane, read] of lanes) {
+        let got;
+        try {
+            got = await timedPull(deps, lane, read);
+        }
+        catch (err) {
+            // With the bot body held, a later store's refusal (a drifted CID, oversize, non-JSON — a
+            // >256 KiB bot claim's dag-pb id never matches the gateway's raw bytes) only means there is
+            // no bound copy: the claim is decided on the bot body, never refused. No bot body ⇒ loud.
+            if (!bot)
+                throw err;
+            logger.warn("claim.lane-refused", { claimId, collectionId, lane });
+            continue;
+        }
+        if (got.status === "found") {
+            // A payout scope walks on past the bot for bytes the engine can bind (header).
+            if (lane === "matrix" && payoutScope) {
+                bot = got;
+                continue;
+            }
+            return pulled(deps, claimId, claim, lane, got);
+        }
+        if (got.status === "unavailable") {
+            logger.warn("claim.lane-unavailable", { claimId, collectionId, lane, reason: got.reason });
+            down.push(`${lane}: ${got.reason}`);
+        }
+    }
+    if (bot) {
+        logger.info("claim.bot-fallback", { claimId, collectionId });
+        return pulled(deps, claimId, claim, "matrix", bot);
+    }
+    // Nowhere we could see — but an unreadable store may hold it, so that is a retry, not a no.
+    if (down.length > 0) {
+        throw AppError.unavailable(`Claim body for ${claimId} not found yet (${down.join("; ")})`);
+    }
+    throw AppError.notFound(`Claim body for ${claimId} is in none of ${lanes.map(([lane]) => lane).join(", ")}`);
+}
+/**
+ * `claim.pull` for one store read (op the store): a miss is an answer (`ok`); an `unavailable`
+ * store or a throw is `error`.
+ */
+async function timedPull(deps, store, read) {
+    const started = Date.now();
+    let outcome = "error";
+    try {
+        const got = await read();
+        if (got?.status !== "unavailable")
+            outcome = "ok";
+        return got;
+    }
+    finally {
+        deps.metrics.timing("claim.pull", Date.now() - started, { op: store, outcome });
+    }
+}
+/** The deliverable: the full claim, logged log-safe by construction (descriptors, no media auth). */
+function pulled(deps, claimId, claim, lane, { body, media, bytes }) {
+    const metadata = claimMetadata(claim);
+    const network = deps.config.IXO_NETWORK;
+    // Only bytes a store CID-verified, and only up to what the engine can bind — never re-serialised.
+    const document = bytes && bytes.length <= MAX_BOUND_DOCUMENT_BYTES ? base64Of(bytes) : undefined;
+    deps.metrics.count("claim.pull.ok", 1);
+    deps.logger.info("claim.pulled", {
+        claimId,
+        collectionId: claim.collectionId,
+        network,
+        lane,
+        // Not `metadata`: that key is redacted in every log line (lib/redact.ts) — the API lane's
+        // caller metadata is personal; this is the chain's (agent, schema type, amounts).
+        claimMeta: metadata,
+    });
+    return {
+        claimId,
+        collectionId: claim.collectionId,
+        network,
+        lane,
+        metadata,
+        body,
+        // Descriptors only (name, mediaType, CID, URL): a bare CID resolves to THIS store (§15).
+        attachments: resolveAttachments(body, media),
+        media,
+        content: { kind: "chain", cid: claimId, ...(document ? { document } : {}) },
+    };
+}
+/** A store that serves any CID it holds to anyone — no auth, because the bytes prove themselves. */
+function publicStore(origin, path) {
+    return { origin, cidUrl: (cid) => `${origin}${path}${cid}` };
+}
+/** A store that serves the body at the same address a bare CID resolves to (`media.cidUrl`). */
+async function readStore(deps, lane, media, claimId, opts = {}) {
+    const read = await readVerifiedClaim(deps, lane, media.cidUrl(claimId), claimId, {
+        ...opts,
+        headers: await media.auth?.(),
+    });
+    return read.status === "found" ? { ...read, media } : read;
+}
+/**
+ * The VFS claims lane (vfs.ts) — none without a collection entity to own it. A 401/403 is a miss,
+ * not an outage: the VFS doesn't see our evaluate grant (revoked, or not indexed yet), which
+ * `readVerifiedClaim` warns about.
+ */
+async function readVfsLane(deps, entityDid, collectionId, claimId) {
+    if (!entityDid)
+        return MISS;
+    try {
+        const media = await vfsClaimsLane(deps, entityDid, collectionId);
+        return await readStore(deps, "vfs", media, claimId, { miss: [401, 403, 404] });
+    }
+    catch (err) {
+        return unavailableOrThrow(err);
+    }
+}
+/**
+ * The Matrix claim bot (claim-bot.ts). It reads under the owner→oracle delegation, so a collection
+ * without a usable one has no Matrix lane at all — a miss, and checked first because it costs no
+ * round trip. When the bot has the body, the claim is exactly what this lane always produced: the
+ * same request, and the same bot auth on the same media host.
+ */
+async function readMatrix(deps, watched, entityDid, collectionId, claimId) {
+    let delegationCar;
+    try {
+        delegationCar = await resolveDelegation(deps, watched);
+    }
+    catch (err) {
+        // 403: none on deposit (register already warned once). 400: the store handed us one that is
+        // not the owner's — refused, and worth a warning.
+        if (err instanceof AppError && (err.status === 403 || err.status === 400)) {
+            deps.logger[err.status === 400 ? "warn" : "info"]("claim.matrix-skipped", {
+                collectionId,
+                reason: err.message,
+            });
+            return MISS;
+        }
+        return unavailableOrThrow(err);
+    }
+    if (!entityDid) {
+        return { status: "unavailable", reason: "no protocol/entity DID to resolve the bot" };
+    }
+    try {
+        const botUrl = await resolveClaimBotUrl(deps, entityDid);
+        const botDid = await getBotDid(deps, botUrl);
+        const botToken = await mintBotInvocation(deps.config, deps.cache, botDid, delegationCar);
+        const body = await getClaimBody(deps, botUrl, botToken, collectionId, claimId);
+        if (!body)
+            return MISS;
+        return { status: "found", body, media: botMedia(botUrl, botToken, collectionId) };
+    }
+    catch (err) {
+        // The bot refused the delegation (owner not room admin?) — a retry changes nothing.
+        if (err instanceof AppError && err.status === 403) {
+            deps.logger.warn("claim.matrix-denied", { collectionId, claimId, reason: err.message });
+            return MISS;
+        }
+        return unavailableOrThrow(err);
+    }
+}
+/** A cellnode the collection's entity declares (cellnode.ts) — none declared, no lane. */
+async function readCellnode(deps, entityDid, claimId) {
+    if (!entityDid)
+        return MISS;
+    try {
+        const cellnodeUrl = cellnodeUrlFromServices(await getEntityServices(deps, entityDid));
+        if (!cellnodeUrl)
+            return MISS;
+        const read = await getCellnodeClaimBody(deps, cellnodeUrl, claimId);
+        return read.status === "found" ? { ...read, media: null } : read;
+    }
+    catch (err) {
+        return unavailableOrThrow(err);
+    }
+}
+/**
+ * A store we could not even ASK (its did.json, Blocksync, the UCAN Store down) is `unavailable` and
+ * passed over; anything else — a CID mismatch, our own misconfiguration — stays loud.
+ */
+function unavailableOrThrow(err) {
+    if (err instanceof AppError && err.status === 503) {
+        return { status: "unavailable", reason: err.message };
+    }
+    throw err;
+}
+/** The chain plane of a claim — identical on every body lane, so none can drift from another. */
+function claimMetadata(claim) {
+    return {
+        agentDid: claim.agentDid,
+        agentAddress: claim.agentAddress,
+        schemaType: claim.schemaType,
+        submissionDate: claim.submissionDate,
+        amount: claim.amount ?? [],
+        payment: claimPayment(claim),
+        evaluation: claim.evaluationByClaimId,
+    };
+}
+/**
+ * The owner→oracle delegation for a watched collection: the stored CAR when it is still
+ * comfortably valid AND verified, otherwise one UCAN-Store refresh (persisted back, best-effort).
+ * No delegation anywhere → the owner must re-register — fail closed.
+ */
+async function resolveDelegation(deps, watched) {
+    const now = Math.floor(Date.now() / 1000);
+    const exp = watched.delegationExpiresAt
+        ? Math.floor(watched.delegationExpiresAt.getTime() / 1000)
+        : null;
+    const stillValid = exp === null || exp - DELEGATION_EXPIRY_MARGIN_SEC > now;
+    if (watched.delegationCar && stillValid && (await storedCarVerifies(deps, watched))) {
+        return watched.delegationCar;
+    }
+    const found = await fetchOwnerDelegation(deps, watched.ownerDid);
+    if (!found) {
+        throw AppError.forbidden(`No valid owner delegation for collection ${watched.collectionId} — re-register it`);
+    }
+    const expiresAt = found.expiresAt ? new Date(found.expiresAt * 1000) : null;
+    await deps.saveDelegation(watched.collectionId, found.car, expiresAt).catch((err) => deps.logger.warn("delegation.persist-failed", {
+        collectionId: watched.collectionId,
+        error: String(err),
+    }));
+    deps.logger.info("delegation.refreshed", {
+        collectionId: watched.collectionId,
+    });
+    return found.car;
+}
+/** How long a stored CAR's signature verdict is trusted before it is checked again. */
+const STORED_CAR_VERDICT_TTL_SEC = 86_400;
+/**
+ * Does the stored CAR's signature verify (delegation-verify.ts)? Rows written before the signature
+ * check existed may hold a forgery — and one with no `exp` was `stillValid` forever. So the stored
+ * CAR is verified like a fresh one, and a PASS is cached in KV per CAR (sha256) for a day: steady
+ * state is one KV read, one Blocksync read a day. A refusal (400) is logged and reads as "no
+ * stored CAR" — the caller falls back to the store; Blocksync trouble (503) is thrown and retried.
+ */
+async function storedCarVerifies(deps, watched) {
+    const car = watched.delegationCar;
+    const key = `delegation-ok:${await sha256Hex(car)}`;
+    if ((await readCache("delegation-ok", () => deps.cache.get(key))) !== null)
+        return true;
+    try {
+        await verifyOwnerDelegation(deps.config, car, watched.ownerDid, () => resolveIssuerKeys(deps.config, watched.ownerDid, deps.trace));
+    }
+    catch (err) {
+        if (err instanceof AppError && err.status === 400) {
+            deps.logger.warn("delegation.stored-refused", {
+                collectionId: watched.collectionId,
+                reason: err.message,
+            });
+            return false;
+        }
+        throw err;
+    }
+    await deps.cache.put(key, "1", { expirationTtl: STORED_CAR_VERDICT_TTL_SEC }).catch(() => { });
+    return true;
+}
+/**
+ * Build pull deps from the Worker env (workflow / scheduled — no request context). The logger's
+ * base carries the run's `traceId` plus whatever `correlation` names, so every line of a claim's
+ * run joins the request that accepted it (observability spec §3 "Correlation").
+ */
+export function depsFromEnv(env, correlation = {}) {
+    const config = loadConfig(env);
+    const { traceparent, ...ids } = correlation;
+    const trace = parseTraceparent(traceparent) ?? generateTraceContext();
+    const logger = createLogger({
+        level: config.LOG_LEVEL,
+        pretty: config.LOG_PRETTY,
+        base: {
+            service: config.SERVICE_NAME,
+            version: config.SERVICE_VERSION,
+            env: config.ENVIRONMENT,
+            traceId: trace.traceId,
+            ...Object.fromEntries(Object.entries(ids).filter(([, v]) => v !== undefined)),
+        },
+    });
+    const metrics = createMetrics(logger, { dataset: env.METRICS, network: config.IXO_NETWORK });
+    const cache = env.CACHE_KV;
+    // D1 is a binding, not a connection — nothing to open or close per access (db/client.ts).
+    const db = getDb(env);
+    return {
+        config,
+        logger,
+        metrics,
+        trace,
+        cache,
+        email: env.EMAIL,
+        getWatched: async (collectionId) => {
+            const row = await db.query.watchedCollections.findFirst({
+                where: (t, { eq }) => eq(t.collectionId, collectionId),
+            });
+            return row ?? null;
+        },
+        saveDelegation: async (collectionId, car, expiresAt) => {
+            await db
+                .update(watchedCollections)
+                .set({ delegationCar: car, delegationExpiresAt: expiresAt })
+                .where(eq(watchedCollections.collectionId, collectionId));
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/ixo/index.js.map

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

package/dist/lib/ixo/payment.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A claim's PAYMENT plane — the one place that reads the chain's intent/escrow semantics, verified
+ * against `ixo-blockchain/x/claims/keeper/msg_server.go`.
+ *
+ * Two lanes, and the oracle must act differently in each:
+ *
+ *   useIntent = false — an ORDINARY claim. The agent's requested `amount` is a request; the
+ *     evaluator's `MsgEvaluateClaim.amount` is what actually pays (falling back to the collection's
+ *     default approval payment when empty), authz-capped by `EvaluateClaimConstraints.MaxCustomAmount`.
+ *     ⇒ we ECHO the claim's own amount so the agent is paid what they asked for.
+ *
+ *   useIntent = true — an ESCROWED claim. `MsgClaimIntent` moved the payout into the collection's
+ *     escrow account BEFORE the claim existed; `MsgSubmitClaim{useIntent:true}` copied the intent's
+ *     terms onto the claim, set `paymentsStatus.approval = GUARANTEED`, and DELETED the intent
+ *     record (so there is nothing left to query at evaluation time — the claim IS the record).
+ *     `EvaluateClaim` then OVERWRITES `msg.Amount` with `claim.Amount` (msg_server.go:409-413) and
+ *     pays the full escrowed sum on approve / refunds it on any other terminal status.
+ *     ⇒ we send NO amount: the chain ignores it, and a non-empty amount is still checked against
+ *     `MaxCustomAmount` (authz.go:231), so echoing it can fail the whole MsgExec for zero benefit.
+ *
+ * The denom is always the CLAIM's — the oracle never picks one.
+ */
+import type { CoinSDKType } from "@ixo/impactxclient-sdk/types/codegen/cosmos/base/v1beta1/coin.js";
+import type { ClaimNode, CollectionPayments } from "./blocksync/types.js";
+export interface ClaimPayment {
+    /** Escrow-governed: the payout is fixed by the intent and the oracle may not change it. */
+    useIntent: boolean;
+    /** `paymentsStatus.approval = GUARANTEED` — escrow actually holds funds for this claim. */
+    guaranteed: boolean;
+    /** The claim's payout coins, verbatim from chain (denom included). Empty = collection default. */
+    amount: CoinSDKType[];
+}
+/** The claim's payment plane, normalized. Missing/legacy fields read as an ordinary unpaid claim. */
+export declare function claimPayment(claim: Pick<ClaimNode, "useIntent" | "paymentsStatus" | "amount">): ClaimPayment;
+/**
+ * The coins to put on `MsgEvaluateClaim`, or `undefined` to let the chain decide (§payment above).
+ * Intent claims ALWAYS get `undefined`.
+ */
+export declare function evaluationAmount(payment: ClaimPayment | undefined): CoinSDKType | undefined;
+/**
+ * Would an on-chain APPROVE actually pay something without the evaluator inventing an amount?
+ * True on the escrow lane (the intent priced it), on a claim carrying its own coins, or when the
+ * collection's approval lane has a default. False means approval needs a CUSTOM amount — a money
+ * judgement that belongs to the owner, not this oracle (the act lane leaves such a claim for the
+ * portal rather than signing a zero payout).
+ *
+ * Deliberately a question about the CHAIN, not about settings: it reports whether money would move,
+ * and the caller decides what that means.
+ */
+export declare function hasApprovalPayout(payment: ClaimPayment, collectionPayments: CollectionPayments | null): boolean;
+/** A coin as both the chain and the watched row carry it: an integer base-unit string. */
+export interface Coin {
+    denom: string;
+    amount: string;
+}
+/**
+ * What ONE `MsgEvaluateClaim` draws from the collection's admin account, summed per denom — the
+ * act lane's `admin-unfunded` notice and the funding cron's resume threshold read the same rule.
+ * Proven on chain v8 (S4): the message fails WHOLE ("insufficient funds") unless the admin covers
+ * every leg it pays, and a failed one records nothing, so a retry after a top-up succeeds.
+ *
+ *   evaluation — every evaluation, approve or reject: the collection's `payments.evaluation`
+ *     (all its coins); the watched row's accepted `fee` only when Blocksync has no payments.
+ *   approval — an ORDINARY claim's payout: `claimAmount` (what step 9 puts on the message), else
+ *     the collection's approval default. An INTENT claim adds nothing: the escrow pays it.
+ *   rejection — the collection's rejection payment, whatever the lane.
+ *
+ * Omit `verdict` for the evaluation leg alone. An empty or absent leg adds nothing, and so does
+ * a coin whose amount is not an integer (the chain's coins always are; a ragged jsonb row must
+ * not throw a notice or a probe). Zero sums are dropped.
+ */
+export declare function adminDraw(input: {
+    payments: CollectionPayments | null | undefined;
+    fee?: Coin | null;
+    verdict?: {
+        approve: boolean;
+        payment: ClaimPayment;
+        claimAmount?: Coin;
+    };
+}): Coin[];
+/** The watched row's accepted evaluation fee as a coin, when it carries one. */
+export declare function rowFee(row: {
+    evaluationDenom: string | null;
+    evaluationAmount: string | null;
+} | undefined): Coin | null;
+/** What a provider requires per evaluation (the oracle config's `pricing.evaluation`). */
+export interface EvaluationFee {
+    denom: string;
+    /** Integer base-unit string; compared with BigInt, never Number. */
+    minAmount: string;
+}
+/**
+ * The register-time money gate: the collection's `Payments.evaluation` is the
+ * ONLY way this oracle gets paid — the chain splits that coin 80/10/10 on every `MsgEvaluateClaim`
+ * — so a collection paying nothing, in another denom, or below the fee is refused (402) rather than
+ * evaluated for free. Returns the accepted coin (what the watched row records). The whole coin list
+ * is scanned because an evaluation payment may carry several denoms; the message states required
+ * vs offered so the commissioner can fix the collection's payments, not guess.
+ */
+export declare function requireEvaluationPayment(required: EvaluationFee, payments: CollectionPayments | null | undefined): {
+    denom: string;
+    amount: string;
+};
+//# sourceMappingURL=payment.d.ts.map

package/dist/lib/ixo/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/payment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kEAAkE,CAAC;AAEpG,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,UAAU,EAAE,OAAO,CAAC;IACpB,kGAAkG;IAClG,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,GAAG,gBAAgB,GAAG,QAAQ,CAAC,GAChE,YAAY,CAMd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAG3F;AAOD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,GAC5C,OAAO,CAGT;AAID,0FAA0F;AAC1F,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAC/B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC;IAChD,GAAG,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,YAAY,CAAC;QAAC,WAAW,CAAC,EAAE,IAAI,CAAA;KAAE,CAAC;CAC3E,GAAG,IAAI,EAAE,CAkBT;AAED,gFAAgF;AAChF,wBAAgB,MAAM,CACpB,GAAG,EAAE;IAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,GACnF,IAAI,GAAG,IAAI,CAIb;AAID,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAC9C;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAiCnC"}