agent-recall-core 3.4.47 → 3.4.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. package/README.md +25 -0
  2. package/dist/digest/store.d.ts +15 -6
  3. package/dist/digest/store.d.ts.map +1 -1
  4. package/dist/digest/store.js +33 -20
  5. package/dist/digest/store.js.map +1 -1
  6. package/dist/embeddings/chunker.d.ts +102 -0
  7. package/dist/embeddings/chunker.d.ts.map +1 -0
  8. package/dist/embeddings/chunker.js +260 -0
  9. package/dist/embeddings/chunker.js.map +1 -0
  10. package/dist/embeddings/config.d.ts +93 -0
  11. package/dist/embeddings/config.d.ts.map +1 -0
  12. package/dist/embeddings/config.js +174 -0
  13. package/dist/embeddings/config.js.map +1 -0
  14. package/dist/embeddings/index-store.d.ts +61 -0
  15. package/dist/embeddings/index-store.d.ts.map +1 -0
  16. package/dist/embeddings/index-store.js +158 -0
  17. package/dist/embeddings/index-store.js.map +1 -0
  18. package/dist/embeddings/indexer.d.ts +75 -0
  19. package/dist/embeddings/indexer.d.ts.map +1 -0
  20. package/dist/embeddings/indexer.js +196 -0
  21. package/dist/embeddings/indexer.js.map +1 -0
  22. package/dist/embeddings/runtime.d.ts +66 -0
  23. package/dist/embeddings/runtime.d.ts.map +1 -0
  24. package/dist/embeddings/runtime.js +197 -0
  25. package/dist/embeddings/runtime.js.map +1 -0
  26. package/dist/helpers/associative-link.d.ts.map +1 -1
  27. package/dist/helpers/associative-link.js +26 -1
  28. package/dist/helpers/associative-link.js.map +1 -1
  29. package/dist/helpers/tokenize.d.ts +1 -0
  30. package/dist/helpers/tokenize.d.ts.map +1 -1
  31. package/dist/helpers/tokenize.js +18 -0
  32. package/dist/helpers/tokenize.js.map +1 -1
  33. package/dist/index.d.ts +27 -10
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +50 -6
  36. package/dist/index.js.map +1 -1
  37. package/dist/palace/awareness.d.ts +34 -10
  38. package/dist/palace/awareness.d.ts.map +1 -1
  39. package/dist/palace/awareness.js +249 -180
  40. package/dist/palace/awareness.js.map +1 -1
  41. package/dist/palace/consolidate.d.ts +1 -1
  42. package/dist/palace/consolidate.d.ts.map +1 -1
  43. package/dist/palace/consolidate.js +9 -9
  44. package/dist/palace/consolidate.js.map +1 -1
  45. package/dist/palace/decay-pass.d.ts +1 -1
  46. package/dist/palace/decay-pass.d.ts.map +1 -1
  47. package/dist/palace/decay-pass.js +2 -2
  48. package/dist/palace/decay-pass.js.map +1 -1
  49. package/dist/palace/fan-out.d.ts +1 -1
  50. package/dist/palace/fan-out.d.ts.map +1 -1
  51. package/dist/palace/fan-out.js +5 -5
  52. package/dist/palace/fan-out.js.map +1 -1
  53. package/dist/palace/index-manager.d.ts +1 -1
  54. package/dist/palace/index-manager.d.ts.map +1 -1
  55. package/dist/palace/index-manager.js +1 -1
  56. package/dist/palace/index-manager.js.map +1 -1
  57. package/dist/palace/insights-index.d.ts +19 -6
  58. package/dist/palace/insights-index.d.ts.map +1 -1
  59. package/dist/palace/insights-index.js +36 -13
  60. package/dist/palace/insights-index.js.map +1 -1
  61. package/dist/palace/keystone.d.ts +1 -1
  62. package/dist/palace/keystone.d.ts.map +1 -1
  63. package/dist/palace/keystone.js +2 -2
  64. package/dist/palace/keystone.js.map +1 -1
  65. package/dist/palace/rooms.d.ts +3 -3
  66. package/dist/palace/rooms.d.ts.map +1 -1
  67. package/dist/palace/rooms.js +34 -6
  68. package/dist/palace/rooms.js.map +1 -1
  69. package/dist/retrieval/candidates.d.ts +27 -2
  70. package/dist/retrieval/candidates.d.ts.map +1 -1
  71. package/dist/retrieval/candidates.js +170 -3
  72. package/dist/retrieval/candidates.js.map +1 -1
  73. package/dist/retrieval/contradiction.d.ts +65 -13
  74. package/dist/retrieval/contradiction.d.ts.map +1 -1
  75. package/dist/retrieval/contradiction.js +40 -17
  76. package/dist/retrieval/contradiction.js.map +1 -1
  77. package/dist/retrieval/query-memory.d.ts +112 -9
  78. package/dist/retrieval/query-memory.d.ts.map +1 -1
  79. package/dist/retrieval/query-memory.js +623 -62
  80. package/dist/retrieval/query-memory.js.map +1 -1
  81. package/dist/retrieval/semantic-leg.d.ts +74 -0
  82. package/dist/retrieval/semantic-leg.d.ts.map +1 -0
  83. package/dist/retrieval/semantic-leg.js +180 -0
  84. package/dist/retrieval/semantic-leg.js.map +1 -0
  85. package/dist/storage/archive-write.d.ts.map +1 -1
  86. package/dist/storage/archive-write.js +29 -8
  87. package/dist/storage/archive-write.js.map +1 -1
  88. package/dist/storage/capture-router.d.ts +1 -1
  89. package/dist/storage/capture-router.d.ts.map +1 -1
  90. package/dist/storage/capture-router.js +26 -9
  91. package/dist/storage/capture-router.js.map +1 -1
  92. package/dist/storage/consolidation-queue.d.ts +11 -2
  93. package/dist/storage/consolidation-queue.d.ts.map +1 -1
  94. package/dist/storage/consolidation-queue.js +45 -16
  95. package/dist/storage/consolidation-queue.js.map +1 -1
  96. package/dist/storage/corrections.d.ts +185 -6
  97. package/dist/storage/corrections.d.ts.map +1 -1
  98. package/dist/storage/corrections.js +525 -126
  99. package/dist/storage/corrections.js.map +1 -1
  100. package/dist/storage/durable-intent.d.ts.map +1 -1
  101. package/dist/storage/durable-intent.js +24 -1
  102. package/dist/storage/durable-intent.js.map +1 -1
  103. package/dist/storage/filelock.d.ts +84 -12
  104. package/dist/storage/filelock.d.ts.map +1 -1
  105. package/dist/storage/filelock.js +309 -47
  106. package/dist/storage/filelock.js.map +1 -1
  107. package/dist/storage/fs-utils.d.ts +20 -0
  108. package/dist/storage/fs-utils.d.ts.map +1 -1
  109. package/dist/storage/fs-utils.js +27 -0
  110. package/dist/storage/fs-utils.js.map +1 -1
  111. package/dist/storage/paths.d.ts +34 -0
  112. package/dist/storage/paths.d.ts.map +1 -1
  113. package/dist/storage/paths.js +71 -0
  114. package/dist/storage/paths.js.map +1 -1
  115. package/dist/storage/pending.d.ts +154 -0
  116. package/dist/storage/pending.d.ts.map +1 -0
  117. package/dist/storage/pending.js +454 -0
  118. package/dist/storage/pending.js.map +1 -0
  119. package/dist/storage/project.d.ts.map +1 -1
  120. package/dist/storage/project.js +68 -16
  121. package/dist/storage/project.js.map +1 -1
  122. package/dist/storage/session-card.d.ts +13 -0
  123. package/dist/storage/session-card.d.ts.map +1 -1
  124. package/dist/storage/session-card.js +34 -3
  125. package/dist/storage/session-card.js.map +1 -1
  126. package/dist/storage/unclaimed.d.ts +165 -0
  127. package/dist/storage/unclaimed.d.ts.map +1 -0
  128. package/dist/storage/unclaimed.js +442 -0
  129. package/dist/storage/unclaimed.js.map +1 -0
  130. package/dist/storage/working-memory.d.ts.map +1 -1
  131. package/dist/storage/working-memory.js +19 -1
  132. package/dist/storage/working-memory.js.map +1 -1
  133. package/dist/supabase/recall-backend.d.ts +29 -2
  134. package/dist/supabase/recall-backend.d.ts.map +1 -1
  135. package/dist/supabase/recall-backend.js +231 -29
  136. package/dist/supabase/recall-backend.js.map +1 -1
  137. package/dist/supabase/sync.d.ts.map +1 -1
  138. package/dist/supabase/sync.js +13 -0
  139. package/dist/supabase/sync.js.map +1 -1
  140. package/dist/tools-logic/alignment-check.js +1 -1
  141. package/dist/tools-logic/alignment-check.js.map +1 -1
  142. package/dist/tools-logic/awareness-update.d.ts.map +1 -1
  143. package/dist/tools-logic/awareness-update.js +25 -16
  144. package/dist/tools-logic/awareness-update.js.map +1 -1
  145. package/dist/tools-logic/check-action.js +1 -1
  146. package/dist/tools-logic/check-action.js.map +1 -1
  147. package/dist/tools-logic/check.d.ts +55 -1
  148. package/dist/tools-logic/check.d.ts.map +1 -1
  149. package/dist/tools-logic/check.js +230 -57
  150. package/dist/tools-logic/check.js.map +1 -1
  151. package/dist/tools-logic/confidence.d.ts +11 -6
  152. package/dist/tools-logic/confidence.d.ts.map +1 -1
  153. package/dist/tools-logic/confidence.js +11 -6
  154. package/dist/tools-logic/confidence.js.map +1 -1
  155. package/dist/tools-logic/context-synthesize.js +2 -2
  156. package/dist/tools-logic/context-synthesize.js.map +1 -1
  157. package/dist/tools-logic/digest-read.js +2 -2
  158. package/dist/tools-logic/digest-read.js.map +1 -1
  159. package/dist/tools-logic/digest-recall.js +1 -1
  160. package/dist/tools-logic/digest-recall.js.map +1 -1
  161. package/dist/tools-logic/insight-promotion.d.ts +1 -1
  162. package/dist/tools-logic/insight-promotion.d.ts.map +1 -1
  163. package/dist/tools-logic/insight-promotion.js +17 -6
  164. package/dist/tools-logic/insight-promotion.js.map +1 -1
  165. package/dist/tools-logic/journal-capture.js +3 -3
  166. package/dist/tools-logic/journal-capture.js.map +1 -1
  167. package/dist/tools-logic/journal-write.js +3 -3
  168. package/dist/tools-logic/journal-write.js.map +1 -1
  169. package/dist/tools-logic/knowledge-write.js +2 -2
  170. package/dist/tools-logic/knowledge-write.js.map +1 -1
  171. package/dist/tools-logic/palace-lint.js +1 -1
  172. package/dist/tools-logic/palace-lint.js.map +1 -1
  173. package/dist/tools-logic/palace-read.js +1 -1
  174. package/dist/tools-logic/palace-read.js.map +1 -1
  175. package/dist/tools-logic/palace-search.js +1 -1
  176. package/dist/tools-logic/palace-search.js.map +1 -1
  177. package/dist/tools-logic/palace-walk.js +3 -3
  178. package/dist/tools-logic/palace-walk.js.map +1 -1
  179. package/dist/tools-logic/palace-write.js +4 -4
  180. package/dist/tools-logic/palace-write.js.map +1 -1
  181. package/dist/tools-logic/predict-correction.js +1 -1
  182. package/dist/tools-logic/predict-correction.js.map +1 -1
  183. package/dist/tools-logic/recall-backend.d.ts +11 -2
  184. package/dist/tools-logic/recall-backend.d.ts.map +1 -1
  185. package/dist/tools-logic/recall-backend.js +2 -2
  186. package/dist/tools-logic/recall-backend.js.map +1 -1
  187. package/dist/tools-logic/resurrect.d.ts.map +1 -1
  188. package/dist/tools-logic/resurrect.js +9 -1
  189. package/dist/tools-logic/resurrect.js.map +1 -1
  190. package/dist/tools-logic/safety-consolidation.d.ts.map +1 -1
  191. package/dist/tools-logic/safety-consolidation.js +32 -30
  192. package/dist/tools-logic/safety-consolidation.js.map +1 -1
  193. package/dist/tools-logic/session-end.d.ts +8 -0
  194. package/dist/tools-logic/session-end.d.ts.map +1 -1
  195. package/dist/tools-logic/session-end.js +51 -13
  196. package/dist/tools-logic/session-end.js.map +1 -1
  197. package/dist/tools-logic/session-start.d.ts +23 -0
  198. package/dist/tools-logic/session-start.d.ts.map +1 -1
  199. package/dist/tools-logic/session-start.js +44 -1
  200. package/dist/tools-logic/session-start.js.map +1 -1
  201. package/dist/tools-logic/smart-recall.d.ts +185 -10
  202. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  203. package/dist/tools-logic/smart-recall.js +364 -60
  204. package/dist/tools-logic/smart-recall.js.map +1 -1
  205. package/dist/tools-logic/store-doctor.d.ts.map +1 -1
  206. package/dist/tools-logic/store-doctor.js +7 -4
  207. package/dist/tools-logic/store-doctor.js.map +1 -1
  208. package/dist/tools-logic/store-repair.js +1 -1
  209. package/dist/tools-logic/store-repair.js.map +1 -1
  210. package/dist/tools-logic/supersession.d.ts +64 -3
  211. package/dist/tools-logic/supersession.d.ts.map +1 -1
  212. package/dist/tools-logic/supersession.js +155 -50
  213. package/dist/tools-logic/supersession.js.map +1 -1
  214. package/dist/types.d.ts +12 -1
  215. package/dist/types.d.ts.map +1 -1
  216. package/dist/types.js +1 -1
  217. package/dist/vector/embedding.d.ts +8 -0
  218. package/dist/vector/embedding.d.ts.map +1 -1
  219. package/dist/vector/embedding.js +8 -0
  220. package/dist/vector/embedding.js.map +1 -1
  221. package/package.json +1 -1
