dsh-knit 0.15.0 → 0.17.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.
@@ -1,26 +1,37 @@
1
1
  /**
2
- * Knit v0.15 · **Context Feedback / Context Audit**
2
+ * Knit v0.16 · **Context Feedback / Context Effectiveness**
3
3
  *
4
4
  * Context Pack 给了「应该先读什么」,这个模块回答**它之后真的被用了吗**。
5
5
  * 只有三个事实来源,全部是确定性的:
6
6
  *
7
- * 1. **Context Snapshot** —— Knit 把一份 Context Pack 交出去的那一刻(工具调用 / 面板装配),
8
- * 记下当时的三层排序。它代表「Knit 当时提供给 Agent 的上下文」。
9
- * 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 / 换了层。
7
+ * 1. **Context Snapshot / Epoch** —— Knit 把一份 Context Pack 交出去的那一刻
8
+ * (工具调用 / 面板装配),记下当时的三层排序与它的 `epochId`。
9
+ * 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 / 换了层,以及 `fromEpoch → toEpoch`。
10
10
  * 3. **Read evidence** —— 会话事件流里**真实发生过的 `read` 工具调用**
11
11
  * (`tool/call` 配对 `tool/result`,且 `message.isError !== true`)。
12
- * 搜索命中(`grep` / `glob`)**不算读过** —— 规格 §9。
12
+ * 搜索命中(`grep` / `glob`)**不算读过**。
13
13
  *
14
- * Usage 就是这三者的**连接**:某次读,落在当时那份 Snapshot 的哪一层?
14
+ * Usage 就是这三者的**连接**,而且连接发生在**读的那一刻**:
15
+ * 每条 read 落库时就按 `snapshotAt(read.seq)` 结算出 `tierAtRead` / `rankAtRead` /
16
+ * `insideAtRead` / `epochId` 并**冻结**。之后上下文再怎么变,历史归因都不许重算 ——
17
+ * 「当前视图」与「历史视图」是两件事。
15
18
  *
16
19
  * ⚠️ 本模块**不碰 Retrieval**(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness 一行不改),
17
- * 也**不订阅 DSH event bus、不建 Event Store、不落盘、不联网、不调模型**。
18
- * 它是纯函数 + 一个按会话分片的内存小状态(规格 §10):事件由调用方从
19
- * `session.snapshotEvents()` 拉出来喂进来,`seq` 当幂等游标,所以 5 秒轮询重复喂同一批事件
20
- * 不会重复计数。
20
+ * 也**不落盘、不联网、不调模型、不写 memory、不自动干预上下文**。
21
+ * 读证据的唯一来源是宿主派发的 `session/event`(v0.16 起):本模块**自己**从不调用
22
+ * `session.snapshotEvents()` —— 那个 API 已被 DSH 标记 deprecated
23
+ * (「new production calls are prohibited」),而且它在 fork 会话上会把父会话继承来的
24
+ * 前缀事件也算进来。代价是:订阅之前发生的事件不会自动进来。
25
+ *
26
+ * v0.17 修订:闸门开晚时(真实用法:读完才想起来看面板),宿主可以在**开闸那一刻**
27
+ * 回填一次会话已有的事件(`markBackfilled()` 由宿主在 `ingestEvents()` 之后调用)。
28
+ * 本模块仍然零 I/O、零网络、零模型 —— 事件是宿主喂进来的,它只多知道一件事:
29
+ * 「这批读是补记的」。**顺序是这个机制的组成部分**:`recordRead()` 在事件入库那一刻就把
30
+ * 归因冻结,所以宿主必须**先把手上那份包 `noteSnapshot()` 掉、再喂补记的事件**,
31
+ * 否则那些读会在「一份快照都还没有」的状态下被冻成包外(规格 §6:不知道就不要说)。
21
32
  *
22
33
  * 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
23
- * memory 写入。Usage 不是分数。
34
+ * quality score、memory 写入。Usage 不是分数,是计数与事实。
24
35
  *
25
36
  * @module feedback
26
37
  */
@@ -30,10 +41,15 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
30
41
  export const MAX_SESSIONS = 24
31
42
  /** 每个会话最多记多少篇**读过**的文档。 */
32
43
  export const MAX_READS_PER_SESSION = 200
33
- /** 每个会话最多保留几份 Snapshot(判断「读的时候是哪一层」要用最近两份)。 */
34
- export const MAX_SNAPSHOTS_PER_SESSION = 2
35
- /** 每个会话最多保留多少条 Delta。 */
36
- export const MAX_DELTAS_PER_SESSION = 20
44
+ /** 每个会话最多保留几份 Snapshot / Epoch。
45
+ *
46
+ * v0.16 由 2 提到 20:归因本身**在 Read 时结算**,保留数量不影响它的正确性;
47
+ * 它只决定 `continuedReadAfterExit` / `reEntry` 这两个事实能回溯多远
48
+ * (要能看见「离开过、又回来」就必须留着中间那几份)。
49
+ */
50
+ export const MAX_SNAPSHOTS_PER_SESSION = 20
51
+ /** 每个会话最多保留多少条 Delta 明细(计数不受它影响)。 */
52
+ export const MAX_DELTAS_PER_SESSION = 50
37
53
  /** 最多同时挂起多少个「已调用、还没结果」的 read。 */
38
54
  export const MAX_PENDING_CALLS = 64
39
55
 
@@ -134,7 +150,7 @@ function signatureOf(items, task) {
134
150
  *
135
151
  * @param {object|null} prev - 上一份 Snapshot
136
152
  * @param {object|null} next - 这一份 Snapshot
137
- * @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, stable: boolean}} 差异
153
+ * @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, fromEpoch: number|null, toEpoch: number|null, stable: boolean}} 差异
138
154
  */
