@jjh32456/dsh-longlive 1.6.7 → 1.8.0

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 (289) hide show
  1. package/CHANGELOG.md +70 -1508
  2. package/LICENSE +1 -1
  3. package/QUICKSTART.md +34 -13
  4. package/README.en.md +18 -7
  5. package/README.md +34 -9
  6. package/SPEC.md +5 -5
  7. package/cordis.patch.yml +23 -9
  8. package/docs/ANSWER-GUARD.md +92 -0
  9. package/docs/ARCHITECTURE.md +4 -3
  10. package/docs/AUTO-RECALL-WIRING.md +1 -1
  11. package/docs/AUTO-RECALL.md +15 -9
  12. package/docs/CONFIG.md +168 -35
  13. package/docs/ERRORS.md +17 -5
  14. package/docs/FAQ.md +7 -7
  15. package/docs/FEATURES.md +96 -28
  16. package/docs/MIGRATION-1.6.0.md +2 -2
  17. package/docs/OPERATIONS.md +6 -6
  18. package/docs/PANEL-INTEGRATION.md +6 -0
  19. package/docs/PRIVACY.md +88 -0
  20. package/docs/QUICKSTART.md +5 -5
  21. package/docs/README.en.md +4 -2
  22. package/docs/RESIDENT-WATCHER.md +1 -1
  23. package/docs/SESSION-WATCH.md +6 -6
  24. package/docs/TROUBLESHOOTING.md +4 -4
  25. package/package.json +47 -117
  26. package/runbook.md +2 -2
  27. package/scripts/backfill-auto-cards.mjs +98 -0
  28. package/scripts/install-surgery-task.ps1 +5 -2
  29. package/scripts/lib/session-watch-fixture.mjs +1 -1
  30. package/scripts/longlive-doctor.mjs +6 -0
  31. package/scripts/migrate-180.mjs +163 -0
  32. package/scripts/recall-index-build.mjs +128 -0
  33. package/scripts/session-watch-drill.mjs +1 -1
  34. package/scripts/surgery-run.cmd +1 -1
  35. package/scripts/unattended-surgery.ps1 +5 -2
  36. package/scripts/verify-card-anchors.mjs +138 -0
  37. package/src/actions/audit.js +125 -0
  38. package/src/actions/evidence.js +122 -0
  39. package/src/actions/fs.js +162 -0
  40. package/src/activity/index.js +760 -0
  41. package/src/activity/model.js +351 -0
  42. package/src/activity/store.js +644 -0
  43. package/src/activity/thinking.js +176 -0
  44. package/src/adapters/constants.js +11 -0
  45. package/src/adapters/engram/data/aliases.json +51 -0
  46. package/src/adapters/engram/data/policy.json +8 -0
  47. package/src/adapters/engram/data/routing-rules.json +546 -0
  48. package/src/adapters/engram/index.js +235 -0
  49. package/src/adapters/registry.js +315 -0
  50. package/src/answer/audit.js +193 -0
  51. package/src/answer/evidence.js +30 -0
  52. package/src/answer/guard.js +1370 -0
  53. package/src/answer/index.js +1067 -0
  54. package/src/answer/query.js +111 -0
  55. package/src/answer/second-hop.mjs +101 -0
  56. package/src/auto-truncate.js +1 -1
  57. package/src/config.js +171 -47
  58. package/src/deps.js +6 -4
  59. package/src/features.js +182 -6
  60. package/src/heartbeat.js +156 -23
  61. package/src/identity/handover.js +52 -1
  62. package/src/identity/index.js +13 -5
  63. package/src/identity/inject-position.js +2 -2
  64. package/src/index.js +97 -7
  65. package/src/lifecycle/gap-clocks.js +328 -0
  66. package/src/lifecycle/index.js +269 -0
  67. package/src/live.js +22 -2
  68. package/src/memory/activity-capture.js +229 -0
  69. package/src/memory/anchors.js +194 -0
  70. package/src/memory/audit-records.js +222 -0
  71. package/src/memory/auto-cards.js +401 -0
  72. package/src/memory/capture.js +442 -0
  73. package/src/memory/card-anchors.js +203 -0
  74. package/src/memory/conflicts.js +106 -0
  75. package/src/memory/decay.js +311 -0
  76. package/src/memory/distill.js +471 -0
  77. package/src/memory/event-index.js +917 -0
  78. package/src/memory/evidence-chain.js +295 -0
  79. package/src/memory/evidence.js +145 -0
  80. package/src/memory/filter-runner.js +1 -1
  81. package/src/memory/filter.js +5 -1
  82. package/src/memory/forget-v2.js +410 -0
  83. package/src/memory/forget.js +71 -0
  84. package/src/memory/frames-activation.js +247 -0
  85. package/src/memory/fts-query.js +174 -0
  86. package/src/memory/governance.js +604 -0
  87. package/src/memory/index.js +1 -0
  88. package/src/memory/l2-gate.js +169 -0
  89. package/src/memory/lock.js +121 -0
  90. package/src/memory/migrate.js +139 -0
  91. package/src/memory/recall-v2.js +223 -0
  92. package/src/memory/recall.js +65 -2
  93. package/src/memory/records.js +425 -0
  94. package/src/memory/retention.js +128 -0
  95. package/src/memory/review.js +124 -0
  96. package/src/memory/trust.js +88 -0
  97. package/src/memory/version-chain.js +264 -0
  98. package/src/memory/wal.js +137 -0
  99. package/src/memory/working-frame.js +516 -0
  100. package/src/metrics/classify.mjs +5 -3
  101. package/src/metrics/index.mjs +21 -1
  102. package/src/metrics/prestep-latency.mjs +300 -0
  103. package/src/metrics/store.mjs +25 -0
  104. package/src/policy-profile.js +18 -3
  105. package/src/recall/anaphora.mjs +87 -0
  106. package/src/recall/cards.mjs +7 -0
  107. package/src/recall/embedding.mjs +8 -8
  108. package/src/recall/entities.mjs +112 -0
  109. package/src/recall/index.js +235 -19
  110. package/src/recall/inject-order.mjs +10 -8
  111. package/src/recall/privacy.mjs +105 -16
  112. package/src/recall/recall-core.mjs +116 -10
  113. package/src/recall/shared-visibility.js +302 -0
  114. package/src/recall/time-normalizer.mjs +196 -0
  115. package/src/role/activation.js +191 -0
  116. package/src/role/attention.js +318 -0
  117. package/src/role/base.js +36 -0
  118. package/src/role/channels.js +423 -0
  119. package/src/role/index.js +425 -0
  120. package/src/role/interfaces.js +115 -0
  121. package/src/role/personality.js +370 -0
  122. package/src/role/readers.js +151 -0
  123. package/src/role/relationships.js +477 -0
  124. package/src/role/store.js +202 -0
  125. package/src/role/writeprotect.js +373 -0
  126. package/src/router/aliases.json +176 -25
  127. package/src/router/background/agent-runner.mjs +1 -1
  128. package/src/router/background/anchor.mjs +1 -1
  129. package/src/router/background/audit.mjs +2 -2
  130. package/src/router/background/budget-ledger.mjs +2 -2
  131. package/src/router/background/host-sim.mjs +1 -1
  132. package/src/router/background/memory.mjs +4 -4
  133. package/src/router/background/queue.mjs +1 -1
  134. package/src/router/background/retry.mjs +1 -1
  135. package/src/router/background/router.mjs +1 -1
  136. package/src/router/background/stream.mjs +1 -1
  137. package/src/router/background/tool-policy.mjs +1 -1
  138. package/src/router/design-headings.json +5 -5
  139. package/src/router/face/config.mjs +1 -1
  140. package/src/router/face/identity.mjs +3 -3
  141. package/src/router/judge.mjs +8 -7
  142. package/src/router/policies/generic.json +21 -4
  143. package/src/router/route.js +109 -22
  144. package/src/router/router.mjs +10 -6
  145. package/src/router/routing-rules.json +260 -445
  146. package/src/router/run-sim.mjs +8 -8
  147. package/src/router/runtime.js +23 -12
  148. package/src/router/service/board.mjs +95 -15
  149. package/src/router/service/config.mjs +5 -5
  150. package/src/router/service/context.mjs +1 -1
  151. package/src/router/service/hint.mjs +14 -0
  152. package/src/router/service/queue.mjs +1 -1
  153. package/src/router/service/service.mjs +27 -11
  154. package/src/router/shadow.mjs +4 -3
  155. package/src/surgery-recovery.js +2 -2
  156. package/src/tool-output.js +2 -2
  157. package/src/tools.js +39 -7
  158. package/src/truncate-visible.js +2 -2
  159. package/src/ui/actions.js +1312 -0
  160. package/src/ui/panel-api.js +367 -0
  161. package/src/ui/panel-auth.js +251 -0
  162. package/src/ui/panel-integrity.js +243 -0
  163. package/src/ui/routes-readonly.js +695 -0
  164. package/src/ui/routes.js +3 -0
  165. package/docs/DEV.md +0 -279
  166. package/docs/PRESENCE-BUS-WIRING.md +0 -491
  167. package/docs/PRESENCE-BUS.md +0 -694
  168. package/docs/SURGERY.md +0 -186
  169. package/scripts/mark-core-cards.mjs +0 -289
  170. package/scripts/pack.mjs +0 -392
  171. package/scripts/router-proposals.mjs +0 -386
  172. package/src/router/fixtures/M1.json +0 -16
  173. package/src/router/fixtures/M2.json +0 -16
  174. package/src/router/fixtures/M3.json +0 -20
  175. package/src/router/fixtures/M4.json +0 -20
  176. package/src/router/fixtures/M5.json +0 -45
  177. package/src/router/fixtures/M6.json +0 -53
  178. package/src/router/fixtures/M7.json +0 -46
  179. package/src/router/fixtures/S1.json +0 -20
  180. package/src/router/fixtures/S2.json +0 -23
  181. package/src/router/fixtures/S3.json +0 -20
  182. package/src/router/fixtures/S4.json +0 -34
  183. package/src/router/fixtures/S5.json +0 -43
  184. package/src/router/fixtures/S6.json +0 -47
  185. package/src/router/fixtures/T1.json +0 -23
  186. package/src/router/fixtures/T2.json +0 -16
  187. package/src/router/fixtures/T3.json +0 -19
  188. package/src/router/fixtures/T4.json +0 -16
  189. package/src/router/fixtures/X1.json +0 -17
  190. package/src/router/fixtures/X2.json +0 -20
  191. package/src/router/gen-design-headings.mjs +0 -107
  192. package/src/router/policies/owner-rulings-2026-11-03.json +0 -62
  193. package/test/auto-recall.test.mjs +0 -474
  194. package/test/auto-truncate.test.mjs +0 -931
  195. package/test/autobind.test.mjs +0 -385
  196. package/test/bus.test.mjs +0 -1572
  197. package/test/cli-guard.test.mjs +0 -198
  198. package/test/conclusion.test.mjs +0 -408
  199. package/test/config-schema.test.mjs +0 -204
  200. package/test/d6-output.test.mjs +0 -194
  201. package/test/d6.test.mjs +0 -395
  202. package/test/deps.test.mjs +0 -342
  203. package/test/doctor-setup.test.mjs +0 -297
  204. package/test/embedding-recall.test.mjs +0 -347
  205. package/test/feature-flags.test.mjs +0 -568
  206. package/test/filter-shadow.test.mjs +0 -170
  207. package/test/fixtures/baseline-0.8.0-registration.json +0 -556
  208. package/test/fixtures/d6-header-tools.json +0 -1
  209. package/test/fixtures/lock-child.mjs +0 -67
  210. package/test/fixtures/pre-step-container.mjs +0 -100
  211. package/test/fixtures/privacy-memory/topics/pii-unmarked.md +0 -9
  212. package/test/fixtures/privacy-memory/topics/secret-local-only.md +0 -11
  213. package/test/fixtures/profile-session-longlive-config.json +0 -20
  214. package/test/fixtures/proposal-cas-child.mjs +0 -66
  215. package/test/host-engine-status.test.mjs +0 -307
  216. package/test/hot-truncate.test.mjs +0 -1349
  217. package/test/identity-card-marker.test.mjs +0 -307
  218. package/test/identity-router/run.mjs +0 -721
  219. package/test/integration-pre-step.test.mjs +0 -553
  220. package/test/live.test.mjs +0 -1020
  221. package/test/maintenance-schedule.test.mjs +0 -538
  222. package/test/memory.test.mjs +0 -2828
  223. package/test/metrics.test.mjs +0 -478
  224. package/test/orchestrator.test.mjs +0 -266
  225. package/test/p1_probe.mjs +0 -97
  226. package/test/packaging.test.mjs +0 -182
  227. package/test/portability.test.mjs +0 -343
  228. package/test/rc4-regressions.test.mjs +0 -562
  229. package/test/rc5-regressions.test.mjs +0 -197
  230. package/test/rc6-chinese.test.mjs +0 -394
  231. package/test/router-1100/apply-off.test.mjs +0 -175
  232. package/test/router-1100/budget-reconcile.test.mjs +0 -215
  233. package/test/router-1100/config-context.test.mjs +0 -211
  234. package/test/router-1100/helpers.mjs +0 -129
  235. package/test/router-1100/hint-envelope.test.mjs +0 -150
  236. package/test/router-1100/lock-crossproc.test.mjs +0 -206
  237. package/test/router-1100/proposal-cas-crossproc.test.mjs +0 -184
  238. package/test/router-1100/router-apply.test.mjs +0 -372
  239. package/test/router-1100/router-fixb.test.mjs +0 -602
  240. package/test/router-1100/router-proposals.test.mjs +0 -405
  241. package/test/router-1100/router-queue-lease-wal.test.mjs +0 -355
  242. package/test/router-1100/router-security-cr.test.mjs +0 -333
  243. package/test/router-1100/service-lifecycle.test.mjs +0 -220
  244. package/test/router-1100/tools-contract.test.mjs +0 -164
  245. package/test/router-1100/turn-reflect-tick.test.mjs +0 -89
  246. package/test/router-1100/v6-contract.test.mjs +0 -158
  247. package/test/router-1100/v6b-contract.test.mjs +0 -293
  248. package/test/router-1100/v6c-contract.test.mjs +0 -249
  249. package/test/router-1100/wal-rotation.test.mjs +0 -375
  250. package/test/router-1100/wp1-config.test.mjs +0 -170
  251. package/test/router-1100/wp1-default-off.test.mjs +0 -77
  252. package/test/router-1100/wp1-model-status.test.mjs +0 -90
  253. package/test/router-1100/wp1-status.test.mjs +0 -220
  254. package/test/router-1100/wp1-tools.test.mjs +0 -146
  255. package/test/router-1100/wp5-cli.test.mjs +0 -240
  256. package/test/router-1100/wp5-model-auto.test.mjs +0 -418
  257. package/test/router-1100/wp6-merge.test.mjs +0 -386
  258. package/test/router-1100/wp6-wake.test.mjs +0 -502
  259. package/test/router-background/audit.test.mjs +0 -37
  260. package/test/router-background/budget-ledger.test.mjs +0 -330
  261. package/test/router-background/cross-process.test.mjs +0 -222
  262. package/test/router-background/fixtures/cross-child.mjs +0 -85
  263. package/test/router-background/fixtures/real-shapes.mjs +0 -239
  264. package/test/router-background/router.test.mjs +0 -1044
  265. package/test/router-background/stream-retry.test.mjs +0 -358
  266. package/test/router-background/tool-agent.test.mjs +0 -384
  267. package/test/router-face/bridge.test.mjs +0 -169
  268. package/test/router-face/face.test.mjs +0 -316
  269. package/test/router-failclosed.test.mjs +0 -466
  270. package/test/router-identity.test.mjs +0 -384
  271. package/test/router-l1-l2.contract.test.mjs +0 -1075
  272. package/test/router-memory-tools.test.mjs +0 -262
  273. package/test/router-policy.test.mjs +0 -225
  274. package/test/router-runtime.test.mjs +0 -438
  275. package/test/router-shadow.test.mjs +0 -287
  276. package/test/router.test.mjs +0 -903
  277. package/test/run-rc.mjs +0 -299
  278. package/test/run.mjs +0 -2469
  279. package/test/safety-defaults.test.mjs +0 -179
  280. package/test/seeded-load.test.mjs +0 -436
  281. package/test/session-original.test.mjs +0 -338
  282. package/test/surgery-recovery.test.mjs +0 -936
  283. package/test/t7_drive.mjs +0 -151
  284. package/test/tool-output.test.mjs +0 -393
  285. package/test/tool-schema.test.mjs +0 -177
  286. package/test/tools_contract.test.mjs +0 -716
  287. package/test/truncate-visible.test.mjs +0 -1150
  288. package/test/ui-flags.test.mjs +0 -477
  289. package/test/v4-hardening.test.mjs +0 -427
