@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/facts/stock/unique-store.d.ts

@@ -0,0 +1,420 @@
+/**
+ * Duplicate-detection registry: writes + candidate reads (duplicate-claim spec §3 steps 2–3),
+ * over THIS oracle's D1 — duplicate detection is oracle-side. The
+ * prior-claim scope is every claim this oracle has ingested for the collection: the registries
+ * fill as the stock producer runs, so protection starts the day a collection is watched here, and
+ * no other oracle's registry is ever visible (the D1 IS this oracle's — no oracle column).
+ *
+ * The one ordering rule that matters: **insert self BEFORE reading siblings** (spec §3.2). Two
+ * concurrent duplicates each land their own rows first, so whichever reads second — and at least
+ * one must — sees the other; neither slips through the race window. `onConflictDoNothing` on the
+ * registry PKs makes the whole call idempotent under workflow step retry.
+ *
+ * Reads are candidate COLLECTION only (spec §3.3): exact digest, attachment-CID reuse (§4 L2),
+ * near-text (§4 L3), and the bounded pHash pool (§4 L4 — hamming happens in the pure scoring
+ * layer, never in SQL). Every lane applies the rule's `countPrior` filter here, in one place:
+ * `finalVerdict IS NULL` (not yet finalized) always counts as blockable pending; a finalized
+ * verdict blocks only when listed — a rejected prior never blocks, because resubmitting a fixed
+ * claim is the honest path, and neither does a `void` one (`VOID_TOKEN`: a claim that never
+ * reached a decision — a facts-lane outcome, a content refusal, an unusable rubric, a failed
+ * ingest — is not evidence of anything, eval critique P0-6).
+ *
+ * And every lane reads only claims registered BEFORE this one (`registeredBefore`: the body row's
+ * SQLite rowid, i.e. ingest order). A retry re-runs this read (runner.ts — registry state must be
+ * fresh per attempt), so without the bound an original whose step retried after a copy landed
+ * would see the copy and be flagged too. Two racing copies still meet: the later one sees the
+ * earlier, whichever commits second.
+ *
+ * THE SQLite TRADE-OFF (vs eval-engine's Postgres + pg_trgm): D1 has no trigram index and no
+ * `similarity()`, so the L3 lane reads a BOUNDED pool of the collection's newest rows
+ * (`TRIGRAM_POOL_LIMIT`, newest first — the shape the pHash pool already had) and computes
+ * pg_trgm's own measure in JS (`trigramSimilarity`: word-padded trigram sets, Jaccard). The
+ * numbers match pg_trgm for any pair the pool holds; what is lost is recall beyond the pool — a
+ * near-copy of a claim older than the newest N is caught only by the exact and attachment lanes.
+ * Raise the limit before reaching for FTS5 (its trigram tokenizer matches substrings, it does not
+ * rank by similarity).
+ *
+ * This module runs inside the resolve phase (impure by design: it owns the registry I/O). Its
+ * output freezes into the FactSet, so everything returned is plain JSON — `createdAt` is an ISO
+ * string, not a Date. `finalVerdictUpdate` is the one write the WORKFLOWS make (the decision's
+ * own batch), never the producer: the verdict lands when the engine has decided.
+ */
+import type { Database } from "../../../db/client.js";
+export interface UniqueRegisterInput {
+    collectionId: string;
+    claimId: string;
+    agentAddress: string | null;
+    digest: string;
+    normalizedText: string;
+    attachments: Array<{
+        cid: string;
+        phash: string | null;
+        mediaType: string | null;
+    }>;
+    /** Verdict filter from the rubric's `unique.countPrior` (spec §6). */
+    countPrior: string[];
+}
+export interface SiblingClaim {
+    claimId: string;
+    agentAddress: string | null;
+    finalVerdict: string | null;
+    createdAt: string;
+}
+export interface CidHit extends SiblingClaim {
+    cid: string;
+    phash: string | null;
+    /**
+     * What the attachment was — lets the judge skip CIDs no vision lane can take (§7). Always
+     * present on store-returned rows (null on a row written without one); optional so pure-scoring
+     * fixtures that never reach the judge don't have to carry it.
+     */
+    mediaType?: string | null;
+}
+export interface TrigramHit extends SiblingClaim {
+    /** 0..1 — pg_trgm's `similarity()` measure, computed in JS (header). */
+    similarity: number;
+    /**
+     * The candidate's stored normalized body — the gray-zone AI judge's pair input (spec §7:
+     * candidate bodies come from the registry, never a re-pull). Always present on store-returned
+     * rows (the pool holds non-null text only); optional so pure-scoring fixtures that never reach
+     * the judge don't have to carry bodies.
+     */
+    normalizedText?: string;
+}
+export interface UniqueSiblings {
+    exact: SiblingClaim[];
+    cidHits: CidHit[];
+    trigram: TrigramHit[];
+    phashPool: Array<{
+        claimId: string;
+        agentAddress: string | null;
+        cid: string;
+        phash: string;
+        /** What the hash came from — picks the §5 distance tier. Null on a row written without one (⇒ image). */
+        mediaType: string | null;
+    }>;
+}
+/** The near-text lane's floor (spec §4 L3) — below it a candidate is not shortlisted at all. */
+export declare const TRIGRAM_MIN_SIMILARITY = 0.5;
+export declare const CID_ROW_PARAMS = 7;
+export declare const CID_ROWS_PER_INSERT: number;
+export declare const CIDS_PER_READ = 80;
+/** pg_trgm `similarity(a, b)` for two normalized texts. */
+export declare function trigramSimilarity(a: string, b: string): number;
+/**
+ * Register this claim's digest + attachment rows, then read its duplicate candidates.
+ * One call per evaluation, from the resolve phase only.
+ */
+export declare function registerAndFetchSiblings(db: Database, input: UniqueRegisterInput): Promise<UniqueSiblings>;
+/**
+ * The token of a claim that never reached a decision: not in the rubric's `countPrior` vocabulary
+ * (`approved` / `pending_review` / `queued`), so it never blocks a later claim.
+ */
+export declare const VOID_TOKEN = "void";
+export declare function registryVerdictToken(status: string, verdict: string | null): string | null;
+/**
+ * A failed ingest's registry rows (claim-ingest's terminal catch): `void`, unless the claim is
+ * waiting for review (its NULL is the real pending) or already carries a token. A rerun that does
+ * decide overwrites it in the decision's own batch. One statement; a no-op without `unique`.
+ */
+export declare function voidUndecidedUpdate(db: Database, scope: {
+    collectionId: string;
+    claimId: string;
+}): Omit<import("drizzle-orm/sqlite-core").SQLiteUpdateBase<import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "claim_body_digests";
+    schema: undefined;
+    columns: {
+        collectionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "collectionId";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        digest: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "digest";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        claimId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "claimId";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        agentAddress: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "agentAddress";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        normalizedText: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "normalizedText";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        finalVerdict: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "finalVerdict";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "createdAt";
+            tableName: "claim_body_digests";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'sqlite';
+}>, "async", D1Result<unknown>, undefined, undefined, false, "fullJoin" | "innerJoin" | "leftJoin" | "rightJoin" | "where">, "fullJoin" | "innerJoin" | "leftJoin" | "rightJoin" | "where">;
+/**
+ * The ONE-OFF backfill for registries written before `void` existed (owner-approved, P0-6): the
+ * same rule as `registryVerdictToken` + `voidUndecidedUpdate`, over every row at once — NULL rows
+ * whose claim has a decision row that is not `decided` / `pending_review` (a facts-lane outcome,
+ * a content refusal, `unusable`), or no decision row and a `failed` ingest. A claim still queued or
+ * processing, or waiting for review, keeps its NULL. Idempotent (it only touches NULL rows). An
+ * operator runs it with `wrangler d1 execute <DB> --remote --command "<this>"` (docs/guide.md);
+ * test/unique-store.test.ts runs this exact string; test/node/backfill-sql.test.ts holds the
+ * guide to it.
+ */
+export declare const VOID_UNDECIDED_BACKFILL_SQL = "UPDATE claim_body_digests SET final_verdict = 'void' WHERE final_verdict IS NULL AND (EXISTS (SELECT 1 FROM decisions d WHERE d.claim_id = claim_body_digests.claim_id AND d.status NOT IN ('decided', 'pending_review')) OR (NOT EXISTS (SELECT 1 FROM decisions d WHERE d.claim_id = claim_body_digests.claim_id) AND EXISTS (SELECT 1 FROM claim_ingests i WHERE i.claim_id = claim_body_digests.claim_id AND i.status = 'failed')));";
+/**
+ * The one UPDATE that denormalizes a final verdict onto the claim's registry rows — a `db.batch`
+ * item beside the decision write it belongs with (claim-ingest's insert, review-complete's fold),
+ * so a retry can never see the decision without its verdict token. A no-op when the claim was
+ * never registered (a rubric without `unique`): zero rows match.
+ */
+export declare function finalVerdictUpdate(db: Database, scope: {
+    collectionId: string;
+    claimId: string;
+    token: string;
+}): Omit<import("drizzle-orm/sqlite-core").SQLiteUpdateBase<import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "claim_body_digests";
+    schema: undefined;
+    columns: {
+        collectionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "collectionId";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        digest: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "digest";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        claimId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "claimId";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        agentAddress: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "agentAddress";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        normalizedText: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "normalizedText";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        finalVerdict: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "finalVerdict";
+            tableName: "claim_body_digests";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: undefined;
+        }>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "createdAt";
+            tableName: "claim_body_digests";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: true;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'sqlite';
+}>, "async", D1Result<unknown>, undefined, undefined, false, "fullJoin" | "innerJoin" | "leftJoin" | "rightJoin" | "where">, "fullJoin" | "innerJoin" | "leftJoin" | "rightJoin" | "where">;
+//# sourceMappingURL=unique-store.d.ts.map

package/dist/lib/facts/stock/unique-store.d.ts.map

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