139
155
  export function diffContext(prev, next) {
140
156
  const before = indexOf(prev)
@@ -158,6 +174,9 @@ export function diffContext(prev, next) {
158
174
  disappeared,
159
175
  moved,
160
176
  taskChanged,
177
+ // 哪两个 Epoch 之间的变化(没有上一份时 fromEpoch 为 null)
178
+ fromEpoch: prev && Number.isInteger(prev.epochId) ? prev.epochId : null,
179
+ toEpoch: next && Number.isInteger(next.epochId) ? next.epochId : null,
161
180
  stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
162
181
  }
163
182
  }
@@ -188,7 +207,7 @@ function indexOf(snapshot) {
188
207
  *
189
208
  * 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
190
209
  *
191
- * @param {object[]} events - `session.snapshotEvents()` 的产物
210
+ * @param {object[]} events - 会话事件(v0.16 起由 `session/event` 订阅逐条喂进来)
192
211
  * @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
193
212
  * @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
194
213
  */
@@ -264,7 +283,6 @@ function parseArguments(raw) {
264
283
  return {}
265
284
  }
266
285
  }
267
-
268
286
  /* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
269
287
 
270
288
  /**
@@ -276,7 +294,7 @@ export function createStore() {
276
294
  }
277
295
 
278
296
  /**
279
- * 标记这个会话「被审计了」—— 之后它的面板请求才会被记账。
297
+ * 标记这个会话「被审计了」—— 之后它的读事件与面板请求才会被记账。
280
298
  *
281
299
  * 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
282
300
  * 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
@@ -302,7 +320,8 @@ export function activateAudit(store, sessionId) {
302
320
  }
303
321
 
304
322
  /**
305
- * 这个会话是否在记账。
323
+ * 这个会话是否在记账。**订阅回调的第一行就用它早退** ——
324
+ * 没记账的会话一次 Map 查找就返回,不做任何别的工作。
306
325
  * @param {object} store - store
307
326
  * @param {string} sessionId - 会话 id
308
327
  * @returns {boolean} 是否记账
@@ -311,6 +330,41 @@ export function isAudited(store, sessionId) {
311
330
  return !!(store && sessionId && store.audited.has(sessionId))
312
331
  }
313
332
 
333
+ /**
334
+ * 标记这个会话的历史**已经被回填过**(v0.17 修订)。
335
+ *
336
+ * 幂等:调用方(宿主)在开闸时用它保证「一个会话只回填一次」,之后从订阅来的新事件
337
+ * 照常单独入账。
338
+ *
339
+ * @param {object} store - store
340
+ * @param {string} sessionId - 会话 id
341
+ * @returns {boolean} 是否成功
342
+ */
343
+ export function markBackfilled(store, sessionId) {
344
+ try {
345
+ if (!store || !sessionId) return false
346
+ stateOf(store, sessionId).backfilled = true
347
+ return true
348
+ } catch {
349
+ return false
350
+ }
351
+ }
352
+
353
+ /**
354
+ * 这个会话的历史回填过了吗。
355
+ * @param {object} store - store
356
+ * @param {string} sessionId - 会话 id
357
+ * @returns {boolean} 是否回填过
358
+ */
359
+ export function isBackfilled(store, sessionId) {
360
+ try {
361
+ const state = store && sessionId ? store.sessions.get(sessionId) : null
362
+ return !!(state && state.backfilled)
363
+ } catch {
364
+ return false
365
+ }
366
+ }
367
+
314
368
  /**
315
369
  * 取(或建)一个会话的状态,并按 LRU 触摸 —— 会话数量超上限时淘汰最久没碰的。
316
370
  * @param {object} store - store
@@ -321,15 +375,19 @@ function stateOf(store, sessionId) {
321
375
  let state = store.sessions.get(sessionId)
322
376
  if (!state) {
323
377
  state = {
324
- seq: -1, // 已消费到的事件 seq(幂等游标)
378
+ seq: -1, // 已消费到的事件 seq(幂等游标;也是「当前水位」)
325
379
  pending: new Map(), // 已调用、还没结果的 read
326
- snapshots: [], // 最近两份 Context Pack
380
+ snapshots: [], // 最近 MAX_SNAPSHOTS_PER_SESSION 份 Context Pack(每份 = 一个 Epoch)
381
+ epochs: [], // 与 snapshots 一一对应的 Epoch 级计数
327
382
  deltas: [], // 最近若干条变化
328
- reads: new Map(), // rel → 计数
383
+ reads: new Map(), // rel → 冻结的读归因
329
384
  readOrder: [], // rel 的插入顺序(淘汰用)
330
- // ⚠️ `changes` 是**累计**的上下文替换次数,与 `deltas` 数组的长度无关 ——
331
- // 数组会被上限砍掉,但「这个会话里上下文变过几次」不能被砍(那正是 churn 这个指标)。
332
- churn: { changes: 0, appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
385
+ // ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
386
+ // 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
387
+ churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
388
+ // v0.17 修订:这份状态里的读是**回填**进来的(开闸时补记的历史)。
389
+ // 它只用于「一个会话只回填一次」,不影响归因 —— 归因由宿主喂事件的顺序保证。
390
+ backfilled: false,
333
391
  }
334
392
  store.sessions.set(sessionId, state)
335
393
  }
@@ -346,9 +404,12 @@ function stateOf(store, sessionId) {
346
404
  /* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
347
405
 
348
406
  /**
349
- * 把一批会话事件喂进去,抽出 read 并记账。
407
+ * 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
350
408
  *
351
- * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败(规格 §33)。
409
+ * v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
410
+ * 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
411
+ *
412
+ * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
352
413
  *
353
414
  * @param {object} store - store
354
415
  * @param {string} sessionId - 会话 id
@@ -356,6 +417,35 @@ function stateOf(store, sessionId) {
356
417
  * @param {{root?: string}} [options] - 选项
357
418
  * @returns {{ok: boolean, reads: number, cursor: number}} 结果
358
419
  */
