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

Ouverte
#2,479 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
25/100
Type d'issue
Refactorisation
Clarté
Plutôt claire
Activité
Active
Stack technique
node.js, typescript
Domaine
backend, performance

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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.

Langage dominant
TypeScript
Étoiles
3.4k
Forks
516
Merge moyen
1 j 15 h
PR mergées (30 j)
116

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de github/squad

Toutes les issues de github/squad

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.