@loomfsm/bundle-code 0.1.0

package/knowledge/references/next-app-router.md

@@ -0,0 +1,231 @@
+---
+tags: [nextjs, app-router, rsc, route-handlers, layouts, frontend]
+stack_signals:
+  - language: [typescript, javascript]
+  - project_type: [frontend-app, monorepo]
+summary: |
+  Next.js App Router stance — Server Components by default, Client only where
+  needed, layered cache (data/route/full-route/edge) decided per route. Each
+  file convention has a specific contract; mixing them creates subtle bugs.
+when_to_load: |
+  Project uses Next.js ≥13 with App Router (app/ directory, not pages/).
+  Diff includes files under app/, 'use client'/'use server' directives,
+  loading.tsx, error.tsx, not-found.tsx, route.ts, layout.tsx, revalidate,
+  cacheTag, cacheLife, parallel/intercepted routes, or middleware.
+agent_hints: [logic-reviewer, performance, ui-consistency, api-contract]
+---
+
+# Next.js App Router — Senior Stance
+
+## When this applies
+Load when project uses Next.js ≥13 with App Router (`app/` directory, not `pages/`). Reviewer auto-loads when diff includes files under `app/`, `'use client'`/`'use server'` directives, `loading.tsx`, `error.tsx`, `not-found.tsx`, `route.ts`, `layout.tsx`, `revalidate`, `cacheTag`, `cacheLife`, parallel/intercepted routes, or middleware. Complements `react19.md` (which covers RSC primitives) — this file is router-specific.
+
+## Default Stance
+The App Router collapses concerns that used to live in separate places (data fetching, caching, layouts, error boundaries, middleware, route handlers). Each file convention has a specific contract; mixing them creates subtle bugs. Default to Server Components; mark Client only where you actually need it. Cache behavior is layered (data cache, route cache, full route cache, edge cache) — make caching decisions explicit per route, not by default.
+
+## Patterns (use these)
+
+### File conventions — know what each does
+- `page.tsx` — the route's UI. Default Server Component.
+- `layout.tsx` — wraps pages in this segment. Persists across navigation. Default Server Component.
+- `template.tsx` — like layout but re-renders on navigation. Use when state should reset.
+- `loading.tsx` — Suspense fallback for the route. Auto-wraps the page.
+- `error.tsx` — error boundary for the route. Must be Client Component.
+- `not-found.tsx` — rendered for `notFound()` calls.
+- `route.ts` (or `route.js`) — HTTP handler. Cannot coexist with `page.tsx` in same segment.
+- `middleware.ts` — runs before request, at the edge.
+
+### Server Components by default
+A new component is a Server Component unless you mark it `'use client'`. Server Components:
+- Run only on the server, never ship to the browser.
+- Cannot use hooks (`useState`, `useEffect`, `useRef`, etc.).
+- Can be `async` and fetch data directly.
+- Cannot pass non-serializable values (functions, classes) to Client Components.
+
+### Client Components — at the leaves
+- `'use client'` directive at top of file.
+- Mark only what needs interactivity / browser APIs / hooks.
+- Wrap a small interactive piece, leave the rest Server.
+- Server Components can render Client Components, AND can pass them children prop (slot pattern) — Client renders its slot Server-rendered content.
+
+### Data fetching: where and how
+- **Server Components**: `await fetch(...)` directly in the component. Next dedupes identical fetches per request, caches per default policy.
+- **Server Actions**: `'use server'` functions. Can be invoked from Client Components for mutations. Auth check at the top.
+- **Route Handlers** (`route.ts`): for non-RSC consumers — webhooks, JSON APIs, third-party callbacks.
+- **Client Components**: still use TanStack Query / SWR for client-side data needs (real-time, optimistic, complex caching).
+
+### Caching layers (Next 14+)
+Four layers, each with different invalidation:
+1. **Request Memoization** — per-request dedupe of identical fetches. Automatic.
+2. **Data Cache** — persistent across requests. `fetch` with `next: { revalidate: N }` or `cache: 'no-store'`.
+3. **Full Route Cache** — pre-rendered HTML + RSC payload. Static by default; opt out with dynamic functions (`cookies()`, `headers()`, `searchParams`).
+4. **Router Cache** — client-side, in-memory, soft-navigation cache.
+
+Invalidation: `revalidatePath()`, `revalidateTag()`, `revalidate` time-based.
+
+In Next 16 (Cache Components): `'use cache'` directive + `cacheLife` / `cacheTag`. New PPR (Partial Prerendering) model. If you're on 16, see those primitives — different from 14/15 cache.
+
+### Server Actions: secured at the function
+```ts
+'use server';
+export async function deletePost(formData: FormData) {
+  const session = await getServerSession();
+  if (!session) throw new Error('unauthorized'); // NEVER skip
+  // ... rest
+}
+```
+- Auth check at top of EVERY action body.
+- Validate inputs with a schema (Zod). FormData is untyped.
+- Don't return huge data. Return success flag, errors, redirect target.
+
+### Loading + Error UX
+- Co-locate `loading.tsx` and `error.tsx` per route segment.
+- `loading.tsx` is wrapped in `<Suspense>` automatically — granular suspense by route.
+- `error.tsx` MUST be `'use client'`. Receives `error` and `reset` props.
+- `notFound()` → renders nearest `not-found.tsx`.
+
+### Streaming + Suspense
+- Page can be partially streamed: layout renders first, slow data Suspends, finishes streaming when ready.
+- Place `<Suspense>` around slow data sources. Loading UI shows while waiting.
+- One coarse Suspense around everything → users wait for slowest piece. Multiple fine Suspense → progressive reveal.
+
+### Parallel and Intercepted Routes
+- **Parallel** (`@slot/page.tsx`): render multiple pages in same layout simultaneously. Use for dashboards with independent regions.
+- **Intercepted** (`(.)foo`, `(..)foo`): show one route in the context of another (e.g., photo modal over feed). Browser refresh shows full route.
+- Powerful, but increases mental load. Use only when payoff is clear.
+
+### Middleware
+- Runs on every matching request at the Edge runtime.
+- Auth checks, redirects, A/B routing.
+- Cannot do heavy work — runs on every request.
+- Use `matcher` config to limit which routes run middleware.
+
+### Generating routes
+- `generateStaticParams` for static generation.
+- `dynamic = 'force-dynamic'` to opt out.
+- `revalidate = 60` for ISR-like behavior.
+Set explicitly per route — defaults change between Next versions.
+
+## Anti-Patterns (DO NOT)
+
+### `'use client'` on the root layout
+Marks ENTIRE app tree as Client. You lose all Server Component benefits.
+**Rule:** layout stays Server. Wrap interactive children in their own Client components.
+
+### Big `'use client'` boundary at the top of a route
+Page is mostly server-renderable but one button needs `onClick` → marking the whole page Client → entire tree shipped to browser.
+**Rule:** isolate the interactive piece. Server page → renders Client button only.
+
+### Server Action without auth check
+**Why it bites:** action is callable directly via fetch from anywhere — components are not security boundaries.
+**Rule:** every Server Action begins with explicit auth check. (Repeated from react19.md because it's the #1 issue.)
+
+### Reading `request` / cookies in a layout that's static
+Layout uses `cookies()` → entire route segment opts out of static rendering → unexpectedly dynamic.
+**Rule:** know what you're opting out of. If you need cookies, accept the dynamic cost; if not, isolate the cookie use.
+
+### `fetch` without `cache` option, then surprised by stale data
+Default cache behavior changes between Next versions and per-route. Implicit defaults bite you.
+**Rule:** explicit `cache: 'force-cache' | 'no-store'` and `next: { revalidate: N, tags: [...] }` per fetch. Don't rely on memory of defaults.
+
+### Mutation in Server Component
+```ts
+async function Page() {
+  await deletePost(id); // BAD
+  return <div>...</div>;
+}
+```
+Server Components are GET-equivalent. Mutations go through Server Actions (POST) or route handlers.
+**Rule:** mutation paths use Server Actions or route handlers. Server Components only read.
+
+### Shared `'use client'` utility with re-exports
+File marked Client, re-exports a Server-only function. Imports cross the boundary in unexpected ways.
+**Rule:** keep Client and Server utility files separate. Import boundary follows directive boundary.
+
+### `error.tsx` not marked Client
+File is Server Component (default), but error boundaries must be Client. Build fails or runtime error occurs.
+**Rule:** `error.tsx` always starts with `'use client'`.
+
+### One coarse `<Suspense>` wrapping everything
+Slowest data source dictates user-visible wait time. No streaming benefit.
+**Rule:** Suspense at meaningful UI region boundaries (sidebar, main, footer, slow card).
+
+### Middleware doing DB / heavy work
+Middleware fires per request at the edge → can't reach app DB cheaply, adds 50-200ms per request.
+**Rule:** middleware = lightweight redirects/auth checks. Heavy work in route handlers.
+
+### `searchParams` used in static page
+Page uses `searchParams` → forces dynamic rendering → no static optimization → slower TTFB.
+**Rule:** know that `searchParams` is dynamic. Either accept dynamic, or use `generateStaticParams` for known param sets.
+
+### Returning JSX from Server Action
+Server Actions return data; UI is rendered by the page or component on response.
+**Rule:** action returns plain JSON-serializable data. Component re-renders with that data.
+
+### `revalidate: 0` everywhere "to be safe"
+Defeats Next's caching, every request hits backing source.
+**Rule:** pick TTL based on data freshness needs.
+
+### Calling Client-only APIs inside Server Component
+`window`, `document`, `localStorage` — runtime error or build error.
+**Rule:** access via `'use client'` boundary only. Use `useEffect` for browser APIs.
+
+### Imports from Client Component into Server Component creating cycles
+Client Component imports from a server-only module; server-only module imports from a Client Component. Bundler chokes or duplicates code.
+**Rule:** clean dependency tree. Server depends on Server; Client may depend on Client + serializable Server exports.
+
+### Migrating Pages Router incrementally without strategy
+Keeping `pages/` and `app/` simultaneously, sharing components without checking which directives propagate.
+**Rule:** plan migration per-segment. Don't expect Pages Router middleware/_app to apply to App Router routes.
+
+## Decision Framework
+
+| Need | Choice |
+|---|---|
+| Read DB and render | Server Component with `await` |
+| Form submit | Server Action + `useActionState` |
+| Optimistic UI | `useOptimistic` (Client Component, see react19.md) |
+| Public JSON API | Route handler `route.ts` |
+| Webhook receiver | Route handler with signature verification |
+| Auth redirect | Middleware (lightweight) or in layout/page |
+| Real-time data | Client Component + WebSocket / SSE / polling |
+| Slow data + fast layout | Suspense around slow part; layout renders first |
+| Data shared across pages | Layout component fetches; pages receive via children render |
+| Mutating data + revalidating | Server Action calls `revalidatePath` / `revalidateTag` |
+| Static page with occasional updates | `revalidate: N` (ISR) |
+| Per-user dynamic page | `dynamic = 'force-dynamic'` or use of cookies/headers |
+| Multiple regions in a dashboard | Parallel routes (`@slot`) |
+| Modal that's also a real route | Intercepted routes |
+
+## Cost Model
+
+| Pattern | Cost / Win |
+|---|---|
+| Server Component | 0 client JS for that component |
+| `'use client'` on a leaf | +5-30KB JS bundle for that island |
+| `'use client'` on root layout | Entire app shipped to browser |
+| Server Action call | 1 round trip + serialization |
+| Static route (full prerender) | Sub-100ms TTFB from CDN |
+| `dynamic = 'force-dynamic'` | Every request hits the server; TTFB depends on backing data |
+| ISR with revalidate=60 | First request after 60s rebuilds; users see brief stale |
+| Middleware on every route | +5-50ms per request at the edge |
+| Coarse Suspense | Wait for slowest data → entire page blocked |
+| Granular Suspense | Progressive reveal; better perceived perf |
+
+## Red Flags in Diff
+
+- `'use client'` added to `app/layout.tsx` or any top-level layout → flag (massive bundle impact).
+- `'use client'` added to a component without any hooks / event handlers / browser APIs → flag (probably can stay Server).
+- Server Action without explicit auth check at top of body → flag immediately.
+- New `error.tsx` not starting with `'use client'` → flag.
+- New `fetch(...)` in Server Component without explicit `cache` / `next.revalidate` config → flag (implicit-default risk).
+- `cookies()` / `headers()` used in a layout that's expected to be static → flag (forces dynamic render of all child pages).
+- Server Action returning JSX or a class instance → flag (must be JSON-serializable).
+- New middleware doing DB / heavy work → flag.
+- Whole route or page wrapped in single `<Suspense>` → flag (no streaming benefit).
+- `revalidate: 0` everywhere → flag (caching defeated).
+- New `searchParams` use in a page expected to be statically generated → flag.
+- Server Component file imports from a `'use client'` file and uses non-serializable export → flag.
+- Route handler `route.ts` AND `page.tsx` in same segment → flag (illegal).
+- `redirect()` inside Server Action without idempotency consideration → flag.
+- New parallel/intercepted route without `default.tsx` for the parallel slot when no match → flag (will crash).

package/knowledge/references/observability.md

@@ -0,0 +1,169 @@
+---
+tags: [observability, logging, tracing, metrics, alerts, slo, opentelemetry]
+stack_signals: []
+summary: |
+  Observability design — logs for forensics, metrics for alerts, traces for
+  request paths. Every new endpoint, job, or external dependency emits at
+  least one metric, structured logs, and propagates trace context.
+when_to_load: |
+  Task touches logging, structured logs, tracing (OpenTelemetry, distributed
+  tracing), metrics emission, health checks, alerting rules, dashboards, or
+  error reporting. Diff including new endpoints, new background jobs, new
+  external integrations, or any change that ships behavior-the-team-needs-to-watch
+  also qualifies.
+agent_hints: [logic-reviewer, performance, challenger-reviewer]
+---
+
+# Observability — Senior Stance
+
+## When this applies
+Load when task touches: logging, structured logs, tracing (OpenTelemetry, distributed tracing), metrics emission, health checks, alerting rules, dashboards, error reporting. Reviewer auto-loads when diff includes new endpoints, new background jobs, new external integrations, or any change that ships behavior-the-team-needs-to-watch.
+
+## Default Stance
+You can't fix what you can't see. Every new endpoint, job, or external dependency MUST emit at least one metric, one structured log on entry/exit, and propagate trace context. Logs are for forensics, metrics are for alerts, traces are for "where did this request go". The three are complementary, not interchangeable. Sampling is fine; not emitting at all is not.
+
+## Patterns (use these)
+
+### Structured logs
+- JSON format. One event per line. Machine-parseable.
+- Required fields: `timestamp`, `level`, `message`, `service`, `request_id` (or `trace_id`).
+- Domain fields: `user_id`, `task_id`, `endpoint`, `duration_ms`, etc.
+- NEVER log sensitive data: passwords, tokens, full credit card, full SSN. Hash or redact at log boundary.
+
+```json
+{"ts":"2026-05-10T12:34:56Z","level":"info","msg":"user.created","service":"api","trace_id":"abc","user_id":"u_123","duration_ms":42}
+```
+
+### Trace context propagation
+- Every request gets a `trace_id` at the edge. Pass it downstream via header (`traceparent` per W3C Trace Context, or X-Request-ID).
+- Each service emits its span with its operation, duration, status.
+- Log lines include `trace_id` so you can correlate log events with the trace.
+
+### Metric types
+- **Counter** — monotonic increasing (`requests_total`, `errors_total`). Compute rate via `rate(counter[5m])` in Prometheus.
+- **Gauge** — point-in-time value (`active_connections`, `queue_depth`). Goes up and down.
+- **Histogram** — distribution (request duration, payload size). Compute p50, p95, p99 via `histogram_quantile`.
+
+Naming: `<domain>_<entity>_<unit>`: `http_request_duration_seconds`, `db_query_duration_seconds`, `cache_hits_total`. Lowercase snake_case.
+
+### RED method (per request-driven service)
+For every endpoint:
+- **R**ate — requests per second.
+- **E**rrors — error rate (4xx + 5xx, OR business error count).
+- **D**uration — p50 / p95 / p99 latency.
+
+Dashboard: one row per endpoint, columns R-E-D. Glance to see "what's broken".
+
+### USE method (per resource)
+For every resource (CPU, memory, disk, connection pool, queue):
+- **U**tilization — % busy.
+- **S**aturation — queue depth / wait time.
+- **E**rrors — count of errors talking to this resource.
+
+### Service Level Objectives (SLOs)
+- Define a metric (e.g., "99.5% of requests < 500ms over 30 days").
+- Track an error budget (1 - SLO target).
+- Alert when error budget burn rate is high (will exhaust before period end).
+- Don't alert on every breach — alert on burn-rate over a window.
+
+### Alerting hygiene
+- **Symptom-based**, not cause-based. "p95 latency above 1s for 5 min" is a symptom alert. "CPU above 80%" is a cause alert (often false-positive).
+- **Actionable** — every alert must have a runbook link explaining what the operator does next.
+- **Escalation tiers** — page only for things that need immediate human action. Slack-channel alerts for things that need attention within hours.
+- **No mystery alerts** — if oncall doesn't know why an alert fired, the alert is broken. Fix or delete.
+
+### Health checks
+- **Liveness** — "is process up". Cheap, never depends on external services. Used by orchestrator (k8s) to restart.
+- **Readiness** — "can serve traffic". May check DB connection, downstream service, cache. Used by load balancer to drain.
+- Don't conflate them. Liveness failing = restart me; readiness failing = stop sending traffic.
+
+### Error reporting
+- Capture error + stack trace + request context (user_id, request_id, path, params).
+- Group by error fingerprint (Sentry, Honeybadger, etc.).
+- Tag with deploy version → "this error started at deploy 4.2.0".
+- Don't capture every error: validation errors and 4xx are noise. Capture 5xx and unexpected exceptions.
+
+## Anti-Patterns (DO NOT)
+
+### Logging without structure
+`logger.info(\`User \${userId} did \${action} at \${time}\`)` → unparseable freeform string.
+**Why it bites:** can't filter, group, or aggregate. Every grep is a one-off.
+**Rule:** structured fields always. `logger.info('user.action', { user_id, action, ts })`.
+
+### Logging sensitive data
+`logger.info('login attempt', { email, password })`. Tokens, secrets, full PII in logs = breach surface.
+**Rule:** redact at log boundary. Reject log lines containing forbidden patterns in CI (regex check).
+
+### Excessive logging on hot paths
+Every request → 50 log lines. At 1k QPS, you're emitting 50k lines/sec. Log pipeline backed up; storage cost spikes.
+**Rule:** ONE log per request entry, ONE per exit (with duration). Detail logs at DEBUG level only, sampled or dynamically enabled.
+
+### Metric names that are unique per request
+`requests_total{user_id="u_12345"}` → cardinality explosion. Prometheus can't handle 1M time-series.
+**Rule:** metric labels are LOW cardinality (≤100 unique values). High-cardinality data goes in logs/traces, not metrics.
+
+### Alerting on every breach
+"Latency exceeded threshold" alert fires once per minute when service is degraded. Operator drowns.
+**Rule:** sustained breach (> 5 min) OR error budget burn rate. Alerts have hysteresis.
+
+### Cause-based alerts everywhere
+"CPU > 80%" — but the service is fine, the autoscaler will handle it.
+**Rule:** alert on user-impacting symptoms. CPU/memory only when no symptom-level alert exists for the failure mode.
+
+### No trace context across services
+Service A has `trace_id=abc`, service B logs without it. Can't follow a request across services.
+**Rule:** propagate trace context via header at every hop. Library / middleware ensures this; don't rely on per-handler discipline.
+
+### Logging plus printing
+`console.log(...)` AND `logger.info(...)` for the same event. Or `print('debug')` left in.
+**Rule:** one logger, configured per environment. No bare `print` / `console.log` in committed code.
+
+### Unmonitored "fire and forget" jobs
+Background job runs, fails silently, no metric emitted. Bug ships when output dashboard shows zero new records for a day.
+**Rule:** every job emits start/finish/duration, success/failure. Alert on missing successful run.
+
+### Health check that always returns 200
+`GET /health → 200 OK` even when DB is down. Load balancer keeps sending traffic to broken instance.
+**Rule:** readiness check actually verifies dependencies it serves with.
+
+### Sampling errors
+1% sampled error reporting: 99% of errors invisible.
+**Rule:** sample successful traces aggressively (1-10%). Capture errors at 100% (or near-100%).
+
+## Decision Framework
+
+| Need | Tool |
+|---|---|
+| "What happened in this specific request?" | Distributed trace + structured logs |
+| "How is the system performing right now?" | Metrics dashboard (RED + USE) |
+| "Wake me when something is broken" | Alerts on SLO burn / error budget |
+| "Where's the error coming from?" | Error reporting (Sentry-class), grouped by fingerprint |
+| New endpoint | Add: 1 entry log, 1 exit log, RED metrics, span |
+| New background job | Add: start/finish logs, duration metric, success/fail counter, dead-letter queue with alert |
+| New external dependency | Add: latency histogram, error counter, circuit-breaker state metric |
+| Slow-query investigation | Trace → see which span is slow → check that span's logs |
+
+## Cost Model
+
+| Item | Cost magnitude |
+|---|---|
+| Structured log line, indexed | $0.50-2 per GB ingested (varies by vendor) |
+| Metric time-series with low cardinality | $0.01-0.10 per series per month |
+| Distributed trace span | $0.50-2 per million spans (often sampled to 1-10%) |
+| Error reported & grouped | $0.10-1 per event (Sentry pricing tier) |
+| 1 mystery alert (waking oncall) | Hours of human time + trust erosion |
+
+## Red Flags in Diff
+
+- New endpoint without entry/exit log lines or duration metric → flag.
+- New `console.log` / `print` in non-test code → flag.
+- New log line containing `password`, `token`, `secret`, `api_key` substrings → flag immediately (security + observability).
+- New metric label using request-unique IDs (`user_id`, `request_id`) → flag (cardinality blowup).
+- New alerting rule without runbook reference / linked doc → flag.
+- New alert fires on instantaneous breach (no duration window) → flag (flap risk).
+- New external HTTP/DB call without timeout AND without error metric → flag.
+- Health check returning 200 statically → flag.
+- New background job without success/failure metric → flag.
+- Trace context not propagated across new service boundary (header not forwarded) → flag.
+- New error swallowed silently (`try { ... } catch {}`) without log/metric → flag.
+- Logging large payloads (full request body, full DB row) on hot path → flag (cost + PII risk).

package/knowledge/references/optimization-strategy.md

@@ -0,0 +1,197 @@
+---
+tags: [performance, optimization, profiling, latency, throughput, slo]
+stack_signals: []
+summary: |
+  Strategy-level performance discipline — measure before you optimize. Profile,
+  hypothesize, change one thing, measure again. Pairs with platform-specific
+  perf-*.md files.
+when_to_load: |
+  Task touches performance-sensitive code, "make it faster" is in scope, a
+  perf regression is suspected, or a feature has explicit latency/throughput
+  requirements. Preemptive load when CLAUDE.md or task mentions SLO, latency
+  budget, "scale to N users", or similar.
+agent_hints: [performance, logic-reviewer, challenger-reviewer]
+---
+
+# Optimization Strategy — Senior Stance
+
+## When this applies
+Load when task touches performance-sensitive code, when "make it faster" is in scope, when a perf regression is suspected, or when a feature has explicit latency/throughput requirements. Performance Agent loads this in addition to platform-specific perf-{stack}.md. Load preemptively when CLAUDE.md or task mentions SLO, latency budget, "scale to N users", or similar.
+
+## Default Stance
+Don't optimize what you haven't measured. Most "obviously slow" code is fast enough; most "obviously fine" code has surprises. Profile first, hypothesize, change one thing, measure again. Optimization without measurement is decoration. Once you've measured, fix the biggest hot spot — the long tail rarely matters.
+
+The order: **correct → tested → measured → optimized**. Skip steps and you're guessing.
+
+## Patterns (use these)
+
+### Measure before, measure after
+- Establish a baseline: what's slow, by how much, under what load?
+- Make the change.
+- Re-measure under the same conditions.
+- If you can't tell the difference, you didn't optimize anything.
+
+### Profile to find hot spots
+Tools by stack:
+- Node.js: `--prof` + processed with `--prof-process`, or `clinic.js`, or Chrome DevTools.
+- Python: `cProfile` + `snakeviz` or `py-spy` (sampling, low overhead, prod-safe).
+- JVM: `async-profiler`, `JFR`.
+- Go: `pprof` (built-in).
+- Browser: Chrome DevTools Performance tab; Lighthouse for page-level.
+- DB: EXPLAIN ANALYZE; `pg_stat_statements`.
+
+Look for: tall stack frames, repeated work per call, calls into expensive primitives (DB, network, parse).
+
+### Latency vs throughput
+Different goals, different fixes:
+- **Latency** (single-request time): reduce work in the request path. Cache, denormalize, precompute, prefetch.
+- **Throughput** (aggregate ops/sec): reduce contention, parallelize, batch, queue.
+A change that improves latency may hurt throughput (e.g., always-fresh cache lookup beats stale-while-revalidate for latency, but more DB load → worse throughput).
+
+### Big-O matters when N is large
+- 1000 items in a list: O(N) vs O(N²) matters → microseconds vs milliseconds.
+- 1M items: O(N) vs O(N²) matters → seconds vs minutes.
+- 10 items: O(N²) is fine; readability beats cleverness.
+Don't optimize O(N) → O(log N) when N=10. Don't tolerate O(N²) when N=10K.
+
+### Hot loop discipline
+For code that runs millions of times per second:
+- Avoid allocations inside the loop (object creation, array spread, string concat).
+- Avoid closures/functions created per iteration.
+- Hoist invariants out of the loop.
+- Batch where possible.
+
+For code that runs 100x: clarity beats micro-optimization.
+
+### Caching as last resort, not first
+Cache is hard (invalidation, staleness, stampedes — see caching.md). Add a cache only when:
+- The underlying call is measurably expensive.
+- The data has clear invalidation semantics.
+- You've designed how the cache empties.
+- The hit rate justifies the complexity.
+
+Often the right answer is "fix the slow query" (add index, denormalize, materialize) — not "cache around it".
+
+### Database-side optimization first
+For data-heavy operations, the DB is usually the bottleneck. Before app-side caching:
+- Add indexes for new query shapes.
+- Rewrite N+1 as JOIN or batch loader.
+- Use materialized views for expensive aggregations.
+- Consider read replicas for read-heavy paths.
+
+### Bundle-size optimization (frontend)
+- Measure with `webpack-bundle-analyzer`, `vite-plugin-visualizer`, `next build` output.
+- Code-split routes (lazy / dynamic imports).
+- Remove unused deps; replace heavy libs (moment → date-fns → native Intl).
+- Tree-shake-friendly imports (`import { format } from 'date-fns'` not `import _ from 'date-fns'`).
+
+### Render performance (frontend)
+- Profile with React DevTools Profiler / Vue Devtools.
+- Look for unnecessary rerenders. Memo only after profiling identifies the cost.
+- Move expensive work off render path: `useMemo` for compute, `useCallback` to stabilize refs, `useDeferredValue` for non-urgent updates.
+- React Compiler (when enabled) handles most of this; manual memo becomes anti-pattern.
+
+### Networking
+- Reduce round trips: batch where API allows.
+- Compression: gzip / brotli for text responses.
+- HTTP/2 multiplexing eliminates per-request connection overhead.
+- CDN for static assets and edge-cacheable dynamic content.
+- Connection pooling for outbound HTTP.
+
+## Anti-Patterns (DO NOT)
+
+### Optimize without measuring
+"This loop is slow, let me optimize" — without profiling. Spend a day; benchmark says no improvement.
+**Rule:** profile first. The hot spot is rarely where you think.
+
+### Micro-optimize cold paths
+Code runs 5 times per day; spend a week making it 20% faster.
+**Rule:** ROI matters. Optimize where the wall-clock time lives.
+
+### Cache everything
+"Add cache to make it faster" → invalidation bugs ship → stale data shown to users → harder bug to fix than the original perf.
+**Rule:** cache only what's measurably expensive AND has clear invalidation. Otherwise fix the underlying cost.
+
+### Premature parallelization
+Parallel implementation is harder to debug, harder to read, harder to maintain. If serial is fast enough, leave it alone.
+**Rule:** parallelize after measuring serial cost.
+
+### Optimize without context
+Same code path: 50ms in dev, 5ms in prod (cached at scale). Optimizing dev path costs eng time, prod doesn't care.
+**Rule:** measure under prod-shaped load.
+
+### Synthetic benchmarks unrepresentative of real load
+Loop 1M times calling `f(0)` — JIT detects constant, eliminates the call. Benchmark says "f is free". Real callers vary input → JIT doesn't help → f is expensive.
+**Rule:** realistic input distribution; warm-up; multiple runs.
+
+### Optimizing without acceptance criteria
+"Make it faster" with no target. Spend forever; never know when to stop.
+**Rule:** define the target. p95 < 200ms. Bundle < 100KB. Then stop when met.
+
+### "Faster" code that breaks invariants
+Removed a defensive check "for perf"; turns out the check was load-bearing in an edge case.
+**Rule:** measure, change, re-measure, AND re-test. Performance change must keep tests passing.
+
+### Optimizing the wrong layer
+App caches DB result; DB query was actually fast; the slow part was the JSON serialization. Cache helps a little; fixing the serialization helps a lot.
+**Rule:** profile points at the layer; fix at the layer the profile points to.
+
+### Memoizing pure functions that are already cheap
+`useMemo(() => x + y, [x, y])` — overhead of memo > cost of `+`. Especially with React Compiler.
+**Rule:** memo when profile shows it pays. Otherwise it's noise.
+
+### "10x faster" claims without measurement
+PR description says "10x faster". No benchmark. No before/after.
+**Rule:** include measurement in the PR. Numbers, not vibes.
+
+### Killing readability for micro-perf
+`for (let i = 0, l = arr.length; i < l; ++i)` instead of `for (const x of arr)` — saves nanoseconds, costs reader 5 seconds. Hot loop? OK. Cold path? Don't.
+
+## Decision Framework
+
+| Symptom | Investigation order |
+|---|---|
+| Slow request handler | Profile request path → identify slowest span → fix slowest |
+| Slow page load | Lighthouse → bundle analysis → render profile → fix biggest |
+| High DB latency | EXPLAIN slowest queries → indexes → denormalize → cache as last resort |
+| OOM under load | Heap profile → leaks → unbounded data structures → caching with proper bounds |
+| CPU pinned | Profile → hot function → algorithmic vs micro fix |
+| Throughput plateau | Identify bottleneck (CPU? IO? DB pool? Lock contention?) → fix that one |
+| Tail latency p99 high | Find: GC pauses? Cache miss? DB connection wait? Each has different fix |
+| Slow boot/cold start | Lazy-load non-critical modules; warm pools; provisioned concurrency for serverless |
+
+## Cost Model
+
+| Optimization | Typical effort | Typical gain |
+|---|---|---|
+| Add missing DB index | hours | 10-1000x query speedup |
+| Fix N+1 with JOIN | hours | 10-100x for affected request |
+| Add Redis cache for hot read | day | 5-10x latency, IF hit rate is high |
+| Code-split a heavy route | hours | 30-70% initial bundle reduction |
+| Replace heavy lib (moment → date-fns) | hours | 50-80% lib size reduction |
+| Memoize expensive React component | minutes | 0% if not on hot path; 10-30% if it is |
+| Refactor algorithm O(N²) → O(N log N) | day-week | massive at scale, zero at small N |
+| Migrate to faster runtime / lib | weeks-months | 10-50%; high risk |
+| Add connection pool | hours | reduces tail latency markedly under load |
+
+| Anti-pattern | Cost when wrong |
+|---|---|
+| Cache hides slow query | Quality bug shipped via stale data; original problem still there |
+| Premature parallelism | Code 5x harder to read, race conditions, no measured win |
+| Micro-opt over readability | Slowed team velocity; bug-prone code; nano gain |
+| No measurement before / after | Could be ZERO actual improvement, you have no idea |
+
+## Red Flags in Diff
+
+- New `useMemo` / `useCallback` without a profile/comment justifying it (especially with React Compiler enabled) → flag.
+- New cache layer added without a TTL OR without invalidation strategy → flag (see caching.md).
+- New parallel code (Promise.all, asyncio.gather) without bound on concurrency → flag.
+- New "optimization" PR without before/after benchmark numbers → flag.
+- New micro-optimized code (manual loops, hand-rolled algorithms) replacing a clear stdlib call without measurement → flag.
+- Removed validation / safety check labelled "for perf" → flag.
+- Hardcoded "magic number" tunable (timeout, batch size) without comment about source → flag.
+- Profile-driven changes affecting hot path without test coverage on the changed paths → flag (perf regression risk).
+- New `setImmediate` / `setTimeout(0)` claims to "improve perf" → flag (almost always wrong fix).
+- Heavy library added in a code path that already had a lighter alternative → flag.
+- Heavy operation moved into render / hot loop → flag.
+- New "fast path" with subtly different semantics from the slow path → flag (correctness drift risk).

package/knowledge/references/perf-flutter.md

@@ -0,0 +1,62 @@
+---
+tags: [performance, flutter, dart, widget-rebuild, mobile]
+stack_signals:
+  - language: [dart]
+  - project_type: [mobile, frontend-app]
+summary: |
+  Flutter / Dart performance checklist — const constructors, build() scope,
+  setState() placement, list virtualization, image caching.
+when_to_load: |
+  Task touches Flutter widgets, Dart code with perf concerns, or mobile-app
+  scale targets. Diff in *.dart with widget tree changes, setState() calls,
+  or list/scroll views.
+agent_hints: [performance, logic-reviewer, ui-consistency]
+---
+
+# Performance: Flutter / Dart
+
+## Widget Rebuilds
+- Missing `const` constructors on stateless widgets and static children
+- Large `build()` methods that should be split into smaller widgets
+- `setState()` at too high a level (rebuilds entire subtree instead of targeted widget)
+- Missing `const` keyword on widget constructors with no dynamic params
+- Heavy computation inside `build()` — move to `initState()` or compute outside
+
+## Lists & Scrolling
+- `ListView(children: [...])` with 20+ items — use `ListView.builder` instead
+- Missing `itemExtent` or `prototypeItem` on large uniform lists
+- `SingleChildScrollView` wrapping a `Column` with many children — use `ListView`
+- Missing `cacheExtent` tuning for heavy list items
+- `IntrinsicWidth`/`IntrinsicHeight` in lists — causes expensive two-pass layout
+
+## Animation & Painting
+- Missing `RepaintBoundary` to isolate frequently repainting regions
+- Using `Opacity` widget — use `FadeTransition` or `AnimatedOpacity` instead (Opacity forces offscreen buffer via saveLayer)
+- `ShaderMask`, `ColorFilter`, `ClipPath` with non-default clipBehavior trigger expensive saveLayer calls
+- First-run shader compilation jank — consider Impeller (default on iOS) or `--bundle-sksl-path` for Skia
+
+## Images & Assets
+- No `cacheWidth`/`cacheHeight` on large images (decode full resolution for small display)
+- Missing `CachedNetworkImage` — raw `Image.network` without caching
+- Large images loaded without resize — use `ResizeImage` or server-side thumbnails
+- SVG assets that could be compiled to code via `flutter_svg` or replaced with icons
+
+## State Management
+- Riverpod/BLoC/Provider at too high a scope (rebuilds unrelated widgets)
+- Missing `select()` / `Selector` — listening to entire state when only one field needed
+- `FutureBuilder` / `StreamBuilder` recreating Future/Stream on every build (store in variable or initState)
+- Missing `GlobalKey` cleanup — excessive GlobalKeys kept alive unnecessarily
+
+## Async & Resources
+- Missing `dispose()` for controllers, streams, animation controllers
+- `Timer.periodic` without cancel in `dispose()`
+- Heavy work on main isolate (image processing, JSON parsing of large payloads) — use `compute()` or `Isolate.run()`
+- Network request deduplication — multiple widgets triggering same fetch without caching
+
+## Platform & Size
+- Unused packages in `pubspec.yaml` (inflates app size)
+- Tree-shaking for icon fonts is default in release mode — verify not disabled
+- Platform channels called in hot path without caching result
+
+## Profiling Note
+Always profile in **profile or release mode** — debug mode has vastly different performance characteristics. Use DevTools Performance tab or `flutter run --profile`.