420
+ /**
421
+ * 安全地取一次版本标记。**任何异常都咽掉**:记账坏了不许影响宿主。
422
+ * @param {(rel: string) => unknown} stat - 宿主注入的取样函数
423
+ * @param {string} rel - 已归一化的工作区相对路径
424
+ * @returns {number|null} mtimeMs,或 null(拿不到就不猜)
425
+ */
426
+ function safeStat(stat, rel) {
427
+ try {
428
+ const value = stat(rel)
429
+ return Number.isFinite(value) ? value : null
430
+ } catch {
431
+ return null
432
+ }
433
+ }
434
+
435
+ /**
436
+ * 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
437
+ *
438
+ * v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
439
+ * 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
440
+ *
441
+ * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
442
+ *
443
+ * @param {object} store - store
444
+ * @param {string} sessionId - 会话 id
445
+ * @param {object[]} events - 会话事件
446
+ * @param {{root?: string, stat?: (rel: string) => unknown}} [options] - 选项(v0.17 新增 `stat`)
447
+ * @returns {{ok: boolean, reads: number, cursor: number}} 结果
448
+ */
359
449
  export function ingestEvents(store, sessionId, events, options = {}) {
360
450
  try {
361
451
  if (!store || !sessionId) return { ok: false, reads: 0, cursor: -1 }
@@ -367,7 +457,14 @@ export function ingestEvents(store, sessionId, events, options = {}) {
367
457
  })
368
458
  state.pending = pending
369
459
  if (cursor > state.seq) state.seq = cursor
370
- for (const read of reads) recordRead(state, read)
460
+ // v0.17:只在「这次读被确认成功」的时刻取一次版本标记(stat 由宿主注入,
461
+ // 本模块仍然零 I/O)。取样在 recordRead 之前,而 recordRead 只处理
462
+ // seq > fromSeq 的新事件 —— 同一事件重复派发既不重复计数,也不重复取样。
463
+ const stat = typeof options.stat === 'function' ? options.stat : null
464
+ for (const read of reads) {
465
+ read.mtimeMs = stat ? safeStat(stat, read.rel) : null
466
+ recordRead(state, read)
467
+ }
371
468
  return { ok: true, reads: reads.length, cursor: state.seq }
372
469
  } catch {
373
470
  return { ok: false, reads: 0, cursor: -1 }
@@ -380,6 +477,9 @@ export function ingestEvents(store, sessionId, events, options = {}) {
380
477
  * 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
381
478
  * 同一份上下文记成几十份,Delta churn 立刻变成噪音。
382
479
  *
480
+ * `meta.seq` 省略时用会话当前的**事件水位**(`state.seq`)—— 也就是「交包这一刻,
481
+ * 已经发生到第几个事件」。这正是历史归因要的边界:seq ≤ 它的读算在这份包里。
482
+ *
383
483
  * @param {object} store - store
384
484
  * @param {string} sessionId - 会话 id
385
485
  * @param {object} pack - Context Pack
@@ -390,24 +490,35 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
390
490
  try {
391
491
  if (!store || !sessionId || !pack) return null
392
492
  const state = stateOf(store, sessionId)
393
- const next = snapshotOf(pack, meta)
493
+ // ⚠️ 不传 `seq` 时取**当前事件水位**。回填路径下宿主必须先记包再喂事件 ——
494
+ // 那一刻水位还是 -1,第一份快照自然落在会话开头,补记的读才有资格归到
495
+ // 「我们已知最早的那份包」上(见文件头与 index.js 的 `backfillFeedback`)。
496
+ const seq = Number.isInteger(meta.seq) ? meta.seq : state.seq
497
+ const next = snapshotOf(pack, { seq, at: meta.at })
394
498
  const prev = state.snapshots[state.snapshots.length - 1] || null
395
499
 
396
500
  if (prev && prev.sig === next.sig) {
397
501
  if (next.at > prev.at) prev.at = next.at
398
502
  if (next.seq > prev.seq) prev.seq = next.seq
503
+ const epoch = epochIn(state, prev.epochId)
504
+ if (epoch && prev.seq > epoch.snapshotSeq) epoch.snapshotSeq = prev.seq
399
505
  return null
400
506
  }
401
507
 
508
+ // Epoch 编号从这里发出:新建一份上下文 = 一个新 Epoch。同签名不算新 Epoch。
509
+ next.epochId = prev && Number.isInteger(prev.epochId) ? prev.epochId + 1 : 1
402
510
  state.snapshots.push(next)
403
- while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) state.snapshots.shift()
511
+ state.epochs.push(createEpoch(next))
512
+ while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) {
513
+ state.snapshots.shift()
514
+ state.epochs.shift()
515
+ }
404
516
 
405
517
  let delta = null
406
518
  if (prev) {
407
519
  delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
408
520
  state.deltas.push(delta)
409
521
  while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
410
- state.churn.changes += 1
411
522
  state.churn.appeared += delta.appeared.length
412
523
  state.churn.disappeared += delta.disappeared.length
413
524
  state.churn.moved += delta.moved.length
@@ -420,79 +531,338 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
420
531
  }
421
532
 
422
533
  /**
423
- * 记一次真实读。**不属于任何快照的读 = outside context**(这不是错,是信息)。
534
+ * 给一个新 Epoch 建计数骨架(总量取自这份快照,已读量靠后续 read 累加)。
535
+ * @param {object} snapshot - 刚记下的快照(已带 epochId)
536
+ * @returns {object} Epoch 记录
537
+ */
538
+ function createEpoch(snapshot) {
539
+ const counts = {
540
+ primary: { total: 0, read: 0 },
541
+ supporting: { total: 0, read: 0 },
542
+ related: { total: 0, read: 0 },
543
+ }
544
+ for (const item of snapshot.items) {
545
+ const bucket = counts[item.tier]
546
+ if (bucket) bucket.total += 1
547
+ }
548
+ const primary = snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1)
549
+ return {
550
+ epochId: snapshot.epochId,
551
+ snapshotSeq: snapshot.seq,
552
+ topic: snapshot.topic,
553
+ task: snapshot.task,
554
+ primary: { rel: primary ? primary.rel : '', read: false },
555
+ supporting: counts.supporting,
556
+ related: counts.related,
557
+ outsideReads: 0,
558
+ continuedReadsAfterExit: 0,
559
+ reEntries: 0,
560
+ seen: new Set(), // 本 Epoch 里已经计过「读」的 `层:rel`(导出前会剥掉)
561
+ }
562
+ }
563
+
564
+ /**
565
+ * 按 epochId 找 Epoch 记录。找不到返回 null(早于任何快照的读就是这种)。
566
+ * @param {object} state - 会话状态
567
+ * @param {number|null} epochId - Epoch 编号
568
+ * @returns {object|null} Epoch 记录
569
+ */
570
+ function epochIn(state, epochId) {
571
+ const list = state && Array.isArray(state.epochs) ? state.epochs : []
572
+ if (!Number.isInteger(epochId)) return null
573
+ for (let i = list.length - 1; i >= 0; i -= 1) {
574
+ if (list[i].epochId === epochId) return list[i]
575
+ }
576
+ return null
577
+ }
578
+
579
+ /**
580
+ * 记一次真实读。**归因在这一次调用里就结算并冻结**,之后不再重算。
581
+ * 不属于任何快照的读 = outside context(这不是错,是信息)。
424
582
  * @param {object} state - 会话状态
425
583
  * @param {object} read - 归一化后的 read 证据
426
584
  */
