@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,217 @@
1
+ // entry/state-handle.ts —— 状态服务(M1 适配,分派 07)
2
+ //
3
+ // 职责(07 号任务书):kernel/state 的 StateStore 经 ctx.provide 提供为 Cordis 服务
4
+ // `ctx.state`;BlobSink 接 DSH storage(adapter-kit.DurableBlobSink:内存覆盖读 + 写回后
5
+ // 异步持久,内核同步语义不变);resume 时从持久层快照重建句柄目录——重放编排在本层,
6
+ // 确定性由内核内容寻址保证(同内容 → 同 hash → 同版本,重放结果逐字节可验证)。
7
+ // 本 entry 只做"翻译"(快照格式 + 重放校验),无业务逻辑。
8
+ //
9
+ // fail-open(红线 5):storage 不可用 → 内存实现降级 + 告警(durable=false),服务照常提供。
10
+
11
+ import { createHash } from 'node:crypto';
12
+ import { join } from 'node:path';
13
+ import { StateStore, parseHandle, formatHandle } from '../kernel/state.js';
14
+
15
+ import { makeWarn, EntryLedger, DurableBlobSink, bytesToB64, b64ToBytes, hydrateFromUnit, openKvUnit } from './adapter-kit.js';
16
+ import { asPluginEffect, getService } from './cordis-compat.js';
17
+
18
+ import { JsonFileKvUnit, resolveStateDir, safeFileName } from './json-persistence.js';
19
+
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
+                       
45
+
46
+                             
47
+
48
+                                  
49
+
50
+
51
+
52
+
53
+
54
+                    
55
+
56
+                          
57
+
58
+                            
59
+                 
60
+
61
+               
62
+
63
+
64
+
65
+ /** 句柄字符串 → 内核 put 的 ref(重放用;解析失败抛 UnknownHandleError → 上层计入 mismatches)。 */
66
+ function refOf(handle ) {
67
+ const parsed = parseHandle(handle);
68
+ if (parsed.kind === 'file') return { kind: 'file', path: parsed.path };
69
+ if (parsed.kind === 'obs') {
70
+ const colon = parsed.path.indexOf(':');
71
+ if (colon <= 0) return null;
72
+ return { kind: 'obs', tool: parsed.path.slice(0, colon), callId: parsed.path.slice(colon + 1) };
73
+ }
74
+ return {}; // blob:path 由 put 从 hash 自动生成
75
+ }
76
+
77
+ /** store → 快照(内容取不到的句柄记 null,resume 时跳过并如实报告)。 */
78
+ function snapshotOf(store ) {
79
+ const handles = store.handles().map((h) => {
80
+ try {
81
+ const content = store.get(h);
82
+ const text = typeof content === 'string';
83
+ const bytes = text ? new TextEncoder().encode(content) : content;
84
+ return { handle: formatHandle(h), hash: h.hash, text, contentB64: bytesToB64(bytes) };
85
+ } catch {
86
+ return { handle: formatHandle(h), hash: h.hash, text: false, contentB64: null };
87
+ }
88
+ });
89
+ return { handles };
90
+ }
91
+
92
+ function sha256Hex(bytes ) {
93
+ return createHash('sha256').update(bytes).digest('hex');
94
+ }
95
+
96
+ export const name = 'stream-agent-state';
97
+ export const inject = ['storage'];
98
+
99
+ export default function apply(ctx , config = {}) {
100
+ const warn = makeWarn(ctx, 'state-handle');
101
+ const ledger = new EntryLedger();
102
+ const sink = new DurableBlobSink(warn, (kind, data) => ledger.push(kind, data));
103
+ let store = new StateStore(sink);
104
+ let unit ;
105
+
106
+ const service = {
107
+ get store() {
108
+ return store;
109
+ },
110
+ get sink() {
111
+ return sink;
112
+ },
113
+ get durable() {
114
+ return sink.attached;
115
+ },
116
+ snapshot: () => snapshotOf(store),
117
+ async persist() {
118
+ const snap = snapshotOf(store);
119
+ if (unit === undefined) return snap; // 内存降级:无处可写,快照照常返回
120
+ let seq = 0;
121
+ for (const entry of snap.handles) await unit.putRecord('handles', String(++seq), entry);
122
+ ledger.push('persist-catalog', { handles: snap.handles.length });
123
+ return snap;
124
+ },
125
+ async load() {
126
+ if (unit === undefined) return null;
127
+ const all = await unit.loadAll();
128
+ return {
129
+ handles: Object.entries(all.tables['handles'] ?? [])
130
+ .sort((a, b) => Number(a[0]) - Number(b[0])) // 表键为序号;磁盘序是字典序,须数值排序
131
+ .map(([, value]) => value ),
132
+ };
133
+ },
134
+ async resume(snap ) {
135
+ const source = snap ?? (await service.load());
136
+ if (source === null || source === undefined) {
137
+ ledger.push('resume-unavailable', {});
138
+ warn('resume 快照不可得(storage 未接驳或为空):保留原 store');
139
+ return { ok: false, rebuilt: 0, skipped: 0, mismatches: ['持久层快照不可得'] };
140
+ }
141
+ const mismatches = [];
142
+ const next = new StateStore(sink);
143
+ let rebuilt = 0;
144
+ let skipped = 0;
145
+ for (const entry of source.handles) {
146
+ if (entry.contentB64 === null) {
147
+ skipped += 1;
148
+ continue;
149
+ }
150
+ try {
151
+ const ref = refOf(entry.handle);
152
+ if (ref === null) throw new Error('ref 解析失败');
153
+ const bytes = b64ToBytes(entry.contentB64);
154
+ // 内容完整性:快照 hash 与重放内容、内核寻址结果三方对上才收
155
+ if (sha256Hex(bytes) !== entry.hash) throw new Error('内容 hash 与快照不符');
156
+ const rebuiltHandle = next.put(entry.text ? new TextDecoder().decode(bytes) : bytes, ref);
157
+ if (rebuiltHandle.hash !== entry.hash) throw new Error(`内核寻址 hash 不符(${rebuiltHandle.hash.slice(0, 8)}…)`);
158
+ if (formatHandle(rebuiltHandle) !== entry.handle) throw new Error(`重建为 ${formatHandle(rebuiltHandle)}`);
159
+ rebuilt += 1;
160
+ } catch (error) {
161
+ mismatches.push(`${entry.handle}: ${error instanceof Error ? error.message : String(error)}`);
162
+ }
163
+ }
164
+ const report = { ok: mismatches.length === 0, rebuilt, skipped, mismatches };
165
+ if (report.ok) {
166
+ store = next; // 全部对上才切换(fail-closed:不许半重建状态静默生效)
167
+ ledger.push('resume', { rebuilt, skipped });
168
+ } else {
169
+ ledger.push('resume-mismatch', { ...report });
170
+ warn('resume 重建校验失败:保留原 store,报告 mismatches', report);
171
+ }
172
+ return report;
173
+ },
174
+ flush: () => sink.flush(),
175
+ };
176
+
177
+ // storage 异步接驳(open → 水合 → attach);宿主 backend 缺位 → 本地文件 KvUnit 兜底
178
+ // (修复限制 3,durable 不再是易失内存);连本地兜底也失败才降级内存(fail-open,不静默)
179
+ const storage = getService (ctx, 'storage');
180
+ const unitName = config.unit ?? 'tfAgentState';
181
+ openKvUnit(storage, unitName, ['blobs', 'handles'])
182
+ .catch(() => undefined) // 宿主 storage 异常 → 走本地兜底,最终降级由下级 catch 统一记账
183
+ .then(async (opened) => {
184
+ if (opened === undefined && config.localFallback !== false) {
185
+ // 修复限制 3:本地 JSON 文件 KvUnit(JsonFileKvUnit 构造即做可写性探针,失败抛错)
186
+ const local = new JsonFileKvUnit(join(resolveStateDir(config.stateDir), 'storage'), unitName, warn);
187
+ await local.putRecord('blobs', '__open_probe__', { at: Date.now() });
188
+ sink.attach(local, await hydrateFromUnit(local));
189
+ unit = local;
190
+ ledger.push('storage-local-fallback', { unit: unitName, file: local.file });
191
+ warn(`宿主 storage backend "json" 不可用,降级本地文件 KvUnit(${local.file};durable,跨会话 resume 可用)`);
192
+ return;
193
+ }
194
+ if (opened === undefined) throw new Error('storage backend "json" 不可用或无 kv facet(本地兜底已关闭或失败)');
195
+ sink.attach(opened, await hydrateFromUnit(opened));
196
+ unit = opened;
197
+ ledger.push('storage-attached', { unit: unitName });
198
+ })
199
+ .catch((error) => {
200
+ ledger.push('storage-degraded', { error: String(error) });
201
+ warn('storage 接驳失败(宿主与本地兜底均不可用),降级内存 BlobSink(服务照常提供)', error);
202
+ });
203
+
204
+ if (typeof ctx.provide !== 'function') throw new Error('[state-handle] ctx.provide 不可用:无法提供服务 ctx.state');
205
+ ctx.provide('state', service);
206
+ if (config.announce === true) console.error('[state-handle] mounted: provide(state)(storage 异步接驳中,降级与否见后续告警)');
207
+
208
+ const dispose = () => {
209
+ void (async () => {
210
+ await service.persist().catch((error) => warn('句柄目录落盘失败(内存事实不丢)', error));
211
+ await sink.flush().catch(() => {});
212
+ await unit?.close().catch((error) => warn('storage unit 关闭失败', error));
213
+ })();
214
+ };
215
+ ctx.effect?.(() => dispose, 'stateHandle.provide(state)');
216
+ return asPluginEffect({ service, dispose });
217
+ }
@@ -0,0 +1,60 @@
1
+ // entry/takeover-registry.ts —— 接管状态的最小进程内登记(v0.2.1)
2
+ //
3
+ // 为什么需要:控制栏要在装载横幅上如实写"接管生效 / 未接管"。接管发生在 loop entry 的
4
+ // setFactory 成功之后,而 bundle 的装载顺序是 sidecar → loop → control-bar;两个 entry
5
+ // 之间没有服务依赖(控制栏注入空数组,不能为了读状态把 loop 变成硬依赖)。
6
+ // 于是用同进程的模块级单例做登记:同一份 bundle 内 ESM 只求值一次,读到的是实时事实,
7
+ // 不引入任何 cordis 依赖,也不会跨进程泄漏。
8
+ //
9
+ // 语义边界:
10
+ // · markTakeover —— loop.apply 里 setFactory 成功之后调用;
11
+ // · clearTakeover —— factory 卸载(dispose)时调用,控制栏随即显示"未接管";
12
+ // · isTakeoverActive —— 只表示"本进程内工厂已注册",不表示"任务正在跑"。
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+ const state = { active: false, mode: '', at: '' };
21
+ let listeners = [];
22
+
23
+ export function markTakeover(mode ) {
24
+ state.active = true;
25
+ state.mode = mode;
26
+ state.at = new Date().toISOString();
27
+ // 一次性通知:控制栏据此打印"接管生效"横幅(与装载先后无关,不靠定时器猜时序)
28
+ const pending = listeners;
29
+ listeners = [];
30
+ for (const listener of pending) listener();
31
+ }
32
+
33
+ export function clearTakeover() {
34
+ state.active = false;
35
+ state.mode = '';
36
+ state.at = '';
37
+ }
38
+
39
+ /**
40
+ * 订阅"接管成立"这一刻:已接管则立即回调,否则等 markTakeover。
41
+ * 返回退订函数(entry 卸载时调用,避免悬挂回调)。
42
+ */
43
+ export function onTakeover(listener ) {
44
+ if (state.active) {
45
+ listener();
46
+ return () => {};
47
+ }
48
+ listeners.push(listener);
49
+ return () => {
50
+ listeners = listeners.filter((item) => item !== listener);
51
+ };
52
+ }
53
+
54
+ export function takeover() {
55
+ return { ...state };
56
+ }
57
+
58
+ export function isTakeoverActive() {
59
+ return state.active;
60
+ }