Files
faunosteo/.claude/memory/learnings.md
T

429 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Learnings Registry
Format: LRN-XXX | Date | Pattern | Context | Future application
---
## LRN-001 | 2026-05-18 | Zod discriminatedUnion for nextAppointment
Report.nextAppointment uses discriminatedUnion('kind', [...]).
Gives precise TS narrowing on .kind; avoids optional union type ambiguity.
Apply: any polymorphic field with a literal discriminant.
---
## LRN-002 | 2026-05-18 | SVG hitbox+visible twin pattern
Two SVG elements share same data-anno-id: hitbox (pointer-events:all, fill:transparent) + visible (pointer-events:none, colored).
Parser groups by data-anno-id → Bone.hitboxEls[], Bone.visibleEls[].
Apply: any SVG-based interactive map needing precise click areas.
---
## LRN-003 | 2026-05-18 | pnpm via corepack shim breaks on older Node 20
corepack shim on Node 20.20.0 throws ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.
Fix: install pnpm directly via get.pnpm.io/install.sh.
Binary lands at ~/.local/share/pnpm/bin/pnpm.
Apply: CI/dev envs without system pnpm.
---
## LRN-004 | 2026-05-19 | SVG behavior hints via free-form data-anno-special
Branch click handling on `data-anno-special` (free-form string), not on `data-anno-category`.
Why: category is free-form metadata (LRN follow-up to refactor BDR/cad94a4 chain); coupling logic to category re-introduces a closed enum and silently breaks when SVG author renames a slug. Hints stay opaque to parser, consumed only at use site.
Apply: any SVG-driven UI where authors add new annotation types regularly — use `data-anno-special` for behavior triggers, keep category for grouping/filters only.
---
## LRN-005 | 2026-05-19 | Detail-popup needs its own bones map
When a popup loads a separate SVG, its annotation ids are not in the parent's bones map.
Parse detail SVG on popup open and keep a `detailBones` map; fall back lookup `bones.get(id) ?? detailBones.get(id)` in shared click handler.
Apply: any nested/zoom-popup pattern where the child SVG has independent ids.
---
## LRN-006 | 2026-05-19 | Strip authoring annotations before rasterizing for print
Source SVGs carry interaction-only artifacts (data-anno-*, transparent hitboxes, faint default fills) that are invisible in-app via CSS but leak into PDF rasterization.
Before raster: walk `[data-anno-id]`, hide non-selected via display="none", strip data-anno-* attributes, recolor selected.
Apply: any "screen → print" pipeline where the screen SVG has interaction layers.
---
## LRN-007 | 2026-05-19 | pdf-lib maxWidth wraps glyphs, not your cursor
pdf-lib's drawText({ maxWidth }) wraps the visible glyph run but the returned y is unchanged — caller must measure with widthOfTextAtSize and advance the cursor per wrapped line. Otherwise subsequent text blocks overlap the wrapped tail.
Apply: any pdf-lib layout with variable-length user text. Always wrap explicitly + advance per line.
---
## LRN-008 | 2026-05-19 | pdf-lib eyebrow + title vertical spacing
Times-22 ascender ≈ 17pt. Eyebrow size-9 baseline above title baseline needs ≥22pt gap to clear the ascender + leave ≥6pt visual breathing. Header rule needs ≥30pt cushion below for a size-22 title (title baseline at height-120ish on A4).
Apply: any pdf-lib heading stack (eyebrow + title or chained headings). Compute from font.heightAtSize/widthOfTextAtSize, never eyeball pixel offsets.
---
## LRN-009 | 2026-05-19 | pdf-lib variable-count image layout — pre-rasterize, reserve text, then grid
Variable-count image blocks (N SVGs per observation) overflow page when stacked top-down because each item's height depends on its rasterized aspect ratio, unknown until after embedPng.
Order: (1) pre-rasterize every image in parallel via Promise.all, capture aspect = img.height/img.width; (2) build text sections + estimate their height with wrapLines on real font metrics; (3) reserve bottom area = MARGIN_BOTTOM + textHeight + gap, derive availH for images; (4) pick cols (1 if single image, else 2), rows = ceil(n/cols); (5) rowBudget = (availH - rows*labelGap - (rows-1)*rowGap)/rows with a min-cell floor; (6) cellH per item = min(cellW*aspect, rowBudget) — preserves aspect, capped by budget.
Apply: any pdf-lib page where image count is data-driven and text must remain visible. Never lay out images before measuring text; never embed-then-skip — embed all, then place. Min-cell floor prevents zero-height when content is dense.
---
## LRN-010 | 2026-05-19 | React effect that mutates async-appended DOM needs a "loaded" gate
Symptom: highlight effect (querySelectorAll + setAttribute) silently no-ops when sibling effect appends DOM async via loadSvg().then(append). First render: mutate-effect runs against empty container, then DOM arrives, then nothing re-paints because deps didn't change. Symptom is intermittent ("sometimes highlighted, sometimes not") — actually depends on which effect resolves first on a given mount.
Fix pattern: hold a `loadedSrc` state, set it to null at src-change, set it to src right after appendChild, and depend the mutate-effect on [data, loadedSrc, src] with guard `if (loadedSrc !== src) return`. Now the mutate-effect re-runs both on data change AND when DOM finishes mounting.
Apply: any React component that mounts external DOM async and applies attribute/style mutations in a separate effect. Includes inline SVG injection, MapLibre overlays, Lottie players. Never rely on effect ordering across an async boundary.
---
## LRN-011 | 2026-05-20 | Zod recursive schema via z.lazy + explicit ZodType<T>
Recursive shapes (FindingNode with optional children: FindingNode[]) need TS interface declared first, then `const FindingNodeSchema: z.ZodType<FindingNode> = z.lazy(() => z.object({...}))`. Without the explicit ZodType<T> annotation, TS infers `any` for the recursive arm and the entire downstream type chain collapses. Without z.lazy, the schema references itself before initialization → runtime ReferenceError.
Apply: any tree/AST-style schema in Zod 3.x. Declare interface first, type the schema explicitly, wrap recursive shape in z.lazy. Same trick works for ZodType<U[]> when the recursion is via children: U[].
---
## LRN-012 | 2026-05-20 | Once-per-session UX modal via sessionStorage flag
Pattern: state `disclaimer: string | null`, useEffect on the data dep that reads `sessionStorage.getItem(FLAG)`; if absent, set state to the message. Acknowledge handler writes the flag and clears state. Survives reloads within tab, resets on new tab. Cheaper than persisting per-user (no backend) and respects practitioner intent — they see the legal scope reminder once per work session.
Apply: any single-praticien tool needing one-shot acknowledgment per session (legal disclaimers, version-change notices, GDPR banners scoped to a session). Use a stable string key prefixed with `osteo:` to avoid collision.
---
## LRN-013 | 2026-05-20 | Vite import.meta.glob + default-export = plugin discovery
`import.meta.glob<{ default: T }>('./*/index.ts', { eager: true })` scans the folder at build time and returns a `Record<path, module>`. Combined with a "each module must default-export a T" convention, you get drop-folder plugin discovery: drop a conforming folder → it shows up in `Object.values(modules).map(m => m.default)`. Eager mode resolves synchronously so the registry is a plain object literal in the bundled output.
Pitfalls: a missing default export silently disappears (warn explicitly on `!mod.default`), and duplicate ids need a tie-break policy (first-wins + warn). Glob ordering is filesystem-dependent — sort the output by a stable key (e.g. labelFr) before exposing it to UI.
Apply: any registry-style module set where you want zero-touch onboarding — species, integrations, plugins, theme packs.
---
## LRN-014 | 2026-05-20 | Cross-walk human strings via normalize + Levenshtein
When bridging two sources of the same human label (SVG `data-anno-name-fr` ↔ JSON `zone.name_fr`), strict equality is too brittle (casse, accents, "(ATM)" abbreviations, typos). Robust strategy: aggressive normalize (lowercase + NFD-strip combining marks + drop non-alphanumerics), then score by `0=exact`, `1=substring`, `2+d=Levenshtein within max(2, floor(maxLen*0.25))`, `∞=no match`. EN-first if both languages available — no accent normalization edge cases.
Apply: any cross-system label match where one side is authored, the other generated or hand-typed. The 25% character tolerance is a sweet spot — catches single typos on labels 8+ chars, refuses cross-zone collisions (Sphenoid ↛ Spheno-Basilar Synchondrosis even though both share "spheno").
---
## LRN-015 | 2026-05-20 | Per-source try/catch beats loop-wrapping try/catch
Original `buildZoneLabels` wrapped main + every detail SVG fetch in one outer try/catch. First failing source (e.g. 404 on a detail asset) aborted the whole loop, leaving callers a partially-filled map with no signal — the rest of the labels never made it in. Lesson: when each iteration is independent, the try/catch belongs INSIDE the iteration (or inside the `Promise.all` callback). Outer catch only makes sense when iterations are sequentially dependent and the work is moot after a failure.
Apply: any fan-out fetch / parse / transform over heterogeneous sources — config loaders, plugin enumerators, asset preloaders. Bonus: log on failure (console.warn) so the silent skip is observable in dev.
---
## LRN-016 | 2026-05-20 | PDF custom-font text is glyph-subset — bytes-grep won't find it
pdf-lib with embedded TTF fonts (Inter, Fraunces) subsets glyphs and stores text streams as glyph indices, not codepoints. A latin1 / utf-8 grep over the raw PDF bytes will not match user-visible strings ("Temporo" never appears literally in the dump). Standard PDF text show ops (`Tj`, `TJ`) carry the glyph IDs inside content streams that are typically Flate-encoded too.
Testing implication: don't assert PDF text via byte grep — either re-extract the embedded JSON attachment (already plain text) or refactor the offending logic into an exported helper and unit-test that. Same pattern when smoke-testing PDF output in CI.
---
## LRN-017 | 2026-05-20 | i18n dict parity via Object.keys.sort equality
Cheapest drift guard between fr/en dicts: one test asserts `Object.keys(fr).sort()` deep-equals `Object.keys(en).sort()` + every value non-empty. Catches any forgotten translation at CI time without enumerating keys. Pairs with a flat `<area>.<key>` convention so adding a key in fr.ts forces matching update in en.ts at the next test run.
Apply: any project with N parallel translation dicts (i18n, locale strings, error-code maps). Beats type-level enforcement (TS can't easily require Record<K, ...> shapes to match across two `as const` literals without ceremony).
---
## LRN-018 | 2026-05-20 | useT hook: selector subscribe + closure-per-render
```ts
export function useT() {
const locale = useLocaleStore((s) => s.locale)
const dict = getDict(locale)
return (key) => dict[key] ?? (warn(key), key)
}
```
Selector subscribe re-renders consumer only on locale change. Dict resolved once per render, the returned closure does a single hash lookup per call. No prop drilling, no context provider, no React `useMemo` needed. Missing-key path warns in DEV (`import.meta.env?.DEV`) and falls back to the key literal so the UI never crashes on a typo.
Apply: any Zustand-state-driven derived computation that needs to re-render N components without prop chains. Same pattern works for theme tokens, feature flags, current user.
---
## LRN-019 | 2026-05-20 | exhaustive-deps trap with closures over store values
Defining a helper like `const nameOf = (z) => locale === 'en' ? z.name_en : z.name_fr` inside a component and using it inside `useMemo([deps])` triggers `react-hooks/exhaustive-deps`: nameOf is a fresh function each render, listing it in deps invalidates the memo every render; omitting it makes the linter complain. Two fixes:
1. Inline the locale-conditional inside the memo body (no closure).
2. Wrap the helper in `useCallback([locale])` so it's referentially stable.
Inline is simpler when the helper is one expression. Apply: any closure that bridges a memoized computation to an outer hook value (store selector, prop, context). Same trap with `useEffect` deps.
---
## LRN-021 | 2026-05-21 | pdf-lib StandardFonts use WinAnsi — Latin-1 only, throws on any non-WinAnsi char
`PDFDocument.embedFont(StandardFonts.Helvetica)` (and the 13 other Adobe built-ins) returns a font whose encoding is WinAnsi (cp1252). Any text op (`widthOfTextAtSize`, `drawText`) on a string carrying a non-WinAnsi codepoint throws synchronously: `WinAnsi cannot encode "<glyph>" (0x<hex>)`. Common offenders: ⚠ U+26A0, → U+2192, ✓ U+2713, ★, em-dash variants outside cp1252, all CJK. The error surfaces at the FIRST measurement pass (text-height estimator) — well before any draw call — so even a `try/catch` around drawing won't save you.
Fix paths:
- Quick: replace the offending glyph with a WinAnsi-safe ASCII surrogate (`(!) ` instead of `⚠ `, `->` instead of `→`).
- Right: embed a TTF (Inter, NotoSans, Fraunces…) via `pdfDoc.embedFont(ttfBytes)`. pdf-lib then subsets the actually-used glyphs into the PDF; arbitrary Unicode works. Per CLAUDE.md spec our PDF should already use TTFs — current StandardFonts shipment is a drift.
**Why:** Slipped past CI because the existing PDF roundtrip tests exercised observations without vet-referral findings; the WinAnsi error only fires when the offending glyph is present in a measured string.
**How to apply:** When a new visual cue (icon, badge, arrow) is added to PDF output, either restrict to ASCII or audit the font path. Add a regression test that exercises the measurement path with a representative string. The cheap canary: `font.widthOfTextAtSize(candidateGlyph, 10)` in a test.
---
## LRN-020 | 2026-05-21 | Forward-compat Zod schema absorbs catalog version bump zero-code
Catalog JSON went v1.2→v2.0 (semantic breaking change per author doc), but `findings.ts` Zod schema declared `requires_vet_referral` boolean + `description_fr` optional from B0 day-one. Result: v2.0 file dropped in, parses clean, 154/154 tests stay green, no schema edit, no consumer rewrite. Picker + PDF already keyed on boolean (no textual `description_fr.includes('vétérinaire')` fallback ever existed in our code), so the v2.0 "removed redundant text" change is a no-op at consumption site. Lesson: when authoring a Zod schema for external content, mark anything that "might or might not" appear as `.optional()` + make booleans authoritative early. The schema then forms a stable contract that absorbs author-side simplifications without code churn.
Apply: any data contract sourced from non-engineering authors (clinical, legal, marketing). Decouple presence-of-field from semantic-of-field; let the boolean drive logic, let text be display-only ornamentation.
---
## LRN-023 | 2026-05-22 | DOMParser for safe SVG loading in React-wrapped vanilla editors
When wrapping vanilla JS editor in React, avoid `innerHTML = svgText` for user-uploaded SVG. Use `new DOMParser().parseFromString(svgText, 'image/svg+xml')` + `document.importNode(parsedSvg, true)` to safely parse and import SVG into DOM. Parser rejects malformed XML, returns parseerror element on failure — gives clean error path. importNode deep-clones into current document context so all DOM APIs (createSVGPoint, getScreenCTM) work correctly.
Apply: any user-uploaded SVG injection into a React-hosted vanilla canvas. Also avoids security hook warnings about innerHTML with untrusted content.
---
## LRN-022 | 2026-05-21 | pnpm 11.x requires Node 22.13 — pin pnpm to ≤10.x when staying on Node 20, never use `@latest`
pnpm 11.x imports `node:sqlite` for its store-index module — loaded at pnpm startup for any command that touches the store (install, fetch, add, prune). `node:sqlite` is a Node 22.13+ built-in. Result: `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` on every fresh Docker build using `node:20-alpine` + pnpm 11.x. The crash is deterministic for cold installs and invisible for warm dev hosts that already have `node_modules` resolved (pnpm 11 on Node 20 can still spawn child scripts because the store module isn't required for `pnpm run`).
Initial hypothesis ("pnpm@latest pulls a newer 11.x with a new Node floor") was wrong — the whole pnpm 11.0+ line carries the sqlite dependency.
Fix paths:
- Stay on Node 20 → pin Dockerfile to `pnpm@10.x` (e.g. `corepack prepare pnpm@10.13.1 --activate`). pnpm 10 reads lockfile v9 unchanged.
- Move to Node 22 → bump `FROM node:22-alpine`, `.nvmrc`, and CLAUDE.md stack table together. Required if pnpm 11+ features needed.
- Mirror exact version in `package.json`: `"packageManager": "pnpm@X.Y.Z"` so host + Docker stay synced via corepack.
- Never `corepack prepare pnpm@latest` — re-resolves at every cold build, silently bumps toolchain across deploys with no commit.
**Why:** Floating tag = drift bomb between cached dev + fresh prod resolve. Same risk for unpinned `node:lts`, `:alpine`, GitHub Actions `uses: foo@v1` (prefer SHA). Lockfile pins app deps; Dockerfile must pin toolchain.
**How to apply:** Before first prod deploy, audit every Dockerfile, docker-compose, and CI workflow for floating upstream refs. For pnpm specifically, check Node version against pnpm minimum (pnpm 11 ↔ Node 22.13, pnpm 10 ↔ Node 18+, pnpm 9 ↔ Node 18+).
---
## LRN-025 | 2026-05-22 | SVG importNode executes inline scripts — sanitize before append
`DOMParser.parseFromString(text, 'image/svg+xml')` is safe — doesn't execute scripts during parse. But `document.importNode(svg, true)` into a live document DOES allow `<script>`, `on*` event handlers, and `<foreignObject>` to execute. Must strip these after importNode, before appending to DOM.
**Why:** discovered during pathology editor code review — file upload path accepts arbitrary SVG.
**How to apply:** any tool accepting user-uploaded SVG: strip `script`, `foreignObject`, and all `on*` attributes after importNode. Or use DOMPurify. Applies to both standalone HTML tools and React-wrapped vanilla editors.
---
## LRN-026 | 2026-05-22 | Standalone HTML tools: port logic inline, don't share modules
When standalone .html tools (no build step) need logic from TS modules (zoneMatch, ID generation), port algorithm inline as vanilla JS. Cannot import .ts files. Keep algorithms identical to source for consistency. Document which .ts file was ported so future changes can sync.
**Why:** pathology-editor.html ports normalizeLabel/levenshtein/scorePair/matchZone from src/lib/zoneMatch.ts.
**How to apply:** if zoneMatch.ts changes, pathology-editor.html matching must be updated manually. Consider a test that compares outputs of both implementations on a shared fixture set.
---
## LRN-027 | 2026-05-22 | CSS h-full fails in nested flex — use flex-1
`height: 100%` (Tailwind `h-full`) resolves to `auto` when parent has `flex-1` but no explicit `height`. Caused 3 failed centering attempts on route containers inside App.tsx flex layout. Fix: use `flex-1` (flex-grow) on child instead — works because parent IS a flex container, no explicit height needed.
**Why:** nested flex layout: App wrapper (min-h-screen flex-col) → main (flex-1) → route (h-full broke here) → section (flex-1 grid place-items-center). The section's `place-items-center` needs actual height to center within.
**How to apply:** any flex-nested layout where child needs to fill parent — use `flex-1`, not `h-full`, unless parent has explicit `height` or is viewport-sized (`h-screen`).
---
## LRN-028 | 2026-05-27 | Drive derived UI by spawning the source-of-truth row, not patching each consumer
SVG highlight (boneStates) AND findings picker both derive from observation.zones. So making a cross-region vertebra pick "highlight + add zone + add findings" = ONE lever: spawn the spine zone in observation.zones. No separate highlight call, no separate findings wiring — both consumers already react to zones. Keep distribution logic pure (`distributeVertebraeToZones(zones, targetIndex, verts, bones)` → new zones[]) so it unit-tests without React; component handler stays a one-liner.
Inverse-map region→zone via reusing the same label heuristic (`regionFromLabel`) that maps zone→region — store the function once, scan bones for `special==='vertebral-precision'` whose label matches.
Apply: any feature where "select X in modal → reflect in N places". Find the single derived-from state; mutate that; let existing selectors fan out. Avoids drift between the highlight path and the data path.
---
## LRN-029 | 2026-06-13 | Vite bundles only index.html — standalone HTML must live in public/
Extra .html at repo root never reaches dist/ — Vite build entry = index.html only. Prod 404: nginx try_files falls through to SPA index.html, React shows "Page introuvable". Fix: put standalone HTML in public/ (copied verbatim to dist/). Links resolve from web root, so href stays /file.html.
**Why:** pathology-editor.html shipped at root (BDR-020 standalone-HTML pattern), worked in `pnpm dev` (Vite serves root files in dev) but 404'd in prod (only public/ + bundled entries land in dist/). Dev-vs-prod gap hid it.
**How to apply:** standalone HTML tool / extra entry → public/, OR add to vite build.rollupOptions.input for hashed-asset processing. Verify via `vite preview` (serves real dist/), not just `pnpm dev`. Ties to [[BDR-020]].
## LRN-030 | 2026-07-12 | Dockerized SPA on port >=1024 — full non-root nginx works
nginx:alpine default = master root, workers nginx. Listen port >=1024 → USER nginx viable: chown /var/cache/nginx + pre-created /var/run/nginx.pid + /etc/nginx/conf.d (entrypoint envsubst rewrite) + html dir (env.js write). Official image log symlinks (/dev/stdout|stderr) work non-root.
**Why:** tour 2026-07-12 semgrep HIGH (no USER before ENTRYPOINT, Dockerfile:34). Fixed d8e478a; verified docker run: HTTP 200, SPA fallback, env override, ps = uid 101 master+workers.
**How to apply:** any nginx-served SPA container: keep listen >=1024, chown the 4 paths above, USER nginx. Contract change: PORT <1024 now fails to bind — flag BREAKING. Alt base: nginxinc/nginx-unprivileged.
## LRN-031 | 2026-07-12 | Build toolchain in dependencies inflates prod CVE audit surface
vite + @vitejs/plugin-react-swc + @tailwindcss/vite sat in dependencies → `pnpm audit --prod` reported their CVEs as prod findings. Build-time-only packages belong in devDependencies; SPA runtime imports none of them.
**Why:** tour 2026-07-12 cso posture audit — all 3 "prod" advisories were build-toolchain. Moved 187dfb5; build+tests green, prod audit clean.
**How to apply:** scaffold check: anything imported only by vite.config / build pipeline → devDependencies. Then `pnpm audit --prod` reflects real runtime surface. Docker multi-stage unaffected (builder installs all).
---
## LRN-032 | 2026-10-08 | pnpm via corepack prepare, not ~/.local/bin
Dev host: no pnpm on PATH, no node_modules, Node 24.21 (CLAUDE.md said Node 20 + `~/.local/bin/pnpm`, both stale). `corepack prepare pnpm@10.13.1 --activate` + `corepack pnpm <cmd>` works, zero global install, same pin as Dockerfile (BLK-005). Suite 271/271 on Node 24.
Apply: never `export PATH=…` in Bash tool (denied); call `corepack pnpm`. Pin `packageManager` in package.json so corepack picks version alone.
---
## LRN-033 | 2026-10-08 | Characterise legacy via DOM + prototype spies, no refactor
Untestable seams (click chain inside route, PDF text) pinned without touching src: render route in MemoryRouter + mock `@/anatomy/svgLoader` to parse real files, dispatch bubbling click on `[data-anno-id]`; `vi.spyOn(PDFPage.prototype,'drawText')` captures every drawn string (pdf-lib has no extractor); attachment dicts via `doc.context.enumerateIndirectObjects()` + `String(obj)` (object streams hide names from raw bytes). Standalone HTML tool: slice functions by text markers, `new Function(src)` → parity test.
Trap: store set outside React then click = stale closure; drive state through UI (collapse card) and `waitFor`.
Apply: any "tests before migration" step on untested legacy code.
---
## LRN-034 | 2026-10-08 | pnpm 10.13 reads onlyBuiltDependencies, not allowBuilds
`allowBuilds` key in pnpm-workspace.yaml = pnpm ≥10.14 syntax; 10.13.1 ignores it silently → "Ignored build scripts: @swc/core, esbuild" on every install. Fix: `onlyBuiltDependencies` list. Warning persists until `pnpm rebuild` (state cached in node_modules/.modules.yaml), then disappears.
Also: root scripts calling `pnpm -r` fail under `corepack pnpm` (shim not on child PATH) → pin pnpm as root devDependency.
Apply: any pnpm 10.x workspace; check `pnpm --version` vs key syntax before trusting a silent config.
---
## LRN-035 | 2026-10-08 | PGlite + pgtap = Dockerless Supabase RLS tests
`@electric-sql/pglite` 0.3 bundles `pgtap`, `pgcrypto`, `uuid_ossp` (`import { pgtap } from '@electric-sql/pglite/pgtap'`). Boot ~1s, `create extension pgtap with schema extensions` + `set search_path to public, extensions` (else pgTAP functions pollute `public` and break "list public functions" checks; filter `pg_depend deptype='e'` too). `db.exec(file)` runs multi-statement begin…rollback; collect string cells → TAP lines; fail on `/^not ok/` or `# Looks like`. After error: `rollback` to clear aborted tx. Impersonate: `set local role authenticated; set_config('request.jwt.claims', '{"sub":…}', true)`. `now()` frozen in tx → test updated_at by overwriting then `is(updated_at, now())`.
Apply: any Supabase project needing SQL tests in CI without Docker.
---
## LRN-036 | 2026-10-08 | Supabase default privileges grant ALL to anon/authenticated on new public tables
Hosted/local Supabase: `alter default privileges … grant all on tables/functions to anon, authenticated, service_role`. New table or RPC = anon can SELECT/EXECUTE until revoked (RLS still filters rows, but RPC runs). Pattern per migration: `revoke all on <table> from public, anon, authenticated;` then exact grants (column-level for partial UPDATE); `revoke all on function … from public, anon`. Also Postgres default EXECUTE to PUBLIC on functions in own schemas → `alter default privileges in schema private revoke execute on functions from public`. Shim replicates defaults so pgTAP `has_table_privilege('anon',…)` catches omissions.
Apply: every migration; pin with pgTAP privilege checks.
---
## LRN-037 | 2026-10-08 | SQL tests seed-agnostic; generated files through a deterministic formatter
Real stack applies `seed.sql` before `supabase test db`; PGlite harness applies migrations only → absolute `count(*)` and "last owner" assertions passed on PGlite, failed on real stack (6/81). Fix: filter every count by fixture ids; neutralise foreign rows inside the rolled-back tx before invariants like "last owner". `supabase gen types` (CLI 2.120) emits unformatted TS and suggests oxfmt → pipe through project prettier in both `db:types` and `db:types:check`, else CI diff flaps.
Apply: any dual-runner test setup (shim vs real); any CI diff on generated code.
---
## LRN-038 | 2026-10-08 | RLS filters, never raises: test "no change", and trigger guards under the owner role
API-role UPDATE/DELETE on a row hidden by policy touches 0 rows silently → `throws_ok` wrong; assert the row unchanged afterwards (`is((select content ...), expected)`). Trigger-level immutability must be proven with `reset role` (table owner bypasses RLS). pgTAP `is()` cannot wrap a data-modifying CTE (`with u as (update …)` must be top level) → plain statement then a read. Triggers fire alphabetically by name: when two BEFORE triggers reject, the first name's errcode surfaces (species check 23514 before guard 42501) → pick test inputs that isolate the guard.
Apply: every RLS + trigger pgTAP file.
---
## LRN-039 | 2026-10-08 | Dual-runner parity: pin collation, grant pg_temp fixtures to API roles
Real Supabase image sorts text with a locale collation (`anatomical_sheet_asset…` before `anatomical_sheet.archived`), PGlite with C → `results_eq` on `order by text` flaps; pin `order by col collate "C"`. pg_temp tables/functions created as postgres are invisible to `set local role authenticated` → `grant all on pg_temp.t to anon, authenticated; grant execute on function pg_temp.f(...)`. jsonb equality check beats `(x->>'k')::int = n` in a CHECK (no cast error on garbage).
Apply: any pgTAP file with fixtures read while impersonating; any ordered results_eq (extends LRN-037).
---
## LRN-040 | 2026-10-08 | Function privileges: revoke per function, pin with a pg_proc census
`alter default privileges in schema X revoke execute on functions from public` does nothing (BLK-007). Pattern: every migration ends with `revoke all on function private.f(args) from public` per function + explicit grants; a pgTAP census (`has_function_privilege('anon'|'authenticated', p.oid, 'execute')` over pg_proc of private/audit, compared to an allowlist via `string_agg(... order by proname::text collate "C")`) fails the next omission. `results_eq` over `name`-typed columns vs text literals raises "could not determine which collation" on PGlite → compare one aggregated string. Trigger functions that call other private functions must be `security definer` once EXECUTE is revoked (the invoking API role no longer holds it).
Apply: every Supabase migration; the census is the backstop.
---
## LRN-041 | 2026-10-09 | Real Supabase image vs PGlite shim: storage triggers, pnpm script cwd
Real `storage.objects` carries `storage.protect_delete` (statement trigger: "Direct deletion from storage tables is not allowed") → a pgTAP that runs DELETE as an API role passes on the shim and aborts the whole file on the real stack; assert write restrictions through a `pg_policies` census instead. Shim stays minimal (buckets/objects columns actually touched). `pnpm --filter pkg script <relative path>` runs inside the package dir → resolve CLI paths from `process.env.INIT_CWD`. Node 24 strip-types cannot follow workspace directory imports (`ERR_UNSUPPORTED_DIR_IMPORT`) → tsx for CLIs that import workspace packages.
Apply: every pgTAP touching storage.*; every workspace CLI.
---
## LRN-042 | 2026-10-10 | Changeset authoring over a baseline: python modules per theme, stylised SVG audited by gridded crops
Authoring 44 changes / 679 ops by hand is error-prone → scratch python modules (one per research theme, shared helpers `set_op/cite_op/add_change`, auto-numbered ids, targets derived from the baseline by walking it) built into changes.json; the pipeline's Zod + integrity rules catch any bad target at once. Order of modules = order of ops: a later module must address ids renamed by an earlier one (consultation-reason category ids). Stylised drawing: render with `magick` + 50-unit grid crops; sample first non-white row per column to prove "point floats above the silhouette" (t18-l1, l6-s1 were 30-70 units above the back). ImageMagick's internal SVG renderer drops shapes with `fill="none"` and shapes containing a `<title>` child → overlay uses fill-opacity and puts `<title>` on the `<g>`. Research agents: one theme each, every citation tagged VERIFIED-fetched/snippet/UNVERIFIED; only fetched or bibliographically confirmed entries enter the registry, unread books say "non consulté" in the citation.
Apply: next species/sheet curation; any overlay/diagnostic SVG rasterised with ImageMagick.
---
## LRN-043 | 2026-10-10 | Migrating an app onto a new data model: freeze goldens first, make ids + maps data, read fresh state in DOM handlers
Freeze golden artifacts with the OLD code before touching it (v2 PDFs via a one-shot vitest, MAKE_GOLDEN=1, deleted after): the new importer is then tested against real archive-like bytes. Generate id/path maps from the pipeline's own records (renames/removals), never hand-written, and commit them as golden-tested data. In React routes, click handlers bound through `useEffect` capture stale closures when two DOM clicks land before a re-render (tests dispatch synchronously): read `store.getState()` inside the handler. A sheet needed to restore a draft but only known from the draft → load the default species' sheet when no report is open. Vitest has its own config: a Vite plugin providing a virtual module must be registered there too. ImageMagick cannot verify marker look with `<title>` children or `fill="none"`: strip titles for the raster only.
Apply: Step 6 (PDF v3 snapshot), Step 13 (Supabase SheetProvider), any future schema bump.
## LRN-044 | 2026-10-10 | CLI over untrusted documents: escape before print, privacy default, generic parse errors
Context: `report:compare` prints content of archive PDFs (attachment JSON). Security audit: raw interpolation lets a crafted attachment carry ESC/CR sequences that erase or forge lines, including a `!! UNRESOLVED` marker in an integrity tool; free text leaks names when stdout lands in CI logs; V8 `JSON.parse` message echoes ~15 chars of the input.
Pattern: one `esc()` helper (`/[\p{Cc}\p{Cf}\u2028\u2029]/gu` → `\uXXXX`) on every interpolated untrusted string incl. file names and error messages; default output = ids + catalog labels + counts + placeholders, `--full` opt-in for names and free text, same rule in every mode (`--diff` too); `SyntaxError` → generic reason; `statSync().isFile()` + size before `readFileSync`; INIT_CWD for paths under pnpm.
Apply: any future CLI/log over report content (Step 6 server import, worker). Test with `\u001b[2K`, `\n`, `\u009b`, `\u202e`, `__proto__` ids.
---
## LRN-045 | 2026-10-10 | Permanent `will-change: transform` blurs text; promote only during the animation
Context: findings picker text blurry on screen, crisp in PDF (Step 5 validation). `motion.ul` kept inline `will-change: transform, opacity` after its 220 ms slide (computed transform `none`); list sat at fractional offset inside height-animated card (left 561.1875 px desktop, top 735.77 px mobile) → element stayed on own compositor layer, text resampled at non-integer position → blur. Fix = drop the prop; motion promotes the element itself while animating (1f0b710).
Pattern: never set permanent `will-change` on text containers; let the animation lib promote for the duration. Diagnose with headless Chromium: computed `willChange`, bounding rect fractional offsets, edge-sharpness ratio before/after (headless has no LCD antialiasing → desktop delta flat, user confirms in real browser). Regression test = rendered element has no inline `will-change`.
Apply: any `motion.*`/CSS transition on lists, cards, modals holding text; design-review audits.
---
## LRN-046 | 2026-10-11 | Refactor a render pipeline behind goldens frozen in two fixture modes; lean-document snapshot beats a new schema
Step 6 moved the PDF pipeline into `packages/pdf` with zero visible change. What made it provable: Phase 0 froze drawn text (page, x, y, size, font), image placements, link annotations and per-view structural facts with the OLD code, in two harness modes (logos absent / present via a fetch stub serving the real public/ bytes) and per locale (footer geometry depends on label width). Golden JSON = oracle; the port had 0 mismatch; the two intentional differences (hidden markers absent, data-* gone) were declared as relaxed fields, never by editing goldens. Snapshot shaped as a valid lean `AnatomicalSheetDocument` reused the index, the renderer and 21 integrity rules (3 challengers killed the dedicated-schema idea). Node-side xmldom composer already existed in curation (`app-review.ts`): promote, don't rewrite. resvg 0.40 panics on gradient fills culled by a cropped root viewBox (head view) → test adapter renders the full box and crops pixels; Chrome is fine. Executors denied `rm`/`git rm`: orchestrator deletes on literal relative paths after checking importers.
Apply: any pipeline extraction (Step 13 Supabase provider, Step 14 worker); any "snapshot" design: reuse the live schema minus content before inventing one.
## LRN-047 | 2026-10-11 | Supabase Auth in a SPA: initialize() + PKCE same-browser rule, GoTrue codes → closed kinds, pgTAP data-modifying CTE trap
Step 7 facts worth keeping. (1) `client.auth.initialize()` is public and idempotent: await it at store start to catch the URL exchange error (expired/foreign link) that `onAuthStateChange` never reports; `INITIAL_SESSION` ordering vs that promise is not guaranteed → a callback route landing signed-out = failure, don't wait for a flag. (2) PKCE confirmation/recovery links only open a session in the browser that made the request (verifier in its localStorage); the email is still confirmed server-side → phrase it ("opened in another browser… just sign in"), don't claim expiry. (3) supabase-js 2.117 `AuthError.code` (`invalid_credentials`, `user_already_exists`, `weak_password`, `otp_expired`, `bad_code_verifier`…) → map to a closed union in the access layer, UI translates `auth.failure.<kind>`; raw messages never rendered. (4) Account load must run outside the auth callback (`setTimeout 0`): the client serialises callbacks, awaiting a request inside deadlocks. (5) pgTAP: `select is((with upd as (update … returning 1) select count(*) from upd), …)` fails ("data-modifying CTE must be top level") and silently breaks the plan count; use `lives_ok` + a read after `reset role`. (6) Mailpit API (`/api/v1/search?query=to:<email>`, `/api/v1/message/<id>`) makes the confirmation + recovery flows scriptable headlessly; playwright-core installed in the scratchpad + cached `ms-playwright` chromium via `executablePath` = no project dependency.
Apply: every future Supabase auth surface (Step 14 gating, invitations), any pgTAP write assertion, any e2e of email flows.
## LRN-048 | 2026-10-12 | Before porting a module, list the hidden serialisation contracts; goldens on drawn primitives make an engine swap provable
Context: Rust review inventories. Facts found: `documentSha256` = sha256 of Prettier-formatted text (only compared at runtime → mismatch = rebase, not loss); coordinates = raw JS number strings (serde_json prints `1523.0`); attachment = insertion-order JSON, snapshot = Zod schema order; `.optional()` absent vs nullable `null` (serde-wasm-bindgen json preset writes null → breaks readers); text x positions = AFM widths + kerning pairs; dates = ICU; `toUpperCase`, `/\s+/`, non-fatal TextDecoder, last-dup-key JSON.parse, Zod `.int()` accepting 2.0. The 39 PDF goldens record draw calls (spies), never bytes → a Rust engine with a draw-log layer can match them exactly; byte goldens (xmldom XMLSerializer, Prettier files) cannot be matched by another stack → compare parsed trees or regenerate by decision.
Apply: any port (R2–R5): freeze unpinned outputs with the old code (LRN-046), write the contract list with a fixture each, decide lenient-vs-strict per item, keep an N-1 reader test permanently. Challengers found 2 blockers rev 1: deletion schedule vs surviving consumers (name the last consumer per module), and deployment facts (CSP without 'wasm-unsafe-eval', VPS compiling images) → check the serving path before the language.
## LRN-049 | 2026-10-13 | R0 experimental findings: serde_json fast float path, wasm traps and the ESM cache, RLIMIT_CPU soft=hard, minimal rustup profile, traced seccomp set
Facts proven on the real environment (docs/development/RUST.md §5), each one changed a design assumption of the review:
- `serde_json` default float parsing is a fast path one ULP off on some inputs (`1715.4285714285713` → `1715.428571428571`): enable `float_roundtrip` whenever bytes must match `JSON.stringify`; the formatter alone (`js_number`) is not enough.
- wasm32 = panic=abort: a panic and a shadow-stack overflow both surface as `WebAssembly.RuntimeError`; after a stack-overflow trap the next call fails in the allocator (deterministic), after a plain panic the instance still answers with a never-unwound stack pointer (silent) → never reuse an instance after any trap; the wasm-bindgen glue caches its instance in a module variable and `import()` of the same URL returns it → a fresh instance needs a new module record (cache-busting query) or a new Worker.
- `setrlimit(RLIMIT_CPU, soft, hard)` with soft == hard kills with SIGKILL (hard checked first), indistinguishable from a parent deadline kill → soft two seconds below hard gives SIGXCPU.
- Official `rust:` images install rustup's minimal profile: `rustup component add rustfmt clippy` in the image, else every container downloads them (rust-toolchain.toml lists the components).
- A single-threaded musl static decode (image/zune-jpeg/png/image-webp + libwebp encode) makes exactly 7 syscalls after start: read write mmap munmap mremap exit_group getrandom; mallocng used neither brk nor mprotect, no futex. Derive with strace after a stderr marker, compare in the build, keep an explicit abort-path set (rt_sigaction rt_sigprocmask getpid gettid tkill tgkill exit) proven by the RLIMIT_AS → SIGABRT test.
- Unoptimised debug decoders blow a 10 s CPU budget on 4096² inputs: `[profile.dev.package."*"] opt-level = 3`.
- cargo-deny 0.20: a versionless path dependency is a "wildcard" (`allow-wildcard-paths = true`) and a workspace-inherited path dependency triggers an `unresolved-workspace-dependency` bug (declare `path = "../core"` per crate).
- CSP: `'wasm-unsafe-eval'` is required for `WebAssembly.instantiateStreaming` under `script-src 'self'` and allows nothing else (inline scripts still blocked); proven with the production nginx image + headers in headless Chrome 156.
Apply: R1 (worker loop keeps the same child), R2 (browser loader: fresh-instance mechanism, float_roundtrip stays on, CSP line at activation), any future "it should work" assumption about a runtime → run it in the real environment first.
## LRN-050 | 2026-10-13 | Native vs Docker Rust: rustup auto-install, non-interactive PATH, path strings in the wasm, worker unit tests native
- `rustup show` inside a repo with `rust-toolchain.toml` auto-installs the channel (rustup 1.29, default profile → rust-docs too, ~1.5 GB per toolchain); `rustup target add --toolchain <ver>` + two `cargo install --locked` ≈ 100 s with a warm registry.
- Agent / hook / editor shells are non-interactive: `~/.bashrc` returns early, `~/.cargo/bin` absent from PATH while the user's shell has it → scripts source a 5-line guard (`scripts/rust-env.sh`), never assume PATH. The harness refuses tool commands containing `export PATH=`: use absolute paths or a sourced file.
- Same rustc + lock → wasm differs by 64 B and by hash between build roots (`/w` vs `/home/...`): panic `Location` paths embedded; bit-identity needs `--remap-path-prefix` (unset at R0). Builder image = reference when bytes must match.
- Worker sandbox tests are `#![cfg(feature = "test-hooks")]`: plain `cargo test --workspace` compiles them empty → the 9 worker unit tests run natively for free (R0's `--exclude faunosteo-worker` was unneeded); seccomp derivation stays Docker/musl only (glibc syscalls differ).
- Contract oracles need a dry run before dispatch (EVAL-013/017 lesson, applied): a grep for `width * 4` matched my own SAFETY prose; `pnpm -r test:run` prints per-package totals, never one root line.
## LRN-051 | 2026-10-13 | Supabase Storage + worker facts: 400-as-404, RETURNS TABLE arg names, service_role cannot read private tables, pg_temp definer helpers in pgTAP
- storage-api v1.79 answers a missing object with HTTP 400 and body `{"statusCode":"404","error":"not_found"}` (DELETE and GET alike): classify by body, not status, or purge acks never happen (sweep errors loop every interval; caught by the e2e queue-drained assertion, not by unit tests).
- `pg_proc.proargnames` lists OUT columns of a `returns table` function: a types-vs-schema test must filter `proargmodes in ('i','b','v')` or the generator's Args (IN only) never match.
- `service_role` has BYPASSRLS but no table grants on `private.*`: a pgTAP block running as service_role cannot `select` the purge queue → read private tables after `reset role`; the worker RPCs are definer anyway.
- pgTAP pattern: `pg_temp.row(key) returns public.assets security definer` + `pg_temp.ids` map lets authenticated/service sessions inspect rows across role switches; `is((row).status, 'literal')` resolves the enum from the first arg; rows inserted in the test share `now()` → an "older than 0 s" sweep needs `<=`, not `<`.
- PostgREST: `raise exception using message = '<code>', errcode = 'P0001'` → 400 `{code:"P0001", message:"<code>"}`; only accept messages with the closed-code shape (lowercase + `_`, ≤ 40) to keep server free text out of the kinds.
- Harness: writing any `.env*` file and `gitflow finish` (merge + push to develop) are refused by the auto-mode classifier; forks (full-context subagents) parallelise Rust vs TS tracks well when a contract-level doc (STORAGE.md) is written first.
- Real browser proof without a project dep: playwright-core in the scratchpad + cached `~/.cache/ms-playwright/chromium-*` via `executablePath`, Vite on a spare port with `VITE_SUPABASE_*`; `setInputFiles` exercises createImageBitmap + canvas for real (happy-dom cannot).
Apply: every Storage call in later steps (documents, logos), every `returns table` RPC, future pgTAP on service-role paths, R2+ gates.
## LRN-052 | 2026-10-13 | Restrict Supabase CLI ports under Docker rootless without sudo: daemon default ip + gateway; rootless file-permission trap
- Supabase CLI 2.120 publishes 54321-54324 with no host address and has no bind option in config.toml → Docker uses the daemon's default (`0.0.0.0` + `[::]`). Docker rootless reads `~/.config/docker/daemon.json`: `{"ip":"127.0.0.1"}` makes every address-less published port loopback-only, no sudo, no firewall (needs daemon restart + containers recreated: `pnpm db:stop && pnpm db:start`).
- Rootless publishing = rootlesskit listening sockets in the host netns → host INPUT/UFW rules DO apply (rootful Docker's DNAT bypasses UFW). Still prefer removing the listener over filtering it.
- Re-expose only what browsers need with a tiny nginx on the stack's network, published on the LAN address explicitly (`<ip>:54321`, `<ip>:54324`); `resolver 127.0.0.11` + variables in `proxy_pass` so a restarted stack is followed.
- Rootless bind mounts: a 600 file owned by the user is unreadable by the container's non-root user (subordinate uid) → nginx 500 "open() htpasswd failed (13)". Make hash-only files 644, keep clear secrets 600 outside the mount.
- Probing "closed" vs "open" with curl: exit 7 (refused) / 28 (timeout) = closed; a non-HTTP TCP service (PostgreSQL) gives exit 52/56 = OPEN. HTTP 000 alone proves nothing.
Apply: any DEV service exposure on this machine; future staging compose.
## LRN-053 | 2026-10-13 | Correction of LRN-052: Supabase CLI 2.120 binds 0.0.0.0 explicitly; rootless container probes cannot see the host LAN firewall
- Owner applied `~/.config/docker/daemon.json {"ip":"127.0.0.1"}` + restart: the CLI still published 54321-54324 on 0.0.0.0 and prints "All services bind to 0.0.0.0" → it sets the host IP explicitly; the daemon default never applies. LRN-052 bullet 1 is wrong for the CLI (still true for address-less ports of other containers). Only a host firewall closes PG/Studio/raw Mailpit; UFW rules scoped `in on <lan-iface>` work on rootless listeners.
- A gateway cannot share a port with a 0.0.0.0 listener whatever its own address ("port is already allocated") → serve the authenticated Mailpit on another port (54325).
- Rootless (slirp/pasta) containers reach the host's own LAN IP by local delivery, never through the LAN interface → firewall refusals on that interface are invisible to any probe run on the host; prove them from another device (`nc -zv -w 3 <ip> <port>`).
- Lesson: an "it should apply" assumption about a third-party tool's binding must be tested before handing a procedure to the owner (I flagged it as a hypothesis, but the owner still spent a daemon restart on it).
Apply: any exposure work on this machine; staging compose (bind explicitly there).
## LRN-054 | 2026-10-14 | Porting Zod to serde without drift; wasm in Vite; agent and harness traps
- serde silently widens Zod: a missing `Option` field defaults to None (use `deserialize_with` to make a nullable key required), `null` reads as None for an optional (use a `present` helper refusing null), `u32` refuses `2.0` that `.int()` accepts (JsInt over f64), internally tagged enums print the tag first (untagged enum + literal tag field at the schema position keeps Zod order). Zod drops a `__proto__` key in `z.record`; JS regex `$` = end of input; `.min/.max` count UTF-16. Prove with byte equality against `JSON.stringify(Schema.parse(x),null,2)` on real documents, a characterisation set frozen from the old functions, and a verdict table run by Zod once.
- Vite: `import x from 'pkg/glue.js?url'` emits the wasm-bindgen glue as an asset (no bundling); `import(`${url}?instance=${n}`)` gives a fresh module record in dev (`/@fs/…`) and build; works under CSP `script-src 'self' 'wasm-unsafe-eval'`. In happy-dom suites Vite rewrites `new URL(rel, import.meta.url)` into `/@fs/…` → Node readFile fails: build paths from `fileURLToPath(import.meta.url)`.
- A caught `WebAssembly.compile` CSP refusal logs nothing in the console: read the `securitypolicyviolation` event (`blockedURI` = `wasm-eval`). Headless Chromium defaults to en-US: set the page locale before asserting French strings. The DEPLOY CSP also refuses the footer's external credit logo (img-src).
- This harness decodes `\uXXXX` in tool inputs (heredocs, Write): build escape sequences with python `chr(92)`.
- `isolation: worktree` forks started at an old commit (605ee7c, not HEAD): each fork had to move its temp branch; brief forks to check `git log -1` first. `git worktree remove` / `git branch -d` on those temp branches refused by the auto-mode classifier → leftover worktrees (3.2 GB) for the owner to remove.
- Forks with full context + disjoint file ownership + "no commit, I collect the diff" merged with zero conflicts (one deliberate stub replaced).
Apply: R3/R4/R5 ports (same oracle stack), any wasm loaded by Vite, any agent fan-out.
## LRN-055 | 2026-10-14 | Lossy normalisation pre-pass hides user-data alteration; classify parser refusal instead
Context: R2 rewrote lone surrogate escapes to U+FFFD before serde_json so JS-era texts still parsed (L1). Owner refused: silent change of historical data. Fix: drop pre-pass; serde_json already refuses; scan text only after failure to name kind (zero cost on valid input, exact refusal kind for UI message + quarantine). Trap found by fix: oracle file freezing TS outputs carried lone escapes → whole-file parse failed; test loader must spell escapes out as literal text (evidence kept), never re-normalise. Also: `u32::from_str_radix` accepts leading `+` → escape scanner checks hex digits explicitly.
Apply: any reader of user data (R3 SVG, R4 PDF reader, R5 pipeline) → refuse with closed kind + keep original, never repair silently; a leniency step needs explicit owner decision and declared-difference test.