@gamaze/hicortex 0.22.0 → 0.22.1

package/assets/dashboard.html

@@ -1391,9 +1391,15 @@ function fmtTokens(n){
   return String(n);
 }
 /* deterministic per-id randomness — the same memory always lands in the
-   same place across reloads (positions are content of the field, not noise) */
+   same place across reloads (positions are content of the field, not noise).
+   #465: the salt hashes at the FRONT (hash32(salt+':'+s)) — FNV-1a does not
+   diffuse a trailing-byte difference, and salts 1/2/3 differ only in their
+   last character, so the old trailing form coupled angle to radius at
+   Pearson r=0.953 (four spiral arms per domain). Salt-first measures
+   r=0.019 (noise). Positions shift once (hash-derived content), then
+   re-stabilize. */
 function hash32(s){ let h=2166136261; for(let i=0;i<s.length;i++){ h^=s.charCodeAt(i); h=Math.imul(h,16777619);} return h>>>0; }
-function rand01(s,salt){ return hash32(s+':'+salt)/4294967296; }
+function rand01(s,salt){ return hash32(salt+':'+s)/4294967296; }
 
 /* ---------- token handling (harvested verbatim from the 0.20.4 console:
    ?token= handoff stripped from the URL, localStorage persistence, 401 →

package/dist/calibration.d.ts

@@ -115,23 +115,58 @@ export declare const SCORE_SIMILARITY_WEIGHT = 0.5;
 export declare const SCORE_STRENGTH_WEIGHT = 0.2;
 /** Graph-centrality share of the composite score (was 0.20; see above). */
 export declare const SCORE_CONNECTIONS_WEIGHT = 0.15;
-/** Slow recency curve share of the composite score (was 0.10; see above). */
+/**
+ * Log-saturation degree K for the connections term (#449 PR E, items 1+3):
+ * the credit is min(1, log1p(k) / log1p(K)) × SCORE_CONNECTIONS_WEIGHT on
+ * the ABSOLUTE undirected-degree scale k — full at k = K, exactly +0 at
+ * k = 0 (unlinked rows score bit-identically to the linear term they
+ * replace). Provenance: p99 of the REAL undirected degree distribution
+ * (read-only audit 2026-09-17 of the canonical wave snapshot, 18,798
+ * memories / 14,600 linked: p50 = 4, p90 = 8, p95 = 9, p99 = 15, p99.9 =
+ * 28.4, max = 40; 135 memories ≥ 16 links = 0.92% of linked) — so the top
+ * ~1% of hubs tie at full credit and everything below differentiates
+ * modestly. Shape grounded in the #449 research base: ACT-R fan saturation
+ * (Anderson & Reder 1999 — activation falls with the LOG of fan), SAM's
+ * saturating returns, cue overload (Watkins & Watkins 1975). Replaces the
+ * candidate-set-relative normalization #449 deleted (k / the per-query max
+ * degree) — a row's score no longer depends on which other rows happened
+ * to match. Alternatives K = 8 (p90 — collapses all p90+ rows to
+ * full credit) and K = 32 (≈p99.9 — leaves the p99 hub at 0.12 of the
+ * term) were tabled in the #449 spec. RELEASE-MANAGED per this module's
+ * evolution contract — overridable only through the configureScoring seam.
+ */
+export declare const CONNECTIONS_SATURATION_DEGREE = 16;
+/** Time-curve share of the composite score — the merged curve's blend weight
+ *  AND slow-region amplitude (was 0.10; see above). The four blend weights
+ *  still sum to 1.0; the head amplitude below is a documented overshoot, NOT
+ *  a fifth blend weight (#430). Zero (via the seam) disables the whole term. */
 export declare const SCORE_RECENCY_WEIGHT = 0.15;