@@ -34,9 +34,12 @@
34
34
  * change on day one." The five formulas smart-recall.ts documents (RRF k=60,
35
35
  * Ebbinghaus, hot-window recency, betaUtility feedback, two-stage fusion) are
36
36
  * split by WHERE they belong in a genuinely reusable pipeline, not merged:
37
- * - RRF (two-stage: applyRRF + fuseCanonical) + hot-window recency:
38
- * pipeline-owned (RANK/FUSE stage below) — generic to any date-bearing,
39
- * multi-tier candidate set, not smart_recall-specific.
37
+ * - RRF (two-stage: applyRRF + fuseCanonical): pipeline-owned (RANK/FUSE
38
+ * stage below) — generic to any multi-tier candidate set, not
39
+ * smart_recall-specific. The hot-window recency boost that used to run
40
+ * here was REMOVED from default ranking by fix4b (2026-09-12) — it
41
+ * survives only behind the explicit `freshnessBias` opt-in; see
42
+ * applyLegacyHotWindowBoost's doc block for the measurements.
40
43
  * - Ebbinghaus decay, palace salience/IDF blend, insight confirmation blend:
41
44
  * pipeline-owned (TOKENIZE+SCORE stage, per-tier) — these ARE the
42
45
  * per-tier strategies the review names.
@@ -171,7 +174,10 @@
171
174
  * grammar to find, within one tier's own already-scored candidate list,
172
175
  * pairs that assert the same fact-key with a different semver value. A
173
176
  * candidate detected as the STALE side of such a pair is DOWN-RANKED
