@jjh32456/dsh-longlive 1.6.8 → 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 (288) hide show
  1. package/CHANGELOG.md +69 -1539
  2. package/LICENSE +1 -1
  3. package/QUICKSTART.md +33 -12
  4. package/README.en.md +17 -7
  5. package/README.md +29 -10
  6. package/SPEC.md +5 -5
  7. package/cordis.patch.yml +17 -12
  8. package/docs/ANSWER-GUARD.md +92 -0
  9. package/docs/ARCHITECTURE.md +3 -3
  10. package/docs/AUTO-RECALL-WIRING.md +1 -1
  11. package/docs/AUTO-RECALL.md +15 -9
  12. package/docs/CONFIG.md +143 -37
  13. package/docs/ERRORS.md +17 -5
  14. package/docs/FAQ.md +7 -7
  15. package/docs/FEATURES.md +66 -29
  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 +3 -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 +42 -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 +129 -18
  41. package/src/activity/model.js +11 -1
  42. package/src/activity/store.js +22 -3
  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 +145 -48
  58. package/src/deps.js +6 -4
  59. package/src/features.js +158 -8
  60. package/src/identity/index.js +13 -5
  61. package/src/identity/inject-position.js +2 -2
  62. package/src/index.js +97 -7
  63. package/src/lifecycle/gap-clocks.js +328 -0
  64. package/src/lifecycle/index.js +269 -0
  65. package/src/memory/activity-capture.js +229 -0
  66. package/src/memory/anchors.js +194 -0
  67. package/src/memory/audit-records.js +222 -0
  68. package/src/memory/auto-cards.js +401 -0
  69. package/src/memory/capture.js +442 -0
  70. package/src/memory/card-anchors.js +203 -0
  71. package/src/memory/conflicts.js +106 -0
  72. package/src/memory/decay.js +311 -0
  73. package/src/memory/distill.js +471 -0
  74. package/src/memory/event-index.js +917 -0
  75. package/src/memory/evidence-chain.js +295 -0
  76. package/src/memory/evidence.js +145 -0
  77. package/src/memory/filter-runner.js +1 -1
  78. package/src/memory/filter.js +5 -1
  79. package/src/memory/forget-v2.js +410 -0
  80. package/src/memory/forget.js +71 -0
  81. package/src/memory/frames-activation.js +247 -0
  82. package/src/memory/fts-query.js +174 -0
  83. package/src/memory/governance.js +604 -0
  84. package/src/memory/index.js +1 -0
  85. package/src/memory/l2-gate.js +169 -0
  86. package/src/memory/lock.js +121 -0
  87. package/src/memory/migrate.js +139 -0
  88. package/src/memory/recall-v2.js +223 -0
  89. package/src/memory/recall.js +65 -2
  90. package/src/memory/records.js +425 -0
  91. package/src/memory/retention.js +128 -0
  92. package/src/memory/review.js +124 -0
  93. package/src/memory/trust.js +88 -0
  94. package/src/memory/version-chain.js +264 -0
  95. package/src/memory/wal.js +137 -0
  96. package/src/memory/working-frame.js +516 -0
  97. package/src/metrics/classify.mjs +5 -3
  98. package/src/metrics/index.mjs +21 -1
  99. package/src/metrics/prestep-latency.mjs +300 -0
  100. package/src/metrics/store.mjs +25 -0
  101. package/src/policy-profile.js +18 -3
  102. package/src/recall/anaphora.mjs +87 -0
  103. package/src/recall/cards.mjs +7 -0
  104. package/src/recall/embedding.mjs +8 -8
  105. package/src/recall/entities.mjs +112 -0
  106. package/src/recall/index.js +235 -19
  107. package/src/recall/inject-order.mjs +10 -8
  108. package/src/recall/privacy.mjs +1 -1
  109. package/src/recall/recall-core.mjs +116 -10
  110. package/src/recall/shared-visibility.js +302 -0
  111. package/src/recall/time-normalizer.mjs +196 -0
  112. package/src/role/activation.js +191 -0
  113. package/src/role/attention.js +318 -0
  114. package/src/role/base.js +36 -0
  115. package/src/role/channels.js +423 -0
  116. package/src/role/index.js +425 -0
  117. package/src/role/interfaces.js +115 -0
  118. package/src/role/personality.js +370 -0
  119. package/src/role/readers.js +151 -0
  120. package/src/role/relationships.js +477 -0
  121. package/src/role/store.js +202 -0
  122. package/src/role/writeprotect.js +373 -0
  123. package/src/router/aliases.json +176 -25
  124. package/src/router/background/agent-runner.mjs +1 -1
  125. package/src/router/background/anchor.mjs +1 -1
  126. package/src/router/background/audit.mjs +2 -2
  127. package/src/router/background/budget-ledger.mjs +2 -2
  128. package/src/router/background/host-sim.mjs +1 -1
  129. package/src/router/background/memory.mjs +4 -4
  130. package/src/router/background/queue.mjs +1 -1
  131. package/src/router/background/retry.mjs +1 -1
  132. package/src/router/background/router.mjs +1 -1
  133. package/src/router/background/stream.mjs +1 -1
  134. package/src/router/background/tool-policy.mjs +1 -1
  135. package/src/router/design-headings.json +5 -5
  136. package/src/router/face/config.mjs +1 -1
  137. package/src/router/face/identity.mjs +3 -3
  138. package/src/router/judge.mjs +8 -7
  139. package/src/router/policies/generic.json +21 -4
  140. package/src/router/route.js +109 -22
  141. package/src/router/router.mjs +10 -6
  142. package/src/router/routing-rules.json +260 -445
  143. package/src/router/run-sim.mjs +8 -8
  144. package/src/router/runtime.js +23 -12
  145. package/src/router/service/config.mjs +5 -5
  146. package/src/router/service/context.mjs +1 -1
  147. package/src/router/service/queue.mjs +1 -1
  148. package/src/router/shadow.mjs +4 -3
  149. package/src/surgery-recovery.js +2 -2
  150. package/src/tool-output.js +2 -2
  151. package/src/tools.js +39 -7
  152. package/src/truncate-visible.js +2 -2
  153. package/src/ui/actions.js +1312 -0
  154. package/src/ui/panel-api.js +367 -0
  155. package/src/ui/panel-auth.js +251 -0
  156. package/src/ui/panel-integrity.js +243 -0
  157. package/src/ui/routes-readonly.js +695 -0
  158. package/src/ui/routes.js +3 -0
  159. package/docs/DEV.md +0 -279
  160. package/docs/PRESENCE-BUS-WIRING.md +0 -491
  161. package/docs/PRESENCE-BUS.md +0 -694
  162. package/docs/SURGERY.md +0 -186
  163. package/scripts/mark-core-cards.mjs +0 -289
  164. package/scripts/pack.mjs +0 -392
  165. package/scripts/router-proposals.mjs +0 -386
  166. package/src/router/fixtures/M1.json +0 -16
  167. package/src/router/fixtures/M2.json +0 -16
  168. package/src/router/fixtures/M3.json +0 -20
  169. package/src/router/fixtures/M4.json +0 -20
  170. package/src/router/fixtures/M5.json +0 -45
  171. package/src/router/fixtures/M6.json +0 -53
  172. package/src/router/fixtures/M7.json +0 -46
  173. package/src/router/fixtures/S1.json +0 -20
  174. package/src/router/fixtures/S2.json +0 -23
  175. package/src/router/fixtures/S3.json +0 -20
  176. package/src/router/fixtures/S4.json +0 -34
  177. package/src/router/fixtures/S5.json +0 -43
  178. package/src/router/fixtures/S6.json +0 -47
  179. package/src/router/fixtures/T1.json +0 -23
  180. package/src/router/fixtures/T2.json +0 -16
  181. package/src/router/fixtures/T3.json +0 -19
  182. package/src/router/fixtures/T4.json +0 -16
  183. package/src/router/fixtures/X1.json +0 -17
  184. package/src/router/fixtures/X2.json +0 -20
  185. package/src/router/gen-design-headings.mjs +0 -107
  186. package/src/router/policies/owner-rulings-2026-11-03.json +0 -62
  187. package/test/activity-realtime.test.mjs +0 -959
  188. package/test/activity-stream.test.mjs +0 -512
  189. package/test/auto-recall.test.mjs +0 -474
  190. package/test/auto-truncate.test.mjs +0 -931
  191. package/test/autobind.test.mjs +0 -399
  192. package/test/bus.test.mjs +0 -1572
  193. package/test/cli-guard.test.mjs +0 -198
  194. package/test/conclusion.test.mjs +0 -408
  195. package/test/config-schema.test.mjs +0 -210
  196. package/test/d6-output.test.mjs +0 -194
  197. package/test/d6.test.mjs +0 -395
  198. package/test/deps.test.mjs +0 -342
  199. package/test/doctor-setup.test.mjs +0 -297
  200. package/test/embedding-recall.test.mjs +0 -347
  201. package/test/feature-flags.test.mjs +0 -585
  202. package/test/filter-shadow.test.mjs +0 -170
  203. package/test/fixtures/activity-append-child.mjs +0 -29
  204. package/test/fixtures/baseline-0.8.0-registration.json +0 -556
  205. package/test/fixtures/d6-header-tools.json +0 -1
  206. package/test/fixtures/lock-child.mjs +0 -67
  207. package/test/fixtures/pre-step-container.mjs +0 -100
  208. package/test/fixtures/privacy-memory/topics/pii-unmarked.md +0 -9
  209. package/test/fixtures/privacy-memory/topics/secret-local-only.md +0 -11
  210. package/test/fixtures/profile-session-longlive-config.json +0 -20
  211. package/test/fixtures/proposal-cas-child.mjs +0 -66
  212. package/test/host-engine-status.test.mjs +0 -307
  213. package/test/hot-truncate.test.mjs +0 -1349
  214. package/test/identity-card-marker.test.mjs +0 -307
  215. package/test/identity-router/run.mjs +0 -721
  216. package/test/integration-pre-step.test.mjs +0 -553
  217. package/test/live.test.mjs +0 -1023
  218. package/test/maintenance-schedule.test.mjs +0 -538
  219. package/test/memory.test.mjs +0 -2828
  220. package/test/metrics.test.mjs +0 -478
  221. package/test/orchestrator.test.mjs +0 -266
  222. package/test/p1_probe.mjs +0 -97
  223. package/test/packaging.test.mjs +0 -184
  224. package/test/portability.test.mjs +0 -343
  225. package/test/rc4-regressions.test.mjs +0 -562
  226. package/test/rc5-regressions.test.mjs +0 -197
  227. package/test/rc6-chinese.test.mjs +0 -394
  228. package/test/router-1100/apply-off.test.mjs +0 -175
  229. package/test/router-1100/budget-reconcile.test.mjs +0 -215
  230. package/test/router-1100/config-context.test.mjs +0 -211
  231. package/test/router-1100/helpers.mjs +0 -129
  232. package/test/router-1100/hint-envelope.test.mjs +0 -150
  233. package/test/router-1100/lock-crossproc.test.mjs +0 -206
  234. package/test/router-1100/proposal-cas-crossproc.test.mjs +0 -184
  235. package/test/router-1100/router-apply.test.mjs +0 -372
  236. package/test/router-1100/router-fixb.test.mjs +0 -602
  237. package/test/router-1100/router-proposals.test.mjs +0 -405
  238. package/test/router-1100/router-queue-lease-wal.test.mjs +0 -355
  239. package/test/router-1100/router-security-cr.test.mjs +0 -333
  240. package/test/router-1100/service-lifecycle.test.mjs +0 -220
  241. package/test/router-1100/tools-contract.test.mjs +0 -164
  242. package/test/router-1100/turn-reflect-tick.test.mjs +0 -89
  243. package/test/router-1100/v6-contract.test.mjs +0 -158
  244. package/test/router-1100/v6b-contract.test.mjs +0 -293
  245. package/test/router-1100/v6c-contract.test.mjs +0 -249
  246. package/test/router-1100/wal-rotation.test.mjs +0 -375
  247. package/test/router-1100/wp1-config.test.mjs +0 -170
  248. package/test/router-1100/wp1-default-off.test.mjs +0 -77
  249. package/test/router-1100/wp1-model-status.test.mjs +0 -90
  250. package/test/router-1100/wp1-status.test.mjs +0 -220
  251. package/test/router-1100/wp1-tools.test.mjs +0 -146
  252. package/test/router-1100/wp5-cli.test.mjs +0 -240
  253. package/test/router-1100/wp5-model-auto.test.mjs +0 -418
  254. package/test/router-1100/wp6-merge.test.mjs +0 -386
  255. package/test/router-1100/wp6-wake.test.mjs +0 -502
  256. package/test/router-background/audit.test.mjs +0 -37
  257. package/test/router-background/budget-ledger.test.mjs +0 -330
  258. package/test/router-background/cross-process.test.mjs +0 -222
  259. package/test/router-background/fixtures/cross-child.mjs +0 -85
  260. package/test/router-background/fixtures/real-shapes.mjs +0 -239
  261. package/test/router-background/router.test.mjs +0 -1076
  262. package/test/router-background/stream-retry.test.mjs +0 -358
  263. package/test/router-background/tool-agent.test.mjs +0 -384
  264. package/test/router-face/bridge.test.mjs +0 -169
  265. package/test/router-face/face.test.mjs +0 -316
  266. package/test/router-failclosed.test.mjs +0 -466
  267. package/test/router-identity.test.mjs +0 -384
  268. package/test/router-l1-l2.contract.test.mjs +0 -1075
  269. package/test/router-memory-tools.test.mjs +0 -262
  270. package/test/router-policy.test.mjs +0 -225
  271. package/test/router-runtime.test.mjs +0 -438
  272. package/test/router-shadow.test.mjs +0 -287
  273. package/test/router.test.mjs +0 -903
  274. package/test/run-rc.mjs +0 -315
  275. package/test/run.mjs +0 -2469
  276. package/test/safety-defaults.test.mjs +0 -181
  277. package/test/seeded-load.test.mjs +0 -436
  278. package/test/session-original.test.mjs +0 -338
  279. package/test/state-truth.test.mjs +0 -937
  280. package/test/surgery-recovery.test.mjs +0 -936
  281. package/test/t7_drive.mjs +0 -151
  282. package/test/tool-output.test.mjs +0 -393
  283. package/test/tool-schema.test.mjs +0 -177
  284. package/test/tools_contract.test.mjs +0 -716
  285. package/test/truncate-visible.test.mjs +0 -1150
  286. package/test/ui-flags.test.mjs +0 -477
  287. package/test/v4-hardening.test.mjs +0 -427
  288. package/test/version-consistency.test.mjs +0 -286
@@ -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
+ }