dsh-session-matrix 0.0.0-stage → 0.16.2

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,283 @@
1
+ /**
2
+ * usage-split contract test — the parser that reconstructs peak/off-peak usage
3
+ * from session logs.
4
+ *
5
+ * The inputs here are synthetic on purpose: frame layout, truncated tails and
6
+ * corrupted middles are hard to produce from real logs on demand. The one
7
+ * thing that is *not* synthetic is `event.time`: the unit was read off real
8
+ * DSH logs (1794040946351, milliseconds since epoch) and is asserted below.
9
+ */
10
+
11
+ import { zstdCompressSync, zstdDecompressSync } from 'node:zlib'
12
+ import { isPeakTime, decompressFrames, splitUsageText } from '../lib/usage-split.js'
13
+
14
+ /** zstd frame decoder used by the tests, matching the host's call site. */
15
+ const decode = buffer => zstdDecompressSync(buffer)
16
+
17
+ const pass = []
18
+ const fail = []
19
+ const check = (label, fn) => {
20
+ try {
21
+ fn()
22
+ pass.push(label)
23
+ } catch (error) {
24
+ fail.push(`${label}: ${error.message}`)
25
+ }
26
+ }
27
+
28
+ const assert = (cond, message) => {
29
+ if (!cond) throw new Error(message)
30
+ }
31
+
32
+ /** Build an epoch-ms timestamp for a given Beijing wall clock. */
33
+ const beijing = (y, m, d, h, min = 0, sec = 0) => Date.UTC(y, m - 1, d, h - 8, min, sec)
34
+
35
+ // 2026-11-16 is a Monday, 2026-11-14 a Saturday.
36
+ check('peak windows are 09:00–12:00 and 14:00–18:00 on weekdays', () => {
37
+ assert(isPeakTime(beijing(2026, 11, 16, 8, 59)) === false, '08:59 should be off-peak')
38
+ assert(isPeakTime(beijing(2026, 11, 16, 9, 0)) === true, '09:00 should be peak')
39
+ assert(isPeakTime(beijing(2026, 11, 16, 11, 59)) === true, '11:59 should be peak')
40
+ assert(isPeakTime(beijing(2026, 11, 16, 12, 0)) === false, '12:00 should be off-peak')
41
+ assert(isPeakTime(beijing(2026, 11, 16, 13, 59)) === false, '13:59 should be off-peak')
42
+ assert(isPeakTime(beijing(2026, 11, 16, 14, 0)) === true, '14:00 should be peak')
43
+ assert(isPeakTime(beijing(2026, 11, 16, 17, 59)) === true, '17:59 should be peak')
44
+ assert(isPeakTime(beijing(2026, 11, 16, 18, 0)) === false, '18:00 should be off-peak')
45
+ })
46
+
47
+ check('weekends are always off-peak', () => {
48
+ assert(isPeakTime(beijing(2026, 11, 14, 10, 0)) === false, 'Saturday 10:00')
49
+ assert(isPeakTime(beijing(2026, 11, 15, 15, 0)) === false, 'Sunday 15:00')
50
+ })
51
+
52
+ check('timestamps are milliseconds, not seconds', () => {
53
+ // Taken from a real log line: {"type":"assistant/message","time":1794040946138}
54
+ const real = 1794040946_138
55
+ assert(real > 1e12, 'real log time should be in ms range')
56
+ // Treating it as seconds would land in 1970 and never be peak either way,
57
+ // so assert the shift maths directly against a known Beijing wall clock.
58
+ assert(isPeakTime(beijing(2026, 11, 16, 10, 0)) === true, '10:00 Monday must be peak')
59
+ })
60
+
61
+ /** Encode one JSONL batch as a zstd frame. */
62
+ const frame = lines => zstdCompressSync(Buffer.from(lines.join('\n') + '\n', 'utf8'))
63
+
64
+ const usageEvent = (time, input, output, cacheRead = 0) => JSON.stringify({
65
+ type: 'assistant/message',
66
+ seq: 1,
67
+ time,
68
+ data: { usage: { inputTokens: input, outputTokens: output, cacheReadTokens: cacheRead, cacheWriteTokens: 0 } },
69
+ })
70
+
71
+ check('multiple concatenated frames are all decompressed', () => {
72
+ const buf = Buffer.concat([
73
+ frame([JSON.stringify({ type: 'session', id: 'x' })]),
74
+ frame([usageEvent(beijing(2026, 11, 16, 10, 0), 100, 10)]),
75
+ frame([usageEvent(beijing(2026, 11, 16, 20, 0), 200, 20)]),
76
+ ])
77
+ const text = decompressFrames(buf, decode)
78
+ const split = splitUsageText(text)
79
+ assert(split, 'should find usage across frames')
80
+ assert(split.peak.uncached === 100, `peak uncached ${split.peak.uncached}`)
81
+ assert(split.off.uncached === 200, `off uncached ${split.off.uncached}`)
82
+ assert(split.requests === 2, `requests ${split.requests}`)
83
+ })
84
+
85
+ check('a truncated tail keeps what decoded', () => {
86
+ const whole = Buffer.concat([
87
+ frame([usageEvent(beijing(2026, 11, 16, 10, 0), 50, 5)]),
88
+ frame([usageEvent(beijing(2026, 11, 16, 20, 0), 60, 6)]),
89
+ ])
90
+ const truncated = whole.subarray(0, whole.length - 12)
91
+ const split = splitUsageText(decompressFrames(truncated, decode))
92
+ assert(split, 'first frame should still decode')
93
+ // A truncated tail decodes to whatever zstd can recover; it must not throw
94
+ // and must not lose the frames that came before it.
95
+ assert(split.peak.uncached === 50, `expected 50, got ${split.peak.uncached}`)
96
+ })
97
+
98
+ check('a corrupted middle frame does not throw', () => {
99
+ // Truncation is what makes zstd throw; a header-only frame decodes to zero
100
+ // bytes without an error, which the parser tolerates either way.
101
+ const good = frame([usageEvent(beijing(2026, 11, 16, 10, 0), 70, 7)])
102
+ const broken = good.subarray(0, Math.max(8, good.length - 6))
103
+ const buf = Buffer.concat([good, broken, good])
104
+ let split = null
105
+ try {
106
+ split = splitUsageText(decompressFrames(buf, decode))
107
+ } catch (error) {
108
+ throw new Error(`decompressFrames threw: ${error.message}`)
109
+ }
110
+ // The damaged frame contributes nothing; the frames around it must still be read.
111
+ assert(split && split.peak.uncached === 140, `expected both good frames, got ${split && split.peak.uncached}`)
112
+ })
113
+
114
+ check('magic bytes inside plain text are not treated as a frame', () => {
115
+ // A JSON string can contain the 4 magic bytes; the scanner only looks at the
116
+ // compressed file, so this exercises the parser's tolerance instead.
117
+ const text = `{"type":"note","text":"\\u28b5\\u2ffd"}\n` + usageEvent(beijing(2026, 11, 16, 10, 0), 3, 1)
118
+ const split = splitUsageText(text)
119
+ assert(split && split.peak.uncached === 3, 'unrelated lines must not break parsing')
120
+ })
121
+
122
+ check('events without usage are ignored', () => {
123
+ const split = splitUsageText([
124
+ JSON.stringify({ type: 'step/end', time: beijing(2026, 11, 16, 10, 0) }),
125
+ JSON.stringify({ type: 'assistant/message', time: beijing(2026, 11, 16, 10, 0), data: {} }),
126
+ ].join('\n'))
127
+ assert(split === null, 'no usage should yield null')
128
+ })
129
+
130
+ check('corrupt numbers are clamped, not credited', () => {
131
+ const split = splitUsageText([
132
+ JSON.stringify({ type: 'assistant/message', time: beijing(2026, 11, 16, 10, 0), data: { usage: { inputTokens: -500, outputTokens: 'abc', cacheReadTokens: 10 } } }),
133
+ JSON.stringify({ type: 'assistant/message', time: beijing(2026, 11, 16, 10, 0), data: { usage: { inputTokens: 5, outputTokens: 1 } } }),
134
+ ].join('\n'))
135
+ assert(split.peak.uncached === 5, `negatives must not reduce the total: ${split.peak.uncached}`)
136
+ assert(split.peak.output === 1, `NaN must count as 0: ${split.peak.output}`)
137
+ })
138
+
139
+ check('an unterminated line is skipped without throwing', () => {
140
+ const split = splitUsageText('{"type":"assistant/message","time":1,"data":{"usage":{"inputT')
141
+ assert(split === null, 'partial JSON should be ignored')
142
+ })
143
+
144
+ // ── settlement events ────────────────────────────────────────────────────────
145
+ // `assistant/attempt` carries usage only inside its stream (failed / retried /
146
+ // cancelled calls), and `assistant/message` may omit the top-level summary.
147
+ // Both must be counted, exactly once per request.
148
+
149
+ const usageChunk = (time, usage) => ({ type: 'chunk', time, chunk: { type: 'usage', usage } })
150
+
151
+ check('stream-only usage on a successful message is counted', () => {
152
+ const event = JSON.stringify({
153
+ type: 'assistant/message',
154
+ time: beijing(2026, 11, 16, 10, 0),
155
+ data: { stream: [usageChunk(beijing(2026, 11, 16, 10, 0), { inputTokens: 40, outputTokens: 4 })] },
156
+ })
157
+ const split = splitUsageText(event)
158
+ assert(split.peak.uncached === 40 && split.peak.output === 4, JSON.stringify(split.peak))
159
+ })
160
+
161
+ check('a failed attempt is counted from its stream', () => {
162
+ const event = JSON.stringify({
163
+ type: 'assistant/attempt',
164
+ time: beijing(2026, 11, 16, 20, 0),
165
+ data: { turn: 1, step: 3, stream: [usageChunk(beijing(2026, 11, 16, 20, 0), { inputTokens: 900, outputTokens: 30 })] },
166
+ })
167
+ const split = splitUsageText(event)
168
+ assert(split.off.uncached === 900 && split.off.output === 30, JSON.stringify(split.off))
169
+ assert(split.peak.uncached === 0, 'attempt time is off-peak')
170
+ })
171
+
172
+ check('every retry attempt is counted', () => {
173
+ const at = beijing(2026, 11, 16, 11, 0)
174
+ const lines = [1, 2, 3].map(i => JSON.stringify({
175
+ type: 'assistant/attempt',
176
+ time: at,
177
+ data: { turn: 1, step: i, stream: [usageChunk(at, { inputTokens: 100, outputTokens: 10 })] },
178
+ }))
179
+ const split = splitUsageText(lines.join('\n'))
180
+ assert(split.requests === 3, `requests ${split.requests}`)
181
+ assert(split.peak.uncached === 300 && split.peak.output === 30, JSON.stringify(split.peak))
182
+ })
183
+
184
+ check('top-level and stream usage are never added together', () => {
185
+ const at = beijing(2026, 11, 16, 10, 0)
186
+ const usage = { inputTokens: 500, outputTokens: 50 }
187
+ const event = JSON.stringify({
188
+ type: 'assistant/message',
189
+ time: at,
190
+ data: { usage, stream: [usageChunk(at, usage)] },
191
+ })
192
+ const split = splitUsageText(event)
193
+ assert(split.requests === 1, `requests ${split.requests}`)
194
+ assert(split.peak.uncached === 500, `expected 500 once, got ${split.peak.uncached}`)
195
+ })
196
+
197
+ check('peak classification uses the usage chunk time, not the settlement time', () => {
198
+ // The chunk landed at 11:59:59 (peak); the event was written at 12:00:01 (off).
199
+ const event = JSON.stringify({
200
+ type: 'assistant/message',
201
+ time: beijing(2026, 11, 16, 12, 0, 1),
202
+ data: { stream: [usageChunk(beijing(2026, 11, 16, 11, 59, 59), { inputTokens: 77, outputTokens: 7 })] },
203
+ })
204
+ const split = splitUsageText(event)
205
+ assert(split.peak.uncached === 77, `expected peak, got peak=${split.peak.uncached} off=${split.off.uncached}`)
206
+ assert(split.off.uncached === 0, 'must not be classified as off-peak')
207
+ })
208
+
209
+ check('a top-level usage still takes the chunk time across the morning boundary', () => {
210
+ // Event at 08:59:59.999 (off-peak), chunk at 09:00:00.001 (peak).
211
+ const event = JSON.stringify({
212
+ type: 'assistant/message',
213
+ time: beijing(2026, 11, 16, 8, 59, 59) + 999,
214
+ data: {
215
+ usage: { inputTokens: 11, outputTokens: 1 },
216
+ stream: [usageChunk(beijing(2026, 11, 16, 9, 0, 0) + 1, { inputTokens: 999, outputTokens: 99 })],
217
+ },
218
+ })
219
+ const split = splitUsageText(event)
220
+ assert(split.peak.uncached === 11, `numbers must come from the top-level usage, got ${split.peak.uncached}`)
221
+ assert(split.off.uncached === 0, 'the chunk time (09:00:00.001) makes this peak, not off-peak')
222
+ })
223
+
224
+ check('a top-level usage still takes the chunk time across the noon boundary', () => {
225
+ // Event at 11:59:59.999 (peak), chunk at 12:00:00.001 (off-peak).
226
+ const event = JSON.stringify({
227
+ type: 'assistant/message',
228
+ time: beijing(2026, 11, 16, 11, 59, 59) + 999,
229
+ data: {
230
+ usage: { inputTokens: 12, outputTokens: 2 },
231
+ stream: [usageChunk(beijing(2026, 11, 16, 12, 0, 0) + 1, { inputTokens: 888, outputTokens: 88 })],
232
+ },
233
+ })
234
+ const split = splitUsageText(event)
235
+ assert(split.off.uncached === 12, `numbers from top-level, time from chunk: ${JSON.stringify(split)}`)
236
+ assert(split.peak.uncached === 0, 'must not be peak')
237
+ })
238
+
239
+ check('without a chunk time the event time is used', () => {
240
+ const event = JSON.stringify({
241
+ type: 'assistant/message',
242
+ time: beijing(2026, 11, 16, 10, 0),
243
+ data: { usage: { inputTokens: 30, outputTokens: 3 }, stream: [{ type: 'chunk', chunk: { type: 'text', text: 'x' } }] },
244
+ })
245
+ const split = splitUsageText(event)
246
+ assert(split.peak.uncached === 30, 'event time is peak, so this is peak')
247
+ })
248
+
249
+ check('several usage chunks settle on the last one, never summed', () => {
250
+ const at = beijing(2026, 11, 16, 10, 0)
251
+ const event = JSON.stringify({
252
+ type: 'assistant/message',
253
+ time: at,
254
+ data: {
255
+ stream: [
256
+ usageChunk(at, { inputTokens: 10, outputTokens: 1 }),
257
+ usageChunk(at, { inputTokens: 40, outputTokens: 4 }),
258
+ ],
259
+ },
260
+ })
261
+ const split = splitUsageText(event)
262
+ assert(split.requests === 1, `requests ${split.requests}`)
263
+ assert(split.peak.uncached === 40, `expected the last snapshot (40), got ${split.peak.uncached}`)
264
+ })
265
+
266
+ check('cache buckets accumulate separately', () => {
267
+ const at = beijing(2026, 11, 16, 10, 0)
268
+ const a = JSON.stringify({ type: 'assistant/message', time: at, data: { usage: { inputTokens: 10, outputTokens: 1, cacheReadTokens: 1000, cacheWriteTokens: 20 } } })
269
+ const b = JSON.stringify({ type: 'assistant/message', time: at, data: { usage: { inputTokens: 5, outputTokens: 2, cacheReadTokens: 2000, cacheWriteTokens: 30 } } })
270
+ const split = splitUsageText([a, b].join('\n'))
271
+ assert(split.peak.cacheRead === 3000, `cacheRead ${split.peak.cacheRead}`)
272
+ assert(split.peak.cacheWrite === 50, `cacheWrite ${split.peak.cacheWrite}`)
273
+ assert(split.peak.uncached === 15 && split.peak.output === 3, 'input/output totals')
274
+ })
275
+
276
+
277
+ if (fail.length) {
278
+ console.error(`\nusage-split.test.mjs — ${pass.length} passed, ${fail.length} failed`)
279
+ for (const line of fail) console.error(' ✗ ' + line)
280
+ process.exitCode = 1
281
+ } else {
282
+ console.log(`usage-split.test.mjs — ${pass.length} passed, 0 failed`)
283
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Cross-check the log parser against the host's own totals.
3
+ *
4
+ * For every session we can read, sum the usage the parser finds and compare it
5
+ * with `tokenUsage.totals` from the projection cache — the number DSH itself
6
+ * computed while the session ran. A parser that misses `assistant/attempt`
7
+ * shows up here as a shortfall.
8
+ */
9
+ import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
10
+ import { zstdDecompressSync } from 'node:zlib'
11
+ import { join } from 'node:path'
12
+ import { decompressFrames, splitUsageText } from '../lib/usage-split.js'
13
+
14
+ const home = process.env.DSH_HOME || join(process.env.USERPROFILE || process.env.HOME, '.dsh')
15
+ const sessionsRoot = join(home, 'sessions')
16
+ const cacheRoot = join(home, 'storages', 'session_projcache', 'sessions')
17
+
18
+ if (!existsSync(sessionsRoot) || !existsSync(cacheRoot)) {
19
+ console.log('usage-vs-projection.test.mjs — skipped (no local DSH data)')
20
+ process.exit(0)
21
+ }
22
+
23
+ /** session id → tokenUsage totals, from the projection cache. */
24
+ const totals = new Map()
25
+ for (const file of readdirSync(cacheRoot)) {
26
+ if (!file.endsWith('.json')) continue
27
+ try {
28
+ const record = JSON.parse(readFileSync(join(cacheRoot, file), 'utf8'))
29
+ const value = record?.record?.rows?.tokenUsage?.val ?? record?.record?.rows?.tokenUsage
30
+ const t = value?.totals
31
+ if (t) totals.set(file.replace(/\.json$/, ''), t)
32
+ } catch { /* a half-written cache file is not interesting */ }
33
+ }
34
+
35
+ let compared = 0
36
+ let exact = 0
37
+ const diffs = []
38
+ for (const dir of readdirSync(sessionsRoot)) {
39
+ const ws = join(sessionsRoot, dir)
40
+ if (!statSync(ws).isDirectory()) continue
41
+ for (const entry of readdirSync(ws, { withFileTypes: true })) {
42
+ if (!entry.isDirectory()) continue
43
+ const file = join(ws, entry.name, 'session.v4.jsonl.zstd')
44
+ if (!existsSync(file)) continue
45
+ const want = totals.get(`session-${entry.name}`) ?? totals.get(entry.name)
46
+ if (!want) continue
47
+ let text = ''
48
+ try {
49
+ text = decompressFrames(readFileSync(file), zstdDecompressSync)
50
+ } catch { continue }
51
+ const split = splitUsageText(text)
52
+ if (!split) continue
53
+ const got = {
54
+ input: split.peak.uncached + split.off.uncached,
55
+ output: split.peak.output + split.off.output,
56
+ cacheRead: split.peak.cacheRead + split.off.cacheRead,
57
+ cacheWrite: split.peak.cacheWrite + split.off.cacheWrite,
58
+ }
59
+ compared += 1
60
+ const delta = Math.abs(got.input - (want.uncachedInputTokens ?? 0))
61
+ + Math.abs(got.output - (want.outputTokens ?? 0))
62
+ + Math.abs(got.cacheRead - (want.cacheReadTokens ?? 0))
63
+ + Math.abs(got.cacheWrite - (want.cacheWriteTokens ?? 0))
64
+ if (delta === 0) exact += 1
65
+ else if (diffs.length < 3) diffs.push({ id: entry.name.slice(0, 8), got, want, delta })
66
+ }
67
+ }
68
+
69
+ console.log(`usage-vs-projection.test.mjs — ${exact}/${compared} sessions match exactly`)
70
+ for (const d of diffs) console.log(' diff', JSON.stringify(d))
71
+ process.exitCode = compared > 0 && exact === compared ? 0 : 1