@nklisch/pi-agile-workflow 0.15.3

package/skills/bug-scan/references/state-closures.md

@@ -0,0 +1,148 @@
+# State Management & Closure — Bug Reference
+
+> **When to load this reference**: when scanning code that uses closures, callbacks captured for
+> later execution, framework reactivity primitives (useState/useEffect, ref/reactive, $state,
+> signals, stores), or any "value captured at one time, read at another" pattern.
+
+## Detection signals
+- grep heuristics: `useEffect\(`, `useCallback\(`, `useMemo\(`, `useRef\(`, `useState\(`,
+  `\.bind\(`, `for\s*\(\s*var\s`, `for\s*\(.*\)\s*\{[^}]*function`, `setTimeout\([^,]+,`,
+  `addEventListener\(`, `ref\(`, `reactive\(`, `\$state\b`, `\$derived\b`, `\$effect\b`,
+  `createSignal`, `createEffect`, `watch\(`, `watchEffect\(`, `useStore\(`, `useSelector\(`,
+  `queryKey:\s*\[`, `enabled:\s*!!`, `defineProps\(`, `\.value` after destructure,
+  async arrow inside JSX, module-scope `let` or `const` arrays/maps in server code.
+- Read-time vs write-time mismatch: any place the value was captured before the read.
+
+## Patterns
+
+### 1. Loop variable captured by closure
+- **Signature**: `for` / iteration creates closures that all read the same loop variable; all callbacks end up using the final value.
+- **Why hard to find**: Looks correct line-by-line; the bug only appears when callbacks fire.
+- **Where to look**: `setTimeout`/`setInterval` inside loops, `forEach` with async work scheduled, event handlers bound in loops, goroutines started in loops, Python `lambda` in list comprehensions.
+- **Example**: `for (var i = 0; i < n; i++) setTimeout(() => log(i), 0)` logs `n` n times.
+- **Fix direction**: Bind a per-iteration copy: JS `let` instead of `var`; Python `lambda i=i: ...`; Go 1.22+ loop-var scoping is per-iteration (older Go: copy to inner var); Rust prefer `move` closures over borrows of loop locals.
+- **Language/framework variants**: JS `var` (broken) vs `let`/`const` (fine); Go pre-1.22 vs 1.22+; Python lambdas always capture by name; Rust borrow checker often catches this at compile.
+
+### 2. React: stale closure in useEffect reading outside-dep state
+- **Signature**: Effect body reads `state` or `props` that aren't in the dep array; subscriber/handler keeps seeing the initial value.
+- **Why hard to find**: First render works; bug surfaces only after a state change.
+- **Where to look**: `useEffect(() => { ws.onmessage = e => setX(state + e.data) }, [])` — `state` is frozen at mount.
+- **Example**: Counter increments only show `1` because handler closes over `count = 0`.
+- **Fix direction**: Add to deps, use functional setter `setX(prev => ...)`, move logic into `useEffectEvent` (React 19.2+) for non-reactive reads, or stash latest via `useRef`.
+- **Variants**: Same bug in `useCallback`/`useMemo` with stale deps; React 19's `useEffectEvent` is now the idiomatic fix and ESLint ignores it in dep arrays.
+
+### 3. React: missing or wrong dep array → infinite re-render / stale read
+- **Signature**: Object/array/function literal in deps that's reconstructed every render; or no deps when there should be.
+- **Why hard to find**: Symptoms range from network storms to no symptom until data shape shifts.
+- **Where to look**: `useEffect(() => fetch(...), [{ id }])` — object literal is new each render. Or `useEffect(fn)` with no deps array (runs every render).
+- **Fix direction**: Depend on primitives, not objects. Memoize with `useMemo`/`useCallback`. Use the React ESLint plugin (`react-hooks/exhaustive-deps`).
+- **Variants**: Same shape in Preact's `useEffect`; SolidJS `createEffect` tracks automatically so this class is rarer there.
+
+### 4. React: setState during render (incl. derived-state anti-pattern)
+- **Signature**: Calling `setState` synchronously inside the render function or inside `useMemo`; or syncing prop → state with `useEffect(() => setX(prop), [prop])`.
+- **Why hard to find**: "Too many re-renders" error or one-frame-stale UI; tests that don't await commit miss it.
+- **Where to look**: Component bodies that conditionally call `setX(...)`; `useEffect` blocks whose only job is to mirror a prop into state.
+- **Fix direction**: Derive during render (`const derived = compute(prop)`), use `key` to reset child state, or call `setState` in an event handler — never just to mirror props.
+- **Variants**: React 18+ strict mode double-invokes render, exposing more of these.
+
+### 5. React: ref read in render path (no rerender on mutation)
+- **Signature**: Rendering `ref.current` directly in JSX, then expecting UI to update when ref changes.
+- **Why hard to find**: It works on first render; subsequent updates silently lag because mutating `.current` does not schedule render.
+- **Where to look**: `<div>{countRef.current}</div>`, `if (someRef.current) ...` in JSX.
+- **Fix direction**: Use `useState` if the value drives UI; refs are for imperative handles, DOM nodes, or values needed across renders without triggering one.
+
+### 6. React: race in async effect (setState after unmount / out-of-order responses)
+- **Signature**: `useEffect(async () => { const r = await fetch(...); setX(r) }, [id])` — when `id` changes fast, late responses overwrite newer ones.
+- **Why hard to find**: Only shows under latency variance; tests with mocked instant fetches miss it.
+- **Where to look**: Any async work in an effect without a cancellation flag or `AbortController`.
+- **Fix direction**: `let cancelled = false; ... if (!cancelled) setX(r); return () => { cancelled = true }`. Or use `AbortController` + check `signal.aborted`. Better: use TanStack Query.
+
+### 7. Vue 3: destructuring `reactive()` loses reactivity
+- **Signature**: `const { x } = reactive({ x: 1 })` — `x` is a plain primitive, not reactive.
+- **Why hard to find**: Code reads naturally; template updates simply don't fire.
+- **Where to look**: Anywhere a `reactive` object is unpacked into locals, passed across composable boundaries, or spread.
+- **Fix direction**: Use `toRefs(state)` then destructure, prefer `ref()` for primitives, or access via `state.x`. In Vue 3.5+ `defineProps()` destructure is compiler-magic and stays reactive — **only** there.
+- **Variants**: `reactive` arrays lose reactivity on full reassignment (`state.list = newArr` works only if `state` itself is reactive and `list` is a property, not on a destructured local).
+
+### 8. Vue 3: `ref` / `.value` mistakes across boundaries
+- **Signature**: Forgetting `.value` in `<script>`, or accidentally using `.value` in template (unwrap is automatic only at top level of template).
+- **Why hard to find**: TS may not flag it if types collapse; runtime just reads `undefined` or never updates.
+- **Where to look**: Composables returning refs that get used as values; nested refs in objects (no auto-unwrap inside a plain object passed to template).
+- **Fix direction**: Consistent ref convention; rely on Volar/Vetur warnings; prefer returning `toRefs`-style records from composables.
+
+### 9. Vue 3: `watch` / `watchEffect` stop handle leaked
+- **Signature**: `watch(...)` called outside a component setup (e.g., in a module, in a long-lived store) and never `stop()`-ed.
+- **Why hard to find**: Memory grows slowly; same callback fires N times after N route changes.
+- **Where to look**: Pinia stores that register watchers in actions; composables that watch without `onScopeDispose`.
+- **Fix direction**: Capture the returned stop handle and call it in `onUnmounted`/`onScopeDispose`, or use `effectScope`.
+
+### 10. Svelte 5: replacing $state object loses reactivity on properties
+- **Signature**: Re-exporting/re-assigning a `$state` object reference from a module or destructuring it loses the proxy; mutating `obj.field` no longer triggers updates.
+- **Why hard to find**: Looks identical to working code; only the binding mechanism differs.
+- **Where to look**: Modules exporting `$state` directly (`export const s = $state({...})` then `import { s } from ...`; destructuring at import-site breaks), components doing `let local = sharedState` then mutating `local.x`.
+- **Fix direction**: Export an accessor/getter or wrap in a class with `$state` fields. Never destructure a `$state` proxy. For immutable replacement, use `$state.raw` (only full reassignment triggers).
+- **Variants**: `$state.raw` is opposite trap — mutating fields does NOT trigger; must reassign whole value.
+
+### 11. Svelte 5: `$derived` stale via `untrack` or non-reactive read
+- **Signature**: `$derived` body reads from a plain (non-rune) variable, or wraps reads in `untrack()`, then never updates.
+- **Why hard to find**: Compiler doesn't error; first paint correct.
+- **Where to look**: `$derived` reading from module-scope `let`, or from a destructured rune (see #10), or `$derived.by(() => untrack(() => state.x))`.
+- **Fix direction**: Read directly from `$state` runes inside `$derived`; reserve `untrack` for known one-shot reads (e.g., initialization values).
+
+### 12. SolidJS: signal accessor not called
+- **Signature**: `<div>{count}</div>` instead of `<div>{count()}</div>` — passing the function instead of invoking it.
+- **Why hard to find**: Renders something (often `function count()` source string or `[object Function]`); no reactivity.
+- **Where to look**: All JSX expressions where a signal is referenced; props passed to children as `prop={signal}` vs `prop={signal()}`.
+- **Fix direction**: Call accessors at the point of use. Pass signal itself (uncalled) only when the child needs lazy reactive access; document the convention.
+- **Variants**: `createMemo` returns an accessor too; same bug. SolidStart SSR amplifies symptom because hydration mismatches.
+
+### 13. Zustand / Pinia: mutating state outside the setter / action
+- **Signature**: Direct `store.items.push(x)` without going through `set(state => ...)` or a Pinia action.
+- **Why hard to find**: In Pinia (Proxy-based) it may "work" until devtools/time-travel break; in Zustand it silently fails to notify subscribers.
+- **Where to look**: Components grabbing the whole store and mutating; reducers using `state.x = y` outside Immer/Redux Toolkit.
+- **Fix direction**: Always go through `set`/actions. Use Immer for ergonomic updates. Lint with `no-param-reassign` on reducers.
+- **Variants**: Redux without Toolkit: mutation breaks `===` checks and selectors. Redux Toolkit reducers run in Immer so mutation is fine *only inside* `createSlice` reducers.
+
+### 14. Selector returning new object each call → infinite re-render
+- **Signature**: `useSelector(s => ({ a: s.a, b: s.b }))` or Zustand `useStore(s => s.list.filter(...))` returns a fresh reference every render.
+- **Why hard to find**: Test passes; production hits React's render-loop bailout or just thrashes.
+- **Where to look**: Any selector that constructs an object/array/derived list inline.
+- **Fix direction**: Select primitives, use `shallow` (`useStore(sel, shallow)` in Zustand), `createSelector` (reselect) in Redux, or `useShallow` (Zustand v4.4+).
+
+### 15. TanStack Query v5: queryKey identity unstable
+- **Signature**: `queryKey: [{ id, filters }]` or `queryKey: ['x', new Date()]` — fresh reference each render means cache misses and refetch storms.
+- **Why hard to find**: Network tab shows constant requests; logic works.
+- **Where to look**: Object literals, `Date.now()`, `Math.random()`, function references in queryKeys; queryKeys built inside render without memoization.
+- **Fix direction**: Keys should be serializable and stable: `['user', id, { sort, filter }]` — TanStack Query v5 hashes deterministically, so object literals are fine *if their content is stable*. The bug is when content changes identity (e.g., `filters` rebuilt each render). Memoize the input or flatten to primitives.
+- **Variants**: `enabled: !!user && user.role === 'admin'` toggling causes refetch; `placeholderData`/`select` returning new refs causes re-render churn — wrap with `useCallback`.
+
+### 16. Global module-level mutable state in SSR / serverless
+- **Signature**: `const cache = new Map()` at module scope in a Next.js / Remix / Nuxt server module; first request populates, later requests for other users see leaked data.
+- **Why hard to find**: Works locally with one user; appears as cross-tenant data leak in prod.
+- **Where to look**: Top-level `let`/`const` collections in server files; singletons holding request-specific context; React Server Components storing per-request data in module scope.
+- **Fix direction**: Use request-scoped storage (`AsyncLocalStorage` in Node, request context in framework), pass context explicitly, or use per-request providers. Treat module scope as multi-tenant shared.
+- **Variants**: Same bug with global Prisma / DB clients holding per-request transaction state, or globally cached auth tokens.
+
+### 17. Event listener captured stale `this` (or stale closure)
+- **Signature**: `el.addEventListener('click', this.handle)` without `.bind(this)` or arrow, then `this` inside is `undefined`/the element; or handler captures stale local.
+- **Why hard to find**: Throws only on dispatch path that may be rare.
+- **Where to look**: Class components, vanilla JS modules, custom elements, third-party widget integrations.
+- **Fix direction**: Class fields with arrow (`handle = () => {...}`), explicit `.bind(this)` once and store the bound ref so `removeEventListener` works, or use functional patterns.
+
+### 18. Memoization key includes object identity (always different)
+- **Signature**: `useMemo(() => compute(opts), [opts])` where `opts` is a fresh object each render; or `_.memoize(fn)` keyed on object args.
+- **Why hard to find**: Looks memoized; profiler shows cache never hits.
+- **Where to look**: Any memo whose deps are objects/arrays/functions not stabilized upstream.
+- **Fix direction**: Depend on primitives or memoize the upstream object too. For caches, key on a serialized form (`JSON.stringify` for shallow data, structural hash for deep).
+
+### 19. Reactive computation reading from non-reactive source
+- **Signature**: Vue `computed`, Svelte `$derived`, Solid `createMemo` reading a plain variable, DOM property, `Date.now()`, or globalThis — no dependency is tracked, so never re-runs.
+- **Why hard to find**: Initial value correct; never updates.
+- **Where to look**: Bridges between framework state and "outside" data (localStorage, window size before `ResizeObserver` is wired, native events).
+- **Fix direction**: Wrap external sources in framework primitives (`ref` + listener that writes it, `createSignal` + subscription, `$state` + `$effect`). Many frameworks ship adapters (`useSyncExternalStore` in React, `useExternalStore`-style composables in Vue).
+
+### 20. Async race with React 18+ concurrent rendering / Suspense
+- **Signature**: Effect reads `state` then awaits, but a transition/`useDeferredValue` already rendered with newer state by the time the await resolves.
+- **Why hard to find**: Only under heavy interaction or `startTransition` boundaries.
+- **Where to look**: Code mixing `useTransition`, `useDeferredValue`, and manual async work in effects.
+- **Fix direction**: Prefer Suspense-aware data libs (TanStack Query, Relay, RSC). For manual effects, version-tag the request (`const reqId = ++ref.current; if (reqId !== ref.current) return`).

package/skills/bug-scan/references/time-numbers.md

@@ -0,0 +1,158 @@
+# Time, Date & Numeric Precision — Bug Reference
+
+> **When to load this reference**: when scanning code that handles dates, timestamps, durations,
+> calendars, scheduling, billing periods — or any numeric work involving money, percentages,
+> floating-point comparisons, integer overflow risk, or cross-language number boundaries.
+
+These bugs share the "value looks right, isn't" property: tests pass on the dev's machine, in
+their locale, on Tuesday afternoon, with their sample data — and break elsewhere.
+
+## Detection signals
+
+**Time/date grep heuristics:**
+- `new Date(`, `Date.now`, `\.toISOString`, `\.getTime`, `\.getHours` (local!) vs `\.getUTCHours`
+- `moment(`, `dayjs(`, `date-fns`, `luxon`, `Temporal\.`
+- `datetime\.now\(\)`, `datetime\.utcnow`, `datetime\.today`, `strftime`, `strptime`, `time\.time\(\)`
+- `time\.Now\(\)`, `time\.Parse`, `chrono::`, `SystemTime::now`, `Instant::now`
+- `setTimeout.*\*.*1000`, `\* 86400`, `\* 3600`, magic seconds-in-X constants
+- `TIMESTAMP`, `DATETIME`, `TIMESTAMPTZ` in schemas; `WITHOUT TIME ZONE`
+- String date sorts: `\.sort\(.*date`, ISO vs `MM/DD/YYYY` mixing
+
+**Numeric grep heuristics:**
+- `parseFloat`, `parseInt`(without radix), `Number\(`, `\+\+` on string-typed value
+- `\.toFixed`, `Math\.round`, `Math\.floor` on money-shaped names (`price`, `total`, `amount`, `cents`)
+- `==` or `===` with floats; `=== NaN`, `isNaN(` (vs `Number\.isNaN`)
+- `BigInt\(`, `n` suffix mixed with regular `\d`; `Decimal\(`, `decimal\.Decimal`
+- `i32`, `u32`, `as i64`, `as u32`, casts that narrow
+- `\$\{.*\}`/string-templating numbers without `Intl\.NumberFormat` / `toLocaleString`
+
+## Time / Date / TZ Patterns
+
+### 1. Naive datetime treated as UTC (or vice versa)
+- **Signature**: `datetime.utcnow()`, `datetime.now()` without tz, `new Date('2025-01-01')`, naive `LocalDateTime`.
+- **Why hard to find**: works perfectly when server TZ == UTC. Breaks at deploy to a non-UTC host or when devs run locally.
+- **Where to look**: API boundaries (request parsing, DB writes), cron jobs, log timestamps, JWT `exp`/`iat`.
+- **Example**: Python `datetime.utcnow()` returns a *naive* datetime (no tzinfo) — comparing it to an aware `datetime.now(tz=...)` raises `TypeError`, and serializing it omits the offset so the consumer guesses. Deprecated in Python 3.12; removal targeted for a future version.
+- **Fix direction**: Always construct aware datetimes: `datetime.now(timezone.utc)` (or `datetime.UTC` on 3.11+). In JS, store as ISO-8601 with explicit `Z` or offset. In Postgres, prefer `TIMESTAMPTZ`.
+- **Language variants**: Java `LocalDateTime` vs `ZonedDateTime`/`Instant`; Go `time.Time` always carries location but `time.Parse` without layout-with-zone yields UTC.
+
+### 2. DST transitions: missing and duplicate hours
+- **Signature**: scheduling, recurring jobs, "every day at 2:30am", date arithmetic across spring/fall.
+- **Why hard to find**: only fires twice a year, in some timezones. CI in UTC never sees it.
+- **Where to look**: cron-like schedulers, billing-period rollovers, alarm clocks, calendar invites.
+- **Example**: `2025-03-09 02:30` doesn't exist in `America/New_York` (skipped forward); `2025-11-02 01:30` happens twice (fall back).
+- **Fix direction**: Schedule in UTC or use a library with explicit DST disambiguation (`fold` in Python, `Temporal.ZonedDateTime` with `disambiguation: 'earlier'|'later'|'reject'`). Never compute "tomorrow at X" by adding 86400 seconds.
+- **Language variants**: JS `Date` silently shifts; Luxon and Temporal expose `isAmbiguous`/`isValid`.
+
+### 3. Date arithmetic crossing month / year / DST
+- **Signature**: `date + 30 days`, `addMonths(d, 1)`, "last day of month", anniversary billing.
+- **Why hard to find**: tests use mid-month dates that never trigger edge cases.
+- **Where to look**: subscriptions, trial expirations, statement periods, leap-year-sensitive logic (`Feb 29 + 1 year`).
+- **Example**: `addMonths(new Date('2025-01-31'), 1)` — Feb has no 31st. Different libraries return Feb 28, Mar 3, or throw.
+- **Fix direction**: Use a calendar-aware library (`date-fns`, Luxon, Temporal). For anniversaries, snap to last-day-of-month explicitly. For Feb 29 birthdays on non-leap years, define policy (Feb 28 or Mar 1).
+- **Language variants**: Java `Period` vs `Duration` — `Period` is calendar-aware, `Duration` is fixed seconds.
+
+### 4. Monotonic clock vs wall clock for durations
+- **Signature**: `Date.now() - start`, `time.time() - start`, `SystemTime::now()` deltas.
+- **Why hard to find**: NTP slews and leap seconds make wall clock jump backward; only matters for sub-second timing or long-running timers.
+- **Where to look**: performance metrics, timeouts, retry backoff, rate limits, "time since last X".
+- **Example**: NTP adjustment moves `Date.now()` backward by 200ms → negative duration → infinite retry loop.
+- **Fix direction**: Use monotonic clocks for durations: `performance.now()` (JS), `time.monotonic()` (Python), `Instant::now()` (Rust), `System.nanoTime()` (Java), `time.Since` with `time.Now()` is wall in Go — use `time.Monotonic` reading where available.
+
+### 5. Unix timestamp unit confusion (s / ms / µs / ns)
+- **Signature**: integer timestamp passed to a function expecting a different unit. `1700000000` vs `1700000000000`.
+- **Why hard to find**: dates near 1970 (small ms read as seconds) or far future (seconds read as ms) — usually wrong by ~1000x but might just look like "a wrong date."
+- **Where to look**: cross-language boundaries (Python→JS, Go→browser), Redis/Kafka, log aggregation.
+- **Example**: `new Date(timestamp)` expects ms; `time.time()` returns float seconds; Go `time.Unix(sec, nsec)`; Rust's chrono `from_timestamp` is seconds, `from_timestamp_millis` is ms.
+- **Fix direction**: Name variables with units (`expires_at_ms`, `expires_at_s`). Validate range at boundaries (anything before 2001 or after 2100 in seconds is suspect).
+
+### 6. ISO 8601 parsing ambiguity (date-only strings)
+- **Signature**: `new Date('2025-01-01')`, `Date.parse('2025-01-01')`.
+- **Why hard to find**: same string parses to different instants depending on tool/version.
+- **Where to look**: date pickers, query params, CSV imports.
+- **Example**: `new Date('2025-01-01')` is parsed as UTC midnight; `new Date('2025-01-01T00:00:00')` is parsed as *local* midnight. In `America/Los_Angeles` these differ by 8 hours and land on different *dates*.
+- **Fix direction**: Always include explicit offset (`Z` or `+00:00`). For calendar-only data use `Temporal.PlainDate` or store as `DATE` not `TIMESTAMP`.
+
+### 7. Locale-dependent date parsing (`MM/DD` vs `DD/MM`)
+- **Signature**: `new Date('03/04/2025')`, `strptime` without explicit format, Excel/CSV imports.
+- **Why hard to find**: ambiguous dates (day ≤ 12) silently parse to wrong date; clearly invalid ones throw.
+- **Where to look**: file imports, user-typed forms, third-party feeds.
+- **Fix direction**: Require ISO-8601 at boundaries. If accepting locale formats, ask for locale explicitly and reject ambiguous input.
+
+### 8. Sorting mixed date string formats
+- **Signature**: `array.sort()` on strings like `'1/2/2025'`, `'12/31/2024'`, `'2025-01-02'`.
+- **Why hard to find**: ISO-8601 sorts lexically as it does chronologically; other formats don't. Mixing them silently misorders.
+- **Where to look**: report generation, log file processing, filename sorts.
+- **Fix direction**: Parse to instants/PlainDates and sort those, or normalize to ISO-8601 first.
+
+### 9. Year 2038 problem (32-bit unix epoch)
+- **Signature**: `int32`/`time_t`/`i32` storing seconds since 1970; embedded systems, legacy DBs, C structs over the wire.
+- **Why hard to find**: works today, will fail at `2038-01-19T03:14:07Z`. Code paths computing "1 year from now" already trigger near 2037.
+- **Where to look**: MySQL `INT UNSIGNED` for timestamps, old C/C++ binaries, MQTT/binary protocols, JWT `exp` rendered as `int32`.
+- **Fix direction**: Use 64-bit timestamp types end-to-end. Postgres `TIMESTAMPTZ` is already 64-bit; MySQL `DATETIME` (not `TIMESTAMP`) avoids the 2038 cliff.
+
+## Numeric Precision Patterns
+
+### 10. Floating-point equality and `0.1 + 0.2 != 0.3`
+- **Signature**: `===`/`==` on floats, `if (total === expected)`, fixture comparisons.
+- **Why hard to find**: passes for "round" values, fails when inputs accumulate from arithmetic.
+- **Where to look**: tax/discount/percentage math, geometric calculations, currency conversion, test assertions.
+- **Example**: `(0.1 + 0.2) === 0.3` → `false`. `0.3 - 0.1 - 0.1 - 0.1` → `-2.78e-17`.
+- **Fix direction**: Compare with epsilon: `Math.abs(a - b) < EPSILON`. For currency, use integer minor units (cents) or a Decimal library. Use language-provided `isClose` (Python `math.isclose`, Rust `approx::abs_diff_eq!`).
+
+### 11. Money in floating point
+- **Signature**: `price: number`, `amount: f64`, `total *= 1.08`, JSON dollars-as-float.
+- **Why hard to find**: small invoices appear correct; rounding errors compound at scale, in batch jobs, or under FX conversion.
+- **Where to look**: invoicing, ledger entries, tax math, refunds, exchange rates, anywhere `*=` or `+=` accumulates a price.
+- **Fix direction**: Store money as integer minor units (cents) **or** use Decimal: `decimal.Decimal` (Python), `BigDecimal` (Java/Scala), `decimal.js` / `dinero.js` (JS), `rust_decimal` (Rust). Never `parseFloat` a money string and put it back in a DB.
+
+### 12. NaN propagation and `NaN === NaN` is false
+- **Signature**: `parseFloat`/`parseInt` on bad input, `0/0`, `Math.sqrt(-1)`, `Number(undefined)`.
+- **Why hard to find**: NaN poisons every downstream calculation silently (no exception). `if (x === NaN)` never fires.
+- **Where to look**: form input parsing, JSON without schema, division, aggregations over partially-null data.
+- **Example**: `parseFloat('--')` → `NaN` → stored, summed, displayed as `NaN`. `[1, 2, NaN].reduce((a,b)=>a+b)` → `NaN`.
+- **Fix direction**: Use `Number.isNaN(x)` (not the global `isNaN` — that coerces strings). Validate at boundaries; reject NaN early. Python `float('nan')` and `math.isnan` analogues.
+
+### 13. Integer overflow (i32 / i64 / JS safe range)
+- **Signature**: `i32`/`u32` arithmetic, `as i32` narrowing casts, JS numbers beyond `2^53`.
+- **Why hard to find**: Rust panics in debug but **wraps silently** in `--release` for primitive `+`/`-`/`*`. JS silently loses precision past `Number.MAX_SAFE_INTEGER` (`2^53 - 1`).
+- **Where to look**: ID generation, counters, byte-size math, multiplication of "reasonable" numbers (`1_000_000 * 1_000_000` overflows `i32`).
+- **Example**: Rust `let x: i32 = 1_000_000 * 3_000;` panics in debug, wraps to a negative in release. JS `9007199254740993 === 9007199254740992` → `true`.
+- **Fix direction**: Rust — use `checked_*`, `wrapping_*`, `saturating_*` explicitly; or enable `overflow-checks = true` in release profile. JS — use `BigInt` for 64-bit IDs (Twitter-style snowflake IDs from APIs). Serialize 64-bit ints as strings over JSON.
+
+### 14. BigInt / Number mixing in JavaScript
+- **Signature**: `bigIntValue + 1`, `Math.floor(bigIntValue)`, `JSON.stringify(bigIntValue)`.
+- **Why hard to find**: TypeError at runtime (`Cannot mix BigInt and other types`); `JSON.stringify` throws on BigInt; silent precision loss when forced via `Number(big)`.
+- **Where to look**: ID handling from APIs, high-precision counters, crypto/blockchain code, anywhere BigInt enters from one source and meets `+ 1` somewhere else.
+- **Fix direction**: Pick one type at the boundary and convert explicitly: `Number(big)` (lossy past 2^53) or `BigInt(num)` (throws on fractions). Custom `JSON.stringify` replacer to render BigInts as strings.
+
+### 15. Implicit type coercion (`"10" + 5`)
+- **Signature**: numeric op on a value sourced from `req.query`, `process.env`, form input, CSV.
+- **Why hard to find**: JS `+` is string concat for any string operand; `-`/`*`/`/` coerce both sides. `"10" + 5 === "105"` but `"10" - 5 === 5`.
+- **Where to look**: query-string parsing, env-var-as-number, JSON with quoted numbers, Python `input()` (always str).
+- **Fix direction**: Parse and validate at boundaries (`Number(x)`, `parseInt(x, 10)`, `int(x)`, zod/pydantic). Use strict TypeScript and lint rules against arithmetic on `any`.
+
+### 16. Division rounding surprises
+- **Signature**: integer `/` in Python 2 / Go / Rust / C; `Math.round` and `toFixed` for display.
+- **Why hard to find**: Go/Rust `5/2 == 2` (integer truncation toward zero). JS `Math.round(0.5) === 1` but `Math.round(-0.5) === 0` (rounds half-up). Python 3 `5/2 == 2.5`, `5//2 == 2`. Banker's rounding (Python `round`, `decimal.ROUND_HALF_EVEN`) differs from `toFixed` (which rounds half-to-even-ish but is browser-inconsistent).
+- **Where to look**: pagination, distributing remainders, percentage splits, tax allocation.
+- **Example**: `(0.1 + 0.2).toFixed(2)` may render `"0.30"` while sum-of-rounded ≠ rounded-sum.
+- **Fix direction**: For display, use `Intl.NumberFormat` (locale-aware, deterministic). For money allocation, use a "largest remainder" or "banker's" distribution algorithm — don't trust naive `total / n`.
+
+### 17. Sum of large + small floats loses the small
+- **Signature**: accumulating many small floats into a running large total, telemetry aggregation, financial running totals.
+- **Why hard to find**: result is plausible but wrong by a percent or two; depends on iteration order.
+- **Example**: `1e16 + 1.0 - 1e16` → `0` (the `1.0` falls below the precision of `1e16`).
+- **Fix direction**: Use Kahan / Neumaier compensated summation, or sort small-to-large before summing. For exact totals, use Decimal/integer cents.
+
+### 18. Negative zero edge cases
+- **Signature**: `Math.sign`, `1/x` (gives `-Infinity` vs `Infinity`), `Object.is(0, -0)`, sort keys.
+- **Why hard to find**: `-0 === 0` is `true`, but `Object.is(-0, 0)` is `false` and `1/-0 === -Infinity`. Sorts and `Map` keys behave inconsistently.
+- **Fix direction**: Normalize to `+0` when sign is irrelevant: `x === 0 ? 0 : x` or `x + 0`. Be explicit when sign matters.
+
+## Cross-cutting fix directions
+- Pick canonical representations at the **system boundary** (UTC instant + IANA tz name; integer minor units for money; ISO-8601 for dates; explicit unit in field name for timestamps).
+- Validate with schemas (zod, pydantic, JSON Schema) — don't trust upstream types.
+- For JS in 2026, prefer the **Temporal API** (Stage 4, ES2026, shipping in Chrome 144 / Firefox 139+; polyfill `@js-temporal/polyfill` elsewhere) over legacy `Date`.
+- For Python, use **timezone-aware** datetimes everywhere (`datetime.now(timezone.utc)`); `utcnow()` is deprecated in 3.12+.
+- For Rust, prefer `checked_*` / `saturating_*` over raw arithmetic in any code that handles untrusted input or runs in release with `overflow-checks = false`.