dsh-knit 0.14.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.
@@ -0,0 +1,322 @@
1
+ /**
2
+ * Knit v0.15 · **Context Snapshot / Delta / Usage 的行为测试**
3
+ *
4
+ * 这里测的是「Knit 把上下文交出去之后,到底发生了什么」——
5
+ * Context Snapshot(交出去那一刻的三层排序)· Context Delta(两次之间谁进谁出)
6
+ * · Usage(某次真实的读落在哪一层)。
7
+ *
8
+ * 六条纪律,每一条都对应一组用例:
9
+ * 1. **无变化不记新快照** —— 否则 5 秒轮询会把同一份上下文记成几十份,Delta churn 全是噪音;
10
+ * 2. **游标幂等** —— 同一批事件喂两遍,读只算一遍;
11
+ * 3. **会话隔离** —— A 会话的读不许进 B 会话的报告;
12
+ * 4. **内存有上限** —— 会话数 / 读过的篇数 / Delta 条数都有硬上限(LRU);
13
+ * 5. **失败降级** —— store 给错了、事件是 null、pack 是 undefined,都不许抛,只返回空结果;
14
+ * 6. **没有分数** —— Usage 里只有计数与事实(`primaryFollowThrough` 是布尔,不是成功率)。
15
+ */
16
+ import test from 'node:test'
17
+ import assert from 'node:assert/strict'
18
+
19
+ import {
20
+ createStore, activateAudit, isAudited, ingestEvents, noteSnapshot, usageFor, usageFrom,
21
+ auditPayload, getAuditSummary, resetStore,
22
+ MAX_SESSIONS, MAX_READS_PER_SESSION, MAX_DELTAS_PER_SESSION,
23
+ } from '../src/host/feedback.js'
24
+
25
+ const ROOT = '/w'
26
+
27
+ /** 造一份 Context Pack(只给测试要用的字段)。 */
28
+ function pack(options = {}) {
29
+ const rows = (list) => (list || []).map((rel) => ({ rel }))
30
+ return {
31
+ mode: 'relevance',
32
+ topic: options.topic || 'knit',
33
+ task: options.task || '',
34
+ primary: rows(options.primary),
35
+ supporting: rows(options.supporting),
36
+ related: rows(options.related),
37
+ totals: { matched: 0, total: Number.isInteger(options.total) ? options.total : 10 },
38
+ }
39
+ }
40
+
41
+ /** 造一批 read 事件:`pairs` 是 `[rel, seq]`。 */
42
+ function readEvents(pairs, startSeq = 100) {
43
+ const events = []
44
+ let seq = startSeq
45
+ for (const [rel, at] of pairs) {
46
+ const callId = `c${seq}`
47
+ events.push({
48
+ type: 'tool/call',
49
+ seq,
50
+ time: (at || seq) * 1,
51
+ data: { turn: 1, step: 1, callId, name: 'read', arguments: JSON.stringify({ file_path: rel }) },
52
+ })
53
+ seq += 1
54
+ events.push({
55
+ type: 'tool/result',
56
+ seq,
57
+ time: (at || seq) * 1,
58
+ data: { message: { role: 'tool', toolCallId: callId, source: { kind: 'tool', callId }, isError: false } },
59
+ })
60
+ seq += 1
61
+ }
62
+ return events
63
+ }
64
+
65
+ test('快照:第一次交出去只记快照,没有 Delta', () => {
66
+ const store = createStore()
67
+ const first = noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md'] }), { seq: 5, at: 100 })
68
+ assert.ok(first.snapshot)
69
+ assert.equal(first.delta, null)
70
+ const usage = usageFor(store, 's1')
71
+ assert.equal(usage.items.length, 2)
72
+ assert.equal(usage.stats.churn.deltas, 0)
73
+ })
74
+
75
+ test('快照:内容完全相同就不记新快照(否则轮询会灌进几十份)', () => {
76
+ const store = createStore()
77
+ const p = pack({ primary: ['a.md'], supporting: ['b.md'], related: ['c.md'] })
78
+ noteSnapshot(store, 's1', p, { seq: 5, at: 100 })
79
+ assert.equal(noteSnapshot(store, 's1', p, { seq: 6, at: 200 }), null)
80
+ assert.equal(noteSnapshot(store, 's1', p, { seq: 7, at: 300 }), null)
81
+ const usage = usageFor(store, 's1')
82
+ assert.equal(usage.stats.churn.deltas, 0)
83
+ // 时间戳要跟着往前推,不能停在第一次
84
+ assert.equal(usage.at, 300)
85
+ assert.equal(usage.seq, 7)
86
+ })
87
+
88
+ test('变化:进 / 出 / 换层都记下来,churn 是累计值', () => {
89
+ const store = createStore()
90
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md'], related: ['c.md'] }), { seq: 5, at: 100 })
91
+ const second = noteSnapshot(store, 's1', pack({ primary: ['b.md'], supporting: ['d.md'], related: [] }), { seq: 20, at: 200 })
92
+ assert.deepEqual(second.delta.appeared.map((x) => x.rel), ['d.md'])
93
+ assert.deepEqual(second.delta.disappeared.map((x) => x.rel), ['a.md', 'c.md'])
94
+ assert.deepEqual(second.delta.moved.map((x) => x.rel), ['b.md'])
95
+
96
+ const usage = usageFor(store, 's1')
97
+ assert.equal(usage.stats.churn.deltas, 1)
98
+ assert.equal(usage.stats.churn.appeared, 1)
99
+ assert.equal(usage.stats.churn.disappeared, 2)
100
+ assert.equal(usage.stats.churn.moved, 1)
101
+ assert.deepEqual(usage.delta.appeared.map((x) => x.rel), ['d.md'])
102
+ })
103
+
104
+ test('使用情况:读了 Primary 就是 primaryFollowThrough;读的是 Supporting 记进覆盖率', () => {
105
+ const store = createStore()
106
+ activateAudit(store, 's1')
107
+ noteSnapshot(store, 's1', pack({
108
+ primary: ['a.md'], supporting: ['b.md', 'c.md', 'd.md'], related: ['e.md'],
109
+ }), { seq: 5, at: 100 })
110
+
111
+ ingestEvents(store, 's1', readEvents([['a.md', 10], ['b.md', 11]], 100), { root: ROOT })
112
+ const usage = usageFor(store, 's1')
113
+
114
+ assert.equal(usage.stats.primaryRel, 'a.md')
115
+ assert.equal(usage.stats.primaryFollowThrough, true)
116
+ assert.equal(usage.stats.firstReadTier, 'primary')
117
+ assert.equal(usage.stats.firstReadRel, 'a.md')
118
+ assert.deepEqual(usage.stats.byTier.supporting, { total: 3, read: 1 })
119
+ assert.equal(Number(usage.stats.supportingCoverage.toFixed(3)), 0.333)
120
+ assert.equal(usage.stats.outside, 0)
121
+ assert.equal(usage.stats.reads, 2)
122
+ assert.equal(usage.stats.distinct, 2)
123
+ })
124
+
125
+ test('使用情况:快照之外的读如实记成 outside,不解释成「失败」', () => {
126
+ const store = createStore()
127
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'] }), { seq: 5, at: 100 })
128
+ ingestEvents(store, 's1', readEvents([['z.md', 50], ['y.md', 51]], 200), { root: ROOT })
129
+
130
+ const usage = usageFor(store, 's1')
131
+ assert.equal(usage.stats.outside, 2)
132
+ assert.deepEqual(usage.stats.outsideReads.sort(), ['y.md', 'z.md'])
133
+ assert.equal(usage.stats.primaryFollowThrough, false)
134
+ // v0.16:读过但读在包外 ⇒ 'outside'。null 只留给「一次都还没读」
135
+ assert.equal(usage.stats.firstReadTier, 'outside')
136
+ const outside = usage.reads.find((r) => r.rel === 'z.md')
137
+ assert.equal(outside.tier, null)
138
+ assert.equal(outside.outside, true)
139
+ })
140
+
141
+ test('使用情况:Knit 还没给过上下文就自己读了 ⇒ 那一篇算 outside(tier 为 null)', () => {
142
+ const store = createStore()
143
+ activateAudit(store, 's1')
144
+ ingestEvents(store, 's1', readEvents([['a.md', 10]], 100), { root: ROOT })
145
+ const usage = usageFor(store, 's1')
146
+ assert.equal(usage.stats.outside, 1)
147
+ // 一份快照都没给过 ⇒ 那一读只能算包外
148
+ assert.equal(usage.stats.firstReadTier, 'outside')
149
+ assert.equal(usage.stats.firstReadEpoch, null)
150
+ assert.equal(usage.stats.primaryFollowThrough, false)
151
+ })
152
+
153
+ test('使用情况:读的时候用的是**当时**那份快照,不是最新那份', () => {
154
+ const store = createStore()
155
+ // 第一份:a.md 在 Primary
156
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md'] }), { seq: 5, at: 100 })
157
+ // 读发生在 seq 150 —— 此时生效的是第一份
158
+ ingestEvents(store, 's1', readEvents([['a.md', 300]], 300), { root: ROOT })
159
+ // 之后上下文换了:a.md 掉到 Related
160
+ noteSnapshot(store, 's1', pack({ supporting: ['b.md'], related: ['a.md'] }), { seq: 400, at: 400 })
161
+
162
+ const usage = usageFor(store, 's1')
163
+ const row = usage.reads.find((r) => r.rel === 'a.md')
164
+ // v0.16:`tier` / `rank` / `outside` 全是**读那一刻**冻结的归因,
165
+ // 因此行上的 `tier` 与 `firstTier` 一致 —— 不许等出报告时再拿最新快照重判。
166
+ assert.equal(row.firstTier, 'primary')
167
+ assert.equal(row.tier, 'primary')
168
+ assert.equal(row.outside, false)
169
+ // 换过上下文 ⇒ 两个 Epoch;那一读只算进**它当时**那个 Epoch 的主看篇
170
+ assert.equal(usage.stats.churn.epochs, 2)
171
+ assert.equal(usage.epochs.length, 2)
172
+ assert.equal(usage.epochs[0].primary.read, true)
173
+ assert.equal(usage.epochs[1].primary.read, false)
174
+ })
175
+
176
+ test('幂等:同一批事件喂两遍,读只算一遍', () => {
177
+ const store = createStore()
178
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'] }), { seq: 1, at: 1 })
179
+ const events = readEvents([['a.md', 10]], 100)
180
+ const first = ingestEvents(store, 's1', events, { root: ROOT })
181
+ const second = ingestEvents(store, 's1', events, { root: ROOT })
182
+ assert.equal(first.reads, 1)
183
+ assert.equal(second.reads, 0)
184
+ const usage = usageFor(store, 's1')
185
+ assert.equal(usage.stats.reads, 1)
186
+ assert.equal(usage.reads[0].count, 1)
187
+ })
188
+
189
+ test('幂等:同一篇读两次是 count 2,但仍然只算一个 distinct 篇目', () => {
190
+ const store = createStore()
191
+ noteSnapshot(store, 's1', pack({ supporting: ['b.md'] }), { seq: 1, at: 1 })
192
+ ingestEvents(store, 's1', readEvents([['b.md', 10], ['b.md', 20]], 100), { root: ROOT })
193
+ const usage = usageFor(store, 's1')
194
+ assert.equal(usage.stats.reads, 2)
195
+ assert.equal(usage.stats.distinct, 1)
196
+ assert.equal(usage.reads[0].count, 2)
197
+ assert.deepEqual(usage.stats.byTier.supporting, { total: 1, read: 1 })
198
+ })
199
+
200
+ test('隔离:两个会话各记各的,互不串味', () => {
201
+ const store = createStore()
202
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'] }), { seq: 1, at: 1 })
203
+ noteSnapshot(store, 's2', pack({ primary: ['x.md'] }), { seq: 1, at: 1 })
204
+ ingestEvents(store, 's1', readEvents([['a.md', 10]], 100), { root: ROOT })
205
+
206
+ assert.equal(usageFor(store, 's1').stats.primaryFollowThrough, true)
207
+ assert.equal(usageFor(store, 's2').stats.reads, 0)
208
+ assert.equal(usageFor(store, 's2').stats.primaryFollowThrough, false)
209
+ assert.equal(usageFor(store, 's3'), null)
210
+
211
+ resetStore(store, 's1')
212
+ assert.equal(usageFor(store, 's1'), null)
213
+ assert.ok(usageFor(store, 's2'))
214
+ })
215
+
216
+ test('审计开关:只对主动开启的会话记账(默认不攒数据)', () => {
217
+ const store = createStore()
218
+ assert.equal(isAudited(store, 's1'), false)
219
+ assert.equal(activateAudit(store, 's1'), true)
220
+ assert.equal(isAudited(store, 's1'), true)
221
+ assert.equal(isAudited(store, 's2'), false)
222
+ resetStore(store)
223
+ assert.equal(isAudited(store, 's1'), false)
224
+ })
225
+
226
+ test('内存上限:读过的篇目按 LRU 砍到上限', () => {
227
+ const store = createStore()
228
+ noteSnapshot(store, 's1', pack({ related: [] }), { seq: 1, at: 1 })
229
+ const pairs = []
230
+ for (let i = 0; i < MAX_READS_PER_SESSION + 25; i += 1) pairs.push([`doc${i}.md`, i])
231
+ ingestEvents(store, 's1', readEvents(pairs, 10), { root: ROOT })
232
+
233
+ const usage = usageFor(store, 's1')
234
+ assert.equal(usage.reads.length, MAX_READS_PER_SESSION)
235
+ // 保留的是**最近**读的那批
236
+ assert.equal(usage.reads[usage.reads.length - 1].rel, `doc${MAX_READS_PER_SESSION + 24}.md`)
237
+ assert.equal(usage.reads.find((r) => r.rel === 'doc0.md'), undefined)
238
+ })
239
+
240
+ test('内存上限:会话数超上限时淘汰最久没碰的', () => {
241
+ const store = createStore()
242
+ for (let i = 0; i < MAX_SESSIONS + 3; i += 1) {
243
+ noteSnapshot(store, `s${i}`, pack({ primary: ['a.md'] }), { seq: i, at: i })
244
+ }
245
+ assert.equal(store.sessions.size, MAX_SESSIONS)
246
+ assert.equal(store.sessions.has('s0'), false)
247
+ assert.equal(store.sessions.has(`s${MAX_SESSIONS + 2}`), true)
248
+ })
249
+
250
+ test('内存上限:Delta 只留最近若干条,churn 仍是累计值', () => {
251
+ const store = createStore()
252
+ noteSnapshot(store, 's1', pack({ primary: ['base.md'] }), { seq: 0, at: 0 })
253
+ for (let i = 0; i < MAX_DELTAS_PER_SESSION + 5; i += 1) {
254
+ noteSnapshot(store, 's1', pack({ primary: [`d${i}.md`] }), { seq: i + 1, at: i + 1 })
255
+ }
256
+ const usage = usageFor(store, 's1')
257
+ const changes = MAX_DELTAS_PER_SESSION + 5
258
+ // churn 是**累计**的:明细数组被砍到上限,但「变过几次」不砍
259
+ assert.equal(usage.stats.churn.deltas, changes)
260
+ assert.equal(usage.stats.churn.retained, MAX_DELTAS_PER_SESSION)
261
+ assert.equal(store.sessions.get('s1').deltas.length, MAX_DELTAS_PER_SESSION)
262
+ // 每一次替换都是「进一篇、出一篇」
263
+ assert.equal(usage.stats.churn.appeared, changes)
264
+ assert.equal(usage.stats.churn.disappeared, changes)
265
+ })
266
+
267
+ test('降级:store / 会话 / 事件给错,一律返回空结果,不抛', () => {
268
+ const store = createStore()
269
+ assert.deepEqual(ingestEvents(null, 's1', []), { ok: false, reads: 0, cursor: -1 })
270
+ assert.equal(ingestEvents(store, '', []).ok, false)
271
+ assert.equal(ingestEvents(store, 's1', null).ok, true)
272
+ assert.equal(noteSnapshot(null, 's1', pack()), null)
273
+ assert.equal(noteSnapshot(store, 's1', null), null)
274
+ assert.equal(usageFor(null, 's1'), null)
275
+ assert.equal(usageFor(store, 'nope'), null)
276
+ assert.equal(activateAudit(null, 's1'), false)
277
+ assert.equal(activateAudit(store, ''), false)
278
+ // 坏事件不会把整批作废
279
+ const bad = [null, { type: 'tool/call' }, { type: 'tool/call', seq: 1, data: { name: 'read', callId: 'c', arguments: 'not json' } }]
280
+ assert.equal(ingestEvents(store, 's1', bad).ok, true)
281
+ })
282
+
283
+ test('给 Agent 的摘要:只有事实、没有分数;没可说的就返回空串', () => {
284
+ const store = createStore()
285
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md', 'c.md'] }), { seq: 1, at: 1 })
286
+ ingestEvents(store, 's1', readEvents([['a.md', 10], ['z.md', 11]], 100), { root: ROOT })
287
+
288
+ const usage = usageFor(store, 's1')
289
+ const summary = getAuditSummary(usage)
290
+ assert.match(summary, /primary read \(a\.md\)/)
291
+ assert.match(summary, /supporting 0\/2/)
292
+ assert.match(summary, /1 read outside the pack/)
293
+ assert.doesNotMatch(summary, /%|score|confidence/i)
294
+
295
+ const payload = auditPayload(usage)
296
+ assert.deepEqual(payload, {
297
+ primaryRead: true,
298
+ primaryRel: 'a.md',
299
+ supportingRead: 0,
300
+ supportingTotal: 2,
301
+ readsOutside: 1,
302
+ contextChanges: 0,
303
+ epochs: 1,
304
+ continuedReadsAfterExit: 0,
305
+ reEntries: 0,
306
+ })
307
+ assert.equal(getAuditSummary(null), '')
308
+ assert.equal(auditPayload(null), null)
309
+ })
310
+
311
+ test('Usage 的形状是稳定的(给面板与工具用的字段一个不少)', () => {
312
+ const store = createStore()
313
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md'], related: ['c.md'] }), { seq: 1, at: 1 })
314
+ const usage = usageFrom(store.sessions.get('s1'))
315
+ assert.deepEqual(Object.keys(usage.stats).sort(), [
316
+ 'byTier', 'churn', 'continuedReadsAfterExit', 'distinct', 'firstReadAt', 'firstReadEpoch',
317
+ 'firstReadRel', 'firstReadTier', 'outside', 'outsideReads', 'primaryFollowThrough',
318
+ 'primaryRel', 'reEntries', 'reads', 'supportingCoverage',
319
+ ])
320
+ assert.equal(usage.stats.supportingCoverage, 0)
321
+ assert.equal(usage.stats.churn.snapshots, 0)
322
+ })
@@ -0,0 +1,309 @@
1
+ /**
2
+ * Knit v0.16 · **Context Effectiveness 的行为测试**(SDD §24.3 / §24.4 / §24.5 / §24.6)。
3
+ *
4
+ * 这里只测 v0.15 里**做不到**的那件事:一次读落在哪一层,必须**在读发生的那一刻**结算并冻结,
5
+ * 之后上下文怎么换都不许改口。
6
+ *
7
+ * 1. **历史归因**(§24.3)—— 读发生在 Epoch 1、出报告时已经是 Epoch 2,`tier` / `rank` /
8
+ * `inside` / `epochId` 仍然是 Epoch 1 的值;
9
+ * 2. **持续性**(§24.4)—— 离开上下文之后还读 ⇒ 记成事实 `continuedReadAfterExit`,
10
+ * 不许解释成「Agent 不认可新上下文」;
11
+ * 3. **重新进入**(§24.5)—— 离开过、又回到包里、再读 ⇒ `reEntry`;
12
+ * 4. **规则一致**(§24.6)—— runtime 记下来的归因,逐字段等于拿同一份
13
+ * `(snapshots, reads)` 直接调 `snapshotAt()` + `attributeRead()` 现算的结果。
14
+ * 对齐的是**规则**,不是数字(交付时刻不可观测,见 SDD §3 G4)。
15
+ *
16
+ * ⚠️ 一条纪律:`tier` / `rank` / `outside` 是**首读时**的归因(`firstRead`),
17
+ * 不是「它现在在哪一层」—— 后者根本不存在,那是 Current View ≠ Historical View。
18
+ */
19
+ import test from 'node:test'
20
+ import assert from 'node:assert/strict'
21
+
22
+ import {
23
+ createStore, activateAudit, ingestEvents, noteSnapshot, usageFor, snapshotOf,
24
+ snapshotAt, attributeRead, attributeReadFacts, MAX_SNAPSHOTS_PER_SESSION,
25
+ } from '../src/host/feedback.js'
26
+
27
+ const ROOT = '/w'
28
+
29
+ /** 造一份 Context Pack(只给测试要用的字段)。 */
30
+ function pack(options = {}) {
31
+ const rows = (list) => (list || []).map((rel) => ({ rel }))
32
+ return {
33
+ mode: 'relevance',
34
+ topic: options.topic || 'knit',
35
+ task: options.task || '',
36
+ primary: rows(options.primary),
37
+ supporting: rows(options.supporting),
38
+ related: rows(options.related),
39
+ totals: { matched: 0, total: Number.isInteger(options.total) ? options.total : 10 },
40
+ }
41
+ }
42
+
43
+ /**
44
+ * 一次成功的读 = `tool/call` + `tool/result` 两件事(与宿主事件流同形)。
45
+ * 归因认的是**结果**那件事的 seq(`callSeq` 只是配对用),所以 `readAt('a.md', 20)`
46
+ * 记下来的 `firstRead.seq` 是 21。
47
+ * @param {string} rel - 路径
48
+ * @param {number} seq - `tool/call` 的 seq
49
+ * @returns {object[]} 两件事
50
+ */
51
+ function readAt(rel, seq) {
52
+ const callId = `c${seq}`
53
+ return [
54
+ {
55
+ type: 'tool/call',
56
+ seq,
57
+ time: seq,
58
+ data: { turn: 1, step: 1, callId, name: 'read', arguments: JSON.stringify({ file_path: rel }) },
59
+ },
60
+ {
61
+ type: 'tool/result',
62
+ seq: seq + 1,
63
+ time: seq + 1,
64
+ data: { message: { role: 'tool', toolCallId: callId, source: { kind: 'tool', callId }, isError: false } },
65
+ },
66
+ ]
67
+ }
68
+
69
+ /** 一个开着账、只交过几份包的会话。 */
70
+ function audited(id) {
71
+ const store = createStore()
72
+ activateAudit(store, id)
73
+ return store
74
+ }
75
+
76
+ /* ── 1. 历史归因(§24.3)────────────────────────────────────── */
77
+
78
+ test('历史归因:换成新 Context 之后再看,旧读的层与 Epoch 一个字节都不许变', () => {
79
+ const store = audited('s1')
80
+ // Epoch 1:a.md 是主看篇
81
+ noteSnapshot(store, 's1', pack({ primary: ['a.md'], supporting: ['b.md'] }), { seq: 10, at: 1000 })
82
+ // 读发生在 Epoch 1(call seq 20 → result seq 21)
83
+ ingestEvents(store, 's1', readAt('a.md', 20), { root: ROOT })
84
+ // Epoch 2:换任务,a.md 掉出包外
85
+ noteSnapshot(store, 's1', pack({ topic: 'other', primary: ['c.md'] }), { seq: 40, at: 2000 })
86
+
87
+ const usage = usageFor(store, 's1')
88
+ const row = usage.reads.find((r) => r.rel === 'a.md')
89
+
90
+ // 冻结值:读发生时 a.md 在 primary、第 1 个 Epoch、快照 seq 10
91
+ assert.equal(row.firstRead.seq, 21)
92
+ assert.equal(row.firstRead.snapshotSeq, 10)
93
+ assert.equal(row.firstRead.epochId, 1)
94
+ assert.equal(row.firstRead.tier, 'primary')
95
+ assert.equal(row.firstRead.rank, 1)
96
+ assert.equal(row.firstRead.inside, true)
97
+
98
+ // 「现在」是 Epoch 2,包里已经没有 a.md 了 —— 但那是 Current View,不是历史
99
+ assert.equal(usage.epochId, 2)
100
+ assert.equal(usage.items.some((item) => item.rel === 'a.md'), false)
101
+ assert.equal(usage.stats.firstReadTier, 'primary')
102
+ assert.equal(usage.stats.firstReadEpoch, 1)
103
+ // 兼容别名也只能是首读的归因(v0.15 这里会拿最新快照重判成 outside)
104
+ assert.equal(row.tier, 'primary')
105
+ assert.equal(row.outside, false)
106
+ // 它算进的是**当时**那个 Epoch,不是现在这个
107
+ assert.equal(usage.epochs[0].primary.read, true)
108
+ assert.equal(usage.epochs[1].primary.read, false)
109
+ assert.equal(usage.stats.primaryFollowThrough, false)
110
+ assert.equal(usage.stats.byTier.primary.read, 0)
111
+ })
112
+
113
+ test('当前视图可变、历史视图不可变:换回来也不重算', () => {
114
+ const store = audited('s2')
115
+ noteSnapshot(store, 's2', pack({ primary: ['a.md'] }), { seq: 10, at: 1 })
116
+ ingestEvents(store, 's2', readAt('a.md', 20), { root: ROOT })
117
+ noteSnapshot(store, 's2', pack({ primary: ['b.md'] }), { seq: 40, at: 2 })
118
+ noteSnapshot(store, 's2', pack({ primary: ['a.md'] }), { seq: 60, at: 3 })
119
+
120
+ const usage = usageFor(store, 's2')
121
+ const row = usage.reads.find((r) => r.rel === 'a.md')
122
+ assert.equal(row.firstRead.epochId, 1)
123
+ assert.equal(row.firstRead.tier, 'primary')
124
+ assert.equal(usage.epochId, 3)
125
+ })
126
+
127
+ /* ── 2. 离开之后仍然被读(§24.4)────────────────────────────── */
128
+
129
+ test('持续读:离开上下文之后还读那篇 ⇒ 只记事实,不加解释', () => {
130
+ const store = audited('s3')
131
+ noteSnapshot(store, 's3', pack({ primary: ['a.md'], supporting: ['b.md'] }), { seq: 10, at: 1 })
132
+ // Epoch 2:a.md 出包
133
+ noteSnapshot(store, 's3', pack({ supporting: ['b.md'] }), { seq: 20, at: 2 })
134
+ // 出包之后仍然读它
135
+ ingestEvents(store, 's3', readAt('a.md', 30), { root: ROOT })
136
+
137
+ const usage = usageFor(store, 's3')
138
+ const row = usage.reads.find((r) => r.rel === 'a.md')
139
+ assert.equal(row.firstRead.epochId, 2)
140
+ assert.equal(row.firstRead.inside, false)
141
+ assert.equal(row.firstRead.tier, null)
142
+ assert.equal(row.continuedReadAfterExit, true)
143
+ assert.equal(row.reEntry, false)
144
+ assert.equal(usage.stats.continuedReadsAfterExit, 1)
145
+ assert.equal(usage.stats.reEntries, 0)
146
+ assert.equal(usage.stats.firstReadTier, 'outside')
147
+ assert.equal(usage.epochs[1].continuedReadsAfterExit, 1)
148
+ // 摘要里只有事实,没有「Agent 不认可」这种话
149
+ assert.equal(/不认可|不信任|confidence|score/i.test(JSON.stringify(usage.epochs)), false)
150
+ })
151
+
152
+ /* ── 3. 离开又回来(§24.5)──────────────────────────────────── */
153
+
154
+ test('重新进入:离开 → 又回到包里 → 再读 ⇒ reEntry 与 tierAtRead 都是事实', () => {
155
+ const store = audited('s4')
156
+ noteSnapshot(store, 's4', pack({ primary: ['a.md'] }), { seq: 10, at: 1 })
157
+ noteSnapshot(store, 's4', pack({ primary: ['c.md'] }), { seq: 20, at: 2 })
158
+ noteSnapshot(store, 's4', pack({ primary: ['c.md'], supporting: ['a.md'] }), { seq: 30, at: 3 })
159
+ ingestEvents(store, 's4', readAt('a.md', 40), { root: ROOT })
160
+
161
+ const usage = usageFor(store, 's4')
162
+ const row = usage.reads.find((r) => r.rel === 'a.md')
163
+ assert.equal(row.firstRead.epochId, 3)
164
+ assert.equal(row.firstRead.tier, 'supporting')
165
+ assert.equal(row.firstRead.inside, true)
166
+ assert.equal(row.reEntry, true)
167
+ // 这一次读本身在包里 ⇒ 不是「离开之后仍在读」
168
+ assert.equal(row.continuedReadAfterExit, false)
169
+ assert.equal(usage.stats.reEntries, 1)
170
+ assert.equal(usage.epochs[2].reEntries, 1)
171
+ })
172
+
173
+ /* ── 4. 两个事实的判据(纯函数直接问)──────────────────────── */
174
+
175
+ test('事实判据:更早的窗口里从来没有过这篇 ⇒ 两个都是 false', () => {
176
+ const snapshots = [
177
+ { ...snapshotOf(pack({ primary: ['a.md'] }), { seq: 10, at: 1 }), epochId: 1 },
178
+ { ...snapshotOf(pack({ primary: ['b.md'] }), { seq: 20, at: 2 }), epochId: 2 },
179
+ ]
180
+ assert.deepEqual(attributeReadFacts(snapshots, 'z.md', 30), { continuedReadAfterExit: false, reEntry: false })
181
+ // 一直在包里、且没离开过 ⇒ 也不是「重新进入」
182
+ assert.deepEqual(attributeReadFacts(snapshots, 'a.md', 15), { continuedReadAfterExit: false, reEntry: false })
183
+ // 早于任何快照的读:连快照都配不上,两个事实都无从谈起
184
+ assert.deepEqual(attributeReadFacts(snapshots, 'a.md', 5), { continuedReadAfterExit: false, reEntry: false })
185
+ assert.deepEqual(attributeReadFacts(null, 'a.md', 30), { continuedReadAfterExit: false, reEntry: false })
186
+ })
187
+
188
+ test('事实判据:出包那一读算持续读,回到包里那一读算重新进入', () => {
189
+ const snapshots = [
190
+ { ...snapshotOf(pack({ primary: ['a.md'] }), { seq: 10, at: 1 }), epochId: 1 },
191
+ { ...snapshotOf(pack({ primary: ['b.md'] }), { seq: 20, at: 2 }), epochId: 2 },
192
+ { ...snapshotOf(pack({ primary: ['b.md'], related: ['a.md'] }), { seq: 30, at: 3 }), epochId: 3 },
193
+ ]
194
+ assert.deepEqual(attributeReadFacts(snapshots, 'a.md', 25), { continuedReadAfterExit: true, reEntry: false })
195
+ assert.deepEqual(attributeReadFacts(snapshots, 'a.md', 35), { continuedReadAfterExit: false, reEntry: true })
196
+ })
197
+
198
+ test('attributeRead:不在包里也照样给出「当时那份快照」的身份', () => {
199
+ const snapshot = { ...snapshotOf(pack({ primary: ['a.md'] }), { seq: 10, at: 1 }), epochId: 4 }
200
+ assert.deepEqual(attributeRead(snapshot, 'a.md'), {
201
+ snapshotSeq: 10, epochId: 4, tierAtRead: 'primary', rankAtRead: 1, insideAtRead: true,
202
+ })
203
+ assert.deepEqual(attributeRead(snapshot, 'z.md'), {
204
+ snapshotSeq: 10, epochId: 4, tierAtRead: null, rankAtRead: null, insideAtRead: false,
205
+ })
206
+ assert.deepEqual(attributeRead(null, 'a.md'), {
207
+ snapshotSeq: null, epochId: null, tierAtRead: null, rankAtRead: null, insideAtRead: false,
208
+ })
209
+ })
210
+
211
+ /* ── 5. 规则一致(§24.6)────────────────────────────────────── */
212
+
213
+ test('规则一致:runtime 记下的归因,逐字段等于 snapshotAt() + attributeRead() 现算的结果', () => {
214
+ const store = audited('s5')
215
+ noteSnapshot(store, 's5', pack({ primary: ['a.md'], supporting: ['b.md', 'c.md'] }), { seq: 10, at: 1 })
216
+ noteSnapshot(store, 's5', pack({ supporting: ['b.md'], related: ['a.md'] }), { seq: 30, at: 2 })
217
+ ingestEvents(store, 's5', readAt('a.md', 20), { root: ROOT })
218
+ ingestEvents(store, 's5', readAt('z.md', 40), { root: ROOT })
219
+
220
+ const state = store.sessions.get('s5')
221
+ const usage = usageFor(store, 's5')
222
+ assert.equal(usage.reads.length, 2)
223
+ for (const row of usage.reads) {
224
+ const attributed = attributeRead(snapshotAt(state.snapshots, row.firstRead.seq), row.rel)
225
+ assert.deepEqual(
226
+ {
227
+ snapshotSeq: row.firstRead.snapshotSeq,
228
+ epochId: row.firstRead.epochId,
229
+ tierAtRead: row.firstRead.tier,
230
+ rankAtRead: row.firstRead.rank,
231
+ insideAtRead: row.firstRead.inside,
232
+ },
233
+ {
234
+ snapshotSeq: attributed.snapshotSeq,
235
+ epochId: attributed.epochId,
236
+ tierAtRead: attributed.tierAtRead,
237
+ rankAtRead: attributed.rankAtRead,
238
+ insideAtRead: attributed.insideAtRead,
239
+ },
240
+ `${row.rel} 的归因必须是那两个纯函数算出来的`,
241
+ )
242
+ }
243
+ })
244
+
245
+ test('规则一致:同样的输入喂两个 store,逐字段 deepEqual(没有隐藏的当前时刻依赖)', () => {
246
+ const build = (id) => {
247
+ const store = audited(id)
248
+ noteSnapshot(store, id, pack({ primary: ['a.md'] }), { seq: 10, at: 1 })
249
+ ingestEvents(store, id, readAt('a.md', 20), { root: ROOT })
250
+ noteSnapshot(store, id, pack({ primary: ['b.md'] }), { seq: 30, at: 2 })
251
+ ingestEvents(store, id, readAt('a.md', 40), { root: ROOT })
252
+ return usageFor(store, id)
253
+ }
254
+ assert.deepEqual(build('left'), build('right'))
255
+ })
256
+
257
+ /* ── 6. Epoch 的边界与上限 ──────────────────────────────────── */
258
+
259
+ test('Epoch 与快照同生共死:同签名不新建,换了内容才 +1,Delta 带 fromEpoch/toEpoch', () => {
260
+ const store = audited('s6')
261
+ noteSnapshot(store, 's6', pack({ primary: ['a.md'] }), { seq: 10, at: 1 })
262
+ noteSnapshot(store, 's6', pack({ primary: ['a.md'] }), { seq: 20, at: 2 })
263
+ let usage = usageFor(store, 's6')
264
+ assert.equal(usage.stats.churn.epochs, 1)
265
+ assert.equal(usage.stats.churn.changes, 0)
266
+ assert.equal(usage.epochs.length, 1)
267
+
268
+ noteSnapshot(store, 's6', pack({ primary: ['b.md'] }), { seq: 30, at: 3 })
269
+ usage = usageFor(store, 's6')
270
+ assert.equal(usage.epochId, 2)
271
+ assert.equal(usage.epochs.length, 2)
272
+ assert.equal(usage.stats.churn.epochs, 2)
273
+ assert.equal(usage.stats.churn.changes, 1)
274
+ assert.equal(usage.delta.fromEpoch, 1)
275
+ assert.equal(usage.delta.toEpoch, 2)
276
+ })
277
+
278
+ test('上限:Epoch 明细只留最近 20 份,「换过几次」仍是累计事实', () => {
279
+ const store = audited('s7')
280
+ const total = MAX_SNAPSHOTS_PER_SESSION + 3
281
+ for (let i = 0; i < total; i += 1) {
282
+ noteSnapshot(store, 's7', pack({ primary: [`p${i}.md`] }), { seq: 10 + i, at: 100 + i })
283
+ }
284
+ const usage = usageFor(store, 's7')
285
+ assert.equal(usage.epochs.length, MAX_SNAPSHOTS_PER_SESSION)
286
+ // 编号是累计的:被淘汰的 Epoch 也算「换过」
287
+ assert.equal(usage.stats.churn.epochs, total)
288
+ assert.equal(usage.stats.churn.changes, total - 1)
289
+ // 客户端在用的旧键名 = 变化次数(`usage.changes` 文案)
290
+ assert.equal(usage.stats.churn.snapshots, total - 1)
291
+ assert.equal(usage.stats.churn.deltas, total - 1)
292
+ // 明细里留下的是最新的那 20 个
293
+ assert.equal(usage.epochs[usage.epochs.length - 1].epochId, total)
294
+ })
295
+
296
+ test('还没交过任何包:Epoch 编号为 0,没有快照可配', () => {
297
+ const store = audited('s8')
298
+ ingestEvents(store, 's8', readAt('a.md', 20), { root: ROOT })
299
+ const usage = usageFor(store, 's8')
300
+ const row = usage.reads[0]
301
+ // 一份包都没交过 ⇒ 没有「当前 Epoch」可指(null,不是 0 —— 0 是个编号)
302
+ assert.equal(usage.epochId, null)
303
+ assert.equal(usage.epochs.length, 0)
304
+ assert.equal(usage.stats.churn.epochs, 0)
305
+ assert.equal(row.firstRead.snapshotSeq, null)
306
+ assert.equal(row.firstRead.epochId, null)
307
+ assert.equal(row.firstRead.inside, false)
308
+ assert.equal(usage.stats.firstReadTier, 'outside')
309
+ })