Long-running scan memory profiling + leak detection

[truthixify]

Labels: Stellar Wave, perf, test, drips, help-wanted
Tier: M (2–4 days)
Type: perf / test

Context

The Spectre TEE agent runs for months. Its scanner is the hottest code path. A small memory leak in the SDK becomes an OOM kill in production. We've never run the SDK's scan loop under a profiler to find out.

Scope

1. Build a long-running harness at test/leak/scan-leak.test.ts:
   • Calls scanAnnouncements (or scanAnnouncementsStream after #09) in a tight loop.
   • Synthetic dataset of 10k announcements; loop runs 10k iterations.
   • Captures heap snapshots at intervals via v8.writeHeapSnapshot (Node) or performance.memory (browser).
2. Detect leaks: compute slope of RSS over iterations. Fail if slope > N KB per iteration (tunable).
3. Profile hot paths — run the harness with --prof (V8 profiler) and clinic.js doctor. Capture flame graphs.
4. Identify and fix any leaks found. Common suspects:
   • Closures holding references to large buffers
   • Event listener accumulation
   • The cache layer (from #17) not evicting properly
   • Worker pool workers not being terminated
5. Add CI — the leak test runs nightly, fails on regression.

Specific things to check

• After scanAnnouncements returns, the input announcements array should be garbage-collectible — we shouldn't be holding onto it.
• After pool.scanAll returns, all worker threads must be terminated.
• The IndexedDB cache shouldn't grow without bound (it has a 50 MB cap per #17, verify enforcement).

Acceptance criteria

• Leak detection harness committed.
• Profiling outputs (flame graph PNG or HTML) committed.
• Any identified leaks fixed.
• CI nightly job.
• Documented "how to interpret the heap snapshot" guide for future debugging.

Why this matters

The TEE's job is privacy. The TEE crashing because the SDK leaks is a privacy failure that looks like a reliability failure. We should know our SDK is leak-clean before a real user notices.

Resources

• Node memory debugging: https://nodejs.org/en/docs/guides/diagnostics-flamegraph
• clinic.js: https://clinicjs.org/

[israelolrunfemi]

@israelolrunfemi has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hey, I'd like to pick this up.

I've been building Node.js/TypeScript backends for a while and have dealt with long-running process memory issues firsthand — most recently on a TEE-based trading agent (GhostTrader) where keeping the process alive across sessions was a hard requirement. I'm comfortable with V8 heap profiling, v8.writeHeapSnapshot, and clinic.js doctor for flame graph capture.

For this issue, my plan:

Harness (test/leak/scan-leak.test.ts)

• Synthetic dataset of 10k announcements, 10k iterations tight loop
• Heap snapshots at configurable intervals via v8.writeHeapSnapshot
• RSS slope computation — fail if slope exceeds configurable KB/iteration threshold

Leak suspects I'll specifically target

• Input announcement array reachability after scanAnnouncements returns (WeakRef-based check or post-call GC + snapshot diff)
• Worker thread termination audit after pool.scanAll
• Cache eviction enforcement — verify the 50 MB cap from Tree-shaking audit + per-chain bundle size budget #17 is actually enforced under churn
• Event listener accumulation (will instrument EventEmitter.listenerCount across iterations)

Profiling outputs

• --prof + node --prof-process tick log
• clinic.js doctor HTML report + flame graph PNG, both committed to test/leak/profiles/

CI

• Nightly GitHub Actions job, separate from the main test suite, with a clear fail message pointing to the heap snapshot guide

Docs

• "How to interpret heap snapshots" markdown guide covering retained size vs shallow size, the dominators view, and how to read the slope metric

I can start immediately. Any preferences on the slope threshold default (e.g. 1 KB/iter) or snapshot interval before I open the PR?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @israelolrunfemi to this issue.

[drips-wave]

Congratulations, @israelolrunfemi! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @israelolrunfemi: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