dsh-knit 0.15.0 → 0.16.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,30 @@
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
+ * 前缀事件也算进来。代价是:订阅之前发生的事件不回溯,只记订阅之后真实发生的读。
21
25
  *
22
26
  * 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
23
- * memory 写入。Usage 不是分数。
27
+ * quality score、memory 写入。Usage 不是分数,是计数与事实。
24
28
  *
25
29
  * @module feedback
26
30
  */
@@ -30,10 +34,15 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
30
34
  export const MAX_SESSIONS = 24
31
35
  /** 每个会话最多记多少篇**读过**的文档。 */
32
36
  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
37
+ /** 每个会话最多保留几份 Snapshot / Epoch。
38
+ *
39
+ * v0.16 由 2 提到 20:归因本身**在 Read 时结算**,保留数量不影响它的正确性;
40
+ * 它只决定 `continuedReadAfterExit` / `reEntry` 这两个事实能回溯多远
41
+ * (要能看见「离开过、又回来」就必须留着中间那几份)。
42
+ */
43
+ export const MAX_SNAPSHOTS_PER_SESSION = 20
44
+ /** 每个会话最多保留多少条 Delta 明细(计数不受它影响)。 */
45
+ export const MAX_DELTAS_PER_SESSION = 50
37
46
  /** 最多同时挂起多少个「已调用、还没结果」的 read。 */
38
47
  export const MAX_PENDING_CALLS = 64
39
48
 
@@ -134,7 +143,7 @@ function signatureOf(items, task) {
134
143
  *
135
144
  * @param {object|null} prev - 上一份 Snapshot
136
145
  * @param {object|null} next - 这一份 Snapshot
137
- * @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, stable: boolean}} 差异
146
+ * @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, fromEpoch: number|null, toEpoch: number|null, stable: boolean}} 差异
138
147
  */
139
148
  export function diffContext(prev, next) {
140
149
  const before = indexOf(prev)
@@ -158,6 +167,9 @@ export function diffContext(prev, next) {
158
167
  disappeared,
159
168
  moved,
160
169
  taskChanged,
170
+ // 哪两个 Epoch 之间的变化(没有上一份时 fromEpoch 为 null)
171
+ fromEpoch: prev && Number.isInteger(prev.epochId) ? prev.epochId : null,
172
+ toEpoch: next && Number.isInteger(next.epochId) ? next.epochId : null,
161
173
  stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
162
174
  }
163
175
  }
@@ -188,7 +200,7 @@ function indexOf(snapshot) {
188
200
  *
189
201
  * 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
190
202
  *
191
- * @param {object[]} events - `session.snapshotEvents()` 的产物
203
+ * @param {object[]} events - 会话事件(v0.16 起由 `session/event` 订阅逐条喂进来)
192
204
  * @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
193
205
  * @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
194
206
  */
@@ -264,7 +276,6 @@ function parseArguments(raw) {
264
276
  return {}
265
277
  }
266
278
  }
