@hugesb/dsh-stream-agent 0.0.0-stage → 0.3.1

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 (158) hide show
  1. package/CHANGELOG.md +497 -0
  2. package/CONTRIBUTING.md +72 -0
  3. package/LICENSE +202 -0
  4. package/README.en.md +349 -0
  5. package/README.md +300 -3
  6. package/cordis.patch.yml +77 -0
  7. package/dist/entry/action-gate.js +206 -0
  8. package/dist/entry/adapter-kit.js +192 -0
  9. package/dist/entry/context-render.js +119 -0
  10. package/dist/entry/control-bar-cli.js +289 -0
  11. package/dist/entry/control-bar.js +123 -0
  12. package/dist/entry/control-session.js +115 -0
  13. package/dist/entry/control-state.js +125 -0
  14. package/dist/entry/cordis-compat.js +95 -0
  15. package/dist/entry/eval-probe.js +112 -0
  16. package/dist/entry/intent-log.js +121 -0
  17. package/dist/entry/json-persistence.js +306 -0
  18. package/dist/entry/loop.js +3852 -0
  19. package/dist/entry/mock-provider.js +536 -0
  20. package/dist/entry/obs-broker.js +178 -0
  21. package/dist/entry/ptc-bridge.js +405 -0
  22. package/dist/entry/state-handle.js +217 -0
  23. package/dist/entry/takeover-registry.js +60 -0
  24. package/dist/kernel/control-bar.js +559 -0
  25. package/dist/kernel/final.js +62 -0
  26. package/dist/kernel/gate.js +464 -0
  27. package/dist/kernel/modes.js +253 -0
  28. package/dist/kernel/obs.js +517 -0
  29. package/dist/kernel/parser.js +632 -0
  30. package/dist/kernel/render.js +444 -0
  31. package/dist/kernel/state.js +416 -0
  32. package/dist/version.js +9 -0
  33. package/docs/TEST-PROPOSITIONS.md +139 -0
  34. package/docs/adr-001-segment-boundary.md +61 -0
  35. package/docs/architecture.md +104 -0
  36. package/docs/desktop-ui-feasibility.md +277 -0
  37. package/docs/disabled-lines-audit.md +53 -0
  38. package/docs/limitations.md +181 -0
  39. package/docs/protocol.md +99 -0
  40. package/docs/v0.4.0-plan.md +50 -0
  41. package/eval/METRICS.md +128 -0
  42. package/eval/RESULTS.md +246 -0
  43. package/eval/tasks/fixtures/big-report.md +298 -0
  44. package/eval/tasks/fixtures/build-manifest.txt +5 -0
  45. package/eval/tasks/fixtures/deploy.yaml +4 -0
  46. package/eval/tasks/fixtures/error.log +200 -0
  47. package/eval/tasks/fixtures/features.yaml +4 -0
  48. package/eval/tasks/fixtures/pipeline.yaml +4 -0
  49. package/eval/tasks/fixtures/sales-q1.csv +61 -0
  50. package/eval/tasks/fixtures/settings.yaml +4 -0
  51. package/eval/tasks/fixtures/users-roster.json +304 -0
  52. package/eval/tasks/fixtures/users-scores.json +20 -0
  53. package/eval/tasks/gen-fixtures.cjs +80 -0
  54. package/eval/tasks/tasks.json +150 -0
  55. package/eval/tools/f6-kill-drill.cjs +176 -0
  56. package/eval/tools/f6-kill-drill.worker.cjs +131 -0
  57. package/eval/tools/gen-results.cjs +191 -0
  58. package/eval/tools/machine-test.cjs +200 -0
  59. package/eval/tools/manual-code-scenarios.md +59 -0
  60. package/eval/tools/replay-check.cjs +311 -0
  61. package/eval/tools/runner.cjs +219 -0
  62. package/eval/tools/session-log.cjs +106 -0
  63. package/eval/tools/summarize.cjs +185 -0
  64. package/eval/tools/t3-cells.cjs +173 -0
  65. package/package.json +73 -6
  66. package/patches/adapters-smoke.yml +41 -0
  67. package/patches/eval-account.yml +36 -0
  68. package/patches/eval-baseline.yml +33 -0
  69. package/patches/eval-stream-code-off.yml +46 -0
  70. package/patches/eval-stream-code-on.yml +47 -0
  71. package/patches/eval-stream.yml +54 -0
  72. package/patches/takeover.yml +42 -0
  73. package/patches/test-preset.yml +23 -0
  74. package/preset/stream/cordis.patch.yml +39 -0
  75. package/preset/stream/package.json +13 -0
  76. package/preset.yml +56 -0
  77. package/profiles/stream/README.md +66 -0
  78. package/profiles/stream/cordis.patch.yml +12 -0
  79. package/profiles/stream/package.json +17 -0
  80. package/profiles/stream-headless/package.json +16 -0
  81. package/scripts/build.mjs +103 -0
  82. package/scripts/check-consistency.mjs +146 -0
  83. package/scripts/gate.mjs +138 -0
  84. package/scripts/install-check.mjs +116 -0
  85. package/scripts/install-cycle.mjs +88 -0
  86. package/scripts/release.mjs +415 -0
  87. package/scripts/repair-session-logs.mjs +403 -0
  88. package/src/entry/action-gate.ts +206 -0
  89. package/src/entry/adapter-kit.ts +192 -0
  90. package/src/entry/context-render.ts +119 -0
  91. package/src/entry/control-bar-cli.ts +289 -0
  92. package/src/entry/control-bar.ts +123 -0
  93. package/src/entry/control-session.ts +115 -0
  94. package/src/entry/control-state.ts +125 -0
  95. package/src/entry/cordis-compat.ts +95 -0
  96. package/src/entry/eval-probe.ts +112 -0
  97. package/src/entry/intent-log.ts +121 -0
  98. package/src/entry/json-persistence.ts +306 -0
  99. package/src/entry/loop.ts +3852 -0
  100. package/src/entry/mock-provider.ts +536 -0
  101. package/src/entry/obs-broker.ts +178 -0
  102. package/src/entry/ptc-bridge.ts +405 -0
  103. package/src/entry/state-handle.ts +217 -0
  104. package/src/entry/takeover-registry.ts +60 -0
  105. package/src/kernel/control-bar.ts +559 -0
  106. package/src/kernel/final.ts +62 -0
  107. package/src/kernel/gate.ts +464 -0
  108. package/src/kernel/modes.ts +253 -0
  109. package/src/kernel/obs.ts +517 -0
  110. package/src/kernel/parser.ts +632 -0
  111. package/src/kernel/render.ts +444 -0
  112. package/src/kernel/state.ts +416 -0
  113. package/src/version.ts +9 -0
  114. package/test/activation.test.ts +187 -0
  115. package/test/adapters.test.ts +676 -0
  116. package/test/control-bar.test.ts +486 -0
  117. package/test/desktop-ui.test.ts +359 -0
  118. package/test/eval-probe.test.ts +139 -0
  119. package/test/f5-plan.test.ts +221 -0
  120. package/test/f6-intent.test.ts +168 -0
  121. package/test/f7-segment.test.ts +190 -0
  122. package/test/fix-limits.test.ts +599 -0
  123. package/test/gate.test.ts +380 -0
  124. package/test/helpers/stub-loop.ts +240 -0
  125. package/test/kernel/obs.test.ts +329 -0
  126. package/test/kernel/parser.test.ts +450 -0
  127. package/test/loop.test.ts +1393 -0
  128. package/test/mock-provider.test.ts +386 -0
  129. package/test/ptc-bridge.test.ts +356 -0
  130. package/test/render.test.ts +418 -0
  131. package/test/s2-install-check.test.ts +46 -0
  132. package/test/scenarios/3-file-basic.json +13 -0
  133. package/test/scenarios/5-file-basic.json +22 -0
  134. package/test/scenarios/burn-more.json +9 -0
  135. package/test/scenarios/degraded-final.json +10 -0
  136. package/test/scenarios/fault-abort-xml.json +11 -0
  137. package/test/scenarios/fault-malformed-command.json +12 -0
  138. package/test/scenarios/fault-midstream-abort.json +11 -0
  139. package/test/scenarios/fault-saturating-output.json +9 -0
  140. package/test/scenarios/fault-timeout.json +9 -0
  141. package/test/scenarios/peek-first.json +11 -0
  142. package/test/scenarios/peek-second.json +11 -0
  143. package/test/scenarios/peek-third.json +10 -0
  144. package/test/scenarios/recover-final.json +10 -0
  145. package/test/scenarios/reroute-first.json +17 -0
  146. package/test/scenarios/reroute-second.json +16 -0
  147. package/test/scenarios/starvation-final.json +10 -0
  148. package/test/scenarios/starvation-promote.json +11 -0
  149. package/test/scenarios/wait-tools-continue.json +10 -0
  150. package/test/scenarios/wait-tools-xml.json +22 -0
  151. package/test/scenarios/wait-tools.json +15 -0
  152. package/test/session-format.test.ts +234 -0
  153. package/test/state.test.ts +335 -0
  154. package/test/stream-v02.test.ts +264 -0
  155. package/test/v031-display.test.ts +333 -0
  156. package/ui/client.js +576 -0
  157. package/ui/index.js +282 -0
  158. package/ui/package.json +26 -0
