@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/facts/geo.js

@@ -0,0 +1,267 @@
+/**
+ * Ready-made `ExtHandler`s for the location checks a rubric cannot ask the decision engine to run
+ * itself (the engine has no geo operators — plan §4.3 D5): `withinRadius`, `located`, `beforeAfter`.
+ * A provider imports the one it needs and registers it under whatever source name their rubric
+ * declares — `defineFacts({ ext: { deliveredNearby: withinRadius } })` — rather than the kit
+ * dispatching on a name prefix, so a provider's `defineFacts` table stays the one place that says
+ * which name means what.
+ *
+ * EVIDENCE IS GRADED by who said when and where (eval critique P0-3, promoted from Spongy Shine's
+ * `pairOrder`), and the grade is written into every reason so it lands in the trace and receipt:
+ *
+ *   - `camera` — the photo's own EXIF (GPS, `DateTimeOriginal`);
+ *   - `browser-reported` — EXIF an app wrote from the browser's reading into a photo that had none
+ *     (`Software` is one of {@link APP_EXIF_SOFTWARE}), or the claim's per-photo
+ *     `capturedAt.<role>` reading (`{ at, lat?, lon?, accuracy? }`, `role` = `before` / `after` /
+ *     `photo`);
+ *   - `claim` — the answer's own `send.lat`/`send.lon` (a point the claimant's form reported).
+ *
+ * Client-supplied EXIF is editable, so a grade says where a value came FROM, never that it is true.
+ *
+ * MISSING EVIDENCE IS AN ERROR, never `false`. `false` means "the evidence says no" (too far, out
+ * of order); a claimant whose phone hid its location, or whose photo lost its EXIF on the way
+ * (forwarded through a messenger, a screenshot, a canvas resize), answered nothing either way — so
+ * it is `fact.error(...)` naming what was missing, and the rubric's own `onError` decides. The one
+ * exception is `located`, whose whole question IS "is there a point".
+ */
+import { rootQuestionName } from "../lib/facts/stock/send.js";
+import { photoFactsFromJpeg } from "./exif.js";
+import { fact } from "./fact.js";
+/** A photo attachment this large or larger is refused before it is even fetched (kit-wide cap). */
+const MAX_PHOTO_BYTES = 25_000_000;
+/** Mean earth radius (metres) — the constant behind every `haversineMeters` call in this file. */
+const EARTH_RADIUS_METERS = 6_371_000;
+/** Great-circle distance between two points, in metres. */
+export function haversineMeters(a, b) {
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(b.lat - a.lat);
+    const dLon = toRad(b.lon - a.lon);
+    const sinLat = Math.sin(dLat / 2);
+    const sinLon = Math.sin(dLon / 2);
+    const h = sinLat * sinLat + Math.cos(toRad(a.lat)) * Math.cos(toRad(b.lat)) * sinLon * sinLon;
+    return 2 * EARTH_RADIUS_METERS * Math.asin(Math.sqrt(h));
+}
+/** `send.lat`/`send.lon` (or any two numeric-or-numeric-string fields) as a bounds-checked point. */
+function numberIn(value, min, max) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) && n >= min && n <= max ? n : null;
+}
+function reportedPoint(send) {
+    const lat = numberIn(send.lat, -90, 90);
+    const lon = numberIn(send.lon, -180, 180);
+    return lat !== null && lon !== null ? { lat, lon } : null;
+}
+/** A `send` value as a finite number, or null when absent/blank/not-a-number. */
+function finiteNumber(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * The `Software` values that mean "the time and place in this EXIF are the BROWSER's, written by
+ * the capturing app into a photo that carried none" — browser-reported, not camera, evidence. The
+ * Openhands app stamps `openhands-app` (openhands-sdk `geo/exifnote.ts`); an app that does the same
+ * adds its own stamp here.
+ */
+const APP_EXIF_SOFTWARE = ["openhands-app"];
+/** The grade of what a photo's own EXIF says. */
+const exifGrade = (facts) => facts.software !== null && APP_EXIF_SOFTWARE.includes(facts.software)
+    ? "browser-reported"
+    : "camera";
+/**
+ * `send[key]`'s photo, read for its EXIF. The RAW `$ref` in `input.expected.send` — never the
+ * resolved value — says which question the attachment lives on (`rootQuestionName`); the resolved
+ * `send[key]` is not an attachment descriptor at all and is never consulted here.
+ */
+async function photoFactsFor(input, tools, key) {
+    const ref = input.expected.send[key];
+    const question = ref !== undefined ? rootQuestionName(String(ref)) : undefined;
+    const attachment = question ? tools.attachments.on(question)[0] : undefined;
+    if (!attachment)
+        return { kind: "none" };
+    const body = await tools.attachments.bytes(attachment, { maxBytes: MAX_PHOTO_BYTES });
+    if (!body.ok)
+        return { kind: "error", error: fact.error(`photo ${body.reason}`) };
+    return { kind: "facts", facts: photoFactsFromJpeg(body.bytes) };
+}
+/** An ISO instant as epoch ms; a stamp with no zone is read as UTC. Null for anything else. */
+function instant(value) {
+    if (typeof value !== "string" || value.trim() === "")
+        return null;
+    const text = value.trim();
+    const ms = Date.parse(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(text) ? text : `${text}Z`);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * `answers.capturedAt[role]` — the browser's reading as that photo was taken:
+ * `{ at: <ISO instant>, lat?, lon?, accuracy? }`. Absent or malformed fields are null.
+ */
+function capturedAtOf(input, role) {
+    const all = input.answers.capturedAt;
+    const shot = all && typeof all === "object" ? all[role] : null;
+    if (!shot || typeof shot !== "object")
+        return { at: null, point: null };
+    const fields = shot;
+    return { at: instant(fields.at), point: reportedPoint(fields) };
+}
+/**
+ * The shared coordinate resolution for `withinRadius`/`located`, in order: the answer's own
+ * `lat`/`lon` (the rubric pointed at them), the `photo` attachment's EXIF GPS, then the photo's
+ * `capturedAt` reading (`capturedAt.photo`, else `capturedAt.after` — the after photo of a pair is
+ * where the work ended). No point from any of them is `none`.
+ */
+async function claimPoint(input, tools) {
+    const reported = reportedPoint(input.send);
+    if (reported) {
+        return {
+            kind: "point",
+            at: { point: reported, grade: "claim", source: "the answer's lat/lon" },
+        };
+    }
+    const resolved = await photoFactsFor(input, tools, "photo");
+    if (resolved.kind === "error")
+        return resolved;
+    if (resolved.kind === "facts" && resolved.facts.point) {
+        const grade = exifGrade(resolved.facts);
+        return { kind: "point", at: { point: resolved.facts.point, grade, source: "photo EXIF" } };
+    }
+    for (const role of ["photo", "after"]) {
+        const noted = capturedAtOf(input, role).point;
+        if (noted) {
+            return {
+                kind: "point",
+                at: { point: noted, grade: "browser-reported", source: `capturedAt.${role}` },
+            };
+        }
+    }
+    return { kind: "none" };
+}
+const evidence = (at) => `evidence: ${at.grade} (${at.source})`;
+const NO_POINT = "no coordinates from any source (the answer's lat/lon, the photo's EXIF GPS, capturedAt)";
+/** `send: { lat?, lon?, photo?, centerLat, centerLon, meters }` — is the claim within `meters` of centre? */
+export const withinRadius = async (input, tools) => {
+    const centerLat = numberIn(input.send.centerLat, -90, 90);
+    const centerLon = numberIn(input.send.centerLon, -180, 180);
+    const meters = finiteNumber(input.send.meters);
+    if (centerLat === null || centerLon === null || meters === null) {
+        return fact.error("withinRadius: centerLat, centerLon and meters are required");
+    }
+    const resolved = await claimPoint(input, tools);
+    if (resolved.kind === "error")
+        return resolved.error;
+    // Nothing to measure is not "too far": the rubric's onError decides (P0-3).
+    if (resolved.kind === "none")
+        return fact.error(`withinRadius: ${NO_POINT}`);
+    const d = haversineMeters(resolved.at.point, { lat: centerLat, lon: centerLon });
+    return fact.ok(d <= meters, {
+        reason: `${Math.round(d)} m from centre, limit ${meters} m; ${evidence(resolved.at)}`,
+    });
+};
+/**
+ * `send: { lat?, lon?, photo? }` — does the claim carry coordinates at all, from any source? The
+ * one geo check where "none" IS the answer to the question asked, so it stays `false`.
+ */
+export const located = async (input, tools) => {
+    const resolved = await claimPoint(input, tools);
+    if (resolved.kind === "error")
+        return resolved.error;
+    return fact.ok(resolved.kind === "point", {
+        reason: resolved.kind === "point" ? `coordinates present; ${evidence(resolved.at)}` : NO_POINT,
+    });
+};
+/**
+ * `send: { before, after, meters?, lat?, lon? }` — two photo attachments, `before` and `after`,
+ * each its own question: `after` must be taken at or after `before`, and (when `meters` is given)
+ * the two places must be within it. `meters` absent skips the place entirely — no GPS is needed.
+ *
+ * TIME comes from ONE source for both photos (an EXIF stamp is local time with no zone and a
+ * `capturedAt` an instant, so one of each never orders a pair): both photos' EXIF, else both
+ * `capturedAt.before/after.at`. The claim's single `lat`/`lon` cannot order two photos, so it is
+ * never a time source. PLACE may differ per photo — two points on a map always compare — in order:
+ * the photo's EXIF GPS, its `capturedAt` point, then the claim's `send.lat`/`send.lon`. A pair
+ * placed only by the claim's one point is in order but its distance is not measured.
+ */
+export const beforeAfter = async (input, tools) => {
+    const exif = {};
+    for (const role of ["before", "after"]) {
+        const photo = await photoFactsFor(input, tools, role);
+        if (photo.kind === "error")
+            return photo.error;
+        if (photo.kind === "none")
+            return fact.error(`beforeAfter: no ${role} photo attached`);
+        exif[role] = photo.facts;
+    }
+    const captured = { before: capturedAtOf(input, "before"), after: capturedAtOf(input, "after") };
+    let time = null;
+    const stamps = { before: exif.before.takenAt, after: exif.after.takenAt };
+    if (stamps.before && stamps.after) {
+        const grades = new Set([exifGrade(exif.before), exifGrade(exif.after)]);
+        time = {
+            before: Date.parse(`${stamps.before}Z`),
+            after: Date.parse(`${stamps.after}Z`),
+            show: (r) => stamps[r] ?? "",
+            grade: `${grades.has("browser-reported") ? "browser-reported" : "camera"} (photo EXIF)`,
+        };
+    }
+    else if (captured.before.at !== null && captured.after.at !== null) {
+        const at = { before: captured.before.at, after: captured.after.at };
+        time = {
+            ...at,
+            show: (r) => new Date(at[r]).toISOString(),
+            grade: "browser-reported (capturedAt)",
+        };
+    }
+    if (!time) {
+        return fact.error("beforeAfter: no capture time for both photos from one source (photo EXIF, capturedAt)");
+    }
+    const meters = finiteNumber(input.send.meters);
+    const claim = reportedPoint(input.send);
+    const placeOf = (role) => {
+        const own = exif[role].point;
+        if (own)
+            return { point: own, grade: exifGrade(exif[role]), source: "photo EXIF" };
+        const noted = captured[role].point;
+        if (noted)
+            return { point: noted, grade: "browser-reported", source: `capturedAt.${role}` };
+        return claim ? { point: claim, grade: "claim", source: "the answer's lat/lon" } : null;
+    };
+    const before = meters !== null ? placeOf("before") : null;
+    const after = meters !== null ? placeOf("after") : null;
+    if (meters !== null && (!before || !after)) {
+        const missing = [before ? null : "before", after ? null : "after"]
+            .filter(Boolean)
+            .join(" and ");
+        return fact.error(`beforeAfter: no place for the ${missing} photo from any source (photo EXIF, capturedAt, the answer's lat/lon)`);
+    }
+    const placeGrade = before && after
+        ? [...new Set([before, after].map((p) => `${p.grade} (${p.source})`))].join(" / ")
+        : null;
+    const graded = `evidence: time ${time.grade}${placeGrade ? `, place ${placeGrade}` : ""}`;
+    if (time.after < time.before) {
+        return fact.ok(false, {
+            reason: `after (${time.show("after")}) is before before (${time.show("before")}); ${graded}`,
+        });
+    }
+    const seconds = Math.round((time.after - time.before) / 1000);
+    if (meters === null || !before || !after) {
+        return fact.ok(true, {
+            reason: `after is ${seconds} s after before (distance not checked); ${graded}`,
+        });
+    }
+    if (before.grade === "claim" && after.grade === "claim") {
+        return fact.ok(true, {
+            reason: `after is ${seconds} s after before, one reported point for both (distance not measured); ${graded}`,
+        });
+    }
+    const d = haversineMeters(before.point, after.point);
+    if (d > meters) {
+        return fact.ok(false, { reason: `${Math.round(d)} m apart, limit ${meters} m; ${graded}` });
+    }
+    return fact.ok(true, {
+        reason: `after is ${seconds} s after before, ${Math.round(d)} m apart; ${graded}`,
+    });
+};
+//# sourceMappingURL=geo.js.map

package/dist/facts/geo.js.map

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

package/dist/facts/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@ixo/decision-oracle/facts` — everything a provider needs to write fact handlers, and nothing that
+ * needs a Worker to load. This subpath must import cleanly in plain node (a provider's unit tests
+ * run there), which is why it is types, the `fact` helpers, `defineFacts`, and pure readers — the
+ * claim-body path reader, the EXIF reader (`photoFactsFromJpeg`), the anchored-document reader
+ * (`readLinkedDoc`), and the ready-made geo handlers (`withinRadius`, `located`, `beforeAfter`) a
+ * provider registers under their own source names.
+ *
+ * ```ts
+ * import { defineFacts, fact, readAnswer } from "@ixo/decision-oracle/facts";
+ *
+ * export const facts = defineFacts({
+ *   ext: {
+ *     batchRegistered: async ({ send }, tools) => (await tools.http.json(…)).body?.ok === true,
+ *   },
+ *   ai: { "*": (input, tools) => tools.stock() },
+ * });
+ * ```
+ */
+/** The `$path` reader the package itself uses on a claim body — same grammar as the engine's binder. */
+export { resolveFieldPath as readAnswer, rootQuestionName } from "../lib/facts/stock/send.js";
+export type { PhotoFacts } from "./exif.js";
+export { photoFactsFromJpeg } from "./exif.js";
+export { defineFacts, fact, group, RetryLater } from "./fact.js";
+/** Ready-made ext handlers for location checks the engine cannot run itself — register under any name. */
+export { beforeAfter, haversineMeters, located, withinRadius } from "./geo.js";
+/** A chain-anchored document by its LinkedResource — Vault, IPFS or Matrix, hash-checked against its proof. */
+export type { LinkedDocRead, LinkedDocRef, ReadLinkedDocOptions } from "./linked-doc.js";
+export { linkedDocUrl, readLinkedDoc } from "./linked-doc.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/facts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/facts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wGAAwG;AACxG,OAAO,EAAE,gBAAgB,IAAI,UAAU,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC9D,0GAA0G;AAC1G,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC5E,+GAA+G;AAC/G,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,mBAAmB,SAAS,CAAC"}

package/dist/facts/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@ixo/decision-oracle/facts` — everything a provider needs to write fact handlers, and nothing that
+ * needs a Worker to load. This subpath must import cleanly in plain node (a provider's unit tests
+ * run there), which is why it is types, the `fact` helpers, `defineFacts`, and pure readers — the
+ * claim-body path reader, the EXIF reader (`photoFactsFromJpeg`), the anchored-document reader
+ * (`readLinkedDoc`), and the ready-made geo handlers (`withinRadius`, `located`, `beforeAfter`) a
+ * provider registers under their own source names.
+ *
+ * ```ts
+ * import { defineFacts, fact, readAnswer } from "@ixo/decision-oracle/facts";
+ *
+ * export const facts = defineFacts({
+ *   ext: {
+ *     batchRegistered: async ({ send }, tools) => (await tools.http.json(…)).body?.ok === true,
+ *   },
+ *   ai: { "*": (input, tools) => tools.stock() },
+ * });
+ * ```
+ */
+/** The `$path` reader the package itself uses on a claim body — same grammar as the engine's binder. */
+export { resolveFieldPath as readAnswer, rootQuestionName } from "../lib/facts/stock/send.js";
+export { photoFactsFromJpeg } from "./exif.js";
+export { defineFacts, fact, group, RetryLater } from "./fact.js";
+/** Ready-made ext handlers for location checks the engine cannot run itself — register under any name. */
+export { beforeAfter, haversineMeters, located, withinRadius } from "./geo.js";
+export { linkedDocUrl, readLinkedDoc } from "./linked-doc.js";
+//# sourceMappingURL=index.js.map

package/dist/facts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/facts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wGAAwG;AACxG,OAAO,EAAE,gBAAgB,IAAI,UAAU,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC9D,0GAA0G;AAC1G,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/facts/linked-doc.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `readLinkedDoc` — the ONE read of a chain-anchored document by its LinkedResource. Every entity
+ * doc this package GETs goes through it (the work order's `#vct`, the CLI's `#pro` / `#orz` / card
+ * reads, `rubric fetch-form`), and it is exported so a provider's adapter reads theirs the same way
+ * (an ask's `#done` or `#payoutTerms`, a `#rub` for its labels).
+ *
+ * WHERE. A `serviceEndpoint` is one of three public, unauthenticated spellings (OpenHands #222,
+ * 2f7857a — ask documents left Matrix media because unauthenticated Matrix reads may stop):
+ *   - the IXO Vault's public copy, `https://<network.>vfs.ixo.earth/public/cid/<cid>`;
+ *   - the IXO IPFS gateway, `https://ipfs.gateway.ixo.world/ipfs/<cid>` — or a bare `ipfs:<cid>` /
+ *     `ipfs://<cid>`, resolved through it (never a public gateway: they rate-limit);
+ *   - a Matrix media download URL, `https://<hs>/_matrix/media/v3/download/<server>/<id>` — older
+ *     asks and this package's own identity docs, which must keep reading.
+ * Anything else (`matrix:<cid>` room state, `mxc://`) is no fetchable document: `unsupported`.
+ *
+ * WHAT. The bytes are trusted by their hash alone, over EXACTLY what was served. The `proof` names
+ * the check by its shape (CLAUDE.md's proof rules): a raw-sha256 CIDv1 (`bafkrei…` — identity docs
+ * and every Vault/IPFS ask doc) or 64 hex (sha256 — `#vct`/`#rub`/`#orz` an owner uploaded). With no
+ * proof, the content address in the URL itself is the check. A proof of any other shape (a dag-pb
+ * `bafybei…`) cannot be recomputed from the bytes, so the read is returned `verified: false` for the
+ * caller to judge — never called a mismatch. A mismatch is deterministic and fails closed: the read
+ * is refused, never handed to another store to try.
+ *
+ * Node-safe (the `./facts` subpath): plain `fetch` unless the caller injects its own.
+ */
+export interface LinkedDocRef {
+    serviceEndpoint?: string | null;
+    /** The anchored content hash; absent ⇒ the URL's own content address (if any) is checked. */
+    proof?: string | null;
+}
+export interface ReadLinkedDocOptions {
+    /** The IPFS gateway an `ipfs:` endpoint resolves through. Default IXO's. */
+    ipfsGateway?: string;
+    /** The transport — e.g. the runtime's `fetchClient` with its retries. Default global `fetch`. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    headers?: Record<string, string>;
+    /** Default 10 s; only applied with the default transport. */
+    timeoutMs?: number;
+    /** Default `MAX_JSON_DOC_BYTES` (2 MiB). */
+    maxBytes?: number;
+}
+export type LinkedDocRead = {
+    ok: true;
+    url: string;
+    bytes: Uint8Array;
+    json: unknown;
+    verified: boolean;
+} | {
+    ok: false;
+    url: string | null;
+    reason: "unsupported" | "unreachable" | "status" | "too-large" | "mismatch" | "not-json";
+    /** Worth asking again later (the store was down, timed out or said 5xx/429); else final. */
+    retryable: boolean;
+    status?: number;
+    message: string;
+};
+/** The URL a `serviceEndpoint` is read from, or null when it names no fetchable document. */
+export declare function linkedDocUrl(endpoint: string, ipfsGateway?: string): string | null;
+export declare function readLinkedDoc(ref: LinkedDocRef, opts?: ReadLinkedDocOptions): Promise<LinkedDocRead>;
+//# sourceMappingURL=linked-doc.d.ts.map

package/dist/facts/linked-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linked-doc.d.ts","sourceRoot":"","sources":["../../src/facts/linked-doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC9E;IACE,EAAE,EAAE,KAAK,CAAC;IACV,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,aAAa,GAAG,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAAC;IACzF,4FAA4F;IAC5F,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAON,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQlF;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,YAAY,EACjB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA4DxB"}

package/dist/facts/linked-doc.js

@@ -0,0 +1,101 @@
+/**
+ * `readLinkedDoc` — the ONE read of a chain-anchored document by its LinkedResource. Every entity
+ * doc this package GETs goes through it (the work order's `#vct`, the CLI's `#pro` / `#orz` / card
+ * reads, `rubric fetch-form`), and it is exported so a provider's adapter reads theirs the same way
+ * (an ask's `#done` or `#payoutTerms`, a `#rub` for its labels).
+ *
+ * WHERE. A `serviceEndpoint` is one of three public, unauthenticated spellings (OpenHands #222,
+ * 2f7857a — ask documents left Matrix media because unauthenticated Matrix reads may stop):
+ *   - the IXO Vault's public copy, `https://<network.>vfs.ixo.earth/public/cid/<cid>`;
+ *   - the IXO IPFS gateway, `https://ipfs.gateway.ixo.world/ipfs/<cid>` — or a bare `ipfs:<cid>` /
+ *     `ipfs://<cid>`, resolved through it (never a public gateway: they rate-limit);
+ *   - a Matrix media download URL, `https://<hs>/_matrix/media/v3/download/<server>/<id>` — older
+ *     asks and this package's own identity docs, which must keep reading.
+ * Anything else (`matrix:<cid>` room state, `mxc://`) is no fetchable document: `unsupported`.
+ *
+ * WHAT. The bytes are trusted by their hash alone, over EXACTLY what was served. The `proof` names
+ * the check by its shape (CLAUDE.md's proof rules): a raw-sha256 CIDv1 (`bafkrei…` — identity docs
+ * and every Vault/IPFS ask doc) or 64 hex (sha256 — `#vct`/`#rub`/`#orz` an owner uploaded). With no
+ * proof, the content address in the URL itself is the check. A proof of any other shape (a dag-pb
+ * `bafybei…`) cannot be recomputed from the bytes, so the read is returned `verified: false` for the
+ * caller to judge — never called a mismatch. A mismatch is deterministic and fails closed: the read
+ * is refused, never handed to another store to try.
+ *
+ * Node-safe (the `./facts` subpath): plain `fetch` unless the caller injects its own.
+ */
+import { cidForBytes, sha256Hex } from "../lib/hash.js";
+import { MAX_JSON_DOC_BYTES, readCappedBytes } from "../lib/http/client.js";
+import { NETWORKS } from "../networks.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const RAW_CID = /^bafkrei[a-z2-7]{52}$/;
+const HEX_SHA256 = /^[0-9a-f]{64}$/i;
+const IN_URL_CID = /\/(?:ipfs|public\/cid)\/(bafkrei[a-z2-7]{52})(?:[/?#]|$)/;
+/** The URL a `serviceEndpoint` is read from, or null when it names no fetchable document. */
+export function linkedDocUrl(endpoint, ipfsGateway) {
+    const trimmed = endpoint.replace(/\s+/g, "");
+    const cid = /^ipfs:(?:\/\/)?([A-Za-z0-9]+)\/?$/i.exec(trimmed)?.[1];
+    if (cid) {
+        const gateway = ipfsGateway ?? NETWORKS.devnet.ipfsGateway;
+        return `${gateway.replace(/\/+$/, "")}/ipfs/${cid}`;
+    }
+    return /^https?:\/\//i.test(trimmed) ? trimmed : null;
+}
+export async function readLinkedDoc(ref, opts = {}) {
+    const endpoint = ref.serviceEndpoint ?? "";
+    const url = linkedDocUrl(endpoint, opts.ipfsGateway);
+    const fail = (reason, message, retryable = false, status) => ({ ok: false, url, reason, retryable, message, status });
+    if (!url)
+        return fail("unsupported", `not a fetchable document address: ${endpoint || "(none)"}`);
+    let res;
+    try {
+        const init = { headers: opts.headers };
+        res = opts.fetch
+            ? await opts.fetch(url, init)
+            : await fetch(url, {
+                ...init,
+                signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            });
+    }
+    catch (err) {
+        return fail("unreachable", `${url} unreachable (${String(err)})`, true);
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        const retryable = res.status >= 500 || res.status === 429 || res.status === 408;
+        return fail("status", `${url} answered ${res.status}`, retryable, res.status);
+    }
+    let bytes;
+    try {
+        bytes = await readCappedBytes(res, opts.maxBytes ?? MAX_JSON_DOC_BYTES);
+    }
+    catch (err) {
+        return fail("unreachable", `${url} body read failed (${String(err)})`, true);
+    }
+    if (!bytes)
+        return fail("too-large", `${url} exceeds ${opts.maxBytes ?? MAX_JSON_DOC_BYTES} B`);
+    // The integrity check: the anchored proof, else the address the URL itself names.
+    const expected = ref.proof?.trim() || IN_URL_CID.exec(url)?.[1] || "";
+    let verified = false;
+    if (RAW_CID.test(expected)) {
+        const got = await cidForBytes(bytes);
+        if (got !== expected)
+            return fail("mismatch", `${url} does not hash to ${expected} (got ${got})`);
+        verified = true;
+    }
+    else if (HEX_SHA256.test(expected)) {
+        const got = await sha256Hex(bytes);
+        if (got !== expected.toLowerCase()) {
+            return fail("mismatch", `${url} does not hash to ${expected} (got ${got})`);
+        }
+        verified = true;
+    }
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return fail("not-json", `${url} is not JSON`);
+    }
+    return { ok: true, url, bytes, json, verified };
+}
+//# sourceMappingURL=linked-doc.js.map

package/dist/facts/linked-doc.js.map

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