@gamaze/hicortex 0.22.0 → 0.22.1

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.