sagarithm-kit / rules

<!-- SAGARITHM:START - DO NOT EDIT DIRECTLY -->
---
description: "Diagnose and eliminate performance bottlenecks, CPU hotspots, memory leaks, event-loop lag, and sub-optimal algorithmic complexity."
globs: ["**/*"]
alwaysApply: false
---

# Systems Performance & Profiling Engineering

# Systems Performance & Profiling Engineering

## Overview
This skill embodies the rigor of a Staff Performance Engineer and Systems Profiling Specialist. It provides deterministic methodologies for identifying latency bottlenecks, eliminating $O(N^2)$ algorithmic traps, and preventing memory leaks before they manifest in production.

## 🎯 Token Conservation & High-Yield Heuristics
1. **Empirical Benchmarks First**: Never optimize speculatively. Always obtain a baseline metric before refactoring (`console.time`, `process.hrtime`, or `Benchmark.js`) and demonstrate statistically significant improvement ($p < 0.05$).
2. **Minimal Diff Footprint**: Performance optimizations must target only hot inner loops identified by profiling. Avoid broad rewrites that increase regression blast radius.

## 📐 Core Engineering Directives

### 1. Algorithmic Complexity Governance
- **Eliminate $O(N^2)$ Nested Loops**: Replace nested loop searches (`array.filter(a => otherArray.some(b => b.id === a.id))`) with $O(1)$ Hash Map / `Set` lookups:
  ```typescript
  // Convert lookup list to Set for O(1) membership testing
  const validIds = new Set(otherArray.map(b => b.id));
  const filtered = array.filter(a => validIds.has(a.id)); // O(N + M) vs O(N * M)
  ```
- **Stream Large Datasets**: Never load gigabyte-scale datasets or large files into a single in-memory array (`fs.readFileSync`). Use Node.js Streams (`fs.createReadStream`, `stream/promises`, or pipeline transforms) to process records with bounded $O(1)$ memory usage.

### 2. Runtime Profiling & Memory Leak Detection
- **Event-Loop Lag**: In Node.js, long-running synchronous operations block the event loop, stalling all concurrent HTTP requests. Break long-running CPU loops into chunks using `setImmediate()` or worker threads (`node:worker_threads`).
- **Memory Leak Patterns**:
  - **Dangling Event Listeners**: Always call `removeListener()` / `abortSignal.removeEventListener()` when tearing down objects.
  - **Unbounded In-Memory Caches**: Never use raw JavaScript objects or unbounded arrays as caches. Always enforce an explicit Maximum Size and Least-Recently-Used (LRU) eviction policy.
  - **Closures Retaining Large Outer Scopes**: Avoid capturing large buffers or DOM trees inside long-lived callback closures.
- **Heap Snapshot Diagnostics**: Compare baseline heap snapshots with post-load snapshots to detect retained detached objects.

### 3. Network & Payload Optimization
- **Payload Compression**: Ensure HTTP compression (`brotli`, `gzip`) is enabled on all responses over $1\text{KB}$.
- **Bundle Splitting & Tree-Shaking**: Use dynamic `import()` for heavy client-side dependencies (charts, syntax highlighters, PDF generators) to keep initial JavaScript bundles under $150\text{KB}$ gzipped.
- **HTTP Caching Directives**: Set deterministic `Cache-Control` headers:
  - Static hashed assets (`main.[hash].js`): `public, max-age=31536000, immutable`.
  - Dynamic API responses: `private, no-cache, must-revalidate` or `stale-while-revalidate`.

## 🛑 Anti-Rationalization Matrix

| Agent Excuse / Shortcut | Performance Reality | Mandatory Action |
|---|---|---|
| *"Premature optimization is the root of all evil, so I didn't optimize this nested loop."* | Writing $O(N^2)$ operations where an $O(N)$ map lookup is natural is not avoiding premature optimization; it is gross inefficiency that crashes servers when dataset sizes grow. | Use Sets and Maps for associative lookups as standard practice. |
| *"I'll just read the whole 500MB file into memory with `readFileSync`."* | Exhausts Node.js heap limit (`ERR_STRING_TOO_LONG` or V8 OOM crash) and starves system memory. | Use streaming pipelines (`createReadStream` with readline or transform streams). |
| *"I made changes that should feel much faster."* | Speculative assertion. Perceived speed is subjective and often illusory. | Measure execution duration with microsecond precision before and after changes. |
| *"I'll store user sessions in an in-memory object."* | Unbounded memory growth, leaks memory on disconnected clients, and fails multi-instance horizontal scaling. | Store state in a bounded external store (Redis) with explicit TTL expiration. |

## ✅ Performance Verification Checklist
- [ ] No $O(N^2)$ complexity in loops processing dynamic user collections.
- [ ] File and network operations use streaming for payloads $> 10\text{MB}$.
- [ ] All caches enforce bounded capacity with LRU eviction and TTL.
- [ ] Event listeners and timeouts are cleaned up on teardown.
- [ ] Empirical execution time benchmarks confirm zero regressions.
<!-- SAGARITHM:END -->