@@ -0,0 +1,442 @@
1
+ // src/memory/capture.js — M2-B:写入路径全覆盖(turn 内/轮末 / 会话启动 / 宿主生命周期 /
2
+ // 离线空窗补记 / 场外事件)+ 幂等 + 跨进程锁(lock.js)+ WAL(wal.js)
3
+ //
4
+ // 设计(提案 §2.1 写入矩阵 / §2.3 幂等 / §2.4 双会话并发 / PLAN §2.7):
5
+ // * 每个写路径 = lease(O_EXCL)→ WAL pending → 真正写(索引/记录/journal)→ WAL done;
6
+ // 崩溃后 replay pending(写入本身幂等,不产生半行)。
7
+ // * captureTurn:从 L0 抽该会话本轮(或全部未入库轮)→ EventRecord 入索引(幂等 key=id+digest)。
8
+ // * captureMemoryGap:把双时钟(host-gap / memory-gap)**分两行**写 journal,
9
+ // 幂等 key 由 (from,to) 决定;同时写索引 lifecycle 事件(可被回忆检索)。
10
+ // * captureOffFieldNote(场外事件):records.jsonl 追加 kind=episode(机器断言层)。
11
+ // 禁止触碰 L0:本模块只读会话日志,所有写都在 <memoryRoot>。
12
+
13
+ import crypto from 'node:crypto';
14
+ import fs from 'node:fs';
15
+ import path from 'node:path';
16
+
17
+ import { parseSession, stableStringify } from '../codec.js';
18
+ import { makeSessionTurnAnchor, turnDigest } from './anchors.js';
19
+ import { appendClaimFromRecord } from './governance.js';
20
+ import { appendAutoCards } from './auto-cards.js';
21
+ import { evaluateEvidenceForWrite, evidenceFromAnchors } from './records.js';
22
+ import { extractTurns, openEventIndex } from './event-index.js';
23
+ import { acquireLease, releaseLease } from './lock.js';
24
+ import { createWal } from './wal.js';
25
+
26
+ export const RECORDS_SCHEMA = 'records/v1';
27
+
28
+ function sha256Hex(text) {
29
+ return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
30
+ }
31
+
32
+ function sha1Short(text, length = 12) {
33
+ return crypto.createHash('sha1').update(text, 'utf8').digest('hex').slice(0, length);
34
+ }
35
+
36
+ function nowDate(now) {
37
+ const value = typeof now === 'function' ? now() : new Date();
38
+ return value instanceof Date ? value : new Date(value);
39
+ }
40
+
41
+ export function journalPathOf(memoryRoot, atMs) {
42
+ const date = new Date(atMs);
43
+ const month = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
44
+ return path.join(path.resolve(String(memoryRoot)), 'journal', `${month}.md`);
45
+ }
46
+
47
+ export function recordsPathOf(memoryRoot) {
48
+ return path.join(path.resolve(String(memoryRoot)), '.longlive', 'records.jsonl');
49
+ }
50
+
51
+ export function writeFileAtomic(file, content) {
52
+ fs.mkdirSync(path.dirname(file), { recursive: true });
53
+ const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
54
+ fs.writeFileSync(tmp, content, 'utf8');
55
+ fs.renameSync(tmp, file);
56
+ }
57
+
58
+ /**
59
+ * Append an idempotent journal line. `capKey` is hashed into a `<!-- cap:… -->`
60
+ * marker; the same key is written at most once (checked by substring scan).
61
+ */
62
+ export function appendJournalLine({ memoryRoot, atMs, text, capKey }) {
63
+ const file = journalPathOf(memoryRoot, atMs);
64
+ const cap = sha1Short(`lifecycle:${capKey}`);
65
+ let existing = '';
66
+ try {
67
+ existing = fs.readFileSync(file, 'utf8');
68
+ } catch {
69
+ existing = '';
70
+ }
71
+ if (existing.includes(`<!-- cap:${cap} -->`)) return { ok: true, written: false, file, cap };
72
+ const date = new Date(atMs);
73
+ const stamp = `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')} ${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
74
+ const prefix = existing === '' ? '' : (existing.endsWith('\n') ? '' : '\n');
75
+ fs.mkdirSync(path.dirname(file), { recursive: true });
76
+ fs.appendFileSync(file, `${prefix}- **${stamp}** ${text} <!-- cap:${cap} -->\n`, 'utf8');
77
+ return { ok: true, written: true, file, cap };
78
+ }
79
+
80
+ /** Append one records.jsonl assertion (idempotent by record.id). */
81
+ export function appendRecordLine({ memoryRoot, record }) {
82
+ const file = recordsPathOf(memoryRoot);
83
+ const id = record.id;
84
+ let existing = '';
85
+ try {
86
+ existing = fs.readFileSync(file, 'utf8');
87
+ } catch {
88
+ existing = '';
89
+ }
90
+ if (existing.includes(`"id":"${id}"`)) return { ok: true, written: false, id, file };
91
+ fs.mkdirSync(path.dirname(file), { recursive: true });
92
+ const line = JSON.stringify({ schema: RECORDS_SCHEMA, ...record });
93
+ fs.appendFileSync(file, `${line}\n`, 'utf8');
94
+ return { ok: true, written: true, id, file };
95
+ }
96
+
97
+ export function makeRecordId({ content, createdAt, source }) {
98
+ return `rec:${sha1Short(`${content}|${createdAt}|${source}`, 12)}`;
99
+ }
100
+
101
+ /**
102
+ * Create the capture facade.
103
+ *
104
+ * @param {object} options
105
+ * @param {string} options.memoryRoot
106
+ * @param {() => Date} [options.now]
107
+ * @param {string[]} [options.sessionRoots]
108
+ * @param {number} [options.lockTtlMs]
109
+ */
110
+ export function createCapture(options = {}) {
111
+ const memoryRoot = path.resolve(String(options.memoryRoot ?? ''));
112
+ if (memoryRoot === '') throw new Error('E_MEMORY_ROOT: capture requires memoryRoot');
113
+ const sessionRoots = Array.isArray(options.sessionRoots) ? options.sessionRoots : [];
114
+ const now = typeof options.now === 'function' ? options.now : () => new Date();
115
+ const holder = typeof options.holder === 'string' && options.holder !== '' ? options.holder : `capture-${process.pid}`;
116
+ const lockTtlMs = Number.isInteger(options.lockTtlMs) ? options.lockTtlMs : undefined;
117
+ const lockFile = path.join(memoryRoot, '.longlive', 'memory', 'write.lock');
118
+ const wal = createWal({ memoryRoot, now });
119
+ const indexPath = path.join(memoryRoot, '.longlive', 'index', 'events.db');
120
+
121
+ function withLease(fn) {
122
+ const lease = acquireLease(lockFile, { holder, now, ...(lockTtlMs ? { ttlMs: lockTtlMs } : {}) });
123
+ try {
124
+ return fn(lease);
125
+ } finally {
126
+ releaseLease(lockFile, lease.holder);
127
+ }
128
+ }
129
+
130
+ function withIndex(fn) {
131
+ if (!fs.existsSync(indexPath)) {
132
+ throw new Error('E_EVENTS_INDEX_NOT_BUILT: run scripts/recall-index-build.mjs first');
133
+ }
134
+ const index = openEventIndex({ memoryRoot, now });
135
+ try {
136
+ return fn(index);
137
+ } finally {
138
+ index.close();
139
+ }
140
+ }
141
+
142
+ function findSessionLog(sessionId) {
143
+ const stack = sessionRoots.map((root) => path.resolve(root));
144
+ const seen = new Set();
145
+ while (stack.length > 0) {
146
+ const dir = stack.pop();
147
+ if (seen.has(dir)) continue;
148
+ seen.add(dir);
149
+ let entries = [];
150
+ try {
151
+ entries = fs.readdirSync(dir, { withFileTypes: true });
152
+ } catch {
153
+ continue;
154
+ }
155
+ for (const entry of entries) {
156
+ const full = path.join(dir, entry.name);
157
+ if (entry.isDirectory()) {
158
+ if (entry.name === sessionId) {
159
+ const file = path.join(full, 'session.v4.jsonl.zstd');
160
+ if (fs.existsSync(file)) return file;
161
+ }
162
+ stack.push(full);
163
+ }
164
+ }
165
+ }
166
+ return null;
167
+ }
168
+
169
+ /** Index native turns from a session log (turn-in/turn-end/会话启动 coverage). */
170
+ function captureTurn(input = {}) {
171
+ const sessionId = typeof input.sessionId === 'string' ? input.sessionId : '';
172
+ const logFile = typeof input.logFile === 'string' && input.logFile !== ''
173
+ ? input.logFile
174
+ : (sessionId !== '' ? findSessionLog(sessionId) : null);
175
+ if (!logFile) throw new Error(`E_SESSION_LOG_MISSING: ${sessionId}`);
176
+ return withLease(() => {
177
+ const walId = wal.begin('captureTurn', { sessionId, logFile, turn: input.turn ?? null, source: input.source ?? 'turn-end' });
178
+ try {
179
+ const parsed = parseSession(fs.readFileSync(logFile));
180
+ const records = extractTurns(parsed.header, parsed.events, parsed.frames, parsed.texts);
181
+ const selected = Number.isInteger(input.turn)
182
+ ? records.filter((record) => record.turn === input.turn)
183
+ : records;
184
+ const result = withIndex((index) => {
185
+ let inserted = 0;
186
+ for (const record of selected) {
187
+ record.builtAt = nowDate(now).getTime();
188
+ record.source = input.source ?? 'turn-end';
189
+ const written = index.upsertEvent(record, { source: record.source });
190
+ if (written.inserted) inserted += 1;
191
+ }
192
+ return { inserted, skipped: selected.length - inserted };
193
+ });
194
+ // 1.8.0: every captured turn gets one deterministic AutoCard pointing
195
+ // back at the exact session turn. Idempotent by EventRecord.id.
196
+ const cards = appendAutoCards({ memoryRoot, records: selected, now, skipLock: true });
197
+ wal.markDone(walId, { inserted: result.inserted, cards: cards.written });
198
+ return {
199
+ ok: true,
200
+ sessionId,
201
+ logFile,
202
+ turns: selected.length,
203
+ ...result,
204
+ cardsWritten: cards.written,
205
+ cardsSkipped: cards.skipped,
206
+ cardsFile: cards.file,
207
+ walId,
208
+ };
209
+ } catch (error) {
210
+ wal.markFailed(walId, error?.message ?? error);
211
+ throw error;
212
+ }
213
+ });
214
+ }
215
+
216
+ /** 会话启动:把会话当前所有轮补进索引(首次启动全覆盖)并写 boot 事件。 */
217
+ function captureSessionStart(input = {}) {
218
+ const result = captureTurn({ ...input, source: input.source ?? 'session-start' });
219
+ const event = captureLifecycleEvent({
220
+ event: 'session-start',
221
+ at: input.at,
222
+ data: { sessionId: result.sessionId, turns: result.turns },
223
+ });
224
+ return { ...result, lifecycleEvent: event };
225
+ }
226
+
227
+ /** 宿主生命周期事件(boot/shutdown/crash/restart)→ journal 行 + 索引事件。 */
228
+ function captureLifecycleEvent(input = {}) {
229
+ const at = Number.isFinite(input.at) ? input.at : nowDate(now).getTime();
230
+ const event = typeof input.event === 'string' ? input.event : 'lifecycle';
231
+ const key = `lifecycle:${event}:${input.key ?? Math.round(at / 1000)}`;
232
+ const journal = appendJournalLine({
233
+ memoryRoot,
234
+ atMs: at,
235
+ text: `宿主生命周期 **${event}**${input.text ? `:${input.text}` : ''}`,
236
+ capKey: key,
237
+ });
238
+ let indexed = null;
239
+ if (fs.existsSync(indexPath)) {
240
+ const summary = `宿主生命周期 ${event}${input.text ? `:${input.text}` : ''}`;
241
+ const digest = sha256Hex(stableStringify({ event, at, data: input.data ?? null }));
242
+ indexed = withIndex((index) => index.upsertEvent({
243
+ id: `evt:host-lifecycle:${sha1Short(key)}`,
244
+ sessionId: 'host-lifecycle',
245
+ turn: 0,
246
+ seqStart: null,
247
+ seqEnd: null,
248
+ timeStart: at,
249
+ timeEnd: at,
250
+ project: null,
251
+ kind: 'lifecycle',
252
+ topics: ['lifecycle'],
253
+ terms: [event],
254
+ summary,
255
+ counts: {},
256
+ anchors: [],
257
+ digest,
258
+ source: 'lifecycle',
259
+ builtAt: nowDate(now).getTime(),
260
+ }, { source: 'lifecycle' }));
261
+ }
262
+ return { ok: true, event, at, journal, indexed };
263
+ }
264
+
265
+ /** 离线空窗补记:host-gap 与 memory-gap 分两行写,幂等 key=(from,to)。 */
266
+ function captureMemoryGap(input = {}) {
267
+ const gaps = input.gaps;
268
+ if (!gaps || typeof gaps !== 'object') throw new Error('E_GAPS_REQUIRED: captureMemoryGap requires computeGaps() output');
269
+ const at = gaps.bootAt ? Date.parse(gaps.bootAt) : nowDate(now).getTime();
270
+ const out = { ok: true, journal: [], indexed: [] };
271
+ if (gaps.memoryGap && gaps.memoryGap.kind !== 'unknown') {
272
+ const from = gaps.memoryGap.from ?? 'unknown';
273
+ const to = gaps.memoryGap.to ?? 'unknown';
274
+ const evidence = gaps.memoryGap.activityEvidence ?? {};
275
+ const text = `记忆空窗 ${gaps.memoryGap.gapText}(上次记忆写入 ${String(from).slice(11, 19)},`
276
+ + `期间 ${evidence.toolOutputs ?? 0} 个 tool-output 活动证据)`;
277
+ out.journal.push(appendJournalLine({ memoryRoot, atMs: at, text, capKey: `memory-gap:${from}:${to}` }));
278
+ }
279
+ if (gaps.hostGap && gaps.hostGap.kind !== 'unknown') {
280
+ const from = gaps.hostGap.from ?? 'unknown';
281
+ const to = gaps.hostGap.to ?? 'unknown';
282
+ const text = `宿主中断 ${gaps.hostGap.gapText}(${String(from).slice(11, 19)} → ${String(to).slice(11, 19)} · 上次退出:${gaps.hostGap.prevExitForm ?? '未知'})`;
283
+ out.journal.push(appendJournalLine({ memoryRoot, atMs: at, text, capKey: `host-gap:${from}:${to}` }));
284
+ }
285
+ if (fs.existsSync(indexPath)) {
286
+ for (const [clock, gap] of [['memory-gap', gaps.memoryGap], ['host-gap', gaps.hostGap]]) {
287
+ if (!gap || gap.kind === 'unknown') continue;
288
+ const key = `${clock}:${gap.from}:${gap.to}`;
289
+ const clockText = clock === 'memory-gap' ? '记忆空窗' : '宿主中断';
290
+ const digest = sha256Hex(stableStringify({ clock, gap }));
291
+ out.indexed.push(withIndex((index) => index.upsertEvent({
292
+ id: `evt:host-lifecycle:${sha1Short(key)}`,
293
+ sessionId: 'host-lifecycle',
294
+ turn: 0,
295
+ seqStart: null,
296
+ seqEnd: null,
297
+ timeStart: at,
298
+ timeEnd: at,
299
+ project: null,
300
+ kind: 'lifecycle',
301
+ topics: ['lifecycle', clockText],
302
+ terms: [clock, clockText, gap.gapText],
303
+ summary: `${clockText} ${gap.gapText}`,
304
+ counts: {},
305
+ anchors: [],
306
+ digest,
307
+ source: 'lifecycle',
308
+ builtAt: nowDate(now).getTime(),
309
+ }, { source: 'lifecycle' })));
310
+ }
311
+ }
312
+ return out;
313
+ }
314
+
315
+ /** 场外事件(老大在外面做的事,口述补记)→ records.jsonl(kind=episode)。 */
316
+ function captureOffFieldNote(input = {}) {
317
+ const text = String(input.text ?? '').trim();
318
+ if (text === '') throw new Error('E_NOTE_EMPTY: memory_note requires text');
319
+ const at = Number.isFinite(input.at) ? input.at : nowDate(now).getTime();
320
+ const createdAt = new Date(at).toISOString();
321
+ const content = text;
322
+ const source = input.source ?? 'off-field-note';
323
+ const id = makeRecordId({ content, createdAt, source });
324
+ // EA-02:sourceTier 由服务端强制——场外补记只能是 user;调用方自报 host/agent 一律拒绝。
325
+ if (input.sourceTier !== undefined && input.sourceTier !== 'user') {
326
+ const error = new Error('E_SOURCE_TIER_SELF_REPORT: 不接受调用方自报 sourceTier');
327
+ error.code = 'E_SOURCE_TIER_SELF_REPORT';
328
+ throw error;
329
+ }
330
+ const sourceTier = 'user';
331
+ const anchors = Array.isArray(input.anchors) ? input.anchors : [];
332
+ const evidenceEval = evaluateEvidenceForWrite(anchors, { verifiedAt: createdAt });
333
+ const evidence = evidenceEval.evidence.map((entry) => ({
334
+ anchorId: entry.anchorId, sha256: entry.sha256, excerptRef: entry.excerptRef, verifiedAt: entry.verifiedAt,
335
+ valid: entry.valid, invalidCode: entry.invalidCode,
336
+ }));
337
+ const evidenceState = evidence.length === 0 ? 'unverified' : (evidenceEval.verified ? 'active' : 'unverified');
338
+ const record = {
339
+ id,
340
+ kind: 'episode',
341
+ content,
342
+ subject: null,
343
+ project: input.project ?? null,
344
+ salience: Number.isInteger(input.salience) ? input.salience : 3,
345
+ importance: 0.5,
346
+ status: 'active',
347
+ createdAt,
348
+ lastUsed: createdAt.slice(0, 10),
349
+ useCount: 0,
350
+ anchors: Array.isArray(input.anchors) ? input.anchors : [],
351
+ evidence,
352
+ sourceTier,
353
+ conflict: false,
354
+ conflict_with: [],
355
+ state: evidenceState,
356
+ evidenceVerified: evidenceEval.verified,
357
+ evidenceReasons: evidenceEval.reasons,
358
+ anchorStatus: evidence.length > 0 ? 'unverified' : 'missing',
359
+ supersedes: [],
360
+ supersededBy: null,
361
+ audit: { createdBy: 'memory-note', source },
362
+ };
363
+ const written = withLease(() => appendRecordLine({ memoryRoot, record }));
364
+ // Activation: runtime memory writes must also land Claims (not records-only).
365
+ let claim = null;
366
+ try {
367
+ claim = appendClaimFromRecord({ memoryRoot, record, now });
368
+ } catch (error) {
369
+ claim = { ok: false, code: error?.code ?? 'E_CLAIM_BRIDGE' };
370
+ }
371
+ return { ok: true, id, written: written.written, file: written.file, record, claim };
372
+ }
373
+
374
+ /** Replay pending WAL intents and retry failed ones once (idempotent). */
375
+ function replayWal() {
376
+ const handleEntry = (entry) => {
377
+ if (entry.op !== 'captureTurn') throw new Error(`E_WAL_OP_UNKNOWN: ${entry.op}`);
378
+ const payload = entry.payload ?? {};
379
+ const logFile = payload.logFile ?? findSessionLog(payload.sessionId);
380
+ if (!logFile) throw new Error(`E_SESSION_LOG_MISSING: ${payload.sessionId}`);
381
+ const parsed = parseSession(fs.readFileSync(logFile));
382
+ const records = extractTurns(parsed.header, parsed.events, parsed.frames, parsed.texts);
383
+ const selected = Number.isInteger(payload.turn)
384
+ ? records.filter((record) => record.turn === payload.turn)
385
+ : records;
386
+ withIndex((index) => {
387
+ for (const record of selected) {
388
+ record.builtAt = nowDate(now).getTime();
389
+ record.source = 'wal-replay';
390
+ index.upsertEvent(record, { source: record.source });
391
+ }
392
+ });
393
+ // W1: the index may already have the EventRecord while the card write was
394
+ // lost; replay must backfill AutoCards too (eventId-idempotent).
395
+ const cards = appendAutoCards({ memoryRoot, records: selected, now, skipLock: true });
396
+ return cards;
397
+ };
398
+ const results = wal.replay((entry) => { handleEntry(entry); });
399
+ // W2: a failed intent is retried once, then left failed with an audit row
400
+ // rather than retrying forever (EISDIR / permission errors are persistent).
401
+ results.retried = 0;
402
+ results.retryErrors = [];
403
+ for (const entry of wal.failed()) {
404
+ const retryCount = Number(entry.retryCount ?? 0);
405
+ if (retryCount >= 1) continue;
406
+ try {
407
+ handleEntry(entry);
408
+ wal.markDone(entry.walId, { replayed: true, retried: true });
409
+ results.replayed += 1;
410
+ results.retried += 1;
411
+ } catch (error) {
412
+ wal.markFailed(entry.walId, error?.message ?? error, { retryCount: retryCount + 1 });
413
+ results.failed += 1;
414
+ results.retryErrors.push({ walId: entry.walId, op: entry.op, message: String(error?.message ?? error) });
415
+ try {
416
+ fs.mkdirSync(path.join(memoryRoot, '.longlive', 'index'), { recursive: true });
417
+ fs.appendFileSync(path.join(memoryRoot, '.longlive', 'index', 'card-audit.jsonl'),
418
+ `${JSON.stringify({ schema: 'card-audit/v1', at: new Date(nowDate(now)).toISOString(), action: 'wal-retry-exhausted', walId: entry.walId, op: entry.op, message: String(error?.message ?? error) })}\n`, 'utf8');
419
+ } catch { /* audit is best-effort; WAL remains failed */ }
420
+ }
421
+ }
422
+ results.ok = results.failed === 0;
423
+ return results;
424
+ }
425
+
426
+ return { memoryRoot, lockFile, wal, captureTurn, captureSessionStart, captureLifecycleEvent, captureMemoryGap, captureOffFieldNote, replayWal, findSessionLog, indexPath };
427
+ }
428
+
429
+ /** Index a raw EventRecord directly (used by activity-capture). */
430
+ export function upsertEventRecord({ memoryRoot, now, record }) {
431
+ const indexPath = path.join(path.resolve(String(memoryRoot)), '.longlive', 'index', 'events.db');
432
+ if (!fs.existsSync(indexPath)) return { ok: false, code: 'E_EVENTS_INDEX_NOT_BUILT' };
433
+ const index = openEventIndex({ memoryRoot, now });
434
+ try {
435
+ const result = index.upsertEvent({ ...record, builtAt: record.builtAt ?? (typeof now === 'function' ? now().getTime() : Date.now()) }, { source: record.source ?? 'capture' });
436
+ return { ok: true, ...result };
437
+ } finally {
438
+ index.close();
439
+ }
440
+ }
441
+
442
+ export { makeSessionTurnAnchor, turnDigest };
@@ -0,0 +1,203 @@
1
+ // src/memory/card-anchors.js — 1.8.0 precision-card ↔ source backlinks (sidecar).
2
+ //
3
+ // Precisely curated cards (topics/journal/handover/flow markdown) keep their
4
+ // prose untouched. Provenance lives in `.longlive/index/card-anchors.jsonl`:
5
+ // { schema, rel, sourceEventIds[], anchors[], legacy, at, hash, prevLineHash, sig }
6
+ //
7
+ // Every line is hash-chained and HMAC-signed with the host key
8
+ // (`<memoryRoot>/.longlive/.hostkey`). Readers verify the chain + signature;
9
+ // tampered/replayed/duplicate rows fail closed (E_CHAIN_TAMPERED) and are
10
+ // audited. Unsigned legacy rows are `untrusted`, never silently accepted.
11
+
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+
15
+ import { hmacHexFor, sha256Hex, stableStringify } from '../actions/fs.js';
16
+ import { readHostKey, resolveHostKey } from '../role/writeprotect.js';
17
+ import { updateExtras } from './frontmatter.js';
18
+
19
+ export const CARD_ANCHOR_SCHEMA = 'card-anchor/v1';
20
+ export const CARD_ANCHORS_REL = path.join('.longlive', 'index', 'card-anchors.jsonl');
21
+ export const GENESIS_HASH = '0'.repeat(64);
22
+ export const CARD_AUDIT_REL = path.join('.longlive', 'index', 'card-audit.jsonl');
23
+
24
+ let cache = null;
25
+
26
+ export function cardAnchorsPathOf(memoryRoot) {
27
+ return path.join(path.resolve(String(memoryRoot)), CARD_ANCHORS_REL);
28
+ }
29
+
30
+ function auditSidecar(memoryRoot, code, detail = null) {
31
+ try {
32
+ const file = path.join(path.resolve(String(memoryRoot)), CARD_AUDIT_REL);
33
+ fs.mkdirSync(path.dirname(file), { recursive: true });
34
+ fs.appendFileSync(file, `${JSON.stringify({
35
+ schema: 'card-audit/v1',
36
+ at: new Date().toISOString(),
37
+ action: 'sidecar-tamper',
38
+ code,
39
+ detail,
40
+ })}\n`, 'utf8');
41
+ } catch { /* audit failure must not make the sidecar trusted */ }
42
+ }
43
+
44
+ function linkPayload(link) {
45
+ return {
46
+ schema: link?.schema ?? CARD_ANCHOR_SCHEMA,
47
+ linkId: link?.linkId ?? '',
48
+ rel: link?.rel ?? '',
49
+ sourceEventIds: Array.isArray(link?.sourceEventIds) ? link.sourceEventIds : [],
50
+ anchors: Array.isArray(link?.anchors) ? link.anchors : [],
51
+ legacy: link?.legacy === true,
52
+ at: link?.at ?? '',
53
+ };
54
+ }
55
+
56
+ function lineHashOf(link) {
57
+ return sha256Hex(stableStringify(linkPayload(link)));
58
+ }
59
+
60
+ function signHash(auditKey, hash) {
61
+ return hmacHexFor(auditKey, hash);
62
+ }
63
+
64
+ export function linkIdOf(rel) {
65
+ return `link:${sha256Hex(String(rel ?? '')).slice(0, 16)}`;
66
+ }
67
+
68
+ /** Raw (unverified) view, for migration/inspection tooling only. */
69
+ export function readCardAnchors(memoryRoot) {
70
+ const file = cardAnchorsPathOf(memoryRoot);
71
+ let stat = null;
72
+ try { stat = fs.statSync(file); } catch { cache = { file: null, mtimeMs: 0, size: 0, links: new Map() }; return cache.links; }
73
+ if (cache && cache.file === file && cache.mtimeMs === stat.mtimeMs && cache.size === stat.size) return cache.links;
74
+ const links = new Map();
75
+ let raw = '';
76
+ try { raw = fs.readFileSync(file, 'utf8'); } catch { return links; }
77
+ for (const line of raw.split('\n')) {
78
+ if (line.trim() === '') continue;
79
+ try {
80
+ const link = JSON.parse(line);
81
+ if (link && typeof link.rel === 'string') links.set(link.rel, link);
82
+ } catch { /* corrupt line skipped; verified reader will reject the file */ }
83
+ }
84
+ cache = { file, mtimeMs: stat.mtimeMs, size: stat.size, links };
85
+ return links;
86
+ }
87
+
88
+ /**
89
+ * Verify the whole sidecar. Any bad hash, broken prev link, invalid signature,
90
+ * duplicate rel, or unsigned legacy row makes the sidecar untrusted.
91
+ * No host key => fail closed: links are not returned.
92
+ */
93
+ export function readVerifiedCardAnchors({ memoryRoot, auditKey = null } = {}) {
94
+ const root = path.resolve(String(memoryRoot ?? ''));
95
+ const file = cardAnchorsPathOf(root);
96
+ let raw = '';
97
+ try { raw = fs.readFileSync(file, 'utf8'); } catch {
98
+ return { ok: true, trusted: fs.existsSync(file) === false, links: new Map(), code: null, reason: 'no-sidecar' };
99
+ }
100
+ let key = auditKey;
101
+ if (!key) key = readHostKey(root);
102
+ if (!key) {
103
+ auditSidecar(root, 'E_NO_KEY');
104
+ return { ok: false, trusted: false, links: new Map(), code: 'E_NO_KEY', reason: 'host key unavailable' };
105
+ }
106
+ const links = new Map();
107
+ let prev = GENESIS_HASH;
108
+ for (const lineText of raw.split('\n')) {
109
+ if (lineText.trim() === '') continue;
110
+ let line;
111
+ try { line = JSON.parse(lineText); } catch {
112
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'bad-json');
113
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'bad-json' };
114
+ }
115
+ const hash = lineHashOf(line);
116
+ if (line.hash !== hash) {
117
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'hash-mismatch');
118
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'hash-mismatch' };
119
+ }
120
+ if (line.prevLineHash !== prev) {
121
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'prev-mismatch');
122
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'prev-mismatch' };
123
+ }
124
+ if (typeof line.sig !== 'string' || signHash(key, hash) !== line.sig) {
125
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'sig-mismatch');
126
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'sig-mismatch' };
127
+ }
128
+ if (typeof line.rel !== 'string' || line.rel === '' || line.rel.startsWith('/') || line.rel.includes('..')) {
129
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'bad-rel');
130
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'bad-rel' };
131
+ }
132
+ if (links.has(line.rel)) {
133
+ auditSidecar(root, 'E_CHAIN_TAMPERED', 'duplicate-rel');
134
+ return { ok: false, trusted: false, links: new Map(), code: 'E_CHAIN_TAMPERED', reason: 'duplicate-rel' };
135
+ }
136
+ links.set(line.rel, { ...line, trusted: true });
137
+ prev = line.hash;
138
+ }
139
+ return { ok: true, trusted: true, links, code: null, reason: 'ok' };
140
+ }
141
+
142
+ /**
143
+ * Append one signed precision-card backlink. Idempotent by rel: the same rel is
144
+ * never appended twice (duplicate rel would make the whole sidecar untrusted).
145
+ */
146
+ export function appendCardAnchor({
147
+ memoryRoot,
148
+ rel,
149
+ sourceEventIds = [],
150
+ anchors = [],
151
+ legacy = false,
152
+ at = null,
153
+ dryRun = false,
154
+ auditKey = null,
155
+ } = {}) {
156
+ const root = path.resolve(String(memoryRoot ?? ''));
157
+ if (root === '') throw new Error('E_MEMORY_ROOT: appendCardAnchor requires memoryRoot');
158
+ const relText = String(rel ?? '').replace(/\\/g, '/');
159
+ if (relText === '' || relText.startsWith('/') || relText.includes('..')) throw new Error(`E_CARD_REL: ${JSON.stringify(rel)}`);
160
+ const existing = readCardAnchors(root);
161
+ if (existing.has(relText)) return { ok: true, written: false, skipped: true, rel: relText };
162
+ let key = auditKey;
163
+ if (!key) { try { key = resolveHostKey(root); } catch { key = null; } }
164
+ if (!key) throw new Error('E_NO_KEY: card-anchors write requires the host key');
165
+ const prev = existing.size > 0 ? [...existing.values()][existing.size - 1]?.hash ?? GENESIS_HASH : GENESIS_HASH;
166
+ const link = {
167
+ schema: CARD_ANCHOR_SCHEMA,
168
+ linkId: linkIdOf(relText),
169
+ rel: relText,
170
+ sourceEventIds: (Array.isArray(sourceEventIds) ? sourceEventIds : []).filter((id) => typeof id === 'string' && id !== ''),
171
+ anchors: (Array.isArray(anchors) ? anchors : []).filter((anchor) => anchor && typeof anchor === 'object'),
172
+ legacy: legacy === true || ((!sourceEventIds || sourceEventIds.length === 0) && (!anchors || anchors.length === 0)),
173
+ at: at ?? new Date().toISOString(),
174
+ };
175
+ link.hash = lineHashOf(link);
176
+ link.prevLineHash = prev;
177
+ link.sig = signHash(key, link.hash);
178
+ if (!dryRun) {
179
+ const file = cardAnchorsPathOf(root);
180
+ fs.mkdirSync(path.dirname(file), { recursive: true });
181
+ fs.appendFileSync(file, `${JSON.stringify(link)}\n`, 'utf8');
182
+ cache = null;
183
+ }
184
+ return { ok: true, written: !dryRun, skipped: false, rel: relText, link, dryRun };
185
+ }
186
+
187
+ /** Write backlinks onto a precision card's frontmatter extras (new cards only). */
188
+ export function attachCardExtras({ memoryRoot, rel, sourceEventIds = [], anchors = [], legacy = false } = {}) {
189
+ const root = path.resolve(String(memoryRoot ?? ''));
190
+ const abs = path.resolve(root, String(rel ?? ''));
191
+ if (!abs.startsWith(root + path.sep)) throw new Error('E_CARD_PATH: outside memoryRoot');
192
+ const text = fs.readFileSync(abs, 'utf8');
193
+ const extras = {
194
+ sourceEventIds: JSON.stringify(sourceEventIds),
195
+ anchors: JSON.stringify(anchors),
196
+ ...(legacy ? { legacy: true } : {}),
197
+ };
198
+ const updated = updateExtras(text, extras);
199
+ const tmp = `${abs}.tmp-${process.pid}-${Date.now()}`;
200
+ fs.writeFileSync(tmp, updated, 'utf8');
201
+ fs.renameSync(tmp, abs);
202
+ return { ok: true, rel, extras };
203
+ }