@loomfsm/bundle-code 0.1.0

package/dist/test/bundle.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.test.js","sourceRoot":"","sources":["../../test/bundle.test.ts"],"names":[],"mappings":"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"}

package/dist/test/sandbox-rules.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/sandbox-rules.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { KERNEL_SENSITIVE_PATH_RULES, createPathRestrictedSandbox, fileReadTool, mergeSensitivePathRules, } from "@loomfsm/kernel";
+import { CODE_BUNDLE_SENSITIVE_PATH_RULES } from "../src/sandbox-rules.js";
+// Build a tool context. When `rules` is omitted the tool falls back to the
+// bare kernel floor — exactly the production fallback path.
+function makeCtx(projectDir, rules) {
+    const audited = [];
+    const ctx = {
+        project_dir: projectDir,
+        sandbox: createPathRestrictedSandbox(projectDir),
+        audit_emit: (p) => audited.push(p),
+        ...(rules !== undefined ? { sensitive_path_rules: rules } : {}),
+    };
+    return { ctx, audited };
+}
+const MERGED = mergeSensitivePathRules(KERNEL_SENSITIVE_PATH_RULES, CODE_BUNDLE_SENSITIVE_PATH_RULES);
+describe("@loomfsm/bundle-code — dev-ecosystem sandbox rules", () => {
+    let project;
+    beforeEach(() => {
+        project = mkdtempSync(join(tmpdir(), "loom-bundle-sandbox-"));
+    });
+    afterEach(() => {
+        rmSync(project, { recursive: true, force: true });
+    });
+    it("refuses .npmrc once the bundle rules are merged, allows it under the bare kernel floor", async () => {
+        writeFileSync(join(project, ".npmrc"), "//registry.example/:_authToken=secret", "utf8");
+        // Bare floor (no bundle rules wired): .npmrc is NOT a kernel-floor
+        // secret, so the read is allowed and returns content.
+        {
+            const { ctx } = makeCtx(project);
+            const r = await fileReadTool.handler({ path: ".npmrc" }, ctx);
+            assert.ok("content" in r, ".npmrc should be readable under the bare kernel floor");
+        }
+        // Merged rules (the production wiring): .npmrc is refused as a
+        // sensitive file. This fails if the file tool ignores the carried
+        // rules — i.e. if the bundle rules are not actually wired through.
+        {
+            const { ctx, audited } = makeCtx(project, MERGED);
+            const r = await fileReadTool.handler({ path: ".npmrc" }, ctx);
+            assert.ok("error" in r, ".npmrc must be refused once the bundle rules are merged");
+            assert.equal(audited[0]?.error_class, "sandbox-violation");
+            assert.match(String(audited[0]?.reason), /^sensitive-file:/);
+        }
+    });
+    it("refuses .kube/config under the merged rules, allows it under the bare floor", async () => {
+        mkdirSync(join(project, ".kube"), { recursive: true });
+        writeFileSync(join(project, ".kube", "config"), "apiVersion: v1\nclusters: []", "utf8");
+        {
+            const { ctx } = makeCtx(project);
+            const r = await fileReadTool.handler({ path: ".kube/config" }, ctx);
+            assert.ok("content" in r, ".kube/config should be readable under the bare kernel floor");
+        }
+        {
+            const { ctx, audited } = makeCtx(project, MERGED);
+            const r = await fileReadTool.handler({ path: ".kube/config" }, ctx);
+            assert.ok("error" in r, ".kube/config must be refused once the bundle rules are merged");
+            assert.equal(audited[0]?.error_class, "sandbox-violation");
+            assert.match(String(audited[0]?.reason), /^sensitive-dir:\/\.kube\//);
+        }
+    });
+    it("keeps the kernel floor intact under the merge (.env still refused)", async () => {
+        writeFileSync(join(project, ".env"), "SECRET=1", "utf8");
+        const { ctx, audited } = makeCtx(project, MERGED);
+        const r = await fileReadTool.handler({ path: ".env" }, ctx);
+        assert.ok("error" in r, "the merge must preserve the kernel floor");
+        assert.equal(audited[0]?.error_class, "sandbox-violation");
+    });
+});
+//# sourceMappingURL=sandbox-rules.test.js.map

package/dist/test/sandbox-rules.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-rules.test.js","sourceRoot":"","sources":["../../test/sandbox-rules.test.ts"],"names":[],"mappings":"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"}

package/knowledge/references/api-design.md

@@ -0,0 +1,188 @@
+---
+tags: [api, contract, rest, graphql, grpc, versioning, idempotency, pagination, backend]
+stack_signals:
+  - project_type: [backend, monorepo]
+summary: |
+  Public-contract design for HTTP/RPC/GraphQL endpoints — idempotency, pagination,
+  error envelopes, versioning. Treats the API signature as forever-ish and
+  prioritises contract shape over implementation detail.
+when_to_load: |
+  Task touches HTTP/RPC endpoints, GraphQL schema, gRPC proto, OpenAPI spec,
+  route handlers, or anything that's a public contract between services /
+  frontend and backend / between teams. Diff under routes/, controllers/,
+  *.proto, openapi.yaml, GraphQL *.graphql / resolvers, or new public-facing
+  functions also qualifies.
+agent_hints: [logic-reviewer, challenger-reviewer, security, api-contract]
+---
+
+# API Design — Senior Stance
+
+## When this applies
+Load when task touches HTTP/RPC endpoints, GraphQL schema, gRPC proto, OpenAPI spec, route handlers, or anything that's a public contract between services / between frontend and backend / between teams. Reviewer auto-loads when diff includes `routes/`, `controllers/`, `*.proto`, `openapi.yaml`, GraphQL `*.graphql` / resolvers, or new public-facing functions.
+
+## Default Stance
+The signature you ship is the signature you live with. Internal code can refactor freely; public contracts are forever-ish. Spend more time on shape than on implementation. Idempotency, pagination, errors, versioning — design these explicitly before the first request hits prod. Default to boring REST until you have a concrete reason for GraphQL or gRPC.
+
+## Patterns (use these)
+
+### Resource modeling
+- Nouns, not verbs: `POST /users` to create, not `POST /createUser`.
+- Hierarchy when entities truly nest: `/users/{id}/orders/{order_id}`. Stop nesting at 2 levels — `/a/{}/b/{}/c/{}/d/{}` becomes unreadable and inflexible.
+- Plural collections: `/users` returns many, `/users/{id}` returns one.
+- Filtering via query: `GET /users?status=active&created_after=2026-01-01`. Avoid `POST /users/search` with body unless you need huge filters that don't fit URL.
+
+### Idempotency keys
+Every state-mutating endpoint accepts `Idempotency-Key` header (or body field). Server stores `(key → response)` for 24h. Replay of same key returns the cached response, NOT a duplicate write. This is the single most-important defense against duplicate writes from retries/network blips.
+
+### Pagination patterns
+- **Cursor-based** (preferred for large/changing collections): `?cursor=eyJ...&limit=50`. Stable under inserts, indexable, no offset cost.
+- **Page-based** OK for stable small datasets: `?page=2&size=50`. Simple but breaks under concurrent inserts.
+- **NEVER unbounded**: every list endpoint has a default limit and a max limit. Reject `limit > max` with 400.
+
+### Versioning
+- **URL versioning** (`/v1/users`, `/v2/users`) — clearest, easiest to route, easiest for caches.
+- **Header versioning** (`Accept: application/vnd.foo.v2+json`) — cleaner URLs but invisible to logs/CDN.
+- For internal APIs, version-on-spec-change is fine. For public APIs, version-on-breaking-change only — additive changes (new optional field) don't warrant a new major.
+- Document the deprecation timeline. Sunset old versions on a calendar, not "when we feel like it".
+
+### Error envelope (consistent shape)
+Every error response has the same shape:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [{ "field": "email", "rule": "required" }],
+    "request_id": "req_abc123"
+  }
+}
+```
+- `code` is machine-parseable, stable, SCREAMING_SNAKE_CASE.
+- `message` is human-readable, may be localized.
+- `details` is structured per error type; clients can opt-in to handle.
+- `request_id` echoes back from logs for debugging.
+
+### HTTP status code discipline
+- `200` — success with body.
+- `201` — created (POST returning a new resource), include `Location` header.
+- `204` — success, no body (DELETE, void mutations).
+- `400` — client sent malformed/invalid input. Body explains.
+- `401` — not authenticated.
+- `403` — authenticated but not authorized.
+- `404` — resource doesn't exist OR you don't want to leak that it does (auth-by-existence).
+- `409` — conflict (idempotency-key reuse, optimistic-lock failure, unique constraint).
+- `422` — semantically valid but unprocessable (validation rules failed). Some teams use `400` for this; pick one and stay consistent.
+- `429` — rate limited. Include `Retry-After` header.
+- `5xx` — server's fault. Don't leak stack traces.
+
+### Rate limiting
+- Per-user (authenticated) AND per-IP (unauthenticated).
+- Token bucket via `redis-cell` or equivalent. Document limits in API docs.
+- Return `429` with `Retry-After: <seconds>` and `X-RateLimit-Remaining: <n>` headers.
+- Different limits per endpoint based on cost (cheap reads vs expensive computes).
+
+### Auth at the edge
+- Validate token at the API gateway / first middleware. Internal services trust the validated context.
+- Don't mix authn (who are you) and authz (what can you do). Authn produces a principal; authz checks the principal against the resource per request.
+- Time-box tokens. JWT exp ≤ 1 hour, refresh tokens longer with revocation.
+
+### REST vs GraphQL vs gRPC
+
+| Need | Default |
+|---|---|
+| Public API for humans/external | REST + OpenAPI |
+| Internal service-to-service, low latency, strong typing | gRPC |
+| Frontend with widely-varying data needs | GraphQL — only if you're paying the operational cost |
+| Real-time bidirectional | WebSocket / gRPC streaming |
+
+Don't pick GraphQL because it's trendy. Operational cost (N+1, query depth limits, auth-per-field, persisted queries, schema evolution, caching) is real. REST + a few well-chosen aggregating endpoints often wins.
+
+## Anti-Patterns (DO NOT)
+
+### `POST /verb` instead of `POST /resource`
+**Why it bites:** `POST /createUser`, `POST /updateUser`, `POST /deleteUser` — you've reinvented RPC over HTTP, lost all REST conventions (caching, methods, status codes). Tools, gateways, CDNs assume REST shape.
+**Rule:** Use HTTP methods for verbs. `POST /users` to create, `PATCH /users/{id}` to update, `DELETE /users/{id}` to delete.
+
+### Returning everything always
+`GET /users` returns full user with addresses, preferences, audit log embedded.
+**Why it bites:** payload sizes balloon, mobile clients pay for bytes they don't render, evolving the response shape breaks consumers. Privacy: you may leak fields.
+**Rule:** lean default response. Use `?fields=` or `?include=addresses` for opt-in expansion.
+
+### No idempotency on writes
+**Why it bites:** retry storm = N duplicate writes. Mobile network blip = duplicate charge. Distributed clients without idempotency keys is a guaranteed prod incident.
+**Rule:** every mutating endpoint accepts `Idempotency-Key`, server enforces it.
+
+### Inconsistent error shapes
+`POST /a` returns `{"error": "..."}`, `POST /b` returns `{"errors": [...]}`, `POST /c` returns `"failed"`. Frontend has 5 error parsers.
+**Rule:** one error envelope for the whole API.
+
+### Breaking changes without versioning
+Renaming `userName` → `user_name`, removing a field, changing types — all without a version bump.
+**Rule:** breaking change = new major. Old version stays until sunset date. Communicate via deprecation header `Deprecation: <date>` and `Sunset: <date>`.
+
+### Exposing internal IDs / database structure
+`GET /users/42` where `42` is the autoincrement DB primary key.
+**Why it bites:** id leaks user count, sequencing reveals signup velocity, easy to enumerate. Internal refactor (DB swap, sharding) breaks contract.
+**Rule:** opaque identifiers (UUID v7, ULID, or surrogate slug). DB id stays internal.
+
+### Hidden state in query params
+`GET /users?limit=50&filter[status]=active&sort[name]=asc&include=addresses,roles&fields=id,name,email&page=3...`
+Six concepts in URL, parsing nightmare, no schema validation.
+**Rule:** if a "list" endpoint has > 4 query params, design a structured filter type or split into multiple endpoints.
+
+### `200 OK` with `{"error": ...}` body
+Failed but returned 200. Frontend has to parse body to know if it succeeded. CDN caches the "error" response.
+**Rule:** HTTP status reflects success/failure. `4xx` for client errors, `5xx` for server errors. Always.
+
+### Returning partial success silently
+Bulk endpoint accepts 100 items, succeeds for 87, fails for 13, returns 200 with no breakdown.
+**Rule:** explicit per-item result array, OR fail the whole request, OR use `207 Multi-Status` with per-item details.
+
+### Versioning everything as v1 forever
+Adding optional fields, deprecating old ones, but never bumping the version. After 2 years, "v1" looks nothing like the original.
+**Rule:** name versions honestly. Or use header-based versioning with explicit deprecation.
+
+### CORS wildcard with credentials
+`Access-Control-Allow-Origin: *` AND `Access-Control-Allow-Credentials: true` — browsers reject this anyway, but seeing it in code = misconfigured intent.
+**Rule:** explicit origin allowlist; never `*` with credentials.
+
+## Decision Framework
+
+| Situation | Choice |
+|---|---|
+| Mutating endpoint | POST/PUT/PATCH + idempotency key |
+| Listing changing collection | Cursor pagination |
+| Listing stable small set | Page/size pagination acceptable |
+| Need to filter on 5+ axes | Reconsider — split endpoints, or POST /search with structured body |
+| Bulk operation | Limit batch size; return per-item status array |
+| Long-running operation | `202 Accepted` + `Location: /jobs/{id}` polling, OR webhook on completion |
+| Sensitive update | Require fresh auth (re-auth or step-up) |
+| Adding new optional field | Minor version (or no bump) |
+| Removing/renaming/changing type | Major version, deprecation timeline |
+| Internal vs external API | More flexibility internally; stricter discipline externally |
+
+## Cost Model
+
+| Decision | Cost when wrong |
+|---|---|
+| No idempotency key | Duplicate writes from retry storm; fix is per-endpoint, takes weeks per service |
+| `OFFSET` pagination on big tables | Page 1000 = 50ms → 5s as data grows; users see "loading…" forever |
+| Status code wrong | Client error handlers get fragile, observability dashboards mislead |
+| Breaking change without version | Every consumer breaks at deploy time; rollback may take hours |
+| Exposing internal DB id | One refactor away from leaking implementation; can't easily migrate to sharding |
+| `Cache-Control: public` on per-user data | Privacy incident, cross-user data leak |
+
+## Red Flags in Diff
+
+- New endpoint missing `Idempotency-Key` handling on POST/PUT/PATCH → flag.
+- New list endpoint without `limit` or with no max-limit enforcement → flag.
+- New error response not matching the project's error envelope shape → flag.
+- New endpoint reusing an existing version (`/v1/...`) but adding a breaking change → flag major-bump needed.
+- `POST /api/<verb>` style introduced when project uses RESTful nouns → flag.
+- Internal DB primary key (autoincrement integer) exposed in a response → flag.
+- New endpoint returning `200` on logical failure → flag.
+- Bulk endpoint without per-item result array → flag.
+- New 5xx code being returned for client-side validation errors → flag.
+- CORS config allowing wildcard origin AND credentials → flag immediately.
+- New endpoint without rate-limit middleware → flag if it's potentially expensive (DB writes, computes, external calls).
+- Response payload includes fields not declared in the project's API spec / OpenAPI doc → flag (drift).

package/knowledge/references/arch-patterns.md

@@ -0,0 +1,106 @@
+---
+tags: [architecture, design, complexity, refactor, boundaries, service-split]
+stack_signals: []
+summary: |
+  Architectural decision patterns — prefer the cheapest abstraction that
+  survives 6 months. Boundary cost framing for service splits, shared
+  modules, and async hops.
+when_to_load: |
+  COMPLEX tasks; task requires architectural decisions; Architect or Planner
+  is reasoning about new components, services, or boundaries; refactor scope
+  spans multiple modules or introduces a new abstraction layer.
+agent_hints: [architect, planner, logic-reviewer, challenger-reviewer]
+---
+
+# Architecture Patterns — Senior Stance
+
+## When this applies
+Load on COMPLEX tasks, when task requires architectural decisions, or when Architect/Planner is reasoning about new components, services, or boundaries.
+
+## Default Stance
+Pick the cheapest abstraction that survives the next 6 months — not the next 5 years. Premature abstraction costs more than wrong abstraction. Reuse > generalize. Boundaries are expensive: every async hop, every service split, every shared module is a maintenance liability that must pay rent in actual decoupling, scaling, or team-ownership benefit. Default to inline / function / module before service / queue / framework.
+
+## Patterns (use these)
+
+### Sync vs Async boundary
+- **Sync** when caller needs result for next decision. HTTP request-response, function call, DB query.
+- **Async** when caller doesn't block on the work AND failure can be retried independently. Email send, analytics push, cache warmup.
+- **Choose async only if**: (a) latency budget allows it, (b) downstream can be retried idempotently, (c) you have observability for the queue.
+
+### Idempotency by design
+Every external-facing write endpoint accepts an `idempotency-key` (header or body). Server stores `(key, request-hash) → response` for 24h. Replays return cached response. Without this, every retry is a potential dup-write bug.
+
+### Strong invariants at the edge
+Validate input at the system boundary (controller / route handler), then trust internal code. Don't re-validate in every layer. The cost of "defensive everywhere" is unreadable code AND it doesn't actually catch bugs — bugs come from missing validation, not from "we only validated once".
+
+### Failure modes named explicitly
+For every new service/handler, list in the plan: what happens on (a) downstream timeout, (b) downstream 5xx, (c) partial write, (d) duplicate request, (e) caller disconnects mid-write. If you can't answer, you don't have a design.
+
+### Single source of truth
+For any piece of state, exactly one component owns the write. Everyone else reads. Multi-writer state without a coordination protocol = race condition waiting to ship.
+
+## Anti-Patterns (DO NOT)
+
+### Premature service split
+Splitting a function into a microservice because "it might scale" but it has zero independent scaling pressure today.
+**Why it bites:** every cross-service call adds 1-50ms latency, retry logic, network failure modes, deploy coordination, observability gap, and a team boundary that may not match the actual ownership. Roll back via merge is much harder than roll forward via split.
+**Sign:** the new service has the same deploy cadence and team as the caller.
+
+### Generic abstraction layer at the start
+"Repository" / "Service" / "Strategy" pattern wrapping a single concrete implementation, "for future extension".
+**Why it bites:** you pay the indirection cost (3 files instead of 1, harder to navigate, mental model overhead) for an extension that 80% of the time never comes. When it comes, the abstraction usually doesn't fit anyway because the second use case has different shape.
+**Rule:** wait for the second concrete use case, then refactor.
+
+### Shared mutable state across modules
+Singletons holding cache, config, or connection state mutated from multiple call sites.
+**Why it bites:** test isolation breaks. Hot reload breaks. Race conditions appear at scale, not in dev. One service touched the singleton in a different module last week and you don't know.
+**Rule:** if it's mutable and shared, put it behind a single owning module with a narrow interface, or pass it explicitly.
+
+### Async for what's actually sync
+Wrapping a fast in-process function in a queue + worker because "it's cleaner".
+**Why it bites:** debug surface explodes (queue, worker, retry, DLQ, observability), latency goes up (queue lag), and you have eventually-consistent state where strongly-consistent state was correct.
+**Sign:** the worker reads result from DB and the caller polls for it.
+
+### Cross-cutting framework before need
+Building a generic event bus / plugin system / DSL before there are 3 concrete users.
+**Why it bites:** you're designing in the dark. By the time real users appear, the API is wrong.
+**Rule:** copy-paste 3 times, then extract.
+
+### Layered architecture as ritual
+Auto-creating Controller → Service → Repository → Entity layers for endpoints that just `SELECT` and return.
+**Why it bites:** 4 files to add a column. Reading any single piece of code requires opening 4 tabs.
+**Rule:** if the layer adds zero logic, delete it. Keep layers where logic lives.
+
+## Decision Framework
+
+| Situation | Default | Reason |
+|---|---|---|
+| New CRUD endpoint, no logic | Inline in route handler | Layer count = logic count |
+| New write endpoint with side-effects | Sync core + async side-effect via queue | Side-effects retry independently |
+| Need to share state between requests | Redis / DB / explicit cache layer | Never module-level globals |
+| New cross-team boundary needed | Library / interface in same repo first | Service split only when team owns deploy |
+| State machine with 3+ states | Explicit state column + transition fn | Don't infer state from booleans |
+| Read-heavy aggregation | Materialized view / read replica | Don't do app-side aggregation across millions of rows |
+| Write contention point | Queue + single worker | Avoid multi-writer races |
+
+## Cost Model (rough, defaults)
+
+| Decision | Cost when wrong |
+|---|---|
+| Service split | 2-4 weeks to undo (re-merge, re-deploy, re-observability) |
+| Async for sync work | Latency +50ms minimum, debug 5x harder |
+| Generic abstraction prematurely | 2-3 days dev time, plus ongoing reading cost forever |
+| Missing idempotency key | First prod retry → duplicate write → data corruption incident |
+| Shared mutable singleton | Race condition at scale; not reproducible in dev |
+| Layered architecture without logic | 4x code volume, 2x review time, no benefit |
+
+## Red Flags in Diff (reviewer hunts these)
+
+- New service / module / package introduced for a single caller — flag for justification.
+- New abstraction with one concrete impl — flag for "wait for second user".
+- Async path added but caller polls for result — flag as accidental complexity.
+- Module-level `let` / `var` mutated in handler code — flag as shared mutable state.
+- Write endpoint without idempotency key in route signature — flag as retry hazard.
+- New layer (controller/service/repo) with no logic, just pass-through — flag as ritual.
+- "TODO: handle retry" / "for future extension" comments — fail-fast: either handle now or remove the comment.
+- New interface with single implementer + `*Impl` suffix — almost always wrong.

package/knowledge/references/caching.md

@@ -0,0 +1,190 @@
+---
+tags: [caching, cdn, redis, http-cache, react-query, swr, invalidation, staleness]
+stack_signals: []
+summary: |
+  Caching design and invalidation discipline — every cache layer is a stale
+  copy. Patterns for HTTP cache, CDN, Redis, React Query / SWR, Next.js
+  Data/Route caches, and the invalidation contract that makes them safe.
+when_to_load: |
+  Task touches HTTP cache headers, CDN config, in-memory cache, Redis cache,
+  browser cache, query cache (React Query / SWR / RTK Query / Apollo),
+  Next.js Data/Route/Full-Route cache, server-side render cache, or
+  materialized views. Diff with cache TTLs, invalidation logic, revalidate,
+  cacheTag, cacheLife, staleTime, Cache-Control, ETag, or mutate() qualifies.
+agent_hints: [logic-reviewer, performance, challenger-reviewer]
+---
+
+# Caching — Senior Stance
+
+## When this applies
+Load when task touches: HTTP cache headers, CDN config, in-memory cache, Redis cache, browser cache, query cache (React Query / SWR / RTK Query / Apollo), Next.js Data/Route/Full-Route cache, server-side render cache, materialized views. Reviewer auto-loads when diff includes cache TTLs, invalidation logic, `revalidate`, `cacheTag`, `cacheLife`, `staleTime`, `Cache-Control`, `ETag`, `mutate()`.
+
+## Default Stance
+The hardest part of caching isn't speed — it's correctness under invalidation. Every cache layer is a copy that may be stale. Add a cache only when (a) you've measured the underlying call is expensive, (b) the data has a clear invalidation event or a tolerable staleness window, (c) you've designed how the cache empties. If you can't answer "what happens when the source changes?" — don't cache yet.
+
+## Patterns (use these)
+
+### Choose the layer based on shape
+
+| Layer | Good for | Cost |
+|---|---|---|
+| HTTP / CDN | Public, immutable or long-TTL responses | Hard to invalidate per-user |
+| Browser HTTP cache | Static assets, idempotent GET | User-controlled, can be bypassed |
+| Service-worker cache | Offline-first, PWA | Complexity, version skew |
+| In-memory app cache (per-instance LRU) | Hot small data with short TTL, per-process | Inconsistent across instances, lost on restart |
+| Redis cache | Cross-instance hot reads, sessions, rate state | Network round-trip, single point |
+| DB query cache (built-in or materialized view) | Aggregations, joins refreshed periodically | Refresh window staleness |
+| Client-side query cache (React Query / SWR) | UI data, deduped fetches | Per-tab; needs explicit invalidation |
+| Edge cache (Vercel, Cloudflare) | Per-user-segment static-ish content | Tag-based invalidation needed |
+
+Pick the **outermost** layer that matches the access pattern. Caching deeper than necessary multiplies invalidation surfaces.
+
+### Invalidation strategy — name it explicitly
+
+For every cache, document one of:
+- **TTL only** — accept staleness up to TTL. Simplest, default for read-heavy approximate data.
+- **Event-driven** — write path also invalidates (delete key, bump tag, increment version). Use when stale = wrong.
+- **Versioned key** — key includes a version/etag; on change, new version auto-evicts old via TTL. Avoids the "did we forget to invalidate?" class of bug.
+- **Write-through** — write goes to both cache and source. Cache is always fresh; cost is doubled write latency.
+- **Read-through with refresh-ahead** — refresh proactively before expiry. Hides cold misses from users.
+
+### TTL — pick it deliberately
+
+- **Public read-mostly with weak freshness** — minutes to hours.
+- **User-specific read-mostly** — seconds to minutes.
+- **Computed aggregations** — depends on tolerable staleness; document it.
+- **Auth / permission decisions** — seconds at most. Stale auth = security bug.
+- **Always set a backup TTL even with event-driven invalidation** — bugs happen.
+
+### Cache-Aside (lazy loading) — the canonical pattern
+
+```
+read(key):
+  v = cache.get(key)
+  if v: return v
+  v = source.load(key)
+  cache.set(key, v, ttl=T)
+  return v
+```
+
+This is correct ONLY with stampede protection (see anti-patterns). Add it from day one.
+
+### Stampede protection
+Cold cache + high traffic = N concurrent loads of the same expensive thing. Pick one:
+- **Lock-around-fill** — first miss acquires a key-scoped lock, others wait or serve stale.
+- **Probabilistic early refresh (XFetch)** — on read, with probability proportional to how-close-to-expiry, refresh proactively. Smooths traffic.
+- **Single-flight in-process** — dedupe concurrent fills inside one instance. Doesn't help across instances; combine with one of the above.
+
+### Versioned keys for safe schema changes
+When the cached payload shape may change, include a version:
+```
+key = `user:v3:${id}`
+```
+Old version's keys evict naturally via TTL. No mass-purge needed. No "old version stuck in cache for a week" bugs.
+
+### Tag-based invalidation
+For Next.js / Cloudflare / Vercel edge: tag related entries (`['user:123', 'team:42']`), invalidate by tag on write. Avoids enumerating keys; matches "what changed in the source" to "what to evict".
+
+### Cache the result, not the request
+Cache key = a normalized representation of the **answer**, not the URL. Two different URLs that produce the same answer should hit the same cache slot. Two URLs with same query params in different order should normalize.
+
+### Negative caching
+Cache "not found" too — with shorter TTL. Otherwise a 404 hammered repeatedly causes repeated DB lookups.
+
+## Anti-Patterns (DO NOT)
+
+### No TTL ("we'll invalidate manually")
+**Why it bites:** invalidation bugs are forever. One missed write path = stale data permanently. Memory grows.
+**Rule:** TTL is mandatory. Even with event-driven invalidation, set a backup TTL ("at most this stale even if we screw up").
+
+### Cache stampede on hot key
+**Why it bites:** cache miss → 1000 simultaneous loads → DB CPU spike → DB latency up → all caches expire while loads run → worse stampede next minute.
+**Rule:** stampede protection from day one on any cache key with > 100 reads/sec.
+
+### Caching auth/permission decisions for minutes
+**Why it bites:** revoke a user's permission, they keep working for the cache TTL. Real security incident.
+**Rule:** auth cache TTL ≤ 30 seconds, OR invalidate on revoke event, OR don't cache auth at all.
+
+### Caching at multiple layers without invalidation alignment
+**Why it bites:** invalidate L1 (Redis) but L2 (CDN) still serves stale. Or browser HTTP cache holds the old response. Each layer has independent TTL.
+**Rule:** if you cache at multiple layers, invalidation must hit all of them. Document which layer holds what for how long.
+
+### `Cache-Control: public` on per-user data
+**Why it bites:** user A's response cached by CDN, served to user B. Privacy breach, data leak.
+**Rule:** per-user data → `Cache-Control: private` always. Or include user identifier in URL/key and use edge cache with proper key.
+
+### Storing huge payloads in cache
+**Why it bites:** 5MB cache entry × 10000 users = 50GB Redis. Cost and latency explode.
+**Rule:** cache references / IDs / small projections. Fetch full data on demand if needed. Or cache the bits actually rendered.
+
+### Reading-only cache, never refreshed
+**Why it bites:** TTL expires, cache empty, all reads go to DB until refilled. Cold-start tax on every TTL boundary.
+**Rule:** refresh-ahead or lock-around-fill so users never see the cold path.
+
+### Cache invalidation by enumerating keys
+**Why it bites:** "delete all `user:*` keys" → `KEYS user:*` → blocks Redis / iterates massive keyspace. On 10M keys = outage.
+**Rule:** tag-based invalidation, or version bump (atomic, instant), or accept TTL window.
+
+### Conditional caching ("only cache if user is logged out")
+**Why it bites:** branching makes invalidation logic non-uniform. Bug: a logged-in user's query slips into a public cache slot.
+**Rule:** different cache namespaces for different access categories. Don't share keys across auth boundaries.
+
+### Caching the bug
+You found a slow query → cache it → slow query is now hidden but still fires on miss. Cache hides production load, masks the real issue (missing index, N+1, wrong query).
+**Rule:** cache after fixing the underlying cost where reasonable. Cache as a layer, not a band-aid.
+
+### `revalidate: 0` / `cache: 'no-store'` everywhere "to be safe"
+**Why it bites:** every request = full backend hit. Wastes the entire caching infrastructure.
+**Rule:** opt-out caching is the wrong default. Pick a TTL that matches the staleness tolerance.
+
+### Different TTLs for the same data across endpoints
+**Why it bites:** one endpoint serves 10s-stale, another serves 5min-stale, user sees inconsistent state across pages.
+**Rule:** the staleness tolerance is a property of the data, not the endpoint. Document and align.
+
+## Decision Framework
+
+| Situation | Choice |
+|---|---|
+| Same data fetched many places in UI | Client query cache (React Query / SWR), shared key |
+| Public mostly-static page | CDN/edge cache + tag invalidation |
+| Per-user dashboard data | Per-user Redis key, short TTL, event-invalidate on write |
+| Expensive aggregation refreshed nightly | Materialized view in DB |
+| Hot read of a single small value (1000+/sec) | In-memory LRU per instance + Redis fallback |
+| Mutation invalidates many entries | Tag-based, OR version-bump pattern |
+| Auth/permission check | Don't cache, OR ≤30s TTL with explicit invalidate on grant change |
+| Analytics counter | Redis `INCR`, batched flush to source |
+| Image/asset | CDN + immutable URL with version hash |
+| Search results page 1, 2, 3 | Cache by `(query, page)`; invalidate by query on data change |
+
+## Cost Model
+
+| Layer | Hit cost | Miss cost (approx) |
+|---|---|---|
+| Browser HTTP | < 1ms | + full request to server |
+| CDN/edge | 5-30ms | + origin fetch |
+| In-memory LRU | < 100µs | + downstream load |
+| Redis (same region) | 0.5-1ms | + source load |
+| DB query cache | varies by warmness | + planning + execution |
+
+| Anti-pattern | Cost when wrong |
+|---|---|
+| No stampede protection | DB CPU spike during high traffic + cache flush |
+| No TTL with bug | Stale data accumulates, eventual user-facing wrongness |
+| Long auth TTL | Revoked perms still active = security |
+| Public cache on private data | Cross-user data leak |
+| Mass enumeration invalidate | Redis stall, possible outage |
+
+## Red Flags in Diff
+
+- New cache write without TTL set inline → flag.
+- New cache fill without stampede mitigation on a path the planner described as hot → flag.
+- `Cache-Control: public, max-age=...` on per-user response → flag immediately.
+- TTL > 60 seconds on auth / permission / billing-related data → flag.
+- `KEYS pattern*` or `SCAN` over the entire keyspace called from a write path → flag.
+- Cache invalidation that loops over a list to delete keys, list size unbounded → flag.
+- Cache key without version/namespace prefix in a codebase that uses them → flag.
+- Two endpoints caching the same logical data with different TTLs → flag.
+- Cache fill block under a single mutex covering unrelated keys → flag (lock too coarse).
+- New cache layer added without a "how does this get invalidated?" comment or doc → flag.
+- `staleTime: Infinity` / `revalidate: false` on a query whose data clearly changes → flag.
+- Cache configured with no `maxmemory` / eviction policy → flag (unbounded memory).