Skip to content

Commit 791e0fb

Browse files
authored
Merge pull request #1099 from lidge-jun/codex/usage-entry-cap-500k
feat(usage): raise the management read entry cap from 200k to 500k
2 parents 7425855 + 9f6df99 commit 791e0fb

3 files changed

Lines changed: 56 additions & 5 deletions

File tree

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# 060 — usage management read cap: 200k → 500k entries
2+
3+
User authorization (2026-08-06): adopt the user's uncommitted 500k edits from
4+
the main checkout, "의견을 종합해서" — synthesize the review context and land
5+
it properly. Authority includes push + PR + merge for this item.
6+
7+
## Synthesis (why 500k is the right call now)
8+
9+
- The cap is a READER bound (`MANAGEMENT_USAGE_MAX_ENTRIES` in
10+
`src/usage/log.ts`), not a retention bound: raw `usage.jsonl` is never
11+
deleted by it. Raising it widens what one management read can return.
12+
- The BYTE cap (`managementUsageMaxReadBytes`, 64 MiB default) bounds the raw
13+
INPUT of a read before the entry cap applies (log.ts:532-558); the entry cap
14+
trims parsed rows afterwards (log.ts:500-519). Corrected per audit: 64 MiB
15+
bounds input bytes, while 500k raises the TRANSIENT parse/summary heap and
16+
CPU — up to 300k more normalized JS objects can be retained per read, and
17+
`/api/usage` does several full passes with per-request Map/Set aggregation
18+
(summary.ts:301-583). This is a bounded, transient cost on a management
19+
read, not an unbounded leak — but it must be measured, not assumed.
20+
- Acceptance criterion added: a representative 500k-entry benchmark (small
21+
rows, worst-case unique request ids) must show acceptable wall time and
22+
peak RSS delta for `readUsageSnapshotForManagement` + `summarizeUsage`
23+
before landing.
24+
- Prior lesson (usage-log cap incident): "a reader cap can hide data without
25+
deleting it" — the 200k clip was exactly that failure shape for the GUI.
26+
- With the #1008 rollup sidecar (still open) history older than the window
27+
will come from folded rows anyway; until it lands, the raw window IS the
28+
history, which strengthens the case for the wider entry cap now.
29+
- Overlap handling: this branch cuts from current dev, applying the same
30+
content as the user's dirty edits. The main checkout stays untouched; once
31+
this lands, the user's local diff becomes content-identical to HEAD.
32+
33+
## Work
34+
35+
1. Branch `codex/usage-entry-cap-500k` off current dev; apply the two-file
36+
change (constant + test expectations).
37+
2. 500k benchmark (bench script in .tmp/, not committed): parse + summarize
38+
wall time and heap delta at 200k vs 500k; record numbers in this ledger.
39+
3. Focused tests + typecheck; terra regression audit. Collision check done:
40+
#1008's log.ts diff starts at the reader (~line 523) and does not touch
41+
the cap line or this test — no hunk collision (audit-verified).
42+
4. Push, PR to dev, CI green, merge with `--match-head-commit` pin.
43+
44+
## Ledger
45+
46+
| Step | Evidence |
47+
|------|----------|
48+
| Benchmark (bench.ts in mktemp, not committed) | Baseline 200k-cap: 200k entries, read 475ms, summarize 358ms, ΔRSS 547MiB. With 500k cap on a 96.7MiB/500k-row file: byte cap binds first → 330,585 entries, read 835ms, summarize 609ms, ΔRSS ~1.1GiB transient. 600k-row file: identical 330,585 entries — the 64MiB byte window is the effective bound for realistic rows; the 500k entry cap is a secondary guard, not the binding limit |
49+
| Cap-binding benchmark (bench2, audit-required) | Tiny rows densely packing 63.5MiB → 629,205 rows in the byte window; parse-all-then-slice yields exactly 500,000 entries (129,205 dropped). read 1,436ms, summarize 637ms, ΔRSS 897MiB transient. This exercises the exact widened case (entry cap binding, unique request ids) |
50+
| Acceptance threshold + verdict | Threshold: ≤3s combined read+summarize, ≤1.5GiB transient RSS on the worst case. Measured: 2.07s combined, 897MiB — inside threshold. Request-scoped, no steady-state retention; acceptable for an on-demand admin endpoint |
51+
| Stale comment | tests/usage-log.test.ts:138 timing comment updated to the 500k shape (audit minor) |

‎src/usage/log.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -421,7 +421,7 @@ export type UsageLogRevision = {
421421
let usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
422422
const MANAGEMENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
423423
const MANAGEMENT_USAGE_READ_CHUNK_BYTES = 1024 * 1024;
424-
const MANAGEMENT_USAGE_MAX_ENTRIES = 200_000;
424+
const MANAGEMENT_USAGE_MAX_ENTRIES = 500_000;
425425
const MANAGEMENT_USAGE_FLIGHT_STALE_MS = 30_000;
426426
export interface ManagementUsageSnapshot {
427427
entries: PersistedUsageEntry[];

‎tests/usage-log.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -126,16 +126,16 @@ describe("usage log", () => {
126126
test("usage byte-prefix truncation and entry-count truncation report independent metadata", async () => {
127127
writeFileSync(
128128
usageLogPath(),
129-
`${Array.from({ length: 200_001 }, (_, index) => JSON.stringify({ requestId: String(index) })).join("\n")}\n`,
129+
`${Array.from({ length: 500_001 }, (_, index) => JSON.stringify({ requestId: String(index) })).join("\n")}\n`,
130130
);
131131
const snapshot = await readUsageSnapshotForManagement();
132-
expect(snapshot.entries).toHaveLength(200_000);
132+
expect(snapshot.entries).toHaveLength(500_000);
133133
expect(snapshot.entries[0]?.requestId).toBe("1");
134-
expect(snapshot.entries.at(-1)?.requestId).toBe("200000");
134+
expect(snapshot.entries.at(-1)?.requestId).toBe("500000");
135135
expect(snapshot.truncatedPrefixBytes).toBe(0);
136136
expect(snapshot.entriesTruncated).toBe(true);
137137
expect(snapshot.entriesDropped).toBe(1);
138-
}, STORE_BUDGET_MS); // parsing 200,001 rows IS the entry-cap assertion; windows-latest measured ~5.05s against Bun's 5s default.
138+
}, STORE_BUDGET_MS); // parsing 500,001 rows IS the entry-cap assertion; the 200k-row variant measured ~5.05s on windows-latest against Bun's 5s default.
139139

140140
test("stale usage-read flight is replaced and old completion cannot clear new owner", async () => {
141141
writeFileSync(

0 commit comments

Comments
 (0)