@gamaze/hicortex 0.14.3 → 0.15.0

package/dist/eval/decay-eval.d.ts

@@ -0,0 +1,110 @@
+/**
+ * D4 — decay / no-fit lifecycle + #192 adoption audit (#191 mechanical
+ * baseline). Four sections, all read-only against a snapshot connection:
+ *
+ *   (a) domain backlog     — NULL-domain memories split into "never scanned
+ *                             yet" vs "scanned, no fitting domain"
+ *   (b) prune dry-run      — the REAL production predicate (stageDecayPrune,
+ *                             dryRun=true), not a reimplementation
+ *   (c) structural strength — how many memories can EVER cross the prune
+ *                             floor, now vs simulated further out
+ *   (d) adoption            — #192 shown_count/access_count signal quality
+ */
+import type Database from "better-sqlite3";
+export interface DomainBacklogReport {
+    nullDomainTotal: number;
+    /** rowid > domainCursor: the classify-domains scan has not reached these rows yet. */
+    neverClassifiedBacklog: number;
+    /** rowid <= domainCursor: scanned, but the LLM found no fitting domain (no-fit, below weakPrimaryFloor). */
+    classifiedButEmpty: number;
+    domainCursor: number | null;
+    maxRowid: number;
+    /** True when domainCursor was mapped 1:1 (classify-domains.ts documents it as "last committed rowid"). */
+    cursorMappingConfident: boolean;
+}
+/**
+ * Partition NULL-domain memories by the `domainCursor` rowid watermark.
+ * `domainCursor` is documented in classify-domains.ts as "last fully
+ * committed rowid" — a direct rowid position, not an opaque offset — so the
+ * split is a plain rowid comparison. If a future version changes that
+ * contract this function still degrades safely: with no cursor, everything
+ * NULL is reported as backlog (worst case, never silently wrong).
+ */
+export declare function runDomainBacklogAudit(db: Database.Database, stateDir?: string): DomainBacklogReport;
+export interface PruneDryRunReport {
+    candidates: number;
+    pruned: number;
+    failed: number;
+    decayHalfLifeDaysUsed: number;
+}
+/**
+ * Run the actual `stageDecayPrune` (imported from consolidate.ts, `dryRun:
+ * true`) against the snapshot. Configures the decay clock to the given
+ * half-life first (bedrock has no `decayHalfLifeDays` override, so the
+ * caller should pass the shipped default — see run-eval.ts) so the eval and
+ * production score with the same clock.
+ */
+export declare function runPruneDryRun(db: Database.Database, decayHalfLifeDays?: number): PruneDryRunReport;
+/**
+ * effectiveStrength's asymptotic floor is `base_strength * importance * 0.1`
+ * with `importance` defaulting to `base_strength` (retrieval.ts). A memory
+ * can EVER cross the prune floor (0.01, stageDecayPrune) only if that
+ * asymptote is itself below it: base_strength² * 0.1 < 0.01, i.e.
+ * base_strength < sqrt(0.1). Independent of access/link hardening — those
+ * only slow the approach, they never raise the floor.
+ */
+export declare const EVER_PRUNABLE_BASE_STRENGTH_CEILING: number;
+export declare function histogram(values: number[], edges?: number[]): Record<string, number>;
+export interface StructuralStrengthStats {
+    totalMemories: number;
+    everPrunableCount: number;
+    everPrunableCeiling: number;
+    effectiveStrengthNowHistogram: Record<string, number>;
+    effectiveStrengthAt180dHistogram: Record<string, number>;
+    effectiveStrengthAt365dHistogram: Record<string, number>;
+    /** The asymptotic floor per memory (base_strength² × 0.1) — what "at infinity" converges to. */
+    effectiveStrengthNeverHistogram: Record<string, number>;
+}
+/**
+ * Compute effective-strength distributions now, and simulated further out
+ * (same access/link counts, decay continuing with no further access — the
+ * "if nothing changes" projection), plus the asymptotic floor per memory.
+ * Requires `configureDecay` to already reflect the desired half-life (call
+ * `runPruneDryRun` first, or `configureDecay` directly, in the same process).
+ */
+export declare function runStructuralStrengthStats(db: Database.Database): StructuralStrengthStats;
+export interface AdoptionStats {
+    totalMemories: number;
+    shownCountHistogram: Record<string, number>;
+    accessCountHistogram: Record<string, number>;
+    totalShown: number;
+    totalAccess: number;
+    /** sum(access_count) / sum(shown_count) across the corpus — null if nothing has ever been shown. */
+    usesPerShowingOverall: number | null;
+    usesPerShowingBySourceAgent: Record<string, {
+        shown: number;
+        access: number;
+        ratio: number | null;
+    }>;
+    /** Never shown AND never accessed — completely inert memories. */
+    coldShare: {
+        coldCount: number;
+        total: number;
+        share: number;
+    };
+    /** By memory age bucket: total count, how many have ever been shown, and the share. */
+    exposureAgeProfile: Array<{
+        bucket: string;
+        total: number;
+        everShown: number;
+        shareShown: number;
+    }>;
+}
+/**
+ * Adoption snapshot from the #192 exposure/use columns. `shown_count` was
+ * added by migration v8 on 27.07.2026 — freshly deployed at snapshot time
+ * (~2 days), so near-zero shown counts across the board reflect the
+ * feature's youth as much as its effectiveness. Report callers should state
+ * that caveat alongside the numbers, not just the numbers.
+ */
+export declare function runAdoptionStats(db: Database.Database): AdoptionStats;

package/dist/eval/decay-eval.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * D4 — decay / no-fit lifecycle + #192 adoption audit (#191 mechanical
+ * baseline). Four sections, all read-only against a snapshot connection:
+ *
+ *   (a) domain backlog     — NULL-domain memories split into "never scanned
+ *                             yet" vs "scanned, no fitting domain"
+ *   (b) prune dry-run      — the REAL production predicate (stageDecayPrune,
+ *                             dryRun=true), not a reimplementation
+ *   (c) structural strength — how many memories can EVER cross the prune
+ *                             floor, now vs simulated further out
+ *   (d) adoption            — #192 shown_count/access_count signal quality
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVER_PRUNABLE_BASE_STRENGTH_CEILING = void 0;
+exports.runDomainBacklogAudit = runDomainBacklogAudit;
+exports.runPruneDryRun = runPruneDryRun;
+exports.histogram = histogram;
+exports.runStructuralStrengthStats = runStructuralStrengthStats;
+exports.runAdoptionStats = runAdoptionStats;
+const retrieval_js_1 = require("../retrieval.js");
+const consolidate_js_1 = require("../consolidate.js");
+const storage = __importStar(require("../storage.js"));
+const state_js_1 = require("../state.js");
+/**
+ * Partition NULL-domain memories by the `domainCursor` rowid watermark.
+ * `domainCursor` is documented in classify-domains.ts as "last fully
+ * committed rowid" — a direct rowid position, not an opaque offset — so the
+ * split is a plain rowid comparison. If a future version changes that
+ * contract this function still degrades safely: with no cursor, everything
+ * NULL is reported as backlog (worst case, never silently wrong).
+ */
+function runDomainBacklogAudit(db, stateDir) {
+    const state = (0, state_js_1.loadState)(stateDir);
+    const domainCursor = state.domainCursor ?? null;
+    const maxRowid = db.prepare("SELECT MAX(rowid) AS r FROM memories").get().r ?? 0;
+    const nullDomainTotal = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE domain IS NULL").get().c;
+    let neverClassifiedBacklog;
+    if (domainCursor !== null) {
+        neverClassifiedBacklog = db
+            .prepare("SELECT COUNT(*) AS c FROM memories WHERE domain IS NULL AND rowid > ?")
+            .get(domainCursor).c;
+    }
+    else {
+        neverClassifiedBacklog = nullDomainTotal;
+    }
+    return {
+        nullDomainTotal,
+        neverClassifiedBacklog,
+        classifiedButEmpty: nullDomainTotal - neverClassifiedBacklog,
+        domainCursor,
+        maxRowid,
+        cursorMappingConfident: true,
+    };
+}
+/**
+ * Run the actual `stageDecayPrune` (imported from consolidate.ts, `dryRun:
+ * true`) against the snapshot. Configures the decay clock to the given
+ * half-life first (bedrock has no `decayHalfLifeDays` override, so the
+ * caller should pass the shipped default — see run-eval.ts) so the eval and
+ * production score with the same clock.
+ */
+function runPruneDryRun(db, decayHalfLifeDays = retrieval_js_1.DEFAULT_DECAY_HALF_LIFE_DAYS) {
+    (0, retrieval_js_1.configureDecay)({ halfLifeDays: decayHalfLifeDays });
+    const result = (0, consolidate_js_1.stageDecayPrune)(db, true);
+    return { ...result, decayHalfLifeDaysUsed: decayHalfLifeDays };
+}
+// ---------------------------------------------------------------------------
+// (c) Structural strength stats
+// ---------------------------------------------------------------------------
+/**
+ * effectiveStrength's asymptotic floor is `base_strength * importance * 0.1`
+ * with `importance` defaulting to `base_strength` (retrieval.ts). A memory
+ * can EVER cross the prune floor (0.01, stageDecayPrune) only if that
+ * asymptote is itself below it: base_strength² * 0.1 < 0.01, i.e.
+ * base_strength < sqrt(0.1). Independent of access/link hardening — those
+ * only slow the approach, they never raise the floor.
+ */
+exports.EVER_PRUNABLE_BASE_STRENGTH_CEILING = Math.sqrt(0.1);
+const STRENGTH_BUCKET_EDGES = [0, 0.01, 0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 1.0];
+function bucketLabel(value, edges) {
+    for (let i = 0; i < edges.length - 1; i++) {
+        if (value >= edges[i] && value < edges[i + 1])
+            return `[${edges[i]}, ${edges[i + 1]})`;
+    }
+    return `[${edges[edges.length - 1]}, +]`;
+}
+function histogram(values, edges = STRENGTH_BUCKET_EDGES) {
+    const buckets = {};
+    for (const v of values) {
+        const label = bucketLabel(v, edges);
+        buckets[label] = (buckets[label] ?? 0) + 1;
+    }
+    return buckets;
+}
+/**
+ * Compute effective-strength distributions now, and simulated further out
+ * (same access/link counts, decay continuing with no further access — the
+ * "if nothing changes" projection), plus the asymptotic floor per memory.
+ * Requires `configureDecay` to already reflect the desired half-life (call
+ * `runPruneDryRun` first, or `configureDecay` directly, in the same process).
+ */
+function runStructuralStrengthStats(db) {
+    const rows = db
+        .prepare("SELECT id, base_strength, last_accessed, access_count FROM memories")
+        .all();
+    const linkCounts = storage.getAllLinkCounts(db);
+    const now = new Date();
+    const nowVals = [];
+    const at180 = [];
+    const at365 = [];
+    const neverVals = [];
+    let everPrunable = 0;
+    for (const r of rows) {
+        const base = r.base_strength ?? 0.5;
+        if (base < exports.EVER_PRUNABLE_BASE_STRENGTH_CEILING)
+            everPrunable++;
+        const linkCount = linkCounts.get(r.id) ?? 0;
+        const opts = { accessCount: r.access_count ?? 0, linkCount };
+        nowVals.push((0, retrieval_js_1.effectiveStrength)(base, r.last_accessed, now, opts));
+        at180.push((0, retrieval_js_1.effectiveStrength)(base, r.last_accessed, new Date(now.getTime() + 180 * 86_400_000), opts));
+        at365.push((0, retrieval_js_1.effectiveStrength)(base, r.last_accessed, new Date(now.getTime() + 365 * 86_400_000), opts));
+        neverVals.push(base * base * 0.1);
+    }
+    return {
+        totalMemories: rows.length,
+        everPrunableCount: everPrunable,
+        everPrunableCeiling: exports.EVER_PRUNABLE_BASE_STRENGTH_CEILING,
+        effectiveStrengthNowHistogram: histogram(nowVals),
+        effectiveStrengthAt180dHistogram: histogram(at180),
+        effectiveStrengthAt365dHistogram: histogram(at365),
+        effectiveStrengthNeverHistogram: histogram(neverVals),
+    };
+}
+// ---------------------------------------------------------------------------
+// (d) Adoption stats (#192 columns: shown_count, access_count)
+// ---------------------------------------------------------------------------
+const COUNT_BUCKET_EDGES = [0, 1, 2, 5, 10, 25, 50, 100, 1000];
+const AGE_BUCKET_EDGES_DAYS = [0, 7, 30, 90, 180, 365];
+function ageBucketLabel(ageDays) {
+    for (let i = 0; i < AGE_BUCKET_EDGES_DAYS.length - 1; i++) {
+        if (ageDays >= AGE_BUCKET_EDGES_DAYS[i] && ageDays < AGE_BUCKET_EDGES_DAYS[i + 1]) {
+            return `${AGE_BUCKET_EDGES_DAYS[i]}-${AGE_BUCKET_EDGES_DAYS[i + 1]}d`;
+        }
+    }
+    return `${AGE_BUCKET_EDGES_DAYS[AGE_BUCKET_EDGES_DAYS.length - 1]}d+`;
+}
+/**
+ * Adoption snapshot from the #192 exposure/use columns. `shown_count` was
+ * added by migration v8 on 27.07.2026 — freshly deployed at snapshot time
+ * (~2 days), so near-zero shown counts across the board reflect the
+ * feature's youth as much as its effectiveness. Report callers should state
+ * that caveat alongside the numbers, not just the numbers.
+ */
+function runAdoptionStats(db) {
+    const rows = db
+        .prepare("SELECT id, shown_count, access_count, source_agent, created_at FROM memories")
+        .all();
+    const now = new Date();
+    const shownVals = [];
+    const accessVals = [];
+    let totalShown = 0;
+    let totalAccess = 0;
+    let coldCount = 0;
+    const byAgent = new Map();
+    const ageBuckets = new Map();
+    for (const r of rows) {
+        const shown = r.shown_count ?? 0;
+        const access = r.access_count ?? 0;
+        shownVals.push(shown);
+        accessVals.push(access);
+        totalShown += shown;
+        totalAccess += access;
+        if (shown === 0 && access === 0)
+            coldCount++;
+        const agentAgg = byAgent.get(r.source_agent) ?? { shown: 0, access: 0 };
+        agentAgg.shown += shown;
+        agentAgg.access += access;
+        byAgent.set(r.source_agent, agentAgg);
+        const ageDays = (now.getTime() - Date.parse(r.created_at)) / 86_400_000;
+        const label = ageBucketLabel(Number.isFinite(ageDays) ? Math.max(ageDays, 0) : 0);
+        const bucketAgg = ageBuckets.get(label) ?? { total: 0, everShown: 0 };
+        bucketAgg.total++;
+        if (shown > 0)
+            bucketAgg.everShown++;
+        ageBuckets.set(label, bucketAgg);
+    }
+    const usesPerShowingBySourceAgent = {};
+    for (const [agent, agg] of byAgent) {
+        usesPerShowingBySourceAgent[agent] = {
+            shown: agg.shown,
+            access: agg.access,
+            ratio: agg.shown > 0 ? agg.access / agg.shown : null,
+        };
+    }
+    const exposureAgeProfile = AGE_BUCKET_EDGES_DAYS.map((edge, i) => {
+        const label = i < AGE_BUCKET_EDGES_DAYS.length - 1
+            ? `${edge}-${AGE_BUCKET_EDGES_DAYS[i + 1]}d`
+            : `${edge}d+`;
+        const agg = ageBuckets.get(label) ?? { total: 0, everShown: 0 };
+        return {
+            bucket: label,
+            total: agg.total,
+            everShown: agg.everShown,
+            shareShown: agg.total > 0 ? agg.everShown / agg.total : 0,
+        };
+    }).filter((b) => b.total > 0);
+    return {
+        totalMemories: rows.length,
+        shownCountHistogram: histogram(shownVals, COUNT_BUCKET_EDGES),
+        accessCountHistogram: histogram(accessVals, COUNT_BUCKET_EDGES),
+        totalShown,
+        totalAccess,
+        usesPerShowingOverall: totalShown > 0 ? totalAccess / totalShown : null,
+        usesPerShowingBySourceAgent,
+        coldShare: { coldCount, total: rows.length, share: rows.length > 0 ? coldCount / rows.length : 0 },
+        exposureAgeProfile,
+    };
+}

package/dist/eval/dups.d.ts

@@ -0,0 +1,100 @@
+/**
+ * D1 — duplicate-rate audit (#191 mechanical baseline).
+ *
+ * For each memory, finds its top-10 nearest neighbors by vector distance and
+ * keeps every pair whose cosine similarity clears the lowest of three report
+ * thresholds (0.90 / 0.92 / 0.95). Clusters are built per threshold with
+ * union-find; the headline number at each threshold is "excess" — how many
+ * rows would disappear if every cluster were merged down to one memory.
+ *
+ * Duplicate pairs are additionally attributed to either the #189 recovery
+ * re-ingest (a retried capture segment produced a second row for content
+ * already stored) or organic near-duplication (independent sessions that
+ * happened to cover the same ground), using two signals: a shared base
+ * `source_session` (the `#<segment>` suffix stripped), or ingestion runs that
+ * differ while `created_at` is near-identical (a re-ingest preserves the
+ * original session date but lands in a later ingestion run).
+ *
+ * The clustering primitives (union-find, KNN edge building, metadata-mismatch
+ * check) live in `../cluster.js` — extracted (#100/#191) so `hicortex dedup`
+ * reuses the exact same math instead of re-implementing it. Re-exported below
+ * for backward compatibility with existing importers of this module.
+ */
+import type Database from "better-sqlite3";
+import { UnionFind, clusterEdges, clusterExcess, clusterMetadataMismatch, type Edge, type ClusterMetadataMismatch } from "../cluster.js";
+export { UnionFind, clusterEdges, clusterExcess, clusterMetadataMismatch, type ClusterMetadataMismatch };
+/** @deprecated import `Edge` from `../cluster.js` instead. */
+export type DupEdge = Edge;
+/** Cosine thresholds the report evaluates, low to high. */
+export declare const DUP_THRESHOLDS: readonly [0.9, 0.92, 0.95];
+export interface DupMemoryRow {
+    id: string;
+    content: string;
+    created_at: string;
+    ingested_at: string;
+    source_session: string | null;
+    project: string | null;
+    privacy: string;
+    source_agent: string;
+}
+/**
+ * Partition memories into ingestion "runs" by `ingested_at`: sorted
+ * ascending, a gap greater than `gapHours` starts a new run. Returns a map
+ * of memory id -> run id (0-based, monotonically increasing).
+ */
+export declare function sessionizeByIngestedAt(rows: Array<{
+    id: string;
+    ingested_at: string;
+}>, gapHours?: number): Map<string, number>;
+/** Strip the `#<segment>` suffix from a `source_session` value. Null-safe. */
+export declare function baseSessionId(sourceSession: string | null): string | null;
+/** Whether two ISO timestamps fall within `toleranceDays` of each other. */
+export declare function nearIdenticalDate(a: string, b: string, toleranceDays?: number): boolean;
+export type PairAttribution = "recovery_reingest" | "organic";
+/**
+ * Classify a duplicate pair as a #189 recovery re-ingest or organic overlap.
+ * Recovery re-ingest when either: both sides share the same base
+ * `source_session`, or they landed in different ingestion runs but
+ * `created_at` is near-identical (the re-ingest preserves the original
+ * session date while landing in a later run).
+ */
+export declare function attributePair(a: DupMemoryRow, b: DupMemoryRow, runOf: Map<string, number>): PairAttribution;
+export interface DupThresholdResult {
+    threshold: number;
+    clusterCount: number;
+    excess: number;
+    /** Cluster sizes, largest first — a quick histogram without dumping content. */
+    clusterSizes: number[];
+}
+export interface DupClusterDump {
+    size: number;
+    members: Array<{
+        id: string;
+        created_at: string;
+        preview: string;
+    }>;
+    attribution: {
+        recoveryReingest: number;
+        organic: number;
+    };
+    metadataMismatch: ClusterMetadataMismatch;
+}
+export interface DupReport {
+    totalMemories: number;
+    knnK: number;
+    thresholds: DupThresholdResult[];
+    /** Attribution over every pair at/above the lowest threshold (broadest view). */
+    pairAttribution: {
+        recoveryReingest: number;
+        organic: number;
+        totalPairs: number;
+    };
+    /** Top clusters at the lowest threshold, largest first, for manual review. */
+    topClusters: DupClusterDump[];
+}
+/**
+ * Run the full D1 duplicate audit against an open (readonly) snapshot
+ * connection. Pure aside from the DB reads — safe against a readonly
+ * connection, no writes attempted.
+ */
+export declare function runDupAudit(db: Database.Database, topN?: number): DupReport;