427
585
  function recordRead(state, read) {
428
- const snapshot = snapshotAt(state.snapshots, read.seq)
429
- const hit = snapshot ? snapshot.items.find((item) => item.rel === read.rel) : null
430
- const inside = !!hit
431
- const tier = hit ? hit.tier : null
432
- const rank = hit ? hit.rank : null
586
+ const at = snapshotAt(state.snapshots, read.seq)
587
+ const attribution = attributeRead(at, read.rel)
588
+ const facts = attributeReadFacts(state.snapshots, read.rel, read.seq)
589
+ const point = {
590
+ seq: read.seq,
591
+ at: read.time,
592
+ snapshotSeq: attribution.snapshotSeq,
593
+ epochId: attribution.epochId,
594
+ tier: attribution.tierAtRead,
595
+ rank: attribution.rankAtRead,
596
+ inside: attribution.insideAtRead,
597
+ }
433
598
 
434
599
  let entry = state.reads.get(read.rel)
435
600
  if (!entry) {
436
601
  entry = {
437
602
  rel: read.rel,
438
- count: 1,
439
- firstReadAt: read.time,
440
- firstReadSeq: read.seq,
441
- firstTier: tier,
442
- firstRank: rank,
443
- lastReadAt: read.time,
444
- lastTier: tier,
445
- outside: !inside,
446
- outsideCount: inside ? 0 : 1,
603
+ count: 0,
604
+ firstRead: { ...point },
605
+ lastRead: { ...point },
606
+ insideReads: 0,
607
+ outsideReads: 0,
608
+ primaryReads: 0,
609
+ supportingReads: 0,
610
+ relatedReads: 0,
611
+ reEntry: false,
612
+ continuedReadAfterExit: false,
613
+ // v0.17:首次读之前没有「上一次」,三个字段的初值就是「不知道」
614
+ lastReadMtimeMs: null,
615
+ prevReadMtimeMs: null,
616
+ rereadAfterChange: false,
447
617
  }
448
618
  state.reads.set(read.rel, entry)
449
619
  state.readOrder.push(read.rel)
450
620
  while (state.readOrder.length > MAX_READS_PER_SESSION) {
451
621
  state.reads.delete(state.readOrder.shift())
452
622
  }
453
- return
454
623
  }
455
624
 
456
625
  entry.count += 1
457
- entry.lastReadAt = read.time
458
- entry.lastTier = tier
459
- if (!inside) {
460
- entry.outside = true
461
- entry.outsideCount += 1
462
- }
463
- if (!Number.isFinite(entry.firstReadAt) || read.time < entry.firstReadAt) {
464
- entry.firstReadAt = read.time
465
- entry.firstReadSeq = read.seq
466
- entry.firstTier = tier
467
- entry.firstRank = rank
626
+ // v0.17:把「这次读观察到的版本标记」冻结下来 —— 只在成功 read 时更新,
627
+ // 永不被扫描或投影改写(与「归因在读那一刻冻结」是同一条纪律)。
628
+ entry.prevReadMtimeMs = entry.lastReadMtimeMs
629
+ entry.rereadAfterChange = entry.lastReadMtimeMs !== null
630
+ && read.mtimeMs !== null
631
+ && read.mtimeMs !== entry.lastReadMtimeMs
632
+ entry.lastReadMtimeMs = Number.isFinite(read.mtimeMs) ? read.mtimeMs : null
633
+ // 「第一次读」按**事件 seq** 认(seq 才是真相,墙钟只用来显示)
634
+ if (read.seq < entry.firstRead.seq || (read.seq === entry.firstRead.seq && read.time < entry.firstRead.at)) {
635
+ entry.firstRead = { ...point }
636
+ }
637
+ if (read.seq > entry.lastRead.seq || (read.seq === entry.lastRead.seq && read.time >= entry.lastRead.at)) {
638
+ entry.lastRead = { ...point }
639
+ }
640
+ if (attribution.insideAtRead) entry.insideReads += 1
641
+ else entry.outsideReads += 1
642
+ if (attribution.tierAtRead === 'primary') entry.primaryReads += 1
643
+ else if (attribution.tierAtRead === 'supporting') entry.supportingReads += 1
644
+ else if (attribution.tierAtRead === 'related') entry.relatedReads += 1
645
+ if (facts.continuedReadAfterExit) entry.continuedReadAfterExit = true
646
+ if (facts.reEntry) entry.reEntry = true
647
+
648
+ const epoch = epochIn(state, attribution.epochId)
649
+ if (epoch) {
650
+ if (!attribution.insideAtRead) epoch.outsideReads += 1
651
+ if (facts.continuedReadAfterExit) epoch.continuedReadsAfterExit += 1
652
+ if (facts.reEntry) epoch.reEntries += 1
653
+ if (attribution.insideAtRead && attribution.tierAtRead) {
654
+ const key = `${attribution.tierAtRead}:${read.rel}`
655
+ if (!epoch.seen.has(key)) {
656
+ epoch.seen.add(key)
657
+ const bucket = epoch[attribution.tierAtRead]
658
+ if (bucket) bucket.read += 1
659
+ }
660
+ if (attribution.tierAtRead === 'primary' && epoch.primary.rel === read.rel) epoch.primary.read = true
661
+ }
468
662
  }
469
663
  }
470
664
 
471
665
  /**
472
666
  * 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
473
667
  * 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
668
+ *
669
+ * 这是 runtime 与离线回放到共用的**同一个纯函数**:两边「规则一致」靠它,
670
+ * 而不是靠两边的数字恰好相等(交付时刻不可观测,数字本来就不可能相等)。
671
+ *
474
672
  * @param {object[]} snapshots - 快照栈
475
673
  * @param {number} seq - 读的 seq
476
674
  * @returns {object|null} 快照
477
675
  */
478
- function snapshotAt(snapshots, seq) {
479
- for (let i = snapshots.length - 1; i >= 0; i -= 1) {
480
- if (snapshots[i].seq <= seq) return snapshots[i]
676
+ export function snapshotAt(snapshots, seq) {
677
+ const list = Array.isArray(snapshots) ? snapshots : []
678
+ for (let i = list.length - 1; i >= 0; i -= 1) {
679
+ if (list[i].seq <= seq) return list[i]
481
680
  }
482
681
  return null
483
682
  }
484
683
 
684
+ /**
685
+ * 把「这次读」钉到一份快照上 —— 输出的是**读那一刻**的事实,不是当前视图。
686
+ * @param {object|null} snapshot - 读那一刻生效的快照(`snapshotAt()` 的结果)
687
+ * @param {string} rel - 归一化后的路径
688
+ * @returns {{snapshotSeq: number|null, epochId: number|null, tierAtRead: string|null, rankAtRead: number|null, insideAtRead: boolean}} 归因
689
+ */
690
+ export function attributeRead(snapshot, rel) {
691
+ if (!snapshot || !Array.isArray(snapshot.items)) {
692
+ return { snapshotSeq: null, epochId: null, tierAtRead: null, rankAtRead: null, insideAtRead: false }
693
+ }
694
+ const hit = snapshot.items.find((item) => item.rel === rel)
695
+ return {
696
+ snapshotSeq: Number.isInteger(snapshot.seq) ? snapshot.seq : null,
697
+ epochId: Number.isInteger(snapshot.epochId) ? snapshot.epochId : null,
698
+ tierAtRead: hit ? hit.tier : null,
699
+ rankAtRead: hit ? hit.rank : null,
700
+ insideAtRead: !!hit,
701
+ }
702
+ }
703
+
704
+ /**
705
+ * 推导两个**事实**字段(规格 §12 / §13),只用保留窗口内的快照:
706
+ *
707
+ * - `continuedReadAfterExit`:这次读**在当时那份快照之外**,但更早的某份快照里有这篇
708
+ * ⇒ 「离开上下文之后它仍然被读了」。
709
+ * - `reEntry`:这次读**在当时那份快照之内**,更早的某份快照里也有过,但中间至少有一份
710
+ * 快照里没有它 ⇒ 「离开过,又回来了,而且回来之后被读了」。
711
+ *
712
+ * ⚠️ 这两个字段只是**事实**。它们**不许**被解释成「Agent 不认可新上下文」
713
+ * —— 那是推断,不在这个模块的职责里(规格 §5 Evidence Over Interpretation)。
714
+ *
715
+ * 只在保留窗口内推导:宁可漏记,也不猜。
716
+ *
717
+ * @param {object[]} snapshots - 快照栈
718
+ * @param {string} rel - 归一化后的路径
719
+ * @param {number} readSeq - 这次读的 seq
720
+ * @returns {{continuedReadAfterExit: boolean, reEntry: boolean}} 两个事实
721
+ */
722
+ export function attributeReadFacts(snapshots, rel, readSeq) {
723
+ const list = Array.isArray(snapshots) ? snapshots : []
724
+ const empty = { continuedReadAfterExit: false, reEntry: false }
725
+ const at = snapshotAt(list, readSeq)
726
+ if (!at) return empty
727
+ const atIndex = list.indexOf(at)
728
+ if (atIndex < 0) return empty
729
+
730
+ const insideNow = at.items.some((item) => item.rel === rel)
731
+ let sawInside = false
732
+ let sawGapAfterInside = false
733
+ for (let i = 0; i < atIndex; i += 1) {
734
+ const has = list[i].items.some((item) => item.rel === rel)
735
+ if (has) sawInside = true
736
+ else if (sawInside) sawGapAfterInside = true
737
+ }
738
+ // 更早的窗口里从来没有过它 —— 那这次既不是「继续读」也不是「重新进入」
739
+ if (!sawInside) return empty
740
+ if (insideNow) return { continuedReadAfterExit: false, reEntry: sawGapAfterInside }
741
+ return { continuedReadAfterExit: true, reEntry: false }
742
+ }
743
+
744
+ /* ── 6. Lifecycle 投影(v0.17) ─────────────────────────────────────── */
745
+
746
+ /**
747
+ * 把一条 read entry 与**当前扫描到的版本标记**投影成一个 lifecycle 事实。
748
+ *
749
+ * 判定优先级是**硬顺序**:`changedAfterLastRead` 先于 `rereadAfterChange` ——
750
+ * 这就是「文件再次变化后状态回到 `读后已更新`」的实现方式。
751
+ *
752
+ * 状态值只有四个英文事实,**中文文案不进数据层**(UI 按 locale 映射):
753
+ * `unread` / `read` / `updated_after_read` / `reread_after_update`。
754
+ *
755
+ * 拿不到版本标记(文件被删、不在扫描结果、stat 失败)时**不做变化判断**,
756
+ * 状态回落到冻结的事实 —— 宁可少说,也不乱说。
757
+ *
758
+ * @param {object|null} entry - `state.reads` 里的 entry
759
+ * @param {number|null} [mtimeMs] - 当前扫描到的版本标记
760
+ * @returns {{status: string, lastReadMtimeMs: number|null, changedAfterLastRead: boolean, rereadAfterChange: boolean}} 状态
761
+ */
762
+ export function lifecycleOf(entry, mtimeMs = null) {
763
+ const count = entry && Number.isInteger(entry.count) ? entry.count : 0
764
+ const lastReadMtimeMs = entry && Number.isFinite(entry.lastReadMtimeMs) ? entry.lastReadMtimeMs : null
765
+ const changedAfterLastRead = Number.isFinite(mtimeMs) && lastReadMtimeMs !== null
766
+ && mtimeMs !== lastReadMtimeMs
767
+ let status = 'unread'
768
+ if (count > 0) {
769
+ if (changedAfterLastRead) status = 'updated_after_read'
770
+ else if (entry.rereadAfterChange) status = 'reread_after_update'
771
+ else status = 'read'
772
+ }
773
+ return {
774
+ status,
775
+ lastReadMtimeMs,
776
+ changedAfterLastRead,
777
+ rereadAfterChange: !!(entry && entry.rereadAfterChange),
778
+ }
779
+ }
780
+
781
+ /**
782
+ * 把 `state.reads` 摊平成数组(Map 与数组都收,测试常直接喂数组)。
783
+ * @param {Map<string, object>|object[]} reads - 读证据
784
+ * @returns {object[]} entry 列表
785
+ */
786
+ function readEntries(reads) {
787
+ if (reads instanceof Map) return [...reads.values()]
788
+ return Array.isArray(reads) ? reads : []
789
+ }
790
+
791
+ /**
792
+ * 「最近读取」= 所有成功 read 里 `lastRead.seq` 最大的那一篇。
793
+ *
794
+ * seq 才是真相(墙钟只用来显示相对时间);seq 相同时取 `lastRead.at` 较大者,
795
+ * 保证同样是确定性的。**不建立第二份 read history**,完全从现有 entry 派生。
796
+ *
797
+ * @param {Map<string, object>|object[]} reads - 读证据
798
+ * @returns {{rel: string, at: number, seq: number, epochId: number|null, tier: string|null, rank: number|null, inside: boolean}|null} 最近读取
799
+ */
800
+ export function latestReadOf(reads) {
801
+ let best = null
802
+ for (const entry of readEntries(reads)) {
803
+ if (!entry || !entry.lastRead || !(entry.count > 0)) continue
804
+ if (!best
805
+ || entry.lastRead.seq > best.lastRead.seq
806
+ || (entry.lastRead.seq === best.lastRead.seq && entry.lastRead.at > best.lastRead.at)) {
807
+ best = entry
808
+ }
809
+ }
810
+ if (!best) return null
811
+ return {
812
+ rel: best.rel,
813
+ at: best.lastRead.at,
814
+ seq: best.lastRead.seq,
815
+ epochId: Number.isInteger(best.lastRead.epochId) ? best.lastRead.epochId : null,
816
+ tier: best.lastRead.tier || null,
817
+ rank: Number.isInteger(best.lastRead.rank) ? best.lastRead.rank : null,
818
+ inside: !!best.lastRead.inside,
819
+ }
820
+ }
821
+
822
+ /**
823
+ * 「当前包外、且真实成功读取过」的文档明细。
824
+ *
825
+ * ⚠️ 与 v0.16 的 `stats.outside` / `stats.outsideReads` **语义不同,两个都要留**:
826
+ * 那个是**历史层**(至少有一次读发生在当时的包外,永不重算),
827
+ * 这个是**当前层**(这篇文档不在**当前**包内,但被读过)—— 当前包变了它就变。
828
+ *
829
+ * @param {Map<string, object>|object[]} reads - 读证据
830
+ * @param {Array<{rel: string}>} items - 当前快照的扁平条目
831
+ * @returns {Array<{rel: string, count: number, lastReadAt: number, seq: number}>} 包外明细(按首次读的 seq 升序)
832
+ */
833
+ export function outsideDocsOf(reads, items) {
834
+ const inside = new Set()
835
+ for (const item of Array.isArray(items) ? items : []) {
836
+ if (item && typeof item.rel === 'string' && item.rel) inside.add(item.rel)
837
+ }
838
+ const rows = []
839
+ for (const entry of readEntries(reads)) {
840
+ if (!entry || !entry.rel || !(entry.count > 0) || inside.has(entry.rel)) continue
841
+ if (!entry.firstRead || !entry.lastRead) continue
842
+ rows.push({
843
+ rel: entry.rel,
844
+ count: entry.count,
845
+ lastReadAt: entry.lastRead.at,
846
+ seq: entry.firstRead.seq,
847
+ })
848
+ }
849
+ // 阅读顺序(首次读的 seq),同 seq 用 rel 兜底 —— 不用 localeCompare(它依赖运行环境)
850
+ rows.sort((a, b) => (a.seq - b.seq) || (a.rel < b.rel ? -1 : (a.rel > b.rel ? 1 : 0)))
851
+ return rows
852
+ }
853
+
485
854
  /**
486
855
  * 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
487
856
  * @param {object} store - store
488
857
  * @param {string} sessionId - 会话 id
858
+ * @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
489
859
  * @returns {object|null} 使用情况
490
860
  */
491
- export function usageFor(store, sessionId) {
861
+ export function usageFor(store, sessionId, options = {}) {
492
862
  try {
493
863
  const state = store && store.sessions.get(sessionId)
494
864
  if (!state) return null
495
- return usageFrom(state)
865
+ return usageFrom(state, options)
496
866
  } catch {
497
867
  return null
498
868
  }
@@ -501,15 +871,27 @@ export function usageFor(store, sessionId) {
501
871
  /**
502
872
  * 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
503
873
  *
874
+ * 报告分两层,界线是硬的:
875
+ *
876
+ * - **历史层**(`reads[].firstRead/lastRead`、`byTier[].read`、`primaryFollowThrough`、
877
+ * `outside`)—— 全部来自读时冻结的归因,**永不按当前上下文重算**。
878
+ * - **当前层**(`items`、`byTier[].total`、`primaryRel`、`delta`)—— 反映最近一份上下文。
879
+ *
504
880
  * 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
505
- * 上下文变了几次。**没有分数、没有百分比评分、没有「相关性」**。
881
+ * 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
506
882
  *
507
883
  * @param {object} state - 会话状态
884
+ * @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
508
885
  * @returns {object} 使用情况
509
886
  */
510
- export function usageFrom(state) {
887
+ export function usageFrom(state, options = {}) {
511
888
  const snapshots = (state && state.snapshots) || []
512
889
  const snapshot = snapshots[snapshots.length - 1] || null
890
+ // v0.17:当前版本标记。不传 = 拿不到变化证据 = 保守(只有 read / reread_after_update)
891
+ const mtimes = options.mtimes instanceof Map
892
+ ? options.mtimes
893
+ : new Map(Object.entries(options.mtimes || {}))
894
+ const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
513
895
  const byTier = {
514
896
  primary: { total: 0, read: 0 },
515
897
  supporting: { total: 0, read: 0 },
@@ -522,53 +904,115 @@ export function usageFrom(state) {
522
904
  }
523
905
 
524
906
  const reads = []
907
+ // v0.17:lifecycle 是**读证据 + 当前版本标记**的投影,只含有 read 证据的 rel;
908
+ // 没有 entry 的文档不出现在这里(UI 自行落回 unread),免得把整个工作区灌进来。
909
+ const lifecycle = {}
525
910
  for (const entry of state.reads.values()) {
526
- const hit = snapshot ? snapshot.items.find((item) => item.rel === entry.rel) : null
911
+ const currentMtimeMs = mtimes.has(entry.rel) ? mtimes.get(entry.rel) : null
912
+ const life = lifecycleOf(entry, currentMtimeMs)
913
+ lifecycle[entry.rel] = {
914
+ status: life.status,
915
+ count: entry.count,
916
+ lastReadMtimeMs: life.lastReadMtimeMs,
917
+ changedAfterLastRead: life.changedAfterLastRead,
918
+ rereadAfterChange: life.rereadAfterChange,
919
+ lastReadAt: entry.lastRead.at,
920
+ }
527
921
  reads.push({
528
922
  rel: entry.rel,
529
923
  count: entry.count,
530
- firstReadAt: entry.firstReadAt,
531
- firstReadSeq: entry.firstReadSeq,
532
- firstTier: entry.firstTier || null,
533
- tier: hit ? hit.tier : null,
534
- rank: hit ? hit.rank : null,
535
- outside: !hit,
536
- outsideCount: entry.outsideCount || 0,
924
+ firstRead: { ...entry.firstRead },
925
+ lastRead: { ...entry.lastRead },
926
+ // 兼容别名(旧调用方与测试用的字段名):都是**首次读**的归因,历史值
927
+ firstReadAt: entry.firstRead.at,
928
+ firstReadSeq: entry.firstRead.seq,
929
+ firstTier: entry.firstRead.tier,
930
+ lastReadAt: entry.lastRead.at,
931
+ lastTier: entry.lastRead.tier,
932
+ insideReads: entry.insideReads,
933
+ outsideReads: entry.outsideReads,
934
+ outsideCount: entry.outsideReads,
935
+ outside: entry.outsideReads > 0,
936
+ reEntry: !!entry.reEntry,
937
+ continuedReadAfterExit: !!entry.continuedReadAfterExit,
938
+ // ⚠️ `tier`/`rank` 是**首次读时**的层与名次,不是「它现在在哪一层」。
939
+ tier: entry.firstRead.tier,
940
+ rank: entry.firstRead.rank,
537
941
  })
538
942
  }
539
- reads.sort((a, b) => a.firstReadSeq - b.firstReadSeq)
540
- for (const row of reads) if (row.tier && byTier[row.tier]) byTier[row.tier].read += 1
943
+ reads.sort((a, b) => (a.firstRead.seq - b.firstRead.seq) || (a.firstRead.at - b.firstRead.at))
944
+ // 「这一 Epoch 的某一层里,有几篇真的被读过」—— 只认归因落在**当前 Epoch** 的读
945
+ for (const row of reads) {
946
+ if (row.firstRead.epochId === epochId && row.firstRead.inside && byTier[row.firstRead.tier]) {
947
+ byTier[row.firstRead.tier].read += 1
948
+ }
949
+ }
541
950
 
542
- const outside = reads.filter((row) => row.outside)
951
+ const outside = reads.filter((row) => row.outsideReads > 0)
543
952
  const first = reads[0] || null
544
- const primary = snapshot ? snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1) : null
545
- const supportingTotal = byTier.supporting.total
953
+ const epoch = epochIn(state, epochId)
954
+ const primaryRel = epoch && epoch.primary ? epoch.primary.rel : ''
955
+ const continued = reads.filter((row) => row.continuedReadAfterExit)
956
+ const reentries = reads.filter((row) => row.reEntry)
957
+ // 只取 `state.deltas` 的最后一条:与 `delta` 是**同一个对象**的两个引用,永不新建 Delta Store
958
+ const latestDelta = state.deltas[state.deltas.length - 1] || null
959
+ const lastEpochId = Number.isInteger(epochId) ? epochId : 0
960
+ const epochs = (Array.isArray(state.epochs) ? state.epochs : []).map((e) => ({
961
+ epochId: e.epochId,
962
+ snapshotSeq: e.snapshotSeq,
963
+ topic: e.topic,
964
+ task: e.task,
965
+ primary: { rel: e.primary.rel, read: e.primary.read },
966
+ supporting: { total: e.supporting.total, read: e.supporting.read },
967
+ related: { total: e.related.total, read: e.related.read },
968
+ outsideReads: e.outsideReads,
969
+ continuedReadsAfterExit: e.continuedReadsAfterExit,
970
+ reEntries: e.reEntries,
971
+ }))
546
972
 
547
973
  return {
548
974
  at: snapshot ? snapshot.at : 0,
549
975
  seq: snapshot ? snapshot.seq : -1,
976
+ epochId,
550
977
  task: snapshot ? snapshot.task : '',
551
978
  topic: snapshot ? snapshot.topic : '',
552
979
  items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
553
980
  reads,
554
- delta: state.deltas[state.deltas.length - 1] || null,
981
+ // §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
982
+ epochs,
983
+ delta: latestDelta,
984
+ // ── v0.17 的四个新投影(全部是当前层派生物;`stats` 一个键都不动) ──
985
+ // `latestDelta` 与 `delta` 同引用,保证两处永远一致
986
+ latestDelta,
987
+ lifecycle,
988
+ recentRead: latestReadOf(state.reads),
989
+ outsideDocs: outsideDocsOf(state.reads, snapshot ? snapshot.items : []),
555
990
  stats: {
556
991
  reads: reads.reduce((sum, row) => sum + row.count, 0),
557
992
  distinct: reads.length,
558
993
  outside: outside.length,
559
994
  outsideReads: outside.map((row) => row.rel),
560
- firstReadTier: first ? first.tier : null,
995
+ // 第一条成功读落在哪一层:primary / supporting / related / outside / null
996
+ firstReadTier: first ? (first.firstRead.inside ? first.firstRead.tier : 'outside') : null,
561
997
  firstReadRel: first ? first.rel : '',
562
- firstReadAt: first ? first.firstReadAt : 0,
563
- primaryRel: primary ? primary.rel : '',
564
- // 「先看的那篇被读了吗」—— 这不是成功率,只是一次真实的命中
565
- primaryFollowThrough: !!(primary && reads.some((row) => row.rel === primary.rel)),
998
+ firstReadAt: first ? first.firstRead.at : 0,
999
+ firstReadEpoch: first ? first.firstRead.epochId : null,
1000
+ primaryRel,
1001
+ // 「这个 Epoch 先看的那篇被真的读了吗」—— 按 Epoch 归因的布尔,不是成功率
1002
+ primaryFollowThrough: !!(epoch && epoch.primary && epoch.primary.read),
566
1003
  byTier,
567
- supportingCoverage: supportingTotal === 0 ? null : byTier.supporting.read / supportingTotal,
1004
+ supportingCoverage: byTier.supporting.total === 0 ? null : byTier.supporting.read / byTier.supporting.total,
1005
+ // 事实计数(不是「Agent 不认可新上下文」这种解释)
1006
+ continuedReadsAfterExit: continued.length,
1007
+ reEntries: reentries.length,
568
1008
  churn: {
569
- // 累计变过几次(不受 Delta 数组上限影响)
570
- snapshots: state.churn.changes,
571
- deltas: state.churn.changes,
1009
+ // 观察到的**不同 Epoch 数**(= 最后一份 Epoch 的编号;被淘汰的也算过)
1010
+ epochs: lastEpochId,
1011
+ // 变化次数 = 换过几次上下文(第一份不算变化)
1012
+ changes: lastEpochId > 0 ? lastEpochId - 1 : 0,
1013
+ // ⚠️ `snapshots` 是客户端已经在用的键名(`usage.changes` 文案),保留它 = 变化次数
1014
+ snapshots: lastEpochId > 0 ? lastEpochId - 1 : 0,
1015
+ deltas: lastEpochId > 0 ? lastEpochId - 1 : 0,
572
1016
  // 手上还留着几条 Delta 明细
573
1017
  retained: state.deltas.length,
574
1018
  appeared: state.churn.appeared,
@@ -594,7 +1038,10 @@ export function auditPayload(usage) {
594
1038
  supportingRead: s.byTier.supporting.read,
595
1039
  supportingTotal: s.byTier.supporting.total,
596
1040
  readsOutside: s.outside,
597
- contextChanges: s.churn.deltas,
1041
+ contextChanges: s.churn.changes,
1042
+ epochs: s.churn.epochs,
1043
+ continuedReadsAfterExit: s.continuedReadsAfterExit,
1044
+ reEntries: s.reEntries,
598
1045
  }
599
1046
  }
600
1047