@gamaze/hicortex 0.21.0 → 0.22.1

package/dist/eval/ranking-fixtures.js

@@ -6,7 +6,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,
@@ -21,14 +21,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
@@ -38,7 +43,7 @@
  *    fixture exercises the same rows retrieval() will see.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REAL_SIRNAS_MEMORY_ID = exports.NO_MATCH_FIXTURE = exports.SIRNAS_FIXTURE = exports.RANKING_SOURCE_AGENT = exports.RANKING_PROJECT = void 0;
+exports.LINKED_FALLBACK_FIXTURE = exports.REAL_SIRNAS_MEMORY_ID = exports.NO_MATCH_FIXTURE = exports.SIRNAS_FIXTURE = exports.RANKING_SOURCE_AGENT = exports.RANKING_PROJECT = void 0;
 exports.checkFixtureInvariants = checkFixtureInvariants;
 /** All planted rows share project + source_agent (metadata never refuses). */
 exports.RANKING_PROJECT = "ranking-eval";
@@ -50,13 +55,13 @@ exports.RANKING_SOURCE_AGENT = "ranking-eval";
 // The target mirrors the field case's SHAPE with invented names: a home
 // harbour memory carrying one distinctive proper noun, born weak (base 0.35,
 // the "routine-but-curated" band), never accessed, unlinked, a few months