-/** Fresh-memory window: the additive bonus fades linearly to 0 over this
- *  many days. 7 — nightly capture means 1 day is the floor of "fresh"
- *  (#191 Phase B). */
-export declare const FRESHNESS_BOOST_DAYS = 7;
-/** Fresh-memory bonus size at age 0 (#191 Phase B; 0 = disabled via seam). */
-export declare const FRESHNESS_BOOST_WEIGHT = 0.15;
+/** Hourly decay of the merged curve's slow region (#430) — promoted from the
+ *  inline literal computeScore carried; half-life ≈ 57.7 days. At and beyond
+ *  RECENCY_HEAD_DAYS the curve is bit-identical to the pre-#430 slow term
+ *  (SCORE_RECENCY_WEIGHT × RECENCY_HOURLY_DECAY^hours). */
+export declare const RECENCY_HOURLY_DECAY = 0.9995;
+/** Merged time-curve head amplitude at age 0 (#430) — the pre-#430 slow
+ *  weight 0.15 + fresh bonus 0.15: the freshness job is now the early steep
+ *  part of ONE curve. The head joins value-continuously onto the slow region
+ *  at RECENCY_HEAD_DAYS; its rate is DERIVED from that continuity, never a
+ *  free constant. */
+export declare const RECENCY_HEAD_WEIGHT = 0.3;
+/** Join age in days of the merged time curve (#430) — the head window edge,
+ *  carried over from the pre-#430 freshness window. Nightly capture means
+ *  1 day is the floor of "fresh" (#191 Phase B). */
+export declare const RECENCY_HEAD_DAYS = 7;
 /** Score multiplier for a memory a later decision superseded (0.15.2; the
  *  belief walk (#393 D) is the primary mechanism — this is the safety net
  *  for rows the walk does not reach). */
 export declare const SUPERSEDED_DEMOTION = 0.5;
-/** #203 soft boost on exact project match. ADDITIVE, zero-boost neutral,
- *  never a penalty — a foreign memory ranks equal, not lower. */
-export declare const PROJECT_AFFINITY_WEIGHT = 0.15;
-/** #203 soft boost multiplier on max overlapping domain-tag weight. */
-export declare const DOMAIN_AFFINITY_WEIGHT = 0.15;
+/** #430 merged scope affinity — ONE term replacing #203's two boosts (the
+ *  project-affinity and domain-affinity constants) at their shared value.
+ *  Boost = max(project-match indicator (1 on exact match), max overlapping
+ *  domain-tag weight) × this weight: the strongest single scope signal counts
+ *  once, never stacked. ADDITIVE, zero-boost neutral, never a penalty — an
+ *  absent scope adds exactly 0; a foreign memory ranks equal, not lower. */
+export declare const SCOPE_AFFINITY_WEIGHT = 0.15;
 /** #205 RRF k parameter (1/(k+rank+1)) — matches the pre-#205 hardcoded 60
  *  so the no-config path was byte-identical to 0.15.3. */
 export declare const RRF_K = 60;

package/dist/calibration.js

@@ -24,7 +24,8 @@
  * the removal is never silent.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIAGNOSTIC_ENV_TIER = exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = exports.ENRICH_STRENGTH_DELTA = exports.STAGE_TRUTH_STRENGTH = exports.STAGE_BELIEF_STRENGTH = exports.STAGE_FADING_STRENGTH = exports.STAGE_FADING_DAYS = exports.WEAK_PRIMARY_FLOOR = exports.CORRECTION_REWRITE_MIN_CONFIDENCE = exports.CORRECTION_MIN_SIMILARITY = exports.SUPERSESSION_MIN_SIMILARITY = exports.DEDUP_AUTO_MERGE_THRESHOLD = exports.IMPORTANCE_CEILING = exports.BM25_WEIGHT_DOMAIN = exports.BM25_WEIGHT_PROJECT = exports.BM25_WEIGHT_BODY = exports.BOTH_CHANNEL_BOOST = exports.RRF_VECTOR_WEIGHT = exports.RRF_FTS_WEIGHT = exports.RRF_COMPOSITE_WEIGHT = exports.RRF_K = exports.DOMAIN_AFFINITY_WEIGHT = exports.PROJECT_AFFINITY_WEIGHT = exports.SUPERSEDED_DEMOTION = exports.FRESHNESS_BOOST_WEIGHT = exports.FRESHNESS_BOOST_DAYS = exports.SCORE_RECENCY_WEIGHT = exports.SCORE_CONNECTIONS_WEIGHT = exports.SCORE_STRENGTH_WEIGHT = exports.SCORE_SIMILARITY_WEIGHT = exports.RECALL_USES_AXIS_MAX = exports.RECALL_USES_NORMAL_MAX = exports.RECALL_USES_LOW_MAX = exports.RECALL_RESHOW_TURNS = exports.NOVELTY_FLOOR_SLOTS = exports.RECALL_TITLE_CHARS = exports.RECALL_MIN_PROMPT_CHARS = exports.RECALL_MAX_ITEMS = exports.RECALL_MIN_SIMILARITY = exports.SESSION_INTENT_WEIGHT = exports.COLD_EXPOSURE_SLOTS = exports.RECENT_WINDOW_DAYS = exports.RECENT_LIMIT = exports.SEARCH_LIMIT = exports.PROMOTION_STRENGTH_FLOOR = exports.PROMOTION_RATE = exports.DECAY_HALF_LIFE_DAYS = void 0;
+exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = exports.ENRICH_STRENGTH_DELTA = exports.STAGE_TRUTH_STRENGTH = exports.STAGE_BELIEF_STRENGTH = exports.STAGE_FADING_STRENGTH = exports.STAGE_FADING_DAYS = exports.WEAK_PRIMARY_FLOOR = exports.CORRECTION_REWRITE_MIN_CONFIDENCE = exports.CORRECTION_MIN_SIMILARITY = exports.SUPERSESSION_MIN_SIMILARITY = exports.DEDUP_AUTO_MERGE_THRESHOLD = exports.IMPORTANCE_CEILING = exports.BM25_WEIGHT_DOMAIN = exports.BM25_WEIGHT_PROJECT = exports.BM25_WEIGHT_BODY = exports.BOTH_CHANNEL_BOOST = exports.RRF_VECTOR_WEIGHT = exports.RRF_FTS_WEIGHT = exports.RRF_COMPOSITE_WEIGHT = exports.RRF_K = exports.SCOPE_AFFINITY_WEIGHT = exports.SUPERSEDED_DEMOTION = exports.RECENCY_HEAD_DAYS = exports.RECENCY_HEAD_WEIGHT = exports.RECENCY_HOURLY_DECAY = exports.SCORE_RECENCY_WEIGHT = exports.CONNECTIONS_SATURATION_DEGREE = exports.SCORE_CONNECTIONS_WEIGHT = exports.SCORE_STRENGTH_WEIGHT = exports.SCORE_SIMILARITY_WEIGHT = exports.RECALL_USES_AXIS_MAX = exports.RECALL_USES_NORMAL_MAX = exports.RECALL_USES_LOW_MAX = exports.RECALL_RESHOW_TURNS = exports.NOVELTY_FLOOR_SLOTS = exports.RECALL_TITLE_CHARS = exports.RECALL_MIN_PROMPT_CHARS = exports.RECALL_MAX_ITEMS = exports.RECALL_MIN_SIMILARITY = exports.SESSION_INTENT_WEIGHT = exports.COLD_EXPOSURE_SLOTS = exports.RECENT_WINDOW_DAYS = exports.RECENT_LIMIT = exports.SEARCH_LIMIT = exports.PROMOTION_STRENGTH_FLOOR = exports.PROMOTION_RATE = exports.DECAY_HALF_LIFE_DAYS = void 0;
+exports.DIAGNOSTIC_ENV_TIER = void 0;
 exports.resolveNumCtx = resolveNumCtx;
 exports.resolveOllamaFlushEvery = resolveOllamaFlushEvery;
 exports.resolveOllamaFlushWaitMs = resolveOllamaFlushWaitMs;
