@gamaze/hicortex 0.21.0 → 0.22.1

package/dist/eval/graph-eval.js

@@ -42,6 +42,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.seededSample = seededSample;
 exports.cosineBetween = cosineBetween;
 exports.byRelationshipCounts = byRelationshipCounts;
 exports.partitionByRelinkCursor = partitionByRelinkCursor;
@@ -55,8 +56,46 @@ const decay_eval_js_1 = require("./decay-eval.js");
 /** Matches the middle D1 duplicate threshold — a link between near-dups is noise, not signal. */
 const DUP_NOISE_THRESHOLD = 0.92;
 const DRIFT_SAMPLE_SIZE = 500;
+/**
+ * Seed for the drift sample's PRNG (#460). SQLite's `random()` cannot be
+ * seeded, so the draw happens client-side with a deterministic Fisher–Yates;
+ * this fixed seed makes the sample — and therefore the whole DriftReport —
+ * byte-identical across runs on the same build + snapshot, which lets
+ * before/after eval comparisons require full-output identity.
+ */
+const DRIFT_SAMPLE_SEED = 460;
 const DEGREE_BUCKET_EDGES = [0, 1, 2, 3, 5, 10, 20, 50, 100];
 const DRIFT_BUCKET_EDGES = [0, 0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.5, 1.0];
+/**
+ * mulberry32 — a 32-bit seeded PRNG (public-domain reference implementation).
+ * JS number ops are deterministic across platforms, so a fixed seed yields
+ * the same sequence everywhere.
+ */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Deterministic sample of `rows` (#460): a seeded partial Fisher–Yates
+ * shuffles the LAST `size` slots from the back, and that shuffled tail is
+ * the sample. Rows must already be in a stable order (the caller sorts by
+ * PK) so the draw does not depend on SQLite's scan order.
+ */
+function seededSample(rows, size, seed) {
+    const rand = mulberry32(seed);
+    const arr = [...rows];
+    const n = Math.min(size, arr.length);
+    for (let i = arr.length - 1; i > arr.length - 1 - n; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr.slice(arr.length - n);
+}
 // ---------------------------------------------------------------------------
 // Pure helpers (unit tested)
 // ---------------------------------------------------------------------------
@@ -109,11 +148,18 @@ function runDegreeAudit(db, topN = 10) {
     });
     return { memoriesWithLinks: linkCounts.size, totalMemories, degreeHistogram, topHubs };
 }
