agent-recall-core 3.4.45 → 3.4.47

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 (135) hide show
  1. package/dist/helpers/activity-feed.d.ts.map +1 -1
  2. package/dist/helpers/activity-feed.js +8 -0
  3. package/dist/helpers/activity-feed.js.map +1 -1
  4. package/dist/helpers/handoff.d.ts.map +1 -1
  5. package/dist/helpers/handoff.js +17 -9
  6. package/dist/helpers/handoff.js.map +1 -1
  7. package/dist/helpers/journal-files.d.ts +24 -1
  8. package/dist/helpers/journal-files.d.ts.map +1 -1
  9. package/dist/helpers/journal-files.js +29 -10
  10. package/dist/helpers/journal-files.js.map +1 -1
  11. package/dist/helpers/journal-filter.d.ts +53 -0
  12. package/dist/helpers/journal-filter.d.ts.map +1 -1
  13. package/dist/helpers/journal-filter.js +101 -0
  14. package/dist/helpers/journal-filter.js.map +1 -1
  15. package/dist/index.d.ts +12 -4
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +33 -4
  18. package/dist/index.js.map +1 -1
  19. package/dist/palace/consolidate.d.ts.map +1 -1
  20. package/dist/palace/consolidate.js +10 -0
  21. package/dist/palace/consolidate.js.map +1 -1
  22. package/dist/retrieval/candidates.d.ts +314 -0
  23. package/dist/retrieval/candidates.d.ts.map +1 -0
  24. package/dist/retrieval/candidates.js +321 -0
  25. package/dist/retrieval/candidates.js.map +1 -0
  26. package/dist/retrieval/contradiction.d.ts +232 -0
  27. package/dist/retrieval/contradiction.d.ts.map +1 -0
  28. package/dist/retrieval/contradiction.js +320 -0
  29. package/dist/retrieval/contradiction.js.map +1 -0
  30. package/dist/retrieval/query-memory.d.ts +419 -0
  31. package/dist/retrieval/query-memory.d.ts.map +1 -0
  32. package/dist/retrieval/query-memory.js +1068 -0
  33. package/dist/retrieval/query-memory.js.map +1 -0
  34. package/dist/retrieval/scope.d.ts +75 -0
  35. package/dist/retrieval/scope.d.ts.map +1 -0
  36. package/dist/retrieval/scope.js +91 -0
  37. package/dist/retrieval/scope.js.map +1 -0
  38. package/dist/storage/corrections.d.ts +31 -1
  39. package/dist/storage/corrections.d.ts.map +1 -1
  40. package/dist/storage/corrections.js +34 -1
  41. package/dist/storage/corrections.js.map +1 -1
  42. package/dist/storage/cwd-allowlist.d.ts +58 -0
  43. package/dist/storage/cwd-allowlist.d.ts.map +1 -1
  44. package/dist/storage/cwd-allowlist.js +46 -7
  45. package/dist/storage/cwd-allowlist.js.map +1 -1
  46. package/dist/storage/lifecycle-telemetry.d.ts +20 -5
  47. package/dist/storage/lifecycle-telemetry.d.ts.map +1 -1
  48. package/dist/storage/lifecycle-telemetry.js +16 -5
  49. package/dist/storage/lifecycle-telemetry.js.map +1 -1
  50. package/dist/storage/project.d.ts.map +1 -1
  51. package/dist/storage/project.js +162 -35
  52. package/dist/storage/project.js.map +1 -1
  53. package/dist/storage/recency-index.d.ts +14 -0
  54. package/dist/storage/recency-index.d.ts.map +1 -1
  55. package/dist/storage/recency-index.js.map +1 -1
  56. package/dist/storage/session.d.ts +28 -1
  57. package/dist/storage/session.d.ts.map +1 -1
  58. package/dist/storage/session.js +41 -8
  59. package/dist/storage/session.js.map +1 -1
  60. package/dist/storage/working-memory.d.ts.map +1 -1
  61. package/dist/storage/working-memory.js +10 -1
  62. package/dist/storage/working-memory.js.map +1 -1
  63. package/dist/supabase/recall-backend.d.ts +25 -2
  64. package/dist/supabase/recall-backend.d.ts.map +1 -1
  65. package/dist/supabase/recall-backend.js +82 -21
  66. package/dist/supabase/recall-backend.js.map +1 -1
  67. package/dist/supabase/sync.d.ts +41 -0
  68. package/dist/supabase/sync.d.ts.map +1 -1
  69. package/dist/supabase/sync.js +46 -0
  70. package/dist/supabase/sync.js.map +1 -1
  71. package/dist/tools-logic/check.d.ts.map +1 -1
  72. package/dist/tools-logic/check.js +62 -36
  73. package/dist/tools-logic/check.js.map +1 -1
  74. package/dist/tools-logic/context-synthesize.d.ts.map +1 -1
  75. package/dist/tools-logic/context-synthesize.js +24 -3
  76. package/dist/tools-logic/context-synthesize.js.map +1 -1
  77. package/dist/tools-logic/drill-down.d.ts +24 -0
  78. package/dist/tools-logic/drill-down.d.ts.map +1 -1
  79. package/dist/tools-logic/drill-down.js +36 -0
  80. package/dist/tools-logic/drill-down.js.map +1 -1
  81. package/dist/tools-logic/journal-archive.d.ts.map +1 -1
  82. package/dist/tools-logic/journal-archive.js +12 -2
  83. package/dist/tools-logic/journal-archive.js.map +1 -1
  84. package/dist/tools-logic/journal-cold-start.d.ts.map +1 -1
  85. package/dist/tools-logic/journal-cold-start.js +48 -9
  86. package/dist/tools-logic/journal-cold-start.js.map +1 -1
  87. package/dist/tools-logic/journal-list.d.ts +42 -0
  88. package/dist/tools-logic/journal-list.d.ts.map +1 -1
  89. package/dist/tools-logic/journal-list.js +60 -10
  90. package/dist/tools-logic/journal-list.js.map +1 -1
  91. package/dist/tools-logic/journal-read.d.ts.map +1 -1
  92. package/dist/tools-logic/journal-read.js +22 -13
  93. package/dist/tools-logic/journal-read.js.map +1 -1
  94. package/dist/tools-logic/journal-search.d.ts +58 -0
  95. package/dist/tools-logic/journal-search.d.ts.map +1 -1
  96. package/dist/tools-logic/journal-search.js +123 -80
  97. package/dist/tools-logic/journal-search.js.map +1 -1
  98. package/dist/tools-logic/palace-search.d.ts.map +1 -1
  99. package/dist/tools-logic/palace-search.js +30 -11
  100. package/dist/tools-logic/palace-search.js.map +1 -1
  101. package/dist/tools-logic/palace-walk.d.ts +10 -0
  102. package/dist/tools-logic/palace-walk.d.ts.map +1 -1
  103. package/dist/tools-logic/palace-walk.js +25 -16
  104. package/dist/tools-logic/palace-walk.js.map +1 -1
  105. package/dist/tools-logic/recall-insight.d.ts +20 -0
  106. package/dist/tools-logic/recall-insight.d.ts.map +1 -1
  107. package/dist/tools-logic/recall-insight.js +12 -1
  108. package/dist/tools-logic/recall-insight.js.map +1 -1
  109. package/dist/tools-logic/recognition-builder.d.ts.map +1 -1
  110. package/dist/tools-logic/recognition-builder.js +33 -19
  111. package/dist/tools-logic/recognition-builder.js.map +1 -1
  112. package/dist/tools-logic/resurrect.d.ts +11 -0
  113. package/dist/tools-logic/resurrect.d.ts.map +1 -1
  114. package/dist/tools-logic/resurrect.js +64 -2
  115. package/dist/tools-logic/resurrect.js.map +1 -1
  116. package/dist/tools-logic/session-end-reflect.d.ts.map +1 -1
  117. package/dist/tools-logic/session-end-reflect.js +11 -0
  118. package/dist/tools-logic/session-end-reflect.js.map +1 -1
  119. package/dist/tools-logic/session-end.d.ts.map +1 -1
  120. package/dist/tools-logic/session-end.js +23 -7
  121. package/dist/tools-logic/session-end.js.map +1 -1
  122. package/dist/tools-logic/session-start-lite.d.ts.map +1 -1
  123. package/dist/tools-logic/session-start-lite.js +13 -2
  124. package/dist/tools-logic/session-start-lite.js.map +1 -1
  125. package/dist/tools-logic/session-start.d.ts +101 -0
  126. package/dist/tools-logic/session-start.d.ts.map +1 -1
  127. package/dist/tools-logic/session-start.js +301 -78
  128. package/dist/tools-logic/session-start.js.map +1 -1
  129. package/dist/tools-logic/smart-recall.d.ts +87 -62
  130. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  131. package/dist/tools-logic/smart-recall.js +159 -510
  132. package/dist/tools-logic/smart-recall.js.map +1 -1
  133. package/dist/types.d.ts +1 -1
  134. package/dist/types.js +1 -1
  135. package/package.json +1 -1