-// old. The rivals are what the decay model produces for early-hardened
+// old. The rivals are what the decay model produces for early high-strength
 // technical rows: base 0.90-0.95, mutual links, access history, created
 // BEFORE the target. They share the harbour/boating domain vocabulary — so
 // a bare proper-noun query lands in their neighborhood — but none carries
 // the proper noun.
 const SIRNAS_ROWS = [
-    // --- rivals: hardened, connected, older, domain-adjacent ---
+    // --- rivals: high-strength, connected, older, domain-adjacent ---
     {
         key: "rival_fees",
         content: "Harbour fees and guest dock rules: pay at the machine by the fuel quay, electricity on the guest dock is metered, " +
@@ -158,11 +163,25 @@ const SIRNAS_ROWS = [
 exports.SIRNAS_FIXTURE = {
     key: "sirnas_exact_match",
     description: "AC1: a distinctive proper-noun query must rank the exact-match (both-channel) memory first, " +
-        "ahead of hardened domain-adjacent rivals that win on strength + connections.",
+        "ahead of high-strength domain-adjacent rivals that win on strength + connections.",
     rows: SIRNAS_ROWS,
     query: "Vindarsvik",
     distinctiveToken: "vindarsvik",
     expectedTop1: "target_harbour",
+    // Undirected degrees (#449 invariant extension): the rivals' mutual-link
+    // cluster — fees/channel 4 each, maintenance 3, passage 1 (each linksTo
+    // entry is one link row; both directions of a mutual pair count).
+    expectedUndirectedDegree: {
+        rival_fees: 4,
+        rival_channel: 4,
+        rival_maintenance: 3,
+        rival_passage: 1,
+        target_harbour: 0,
+        fill_recipe: 0,
+        fill_books: 0,
+        fill_lang: 0,
+        fill_garden: 0,
+    },
 };
 // ---------------------------------------------------------------------------
 // Case 2 — no_match_control (AC2)
@@ -186,13 +205,213 @@ exports.NO_MATCH_FIXTURE = {
     // records the list; the gate compares runs).
     expectedTop1: "",
 };
-/** 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). */
 exports.REAL_SIRNAS_MEMORY_ID = "12980c9d-0eba-4963-95eb-0548bc2aa93e";
 // ---------------------------------------------------------------------------
+// Case 3 — linked_fallback (#449 items 1+3, PR E)
+// ---------------------------------------------------------------------------
+//
+// The connections-term fixture for the log-saturation reshape. Two probes in
+// ONE corpus (planted in its own throwaway DB by ranking-eval.ts — the 40
+// link-neighbor rows stay out of the case-1/2 corpus):
+//
+//   saturation pair — two hubs with IDENTICAL content strings and identical
+//   metadata (same baseStrength, accessCount, lastAccessedDaysAgo,
+//   createdAt, memoryType); hub A carries exactly 16 undirected links, hub B
+//   exactly 20, through disjoint off-domain neighbor rows. Declared
+//   expectation POST-change (Option A, K = 16): the two hubs' scores are
+//   byte-EQUAL — the term min(1, log1p(k)/log1p(16)) saturates at 1 for both.
+//   Under the pre-#449 linear term (connectionCount / maxConnections = k/20)
+//   they differ by 0.2 × 0.15 ≈ 0.03 composite — that red is the recorded
+//   before-picture; the harness does NOT make it pass.
+//
+//   direction pair — an unlinked row carrying the query's distinctive proper
+//   noun (the highest measured similarity) vs a linked row (exactly 4 links)
+//   whose MEASURED similarity is engineered ~0.20 LOWER, with equal metadata
+//   otherwise (equal strength/dates). Declared expectation (Option A, owner
+//   decision 2026-09-17): the unlinked row ranks ABOVE the linked one — a
+//   0.20 gap is worth 0.10 composite at the 0.50 similarity weight, more
+//   than the k=4 connections credit (0.0852 post-change). The gap must
+//   exceed 0.171 for the pin to be sound at k = 4; the wording is tuned
+//   until the real-embedder measurement (recorded in the photo/report)
+//   lands at ~0.20.
+//
+// Neighbors are DISTINCT filler rows, disjoint between the two hubs and from
+// the direction pair's cluster, all off-domain from the query — they exist
+// to carry the hub/dir-linked degrees and nothing else.
+const HUB_CONTENT = "Community noticeboard archive: the autumn fair needs tombola volunteers, choir practice moves to " +
+    "Thursday evenings, and the book-swap shelf now carries the walking-map folder.";
+/** Off-domain one-line filler rows (deterministic keys, uniform metadata). */
+function fillerRows(prefix, contents) {
+    return contents.map((content, i) => ({
+        key: `${prefix}_n${i}`,
+        content,
+        createdAt: "2026-04-15T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 150,
+        linksTo: [],
+    }));
+}
+const HUB_A_NEIGHBOR_CONTENTS = [
+    "Slow-cooker beans: soak overnight, then four hours on low with a bay leaf and a piece of smoked pork.",
+    "The second detective novel in the series drags until the lighthouse keeper's ledger turns up.",
+    "German grammar drill: subordinate clauses shove the verb to the end, so read the whole sentence before translating.",
+    "Raised-bed rotation: legumes follow brassicas, and lime the bed the cabbage family just emptied.",
+    "October weather pattern: the first night frosts usually arrive right after the harvest moon.",
+    "Bike maintenance: true the wheel by tightening spokes a quarter turn at a time, listening for the ping.",
+    "Chess opening note: against the locked center, flank with pawns only after the pieces are developed.",
+    "The documentary about the alpine tunnels spent too long on the geologists' cafeteria.",
+    "Coffee grinding: a burr grind for the pour-over; the blade grinder is fine enough only for the French press.",
+    "Hiking the ridge trail: start before the thermals build, and carry an extra liter once the pass is in sight.",
+    "Piano practice: separate hands at half tempo until the fingering is automatic, then join them slowly.",
+    "Sewing patch pockets: interface the fabric, and topstitch the same distance from every edge.",
+    "Bird notes: the chiffchaff repeats its own name all day; the willow warbler slides down the scale.",
+    "Sourdough rhythm: feed the starter after work, shape in the morning, bake when the poke test springs back halfway.",
+    "Replacing the washing-machine hose: shut the valve, expect a cup of water, and check the jubilee clip.",
+    "Audiobook note: the narrator's accent makes every ship's name sound like a Hebridean island.",
+];
+const HUB_B_NEIGHBOR_CONTENTS = [
+    "Winter tyres: swap before the first ice, and store the summer set flat in the dark basement.",
+    "The boardgame group settled on tiles-and-traders for the long evenings; the card game stays in the drawer.",
+    "Compost thermometer: the pile is cooking properly when it reads hotter than a warm bath for a week.",
+    "Frost-proof terracotta: empty the pots, stack them dry, and the succulents overwinter on the south sill.",
+    "The photography club theme this month is doors; shoot in morning shade and bracket the exposures.",
+    "Robot vacuum note: keep the charging dock's floor clear, or it nudges the rug and gives up mid-run.",
+    "Knife sharpening: the ceramic rod for touch-ups, the whetstone when the tomato skin resists.",
+    "The lecture on Roman concrete held the room until the slide about seawater pozzolana.",
+    "Necklace repair: jump rings open sideways, never apart, or the circle never closes again.",
+    "Ferry timetable change: the winter crossing departs an hour earlier and stops running on Sunday evenings.",
+    "Ski waxing: glide wax for the thaw, grip wax for the freeze, and never both in the same zone.",
+    "The archive boxes are labelled by decade now; the negatives live in the fire cupboard.",
+    "Beekeeping note: heft the hive — if one side lifts easily, the winter stores are short.",
+    "Jigsaw strategy: edges first, then the sky, and give the lamp a clean bulb for the blue hours.",
+    "The museum's clock gallery is closed for restoration until the pendulum clock returns.",
+    "Preserving basil: pesto freezes flat in bags; the leaves kept in water go black within a week.",
+    "Draft excluder: the brush strip on the letterbox cut the hallway draught more than the door seal did.",
+    "The organ recital opened with a toccata nobody knew and closed with everyone humming it.",
+    "Train-set wiring: one feeder per rail section, or the far loop slows to a crawl.",
+    "The pottery class moved on to wheel work; my first cylinder collapsed into a bowl with charm.",
+];
+const DIR_NEIGHBOR_CONTENTS = [
+    "Vaccine appointment bookkeeping: the clinic sends both a text and a letter, and only the letter carries the time.",
+    "Reading glasses: the cheap pair from the station shop outlasted the optician's by two years.",
+    "The new debit card needs the reader for anything over the limit; the shop keeps the old machine as backup.",
+    "Laundering the down jacket: tennis balls in the dryer, low heat, and patience.",
+];
+const hubNeighbors = (prefix, contents) => contents.map((_, i) => `${prefix}_n${i}`);
+const LINKED_FALLBACK_ROWS = [
+    // --- saturation pair: identical content + metadata, degrees 16 vs 20 ---
+    {
+        key: "hub_sat_16",
+        content: HUB_CONTENT,
+        createdAt: "2026-05-10T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.6,
+        accessCount: 0,
+        lastAccessedDaysAgo: 120,
+        linksTo: hubNeighbors("huba", HUB_A_NEIGHBOR_CONTENTS),
+    },
+    {
+        key: "hub_sat_20",
+        content: HUB_CONTENT,
+        createdAt: "2026-05-10T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.6,
+        accessCount: 0,
+        lastAccessedDaysAgo: 120,
+        linksTo: hubNeighbors("hubb", HUB_B_NEIGHBOR_CONTENTS),
+    },
+    // --- direction pair: equal metadata; similarity gap engineered ~0.20 ---
+    // MEASURED (bge-small-en-v1.5, 2026-09-17): unlinked 0.8233 vs linked
+    // 0.6022 — gap 0.2212. The linked row deliberately carries the plural
+    // "guests" (an FTS-DISTINCT token from the query's "guest" under the
+    // unicode61 tokenizer) so it stays single-channel: the pin isolates
+    // similarity vs connections credit, not the both-channel boost.
+    {
+        key: "dir_unlinked",
+        content: "Home anchorage: Anchorholme, east of the skerries. The guest mooring lies by the old timber jetty — " +
+            "arrive at slack water and mind the ferry wake inside the bay.",
+        createdAt: "2026-07-01T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.6,
+        accessCount: 0,
+        lastAccessedDaysAgo: 90,
+        linksTo: [],
+    },
+    {
+        key: "dir_linked",
+        content: "Anchoring for the night behind the skerries: lay out chain at least four times the depth in the crowded " +
+            "bay, take one of the buoys kept for guests if the harbour has room, and check the swing radius around " +
+            "the mooring field before dark.",
+        createdAt: "2026-07-01T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.6,
+        accessCount: 0,
+        lastAccessedDaysAgo: 90,
+        linksTo: ["dirn_n0", "dirn_n1", "dirn_n2", "dirn_n3"],
+    },
+    // --- link carriers: 40 disjoint off-domain filler rows (degrees all 1) ---
+    ...fillerRows("huba", HUB_A_NEIGHBOR_CONTENTS),
+    ...fillerRows("hubb", HUB_B_NEIGHBOR_CONTENTS),
+    ...fillerRows("dirn", DIR_NEIGHBOR_CONTENTS),
+];
+/** Declared degrees: hubs 16/20, direction-linked 4, every neighbor 1. */
+function linkedFallbackDegrees() {
+    const degrees = {
+        hub_sat_16: 16,
+        hub_sat_20: 20,
+        dir_linked: 4,
+        dir_unlinked: 0,
+    };
+    for (const prefix of ["huba", "hubb", "dirn"]) {
+        const count = prefix === "huba"
+            ? HUB_A_NEIGHBOR_CONTENTS.length
+            : prefix === "hubb"
+                ? HUB_B_NEIGHBOR_CONTENTS.length
+                : DIR_NEIGHBOR_CONTENTS.length;
+        for (let i = 0; i < count; i++)
+            degrees[`${prefix}_n${i}`] = 1;
+    }
+    return degrees;
+}
+exports.LINKED_FALLBACK_FIXTURE = {
+    key: "linked_fallback",
+    description: "#449 (items 1+3): the connections reshape — a 16-link and a 20-link identical-content hub " +
+        "must score byte-equal post-change (both saturate at K=16), and an unlinked row ~0.20 more " +
+        "similar must outrank a 4-link rival (similarity dominates the saturated connections credit).",
+    rows: LINKED_FALLBACK_ROWS,
+    query: "Anchorholme guest anchorage",
+    distinctiveToken: "anchorholme",
+    expectedTop1: "dir_unlinked",
+    expectedUndirectedDegree: linkedFallbackDegrees(),
+    linkedExpectations: {
+        saturationPair: { hubA: "hub_sat_16", hubB: "hub_sat_20" },
+        directionPair: { unlinked: "dir_unlinked", linked: "dir_linked" },
+    },
+};
+// ---------------------------------------------------------------------------
 // Fixture invariants (checked by ranking-eval at run time AND pinned in
 // tests/ranking-eval-tooling.test.ts — a corpus that silently drifts from
 // its declared shape would fake a pass/fail)
 // ---------------------------------------------------------------------------
+/**
+ * Undirected degree per row key from the declared linksTo arrays (#449):
+ * a row's own linksTo entries PLUS the times other rows reference it — each
+ * linksTo entry is one link row, so a mutual pair counts twice, mirroring
+ * storage.getLinks(id, "both").length.
+ */
+function undirectedDegrees(rows) {
+    const degree = new Map(rows.map((r) => [r.key, 0]));
+    for (const r of rows) {
+        for (const to of r.linksTo) {
+            degree.set(r.key, (degree.get(r.key) ?? 0) + 1);
+            degree.set(to, (degree.get(to) ?? 0) + 1);
+        }
+    }
+    return degree;
+}
 function checkFixtureInvariants(f) {
     const problems = [];
     const keys = new Set(f.rows.map((r) => r.key));
@@ -209,6 +428,46 @@ function checkFixtureInvariants(f) {
     if (f.expectedTop1 && !keys.has(f.expectedTop1)) {
         problems.push(`expectedTop1 ${f.expectedTop1} is not a row key`);
     }
+    if (f.linkedExpectations) {
+        const declared = [
+            ["hubA", f.linkedExpectations.saturationPair.hubA],
+            ["hubB", f.linkedExpectations.saturationPair.hubB],
+            ["unlinked", f.linkedExpectations.directionPair.unlinked],
+            ["linked", f.linkedExpectations.directionPair.linked],
+        ];
+        for (const [role, key] of declared) {
+            if (!keys.has(key)) {
+                problems.push(`linkedExpectations ${role} ${key} is not a row key`);
+            }
+        }
+        const hubs = f.rows.filter((r) => r.key === f.linkedExpectations.saturationPair.hubA ||
+            r.key === f.linkedExpectations.saturationPair.hubB);
+        if (hubs.length === 2) {
+            const [a, b] = hubs;
+            const metaEqual = a.content === b.content &&
+                a.createdAt === b.createdAt &&
+                a.memoryType === b.memoryType &&
+                a.baseStrength === b.baseStrength &&
+                a.accessCount === b.accessCount &&
+                a.lastAccessedDaysAgo === b.lastAccessedDaysAgo;
+            if (!metaEqual) {
+                problems.push("saturation-pair hubs differ beyond their links (content/metadata must be identical)");
+            }
+        }
+    }
+    if (f.expectedUndirectedDegree) {
+        const degree = undirectedDegrees(f.rows);
+        for (const [key, expected] of Object.entries(f.expectedUndirectedDegree)) {
+            if (!keys.has(key)) {
+                problems.push(`expectedUndirectedDegree names unknown key ${key}`);
+                continue;
+            }
+            const actual = degree.get(key) ?? 0;
+            if (actual !== expected) {
+                problems.push(`${key} undirected degree is ${actual}, declared ${expected}`);
+            }
+        }
+    }
     if (f.distinctiveToken) {
         const token = f.distinctiveToken.toLowerCase();
         const carriers = f.rows.filter((r) => r.content.toLowerCase().includes(token));

package/dist/eval/recall-sweep.d.ts

@@ -68,7 +68,7 @@
  *
  *   Each hardware query runs TWICE on the same static DB:
  *     scope OFF — no `project` sent (byte-identical to pre-#203).
- *     scope ON  — `project: "hardware"` (computeScore adds +projectAffinity 0.15
+ *     scope ON  — `project: "hardware"` (computeScore adds +scopeAffinity 0.15
  *                 to hardware memories; marine gets 0; no hard filter).
  *
  *   Metrics: contamination@5 (marine in top-5 / 5 — LOWER is better),
@@ -77,6 +77,11 @@
  *   `project` is the ONLY variable. Same invariants (noStrengthen, real
  *   embedder, uniform metadata, neverCalledEmbed self-check).
  *
- * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
+ * Run:  npm run eval:recall-sweep [--now <ISO>]   (==  node dist/eval/recall-sweep.js)
+ *
+ * `--now <ISO>` (#458) pins the eval clock: the planted corpora's created_at
+ * AND every retrieve() call score against the SAME instant, so before/after
+ * runs are wall-clock-independent. Default: the live clock (the pre-#458
+ * behavior); the report header records which clock produced it.
  */
 export {};

package/dist/eval/recall-sweep.js

@@ -69,7 +69,7 @@
  *
  *   Each hardware query runs TWICE on the same static DB:
  *     scope OFF — no `project` sent (byte-identical to pre-#203).
- *     scope ON  — `project: "hardware"` (computeScore adds +projectAffinity 0.15
+ *     scope ON  — `project: "hardware"` (computeScore adds +scopeAffinity 0.15
  *                 to hardware memories; marine gets 0; no hard filter).
  *
  *   Metrics: contamination@5 (marine in top-5 / 5 — LOWER is better),
@@ -78,7 +78,12 @@
  *   `project` is the ONLY variable. Same invariants (noStrengthen, real
  *   embedder, uniform metadata, neverCalledEmbed self-check).
  *
- * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
+ * Run:  npm run eval:recall-sweep [--now <ISO>]   (==  node dist/eval/recall-sweep.js)
+ *
+ * `--now <ISO>` (#458) pins the eval clock: the planted corpora's created_at
+ * AND every retrieve() call score against the SAME instant, so before/after
+ * runs are wall-clock-independent. Default: the live clock (the pre-#458
+ * behavior); the report header records which clock produced it.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -119,6 +124,7 @@ const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
 const db_js_1 = require("../db.js");
+const eval_clock_js_1 = require("./eval-clock.js");
 const storage = __importStar(require("../storage.js"));
 const embedder_js_1 = require("../embedder.js");
 const retrieval_js_1 = require("../retrieval.js");
@@ -424,7 +430,7 @@ function buildSessions() {
 // ---------------------------------------------------------------------------
 // DB construction
 // ---------------------------------------------------------------------------
-async function buildCorpusDb(dbPath) {
+async function buildCorpusDb(dbPath, now) {
     const db = (0, db_js_1.initDb)(dbPath);
     const idToTopic = new Map();
     for (const mem of CORPUS) {
@@ -433,6 +439,9 @@ async function buildCorpusDb(dbPath) {
             sourceAgent: "eval-corpus",
             memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
+            // #458: pinned created_at (the same instant retrieve() scores against)
+            // so the uniform-metadata invariant holds on a pinned clock too.
+            createdAt: (now ?? new Date()).toISOString(),
         });
         idToTopic.set(id, mem.topic);
     }
@@ -447,7 +456,7 @@ async function buildCorpusDb(dbPath) {
  *
  * Returns `ids` in corpus order so SCOPE_QUERIES goldIndices map to ids.
  */
-async function buildScopeDb(dbPath) {
+async function buildScopeDb(dbPath, now) {
     const db = (0, db_js_1.initDb)(dbPath);
     const idToProject = new Map();
     const ids = [];
@@ -458,6 +467,7 @@ async function buildScopeDb(dbPath) {
             memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
             project: mem.project, // #203 scope label
+            createdAt: (now ?? new Date()).toISOString(), // #458: pinned clock
         });
         idToProject.set(id, mem.project);
         ids.push(id);
@@ -481,7 +491,7 @@ async function embedAllPrompts(sessions) {
  * only the blend differs). A fresh SessionRecallRegistry per (weight,session)
  * keeps each centroid seeded only by that session's own turns.
  */
-async function runSweep(db, idToTopic, sessions) {
+async function runSweep(db, idToTopic, sessions, now) {
     const promptEmb = await embedAllPrompts(sessions);
     // Fail-explicit embedFn: we ALWAYS supply queryEmbedding, so retrieve()
     // must never call this. If it does, the sweep is measuring the wrong thing.
@@ -503,6 +513,7 @@ async function runSweep(db, idToTopic, sessions) {
                     limit: 5,
                     queryEmbedding: queryVec,
                     noStrengthen: true,
+                    ...(now ? { now } : {}), // #458: pinned clock (undefined = live)
                 });
                 const topIds = results.map((r) => r.id);
                 const onTopic = topIds.filter((id) => idToTopic.get(id) === turnDef.topic);
@@ -599,7 +610,8 @@ function renderReport(focused, shifts, records, sessions, meta) {
     L.push("# Recall@k Sweep — session-intent keying (#192, 0867d6c)\n");
     L.push(`Corpus: ${meta.memoryCount} memories across ${TOPICS.length} topics (5 each), embedded with the ` +
         `real bge-small-en-v1.5 model. ${nFocused} focused scenarios x 4 turns + ${nShift} shift scenarios ` +
-        `x 4 turns (2 on A -> 2 on B).\n`);
+        `x 4 turns (2 on A -> 2 on B). Clock: ${meta.clock} (#458 — the instant the planted ` +
+        `created_at and every retrieve() scored against).\n`);
     L.push("_Static DB across all retrieve() calls (`noStrengthen: true`); uniform memory metadata " +
         "(base_strength=0.5, created_at~now, no links) so vector cosine + RRF is the only discriminator; " +
         "cold-exposure slots are a no-op (all candidates equally cold). Centroid EMA at α=0.4. " +
@@ -784,7 +796,7 @@ function renderReport(focused, shifts, records, sessions, meta) {
  * options. `queryEmbedding` is supplied (pure prompt), so retrieve() must never
  * call the embedFn; the `neverCalledEmbed` self-check enforces that.
  */
-async function runScopeSweep(db, idToProject, ids) {
+async function runScopeSweep(db, idToProject, ids, now) {
     // Precompute query embeddings once — pure prompt, no centroid (scope is the
     // only variable; blend held at 0 to isolate it).
     const queryEmb = new Map();
@@ -806,9 +818,10 @@ async function runScopeSweep(db, idToProject, ids) {
                 queryEmbedding: promptVec,
                 noStrengthen: true,
                 // OFF: omit project entirely (byte-identical to pre-#203).
-                // ON:  send project — computeScore adds +projectAffinity (0.15) to
+                // ON:  send project — computeScore adds +scopeAffinity (max() of the project signal → 0.15) to
                 //      every hardware memory; marine memories get 0.
                 ...(mode === "on" ? { project: SCOPE_PROJECT } : {}),
+                ...(now ? { now } : {}), // #458: pinned clock (undefined = live)
             });
             const topIds = results.map((r) => r.id);
             const marineCount = topIds.filter((id) => idToProject.get(id) === "marine").length;
@@ -842,7 +855,7 @@ function renderScopeSection(records) {
         `(share a token — battery / drain / voltage / charge / temperature — with the hardware queries); ` +
         `${SCOPE_CORPUS.filter((m) => m.project === "marine" && !m.seed).length} are marine-only fillers (no token overlap — control). ` +
         `Each hardware query runs TWICE: scope OFF (no \`project\` sent — byte-identical to pre-#203) and scope ON (\`project: "${SCOPE_PROJECT}"\`). ` +
-        `The #203 affinity adds +projectAffinity (0.15) to hardware memories in computeScore; marine memories get 0. No hard filter anywhere.\n`);
+        `The #203 affinity adds +scopeAffinity (max() of the project signal → 0.15) to hardware memories in computeScore; marine memories get 0. No hard filter anywhere.\n`);
     L.push("_Same invariants as the blend sweep: static DB (`noStrengthen: true`), real bge-small-en-v1.5 embedder, " +
         "uniform metadata (base_strength=0.5, created_at~now, no links). Blend weight held at 0 (pure prompt) — " +
         "scope is orthogonal to session-intent keying. The `neverCalledEmbed` self-check still passes._\n");
@@ -926,6 +939,21 @@ async function main() {
     (0, retrieval_js_1.configureDecay)();
     (0, retrieval_js_1.configureRecall)();
     (0, retrieval_js_1.configureSessionIntent)();
+    // Minimal flag parsing (the file's first flag): --now <ISO> pins the eval
+    // clock (#458). Invalid input fails explicit — never a silent live clock.
+    let now;
+    const argv = process.argv.slice(2);
+    const nowIdx = argv.indexOf("--now");
+    try {
+        now = (0, eval_clock_js_1.parsePinnedNow)(nowIdx !== -1 ? argv[nowIdx + 1] : undefined);
+    }
+    catch (err) {
+        console.error(`[recall-sweep] ${err instanceof Error ? err.message : err}`);
+        process.exitCode = 1;
+        return;
+    }
+    const nowArg = now ?? undefined;
+    console.log(`[recall-sweep] clock: ${(0, eval_clock_js_1.clockLabel)(now)}`);
     const sessions = buildSessions();
     const tmpDir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `hicortex-recall-sweep-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`);
     (0, node_fs_1.mkdirSync)(tmpDir, { recursive: true });
@@ -945,27 +973,28 @@ async function main() {
     try {
         console.log("[recall-sweep] building corpus (embedding 30 memories)...");
         const t0 = Date.now();
-        const { db: opened, idToTopic } = await buildCorpusDb(dbPath);
+        const { db: opened, idToTopic } = await buildCorpusDb(dbPath, nowArg);
         db = opened;
         console.log(`[recall-sweep] corpus ready in ${Date.now() - t0}ms (${idToTopic.size} memories)`);
         console.log("[recall-sweep] running sweep...");
         const t1 = Date.now();
-        const records = await runSweep(db, idToTopic, sessions);
+        const records = await runSweep(db, idToTopic, sessions, nowArg);
         console.log(`[recall-sweep] sweep done in ${Date.now() - t1}ms (${records.length} turn records)`);
         const focused = summarizeFocused(records, sessions);
         const shifts = summarizeShift(records);
         let report = renderReport(focused, shifts, records, sessions, {
             memoryCount: CORPUS.length,
+            clock: (0, eval_clock_js_1.clockLabel)(now),
         });
         // ---- SCOPE sweep (#203) ----
         console.log(`[recall-sweep] building scope corpus (embedding ${SCOPE_CORPUS.length} project-labeled memories)...`);
         const t2 = Date.now();
-        const scopeBuilt = await buildScopeDb(scopeDbPath);
+        const scopeBuilt = await buildScopeDb(scopeDbPath, nowArg);
         scopeDb = scopeBuilt.db;
         console.log(`[recall-sweep] scope corpus ready in ${Date.now() - t2}ms (${scopeBuilt.ids.length} memories)`);
         console.log("[recall-sweep] running scope sweep (OFF vs ON)...");
         const t3 = Date.now();
-        const scopeRecords = await runScopeSweep(scopeDb, scopeBuilt.idToProject, scopeBuilt.ids);
+        const scopeRecords = await runScopeSweep(scopeDb, scopeBuilt.idToProject, scopeBuilt.ids, nowArg);
         console.log(`[recall-sweep] scope sweep done in ${Date.now() - t3}ms (${scopeRecords.length} turn records)`);
         report += "\n\n" + renderScopeSection(scopeRecords);
         (0, node_fs_1.mkdirSync)(reportDir, { recursive: true });

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

@@ -59,6 +59,120 @@
  * Run:
  *   npm run eval:relevance -- <snapshot.db> [prompts.json] [report.md] \
  *       [--judge-delay-ms=2000] [--max-calls=900] [--resume] \
- *       [--verdicts-json=path] [--verdicts-jsonl=path]
+ *       [--verdicts-json=path] [--verdicts-jsonl=path] \
+ *       [--now=<ISO>] [--runs=N]
+ *
+ * #458 clock pin + judge variance protocol:
+ *   - `--now=<ISO>` pins the clock the retrieve sweep scores against (the
+ *     retrieve() `now` seam) — before/after runs become wall-clock-independent
+ *     (default: live clock, the pre-#458 behavior).
+ *   - `--runs=N` (default 1) runs judge phases 1+2 N times over the SAME
+ *     selections (one retrieve sweep) and reports the run-to-run noise floor
+ *     (median + spread + selection-identical flip counts, §15b). Phases 3+4
+ *     stay single-shot; the shared --max-calls budget spans all runs and the
+ *     default scales ×N unless --max-calls was passed explicitly.
+ */
+type Verdict = "relevant" | "noise" | "stale";
+interface JudgeVerdict {
+    /** Q1..Q8 label — mapped back to the real memory id via the caller's
+     *  position-ordered topIds list. */
+    id: string;
+    verdict: Verdict;
+    reason: string;
+}
+type VerdictsOrError = JudgeVerdict[] | {
+    judgeError: string;
+};
+interface CliArgs {
+    positionals: string[];
+    judgeDelayMs: number;
+    maxCalls: number;
+    /** True when --max-calls was passed explicitly (#458) — an explicit budget
+     *  was sized by the caller for the whole invocation and must NOT be scaled
+     *  by --runs (see scaleMaxCalls). */
+    maxCallsExplicit: boolean;
+    resume: boolean;
+    /** Override the raw-verdicts JSON path (default VERDICTS_JSON_PATH) — added
+     *  2026-08-02 so a re-run against a NEW snapshot can never silently
+     *  overwrite a baseline's raw verdicts. */
+    verdictsJsonPath: string;
+    /** Override the checkpoint sidecar / raw-verdicts JSONL path (default
+     *  VERDICTS_JSONL_PATH) — same reason. */
+    verdictsJsonlPath: string;
+    /** #458: raw --now=<ISO> value — undefined = live clock. Validated in main
+     *  via parsePinnedNow (invalid → usage-style error, exit 1). */
+    nowIso: string | undefined;
+    /** #458: judge runs over the fixed selections (phases 1+2 only). Default 1
+     *  = the pre-#458 single-run behavior. */
+    runs: number;
+}
+/** Parsed and exported for tests (#458). Throws on an invalid --runs value
+ *  (NaN or <1) — fail-explicit, never a silent default. */
+export declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * #458 — resolve the effective --max-calls budget. The ONE shared budget
+ * spans ALL judge runs, so when --runs>1 and the caller did NOT pass
+ * --max-calls explicitly, the default scales ×N (each run re-judges every
+ * unit). An explicit budget always wins — the caller sized it for the whole
+ * invocation. Pure, exported for tests.
+ */
+export declare function scaleMaxCalls(runs: number, explicitMaxCalls: number | undefined, defaultMaxCalls: number): number;
+/** Median of a numeric sample (even count → mean of the two middle values).
+ *  Empty input → NaN, the mean() convention above. Does not mutate input. */
+export declare function median(xs: number[]): number;
+/** One judged unit's verdicts for variance accounting (#458): `key` is the
+ *  stable (promptIdx|mode) unit identity, identical across runs because the
+ *  retrieve sweep runs ONCE. */
+export interface VarianceUnitVerdicts {
+    key: string;
+    verdicts: VerdictsOrError;
+}
+/** A headline metric measured once per run (e.g. precision@5 OFF). Values are
+ *  in raw fractions; null = not computable that run (excluded from
+ *  median/spread). */
+export interface VarianceMetricSeries {
+    label: string;
+    values: Array<number | null>;
+}
+export interface VarianceMetricStats extends VarianceMetricSeries {
+    median: number | null;
+    /** (max − min) × 100, in points — the measured run-to-run noise floor. */
+    spreadPts: number | null;
+}
+/** Pairwise flip counts between runs i and j (1-based run numbers). */
+export interface PairwiseFlips {
+    runA: number;
+    runB: number;
+    /** Verdict ROWS compared: (unit, Q-label) pairs present as parsed verdict
+     *  arrays in BOTH runs. judge_error units and labels the judge omitted in
+     *  one run are not comparable — excluded, never counted as flips. */
+    rowsCompared: number;
+    rowsFlipped: number;
+    unitsCompared: number;
+    /** A UNIT flips if any of its comparable rows differ. */
+    unitsFlipped: number;
+}
+export interface JudgeVariance {
+    runs: number;
+    metrics: VarianceMetricStats[];
+    flips: PairwiseFlips[];
+    maxRowsFlipped: number;
+    maxUnitsFlipped: number;
+    meanRowsFlipped: number;
+    meanUnitsFlipped: number;
+    /** Comparable rows of the first pair — selections are identical across
+     *  runs, so only judge errors shrink this (reported per run below). */
+    totalComparableRows: number;
+    /** judge_error UNITS per run (a failed unit yields no parsed rows; it is
+     *  excluded from every flip denominator). */
+    judgeErrorUnitsPerRun: number[];
+}
+/**
+ * Compute the #458 judge-variance account over N runs of the same selections:
+ * per-metric median + spread (the noise floor), and pairwise verdict flip
+ * counts (rows = one Q-label judgment on one (prompt,mode) unit; units flip
+ * if any row does). `perRunVerdicts[r]` is run r+1's units in a stable
+ * order/identity; `metricSeries[s].values[r]` is run r+1's headline value.
  */
+export declare function computeJudgeVariance(perRunVerdicts: VarianceUnitVerdicts[][], metricSeries: VarianceMetricSeries[]): JudgeVariance;
 export {};