package/dist/eval/dups.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * D1 — duplicate-rate audit (#191 mechanical baseline).
+ *
+ * For each memory, finds its top-10 nearest neighbors by vector distance and
+ * keeps every pair whose cosine similarity clears the lowest of three report
+ * thresholds (0.90 / 0.92 / 0.95). Clusters are built per threshold with
+ * union-find; the headline number at each threshold is "excess" — how many
+ * rows would disappear if every cluster were merged down to one memory.
+ *
+ * Duplicate pairs are additionally attributed to either the #189 recovery
+ * re-ingest (a retried capture segment produced a second row for content
+ * already stored) or organic near-duplication (independent sessions that
+ * happened to cover the same ground), using two signals: a shared base
+ * `source_session` (the `#<segment>` suffix stripped), or ingestion runs that
+ * differ while `created_at` is near-identical (a re-ingest preserves the
+ * original session date but lands in a later ingestion run).
+ *
+ * The clustering primitives (union-find, KNN edge building, metadata-mismatch
+ * check) live in `../cluster.js` — extracted (#100/#191) so `hicortex dedup`
+ * reuses the exact same math instead of re-implementing it. Re-exported below
+ * for backward compatibility with existing importers of this module.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DUP_THRESHOLDS = exports.clusterMetadataMismatch = exports.clusterExcess = exports.clusterEdges = exports.UnionFind = void 0;
+exports.sessionizeByIngestedAt = sessionizeByIngestedAt;
+exports.baseSessionId = baseSessionId;
+exports.nearIdenticalDate = nearIdenticalDate;
+exports.attributePair = attributePair;
+exports.runDupAudit = runDupAudit;
+const cluster_js_1 = require("../cluster.js");
+Object.defineProperty(exports, "UnionFind", { enumerable: true, get: function () { return cluster_js_1.UnionFind; } });
+Object.defineProperty(exports, "clusterEdges", { enumerable: true, get: function () { return cluster_js_1.clusterEdges; } });
+Object.defineProperty(exports, "clusterExcess", { enumerable: true, get: function () { return cluster_js_1.clusterExcess; } });
+Object.defineProperty(exports, "clusterMetadataMismatch", { enumerable: true, get: function () { return cluster_js_1.clusterMetadataMismatch; } });
+/** Cosine thresholds the report evaluates, low to high. */
+exports.DUP_THRESHOLDS = [0.9, 0.92, 0.95];
+/** Neighbors requested per memory (excluding the memory itself). */
+const KNN_K = 10;
+/** Ingestion-run gap: a pause longer than this starts a new "run". */
+const DEFAULT_RUN_GAP_HOURS = 1;
+/** created_at proximity treated as "near-identical" for cross-run pairs. */
+const DEFAULT_SAME_DATE_TOLERANCE_DAYS = 1;
+// ---------------------------------------------------------------------------
+// Sessionization + attribution (pure — unit tested)
+// ---------------------------------------------------------------------------
+/**
+ * Partition memories into ingestion "runs" by `ingested_at`: sorted
+ * ascending, a gap greater than `gapHours` starts a new run. Returns a map
+ * of memory id -> run id (0-based, monotonically increasing).
+ */
+function sessionizeByIngestedAt(rows, gapHours = DEFAULT_RUN_GAP_HOURS) {
+    const sorted = [...rows].sort((a, b) => a.ingested_at.localeCompare(b.ingested_at));
+    const gapMs = gapHours * 3_600_000;
+    const runOf = new Map();
+    let runId = -1;
+    let prevTime = null;
+    for (const r of sorted) {
+        const t = Date.parse(r.ingested_at);
+        const valid = Number.isFinite(t);
+        if (prevTime === null || !valid || t - prevTime > gapMs) {
+            runId++;
+        }
+        runOf.set(r.id, runId);
+        if (valid)
+            prevTime = t;
+    }
+    return runOf;
+}
+/** Strip the `#<segment>` suffix from a `source_session` value. Null-safe. */
+function baseSessionId(sourceSession) {
+    if (!sourceSession)
+        return null;
+    const idx = sourceSession.indexOf("#");
+    return idx === -1 ? sourceSession : sourceSession.slice(0, idx);
+}
+/** Whether two ISO timestamps fall within `toleranceDays` of each other. */
+function nearIdenticalDate(a, b, toleranceDays = DEFAULT_SAME_DATE_TOLERANCE_DAYS) {
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (!Number.isFinite(ta) || !Number.isFinite(tb))
+        return false;
+    return Math.abs(ta - tb) / 86_400_000 <= toleranceDays;
+}
+/**
+ * Classify a duplicate pair as a #189 recovery re-ingest or organic overlap.
+ * Recovery re-ingest when either: both sides share the same base
+ * `source_session`, or they landed in different ingestion runs but
+ * `created_at` is near-identical (the re-ingest preserves the original
+ * session date while landing in a later run).
+ */
+function attributePair(a, b, runOf) {
+    const baseA = baseSessionId(a.source_session);
+    const baseB = baseSessionId(b.source_session);
+    if (baseA !== null && baseA === baseB)
+        return "recovery_reingest";
+    const runA = runOf.get(a.id);
+    const runB = runOf.get(b.id);
+    if (runA !== undefined &&
+        runB !== undefined &&
+        runA !== runB &&
+        nearIdenticalDate(a.created_at, b.created_at)) {
+        return "recovery_reingest";
+    }
+    return "organic";
+}
+/**
+ * Run the full D1 duplicate audit against an open (readonly) snapshot
+ * connection. Pure aside from the DB reads — safe against a readonly
+ * connection, no writes attempted.
+ */
+function runDupAudit(db, topN = 15) {
+    const rows = db
+        .prepare(`SELECT id, content, created_at, ingested_at, source_session, project, privacy, source_agent
+       FROM memories`)
+        .all();
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const runOf = sessionizeByIngestedAt(rows.map((r) => ({ id: r.id, ingested_at: r.ingested_at })));
+    const lowestThreshold = Math.min(...exports.DUP_THRESHOLDS);
+    const edges = (0, cluster_js_1.buildKnnEdges)(db, { k: KNN_K, minCosine: lowestThreshold });
+    const thresholds = exports.DUP_THRESHOLDS.map((threshold) => {
+        const clusters = (0, cluster_js_1.clusterEdges)(edges, threshold);
+        return {
+            threshold,
+            clusterCount: clusters.length,
+            excess: (0, cluster_js_1.clusterExcess)(clusters),
+            clusterSizes: clusters.map((c) => c.length).sort((a, b) => b - a),
+        };
+    });
+    let recoveryReingest = 0;
+    let organic = 0;
+    for (const e of edges) {
+        const a = byId.get(e.a);
+        const b = byId.get(e.b);
+        if (!a || !b)
+            continue;
+        if (attributePair(a, b, runOf) === "recovery_reingest")
+            recoveryReingest++;
+        else
+            organic++;
+    }
+    const broadestClusters = (0, cluster_js_1.clusterEdges)(edges, lowestThreshold).sort((a, b) => b.length - a.length);
+    const topClusters = broadestClusters.slice(0, topN).map((memberIds) => {
+        const members = memberIds.map((id) => byId.get(id)).filter((m) => !!m);
+        let recovery = 0;
+        let organicCount = 0;
+        for (let i = 0; i < members.length; i++) {
+            for (let j = i + 1; j < members.length; j++) {
+                if (attributePair(members[i], members[j], runOf) === "recovery_reingest")
+                    recovery++;
+                else
+                    organicCount++;
+            }
+        }
+        const sortedMembers = [...members].sort((a, b) => a.created_at.localeCompare(b.created_at));
+        return {
+            size: members.length,
+            members: sortedMembers.map((m) => ({
+                id: m.id,
+                created_at: m.created_at,
+                preview: m.content.slice(0, 80),
+            })),
+            attribution: { recoveryReingest: recovery, organic: organicCount },
+            metadataMismatch: (0, cluster_js_1.clusterMetadataMismatch)(members),
+        };
+    });
+    return {
+        totalMemories: rows.length,
+        knnK: KNN_K,
+        thresholds,
+        pairAttribution: { recoveryReingest, organic, totalPairs: edges.length },
+        topClusters,
+    };
+}

package/dist/eval/eval-db.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read-only snapshot access for the #191 mechanical audit baseline.
+ *
+ * The eval NEVER touches a live database — it runs against a checkpointed
+ * copy (`data/audit-<date>/snapshot.db`, gitignored). This module opens that
+ * copy in better-sqlite3's `readonly` mode and loads the sqlite-vec
+ * extension the same way `db.ts#initDb` does, WITHOUT calling `initDb()`
+ * itself: `initDb` runs schema migrations, which write to the file. A
+ * snapshot is assumed to already be at the current schema version (verified
+ * by `assertReadonly`, which also proves no migration silently ran).
+ */
+import Database from "better-sqlite3";
+/**
+ * Open a DB snapshot for read-only analysis.
+ *
+ * Throws if the path does not exist, or if a write attempt against the
+ * returned connection would (surprisingly) succeed — the second check is a
+ * belt-and-suspenders guard against a future better-sqlite3/OS combination
+ * where `readonly: true` is silently ignored (e.g. a non-standard
+ * filesystem), so a bug can never turn the audit into a mutation of
+ * production data.
+ */
+export declare function openSnapshot(dbPath: string): Database.Database;
+/** Convert a sqlite-vec embedding BLOB (as read back from `memory_vectors`) to a Float32Array. */
+export declare function blobToEmbedding(blob: Buffer): Float32Array;