perf(backend): avoid full-snapshot parsing on unchanged empty-tail polls

Open
#2,479 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
node.js, typescript

Research direction

Start in packages/squad-sdk/src/backend/local-backend.ts: the readEvents filtering and slicing around lines 552-569, and the snapshot loading in load() around lines 878-903. Reproduce the empty-tail poll (readEvents with after set to the current tail and limit 1) against a built copy, and count how often the full snapshot is deserialized. Done means an unchanged poll performs zero full deserializations, with the external-append, restart and corrupted-persistence cases still passing and the benchmark evidence the issue asks for.

Written by the indexing model from the issue text.

Description

Summary

The local file backend reads/parses the complete conversation snapshot before filtering/slicing readEvents results. A one-event request and an empty-tail poll therefore scale with the full conversation history rather than the requested page.

Proposed primary owner: sdk-runtime-dev.

Baseline evidence

Revision: 47082a81799710c3e457b594123d190c00596ebf, observed 2026-11-12.

Code: local-backend.ts:552-569, and snapshot loading at lines 878-903.

Independent source-function repeat:

History events p50, one-event tail page p50, empty-tail poll
100 0.110 ms 0.110 ms
1,000 0.849 ms 0.849 ms
10,000 9.353 ms 9.203 ms

Fixture: production local file-state backend, synthetic valid event/cursor sequence, after cursor and limit: 1, returning either the final event or no events. At 10,000 events the complete snapshot is 5,795,874 bytes. Assertions verified count, final sequence and resumability. A separate diagnostic CPU profile identified load() as the dominant sampled path; profiling was outside these timing runs.

Environment: Apple M4 arm64, 16 GiB, Darwin 25.6, Node 24.15.0; three rounds of ten sequential observations per case, two warmups, warm filesystem caches, setup/imports outside timing, rotated/reversed case order. Unmodified TypeScript methods ran through Node's built-in transformation and isolated relative-import resolution.

Limit: locked restoration failed with a configured-feed E404, blocking packaged build/tests. These are source-function diagnostics without a real harness/model, not application-throughput or optimization gains. Reproduce through the built path and publish portable fixtures/raw evidence before accepting a change.

Scope

Parent: github/squad#2481.

One hot path: repeated unchanged readEvents(after=current-tail, limit=1) calls against the local file-state backend. A one-event page is a correctness/control case, not a second optimization requirement. No public cursor redesign, harness/model changes, new storage backend or broad event-store rewrite.

Measurable acceptance and tests

For an optimization, use at least three interleaved built-baseline/change rounds with at least 30 observations per case per round; publish raw observations, per-round p50/p95, exact SHA/environment and correctly labeled CPU/I/O/memory evidence. The budgets below are proposed acceptance targets, not already-demonstrated gains. If a safe material win cannot be reproduced, record rejection/defer rather than broaden the implementation to chase the target.

  • Fixed histories: 100/1,000/10,000 valid events. Measure repeated empty-tail polls and a single newly appended event using the same cursor contract.
  • After initial hydration, an unchanged empty-tail poll must perform zero full conversation-snapshot deserializations. Instrument and assert that count separately from timing.
  • Target at least 25% lower p50 at 10,000 events than the same built baseline; publish p95, bytes read/parsed, CPU and retained heap at every size.
  • Append an event from another process, then verify the next poll observes it with the exact sequence/cursor/resumability contract. Include stream/limit controls and restart replay.
  • Test corrupted persistence, epoch/fencing change and cancellation/approval boundaries affected by the implementation. Preserve explicit errors and durable recovery; no stale or successful partial state.
  • If caching/indexing is used, assert bounded retained state and invalidation on external change/restart. Initial/recovery loads may parse fully but must be labeled separately from steady-state polls.
  • Publish a portable built-path fixture and before/after results; keep implementation limited to this polling path and necessary correctness plumbing.

Related work

The backend/harness implementation in github/squad#2451 is related prior art, not evidence of bounded polling performance. A fresh open-issue search found no focused readEvents performance duplicate.

Methodology: dotnet/aspnetcore#70219 and microsoft/waza#846.

Dominant language
TypeScript
Stars
3.4k
Forks
516
Avg merge
1d 15h
Merged PRs (30d)
116

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/squad

All issues in github/squad

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.