267
-
268
279
  /* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
269
280
 
270
281
  /**
@@ -276,7 +287,7 @@ export function createStore() {
276
287
  }
277
288
 
278
289
  /**
279
- * 标记这个会话「被审计了」—— 之后它的面板请求才会被记账。
290
+ * 标记这个会话「被审计了」—— 之后它的读事件与面板请求才会被记账。
280
291
  *
281
292
  * 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
282
293
  * 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
@@ -302,7 +313,8 @@ export function activateAudit(store, sessionId) {
302
313
  }
303
314
 
304
315
  /**
305
- * 这个会话是否在记账。
316
+ * 这个会话是否在记账。**订阅回调的第一行就用它早退** ——
317
+ * 没记账的会话一次 Map 查找就返回,不做任何别的工作。
306
318
  * @param {object} store - store
307
319
  * @param {string} sessionId - 会话 id
308
320
  * @returns {boolean} 是否记账
@@ -321,15 +333,16 @@ function stateOf(store, sessionId) {
321
333
  let state = store.sessions.get(sessionId)
322
334
  if (!state) {
323
335
  state = {
324
- seq: -1, // 已消费到的事件 seq(幂等游标)
336
+ seq: -1, // 已消费到的事件 seq(幂等游标;也是「当前水位」)
325
337
  pending: new Map(), // 已调用、还没结果的 read
326
- snapshots: [], // 最近两份 Context Pack
338
+ snapshots: [], // 最近 MAX_SNAPSHOTS_PER_SESSION 份 Context Pack(每份 = 一个 Epoch)
339
+ epochs: [], // 与 snapshots 一一对应的 Epoch 级计数
327
340
  deltas: [], // 最近若干条变化
328
- reads: new Map(), // rel → 计数
341
+ reads: new Map(), // rel → 冻结的读归因
329
342
  readOrder: [], // rel 的插入顺序(淘汰用)
330
- // ⚠️ `changes` 是**累计**的上下文替换次数,与 `deltas` 数组的长度无关 ——
331
- // 数组会被上限砍掉,但「这个会话里上下文变过几次」不能被砍(那正是 churn 这个指标)。
332
- churn: { changes: 0, appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
343
+ // ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
344
+ // 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
345
+ churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
333
346
  }
334
347
  store.sessions.set(sessionId, state)
335
348
  }
@@ -346,9 +359,12 @@ function stateOf(store, sessionId) {
346
359
  /* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
347
360
 
348
361
  /**
349
- * 把一批会话事件喂进去,抽出 read 并记账。
362
+ * 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
363
+ *
364
+ * v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
365
+ * 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
350
366
  *
351
- * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败(规格 §33)。
367
+ * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
352
368
  *
353
369
  * @param {object} store - store
354
370
  * @param {string} sessionId - 会话 id
@@ -380,6 +396,9 @@ export function ingestEvents(store, sessionId, events, options = {}) {
380
396
  * 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
381
397
  * 同一份上下文记成几十份,Delta churn 立刻变成噪音。
382
398
  *
399
+ * `meta.seq` 省略时用会话当前的**事件水位**(`state.seq`)—— 也就是「交包这一刻,
400
+ * 已经发生到第几个事件」。这正是历史归因要的边界:seq ≤ 它的读算在这份包里。
401
+ *
383
402
  * @param {object} store - store
384
403
  * @param {string} sessionId - 会话 id
385
404
  * @param {object} pack - Context Pack
@@ -390,24 +409,34 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
390
409
  try {
391
410
  if (!store || !sessionId || !pack) return null
392
411
  const state = stateOf(store, sessionId)
393
- const next = snapshotOf(pack, meta)
412
+ const next = snapshotOf(pack, {
413
+ seq: Number.isInteger(meta.seq) ? meta.seq : state.seq,
414
+ at: meta.at,
415
+ })
394
416
  const prev = state.snapshots[state.snapshots.length - 1] || null
395
417
 
396
418
  if (prev && prev.sig === next.sig) {
397
419
  if (next.at > prev.at) prev.at = next.at
398
420
  if (next.seq > prev.seq) prev.seq = next.seq
421
+ const epoch = epochIn(state, prev.epochId)
422
+ if (epoch && prev.seq > epoch.snapshotSeq) epoch.snapshotSeq = prev.seq
399
423
  return null
400
424
  }
401
425
 
426
+ // Epoch 编号从这里发出:新建一份上下文 = 一个新 Epoch。同签名不算新 Epoch。
427
+ next.epochId = prev && Number.isInteger(prev.epochId) ? prev.epochId + 1 : 1
402
428
  state.snapshots.push(next)
403
- while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) state.snapshots.shift()
429
+ state.epochs.push(createEpoch(next))
430
+ while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) {
431
+ state.snapshots.shift()
432
+ state.epochs.shift()
433
+ }
404
434
 
405
435
  let delta = null
406
436
  if (prev) {
407
437
  delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
408
438
  state.deltas.push(delta)
409
439
  while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
410
- state.churn.changes += 1
411
440
  state.churn.appeared += delta.appeared.length
412
441
  state.churn.disappeared += delta.disappeared.length
413
442
  state.churn.moved += delta.moved.length
@@ -420,68 +449,205 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
420
449
  }
421
450
 
422
451
  /**
423
- * 记一次真实读。**不属于任何快照的读 = outside context**(这不是错,是信息)。
452
+ * 给一个新 Epoch 建计数骨架(总量取自这份快照,已读量靠后续 read 累加)。
453
+ * @param {object} snapshot - 刚记下的快照(已带 epochId)
454
+ * @returns {object} Epoch 记录
455
+ */
456
+ function createEpoch(snapshot) {
457
+ const counts = {
458
+ primary: { total: 0, read: 0 },
459
+ supporting: { total: 0, read: 0 },
460
+ related: { total: 0, read: 0 },
461
+ }
462
+ for (const item of snapshot.items) {
463
+ const bucket = counts[item.tier]
464
+ if (bucket) bucket.total += 1
465
+ }
466
+ const primary = snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1)
467
+ return {
468
+ epochId: snapshot.epochId,
469
+ snapshotSeq: snapshot.seq,
470
+ topic: snapshot.topic,
471
+ task: snapshot.task,
472
+ primary: { rel: primary ? primary.rel : '', read: false },
473
+ supporting: counts.supporting,
474
+ related: counts.related,
475
+ outsideReads: 0,
476
+ continuedReadsAfterExit: 0,
477
+ reEntries: 0,
478
+ seen: new Set(), // 本 Epoch 里已经计过「读」的 `层:rel`(导出前会剥掉)
479
+ }
480
+ }
481
+
482
+ /**
483
+ * 按 epochId 找 Epoch 记录。找不到返回 null(早于任何快照的读就是这种)。
484
+ * @param {object} state - 会话状态
485
+ * @param {number|null} epochId - Epoch 编号
486
+ * @returns {object|null} Epoch 记录
487
+ */
488
+ function epochIn(state, epochId) {
489
+ const list = state && Array.isArray(state.epochs) ? state.epochs : []
490
+ if (!Number.isInteger(epochId)) return null
491
+ for (let i = list.length - 1; i >= 0; i -= 1) {
492
+ if (list[i].epochId === epochId) return list[i]
493
+ }
494
+ return null
495
+ }
496
+
497
+ /**
498
+ * 记一次真实读。**归因在这一次调用里就结算并冻结**,之后不再重算。
499
+ * 不属于任何快照的读 = outside context(这不是错,是信息)。
424
500
  * @param {object} state - 会话状态
425
501
  * @param {object} read - 归一化后的 read 证据
426
502
  */