@@ -0,0 +1,321 @@
1
+ /**
2
+ * retrieval/candidates.ts — Wave 1 of the shared retrieval pipeline
3
+ * (reports/2026-08-21-architecture-review.md §4, reports/2026-08-29-kickoff-plan.md §2,
4
+ * plywood SOP 58053587).
5
+ *
6
+ * THE PROBLEM THIS FILE FIXES: the journal and palace-room storage tiers each
7
+ * have MANY independent `readdir`+`readFileSync` scanners (9+ for journal,
8
+ * ~10 for palace-room content — see this file's own header comment sections
9
+ * below for the enumerated class), each deciding filtering/trust/scoping
10
+ * independently. Per the architecture review: "a directory-scanning,
11
+ * tokenizing, trust-tagging, or scoping boundary decided independently, once
12
+ * per surface, with no single place that decision has to be made correctly
13
+ * exactly once" is the actual root cause behind the L1/L2/redteam findings.
14
+ *
15
+ * THIS WAVE (1 of ~4-5): build ONE typed candidate reader per tier, with
16
+ * identity-trust tagging baked in at read time (not deferred to a caller
17
+ * that might forget it, per CRITICAL-1's "3 prior waves each missed
18
+ * same-class members" lesson). `tier` is an ENUMERATED table entry
19
+ * (`TIER_READERS` below) — adding a future tier (e.g. `"palace-pipeline"`,
20
+ * see the CHALLENGE note below) is a new ROW, never a new branch.
21
+ *
22
+ * WAVE 1 SCOPE, EXPLICIT: this module is purely ADDITIVE. Zero existing call
23
+ * site (`journalSearch`, `smartRecall`, `palaceSearch`, `resurrect`,
24
+ * `sessionStart`, etc.) is touched or imports from here yet — that migration
25
+ * is Wave 2+ (`retrieval/pipeline.ts`'s `queryMemory()`). This file only adds
26
+ * a new, unused-by-anyone-yet reader, so it carries zero behavior-change
27
+ * risk for any live surface.
28
+ *
29
+ * ── CHALLENGE outcome: does `tier` need a 3rd value for palace/pipeline? ──
30
+ * The kickoff plan invited this challenge explicitly. Verdict: NO, not this
31
+ * wave — `palace/pipeline/` (numbered `NNNN-slug.md` milestone files with
32
+ * `phase`/`order`/`status`/`opened`/`closed` frontmatter, read via
33
+ * `palace/pipeline.ts`'s `listMilestones()`/`parseMilestoneFile()`) is
34
+ * structurally a DIFFERENT shape from `palace/rooms/<slug>/*.md` (no
35
+ * `_room.json`, no `listRooms()` entry point, no salience/access-count
36
+ * metadata, a different frontmatter schema entirely) — forcing it through
37
+ * the SAME `"palace-room"` reader would be lossy, not a clean fit. It is a
38
+ * genuine sibling tier and deserves its own `"palace-pipeline"` table row in
39
+ * a later wave (architecture review P10 names this explicitly: "CONFIRM
40
+ * this explicitly, don't assume" — confirmed here: it does NOT ride in for
41
+ * free, a dedicated reader is still needed). Tier stays exactly
42
+ * `"journal" | "palace-room"` for Wave 1, matching the task's literal scope.
43
+ *
44
+ * ── W2 INDEPENDENT-REVIEW FIX (2026-08-30): the leaf-utility-vs-pipeline-
45
+ * stage anti-pattern, moved one level down ──
46
+ * `readTierCandidates` is exported (this file's header above literally tells
47
+ * a future surface to call it), but Wave 2's `queryMemory()` pipeline is the
48
+ * ONLY thing that historically applied a trust filter to its output — a
49
+ * naive caller of this function directly got raw, unfiltered rescue-tagged
50
+ * content back, reopening CRITICAL-2. Fixed by making this reader SAFE BY
51
+ * DEFAULT (`ReadTierCandidatesOpts.includeUntrusted`, default `false`, drops
52
+ * `untrusted === true` before returning) and promoting the trust predicate
53
+ * itself (`filterTrusted`, below) to a public, canonical export — the SAME
54
+ * implementation `queryMemory()`'s own trust-filter stage now delegates to,
55
+ * not a forked second copy. See retrieval/query-memory.ts's header for how
56
+ * the pipeline's own stage stays intact around this change.
57
+ */
58
+ import * as fs from "node:fs";
59
+ import * as path from "node:path";
60
+ import { journalDir, archiveRawDir, palaceDir } from "../storage/paths.js";
61
+ import { listJournalFiles } from "../helpers/journal-files.js";
62
+ import { isRescueSourcedContent, extractFrontmatterSource } from "../helpers/journal-filter.js";
63
+ import { listRooms } from "../palace/rooms.js";
64
+ /**
65
+ * Canonical trust-filter: drops every candidate whose `untrusted` flag is
66
+ * exactly `true`. A candidate with `untrusted === undefined` (never actually
67
+ * produced by `readTierCandidates`'s own readers today, which always set a
68
+ * boolean, but defensive for any future non-reader-produced MemoryCandidate)
69
+ * is treated as trusted and kept — only a literal `true` drops.
70
+ *
71
+ * THE single implementation both `readTierCandidates`'s own safe-by-default
72
+ * filtering AND `queryMemory()`'s mandatory TRUST-FILTER pipeline stage
73
+ * delegate to (independent review fix, W2, 2026-08-30) — do not fork a
74
+ * second copy of this predicate.
75
+ */
76
+ export function filterTrusted(candidates) {
77
+ return candidates.filter((c) => c.untrusted !== true);
78
+ }
79
+ /**
80
+ * Read every candidate for one tier, reduced to the quarantine-safe
81
+ * `CandidateStub` shape: existence (date/file/sourcePath) is preserved for
82
+ * EVERY candidate, trusted or not, but `content` is stripped for any
83
+ * candidate whose `untrusted` flag is `true`. See `CandidateStub`'s own doc
84
+ * comment for the full rationale (FIX 1, P0 independent-review fix,
85
+ * 2026-08-30).
86
+ *
87
+ * Ordering is preserved from the underlying tier reader (the SAME ordering
88
+ * `readTierCandidates` itself would return for the same `tier`/`opts`) — a
89
+ * caller that needs a `limit`-bounded window must slice AFTER mapping this
90
+ * function's full output, never before, so a quarantined row's real
91
+ * position is never silently skipped past (see journal-list.ts's own
92
+ * header comment for the "silent backfill" bug this ordering guarantee
93
+ * closes).
94
+ */
95
+ export function listCandidateStubs(tier, project, opts = {}) {
96
+ const candidates = TIER_READERS[tier](project, opts);
97
+ return candidates.map((c) => {
98
+ const trusted = c.untrusted !== true;
99
+ return {
100
+ date: c.date,
101
+ file: c.file,
102
+ sourcePath: c.sourcePath,
103
+ trusted,
104
+ content: trusted ? c.content : undefined,
105
+ };
106
+ });
107
+ }
108
+ function safeReadFile(p) {
109
+ try {
110
+ return fs.readFileSync(p, "utf-8");
111
+ }
112
+ catch {
113
+ return null; // unreadable/missing file — never throw, caller skips it
114
+ }
115
+ }
116
+ /**
117
+ * journal tier — consolidates the ~5 independent journal-archive-raw
118
+ * scanners (resurrect.ts Source 2, smart-recall.ts's archiveSearch,
119
+ * session-end-reflect.ts's collectRawUnconsumed, store-doctor.ts ×2
120
+ * filename-only scans) with `helpers/journal-files.ts`'s existing
121
+ * `listJournalFiles()` as the live/rollup-archive half (per the kickoff
122
+ * plan's "fold in listJournalFiles() as the live-file half"). See this
123
+ * module's own PR report for the full scanner enumeration table.
124
+ */
125
+ function readJournalCandidates(project, opts) {
126
+ const out = [];
127
+ const primaryDir = journalDir(project);
128
+ // ---- live half (delegates to the existing shared reader) ----
129
+ // Deliberately called with includeArchive=false here — see the rollup-
130
+ // archive half below for why archive/ is scanned independently rather
131
+ // than via listJournalFiles(project, true).
132
+ const entries = listJournalFiles(project, false);
133
+ for (const entry of entries) {
134
+ const sourcePath = path.join(entry.dir, entry.file);
135
+ const content = safeReadFile(sourcePath);
136
+ if (content === null)
137
+ continue;
138
+ out.push({
139
+ content,
140
+ tier: "journal",
141
+ project,
142
+ date: entry.date,
143
+ sourcePath,
144
+ file: entry.file,
145
+ sourceKind: "journal-live",
146
+ untrusted: isRescueSourcedContent(content),
147
+ sourceTag: extractFrontmatterSource(content),
148
+ });
149
+ }
150
+ // ---- opt-in rollup-archive half ----
151
+ // NOT delegated to listJournalFiles(project, true): that path requires a
152
+ // leading YYYY-MM-DD date match on every filename (its `dateMatch` guard),
153
+ // which silently drops a week-summary-shaped file (`YYYY-Wnn.md`) living
154
+ // in archive/ — exactly the shape journal-search.test.mjs's own fixture
155
+ // uses and journal-search.ts's independent raw scan (readdirSync +
156
+ // f.endsWith(".md"), NO date-match requirement) correctly picks up. This
157
+ // divergence was found empirically while proving behavioral equivalence
158
+ // (retrieval-candidates.test.mjs) — listJournalFiles() and journal-search.ts
159
+ // are NOT strictly equivalent for archive/ content today. Scanning archive/
160
+ // independently here, matching journal-search.ts's broader (no-date-match)
161
+ // filter, is what makes this reader an honest superset of BOTH existing
162
+ // scanners rather than silently inheriting the narrower one's gap.
163
+ if (opts.includeRollupArchive) {
164
+ const archiveDir = path.join(primaryDir, "archive");
165
+ let archiveFiles = [];
166
+ try {
167
+ archiveFiles = fs.readdirSync(archiveDir).filter((f) => f.endsWith(".md"));
168
+ }
169
+ catch {
170
+ archiveFiles = []; // missing/unreadable archive dir — treat as empty, never throw
171
+ }
172
+ // Independent review fix (MEDIUM-1, W2, 2026-08-30): build this half into
173
+ // its own array and sort it date-descending BEFORE appending to `out` —
174
+ // same pattern the live half above already gets for free from
175
+ // `listJournalFiles()`'s own `entries.sort((a,b) => b.date.localeCompare(a.date))`.
176
+ // Without this, `archiveFiles` is in raw `readdirSync` enumeration order
177
+ // (filesystem-dependent, not date order), so a downstream consumer that
178
+ // truncates before fully consuming this half (e.g. query-memory.ts's
179
+ // `scoreJournalTier` perTierLimit break) would keep an arbitrary
180
+ // enumeration-order subset instead of the newest archived entries — the
181
+ // exact "sort-before-truncate" bug class this fix closes for the archive
182
+ // half, matching what the live half already had.
183
+ const archiveCandidates = [];
184
+ for (const file of archiveFiles) {
185
+ const sourcePath = path.join(archiveDir, file);
186
+ const content = safeReadFile(sourcePath);
187
+ if (content === null)
188
+ continue;
189
+ const dateMatch = file.match(/^(\d{4}-\d{2}-\d{2})/);
190
+ archiveCandidates.push({
191
+ content,
192
+ tier: "journal",
193
+ project,
194
+ date: dateMatch ? dateMatch[1] : "",
195
+ sourcePath,
196
+ file,
197
+ sourceKind: "journal-rollup-archive",
198
+ untrusted: isRescueSourcedContent(content),
199
+ sourceTag: extractFrontmatterSource(content),
200
+ });
201
+ }
202
+ archiveCandidates.sort((a, b) => b.date.localeCompare(a.date));
203
+ out.push(...archiveCandidates);
204
+ }
205
+ // ---- opt-in raw-archive half (the previously-unconsolidated 5 scanners) ----
206
+ if (opts.includeRawArchive) {
207
+ const dir = archiveRawDir(project);
208
+ let files = [];
209
+ try {
210
+ files = fs.readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "index.md");
211
+ }
212
+ catch {
213
+ files = []; // missing/unreadable raw-archive dir — treat as empty, never throw
214
+ }
215
+ for (const file of files) {
216
+ const sourcePath = path.join(dir, file);
217
+ const content = safeReadFile(sourcePath);
218
+ if (content === null)
219
+ continue;
220
+ const dateMatch = file.match(/^(\d{4}-\d{2}-\d{2})/);
221
+ out.push({
222
+ content,
223
+ tier: "journal",
224
+ project,
225
+ date: dateMatch ? dateMatch[1] : "",
226
+ sourcePath,
227
+ file,
228
+ sourceKind: "journal-archive-raw",
229
+ untrusted: isRescueSourcedContent(content),
230
+ sourceTag: extractFrontmatterSource(content),
231
+ });
232
+ }
233
+ }
234
+ return out;
235
+ }
236
+ /**
237
+ * palace-room tier — net-new; no existing function to copy (`palace/rooms.ts`
238
+ * exports metadata only: `listRooms`/`getRoomMeta`/`countRoomEntries`, no
239
+ * content reader). Matches the INCLUSIVE behavior most existing scanners
240
+ * agree on (README.md counts as real room content — countRoomEntries's own
241
+ * doc comment: "both README.md's '## Memories' section and any topic
242
+ * files"): palace-search.ts, palace-walk.ts's readRoomContent,
243
+ * journal-search.ts's include_palace branch, and session-start.ts's
244
+ * autoBackfill all include README.md. A minority (palace-lint.ts, check.ts's
245
+ * alignment-room scanner, palace/fan-out.ts's auto-link keyword scan)
246
+ * exclude README.md/_room.json for their own narrower, non-retrieval
247
+ * purposes (linting the topic files only; keyword-linking heuristics) — see
248
+ * this module's own PR report for the full scanner enumeration table and
249
+ * why those are narrower special-purpose scans, not full content readers.
250
+ */
251
+ function readPalaceRoomCandidates(project, opts) {
252
+ const out = [];
253
+ const pd = palaceDir(project);
254
+ const allRooms = listRooms(project);
255
+ const rooms = opts.room ? allRooms.filter((r) => r.slug === opts.room) : allRooms;
256
+ for (const roomMeta of rooms) {
257
+ const roomPath = path.join(pd, "rooms", roomMeta.slug);
258
+ let files = [];
259
+ try {
260
+ if (!fs.existsSync(roomPath))
261
+ continue;
262
+ files = fs.readdirSync(roomPath).filter((f) => f.endsWith(".md"));
263
+ }
264
+ catch {
265
+ continue; // unreadable room dir — skip, never throw
266
+ }
267
+ for (const file of files) {
268
+ const sourcePath = path.join(roomPath, file);
269
+ const content = safeReadFile(sourcePath);
270
+ if (content === null)
271
+ continue;
272
+ let date = "";
273
+ try {
274
+ date = fs.statSync(sourcePath).mtime.toISOString().slice(0, 10);
275
+ }
276
+ catch {
277
+ date = (roomMeta.updated ?? "").slice(0, 10);
278
+ }
279
+ out.push({
280
+ content,
281
+ tier: "palace-room",
282
+ project,
283
+ date,
284
+ sourcePath,
285
+ file,
286
+ sourceKind: "palace-room",
287
+ untrusted: isRescueSourcedContent(content),
288
+ sourceTag: extractFrontmatterSource(content),
289
+ room: roomMeta.slug,
290
+ });
291
+ }
292
+ }
293
+ return out;
294
+ }
295
+ /**
296
+ * Class-not-instance table: one row per enumerated tier. Extending coverage
297
+ * (a future `"palace-pipeline"` tier, see this file's header CHALLENGE note)
298
+ * is a new row here, never a new branch in `readTierCandidates` itself.
299
+ */
300
+ const TIER_READERS = {
301
+ journal: readJournalCandidates,
302
+ "palace-room": readPalaceRoomCandidates,
303
+ };
304
+ /**
305
+ * Read every candidate for one tier of one project, with identity-trust
306
+ * tagging (`untrusted`) already computed. This is the SOLE function future
307
+ * retrieval surfaces should call instead of touching `journalDirs()`/
308
+ * `listRooms()`/raw `readdirSync` directly (Wave 2+ migration).
309
+ *
310
+ * SAFE BY DEFAULT (independent review fix, W2, 2026-08-30): unless
311
+ * `opts.includeUntrusted` is `true`, every `untrusted === true` candidate is
312
+ * dropped here, before returning — see `ReadTierCandidatesOpts.includeUntrusted`'s
313
+ * own doc comment for the full reasoning. A direct caller that never learns
314
+ * about `untrusted` at all still gets trusted-only content, closing the
315
+ * public escape hatch around `queryMemory()`'s own trust-filter stage.
316
+ */
317
+ export function readTierCandidates(tier, project, opts = {}) {
318
+ const candidates = TIER_READERS[tier](project, opts);
319
+ return opts.includeUntrusted ? candidates : filterTrusted(candidates);
320
+ }
321
+ //# sourceMappingURL=candidates.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"candidates.js","sourceRoot":"","sources":["../../src/retrieval/candidates.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,232 @@
1
+ /**
2
+ * retrieval/contradiction.ts — the CONTRADICTION pipeline stage (Wave 5a,
3
+ * 2026-08-31, reports/2026-08-31-pipe-w5a-contradiction-report.md).
4
+ *
5
+ * ── W5a SALVAGE (2026-08-31, same date, "## W5a salvage" section of the same
6
+ * report) ── An INDEPENDENT review (separate from — and after — the W5a
7
+ * code-reviewer pass named below) passed the mechanism (down-rank+annotate+
8
+ * never-drop, the re-sort→RRF propagation) but found the token grammar's
9
+ * status/kv branches were false-positive-PRONE in a way that actively
10
+ * defeats the stage's own safety intent, not merely "wider than ideal":
11
+ * - HIGH-1 (safeguard defeat): the status branch extracts categories via
12
+ * `extractStatusTokens`, which maps "blocked"/"stuck" to the SAME
13
+ * category (both → "blocked") — so category-EQUIVALENT common phrasing
14
+ * ("status: blocked" vs "status: stuck", genuinely the same fact) should
15
+ * never conflict. It didn't, by that safeguard's own design — but the
16
+ * status branch is un-keyed (see below) and the KV branch's own separate
17
+ * "key: value" extraction treats "status" as a literal KV KEY with
18
+ * "blocked"/"stuck" as different raw VALUES, flagging a conflict the
19
+ * status-category-equivalence check was specifically built to prevent.
20
+ * Two branches reusing overlapping vocabulary defeated each other.
21
+ * - HIGH-2 (generic-key false positive): both the kv branch and (to a
22
+ * narrower degree) the version branch key off whatever single word
23
+ * immediately precedes the value — "priority: high" (a marketing
24
+ * decision) vs "priority: low" (an unrelated cleanup task) share the
25
+ * generic key `priority` and got flagged conflicting despite being
26
+ * about entirely different topics; "key match" gave no topical
27
+ * protection at all for common one-word keys.
28
+ * - HIGH-3 (invisible annotation): `supersededBy`/`conflictsWith` never
29
+ * reached `SmartRecallResultItem`/`JournalSearchResult.results` — fixed
30
+ * separately, see smart-recall.ts's `localRecallSearch` and
31
+ * journal-search.ts's `journalSearch` field-list maps.
32
+ *
33
+ * FIX (this file): restrict `grammarConflict` to `extractVersionTokens`
34
+ * ONLY — status and kv detection are REMOVED from this module entirely
35
+ * (not just gated/pre-filtered). Semver (`\d+\.\d+\.\d+`) is a much
36
+ * narrower, more self-describing pattern than a bare "word: word" or
37
+ * status-category match — a shared key + differing semver value is a
38
+ * strong, low-false-positive signal of a genuine version supersession, and
39
+ * removing the other two branches removes HIGH-1 (the category-vs-KV
40
+ * cross-branch defeat cannot happen when the KV branch does not exist) and
41
+ * the dominant real-world instance of HIGH-2 (KV keys off ANY generic
42
+ * one-word label — "priority", "status", "mode", "env" — a pattern that
43
+ * recurs constantly in prose; a version-shaped `\d+\.\d+\.\d+` collision
44
+ * between two topically-unrelated candidates is comparatively rare, though
45
+ * not literally impossible — e.g. a shared generic key like "step 1.2.3" vs
46
+ * "step 5.6.7" — an acknowledged, narrower residual risk, not claimed to be
47
+ * zero). `extractStatusTokens`/`extractKVTokens` remain exported from
48
+ * `helpers/conflict-scan.ts` and are UNCHANGED there — `conflict-scan.ts`'s
49
+ * own `scanForConflicts` (the separate smart-remember pre-save warning flow)
50
+ * and `tools-logic/supersession.ts`'s `compareForConflicts` (the separate
51
+ * `ar correct` CorrectionRecord flow) both still use all three extractors;
52
+ * this restriction applies ONLY to this module's pairwise same-tier
53
+ * retrieval-time comparison, not to those other two, structurally distinct
54
+ * consumers.
55
+ *
56
+ * WHY THIS IS ITS OWN MODULE, not a function inside query-memory.ts: mirrors
57
+ * `retrieval/scope.ts`'s own precedent — a small, dependency-light, pure
58
+ * comparator that query-memory.ts (this wave) consumes, and that a later
59
+ * wave's caller (e.g. a future `recallInsight()`-style direct consumer) can
60
+ * import without creating an import cycle back into query-memory.ts (which
61
+ * already imports FROM tools-logic — see scope.ts's header for the exact
62
+ * cycle this pattern avoids).
63
+ *
64
+ * WHAT THIS DOES NOT DO (scope, read the eval fixtures before extending):
65
+ * this comparator reuses ONLY `helpers/conflict-scan.ts`'s `extractVersionTokens`
66
+ * semver extractor (post-salvage — see above; status/kv were removed, not
67
+ * merely descoped from the start). It does NOT detect arbitrary
68
+ * semantic-prose contradictions ("we fully migrated OFF Postgres to
69
+ * CockroachDB" vs "we use Postgres") — confirmed empirically against the
70
+ * redteam eval fixture (reports/2026-08-18-eval-redteam.md HIGH-2) while
71
+ * resolving this wave's pre-loaded Challenge A: the version extractor
72
+ * produces no matching key with differing values for that pair at all (no
73
+ * version numbers appear in either sentence). Prose-semantic contradiction
74
+ * detection is a genuinely harder, separate problem (conflict-scan.ts's own
75
+ * header already says so) and is explicitly OUT of this wave's scope — see
76
+ * the wave report's "prose-semantic gap" follow-up section, not silently
77
+ * absorbed into this grammar.
78
+ *
79
+ * ALGORITHM: pairwise, O(n²) over one tier's already-scored item list (n is
80
+ * a per-tier result count, bounded by `perTierLimit`, never the full corpus).
81
+ * For every pair (i, j):
82
+ * 1. GRAMMAR CHECK — same key across version tokens, different semver
83
+ * value → conflict. Symmetric (order of i/j does not matter for
84
+ * whether a conflict exists, only for which side is stale — see 2).
85
+ * 2. DIRECTION — decide which side is stale, if determinable at all:
86
+ * - both items carry a `date` and the dates differ → the OLDER
87
+ * `date` is superseded by the newer one (journal's own authored-
88
+ * date semantics; this only requires "the two dates differ", so it
89
+ * applies to any date-bearing tier, not journal-specifically —
90
+ * journal simply always has a `date`, so this branch always fires
91
+ * for it unless two journal hits share the exact SAME date).
92
+ * - dates are equal, or one/both undefined, AND both items carry an
93
+ * `order` that differs → the LOWER `order` is superseded by the
94
+ * HIGHER `order` (append-order tie-break: palace's same-day-tie
95
+ * policy, per this wave's Challenge B — `order` is populated from
96
+ * the room file's LINE NUMBER for palace items only; journal items
97
+ * are deliberately NOT given an `order` value by this wave's
98
+ * query-memory.ts wiring, so a same-date journal tie falls through
99
+ * to the next bullet instead of guessing off line position, per
100
+ * the wave brief's literal instruction).
101
+ * - neither resolves → AMBIGUOUS: both sides are annotated as
102
+ * conflicting with each other, NEITHER is marked superseded, and
103
+ * (by construction, see query-memory.ts's stage) neither is
104
+ * penalized. Never guess which side to demote from no signal.
105
+ *
106
+ * NEVER DROPS: this module only classifies relations between items already
107
+ * present in the input array — it never removes, reorders, or mutates the
108
+ * input array itself (that is query-memory.ts's stage's job, immediately
109
+ * downstream). A caller that ignores this module's output entirely gets
110
+ * back the exact same candidate set it passed in.
111
+ *
112
+ * ── HIGH-PRECISION GRAMMAR (pre-ship red-team fix, STEP 4b, 2026-09-01,
113
+ * wave/pipe-w5fix — correctness red-team, reports/2026-09-01-pipe-w5fix-
114
+ * report.md) ──
115
+ * The W5a-salvage grammar above (line ~45-46) already NAMED "step 1.2.3 vs
116
+ * step 5.6.7" as "an acknowledged, narrower residual risk, not claimed to be
117
+ * zero" — a second, independent (correctness, not security) red-team then
118
+ * PROVED that risk is much wider and actively harmful, not narrow: the
119
+ * plain `helpers/conflict-scan.ts` `extractVersionTokens` extractor's
120
+ * `(?:v|@|version\s+)?` marker is OPTIONAL, so ANY bare `N.N.N`-shaped
121
+ * digit run gets treated as a version — which false-positives on:
122
+ * - IP addresses: "at 10.0.0.1" / "at 10.0.1.5" (the first 3 octets of a
123
+ * dotted-quad ARE a valid `\d+\.\d+\.\d+` match on their own).
124
+ * - dot-formatted dates: "08.15.2026" / "08.16.2026" (MM.DD.YYYY is
125
+ * structurally IDENTICAL to a semver's `\d+\.\d+\.\d+` shape — nothing
126
+ * about the digits themselves can distinguish a date from a version).
127
+ * - dotted step/section numbers: "step 1.2.3" / "step 5.6.7".
128
+ * Combined with the ORIGINAL (pre-STEP-4a) down-rank+re-sort mechanism, a
129
+ * false-positive match like this didn't just add noise — it actively
130
+ * INVERTED ranking, demoting a correct, unrelated fact below a weaker match.
131
+ * STEP 4a (query-memory.ts's `applyContradictionStage`) already made a false
132
+ * positive here harmless (annotate-only, never reorders/rescores) — this
133
+ * fix is the SECOND, independent layer: shrink how often the false
134
+ * positive fires AT ALL, so even the harmless annotation is rare and
135
+ * meaningful rather than routinely wrong.
136
+ *
137
+ * `extractHighPrecisionVersionTokens` below is a LOCAL, module-scoped
138
+ * extractor — a modified copy of `extractVersionTokens`'s regex, NOT an
139
+ * edit to the shared `helpers/conflict-scan.ts` export. `extractVersionTokens`
140
+ * itself is UNCHANGED and remains exactly as permissive as before for its
141
+ * OTHER two callers (`conflict-scan.ts`'s own `scanForConflicts` — the
142
+ * smart-remember pre-save warning flow — and `tools-logic/supersession.ts`'s
143
+ * `compareForConflicts` — the `ar correct` CorrectionRecord flow), which are
144
+ * structurally distinct consumers this fix's scope (the retrieval area) does
145
+ * not touch and whose own false-positive tolerance was never in question
146
+ * here (see this file's original header, "FIX (this file)", for why
147
+ * `contradiction.ts` choosing a narrower grammar than `conflict-scan.ts`
148
+ * offers was already the file's own precedent).
149
+ *
150
+ * THE TIGHTENING: require an explicit version marker (`v`, `@`, `ver`,
151
+ * `version`, or `#`) IMMEDIATELY adjacent to the digits, AND reject a
152
+ * trailing 4th dot-group (`(?!\.\d)`, an IPv4-shape defense-in-depth layered
153
+ * on top of the marker requirement, in case a marker-adjacent IP ever
154
+ * occurs, e.g. "v10.0.0.1"). Neither an IP address, a plain date, nor a
155
+ * bare "step N.N.N" carries any of these markers in ordinary prose, so all
156
+ * three false-positive classes above no longer extract a token at all —
157
+ * verified empirically (node REPL, this wave's own report) against every
158
+ * named case. The real L1-C1 case ("AgentRecall version 3.5.0" / "AgentRecall
159
+ * version 3.4.41") keeps working: the word "version" IS the marker. See the
160
+ * PART E test suite (`query-memory-pipeline.test.mjs`) for the fixture-level
161
+ * proof of both the false-positive exclusions and the still-detected real
162
+ * case.
163
+ *
164
+ * ACCEPTED RECALL LOSS (code-review LOW note, 2026-09-01, not a regression —
165
+ * precision over recall is this fix's explicit brief): the `(?!\.\d)`
166
+ * IPv4-shape guard also excludes a genuine 4-COMPONENT version string (e.g.
167
+ * a Windows-style "3.5.0.1" vs "3.5.0.2") — the same lookahead cannot tell
168
+ * "this is a 4-octet IP" from "this is a 4-part semver" any more than the
169
+ * plain extractor's digits alone could tell a date from a version. AgentRecall's
170
+ * own versioning (and this stage's own worked example) is 3-part, so this is
171
+ * a narrow, acceptable trade — a missed 4-component version conflict decays
172
+ * away naturally (recency still favors the newer mention); a false-positive
173
+ * IP match would not have.
174
+ */
175
+ /**
176
+ * The minimal shape this comparator needs from a candidate — deliberately
177
+ * NOT `QueryMemoryItem` itself, so this module has zero dependency on
178
+ * query-memory.ts (avoiding the import-cycle query-memory.ts's own header
179
+ * already worries about for scope.ts, and keeping this module trivially
180
+ * unit-testable without any pipeline machinery).
181
+ */
182
+ export interface ContradictionItem {
183
+ /** Text the grammar extractors scan — callers typically pass `${title} ${excerpt}`. */
184
+ text: string;
185
+ /** Best-effort ISO date (YYYY-MM-DD). Absent/unparseable dates never
186
+ * resolve a direction on their own — see DIRECTION above. */
187
+ date?: string;
188
+ /** Append-order signal (e.g. a room file's line number). Only meaningful
189
+ * as a same-tier, same-day tie-break — see DIRECTION above. A caller that
190
+ * never wants order-based tie-breaking (this wave's journal wiring) simply
191
+ * omits it. */
192
+ order?: number;
193
+ }
194
+ export interface ContradictionResult {
195
+ /**
196
+ * index -> the OTHER indices this index's item conflicts with (grammar
197
+ * match found), REGARDLESS of whether a direction could be resolved.
198
+ * Symmetric: if `conflictsWith.get(i)` contains `j`, `conflictsWith.get(j)`
199
+ * contains `i`. This is the full annotation set — a caller uses this for
200
+ * the additive `conflictsWith` field even when no `supersededBy` could be
201
+ * determined (the ambiguous, down-rank-neither case).
202
+ */
203
+ conflictsWith: Map<number, number[]>;
204
+ /**
205
+ * index of the STALE item -> index of the item that supersedes it. Only
206
+ * populated for pairs where a direction was confidently resolved (see
207
+ * DIRECTION above). An index present here is a candidate for down-
208
+ * ranking; an index present ONLY in `conflictsWith` (never as a key here)
209
+ * must be annotated but NOT penalized — the ambiguous-tie safety
210
+ * guarantee this stage exists to prove.
211
+ *
212
+ * If more than one sibling supersedes the same stale item (3+ conflicting
213
+ * items in one tier), this keeps the MOST CURRENT superseder found (the
214
+ * one that would itself win a direct pairwise comparison against any
215
+ * earlier candidate), not simply the last one processed.
216
+ */
217
+ supersededBy: Map<number, number>;
218
+ }
219
+ /**
220
+ * Pairwise contradiction scan over one tier's candidate list. O(n²) — the
221
+ * caller (query-memory.ts) is expected to run this AFTER tokenize+score
222
+ * (so `items.length` is already bounded by `perTierLimit`, not the full
223
+ * on-disk corpus) and to skip tiers with fewer than 2 items (nothing to
224
+ * compare) or with no date signal at all (this wave: the insight tier).
225
+ *
226
+ * Never drops, never reorders, never mutates `items` — returns relations
227
+ * ONLY. The caller decides what to do with them (annotate + down-rank,
228
+ * per this wave's brief; a future caller could choose differently without
229
+ * this module changing).
230
+ */
231
+ export declare function detectContradictions(items: ContradictionItem[]): ContradictionResult;
232
+ //# sourceMappingURL=contradiction.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contradiction.d.ts","sourceRoot":"","sources":["../../src/retrieval/contradiction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6KG;AAcH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb;kEAC8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;oBAGgB;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AA4GD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,mBAAmB,CAmCpF"}