agent-working-memory 0.13.0 → 0.14.0

package/src/core/rerank-window.ts

@@ -0,0 +1,158 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Passage selection for cross-encoder reranking.
+ *
+ * THE PROBLEM
+ * -----------
+ * Reranking truncates each passage to a fixed prefix (historically the first
+ * 400 chars). That truncation exists for a real reason: cross-encoders pad to
+ * the longest passage in the batch, so one 5,000-char memory in a 40-item pool
+ * drags every passage to ~512 tokens and costs 3-4x. The reranker is already
+ * ~90% of warm recall latency, so "just send everything" is not available.
+ *
+ * But a PREFIX is the wrong 400 chars. Measured on the live 29.8k store:
+ *   - canonical memories median 1,965 chars, 98.7% exceed 400
+ *   - the reranker cannot see 78.8% of each canonical memory's vocabulary
+ *   - 99.9% of long canonical memories carry identifiers only past char 400
+ * And measured on tests/longmem-eval: moving the answer from char 150 to char
+ * 700 takes success@1 from 100% to 0%, with the gold's cross-encoder score
+ * collapsing 0.986 -> 0.000 while its BM25 score barely moves. The memory stays
+ * retrievable and stops being rankable.
+ *
+ * THE FIX
+ * -------
+ * Spend the same character budget on the window that actually contains the
+ * query's terms, instead of on whatever happens to be at the top of the memory.
+ * Cost is unchanged — same budget, same batch padding, same inference — so this
+ * buys ranking quality without buying latency.
+ *
+ * The concept line is always kept: it is short, it is the memory's title, and
+ * it is what a human wrote to summarise the thing.
+ */
+
+/** Cheap tokenizer for locating query terms inside a passage. */
+function terms(query: string): string[] {
+  const raw = query.toLowerCase().match(/[a-z0-9_][a-z0-9_.\-]{1,}/g) ?? [];
+  const STOP = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'what', 'where', 'when',
+    'which', 'does', 'did', 'was', 'were', 'are', 'is', 'be', 'to', 'of', 'in',
+    'on', 'at', 'by', 'it', 'as', 'do', 'how', 'why', 'a', 'an', 'or',
+  ]);
+  return Array.from(new Set(raw.filter(t => t.length >= 3 && !STOP.has(t))));
+}
+
+/**
+ * Choose the `budget`-char window of `content` densest in query terms.
+ * Returns the head of the content when nothing matches — the old behaviour,
+ * which is the right fallback: with no query signal there is no reason to
+ * prefer any other part of the memory.
+ */
+export function densestWindow(content: string, query: string, budget: number): string {
+  if (content.length <= budget) return content;
+
+  const toks = terms(query);
+  if (toks.length === 0) return content.slice(0, budget);
+
+  const lower = content.toLowerCase();
+  const hits: number[] = [];
+  for (const t of toks) {
+    let from = 0;
+    for (;;) {
+      const i = lower.indexOf(t, from);
+      if (i < 0) break;
+      hits.push(i);
+      from = i + t.length;
+    }
+  }
+  if (hits.length === 0) return content.slice(0, budget);
+  hits.sort((a, b) => a - b);
+
+  // Slide a window anchored slightly before each hit; keep the one covering most.
+  let bestStart = 0;
+  let bestCount = -1;
+  for (let i = 0; i < hits.length; i++) {
+    const start = Math.max(0, hits[i] - Math.floor(budget / 5));
+    let count = 0;
+    for (let j = i; j < hits.length && hits[j] - start < budget; j++) count++;
+    if (count > bestCount) { bestCount = count; bestStart = start; }
+  }
+
+  // Snap to a word boundary so the cross-encoder is not handed a split token.
+  let start = bestStart;
+  if (start > 0) {
+    const sp = content.indexOf(' ', start);
+    if (sp >= 0 && sp - start < 40) start = sp + 1;
+  }
+  const slice = content.slice(start, start + budget);
+  return (start > 0 ? '…' : '') + slice + (start + budget < content.length ? '…' : '');
+}
+
+/**
+ * Build the passage handed to the cross-encoder for one candidate.
+ *
+ * `mode`:
+ *  - `'prefix'` (default) — legacy behaviour, the first `budget` chars.
+ *  - `'query'`  — the `budget`-char window densest in query terms.
+ */
+export function buildRerankPassage(
+  concept: string,
+  content: string,
+  query: string,
+  budget: number,
+  mode: 'prefix' | 'query',
+  tags?: string[],
+): string {
+  const body = mode === 'query'
+    ? densestWindow(content, query, budget)
+    : (content.length > budget ? content.slice(0, budget) : content);
+  // Topical tags, when enabled. The cross-encoder decides final order since
+  // phase 9b, and it cannot see tags at all — measured on the live store, 66.2%
+  // of topical tag terms never appear in the body, so that vocabulary is
+  // invisible to the stage that now decides ranking. Appended (not substituted)
+  // and length-capped so it cannot crowd out the content window.
+  const extra = rerankTagText(tags);
+  return extra ? `${concept}: ${body} ${extra}` : `${concept}: ${body}`;
+}
+
+/** Whether topical tags are appended to the rerank passage. Default OFF. */
+export function rerankTagsEnabled(): boolean {
+  return process.env.AWM_RERANK_TAGS === '1';
+}
+
+/** Character budget for the appended tag text. */
+export function rerankTagBudget(): number {
+  const v = Number(process.env.AWM_RERANK_TAGS_LEN ?? 80);
+  return Number.isFinite(v) && v > 0 ? v : 80;
+}
+
+/**
+ * Render topical tags as plain terms for the cross-encoder.
+ * Only `topic=` / `proj=` / `project=` carry query vocabulary; date/person/
+ * ticket tags are identifiers the body usually already contains, and adding
+ * them would spend the budget without adding reachable words.
+ */
+export function rerankTagText(tags?: string[]): string {
+  if (!rerankTagsEnabled() || !tags || tags.length === 0) return '';
+  const words = new Set<string>();
+  for (const t of tags) {
+    const m = /^(?:topic|proj|project)=(.+)$/i.exec(t);
+    if (!m) continue;
+    for (const w of m[1].toLowerCase().split(/[-_\s]+/)) {
+      if (w.length > 2) words.add(w);
+    }
+  }
+  if (words.size === 0) return '';
+  return `[${[...words].join(' ').slice(0, rerankTagBudget())}]`;
+}
+
+/** Character budget for a rerank passage. */
+export function rerankTruncation(): number {
+  const v = Number(process.env.AWM_RERANK_TRUNC ?? 400);
+  return Number.isFinite(v) && v > 0 ? v : 400;
+}
+
+/** Passage selection mode. Default `prefix` preserves shipped behaviour. */
+export function rerankWindowMode(): 'prefix' | 'query' {
+  return process.env.AWM_RERANK_WINDOW === 'query' ? 'query' : 'prefix';
+}

