agent-recall-core 3.4.48 → 3.4.50

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 (234) 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 -7
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +42 -5
  36. package/dist/index.js.map +1 -1
  37. package/dist/palace/awareness.d.ts +56 -10
  38. package/dist/palace/awareness.d.ts.map +1 -1
  39. package/dist/palace/awareness.js +279 -182
  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/prompts/consolidation-prompt.d.ts.map +1 -1
  70. package/dist/prompts/consolidation-prompt.js +5 -0
  71. package/dist/prompts/consolidation-prompt.js.map +1 -1
  72. package/dist/retrieval/candidates.d.ts.map +1 -1
  73. package/dist/retrieval/candidates.js +17 -2
  74. package/dist/retrieval/candidates.js.map +1 -1
  75. package/dist/retrieval/query-memory.d.ts +65 -7
  76. package/dist/retrieval/query-memory.d.ts.map +1 -1
  77. package/dist/retrieval/query-memory.js +518 -78
  78. package/dist/retrieval/query-memory.js.map +1 -1
  79. package/dist/retrieval/semantic-leg.d.ts +74 -0
  80. package/dist/retrieval/semantic-leg.d.ts.map +1 -0
  81. package/dist/retrieval/semantic-leg.js +180 -0
  82. package/dist/retrieval/semantic-leg.js.map +1 -0
  83. package/dist/storage/archive-write.d.ts.map +1 -1
  84. package/dist/storage/archive-write.js +29 -8
  85. package/dist/storage/archive-write.js.map +1 -1
  86. package/dist/storage/capture-router.d.ts +1 -1
  87. package/dist/storage/capture-router.d.ts.map +1 -1
  88. package/dist/storage/capture-router.js +26 -9
  89. package/dist/storage/capture-router.js.map +1 -1
  90. package/dist/storage/consolidation-queue.d.ts +11 -2
  91. package/dist/storage/consolidation-queue.d.ts.map +1 -1
  92. package/dist/storage/consolidation-queue.js +45 -16
  93. package/dist/storage/consolidation-queue.js.map +1 -1
  94. package/dist/storage/corrections.d.ts +53 -5
  95. package/dist/storage/corrections.d.ts.map +1 -1
  96. package/dist/storage/corrections.js +412 -124
  97. package/dist/storage/corrections.js.map +1 -1
  98. package/dist/storage/dream-health.d.ts +56 -8
  99. package/dist/storage/dream-health.d.ts.map +1 -1
  100. package/dist/storage/dream-health.js +130 -35
  101. package/dist/storage/dream-health.js.map +1 -1
  102. package/dist/storage/dream-yield.d.ts +81 -0
  103. package/dist/storage/dream-yield.d.ts.map +1 -0
  104. package/dist/storage/dream-yield.js +77 -0
  105. package/dist/storage/dream-yield.js.map +1 -0
  106. package/dist/storage/durable-intent.d.ts.map +1 -1
  107. package/dist/storage/durable-intent.js +24 -1
  108. package/dist/storage/durable-intent.js.map +1 -1
  109. package/dist/storage/filelock.d.ts +92 -12
  110. package/dist/storage/filelock.d.ts.map +1 -1
  111. package/dist/storage/filelock.js +317 -47
  112. package/dist/storage/filelock.js.map +1 -1
  113. package/dist/storage/fs-utils.d.ts +20 -0
  114. package/dist/storage/fs-utils.d.ts.map +1 -1
  115. package/dist/storage/fs-utils.js +27 -0
  116. package/dist/storage/fs-utils.js.map +1 -1
  117. package/dist/storage/paths.d.ts +34 -0
  118. package/dist/storage/paths.d.ts.map +1 -1
  119. package/dist/storage/paths.js +71 -0
  120. package/dist/storage/paths.js.map +1 -1
  121. package/dist/storage/pending.d.ts +154 -0
  122. package/dist/storage/pending.d.ts.map +1 -0
  123. package/dist/storage/pending.js +454 -0
  124. package/dist/storage/pending.js.map +1 -0
  125. package/dist/storage/project.d.ts.map +1 -1
  126. package/dist/storage/project.js +68 -16
  127. package/dist/storage/project.js.map +1 -1
  128. package/dist/storage/session-card.d.ts +13 -0
  129. package/dist/storage/session-card.d.ts.map +1 -1
  130. package/dist/storage/session-card.js +34 -3
  131. package/dist/storage/session-card.js.map +1 -1
  132. package/dist/storage/unclaimed.d.ts +165 -0
  133. package/dist/storage/unclaimed.d.ts.map +1 -0
  134. package/dist/storage/unclaimed.js +442 -0
  135. package/dist/storage/unclaimed.js.map +1 -0
  136. package/dist/storage/working-memory.d.ts.map +1 -1
  137. package/dist/storage/working-memory.js +19 -1
  138. package/dist/storage/working-memory.js.map +1 -1
  139. package/dist/supabase/recall-backend.d.ts +28 -2
  140. package/dist/supabase/recall-backend.d.ts.map +1 -1
  141. package/dist/supabase/recall-backend.js +80 -23
  142. package/dist/supabase/recall-backend.js.map +1 -1
  143. package/dist/supabase/sync.d.ts.map +1 -1
  144. package/dist/supabase/sync.js +13 -0
  145. package/dist/supabase/sync.js.map +1 -1
  146. package/dist/tools-logic/alignment-check.js +1 -1
  147. package/dist/tools-logic/alignment-check.js.map +1 -1
  148. package/dist/tools-logic/awareness-update.d.ts.map +1 -1
  149. package/dist/tools-logic/awareness-update.js +25 -16
  150. package/dist/tools-logic/awareness-update.js.map +1 -1
  151. package/dist/tools-logic/check-action.js +1 -1
  152. package/dist/tools-logic/check-action.js.map +1 -1
  153. package/dist/tools-logic/check.d.ts +55 -1
  154. package/dist/tools-logic/check.d.ts.map +1 -1
  155. package/dist/tools-logic/check.js +230 -57
  156. package/dist/tools-logic/check.js.map +1 -1
  157. package/dist/tools-logic/confidence.d.ts +11 -6
  158. package/dist/tools-logic/confidence.d.ts.map +1 -1
  159. package/dist/tools-logic/confidence.js +11 -6
  160. package/dist/tools-logic/confidence.js.map +1 -1
  161. package/dist/tools-logic/context-synthesize.js +2 -2
  162. package/dist/tools-logic/context-synthesize.js.map +1 -1
  163. package/dist/tools-logic/digest-read.js +2 -2
  164. package/dist/tools-logic/digest-read.js.map +1 -1
  165. package/dist/tools-logic/digest-recall.js +1 -1
  166. package/dist/tools-logic/digest-recall.js.map +1 -1
  167. package/dist/tools-logic/dream-admission.d.ts +144 -0
  168. package/dist/tools-logic/dream-admission.d.ts.map +1 -0
  169. package/dist/tools-logic/dream-admission.js +537 -0
  170. package/dist/tools-logic/dream-admission.js.map +1 -0
  171. package/dist/tools-logic/insight-promotion.d.ts +19 -1
  172. package/dist/tools-logic/insight-promotion.d.ts.map +1 -1
  173. package/dist/tools-logic/insight-promotion.js +48 -14
  174. package/dist/tools-logic/insight-promotion.js.map +1 -1
  175. package/dist/tools-logic/journal-capture.js +3 -3
  176. package/dist/tools-logic/journal-capture.js.map +1 -1
  177. package/dist/tools-logic/journal-write.js +3 -3
  178. package/dist/tools-logic/journal-write.js.map +1 -1
  179. package/dist/tools-logic/knowledge-write.js +2 -2
  180. package/dist/tools-logic/knowledge-write.js.map +1 -1
  181. package/dist/tools-logic/palace-lint.js +1 -1
  182. package/dist/tools-logic/palace-lint.js.map +1 -1
  183. package/dist/tools-logic/palace-read.js +1 -1
  184. package/dist/tools-logic/palace-read.js.map +1 -1
  185. package/dist/tools-logic/palace-search.js +1 -1
  186. package/dist/tools-logic/palace-search.js.map +1 -1
  187. package/dist/tools-logic/palace-walk.js +3 -3
  188. package/dist/tools-logic/palace-walk.js.map +1 -1
  189. package/dist/tools-logic/palace-write.js +4 -4
  190. package/dist/tools-logic/palace-write.js.map +1 -1
  191. package/dist/tools-logic/predict-correction.js +1 -1
  192. package/dist/tools-logic/predict-correction.js.map +1 -1
  193. package/dist/tools-logic/recall-backend.d.ts +11 -2
  194. package/dist/tools-logic/recall-backend.d.ts.map +1 -1
  195. package/dist/tools-logic/recall-backend.js +2 -2
  196. package/dist/tools-logic/recall-backend.js.map +1 -1
  197. package/dist/tools-logic/resurrect.d.ts.map +1 -1
  198. package/dist/tools-logic/resurrect.js +9 -1
  199. package/dist/tools-logic/resurrect.js.map +1 -1
  200. package/dist/tools-logic/safety-consolidation.d.ts +15 -0
  201. package/dist/tools-logic/safety-consolidation.d.ts.map +1 -1
  202. package/dist/tools-logic/safety-consolidation.js +44 -31
  203. package/dist/tools-logic/safety-consolidation.js.map +1 -1
  204. package/dist/tools-logic/session-end-reflect.d.ts.map +1 -1
  205. package/dist/tools-logic/session-end-reflect.js +4 -1
  206. package/dist/tools-logic/session-end-reflect.js.map +1 -1
  207. package/dist/tools-logic/session-end.d.ts +8 -0
  208. package/dist/tools-logic/session-end.d.ts.map +1 -1
  209. package/dist/tools-logic/session-end.js +51 -13
  210. package/dist/tools-logic/session-end.js.map +1 -1
  211. package/dist/tools-logic/session-start.d.ts +23 -0
  212. package/dist/tools-logic/session-start.d.ts.map +1 -1
  213. package/dist/tools-logic/session-start.js +44 -1
  214. package/dist/tools-logic/session-start.js.map +1 -1
  215. package/dist/tools-logic/smart-recall.d.ts +185 -10
  216. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  217. package/dist/tools-logic/smart-recall.js +363 -85
  218. package/dist/tools-logic/smart-recall.js.map +1 -1
  219. package/dist/tools-logic/store-doctor.d.ts.map +1 -1
  220. package/dist/tools-logic/store-doctor.js +14 -5
  221. package/dist/tools-logic/store-doctor.js.map +1 -1
  222. package/dist/tools-logic/store-repair.js +1 -1
  223. package/dist/tools-logic/store-repair.js.map +1 -1
  224. package/dist/tools-logic/supersession.d.ts +1 -1
  225. package/dist/tools-logic/supersession.d.ts.map +1 -1
  226. package/dist/tools-logic/supersession.js +2 -2
  227. package/dist/tools-logic/supersession.js.map +1 -1
  228. package/dist/types.d.ts +1 -1
  229. package/dist/types.js +1 -1
  230. package/dist/vector/embedding.d.ts +8 -0
  231. package/dist/vector/embedding.d.ts.map +1 -1
  232. package/dist/vector/embedding.js +8 -0
  233. package/dist/vector/embedding.js.map +1 -1
  234. package/package.json +1 -1