-/** Recompute cosine for a random link sample and compare to stored `strength` (post migration-5 rescale, should track closely). */
-function runDriftSample(db, embeddings, sampleSize = DRIFT_SAMPLE_SIZE) {
-    const sample = db
-        .prepare("SELECT source_id, target_id, strength FROM memory_links ORDER BY RANDOM() LIMIT ?")
-        .all(sampleSize);
+/**
+ * Recompute cosine for a link sample and compare to stored `strength` (post
+ * migration-5 rescale, should track closely). The sample is deterministic
+ * (#460): all link rows in stable PK order, drawn by a seeded Fisher–Yates —
+ * two runs on the same build + snapshot produce an identical report, so
+ * before/after comparisons can require full-output identity.
+ */
+function runDriftSample(db, embeddings, sampleSize = DRIFT_SAMPLE_SIZE, seed = DRIFT_SAMPLE_SEED) {
+    const allLinks = db
+        .prepare("SELECT source_id, target_id, strength FROM memory_links ORDER BY source_id, target_id")
+        .all();
+    const sample = seededSample(allLinks, sampleSize, seed);
     const drifts = [];
     let skipped = 0;
     for (const link of sample) {

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

@@ -20,6 +20,10 @@
  * live-LLM real-corpus acceptance run is the release-soak step (refine Q3),
  * not this one.
  *
+ * `--now <ISO>` (#458) pins the clock the recall-surface retrieve() scores
+ * against — before/after gate runs become wall-clock-independent. Default:
+ * the live clock; the report records which clock produced it.
+ *
  * Never touches ~/.hicortex: DB, state dir, and backups all live under a
  * mkdtemp directory that is removed on exit.
  */

package/dist/eval/planted-eval.js

@@ -21,6 +21,10 @@
  * live-LLM real-corpus acceptance run is the release-soak step (refine Q3),
  * not this one.
  *
+ * `--now <ISO>` (#458) pins the clock the recall-surface retrieve() scores
+ * against — before/after gate runs become wall-clock-independent. Default:
+ * the live clock; the report records which clock produced it.
+ *
  * Never touches ~/.hicortex: DB, state dir, and backups all live under a
  * mkdtemp directory that is removed on exit.
  */
@@ -32,12 +36,15 @@ const embedder_js_1 = require("../embedder.js");
 const capture_js_1 = require("../capture.js");
 const planted_fixtures_js_1 = require("./planted-fixtures.js");
 const planted_harness_js_1 = require("./planted-harness.js");
+const eval_clock_js_1 = require("./eval-clock.js");
 const DEFAULT_REPORT_PATH = (0, node_path_1.join)(process.cwd(), "data", "planted-eval-report.md");
 function usage() {
-    console.error("Usage: npm run eval:planted -- [report.md] [--snapshot <snapshot.db>]\n" +
+    console.error("Usage: npm run eval:planted -- [report.md] [--snapshot <snapshot.db>] [--now <ISO>]\n" +
         "  [report.md]          output path (default data/planted-eval-report.md)\n" +
         "  --snapshot <db>      plant into a COPY of a real snapshot (readonly source;\n" +
-        "                       the copy is writable, the snapshot is never touched)");
+        "                       the copy is writable, the snapshot is never touched)\n" +
+        "  --now <ISO>          #458: pin the eval clock (full ISO 8601 instant) the\n" +
+        "                       recall-surface retrieve() scores against. Default: live.");
     process.exitCode = 1;
     process.exit(1);
 }
@@ -45,16 +52,32 @@ async function main() {
     const argv = process.argv.slice(2);
     let reportPath;
     let snapshotPath;
+    let nowIso;
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === "--snapshot" && argv[i + 1]) {
             snapshotPath = argv[++i];
             continue;
         }
+        if (argv[i] === "--now" && argv[i + 1]) {
+            nowIso = argv[++i];
+            continue;
+        }
         if (!argv[i].startsWith("--"))
             reportPath = argv[i];
     }
     if (argv.includes("--help") || argv.includes("-h"))
         usage();
+    // #458: fail-explicit — an invalid pin is an error, never a live fallback.
+    let now;
+    try {
+        now = (0, eval_clock_js_1.parsePinnedNow)(nowIso);
+    }
+    catch (err) {
+        console.error(`[planted-eval] ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`[planted-eval] clock: ${(0, eval_clock_js_1.clockLabel)(now)}`);
     const workDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-planted-eval-"));
     try {
         const dbPath = (0, node_path_1.join)(workDir, "planted.db");
@@ -70,6 +93,7 @@ async function main() {
             stateDir,
             embedFn: embedder_js_1.embed,
             acquireLock: capture_js_1.acquireCaptureLock, // real lock, but on the temp stateDir only
+            now: now ?? undefined, // #458: pinned clock (undefined = live)
         });
         console.log(`[planted-eval] gate completed in ${Date.now() - t0}ms`);
         const report = (0, planted_harness_js_1.renderPlantedReport)({
@@ -78,6 +102,7 @@ async function main() {
                 : "real-text planted corpus (synthetic texts, real embeddings)",
             generatedAt: new Date().toISOString(),
             embedderLabel: "real bge-small-en-v1.5 (Xenova, fp32) — cosines measured, never asserted",
+            clock: (0, eval_clock_js_1.clockLabel)(now),
             result,
         });
         const outPath = reportPath ?? DEFAULT_REPORT_PATH;

package/dist/eval/planted-harness.d.ts

@@ -162,6 +162,10 @@ export interface PlantedGateOptions {
     acquireLock?: typeof acquireCaptureLock;
     /** Zone ceiling. Default: the production default (0.92). */
     threshold?: number;
+    /** #458: the pinned clock for the recall-surface retrieve() (undefined =
+     *  live). Fixtures keep their absolute createdAt strings — only the
+     *  scoring instant is pinned. */
+    now?: Date;
 }
 /**
  * Build (or plant into) the DB, run the production stage, measure the gate.
@@ -172,5 +176,8 @@ export declare function renderPlantedReport(args: {
     corpusLabel: string;
     generatedAt: string;
     embedderLabel: string;
+    /** #458: clock-mode label ("pinned <ISO>" | "live") — the instant the
+     *  recall-surface retrieve() scored against. */
+    clock: string;
     result: PlantedGateResult;
 }): string;

package/dist/eval/planted-harness.js

@@ -521,6 +521,7 @@ async function runPlantedGate(corpus, opts) {
                 const recall = await (0, retrieval_js_1.retrieve)(db, opts.embedFn, queryContent, {
                     limit: 3,
                     noStrengthen: true,
+                    ...(opts.now ? { now: opts.now } : {}), // #458: pinned clock (undefined = live)
                 });
                 // Every surfaced row must be its own walk terminal — no superseded
                 // ancestor competes as a truth — and the linked chain's terminal
@@ -593,6 +594,7 @@ function renderPlantedReport(args) {
     const L = [];
     L.push("# Planted-Pairs Resolution Gate (#393 increment A)\n");
     L.push(`Corpus: ${args.corpusLabel}  \nGenerated: ${args.generatedAt}  \nEmbedder: ${args.embedderLabel}  \n` +
+        `Clock: ${args.clock} (#458)  \n` +
         `Judge: ground-truth stub (perfect-judge semantics — machinery isolation, per the refine Q3 ruling).  \n` +
         `Floors: correctionMinSimilarity 0.75 (judged-band floor) · dedupAutoMergeThreshold 0.92 (zone ceiling).\n`);
     L.push("## Gate — per planted pair\n");

package/dist/eval/ranking-battery.d.ts

@@ -11,7 +11,8 @@
  * nouns (df 2-8), plus the fixed "Sirnäs" query (the owner's live case).
  *
  * Also carries the photo-comparison gates the sweep protocol defines:
- *   - case 2 byte-stability (no-match queries must not drift),
+ *   - case 2 unlinked-row identity (#449: unlinked rows' scores + mutual
+ *     order must not drift; linked-row order drifts by design),
  *   - battery top-1 stability >= 90%,
  *   - no query losing a both-channel exact match from its top-3.
  */
@@ -47,8 +48,54 @@ export declare function deriveBatteryQueries(rows: Array<{
     id: string;
     content: string;
 }>): BatteryQuery[];
-/** Case 2 gate: the FULL returned list must be byte-identical (ids + order). */
+/**
+ * Case 2 gate (pre-#449): the FULL returned list must be byte-identical
+ * (ids + order). Superseded as the --compare gate by `compareCase2Unlinked`
+ * in #449 PR E — linked rows' connections credit RISES by design under the
+ * reshape, so linked-row order drifts; kept for reference/re-recording old
+ * photos.
+ */
 export declare function compareCase2(baseline: string[], current: string[]): boolean;
+/** One recorded case-2 result row (the #449 per-row photo extension). */
+export interface Case2IdentityRow {
+    key: string;
+    score: number;
+    connections: number;
+}
+/** The photo sections the identity gate reads (baseline or current). */
+export interface Case2IdentityPhoto {
+    ftsHitRows?: number;
+    ids?: string[];
+    results?: Case2IdentityRow[];
+}
+export interface Case2IdentityResult {
+    pass: boolean;
+    failures: string[];
+}
+/**
+ * #449 (spec AC-7): the unlinked-row identity gate REPLACING the ids+order
+ * byte-gate for this PR — linked-row order drifts BY DESIGN (their
+ * connections credit rises), while everything UNLINKED must be untouched:
+ * the log term contributes exactly +0 at k = 0, so an unlinked row's score
+ * is bit-identical pre/post change. On the extended photo (per-row results
+ * with scores + measured connections) it checks that
+ *   (i) FTS hits stay 0 on both sides (no both-channel candidate can exist
+ *       — the case's structural inertness),
+ *   (ii) every connections===0 row's recorded score is identical to the
+ *        baseline's within CASE2_SCORE_TOLERANCE (matched by key — the
+ *        log term contributes exactly +0 at k = 0; the tolerance absorbs
+ *        the wall-clock drift of the time terms between recordings),
+ *   (iii) the subsequence of unlinked keys in the returned list is
+ *        identical (bit-identical scores + stable sort ⇒ their mutual
+ *        order cannot flip), and
+ *   (iv) every position change involves at least one LINKED row.
+ *
+ * A baseline photo without per-row results (pre-#449 harness) fails with a
+ * re-record instruction — the gate refuses to compare what it cannot see.
+ */
+export declare function compareCase2Unlinked(baseline: Case2IdentityPhoto, current: Case2IdentityPhoto, opts?: {
+    ftsHitMax?: number;
+}): Case2IdentityResult;
 export interface BatteryComparison {
     top1Stability: number;
     /** Stability with intended D3 promotions excluded: old top-1 was NOT a

package/dist/eval/ranking-battery.js

@@ -12,7 +12,8 @@
  * nouns (df 2-8), plus the fixed "Sirnäs" query (the owner's live case).
  *
  * Also carries the photo-comparison gates the sweep protocol defines:
- *   - case 2 byte-stability (no-match queries must not drift),
+ *   - case 2 unlinked-row identity (#449: unlinked rows' scores + mutual
+ *     order must not drift; linked-row order drifts by design),
  *   - battery top-1 stability >= 90%,
  *   - no query losing a both-channel exact match from its top-3.
  */
@@ -20,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.STOPWORDS = exports.SIRNAS_QUERY = void 0;
 exports.deriveBatteryQueries = deriveBatteryQueries;
 exports.compareCase2 = compareCase2;
+exports.compareCase2Unlinked = compareCase2Unlinked;
 exports.batteryComparison = batteryComparison;
 exports.SIRNAS_QUERY = "Sirnäs";
 /** Compact English stopword block (battery derivation only, not product). */
@@ -88,11 +90,117 @@ function deriveBatteryQueries(rows) {
         queries.push({ q: t, band: "proper-noun" });
     return queries;
 }
-/** Case 2 gate: the FULL returned list must be byte-identical (ids + order). */
+/**
+ * Case 2 gate (pre-#449): the FULL returned list must be byte-identical
+ * (ids + order). Superseded as the --compare gate by `compareCase2Unlinked`
+ * in #449 PR E — linked rows' connections credit RISES by design under the
+ * reshape, so linked-row order drifts; kept for reference/re-recording old
+ * photos.
+ */
 function compareCase2(baseline, current) {
     return (baseline.length === current.length &&
         baseline.every((id, i) => id === current[i]));
 }
+/**
+ * Score-comparison tolerance for gate (ii) — the WALL-CLOCK drift of the
+ * recorded scores, not slack. retrieve() scores with the live clock
+ * (computeScore's `now`), and the time-curve + decay terms move every
+ * row's score ≈1.5e-5/hour of wall time between photo recordings (measured
+ * 2026-09-17: two SAME-BUILD runs minutes apart differ by ~1e-6; the
+ * embedder itself is bit-deterministic across processes). The tolerance
+ * covers ~7 hours of drift between recordings while staying 290x below the
+ * smallest real movement this gate exists to catch — the k=1 linked-row
+ * credit change (0.0367 − 0.0075 = 0.0292). TRUE bit-identity of the k=0
+ * term is pinned at the unit level instead (tests/ranking-flip.test.ts,
+ * fixed NOW, synthetic distances).
+ */
+const CASE2_SCORE_TOLERANCE = 1e-4;
+/**
+ * #449 (spec AC-7): the unlinked-row identity gate REPLACING the ids+order
+ * byte-gate for this PR — linked-row order drifts BY DESIGN (their
+ * connections credit rises), while everything UNLINKED must be untouched:
+ * the log term contributes exactly +0 at k = 0, so an unlinked row's score
+ * is bit-identical pre/post change. On the extended photo (per-row results
+ * with scores + measured connections) it checks that
+ *   (i) FTS hits stay 0 on both sides (no both-channel candidate can exist
+ *       — the case's structural inertness),
+ *   (ii) every connections===0 row's recorded score is identical to the
+ *        baseline's within CASE2_SCORE_TOLERANCE (matched by key — the
+ *        log term contributes exactly +0 at k = 0; the tolerance absorbs
+ *        the wall-clock drift of the time terms between recordings),
+ *   (iii) the subsequence of unlinked keys in the returned list is
+ *        identical (bit-identical scores + stable sort ⇒ their mutual
+ *        order cannot flip), and
+ *   (iv) every position change involves at least one LINKED row.
+ *
+ * A baseline photo without per-row results (pre-#449 harness) fails with a
+ * re-record instruction — the gate refuses to compare what it cannot see.
+ */
+function compareCase2Unlinked(baseline, current, opts) {
+    const failures = [];
+    const ftsMax = opts?.ftsHitMax ?? 0;
+    if ((baseline.ftsHitRows ?? ftsMax) > ftsMax) {
+        failures.push(`baseline FTS hits ${baseline.ftsHitRows} (expected <= ${ftsMax})`);
+    }
+    if ((current.ftsHitRows ?? ftsMax) > ftsMax) {
+        failures.push(`current FTS hits ${current.ftsHitRows} (expected <= ${ftsMax})`);
+    }
+    if (!baseline.results || baseline.results.length === 0 || !current.results) {
+        failures.push("baseline photo lacks case-2 per-row results — re-record it with the #449 harness " +
+            "(the identity gate reads recorded scores + connections)");
+        return { pass: false, failures };
+    }
+    // (ii) every unlinked row's score identical to the baseline's within the
+    // wall-clock tolerance (both directions: no unlinked row may appear,
+    // disappear, or rescore beyond clock drift).
+    const baseByKey = new Map(baseline.results.map((r) => [r.key, r]));
+    for (const r of current.results) {
+        if (r.connections !== 0)
+            continue;
+        const b = baseByKey.get(r.key);
+        if (!b) {
+            failures.push(`unlinked row ${r.key} missing from baseline results`);
+            continue;
+        }
+        if (Math.abs(b.score - r.score) > CASE2_SCORE_TOLERANCE) {
+            failures.push(`unlinked row ${r.key} score ${r.score} vs baseline ${b.score} (|Δ| ${Math.abs(b.score - r.score).toExponential(2)} > ${CASE2_SCORE_TOLERANCE})`);
+        }
+    }
+    const curKeys = new Set(current.results.map((r) => r.key));
+    for (const b of baseline.results) {
+        if (b.connections === 0 && !curKeys.has(b.key)) {
+            failures.push(`baseline unlinked row ${b.key} missing from current results`);
+        }
+    }
+    // (iii) the unlinked-key subsequence (order included) is identical.
+    const unlinkedKeys = (rows) => rows.filter((r) => r.connections === 0).map((r) => r.key);
+    const baseSub = unlinkedKeys(baseline.results);
+    const curSub = unlinkedKeys(current.results);
+    if (baseSub.join("") !== curSub.join("")) {
+        failures.push(`unlinked-key subsequence changed: [${baseSub.join(", ")}] -> [${curSub.join(", ")}]`);
+    }
+    // (iv) every position change involves at least one linked row.
+    const connByKey = (photo) => new Map(photo.map((r) => [r.key, r.connections]));
+    const baseConn = connByKey(baseline.results);
+    const curConn = connByKey(current.results);
+    if (baseline.results.length !== current.results.length) {
+        failures.push(`returned-list length changed (${baseline.results.length} -> ${current.results.length})`);
+    }
+    else {
+        for (let i = 0; i < current.results.length; i++) {
+            const oldKey = baseline.results[i].key;
+            const newKey = current.results[i].key;
+            if (oldKey === newKey)
+                continue;
+            const oldLinked = (baseConn.get(oldKey) ?? 0) > 0;
+            const newLinked = (curConn.get(newKey) ?? 0) > 0;
+            if (!oldLinked && !newLinked) {
+                failures.push(`position ${i + 1} changed ${oldKey} -> ${newKey} with BOTH rows unlinked`);
+            }
+        }
+    }
+    return { pass: failures.length === 0, failures };
+}
 /** A both-channel row carrying the query term — the genuine-match signature. */
 function isBothChannelExact(m, id, term, contentById) {
     if (m)

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

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 /**
  * Search-trust ranking gate (#425) — the AC1/AC2/AC3 before/after photo.
+ * Extended by #449 (items 1+3, PR E): the case-2 photo gains per-row
+ * results (scores + measured connections) and its gate becomes the
+ * unlinked-row identity comparator; a new planted case 3 (linked_fallback)
+ * pins the connections-reshape expectations.
  *
  *   npm run eval:ranking [--snapshot <db>] [--photo <out.json>]
  *                        [--compare <baseline.json>] [--scoring '<json>']
  *
- *   --snapshot <db>    enables case 3: the deterministic real-query battery
+ *   --snapshot <db>    enables case 4: the deterministic real-query battery
  *                      against a READONLY snapshot (openSnapshot — never
  *                      initDb; the snapshot is never touched). Also reports
  *                      where the real "Sirnäs" memory ranks today (the
@@ -14,12 +18,19 @@
  *                      data/ranking-eval-photo.json). ALWAYS written, even
  *                      on a red run — the photo IS the measurement.
  *   --compare <json>   gate against a previously recorded photo: case 2's
- *                      returned list must be byte-identical, and the battery
- *                      must hold top-1 stability >= 90% with no query losing
- *                      a both-channel exact match from its top-3.
+ *                      UNLINKED rows must keep their scores (within the
+ *                      wall-clock tolerance) and mutual order — linked-row
+ *                      order drifts BY DESIGN under #449 — and the battery
+ *                      (when both sides have one) must hold top-1
+ *                      stability >= 90% with no query losing a both-channel
+ *                      exact match from its top-3.
  *   --scoring '<json>' a JSON object of ScoringWeights overrides passed to
  *                      configureScoring (the eval/test seam, #408) — the
  *                      sweep knob. Production runs omit it.
+ *   --now <ISO>       #458: pin the eval clock — planted lastAccessed offsets
+ *                      AND every retrieve() score against the SAME instant,
+ *                      so before/after photos are wall-clock-independent.
+ *                      Default: the live clock. The photo records the clock.
  *
  * Cases (fixtures: ranking-fixtures.ts, real bge-small-en-v1.5 embedder):
  *   1. sirnas_exact_match — planted corpus in a THROWAWAY writable DB;
@@ -27,8 +38,17 @@
  *      Exit code reflects the verdict (a pre-fix run is EXPECTED to exit
  *      non-zero — that red photo is the before picture).
  *   2. no_match_control — same corpus, a "mamma"-class query with zero FTS
- *      hits; records the full returned list for byte-stability comparison.
- *   3. real-query battery (needs --snapshot) — ~30 queries derived
+ *      hits; records the full returned list (ids + per-row results) for the
+ *      unlinked-identity comparison.
+ *   3. linked_fallback (#449) — planted corpus in its OWN throwaway DB: a
+ *      16-link vs 20-link identical-content hub pair (saturation tie,
+ *      declared byte-equal post-change) + an unlinked higher-similarity row
+ *      vs a 4-link lower-similarity row (direction pin). Measured under the
+ *      eval seam rrfCompositeWeight=1 (finalScore = composite exactly —
+ *      identical-content hubs differ by an RRF epsilon at the default
+ *      blend). RED under the pre-#449 linear term: the recorded
+ *      before-picture.
+ *   4. real-query battery (needs --snapshot) — ~30 queries derived
  *      deterministically from the snapshot corpus (top/mid/rare-frequency
  *      distinctive terms + proper nouns) + the fixed "Sirnäs" query; top-8
  *      ids per query recorded to the photo.