@@ -0,0 +1,121 @@
1
+ // entry/intent-log.ts —— F6 恢复意图:写前意图落盘(fsync)+ 写后回执 + resume 停机核对
2
+ //
3
+ // 红线(v0.4.0 规划 F6,随 0.3.0 实施):
4
+ // · 意图必须在写入发生**之前**落盘并 fsync——崩溃后"有意图无回执"即可判定"写入可能已发生";
5
+ // · 写后回执记录结果与时间;三态判定:未发生(意图前崩溃)/ 已发生(有意图有回执且 ok)/
6
+ // 不确定(有意图无回执——强制杀在写入中);
7
+ // · resume 时"有意图无回执"一律**停机核对**,不自动重放、不自动继续;
8
+ // · 零注入:意图与回执不进模型上下文,只在账本与 resume 判定中使用。
9
+ //
10
+ // 文件布局:<stateRoot>/intents/<sessionId>.jsonl,每行一个 JSON 记录:
11
+ // { type:'intent', seq, at, sessionId, cmdId, op, path, fingerprint }
12
+ // { type:'receipt', seq, at, intentSeq, ok, detail? }
13
+ // { type:'ack', seq, at, intentSeqs, note? } —— 人工核对后的确认(CLI intents --ack)
14
+
15
+ import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
16
+ import { createHash } from 'node:crypto';
17
+ import { dirname, join } from 'node:path';
18
+
19
+ /** 写前意图记录(写入发生前 fsync 落盘)。 */
20
+
21
+
22
+
23
+
24
+
25
+
26
+               
27
+
28
+
29
+                             
30
+
31
+
32
+
33
+ /** 写后回执记录(命令落定即追加;失败也记——把意图闭合为"已发生但失败")。 */
34
+
35
+
36
+
37
+
38
+                       
39
+
40
+
41
+
42
+
43
+
44
+ /** 人工核对确认(CLI intents --ack;停机核对的出口)。 */
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+
55
+ /** 内容指纹(sha256 前 16 位;够对账,不泄露内容)。 */
56
+ export function intentFingerprint(content ) {
57
+ return createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
58
+ }
59
+
60
+ /** 会话的意图日志路径:<stateRoot>/intents/<sessionId>.jsonl。 */
61
+ export function intentFileOf(stateRoot , sessionId ) {
62
+ return join(stateRoot, 'intents', `${sessionId}.jsonl`);
63
+ }
64
+
65
+ /** 追加一条记录并 fsync(崩溃安全的关键:写入发生前意图必须已到盘)。 */
66
+ export function appendIntentRecord(file , record ) {
67
+ mkdirSync(dirname(file), { recursive: true });
68
+ const fd = openSync(file, 'a');
69
+ try {
70
+ writeFileSync(fd, `${JSON.stringify(record)}\n`, { encoding: 'utf8' });
71
+ fsyncSync(fd);
72
+ } finally {
73
+ closeSync(fd);
74
+ }
75
+ }
76
+
77
+ /** 读取全部记录(坏行如实跳过并计数,不中断——崩溃可能截断最后一行)。 */
78
+ export function loadIntentRecords(file ) {
79
+ if (!existsSync(file)) return { records: [], badLines: 0 };
80
+ const records = [];
81
+ let badLines = 0;
82
+ for (const line of readFileSync(file, 'utf8').split('\n')) {
83
+ if (line.trim() === '') continue;
84
+ try {
85
+ const parsed = JSON.parse(line) ;
86
+ if (parsed.type === 'intent' || parsed.type === 'receipt' || parsed.type === 'ack') records.push(parsed);
87
+ else badLines += 1;
88
+ } catch {
89
+ badLines += 1;
90
+ }
91
+ }
92
+ return { records, badLines };
93
+ }
94
+
95
+
96
+
97
+                                  
98
+
99
+
100
+
101
+ /**
102
+ * 计算"有意图无回执"集合(resume 停机核对的输入):
103
+ * - intent 没有任何 receipt 引用、也不在任何 ack 里 → pending(不确定);
104
+ * - intent 的 receipt ok=false 且无后续 ack → failed(已发生但失败——列出供参考,不阻断)。
105
+ */
106
+ export function pendingIntents(records ) {
107
+ const receiptByIntent = new Map ();
108
+ const acked = new Set ();
109
+ for (const r of records) {
110
+ if (r.type === 'receipt') receiptByIntent.set(r.intentSeq, r);
111
+ if (r.type === 'ack') for (const seq of r.intentSeqs) acked.add(seq);
112
+ }
113
+ const out = [];
114
+ for (const r of records) {
115
+ if (r.type !== 'intent' || acked.has(r.seq)) continue;
116
+ const receipt = receiptByIntent.get(r.seq);
117
+ if (receipt === undefined) out.push({ intent: r, state: 'pending' });
118
+ else if (!receipt.ok) out.push({ intent: r, state: 'failed' });
119
+ }
120
+ return out;
121
+ }
@@ -0,0 +1,306 @@
1
+ // entry/json-persistence.ts —— 插件本地持久化兜底(修复已知限制 3 / 4)
2
+ //
3
+ // 职责:宿主缺 storage backend、缺 sessionPersistence、或 dsh-session 模块不可达
4
+ // (bundle 形态 bare import 解析不到宿主同一副本)时,提供零依赖的本地文件持久化面:
5
+ // ① JsonFileKvUnit —— KvUnit 的本地 JSON 文件实现(state-handle 降级用:
6
+ // 句柄目录 + blob 落盘,resume 可重建,不再是易失内存);
7
+ // ② createJsonlPersistence —— 会话事件 JSONL 持久化(AgentFactory.create/resume 的
8
+ // persistence 降级实现;headless 未挂 sessionPersistence 时
9
+ // 跨会话 resume 真正可用);
10
+ // ③ FileLedgerSink —— plugin:tf-agent/* 台账的 JSONL 落点(bundle 形态 plugin
11
+ // record 通道降级时的可重放落点,不再是易失内存台账);
12
+ // ④ withEventCapture —— 会话 append 代理:事件镜像进 ② 的 JSONL(仅降级路径用)。
13
+ //
14
+ // 纪律(与 adapter-kit 一致):零 @deepseek-ai 依赖;fail-open(红线 5)——
15
+ // IO 失败向上抛错或走告警出口,绝不静默吞事实。
16
+
17
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
18
+ import { homedir } from 'node:os';
19
+ import { dirname, join } from 'node:path';
20
+
21
+
22
+ // ---------------------------------------------------------------------------
23
+ // 状态目录
24
+ // ---------------------------------------------------------------------------
25
+
26
+ /** 状态根目录解析:config 显式指定 → env STREAM_AGENT_STATE_DIR → ~/.dsh-stream-agent */
27
+ export function resolveStateDir(configDir ) {
28
+ if (configDir !== undefined && configDir.trim() !== '') return configDir;
29
+ const env = process.env.STREAM_AGENT_STATE_DIR;
30
+ if (env !== undefined && env.trim() !== '') return env;
31
+ return join(homedir(), '.dsh-stream-agent');
32
+ }
33
+
34
+ /** 文件名安全化(session id 可能含 ':' '/' 等路径字符)。 */
35
+ export function safeFileName(id ) {
36
+ return id.replace(/[^a-zA-Z0-9._-]/g, '_') || 'session';
37
+ }
38
+
39
+ // ---------------------------------------------------------------------------
40
+ // ① KvUnit —— JSON 文件实现(镜像 adapter-kit.KvUnitLike)
41
+ // ---------------------------------------------------------------------------
42
+
43
+
44
+
45
+
46
+
47
+ function loadJsonKv(file , warn ) {
48
+ if (!existsSync(file)) return { tables: {} };
49
+ try {
50
+ const raw = JSON.parse(readFileSync(file, 'utf8')) ;
51
+ return { tables: (raw.tables ?? {}) };
52
+ } catch (error) {
53
+ warn(`本地 KvUnit 文件损坏,按空库打开(原文件保留在 ${file}.corrupt 语义之外,不做改写)`, error);
54
+ return { tables: {} };
55
+ }
56
+ }
57
+
58
+ /** 原子写:tmp + rename,避免半截 JSON。 */
59
+ function flushJsonKv(file , data ) {
60
+ const tmp = `${file}.tmp`;
61
+ writeFileSync(tmp, JSON.stringify(data), 'utf8');
62
+ renameSync(tmp, file);
63
+ }
64
+
65
+ /**
66
+ * 本地 JSON 文件 KvUnit。open 时创建目录并真实写一次(可写性探针失败即抛,
67
+ * 由调用方走最终内存降级——绝不带着假 durable 面)。putRecord 走串行队列
68
+ * 防读改写竞态;每次写全量重写文件(插件规模的状态量下足够,简单优先)。
69
+ */
70
+ export class JsonFileKvUnit {
71
+ #file ;
72
+ #warn ;
73
+ #cache ;
74
+ #queue = Promise.resolve();
75
+ #closed = false;
76
+
77
+ constructor(dir , name , warn ) {
78
+ this.#warn = warn;
79
+ mkdirSync(dir, { recursive: true });
80
+ this.#file = join(dir, `${safeFileName(name)}.json`);
81
+ // 可写性探针:文件缺失时落一次空库(rename 原子性同时验证目录可写)
82
+ if (!existsSync(this.#file)) flushJsonKv(this.#file, { tables: {} });
83
+ this.#cache = loadJsonKv(this.#file, warn);
84
+ }
85
+
86
+ /** 实际落盘文件路径(排障/日志用)。 */
87
+ get file() {
88
+ return this.#file;
89
+ }
90
+
91
+ async loadAll() {
92
+ return { tables: this.#cache.tables, global: null };
93
+ }
94
+
95
+ async putRecord(table , key , value ) {
96
+ const op = this.#queue.then(() => {
97
+ if (this.#closed) throw new Error('kv unit closed');
98
+ const t = this.#cache.tables[table] ?? (this.#cache.tables[table] = {});
99
+ t[key] = value;
100
+ flushJsonKv(this.#file, this.#cache);
101
+ });
102
+ this.#queue = op.catch(() => {}); // 队列不因单次失败卡死;错误由 await 侧上抛
103
+ await op;
104
+ }
105
+
106
+ async close() {
107
+ await this.#queue;
108
+ this.#closed = true;
109
+ }
110
+ }
111
+
112
+ // ---------------------------------------------------------------------------
113
+ // ② 会话事件 JSONL 持久化(AgentFactory.create/resume 的 persistence 降级实现)
114
+ // ---------------------------------------------------------------------------
115
+
116
+ const HEADER_KIND = '__tf_agent_header__';
117
+
118
+
119
+
120
+
121
+
122
+
123
+
124
+
125
+
126
+
127
+
128
+
129
+
130
+
131
+ /**
132
+ * 逐会话一个 JSONL 文件:<sessionsDir>/<sessionId>.jsonl。
133
+ * 首行 header(kind=__tf_agent_header__),后续每行一个会话事件(原样对象)。
134
+ * append 同步落盘(appendFileSync;会话事件频度低,简单优先于缓冲)。
135
+ */
136
+ class JsonlSessionFile {
137
+ #file ;
138
+ #warn ;
139
+ #sessionId ;
140
+ #header = undefined;
141
+ #inheritedEventCount = undefined;
142
+ #events = [];
143
+ #loaded = false;
144
+
145
+ constructor(sessionsDir , sessionId , warn ) {
146
+ this.#warn = warn;
147
+ this.#sessionId = sessionId;
148
+ mkdirSync(sessionsDir, { recursive: true });
149
+ this.#file = join(sessionsDir, `${safeFileName(sessionId)}.jsonl`);
150
+ }
151
+
152
+ /** create 路径:写 header 行(已存在文件 → 抛错,上层转 resume 语义打开)。 */
153
+ initHeader(header , inheritedEventCount ) {
154
+ if (existsSync(this.#file)) {
155
+ throw new Error(`session already exists: ${this.#sessionId}`);
156
+ }
157
+ appendFileSync(this.#file, `${JSON.stringify({ kind: HEADER_KIND, header, inheritedEventCount })}\n`, 'utf8');
158
+ this.#header = header;
159
+ this.#inheritedEventCount = inheritedEventCount;
160
+ this.#loaded = true;
161
+ }
162
+
163
+ /** open 路径:冷读全部行(坏行跳过 + 告警,不静默吞事件)。 */
164
+ load() {
165
+ this.#events = [];
166
+ if (!existsSync(this.#file)) {
167
+ throw new Error(`session log not found: ${this.#sessionId}`);
168
+ }
169
+ const lines = readFileSync(this.#file, 'utf8').split('\n');
170
+ let first = true;
171
+ for (const line of lines) {
172
+ if (line.trim() === '') continue;
173
+ let parsed ;
174
+ try {
175
+ parsed = JSON.parse(line);
176
+ } catch (error) {
177
+ this.#warn(`会话 JSONL 坏行跳过(${this.#file})`, error);
178
+ continue;
179
+ }
180
+ const rec = parsed ;
181
+ if (first && rec?.kind === HEADER_KIND) {
182
+ this.#header = rec.header;
183
+ this.#inheritedEventCount = typeof rec.inheritedEventCount === 'number' ? rec.inheritedEventCount : undefined;
184
+ first = false;
185
+ continue;
186
+ }
187
+ first = false;
188
+ this.#events.push(parsed);
189
+ }
190
+ this.#loaded = true;
191
+ }
192
+
193
+ async append(events ) {
194
+ if (!this.#loaded) throw new Error('session jsonl not initialized');
195
+ for (const event of events) {
196
+ appendFileSync(this.#file, `${JSON.stringify(event)}\n`, 'utf8');
197
+ this.#events.push(event);
198
+ }
199
+ }
200
+
201
+ async read(from ) {
202
+ if (!this.#loaded) throw new Error('session jsonl not initialized');
203
+ const start = Math.max(0, Math.floor(from));
204
+ return { events: this.#events.slice(start) };
205
+ }
206
+
207
+ async close() {
208
+ // appendFileSync 直写,无需 flush
209
+ }
210
+
211
+ get headerValue() {
212
+ return this.#header;
213
+ }
214
+
215
+ get inheritedCount() {
216
+ return this.#inheritedEventCount;
217
+ }
218
+ }
219
+
220
+ /** 创建 per-session 的 JSONL persistence 工厂(AgentFactory 降级接驳点)。 */
221
+ export function createJsonlPersistence(sessionsDir , sessionId , warn ) {
222
+ return {
223
+ async create(header, opts) {
224
+ const f = new JsonlSessionFile(sessionsDir, sessionId, warn);
225
+ f.initHeader(header, opts?.inheritedEventCount);
226
+ return f;
227
+ },
228
+ async open(id) {
229
+ const f = new JsonlSessionFile(sessionsDir, id, warn);
230
+ f.load();
231
+ return f;
232
+ },
233
+ };
234
+ }
235
+
236
+ // ---------------------------------------------------------------------------
237
+ // ③ plugin:tf-agent/* 台账 JSONL(bundle 形态 plugin record 通道降级落点)
238
+ // ---------------------------------------------------------------------------
239
+
240
+
241
+
242
+                            
243
+
244
+
245
+
246
+ export function ledgerFileOf(stateDir , sessionId ) {
247
+ return join(stateDir, 'ledger', `${safeFileName(sessionId)}.jsonl`);
248
+ }
249
+
250
+ /** 追加一条台账记录(同步落盘;目录缺则建)。IO 失败向上抛——驱动器侧告警不静默。 */
251
+ export function appendLedgerRecord(file , type , data ) {
252
+ mkdirSync(dirname(file), { recursive: true });
253
+ appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), type, data })}\n`, 'utf8');
254
+ }
255
+
256
+ /** 读回台账记录(resume 重放用;坏行跳过并计数,由调用方决定是否告警)。 */
257
+ export function loadLedgerRecords(file ) {
258
+ if (!existsSync(file)) return { records: [], skipped: 0 };
259
+ const records = [];
260
+ let skipped = 0;
261
+ for (const line of readFileSync(file, 'utf8').split('\n')) {
262
+ if (line.trim() === '') continue;
263
+ try {
264
+ const rec = JSON.parse(line) ;
265
+ if (typeof rec?.type === 'string') records.push({ type: rec.type, data: rec.data });
266
+ else skipped += 1;
267
+ } catch {
268
+ skipped += 1;
269
+ }
270
+ }
271
+ return { records, skipped };
272
+ }
273
+
274
+ // ---------------------------------------------------------------------------
275
+ // ④ 会话事件捕获代理(仅降级持久化路径使用)
276
+ // ---------------------------------------------------------------------------
277
+
278
+ /**
279
+ * 会话 append 代理:事件镜像进 JSONL,其余方法/属性原型链透传
280
+ * (snapshotEvents / header / seq 等行为不变)。宿主 checkpoint 机制依赖
281
+ * sessionPersistence 存在;降级路径没有它,事件捕获只能在这里做。
282
+ */
283
+ export function withEventCapture(
284
+ session ,
285
+ sink ,
286
+ warn ,
287
+ ) {
288
+ if (session === null || typeof session !== 'object') return session;
289
+ const target = session ;
290
+ if (typeof target.append !== 'function') return session;
291
+ const wrapped = Object.create(session) ;
292
+ wrapped.append = (type , data , opts ) => {
293
+ const appended = target.append (type, data, opts);
294
+ // 落盘对象:宿主返回的完整事件优先(保真 seq/type/data),拿不到事件对象则用最小形状
295
+ const event = appended !== null && typeof appended === 'object'
296
+ ? { type, data, ...(appended ) }
297
+ : { type, data };
298
+ try {
299
+ sink.appendEvents([event]);
300
+ } catch (error) {
301
+ warn('会话事件镜像落盘失败(fail-open:内存事实不丢,本事件不再重试)', error);
302
+ }
303
+ return appended;
304
+ };
305
+ return wrapped;
306
+ }