fix(server): release consumed event replay pages

[Gigioxx]

Nightly 1400 runs attachment cleanup over the full event history at startup. The event store recursively concatenated 500-row pages, keeping consumed pages alive until replay finished. Large histories exhausted the backend heap before cleanup could save progress.

Use Stream.paginate for both global and aggregate replay so only the cursor and remaining limit carry between pages. Full catch-up, ordering, limits, decoding errors, captured heads, and cleanup retries keep their existing behavior. No new dependencies, API changes, or data migration.

Reproduced both readers retaining a consumed page before the change. The new regression tests use V8's post-GC object counts rather than memory-size or timing thresholds. All 67 focused event-store, projection-pipeline, and orchestration-engine tests pass, as do server typecheck and scoped lint/format checks.

On an isolated copy of the affected 1,131,083-event database (3.44 GB of payload), cleanup completed in 40 seconds under a 1 GiB heap cap and advanced its cursor from zero to the head. A second bootstrap took under 1 ms; all 586 threads and all events remained present. This exercised the real startup projection pipeline, not the Electron UI. The installed app and live data were untouched.

Closes #10774.

Created with GPT-6 Astra in Codex.

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability when reading large event histories by releasing consumed replay pages promptly, helping reduce memory usage during extended processing.
  • Event streams can be safely collected more than once with consistent results.
  • Invalid negative limits now return an empty result instead of attempting to read events.

• Performance

  • Stream pagination was streamlined while preserving existing ordering and stopping behavior.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The server change is a narrowly scoped replay-pagination fix with tests covering both affected paths and page release behavior. Human review is required because the test adds a line-level oxlint suppression directive.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: bd782b86-b189-4752-9a49-394d27d10b0b

📥 Commits

Reviewing files that changed from the base of the PR and between 061543e and 04c157d.

📒 Files selected for processing (2)

• apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
• apps/server/src/persistence/Layers/OrchestrationEventStore.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The event store replaces recursive page concatenation with explicit pagination state. New tests verify reusable streams, negative-limit handling, and release of consumed pages during large replays.

Changes

Event pagination and retention

Layer / File(s)	Summary
Explicit event pagination apps/server/src/persistence/Layers/OrchestrationEventStore.ts	readFromSequence and readAggregateRange use Stream.paginate with cursor and remaining state. Existing page and sequence termination conditions remain explicit.
Pagination and page-retention tests apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts	Tests verify repeated collection, negative limits, and release of consumed pages after a 1,501-event replay.

Priority: ⬆️ High — Prioritize the event-store pagination fix because replay from a 1.13-million-event history can exhaust startup memory and block attachment cleanup.

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

Severity of issue fixed: High

Merge Risk: ⚪ Minimal · up to 04c15

Event replay now releases consumed pages during large catch-up scans without changing replay limits or ordering. The change is covered by pagination and retention tests and is ready to merge.

Suggested reviewers: t3dotgg

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: releasing consumed event replay pages in the server.
Description check	✅ Passed	The description clearly explains the problem, implementation, preserved behavior, tests, and validation results. It does not use the template headings or include the checklist, but it contains the req…
Linked Issues check	✅ Passed	The changes satisfy issue #10774 by replacing retaining recursive pagination with Stream.paginate for global and aggregate replay while preserving catch-up, limits, ordering, decoding errors, and retr…
Out of Scope Changes check	✅ Passed	The changes are limited to the event-store pagination implementation and focused regression tests. No unrelated code, API, dependency, schema, or migration changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}