@@ -127,8 +128,9 @@ exports.RECALL_USES_NORMAL_MAX = 0.25;
  *  keeps a visible span, not a measured bound. */
 exports.RECALL_USES_AXIS_MAX = 0.30;
 // ---------------------------------------------------------------------------
-// Composite ranking weights (was: score*Weight, freshnessBoost*,
-// supersededDemotion, *AffinityWeight, rrf*)
+// Composite ranking weights (was: score*Weight, supersededDemotion,
+// *AffinityWeight, rrf*; the pre-#430 freshness bonus constants merged into
+// the RECENCY family below)
 // ---------------------------------------------------------------------------
 /** Semantic-similarity share of the composite score. 0.50 (raised from 0.40
  *  in the 0.15.2 rebalance, #191 Phase B): on the production corpus effective
@@ -140,23 +142,58 @@ exports.SCORE_SIMILARITY_WEIGHT = 0.50;
 exports.SCORE_STRENGTH_WEIGHT = 0.20;
 /** Graph-centrality share of the composite score (was 0.20; see above). */
 exports.SCORE_CONNECTIONS_WEIGHT = 0.15;
-/** Slow recency curve share of the composite score (was 0.10; see above). */
+/**
+ * Log-saturation degree K for the connections term (#449 PR E, items 1+3):
+ * the credit is min(1, log1p(k) / log1p(K)) × SCORE_CONNECTIONS_WEIGHT on
+ * the ABSOLUTE undirected-degree scale k — full at k = K, exactly +0 at
+ * k = 0 (unlinked rows score bit-identically to the linear term they
+ * replace). Provenance: p99 of the REAL undirected degree distribution
+ * (read-only audit 2026-09-17 of the canonical wave snapshot, 18,798
+ * memories / 14,600 linked: p50 = 4, p90 = 8, p95 = 9, p99 = 15, p99.9 =
+ * 28.4, max = 40; 135 memories ≥ 16 links = 0.92% of linked) — so the top
+ * ~1% of hubs tie at full credit and everything below differentiates
+ * modestly. Shape grounded in the #449 research base: ACT-R fan saturation
+ * (Anderson & Reder 1999 — activation falls with the LOG of fan), SAM's
+ * saturating returns, cue overload (Watkins & Watkins 1975). Replaces the
+ * candidate-set-relative normalization #449 deleted (k / the per-query max
+ * degree) — a row's score no longer depends on which other rows happened
+ * to match. Alternatives K = 8 (p90 — collapses all p90+ rows to
+ * full credit) and K = 32 (≈p99.9 — leaves the p99 hub at 0.12 of the
+ * term) were tabled in the #449 spec. RELEASE-MANAGED per this module's
+ * evolution contract — overridable only through the configureScoring seam.
+ */
+exports.CONNECTIONS_SATURATION_DEGREE = 16;
+/** Time-curve share of the composite score — the merged curve's blend weight
+ *  AND slow-region amplitude (was 0.10; see above). The four blend weights
+ *  still sum to 1.0; the head amplitude below is a documented overshoot, NOT
+ *  a fifth blend weight (#430). Zero (via the seam) disables the whole term. */
 exports.SCORE_RECENCY_WEIGHT = 0.15;