174
- * (multiplicative score penalty, mirroring `applyHotWindowBoost`'s pattern)
177
+ * (multiplicative score penalty; historically mirrored `applyHotWindowBoost`'s
178
+ * pattern — fix4b, 2026-09-12, removed that boost from default ranking
179
+ * [legacy opt-in only, see applyLegacyHotWindowBoost]; the contradiction
180
+ * penalty here is unchanged)
175
181
  * and ANNOTATED (`supersededBy`) — it is NEVER removed from the set. This
176
182
  * closes part of the reconciliation gap `reports/2026-08-18-eval-redteam.md`'s
177
183
  * HIGH-2 finding named (0% of grammar-detectable contradictions were
@@ -239,6 +245,7 @@ import { CONFIDENCE_FLOOR } from "../tools-logic/confidence.js";
239
245
  import { scrubForCloud, fenceMemory } from "../storage/content-guard.js";
240
246
  import { isRescueSourcedContent, extractFrontmatterSource } from "../helpers/journal-filter.js";
241
247
  import { getLegacyRoot } from "../types.js";
248
+ import { embeddingsEnabled } from "../embeddings/config.js";
242
249
  import * as fs from "node:fs";
243
250
  import * as path from "node:path";
244
251
  // ---------------------------------------------------------------------------
@@ -272,6 +279,112 @@ function keywordExactness(query, text) {
272
279
  const matches = expandedQuery.filter((w) => textSet.has(w) || textLower.includes(w));
273
280
  return Math.min(1.0, matches.length / rawWords.length);
274
281
  }
282
+ // ---------------------------------------------------------------------------
283
+ // fix4 S5 (2026-09-11, reports/agentrecall-fix4-retrieval-2026-09-11.md):
284
+ // BM25-lite IDF, pure local, computed IN-PASS over the already-scanned
285
+ // candidate corpus. Before this, `keywordExactness` weighted every query
286
+ // token equally, so ubiquitous tokens ("version", "push") matched everything
287
+ // and drowned the rare discriminative ones ("semver") — the S2-standard
288
+ // eval's no-IDF finding. No persistence, no new dependency: DF is counted
289
+ // over the texts the tier scorer has ALREADY read for this query.
290
+ // ---------------------------------------------------------------------------
291
+ /** The BM25 IDF curve — the one shared formula every tier's IDF pass uses.
292
+ * Always > 0 (the +0.5 smoothing keeps df == n above zero), monotonically
293
+ * decreasing in df. */
294
+ function bm25Idf(df, n) {
295
+ return Math.log(1 + (n - df + 0.5) / (df + 0.5));
296
+ }
297
+ /**
298
+ * Build the per-query IDF model from the scanned corpus. Weights are per
299
+ * RAW query word (a word matches if ANY of its stem/synonym variants
300
+ * matches — same containment semantics as `keywordExactness`), BM25-curved
301
+ * over document frequency, then max-normalized to [0, 1] so the weighted
302
+ * exactness stays on the same scale the unweighted ratio lived on.
303
+ *
304
+ * TWO deliberate semantic differences from `keywordExactness`, both
305
+ * per-word SATURATION (independent review M3, 2026-09-11 — this comment's
306
+ * first cut overclaimed "degenerate cases reproduce pre-IDF behavior
307
+ * exactly", which is only true when additionally no word matches via more
308
+ * than one variant and no raw word repeats):
309
+ * 1. A raw word contributes its weight AT MOST ONCE, however many of its
310
+ * stem/synonym variants match ("push" matching both "deploy" and
311
+ * "release" in one text counted twice pre-IDF, capped at min(1, ·)).
312
+ * 2. Duplicate raw query words collapse to one weighted entry
313
+ * (`variantsByRaw` is keyed by word) instead of inflating the
314
+ * denominator.
315
+ * Both are the BM25 saturation stance — evidence for the same query word
316
+ * repeats, it doesn't multiply — pinned by this tranche's mechanism tests.
317
+ *
318
+ * DF and the match predicate use the SAME containment semantics
319
+ * (independent review M4, same day): each corpus doc is tokenized+stemmed
320
+ * once into a Set, and a word counts toward df if any variant hits the
321
+ * doc's stemmed-token set OR its lowercase text — identical to
322
+ * `weightedExactness`'s own predicate below. (The first cut counted df by
323
+ * substring only, so a word matching every doc via stemming — "queries" vs
324
+ * stem "query" — could keep df≈0 and a falsely-maximal weight.)
325
+ *
326
+ * CJK: `tokenizeWords` already segments Han runs, and DF/matching include
327
+ * substring containment (script-agnostic), so a rare Han token earns
328
+ * exactly the same discriminative weight as a rare ASCII one.
329
+ */
330
+ function buildIdfModel(query, corpusTexts) {
331
+ const rawWords = tokenizeWords(query);
332
+ const variantsByRaw = new Map();
333
+ for (const w of rawWords) {
334
+ if (variantsByRaw.has(w))
335
+ continue;
336
+ const variants = new Set([w]);
337
+ for (const v of expandQuery([w]))
338
+ variants.add(v);
339
+ variantsByRaw.set(w, [...variants]);
340
+ }
341
+ const n = corpusTexts.length;
342
+ const docs = corpusTexts.map((t) => {
343
+ const lower = t.toLowerCase();
344
+ return { lower, tokenSet: new Set(tokenizeWords(t).map((tok) => stem(tok))) };
345
+ });
346
+ const idf = new Map();
347
+ let maxIdf = 0;
348
+ for (const [w, variants] of variantsByRaw) {
349
+ let df = 0;
350
+ for (const d of docs) {
351
+ if (variants.some((v) => d.tokenSet.has(v) || d.lower.includes(v)))
352
+ df++;
353
+ }
354
+ const weight = n > 0 ? bm25Idf(df, n) : 1;
355
+ idf.set(w, weight);
356
+ if (weight > maxIdf)
357
+ maxIdf = weight;
358
+ }
359
+ if (maxIdf > 0) {
360
+ for (const [w, v] of idf)
361
+ idf.set(w, v / maxIdf);
362
+ }
363
+ else {
364
+ for (const w of idf.keys())
365
+ idf.set(w, 1);
366
+ }
367
+ const totalMass = [...idf.values()].reduce((a, b) => a + b, 0);
368
+ return {
369
+ weightedExactness(text) {
370
+ if (rawWords.length === 0)
371
+ return 0;
372
+ const textSet = new Set(tokenizeWords(text).map((t) => stem(t)));
373
+ const textLower = text.toLowerCase();
374
+ let matchedMass = 0;
375
+ let matchedCount = 0;
376
+ for (const [w, variants] of variantsByRaw) {
377
+ if (variants.some((v) => textSet.has(v) || textLower.includes(v))) {
378
+ matchedMass += idf.get(w) ?? 0;
379
+ matchedCount++;
380
+ }
381
+ }
382
+ if (totalMass <= 0)
383
+ return Math.min(1, matchedCount / rawWords.length);
384
+ return Math.min(1, matchedMass / totalMass);
385
+ },
386
+ };
387
+ }
275
388
  /**
276
389
  * Simple stable hash for result IDs — ported verbatim from smart-recall.ts.
277
390
  *
@@ -362,6 +475,25 @@ function lineMatchesQuery(line, keywords) {
362
475
  // plan's recency-ledger / working-memory-live / session-card rows) joins
363
476
  // this set WHEN its scorer is built to populate `projects`/an equivalent
364
477
  // attribution field on its QueryMemoryItems — not before.
478
+ //
479
+ // v4 W3 CORRECTION (2026-09-08): the design memo's own Wave 3 table cell
480
+ // reads "wire into SCOPE_ATTRIBUTED_TIERS (corrections are project-scoped)"
481
+ // but "project-scoped" there means the OPPOSITE of what membership in this
482
+ // Set requires. `readCorrectionCandidates` (retrieval/candidates.ts) calls
483
+ // `readActiveCorrections(project)`, which only ever reads THAT project's
484
+ // own `corrections/` directory (`projectSubPath(project, "corrections")`)
485
+ // -- exactly the same "inherently per-slug, nothing cross-project to
486
+ // filter" property this comment already documents for journal/palace-room
487
+ // above, and `CorrectionRecord` carries no `projects: string[]`
488
+ // attribution field at all. Per this Set's own stated purpose ("only these
489
+ // tiers' items carry a genuine, POPULATED `projects` attribution"),
490
+ // corrections must be EXCLUDED, same as journal/palace-room -- adding it
491
+ // would wrongly exclude every corrections item under scope:"project" (an
492
+ // absent `projects` field reads as "unattributed", not "trivially this
493
+ // project's own"). This resolves the wave brief's own CHALLENGE (c)
494
+ // ("scope: corrections are per-project on disk -> scope stage no-op (like
495
+ // journal/palace) -- confirm") in favor of that literal confirmation, over
496
+ // the memo's one-line parenthetical.
365
497
  const SCOPE_ATTRIBUTED_TIERS = new Set(["insight"]);
366
498
  // ---------------------------------------------------------------------------
367
499
  // CONTRADICTION stage (Wave 5a, 2026-08-31) — runs per-tier, AFTER
@@ -381,6 +513,17 @@ const SCOPE_ATTRIBUTED_TIERS = new Set(["insight"]);
381
513
  // branch inside `applyContradictionStage`) keeps that decision explicit and
382
514
  // enumerable rather than an implicit side effect of insight items lacking a
383
515
  // `date` field.
516
+ // v4 W3 (2026-09-08): "corrections" deliberately NOT added here (wave
517
+ // brief CHALLENGE (d), pre-resolved, not re-litigated) -- corrections
518
+ // already have their OWN, more precise supersession machinery
519
+ // (`CorrectionRecord.active`/`superseded_by`, `retractCorrection()`), an
520
+ // explicit human/agent action rather than a grammar guess. Running this
521
+ // stage's version-token comparator over corrections text would be a
522
+ // strictly WORSE signal for a tier that already has ground truth for "is
523
+ // this rule current" -- and `readCorrectionCandidates` never surfaces a
524
+ // retracted record in the first place (see that reader's own doc comment),
525
+ // so there is nothing stale for this stage to find within the corrections
526
+ // tier's own candidate set even in principle.
384
527
  const CONTRADICTION_TIERS = new Set(["journal", "palace"]);
385
528
  /**
386
529
  * ANNOTATE-ONLY (pre-ship red-team fix, STEP 4a, 2026-09-01, wave/pipe-w5fix
@@ -530,7 +673,9 @@ function readLegacyJournalCandidates(project) {
530
673
  continue;
531
674
  let files;
532
675
  try {
533
- files = fs.readdirSync(legacyJournal).filter((f) => f.endsWith(".md"));
676
+ // fix4 (2026-09-11): same generated-index / reserved-namespace
677
+ // exclusion as candidates.ts's journal halves (see that file).
678
+ files = fs.readdirSync(legacyJournal).filter((f) => f.endsWith(".md") && f !== "index.md" && !f.startsWith("_"));
534
679
  }
535
680
  catch {
536
681
  continue;
@@ -579,9 +724,22 @@ function scoreJournalTier(project, query, opts) {
579
724
  const sinceCutoff = opts.since ? parseSinceDate(opts.since) : null;
580
725
  const limit = opts.perTierLimit ?? 25;
581
726
  const hits = [];
727
+ // fix4 S3 (2026-09-11, reports/agentrecall-fix4-retrieval-2026-09-11.md):
728
+ // SCORE-THEN-TRUNCATE. The pre-fix4 loop broke out at `hits.length >=
729
+ // limit` while iterating candidates in date-DESCENDING order — i.e. it
730
+ // truncated by RECENCY before any hit was ever scored, so an old entry
731
+ // matching the query strongly was dropped UNSCORED whenever `limit`
732
+ // weaker-but-newer line matches existed (the S2-standard eval's latent
733
+ // "journal recency pre-truncation" defect; the W2 sort-before-truncate
734
+ // work made the pre-truncation deterministic, not correct). Now every
735
+ // matching line across every candidate is collected and SCORED
736
+ // (recency×0.5 + exactness×0.5, unchanged formula), and `limit` is
737
+ // applied to the score-sorted list at the end — one truncation criterion,
738
+ // the same one RRF ranking uses. Cost: the full line scan always runs
739
+ // (previously it stopped early once `limit` hits were found) — bounded by
740
+ // the same already-read candidate set, and measured within the S11
741
+ // latency budget by this tranche's eval runs.
582
742
  for (const candidate of candidates) {
583
- if (hits.length >= limit)
584
- break;
585
743
  if (sinceCutoff && candidate.date) {
586
744
  const fileDate = new Date(candidate.date);
587
745
  if (!isNaN(fileDate.getTime()) && fileDate < sinceCutoff)
@@ -590,8 +748,6 @@ function scoreJournalTier(project, query, opts) {
590
748
  const lines = candidate.content.split("\n");
591
749
  let currentSection = "top";
592
750
  for (let i = 0; i < lines.length; i++) {
593
- if (hits.length >= limit)
594
- break;
595
751
  const line = lines[i];
596
752
  if (line.startsWith("## ")) {
597
753
  currentSection = line.slice(3).trim().toLowerCase().replace(/\s+/g, "_");
@@ -610,6 +766,14 @@ function scoreJournalTier(project, query, opts) {
610
766
  hits.push({ title: `${date} / ${currentSection}`, excerpt, date, line: i + 1 });
611
767
  }
612
768
  }
769
+ // fix4 S5: IDF over the scanned journal corpus (one doc = one journal
770
+ // file's content) — weights each query word by rarity before the
771
+ // unchanged recency*0.5 + exactness*0.5 blend below. Review L2
772
+ // (2026-09-11): skipped entirely when nothing matched — building the
773
+ // model tokenizes/lowercases the whole corpus, pure waste at zero hits.
774
+ if (hits.length === 0)
775
+ return [];
776
+ const idfModel = buildIdfModel(query, candidates.map((c) => c.content));
613
777
  const items = hits.map((h) => {
614
778
  // Independent review fix (W3b, 2026-08-30): `id` must be unique PER HIT,
615
779
  // not per (date,section) — `applyRRF` (below) groups same-tier items by
@@ -630,12 +794,26 @@ function scoreJournalTier(project, query, opts) {
630
794
  const id = stableId("journal", `${h.title}::${h.line}::${h.excerpt}`);
631
795
  const days = daysSince(h.date);
632
796
  const recency = ebbinghaus(days, EBBINGHAUS_S.journal);
633
- const exactness = keywordExactness(query, h.excerpt);
797
+ const exactness = idfModel.weightedExactness(h.excerpt);
634
798
  const internalScore = recency * 0.5 + exactness * 0.5;
635
799
  return { id, source: "journal", title: h.title, excerpt: h.excerpt, score: internalScore, date: h.date, line: h.line };
636
800
  });
637
801
  items.sort((a, b) => b.score - a.score);
638
- return items;
802
+ // fix4 S4-completion: one (date, section) -> one competitive slot, best
803
+ // line wins (items are already score-sorted, so first-seen per title is
804
+ // the best) — opt-in, see QueryMemoryInput.journal.perSectionDedupe.
805
+ let deduped = items;
806
+ if (opts.perSectionDedupe) {
807
+ const seenSections = new Set();
808
+ deduped = items.filter((it) => {
809
+ if (seenSections.has(it.title))
810
+ return false;
811
+ seenSections.add(it.title);
812
+ return true;
813
+ });
814
+ }
815
+ // fix4 S3: truncate AFTER scoring+sorting — see the loop comment above.
816
+ return deduped.slice(0, limit);
639
817
  }
640
818
  /** Palace tier: ported from palace-search.ts's tagBonus + per-line matching +
641
819
  * IDF re-scoring, operating on already-fetched room-file MemoryCandidates
@@ -643,7 +821,7 @@ function scoreJournalTier(project, query, opts) {
643
821
  * smart-recall.ts's original `internalScore = keyScore*0.65 + salience*0.35`.
644
822
  * TRUST-FILTERED before any of this runs — CLOSES the known gap
645
823
  * documented in this file's header, CHALLENGE (b). */
646
- function scorePalaceTier(project, query, opts) {
824
+ async function scorePalaceTier(project, query, opts) {
647
825
  // Matches palace-search.ts's own first executable step — scaffolds the
648
826
  // palace dir + default rooms (writing each default room's `_room.json`) on
649
827
  // first touch. Without this, `listRooms()` (both here and inside
@@ -719,30 +897,32 @@ function scorePalaceTier(project, query, opts) {
719
897
  roomsWithHits.add(room);
720
898
  }
721
899
  }
722
- // IDF re-scoring — ported verbatim from palace-search.ts's Fix RC3.
723
- if (hits.length > 0) {
724
- const totalDocs = new Set(hits.map((h) => `${h.room}/${h.file}`)).size;
725
- const docFreq = new Map();
726
- for (const h of hits) {
727
- const docId = `${h.room}/${h.file}`;
728
- const combined = (h.excerpt + " " + h.room + " " + h.file).toLowerCase();
729
- for (const w of queryWords) {
730
- if (combined.includes(w)) {
731
- if (!docFreq.has(w))
732
- docFreq.set(w, new Set());
733
- docFreq.get(w).add(docId);
734
- }
735
- }
736
- }
900
+ // IDF re-scoring — structure ported from palace-search.ts's Fix RC3;
901
+ // fix4 S5 (2026-09-11): DF is now counted over the SCANNED CANDIDATE
902
+ // CORPUS (every room file this call already read: full content + room +
903
+ // filename), not over the hit set. Hits-only DF was self-referential —
904
+ // any doc containing a query word IS a hit for that word, so a word's
905
+ // rarity was measured against only the documents that matched it (e.g. a
906
+ // word appearing solely in skipped heading lines contributed nothing),
907
+ // systematically flattening the very signal IDF exists to provide. The
908
+ // idf curve itself moves to the shared `bm25Idf` (the one formula every
909
+ // fix4 tier uses); the 0.70/0.30 idf/raw blend and per-hit matched-word
910
+ // semantics are unchanged.
911
+ if (hits.length > 0 && candidates.length > 0) {
912
+ const corpusDocs = candidates.map((c) => (c.content + " " + (c.room ?? "") + " " + c.file).toLowerCase());
737
913
  const idfRaw = new Map();
738
914
  for (const w of queryWords) {
739
- const df = docFreq.get(w)?.size ?? 0;
740
- idfRaw.set(w, Math.log(1 + totalDocs / (df + 1)));
915
+ let df = 0;
916
+ for (const doc of corpusDocs) {
917
+ if (doc.includes(w))
918
+ df++;
919
+ }
920
+ idfRaw.set(w, bm25Idf(df, corpusDocs.length));
741
921
  }
742
- const maxIdf = Math.max(1, ...Array.from(idfRaw.values()));
922
+ const maxIdf = Math.max(...Array.from(idfRaw.values()), 0);
743
923
  const idf = new Map();
744
924
  for (const [w, v] of idfRaw)
745
- idf.set(w, v / maxIdf);
925
+ idf.set(w, maxIdf > 0 ? v / maxIdf : 1);
746
926
  for (const h of hits) {
747
927
  const combined = (h.excerpt + " " + h.room + " " + h.file).toLowerCase();
748
928
  const matchedIdfWords = queryWords.filter((w) => combined.includes(w));
@@ -756,10 +936,38 @@ function scorePalaceTier(project, query, opts) {
756
936
  // (once per room that contributed >=1 hit).
757
937
  for (const room of roomsWithHits) {
758
938
  try {
759
- recordAccess(project, room);
939
+ await recordAccess(project, room);
760
940
  }
761
941
  catch { /* best-effort, never block scoring on a bookkeeping write */ }
762
942
  }
943
+ // fix4 S4-completion (2026-09-11, diagnosed in-tranche, reports/
944
+ // agentrecall-fix4-retrieval-2026-09-11.md): ONE DOCUMENT, ONE VOTE.
945
+ // Palace item ids are stableId("palace", `${room}/${file}`) — identical
946
+ // for every matching LINE of the same file — so applyRRF's per-id
947
+ // accumulation summed one 1/(60+rank) contribution PER LINE into a single
948
+ // entry. A long, frequently-touched catch-all file (goals/evolution)
949
+ // matching a couple of ubiquitous query words on 30-40 lines reached
950
+ // fused scores of 0.44-0.71 against 0.0164 for a genuinely-relevant
951
+ // single-line match — rank 1 in 15/20 golden queries measured at
952
+ // baseline. Line COUNT tracks document length, not relevance (the signal
953
+ // class BM25's TF-saturation caps); S4's weight rebalance alone could not
954
+ // fix this because the design's stated mechanism (salience) was only the
955
+ // minor leg. Fix: reduce hits to the BEST-scoring line per document
956
+ // before materializing items, so RRF sees exactly one vote per document
957
+ // and the surfaced excerpt is always the document's strongest evidence.
958
+ // This also structurally retires the W3b-documented palace id-collision
959
+ // (two same-file hits can no longer meet applyRRF) and the accidental
960
+ // score inflation helpers/associative-link.ts depended on — its
961
+ // similarity threshold is recalibrated in the same change (see
962
+ // linkToSimilar's own comment).
963
+ const bestByDoc = new Map();
964
+ for (const h of hits) {
965
+ const key = `${h.room}/${h.file}`;
966
+ const cur = bestByDoc.get(key);
967
+ if (!cur || h.keywordScore > cur.keywordScore)
968
+ bestByDoc.set(key, h);
969
+ }
970
+ const docHits = [...bestByDoc.values()];
763
971
  const limit = opts.perTierLimit ?? 40; // matches smart-recall's `limit*2` request to palaceSearch
764
972
  // Score ALL hits first, sort by the SAME internal score used for RRF
765
973
  // ranking, THEN truncate — a single consistent truncation criterion.
@@ -768,34 +976,35 @@ function scorePalaceTier(project, query, opts) {
768
976
  // smart-recall.ts re-scores by keyScore*0.65+salienceFloor*0.35 for its own
769
977
  // ranking; this collapses that two-stage, two-criteria truncation into one,
770
978
  // a characterized simplification, not a regression — see this file's header.)
771
- const items = hits.map((h) => {
979
+ const items = docHits.map((h) => {
772
980
  const title = `${h.room}/${h.file}`;
773
- // NOTE (W3b, 2026-08-30 — deliberately NOT fixed this wave, see the
774
- // report's resurrect/harness-scope section): `title` alone
775
- // (`${room}/${file}`) is not unique per hit, and shares the EXACT SAME
776
- // applyRRF-collision class scoreJournalTier's own fix just above closes
777
- // (see that comment for the mechanism) — two distinct matching lines in
778
- // the SAME room file collide in applyRRF's per-tier id-Map today,
779
- // silently discarding one's excerpt while accumulating both hits' RRF
780
- // contribution into whichever one survives. Unlike the journal case,
781
- // this defect is PRE-EXISTING (live in smart_recall's palace tier since
782
- // Wave 2) and OUT OF W3b's scope (journalSearch/recallInsight only) —
783
- // and, verified while investigating this wave's own journal fix, giving
784
- // palace items the same per-hit-unique id REMOVES an (accidental,
785
- // never-intended) score-inflation side effect of this same bug that
786
- // helpers/associative-link.ts's `linkToSimilar` — an entirely different
787
- // subsystem this wave does not touch — happens to depend on for its
788
- // hardcoded `score > 0.03` similarity threshold
789
- // (associative-link.test.mjs's "linkToSimilar creates bidirectional
790
- // edges..." fails if this is fixed in isolation, because each hit's own
791
- // un-inflated RRF contribution, ~0.016, is genuinely below that
792
- // threshold). Fixing this properly needs a decision about
793
- // linkToSimilar's OWN threshold calibration, not a query-memory.ts-only
794
- // change — flagged in the Wave 3b report for the orchestrator, not
795
- // silently fixed or silently left undocumented.
981
+ // W3b HISTORY (2026-08-30) + fix4 RESOLUTION (2026-09-11): `title`
982
+ // (`${room}/${file}`) was not unique per HIT, so two matching lines of
983
+ // the same room file collided in applyRRF's per-tier id-Map —
984
+ // accumulating both hits' RRF contributions into one entry (the
985
+ // mega-file dominance mechanism the S4-completion comment above
986
+ // documents) while discarding the loser's excerpt. W3b flagged the fix
987
+ // as blocked on a linkToSimilar threshold-calibration decision; fix4
988
+ // resolves it the OTHER way around — items are now one-per-DOCUMENT
989
+ // (`docHits`, best line as evidence), for which this id is genuinely
990
+ // unique, and linkToSimilar's threshold is recalibrated to the
991
+ // un-inflated score scale in the same change (see that function's own
992
+ // comment).
796
993
  const id = stableId("palace", title);
797
994
  const salience = Math.max(0.4, salienceByRoom.get(h.room) ?? 0.5);
798
- const internalScore = h.keywordScore * 0.65 + salience * 0.35;
995
+ // fix4 S4 (2026-09-11, reports/agentrecall-fix4-retrieval-2026-09-11.md):
996
+ // relevance-over-salience rebalance, 0.65/0.35 -> 0.90/0.10. Under the
997
+ // old weights the maximum salience differential (0.35 × (1.0 − 0.4
998
+ // floor) = 0.21) exceeded typical keyword-score deltas between a
999
+ // topically-right room and a high-traffic catch-all room — the
1000
+ // S2-standard eval measured the goals/evolution mega-room taking rank 1
1001
+ // in 15/20 golden queries across 8 projects on salience alone. At
1002
+ // 0.10 the salience spread caps at 0.06: enough to break genuine
1003
+ // relevance ties (its documented role — see the S4b mechanism test),
1004
+ // never enough to overturn a >=0.07 keyword advantage. Query relevance
1005
+ // now dominates the palace tier's internal ordering the same way it
1006
+ // already dominates every other tier's.
1007
+ const internalScore = h.keywordScore * 0.90 + salience * 0.10;
799
1008
  const datePattern = h.excerpt.match(/(\d{4}-\d{2}-\d{2})/);
800
1009
  return {
801
1010
  id,
@@ -873,19 +1082,207 @@ function scoreInsightTier(project, query, opts) {
873
1082
  items.sort((a, b) => b.score - a.score);
874
1083
  return items;
875
1084
  }
876
- function applyRRF(rankedItems, rrfMap) {
1085
+ /**
1086
+ * Corrections tier (v4 W3, 2026-09-08, reports/2026-09-08-v4-w3-corrections-
1087
+ * tier-report.md; design authority reports/2026-09-08-v4-claims-design-
1088
+ * memo.md Wave 3). Follows the SAME FETCH -> TRUST-FILTER -> TOKENIZE+SCORE
1089
+ * shape every other MemoryCandidate-backed tier above already follows:
1090
+ * `readCorrectionCandidates` (retrieval/candidates.ts) is the FETCH stage;
1091
+ * `filterTrusted` is the mandatory TRUST-FILTER stage, run UNCONDITIONALLY
1092
+ * here even though every corrections candidate is `untrusted: false` by
1093
+ * construction (see that reader's own doc comment) — this tier is not
1094
+ * special-cased out of the mandatory stage just because it happens to be a
1095
+ * no-op today; matching every sibling tier's own call shape keeps that
1096
+ * true structurally, not by omission.
1097
+ *
1098
+ * SCORING (fix4 S1, 2026-09-11, reports/agentrecall-fix4-retrieval-2026-09-11.md):
1099
+ * matches on rule+context text via the shared tokenizer (`keywordExactness`
1100
+ * — the SAME helper `scorePalaceTier`/`scoreInsightTier` already use above),
1101
+ * blended with the record's own IMPORTANCE/EVIDENCE signals, mirroring the
1102
+ * insight tier's shape (`relevance*0.40 + exactness*0.35 + confirmation*0.25`
1103
+ * — see `scoreInsightTier` above):
1104
+ *
1105
+ * internalScore = exactness*0.70 + severityBoost*0.15 + proofBoost*0.15
1106
+ * severityBoost: p0 -> 1.0, p1 -> 0.5 (P0-ness reuses the EXISTING
1107
+ * `severity` field, not a parallel signal)
1108
+ * proofBoost: min(1, log2(proof_count+1)/3) — byte-identical to the
1109
+ * insight tier's `confirmed_count` curve; proof_count is the
1110
+ * corrections ledger's own on-write consolidation counter.
1111
+ *
1112
+ * Relevance DOMINATES (0.70): severity/proof can reorder near-equal matches
1113
+ * but can never surface a non-matching record (zero-keyword candidates are
1114
+ * skipped before scoring) nor lift a weak match past a strong one by more
1115
+ * than 0.30. NON-TIME-DECAYING like the insight tier: no recency/decay term
1116
+ * — an April rule and a September rule with equal relevance score equally
1117
+ * (a correction is a standing rule, not an episodic memory).
1118
+ *
1119
+ * `confidence`/`decayClass` remain ANNOTATION ONLY on the returned item —
1120
+ * per the design memo's own repeated finding, rejected TWICE independently
1121
+ * (the July 2 proposal's Option 2, and W5fix's removal of
1122
+ * `CONTRADICTION_PENALTY`, both for the identical stated reason: blending a
1123
+ * confidence/STALENESS signal into a ranking score hides WHY an item
1124
+ * dropped and risks a silent rank inversion) — `internalScore` below never
1125
+ * reads either field. severity/proof_count are a DIFFERENT class of signal
1126
+ * (importance/evidence, same class as the insight tier's already-scored
1127
+ * `confirmed_count`), not belief-confidence or staleness — the invariant
1128
+ * those two rejections protect is preserved, not relaxed.
1129
+ *
1130
+ * `id` is the correction's OWN real, stable `CorrectionRecord.id`
1131
+ * (`meta.correction_id`) — deliberately NOT a `stableId()` hash like every
1132
+ * other tier mints. A correction already has a durable, globally-unique
1133
+ * identity that corrections.ts's own API (`retractCorrection`/
1134
+ * `recordOutcome`) keys off directly; reusing it here means a caller acting
1135
+ * on a surfaced correction never needs a secondary id lookup.
1136
+ */
1137
+ /** Review L3 (2026-09-11): enumerated severity ladder for the corrections
1138
+ * scorer — extending coverage is a new ROW here, never a new branch. */
1139
+ const SEVERITY_BOOST = {
1140
+ p0: 1.0,
1141
+ p1: 0.5,
1142
+ p2: 0.25,
1143
+ p3: 0.1,
1144
+ };
1145
+ function scoreCorrectionsTier(project, query, opts) {
1146
+ const candidates = filterTrusted(readTierCandidates("corrections", project, { includeUntrusted: true }));
1147
+ const keywords = tokenizeWords(query);
1148
+ if (keywords.length === 0)
1149
+ return [];
1150
+ const limit = opts.perTierLimit ?? 25;
1151
+ // fix4 S5: IDF over the scanned corrections corpus (one doc = one
1152
+ // record's rule+context match text) — materialized once, before the
1153
+ // match/score loop, so DF covers ALL scanned records, not just matches.
1154
+ const matchTexts = candidates.map((candidate) => {
1155
+ const context = candidate.meta?.context ?? "";
1156
+ return context ? `${candidate.content}\n${context}` : candidate.content;
1157
+ });
1158
+ const idfModel = buildIdfModel(query, matchTexts);
1159
+ const items = [];
1160
+ for (let ci = 0; ci < candidates.length; ci++) {
1161
+ const candidate = candidates[ci];
1162
+ const meta = candidate.meta ?? {};
1163
+ const matchText = matchTexts[ci];
1164
+ const matchTextLower = matchText.toLowerCase();
1165
+ if (!keywords.some((kw) => matchTextLower.includes(kw)))
1166
+ continue;
1167
+ const exactness = idfModel.weightedExactness(matchText);
1168
+ // fix4 S1: severity/proof_count-aware blend — see this function's doc
1169
+ // comment for the formula and the annotation-only invariant it preserves.
1170
+ // Review L3 (2026-09-11): the ladder is an enumerated CLASS table —
1171
+ // CorrectionRecord.severity types only p0|p1, but legacy on-disk records
1172
+ // carry p2/p3 (corrections.ts severityRank handles them); a binary
1173
+ // p0-else check silently flattened those onto p1. Unknown values score
1174
+ // as p1 (the type's own default tier).
1175
+ const severityBoost = SEVERITY_BOOST[meta.severity ?? "p1"] ?? SEVERITY_BOOST.p1;
1176
+ const proofCount = Math.max(1, parseInt(meta.proof_count ?? "1", 10) || 1);
1177
+ const proofBoost = Math.min(1.0, Math.log2(proofCount + 1) / 3);
1178
+ const internalScore = exactness * 0.70 + severityBoost * 0.15 + proofBoost * 0.15;
1179
+ const excerpt = matchText.length > 300 ? matchText.slice(0, 300) + "..." : matchText;
1180
+ const title = candidate.content.length > 300 ? candidate.content.slice(0, 300) + "..." : candidate.content;
1181
+ // Fallback (candidate.file sans ".json") only covers the defensive case
1182
+ // where a future caller constructs a MemoryCandidate without `meta` —
1183
+ // every real readCorrectionCandidates() candidate always sets
1184
+ // meta.correction_id.
1185
+ //
1186
+ // ID-SPACE DISJOINTNESS (code-review LOW-1, 2026-09-08): `applyRRF`/
1187
+ // `fuseCanonical` below key their cross-tier accumulation Maps on
1188
+ // `item.id` directly — a collision would silently MERGE two unrelated
1189
+ // items from different tiers (one vanishes from `items`, its RRF score
1190
+ // folds into whichever survives), with no error. This is safe today
1191
+ // because the two id shapes are DISJOINT BY CONSTRUCTION: a correction's
1192
+ // own `record.id` always contains a `YYYY-MM-DD-` prefix (a literal
1193
+ // `-`), while `stableId()` — the hash every OTHER tier mints — is a
1194
+ // hyphen-free base36 string (`Math.abs(hash).toString(36)`, see
1195
+ // `stableId`'s own implementation above). If a future correction ID
1196
+ // grammar ever drops the date prefix (or a future stableId() variant
1197
+ // ever introduces a `-`), this disjointness is no longer guaranteed —
1198
+ // this comment exists so that change gets evaluated against this
1199
+ // invariant, not discovered later as a silent cross-tier dedup bug.
1200
+ const correctionId = meta.correction_id || candidate.file.replace(/\.json$/, "");
1201
+ items.push({
1202
+ id: correctionId,
1203
+ source: "corrections",
1204
+ title,
1205
+ excerpt,
1206
+ score: internalScore,
1207
+ date: candidate.date || undefined,
1208
+ severity: meta.severity,
1209
+ confidence: meta.confidence || undefined,
1210
+ decayClass: meta.decay_class || undefined,
1211
+ });
1212
+ }
1213
+ items.sort((a, b) => b.score - a.score);
1214
+ return items.slice(0, limit);
1215
+ }
1216
+ /**
1217
+ * fix7 (2026-09-12): `weight` (default 1 — every lexical tier) scales one
1218
+ * LEG's rank contributions: `weight / (RRF_K + rank)`. This is weighted
1219
+ * Reciprocal Rank Fusion (the standard multi-leg RRF extension) — still
1220
+ * strictly RANK-based, never raw-score-based, so the incompatible-scale
1221
+ * class (smart-recall.ts Fix 1) cannot recur. Used ONLY by the opt-in
1222
+ * semantic leg (see queryMemory below); its value was chosen by golden-eval
1223
+ * measurement, not tuned per-query (fix7 report's placement/weight matrix).
1224
+ *
1225
+ * fix7 review H2 (2026-09-12): on an id-level fold, LEXICAL FIELDS WIN
1226
+ * regardless of insertion order. The semantic leg fuses BEFORE
1227
+ * palace/journal/insight (its measured tie-band placement), so without this
1228
+ * rule a dual-evidence item would keep the semantic chunk's excerpt/line
1229
+ * (unanchored, chunk-start line → wrong verbatim drill-down) and a
1230
+ * `semantic: true` marker whose documented contract is "semantic-ONLY
1231
+ * discoveries". When a LEXICAL item folds into an entry currently held by a
1232
+ * SEMANTIC-originated item, the entry's `item` is REPLACED by the lexical
1233
+ * one (match-anchored excerpt, real line, no `semantic` marker) while the
1234
+ * accumulated score, the sources set, and — critically — the entry's MAP
1235
+ * POSITION (the tie-break authority) are preserved. Flag-off items never
1236
+ * carry `semantic`, so this branch is structurally unreachable flag-off.
1237
+ */
1238
+ function applyRRF(rankedItems, rrfMap, weight = 1) {
877
1239
  rankedItems.forEach((item, idx) => {
878
1240
  const rank = idx + 1;
879
- const contribution = 1 / (RRF_K + rank);
1241
+ const contribution = weight / (RRF_K + rank);
880
1242
  const existing = rrfMap.get(item.id);
881
1243
  if (existing) {
882
1244
  existing.score += contribution;
1245
+ // fix7 review H2: lexical fields displace semantic-originated fields
1246
+ // on a fold (Map value replacement keeps the entry's insertion
1247
+ // position, so tie-break placement is unaffected). No sources.add
1248
+ // here: semantic items carry NATIVE tier source labels, so a fold is
1249
+ // always same-source — and the flag-off path never folds cross-tier
1250
+ // (id spaces disjoint by construction, see scoreCorrectionsTier).
1251
+ if (existing.item.semantic && !item.semantic) {
1252
+ existing.item = item;
1253
+ }
883
1254
  }
884
1255
  else {
885
1256
  rrfMap.set(item.id, { score: contribution, item, sources: new Set([item.source]) });
886
1257
  }
887
1258
  });
888
1259
  }
1260
+ /**
1261
+ * fix7 semantic-leg fusion parameters — MEASURED on the golden eval
1262
+ * (agentrecall-fix7-embeddings-2026-09-12.md, placement/weight matrix),
1263
+ * not designed a priori. Both only ever apply under the embeddings opt-in.
1264
+ *
1265
+ * - SEMANTIC_RRF_WEIGHT: weighted-RRF multiplier for the semantic leg's
1266
+ * contributions (see applyRRF).
1267
+ * - SEMANTIC_AFTER_CORRECTIONS: when true, the semantic leg's items enter
1268
+ * the fusion map immediately AFTER the corrections tier — at EXACT
1269
+ * fused-score ties they then outrank palace/journal/insight lexical
1270
+ * singles (semantic evidence over incidental keyword overlap) while the
1271
+ * owner's own captured rules keep top tie authority. When false, the
1272
+ * leg inserts last (loses all ties).
1273
+ *
1274
+ * MEASURED (fix7 report, twin-clone golden eval; certified post-review-fix
1275
+ * with the default MiniLM-L12-v2 model):
1276
+ * weight 1.0 + after-corrections → 90.0% hit-rate, 3/5 paraphrase
1277
+ * recovered, ZERO regressions, all six protected hits hold. weight 1.0 +
1278
+ * last placement → a semantic-only golden loses every 1/61 tie (measured
1279
+ * −1 hit on the pre-fix matrix). weight 1.3 / 1.1 (any placement) →
1280
+ * semantic items vault the lexical-single band wholesale and FLOOD top-5
1281
+ * (three regressions, one protected) — weights > 1 are measured-toxic on
1282
+ * this store; do not raise without re-running the full protected battery.
1283
+ */
1284
+ const SEMANTIC_RRF_WEIGHT = 1.0;
1285
+ const SEMANTIC_AFTER_CORRECTIONS = true;
889
1286
  function fuseCanonical(rrfMap) {
890
1287
  const canonical = new Map();
891
1288
  for (const entry of rrfMap.values()) {
@@ -902,7 +1299,49 @@ function fuseCanonical(rrfMap) {
902
1299
  }
903
1300
  return canonical;
904
1301
  }
905
- function applyHotWindowBoost(fusedMap) {
1302
+ // fix4b — hot-window redesign (2026-09-12, reports/agentrecall-fix4b-
1303
+ // hotwindow-2026-09-12.md; diagnosed in reports/agentrecall-fix4-retrieval-
1304
+ // 2026-09-11.md Escalation §1). PRODUCT-BEHAVIOR CHANGE, stated prominently:
1305
+ // no POST-FUSION freshness signal exists on default paths — fused scores are
1306
+ // never freshness-multiplied and ties are freshness-blind. (The journal
1307
+ // tier's INTERNAL Ebbinghaus recency×0.5 blend — a per-tier scoring input,
1308
+ // see scoreJournalTier — is a different mechanism and is unchanged by fix4b.)
1309
+ //
1310
+ // The old `applyHotWindowBoost` multiplied FUSED RRF scores ×3.0/×2.0/×1.3
1311
+ // for items dated <6h/<24h/<72h. But RRF compresses adjacent-rank score
1312
+ // differences to ~1.6% (1/(60+r) vs 1/(61+r)), so ANY multiplier > ~1.02
1313
+ // vaulted an off-topic-but-recent item over every un-boosted on-topic
1314
+ // result — in a store written to daily, every query's top-5 filled with the
1315
+ // last 72h of diary sections regardless of relevance. Measured on the golden
1316
+ // eval as the single largest hit-rate loss (55.0% with the boost, 75.0%
1317
+ // with it neutralized).
1318
+ //
1319
+ // The design brief's PRIMARY redesign (D1) kept freshness as a within-
1320
+ // tie-band reorder: fused score decides the band, hotness (<6h → <24h →
1321
+ // <72h → none) reorders inside a band of exactly-tied scores, then the
1322
+ // authority/insertion order. Measured on the same twin-clone protocol, D1
1323
+ // scored 65.0% — below the 70% exit gate — because post one-doc-one-vote,
1324
+ // cross-TIER exact ties at 1/(60+r) are the common case, and hotness-over-
1325
+ // authority handed those bands to <72h diary lines over the owner's own
1326
+ // captured rules (gq05/gq06 measured casualties). Per the brief's explicit
1327
+ // fallback clause, what ships is FULL NEUTRALIZATION: the default pipeline
1328
+ // applies no post-fusion freshness signal; exact fused-score ties resolve
1329
+ // by the fix4 authority/insertion order alone (corrections first — see
1330
+ // localRecallSearch's `tiers` comment). The legacy multiplicative boost
1331
+ // survives SOLELY behind the explicit `freshnessBias` opt-in below, for the
1332
+ // one audited caller whose downstream score floor requires it. A measured
1333
+ // middle design (authority pinned above hotness inside bands, hotness
1334
+ // ordering the rest) scored per-query identical to neutralization (75.0%)
1335
+ // and is documented in the fix4b report as a future option — deliberately
1336
+ // NOT shipped: the brief sanctioned exactly two designs.
1337
+ /** LEGACY multiplicative boost — the exact pre-fix4b `applyHotWindowBoost`
1338
+ * body (all defects included: date-only strings parse to 00:00 UTC so the
1339
+ * bucket depends on wall-clock time-of-day — audit Finding 2; palace
1340
+ * regex-scraped excerpt dates are trusted as timestamps; recent items vault
1341
+ * entire relevance bands). Kept ONLY behind `QueryMemoryInput.freshnessBias`
1342
+ * (see that field's doc comment for the single audited caller class that
1343
+ * needs it). Never runs on a default-configured query. */
1344
+ function applyLegacyHotWindowBoost(fusedMap) {
906
1345
  for (const entry of fusedMap.values()) {
907
1346
  if (entry.item.date) {
908
1347
  const hoursAgo = (Date.now() - new Date(entry.item.date).getTime()) / (1000 * 60 * 60);
@@ -924,6 +1363,7 @@ const TIER_SCORERS = {
924
1363
  // Matches smart-recall.ts's original `journalSearch({..., limit: Math.ceil(limit*1.5)})`.
925
1364
  perTierLimit: input.journal?.perTierLimit ?? Math.ceil((input.limit ?? 10) * 1.5),
926
1365
  since: input.since,
1366
+ perSectionDedupe: input.journal?.perSectionDedupe,
927
1367
  }),
928
1368
  palace: async (input) => scorePalaceTier(input.project, input.query, {
929
1369
  room: input.palace?.room,
@@ -934,6 +1374,13 @@ const TIER_SCORERS = {
934
1374
  // Matches smart-recall.ts's original `recallInsight({..., limit: limit*2})`.
935
1375
  perTierLimit: input.insight?.perTierLimit ?? (input.limit ?? 10) * 2,
936
1376
  }),
1377
+ // v4 W3 (2026-09-08) — no pre-existing surface's `perTierLimit` convention
1378
+ // to match (corrections is new, unlike journal/palace/insight which each
1379
+ // preserve a pre-pipeline caller's own limit multiplier); 25 mirrors
1380
+ // journal's own default perTierLimit.
1381
+ corrections: async (input) => scoreCorrectionsTier(input.project, input.query, {
1382
+ perTierLimit: input.corrections?.perTierLimit ?? 25,
1383
+ }),
937
1384
  };
938
1385
  export async function queryMemory(input) {
939
1386
  const sourcesQueried = [];
@@ -967,15 +1414,122 @@ export async function queryMemory(input) {
967
1414
  // try/catch isolation.
968
1415
  }
969
1416
  }
970
- // RANK/FUSE stage.
1417
+ // SEMANTIC LEG (fix7, 2026-09-12) — OPT-IN ONLY (AGENT_RECALL_EMBEDDINGS
1418
+ // / config.json embeddings_enabled; read per-call, the RECALL_FUSION
1419
+ // precedent). Flag OFF: this block costs one env check (plus, when the
1420
+ // env var is unset, embeddingsEnabled()'s small mtime-cached config.json
1421
+ // probe) — no index read, no model touch, no semantic module executes,
1422
+ // and the RESULT is byte-identical to fix4b (pinned by
1423
+ // fix7-embeddings.test.mjs's equivalence test). Flag ON: one ADDITIONAL
1424
+ // ranked list joins the same RRF fusion below. The leg's items are
1425
+ // trust-filtered/scoped through the same chokepoints as every lexical
1426
+ // tier (see retrieval/semantic-leg.ts's header — the security property,
1427
+ // adversarially tested) and carry native tier source labels. The dynamic
1428
+ // import keeps this FILE decoupled from the embeddings modules (review
1429
+ // note: the package barrel index.ts re-exports them statically for
1430
+ // CLI/test consumers, so package-level import already parses them — they
1431
+ // are side-effect-free at top level by design; the honest claim is
1432
+ // "never EXECUTES flag-off", not "never loads").
1433
+ let semanticItems;
1434
+ let semanticNote;
1435
+ if (embeddingsEnabled()) {
1436
+ try {
1437
+ const { runSemanticLeg } = await import("./semantic-leg.js");
1438
+ const sem = await runSemanticLeg({
1439
+ query: input.query,
1440
+ project: input.project,
1441
+ // Tier scoping — the leg may only contribute tiers this caller
1442
+ // requested (journalSearch passes tiers:["journal"]; a palace item
1443
+ // leaking into its adapter would corrupt its external contract).
1444
+ tiers: input.tiers,
1445
+ scope: input.scope,
1446
+ since: input.since,
1447
+ room: input.palace?.room,
1448
+ // fix7 review L: no silent param discard — the leg honors the
1449
+ // caller's rollup-archive exclusion the same way the lexical
1450
+ // journal scorer does.
1451
+ includeRollupArchive: input.journal?.includeRollupArchive,
1452
+ });
1453
+ semanticItems = sem.items;
1454
+ semanticNote = sem.note;
1455
+ // fix7 review H1 (2026-09-12): journal id-space JOIN. Palace/insight/
1456
+ // corrections semantic items mint the SAME ids as their lexical twins
1457
+ // (chunker.ts id conventions), so applyRRF folds dual-evidence items
1458
+ // into one entry with summed votes. Journal could not: lexical journal
1459
+ // ids embed line+excerpt (per-hit uniqueness, W3b) and are
1460
+ // unreproducible from a chunk — so a section found by BOTH legs
1461
+ // surfaced as TWO near-duplicate slots with SPLIT votes (defeating
1462
+ // perSectionDedupe cross-leg and under-ranking multi-evidence docs).
1463
+ // Join here, where both sides are in hand: a semantic journal item
1464
+ // adopts the id of the BEST lexical item sharing its exact
1465
+ // "${date} / ${section}" title (both sides construct it identically;
1466
+ // scoreJournalTier returns score-sorted items, so first-seen per
1467
+ // title is the best). The semantic leg emits at most one journal item
1468
+ // per title (docKey = journal/title), so no intra-leg id collision
1469
+ // can result. With applyRRF's lexical-fields-win fold rule (H2), the
1470
+ // merged entry carries the lexical line-anchored excerpt.
1471
+ if (semanticItems.length > 0) {
1472
+ const lexicalJournal = byTier.journal;
1473
+ if (lexicalJournal && lexicalJournal.length > 0) {
1474
+ const bestByTitle = new Map();
1475
+ for (const it of lexicalJournal) {
1476
+ if (!bestByTitle.has(it.title))
1477
+ bestByTitle.set(it.title, it);
1478
+ }
1479
+ semanticItems = semanticItems.map((it) => {
1480
+ if (it.source !== "journal")
1481
+ return it;
1482
+ const lex = bestByTitle.get(it.title);
1483
+ return lex ? { ...it, id: lex.id } : it;
1484
+ });
1485
+ }
1486
+ }
1487
+ }
1488
+ catch (err) {
1489
+ // Defense in depth — runSemanticLeg already never throws; this guard
1490
+ // covers the dynamic import itself. The recall must not fail.
1491
+ semanticNote = {
1492
+ status: "error",
1493
+ model: "unknown",
1494
+ message: err instanceof Error ? err.message : String(err),
1495
+ };
1496
+ }
1497
+ }
1498
+ // RANK/FUSE stage. fix7: the semantic leg joins as one additional
1499
+ // weighted-RRF leg — a same-id item found both ways accumulates
1500
+ // contributions into its lexical entry (multi-evidence, the applyRRF
1501
+ // id-level fold), a semantic-only item enters at the MEASURED map
1502
+ // position (SEMANTIC_AFTER_CORRECTIONS): map insertion order is the
1503
+ // tie-break authority order, so "after corrections" gives semantic items
1504
+ // tie priority over palace/journal/insight lexical singles while the
1505
+ // owner's captured rules keep the top; "last" cedes all ties. Weight and
1506
+ // placement were selected on the golden eval — see the fix7 report's
1507
+ // placement/weight matrix, and applyRRF's doc comment for why weighted
1508
+ // RRF stays rank-based.
971
1509
  const rrfMap = new Map();
1510
+ let semanticFused = false; // idempotence guard — the leg fuses exactly once
1511
+ const fuseSemantic = () => {
1512
+ if (!semanticFused && semanticItems && semanticItems.length > 0) {
1513
+ semanticFused = true;
1514
+ applyRRF(semanticItems, rrfMap, SEMANTIC_RRF_WEIGHT);
1515
+ }
1516
+ };
972
1517
  for (const tier of input.tiers) {
973
1518
  const items = byTier[tier];
974
1519
  if (items)
975
1520
  applyRRF(items, rrfMap);
1521
+ if (SEMANTIC_AFTER_CORRECTIONS && tier === "corrections")
1522
+ fuseSemantic();
976
1523
  }
1524
+ // Last-position placement, and the fallback for tier sets that don't
1525
+ // include corrections at all (e.g. journalSearch's ["journal"]).
1526
+ if (!SEMANTIC_AFTER_CORRECTIONS || !input.tiers.includes("corrections"))
1527
+ fuseSemantic();
977
1528
  const fusedMap = fuseCanonical(rrfMap);
978
- applyHotWindowBoost(fusedMap);
1529
+ // fix4b (2026-09-12): the legacy multiplicative boost runs ONLY behind the
1530
+ // explicit freshnessBias opt-in — see QueryMemoryInput.freshnessBias.
1531
+ if (input.freshnessBias)
1532
+ applyLegacyHotWindowBoost(fusedMap);
979
1533
  const seen = new Set();
980
1534
  const fused = [];
981
1535
  for (const { score, item, sources } of fusedMap.values()) {
@@ -986,11 +1540,18 @@ export async function queryMemory(input) {
986
1540
  const alsoFoundIn = [...sources].filter((s) => s !== item.source);
987
1541
  fused.push({ ...item, score, ...(alsoFoundIn.length > 0 ? { alsoFoundIn } : {}) });
988
1542
  }
1543
+ // fix4b (2026-09-12): the sort is stable, so exact fused-score ties
1544
+ // resolve purely by insertion order — the fix4 authority tie-break
1545
+ // (corrections first). No post-fusion freshness signal touches default
1546
+ // ranking; see the fallback doc block above applyLegacyHotWindowBoost.
989
1547
  fused.sort((a, b) => b.score - a.score);
990
1548
  return {
991
1549
  items: fused,
992
1550
  candidatesBySource,
993
1551
  sourcesQueried,
1552
+ // fix7: present ONLY under the opt-in — flag-off objects are shape-
1553
+ // identical to fix4b's (spread of undefined adds nothing).
1554
+ ...(semanticNote ? { semanticLeg: semanticNote } : {}),
994
1555
  renderFenced(limit) {
995
1556
  const capped = typeof limit === "number" ? fused.slice(0, limit) : fused;
996
1557
  const lines = capped.map((it, i) => `[${i + 1}][${it.source}${it.room ? `/${it.room}` : ""}] ${it.title} — ${it.excerpt}`);