@@ -17,8 +17,9 @@
17
17
  import * as fs from "node:fs";
18
18
  import * as path from "node:path";
19
19
  import { getRoot } from "../types.js";
20
- import { ensureDir } from "../storage/fs-utils.js";
20
+ import { ensureDir, writeTextAtomic } from "../storage/fs-utils.js";
21
21
  import { extractKeywords } from "../helpers/auto-name.js";
22
+ import { tokenizeWords } from "../helpers/tokenize.js";
22
23
  import { withLock } from "../storage/filelock.js";
23
24
  import { syncToSupabase } from "../supabase/sync.js";
24
25
  import { scrubForCloud } from "../storage/content-guard.js";
@@ -55,8 +56,23 @@ export function readAwareness() {
55
56
  return "";
56
57
  return fs.readFileSync(p, "utf-8");
57
58
  }
58
- export function writeAwareness(content) {
59
- withLock("awareness", () => {
59
+ /**
60
+ * Lock discipline (fix6-locks):
61
+ * AWARENESS_STATE_LOCK ("awareness-state") guards BOTH awareness-state.json
62
+ * and awareness-archive.json — they are mutated together (demote/resurrect
63
+ * move insights between the two files), so a single lock keeps the pair
64
+ * consistent.
65
+ * AWARENESS_MD_LOCK ("awareness") guards awareness.md.
66
+ * ORDERING: "awareness-state" → "awareness" (render runs inside the state
67
+ * lock so a stale render can never overwrite a newer one). NEVER acquire
68
+ * "awareness-state" while holding "awareness". Same-name nesting is a
69
+ * deadlock — the *Unlocked internals below exist precisely so locked spans
70
+ * never re-enter their own lock.
71
+ */
72
+ const AWARENESS_STATE_LOCK = "awareness-state";
73
+ const AWARENESS_MD_LOCK = "awareness";
74
+ export async function writeAwareness(content) {
75
+ await withLock(AWARENESS_MD_LOCK, () => {
60
76
  const p = awarenessPath();
61
77
  ensureDir(path.dirname(p));
62
78
  // Scrub BEFORE the local write — this is the GLOBAL, cross-project, always
@@ -121,19 +137,53 @@ export function readAwarenessState() {
121
137
  return null;
122
138
  }
123
139
  }
124
- export function writeAwarenessState(state) {
125
- withLock("awareness-state", () => {
126
- const p = AWARENESS_JSON_PATH();
127
- ensureDir(path.dirname(p));
128
- state.lastUpdated = new Date().toISOString();
129
- // Scrub the serialized JSON before it touches disk. session-start.ts reads
130
- // this file DIRECTLY (readAwarenessState()) to build its briefing — not just
131
- // via the rendered awareness.md — so an unscrubbed insight.evidence/title,
132
- // compound-insight pattern, trajectory, or blind-spot string here reaches
133
- // session_start injection even if the markdown render path is clean.
134
- // scrubForCloud's replacement placeholders are plain ASCII with no quote/
135
- // brace characters, so scrubbing the full JSON string is JSON-safe.
136
- fs.writeFileSync(p, scrubForCloud(JSON.stringify(state, null, 2)), "utf-8");
140
+ /** Bare state write — caller MUST hold AWARENESS_STATE_LOCK. */
141
+ function writeAwarenessStateUnlocked(state) {
142
+ const p = AWARENESS_JSON_PATH();
143
+ ensureDir(path.dirname(p));
144
+ state.lastUpdated = new Date().toISOString();
145
+ // Scrub the serialized JSON before it touches disk. session-start.ts reads
146
+ // this file DIRECTLY (readAwarenessState()) to build its briefing — not just
147
+ // via the rendered awareness.md — so an unscrubbed insight.evidence/title,
148
+ // compound-insight pattern, trajectory, or blind-spot string here reaches
149
+ // session_start injection even if the markdown render path is clean.
150
+ // scrubForCloud's replacement placeholders are plain ASCII with no quote/
151
+ // brace characters, so scrubbing the full JSON string is JSON-safe.
152
+ // Atomic (tmp+rename): readers are lock-free, so a truncate-then-write here
153
+ // could tear under a concurrent read — and a torn readAwarenessState()
154
+ // returning null makes awareness-update's init path WIPE the whole state.
155
+ writeTextAtomic(p, scrubForCloud(JSON.stringify(state, null, 2)));
156
+ }
157
+ export async function writeAwarenessState(state) {
158
+ await withLock(AWARENESS_STATE_LOCK, () => writeAwarenessStateUnlocked(state));
159
+ }
160
+ /**
161
+ * The ONE locked read-modify-write combinator for awareness state (fix6-locks).
162
+ *
163
+ * Every writer that reads awareness-state.json, mutates it, and writes it back
164
+ * MUST go through this function — the whole span runs under
165
+ * AWARENESS_STATE_LOCK (the old shape, where writeAwarenessState locked only
166
+ * the final write, lost concurrent writers' insights wholesale: two processes
167
+ * read the same state, each merged one insight, and the last write discarded
168
+ * the other's — reproduced by awareness-state-concurrency.test.mjs).
169
+ *
170
+ * `fn` runs INSIDE the lock: it receives the freshly-read state (null if the
171
+ * store has none) and returns `{ state?, result }`. When `state` is returned
172
+ * it is written AND rendered (render happens inside the state lock, acquiring
173
+ * the "awareness" md lock — the documented "awareness-state" → "awareness"
174
+ * ordering) so renders can never land out of order. fn itself must be
175
+ * synchronous and must NOT call any locked awareness API (addInsight,
176
+ * writeAwarenessState, resurrectFromArchive, ... — the lock is not reentrant);
177
+ * the *Unlocked internals are available to it via closure inside this module.
178
+ */
179
+ export async function mutateAwarenessState(fn) {
180
+ return withLock(AWARENESS_STATE_LOCK, async () => {
181
+ const out = fn(readAwarenessState());
182
+ if (out.state) {
183
+ writeAwarenessStateUnlocked(out.state);
184
+ await renderAwareness(out.state);
185
+ }
186
+ return out.result;
137
187
  });
138
188
  }
139
189
  // ── Archive: demoted insights are preserved, not deleted ──────────────────
@@ -148,16 +198,23 @@ export function readAwarenessArchive() {
148
198
  return [];
149
199
  }
150
200
  }
151
- export function writeAwarenessArchive(archive) {
201
+ /** Bare archive write — caller MUST hold AWARENESS_STATE_LOCK (the archive
202
+ * shares the state lock: demote/resurrect mutate both files together). */
203
+ function writeAwarenessArchiveUnlocked(archive) {
152
204
  const p = AWARENESS_ARCHIVE_PATH();
153
205
  ensureDir(path.dirname(p));
154
206
  // Keep newest first, cap at MAX_ARCHIVE. Scrubbed for the same reason as
155
207
  // writeAwarenessState — resurrectFromArchive() can bring an archived insight's
156
208
  // evidence/title back into the live topInsights list (and therefore back into
157
209
  // session_start injection) without ever passing through writeAwareness's render.
158
- fs.writeFileSync(p, scrubForCloud(JSON.stringify(archive.slice(0, MAX_ARCHIVE), null, 2)), "utf-8");
210
+ // Atomic for the same torn-lock-free-reader reason as writeAwarenessStateUnlocked.
211
+ writeTextAtomic(p, scrubForCloud(JSON.stringify(archive.slice(0, MAX_ARCHIVE), null, 2)));
212
+ }
213
+ export async function writeAwarenessArchive(archive) {
214
+ await withLock(AWARENESS_STATE_LOCK, () => writeAwarenessArchiveUnlocked(archive));
159
215
  }
160
- /** Archive a demoted insight. If a matching insight exists in archive, strengthen it. */
216
+ /** Archive a demoted insight. If a matching insight exists in archive, strengthen it.
217
+ * Caller MUST hold AWARENESS_STATE_LOCK. */
161
218
  function archiveInsight(demoted) {
162
219
  const archive = readAwarenessArchive();
163
220
  const demotedKeywords = extractKeywords(demoted.title, 3);
@@ -176,10 +233,11 @@ function archiveInsight(demoted) {
176
233
  // Add to archive (newest first)
177
234
  archive.unshift(demoted);
178
235
  }
179
- writeAwarenessArchive(archive);
236
+ writeAwarenessArchiveUnlocked(archive);
180
237
  }
181
- /** Check archive for a matching insight to resurrect. Returns the insight if found. */
182
- export function resurrectFromArchive(keywords) {
238
+ /** Check archive for a matching insight to resurrect. Returns the insight if
239
+ * found. Caller MUST hold AWARENESS_STATE_LOCK. */
240
+ function resurrectFromArchiveUnlocked(keywords) {
183
241
  const archive = readAwarenessArchive();
184
242
  for (let i = 0; i < archive.length; i++) {
185
243
  const aKeywords = extractKeywords(archive[i].title, 3);
@@ -188,17 +246,18 @@ export function resurrectFromArchive(keywords) {
188
246
  // Remove from archive and return for resurrection
189
247
  const [resurrected] = archive.splice(i, 1);
190
248
  resurrected.confirmations += 1; // boost for being rediscovered
191
- writeAwarenessArchive(archive);
249
+ writeAwarenessArchiveUnlocked(archive);
192
250
  return resurrected;
193
251
  }
194
252
  }
195
253
  return null;
196
254
  }
197
- /**
198
- * Initialize awareness from scratch.
199
- */
200
- export function initAwareness(identity) {
201
- const state = {
255
+ /** Locked wrapper for external callers. */
256
+ export async function resurrectFromArchive(keywords) {
257
+ return withLock(AWARENESS_STATE_LOCK, () => resurrectFromArchiveUnlocked(keywords));
258
+ }
259
+ export function createInitialState(identity) {
260
+ return {
202
261
  identity,
203
262
  topInsights: [],
204
263
  compoundInsights: [],
@@ -206,187 +265,197 @@ export function initAwareness(identity) {
206
265
  blindSpots: [],
207
266
  lastUpdated: new Date().toISOString(),
208
267
  };
209
- writeAwarenessState(state);
210
- renderAwareness(state);
211
- return state;
268
+ }
269
+ /**
270
+ * Initialize awareness from scratch.
271
+ */
272
+ export async function initAwareness(identity) {
273
+ return mutateAwarenessState((_current) => {
274
+ const state = createInitialState(identity);
275
+ return { state, result: state };
276
+ });
212
277
  }
213
278
  /**
214
279
  * Add or merge an insight into the awareness state.
215
280
  * If similar insight exists (by title keyword overlap), merge and strengthen.
216
281
  * If new, add and demote lowest if over 20.
217
282
  */
218
- export function addInsight(newInsight) {
283
+ export async function addInsight(newInsight) {
219
284
  // ── Quality gate — reject obviously bad insights ──────────────────────────
220
285
  const title = newInsight.title?.trim() ?? "";
221
- if (title.split(/\s+/).filter(Boolean).length < 3)
286
+ // CJK-aware word count (fix #3, 2026-09-11): the pre-fix
287
+ // `title.split(/\s+/)` counted an unspaced CJK title as ONE "word" and
288
+ // rejected every such insight as title_too_short — the final dead gate in
289
+ // the CJK promotion chain (insights-index confirm-first → promotion dedup
290
+ // → THIS gate). tokenizeWords segments Han runs via Intl.Segmenter;
291
+ // minLength 1 preserves the old ASCII semantics exactly (any
292
+ // whitespace-delimited word counted, regardless of length).
293
+ if (tokenizeWords(title, { minLength: 1 }).length < 3)
222
294
  return { accepted: false, reason: "title_too_short" };
223
295
  if (/^test\s+insight/i.test(title))
224
296
  return { accepted: false, reason: "test_fixture" };
225
297
  if (!newInsight.evidence || newInsight.evidence.trim().length < 5)
226
298
  return { accepted: false, reason: "no_evidence" };
227
- let state = readAwarenessState();
228
- if (!state) {
229
- state = initAwareness("(unknown user)");
230
- }
231
- const now = new Date().toISOString();
232
- // Keyword-based matching (uses auto-name extractKeywords instead of raw word split)
233
- // Use limit=6 for broader matching coverage
234
- const newKeywords = extractKeywords(title, 6);
235
- // ── Resurrect from archive if this insight was previously demoted ─────────
236
- // Skip if an insight with the same ID already exists in topInsights (dedup)
237
- const resurrected = resurrectFromArchive(newKeywords);
238
- if (resurrected && !state.topInsights.some((i) => i.id === resurrected.id)) {
239
- // resurrectFromArchive already bumps confirmations by 1 — don't double-bump
240
- resurrected.lastConfirmed = now;
241
- if (!resurrected.evidence.includes(newInsight.evidence.slice(0, 40))) {
242
- const merged = `${resurrected.evidence} | ${newInsight.evidence}`;
243
- resurrected.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
244
- }
245
- for (const aw of newInsight.appliesWhen) {
246
- if (!resurrected.appliesWhen.includes(aw)) {
247
- resurrected.appliesWhen.push(aw);
248
- }
299
+ // fix6-locks: the ENTIRE read→merge→write span runs under the state lock
300
+ // via mutateAwarenessState — the old shape (unlocked read, locked write)
301
+ // lost concurrent sessions' insights wholesale.
302
+ return mutateAwarenessState((current) => {
303
+ let state = current;
304
+ if (!state) {
305
+ state = createInitialState("(unknown user)");
249
306
  }
250
- resurrected.trend = computeTrend(resurrected);
251
- state.topInsights.push(resurrected);
252
- // Enforce 20-item cap — demote lowest if over limit
253
- if (state.topInsights.length > 20) {
254
- state.topInsights.sort((a, b) => b.confirmations - a.confirmations);
255
- const demoted = state.topInsights.pop();
256
- archiveInsight(demoted);
257
- }
258
- writeAwarenessState(state);
259
- renderAwareness(state);
260
- return { action: "added", insight: resurrected };
261
- }
262
- let bestMatch = null;
263
- for (let i = 0; i < state.topInsights.length; i++) {
264
- const existing = state.topInsights[i];
265
- const existingKeywords = extractKeywords(existing.title, 6);
266
- const overlap = newKeywords.filter((k) => existingKeywords.some((ek) => ek.includes(k) || k.includes(ek)));
267
- const ratio = overlap.length / Math.max(newKeywords.length, existingKeywords.length, 1);
268
- if (ratio > 0.5 && (!bestMatch || ratio > bestMatch.overlap)) {
269
- bestMatch = { idx: i, overlap: ratio };
270
- }
271
- }
272
- if (bestMatch) {
273
- const existing = state.topInsights[bestMatch.idx];
274
- // Two-pass merge: if topic overlap is very strong (>0.6), always merge (confirmation).
275
- // If topic overlap is moderate (0.5-0.6), check evidence similarity to avoid merging
276
- // distinct insights that happen to share vocabulary.
277
- if (bestMatch.overlap > 0.6) {
278
- // Strong topic match → merge (strengthen)
279
- existing.confirmations++;
280
- existing.lastConfirmed = now;
281
- // Only append evidence if it's not already present (prevents "evidence | evidence")
282
- if (!existing.evidence.includes(newInsight.evidence.slice(0, 40))) {
283
- const merged = `${existing.evidence} | ${newInsight.evidence}`;
284
- existing.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
307
+ const now = new Date().toISOString();
308
+ // Keyword-based matching (uses auto-name extractKeywords instead of raw word split)
309
+ // Use limit=6 for broader matching coverage
310
+ const newKeywords = extractKeywords(title, 6);
311
+ // ── Resurrect from archive if this insight was previously demoted ─────────
312
+ // Skip if an insight with the same ID already exists in topInsights (dedup)
313
+ const resurrected = resurrectFromArchiveUnlocked(newKeywords);
314
+ if (resurrected && !state.topInsights.some((i) => i.id === resurrected.id)) {
315
+ // resurrectFromArchive already bumps confirmations by 1 — don't double-bump
316
+ resurrected.lastConfirmed = now;
317
+ if (!resurrected.evidence.includes(newInsight.evidence.slice(0, 40))) {
318
+ const merged = `${resurrected.evidence} | ${newInsight.evidence}`;
319
+ resurrected.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
285
320
  }
286
321
  for (const aw of newInsight.appliesWhen) {
287
- if (!existing.appliesWhen.includes(aw)) {
288
- existing.appliesWhen.push(aw);
322
+ if (!resurrected.appliesWhen.includes(aw)) {
323
+ resurrected.appliesWhen.push(aw);
289
324
  }
290
325
  }
291
- existing.trend = computeTrend(existing);
292
- writeAwarenessState(state);
293
- renderAwareness(state);
294
- return { action: "merged", insight: existing };
326
+ resurrected.trend = computeTrend(resurrected);
327
+ state.topInsights.push(resurrected);
328
+ // Enforce 20-item cap — demote lowest if over limit
329
+ if (state.topInsights.length > 20) {
330
+ state.topInsights.sort((a, b) => b.confirmations - a.confirmations);
331
+ const demoted = state.topInsights.pop();
332
+ archiveInsight(demoted);
333
+ }
334
+ return { state, result: { action: "added", insight: resurrected } };
295
335
  }
296
- // Moderate topic match → check evidence before merging
297
- const existingEvKeywords = extractKeywords(existing.evidence, 4);
298
- const newEvKeywords = extractKeywords(newInsight.evidence, 4);
299
- const evOverlap = newEvKeywords.filter((k) => existingEvKeywords.some((ek) => ek.includes(k) || k.includes(ek)));
300
- const evRatio = evOverlap.length / Math.max(newEvKeywords.length, existingEvKeywords.length, 1);
301
- if (evRatio > 0.3) {
302
- // Same topic, similar evidence → merge
303
- existing.confirmations++;
304
- existing.lastConfirmed = now;
305
- if (!existing.evidence.includes(newInsight.evidence.slice(0, 40))) {
306
- const merged = `${existing.evidence} | ${newInsight.evidence}`;
307
- existing.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
336
+ let bestMatch = null;
337
+ for (let i = 0; i < state.topInsights.length; i++) {
338
+ const existing = state.topInsights[i];
339
+ const existingKeywords = extractKeywords(existing.title, 6);
340
+ const overlap = newKeywords.filter((k) => existingKeywords.some((ek) => ek.includes(k) || k.includes(ek)));
341
+ const ratio = overlap.length / Math.max(newKeywords.length, existingKeywords.length, 1);
342
+ if (ratio > 0.5 && (!bestMatch || ratio > bestMatch.overlap)) {
343
+ bestMatch = { idx: i, overlap: ratio };
308
344
  }
309
- for (const aw of newInsight.appliesWhen) {
310
- if (!existing.appliesWhen.includes(aw)) {
311
- existing.appliesWhen.push(aw);
345
+ }
346
+ if (bestMatch) {
347
+ const existing = state.topInsights[bestMatch.idx];
348
+ // Two-pass merge: if topic overlap is very strong (>0.6), always merge (confirmation).
349
+ // If topic overlap is moderate (0.5-0.6), check evidence similarity to avoid merging
350
+ // distinct insights that happen to share vocabulary.
351
+ if (bestMatch.overlap > 0.6) {
352
+ // Strong topic match → merge (strengthen)
353
+ existing.confirmations++;
354
+ existing.lastConfirmed = now;
355
+ // Only append evidence if it's not already present (prevents "evidence | evidence")
356
+ if (!existing.evidence.includes(newInsight.evidence.slice(0, 40))) {
357
+ const merged = `${existing.evidence} | ${newInsight.evidence}`;
358
+ existing.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
312
359
  }
360
+ for (const aw of newInsight.appliesWhen) {
361
+ if (!existing.appliesWhen.includes(aw)) {
362
+ existing.appliesWhen.push(aw);
363
+ }
364
+ }
365
+ existing.trend = computeTrend(existing);
366
+ return { state, result: { action: "merged", insight: existing } };
367
+ }
368
+ // Moderate topic match → check evidence before merging
369
+ const existingEvKeywords = extractKeywords(existing.evidence, 4);
370
+ const newEvKeywords = extractKeywords(newInsight.evidence, 4);
371
+ const evOverlap = newEvKeywords.filter((k) => existingEvKeywords.some((ek) => ek.includes(k) || k.includes(ek)));
372
+ const evRatio = evOverlap.length / Math.max(newEvKeywords.length, existingEvKeywords.length, 1);
373
+ if (evRatio > 0.3) {
374
+ // Same topic, similar evidence → merge
375
+ existing.confirmations++;
376
+ existing.lastConfirmed = now;
377
+ if (!existing.evidence.includes(newInsight.evidence.slice(0, 40))) {
378
+ const merged = `${existing.evidence} | ${newInsight.evidence}`;
379
+ existing.evidence = merged.length > 1500 ? merged.slice(0, 1500) : merged;
380
+ }
381
+ for (const aw of newInsight.appliesWhen) {
382
+ if (!existing.appliesWhen.includes(aw)) {
383
+ existing.appliesWhen.push(aw);
384
+ }
385
+ }
386
+ existing.trend = computeTrend(existing);
387
+ return { state, result: { action: "merged", insight: existing } };
313
388
  }
314
- existing.trend = computeTrend(existing);
315
- writeAwarenessState(state);
316
- renderAwareness(state);
317
- return { action: "merged", insight: existing };
389
+ // Same topic, very different evidence → add as separate insight
390
+ // Fall through to the "new insight" path below
318
391
  }
319
- // Same topic, very different evidence → add as separate insight
320
- // Fall through to the "new insight" path below
321
- }
322
- // New insight
323
- const insight = {
324
- id: `insight-${Date.now()}`,
325
- title: newInsight.title,
326
- evidence: newInsight.evidence,
327
- confirmations: 1,
328
- lastConfirmed: now,
329
- appliesWhen: newInsight.appliesWhen,
330
- source: newInsight.source,
331
- source_project: newInsight.source_project ?? "_global",
332
- severity: newInsight.severity,
333
- trend: "stable",
334
- };
335
- if (state.topInsights.length < 20) {
392
+ // New insight
393
+ const insight = {
394
+ id: `insight-${Date.now()}`,
395
+ title: newInsight.title,
396
+ evidence: newInsight.evidence,
397
+ confirmations: 1,
398
+ lastConfirmed: now,
399
+ appliesWhen: newInsight.appliesWhen,
400
+ source: newInsight.source,
401
+ source_project: newInsight.source_project ?? "_global",
402
+ severity: newInsight.severity,
403
+ trend: "stable",
404
+ };
405
+ if (state.topInsights.length < 20) {
406
+ state.topInsights.push(insight);
407
+ return { state, result: { action: "added", insight } };
408
+ }
409
+ // Over 20: demote lowest-confirmation insight to archive (not deleted)
410
+ state.topInsights.sort((a, b) => b.confirmations - a.confirmations);
411
+ const demoted = state.topInsights.pop();
412
+ archiveInsight(demoted);
336
413
  state.topInsights.push(insight);
337
- writeAwarenessState(state);
338
- renderAwareness(state);
339
- return { action: "added", insight };
340
- }
341
- // Over 20: demote lowest-confirmation insight to archive (not deleted)
342
- state.topInsights.sort((a, b) => b.confirmations - a.confirmations);
343
- const demoted = state.topInsights.pop();
344
- archiveInsight(demoted);
345
- state.topInsights.push(insight);
346
- writeAwarenessState(state);
347
- renderAwareness(state);
348
- return { action: "replaced", insight };
414
+ return { state, result: { action: "replaced", insight } };
415
+ }); // end mutateAwarenessState
349
416
  }
350
417
  /**
351
418
  * Detect compound insights — patterns spanning 3+ individual insights.
352
419
  * Looks for shared appliesWhen keywords across insights.
353
420
  */
354
- export function detectCompoundInsights() {
355
- const state = readAwarenessState();
356
- if (!state || state.topInsights.length < 3)
357
- return [];
358
- // Group insights by shared appliesWhen keywords
359
- const keywordMap = new Map();
360
- for (const insight of state.topInsights) {
361
- for (const aw of insight.appliesWhen) {
362
- const key = aw.toLowerCase();
363
- if (!keywordMap.has(key))
364
- keywordMap.set(key, []);
365
- keywordMap.get(key).push(insight);
421
+ export async function detectCompoundInsights() {
422
+ // fix6-locks: read→derive→write span under the state lock (same lost-update
423
+ // class as addInsight).
424
+ return mutateAwarenessState((state) => {
425
+ if (!state || state.topInsights.length < 3)
426
+ return { result: [] };
427
+ // Group insights by shared appliesWhen keywords
428
+ const keywordMap = new Map();
429
+ for (const insight of state.topInsights) {
430
+ for (const aw of insight.appliesWhen) {
431
+ const key = aw.toLowerCase();
432
+ if (!keywordMap.has(key))
433
+ keywordMap.set(key, []);
434
+ keywordMap.get(key).push(insight);
435
+ }
366
436
  }
367
- }
368
- const compounds = [];
369
- for (const [keyword, insights] of keywordMap) {
370
- if (insights.length >= 3) {
371
- const id = `compound-${keyword}`;
372
- // Don't duplicate
373
- if (state.compoundInsights.some((c) => c.id === id))
374
- continue;
375
- compounds.push({
376
- id,
377
- title: `Pattern: "${keyword}" appears across ${insights.length} insights`,
378
- sourceInsights: insights.map((i) => i.id),
379
- pattern: insights.map((i) => i.title).join(" + "),
380
- confidence: Math.min(1.0, insights.length * 0.25),
381
- });
437
+ const compounds = [];
438
+ for (const [keyword, insights] of keywordMap) {
439
+ if (insights.length >= 3) {
440
+ const id = `compound-${keyword}`;
441
+ // Don't duplicate
442
+ if (state.compoundInsights.some((c) => c.id === id))
443
+ continue;
444
+ compounds.push({
445
+ id,
446
+ title: `Pattern: "${keyword}" appears across ${insights.length} insights`,
447
+ sourceInsights: insights.map((i) => i.id),
448
+ pattern: insights.map((i) => i.title).join(" + "),
449
+ confidence: Math.min(1.0, insights.length * 0.25),
450
+ });
451
+ }
382
452
  }
383
- }
384
- if (compounds.length > 0) {
385
- state.compoundInsights = [...state.compoundInsights, ...compounds].slice(0, 10);
386
- writeAwarenessState(state);
387
- renderAwareness(state);
388
- }
389
- return compounds;
453
+ if (compounds.length > 0) {
454
+ state.compoundInsights = [...state.compoundInsights, ...compounds].slice(0, 10);
455
+ return { state, result: compounds };
456
+ }
457
+ return { result: compounds };
458
+ }); // end mutateAwarenessState
390
459
  }
391
460
  /**
392
461
  * Detect crystallization CANDIDATES — clusters of ≥`minCluster` top-insights
@@ -396,16 +465,36 @@ export function detectCompoundInsights() {
396
465
  *
397
466
  * Operates on the GLOBAL awareness singleton (no project arg — readAwarenessState
398
467
  * takes none). Excludes insights already prefixed CRYSTALLIZED / CRITICAL.
468
+ *
469
+ * fix10 (2026-09-12) — the self-consuming seed rule: excluding CRYSTALLIZED
470
+ * insights entirely meant that once a cluster crystallized, its mass could
471
+ * never help a NEW related insight reach minCluster again — clusters consumed
472
+ * themselves and the gate went permanently quiet (09-10 dream report: largest
473
+ * cluster = 2 insights / 18× confirmed, blocked by the 3-insight minimum
474
+ * while a related CRYSTALLIZED insight sat excluded). With
475
+ * `includeCrystallizedEvidence: true`, CRYSTALLIZED insights count as cluster
476
+ * EVIDENCE (membership + confirmations) but a qualifying cluster must carry
477
+ * ≥1 fresh (non-crystallized) member, and the deterministic graduation path
478
+ * (safety-consolidation.ts) skips any cluster with crystallized members so
479
+ * nothing is ever re-graduated. CRITICAL insights stay excluded in both modes
480
+ * (they don't crystallize — they stay sharp). Default `false` preserves the
481
+ * pre-fix behavior exactly.
399
482
  */
400
483
  export function findCrystallizationCandidates(opts = {}) {
401
484
  const minCluster = opts.minCluster ?? 3;
402
485
  const minTotalConfirm = opts.minTotalConfirm ?? 5;
486
+ const includeCrystallized = opts.includeCrystallizedEvidence === true;
403
487
  const state = readAwarenessState();
404
488
  if (!state || state.topInsights.length < minCluster)
405
489
  return [];
490
+ const isCrystallized = (i) => /^\s*crystallized\b/i.test(i.title ?? "");
406
491
  // Exclude insights already crystallized or marked critical (case-insensitive
407
- // title prefix — tolerate "CRYSTALLIZED:", "CRITICAL ", etc.).
408
- const eligible = state.topInsights.filter((i) => !/^\s*(crystallized|critical)\b/i.test(i.title ?? ""));
492
+ // title prefix — tolerate "CRYSTALLIZED:", "CRITICAL ", etc.). When
493
+ // includeCrystallizedEvidence is set, crystallized insights stay eligible
494
+ // as evidence; CRITICAL is excluded unconditionally.
495
+ const eligible = state.topInsights.filter((i) => includeCrystallized
496
+ ? !/^\s*critical\b/i.test(i.title ?? "")
497
+ : !/^\s*(crystallized|critical)\b/i.test(i.title ?? ""));
409
498
  if (eligible.length < minCluster)
410
499
  return [];
411
500
  // Normalize appliesWhen tokens once per insight.
@@ -435,6 +524,12 @@ export function findCrystallizationCandidates(opts = {}) {
435
524
  const totalConfirm = members.reduce((s, i) => s + i.confirmations, 0);
436
525
  if (totalConfirm < minTotalConfirm)
437
526
  continue;
527
+ // fix10: crystallized members are evidence, never the whole cluster — a
528
+ // cluster with zero fresh members has nothing new to say.
529
+ const crystallizedMembers = members.filter(isCrystallized).length;
530
+ const freshMembers = members.length - crystallizedMembers;
531
+ if (freshMembers < 1)
532
+ continue;
438
533
  const ids = members.map((m) => m.id).sort();
439
534
  const memberKey = ids.join(",");
440
535
  if (seenMemberSets.has(memberKey))
@@ -446,6 +541,8 @@ export function findCrystallizationCandidates(opts = {}) {
446
541
  insight_titles: members.map((m) => m.title),
447
542
  size: members.length,
448
543
  total_confirmations: totalConfirm,
544
+ crystallized_members: crystallizedMembers,
545
+ fresh_members: freshMembers,
449
546
  });
450
547
  }
451
548
  return candidates;
@@ -453,7 +550,7 @@ export function findCrystallizationCandidates(opts = {}) {
453
550
  /**
454
551
  * Render awareness state into the 200-line markdown document.
455
552
  */
456
- export function renderAwareness(state) {
553
+ export async function renderAwareness(state) {
457
554
  const lines = [];
458
555
  lines.push("# Awareness");
459
556
  lines.push(`> Last updated: ${state.lastUpdated}`);
@@ -502,6 +599,6 @@ export function renderAwareness(state) {
502
599
  else {
503
600
  lines.push("_(none detected yet)_");
504
601
  }
505
- writeAwareness(lines.join("\n"));
602
+ await writeAwareness(lines.join("\n"));
506
603
  }
507
604
  //# sourceMappingURL=awareness.js.map