427
503
  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
504
+ const at = snapshotAt(state.snapshots, read.seq)
505
+ const attribution = attributeRead(at, read.rel)
506
+ const facts = attributeReadFacts(state.snapshots, read.rel, read.seq)
507
+ const point = {
508
+ seq: read.seq,
509
+ at: read.time,
510
+ snapshotSeq: attribution.snapshotSeq,
511
+ epochId: attribution.epochId,
512
+ tier: attribution.tierAtRead,
513
+ rank: attribution.rankAtRead,
514
+ inside: attribution.insideAtRead,
515
+ }
433
516
 
434
517
  let entry = state.reads.get(read.rel)
435
518
  if (!entry) {
436
519
  entry = {
437
520
  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,
521
+ count: 0,
522
+ firstRead: { ...point },
523
+ lastRead: { ...point },
524
+ insideReads: 0,
525
+ outsideReads: 0,
526
+ primaryReads: 0,
527
+ supportingReads: 0,
528
+ relatedReads: 0,
529
+ reEntry: false,
530
+ continuedReadAfterExit: false,
447
531
  }
448
532
  state.reads.set(read.rel, entry)
449
533
  state.readOrder.push(read.rel)
450
534
  while (state.readOrder.length > MAX_READS_PER_SESSION) {
451
535
  state.reads.delete(state.readOrder.shift())
452
536
  }
453
- return
454
537
  }
455
538
 
456
539
  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
540
+ // 「第一次读」按**事件 seq** 认(seq 才是真相,墙钟只用来显示)
541
+ if (read.seq < entry.firstRead.seq || (read.seq === entry.firstRead.seq && read.time < entry.firstRead.at)) {
542
+ entry.firstRead = { ...point }
543
+ }
544
+ if (read.seq > entry.lastRead.seq || (read.seq === entry.lastRead.seq && read.time >= entry.lastRead.at)) {
545
+ entry.lastRead = { ...point }
546
+ }
547
+ if (attribution.insideAtRead) entry.insideReads += 1
548
+ else entry.outsideReads += 1
549
+ if (attribution.tierAtRead === 'primary') entry.primaryReads += 1
550
+ else if (attribution.tierAtRead === 'supporting') entry.supportingReads += 1
551
+ else if (attribution.tierAtRead === 'related') entry.relatedReads += 1
552
+ if (facts.continuedReadAfterExit) entry.continuedReadAfterExit = true
553
+ if (facts.reEntry) entry.reEntry = true
554
+
555
+ const epoch = epochIn(state, attribution.epochId)
556
+ if (epoch) {
557
+ if (!attribution.insideAtRead) epoch.outsideReads += 1
558
+ if (facts.continuedReadAfterExit) epoch.continuedReadsAfterExit += 1
559
+ if (facts.reEntry) epoch.reEntries += 1
560
+ if (attribution.insideAtRead && attribution.tierAtRead) {
561
+ const key = `${attribution.tierAtRead}:${read.rel}`
562
+ if (!epoch.seen.has(key)) {
563
+ epoch.seen.add(key)
564
+ const bucket = epoch[attribution.tierAtRead]
565
+ if (bucket) bucket.read += 1
566
+ }
567
+ if (attribution.tierAtRead === 'primary' && epoch.primary.rel === read.rel) epoch.primary.read = true
568
+ }
468
569
  }