package/src/core/rerank2.ts

@@ -0,0 +1,82 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Second-stage reordering — "rerank the rerank".
+ *
+ * THE PROBLEM
+ * -----------
+ * Phase 7 blends the cross-encoder's judgement with the composite score:
+ *
+ *     score = compositeWeight * composite + rerankWeight * rerankerScore
+ *
+ * with `rerankWeight` capped at 0.7, so `composite` always keeps at least 30%
+ * of the vote on final ordering. Composite carries decay, Hebbian and salience
+ * terms — useful for deciding WHICH candidates deserve consideration, but a
+ * poor judge of which one actually answers the question.
+ *
+ * Measured on LoCoMo (616 answerable probes, tests/rerank2-eval): the blend
+ * disagrees with the cross-encoder about which item deserves rank 1 on **38.6%**
+ * of queries. Where that disagreement is decidable — one of the two is the gold
+ * evidence — the **cross-encoder is right 77% of the time** (61 vs 18).
+ *
+ * THE FIX
+ * -------
+ * Re-sort only the final returned window by `rerankerScore` alone. Simulated
+ * gain: **+8.0pp success@1** (39.1% -> 47.1%), fixing 61 queries and breaking
+ * 12, with every category improving.
+ *
+ * WHY THIS IS SAFE
+ * ----------------
+ * Applied AFTER the channel-agreement gate, AFTER computeRecallConfidence, and
+ * AFTER the requireConfidence check. Those read rerankerScore maxima/margins and
+ * the score distribution. Reordering a window afterwards changes neither its
+ * membership nor any score, so **adversarial abstention is provably
+ * unaffected**. Retuning `rerankWeight` inside phase 7 would NOT have that
+ * property — it shifts `item.score`, hence which items clear `minScore`, which
+ * is exactly what cost adversarial 73.4->71.0 when the pool was last widened.
+ *
+ * Margin-guarded variants were simulated and are strictly worse: gating on a
+ * >0.15 reranker margin cuts breakage 12->1 but also cuts fixes 61->17.
+ */
+
+/** Minimal shape this needs — anything carrying a cross-encoder score. */
+export interface RerankScored {
+  phaseScores: { rerankerScore: number };
+}
+
+/**
+ * Re-sort the first `k` entries of `ranked` by descending `rerankerScore`,
+ * leaving the tail untouched. Returns a new array; never mutates the input.
+ *
+ * Returns `ranked` unchanged when reordering would be unsound:
+ *  - `k <= 1`, or fewer than 2 entries to order
+ *  - any entry in the window has `rerankerScore <= 0`, which means the
+ *    cross-encoder did not score it (skipped, failed, or timed out). Sorting
+ *    on a zero would scramble an otherwise sound composite ordering — the
+ *    reranker is wrapped in try/catch and a 10s timeout upstream, so this is a
+ *    real path, not a theoretical one.
+ */
+export function reorderByReranker<T extends RerankScored>(ranked: T[], k: number): T[] {
+  if (k <= 1 || ranked.length <= 1) return ranked;
+
+  const window = Math.min(k, ranked.length);
+  if (window <= 1) return ranked;
+
+  const head = ranked.slice(0, window);
+  for (const r of head) {
+    if (!(r.phaseScores.rerankerScore > 0)) return ranked;  // also catches NaN
+  }
+
+  const sorted = head.slice().sort((a, b) => b.phaseScores.rerankerScore - a.phaseScores.rerankerScore);
+  return sorted.concat(ranked.slice(window));
+}
+
+/** Window size for the second stage. */
+export function rerank2WindowSize(): number {
+  return Number(process.env.AWM_RERANK2_K ?? 10);
+}
+
+/** Whether the second stage is enabled. Default OFF pending the tracer verdict. */
+export function rerank2Enabled(): boolean {
+  return process.env.AWM_RERANK2 === '1';
+}

