Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions src/server/management/usage-aggregate-cache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -477,14 +477,18 @@ async function accumulateCandidates(
try {
let first = true;
for (;;) {
// Candidate selection and row decoding are synchronous bounded chunks. A timer yield
// between them prevents a broad authenticated query from monopolizing the event loop.
// Candidate selection is synchronous and bounded. Row decoding and accumulation also
// yield within each page; keep the page-boundary yield for cheap rows and SQL work.
if (!first) await new Promise<void>(resolve => setTimeout(resolve, 0));
const offsets = read.nextPage();
if (!first && offsets.length === 0) break;
first = false;
const rows = await readUsageLedgerRowsAtOffsets({
offsets,
// This accumulator is private to the rebuild/append attempt and is discarded if the
// reader's final validation fails. Fold inside its time slice instead of retaining a
// page of parsed rows and then aggregating all of them in one synchronous turn.
onEntry: entry => accumulator.add(entry),
expectedIdentityKey: read.snapshot.identityKey,
// The offsets belong to this index snapshot. If the ledger moved since the snapshot,
// the reader re-validates the boundary before trusting any of them, and a rewrite of
Expand All @@ -499,7 +503,6 @@ async function accumulateCandidates(
// Serving only the rows that happened to parse would silently under-report the filter.
throw new UsageFilterIndexCorruptError();
}
for (const entry of rows.entries) accumulator.add(entry);
if (offsets.length === 0) break;
}
} finally {
Expand Down
54 changes: 44 additions & 10 deletions src/usage/ledger-scanner.ts
Original file line number Diff line number Diff line change
Expand Up @@ -486,6 +486,12 @@ export async function scanUsageLedgerCooperatively(
export interface ReadUsageLedgerRowsOptions {
/** Ascending, distinct row-start offsets reported by an earlier scan of the same file. */
offsets: readonly number[];
/**
* Folds rows as they are decoded instead of retaining them in `entries`. Callback work shares
* the cooperative time slice. Results are provisional until this read resolves: discard them
* if identity or content validation fails, as with the full-ledger scanner's callback.
*/
onEntry?: (entry: PersistedUsageEntry, rowStartBytes: number) => void;
/** Identity those offsets were captured under; a replaced file invalidates all of them. */
expectedIdentityKey: string;
/** Revision the offsets were captured under. Any movement re-validates the boundary. */
Expand All @@ -503,6 +509,7 @@ export interface ReadUsageLedgerRowsOptions {
}

export interface UsageLedgerRowRead {
/** Empty when an onEntry callback consumes the rows. */
entries: PersistedUsageEntry[];
/** Offsets that no longer frame a complete, normalizable row. */
unreadableOffsets: number[];
Expand Down Expand Up @@ -626,27 +633,32 @@ export async function readUsageLedgerRowsAtOffsets(
return null;
};

const walk = (visit: (bytes: Buffer, offset: number) => boolean): number[] => {
const walk = async (visit: (bytes: Buffer, offset: number) => boolean): Promise<number[]> => {
const unreadableOffsets: number[] = [];
let lastYieldAt = performance.now();
for (const offset of options.offsets) {
throwIfAborted(options.signal);
if (!Number.isSafeInteger(offset) || offset < 0 || offset >= size) {
unreadableOffsets.push(offset);
continue;
} else {
const bytes = lineAt(offset);
if (!bytes || !visit(bytes, offset)) unreadableOffsets.push(offset);
}
const bytes = lineAt(offset);
if (!bytes) {
unreadableOffsets.push(offset);
continue;
// A bounded candidate count does not bound decoding or aggregation time. Include the
// visitor in the same slice as the full scanner, and let timers/cancellation run even
// within one page. A single row remains atomic.
if (performance.now() - lastYieldAt >= MAX_SCAN_SLICE_MS) {
await new Promise<void>(resolve => setTimeout(resolve, 0));
throwIfAborted(options.signal);
lastYieldAt = performance.now();
}
if (!visit(bytes, offset)) unreadableOffsets.push(offset);
}
return unreadableOffsets;
};

const entries: PersistedUsageEntry[] = [];
const captured = createHash("sha256");
const unreadableOffsets = walk((bytes, offset) => {
const unreadableOffsets = await walk((bytes, offset) => {
captured.update(bytes);
captured.update("\0");
captured.update(String(offset));
Expand All @@ -660,7 +672,8 @@ export async function readUsageLedgerRowsAtOffsets(
// normalizes means the ledger moved under the projection, so it is unreadable rather than
// silently dropped: the caller rebuilds instead of reporting a smaller complete result.
if (!entry) return false;
entries.push(entry);
if (options.onEntry) options.onEntry(entry, offset);
else entries.push(entry);
return true;
});
const capturedDigest = captured.digest("hex");
Expand All @@ -675,6 +688,7 @@ export async function readUsageLedgerRowsAtOffsets(
if (!pathRevision || usageLogIdentityKey(pathRevision) !== options.expectedIdentityKey) {
throw rebuildRequired("identity_mismatch");
}
if (pathRevision.size < size) throw rebuildRequired("shrink");
// Any write during the read can be an in-place rewrite, not just an append. Re-read the
// same offsets and compare, so a rewrite that lands between two batches cannot publish a
// mixture of old and new rows. A pure append leaves every selected row unchanged.
Expand All @@ -686,8 +700,11 @@ export async function readUsageLedgerRowsAtOffsets(
if (physical !== undefined && endingRevision.size <= physical) {
throw rebuildRequired("content_changed");
}
// Verification must read the file again, not re-hash a small page still in the read cache.
windowStart = -1;
windowLength = 0;
const verified = createHash("sha256");
const recheck = walk((bytes, offset) => {
const recheck = await walk((bytes, offset) => {
verified.update(bytes);
verified.update("\0");
verified.update(String(offset));
Expand All @@ -697,7 +714,24 @@ export async function readUsageLedgerRowsAtOffsets(
|| verified.digest("hex") !== capturedDigest) {
throw rebuildRequired("content_changed");
}
const verifiedFdRevision = revisionFromStat(path, fd, fstatSync(fd));
const verifiedPathRevision = currentUsageLogRevision();
if (!verifiedPathRevision
|| usageLogIdentityKey(verifiedFdRevision) !== options.expectedIdentityKey
|| usageLogIdentityKey(verifiedPathRevision) !== options.expectedIdentityKey) {
throw rebuildRequired("identity_mismatch");
}
if (verifiedFdRevision.size < size || verifiedPathRevision.size < size) {
throw rebuildRequired("shrink");
}
// Verification yields too. A later write could change bytes already checked, so retry
// rather than publish a result whose verification raced another mutation.
if (usageLogRevisionKey(verifiedFdRevision) !== usageLogRevisionKey(endingRevision)
|| usageLogRevisionKey(verifiedPathRevision) !== usageLogRevisionKey(pathRevision)) {
throw rebuildRequired("content_changed");
}
}
throwIfAborted(options.signal);
return { entries, unreadableOffsets };
} finally {
closeSync(fd);
Expand Down
2 changes: 1 addition & 1 deletion structure/dashboard-and-usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,7 +340,7 @@ is treated as an append: the scanner verifies the previous LF and its trailing 6
folds only the suffix into a cloned accumulator and publishes it after validation. Concurrent callers
share that work. Cold rebuilds and append scans read fixed-size chunks, yield between chunks after a full
chunk or 1,000 rows, and yield between rows once 8 ms have passed, including within the final chunk, then recheck cancellation. This keeps costly normalization and
aggregation cooperative; one row remains atomic. The first read is proportional to ledger size; later refreshes hash the bounded retained window once and parse only the appended suffix, rather than rescanning the whole ledger. `tests/usage/usage-ledger-scanner.test.ts` covers slow-row scheduling and cancellation.
aggregation cooperative; one row remains atomic. Indexed candidate reads use the same time slice for decoding and direct accumulator callbacks within each page, including cooperative content verification before publication. The first read is proportional to ledger size; later refreshes hash the bounded retained window once and parse only the appended suffix, rather than rescanning the whole ledger. `tests/usage/usage-ledger-scanner.test.ts` covers slow-row scheduling, cancellation and validation across yields.
The Dashboard polls its 30-day usage independently once per minute, separate from five-second state polls.
An unchanged retained snapshot reuses its verified region digest only for identical bounds; appends or trimming hash the returned region, preserving same-inode rewrite detection.
> Decision record: [ADR-0102](decisions/ADR-0102-incremental-stream-accounting.md)
Expand Down
9 changes: 7 additions & 2 deletions structure/usage-client-attribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,17 @@ row offset during ingest, and `readUsageLedgerRowsAtOffsets` re-reads only the s
same identity, row-ceiling and torn-suffix rules. The first filtered query after the index is missing
or invalid pays one cooperative full ingest; appends ingest only new bytes, and every later filter
reuses the projection. Candidate offsets are selected and consumed in bounded keyset pages, with a
timer yield between pages; each page rechecks the published generation before it is read, so broad
filters neither retain the complete offset set nor monopolize the event loop. A replaced, truncated
timer yield between pages; each page rechecks the published generation before it is read. Within a
page, decoding and accumulation share the scanner's 8 ms cooperative slice, with one row atomic and
cancellation checked after yielding. The accumulator consumes rows directly instead of retaining a
page of parsed entries. A replaced, truncated
or same-size rewritten ledger rebuilds it, a write
observed during a row read re-verifies the selected bytes before publishing them, and a recorded
offset that no longer frames a complete row drops the projection instead of serving a partial
answer. `usage.jsonl` stays authoritative and is never truncated or rewritten.
Row callbacks are provisional until validation completes; failed rebuilds discard their accumulator
and failed appends discard their clone. A verification pass clears the cached read window, yields
between rows, and rejects identity, size or revision changes during that pass before publication.

Each candidate page is one keyset statement per branch, and every branch index is ordered
`(generation, <equality prefix>, byte_offset, ...)` so its own `ORDER BY byte_offset LIMIT` is
Expand Down
38 changes: 38 additions & 0 deletions tests/usage/usage-aggregate-cache.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import {
import type { OcxConfig } from "../../src/types/config";
import { resetUsageReadCacheForTests, type PersistedUsageEntry } from "../../src/usage/log";
import * as usageLedgerScannerModule from "../../src/usage/ledger-scanner";
import * as usageSummaryModule from "../../src/usage/summary";
import { getUsageSourceFacets, SourceFacetsBusyError } from "../../src/server/management/usage-source-facets";
import { refreshUserCostOverlays } from "../../src/usage/user-cost-overlays";
import { buildRouteDecisionTrace } from "../../src/routing/trace";
Expand Down Expand Up @@ -81,6 +82,43 @@ afterEach(() => {
});

describe("retained usage aggregate cache", () => {
test("costly accumulator work yields within one indexed candidate page", async () => {
const count = 40;
writeFileSync(join(testDir, "usage.jsonl"), Array.from({ length: count }, (_, index) => line(`costly-${index}`)).join(""));
// Build the shared index with another filter so ingestion cannot supply the observed yield.
const warm = await getFilteredUsageAggregate({ provider: "anthropic" });
expect(warm.filterIndex).toMatchObject({ totalRows: count, candidateRows: 0 });
let elapsed = 0;
let visited = 0;
let visitedAtTimer = -1;
let timer: ReturnType<typeof setTimeout> | undefined;
const original = usageSummaryModule.createUsageSummaryAccumulator;
const clock = spyOn(performance, "now").mockImplementation(() => elapsed);
const create = spyOn(usageSummaryModule, "createUsageSummaryAccumulator").mockImplementation(options => {
const accumulator = original(options);
const add = accumulator.add.bind(accumulator);
accumulator.add = value => {
add(value);
visited += 1;
elapsed += 10;
if (timer === undefined) timer = setTimeout(() => { visitedAtTimer = visited; }, 0);
};
return accumulator;
});
try {
const result = await getFilteredUsageAggregate({ provider: "openai" });
expect(result.filterIndex).toMatchObject({ totalRows: count, candidateRows: count });
expect(visited).toBe(count);
expect(visitedAtTimer).toBeGreaterThan(0);
expect(visitedAtTimer).toBeLessThan(count);
expect(result.accumulator.summarize("all", NOW).summary).toMatchObject({ requests: count, totalTokens: count * 2 });
} finally {
if (timer !== undefined) clearTimeout(timer);
create.mockRestore();
clock.mockRestore();
}
});

test("app breakdowns survive filtered cache appends and match fresh scans", async () => {
const path = join(testDir, "usage.jsonl");
const row = (id: string, client: "codex_cli" | "claude_code", apiKeyId: string) => ({ ...entry(id), client, apiKeyId });
Expand Down
Loading
Loading