@ixo/decision-oracle 0.2.24 → 0.2.25

package/README.md

@@ -784,6 +784,6 @@ symlinks are not packed). CI diffs them — change one, copy it to the other.
 
 ## Status
 
-Published on npm: `@ixo/decision-oracle` 0.2.24 and `@ixo/decision-oracle-client` 0.1.1.
+Published on npm: `@ixo/decision-oracle` 0.2.25 and `@ixo/decision-oracle-client` 0.1.1.
 
 Apache License 2.0: `LICENSE` at the repo root and in each package.

package/dist/define-oracle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-oracle.d.ts","sourceRoot":"","sources":["../src/define-oracle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAItE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,EAAE,KAAK,YAAY,EAAiC,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,cAAc,IAAI,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;IAC9C,SAAS,EAAE,+BAA+B,CAAC,SAAS,CAAC,CAAC;IACtD,WAAW,EAAE,OAAO,gBAAgB,CAAC;IACrC,cAAc,EAAE,OAAO,mBAAmB,CAAC;IAC3C,6FAA6F;IAC7F,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;CAC7C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA4D/D"}
+{"version":3,"file":"define-oracle.d.ts","sourceRoot":"","sources":["../src/define-oracle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAItE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvC,OAAO,EAAE,KAAK,YAAY,EAAiC,MAAM,UAAU,CAAC;AAC5E,OAAO,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,cAAc,IAAI,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;IAC9C,SAAS,EAAE,+BAA+B,CAAC,SAAS,CAAC,CAAC;IACtD,WAAW,EAAE,OAAO,gBAAgB,CAAC;IACrC,cAAc,EAAE,OAAO,mBAAmB,CAAC;IAC3C,6FAA6F;IAC7F,aAAa,EAAE,OAAO,kBAAkB,CAAC;IACzC,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;CAC7C;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CA8D/D"}

package/dist/define-oracle.js

@@ -26,6 +26,7 @@ import app from "./app.js";
 import { runCronTick } from "./cron/scan.js";
 import { producerOf } from "./lib/facts/tools.js";
 import { handleOpenhandsRoute } from "./lib/openhands/routes.js";
+import { handleWhyRoute } from "./lib/openhands/why.js";
 import { sentryOptions } from "./lib/sentry.js";
 import { OracleConfigSchema, setOracle } from "./oracle.js";
 import { ClaimIngest as ClaimIngestClass } from "./workflows/claim-ingest.js";
@@ -64,9 +65,10 @@ export function defineOracle(config) {
     // other Worker handlers live.
     const handler = Sentry.withSentry(sentryOptions, {
         async fetch(request, env, ctx) {
-            // The OpenHands webhooks sit in front of the app: they are not `/v1` routes and carry no UCAN.
+            // The OpenHands routes sit in front of the app: they are not `/v1` routes — the webhooks carry
+            // no UCAN, the claimant's "why" carries one on its claim, not on `ixo:eval-oracle`.
             if (openhands) {
-                const answered = await handleOpenhandsRoute(request, env);
+                const answered = (await handleOpenhandsRoute(request, env)) ?? (await handleWhyRoute(request, env));
                 if (answered)
                     return answered;
             }

package/dist/define-oracle.js.map

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

package/dist/lib/openhands/explain.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The claimant's "why", built from what this oracle already holds for a claim: the decision row
+ * (the engine's gate and criterion outcomes, its receipt, the frozen `ext`/`ai` facts, the
+ * `erroredFacts`) and the pinned rubric's own words (labels, limits, the duplicate and frequency
+ * rules). Pure — `why.ts` reads the row and the rubric and serves what this returns. Ported from
+ * openhands-oracles `core/src/openhands/explain.ts` minus its campaign label table: a fact is
+ * labelled by the rubric's own sentence (an AI check) or by its name, never by a provider's word.
+ *
+ * DISPLAY ONLY. The rubric is read for its public sentences after the engine decided; nothing here
+ * binds, validates or decides — the engine's `Decision` is the only verdict, `outcomeOf` reads it.
+ *
+ * One generic mapper, never a case per claim: each gate and criterion is explained through the ONE
+ * fact its condition reads (`ext.<name>` / `ai.<name>`), or through the claim fields it tests.
+ *
+ * WORKER-SAFE by construction. Nothing reaches the body verbatim except the rubric's own sentences
+ * (the protocol's public text) and the AI's sentence about the claimant's own submission, sanitised.
+ * An `ext` reason is NEVER echoed — a provider's reason may name other claims or places — only
+ * numbers read out of the stock geo handlers' measurement grammar (`facts/geo.ts`:
+ * `<n> m from centre, limit <m> m; evidence: …`, `<n> m apart, limit <m> m`). The engine's
+ * `duplicate` / `frequency` reason lines name the matching claim, so those gates are explained from
+ * the rubric alone. No model prompt (`aiChecks[].instructions`) is ever read.
+ */
+import type { DecisionRow } from "../../db/schema.js";
+export type WhyRow = Pick<DecisionRow, "claimId" | "collectionId" | "rubricId" | "verdict" | "status" | "receiptCid" | "decision" | "facts" | "erroredFacts">;
+export type Outcome = "approved" | "rejected" | "review" | "pending";
+export type Result = "pass" | "fail" | "error" | "review";
+export type EvidenceGrade = "camera" | "browser-reported" | "none";
+export interface WhyReason {
+    code: string;
+    label: string;
+    result: Result;
+    detail: string;
+    value?: number | string;
+    threshold?: number | string;
+    unit?: string;
+}
+export interface WhyBody {
+    outcome: Outcome;
+    summary: string;
+    reasons: WhyReason[];
+    evidenceGrade?: EvidenceGrade;
+    reviewNote?: string;
+    receiptCid?: string;
+}
+type Condition = Record<string, unknown>;
+/** The pinned rubric minus everything a worker must not see (the AI checks' instructions). */
+export interface RubricView {
+    gates: {
+        code: string;
+        reason?: string;
+        when?: Condition;
+        onFail?: string;
+    }[];
+    criteria: {
+        code: string;
+        reason?: string;
+        appliesWhen?: Condition;
+        score?: Condition;
+    }[];
+    /** Review task id → the criterion it scores, when it scores one. */
+    tasks: Record<string, string | null>;
+    unique?: {
+        id: string;
+        label?: string;
+    };
+    frequency?: {
+        id: string;
+        label?: string;
+        max?: number;
+        per?: string;
+    };
+}
+/** A `#rub` envelope (`{ rubric: {...} }`) → the view; null when it is not a rubric at all. */
+export declare function rubricView(doc: unknown): RubricView | null;
+/** What this oracle holds for a claim it has seen but the engine has not yet decided. */
+export declare function pendingBody(): WhyBody;
+export declare function explain(row: WhyRow, rubric: RubricView | null): WhyBody;
+/**
+ * What a model or a handler wrote, minus anything that could identify someone: contact details,
+ * identifiers, places, long numbers, plate-shaped tokens and long verbatim quotes become
+ * `[hidden]`; whitespace is collapsed and the result capped. Empty in, empty out.
+ */
+export declare function sanitise(text: string): string;
+export {};
+//# sourceMappingURL=explain.d.ts.map

package/dist/lib/openhands/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/lib/openhands/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,MAAM,MAAM,GAAG,IAAI,CACvB,WAAW,EACT,SAAS,GACT,cAAc,GACd,UAAU,GACV,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,UAAU,GACV,OAAO,GACP,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AACrE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9E,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,SAAS,CAAC;QACxB,KAAK,CAAC,EAAE,SAAS,CAAC;KACnB,EAAE,CAAC;IACJ,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAQD,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAuC1D;AAqMD,yFAAyF;AACzF,wBAAgB,WAAW,IAAI,OAAO,CAMrC;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAoLvE;AAsDD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB7C"}

package/dist/lib/openhands/explain.js

@@ -0,0 +1,499 @@
+/**
+ * The claimant's "why", built from what this oracle already holds for a claim: the decision row
+ * (the engine's gate and criterion outcomes, its receipt, the frozen `ext`/`ai` facts, the
+ * `erroredFacts`) and the pinned rubric's own words (labels, limits, the duplicate and frequency
+ * rules). Pure — `why.ts` reads the row and the rubric and serves what this returns. Ported from
+ * openhands-oracles `core/src/openhands/explain.ts` minus its campaign label table: a fact is
+ * labelled by the rubric's own sentence (an AI check) or by its name, never by a provider's word.
+ *
+ * DISPLAY ONLY. The rubric is read for its public sentences after the engine decided; nothing here
+ * binds, validates or decides — the engine's `Decision` is the only verdict, `outcomeOf` reads it.
+ *
+ * One generic mapper, never a case per claim: each gate and criterion is explained through the ONE
+ * fact its condition reads (`ext.<name>` / `ai.<name>`), or through the claim fields it tests.
+ *
+ * WORKER-SAFE by construction. Nothing reaches the body verbatim except the rubric's own sentences
+ * (the protocol's public text) and the AI's sentence about the claimant's own submission, sanitised.
+ * An `ext` reason is NEVER echoed — a provider's reason may name other claims or places — only
+ * numbers read out of the stock geo handlers' measurement grammar (`facts/geo.ts`:
+ * `<n> m from centre, limit <m> m; evidence: …`, `<n> m apart, limit <m> m`). The engine's
+ * `duplicate` / `frequency` reason lines name the matching claim, so those gates are explained from
+ * the rubric alone. No model prompt (`aiChecks[].instructions`) is ever read.
+ */
+const str = (v) => (typeof v === "string" && v ? v : undefined);
+const obj = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+const list = (v) => Array.isArray(v) ? v.map(obj).filter((x) => !!x) : [];
+/** A `#rub` envelope (`{ rubric: {...} }`) → the view; null when it is not a rubric at all. */
+export function rubricView(doc) {
+    const rubric = obj(obj(doc)?.rubric);
+    if (!rubric)
+        return null;
+    const scoring = obj(rubric.scoring);
+    const unique = obj(rubric.unique);
+    const frequency = obj(rubric.frequency);
+    const tasks = {};
+    for (const task of list(obj(rubric.review)?.tasks)) {
+        const id = str(task.id);
+        if (id)
+            tasks[id] = str(task.forCriterion) ?? null;
+    }
+    return {
+        gates: list(rubric.gates).flatMap((g) => {
+            const code = str(g.code);
+            return code
+                ? [{ code, reason: str(g.reason), when: obj(g.when), onFail: str(g.onFail) }]
+                : [];
+        }),
+        criteria: list(scoring?.criteria).flatMap((c) => {
+            const code = str(c.code);
+            return code
+                ? [{ code, reason: str(c.reason), appliesWhen: obj(c.appliesWhen), score: obj(c.score) }]
+                : [];
+        }),
+        tasks,
+        ...(str(unique?.id)
+            ? { unique: { id: str(unique?.id), label: str(unique?.label) } }
+            : {}),
+        ...(str(frequency?.id)
+            ? {
+                frequency: {
+                    id: str(frequency?.id),
+                    label: str(frequency?.label),
+                    max: typeof frequency?.max === "number" ? frequency.max : undefined,
+                    per: str(frequency?.per),
+                },
+            }
+            : {}),
+    };
+}
+/** Every `{ field, op, value }` leaf of a condition tree (`all` / `any` / `not` / a score's `when`). */
+function leaves(node, out = []) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            leaves(n, out);
+    }
+    else if (node && typeof node === "object") {
+        const o = node;
+        if (typeof o.field === "string")
+            out.push(o);
+        for (const [k, v] of Object.entries(o))
+            if (k !== "value")
+                leaves(v, out);
+    }
+    return out;
+}
+/** The facts a condition reads, each once, with a `.score` threshold where it compares one. */
+function factRefs(...nodes) {
+    const refs = new Map();
+    for (const leaf of nodes.flatMap((n) => leaves(n))) {
+        const m = /^(ext|ai)\.([A-Za-z0-9_]+)\.(valid|score)$/.exec(leaf.field);
+        if (!m)
+            continue;
+        const key = `${m[1]}.${m[2]}`;
+        const ref = refs.get(key) ?? { lane: m[1], name: m[2] };
+        if (m[3] === "score" && typeof leaf.value === "number" && /^>=?$/.test(String(leaf.op))) {
+            ref.threshold = Math.max(ref.threshold ?? 0, leaf.value);
+        }
+        refs.set(key, ref);
+    }
+    return [...refs.values()];
+}
+// --- labels ---------------------------------------------------------------------------------------
+const humanise = (s) => s
+    .replace(/^\$/, "")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/[._-]+/g, " ")
+    .trim()
+    .replace(/^./, (c) => c.toUpperCase())
+    .replace(/(?<=\s)([A-Z])(?=[a-z])/g, (c) => c.toLowerCase());
+const capped = (s, n = 160) => s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
+/** An AI check's gate reason IS the criterion the claimant was shown; any other fact, its name. */
+function factLabel(ref, rubricReason) {
+    if (ref.lane === "ai" && rubricReason)
+        return capped(rubricReason);
+    return humanise(ref.name);
+}
+/** A gate that reads only claim fields, labelled by what it tests. */
+function fieldLabel(when, rubricReason) {
+    const ops = leaves(when);
+    const op = String(ops[0]?.op ?? "");
+    const fields = [...new Set(ops.map((l) => String(l.field)))];
+    const what = fields.length === 1 ? humanise(fields[0] ?? "") : "Files";
+    if (op === "present")
+        return `${what} handed in`;
+    if (op === "mediaTypeIn")
+        return `${what === "Files" ? "File" : what} type`;
+    if (op === "maxSizeMB")
+        return `${what === "Files" ? "File" : what} size`;
+    return rubricReason ? capped(rubricReason) : what;
+}
+const fmt = (n) => n.toLocaleString("en-US", { maximumFractionDigits: 2 });
+/** The package's measurement grammar: the distance and its limit, never the rest of the reason. */
+function measured(reason) {
+    const m = /(\d+(?:\.\d+)?) m (from centre|apart|from the reported point)(?:, limit (\d+(?:\.\d+)?) m)?/.exec(reason);
+    if (!m)
+        return null;
+    return {
+        value: Number(m[1]),
+        apart: m[2] === "apart",
+        ...(m[3] ? { threshold: Number(m[3]) } : {}),
+    };
+}
+/** Who wrote a fact's time and place, from the grade its reason carries. */
+function gradeOf(fact, errored) {
+    if (errored && NO_TIME_PLACE.test(errored))
+        return "none";
+    const reason = fact?.status === "ok" ? (fact.reason ?? "") : "";
+    if (/evidence: .*\b(?:browser-reported|claim) \(/.test(reason))
+        return "browser-reported";
+    if (/browser-reported/.test(reason))
+        return "browser-reported";
+    if (/evidence: .*\bcamera \(/.test(reason))
+        return "camera";
+    return null;
+}
+const NO_TIME_PLACE = /no (?:EXIF|timestamp|GPS|capture time|coordinates)|no timestamp or GPS/i;
+/**
+ * The stock pair check's `evidence: time T, place P` (P may name each photo, `a / b`) → the
+ * worker's two words for it. The claim's own lat/lon is the claimant's word, so it reads as
+ * browser-reported; the weakest source on either side wins.
+ */
+function gradeText(reason) {
+    const m = /evidence: time ([^;]+?)(?:, place ([^;]+))?$/.exec(reason);
+    if (!m)
+        return null;
+    const short = (s) => /\b(?:browser-reported|claim) \(/.test(s) ? "browser-reported" : "camera";
+    const time = short(m[1] ?? "");
+    const place = m[2] ? short(m[2]) : time;
+    return time === place ? `Time/place: ${time}` : `Time: ${time}, place: ${place}`;
+}
+const HELD = "could not be checked automatically: held for a person";
+/** One gate or criterion, explained through the one fact it reads. */
+function factReason(code, result, ref, fact, errored, rubricReason) {
+    const label = factLabel(ref, rubricReason);
+    const base = { code, label, result };
+    if (result === "error" || fact?.status === "error") {
+        const text = errored ?? fact?.detail ?? "";
+        const held = result === "error" ? ": held for a person" : "";
+        return {
+            ...base,
+            detail: NO_TIME_PLACE.test(text)
+                ? `No photo time/GPS${held}`
+                : `${label}: could not be checked automatically${held}`,
+        };
+    }
+    if (result === "review")
+        return { ...base, detail: `${label}: a person is checking this` };
+    const reason = fact?.reason ?? "";
+    if (typeof fact?.value === "number" &&
+        fact.value >= 0 &&
+        fact.value <= 10_000 &&
+        ref.lane === "ext" &&
+        !measured(reason) &&
+        ref.threshold !== undefined) {
+        const pct = Math.round(fact.value / 100);
+        const needs = Math.round(ref.threshold / 100);
+        return {
+            ...base,
+            detail: `${label}: ${pct}% (needs ${needs}%)`,
+            value: pct,
+            threshold: needs,
+            unit: "%",
+        };
+    }
+    if (ref.lane === "ext") {
+        const m = measured(reason);
+        const grade = gradeText(reason);
+        if (m) {
+            const limit = m.threshold !== undefined ? ` (limit ${fmt(m.threshold)} m)` : "";
+            return {
+                ...base,
+                detail: `${label}: ${fmt(m.value)} m${m.apart ? " apart" : ""}${limit}${grade ? `; ${grade}` : ""}`,
+                value: m.value,
+                ...(m.threshold !== undefined ? { threshold: m.threshold } : {}),
+                unit: "m",
+            };
+        }
+        if (grade && result === "pass")
+            return { ...base, detail: grade };
+    }
+    if (result === "pass")
+        return { ...base, detail: "Passed" };
+    if (ref.lane === "ai" && reason) {
+        const said = sanitise(reason);
+        if (said)
+            return { ...base, detail: said };
+    }
+    return { ...base, detail: rubricReason ?? "Did not pass" };
+}
+// --- the mapper -----------------------------------------------------------------------------------
+const GATE_RESULT = {
+    passed: "pass",
+    failed: "fail",
+    unevaluated: "error",
+    not_reached: null,
+    skipped: null,
+};
+function outcomeOf(row) {
+    if (!row.decision || row.status === "unusable" || row.status === "invalid_facts")
+        return "pending";
+    if (row.status === "pending_review" || row.verdict === "review")
+        return "review";
+    if (row.verdict === "approve" || row.verdict === "partial")
+        return "approved";
+    if (row.verdict === "reject")
+        return "rejected";
+    return "pending";
+}
+/** What this oracle holds for a claim it has seen but the engine has not yet decided. */
+export function pendingBody() {
+    return {
+        outcome: "pending",
+        summary: "Not decided yet: the checks on your claim are still running.",
+        reasons: [],
+    };
+}
+export function explain(row, rubric) {
+    const outcome = outcomeOf(row);
+    const decision = row.decision;
+    const receipt = row.receiptCid ? { receiptCid: row.receiptCid } : {};
+    if (!decision || outcome === "pending") {
+        return {
+            ...pendingBody(),
+            summary: "Not decided yet: your claim could not be checked automatically. Nothing is needed from you.",
+            ...receipt,
+        };
+    }
+    const ext = (row.facts?.ext ?? {});
+    const ai = (row.facts?.ai ?? {});
+    const factOf = (ref) => (ref.lane === "ext" ? ext : ai)[ref.name];
+    // `erroredFacts` (the engine's copy of what errored) when it sent one, else the frozen facts'.
+    const errored = new Map();
+    for (const e of row.erroredFacts ?? [])
+        errored.set(e.name, e.detail);
+    for (const [lane, facts] of [
+        ["ext", ext],
+        ["ai", ai],
+    ]) {
+        for (const [name, f] of Object.entries(facts)) {
+            if (f.status === "error" && f.detail && !errored.has(`${lane}.${name}`)) {
+                errored.set(`${lane}.${name}`, f.detail);
+            }
+        }
+    }
+    const erroredOf = (ref) => errored.get(`${ref.lane}.${ref.name}`);
+    const reasons = [];
+    const seen = new Set();
+    const push = (r) => {
+        // A criterion that restates its gate (same fact, same answer) is said once.
+        const key = `${r.result}|${r.label}|${r.detail}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        reasons.push(r);
+    };
+    const engineReason = (code) => decision.reasons.find((r) => r.code === code)?.reason;
+    // A review fold never rewrites gates: a gate that held the claim for a person stays `failed`,
+    // and the person's answer is a reason line (decide.ts, S11 settle). Say what the person said.
+    const settled = decision.reasons.find((r) => / by human review$/.test(r.reason))?.reason;
+    for (const gate of decision.gates) {
+        const result = GATE_RESULT[gate.outcome] ?? null;
+        if (!result)
+            continue;
+        // Engine-synthetic gates: their reason lines name the matching claim — the rubric speaks instead.
+        if (gate.code.startsWith("unique:")) {
+            const id = gate.code.slice("unique:".length);
+            push({
+                code: id,
+                label: rubric?.unique?.label ?? "Photo not used before",
+                result,
+                detail: result === "fail" ? "This photo was already used in another claim" : "Passed",
+            });
+            continue;
+        }
+        if (gate.code.startsWith("frequency:")) {
+            const id = gate.code.slice("frequency:".length);
+            const f = rubric?.frequency;
+            push({
+                code: id,
+                label: f?.label ?? "Claim limit",
+                result,
+                detail: result !== "fail"
+                    ? "Passed"
+                    : f?.max !== undefined && f.per
+                        ? `Limit reached: at most ${fmt(f.max)} claims a ${f.per}`
+                        : "Limit reached",
+                ...(f?.max !== undefined ? { threshold: f.max } : {}),
+            });
+            continue;
+        }
+        const spec = rubric?.gates.find((g) => g.code === gate.code);
+        // An approved claim cannot carry a hard failed gate, so without the rubric it was a review gate.
+        if (settled &&
+            result === "fail" &&
+            (spec ? spec.onFail === "review" : outcome === "approved")) {
+            push({
+                code: gate.code,
+                label: "Checked by a person",
+                result: outcome === "approved" ? "pass" : "fail",
+                detail: `${settled.replace(/ by human review$/, "")} by a person`,
+            });
+            continue;
+        }
+        const reasonText = spec?.reason ?? engineReason(gate.code);
+        const refs = factRefs(spec?.when);
+        const [only] = refs;
+        if (only && refs.length === 1) {
+            push(factReason(gate.code, result, only, factOf(only), erroredOf(only), reasonText));
+        }
+        else {
+            const label = spec ? fieldLabel(spec.when, reasonText) : humanise(gate.code);
+            push({
+                code: gate.code,
+                label,
+                result,
+                detail: result === "pass"
+                    ? "Passed"
+                    : result === "fail"
+                        ? (reasonText ?? "Did not pass")
+                        : `${label}: ${HELD}`,
+            });
+        }
+    }
+    const reviewed = new Set();
+    for (const c of decision.criteria) {
+        const spec = rubric?.criteria.find((s) => s.code === c.code);
+        let result;
+        if (c.pending)
+            result = "review";
+        else if (c.scoreBps === null)
+            result = null;
+        else
+            result = c.scoreBps >= 5000 ? "pass" : "fail";
+        if (!result)
+            continue;
+        if (result === "review")
+            reviewed.add(c.code);
+        const refs = factRefs(spec?.appliesWhen, spec?.score);
+        const [only] = refs;
+        if (only && refs.length === 1 && result !== "review") {
+            push(factReason(c.code, result, only, factOf(only), erroredOf(only), spec?.reason));
+        }
+        else {
+            const label = spec?.reason ? capped(spec.reason) : humanise(c.code);
+            push({
+                code: c.code,
+                label,
+                result,
+                detail: result === "review"
+                    ? "A person is checking this"
+                    : result === "pass"
+                        ? "Passed"
+                        : "Did not pass",
+            });
+        }
+    }
+    if (outcome === "review" && !reasons.some((r) => r.result === "error" || r.result === "review")) {
+        const task = decision.pendingTasks.find((t) => !reviewed.has(rubric?.tasks[t] ?? ""));
+        if (task) {
+            push({
+                code: task,
+                label: "Checked by a person",
+                result: "review",
+                detail: "A person is checking your claim",
+            });
+        }
+    }
+    const grades = Object.entries(ext)
+        .map(([name, f]) => gradeOf(f, errored.get(`ext.${name}`)))
+        .filter((g) => g !== null);
+    const evidenceGrade = grades.includes("none")
+        ? "none"
+        : grades.includes("browser-reported")
+            ? "browser-reported"
+            : grades.includes("camera")
+                ? "camera"
+                : undefined;
+    const note = outcome === "review"
+        ? [...errored.values()]
+            .map((d) => sanitise(d.replace(/^[A-Za-z0-9_]+: /, "")))
+            .filter(Boolean)
+            .join(" · ")
+        : "";
+    return {
+        outcome,
+        summary: summaryOf(outcome, row.verdict, reasons),
+        reasons,
+        ...(evidenceGrade ? { evidenceGrade } : {}),
+        ...(note ? { reviewNote: capped(note, REASON_CAP) } : {}),
+        ...receipt,
+    };
+}
+const sentence = (s) => (/[.!?…]$/.test(s) ? s : `${s}.`);
+function summaryOf(outcome, verdict, reasons) {
+    if (outcome === "approved") {
+        return verdict === "partial"
+            ? "Approved in part: some checks fell short."
+            : "Approved: every check passed.";
+    }
+    if (outcome === "rejected") {
+        const first = reasons.find((r) => r.result === "fail");
+        return first ? `Rejected. ${sentence(first.detail)}` : "Rejected.";
+    }
+    const held = reasons.find((r) => r.result === "error" || r.result === "review");
+    return held
+        ? `Held for a person to check. ${sentence(held.result === "review" ? held.label : held.detail)}`
+        : "Held for a person to check.";
+}
+// --- sanitising the AI's sentence and the errored details ------------------------------------------
+const REASON_CAP = 280;
+const HIDDEN = "[hidden]";
+const URL_RE = /\b(?:https?:\/\/|www\.)\S+/gi;
+const EMAIL_RE = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+/** A DID, a CID, a chain address, a hash — any identifier that could name another claim or person. */
+const DID_RE = /\bdid:[a-z0-9]+:[^\s,;)]+/gi;
+const ID_TOKEN_RE = /\b(?:baf[a-z2-7]{20,}|[A-Za-z0-9]{30,}|(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{12,})\b/g;
+/** A lat/lon pair, or one coordinate precise enough to place someone (4+ decimals). */
+const COORD_PAIR_RE = /-?\d{1,3}\.\d+\s*[,;/ ]\s*-?\d{1,3}\.\d+/g;
+const COORD_ONE_RE = /-?\d{1,3}\.\d{4,}/g;
+/** Phone-shaped runs; only hidden when they carry 7+ digits, so "2 - 3 bags" survives. */
+const PHONE_RE = /\+?\(?\d[\d\s().-]{5,}\d/g;
+const LONG_DIGITS_RE = /\d{6,}/g;
+/** One token of 5–8 letters/digits — a plate when it mixes 2+ letters with 2+ digits. */
+const PLATE_TOKEN_RE = /\b[A-Za-z0-9]{5,8}\b/g;
+/** Two short upper-case groups split by a space or hyphen — "AB12 CDE", "KA-01 MX". */
+const PLATE_SPACED_RE = /\b[A-Z0-9]{2,4}[ -][A-Z0-9]{2,4}\b/g;
+/**
+ * Text the model quoted verbatim (a sign, a label, something written) once it runs to 4+ words.
+ * A single quote only opens after whitespace, so the apostrophes in "claimant's … isn't" never
+ * pair up into a quote.
+ */
+const QUOTED_RE = /["“]([^"“”]*)["”]|‘([^‘’]*)’|(?<=^|\s)'([^']*)'(?=[\s.,;:!?)]|$)/g;
+const digits = (s) => (s.match(/\d/g) ?? []).length;
+const letters = (s) => (s.match(/[A-Za-z]/g) ?? []).length;
+const plateLike = (s) => {
+    const alnum = s.replace(/[^A-Za-z0-9]/g, "");
+    return alnum.length >= 5 && alnum.length <= 8 && digits(alnum) >= 2 && letters(alnum) >= 2;
+};
+/**
+ * What a model or a handler wrote, minus anything that could identify someone: contact details,
+ * identifiers, places, long numbers, plate-shaped tokens and long verbatim quotes become
+ * `[hidden]`; whitespace is collapsed and the result capped. Empty in, empty out.
+ */
+export function sanitise(text) {
+    let out = text
+        .replace(URL_RE, HIDDEN)
+        .replace(EMAIL_RE, HIDDEN)
+        .replace(DID_RE, HIDDEN)
+        .replace(ID_TOKEN_RE, HIDDEN)
+        .replace(COORD_PAIR_RE, HIDDEN)
+        .replace(COORD_ONE_RE, HIDDEN)
+        .replace(PHONE_RE, (m) => (digits(m) >= 7 ? HIDDEN : m))
+        .replace(LONG_DIGITS_RE, HIDDEN)
+        .replace(PLATE_SPACED_RE, (m) => (plateLike(m) ? HIDDEN : m))
+        .replace(PLATE_TOKEN_RE, (m) => (plateLike(m) ? HIDDEN : m))
+        .replace(QUOTED_RE, (m, a, b, c) => (a ?? b ?? c ?? "").trim().split(/\s+/).length >= 4 ? `"${HIDDEN}"` : m);
+    out = out.replace(/\s+/g, " ").trim();
+    return capped(out, REASON_CAP);
+}
+//# sourceMappingURL=explain.js.map