-/** Fresh-memory window: the additive bonus fades linearly to 0 over this
- *  many days. 7 — nightly capture means 1 day is the floor of "fresh"
- *  (#191 Phase B). */
-exports.FRESHNESS_BOOST_DAYS = 7;
-/** Fresh-memory bonus size at age 0 (#191 Phase B; 0 = disabled via seam). */
-exports.FRESHNESS_BOOST_WEIGHT = 0.15;
+/** Hourly decay of the merged curve's slow region (#430) — promoted from the
+ *  inline literal computeScore carried; half-life ≈ 57.7 days. At and beyond
+ *  RECENCY_HEAD_DAYS the curve is bit-identical to the pre-#430 slow term
+ *  (SCORE_RECENCY_WEIGHT × RECENCY_HOURLY_DECAY^hours). */
+exports.RECENCY_HOURLY_DECAY = 0.9995;
+/** Merged time-curve head amplitude at age 0 (#430) — the pre-#430 slow
+ *  weight 0.15 + fresh bonus 0.15: the freshness job is now the early steep
+ *  part of ONE curve. The head joins value-continuously onto the slow region
+ *  at RECENCY_HEAD_DAYS; its rate is DERIVED from that continuity, never a
+ *  free constant. */
+exports.RECENCY_HEAD_WEIGHT = 0.30;
+/** Join age in days of the merged time curve (#430) — the head window edge,
+ *  carried over from the pre-#430 freshness window. Nightly capture means
+ *  1 day is the floor of "fresh" (#191 Phase B). */
+exports.RECENCY_HEAD_DAYS = 7;
 /** Score multiplier for a memory a later decision superseded (0.15.2; the
  *  belief walk (#393 D) is the primary mechanism — this is the safety net
  *  for rows the walk does not reach). */
 exports.SUPERSEDED_DEMOTION = 0.50;
-/** #203 soft boost on exact project match. ADDITIVE, zero-boost neutral,
- *  never a penalty — a foreign memory ranks equal, not lower. */
-exports.PROJECT_AFFINITY_WEIGHT = 0.15;
-/** #203 soft boost multiplier on max overlapping domain-tag weight. */
-exports.DOMAIN_AFFINITY_WEIGHT = 0.15;
+/** #430 merged scope affinity — ONE term replacing #203's two boosts (the
+ *  project-affinity and domain-affinity constants) at their shared value.
+ *  Boost = max(project-match indicator (1 on exact match), max overlapping
+ *  domain-tag weight) × this weight: the strongest single scope signal counts
+ *  once, never stacked. ADDITIVE, zero-boost neutral, never a penalty — an
+ *  absent scope adds exactly 0; a foreign memory ranks equal, not lower. */
+exports.SCOPE_AFFINITY_WEIGHT = 0.15;
 /** #205 RRF k parameter (1/(k+rank+1)) — matches the pre-#205 hardcoded 60
  *  so the no-config path was byte-identical to 0.15.3. */
 exports.RRF_K = 60;

package/dist/consolidate.js

@@ -1376,6 +1376,7 @@ function stagePromotion(db, dryRun) {
     const demoted = (0, retrieval_js_1.findDemotedIds)(db, rows.map((r) => r.id));
     let promoted = 0;
     let demotedSkipped = 0;
+    let totalGain = 0;
     const writes = [];
     for (const row of rows) {
         const accessCount = row.access_count ?? 0;
@@ -1389,18 +1390,25 @@ function stagePromotion(db, dryRun) {
         }
         // base_strength is NOT NULL after scoring; the `?? 0.5` mirrors
         // stageDecayPrune's defensive default for unscored rows (inserts at 0.5).
-        let strength = row.base_strength ?? 0.5;
+        const startStrength = row.base_strength ?? 0.5;
+        let strength = startStrength;
         for (let i = 0; i < row.delta; i++)
             strength = applyStrengthPromotion(strength);
+        totalGain += strength - startStrength;
         promoted++;
         writes.push({
             id: row.id,
             fields: { base_strength: strength, promotion_last_count: accessCount },
         });
     }
+    // #459: the stage's one-line summary in the shared stage idiom (rows
+    // examined / promoted / total gain, like the supersession summary) — the
+    // stage writes its report in-memory only, so the log line is the soak-time
+    // health signal. Zero examined rows stay silent (the supersession gate).
     if (dryRun) {
-        console.log(`[hicortex] Strength promotion (dry-run): would promote ${promoted} memories ` +
-            `(${demotedSkipped} demotion-set rows advance their baseline only).`);
+        console.log(`[hicortex] Strength promotion (dry-run): ${rows.length} examined, would promote ` +
+            `${promoted} (+${totalGain.toFixed(3)} total strength, ` +
+            `${demotedSkipped} demotion-set rows advance their baseline only).`);
         return { promoted, demoted_skipped: demotedSkipped };
     }
     // One transaction for the whole stage (the stageMemoryCapEviction pattern):
@@ -1411,8 +1419,9 @@ function stagePromotion(db, dryRun) {
             storage.updateMemory(db, w.id, w.fields);
     });
     tx();
