@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/facts/exif.js

@@ -0,0 +1,224 @@
+/**
+ * Where a photograph says it was taken, and when.
+ *
+ * Hand-rolled rather than a dependency: this reads two tags out of one container, it must load in
+ * plain node as readily as inside a Worker (the `./facts` subpath's whole point), and an EXIF
+ * library brings orientation, thumbnails, XMP, IPTC and a decoder for every camera maker's private
+ * notes to answer a question about six numbers.
+ *
+ * The format, briefly. A JPEG is segments beginning `FF D8`; the one marked `FF E1` and starting
+ * `Exif\0\0` holds a TIFF block, which has its own byte order (`II` little-endian or `MM`
+ * big-endian — cameras genuinely use both), a table of tags, and a pointer at tag `0x8825` to a
+ * second table holding the GPS tags. Latitude and longitude are each three rationals — degrees,
+ * minutes, seconds — with a separate tag saying N/S and E/W, and **the sign lives only in that
+ * letter**: a photograph taken in Chile carries a positive latitude and an `S`, and reading the
+ * number without the letter puts it in Canada.
+ *
+ * Everything is bounds-checked and every failure is `null`, because this is handed bytes from
+ * strangers. It is also **client-assisted evidence**: EXIF is trivially editable, and the geo
+ * handlers that read it (`./geo.ts`) say so in every reason they report.
+ *
+ * Ported from `openhands-geo/src/exif.ts` for `@ixo/decision-oracle/facts`'s geo handlers — the point
+ * is the inline `{ lat, lon }` below instead of Openhands's own `GeoPoint` type, so this module
+ * carries no dependency on that package.
+ */
+const GPS_IFD_POINTER = 0x8825;
+const EXIF_IFD_POINTER = 0x8769;
+/** When the shutter fired. `DateTimeOriginal` in the Exif sub-IFD... */
+const TAG_DATE_ORIGINAL = 0x9003;
+/** ...and `DateTime` in IFD0, which is the file's own modification stamp and
+    the weaker of the two — used only when the first is absent. */
+const TAG_DATE_MODIFIED = 0x0132;
+/** IFD0 `Software` — who wrote the file. An app that writes the BROWSER's time and place into a
+    photo with no EXIF of its own names itself here, which is what grades that evidence. */
+const TAG_SOFTWARE = 0x0131;
+const TAG_LAT_REF = 0x0001;
+const TAG_LAT = 0x0002;
+const TAG_LON_REF = 0x0003;
+const TAG_LON = 0x0004;
+/** Bytes per TIFF type code, indexed by the code itself. 0 = one we skip. */
+const TYPE_SIZE = [0, 1, 1, 2, 4, 8, 1, 1, 2, 4, 8, 4, 8];
+const u16 = (r, at) => r.view.getUint16(at, r.little);
+const u32 = (r, at) => r.view.getUint32(at, r.little);
+/** Three rationals — degrees, minutes, seconds — as one decimal degree. */
+function degrees(r, at, count) {
+    if (count < 3)
+        return null;
+    let total = 0;
+    for (let part = 0; part < 3; part += 1) {
+        const offset = at + part * 8;
+        if (offset + 8 > r.view.byteLength)
+            return null;
+        const denominator = u32(r, offset + 4);
+        if (denominator === 0)
+            return null;
+        total += u32(r, offset) / denominator / 60 ** part;
+    }
+    return total;
+}
+/** The one-letter reference, which carries the sign. */
+function letter(r, entry) {
+    const count = u32(r, entry + 4);
+    /* A value of four bytes or fewer is stored in the entry itself; anything
+       larger is a pointer. A single letter is always inline. */
+    const at = count <= 4 ? entry + 8 : r.base + u32(r, entry + 8);
+    return at < r.view.byteLength ? String.fromCharCode(r.view.getUint8(at)).toUpperCase() : "";
+}
+/**
+ * An ASCII value, for the date tags.
+ *
+ * EXIF dates are `YYYY:MM:DD HH:MM:SS` in **local time with no zone** — the standard simply has
+ * nowhere to put one. Two photographs from the same phone an hour apart are therefore comparable
+ * to each other, which is exactly and only what the before/after gate asks of them. Treating one
+ * as an instant on a world clock would be inventing a timezone.
+ */
+function ascii(r, entry) {
+    const count = u32(r, entry + 4);
+    if (count === 0 || count > 64)
+        return "";
+    const at = count <= 4 ? entry + 8 : r.base + u32(r, entry + 8);
+    if (at + count > r.view.byteLength)
+        return "";
+    let out = "";
+    for (let index = 0; index < count; index += 1) {
+        const code = r.view.getUint8(at + index);
+        if (code === 0)
+            break;
+        out += String.fromCharCode(code);
+    }
+    return out.trim();
+}
+/** `2026:09:20 09:35:12` → `2026-09-20T09:35:12`. Empty for anything else. */
+function exifDate(raw) {
+    const match = /^(\d{4}):(\d{2}):(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/.exec(raw);
+    if (!match)
+        return null;
+    const [, year, month, day, hour, minute, second] = match;
+    const iso = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+    return Number.isFinite(Date.parse(iso)) ? iso : null;
+}
+function readGpsIfd(r, at) {
+    if (at + 2 > r.view.byteLength)
+        return null;
+    const entries = u16(r, at);
+    if (entries > 200)
+        return null;
+    let lat = null;
+    let lon = null;
+    let latRef = "N";
+    let lonRef = "E";
+    for (let index = 0; index < entries; index += 1) {
+        const entry = at + 2 + index * 12;
+        if (entry + 12 > r.view.byteLength)
+            return null;
+        const tag = u16(r, entry);
+        const type = u16(r, entry + 2);
+        const count = u32(r, entry + 4);
+        const size = (TYPE_SIZE[type] ?? 0) * count;
+        const valueAt = size <= 4 ? entry + 8 : r.base + u32(r, entry + 8);
+        if (tag === TAG_LAT)
+            lat = degrees(r, valueAt, count);
+        else if (tag === TAG_LON)
+            lon = degrees(r, valueAt, count);
+        else if (tag === TAG_LAT_REF)
+            latRef = letter(r, entry);
+        else if (tag === TAG_LON_REF)
+            lonRef = letter(r, entry);
+    }
+    if (lat === null || lon === null)
+        return null;
+    /* The sign lives in the letter, and only there. */
+    const point = { lat: latRef === "S" ? -lat : lat, lon: lonRef === "W" ? -lon : lon };
+    return Math.abs(point.lat) <= 90 && Math.abs(point.lon) <= 180 ? point : null;
+}
+/** The coordinates and shutter time a JPEG carries; non-JPEG or no EXIF is `{ null, null }`. */
+export function photoFactsFromJpeg(bytes) {
+    const none = { point: null, takenAt: null, software: null };
+    try {
+        if (bytes.length < 12 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+            return none;
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        /* Walk the segment chain rather than scanning for a magic string: a byte
+           sequence spelling "Exif" can appear inside image data. */
+        let at = 2;
+        while (at + 4 <= bytes.length) {
+            if (bytes[at] !== 0xff)
+                return none;
+            /* In range by the loop's own bound; read defensively anyway, because every other
+               out-of-bounds read in this file answers `none` rather than trusting the arithmetic. */
+            const marker = bytes[at + 1];
+            if (marker === undefined)
+                return none;
+            /* Start of scan — the compressed image begins and metadata is behind us. */
+            if (marker === 0xda)
+                return none;
+            const length = view.getUint16(at + 2, false);
+            if (length < 2)
+                return none;
+            if (marker === 0xe1 && at + 10 <= bytes.length) {
+                const isExif = bytes[at + 4] === 0x45 &&
+                    bytes[at + 5] === 0x78 &&
+                    bytes[at + 6] === 0x69 &&
+                    bytes[at + 7] === 0x66;
+                if (isExif) {
+                    const base = at + 10;
+                    if (base + 8 > bytes.length)
+                        return none;
+                    const order = view.getUint16(base, false);
+                    if (order !== 0x4949 && order !== 0x4d4d)
+                        return none;
+                    const r = { view, base, little: order === 0x4949 };
+                    const first = u32(r, base + 4);
+                    const ifd0 = base + first;
+                    if (ifd0 + 2 > bytes.length)
+                        return none;
+                    const count = u16(r, ifd0);
+                    if (count > 200)
+                        return none;
+                    const found = { point: null, takenAt: null, software: null };
+                    let exifIfd = 0;
+                    for (let index = 0; index < count; index += 1) {
+                        const entry = ifd0 + 2 + index * 12;
+                        if (entry + 12 > bytes.length)
+                            return found;
+                        const tag = u16(r, entry);
+                        if (tag === GPS_IFD_POINTER)
+                            found.point = readGpsIfd(r, base + u32(r, entry + 8));
+                        else if (tag === EXIF_IFD_POINTER)
+                            exifIfd = base + u32(r, entry + 8);
+                        else if (tag === TAG_SOFTWARE)
+                            found.software = ascii(r, entry) || null;
+                        /* The weaker stamp, kept only until the real one turns up. */ else if (tag === TAG_DATE_MODIFIED)
+                            found.takenAt = exifDate(ascii(r, entry));
+                    }
+                    /* `DateTimeOriginal` lives in the Exif sub-IFD and is the shutter
+                       time — it wins over IFD0's file stamp, which an edit can move. */
+                    if (exifIfd && exifIfd + 2 <= bytes.length) {
+                        const subCount = u16(r, exifIfd);
+                        if (subCount <= 200) {
+                            for (let index = 0; index < subCount; index += 1) {
+                                const entry = exifIfd + 2 + index * 12;
+                                if (entry + 12 > bytes.length)
+                                    break;
+                                if (u16(r, entry) === TAG_DATE_ORIGINAL) {
+                                    const original = exifDate(ascii(r, entry));
+                                    if (original)
+                                        found.takenAt = original;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    return found;
+                }
+            }
+            at += 2 + length;
+        }
+        return none;
+    }
+    catch {
+        /* Bytes from a stranger. Absence is an answer; a crash is not. */
+        return none;
+    }
+}
+//# sourceMappingURL=exif.js.map

package/dist/facts/exif.js.map

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

package/dist/facts/fact.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `defineFacts()` and the `fact` helpers — the two things a provider writes against.
+ *
+ * `defineFacts({ ext, ai, unique, frequency })` is a DIFF against the stock producer: list the
+ * names you answer yourself, every other name in the work order keeps running its stock lane
+ * (lib/facts/runner.ts). `fact.*` builds what a handler returns when a bare `true`/`8200` isn't
+ * enough — a reason, a transcript, a failure. Note what is NOT here: no way to choose an
+ * `onError`. A fact that failed carries the RUBRIC's fallback, stamped by the runner, because the
+ * one thing a handler must never be able to do is turn its own failure into an approve.
+ *
+ * `fact.retryLater()` is the single exception, and it is a THROW, not a fact: "this wasn't the
+ * claim's fault, ask me again" — the runner turns it into `unavailable` so the workflow step
+ * retries instead of freezing a verdict.
+ *
+ * Node-safe (the `./facts` subpath): types and plain objects only.
+ */
+import type { AiFact, ExtFact, Transcript } from "../lib/facts/factset.js";
+import type { FactErrorDraft, FactGroup, FactsConfig, FactsDeclaration, GroupHandler } from "./types.js";
+/** `throw fact.retryLater(detail)` — the runner's only pass-through, as `AppError.unavailable`. */
+export declare class RetryLater extends Error {
+    readonly retryLater: true;
+    constructor(detail: string);
+}
+export declare const fact: {
+    /** An answered external source: the value the rules read, plus optional colour for the trace. */
+    ok: (value: boolean | number, extra?: {
+        reason?: string | null;
+        confidence?: number;
+        transcript?: Transcript;
+    }) => ExtFact;
+    /** A fact that could not be answered. The runner stamps the manifest's `onError` over it. */
+    error: (detail: string, extra?: {
+        transcript?: Transcript;
+    }) => FactErrorDraft;
+    /** Transient trouble — `throw fact.retryLater("…")` and the workflow step tries again. */
+    retryLater: (detail: string) => RetryLater;
+    ai: {
+        /** An AI check's verdict. `score` is confidence in the VERDICT (0–100), not input quality. */
+        ok: (value: boolean, extra?: {
+            reason?: string | null;
+            failedRules?: string[];
+            score?: number;
+            confidence?: number;
+            transcript?: Transcript;
+        }) => AiFact;
+    };
+};
+/**
+ * ONE handler for SEVERAL declared sources: `groups: [group(["quality", "price"], scores)]`. The
+ * runner calls it once per claim (one slot in the fan-out cap), hands it the names it must answer,
+ * and expects one fact per name back — a name left out becomes that name's own error fact.
+ *
+ * Why it exists: an oracle that judges four criteria from ONE structured model call must not pay
+ * for four completions to fill four names. It is the sanctioned way to share a call between facts —
+ * a private cache inside a handler still is not (the runner's fact cache is the only cache).
+ */
+export declare function group(names: readonly string[], handler: GroupHandler): FactGroup;
+/** The handler table, normalized — absent lanes are empty, so the runner never branches on undefined. */
+export declare function defineFacts(decl: FactsDeclaration): FactsConfig;
+/** Tells a `defineFacts()` table from the older single-function producer (define-oracle.ts). */
+export declare const isFactsConfig: (v: unknown) => v is FactsConfig;
+//# sourceMappingURL=fact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact.d.ts","sourceRoot":"","sources":["../../src/facts/fact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAEjB,mGAAmG;AACnG,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,UAAU,OAAiB;IACpC,YAAY,MAAM,EAAE,MAAM,EAGzB;CACF;AAED,eAAO,MAAM,IAAI;IACf,iGAAiG;IACjG,EAAE,UACO,OAAO,GAAG,MAAM,UAChB;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,KAC9E,OAAO;IAQV,6FAA6F;IAC7F,KAAK,WAAW,MAAM,UAAS;QAAE,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,KAAQ,cAAc;IAMhF,0FAA0F;IAC1F,UAAU,WAAW,MAAM,KAAG,UAAU;IAExC,EAAE;QACA,8FAA8F;QAC9F,EAAE,UACO,OAAO,UACP;YACL,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;YACvB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,UAAU,CAAC,EAAE,UAAU,CAAC;SACzB,KACA,MAAM;;CAUZ,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,CAGhF;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAkC/D;AAED,gGAAgG;AAChG,eAAO,MAAM,aAAa,MAAO,OAAO,KAAG,CAAC,IAAI,WAC0C,CAAC"}

package/dist/facts/fact.js

@@ -0,0 +1,105 @@
+/**
+ * `defineFacts()` and the `fact` helpers — the two things a provider writes against.
+ *
+ * `defineFacts({ ext, ai, unique, frequency })` is a DIFF against the stock producer: list the
+ * names you answer yourself, every other name in the work order keeps running its stock lane
+ * (lib/facts/runner.ts). `fact.*` builds what a handler returns when a bare `true`/`8200` isn't
+ * enough — a reason, a transcript, a failure. Note what is NOT here: no way to choose an
+ * `onError`. A fact that failed carries the RUBRIC's fallback, stamped by the runner, because the
+ * one thing a handler must never be able to do is turn its own failure into an approve.
+ *
+ * `fact.retryLater()` is the single exception, and it is a THROW, not a fact: "this wasn't the
+ * claim's fault, ask me again" — the runner turns it into `unavailable` so the workflow step
+ * retries instead of freezing a verdict.
+ *
+ * Node-safe (the `./facts` subpath): types and plain objects only.
+ */
+/** `throw fact.retryLater(detail)` — the runner's only pass-through, as `AppError.unavailable`. */
+export class RetryLater extends Error {
+    retryLater = true;
+    constructor(detail) {
+        super(detail);
+        this.name = "RetryLater";
+    }
+}
+export const fact = {
+    /** An answered external source: the value the rules read, plus optional colour for the trace. */
+    ok: (value, extra = {}) => ({
+        status: "ok",
+        value,
+        reason: extra.reason ?? null,
+        ...(extra.confidence !== undefined ? { confidence: extra.confidence } : {}),
+        ...(extra.transcript ? { transcript: extra.transcript } : {}),
+    }),
+    /** A fact that could not be answered. The runner stamps the manifest's `onError` over it. */
+    error: (detail, extra = {}) => ({
+        status: "error",
+        detail,
+        ...(extra.transcript ? { transcript: extra.transcript } : {}),
+    }),
+    /** Transient trouble — `throw fact.retryLater("…")` and the workflow step tries again. */
+    retryLater: (detail) => new RetryLater(detail),
+    ai: {
+        /** An AI check's verdict. `score` is confidence in the VERDICT (0–100), not input quality. */
+        ok: (value, extra = {}) => ({
+            status: "ok",
+            value,
+            reason: extra.reason ?? null,
+            failedRules: extra.failedRules ?? [],
+            score: extra.score ?? 100,
+            ...(extra.confidence !== undefined ? { confidence: extra.confidence } : {}),
+            ...(extra.transcript ? { transcript: extra.transcript } : {}),
+        }),
+    },
+};
+/**
+ * ONE handler for SEVERAL declared sources: `groups: [group(["quality", "price"], scores)]`. The
+ * runner calls it once per claim (one slot in the fan-out cap), hands it the names it must answer,
+ * and expects one fact per name back — a name left out becomes that name's own error fact.
+ *
+ * Why it exists: an oracle that judges four criteria from ONE structured model call must not pay
+ * for four completions to fill four names. It is the sanctioned way to share a call between facts —
+ * a private cache inside a handler still is not (the runner's fact cache is the only cache).
+ */
+export function group(names, handler) {
+    if (names.length === 0)
+        throw new Error("group() needs at least one source name");
+    return { kind: "fact-group", names: [...names], handler };
+}
+/** The handler table, normalized — absent lanes are empty, so the runner never branches on undefined. */
+export function defineFacts(decl) {
+    const ext = decl.ext ?? {};
+    const groups = decl.groups ?? [];
+    // Two handlers for one name is ambiguous, and the ambiguity would surface as a fact whose value
+    // depends on which lane wrote last. The table is code the provider wrote, so it fails at module
+    // evaluation — at boot, loudly, not on some claim months later.
+    const owner = new Map(Object.keys(ext).map((name) => [name, `ext.${name}`]));
+    for (const g of groups) {
+        const label = `group(${g.names.join(", ")})`;
+        // A name repeated within the SAME group's own list is a different mistake than two lanes
+        // claiming a name — catch it first, or it reads as the group answering itself twice.
+        const seenInGroup = new Set();
+        for (const name of g.names) {
+            if (seenInGroup.has(name)) {
+                throw new Error(`defineFacts: ${label} lists '${name}' twice.`);
+            }
+            seenInGroup.add(name);
+            const first = owner.get(name);
+            if (first) {
+                throw new Error(`defineFacts: '${name}' is answered twice — by ${first} and ${label}. One name, one handler.`);
+            }
+            owner.set(name, label);
+        }
+    }
+    return {
+        kind: "facts-config",
+        ext,
+        ai: decl.ai ?? {},
+        groups,
+        ...(decl.unique ? { unique: decl.unique } : {}),
+        ...(decl.frequency ? { frequency: decl.frequency } : {}),
+    };
+}
+/** Tells a `defineFacts()` table from the older single-function producer (define-oracle.ts). */
+export const isFactsConfig = (v) => typeof v === "object" && v !== null && v.kind === "facts-config";
+//# sourceMappingURL=fact.js.map

package/dist/facts/fact.js.map

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

package/dist/facts/geo.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 type { ExtHandler } from "./types.js";
+type Point = {
+    lat: number;
+    lon: number;
+};
+/** Great-circle distance between two points, in metres. */
+export declare function haversineMeters(a: Point, b: Point): number;
+/** `send: { lat?, lon?, photo?, centerLat, centerLon, meters }` — is the claim within `meters` of centre? */
+export declare const withinRadius: ExtHandler;
+/**
+ * `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 declare const located: ExtHandler;
+/**
+ * `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 declare const beforeAfter: ExtHandler;
+export {};
+//# sourceMappingURL=geo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../../src/facts/geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,SAAS,CAAC;AAK9E,KAAK,KAAK,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAK1C,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAQ1D;AA8HD,6GAA6G;AAC7G,eAAO,MAAM,YAAY,EAAE,UAiB1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,UAMrB,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,UAoFzB,CAAC"}