469
570
  }
470
571
 
471
572
  /**
472
573
  * 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
473
574
  * 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
575
+ *
576
+ * 这是 runtime 与离线回放到共用的**同一个纯函数**:两边「规则一致」靠它,
577
+ * 而不是靠两边的数字恰好相等(交付时刻不可观测,数字本来就不可能相等)。
578
+ *
474
579
  * @param {object[]} snapshots - 快照栈
475
580
  * @param {number} seq - 读的 seq
476
581
  * @returns {object|null} 快照
477
582
  */
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]
583
+ export function snapshotAt(snapshots, seq) {
584
+ const list = Array.isArray(snapshots) ? snapshots : []
585
+ for (let i = list.length - 1; i >= 0; i -= 1) {
586
+ if (list[i].seq <= seq) return list[i]
481
587
  }
482
588
  return null
483
589
  }
484
590
 
591
+ /**
592
+ * 把「这次读」钉到一份快照上 —— 输出的是**读那一刻**的事实,不是当前视图。
593
+ * @param {object|null} snapshot - 读那一刻生效的快照(`snapshotAt()` 的结果)
594
+ * @param {string} rel - 归一化后的路径
595
+ * @returns {{snapshotSeq: number|null, epochId: number|null, tierAtRead: string|null, rankAtRead: number|null, insideAtRead: boolean}} 归因
596
+ */
597
+ export function attributeRead(snapshot, rel) {
598
+ if (!snapshot || !Array.isArray(snapshot.items)) {
599
+ return { snapshotSeq: null, epochId: null, tierAtRead: null, rankAtRead: null, insideAtRead: false }
600
+ }
601
+ const hit = snapshot.items.find((item) => item.rel === rel)
602
+ return {
603
+ snapshotSeq: Number.isInteger(snapshot.seq) ? snapshot.seq : null,
604
+ epochId: Number.isInteger(snapshot.epochId) ? snapshot.epochId : null,
605
+ tierAtRead: hit ? hit.tier : null,
606
+ rankAtRead: hit ? hit.rank : null,
607
+ insideAtRead: !!hit,
608
+ }
609
+ }
610
+
611
+ /**
612
+ * 推导两个**事实**字段(规格 §12 / §13),只用保留窗口内的快照:
613
+ *
614
+ * - `continuedReadAfterExit`:这次读**在当时那份快照之外**,但更早的某份快照里有这篇
615
+ * ⇒ 「离开上下文之后它仍然被读了」。
616
+ * - `reEntry`:这次读**在当时那份快照之内**,更早的某份快照里也有过,但中间至少有一份
617
+ * 快照里没有它 ⇒ 「离开过,又回来了,而且回来之后被读了」。
618
+ *
619
+ * ⚠️ 这两个字段只是**事实**。它们**不许**被解释成「Agent 不认可新上下文」
620
+ * —— 那是推断,不在这个模块的职责里(规格 §5 Evidence Over Interpretation)。
621
+ *
622
+ * 只在保留窗口内推导:宁可漏记,也不猜。
623
+ *
624
+ * @param {object[]} snapshots - 快照栈
625
+ * @param {string} rel - 归一化后的路径
626
+ * @param {number} readSeq - 这次读的 seq
627
+ * @returns {{continuedReadAfterExit: boolean, reEntry: boolean}} 两个事实
628
+ */
629
+ export function attributeReadFacts(snapshots, rel, readSeq) {
630
+ const list = Array.isArray(snapshots) ? snapshots : []
631
+ const empty = { continuedReadAfterExit: false, reEntry: false }
632
+ const at = snapshotAt(list, readSeq)
633
+ if (!at) return empty
634
+ const atIndex = list.indexOf(at)
635
+ if (atIndex < 0) return empty
636
+
637
+ const insideNow = at.items.some((item) => item.rel === rel)
638
+ let sawInside = false
639
+ let sawGapAfterInside = false
640
+ for (let i = 0; i < atIndex; i += 1) {
641
+ const has = list[i].items.some((item) => item.rel === rel)
642
+ if (has) sawInside = true
643
+ else if (sawInside) sawGapAfterInside = true
644
+ }
645
+ // 更早的窗口里从来没有过它 —— 那这次既不是「继续读」也不是「重新进入」
646
+ if (!sawInside) return empty
647
+ if (insideNow) return { continuedReadAfterExit: false, reEntry: sawGapAfterInside }
648
+ return { continuedReadAfterExit: true, reEntry: false }
649
+ }
650
+
485
651
  /**
486
652
  * 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
487
653
  * @param {object} store - store
@@ -501,8 +667,14 @@ export function usageFor(store, sessionId) {
501
667
  /**
502
668
  * 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
503
669
  *
670
+ * 报告分两层,界线是硬的:
671
+ *
672
+ * - **历史层**(`reads[].firstRead/lastRead`、`byTier[].read`、`primaryFollowThrough`、
673
+ * `outside`)—— 全部来自读时冻结的归因,**永不按当前上下文重算**。
674
+ * - **当前层**(`items`、`byTier[].total`、`primaryRel`、`delta`)—— 反映最近一份上下文。
675
+ *
504
676
  * 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
505
- * 上下文变了几次。**没有分数、没有百分比评分、没有「相关性」**。
677
+ * 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
506
678
  *
507
679
  * @param {object} state - 会话状态
508
680
  * @returns {object} 使用情况
@@ -510,6 +682,7 @@ export function usageFor(store, sessionId) {
510
682
  export function usageFrom(state) {
511
683
  const snapshots = (state && state.snapshots) || []
512
684
  const snapshot = snapshots[snapshots.length - 1] || null
685
+ const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
513
686
  const byTier = {
514
687
  primary: { total: 0, read: 0 },
515
688
  supporting: { total: 0, read: 0 },
@@ -523,52 +696,93 @@ export function usageFrom(state) {
523
696
 
524
697
  const reads = []
525
698
  for (const entry of state.reads.values()) {
526
- const hit = snapshot ? snapshot.items.find((item) => item.rel === entry.rel) : null
527
699
  reads.push({
528
700
  rel: entry.rel,
529
701
  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,
702
+ firstRead: { ...entry.firstRead },
703
+ lastRead: { ...entry.lastRead },
704
+ // 兼容别名(旧调用方与测试用的字段名):都是**首次读**的归因,历史值
705
+ firstReadAt: entry.firstRead.at,
706
+ firstReadSeq: entry.firstRead.seq,
707
+ firstTier: entry.firstRead.tier,
708
+ lastReadAt: entry.lastRead.at,
709
+ lastTier: entry.lastRead.tier,
710
+ insideReads: entry.insideReads,
711
+ outsideReads: entry.outsideReads,
712
+ outsideCount: entry.outsideReads,
713
+ outside: entry.outsideReads > 0,
714
+ reEntry: !!entry.reEntry,
715
+ continuedReadAfterExit: !!entry.continuedReadAfterExit,
716
+ // ⚠️ `tier`/`rank` 是**首次读时**的层与名次,不是「它现在在哪一层」。
717
+ tier: entry.firstRead.tier,
718
+ rank: entry.firstRead.rank,
537
719
  })
538
720
  }
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
721
+ reads.sort((a, b) => (a.firstRead.seq - b.firstRead.seq) || (a.firstRead.at - b.firstRead.at))
722
+ // 「这一 Epoch 的某一层里,有几篇真的被读过」—— 只认归因落在**当前 Epoch** 的读
723
+ for (const row of reads) {
724
+ if (row.firstRead.epochId === epochId && row.firstRead.inside && byTier[row.firstRead.tier]) {
725
+ byTier[row.firstRead.tier].read += 1
726
+ }
727
+ }
541
728
 
542
- const outside = reads.filter((row) => row.outside)
729
+ const outside = reads.filter((row) => row.outsideReads > 0)
543
730
  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
731
+ const epoch = epochIn(state, epochId)
732
+ const primaryRel = epoch && epoch.primary ? epoch.primary.rel : ''
733
+ const continued = reads.filter((row) => row.continuedReadAfterExit)
734
+ const reentries = reads.filter((row) => row.reEntry)
735
+ const lastEpochId = Number.isInteger(epochId) ? epochId : 0
736
+ const epochs = (Array.isArray(state.epochs) ? state.epochs : []).map((e) => ({
737
+ epochId: e.epochId,
738
+ snapshotSeq: e.snapshotSeq,
739
+ topic: e.topic,
740
+ task: e.task,
741
+ primary: { rel: e.primary.rel, read: e.primary.read },
742
+ supporting: { total: e.supporting.total, read: e.supporting.read },
743
+ related: { total: e.related.total, read: e.related.read },
744
+ outsideReads: e.outsideReads,
745
+ continuedReadsAfterExit: e.continuedReadsAfterExit,
746
+ reEntries: e.reEntries,
747
+ }))
546
748
 
547
749
  return {
548
750
  at: snapshot ? snapshot.at : 0,
549
751
  seq: snapshot ? snapshot.seq : -1,
752
+ epochId,
550
753
  task: snapshot ? snapshot.task : '',
551
754
  topic: snapshot ? snapshot.topic : '',
552
755
  items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
553
756
  reads,
757
+ // §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
758
+ epochs,
554
759
  delta: state.deltas[state.deltas.length - 1] || null,
555
760
  stats: {
556
761
  reads: reads.reduce((sum, row) => sum + row.count, 0),
557
762
  distinct: reads.length,
558
763
  outside: outside.length,
559
764
  outsideReads: outside.map((row) => row.rel),
560
- firstReadTier: first ? first.tier : null,
765
+ // 第一条成功读落在哪一层:primary / supporting / related / outside / null
766
+ firstReadTier: first ? (first.firstRead.inside ? first.firstRead.tier : 'outside') : null,
561
767
  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)),
768
+ firstReadAt: first ? first.firstRead.at : 0,
769
+ firstReadEpoch: first ? first.firstRead.epochId : null,
770
+ primaryRel,
771
+ // 「这个 Epoch 先看的那篇被真的读了吗」—— 按 Epoch 归因的布尔,不是成功率
772
+ primaryFollowThrough: !!(epoch && epoch.primary && epoch.primary.read),
566
773
  byTier,
567
- supportingCoverage: supportingTotal === 0 ? null : byTier.supporting.read / supportingTotal,
774
+ supportingCoverage: byTier.supporting.total === 0 ? null : byTier.supporting.read / byTier.supporting.total,
775
+ // 事实计数(不是「Agent 不认可新上下文」这种解释)
776
+ continuedReadsAfterExit: continued.length,
777
+ reEntries: reentries.length,
568
778
  churn: {
569
- // 累计变过几次(不受 Delta 数组上限影响)
570
- snapshots: state.churn.changes,
571
- deltas: state.churn.changes,
779
+ // 观察到的**不同 Epoch 数**(= 最后一份 Epoch 的编号;被淘汰的也算过)
780
+ epochs: lastEpochId,
781
+ // 变化次数 = 换过几次上下文(第一份不算变化)
782
+ changes: lastEpochId > 0 ? lastEpochId - 1 : 0,
783
+ // ⚠️ `snapshots` 是客户端已经在用的键名(`usage.changes` 文案),保留它 = 变化次数
784
+ snapshots: lastEpochId > 0 ? lastEpochId - 1 : 0,
785
+ deltas: lastEpochId > 0 ? lastEpochId - 1 : 0,
572
786
  // 手上还留着几条 Delta 明细
573
787
  retained: state.deltas.length,
574
788
  appeared: state.churn.appeared,
@@ -594,7 +808,10 @@ export function auditPayload(usage) {
594
808
  supportingRead: s.byTier.supporting.read,
595
809
  supportingTotal: s.byTier.supporting.total,
596
810
  readsOutside: s.outside,
597
- contextChanges: s.churn.deltas,
811
+ contextChanges: s.churn.changes,
812
+ epochs: s.churn.epochs,
813
+ continuedReadsAfterExit: s.continuedReadsAfterExit,
814
+ reEntries: s.reEntries,
598
815
  }
599
816
  }
600
817