renor-engine 0.0.0-stage → 1.0.0

package/dist/retrieval/orchestrator.js

@@ -0,0 +1,1086 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_EXPAND_DEFAULT_NOTES = exports.SESSION_EXPAND_REASON = exports.SESSION_EXPAND_RANKED_TOKENS = exports.SESSION_EXPAND_DEFAULT_TOKENS = exports.SESSION_EXPAND_DOCUMENT_MAX_CHUNK_TOKENS = exports.SESSION_EXPAND_MAX_CHUNK_TOKENS = exports.SESSION_DIVERSITY_DEFAULT_CAP = exports.WRITE_CLOCK_TOLERANCE_MS = void 0;
+exports.searchBestFirstEnabled = searchBestFirstEnabled;
+exports.parseQueryDateRef = parseQueryDateRef;
+exports.queryDateRefMs = queryDateRefMs;
+exports.hasNowOverride = hasNowOverride;
+exports.asofPastLike = asofPastLike;
+exports.asofDatedRef = asofDatedRef;
+exports.hasPastIntent = hasPastIntent;
+exports.hasStrictPastIntent = hasStrictPastIntent;
+exports.frontmatterMarksHistorical = frontmatterMarksHistorical;
+exports.sessionDateMs = sessionDateMs;
+exports.resolveSessionDate = resolveSessionDate;
+exports.clampSessionDate = clampSessionDate;
+exports.boundContentDate = boundContentDate;
+exports.createNoteTimeBound = createNoteTimeBound;
+exports.createNoteDater = createNoteDater;
+exports.orderHits = orderHits;
+exports.contentfulText = contentfulText;
+exports.isSpeakerStub = isSpeakerStub;
+exports.resolveSessionDiversityCap = resolveSessionDiversityCap;
+exports.resolveSessionExpand = resolveSessionExpand;
+exports.resolveRankedExpansion = resolveRankedExpansion;
+exports.calibratedModelKey = calibratedModelKey;
+exports.retrieveContext = retrieveContext;
+const ledgerLiveness_1 = require("./ledgerLiveness");
+const ledgerPresentation_1 = require("./ledgerPresentation");
+const ledgerEventTime_1 = require("./ledgerEventTime");
+const dailyEntryTime_1 = require("./dailyEntryTime");
+const dailyNote_1 = require("../memory/dailyNote");
+const readCache_1 = require("../db/readCache");
+const statements_1 = require("../db/statements");
+const semantic_1 = require("./semantic");
+const entityLookup_1 = require("./entityLookup");
+const factsFirst_1 = require("./factsFirst");
+const conversationShape_1 = require("./conversationShape");
+const contextRelevance_1 = require("../mvp/contextRelevance");
+const keyword_1 = require("./keyword");
+const queryHelpers_1 = require("./queryHelpers");
+const ledgerPresentation_2 = require("./ledgerPresentation");
+function envFlagOn(name) {
+    const v = (process.env[name] ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/** Newest-first is product default (S0 KEEP). Opt out with RENOR_NEWEST_FIRST=0/false/off. */
+function newestFirstEnabled() {
+    const v = (process.env.RENOR_NEWEST_FIRST ?? '').trim().toLowerCase();
+    if (v === '0' || v === 'false' || v === 'no' || v === 'off')
+        return false;
+    if (v === '')
+        return true;
+    return envFlagOn('RENOR_NEWEST_FIRST');
+}
+/**
+ * RENOR_SEARCH_BEST_FIRST (default off; `1` / `true` / `yes` / `on` turns it on): search_memory lays its window out best
+ * match first (`rankedBy: "score"`) instead of newest session first. It reaches only the reads that ask for it
+ * (`RetrieveOptions.bestFirst`, which only the search_memory tool sets): get_context, the CLI and RENOR_NEWEST_FIRST are
+ * untouched, and so is which chunks are selected. Every hit keeps its session_date. Measured on the agent-workflow eval.
+ */
+function searchBestFirstEnabled(env = process.env) {
+    const v = (env.RENOR_SEARCH_BEST_FIRST ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/**
+ * Temporal ranking is product default (RenorBench prefer_current/prefer_historical
+ * fix, 2026-09-17). Opt out with RENOR_TEMPORAL_RANKING=0/false/off — a kill
+ * switch that reverts to pre-temporal ordering without a redeploy.
+ */
+function temporalRankingEnabled() {
+    const v = (process.env.RENOR_TEMPORAL_RANKING ?? '').trim().toLowerCase();
+    if (v === '0' || v === 'false' || v === 'no' || v === 'off')
+        return false;
+    if (v === '')
+        return true;
+    return envFlagOn('RENOR_TEMPORAL_RANKING');
+}
+/**
+ * Explicit-date as-of lane (RENOR_TEMPORAL_ASOF, default OFF).
+ * Opt in with RENOR_TEMPORAL_ASOF=1/true/yes/on — a kill switch that restores
+ * pre-lane behavior without a redeploy.
+ */
+function asofEnabled() {
+    return envFlagOn('RENOR_TEMPORAL_ASOF');
+}
+const ASOF_MONTHS = {
+    january: 1, february: 2, march: 3, april: 4, may: 5, june: 6,
+    july: 7, august: 8, september: 9, october: 10, november: 11, december: 12,
+};
+/**
+ * Extract an explicit past-date reference from a natural-language query.
+ * General (gold-blind): matches any month+year, season+year, or bare year —
+ * never fixture-specific dates. Returns undefined when the query carries no
+ * calendar reference or origin marker.
+ */
+function parseQueryDateRef(query) {
+    const q = query.toLowerCase();
+    const monthNames = Object.keys(ASOF_MONTHS).join('|');
+    const my = q.match(new RegExp(`\\b(${monthNames})\\s+(\\d{4})\\b`));
+    if (my)
+        return { year: Number(my[2]), month: ASOF_MONTHS[my[1]], originMarker: false };
+    const season = q.match(/\b(early|mid|late)\s+(\d{4})\b/);
+    if (season) {
+        const month = season[1] === 'early' ? 3 : season[1] === 'mid' ? 6 : 9;
+        return { year: Number(season[2]), month, originMarker: false };
+    }
+    const part = q.match(/\b(end|start|beginning|middle)\s+of\s+(\d{4})\b/);
+    if (part) {
+        const month = part[1] === 'end' ? 12 : part[1] === 'middle' ? 6 : 1;
+        return { year: Number(part[2]), month, originMarker: false };
+    }
+    const iso = q.match(/\b(\d{4})-(\d{2})-(\d{2})\b/);
+    if (iso)
+        return { year: Number(iso[1]), month: Number(iso[2]), originMarker: false };
+    const bareYear = q.match(/\b((?:19|20)\d{2})\b/);
+    if (bareYear)
+        return { year: Number(bareYear[1]), originMarker: false };
+    if (/\boriginal(ly)?\b|\bv1\b|first version/.test(q))
+        return { year: 0, originMarker: true };
+    return undefined;
+}
+/** Resolve a date ref to an end-of-period timestamp for past/future tests. */
+function queryDateRefMs(ref) {
+    if (ref.originMarker)
+        return Number.NEGATIVE_INFINITY; // always "the past"
+    const month = ref.month ?? 12;
+    // End of the referenced month (Date.UTC month is 0-based; day 0 = last of prev).
+    return Date.UTC(ref.year, month, 0, 23, 59, 59);
+}
+function hasNowOverride(query) {
+    return /\b(now|currently|current)\b/i.test(query);
+}
+/**
+ * Past-like via the as-of lane: an explicit past calendar reference (or an
+ * origin marker) with no present-tense override. Independent of the temporal
+ * flag — the lane has its own kill switch.
+ */
+function asofPastLike(query, nowMs) {
+    if (!asofEnabled())
+        return false;
+    const ref = parseQueryDateRef(query);
+    if (!ref)
+        return false;
+    if (hasNowOverride(query))
+        return false;
+    return queryDateRefMs(ref) < nowMs - 86_400_000;
+}
+/** Explicit past-date refs (no origin markers) for the date-overlap boost. */
+function asofDatedRef(query, nowMs) {
+    if (!asofEnabled())
+        return undefined;
+    const ref = parseQueryDateRef(query);
+    if (!ref || ref.originMarker)
+        return undefined;
+    if (hasNowOverride(query))
+        return undefined;
+    if (!(queryDateRefMs(ref) < nowMs - 86_400_000))
+        return undefined;
+    return ref;
+}
+/** Explicit past-intent query: "what was it before / previously / used to be". */
+function hasPastIntent(query) {
+    return /\b(previously|before|used to|former|formerly|earlier|in the past|history)\b/i.test(query);
+}
+/**
+ * STRICT past intent: the temporal word must signal that the QUESTION TARGET is
+ * the past state, not merely appear in a query whose answer is current
+ * ("Which FORMER vegetarian NOW eats fish?" asks for the present).
+ */
+function hasStrictPastIntent(query) {
+    if (!hasPastIntent(query))
+        return false;
+    return !/\b(now|currently|current)\b/i.test(query);
+}
+/**
+ * Corpus-level historical marker in note frontmatter. Deliberately conservative:
+ * only explicit declarations count, so ordinary notes are never demoted.
+ */
+function frontmatterMarksHistorical(frontmatterJson) {
+    if (!frontmatterJson)
+        return false;
+    let fm = {};
+    try {
+        const parsed = JSON.parse(frontmatterJson);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            fm = parsed;
+    }
+    catch {
+        return false;
+    }
+    const historicalFlag = fm['historical'] === true || fm['archived'] === true;
+    const kind = typeof fm['kind'] === 'string' ? fm['kind'].toLowerCase() : '';
+    const type = typeof fm['type'] === 'string' ? fm['type'].toLowerCase() : '';
+    return historicalFlag || kind === 'history' || kind === 'historical' || type === 'history' || type === 'historical';
+}
+function asDateString(value) {
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return value.toISOString();
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const d = new Date(value);
+        if (!Number.isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    return undefined;
+}
+/**
+ * Parse LME `YYYY/MM/DD (Dow) HH:MM` as UTC and ISO date-only strings as UTC midnight.
+ * ISO datetimes require `Z` or an explicit numeric offset; never interpret them in host-local time.
+ */
+function sessionDateMs(value) {
+    if (!value)
+        return Number.NEGATIVE_INFINITY;
+    const official = /^(\d{4})\/(\d{2})\/(\d{2})(?: \([A-Za-z]{3}\))?(?: (\d{2}):(\d{2}))?$/.exec(value);
+    const isoDateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+    const zonedIsoDateTime = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/i.test(value);
+    const iso = official
+        ? `${official[1]}-${official[2]}-${official[3]}T${official[4] ?? '00'}:${official[5] ?? '00'}:00Z`
+        : isoDateOnly
+            ? `${value}T00:00:00Z`
+            : zonedIsoDateTime
+                ? value
+                : undefined;
+    const ms = iso === undefined ? Number.NaN : Date.parse(iso);
+    return Number.isFinite(ms) ? ms : Number.NEGATIVE_INFINITY;
+}
+function resolveSessionDate(frontmatterJson, modifiedAt) {
+    let fm = {};
+    if (frontmatterJson) {
+        try {
+            const parsed = JSON.parse(frontmatterJson);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                fm = parsed;
+        }
+        catch {
+            fm = {};
+        }
+    }
+    const modified = asDateString(modifiedAt);
+    const asserted = asDateString(fm.session_date) ?? asDateString(fm.date);
+    if (asserted === undefined)
+        return modified;
+    return clampSessionDate(asserted, modified);
+}
+// Absorbs coarse kernel file timestamps and 1–2 s filesystem resolution.
+exports.WRITE_CLOCK_TOLERANCE_MS = 2000;
+/** Every content-derived clock, including entry/event overrides, obeys the write-time bound plus clock tolerance. */
+function clampSessionDate(asserted, modifiedAt) {
+    const modified = asDateString(modifiedAt);
+    const modifiedMs = sessionDateMs(modified);
+    // With no trusted timestamp, untrusted content cannot gain newest-session priority.
+    if (!Number.isFinite(modifiedMs))
+        return undefined;
+    if (asserted === undefined)
+        return modified;
+    const assertedMs = sessionDateMs(asserted);
+    // A claim that is not an instant sorts as undated (sessionDateMs is -Infinity), so it is shown as undated, never verbatim.
+    if (!Number.isFinite(assertedMs))
+        return undefined;
+    return assertedMs > modifiedMs + exports.WRITE_CLOCK_TOLERANCE_MS ? modified : asserted;
+}
+/**
+ * Bound a content-derived date that is stored (structured-row valid_from) by the source file's write time, with the same
+ * tolerance as `clampSessionDate`. Day-precision dates stay day-precision, and a clamped one floors to the write day, so
+ * mixed formats still compare consistently. With no trusted write time, or a date that cannot be read as an instant, no
+ * content date is kept (unknown stays unknown).
+ */
+function boundContentDate(asserted, modifiedAt) {
+    if (asserted === null)
+        return null;
+    const modified = asDateString(modifiedAt ?? undefined);
+    if (!Number.isFinite(sessionDateMs(modified)))
+        return null;
+    const trimmed = asserted.trim();
+    // A zone-less date-time reads as UTC, the way every other date in the index does; sessionDateMs refuses it otherwise.
+    const comparable = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/.test(trimmed) ? `${trimmed}Z` : trimmed;
+    if (!Number.isFinite(sessionDateMs(comparable)))
+        return null;
+    if (clampSessionDate(comparable, modified) === comparable)
+        return trimmed;
+    return /^\d{4}-\d{2}-\d{2}$/.test(trimmed) ? modified.slice(0, 10) : modified;
+}
+/** Bound an excerpt clock using its indexed file timestamp, rather than its (possibly historical) front matter. */
+function createNoteTimeBound(db) {
+    const row = onceStatement(db, 'SELECT modified_at FROM notes WHERE path = ?');
+    return (notePath, asserted) => {
+        const note = row().get(notePath);
+        return clampSessionDate(asserted, note?.modified_at);
+    };
+}
+/**
+ * A note's date as retrieval dates the excerpts of it (front-matter session_date, else date, capped at the file's
+ * modification time; absent front matter falls back to that time). For a caller that works on whole notes, such as
+ * evidence hydration, and so needs the date of the note rather than of one excerpt: for a ledger event those differ.
+ * One prepared statement per dater.
+ */
+function createNoteDater(db) {
+    const row = onceStatement(db, 'SELECT modified_at, frontmatter_json FROM notes WHERE path = ?');
+    return notePath => {
+        const note = row().get(notePath);
+        return resolveSessionDate(note?.frontmatter_json, note?.modified_at);
+    };
+}
+/**
+ * Lay hits out by the key they are said to be in order of, so the claim is true of the list and not only of
+ * the code that usually produces it. Stable, and the input is not touched.
+ * `session_date`: newest first; hits on one date, and hits with no date (which come last), by score.
+ * `score`: highest first.
+ */
+function orderHits(hits, by) {
+    if (by === 'score')
+        return [...hits].sort((a, b) => b.score - a.score);
+    // A date is read once for each hit, not once for each comparison the sort makes (a few hundred for a window).
+    return hits.map(hit => ({ hit, ms: sessionDateMs(hit.session_date) })).sort((a, b) => {
+        const delta = b.ms - a.ms;
+        return delta !== 0 && !Number.isNaN(delta) ? delta : b.hit.score - a.hit.score; // NaN: both undated
+    }).map(entry => entry.hit);
+}
+/**
+ * The visible text of each hit text the current read has met. A read asks it of the same text several times: whether the
+ * hit is a stub, the key that drops a repeat, the boost for a hit with something to say, and again for a hit the session
+ * expansion brings back. The text is the whole input, so the answer is kept until the read ends (`retrieveContext`
+ * forgets it as it ends and again as the next one starts, which also covers a read that failed) and no longer: nothing
+ * outlives the read it was worked out for. A text over the size limit, or a read that meets more texts than the count
+ * limit, is simply worked out again.
+ */
+const CONTENTFUL_HELD_MAX = 256;
+const CONTENTFUL_HELD_MAX_CHARS = 8 * 1024;
+const contentfulHeld = new Map();
+/** Visible text after markdown/speaker-label strip — used to bury transcript stubs. */
+function contentfulText(text) {
+    const raw = text ?? '';
+    const held = contentfulHeld.get(raw);
+    if (held !== undefined)
+        return held;
+    const visible = stripToContentful(raw);
+    if (raw.length <= CONTENTFUL_HELD_MAX_CHARS) {
+        if (contentfulHeld.size >= CONTENTFUL_HELD_MAX)
+            contentfulHeld.delete(contentfulHeld.keys().next().value);
+        contentfulHeld.set(raw, visible);
+    }
+    return visible;
+}
+function stripToContentful(raw) {
+    // Each pass below but the heading rule can only change a text that holds the character it looks for, and most hit texts hold
+    // few of them, so a pass whose character is absent is not run (a replace that finds nothing still reads the whole text).
+    let t = raw.includes('\r') ? raw.replace(/\r/g, '') : raw;
+    if (t.includes('*'))
+        t = t.replace(/\*+/g, '');
+    // Whole ATX heading line is structure, not answer text (chunker prefixes
+    // section buffers with the heading — Kimi R-O1).
+    t = t.replace(/^#{1,6}\s+.*$/gm, '');
+    // Speaker-only lines: **Rowan:** / Rowan: / **Gabriel:** / 李雷： — any script and
+    // either colon. Cue detection was Latin-1 only (`[A-Za-zÀ-ÿ]`), so labels in
+    // non-Latin scripts were counted as content by contentfulText, which feeds both
+    // contentBoost and dedupeHits.
+    if (t.includes(':') || t.includes('：'))
+        t = t.replace(/^[\s>*-]*[\p{L}\p{M}][\p{L}\p{M} .'-]{0,40}[:：]\s*$/gmu, '');
+    if (t.includes('\n\n'))
+        t = t.replace(/\n{2,}/g, '\n');
+    return t.trim();
+}
+function isSpeakerStub(text) {
+    const raw = (text ?? '').replace(/\r/g, '').trim();
+    // Whole chunk is only a speaker cue (optional markdown/list markers) — any
+    // script, either colon.
+    if (/^(?:[\s>*-]*\*?\*?[\p{L}\p{M}][\p{L}\p{M} .'-]{0,40}\*?\*?[:：]\s*)+$/u.test(raw) && contentfulText(raw).length === 0) {
+        return true;
+    }
+    return contentfulText(raw).length === 0;
+}
+function contentBoost(text) {
+    const n = contentfulText(text).length;
+    if (n < 40)
+        return 0;
+    return Math.min(0.12, (n / 800) * 0.12);
+}
+/** Two hits of one note whose visible text opens the same way are one hit: the key dedupeHits keeps the first of. */
+function hitKey(h) {
+    return `${h.notePath}\0${contentfulText(h.text).slice(0, 80)}`;
+}
+function dedupeHits(hits) {
+    const seen = new Set();
+    const out = [];
+    for (const h of hits) {
+        const key = hitKey(h);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(h);
+    }
+    return out;
+}
+/** The search cap when RENOR_SESSION_DIVERSITY is unset or empty; get_context uses 0. */
+exports.SESSION_DIVERSITY_DEFAULT_CAP = 2;
+/**
+ * RENOR_SESSION_DIVERSITY (search default 2, get_context default 0; explicit 0 turns it off): max chunks per note in the top-K
+ * window. Capped chunks do not vanish — every hit in the candidate pool is
+ * scanned, so chunks of notes that have not reached the cap still take their
+ * slots in rank order, and distinct notes that outrank the surplus are kept.
+ *
+ * MEASURED LIMIT, stated because the previous revision of this comment claimed
+ * the opposite ("so the window keeps topK entries"): the window is NOT
+ * guaranteed to be full. When the candidate pool is concentrated in fewer than
+ * topK/cap distinct notes there is nothing else to promote — every surplus hit
+ * belongs to a note already at its cap by construction — so the window shrinks
+ * below topK. That is exactly the chunk-heavy corpus this flag targets:
+ * measured on a 4-notes x 5-chunks pool, topK=10, cap=1 -> 4 slots, cap=2 -> 8
+ * slots, and on the 90-case screen the delivered context fell 3,791 -> 2,221
+ * tokens (-41.4%). A true backfill would have to retrieve BEYOND the current
+ * candidate pool, which this function cannot do and does not claim to.
+ *
+ * THE CAP IS AUTHORITATIVE WHENEVER IT IS ARMED, including when the candidate pool is no
+ * deeper than the window. This function used to early-return on `hits.length <= topK`,
+ * which skipped the cap entirely for a small or single-note vault (measured: cap=1 over ten
+ * same-note chunks returned all ten, `kept=10`, while the headline above promises a maximum
+ * per note). The window then shrinks rather than silently ignoring the setting, which is the
+ * same trade the concentrated-pool case above already makes: the cap is not a backfill
+ * guarantee, but it is not optional either. Only `cap < 1` (0, or a value that names no cap)
+ * short-circuits, so the off path is untouched.
+ *
+ * Rationale (measured on full500-count-contract results.jsonl, 2026-09-28):
+ * the top-20 window carries a mean 9.4 repeated-note slots (all different
+ * chunks of the same note — dedupeHits only matches identical prefixes), and
+ * cap=2 frees 6.9 slots on 453/500 cases.
+ *
+ * DEFAULT 2 since 2026-10-07 (the captain's call), from the held-out answer confirmation of 2026-10-06: GLM-5.3-Flash
+ * reading and gemma4:31b judging through the shipped CLI, the 395 held-out LongMemEval-S questions the base answered.
+ * No cap got 340 right and a cap of 2 got 350 (16 wins, 6 losses, +2.5 points, interval +0.3 to +4.8, p = 0.0525),
+ * with 6.3% fewer context tokens and no category worse by more than 2 questions. A cap of 1 looked best on dev and lost
+ * evidence on held-out, which is why 1 is not the default. The record: docs/evals/results/SESSION-DIVERSITY-DEFAULT-20261007.md.
+ *
+ * WHAT THE CAP COUNTS, because the evidence covers one kind of note. The cap is about the chunks of one conversation or
+ * one document crowding out the others, so it counts only those. Three kinds of hit share a note path without being parts
+ * of one thing said, and are left alone (not counted, not cut): a fact row (a negative chunkId, no chunk of a note; the
+ * facts-first rows all carry the pseudo-path `_mcp_`), a ledger event (every fact-mode save is an event of the one ledger
+ * file) and an entry of a daily log (one file per day, one memory per entry: dailyEntryTime.ts). Counted by path they
+ * were capped at `cap` each, and a saved statement stopped coming back from search_memory once `cap` others of the
+ * ledger, or of its day, outranked it. A benchmark vault holds none of the three, so what was measured is unchanged;
+ * docs/evals/results/SESSION-DIVERSITY-DEFAULT-20261007.md has the tests that showed it.
+ *
+ * Unset (or empty) is the default. 0, or a value that names no cap (junk, negative, below 1), is off, and off is the
+ * window as it was before the default existed, byte for byte. Searches default to 2 (search_memory, the CLI search and
+ * the older API/MCP search servers). get_context passes noteCapWhenUnset=0, preserving its existing window and budget
+ * assembly. An explicit environment value still wins on every read, as it did before this default changed.
+ */
+function resolveSessionDiversityCap(env = process.env, unsetCap = exports.SESSION_DIVERSITY_DEFAULT_CAP) {
+    const rawCap = (env.RENOR_SESSION_DIVERSITY ?? '').trim();
+    const cap = rawCap === '' ? unsetCap : Number(rawCap);
+    if (!Number.isFinite(cap) || cap < 1)
+        return 0; // off: 0, or a value that names no cap
+    return Math.floor(cap);
+}
+/**
+ * Whether a hit counts toward its note's cap: a chunk of a conversation or a document. A fact row (a negative chunkId)
+ * is no chunk of a note and a ledger event is no session's chunk (the two tests sessionExpansionHits ranks notes by),
+ * and an entry of a daily log is a memory of its own.
+ */
+function countsTowardNoteCap(h) {
+    return h.chunkId > 0 && (0, ledgerLiveness_1.ledgerEventIds)(h).length === 0 && (0, dailyNote_1.dailyNoteDayName)(h.notePath) === null;
+}
+function applySessionDiversity(hits, cap, topK) {
+    // `cap < 1` is the flag-OFF short-circuit and must stay: 0 restores the window exactly as it was
+    // before the default existed. The former `|| hits.length <= topK` here was a bypass, not an optimization — it
+    // skipped the configured cap entirely whenever the pool was no deeper than the window.
+    if (cap < 1)
+        return hits;
+    const kept = [];
+    const counts = new Map();
+    // Single pass over the WHOLE pool, in rank order: a hit is kept while its note
+    // has fewer than `cap` slots already taken (a hit that is no chunk of a note is kept and takes none).
+    // This is the entire mechanism —
+    // the "backfill" loop that used to follow it was dead code (every item it
+    // could reach came from a note already at cap, and counts never decrease, so
+    // its `continue` was always taken and it never appended anything). It is
+    // deleted rather than kept, because a loop that cannot run cannot be a
+    // guarantee, and the docstring above used to rest on it.
+    for (const h of hits) {
+        if (!countsTowardNoteCap(h)) {
+            kept.push(h);
+            continue;
+        }
+        const n = counts.get(h.notePath) ?? 0;
+        if (n < cap) {
+            counts.set(h.notePath, n + 1);
+            kept.push(h);
+        }
+    }
+    return kept;
+}
+/**
+ * RENOR_SESSION_EXPAND (default 5 notes; 0 turns it off): add the short statements of the notes retrieval already found.
+ *
+ * What it fixes, measured (PageIndex scout, 2026-10-03, on the frozen product-path top-20 of LongMemEval-S): the
+ * window holds every gold SESSION for 98.3% of the 470 answerable questions but every evidence TURN for only 79.4%.
+ * The miss is inside a session it found: the note comes back through several of its chunks, but not through the one
+ * short sentence ("by the way, I ...") that answers the question, because that sentence is not what the query is
+ * about. Adding the short turns of the five best sessions to the top-20 delivered every evidence turn for 93.6%, with
+ * no model call. Measured through the shipped CLI with this code (results/SESSION-EXPAND-DELIVERY-20261003.md): off
+ * 373/470 = 79.4%; five notes 440/470 = 93.6% unbounded and 439/470 = 93.4% under the default 2,000-token budget, at
+ * 3,430 mean / 5,162 p95 tokens of client context against 1,978 / 4,033 off.
+ *
+ * What it does: rank the notes in the window by their best hit, take the best `RENOR_SESSION_EXPAND` of them, and add
+ * their statements that the window does not already hold, best note first and each note in document order, while
+ * they fit in `RENOR_SESSION_EXPAND_TOKENS` (default SESSION_EXPAND_DEFAULT_TOKENS). The expansion is the longest run
+ * of that list that fits: it stops at the first statement that does not. Two bounded queries over `chunks`, no embedding and no
+ * model call.
+ *
+ *  - A statement is a whole section (one chunk under a unique heading path), skipped whole when over its limit,
+ *    never cut. Conversation-shaped notes use `RENOR_SESSION_EXPAND_STATEMENT_TOKENS` (default 120); every other
+ *    note keeps the former 200-token limit (`RENOR_SESSION_EXPAND_DOCUMENT_STATEMENT_TOKENS`). The shape comes
+ *    only from the note's own headings (conversationShape.ts), never benchmark labels or front matter.
+ *    The document screen found that applying 100 to all notes lost 186 delivered answer statements. Keeping
+ *    documents at 200 preserved every document reply and 96.2% of the conversation token saving (11.7% overall).
+ *    See docs/evals/results/SESSION-EXPAND-STATEMENT-LIMIT-20261007.md for the measurement and its limits.
+ *  - Role-agnostic within a conversation: both user and assistant statements qualify, regardless of speaker.
+ *  - A union, never a replacement: the window is returned as it was, and the expansion only adds. Replacing the
+ *    window with the expansion lost the questions whose evidence is what the assistant said (56/56 -> 5/56).
+ *  - An added hit was not matched by the query, and says so: `reason` 'session-expand', `score` 0 and no `similarity`
+ *    (get_context's relevance signal stays the window's). get_context surfaces that as a first-class field on the
+ *    item it lists (`matched: false`, mvp/agentMemory.ts normalizeMemory); the search lane is unchanged. It carries its
+ *    note's date, so the layout (`orderHits`) places it with its session, after the chunks that matched; by score it
+ *    comes after the whole window.
+ *  - It never adds a note: every added hit belongs to a note the window holds, so a read scoped by note path keeps or
+ *    drops it with that note. And it never adds a ledger event: the ledger is no session, its events are judged for
+ *    liveness and scope one by one, and an event added here would skip both (a superseded event would come back as
+ *    live). An event in the window does not rank the ledger either.
+ *
+ * RANKED (default, for an embedding model with a calibrated bar; RENOR_SESSION_EXPAND_RANK=0 restores the above): the
+ * statements of EVERY note in the window compete by their cosine to the query (one `VectorIndex.search` among their
+ * chunk ids: no embedding, no model call), and the best are added while they fit in `SESSION_EXPAND_RANKED_TOKENS`, each
+ * note's laid out in document order. The statement limits are the former expansion's (120 for a conversation, 200 for a
+ * document), and only the cosine ranks: nothing the note's author writes (a heading, a speaker label) adds to it. Why:
+ * the expansion above spends its budget on every short statement of five notes whatever the query, and the gold
+ * evidence of a multi-session question sits in a session ranked below five. Measured on the held-out 400 in
+ * docs/evals/results/RANKED-EXPANSION-20261011.md. Armed only for a calibrated model because it relies on the
+ * cosine's order being meaningful: the lexical eval stub and an unmeasured model keep the expansion above, byte for byte.
+ * An OpenAI-compatible endpoint that returns a calibrated model's vectors is armed by the operator's declaration
+ * (RENOR_EMBEDDING_SERVED_BY, see calibratedModelKey); docs/evals/results/EXPANSION-PATH-ALIGNMENT-20261018.md.
+ *
+ * Unset is five notes. 0, a value that names no note, a budget that allows nothing or both statement limits admitting
+ * nothing is off, and off costs nothing: no statement is prepared and the result is what it was before the expansion
+ * existed, byte for byte. The budget bounds what is added; nothing in the window is cut to make room. A caller that
+ * cuts the result by position cuts what the layout puts last: by score, the added hits; newest first, the oldest
+ * session's hits, matched or added. Measured with the benchmark client's 6,000-token cap: five notes lost no question
+ * at any budget, seven notes unbounded lost 3 whose evidence the window had delivered. And a caller with a small
+ * budget of its own spends it on added hits too, so it must not let them take a match's room: get_context (800 tokens
+ * by default) gives them only what its facts and its matches leave (mvp/agentMemory.ts applyBudget).
+ */
+/**
+ * The longest statement of a conversation-shaped note the expansion adds.
+ *
+ * 120, not 100: the evidence turns of the questions that still miss at 100 sit just over it. Measured on LongMemEval-S
+ * 2026-10-10 (cache-only retrieval ablation, practice split and held-out 400): the practice split's remaining
+ * multi-session misses hold statements of 101-117 tokens, and every one of them is under 120. The held-out curve at the
+ * shipped defaults, 376 answerable questions: a cap of 100 delivers every gold evidence turn on 341 questions in 2,822
+ * mean client tokens, 120 on 349 in 2,921 (+8 questions, +3.5%), 150 on 351 in 3,047 (+10, +8.0%); the 120-to-150 step is
+ * 2 questions inside the noise (exact McNemar p = 0.500). The 2026-10-07 record
+ * (docs/evals/results/SESSION-EXPAND-STATEMENT-LIMIT-20261007.md) adds that the answer-level effect of the limit is flat
+ * from 120 to 200 while the delivered context keeps growing, so 120 is the knee of the curve. Documents keep 200: their
+ * statements were measured separately and a flat 100 there lost 186 delivered answer statements.
+ */
+exports.SESSION_EXPAND_MAX_CHUNK_TOKENS = 120;
+/** The longest statement of a note that is not shaped like a conversation (a document): the limit before the cap. */
+exports.SESSION_EXPAND_DOCUMENT_MAX_CHUNK_TOKENS = 200;
+exports.SESSION_EXPAND_DEFAULT_TOKENS = 2000;
+/** The ranked expansion's budget. Its statement limits are the former expansion's (120 for a conversation, 200 for a document). */
+exports.SESSION_EXPAND_RANKED_TOKENS = 1300;
+/** The `reason` of a hit the expansion added: no word of the query matched it, and it has no score of its own. */
+exports.SESSION_EXPAND_REASON = 'session-expand';
+/** How many of the window's best notes are expanded when RENOR_SESSION_EXPAND is unset. */
+exports.SESSION_EXPAND_DEFAULT_NOTES = 5;
+function resolveSessionExpand(env = process.env) {
+    const rawNotes = (env.RENOR_SESSION_EXPAND ?? '').trim();
+    const notes = rawNotes === '' ? exports.SESSION_EXPAND_DEFAULT_NOTES : Number(rawNotes);
+    if (!Number.isFinite(notes) || notes < 1)
+        return null; // off: 0, or a value that names no note
+    const rawBudget = (env.RENOR_SESSION_EXPAND_TOKENS ?? '').trim();
+    const budget = rawBudget === '' ? exports.SESSION_EXPAND_DEFAULT_TOKENS : Number(rawBudget);
+    if (!Number.isFinite(budget) || budget < 1)
+        return null; // a budget that allows nothing adds nothing
+    // Each class has its own limit; one that admits no statement adds nothing for that class, both of them add nothing at all.
+    const limit = (raw, fallback) => {
+        const text = (raw ?? '').trim();
+        const value = text === '' ? fallback : Number(text);
+        return Number.isFinite(value) && value >= 1 ? Math.floor(value) : 0;
+    };
+    const statementTokens = limit(env.RENOR_SESSION_EXPAND_STATEMENT_TOKENS, exports.SESSION_EXPAND_MAX_CHUNK_TOKENS);
+    const documentStatementTokens = limit(env.RENOR_SESSION_EXPAND_DOCUMENT_STATEMENT_TOKENS, exports.SESSION_EXPAND_DOCUMENT_MAX_CHUNK_TOKENS);
+    if (statementTokens === 0 && documentStatementTokens === 0)
+        return null;
+    return { notes: Math.floor(notes), tokenBudget: Math.floor(budget), statementTokens, documentStatementTokens };
+}
+function resolveRankedExpansion(env = process.env) {
+    if ((env.RENOR_SESSION_EXPAND_RANK ?? '').trim() === '0')
+        return null;
+    const legacy = resolveSessionExpand(env);
+    if (!legacy)
+        return null;
+    const rawNotes = (env.RENOR_SESSION_EXPAND ?? '').trim();
+    const rawBudget = (env.RENOR_SESSION_EXPAND_TOKENS ?? '').trim();
+    return {
+        notes: rawNotes === '' ? Number.POSITIVE_INFINITY : legacy.notes,
+        tokenBudget: rawBudget === '' ? exports.SESSION_EXPAND_RANKED_TOKENS : legacy.tokenBudget,
+        statementTokens: legacy.statementTokens,
+        documentStatementTokens: legacy.documentStatementTokens,
+    };
+}
+/**
+ * The calibrated key (CALIBRATED_BARS) of the embedding model behind a provider, or null when there is none.
+ *
+ * A key names the provider that made the vectors. An OpenAI-compatible endpoint that returns Vertex's gemini-embedding-001
+ * vectors (the benchmark's embedding cache proxy replays them) declares itself `openai:gemini-embedding-001:768`, which is
+ * not calibrated, so it keeps the former expansion where a hosted workspace, which calls Vertex itself, runs the ranked one.
+ * RENOR_EMBEDDING_SERVED_BY (default unset) is the operator's declaration of whose vectors the endpoint returns: `vertex`
+ * there counts the provider as the calibrated model, but only when the key that makes (the declared kind with the provider's
+ * own model and dimensions) is in CALIBRATED_BARS. Any other value, model or size changes nothing, and the declaration is the
+ * operator's word: nothing here checks the vectors. Read here and nowhere else; a hosted workspace is unaffected.
+ */
+function calibratedModelKey(identity, dimensions, env = process.env) {
+    if (!identity)
+        return null;
+    const own = (0, contextRelevance_1.embeddingModelKey)(identity.kind, identity.model, dimensions);
+    if (own in contextRelevance_1.CALIBRATED_BARS)
+        return own;
+    const servedBy = (env.RENOR_EMBEDDING_SERVED_BY ?? '').trim().toLowerCase();
+    if (servedBy === '')
+        return null;
+    const declared = (0, contextRelevance_1.embeddingModelKey)(servedBy, identity.model, dimensions);
+    return declared in contextRelevance_1.CALIBRATED_BARS ? declared : null;
+}
+function sessionExpansionHits(db, window, expansion, ranking) {
+    // A note is ranked by its best chunk in the window. A fact row (chunkId < 0) is no chunk of a note, and a ledger
+    // event is no session's chunk: neither ranks a note.
+    const best = new Map();
+    for (const hit of window) {
+        if (hit.chunkId > 0 && (0, ledgerLiveness_1.ledgerEventIds)(hit).length === 0 && hit.score > (best.get(hit.notePath)?.score ?? Number.NEGATIVE_INFINITY)) {
+            best.set(hit.notePath, hit);
+        }
+    }
+    const ranked = ranking?.ranked;
+    if (ranked)
+        expansion = { ...expansion, ...ranked };
+    const notes = [...best.values()].sort((a, b) => b.score - a.score).slice(0, expansion.notes);
+    if (notes.length === 0)
+        return [];
+    const rank = new Map(notes.map((hit, i) => [hit.notePath, i]));
+    // A statement is a whole section: a chunk that no other chunk of its note shares a heading path with. The chunker
+    // cuts a section of over 400 tokens into paragraphs under one heading path, and such a piece is a fragment of a long
+    // answer, not something said in a few words.
+    const paths = notes.map(hit => hit.notePath);
+    // What a note is shaped like decides its limit: every heading path of its chunks, not only the statements'.
+    const headings = new Map();
+    for (const row of (0, statements_1.listStatement)(db, paths.length, marks => `SELECT note_path AS notePath, heading_path AS headingPath FROM chunks WHERE note_path IN (${marks})`).all(...(0, statements_1.paddedList)(paths))) {
+        const list = headings.get(row.notePath) ?? [];
+        list.push(row.headingPath);
+        headings.set(row.notePath, list);
+    }
+    const limitOf = new Map(paths.map(notePath => [
+        notePath,
+        (0, conversationShape_1.isConversationShaped)(headings.get(notePath) ?? []) ? expansion.statementTokens : expansion.documentStatementTokens,
+    ]));
+    const rows = db.prepare(`SELECT chunkId, notePath, headingPath, text, tokens FROM (
+       SELECT id AS chunkId, note_path AS notePath, heading_path AS headingPath, text, token_count AS tokens,
+         start_line AS startLine, COUNT(*) OVER (PARTITION BY note_path, heading_path) AS parts
+       FROM chunks WHERE note_path IN (${paths.map(() => '?').join(',')})
+     ) WHERE parts = 1 AND tokens <= ?
+     ORDER BY startLine, chunkId`).all(...paths, Math.max(expansion.statementTokens, expansion.documentStatementTokens)).filter(row => row.tokens <= limitOf.get(row.notePath))
+        .sort((a, b) => rank.get(a.notePath) - rank.get(b.notePath)); // stable: document order inside a note
+    const inWindow = new Set(window.map(hit => hit.chunkId));
+    const seen = new Set(window.map(hitKey));
+    const added = [];
+    let spent = 0;
+    let candidates = rows;
+    if (ranking) {
+        const eligible = rows.filter(row => !inWindow.has(row.chunkId) && !isSpeakerStub(row.text) && (0, ledgerLiveness_1.ledgerEventIds)(row).length === 0 && !seen.has(hitKey(row)));
+        const cosine = new Map(ranking.vectorIndex.search(ranking.queryVector, Math.max(1, eligible.length), eligible.map(r => r.chunkId)).map(h => [h.chunkId, h.score]));
+        const picked = [];
+        let room = expansion.tokenBudget;
+        // Cosine and nothing else: a heading, a speaker label or a front-matter field is text the note's author wrote, and
+        // a ranking signal taken from it would be one more way for a planted note to steer what the expansion delivers.
+        const cosineOf = (row) => cosine.get(row.chunkId) ?? -1;
+        for (const row of [...eligible].sort((a, b) => cosineOf(b) - cosineOf(a) || a.chunkId - b.chunkId)) {
+            if (row.tokens > room)
+                break;
+            room -= row.tokens;
+            picked.push(row);
+        }
+        const chosen = new Set(picked.map(r => r.chunkId));
+        candidates = rows.filter(r => chosen.has(r.chunkId)); // note rank, then document order, as the unranked expansion lays them out
+    }
+    for (const row of candidates) {
+        // A ledger event is never added: liveness (closed events) and scope (per event) are judged on the window only.
+        if (inWindow.has(row.chunkId) || isSpeakerStub(row.text) || (0, ledgerLiveness_1.ledgerEventIds)(row).length > 0)
+            continue;
+        const key = hitKey(row);
+        if (seen.has(key))
+            continue;
+        if (spent + row.tokens > expansion.tokenBudget)
+            break;
+        spent += row.tokens;
+        seen.add(key);
+        const sessionDate = best.get(row.notePath).session_date;
+        added.push({
+            notePath: row.notePath,
+            chunkId: row.chunkId,
+            headingPath: row.headingPath,
+            text: row.text,
+            score: 0,
+            reason: exports.SESSION_EXPAND_REASON,
+            ...(sessionDate ? { session_date: sessionDate } : {}),
+        });
+    }
+    return added;
+}
+/** Prepares `sql` on first use, and once per connection: for lookups that run once per hit, and on every read. */
+function onceStatement(db, sql) {
+    let statement;
+    return () => (statement ??= (0, statements_1.prepareOnce)(db, sql));
+}
+function getEntityIdsForNotes(db, notePaths) {
+    if (notePaths.length === 0)
+        return [];
+    return (0, statements_1.listStatement)(db, notePaths.length, marks => `SELECT id, source_note as notePath FROM entities WHERE source_note IN (${marks})`).all(...(0, statements_1.paddedList)(notePaths)).map(r => ({ id: r.id, notePath: r.notePath }));
+}
+function getRelatedEntityIds(db, entityIds) {
+    if (entityIds.length === 0)
+        return [];
+    const ids = entityIds.map(e => e.id);
+    const rows = (0, statements_1.listStatement)(db, ids.length, marks => `SELECT DISTINCT target_entity_id as id FROM relations WHERE source_entity_id IN (${marks})
+     UNION
+     SELECT DISTINCT source_entity_id as id FROM relations WHERE target_entity_id IN (${marks})`).all(...(0, statements_1.paddedList)(ids), ...(0, statements_1.paddedList)(ids));
+    const existing = new Set(ids);
+    return rows.map(r => r.id).filter(id => !existing.has(id));
+}
+function getNotesForEntities(db, entityIds) {
+    if (entityIds.length === 0)
+        return [];
+    return (0, statements_1.listStatement)(db, entityIds.length, marks => `SELECT DISTINCT source_note FROM entities WHERE id IN (${marks})`).all(...(0, statements_1.paddedList)(entityIds)).map(r => r.source_note);
+}
+function getBestChunksForNotes(db, notePaths, limit, keep) {
+    if (notePaths.length === 0)
+        return [];
+    // The longest chunk of each note, the first of equally long ones; the notes in path order. Neither is left to row
+    // order, which follows the order indexing wrote the notes in.
+    const chunks = (0, statements_1.listStatement)(db, notePaths.length, marks => `SELECT chunkId, notePath, headingPath, text, startLine, endLine FROM (
+       SELECT id as chunkId, note_path as notePath, heading_path as headingPath, text, start_line as startLine, end_line as endLine,
+         ROW_NUMBER() OVER (PARTITION BY note_path ORDER BY token_count DESC, id) as rn
+       FROM chunks WHERE note_path IN (${marks})
+     ) WHERE rn = 1
+     ORDER BY notePath
+     LIMIT ?`).all(...(0, statements_1.paddedList)(notePaths), keep ? -1 : limit);
+    // Given `keep`, the chunks it shows are judged before the limit (LIMIT -1 is none).
+    return keep ? chunks.filter(keep).slice(0, limit) : chunks;
+}
+async function retrieveContext(db, vectorIndex, provider, query, topK = 20, priorityPaths = [], clock = {}, opts = {}) {
+    contentfulHeld.clear(); // what another read worked out is not this read's
+    const factHits = (0, factsFirst_1.factsFirstHits)(db, query, Math.min(3, topK), opts.scope?.shows);
+    const queryProbe = opts.probe ?? {}; // the query vector, for the expansion's ranking
+    const candidateLimit = Math.min(40, topK * 4);
+    const semanticHits = vectorIndex && provider
+        ? await (0, semantic_1.semanticSearch)(db, vectorIndex, provider, query, candidateLimit, queryProbe, opts.scope)
+        : (() => {
+            const match = (0, queryHelpers_1.quoteFtsQuery)(query);
+            if (!match)
+                return [];
+            // No embedding provider: the keyword index stands in for the semantic lane. Its rows are judged (ledger
+            // header and events the words are not in, then the scope) before the page is cut, as every keyword reader does.
+            return (0, queryHelpers_1.shownPage)(rows => (0, keyword_1.keywordSearch)(db, match, rows), rows => {
+                const live = (0, ledgerPresentation_2.keywordLedgerHits)(rows.map(r => ({ ...r, score: 1 / (1 + Math.abs(r.score)) })), opts.isLedgerNote, query);
+                return opts.scope ? live.filter(hit => opts.scope.shows(hit)) : live;
+            }, candidateLimit);
+        })();
+    // The window is ranked without waiting for anything, so it is read in one transaction (inReadSnapshot).
+    const window = (0, readCache_1.inReadSnapshot)(db, () => rankWindow({ db, query, topK, priorityPaths, clock, opts, factHits, semanticHits }));
+    return finishContext({ db, vectorIndex, provider, query, queryProbe, window, bestFirst: opts.bestFirst === true });
+}
+/** The window of hits of a read: scored, with the graph of its notes, their facts and dates, live and capped per note. Waits for nothing. */
+function rankWindow(read) {
+    const { db, query, topK, priorityPaths, clock, opts, factHits, semanticHits } = read;
+    // Raw cosines, kept only for a caller that asked to see them (get_context's relevance signal).
+    const cosineByChunk = opts.probe ? new Map(semanticHits.map(h => [h.chunkId, h.score])) : null;
+    const entityHit = (0, entityLookup_1.lookupEntity)(db, query.trim());
+    // As-of lane pre-compute: explicit past-date queries must not receive the
+    // "now" recency boost below — the newest note describes the current world,
+    // not the asked-about past. Gated by its own kill switch.
+    const asofPreNowMs = clock.nowMs ?? Date.now();
+    const asofPrePast = asofPastLike(query, asofPreNowMs);
+    // Prepared once per call, not once per hit: each of these runs for every semantic hit (dozens per call).
+    const noteRowStmt = onceStatement(db, 'SELECT modified_at, frontmatter_json FROM notes WHERE path = ?');
+    const ownFactsStmt = onceStatement(db, 'SELECT predicate, object_text, valid_to FROM facts WHERE subject_entity_id = ?');
+    const noteRows = new Map();
+    const noteRow = (notePath) => {
+        if (!noteRows.has(notePath))
+            noteRows.set(notePath, noteRowStmt().get(notePath));
+        return noteRows.get(notePath);
+    };
+    const ownFactRows = new Map();
+    const scored = semanticHits.map(h => {
+        let score = h.score;
+        let reason = 'semantic';
+        if (isSpeakerStub(h.text)) {
+            score -= 0.5;
+            reason = 'semantic+stub';
+        }
+        else {
+            const boost = contentBoost(h.text);
+            if (boost > 0) {
+                score += boost;
+                reason += '+content';
+            }
+        }
+        if (priorityPaths.some(p => h.notePath.includes('/' + p) || h.notePath.startsWith(p))) {
+            score += 0.1;
+            reason += '+priority';
+        }
+        if (entityHit?.sourceNote === h.notePath) {
+            score += 0.2;
+            reason += '+entity';
+        }
+        // Time-decay recency: +0.1 for today, linearly decaying to 0 over 30 days.
+        // Skipped for explicit past-date (as-of) queries: recency answers "now",
+        // the as-of query asks about "then".
+        const row = noteRow(h.notePath);
+        const session_date = resolveSessionDate(row?.frontmatter_json, row?.modified_at);
+        if (row && !asofPrePast) {
+            const daysSince = ((clock.nowMs ?? Date.now()) - new Date(row.modified_at).getTime()) / 86400000;
+            const recencyBoost = Math.max(0, 0.1 * (1 - daysSince / 30));
+            if (recencyBoost > 0.001) {
+                score += recencyBoost;
+                reason += '+recency';
+            }
+        }
+        return { ...h, score, reason, session_date };
+    });
+    // Graph expansion
+    const hitNotePaths = [...new Set(semanticHits.map(h => h.notePath))];
+    const hitEntityIds = getEntityIdsForNotes(db, hitNotePaths);
+    const relatedEntityIds = getRelatedEntityIds(db, hitEntityIds);
+    const relatedNotePaths = getNotesForEntities(db, relatedEntityIds);
+    const newPaths = relatedNotePaths.filter(p => !hitNotePaths.includes(p));
+    if (newPaths.length > 0) {
+        const relatedChunks = getBestChunksForNotes(db, newPaths, topK, opts.scope?.shows);
+        for (const chunk of relatedChunks) {
+            const row = noteRow(chunk.notePath);
+            scored.push({
+                ...chunk,
+                score: 0.3,
+                reason: 'graph',
+                session_date: resolveSessionDate(row?.frontmatter_json, row?.modified_at),
+            });
+        }
+    }
+    // Fact-aware boost + temporal ranking. Two complementary signals, both general:
+    //
+    // 1. Lifecycle facts (facts table, incl. MCP-written facts resolved by
+    //    canonical_name across entity rows — not just per-note entities): chunks
+    //    carrying a superseded value are demoted, chunks carrying the current
+    //    value are lifted, and explicit past-intent queries invert both.
+    // 2. Corpus signal (works without an LLM fact extractor — RenorBench, and
+    //    real vaults with a History/ convention): notes whose frontmatter marks
+    //    them historical (kind/type: history|historical, historical: true,
+    //    archived: true) are demoted for present-tense queries and lifted for
+    //    past-intent ones.
+    // No hardcoded subject or cue table. Kill switch: RENOR_TEMPORAL_RANKING=0.
+    const temporal = temporalRankingEnabled();
+    const pastIntent = temporal && hasStrictPastIntent(query);
+    // As-of lane: explicit past-date queries behave past-like for presentation
+    // ranking even without past-intent cue words ("in April 2025" has none).
+    const asofNowMs = clock.nowMs ?? Date.now();
+    const asofPast = asofPastLike(query, asofNowMs);
+    const asofRef = asofDatedRef(query, asofNowMs);
+    const historicalNotes = new Set();
+    const factsByNote = new Map();
+    if (temporal) {
+        // Frontmatter historical flags for all hit notes (one batched query).
+        if (hitNotePaths.length > 0) {
+            const noteRows = (0, statements_1.listStatement)(db, hitNotePaths.length, marks => `SELECT path, frontmatter_json FROM notes WHERE path IN (${marks})`).all(...(0, statements_1.paddedList)(hitNotePaths));
+            for (const row of noteRows) {
+                if (frontmatterMarksHistorical(row.frontmatter_json))
+                    historicalNotes.add(row.path);
+            }
+        }
+        // Lifecycle facts: a note's entities share canonical names with MCP-written
+        // entities (source_note '_mcp_'), so expand by canonical_name — otherwise
+        // MCP facts would never match corpus hits.
+        if (hitEntityIds.length > 0) {
+            const ids = hitEntityIds.map(e => e.id);
+            const nameRows = (0, statements_1.listStatement)(db, ids.length, marks => `SELECT DISTINCT canonical_name FROM entities WHERE id IN (${marks})`).all(...(0, statements_1.paddedList)(ids));
+            const names = nameRows.map(r => String(r.canonical_name)).filter(Boolean);
+            if (names.length > 0) {
+                const entityRows = (0, statements_1.listStatement)(db, names.length, marks => `SELECT id, canonical_name, source_note FROM entities WHERE canonical_name COLLATE NOCASE IN (${marks})`).all(...(0, statements_1.paddedList)(names));
+                const nameByEntityId = new Map(entityRows.map(r => [r.id, String(r.canonical_name).toLowerCase()]));
+                const factRows = (0, statements_1.listStatement)(db, entityRows.length, marks => `SELECT subject_entity_id, predicate, object_text, valid_to FROM facts WHERE subject_entity_id IN (${marks})`).all(...(0, statements_1.paddedList)(entityRows.map(r => r.id)));
+                for (const hitEntity of hitEntityIds) {
+                    const ownName = nameByEntityId.get(hitEntity.id);
+                    if (ownName === undefined)
+                        continue;
+                    const merged = factsByNote.get(hitEntity.notePath) ?? [];
+                    for (const f of factRows) {
+                        if (nameByEntityId.get(f.subject_entity_id) === ownName)
+                            merged.push(f);
+                    }
+                    factsByNote.set(hitEntity.notePath, merged);
+                }
+            }
+        }
+    }
+    // Distinctive query words (not pure temporal/function markers): used to anchor
+    // the past-intent lift to content — an unconditional lift rockets OTHER
+    // subjects' historical notes above multi-constraint gold (RenorBench hop-009).
+    const TEMPORAL_STOPWORDS = new Set(['previously', 'before', 'used', 'earlier', 'former', 'formerly', 'past', 'history', 'was', 'were', 'did', 'does', 'the', 'and', 'what', 'where', 'who', 'when', 'from']);
+    const contentfulQueryWords = (query.toLowerCase().match(/[\p{L}\p{M}]{3,}/gu) ?? [])
+        .filter(w => !TEMPORAL_STOPWORDS.has(w));
+    const hitText = (h) => h.text.toLowerCase();
+    const queryWords = query.toLowerCase().split(/\s+/);
+    for (const hit of scored) {
+        // Legacy fact-aware boost: scoped to the hit note's OWN entity facts exactly
+        // as before this change — the canonical-name expansion below exists for
+        // temporal decisions only and must not perturb the legacy boost distribution.
+        const ownEntityFacts = (() => {
+            const own = hitEntityIds.find(e => e.notePath === hit.notePath);
+            if (!own)
+                return [];
+            let rows = ownFactRows.get(own.id);
+            if (!rows)
+                ownFactRows.set(own.id, rows = ownFactsStmt().all(own.id));
+            return rows;
+        })();
+        const facts = factsByNote.get(hit.notePath) ?? [];
+        const factMatch = ownEntityFacts.some(f => queryWords.some(w => (f.object_text ?? '').toLowerCase().includes(w) ||
+            (f.predicate ?? '').toLowerCase().includes(w)));
+        if (factMatch) {
+            hit.score += 0.15;
+            hit.reason += '+fact';
+        }
+        // As-of lane: the query names a past date, so hits carrying the same
+        // calendar reference are likelier to hold the as-of answer than the
+        // newest note (which describes the current world, not the asked one).
+        if (asofRef) {
+            const yearToken = String(asofRef.year);
+            const lowerText = hit.text.toLowerCase();
+            if (lowerText.includes(yearToken)) {
+                hit.score += 0.08;
+                hit.reason += '+asof-year';
+                if (asofRef.month !== undefined) {
+                    const monthName = Object.keys(ASOF_MONTHS).find(m => ASOF_MONTHS[m] === asofRef.month);
+                    if (monthName && lowerText.includes(monthName)) {
+                        hit.score += 0.04;
+                        hit.reason += '+asof-month';
+                    }
+                }
+            }
+        }
+        if (temporal) {
+            const text = hitText(hit);
+            // Historical-note signal is lift-only, on strict past-intent queries:
+            // a blanket present-tense demotion pushed gold historical notes out of the
+            // window for queries like "which tea drinker grew up in Sacramento?" —
+            // present-tense phrasing, past answer. The lifecycle-fact staleness
+            // demotion below remains the general present-tense mechanism.
+            const isHistoricalNote = historicalNotes.has(hit.notePath);
+            if (pastIntent && isHistoricalNote) {
+                // Content-anchored lift: the historical note must itself match the query's
+                // distinctive words (≥2), so an unrelated person's history note — however
+                // semantically adjacent — does not ride the intent signal past the gold.
+                const contentOverlap = contentfulQueryWords.filter(w => text.includes(w)).length;
+                if (contentOverlap >= 2) {
+                    // Must clear recency (+0.1 max) + fact boost (+0.15) the current note
+                    // typically carries, or past-intent queries can never win.
+                    hit.score += 0.3;
+                    hit.reason += '+historical-intent';
+                }
+            }
+            const currentPredicates = new Set(facts.filter(f => f.valid_to === null).map(f => String(f.predicate)));
+            // Demote: chunk carries a value the lifecycle has since superseded.
+            for (const f of facts) {
+                if (f.valid_to === null || !currentPredicates.has(String(f.predicate)))
+                    continue;
+                const stale = (f.object_text ?? '').trim().toLowerCase();
+                if (stale.length >= 3 && text.includes(stale)) {
+                    if (pastIntent) {
+                        hit.score += 0.1;
+                        hit.reason += '+historical-intent';
+                    }
+                    else {
+                        hit.score -= 0.15;
+                        hit.reason += '+stale-fact';
+                    }
+                    break; // one demotion per hit; stale signal already applied
+                }
+            }
+            // Lift: chunk carries the currently-valid value for a superseded predicate.
+            if (!pastIntent) {
+                for (const f of facts) {
+                    if (f.valid_to !== null)
+                        continue;
+                    const wasSuperseded = facts.some(g => g.valid_to !== null && String(g.predicate) === String(f.predicate));
+                    if (!wasSuperseded)
+                        continue; // plain current facts already get the fact boost above
+                    const cur = (f.object_text ?? '').trim().toLowerCase();
+                    if (cur.length >= 3 && text.includes(cur)) {
+                        hit.score += 0.1;
+                        hit.reason += '+current-fact';
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    const ranked = dedupeHits(scored.sort(semantic_1.byScoreThenPlace));
+    // Fail-open floor. The stub filter must never empty the window: a zero-hit
+    // retrieval is a hard abort on the product path, because the benchmark client
+    // refuses to score a case with no hits ("Retrieval precondition failed: public
+    // CLI search returned zero hits"). That is strictly worse than surfacing a stub.
+    // Measured 2026-09-29: an arm carrying a metadata-strip variant of this filter
+    // died at case 122/500 on exactly this precondition. Fall back to the unfiltered
+    // ranking when filtering would leave nothing.
+    const filtered = ranked.filter(h => !isSpeakerStub(h.text));
+    const contentful = filtered.length > 0 ? filtered : ranked;
+    const datedFactHits = factHits.map(h => {
+        const row = noteRow(h.notePath);
+        return { ...h, session_date: resolveSessionDate(row?.frontmatter_json, row?.modified_at) };
+    });
+    const seen = new Set(datedFactHits.map(h => h.text));
+    // The ledger's own header is no memory: it comes off with the closed events, before the page is cut.
+    const mixed = (0, ledgerPresentation_1.dropLedgerPreamble)((0, ledgerLiveness_1.resolveLedgerHits)([...datedFactHits, ...contentful.filter(h => !seen.has(h.text))], (0, ledgerLiveness_1.closedLedgerEvents)(db), opts.includeHistory === true), opts.isLedgerNote);
+    const diversityCap = resolveSessionDiversityCap(process.env, opts.noteCapWhenUnset);
+    let hits = applySessionDiversity(mixed, diversityCap, topK).slice(0, topK).map(h => ({
+        notePath: h.notePath,
+        chunkId: h.chunkId,
+        headingPath: h.headingPath,
+        text: h.text,
+        score: h.score,
+        reason: h.reason,
+        ...(h.session_date ? { session_date: h.session_date } : {}),
+        ...(cosineByChunk?.has(h.chunkId) ? { similarity: cosineByChunk.get(h.chunkId) } : {}),
+        // A fact an identity question read names its author, so the reader's view can mark it (mvp/factMarkers.ts).
+        ...('author' in h && h.author !== undefined ? { author: h.author } : {}),
+    }));
+    return { hits, noteRow, temporal, pastIntent, asofPast };
+}
+/** The hits dated, joined by the statements of their sessions and laid out. The first wait is for the date of an entry of a daily note. */
+async function finishContext(read) {
+    const { db, vectorIndex, provider, query, queryProbe, window, bestFirst } = read;
+    const { noteRow, temporal, pastIntent, asofPast } = window;
+    let { hits } = window;
+    // A hit that is a ledger event is dated by the event, and one that is an entry of a daily note by the entry: each
+    // is one note, so the note's date is one date for every event, or every entry of the day, in it. Decided on the
+    // text a hit still has after liveness filtering, and only for the hits that are returned. Everything else keeps its
+    // note's date; no score is touched. Entry headers, filenames and replayed event times are content too: none may
+    // override the indexed file's write-time bound, even on already indexed notes.
+    const eventTime = (0, ledgerEventTime_1.createLedgerEventClock)(db);
+    const entryTime = (0, dailyEntryTime_1.createDailyEntryClock)();
+    // The dates of events are read as the hits are mapped, before any of them waits: in one transaction (inReadSnapshot).
+    hits = await Promise.all((0, readCache_1.inReadSnapshot)(db, () => hits.map(async (h) => {
+        const derived = eventTime(h) ?? await entryTime(h);
+        if (derived === undefined)
+            return h;
+        const session_date = clampSessionDate(derived, noteRow(h.notePath)?.modified_at);
+        return { ...h, session_date };
+    })));
+    // RENOR_SESSION_EXPAND (default 5 notes, 0 is off): the short statements of the best notes in the window join it,
+    // under a token budget. The window itself is not touched; see sessionExpansionHits.
+    const expansion = resolveSessionExpand();
+    // Ranking by cosine is armed only for an embedding model the product has calibrated (CALIBRATED_BARS): the order
+    // of cosines was measured for that model. Any other provider (the lexical eval stub, an unmeasured model) keeps the
+    // former expansion, unless the operator declares that its endpoint serves a calibrated model (calibratedModelKey).
+    const rankedExpansion = calibratedModelKey(provider?.identity, provider?.dimensions) !== null ? resolveRankedExpansion() : null;
+    if (expansion)
+        hits = [...hits, ...(0, readCache_1.inReadSnapshot)(db, () => sessionExpansionHits(db, hits, expansion, rankedExpansion && queryProbe.queryVector && vectorIndex ? { vectorIndex, queryVector: queryProbe.queryVector, ranked: rankedExpansion } : undefined))];
+    // Default-on (S0 78.4%): lay the already-selected window out newest-session-first.
+    // Does not replace scoring or change which chunks enter top-K. Opt out: RENOR_NEWEST_FIRST=0.
+    // An explicit past-intent query overrides this presentation rerank — "what was
+    // it before" is precisely the case where newest-first is the wrong order.
+    // The as-of lane extends the override to explicit past-date queries, which
+    // carry no past-intent cue words but ask about the old world all the same.
+    // Either way the result says which key it is in order of (`rankedBy`): the order is a presentation
+    // choice the agent cannot see from the hits alone, and hits[0] is not "the answer" unless that key is score.
+    // A read that asks for best match first (search_memory under RENOR_SEARCH_BEST_FIRST) is laid out by score.
+    const newestFirst = !bestFirst && newestFirstEnabled() && !(temporal && pastIntent) && !asofPast;
+    const rankedBy = newestFirst ? 'session_date' : 'score';
+    contentfulHeld.clear(); // nothing outlives the read it was worked out for
+    return { query, hits: orderHits(hits, rankedBy), rankedBy };
+}