Skip to content

fix(usage): yield within indexed row decoding and aggregation - #819

Closed
luvs01 wants to merge 1 commit into
devfrom
fix/usage-index-cooperative-row-processing
Closed

luvs01 wants to merge 1 commit into
devfrom
fix/usage-index-cooperative-row-processing

Conversation

@luvs01

@luvs01 luvs01 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

Filtered usage reports already page candidate offsets in groups of 2,000, but decoding and normalizing every row, then folding the whole page into the accumulator, still run synchronously. A page with multi-attempt usage rows can delay other requests and timer-delivered cancellation even though the complete offset set is bounded.

This follows up #816 and the upstream paging fix for the remaining scheduling portion of the Daybreak finding.

  • Apply the existing 8 ms cooperative slice inside indexed row decoding and callback work; one row remains atomic.
  • Fold rows directly into the private accumulator without retaining a parsed page. Callers without the optional callback retain the existing returned-array contract.
  • Preserve cancellation and callback errors, close descriptors on failure, clear the cached read window before verification, and reject identity, shrinkage, or revision changes during a yielding verification pass. Partial accumulators remain unpublished and are discarded by the existing retry paths.
  • Update the usage contracts and add twelve regression cases covering the reader and the production aggregate path.

Verification

Tested with Bun 1.4.4 against fork dev at 1d10758fa6ced80cdd780cb000bc5c4b83f84703.

  • bun run test:changed tests/usage/usage-ledger-scanner.test.ts tests/usage/usage-filter-index.test.ts tests/usage/usage-filter-paging.test.ts tests/usage/usage-aggregate-cache.test.ts tests/server/api-usage.test.ts --timeout 30000 — 175 passed, 0 failed, 913 assertions across five files.
  • bun run typecheck — no type errors in 2,533 files.
  • bun run structure:check and bun run privacy:scan — passed.
  • bun test tests/ci-workflows/file-size-ratchet.test.ts --timeout 30000 — 9 passed, 0 failed.
  • git diff --cached --check — passed.
  • The new tests were also exercised against the unchanged base in an isolated worktree: the compatibility case passed, while the other eleven cases failed. In the production scheduling regression, the old implementation ran the timer only after all 40 rows were folded; the fix permits it to observe partial progress with identical totals.
  • A local synthetic 2,000-row ledger with 32 valid attempts per row (13.44 MB) reproduced about 148 ms of synchronous decoding plus 106 ms of synchronous aggregation before the fix. After the fix, the combined read/fold allowed the timer to run during processing, consumed all 2,000 rows, and retained no returned entries. These are scheduling observations on one host, not a throughput claim.
  • Independent review checked callback compatibility, provisional accumulator disposal, and file-mutation races.

The full repository suite and macOS/Windows runs were not executed: the repository-wide provider/platform suites are disproportionate to this two-function read/aggregation change. This draft uses the documented scoped-validation exception; coverage includes real local management API calls, paging/rebuild behavior, and all added regressions. CI results for this PR head remain to be observed. Continuous writes during verification conservatively cause the existing bounded retry instead of publishing uncertain totals.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Devin Review

Summary by CodeRabbit

  • Performance
    • Long-running usage calculations now yield periodically, helping keep the interface responsive while records are processed.
  • Bug Fixes
    • Usage summaries are validated against changes to the underlying records before results are published, helping prevent incomplete or outdated results.
  • Documentation
    • Updated guidance to describe processing behavior and validation during usage scans.

Stream indexed rows into the private accumulator under the existing cooperative
slice and honor cancellation within a candidate page. Revalidate fresh bytes
and stable file identity after any yielding verification pass.

Add regression coverage for scheduling, aborts, compatibility, and file mutations.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The usage-ledger reader now supports callback-based row consumption and yields during scanning and verification. It validates ledger identity, size, and revision before returning results. The aggregate cache accumulates candidate rows through the callback, with tests covering scheduling, cancellation, and ledger mutations.

Changes: Usage ledger scanning

Layer / File(s) Summary
Callback-based row folding
src/usage/ledger-scanner.ts, tests/usage/usage-ledger-scanner.test.ts, structure/dashboard-and-usage.md
The reader passes decoded rows to onEntry when provided; otherwise, it returns rows in entries. It yields after the scan time slice, including visitor work. Tests cover callback behavior, cancellation, ordering, and yielding.
Mutation verification
src/usage/ledger-scanner.ts, tests/usage/usage-ledger-scanner.test.ts, structure/usage-client-attribution.md
The reader clears its cached window before verification and checks identity, size, and revision after the verification walk. Tests cover replacement, shrinkage, rewrites, appends, and cancellation.
Aggregate cache integration
src/server/management/usage-aggregate-cache.ts, tests/usage/usage-aggregate-cache.test.ts
The aggregate cache accumulates candidate rows through onEntry instead of processing a retained page. A test checks timer progress during costly accumulation and verifies the aggregate totals.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant UsageAggregateCache
  participant LedgerScanner
  participant LedgerFile
  participant Scheduler
  UsageAggregateCache->>LedgerScanner: Read selected rows with onEntry callback
  LedgerScanner->>LedgerFile: Read and decode selected rows
  LedgerScanner-->>UsageAggregateCache: Pass each decoded row to onEntry
  LedgerScanner->>Scheduler: Yield after the scan time slice
  LedgerScanner->>LedgerFile: Re-read selected rows for verification
Loading

Suggested reviewers: lidge-jun, ingwannu

Merge Risk: Minimal · up to 1743a

This change makes filtered usage reports yield during row decoding and aggregation while preserving cancellation, error propagation and descriptor cleanup. It also rejects ledger changes detected while verification yields. No concrete defect was found, so it looks safe to merge once CI passes.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: indexed row decoding and aggregation now yield cooperatively. It is specific, follows the conventional commit form, and matches the raw summary and objectives, which d…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: indexed row decoding and aggregation now yield cooperatively. It is specific, follows the conventional commit form, and matches the raw summary and objectives, which describe an 8 ms cooperative slice applied to decoding, accumulator callbacks, and verification.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 1d10758 and 1743a93.

Files selected for processing: 6

  • src/server/management/usage-aggregate-cache.ts
  • src/usage/ledger-scanner.ts
  • structure/dashboard-and-usage.md
  • structure/usage-client-attribution.md
  • tests/usage/usage-aggregate-cache.test.ts
  • tests/usage/usage-ledger-scanner.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@github-actions

Copy link
Copy Markdown

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 16, 2026

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@luvs01

luvs01 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner Author

No description provided.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant