@loomfsm/bundle-code 0.1.0

package/knowledge/references/perf-nestjs.md

@@ -0,0 +1,59 @@
+---
+tags: [performance, nestjs, nodejs, orm, n-plus-one, backend]
+stack_signals:
+  - language: [typescript, javascript]
+  - project_type: [backend, monorepo]
+summary: |
+  NestJS / Node.js performance checklist — N+1 patterns, missing indexes,
+  pagination, eager loading, ORM mistakes, request-handler hot paths.
+when_to_load: |
+  Task touches NestJS controllers / services / providers, TypeORM or Prisma
+  queries, request-pipeline middleware on a Node.js backend with perf
+  concerns or scale targets.
+agent_hints: [performance, logic-reviewer, challenger-reviewer]
+---
+
+# Performance: NestJS / Node.js
+
+## Database & ORM
+- N+1 query patterns (loading relations in loops)
+- Missing database indexes (implied by WHERE/ORDER BY columns)
+- Missing pagination on list endpoints (unbounded queries)
+- Non-parameterized queries prevent database query plan caching (also a security risk)
+- Eager loading too many relations (over-fetching)
+- Missing select() — fetching all columns when only a few are needed
+- Transaction scope too wide (holding locks longer than necessary)
+
+## API & HTTP
+- Synchronous operations blocking the event loop (CPU-heavy in request handler)
+- Missing caching for expensive repeated operations (Redis, in-memory)
+- No rate limiting on public/expensive endpoints
+- Large response payloads without pagination or streaming
+- Missing compression (gzip/brotli)
+- File uploads without size limits
+- Missing timeout on external HTTP calls
+
+## Serialization & Validation
+- ClassSerializerInterceptor on every response — expensive for hot paths; consider manual DTOs
+- class-validator with deeply nested DTOs — use `whitelist: true` and `forbidNonWhitelisted: true`
+- JSON serialization of large objects without streaming
+
+## Architecture
+- Blocking constructor operations (should be in onModuleInit)
+- Synchronous file I/O (readFileSync, writeFileSync)
+- Request-scoped providers where singleton would work (Scope.REQUEST propagates to all consumers)
+- Unused providers still registered (loaded but never called)
+- Missing queue/background job for heavy operations in request path (emails, reports, file processing)
+- Circular dependencies via `forwardRef()` — unexpected init overhead
+
+## Memory & Resources
+- Event listeners or intervals not cleaned up in onModuleDestroy
+- Large objects held in module-scoped variables (memory leak)
+- Missing stream processing for large files (loading entire file to memory)
+- Unbounded caches without TTL or max size
+
+## Node.js Runtime
+- Not utilizing multiple CPU cores — consider cluster mode or worker threads for CPU-bound ops
+- Node.js doesn't cache DNS by default — repeated external HTTP calls can suffer from DNS lookup latency
+- Verbose logging in production (string formatting overhead even when log level disabled)
+- Consider Fastify adapter over Express for high-throughput services (~2x faster)

package/knowledge/references/perf-python.md

@@ -0,0 +1,50 @@
+---
+tags: [performance, python, fastapi, asyncio, backend]
+stack_signals:
+  - language: [python]
+  - project_type: [backend, monorepo]
+summary: |
+  Python / FastAPI / asyncio performance checklist — N+1, pagination, async
+  pool sizing, transaction scope, gather vs serial calls.
+when_to_load: |
+  Task touches Python backend code (FastAPI, Django, Flask) with perf
+  concerns, scale targets, or async/await + DB interaction. Diff in
+  *.py with route handlers, async functions, or DB query construction.
+agent_hints: [performance, logic-reviewer, challenger-reviewer]
+---
+
+# Performance: Python / FastAPI / asyncio
+
+## Database
+- N+1 queries (loading in loops instead of batch)
+- Missing database indexes (implied by WHERE/ORDER BY columns)
+- Missing pagination on list endpoints (unbounded queries)
+- Transaction scope too wide (holding DB connections across gRPC/HTTP calls)
+- asyncpg pool exhaustion — missing `min_size`/`max_size` tuning, or not releasing connections promptly
+- Unbounded caches without TTL
+
+## Async Runtime
+- Blocking sync calls in async handlers (sync I/O, CPU-heavy ops without executor)
+- GIL-bound CPU work — `asyncio.to_thread()` only helps I/O; CPU parallelism needs `ProcessPoolExecutor`
+- Missing `asyncio.Semaphore` for concurrent external calls
+- Missing timeout on external HTTP/gRPC calls (`httpx` timeout, `asyncio.wait_for`)
+- Sync file I/O in async context
+
+## API & HTTP
+- Missing connection pool limits on outbound HTTP clients
+- Large response payloads without pagination
+- Missing `StreamingResponse` for large data exports (building entire response in memory)
+- Heavy work in request path that should use `BackgroundTasks` or task queue
+- Missing response class optimization (`ORJSONResponse` vs default `JSONResponse` for large payloads)
+
+## Serialization & Validation
+- Pydantic model validation cost on hot paths — use `model_construct` for trusted internal data
+- Repeated validation of same data across middleware/dependencies
+- `json.dumps` for large payloads — use `orjson` for 3-10x speedup
+
+## FastAPI-Specific
+- Heavy middleware running on every request that could be scoped to specific routes
+- `Depends()` chains re-executing expensive lookups per request without caching
+- Not pre-warming connection pools at startup (lifespan handler)
+- Excessive DEBUG-level logging in production (string formatting even when log level disabled)
+- Import-time side effects slowing startup

package/knowledge/references/perf-react.md

@@ -0,0 +1,52 @@
+---
+tags: [performance, react, nextjs, rendering, bundle, hydration, frontend]
+stack_signals:
+  - language: [typescript, javascript]
+  - project_type: [frontend-app, monorepo]
+summary: |
+  React/Next.js performance checklist — unnecessary re-renders, heavy
+  build/render paths, bundle bloat, hydration mismatches, asset
+  optimization, App Router server/client boundary choices.
+when_to_load: |
+  Task touches React/Next.js components, hooks, rendering perf, bundle size,
+  image/font loading, or Next.js-specific perf concerns (revalidate, ISR,
+  Server vs Client components). Reviewer fan-out includes performance
+  or UI-consistency on a React/Next stack.
+agent_hints: [performance, logic-reviewer, ui-consistency]
+---
+
+# Performance: React / Next.js
+
+## Rendering
+- Unnecessary re-renders (missing memo/useMemo/useCallback where it matters)
+- Heavy computations in render path — move to useMemo or outside component
+- Context provider placed too high — causes cascading re-renders in unrelated subtrees
+- State lifted too high when it could be local (colocate state with consumers)
+- Large inline objects/arrays in JSX — creates new references every render, defeats React.memo
+- Key prop misuse — using array index as key in dynamic lists causes unnecessary unmount/remount
+- useEffect with unstable dependencies (object/array refs) running every render
+
+## Data Fetching
+- Client-side data fetching that could be server-side (SSR/SSG)
+- Missing React Query / SWR deduplication for same endpoint called from multiple components
+- Hydration mismatch causing full client-side re-render
+
+## Bundle & Loading
+- Large new dependencies added to bundle (check with bundlephobia)
+- Missing lazy loading for heavy routes/components (`React.lazy` / `next/dynamic`)
+- Missing virtualization for long lists (50+ items) — use react-window/react-virtual
+- Missing debounce/throttle on frequent events (search input, scroll, resize)
+
+## Assets
+- Unoptimized images (missing `next/image`, no width/height, no srcset)
+- Missing font loading strategy (`next/font` or `font-display: swap`)
+- Third-party scripts loaded synchronously — use `next/script` with `strategy="lazyOnload"`
+
+## Next.js Specific
+- Using client components where server component would suffice
+- Missing `revalidate` on ISR pages (stale data served indefinitely)
+- `getServerSideProps` where `getStaticProps` + revalidate would work
+- Not using Route Handlers / Server Actions for mutations (unnecessary client-side fetch)
+
+## Note
+React 19 compiler (React Forget) auto-memoizes — manual useMemo/useCallback may become less critical. Still flag missing memoization but note this.

package/knowledge/references/react19.md

@@ -0,0 +1,176 @@
+---
+tags: [react, react19, rsc, server-components, server-actions, suspense, frontend]
+stack_signals:
+  - language: [typescript, javascript]
+  - project_type: [frontend-app, monorepo]
+summary: |
+  React 19 stance — Server Components, Server Actions, use(), useOptimistic,
+  useFormStatus, useActionState, Suspense boundaries, React Compiler.
+  Delete code that used to be hand-rolled, but don't over-apply primitives.
+when_to_load: |
+  Project uses react@>=19 (per package.json) or Next.js ≥15 (depends on React
+  19). Diff includes Server/Client component boundary changes, Server Actions,
+  use() hook, useOptimistic, useFormStatus, useActionState, useTransition,
+  Suspense boundaries, or React Compiler annotations.
+agent_hints: [logic-reviewer, performance, ui-consistency, challenger-reviewer]
+---
+
+# React 19 — Senior Stance
+
+## When this applies
+Load when project uses `react@>=19` (check package.json) or Next.js ≥15 (which depends on React 19). Reviewer auto-loads when diff includes Server/Client component boundary changes, Server Actions, `use()` hook, `useOptimistic`, `useFormStatus`, `useActionState`, `useTransition`, Suspense boundaries, or React Compiler annotations.
+
+## Default Stance
+React 19 collapses several layers that React 18 made you build by hand: form actions, optimistic updates, async-aware suspension, ref forwarding. The win is "delete code that used to be hand-rolled". The risk is over-applying the new primitives where simpler local state was already correct. Don't refactor working `useState` to `useOptimistic` without a real concurrent-mutation reason. Rename of `forwardRef` is real cleanup; rewriting all forms to Actions is opt-in based on actual benefit.
+
+## Patterns (use these)
+
+### `ref` is now a regular prop (no more `forwardRef`)
+React 19 lets function components accept `ref` directly:
+```tsx
+function Button({ ref, ...props }: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+  return <button ref={ref} {...props} />;
+}
+```
+`forwardRef` still works but is being deprecated. Migrate when touching the file, don't sweep.
+
+### `use()` for reading promises and context conditionally
+- `use(promise)` suspends until resolution. Read inside any component, including conditionally (unlike hooks).
+- `use(context)` works inside conditionals — the only legal hook-like call inside `if`.
+- Cache promises outside render, or use a stable promise source (route loader, parent prop). Creating a new promise inside render = infinite suspend loop.
+
+### `useActionState` for form submissions
+Replaces hand-rolled `useState` + `useTransition` + error tracking + pending tracking around form posts.
+```tsx
+const [state, action, isPending] = useActionState(submitForm, initialState);
+return <form action={action}>...</form>;
+```
+Server Action signature: `async function submitForm(prevState, formData) { ... return newState }`.
+
+### `useOptimistic` for rapid optimistic mutation
+Use when **the user makes the same kind of mutation rapidly** (likes, comments, drag-reorder) and visual lag is the dominant UX cost. Returns optimistic state during the action, reverts on failure.
+```tsx
+const [optimisticItems, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]);
+```
+Don't reach for it on rare mutations where a brief loading state is fine.
+
+### `useFormStatus` to read parent form state
+Inside a child component nested under a `<form>` — read pending/data/method without prop drilling.
+```tsx
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return <button disabled={pending}>...</button>;
+}
+```
+
+### Server Actions
+`'use server'` directive on a function exposes it as an RPC endpoint. Client can call it directly; React handles serialization and form integration.
+- **Validate inputs server-side, always.** `'use server'` is the boundary; client-supplied args are untrusted.
+- Auth check **inside** the action body, not in the calling component. Components can be bypassed.
+- Sensitive data must not be returned through revalidation paths that may surface in cache layers.
+
+### Server Components
+- Server Components run only on server, never ship to client. Default for static and DB-bound content.
+- Cannot use hooks (`useState`, `useEffect`) — they're client-only. If you need state, the component is `'use client'`.
+- Pass server data to client components via props at the boundary. Don't lift `'use client'` higher than necessary.
+
+### Suspense boundary granularity
+Each `<Suspense>` is an independent loading region. Place at the smallest unit where loading has meaning (a single widget, not the whole page). Coarse Suspense boundaries cause whole-screen flashes when one part is slow.
+
+### React Compiler (when adopted)
+- Memoizes automatically. **Stop manually wrapping things in `useMemo` / `useCallback`** when compiler is on.
+- Verify compiler is on with `// eslint-disable-next-line react-compiler/react-compiler` guard rules.
+- Compiler bails out of components with rule violations (impure render, mutating props, etc.). Read compiler logs.
+
+## Anti-Patterns (DO NOT)
+
+### Creating promises inside render
+```tsx
+// BAD
+function Page() {
+  const data = use(fetchData()); // new promise every render → infinite suspend
+}
+```
+**Rule:** create the promise outside the component (route loader, server fetch returned as prop) or stable-cache it.
+
+### Server Action without auth check
+**Why it bites:** the calling component verifies auth, but the action is callable directly via fetch from anywhere. The component isn't a security boundary.
+**Rule:** every Server Action begins with explicit `requireAuth(...)` or equivalent. No exceptions.
+
+### Adding `'use client'` to a component because "it has a button"
+**Why it bites:** marking a tree boundary as Client ships it all to the browser. Big perf regression on what should be server-rendered.
+**Rule:** isolate the interactive island. Wrap just the button in a Client component, leave the rest Server.
+
+### `useOptimistic` on rare or critical mutations
+**Why it bites:** on failure the UI flips back, looks broken; on a payment / save / publish flow the user thinks the action succeeded.
+**Rule:** optimistic UI for repetitive low-stakes actions (likes, cart count, drag). Pessimistic with explicit success state for high-stakes.
+
+### Mixing `useState` for form data with `useActionState`
+**Why it bites:** two sources of truth, redundant pending tracking, divergent error handling.
+**Rule:** pick one. If using `useActionState`, the `state` from it is the form's truth.
+
+### Putting `'use server'` on shared utility files
+**Why it bites:** every export becomes a public RPC endpoint. Easy to accidentally expose internal logic.
+**Rule:** `'use server'` files contain only intended actions. Internal helpers live in non-`'use server'` files.
+
+### Hand-rolled memoization with React Compiler enabled
+**Why it bites:** compiler does it; manual `useMemo` adds noise, can be inconsistent with compiler's analysis, diverges over time.
+**Rule:** when compiler is on, delete `useMemo`/`useCallback` unless there's a measured benefit it doesn't cover.
+
+### Returning huge data from Server Action
+**Why it bites:** action result is serialized through the wire. 1MB response = slow, may exceed framework limits.
+**Rule:** return what the form needs (success flag, errors, redirect target). Refetch heavy data via the page.
+
+### Fine-grained Suspense everywhere
+**Why it bites:** every Suspense = a network round trip in some setups, plus visual jank as parts pop in independently.
+**Rule:** boundaries match user-meaningful regions. Sidebar, main content, secondary content. Not every component.
+
+### Using async client components
+**Why it bites:** client components can't be async. The boundary is server-only.
+**Rule:** async function = Server Component. If you need a Client Component, it's sync; data comes via props or `use()`-wrapped promise from parent server.
+
+### Mutating props or state inside render
+**Why it bites:** React Compiler bails out → no memoization. React 19 strict mode catches more of these. Was tolerated; now broken.
+**Rule:** treat all render inputs as immutable.
+
+## Decision Framework
+
+| Situation | Choice |
+|---|---|
+| Form submission with server-side logic | Server Action + `useActionState` |
+| Optimistic UI for likes/cart-add | `useOptimistic` |
+| Optimistic UI for save/publish/payment | Pessimistic + explicit pending |
+| Reading async data in a component | Server Component (default) or `use()` in client with stable promise |
+| Need state inside what's currently a Server Component | Extract interactive island as Client Component |
+| Forwarding ref to a custom component | Direct `ref` prop (not `forwardRef`) |
+| Heavy compute in render | Server Component, or `useMemo` if React Compiler off |
+| Conditional context read | `use(MyContext)` (legal in conditionals) |
+| Pending UI inside form button | `useFormStatus` (no prop drilling) |
+| Migrating to compiler-managed memo | Run compiler in opt-in mode first, fix bail-outs, then turn on globally |
+
+## Cost Model
+
+| Pattern | Cost / Win |
+|---|---|
+| `'use client'` on a leaf | +5-30KB JS bundle for that island |
+| `'use client'` on parent of large tree | +entire-tree JS to bundle |
+| Server Component | 0 client JS for that component |
+| Server Action call | 1 round trip + serialization cost |
+| `use(promise)` with stable promise | suspends, no extra round trip if promise is from server |
+| `useOptimistic` reverting on error | Visual flip 200-1000ms after action |
+| React Compiler enabled | ~5-20% bundle reduction vs hand-memo, fewer re-renders |
+
+## Red Flags in Diff
+
+- `'use client'` added to a component without an interactive primitive (no `onClick`, `useState`, `useEffect`) — flag (probably can stay Server).
+- New `forwardRef` in React 19 codebase — flag, prefer direct `ref` prop.
+- Server Action without explicit auth check at top of function body — flag immediately (security).
+- `use(somePromise())` where `somePromise()` is invoked inline in render — flag (infinite suspend).
+- `useOptimistic` on mutation with side-effect failure modes (write to external system, payment) — flag (UX/integrity risk).
+- `useState` + `useTransition` + manual error tracking around a form submit — flag (use `useActionState`).
+- Async function inside `'use client'` file as a default export → flag (client components can't be async).
+- Suspense boundary wrapping the entire page or layout → flag (too coarse).
+- `useMemo` / `useCallback` everywhere AND `react-compiler` is on in config → flag (delete the manual ones).
+- `'use server'` file exporting non-action utilities → flag (accidental RPC exposure).
+- Mutation of props or state object during render → flag (compiler bail-out).
+- Server Action returning > 100KB of data → flag (probably should refetch via page).

package/knowledge/references/redis.md

@@ -0,0 +1,175 @@
+---
+tags: [redis, cache, session, queue, rate-limit, pubsub, distributed-lock]
+stack_signals:
+  - project_type: [backend, monorepo]
+summary: |
+  Redis design — single-threaded per shard, in-memory budget. Keep keys
+  small, commands O(1) or bounded, and design every feature to degrade
+  gracefully on a Redis blip.
+when_to_load: |
+  Task touches cache layer, session store, rate limiter, queue (BullMQ,
+  Sidekiq, RQ), pub/sub, distributed lock, ratelimit, or real-time presence.
+  Diff including Redis client calls (redis., ioredis, node-redis, redis-py,
+  lettuce, Bull, BullMQ, RedisCacheStore) qualifies.
+agent_hints: [logic-reviewer, performance, challenger-reviewer]
+---
+
+# Redis — Senior Stance
+
+## When this applies
+Load when task touches: cache layer, session store, rate limiter, queue (BullMQ, Sidekiq, RQ), pub/sub, distributed lock, ratelimit, real-time presence. Reviewer auto-loads when diff includes Redis client calls (`redis.`, `ioredis`, `node-redis`, `redis-py`, `lettuce`, `Bull`, `BullMQ`, `RedisCacheStore`).
+
+## Default Stance
+Redis is single-threaded per shard and held in memory. Every command competes for the same CPU and the same RAM budget. Treat it as a shared resource with a strict SLA: keep keys small, commands O(1) or bounded, and persistence trade-offs explicit. A Redis outage cascades — design every feature so a 30-second Redis blip degrades, not breaks.
+
+## Patterns (use these)
+
+### Pick the right primitive
+- **String** — value + optional TTL. Default for cached payload, counter (`INCR`), feature flag.
+- **Hash** — object with multiple fields, when you read/write fields independently. Cheaper than JSON-string for partial updates.
+- **Set** — uniqueness. Online users, deduplication, tag membership.
+- **Sorted Set (ZSET)** — leaderboards, time-ordered streams of bounded size, top-N queries. `ZADD` + `ZRANGE` is the workhorse.
+- **List** — simple FIFO queue, recent-N items (`LPUSH` + `LTRIM`).
+- **Stream (XADD/XREADGROUP)** — durable queue with consumer groups, replay. Use this for queue-of-record (not List).
+- **HyperLogLog** — approximate cardinality. 12KB for billions of entries. Don't reach for Set when "approximate count of unique" is enough.
+- **Bitmap** — daily active flags. `SETBIT user_id`, `BITCOUNT`. 1MB = 8M users.
+
+### Persistence — choose deliberately
+- **None (cache only)** — RDB off, AOF off. Acceptable for pure cache. Restart = empty.
+- **RDB snapshots** — periodic dump. Loses last N seconds. Cheap. Default for many setups.
+- **AOF (appendonly yes, fsync everysec)** — fsync each second. Loses ≤1s on crash. The right default for state-bearing Redis.
+- **AOF fsync always** — every write fsync'd. 10x slower writes. Almost never the right choice.
+- Replication is not a backup. Use snapshots for backup.
+
+### Eviction policy
+Set explicit `maxmemory` and `maxmemory-policy`. Default of "no eviction" turns Redis into a wall when full → all writes fail.
+- **allkeys-lru** — pure cache.
+- **volatile-lru** — mixed cache + persistent keys (only TTL'd keys evict).
+- **noeviction** — only when Redis is single-purpose state with strict guarantees.
+
+### TTL discipline
+Every cache key has a TTL. No exceptions. Without TTL, a bug accumulates dead data forever. Set TTL on `SET` directly (`SET k v EX 600`), not as a separate `EXPIRE`.
+
+### Pipelining and MULTI
+- **Pipeline** — batch many commands without atomicity. ~10x throughput on round-trip-bound workloads.
+- **MULTI/EXEC** — atomic multi-command. All-or-nothing. Use when you need atomic compose (e.g. `INCR` + `EXPIRE`). Note: still single-threaded, blocks server briefly for the block duration.
+- **Lua script (EVAL)** — atomic, but server runs it single-threaded. Keep scripts O(1) or bounded.
+
+### Distributed locking
+The naive lock — `SET key value NX EX 10` — is correct for single-node Redis if you also:
+1. Use a unique random value per acquirer.
+2. Release via Lua script that checks value before DEL (avoids releasing someone else's lock after expiry).
+
+For multi-node Redis cluster: **Redlock has known correctness issues under network partitions.** If you actually need distributed mutual exclusion across replicas, use a real consensus system (Postgres advisory locks, etcd, ZooKeeper). Redlock is "best-effort with a fence token", not "guaranteed mutex".
+
+### Rate limiting
+- **Fixed window** — `INCR key`, `EXPIRE key 60` if first. Simple, has boundary spikes.
+- **Sliding log** — `ZADD`, prune old, `ZCARD`. Memory-heavy.
+- **Token bucket via Lua** — best correctness/cost balance. One Lua script, atomic, bounded.
+- For high-volume — use a pre-built lib (`redis-cell` module, `node-rate-limiter-flexible`) instead of writing your own.
+
+### Pub/Sub vs Streams
+- **Pub/Sub** — fire-and-forget. Subscriber not connected = message lost. No replay. Use for real-time only when loss is acceptable.
+- **Streams** — durable, consumer groups, replay, ack. Use for "queue of work". Default to streams for anything that must not be lost.
+
+### Cache key design
+- Namespace prefix: `app:env:entity:id` — `wandr:prod:user:123`. Makes debugging and bulk-purge easy.
+- Include version in key when shape may change: `wandr:prod:user:123:v2`. Makes safe rollouts trivial — change version, old cache evicts naturally via TTL.
+- Hash large keys: `user:hash(email)` rather than `user:long-email-string`.
+
+## Anti-Patterns (DO NOT)
+
+### `KEYS *` in production
+**Why it bites:** O(N) over the entire keyspace, blocks the single thread for the duration. On a 10M-key Redis = full server stall for seconds.
+**Rule:** use `SCAN` with `MATCH` and `COUNT`. Iterates with bounded work per call.
+
+### Storing 1MB+ values in a single key
+**Why it bites:** `GET` of 1MB blocks the single thread for the network write. Memory fragmentation worsens with large values.
+**Rule:** keep values < 100KB. Split into hash fields if needed. For huge blobs, use object storage and put the URL in Redis.
+
+### Using Redis as primary database
+**Why it bites:** persistence is best-effort (even AOF every-sec loses 1s). No transactions across multiple keys with rich constraints. No queries beyond key lookup.
+**Rule:** Redis = cache + ephemeral state + queue. Source of truth = real DB.
+
+### No TTL on cache keys
+**Why it bites:** memory grows monotonically. Eventually `maxmemory` hit, eviction kicks in, but eviction may evict the wrong things. Bugs in cache invalidation accumulate forever.
+**Rule:** every cache key has TTL at write time. Even "we'll invalidate manually" — set a backup TTL.
+
+### `SUBSCRIBE` for queue work
+**Why it bites:** subscriber dead for 1ms during deploy = message lost forever. No retry. No DLQ.
+**Rule:** Streams (`XADD` + `XREADGROUP`) for any work that matters.
+
+### Long-running Lua scripts
+**Why it bites:** Lua runs on the single thread. A 100ms script = 100ms freeze of the entire Redis instance for every other client.
+**Rule:** Lua must be bounded. No loops over unbounded sets.
+
+### Multiple Redis clients per process without connection pool
+**Why it bites:** each client = TCP connection + command queue. Connection storm under load.
+**Rule:** one shared client (or a small pool) per process. Configure with retry strategy and backoff.
+
+### Storing JSON-stringified objects when you need partial updates
+**Why it bites:** read-modify-write race. Two clients update field A and B → last write wins → one update lost.
+**Rule:** use Hash type with `HSET field value`. Field-level atomic updates. Or use Lua script for compound update.
+
+### Cache-aside without stampede protection
+**Why it bites:** cache miss → 1000 requests all execute the expensive backing query simultaneously. DB overloaded, sometimes outage.
+**Rule:** cache stampede mitigation — see `caching.md` (lock around fill, or probabilistic early refresh, or request coalescing).
+
+### Hot keys (single key getting all the traffic)
+**Why it bites:** Redis Cluster shards by key. One hot key = one hot shard = no parallelism. CPU pinned.
+**Rule:** if a key is read 10k+ times per second, replicate to local in-memory cache (LRU per app instance) with short TTL. Or shard the key (`counter:0`...`counter:9` and pick at random, sum on read).
+
+### Using `MULTI/EXEC` for "transactions" that aren't actually atomic logic
+**Why it bites:** MULTI/EXEC doesn't roll back on error inside the block. Errors in commands inside MULTI return errors, but other commands still execute. People assume rollback semantics — there are none.
+**Rule:** if you need conditional atomic logic, use Lua. MULTI/EXEC is just batching with no interleaved commands.
+
+## Decision Framework
+
+| Need | Use | Avoid |
+|---|---|---|
+| Pure cache, restart-OK | String + TTL, RDB or no persist | AOF always-fsync |
+| Session store | Hash + TTL, AOF every-sec | String JSON-blob |
+| Counter | `INCR` (atomic) | GET → +1 → SET |
+| Top-N | ZSET | sorted Set + manual trim |
+| Approximate unique | HyperLogLog | Set with millions of entries |
+| Queue, must not lose | Stream + consumer group | Pub/Sub or List |
+| Rate limit | Token bucket Lua, or `redis-cell` | Hand-rolled INCR/EXPIRE with race |
+| Distributed lock, single node | `SET NX EX` + Lua release | naive `SETNX` then `EXPIRE` (race) |
+| Distributed lock, multi-node strong | Postgres advisory lock / etcd | Redlock for hard mutex |
+| Real-time messaging, loss-tolerable | Pub/Sub | Streams (overkill) |
+| Object with partial updates | Hash | JSON in String |
+
+## Cost Model
+
+| Operation | Cost (single-node, cached, no I/O) |
+|---|---|
+| `GET` / `SET` | 50-100µs |
+| `HSET` / `HGET` | 50-100µs |
+| `INCR` | 50-100µs |
+| Pipelined batch of 100 ops | 1-2ms total (~10-20µs each) |
+| `KEYS *` on 1M keys | 100ms+ blocking |
+| Lua script, 100 iterations | 0.5-1ms blocking |
+| `SUBSCRIBE` notification | sub-ms when subscriber alive |
+| `XADD` to stream | 100µs |
+
+| Storage | Bytes |
+|---|---|
+| Empty Hash | ~80B |
+| String value, 100B payload | ~150B with metadata |
+| ZSET, 100 members | ~5KB |
+| Stream entry, 100B payload | ~200B |
+
+## Red Flags in Diff
+
+- `KEYS` / `FLUSHDB` / `FLUSHALL` — flag immediately, almost always wrong in app code.
+- `SET` without `EX` / TTL — flag (cache key without expiry).
+- `SUBSCRIBE` for work-style messaging where loss matters — flag (use Streams).
+- `MULTI` / `EXEC` block doing logic that only works if all succeed — flag (Lua instead).
+- New Redis client constructed inside a request handler — flag (should be shared).
+- Lua script with unbounded loop or `KEYS *`-style iteration — flag.
+- Distributed lock implemented as `SETNX` + separate `EXPIRE` → race condition window. Flag.
+- Cache fill without stampede protection in hot path → flag.
+- Single key receiving high write rate without sharding plan → flag (hot key).
+- Storing JSON-stringified blob > 50KB in a String key → flag.
+- Lock release `DEL key` without checking the value first → flag (releases someone else's lock).
+- Rate limiter using `INCR` + separate `EXPIRE` first-time-key check → race window allows N+1 requests through.