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,419 @@
1
+ /**
2
+ * retrieval/query-memory.ts — Wave 2 of the shared retrieval pipeline
3
+ * (reports/2026-08-21-architecture-review.md §4, reports/2026-08-29-kickoff-plan.md
4
+ * Wave 2, plywood SOP ecbd4351).
5
+ *
6
+ * THE PROBLEM THIS FILE FIXES: Wave 1 (retrieval/candidates.ts) built a shared
7
+ * TYPED reader with trust-tagging baked in, but shipped it as a LEAF UTILITY —
8
+ * nothing was forced to call it. The architecture review's whole point is that
9
+ * a leaf utility gets forgotten by exactly the surfaces that matter most. This
10
+ * file is the fix: a MANDATORY PIPELINE every candidate is forced through
11
+ * before it can be ranked or surfaced — `queryMemory()` composes six stages
12
+ * (fetch -> trust-filter -> tokenize+score -> scope -> rank/fuse -> fence) and
13
+ * NO stage is individually callable/skippable by a consumer; a caller gets
14
+ * `queryMemory()`'s return value or nothing.
15
+ *
16
+ * WAVE 2 SCOPE: build the pipeline, then migrate exactly ONE caller onto it —
17
+ * `smartRecall()` (tools-logic/smart-recall.ts). journalSearch, palaceSearch,
18
+ * recallInsight, resurrect, session_start are UNCHANGED this wave (Wave 3).
19
+ *
20
+ * ── CHALLENGE (a): one canonical scoring formula, or pluggable per tier? ──
21
+ * PLUGGABLE PER TIER — confirmed, not unified. smart-recall.ts's own file
22
+ * header (still true, read in full before writing this file) spends 100 lines
23
+ * justifying why journal (Ebbinghaus S=2, fast episodic decay), palace
24
+ * (S=9999, salience-weighted, near-zero decay) and insight (confirmation-count
25
+ * driven, not time-based at all) encode three genuinely different memory-type
26
+ * semantics — collapsing them into one formula would not be "reconciliation",
27
+ * it would be the same cross-source-raw-score-averaging bug smart-recall.ts's
28
+ * own Fix 1 (RRF) already fixed once, reintroduced one level up. What DOES
29
+ * unify into "ONE score stage" is the STAGE itself (TOKENIZE+SCORE as one named
30
+ * step in the pipeline, always run, never skippable) with an internal per-tier
31
+ * strategy table (`scoreJournalTier`/`scorePalaceTier`/`scoreInsightTier`
32
+ * below) — this is exactly the architecture review's own §4.2 step 3 wording:
33
+ * "applies one scoring strategy per tier ... no scoring behavior needs to
34
+ * change on day one." The five formulas smart-recall.ts documents (RRF k=60,
35
+ * Ebbinghaus, hot-window recency, betaUtility feedback, two-stage fusion) are
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.
40
+ * - Ebbinghaus decay, palace salience/IDF blend, insight confirmation blend:
41
+ * pipeline-owned (TOKENIZE+SCORE stage, per-tier) — these ARE the
42
+ * per-tier strategies the review names.
43
+ * - betaUtility feedback multiplier + calibratedConfidence labeling:
44
+ * LEFT IN smart-recall.ts, NOT pulled into the pipeline. Both are
45
+ * smart_recall-SPECIFIC concepts (a user feedback log keyed by
46
+ * result id/title; a confidence scale built to compare smart_recall's
47
+ * OWN local-vs-remote backends) that no other Wave-3 migration target
48
+ * (journalSearch, palaceSearch, resurrect, session_start) has any
49
+ * equivalent of today. Baking them into queryMemory() would force every
50
+ * future consumer to inherit smart_recall's own feedback-log semantics
51
+ * whether or not they make sense for that surface — exactly the
52
+ * "leaf utility everyone must remember NOT to blindly trust" anti-pattern
53
+ * this effort exists to close, just relocated one level deeper. They stay
54
+ * as smart-recall.ts's OWN post-pipeline processing, applied uniformly to
55
+ * whatever queryMemory() returns.
56
+ *
57
+ * ── CHALLENGE (b): the Wave-1 superset — what does smart_recall now SEE? ──
58
+ * readTierCandidates("palace-room", ...) surfaces every `.md` file in a room,
59
+ * whereas the OLD smart-recall.ts called `palaceSearch()` directly, which has
60
+ * a KNOWN, DOCUMENTED gap (packages/core/test/identity-trust-completeness.test.mjs's
61
+ * `ALLOWLIST_PALACE["tools-logic/palace-search.ts"]`, marked "(KNOWN GAP)"):
62
+ * palaceSearch() never calls the rescue-quarantine choke, so a rescue-tagged
63
+ * file planted in a room would have surfaced through smart_recall's OLD palace
64
+ * source completely unfiltered. Wave 2's migration CLOSES this gap for the
65
+ * smart_recall path specifically (see `scorePalaceTier` below: trust-filter
66
+ * runs before scoring, unconditionally) — a genuine, characterized SECURITY
67
+ * IMPROVEMENT, not a neutral refactor; see this file's own destination-proof
68
+ * test (retrieval/query-memory.test.mjs) for the planted-rescue-content proof.
69
+ * `palaceSearch()` itself (the standalone MCP tool / `ar palace search`
70
+ * surface) is UNCHANGED and still carries the gap — only smart_recall's
71
+ * INTERNAL route to palace-room content no longer does. This wave's report
72
+ * updates identity-trust-completeness.test.mjs's ALLOWLIST_PALACE entry for
73
+ * palace-search.ts to say so precisely (the function is still a known gap;
74
+ * smart-recall.ts no longer calls it).
75
+ *
76
+ * Week-summaries / rollup-archive: smart-recall.ts's journal source already
77
+ * reads rollup-archive today (journalSearch(...) internally calls
78
+ * `journalDirs(slug, true)`) — `scoreJournalTier` below defaults
79
+ * `includeRollupArchive: true` to match, so this is NOT new surface area, it
80
+ * is preserved surface area.
81
+ *
82
+ * Raw-archive: NOT part of the competing tier set here (see the "archive
83
+ * never enters RRF" note on `queryArchiveFallback` below) — unchanged
84
+ * structurally, just relocated into this module.
85
+ *
86
+ * ── CHALLENGE (c): where "exact equivalence" genuinely cannot hold ──
87
+ * Documented per-decision below, not glossed over:
88
+ * 1. FENCE (stage 6) is NOT applied inside this pipeline to `smart_recall`'s
89
+ * per-item fields. See `renderFenced()`'s doc comment — forcing
90
+ * `fenceMemory()` onto every candidate excerpt would corrupt
91
+ * `SmartRecallResultItem.excerpt` (breaking the very "preserve external
92
+ * contract exactly" requirement this wave is graded on) AND double-fence
93
+ * the payload, since `packages/mcp-server/src/tools/{smart-recall,recall}.ts`
94
+ * ALREADY correctly call `fenceMemory()` ONCE around the whole rendered
95
+ * payload at the true MCP-tool surfacing boundary (P1 fence, TOW2-388,
96
+ * predates this wave). This is a genuine architectural conflict between
97
+ * the SOP's literal "fence as the final stage" wording and the
98
+ * already-shipped, already-tested, more-correct fencing architecture —
99
+ * resolved in favor of the shipped architecture; see `renderFenced()`.
100
+ * 2. Journal-tier truncation order: the OLD `journalSearch()` applies its
101
+ * `limit` cutoff DURING an unsorted (raw `readdirSync` order)
102
+ * directory/file/line traversal, THEN sorts by date descending — so
103
+ * when total matches exceed `limit`, WHICH matches survive depends on
104
+ * filesystem enumeration order, not recency. `scoreJournalTier` below
105
+ * iterates `readTierCandidates`'s already-date-sorted-descending live
106
+ * half first — a characterized IMPROVEMENT (more predictable, favors
107
+ * recency, matches the tier's own Ebbinghaus-decay intent), not a
108
+ * silent behavior change. CORRECTION (independent review, W2,
109
+ * 2026-08-30): this file's initial cut only sorted the live half — the
110
+ * rollup-archive half (candidates.ts) and the legacy-journal half
111
+ * (`readLegacyJournalCandidates` below) were still built in raw,
112
+ * filesystem-enumeration order before being concatenated on, so a
113
+ * truncation that spilled into either half would still keep an
114
+ * arbitrary subset rather than the newest. Both halves are now ALSO
115
+ * sorted date-descending before concatenation — the sort-before-
116
+ * truncate class is closed across live AND archive (and legacy).
117
+ * SCOPE OF EQUIVALENCE (independent review, W2, 2026-08-30): this
118
+ * archive/legacy date-desc sort is an INTENTIONAL ranking change, and
119
+ * it is NOT order-preserving even below the truncation limit. When two
120
+ * candidates carry TIED per-tier scores (realistic for similarly-aged
121
+ * archive entries whose Ebbinghaus-decay scores coincide), `applyRRF`'s
122
+ * rank/`score` is decided by array position, so re-sorting the archive
123
+ * half changes the tie-break order — and the resulting numeric RRF
124
+ * `score` — of the tied items, even when nothing is truncated. This is
125
+ * a deterministic recency-favoring improvement over the prior
126
+ * arbitrary-filesystem-order tie-break, NOT a byte-identical no-op.
127
+ * Only STEP 1 (the `includeUntrusted` reconciliation below) is
128
+ * byte-identical; this sort is not, and the report's equivalence
129
+ * section is scoped accordingly.
130
+ * 3. Legacy journal directory (`~/.claude/projects/<entry>/memory/journal/` —
131
+ * `storage/paths.ts`'s `journalDirs()` legacy-fallback branch): Wave 1's
132
+ * `readTierCandidates` does NOT cover this (confirmed by reading
133
+ * candidates.ts — it never imports `getLegacyRoot`). `journalSearch()`
134
+ * today DOES scan it (via `journalDirs(slug, true)`). Rather than
135
+ * silently dropping this surface for smart_recall (a real, if likely
136
+ * rare, regression) or re-opening Wave 1's already-merged, already-tested
137
+ * `candidates.ts` to add it there, this file adds a small, self-contained
138
+ * `readLegacyJournalCandidates()` below that mirrors `journalDirs()`'s own
139
+ * legacy-root traversal — closing the gap without touching Wave 1's file.
140
+ * Also now sorted date-descending before returning (see item 2's
141
+ * correction above) — it is a third half of the same journal-tier
142
+ * concatenation, not exempt from the same truncation hazard.
143
+ *
144
+ * ── SCOPE NOTE (independent review, W2, 2026-08-30) ──
145
+ * CRITICAL-2 (rescue-quarantine injection) is closed for `smart_recall` this
146
+ * wave. `palaceSearch()` / `resurrect()` / `session_start()` remain on their
147
+ * own pre-pipeline paths and are UNCHANGED — they carry whatever
148
+ * trust-filtering (or lack of it) they had before this wave. Do not read
149
+ * this file's fixes as closing the gap workspace-wide.
150
+ *
151
+ * ── WAVE 3b UPDATE (2026-08-30, reports/2026-08-30-pipe-w3b-migrate-report.md) ──
152
+ * `journalSearch()` and `recallInsight()` are now migrated onto this
153
+ * pipeline (journalSearch's primary journal scan via `queryMemory({tiers:
154
+ * ["journal"]})`; recallInsight() shares this file's `applyScope` — see
155
+ * `./scope.ts` — directly on its own `recallInsights()` call, without
156
+ * routing through `queryMemory()` itself, to avoid corrupting its external
157
+ * contract's `relevance`/`applies_when`/`confirmed`/`file` fields, which
158
+ * `QueryMemoryItem` does not carry). `palaceSearch()` / `resurrect()` /
159
+ * `session_start()` remain unmigrated — see the Wave 3b report's resurrect
160
+ * assessment for why `resurrect()` in particular is a RECOMMENDATION, not a
161
+ * migration, this wave.
162
+ *
163
+ * ── WAVE 5a UPDATE (2026-08-31, reports/2026-08-31-pipe-w5a-contradiction-
164
+ * report.md) ──
165
+ * A new CONTRADICTION stage (`./contradiction.ts`'s `detectContradictions`)
166
+ * now runs per-tier, immediately after TOKENIZE+SCORE and before RANK/FUSE
167
+ * (see `applyContradictionStage` below) — for `journal` and `palace` tiers
168
+ * ONLY (the `insight` tier has no per-item authored-date signal to resolve a
169
+ * direction with, so it is deliberately skipped this wave, not silently
170
+ * inherited). It reuses `helpers/conflict-scan.ts`'s existing version token
171
+ * grammar to find, within one tier's own already-scored candidate list,
172
+ * pairs that assert the same fact-key with a different semver value. A
173
+ * candidate detected as the STALE side of such a pair is DOWN-RANKED
174
+ * (multiplicative score penalty, mirroring `applyHotWindowBoost`'s pattern)
175
+ * and ANNOTATED (`supersededBy`) — it is NEVER removed from the set. This
176
+ * closes part of the reconciliation gap `reports/2026-08-18-eval-redteam.md`'s
177
+ * HIGH-2 finding named (0% of grammar-detectable contradictions were
178
+ * previously surfaced with any corrective signal) for the subset of that gap
179
+ * the existing grammar can actually see — semantic-prose contradictions
180
+ * (that same finding's own PostgreSQL→CockroachDB example) remain out of
181
+ * reach; see `./contradiction.ts`'s header for why, and this wave's report
182
+ * for the follow-up.
183
+ *
184
+ * ── W5a SALVAGE (2026-08-31, "## W5a salvage" section of the same report) ──
185
+ * The original W5a cut also ran `extractStatusTokens`/`extractKVTokens`
186
+ * through this stage. An independent review found those two branches
187
+ * false-positive-prone in a way that DEFEATS this stage's own safety intent
188
+ * (HIGH-1: common phrasing like "status: blocked" vs "status: stuck" — the
189
+ * SAME status category — got flagged conflicting via the KV branch's literal
190
+ * value comparison; HIGH-2: generic single-word keys like "priority" gave no
191
+ * topical protection, flagging topically-unrelated candidates) and found the
192
+ * `supersededBy`/`conflictsWith` annotation never reached `smart_recall`'s
193
+ * or `journal_search`'s external contract (HIGH-3, invisible to agents).
194
+ * FIXED: `./contradiction.ts`'s `grammarConflict` now checks version tokens
195
+ * ONLY (see that file's header for the full reasoning); the annotation now
196
+ * threads into `SmartRecallResultItem`/`JournalSearchResult.results` (see
197
+ * `smart-recall.ts`'s `localRecallSearch` and `journal-search.ts`'s
198
+ * `journalSearch`). The down-rank+re-sort+never-drop mechanism itself,
199
+ * proven correct by the original W5a review, is UNCHANGED as of this note —
200
+ * see the PRE-SHIP UPDATE immediately below for the wave that DOES change it.
201
+ *
202
+ * ── PRE-SHIP RED-TEAM FIXES (2026-09-01, two adversarial red-teams, both
203
+ * NO-SHIP; wave/pipe-w5fix) ──
204
+ * Two independent, unrelated fixes landed together in this pass (sequenced to
205
+ * avoid touching the same function):
206
+ * 1. SECURITY (CRITICAL): `readLegacyJournalCandidates` below no longer
207
+ * hardcodes `untrusted: false` — see that function's own updated doc
208
+ * comment for the full CRITICAL-1-class rescue-leak this closed.
209
+ * 2. CORRECTNESS (W5a contradiction, MEDIUM->fixed): the DOWN-RANK half of
210
+ * `applyContradictionStage` (the `CONTRADICTION_PENALTY` multiplier +
211
+ * its re-sort) is REMOVED — the stage is now ANNOTATE-ONLY. A second,
212
+ * independent (correctness, not security) red-team proved the down-rank
213
+ * was net-negative: the version-token grammar false-positives on
214
+ * common number-shaped prose that was never a genuine version mention
215
+ * (IP addresses, dot-formatted dates, dotted step/section numbers), and
216
+ * when it does, the multiplicative penalty INVERTS ranking — demoting a
217
+ * correct, unrelated fact below a weaker match purely because both
218
+ * happened to contain three dot-separated digit groups. Annotate-only
219
+ * makes a false-positive detection harmless (an extra `conflictsWith`
220
+ * flag an agent can ignore) instead of rank-corrupting. Paired with a
221
+ * HIGH-PRECISION tightening of the grammar itself (`./contradiction.ts`'s
222
+ * `grammarConflict` — now requires an explicit version marker adjacent
223
+ * to the digits and rejects a 4th trailing dot-group, i.e. an IPv4
224
+ * shape) and a RESOLVABLE-annotation fix (`JournalSearchResult.results`
225
+ * now carries an additive `id`, mirroring `SmartRecallResultItem`, so
226
+ * `supersededBy`/`conflictsWith` are cross-referenceable there too, not
227
+ * just for `smart_recall`). See `./contradiction.ts`'s own header for
228
+ * the grammar fix's full false-positive-by-false-positive proof.
229
+ */
230
+ /** The three tiers that compete inside the shared RRF fusion this wave. */
231
+ export type QueryMemoryTier = "journal" | "palace" | "insight";
232
+ /** Every source label a `QueryMemoryItem` can carry, including the
233
+ * non-competing archive fallback (see `queryArchiveFallback`). */
234
+ export type QueryMemorySource = QueryMemoryTier | "archive";
235
+ /**
236
+ * The pipeline's per-candidate output shape — deliberately close to (but
237
+ * independent of, to avoid a circular import) `SmartRecallResultItem`.
238
+ * `confidence`/`calibrated` are NOT here — those are smart_recall-specific
239
+ * post-processing (see this file's header, CHALLENGE (a)).
240
+ */
241
+ export interface QueryMemoryItem {
242
+ id: string;
243
+ source: QueryMemorySource;
244
+ alsoFoundIn?: QueryMemorySource[];
245
+ title: string;
246
+ excerpt: string;
247
+ /** Cross-source fusion identity override — see smart-recall.ts's original
248
+ * Fix 5b doc comment (ported verbatim in spirit): insight items set this
249
+ * because their displayed excerpt is too low-entropy to serve as a fusion
250
+ * identity on its own. */
251
+ fusionKey?: string;
252
+ /** Tier-internal score before fusion; post-fusion RRF score after. */
253
+ score: number;
254
+ room?: string;
255
+ /** Palace-room file basename, without `.md` — needed to reconstruct a
256
+ * `VerbatimKey` for the Bridge (kept generic here; smart-recall.ts builds
257
+ * the actual `VerbatimKey` object, since this module must not depend on
258
+ * tools-logic/drill-down.ts's own dependents to avoid coupling). */
259
+ file?: string;
260
+ date?: string;
261
+ severity?: string;
262
+ /** Palace-only: exposed because smart-recall.ts's original item shape
263
+ * carried it (`keyword_score` on `PalaceSearchResult`) — forward-compat,
264
+ * currently unused by any consumer post-migration but not worth dropping. */
265
+ keywordScore?: number;
266
+ /** 1-indexed line number within the matched candidate's content.
267
+ * Journal (Wave 3b, 2026-08-30): needed by `journalSearch()`'s migrated
268
+ * adapter to reconstruct its external `{date,section,excerpt,line}`
269
+ * contract exactly — load-bearing, do not stop populating this for the
270
+ * journal tier. Palace (Wave 5a, 2026-08-31): ALSO now populated — the
271
+ * matched line's append-order within its room file, consumed by the
272
+ * CONTRADICTION stage (`./contradiction.ts`) as the `order` tie-break
273
+ * signal for same-day palace conflicts (palace's `date` is a regex-
274
+ * scraped guess from the excerpt text, not a reliable per-entry
275
+ * timestamp — see that field's own doc comment below — so two same-day
276
+ * or date-less palace hits need a second, always-present signal to
277
+ * resolve "which is more current"; a room file is append-only in
278
+ * practice, so a later line number is a reasonable proxy for "written
279
+ * later"). Purely additive: no existing consumer of the palace tier's
280
+ * `QueryMemoryItem` read this field before Wave 5a, so populating it
281
+ * changes no external contract. */
282
+ line?: number;
283
+ /**
284
+ * SCOPE stage attribution (Wave 3b, `retrieval/scope.ts`'s `applyScope`) —
285
+ * which project(s) this candidate is attributable to, when the tier has a
286
+ * genuine cross-project notion of that. Insight-tier items copy this
287
+ * straight from `IndexedInsight.projects` (`palace/insights-index.ts`).
288
+ * DELIBERATELY left unset for journal/palace-room items: those tiers are
289
+ * inherently per-slug (`readTierCandidates(tier, project, ...)` only ever
290
+ * reads `project`'s own tree), so there is no cross-project attribution to
291
+ * carry — see `scope.ts`'s own doc comment and this file's
292
+ * `SCOPE_ATTRIBUTED_TIERS` for why those tiers must never be run through
293
+ * `applyScope` at all, rather than relying on an absent `projects` field
294
+ * to mean "no-op" (it does not; it means "unattributed", which is a
295
+ * different, tier-inappropriate signal for those two tiers).
296
+ */
297
+ projects?: string[];
298
+ /**
299
+ * CONTRADICTION stage (Wave 5a, `./contradiction.ts`) — set ONLY when
300
+ * this item was detected as the STALE side of a same-tier, same-fact-key
301
+ * version-token grammar conflict (status/kv detection removed by the W5a
302
+ * salvage, 2026-08-31 — see `./contradiction.ts`'s header) with a sibling
303
+ * this stage could confidently order as more current (see `applyContradictionStage`
304
+ * below). Holds the CURRENT sibling's `id`. Additive: absent on every
305
+ * item unaffected by this stage, including every item from the `insight`
306
+ * tier (deliberately skipped this wave) and every journal/palace item
307
+ * with no detected conflict.
308
+ *
309
+ * ANNOTATE-ONLY (pre-ship red-team fix, STEP 4a, 2026-09-01): a
310
+ * `supersededBy` item's `score`/rank is NEVER changed by this stage — see
311
+ * `applyContradictionStage`'s own doc comment for why the original
312
+ * down-rank was removed. It is, and always was, NEVER removed from
313
+ * `items`.
314
+ */
315
+ supersededBy?: string;
316
+ /**
317
+ * CONTRADICTION stage (Wave 5a) — the `id`s of every sibling this item's
318
+ * text grammar-conflicts with, REGARDLESS of whether a stale direction
319
+ * could be resolved (a superset of the signal behind `supersededBy`: an
320
+ * item can appear here alone, with no `supersededBy`, when the conflict
321
+ * is a same-day/no-signal TIE — both sides are annotated, NEITHER is
322
+ * penalized; see `./contradiction.ts`'s own header for why guessing a
323
+ * direction from no signal is the failure mode this stage exists to
324
+ * avoid, not merely to relocate).
325
+ */
326
+ conflictsWith?: string[];
327
+ }
328
+ export interface QueryMemoryInput {
329
+ query: string;
330
+ /** Already-resolved project slug — this module does not call
331
+ * resolveProject(), matching Wave 1's `readTierCandidates` convention. */
332
+ project: string;
333
+ tiers: QueryMemoryTier[];
334
+ /** SCOPE stage (Wave 3b, `./scope.ts`'s `applyScope`) — a real per-
335
+ * candidate project-attribution filter for tiers that carry one
336
+ * (currently: `insight` only — see `SCOPE_ATTRIBUTED_TIERS` below).
337
+ * `undefined`/`"all"` preserves every pre-Wave-3b caller's behavior
338
+ * exactly (no filtering). */
339
+ scope?: string;
340
+ /** Final result cap, applied AFTER fusion (matches smart-recall.ts's
341
+ * `finalResults = results.slice(0, limit)` semantics, but the fused list
342
+ * itself is NOT truncated here — callers that need the untruncated fused
343
+ * list for their own gating (e.g. smart_recall's archive-fallback
344
+ * confidence gate) get it via `QueryMemoryResult.items`, uncut. */
345
+ limit?: number;
346
+ /** journal tier only — matches smart_recall's/journalSearch's `since`. */
347
+ since?: string;
348
+ journal?: {
349
+ includeRollupArchive?: boolean;
350
+ perTierLimit?: number;
351
+ };
352
+ palace?: {
353
+ room?: string;
354
+ perTierLimit?: number;
355
+ };
356
+ insight?: {
357
+ perTierLimit?: number;
358
+ includeAwareness?: boolean;
359
+ };
360
+ }
361
+ export interface QueryMemoryResult {
362
+ /** Fused + ranked (RRF, two-stage canonical fusion, hot-window recency
363
+ * boost applied) — UNCUT, UNFENCED. Caller applies its own limit/labeling/
364
+ * feedback adjustments. */
365
+ items: QueryMemoryItem[];
366
+ /** Raw pre-fusion candidate counts per competing tier (Fix 4/5 semantics —
367
+ * BEFORE cross-source fusion collapses same-excerpt duplicates). */
368
+ candidatesBySource: Partial<Record<QueryMemoryTier, number>>;
369
+ /** Every tier that was successfully queried (did not throw), independent
370
+ * of hit count — matches smart-recall.ts's original `sourcesQueried`
371
+ * semantics exactly. */
372
+ sourcesQueried: QueryMemoryTier[];
373
+ /**
374
+ * FENCE stage (pipeline stage 6) — the pipeline's OWN canonical
375
+ * "wrap retrieved content before it reaches an agent" implementation, for
376
+ * consumers that want a ready-to-surface rendered TEXT blob straight from
377
+ * queryMemory() (e.g. a future markdown-brief-returning caller). Joins
378
+ * `items` (up to `limit`) into one block and wraps it via `fenceMemory()`
379
+ * EXACTLY ONCE.
380
+ *
381
+ * `smart_recall` does NOT call this. Its structured `SmartRecallResultItem[]`
382
+ * output is serialized directly (JSON.stringify) by its OWN MCP tool
383
+ * wrapper (`packages/mcp-server/src/tools/{smart-recall,recall}.ts`), which
384
+ * ALREADY correctly calls `fenceMemory()` ONCE around the entire rendered
385
+ * payload — this is the shipped, tested (fence-completeness.test.mjs) P1
386
+ * fence architecture (TOW2-388), predating this wave. Calling
387
+ * `fenceMemory()` a SECOND time here, per-item, would (a) inject the fence
388
+ * open/close lines into every `excerpt` string, corrupting the exact field
389
+ * values `SmartRecallResultItem` promises callers ("preserve external
390
+ * contract exactly" — this wave's own success condition), and (b) produce
391
+ * a doubly-fenced, garbled blob once the MCP wrapper's own outer
392
+ * `fenceMemory()` wraps the already-fenced JSON a second time. See this
393
+ * file's header, CHALLENGE (c)-1, for the full reasoning. The completeness
394
+ * guarantee ("a queryMemory-based surface cannot bypass fencing") is
395
+ * enforced by keeping `packages/mcp-server/test/fence-completeness.test.mjs`
396
+ * green against the UNCHANGED MCP-tool-layer fenceMemory() call sites, not
397
+ * by mutating this function's structured output.
398
+ */
399
+ renderFenced(limit?: number): string;
400
+ }
401
+ /**
402
+ * Simple stable hash for result IDs — ported verbatim from smart-recall.ts.
403
+ *
404
+ * Exported (STEP 4c, pre-ship red-team fix, 2026-09-01) so
405
+ * `tools-logic/journal-search.ts`'s `journalSearch()` can mint the SAME
406
+ * kind of stable id for its own `include_palace` branch's locally-scanned
407
+ * rows (which never become `QueryMemoryItem`s — that branch bypasses
408
+ * queryMemory() entirely, see `journalSearch`'s own comment) — giving
409
+ * `JournalSearchResult.results` a real `id` on EVERY row, not just the
410
+ * primary journal-tier ones, without forking a second hash implementation.
411
+ * journal-search.ts already imports `queryMemory`/`parseSinceDate` in a
412
+ * pre-existing circular pair with this module (this file imports
413
+ * `parseSinceDate` FROM journal-search.ts); adding this export extends that
414
+ * SAME already-tolerated cycle, not a new one.
415
+ */
416
+ export declare function stableId(source: string, title: string): string;
417
+ export declare function queryMemory(input: QueryMemoryInput): Promise<QueryMemoryResult>;
418
+ export declare function queryArchiveFallback(project: string, query: string, limit: number): QueryMemoryItem[];
419
+ //# sourceMappingURL=query-memory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"query-memory.d.ts","sourceRoot":"","sources":["../../src/retrieval/query-memory.ts"],"names":[],"mappings":"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"}