coding-os 0.3.2__py3-none-any.whl

core/skills/mobile-fundamentals/references/offline-sync.md

@@ -0,0 +1,339 @@
+# Offline Sync — Queue, Retry, Conflict Resolution
+
+The pattern that makes a mobile app feel reliable when the network is anything less than great.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  React component                                                    │
+│   useUseCase('markLessonComplete').execute(input)                   │
+└──────────────────┬──────────────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Use case (application layer)                                       │
+│   1. Update LocalCache  ─────►  Re-render via useQuery cache hook   │
+│   2. Enqueue Mutation   ─────►  SyncQueue.enqueue(...)              │
+│   3. Return immediately (no await on network)                        │
+└──────────────────┬──────────────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Sync queue (durable, MMKV / SQLite)                                │
+│   FIFO of pending mutations with idempotency keys                    │
+│   Background worker drains when network is up                        │
+└──────────────────┬──────────────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  Server (eventually consistent)                                     │
+│   Receives mutation with Idempotency-Key header                     │
+│   Returns canonical state                                           │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## The Sync Queue — Schema
+
+Use SQLite or MMKV. SQLite preferred for >1000 entries or query needs.
+
+```sql
+-- mobile/app database (SQLite via op-sqlite or react-native-quick-sqlite)
+CREATE TABLE sync_queue (
+  id                  TEXT PRIMARY KEY,
+  type                TEXT NOT NULL,          -- 'lesson.complete', 'message.send', ...
+  payload             TEXT NOT NULL,          -- JSON-serialized command
+  idempotency_key     TEXT NOT NULL UNIQUE,
+  created_at          TEXT NOT NULL,          -- ISO8601
+  next_attempt_at     TEXT NOT NULL,          -- ISO8601, advanced on backoff
+  attempts            INTEGER NOT NULL DEFAULT 0,
+  last_error          TEXT,
+  state               TEXT NOT NULL DEFAULT 'pending'  -- 'pending' | 'failed' | 'sent'
+);
+CREATE INDEX idx_sync_queue_pending ON sync_queue(next_attempt_at) WHERE state = 'pending';
+```
+
+```typescript
+// mobile/src/infrastructure/sync/SyncQueueSqlite.ts
+import { open, type DB } from '@op-engineering/op-sqlite';
+
+import type { SyncQueue, QueuedMutation } from '@application/ports/syncQueue';
+
+export class SyncQueueSqlite implements SyncQueue {
+  constructor(private db: DB) {}
+
+  async enqueue(m: Omit<QueuedMutation, 'id' | 'state' | 'attempts' | 'last_error' | 'next_attempt_at'>): Promise<void> {
+    await this.db.execute(`
+      INSERT INTO sync_queue (id, type, payload, idempotency_key, created_at, next_attempt_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `, [
+      crypto.randomUUID(),
+      m.type,
+      JSON.stringify(m.payload),
+      m.idempotency_key,
+      m.created_at,
+      m.created_at,
+    ]);
+  }
+
+  async dequeueBatch(now: string, limit: number): Promise<QueuedMutation[]> {
+    const rows = await this.db.executeAsync(`
+      SELECT * FROM sync_queue
+      WHERE state = 'pending' AND next_attempt_at <= ?
+      ORDER BY created_at ASC
+      LIMIT ?
+    `, [now, limit]);
+    return rows.rows._array.map(parseRow);
+  }
+
+  async markSent(id: string): Promise<void> {
+    await this.db.execute('UPDATE sync_queue SET state = "sent" WHERE id = ?', [id]);
+  }
+
+  async markFailed(id: string, error: string, retryDelayMs: number | null): Promise<void> {
+    if (retryDelayMs === null) {
+      await this.db.execute('UPDATE sync_queue SET state = "failed", last_error = ? WHERE id = ?', [error, id]);
+    } else {
+      const next = new Date(Date.now() + retryDelayMs).toISOString();
+      await this.db.execute(`
+        UPDATE sync_queue
+        SET attempts = attempts + 1, last_error = ?, next_attempt_at = ?
+        WHERE id = ?
+      `, [error, next, id]);
+    }
+  }
+}
+```
+
+## The Worker
+
+```typescript
+// mobile/src/infrastructure/sync/SyncWorker.ts
+import NetInfo from '@react-native-community/netinfo';
+import { AppState } from 'react-native';
+
+import type { SyncQueue } from '@application/ports/syncQueue';
+import type { ApiClient } from '../http/apiClient';
+
+const BACKOFF_MS = [
+  0, 1_000, 5_000, 15_000, 60_000, 5 * 60_000, 30 * 60_000,
+  60 * 60_000, 4 * 3600_000, 24 * 3600_000,
+];
+const MAX_ATTEMPTS = BACKOFF_MS.length;
+
+const HANDLERS: Record<string, (api: ApiClient, payload: unknown, key: string) => Promise<void>> = {
+  'lesson.complete': async (api, payload, idempotencyKey) => {
+    await api.post('/lessons/complete', payload, {
+      headers: { 'Idempotency-Key': idempotencyKey },
+    });
+  },
+  'message.send': async (api, payload, idempotencyKey) => {
+    await api.post('/messages', payload, {
+      headers: { 'Idempotency-Key': idempotencyKey },
+    });
+  },
+  // ... add per mutation type
+};
+
+export class SyncWorker {
+  private running = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private queue: SyncQueue, private api: ApiClient) {}
+
+  start() {
+    this.scheduleNext(0);
+    NetInfo.addEventListener((state) => {
+      if (state.isConnected) this.scheduleNext(0);
+    });
+    AppState.addEventListener('change', (s) => {
+      if (s === 'active') this.scheduleNext(0);
+    });
+  }
+
+  private scheduleNext(delayMs: number) {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.tick(), delayMs);
+  }
+
+  private async tick() {
+    if (this.running) return;
+    this.running = true;
+    try {
+      const now = new Date().toISOString();
+      const batch = await this.queue.dequeueBatch(now, 10);
+      if (batch.length === 0) {
+        this.scheduleNext(60_000);
+        return;
+      }
+      for (const m of batch) {
+        await this.process(m);
+      }
+      this.scheduleNext(1000);  // immediately try next batch
+    } catch (e) {
+      this.scheduleNext(30_000);
+    } finally {
+      this.running = false;
+    }
+  }
+
+  private async process(m: QueuedMutation) {
+    const handler = HANDLERS[m.type];
+    if (!handler) {
+      await this.queue.markFailed(m.id, `unknown type ${m.type}`, null);
+      return;
+    }
+    try {
+      await handler(this.api, m.payload, m.idempotency_key);
+      await this.queue.markSent(m.id);
+    } catch (err: any) {
+      const retryable = isRetryable(err);
+      if (!retryable || m.attempts >= MAX_ATTEMPTS - 1) {
+        await this.queue.markFailed(m.id, String(err?.message || err), null);
+        // TODO: surface to UI as "couldn't sync — review"
+      } else {
+        const delay = BACKOFF_MS[Math.min(m.attempts + 1, BACKOFF_MS.length - 1)];
+        const jittered = delay + Math.floor(Math.random() * delay * 0.2);
+        await this.queue.markFailed(m.id, String(err?.message || err), jittered);
+      }
+    }
+  }
+}
+
+function isRetryable(err: any): boolean {
+  if (!err?.response) return true;            // network/timeout
+  const status = err.response.status;
+  if (status >= 500) return true;
+  if (status === 429) return true;
+  if (status === 408) return true;
+  return false;                                // 4xx terminal
+}
+```
+
+## Key Properties
+
+- **Idempotency-Key on every mutation** — server dedup (see api-design skill).
+- **Exponential backoff with jitter** — avoids thundering herd on reconnect.
+- **Max attempts** — terminal failure surfaces to UI; do not retry forever.
+- **Drains on AppState=active and network=connected** — react to events, don't poll aggressively.
+- **No global flush on logout** — abandoning the queue can lose user work; either await drain or warn the user.
+
+## Conflict Resolution
+
+When the server's state and your queued mutation disagree, three strategies. Pick per mutation type, never per-app.
+
+### 1. Last-Write-Wins (LWW)
+
+Simplest. Server takes the latest mutation's value. Used for: cosmetic changes (display name, theme), single-user data with no merge concerns.
+
+```
+client mutation: name = "Alice"   timestamp 12:00
+server state:    name = "Bob"     last_modified 12:01
+→ server keeps "Bob" (newer)
+```
+
+LWW requires the server to track `updated_at`. Client sends with `If-Unmodified-Since` (or no precondition; server simply takes whichever request has a higher mutation timestamp).
+
+### 2. Server-Wins (Reject + Surface)
+
+Server compares the client's expected version with current; if mismatch, returns 409 with current state. Client surfaces to user: "your changes conflict — resolve".
+
+Used for: shared resources, payment edits, anything where silent overwrites cause data loss.
+
+```
+PATCH /lessons/lsn_123
+If-Match: "v3"
+{ "title": "Old name" }
+
+→ 412 Precondition Failed
+  { "code": "version_conflict", "current": { "version": "v5", "title": "Newer name" } }
+
+Client: shows the conflict UI; user picks "keep mine" / "keep theirs" / merge manually.
+```
+
+### 3. CRDT / Merge
+
+For collaborative editing (chat reactions, shared lists). Library: Yjs, Automerge.
+
+Heavy machinery; only use if you genuinely need real-time collab. For "single-user offline app", LWW + 412 conflicts is enough.
+
+## Cache Invalidation on Sync
+
+After a mutation succeeds:
+
+```typescript
+import { useQueryClient } from '@tanstack/react-query';
+
+// In the worker after markSent:
+queryClient.invalidateQueries({ queryKey: ['lesson', payload.lessonId] });
+```
+
+Or use TanStack Query's `useMutation` directly when the call is online:
+
+```typescript
+const mutation = useMutation({
+  mutationFn: (input) => markLessonComplete.execute(input),
+  onMutate: async (input) => {
+    // Optimistic: update local state.
+    await queryClient.cancelQueries({ queryKey: ['lesson', input.lessonId] });
+    const prev = queryClient.getQueryData(['lesson', input.lessonId]);
+    queryClient.setQueryData(['lesson', input.lessonId], (old: Lesson) => ({
+      ...old, state: 'completed',
+    }));
+    return { prev };
+  },
+  onError: (_err, input, context) => {
+    if (context?.prev) {
+      queryClient.setQueryData(['lesson', input.lessonId], context.prev);
+    }
+  },
+  onSettled: (_data, _err, input) => {
+    queryClient.invalidateQueries({ queryKey: ['lesson', input.lessonId] });
+  },
+});
+```
+
+## Showing Pending State
+
+Users want to know "did my action go through?". Show:
+
+- **Inline indicator** on items with pending mutations (small spinner or "syncing" badge).
+- **Global indicator** in the navbar showing offline state + pending count.
+- **Failure surface** for terminal failures: "couldn't sync — try again" with retry button.
+
+```typescript
+// useSyncStatus hook subscribes to queue state changes.
+const { pending, failed } = useSyncStatus();
+
+return (
+  <View style={styles.statusBar}>
+    {!isConnected && <Text>Offline</Text>}
+    {pending > 0 && <Text>Syncing {pending}…</Text>}
+    {failed > 0 && (
+      <Pressable onPress={() => navigation.navigate('SyncErrors')}>
+        <Text>{failed} couldn't sync</Text>
+      </Pressable>
+    )}
+  </View>
+);
+```
+
+## Common Sync Mistakes
+
+1. **No idempotency key** — retries become duplicates.
+2. **Naive retry without backoff** — DDoSes own server on reconnect.
+3. **Retrying 4xx** — wastes bandwidth on terminal failures; surface them.
+4. **No max-attempts** — failed mutations stuck in queue forever.
+5. **Sync queue not durable** — app kill = lost mutations.
+6. **No cache invalidation after success** — UI shows stale optimistic state.
+7. **Optimistic update without rollback path** — error → UI shows wrong state forever.
+8. **Drain on logout without warning** — user thought they saved, work is gone.
+9. **No conflict UI** — silent overwrites cost users their work.
+10. **Sync queue in main thread** — blocks UI while serializing payloads. Use a worker / async batches.
+
+## Source Material
+
+- "Designing Data-Intensive Applications" (Kleppmann) — chapter on conflict resolution.
+- TanStack Query docs — Optimistic updates, networkMode.
+- Yjs / Automerge docs — for CRDT use cases.
+- "Local-first software" — Ink & Switch (read for the philosophy, then back to your queue).

core/skills/node-backend/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: node-backend
+tier: stack
+domain: [backend]
+description: Build production Node.js backends — Express/Fastify/Nest, the event loop, async/await correctness, streams, graceful shutdown, and not blocking the single thread. Use when writing a Node HTTP service, debugging "the server hangs / is slow under load", handling errors in async code, streaming large payloads, managing the process lifecycle, or choosing a framework. Triggers — "node server", "Express", "Fastify", "NestJS", "event loop", "the API is slow", "unhandled rejection", "stream", "graceful shutdown", any backend `*.js`/`*.ts` with `http`/`express`. Pairs with typescript (typed Node), api-design (the contract), security-web (server hardening), observability (logging/metrics), performance (profiling).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# Node.js Backend
+
+Node runs your JavaScript on **one** thread with an event loop. It scales by never blocking that thread — every CPU-bound or sync call freezes *all* requests. The craft is async-correct code, streaming over buffering, and a clean process lifecycle.
+
+> Audit a package.json for engine pin, lockfile, and risky scripts:
+> `python3 scripts/check_package.py package.json`
+
+## Never block the event loop
+
+```javascript
+// Wrong — sync read blocks EVERY in-flight request until the file loads
+import { readFileSync } from "node:fs";
+app.get("/data", (req, res) => res.send(readFileSync("big.json")));
+
+// Correct — async yields the loop while I/O happens
+import { readFile } from "node:fs/promises";
+app.get("/data", async (req, res) => res.send(await readFile("big.json")));
+```
+
+`*Sync` calls, `JSON.parse` of a huge string, a tight `for` over a million items,
+synchronous crypto/zlib — all freeze the loop and tank p99 for every concurrent
+request. For genuine CPU work (image resize, hashing), offload to a Worker Thread
+or a separate service; don't compute it inline. Detail → [references/event-loop.md](references/event-loop.md).
+
+## Async errors must be caught — or the process dies
+
+```javascript
+// Wrong — a rejected promise in a handler with no catch → unhandledRejection
+app.get("/x", async (req, res) => { const u = await db.get(); res.json(u); });
+// (if db.get rejects, Express 4 doesn't catch async throws → hangs or crashes)
+
+// Correct — wrap, or use a framework that awaits handlers (Express 5 / Fastify do)
+app.get("/x", async (req, res, next) => {
+  try { res.json(await db.get()); } catch (e) { next(e); }
+});
+```
+
+In Express 4 an async handler that throws is **not** caught by the error
+middleware — you need a wrapper (`express-async-errors`) or per-handler
+try/catch. Express 5 and Fastify await handlers natively. Always register a
+top-level `process.on("unhandledRejection")` + `uncaughtException` that logs and
+exits — a silent rejection corrupts state.
+
+## Stream large payloads, don't buffer
+
+```javascript
+// Wrong — loads the whole file into memory; 10 concurrent = OOM
+res.send(await readFile("video.mp4"));
+
+// Correct — pipe; constant memory regardless of size
+import { createReadStream } from "node:fs";
+createReadStream("video.mp4").pipe(res);
+```
+
+Buffering a large response holds it all in RAM per request; streams move it in
+chunks at constant memory. Use `pipeline()` (handles backpressure + cleanup) over
+manual `.pipe()` for production. Same for request bodies and DB cursors.
+
+## Graceful shutdown (zero-downtime deploys)
+
+```javascript
+const server = app.listen(8080);
+for (const sig of ["SIGTERM", "SIGINT"]) {
+  process.on(sig, async () => {
+    server.close();                 // stop accepting new connections
+    await db.end();                 // drain pools / in-flight work
+    process.exit(0);
+  });
+}
+```
+
+On deploy the orchestrator sends `SIGTERM`; without a handler, in-flight requests
+are killed mid-response. Close the listener, drain connections, then exit. Set a
+timeout so a stuck drain still exits.
+
+## Framework pick
+
+| | Express | Fastify | NestJS |
+|---|---|---|---|
+| style | minimal, middleware | minimal, fast, schema-first | opinionated, DI, decorators |
+| async errors | v5 native (v4 needs wrapper) | native | native |
+| validation | bring your own | built-in JSON-schema | class-validator |
+| use when | simplest, huge ecosystem | perf + built-in validation | large team, structured DI |
+
+Pin the Node version in `engines` and use the **Active LTS** in production, not
+Current — Current ships breaking changes. Versions → [versions.json](versions.json).
+
+## Anti-patterns (reject on sight)
+
+- Any `*Sync` fs/crypto/zlib call on the request path → blocks the loop.
+- An async route handler with no error path (Express 4) → unhandled rejection.
+- No `process.on("unhandledRejection")` / `uncaughtException` → silent death.
+- Buffering a large file/response instead of streaming → OOM under load.
+- No `SIGTERM` handler → killed in-flight requests on every deploy.
+- CPU-heavy work inline (sync hashing, big loops) → use a Worker Thread / queue.
+- `npm install` in CI (mutates lockfile) → `npm ci` (lockfile-exact, reproducible).
+
+## See also
+
+- [references/event-loop.md](references/event-loop.md) — the loop phases, blocking sources, workers, backpressure.
+- [references/async-and-errors.md](references/async-and-errors.md) — promises, error propagation, AbortController, timeouts.
+- [assets/node-checklist.md](assets/node-checklist.md) — the ship gate.
+- [typescript](../typescript/SKILL.md) · [api-design](../api-design/SKILL.md) · [security-web](../security-web/SKILL.md) · [observability](../observability/SKILL.md).

core/skills/node-backend/assets/node-checklist.md

@@ -0,0 +1,25 @@
+<!-- domain:BACKEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# Node Backend Ship Checklist
+
+Run before deploying a Node service.
+
+## Event loop
+- [ ] No `*Sync` fs/crypto/zlib on the request path.
+- [ ] CPU-heavy work (hashing, parsing MBs, big loops) offloaded to a Worker / queue.
+- [ ] Large payloads streamed (`pipeline`), not buffered.
+- [ ] Loop-lag metric exported + alerted.
+
+## Errors & lifecycle
+- [ ] `process.on("unhandledRejection")` + `uncaughtException` → log + exit non-zero.
+- [ ] Every async handler has an error path (Express 4 wrapper, or Express 5/Fastify).
+- [ ] No empty `catch` blocks; errors handled or rethrown.
+- [ ] Every outbound call has a timeout + AbortController cancellation.
+- [ ] `Promise.all` over large arrays bounded (`p-limit`/batches).
+- [ ] `SIGTERM`/`SIGINT` graceful shutdown: stop listener → drain → exit (with a cap).
+
+## Build & deploy
+- [ ] `engines.node` pinned to Active LTS.
+- [ ] Lockfile committed; CI uses `npm ci` (not `install`).
+- [ ] `python3 scripts/check_package.py package.json` → `clean`.
+- [ ] Secrets from env/vault, never in code or image.
+- [ ] `make skills-check-versions` — Node/framework pins current.

core/skills/node-backend/references/async-and-errors.md

@@ -0,0 +1,67 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# Async & Error Handling in Node
+
+> P: Propagate, time out, and cancel async work so one failure doesn't crash the process or hang a request.
+> R: Writing any async handler, calling external services, or wiring shutdown.
+> S: Loop scheduling / blocking — see [event-loop.md](event-loop.md).
+> N: [SKILL.md](../SKILL.md), [node-checklist.md](../assets/node-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## The two process-level nets (always install)
+
+```javascript
+process.on("unhandledRejection", (reason) => { logger.error({ reason }, "unhandledRejection"); process.exit(1); });
+process.on("uncaughtException", (err) => { logger.error({ err }, "uncaughtException"); process.exit(1); });
+```
+
+An unhandled rejection or thrown error with no catch will, by default, terminate
+the process (modern Node) — but silently if you don't log it. Log, then exit
+non-zero so the orchestrator restarts a clean process. Do **not** try to "recover"
+after an `uncaughtException` — the state is unknown; exit.
+
+## Propagate, don't swallow
+
+```javascript
+// Wrong — swallows the error; caller thinks it succeeded
+try { await save(x); } catch { /* ignore */ }
+
+// Correct — handle or rethrow; never an empty catch
+try { await save(x); }
+catch (err) { logger.warn({ err }, "save failed"); throw err; }
+```
+
+An empty `catch` is a lie to the caller. Either handle it meaningfully (retry,
+fallback, user-facing error) or rethrow. In Express, `next(err)` routes to the
+error middleware; never `res.send` a raw error (leaks internals).
+
+## Timeouts + cancellation with AbortController
+
+```javascript
+const ac = new AbortController();
+const t = setTimeout(() => ac.abort(), 5000);
+try {
+  const r = await fetch(url, { signal: ac.signal });   // aborts at 5s
+} finally { clearTimeout(t); }
+```
+
+Every outbound call (HTTP, DB) needs a timeout — without one a hung upstream
+holds your request (and its loop slot) forever. `AbortController` cancels fetch,
+streams, and many libraries; propagate the request's signal so a client
+disconnect cancels downstream work.
+
+## Concurrency control
+
+```javascript
+// Wrong — fires 10000 DB calls at once; exhausts the pool, OOMs
+await Promise.all(ids.map((id) => db.get(id)));
+
+// Correct — bounded concurrency
+import pLimit from "p-limit";
+const limit = pLimit(20);
+await Promise.all(ids.map((id) => limit(() => db.get(id))));
+```
+
+`Promise.all` over a huge array launches everything simultaneously. Bound it
+(`p-limit`, a queue, or batched `for` loops) to your pool/rate limits. Use
+`Promise.allSettled` when one failure shouldn't reject the whole batch.

core/skills/node-backend/references/event-loop.md

@@ -0,0 +1,65 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# The Node Event Loop — Phases, Blocking, Workers
+
+> P: How the single thread schedules work, what blocks it, and how to do CPU work without freezing requests.
+> R: Debugging latency under load, or adding any CPU-heavy operation.
+> S: Async error handling — see [async-and-errors.md](async-and-errors.md).
+> N: [SKILL.md](../SKILL.md), [node-checklist.md](../assets/node-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## One thread, phases per tick
+
+The loop cycles through phases: **timers** (`setTimeout`), **pending callbacks**,
+**poll** (I/O — most of your handlers run here), **check** (`setImmediate`),
+**close**. Between every callback it drains the **microtask queue** (resolved
+promises, `queueMicrotask`, `process.nextTick`). Your code shares this one thread
+with every other request — so a callback that runs 200 ms of sync work adds 200 ms
+of latency to everything else waiting.
+
+## What blocks (and the fix)
+
+| Blocker | Fix |
+|---|---|
+| `fs.readFileSync`, `crypto.*Sync`, `zlib.*Sync` | the async variant (`fs/promises`, callback crypto) |
+| `JSON.parse`/`stringify` of MBs | stream-parse, or do it in a Worker |
+| tight loop over 10⁶+ items | chunk with `setImmediate`, or a Worker Thread |
+| sync hashing / bcrypt rounds inline | async bcrypt / a Worker / a queue |
+| a regex with catastrophic backtracking | fix the regex (ReDoS is a DoS *and* a block) |
+
+A microtask that recurses (`process.nextTick` calling itself) **starves** the I/O
+phase — the loop never reaches poll. Prefer `setImmediate` for "run after current
+I/O" so you don't starve.
+
+## CPU work — off the main thread
+
+```javascript
+import { Worker } from "node:worker_threads";
+// hash/resize/parse in a worker; main thread stays responsive
+const result = await new Promise((resolve, reject) => {
+  const w = new Worker("./hash-worker.js", { workerData: payload });
+  w.on("message", resolve); w.on("error", reject);
+});
+```
+
+Worker Threads have their own loop + memory; use them for CPU-bound tasks. For
+heavy or bursty work, a separate queue/worker service (BullMQ + Redis) is better
+than inline workers — it survives restarts and scales independently.
+
+## Backpressure — respect the consumer's pace
+
+```javascript
+import { pipeline } from "node:stream/promises";
+await pipeline(source, transform, destination);   // honors backpressure + cleans up on error
+```
+
+A fast producer (`source.on("data")` → `dest.write()`) that ignores `write()`
+returning `false` buffers unbounded in memory → OOM. `pipeline()` (or `.pipe()`)
+pauses the source when the destination is full. Never hand-roll the data/drain
+dance in production.
+
+## Measure
+
+`--prof` / `clinic.js` / `0x` flame graphs show where the loop spends time;
+`event-loop-lag` (or `perf_hooks.monitorEventLoopDelay`) exposes lag as a metric —
+alert on it. Rising loop lag under load = something is blocking the thread.