@gamaze/hicortex 0.21.0 → 0.22.1

package/dist/eval/ranking-eval.js

@@ -2,11 +2,15 @@
 "use strict";
 /**
  * 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
@@ -15,12 +19,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;
@@ -28,8 +39,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.
@@ -81,15 +101,18 @@ const db_js_1 = require("../db.js");
 const storage = __importStar(require("../storage.js"));
 const retrieval_js_1 = require("../retrieval.js");
 const eval_db_js_1 = require("./eval-db.js");
+const eval_clock_js_1 = require("./eval-clock.js");
 const ranking_fixtures_js_1 = require("./ranking-fixtures.js");
 const ranking_battery_js_1 = require("./ranking-battery.js");
 const DEFAULT_PHOTO_PATH = (0, node_path_1.join)(process.cwd(), "data", "ranking-eval-photo.json");
 /** Battery gate thresholds (sweep protocol, issue #425 commit-3 gates). */
 const BATTERY_TOP1_STABILITY_MIN = 0.9;
-/** Plant one fixture corpus into a writable DB with its hardened metadata. */
-async function plantRankingFixture(db, fixture) {
+/** Plant one fixture corpus into a writable DB with its seeded strength metadata.
+ *  `now` (#458): the instant the planted lastAccessed offsets are measured
+ *  from — the pinned clock when --now was passed, live otherwise. */
+async function plantRankingFixture(db, fixture, now) {
     const idByKey = new Map();
-    const now = Date.now();
+    const nowMs = (now ?? new Date()).getTime();
     for (const row of fixture.rows) {
         const embedding = await (0, embedder_js_1.embed)(row.content);
         const id = storage.insertMemory(db, row.content, embedding, {
@@ -98,7 +121,7 @@ async function plantRankingFixture(db, fixture) {
             memoryType: row.memoryType,
             createdAt: row.createdAt,
         });
-        const lastAccessed = new Date(now - row.lastAccessedDaysAgo * 86_400_000).toISOString();
+        const lastAccessed = new Date(nowMs - row.lastAccessedDaysAgo * 86_400_000).toISOString();
         storage.updateMemory(db, id, {
             base_strength: row.baseStrength,
             access_count: row.accessCount,
@@ -121,7 +144,7 @@ async function plantRankingFixture(db, fixture) {
  * the cold-exposure swap is inert — scored.length <= limit — and the
  * returned order IS the score order), results mapped back to fixture keys.
  */
-async function measurePlantedCase(db, fixture, idByKey) {
+async function measurePlantedCase(db, fixture, idByKey, now) {
     const keyById = new Map([...idByKey.entries()].map(([k, v]) => [v, k]));
     const queryEmb = await (0, embedder_js_1.embed)(fixture.query);
     const ftsRows = storage.searchFts(db, fixture.query, 100, undefined);
@@ -129,6 +152,9 @@ async function measurePlantedCase(db, fixture, idByKey) {
         limit: fixture.rows.length + 8,
         noStrengthen: true,
         queryEmbedding: queryEmb,
+        // #458: the pinned clock (undefined = live) — score terms are
+        // wall-clock-independent across before/after photos.
+        ...(now ? { now } : {}),
     });
     const measured = results.map((r, i) => ({
         key: keyById.get(r.id) ?? r.id,
@@ -136,6 +162,7 @@ async function measurePlantedCase(db, fixture, idByKey) {
         score: Math.round(r.score * 1e6) / 1e6,
         similarity: r.similarity ?? null,
         source: r.source ?? null,
+        connections: r.connections,
         effectiveStrength: Math.round(r.effective_strength * 1e6) / 1e6,
         baseStrength: fixture.rows.find((x) => x.key === keyById.get(r.id))?.baseStrength ?? -1,
         accessCount: r.access_count,
@@ -154,7 +181,46 @@ async function measurePlantedCase(db, fixture, idByKey) {
         top1Top2ScoreGap: gap,
     };
 }
-async function runBattery(db) {
+/** Collapse a linked_fallback measurement into the #449 verdicts. */
+function case3Verdict(fixture, measured) {
+    const exp = fixture.linkedExpectations;
+    const byKey = new Map(measured.map((r) => [r.key, r]));
+    const hubA = byKey.get(exp.saturationPair.hubA);
+    const hubB = byKey.get(exp.saturationPair.hubB);
+    const unlinked = byKey.get(exp.directionPair.unlinked);
+    const linked = byKey.get(exp.directionPair.linked);
+    const byteEqual = Object.is(hubA.score, hubB.score);
+    const unlinkedAbove = unlinked.rank < linked.rank;
+    const measuredGap = unlinked.similarity !== null && linked.similarity !== null
+        ? Math.round((unlinked.similarity - linked.similarity) * 1e6) / 1e6
+        : null;
+    return {
+        pass: byteEqual && unlinkedAbove,
+        query: fixture.query,
+        seam: { rrfCompositeWeight: 1 },
+        saturation: {
+            hubA: { key: hubA.key, connections: hubA.connections, score: hubA.score },
+            hubB: { key: hubB.key, connections: hubB.connections, score: hubB.score },
+            byteEqual,
+        },
+        direction: {
+            unlinked: {
+                key: unlinked.key,
+                rank: unlinked.rank,
+                similarity: unlinked.similarity,
+            },
+            linked: {
+                key: linked.key,
+                rank: linked.rank,
+                similarity: linked.similarity,
+            },
+            measuredGap,
+            unlinkedAbove,
+        },
+        results: measured,
+    };
+}
+async function runBattery(db, now) {
     const rows = db
         .prepare("SELECT id, content FROM memories WHERE COALESCE(status, '') != 'absorbed'")
         .all();
@@ -167,6 +233,7 @@ async function runBattery(db) {
             limit: 8,
             noStrengthen: true,
             queryEmbedding: queryEmb,
+            ...(now ? { now } : {}), // #458: the pinned clock (undefined = live)
         });
         const top8 = results.map((r) => r.id);
         // Per-result provenance for the sweep analysis: the channel that
@@ -195,9 +262,9 @@ async function runBattery(db) {
 // ---------------------------------------------------------------------------
 function renderReport(args) {
     const L = [];
-    const { case1, case2, battery } = args;
-    L.push("# Search-trust ranking gate (#425)\n");
-    L.push(`Generated: ${new Date().toISOString()}  \nScoring: ${JSON.stringify(args.scoring)}\n`);
+    const { case1, case2, case3, battery } = args;
+    L.push("# Search-trust ranking gate (#425 + #449)\n");
+    L.push(`Generated: ${new Date().toISOString()}  \nClock: ${args.clock} (#458)  \nScoring: ${JSON.stringify(args.scoring)}\n`);
     L.push("## Case 1 — sirnas_exact_match (AC1)\n");
     L.push(`Query "${case1.query}" — declared top-1: ${ranking_fixtures_js_1.SIRNAS_FIXTURE.expectedTop1} — ` +
         `**${case1.pass ? "PASS" : "FAIL"}**${case1.top1Top2ScoreGap !== null ? ` (top1-top2 score gap ${case1.top1Top2ScoreGap.toFixed(4)})` : ""}\n`);
@@ -211,11 +278,47 @@ function renderReport(args) {
     L.push("## Case 2 — no_match_control (AC2)\n");
     L.push(`Query "${case2.query}" — FTS hits: ${case2.ftsHitRows} (must be 0 — no both-channel ` +
         `candidates can exist)` +
-        (args.case2Stable === null ? "" : ` — vs baseline: **${args.case2Stable ? "identical" : "DRIFTED"}**`) +
+        (args.case2Identity === null
+            ? ""
+            : ` — vs baseline (unlinked-identity gate): **${args.case2Identity.pass ? "PASS" : "FAILED"}**` +
+                (args.case2Identity.failures.length > 0
+                    ? ` — ${args.case2Identity.failures.slice(0, 3).join("; ")}` +
+                        (args.case2Identity.failures.length > 3 ? "; …" : "")
+                    : "")) +
         "\n");
     L.push("Returned order: " + case2.ids.map((k) => k).join(" → ") + "\n");
+    L.push("| rank | key | similarity | source | conn | score |");
+    L.push("|---|---|---|---|---|---|");
+    for (const r of case2.results.slice(0, 6)) {
+        L.push(`| ${r.rank} | ${r.key} | ${r.similarity?.toFixed(4) ?? "-"} | ${r.source ?? "-"} | ` +
+            `${r.connections} | ${r.score.toFixed(4)} |`);
+    }
+    L.push("");
+    L.push("## Case 3 — linked_fallback (#449 items 1+3)\n");
+    L.push(`Query "${case3.query}" — measured under the eval seam rrfCompositeWeight=1 ` +
+        `(finalScore = composite) — **${case3.pass ? "PASS" : "FAIL"}**\n`);
+    L.push(`Saturation pair (declared post-#449: byte-equal scores — both hubs saturate at K=16; ` +
+        `red under the linear term is the before-picture): ` +
+        `${case3.saturation.hubA.key} (k=${case3.saturation.hubA.connections}) score ` +
+        `${case3.saturation.hubA.score.toFixed(6)} vs ${case3.saturation.hubB.key} ` +
+        `(k=${case3.saturation.hubB.connections}) score ${case3.saturation.hubB.score.toFixed(6)} — ` +
+        `byte-equal: **${case3.saturation.byteEqual ? "YES" : "NO"}**\n`);
+    L.push(`Direction pair (declared: unlinked ranks ABOVE the 4-link row — similarity dominates ` +
+        `the saturated connections credit): ${case3.direction.unlinked.key} sim ` +
+        `${case3.direction.unlinked.similarity?.toFixed(4) ?? "-"} rank #${case3.direction.unlinked.rank} vs ` +
+        `${case3.direction.linked.key} sim ${case3.direction.linked.similarity?.toFixed(4) ?? "-"} rank ` +
+        `#${case3.direction.linked.rank} — measured gap ` +
+        `${case3.direction.measuredGap?.toFixed(4) ?? "-"} — unlinked above: ` +
+        `**${case3.direction.unlinkedAbove ? "YES" : "NO"}**\n`);
+    L.push("| rank | key | similarity | source | conn | score |");
+    L.push("|---|---|---|---|---|---|");
+    for (const r of case3.results.slice(0, 6)) {
+        L.push(`| ${r.rank} | ${r.key} | ${r.similarity?.toFixed(4) ?? "-"} | ${r.source ?? "-"} | ` +
+            `${r.connections} | ${r.score.toFixed(4)} |`);
+    }
+    L.push("");
     if (battery) {
-        L.push("## Case 3 — real-query battery (AC3 no-regression photo)\n");
+        L.push("## Case 4 — real-query battery (AC3 no-regression photo)\n");
         L.push(`Queries: ${battery.queries.length}; Sirnäs rank for "${ranking_battery_js_1.SIRNAS_QUERY}": ` +
             (battery.sirnasRank === null ? "not in top-8" : `#${battery.sirnasRank}`) + "\n");
         if (args.comparison) {
@@ -249,7 +352,7 @@ function renderReport(args) {
 // main
 // ---------------------------------------------------------------------------
 function usage() {
-    console.error("Usage: npm run eval:ranking -- [--snapshot <db>] [--photo <out.json>] [--compare <baseline.json>] [--scoring '<json>']");
+    console.error("Usage: npm run eval:ranking -- [--snapshot <db>] [--photo <out.json>] [--compare <baseline.json>] [--scoring '<json>'] [--now <ISO>]");
     process.exit(1);
 }
 async function main() {
@@ -264,6 +367,19 @@ async function main() {
     const scoringRaw = flag("--scoring");
     if (argv.includes("--help") || argv.includes("-h"))
         usage();
+    // #458: pin the eval clock (planted lastAccessed offsets + every retrieve
+    // score against the same instant). Invalid input fails explicit — never a
+    // silent live fallback that would reintroduce wall-clock drift.
+    let now;
+    try {
+        now = (0, eval_clock_js_1.parsePinnedNow)(flag("--now"));
+    }
+    catch (err) {
+        console.error(`[ranking-eval] ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    console.log(`[ranking-eval] clock: ${(0, eval_clock_js_1.clockLabel)(now)}`);
+    const nowArg = now ?? undefined;
     if (scoringRaw) {
         try {
             const parsed = JSON.parse(scoringRaw);
@@ -274,7 +390,7 @@ async function main() {
             process.exit(1);
         }
     }
-    for (const f of [ranking_fixtures_js_1.SIRNAS_FIXTURE, ranking_fixtures_js_1.NO_MATCH_FIXTURE]) {
+    for (const f of [ranking_fixtures_js_1.SIRNAS_FIXTURE, ranking_fixtures_js_1.NO_MATCH_FIXTURE, ranking_fixtures_js_1.LINKED_FALLBACK_FIXTURE]) {
         const problems = (0, ranking_fixtures_js_1.checkFixtureInvariants)(f);
         if (problems.length > 0) {
             console.error(`[ranking-eval] fixture ${f.key} invariant violations: ${problems.join("; ")}`);
@@ -291,9 +407,9 @@ async function main() {
         const db = (0, db_js_1.initDb)((0, node_path_1.join)(workDir, "planted.db"));
         try {
             console.log("[ranking-eval] planting corpus (real embedder)...");
-            const idByKey = await plantRankingFixture(db, ranking_fixtures_js_1.SIRNAS_FIXTURE);
-            case1 = await measurePlantedCase(db, ranking_fixtures_js_1.SIRNAS_FIXTURE, idByKey);
-            const case2Measured = await measurePlantedCase(db, ranking_fixtures_js_1.NO_MATCH_FIXTURE, idByKey);
+            const idByKey = await plantRankingFixture(db, ranking_fixtures_js_1.SIRNAS_FIXTURE, nowArg);
+            case1 = await measurePlantedCase(db, ranking_fixtures_js_1.SIRNAS_FIXTURE, idByKey, nowArg);
+            const case2Measured = await measurePlantedCase(db, ranking_fixtures_js_1.NO_MATCH_FIXTURE, idByKey, nowArg);
             // The returned list keyed by fixture key (readable photos; ids would
             // churn across replanting).
             case2 = { ...case2Measured, ids: case2Measured.results.map((r) => r.key) };
@@ -305,9 +421,35 @@ async function main() {
     finally {
         (0, node_fs_1.rmSync)(workDir, { recursive: true, force: true });
     }
+    // Case 3 (#449): planted in its OWN throwaway DB, measured under the eval
+    // seam — rrfCompositeWeight 1 makes finalScore = composite exactly (the
+    // savedWeights save/restore pattern from tests/ranking-flip.test.ts; the
+    // --scoring CLI overrides, if any, are what gets saved and restored).
+    let case3;
+    {
+        const savedWeights = (0, retrieval_js_1.getScoringWeights)();
+        (0, retrieval_js_1.configureScoring)({ ...savedWeights, rrfCompositeWeight: 1 });
+        const workDir3 = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-ranking-eval-linked-"));
+        try {
+            const db = (0, db_js_1.initDb)((0, node_path_1.join)(workDir3, "linked.db"));
+            try {
+                console.log("[ranking-eval] planting linked_fallback corpus (real embedder)...");
+                const idByKey3 = await plantRankingFixture(db, ranking_fixtures_js_1.LINKED_FALLBACK_FIXTURE, nowArg);
+                const measured3 = await measurePlantedCase(db, ranking_fixtures_js_1.LINKED_FALLBACK_FIXTURE, idByKey3, nowArg);
+                case3 = case3Verdict(ranking_fixtures_js_1.LINKED_FALLBACK_FIXTURE, measured3.results);
+            }
+            finally {
+                db.close();
+            }
+        }
+        finally {
+            (0, node_fs_1.rmSync)(workDir3, { recursive: true, force: true });
+            (0, retrieval_js_1.configureScoring)(savedWeights); // restore — battery + photo run at the caller's weights
+        }
+    }
     let battery = null;
     let comparison = null;
-    let case2Stable = null;
+    let case2Identity = null;
     // Content lookup for the exact-match gate (the SAME corpus both photos
     // were recorded against — the snapshot, when comparing).
     const contentById = new Map();
@@ -315,7 +457,7 @@ async function main() {
         console.log(`[ranking-eval] battery against readonly snapshot: ${snapshotPath}`);
         const sdb = (0, eval_db_js_1.openSnapshot)(snapshotPath);
         try {
-            battery = await runBattery(sdb);
+            battery = await runBattery(sdb, nowArg);
             for (const r of sdb
                 .prepare("SELECT id, content FROM memories WHERE COALESCE(status, '') != 'absorbed'")
                 .all()) {
@@ -335,15 +477,31 @@ async function main() {
             console.error(`[ranking-eval] cannot read baseline photo ${comparePath}: ${err instanceof Error ? err.message : err}`);
             process.exit(1);
         }
-        if (!baseline.case2 || !baseline.battery || !battery) {
-            console.error("[ranking-eval] baseline photo lacks case2/battery — record one with --photo on the same snapshot first");
+        if (!baseline.case2) {
+            console.error("[ranking-eval] baseline photo lacks case2 — record one with --photo first");
+            process.exit(1);
+        }
+        // #449: the case-2 gate is the unlinked-row identity comparator (linked
+        // rows drift BY DESIGN); it reads the per-row results the baseline must
+        // already carry and fails with a re-record instruction when it doesn't.
+        case2Identity = (0, ranking_battery_js_1.compareCase2Unlinked)(baseline.case2, { ftsHitRows: case2.ftsHitRows, ids: case2.ids, results: case2.results });
+        // The battery comparison runs only when BOTH sides have one (the
+        // baseline was recorded with --snapshot AND this run passes it).
+        if (baseline.battery && battery) {
+            comparison = (0, ranking_battery_js_1.batteryComparison)(baseline.battery, battery, contentById);
+        }
+        else if (baseline.battery && !battery) {
+            console.error("[ranking-eval] baseline photo has a battery but this run recorded none — pass --snapshot to compare it");
             process.exit(1);
         }
-        case2Stable = (0, ranking_battery_js_1.compareCase2)(baseline.case2.ids, case2.ids);
-        comparison = (0, ranking_battery_js_1.batteryComparison)(baseline.battery, battery, contentById);
     }
     const photo = {
         generatedAt: new Date().toISOString(),
+        /** #458: self-describing clock — which instant the decay/recency terms
+         *  scored against ({mode:"pinned", now} or {mode:"live"}). */
+        clock: now === null
+            ? { mode: "live" }
+            : { mode: "pinned", now: now.toISOString() },
         scoring: (0, retrieval_js_1.getScoringWeights)(),
         case1: {
             pass: case1.pass,
@@ -351,10 +509,11 @@ async function main() {
             top1Top2ScoreGap: case1.top1Top2ScoreGap,
             results: case1.results,
         },
-        case2: { ftsHitRows: case2.ftsHitRows, ids: case2.ids },
+        case2: { ftsHitRows: case2.ftsHitRows, ids: case2.ids, results: case2.results },
+        case3,
         battery,
         comparison,
-        case2Stable,
+        case2Identity,
     };
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(photoPath), { recursive: true });
     (0, node_fs_1.writeFileSync)(photoPath, JSON.stringify(photo, null, 2), "utf-8");
@@ -362,10 +521,12 @@ async function main() {
     const report = renderReport({
         case1,
         case2,
+        case3,
         battery,
         comparison,
-        case2Stable,
+        case2Identity,
         scoring: { ...photo.scoring },
+        clock: (0, eval_clock_js_1.clockLabel)(now),
     });
     console.log(report);
     const reportPath = photoPath.endsWith(".json")
@@ -376,10 +537,12 @@ async function main() {
         ? true
         : comparison.top1StabilityExPromotions >= BATTERY_TOP1_STABILITY_MIN &&
             comparison.lostBothChannelExact.length === 0;
-    const case2Ok = case2Stable === null ? true : case2Stable;
-    const ok = case1.pass === true && case2Ok && batteryOk;
+    const case2Ok = case2Identity === null ? true : case2Identity.pass;
+    const case3Ok = case3.pass;
+    const ok = case1.pass === true && case2Ok && case3Ok && batteryOk;
     console.log(`[ranking-eval] ${ok ? "GATE PASS" : "GATE FAIL"} (case1 ${case1.pass ? "pass" : "FAIL"}, ` +
-        `case2 ${case2Ok ? "ok" : "DRIFT"}, battery ${batteryOk ? "ok" : "DRIFT"} ` +
+        `case2 ${case2Ok ? "ok" : "DRIFT"}, case3 ${case3Ok ? "pass" : "FAIL"}, ` +
+        `battery ${batteryOk ? "ok" : "DRIFT"} ` +
         `[top-1 ${((comparison?.top1Stability ?? 1) * 100).toFixed(1)}% raw / ` +
         `${((comparison?.top1StabilityExPromotions ?? 1) * 100).toFixed(1)}% ex-promotions, ` +
         `lost both-channel exact ${comparison?.lostBothChannelExact.length ?? 0}]) in ${Date.now() - t0}ms`);

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

@@ -5,7 +5,7 @@
  * issue (the owner's live console test, 2026-09-13): a user searches a
  * DISTINCTIVE PROPER NOUN they know exists; the one memory carrying that
  * token has the best similarity of all candidates AND the literal FTS hit,
- * yet ranks behind hardened but less-relevant memories that win on
+ * yet ranks behind high-strength but less-relevant memories that win on
  * effective strength + graph connections.
  *
  *   (a) sirnas_exact_match — the AC1 fixture: a low-strength, unlinked,
@@ -20,14 +20,19 @@
  *       under the ranking work (no both-channel candidates exist, so the
  *       boost can never fire — the case pins that the no-regression
  *       guarantee is structural, not lucky).
+ *   (c) linked_fallback — the #449 (items 1+3) connections fixture: a
+ *       16-link vs 20-link identical-content hub pair (the saturation tie)
+ *       plus an unlinked higher-similarity row vs a 4-link lower-similarity
+ *       row (the direction pin). Planted in its OWN throwaway DB — the 40
+ *       link-neighbor rows would pollute the case-1/2 corpus.
  *
  * Honesty rules (the planted-pairs #393 A discipline):
  *  - The texts are synthetic and generic (this package publishes to npm —
  *    no real infrastructure, people, or fleet detail), but SHAPED like the
  *    field failure: the proper noun is invented (it must appear nowhere
- *    else — verified by an invariant test), the rivals are hardened with
- *    metadata the production pipeline itself writes (base strength, access
- *    hardening, link counts).
+ *    else — verified by an invariant test), the rivals carry the metadata
+ *    the production pipeline itself writes (base strength, access history,
+ *    link counts).
  *  - Similarities are MEASURED at run time with the real bge-small-en-v1.5
  *    embedder (ranking-eval.ts) — never asserted into existence. The
  *    declared expectation is about ORDER under the shipped ranking, and
@@ -46,7 +51,7 @@ export interface RankingRow {
     memoryType: string;
     /** Birth base_strength — the value stageImportance would have written. */
     baseStrength: number;
-    /** Access history (hardening + the decay clock). */
+    /** Access history (the decay clock + the #448 promotion baseline). */
     accessCount: number;
     /** Days before the run's `now` of the last access (0 = touched today). */
     lastAccessedDaysAgo: number;
@@ -66,12 +71,47 @@ export interface RankingFixture {
     distinctiveToken: string;
     /** Declared expectation: this row's key must be returned at position 1. */
     expectedTop1: string;
+    /**
+     * Declared undirected link degree per row key (#449): own linksTo entries
+     * PLUS the times other rows reference it (each linksTo entry is one link
+     * row, mirroring storage.getLinks(id, "both").length). Optional — case 1
+     * and case 3 declare it; a corpus that silently drifts from its declared
+     * link-cluster shape would fake a pass/fail.
+     */
+    expectedUndirectedDegree?: Record<string, number>;
+    /**
+     * #449 case-3 (linked_fallback) expectations — absent for cases 1-2. The
+     * verdict logic (byte-equality + rank order) lives in ranking-eval.ts.
+     */
+    linkedExpectations?: {
+        /**
+         * The saturation pair: two identical-content hubs at the declared
+         * degrees — post-#449 (log-saturating term, K = 16) their scores must
+         * be byte-EQUAL (both saturate); under the pre-#449 linear term they
+         * differ by ~0.03 composite (the recorded before-picture).
+         */
+        saturationPair: {
+            hubA: string;
+            hubB: string;
+        };
+        /**
+         * The direction pair: unlinked (higher measured similarity, carries the
+         * distinctive token) vs linked (exactly 4 links, ~0.20 lower measured
+         * similarity, equal metadata otherwise). Declared (Option A, owner
+         * decision 2026-09-17): the unlinked row ranks ABOVE the linked one.
+         */
+        directionPair: {
+            unlinked: string;
+            linked: string;
+        };
+    };
 }
 /** All planted rows share project + source_agent (metadata never refuses). */
 export declare const RANKING_PROJECT = "ranking-eval";
 export declare const RANKING_SOURCE_AGENT = "ranking-eval";
 export declare const SIRNAS_FIXTURE: RankingFixture;
 export declare const NO_MATCH_FIXTURE: RankingFixture;
-/** The battery runs against a real snapshot copy (ranking-eval.ts case 3). */
+/** The battery runs against a real snapshot copy (ranking-eval.ts case 4). */
 export declare const REAL_SIRNAS_MEMORY_ID = "12980c9d-0eba-4963-95eb-0548bc2aa93e";
+export declare const LINKED_FALLBACK_FIXTURE: RankingFixture;
 export declare function checkFixtureInvariants(f: RankingFixture): string[];