package/src/core/reranker.ts

@@ -19,6 +19,7 @@ import {
   type PreTrainedModel,
 } from '@huggingface/transformers';
 import { dispatchRerank, registerInProcessHandlers } from './ml-worker.js';
+import { ensureModelCacheDir } from './model-cache.js';
 
 const DEFAULT_MODEL = 'Xenova/ms-marco-MiniLM-L-6-v2';
 const MODEL_ID = process.env.AWM_RERANKER_MODEL || DEFAULT_MODEL;
@@ -33,6 +34,7 @@ async function ensureLoaded(): Promise<void> {
   if (tokenizer && model) return;
   if (initPromise) return initPromise;
   initPromise = (async () => {
+    ensureModelCacheDir();
     tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID);
     model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, { dtype: 'fp32' });
     console.error(`Re-ranker model loaded in-process: ${MODEL_ID}`);

package/src/core/retrieval-text.ts

@@ -0,0 +1,82 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Derived retrieval text — the machine-facing view of a memory.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Measured on the live 11,294-engram store: 66.2% of topical tag terms never
+ * appear in the memory body, and 94.3% of tagged memories are missing at least
+ * one of their own topical terms. Tags are indexed by BM25 only — the embedding
+ * is built from `concept + content` (write-pipeline.ts) and so is the
+ * cross-encoder rerank passage (activation.ts). So that vocabulary is invisible
+ * to two of the three retrieval channels, including the one that decides final
+ * ordering since phase 9b.
+ *
+ * The consequence, observed on a real memory: "private plan memory peaked 88%,
+ * scale P1v3 -> P2v3" was NOT in the top 40 candidates for "azure app service
+ * plan capacity increase internal application". Its body contains no "azure",
+ * no "capacity", no "app service plan" — only `topic=azure` as a tag.
+ *
+ * THE SHAPE THAT MATTERS
+ * ----------------------
+ * This builds a DERIVED text used for embedding and reranking. It does NOT
+ * mutate `content`. That distinction is the whole design:
+ *
+ *   - AWM's model slots have always been ADDITIVE — the embedder, expander and
+ *     reranker score or expand, they never rewrite what was stored. Appending
+ *     tag terms into the body would break that invariant, and a normaliser that
+ *     silently edits stored memories is unrecoverable if it is wrong.
+ *   - A derived view is recomputable. If the rule turns out to be bad, re-derive
+ *     and re-embed; the source of truth was never touched.
+ *   - And it can be BACKFILLED over the existing corpus, which body-only fixes
+ *     (write-time guidance, future writes) cannot reach. 7,350 memories are
+ *     already wrong.
+ *
+ * Only `topic=` / `proj=` / `project=` are included. Date, person and ticket
+ * tags are identifiers the body usually already carries, so adding them spends
+ * budget without adding reachable words.
+ */
+
+/** Whether the derived retrieval text includes tag vocabulary. Default OFF. */
+export function retrievalTextEnabled(): boolean {
+  return process.env.AWM_RETRIEVAL_TEXT === '1';
+}
+
+/**
+ * Extract the topical vocabulary a future question is likely to use.
+ * Deduplicated and lowercased; order follows first appearance so the output is
+ * deterministic for a given tag list (important: a non-deterministic embedding
+ * input would make re-embedding produce different vectors for the same memory).
+ */
+export function topicalTerms(tags?: string[]): string[] {
+  if (!tags || tags.length === 0) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const t of tags) {
+    const m = /^(?:topic|proj|project)=(.+)$/i.exec(t);
+    if (!m) continue;
+    for (const w of m[1].toLowerCase().split(/[-_\s]+/)) {
+      if (w.length > 2 && !seen.has(w)) { seen.add(w); out.push(w); }
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the text used for EMBEDDING a memory.
+ *
+ * When disabled this returns exactly `concept + ' ' + content`, byte-identical
+ * to the historical input — so leaving the flag off cannot change a single
+ * stored vector.
+ */
+export function buildRetrievalText(concept: string, content: string, tags?: string[]): string {
+  const base = `${concept} ${content}`;
+  if (!retrievalTextEnabled()) return base;
+  const terms = topicalTerms(tags);
+  if (terms.length === 0) return base;
+  // Appended at the END. The embedding model truncates beyond its context
+  // window, and the head of the content is what anchors the topic — putting tag
+  // terms first would displace the memory's actual subject in the vector.
+  return `${base} ${terms.join(' ')}`;
+}

package/src/core/temporal-query.ts

@@ -0,0 +1,193 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Temporal expressions in a recall query.
+ *
+ * THE PROBLEM
+ * -----------
+ * Nothing in the pipeline parsed dates out of query text, and `ActivationQuery`
+ * had no date parameter. So "azure app plan from last Thursday or Friday" spent
+ * "last", "Thursday" and "Friday" as ordinary BM25 tokens — diluting the subject
+ * terms and matching `date=` tags right across the corpus.
+ *
+ * Measured on the real store (101 probes, tests/realstore-eval):
+ *   subject only ............ 59.4% success@1   <- control
+ *   + "from last Friday" .... 56.4%  (-3.0pp)
+ *   + "on 2026-05-01" ....... 51.5%  (-7.9pp)
+ *   ORACLE, week-filtered ... 96.0%  (+36.6pp)
+ *
+ * So the most selective thing the user said was a PENALTY, and a working
+ * temporal filter is worth more than anything else measured on this store.
+ *
+ * DESIGN NOTES
+ * ------------
+ * - `asOf` is required for relative phrases. Using the wall clock would make a
+ *   fixture non-reproducible: "last week" would silently mean something new on
+ *   every run. Callers pass the query time explicitly.
+ * - Matching is deliberately CONSERVATIVE. A greedy matcher that fired on
+ *   ordinary words would reshape every recall in the store, so each pattern is
+ *   anchored on an unambiguous cue ("last", "yesterday", an ISO date, a month
+ *   name). When nothing matches, this returns `null` and callers must treat
+ *   that as a strict no-op.
+ * - The window is a PREFERENCE for callers, never a filter. People misremember
+ *   dates — "last Thursday or Friday" is itself an admission of uncertainty —
+ *   so a memory outside the window must stay reachable on subject strength.
+ */
+
+export interface TemporalMatch {
+  /** Inclusive window start (UTC ms). */
+  from: number;
+  /** Exclusive window end (UTC ms). */
+  to: number;
+  /** The literal phrases matched, for logging and for stripping. */
+  matched: string[];
+  /** The query with temporal phrases removed, for the lexical channel. */
+  stripped: string;
+  /** How the window was derived — useful when explaining a recall. */
+  kind: 'relative-day' | 'relative-week' | 'relative-month' | 'recent' | 'absolute-date' | 'absolute-month';
+}
+
+const DAY = 86400000;
+const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june',
+  'july', 'august', 'september', 'october', 'november', 'december'];
+
+const utcDay = (ms: number) => Math.floor(ms / DAY) * DAY;
+
+/**
+ * Parse a temporal expression out of `query`, anchored at `asOf`.
+ * Returns `null` when nothing matches — callers MUST treat that as a no-op.
+ *
+ * Windows are padded generously rather than tightly: the goal is to prefer a
+ * neighbourhood, not to pin an exact day the user probably misremembers.
+ */
+export function parseTemporal(query: string, asOf: Date | number): TemporalMatch | null {
+  const anchorMs = typeof asOf === 'number' ? asOf : asOf.getTime();
+  if (!Number.isFinite(anchorMs)) return null;
+  const q = query.toLowerCase();
+  const today = utcDay(anchorMs);
+  const matched: string[] = [];
+
+  const build = (from: number, to: number, kind: TemporalMatch['kind']): TemporalMatch => ({
+    from, to, matched,
+    stripped: stripPhrases(query, matched),
+    kind,
+  });
+
+  // ── absolute ISO date — ONLY with an explicit temporal cue ──
+  // A BARE date must not trigger this. Memories routinely carry a date as part
+  // of their SUBJECT ("Hive close-out 2026-04-24 PASS", "FIXED 2026-08-21 event
+  // River Glen"), where the date IS the fact, not a "when" filter. Treating
+  // those as temporal strips a strongly discriminative term and makes recall
+  // worse: measured, a bare-date rule fired on 98 of 1,316 (7.4%) real
+  // identifier queries and cost success@1 75.8% -> 75.0%. Same reason the month
+  // rule below requires an "in"/"during" cue.
+  const iso = q.match(/\b(on|from|since|before|after|around|during|dated)\s+(\d{4})-(\d{2})-(\d{2})\b/);
+  if (iso) {
+    matched.push(iso[0]);
+    const d = Date.UTC(+iso[2], +iso[3] - 1, +iso[4]);
+    // +/- 3 days: a remembered date is often a day or two off.
+    return build(d - 3 * DAY, d + 4 * DAY, 'absolute-date');
+  }
+
+  // ── "yesterday" / "today" ──
+  if (/\byesterday\b/.test(q)) {
+    matched.push('yesterday');
+    return build(today - DAY, today, 'relative-day');
+  }
+  if (/\btoday\b/.test(q)) {
+    matched.push('today');
+    return build(today, today + DAY, 'relative-day');
+  }
+
+  // ── "last <weekday>" / "on <weekday>" ──
+  const wd = q.match(/\b(?:last|this|on)\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/);
+  if (wd) {
+    matched.push(wd[0]);
+    // A second weekday ("Thursday or Friday") widens rather than confuses.
+    const second = q.match(/\bor\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)\b/);
+    if (second) matched.push(second[0]);
+    const targets = [WEEKDAYS.indexOf(wd[1])];
+    if (second) targets.push(WEEKDAYS.indexOf(second[1]));
+    const anchorDow = new Date(today).getUTCDay();
+    const days = targets.map(t => {
+      let back = (anchorDow - t + 7) % 7;
+      if (back === 0) back = 7;                 // "last Friday" on a Friday means the previous one
+      return today - back * DAY;
+    });
+    // +/- 1 day of slack around the named day(s).
+    return build(Math.min(...days) - DAY, Math.max(...days) + 2 * DAY, 'relative-day');
+  }
+
+  // ── "last week" / "this week" / "past week" ──
+  if (/\b(?:last|this|past)\s+week\b/.test(q)) {
+    matched.push((q.match(/\b(?:last|this|past)\s+week\b/) as RegExpMatchArray)[0]);
+    return build(today - 14 * DAY, today + DAY, 'relative-week');
+  }
+
+  // ── "last month" / "this month" / "past month" ──
+  if (/\b(?:last|this|past)\s+month\b/.test(q)) {
+    matched.push((q.match(/\b(?:last|this|past)\s+month\b/) as RegExpMatchArray)[0]);
+    return build(today - 45 * DAY, today + DAY, 'relative-month');
+  }
+
+  // ── "last N days/weeks/months" ──
+  const lastN = q.match(/\b(?:last|past)\s+(\d{1,3})\s+(day|week|month)s?\b/);
+  if (lastN) {
+    matched.push(lastN[0]);
+    const n = +lastN[1];
+    const mult = lastN[2] === 'day' ? DAY : lastN[2] === 'week' ? 7 * DAY : 30 * DAY;
+    return build(today - n * mult, today + DAY, 'relative-week');
+  }
+
+  // ── "recently" / "recent" / "the other day" / "a few days ago" ──
+  if (/\b(?:recently|the other day|a few days ago|just now)\b/.test(q)) {
+    matched.push((q.match(/\b(?:recently|the other day|a few days ago|just now)\b/) as RegExpMatchArray)[0]);
+    return build(today - 14 * DAY, today + DAY, 'recent');
+  }
+
+  // ── "in <Month> [Year]" — requires the "in"/"during" cue so a project named
+  //    "May" or a sentence containing "march" cannot trigger it accidentally.
+  const mon = q.match(/\b(?:in|during|back in)\s+(january|february|march|april|may|june|july|august|september|october|november|december)\b(?:\s+(\d{4}))?/);
+  if (mon) {
+    matched.push(mon[0]);
+    const mIdx = MONTHS.indexOf(mon[1]);
+    const anchorYear = new Date(today).getUTCFullYear();
+    const year = mon[2] ? +mon[2] : anchorYear;
+    const from = Date.UTC(year, mIdx, 1);
+    const to = Date.UTC(mIdx === 11 ? year + 1 : year, (mIdx + 1) % 12, 1);
+    return build(from, to, 'absolute-month');
+  }
+
+  return null;
+}
+
+/** Remove matched temporal phrases (and now-dangling connectives) from a query. */
+function stripPhrases(query: string, phrases: string[]): string {
+  let out = query;
+  // Longest first, so "on 2026-05-01" is removed before the bare date.
+  for (const p of [...phrases].sort((a, b) => b.length - a.length)) {
+    out = out.replace(new RegExp(escapeRe(p), 'gi'), ' ');
+  }
+  return out
+    .replace(/\b(?:from|on|in|during|back in|since)\s*$/i, ' ')
+    .replace(/\s+(?:from|on|in|during)\s+(?=\s|$)/gi, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Whether temporal handling is enabled. Default OFF. */
+export function temporalEnabled(): boolean {
+  return process.env.AWM_TEMPORAL === '1';
+}
+
+/**
+ * Boost applied to a candidate whose creation time falls inside the window.
+ * A PREFERENCE, not a filter — see the design note above.
+ */
+export function temporalBoost(): number {
+  const v = Number(process.env.AWM_TEMPORAL_BOOST ?? 0.35);
+  return Number.isFinite(v) && v >= 0 ? v : 0.35;
+}