-    console.log(`[hicortex] Strength promotion: promoted ${promoted} memories ` +
-        `(${demotedSkipped} demotion-set rows advance their baseline only).`);
+    console.log(`[hicortex] Strength promotion: ${rows.length} examined, promoted ${promoted} ` +
+        `(+${totalGain.toFixed(3)} total strength, ` +
+        `${demotedSkipped} demotion-set rows advance their baseline only).`);
     return { promoted, demoted_skipped: demotedSkipped };
 }
 // ---------------------------------------------------------------------------

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

@@ -70,8 +70,10 @@ export interface StructuralStrengthStats {
  * "if nothing changes" projection), plus the asymptotic floor per memory.
  * Requires `configureDecay` to already reflect the desired half-life (call
  * `runPruneDryRun` first, or `configureDecay` directly, in the same process).
+ * `now` (#458): the instant "now" means — pinned by run-eval's --now for
+ * wall-clock-independent before/after audits; default the live clock.
  */
-export declare function runStructuralStrengthStats(db: Database.Database): StructuralStrengthStats;
+export declare function runStructuralStrengthStats(db: Database.Database, now?: Date): StructuralStrengthStats;
 export interface AdoptionStats {
     totalMemories: number;
     shownCountHistogram: Record<string, number>;
@@ -106,4 +108,4 @@ export interface AdoptionStats {
  * feature's youth as much as its effectiveness. Report callers should state
  * that caveat alongside the numbers, not just the numbers.
  */
-export declare function runAdoptionStats(db: Database.Database): AdoptionStats;
+export declare function runAdoptionStats(db: Database.Database, now?: Date): AdoptionStats;

package/dist/eval/decay-eval.js

@@ -97,12 +97,13 @@ function histogram(values, edges = STRENGTH_BUCKET_EDGES) {
  * "if nothing changes" projection), plus the asymptotic floor per memory.
  * Requires `configureDecay` to already reflect the desired half-life (call
  * `runPruneDryRun` first, or `configureDecay` directly, in the same process).
+ * `now` (#458): the instant "now" means — pinned by run-eval's --now for
+ * wall-clock-independent before/after audits; default the live clock.
  */
-function runStructuralStrengthStats(db) {
+function runStructuralStrengthStats(db, now = new Date()) {
     const rows = db
         .prepare("SELECT id, base_strength, last_accessed FROM memories")
         .all();
-    const now = new Date();
     const nowVals = [];
     const at180 = [];
     const at365 = [];
@@ -147,11 +148,10 @@ function ageBucketLabel(ageDays) {
  * feature's youth as much as its effectiveness. Report callers should state
  * that caveat alongside the numbers, not just the numbers.
  */
-function runAdoptionStats(db) {
+function runAdoptionStats(db, now = new Date()) {
     const rows = db
         .prepare("SELECT id, shown_count, access_count, source_agent, created_at FROM memories")
         .all();
-    const now = new Date();
     const shownVals = [];
     const accessVals = [];
     let totalShown = 0;

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

@@ -0,0 +1,32 @@
+/**
+ * #458 — the shared pinned-clock helper for eval harnesses.
+ *
+ * The recall evals score against wall-clock time (recency + decay terms in
+ * computeScore/effectiveStrength), so a pre-photo and a post-run hours apart
+ * drift even on identical code — PR D evidenced mode-OFF units moving with no
+ * changed code in the path. The fix is a harness-visible pin: every eval that
+ * calls retrieve() (or the decay/adoption stats) accepts a `--now <ISO>` flag
+ * and threads the SAME instant into the retrieve() `now` seam (retrieval.ts —
+ * the injectable-clock idiom of run-deadline.ts), making before/after runs
+ * wall-clock-independent. Default stays the live clock — pinning is opt-in,
+ * for comparability.
+ *
+ * Fail-explicit by design (the repo convention): an invalid pin THROWS with a
+ * clear message rather than silently falling back to the live clock — a run
+ * that believed it was pinned but wasn't would silently reintroduce the drift
+ * class this helper exists to remove.
+ */
+/**
+ * Parse a `--now` flag value into the pinned instant.
+ *
+ * @param raw the raw flag value. undefined or empty/whitespace → null (the
+ *        live clock — the flag was not passed). Anything else must parse as a
+ *        Date; garbage or an invalid instant (e.g. month 13) throws.
+ * @returns the pinned Date, or null for the live clock.
+ */
+export declare function parsePinnedNow(raw: string | undefined): Date | null;
+/**
+ * Human-readable clock mode for report headers / photo JSON: "pinned <ISO>"
+ * or "live" — so artifacts are self-describing about which clock produced them.
+ */
+export declare function clockLabel(now: Date | null): string;

package/dist/eval/eval-clock.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * #458 — the shared pinned-clock helper for eval harnesses.
+ *
+ * The recall evals score against wall-clock time (recency + decay terms in
+ * computeScore/effectiveStrength), so a pre-photo and a post-run hours apart
+ * drift even on identical code — PR D evidenced mode-OFF units moving with no
+ * changed code in the path. The fix is a harness-visible pin: every eval that
+ * calls retrieve() (or the decay/adoption stats) accepts a `--now <ISO>` flag
+ * and threads the SAME instant into the retrieve() `now` seam (retrieval.ts —
+ * the injectable-clock idiom of run-deadline.ts), making before/after runs
+ * wall-clock-independent. Default stays the live clock — pinning is opt-in,
+ * for comparability.
+ *
+ * Fail-explicit by design (the repo convention): an invalid pin THROWS with a
+ * clear message rather than silently falling back to the live clock — a run
+ * that believed it was pinned but wasn't would silently reintroduce the drift
+ * class this helper exists to remove.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePinnedNow = parsePinnedNow;
+exports.clockLabel = clockLabel;
+/**
+ * Parse a `--now` flag value into the pinned instant.
+ *
+ * @param raw the raw flag value. undefined or empty/whitespace → null (the
+ *        live clock — the flag was not passed). Anything else must parse as a
+ *        Date; garbage or an invalid instant (e.g. month 13) throws.
+ * @returns the pinned Date, or null for the live clock.
+ */
+function parsePinnedNow(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return null;
+    const parsed = new Date(raw);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`eval clock: invalid --now value "${raw}" — pass a full ISO 8601 instant ` +
+            `(e.g. 2026-09-17T09:00:00.000Z) or omit the flag to run on the live clock`);
+    }
+    return parsed;
+}
+/**
+ * Human-readable clock mode for report headers / photo JSON: "pinned <ISO>"
+ * or "live" — so artifacts are self-describing about which clock produced them.
+ */
+function clockLabel(now) {
+    return now === null ? "live" : `pinned ${now.toISOString()}`;
+}

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

@@ -8,6 +8,13 @@
  * corrected cosine formula, #145).
  */
 import type Database from "better-sqlite3";
+/**
+ * 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.
+ */
+export declare function seededSample<T>(rows: T[], size: number, seed: number): T[];
 export interface LinkRow {
     source_id: string;
     target_id: string;
@@ -50,8 +57,14 @@ export interface DriftReport {
     maxAbsDrift: number;
     skippedMissingEmbedding: number;
 }
-/** Recompute cosine for a random link sample and compare to stored `strength` (post migration-5 rescale, should track closely). */
-export declare function runDriftSample(db: Database.Database, embeddings: Map<string, Float32Array>, sampleSize?: number): DriftReport;
+/**
+ * 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.
+ */
+export declare function runDriftSample(db: Database.Database, embeddings: Map<string, Float32Array>, sampleSize?: number, seed?: number): DriftReport;
 export interface PartitionStats {
     linkCount: number;
     byRelationship: Record<string, number>;

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");