dsh-retrace 0.4.139 → 0.4.148

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.
package/README.md CHANGED
@@ -35,7 +35,7 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
35
35
 
36
36
  > Versions: [VERSIONS.md](./VERSIONS.md)
37
37
 
38
- > 0.4.139 is the current release — install/pin `0.4.139` (the previous npm latest was `0.4.135`; see [VERSIONS.md](./VERSIONS.md)); the `dsh-retrace@0.4.139` examples below apply after that release.
38
+ > **0.4.148 is the current release** — install/pin `0.4.148` (the **GitHub Release is out; the npm package is still pending** — the latest npm version is `0.4.139`; see [VERSIONS.md](./VERSIONS.md)). The `dsh-retrace@0.4.148` examples below apply to this release.
39
39
 
40
40
  ## ⚡ One-minute install
41
41
 
@@ -89,8 +89,10 @@ Full steps in [📦 Installation](#-installation).
89
89
 
90
90
  | | What | |
91
91
  |---|---|---|
92
- | 🕘 | **Checkpoints** | a **Checkpoints** tab in the conversation view: every change (type, time, message count, file-change badges), pushed live via `session/projection` (no polling), windowed for long histories; nested history is browsable outline-style |
93
- | ↩️ | **Artifact rollback** | **context-only / artifacts-only / both** with dry-run preview; git-first + content-addressed snapshot fallback; a rollback is itself a new checkpoint (`restore`). Preview refuses while the agent is running (so "preview says yes, confirm says no" cannot happen), and preview/rollback failures are shown in the UI instead of failing silently |
92
+ | 🕘 | **Unified restore list** | one **Checkpoints** tab in the conversation view — **change records and pre-operation file snapshots in ONE list**. Each row shows the round (when the log has it), type, time, message count, file-change badges, and old-vs-new input (collapsed by default); pushed live via `session/projection` (no polling), windowed for long histories, nested history browsable outline-style |
93
+ | ↩️ | **Rollback** | **three-way choice: context-only / artifacts-only / both**, with a dry-run preview. Rollback is **always available**; when an entry has no file preimage only context rollback is selectable (the other two are disabled with a reason). A **confirm dialog** lists the round, messages removed, file actions and a risk note (export first). Preview refuses while the agent is running; preview/rollback failures are shown instead of failing silently; a rollback is itself a new checkpoint (`restore`) |
94
+ | ⤓ | **Export as…** | **read-only** zip of exactly that entry (`manifest.json` + the captured file preimages + the original text); it **never rolls anything back**. Uses the host preimage store when available, otherwise a manifest-only archive with a visible note |
95
+ | 🎛 | **Three fixed actions per row** | **Jump to conversation / Rollback / Export as…**, always in that order; an **older host** shows an explicit "upgrade and restart" notice instead of silently missing features |
94
96
  | 🧬 | **Lineage identity** | every new session gets a stable lineage id automatically; the sidebar shows one badge per conversation (no duplicates on refresh) |
95
97
  | 🧭 | **Jump-to-conversation** | one click from a checkpoint to that point in the conversation (auto-loads history, anchor highlight); when the point is out of the auto-load budget the reason is reported instead of nothing happening |
96
98
  | 🧹 | **Bounded storage** | snapshots keep the most recent N checkpoints (default 50); throttled background sweep prunes truncated ones |
@@ -151,7 +153,7 @@ The same result with plain file edits and `pnpm` — exactly the steps
151
153
  ```json
152
154
  {
153
155
  "dependencies": {
154
- "dsh-retrace": "^0.4.139"
156
+ "dsh-retrace": "^0.4.148"
155
157
  },
156
158
  "dsh": {
157
159
  "profile": {
@@ -351,7 +353,7 @@ Historical details and exact error strings live in [CHANGELOG.md](./CHANGELOG.md
351
353
  ### Upgrading
352
354
 
353
355
  ```bash
354
- dsh plugin --profile desktop add dsh-retrace@0.4.139
356
+ dsh plugin --profile desktop add dsh-retrace@0.4.148
355
357
  # then restart DSH — plugins are not hot-reloaded
356
358
  ```
357
359
 
@@ -375,7 +377,7 @@ whole tree down, so recover first and diagnose second:
375
377
 
376
378
  ### Pinning
377
379
 
378
- Pin an exact plugin version (`dsh-retrace@0.4.139`) and let `dsh-log-contract` resolve to
380
+ Pin an exact plugin version (`dsh-retrace@0.4.148`) and let `dsh-log-contract` resolve to
379
381
  `>=0.3.18`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
380
382
  the **host surface**, not by semver alone.
381
383
 
@@ -389,7 +391,6 @@ the **host surface**, not by semver alone.
389
391
  | **DSH** | `>=0.1.5 <0.3.0` (see `package.json#dsh.compatibility`); desktop and web modes supported |
390
392
  | **Runtime files** | All files needed at runtime are **committed** in this repository and declared in `package.json#files` (`lib/**`, `cordis.patch.yml`, `README*.md`, `HUMANS.txt`, `LICENSE`) |
391
393
  | **Build output** | Build output is committed (`lib/client.bundle.js`, `lib/dynamic-client.js`, `lib/dynamic-host.js`) and reproducible in-repo: `pnpm i && pnpm build` (`scripts/generate-dynamic.mjs`, `scripts/build-client.mjs`) |
392
- | **Single-file size** | Every distributed file is **below 256 KiB** (largest ≈ 249 KB) |
393
394
  | **Runtime dependencies** | `dsh-log-contract` (log-contract validation), `zod` (argument validation). No post-install scripts, no network access, no additional code download |
394
395
  | **Peer dependencies** | `@deepseek-ai/cordis` and DSH client packages (provided by DSH itself, not bundled or redistributed here) |
395
396
  | **Permissions / external services** | Reads and writes only the local DSH session data directory and session logs. No external services, no telemetry, no data upload |
@@ -411,6 +412,10 @@ the **host surface**, not by semver alone.
411
412
  `message-pending` ("still being generated") rather than being misreported as gone.
412
413
  - Regenerate re-sends only the **text** of the original prompt; prompts that
413
414
  carried images fall back to the text-only content.
415
+ - File **restore** is text-only: a non-UTF-8 (binary) file is reported as
416
+ `binary-unsupported` and skipped instead of being written back. **Export as…**
417
+ packages the captured preimage bytes (including non-text files) without restoring
418
+ anything.
414
419
  - True restore edits the session log **in place** (it neutralizes the two marker
415
420
  segments; sequence numbers stay as they are). It refuses to run while the session is
416
421
  the one you are viewing, while it is running, or while another process holds the file,
package/README.zh.md CHANGED
@@ -30,7 +30,7 @@
30
30
 
31
31
  > 版本索引:[VERSIONS.md](./VERSIONS.md)
32
32
 
33
- > 0.4.139 **已发布到 npm**——安装/固定版本请用当前 npm latest `0.4.135`(见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.139` 示例在该版本发布后适用。
33
+ > **0.4.148 为当前版本**——安装/固定请用 `0.4.148`(**GitHub Release 已发,npm 待发**;npm 最新可安装版本仍为 `0.4.139`,见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.148` 示例适用于该版本。
34
34
 
35
35
  ## ⚡ 一分钟安装
36
36
 
@@ -84,8 +84,10 @@ dsh plugin --profile desktop add dshmarket # 只需一次
84
84
 
85
85
  | | 能力 | 说明 |
86
86
  |---|---|---|
87
- | 🕘 | **读档点** | 对话视图里的「读档点」Tab:每个改动(类型/时间/消息数/文件变更徽标),经 `session/projection` 推送帧实时更新(零轮询),大列表窗口化;嵌套历史按大纲逐层展开 |
88
- | ↩️ | **产物回退** | 仅对话 / 仅产物 / 两者,先干跑预览再执行;git 优先 + 内容寻址快照兜底;回退本身是新读档点(`restore`)。预览在会话运行中直接拒绝(不会出现「预览说可以、确认时才被拒」),预览/回档失败都会在界面上显示,不静默 |
87
+ | 🕘 | **统一读档点列表** | 对话视图里的「读档点」Tab:**改动记录与操作前文件快照合并在一个列表**。每行显示轮次(日志里取得到才有)、类型、时间、消息数、文件变更徽标,以及新旧输入对照(默认折叠);经 `session/projection` 推送帧实时更新(零轮询),大列表窗口化,嵌套历史按大纲逐层展开 |
88
+ | ↩️ | **回档** | **三选一:仅对话 / 仅产物 / 两者**,先干跑预览。回档**始终可用**;该条没有文件前像时只能选「仅对话」(另两项置灰并给出原因)。**确认弹窗**列明轮次、移除消息数、文件动作与风险提示(建议先导出)。预览在会话运行中直接拒绝;预览/回档失败都会在界面上显示,不静默;回档本身是新读档点(`restore`) |
89
+ | ⤓ | **导出另存为** | 把该条内容打成**只读** zip(`manifest.json` + 捕获的文件前像 + 原文),**只导出、不回档**。宿主提供前像存储时用真实前像,否则退化为仅 manifest 的归档并显式提示 |
90
+ | 🎛 | **每行固定三个动作** | **回到会话 / 回档 / 导出另存为**,顺序固定;**旧宿主**会显式提示「请升级并重启」,而不是静默缺少功能 |
89
91
  | 🧬 | **谱系标识** | 新建会话自动分配稳定谱系标识;侧栏每个会话只显示一个标识(刷新不重复) |
90
92
  | 🧭 | **跳转对话** | 从读档点一键跳转到对应位置(自动翻页加载更早历史 + 锚点高亮);该点超出自动加载预算时,给出可诊断原因,而不是点了没反应 |
91
93
  | 🧹 | **存储有界** | 快照只保留最近 N 个读档点(默认 50);节流后台扫掠回收被截断的旧档 |
@@ -135,7 +137,7 @@ dsh plugin --profile <name> add dsh-retrace
135
137
  ```json
136
138
  {
137
139
  "dependencies": {
138
- "dsh-retrace": "^0.4.139"
140
+ "dsh-retrace": "^0.4.148"
139
141
  },
140
142
  "dsh": {
141
143
  "profile": {
@@ -305,7 +307,7 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
305
307
  ### 升级
306
308
 
307
309
  ```bash
308
- dsh plugin --profile desktop add dsh-retrace@0.4.139
310
+ dsh plugin --profile desktop add dsh-retrace@0.4.148
309
311
  # 然后重启 DSH —— 插件不会热重载
310
312
  ```
311
313
 
@@ -324,7 +326,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.139
324
326
 
325
327
  ### 版本固定建议
326
328
 
327
- 请固定到确切版本(`dsh-retrace@0.4.139`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
329
+ 请固定到确切版本(`dsh-retrace@0.4.148`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
328
330
  **不要在跨宿主升级时依赖 `^0.4` 这种范围**:这里的兼容性由**宿主的面**决定,光看 semver 不够。
329
331
 
330
332
  ---
@@ -339,6 +341,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.139
339
341
  (`target-shadowed`);写入尚未 flush 的消息会如实报 `message-pending`(「消息生成中」),
340
342
  不再被误判成「已不在活跃对话」。
341
343
  - 重新生成只重发原提示的**文本**部分;携带图片的提示会退化为仅文本重发。
344
+ - 文件**恢复**仅支持文本:非 UTF-8(二进制)文件会如实报 `binary-unsupported` 并跳过,不会写回工作区。**导出另存为**会把捕获到的前像字节(含非文本文件)打包带走,但只导出、不回档。
342
345
  - **真正恢复**会**原地**改写会话日志(中和两段标记,seq 编号不动)。会话是你当前正在查看的、
343
346
  正在运行的,或文件被其他进程持有时,它会拒绝执行;成功后需重开该会话(或刷新)才看到结果。
344
347
 
@@ -471,7 +474,6 @@ retrace lineage <session> # 会话 parent 链谱系
471
474
  | **Node.js** | `>=20.0.0`(见 `package.json#engines`) |
472
475
  | **DSH** | `>=0.1.5 <0.3.0`(见 `package.json#dsh.compatibility`;桌面与 Web 两种模式均支持) |
473
476
  | **运行所需文件** | 运行时所需文件**全部随仓库提交**并在 `package.json#files` 声明(`lib/**`、`cordis.patch.yml`、README 等) |
474
- | **单文件体积** | 每个分发文件 **< 256 KiB**(最大约 249 KB) |
475
477
  | **构建产物** | 运行所需构建产物**随包提交**(`lib/client.bundle.js`、`lib/dynamic-client.js`、`lib/dynamic-host.js`);仓库内可复现:`pnpm i && pnpm build`(生成器 `scripts/generate-dynamic.mjs`、`scripts/build-client.mjs`) |
476
478
  | **运行时依赖** | `dsh-log-contract`(日志契约校验)、`zod`(参数校验);**不联网、不下载额外代码** |
477
479
  | **宿主依赖(peer)** | `@deepseek-ai/cordis` 与若干 `@deepseek-ai/dsh-*` 客户端包(由 DSH 提供,不由本插件分发) |
@@ -12,6 +12,16 @@
12
12
  * 4. foldCacheGain(events, foldSpan):折前最近 cacheReadTokens vs 折后(未落盘前不可测,
13
13
  * 由调度器折前折后各读——本函数给"折后读数";实际 Δ 由调用方拼)。
14
14
  *
15
+ * 0.4.142 只读扩四项(检测口径,不做去噪/治理):
16
+ * 5. toolsSha16(tools) + requestHeaderSeries(events):每个 request/header 的 tools sha16
17
+ * (工具面变化 = 前缀缓存变化的独立变量;只报事实,不判断好坏);
18
+ * 6. attributeCacheReadDrops(events):按请求 reason(initial/resume/change/series)归因
19
+ * cacheReadTokens 骤降(Δ<0;骤降阈值 20% 只作标记,不改数据);
20
+ * 7. countInjectedBlocks(events):turn=null 含 AGENTS 特征串的 user/message 计数
21
+ * (注入块在会话面上可见份数);
22
+ * 8. cacheWriteSeries(events):官方 usage.cacheWriteTokens 的读数序列 + 最近值。
23
+ * 四项都是纯读取:不改事件、不折叠、不去重、不做任何"治理"动作。
24
+ *
15
25
  * 口径诚实:cacheReadTokens 是**官方 API 返回的缓存命中输入 token**——不是我们的估算,
16
26
  * 是平台实测值(usage 字段)。Δ = 动作前后之差,只在该会话无并发请求时可靠(单会话
17
27
  * 顺序折叠场景成立);标注"近似,受并发影响"。
@@ -153,3 +163,196 @@ export function compactionHistory(events) {
153
163
  items,
154
164
  }
155
165
  }
166
+
167
+
168
+ // ---------------------------------------------------------------------------
169
+ // 0.4.142 扩四项(检测口径)——只读检测,不做去噪/治理
170
+ // ---------------------------------------------------------------------------
171
+ import { createHash } from 'node:crypto'
172
+
173
+ /** 稳定序列化(对象键排序,数组保序):同一工具定义集 ⇒ 同一 sha。 */
174
+ export function canonicalJson(value) {
175
+ if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
176
+ if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(',')}]`
177
+ const keys = Object.keys(value).sort()
178
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`
179
+ }
180
+
181
+ /** request header.tools 的 sha16;空/非数组 ⇒ null(该请求没有工具面,不伪造哈希)。 */
182
+ export function toolsSha16(tools) {
183
+ if (!Array.isArray(tools) || tools.length === 0) return null
184
+ return createHash('sha256').update(canonicalJson(tools)).digest('hex').slice(0, 16)
185
+ }
186
+
187
+ /**
188
+ * 每个 request/header 一行(事件序):seq / time / reason / toolsCount / toolsSha /
189
+ * toolsChanged(与上一个带工具面的请求相比 sha 变了)。只读,不改事件。
190
+ * @returns {Array<{seq:number,time?:number,reason:string|null,toolsCount:number,toolsSha:string|null,toolsChanged:boolean,startsSeries:boolean}>}
191
+ */
192
+ export function requestHeaderSeries(events) {
193
+ if (!Array.isArray(events)) return []
194
+ const rows = []
195
+ let previousSha = null
196
+ for (const ev of events) {
197
+ if (ev?.type !== 'request/header') continue
198
+ const header = ev.data?.header ?? {}
199
+ const tools = Array.isArray(header.tools) ? header.tools : []
200
+ const sha = toolsSha16(tools)
201
+ const reason = typeof ev.data?.reason === 'string' ? ev.data.reason : null
202
+ rows.push({
203
+ seq: ev.seq,
204
+ time: ev.time,
205
+ reason,
206
+ toolsCount: tools.length,
207
+ toolsSha: sha,
208
+ toolsChanged: previousSha !== null && sha !== null && sha !== previousSha,
209
+ startsSeries: ev.data?.startsSeries === true,
210
+ })
211
+ if (sha !== null) previousSha = sha
212
+ }
213
+ return rows
214
+ }
215
+
216
+ /** Δ<0 之外还标记"骤降"(降幅 ≥ 20%)——阈值只影响标记字段,不删行、不改数。 */
217
+ export const CACHE_DROP_ABRUPT_RATIO = 0.2
218
+
219
+ /**
220
+ * 按请求归因 cacheReadTokens 变化。
221
+ *
222
+ * 每个 request/header 配"该请求之后、下一个 request/header 之前"的第一个 usage
223
+ * 读数(官方 API 值);与上一行的读数比 Δ。reason 取请求自己的 reason
224
+ * (initial/resume/change/series)⇒ resume/series 引起的骤降可以被直接看到。
225
+ *
226
+ * 只读:不推测因果、不剔除样本;读不到配对的请求计入 unpaired(如实披露)。
227
+ *
228
+ * @returns {{rows:Array, byReason:object, unpaired:number, seriesStarts:number}}
229
+ */
230
+ export function attributeCacheReadDrops(events) {
231
+ const headers = requestHeaderSeries(events)
232
+ const list = Array.isArray(events) ? events : []
233
+ const rows = []
234
+ let unpaired = 0
235
+ let previous = null
236
+ for (let i = 0; i < headers.length; i += 1) {
237
+ const header = headers[i]
238
+ const nextSeq = i + 1 < headers.length ? headers[i + 1].seq : Number.POSITIVE_INFINITY
239
+ let reading = null
240
+ for (const ev of list) {
241
+ if (!ev || !Number.isInteger(ev.seq) || ev.seq <= header.seq || ev.seq >= nextSeq) continue
242
+ const usage = ev.data?.usage
243
+ if (!usage || !Number.isFinite(usage.cacheReadTokens)) continue
244
+ reading = { seq: ev.seq, time: ev.time, cacheReadTokens: usage.cacheReadTokens, cacheWriteTokens: Number.isFinite(usage.cacheWriteTokens) ? usage.cacheWriteTokens : null }
245
+ break
246
+ }
247
+ if (reading === null) {
248
+ unpaired += 1
249
+ rows.push({ ...header, cacheReadTokens: null, cacheWriteTokens: null, prevCacheReadTokens: previous, deltaTokens: null, drop: false, dropPct: null, abrupt: false })
250
+ continue
251
+ }
252
+ const deltaTokens = previous === null ? null : reading.cacheReadTokens - previous
253
+ const dropPct = previous !== null && previous > 0 && deltaTokens !== null && deltaTokens < 0
254
+ ? (previous - reading.cacheReadTokens) / previous
255
+ : 0
256
+ rows.push({
257
+ ...header,
258
+ cacheReadTokens: reading.cacheReadTokens,
259
+ cacheWriteTokens: reading.cacheWriteTokens,
260
+ prevCacheReadTokens: previous,
261
+ deltaTokens,
262
+ drop: deltaTokens !== null && deltaTokens < 0,
263
+ dropPct,
264
+ abrupt: dropPct >= CACHE_DROP_ABRUPT_RATIO,
265
+ })
266
+ previous = reading.cacheReadTokens
267
+ }
268
+ const byReason = {}
269
+ for (const reason of ['initial', 'resume', 'change', 'series', null]) {
270
+ byReason[reason ?? 'unset'] = { requests: 0, drops: 0, abrupt: 0, dropTokens: 0, cacheReadTokens: 0 }
271
+ }
272
+ for (const row of rows) {
273
+ const bucket = byReason[row.reason ?? 'unset']
274
+ bucket.requests += 1
275
+ if (row.cacheReadTokens !== null) bucket.cacheReadTokens += row.cacheReadTokens
276
+ if (row.drop) {
277
+ bucket.drops += 1
278
+ bucket.dropTokens += -row.deltaTokens
279
+ if (row.abrupt) bucket.abrupt += 1
280
+ }
281
+ }
282
+ return { rows, byReason, unpaired, seriesStarts: headers.filter((h) => h.reason === 'series').length }
283
+ }
284
+
285
+ /** 注入块特征串(默认 AGENTS.md 指令块;可覆盖以便诊断其他注入面)。 */
286
+ export const INJECTED_BLOCK_SIGNATURE = /AGENTS\.md/i
287
+
288
+ /** user/message 的纯文本(全部 text 块拼接;非文本块忽略)。 */
289
+ function userMessageText(ev) {
290
+ const content = ev?.data?.content
291
+ if (!Array.isArray(content)) return ''
292
+ return content.filter((block) => block?.type === 'text' && typeof block.text === 'string').map((block) => block.text).join('\n')
293
+ }
294
+
295
+ /**
296
+ * 注入块"面上可见份数":turn 为 null/未声明、且文本含 AGENTS 特征串的 user/message。
297
+ * 这类行是会话面上可见的行(不是 log-only),计数即"用户能看到的注入份数"。
298
+ * 只读:不隐藏、不改写、不去重。
299
+ * @returns {{count:number, seqs:number[], bySource:object, scanned:number}}
300
+ */
301
+ export function countInjectedBlocks(events, { signature = INJECTED_BLOCK_SIGNATURE } = {}) {
302
+ if (!Array.isArray(events)) return { count: 0, seqs: [], bySource: {}, scanned: 0 }
303
+ const seqs = []
304
+ const bySource = {}
305
+ let scanned = 0
306
+ for (const ev of events) {
307
+ if (ev?.type !== 'user/message') continue
308
+ scanned += 1
309
+ const turn = ev.data?.turn
310
+ if (turn !== null && turn !== undefined) continue
311
+ if (!signature.test(userMessageText(ev))) continue
312
+ seqs.push(ev.seq)
313
+ const kind = typeof ev.data?.source?.kind === 'string' ? ev.data.source.kind : 'unknown'
314
+ bySource[kind] = (bySource[kind] ?? 0) + 1
315
+ }
316
+ return { count: seqs.length, seqs, bySource, scanned }
317
+ }
318
+
319
+ /**
320
+ * 官方 usage.cacheWriteTokens 读数序列(与 cacheReadTokens 同一来源字段)。
321
+ * @returns {{latest:object|null, total:number, samples:number, series:Array}}
322
+ */
323
+ export function cacheWriteSeries(events) {
324
+ if (!Array.isArray(events)) return { latest: null, total: 0, samples: 0, series: [] }
325
+ const series = []
326
+ for (const ev of events) {
327
+ const usage = ev?.data?.usage
328
+ if (!usage || !Number.isFinite(usage.cacheWriteTokens)) continue
329
+ series.push({
330
+ seq: ev.seq,
331
+ time: ev.time,
332
+ cacheWriteTokens: usage.cacheWriteTokens,
333
+ cacheReadTokens: Number.isFinite(usage.cacheReadTokens) ? usage.cacheReadTokens : null,
334
+ })
335
+ }
336
+ const total = series.reduce((sum, row) => sum + row.cacheWriteTokens, 0)
337
+ return { latest: series.length > 0 ? series[series.length - 1] : null, total, samples: series.length, series }
338
+ }
339
+
340
+ /**
341
+ * 四项一次性只读汇总(检测面入口;消费方自行决定怎么展示,本函数不做治理)。
342
+ * @returns {{tools:object, reasons:object, injected:object, cacheWrite:object, note:string}}
343
+ */
344
+ export function cacheMetricsReport(events) {
345
+ const tools = requestHeaderSeries(events)
346
+ const shas = tools.map((row) => row.toolsSha).filter((sha) => sha !== null)
347
+ return {
348
+ tools: {
349
+ series: tools,
350
+ changes: tools.filter((row) => row.toolsChanged).length,
351
+ distinct: new Set(shas).size,
352
+ },
353
+ reasons: attributeCacheReadDrops(events),
354
+ injected: countInjectedBlocks(events),
355
+ cacheWrite: cacheWriteSeries(events),
356
+ note: 'read-only detection: raw rows kept as-is (no dedupe / no scrub / no folding)',
357
+ }
358
+ }