Compare commits
18
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
06ee6eb797 | ||
|
|
8992c19ae6 | ||
|
|
2d7f4c16ed | ||
|
|
5c3661963f | ||
|
|
8b7eeb6edd | ||
|
|
fa41bc2e5b | ||
|
|
530af1bbfc | ||
|
|
a1fc76c698 | ||
|
|
9e5eba7975 | ||
|
|
4eab981fe2 | ||
|
|
09655b2552 | ||
|
|
d3dfd03213 | ||
|
|
e8da0d96d9 | ||
|
|
3a4614bc86 | ||
|
|
6287e5bb9f | ||
|
|
882905ed21 | ||
|
|
e24e747d90 | ||
|
|
9135d73cfa |
No files matched your search
@@ -0,0 +1,149 @@
|
||||
# Audit log — `pnpm e2e:avatar` on develop reaches the sandbox only (2026-11-02)
|
||||
|
||||
Branch `bugfix/avatar-e2e-sandbox-only` (off develop 6287e5b). Contract
|
||||
`.claude/tasks/contracts/2026-11-02-avatar-e2e-sandbox-only-0240.md`, plan
|
||||
`.claude/tasks/plans/2026-11-02-avatar-e2e-sandbox-only-0215.md` (revision 3).
|
||||
Every live command below was run by the orchestrator, from the bugfix worktree by
|
||||
absolute path (`W=…/scratchpad/bugfix-avatar`), never through a bare `pnpm`, never
|
||||
from the main checkout (which still holds the old DEV runner). Raw traces and outputs
|
||||
stay in the session scratchpad (`…/scratchpad/proofs/`), not in the repository.
|
||||
|
||||
## Pre-flight (read-only)
|
||||
|
||||
- Docker: context `default`, endpoint `unix:///run/user/1000/docker.sock`, `DOCKER_HOST`
|
||||
set to that same socket. No `docker context` pointing elsewhere.
|
||||
- Proxy variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, their lower-case
|
||||
forms, `NODE_USE_ENV_PROXY`, `npm_config_proxy`, `npm_config_https_proxy`,
|
||||
`GLOBAL_AGENT_HTTP_PROXY`): none set in the shell; every proof below also unsets them
|
||||
explicitly (`env -u …`).
|
||||
- `scripts/avatar-e2e.sh` absent in `$W`; `package.json` alias = `bash scripts/db-sandbox.sh avatar-e2e`.
|
||||
- Old DEV runner container `faunosteo_worker_e2e`: absent.
|
||||
- DEV containers `supabase_*_faunosteo` (8), all `running`, `StartedAt` 2026-10-28T14:45:28/29Z
|
||||
(recorded before; identical after every proof, see "After").
|
||||
- Sandbox before: the V1-2 session's stack (db 57432, auth 57999, rest 57300, storage 57500,
|
||||
mail 57025, all on 127.0.0.1, no gateway, no worker), network `faunosteo_dbsandbox_net`
|
||||
(bridge, 5 containers), no Docker volume named `faunosteo_dbsandbox*`.
|
||||
- Shared image `faunosteo_worker:dev` before: `sha256:b32319b9…` (V1-2 build of 2026-11-01 22:59).
|
||||
- No concurrent `db-sandbox`, `vitest` or `playwright` process.
|
||||
|
||||
## Static criteria (contract 1-4, 8)
|
||||
|
||||
| # | Oracle | Result |
|
||||
|---|---|---|
|
||||
| 1 | runner deleted, no line invokes it (the two "removed" mentions excluded) | `DEV_RUNNER_GONE` |
|
||||
| 2 | alias, `bash -n`, dispatcher line | `ALIAS_OK` |
|
||||
| 3 | suite identical to V1-2 once the `noRedirectFetch` lines are dropped (owner-gated, see below); db-sandbox.sh blocks 47-52, 58-61, 255, 270-332, 342-359 verbatim; no `cmd_verify_e2e` / `cmd_sheet_assets_e2e` | `BLOCKS_IDENTICAL` |
|
||||
| 4 | no `supabase status`, `54321`, `supabase_kong`, `supabase_db_faunosteo`, `supabase_network_faunosteo` in the runner or the suite | `NO_DEV_IDS` |
|
||||
| 8 | `corepack pnpm -s typecheck && lint` in `$W` (after `pnpm wasm:build`, the git-ignored `packages/core-wasm/pkg` being absent in a fresh worktree) | `STATIC_GREEN` |
|
||||
|
||||
## Refusal proofs (strace `-f -e trace=connect,sendto,sendmsg`, child processes followed)
|
||||
|
||||
Positive control: the same filter on `curl http://127.0.0.1:9/` shows 1 `AF_INET` connect.
|
||||
Keys in c, d, e, h, i are forged unsigned JWTs (`base64url(header).base64url(payload).x`),
|
||||
never the sandbox secrets, never DEV keys. Criterion: no `AF_INET` / `AF_INET6` line unless stated.
|
||||
|
||||
| Case | Setup | Result | AF_INET lines |
|
||||
|---|---|---|---|
|
||||
| a | `bash $W/scripts/db-sandbox.sh avatar-e2e`, `FAUNOSTEO_SANDBOX_DIR` = empty dir | `db-sandbox: not running (pnpm db:sandbox up fresh)`, rc 1, no container, dir still empty | 0 |
|
||||
| b | the suite (vitest binary, `vitest.e2e.config.ts`), no environment | throws `avatar e2e: run it through pnpm e2e:avatar, on the sandbox stack only`, rc 1 | 0 |
|
||||
| c | `SUPABASE_URL=http://127.0.0.1:54321`, `AVATAR_E2E_DB_CONTAINER=supabase_db_faunosteo`, two keys `iss: supabase-demo` | throws (same message) | 0 |
|
||||
| d | sandbox URL, keys `iss: db-sandbox`, container `supabase_db_faunosteo` | throws | 0 |
|
||||
| e | sandbox URL and container, anon key whose payload is not JSON | throws | 0 |
|
||||
| i | sandbox URL and container, anon `iss: db-sandbox` + service `iss: supabase-demo`, then the swap (i1, i2) | throws, both orders | 0, 0 |
|
||||
| h | nothing listening on 57800 (`ss -ltn`: 0), sandbox URL and container, two forged `iss: db-sandbox` keys | the guard passes; `beforeAll` fails on `createUser: fetch failed` (the refused connect), 5 tests skipped, rc 1 | 1: `connect(127.0.0.1:57800)` |
|
||||
| f | sandbox up, image present, 127.0.0.1:57800 held by `python3 -I -m http.server` | `db-sandbox: port 127.0.0.1:57800 is already in use: free it, nothing was started`, rc 1, no gateway, no worker, no `worker.*` env file | 1: the `/dev/tcp` probe `connect(127.0.0.1:57800) = 0` (the exception accepted by the owner) |
|
||||
|
||||
Reading of h (brief §3): the issuer check routes the run to the sandbox, it is not a signature
|
||||
check and not an authentication: whoever holds 127.0.0.1:57800 receives the keys the
|
||||
environment supplies. Nothing else is contacted.
|
||||
|
||||
## Setup and positive run
|
||||
|
||||
- `corepack pnpm --dir $W worker:image`: `faunosteo_worker:dev` now `sha256:d841660a…`
|
||||
(develop's crates; cached build dated 2026-11-01 01:38). The V1-2 build `b32319b9…` is no
|
||||
longer listed: the V1-2 session rebuilds it before its next worker run.
|
||||
- `bash $W/scripts/db-sandbox.sh down` (identity checked first: 5 `faunosteo_dbsandbox_*`
|
||||
containers on `faunosteo_dbsandbox_net`, no volume, no concurrent process), then
|
||||
`up fresh` from the branch: develop migrations and seeds, no key in the output.
|
||||
- Positive run, once, under strace, with hostile exports in the environment:
|
||||
`SUPABASE_URL=http://127.0.0.1:54321`, forged `iss: supabase-demo` keys,
|
||||
`AVATAR_E2E_DB_CONTAINER=supabase_db_faunosteo`, `SUPABASE_NETWORK=supabase_network_faunosteo`,
|
||||
`SUPABASE_INTERNAL_URL=http://supabase_kong_faunosteo:8000`, `WORKER_IMAGE=faunosteo_worker:local`
|
||||
(the old runner's knobs), proxies unset → `bash $W/scripts/db-sandbox.sh avatar-e2e`:
|
||||
**5/5 passed** (15 s), rc 0, `== worker up (faunosteo_worker:dev, run, via faunosteo_dbsandbox_gateway)`.
|
||||
- strace of the run: 4 `AF_INET` connects, all `127.0.0.1:57800` (1 probe `ECONNREFUSED`
|
||||
before the gateway existed, 3 from the suite); 0 to `:54321` / `:54322` / a LAN address; 0 `AF_INET6`.
|
||||
- Watcher during the run (filtered templates only, never a raw `docker inspect`):
|
||||
`docker port faunosteo_dbsandbox_gateway 8000/tcp` = `127.0.0.1:57800`; gateway and worker
|
||||
networks = `faunosteo_dbsandbox_net` only; worker `SUPABASE_URL=http://faunosteo_dbsandbox_gateway:8000`;
|
||||
worker env names = `PATH SSL_CERT_FILE SUPABASE_SERVICE_ROLE_KEY SUPABASE_URL WORKER_ID
|
||||
WORKER_POLL_SECONDS WORKER_QUARANTINE_GRACE_SECONDS WORKER_SWEEP_SECONDS`; image
|
||||
`faunosteo_worker:dev` = `d841660a…`; user `nonroot`, read-only rootfs, `CapDrop=[ALL]`,
|
||||
no published port.
|
||||
- Worker log events: `worker_start` 1, `job_completed` 3, `job_rejected` 3, `child_rejected` 3,
|
||||
`sweep_done` 4, `token_expires_soon` 1 (the sandbox key's lifetime); no DEV name, no key
|
||||
(`eyJ` count 0 in every output).
|
||||
|
||||
## After
|
||||
|
||||
- Gateway and avatar worker removed by the EXIT trap; no `worker.*` env file left in the state dir.
|
||||
- Final `bash $W/scripts/db-sandbox.sh down`: 0 `faunosteo_dbsandbox_*` container; the state
|
||||
dir keeps only `rehearsal/` and `upgrade-base/` (pre-existing).
|
||||
- DEV containers: same 8 `StartedAt` values as before. No HTTP request to DEV at any point
|
||||
(no connect to 54321/54322 in any trace).
|
||||
|
||||
## What the isolation rests on (not the issuer check)
|
||||
|
||||
- The worker's target is fixed to `http://faunosteo_dbsandbox_gateway:8000` in a 600 env file
|
||||
removed once the container started (`scripts/db-sandbox.sh` `start_worker`); the worker's
|
||||
HTTP client sets `max_redirects(0)` and `proxy(None)` (`crates/worker/src/http.rs:31,33`).
|
||||
- The gateway's upstreams are the sandbox containers by name; `location / { return 404; }`;
|
||||
published on `127.0.0.1:57800` only, checked after start (`docker port`).
|
||||
- The sandbox keys are signed with a secret DEV does not hold; the suite builds its clients on the
|
||||
constant `http://127.0.0.1:57800`, never on the env URL; `psql` on the constant container.
|
||||
- `scripts/dev-env.sh:23` exports `FAUNOSTEO_DEV_API_URL` into every child of db-sandbox.sh;
|
||||
nothing in the runner or the suite reads it. `NET` is a plain bridge (it can route to the host):
|
||||
the proofs above show nothing uses that route.
|
||||
|
||||
## Redirects refused (owner condition at the checkpoint, 2026-11-02)
|
||||
|
||||
The former residual LOW is closed on this branch: `tests/e2e/noRedirectFetch.ts` wraps the
|
||||
global fetch with `redirect: 'error'` (set after the caller's init, so nothing restores
|
||||
`follow`); the suite's `anonClient()` and `serviceClient()` pass it through `global.fetch`,
|
||||
which supabase-js hands to its auth, REST and Storage calls (raw to auth-js, through
|
||||
`fetchWithAuth` for REST and Storage; neither layer sets `redirect`, retries reuse the wrapper). No production client changes (`packages/supabase/src`, `apps/app/src`
|
||||
untouched since 6287e5b). Security gate nuance that motivated it: on a cross-origin redirect
|
||||
undici drops `Authorization` but keeps supabase-js's `apikey` header.
|
||||
- Regression test `packages/supabase/tests/no-redirect-fetch.test.ts` (in `pnpm --filter
|
||||
@faunosteo/supabase test:run`, 12 files / 131 tests green): two `node:http` servers, the
|
||||
origin answers every request with 302 towards the target; REST, auth and Storage calls all
|
||||
error, the target receives nothing, every origin request carries `apikey: test-key`; the
|
||||
control (plain fetch, default `follow`) reaches the target at `/landed`. Negative control by
|
||||
the executor: with `follow` in the wrapper, 3 of the 4 cases fail.
|
||||
- Live proof j (strace, same harness as a-i): a Python 302 listener on 127.0.0.1:57800
|
||||
(`Location: http://127.0.0.1:57801/landed`) and a recording target on 57801. Control:
|
||||
`curl -L` lands on 57801 (1 hit). The suite with forged `iss: db-sandbox` keys: 1 connect to
|
||||
127.0.0.1:57800, 0 to 57801, 0 hit on the target, `createUser: fetch failed`, 5 tests skipped,
|
||||
rc 1 (fails closed).
|
||||
- Positive run 2, fresh sandbox from the branch, under strace, proxies unset: **5/5**, 4
|
||||
connects all to 127.0.0.1:57800, 0 key in the output, gateway and worker removed, final `down`.
|
||||
DEV `StartedAt` digest identical to the pre-flight.
|
||||
|
||||
## Residual LOW (owner brief §3; kept as is, V1-2 first then port)
|
||||
|
||||
- A proxy would be honoured by Node's fetch only with `NODE_USE_ENV_PROXY=1` (unset here,
|
||||
unset by every proof).
|
||||
- `worker_env` is read by the EXIT trap before `start_worker` assigns it (an inherited value
|
||||
would be `rm -f`'d on an early `die`).
|
||||
- Every docker call follows `DOCKER_HOST` / the current context (both local here).
|
||||
- `SB_SEED_PW` / rotated seed password not ported (develop's sandbox suite signs in with the
|
||||
seed password); the avatar suite itself creates its two accounts with a random password.
|
||||
|
||||
## Hand-off
|
||||
|
||||
- V1-2 session: rebuild `faunosteo_worker:dev` (`pnpm worker:image` in its worktree) and run
|
||||
`pnpm db:sandbox up fresh` before its next sandbox run (the develop secrets file carries no
|
||||
`SB_SEED_PW`; V1-2's `load_secrets` refuses it: fails closed).
|
||||
- Copies that still reach DEV through `pnpm e2e:avatar`: the main checkout
|
||||
`/home/bchanot/Documents/faunosteo` (feature/v1-1-clients-animals, merged) and the worktree
|
||||
`old-958228a`. Agents never run them; their fate is the owner's call.
|
||||
+37
-12
@@ -1,10 +1,28 @@
|
||||
---
|
||||
format: 2
|
||||
type: blockers_registry
|
||||
entry_prefix: BLK
|
||||
schema:
|
||||
id: BLK-XXX
|
||||
date: YYYY-MM-DD
|
||||
friction: string (what was blocked)
|
||||
real_cause: string (root cause, not symptom)
|
||||
solution: string (workaround or fix)
|
||||
status: [open | resolved | upstream]
|
||||
rules:
|
||||
- Open a blocker as soon as friction > 15 min wasted. Close it with a real cause, not "moved on".
|
||||
- Link to upstream issue / PR / commit when applicable.
|
||||
- If cause is a bug in a dependency, set status upstream with a pointer to the tracker.
|
||||
- Entries in English, caveman format (BDR-009): drop articles + filler, fragments OK, technical terms exact.
|
||||
---
|
||||
|
||||
# Blockers Registry
|
||||
|
||||
Format: BLK-XXX | Date | Friction | Root cause | Solution | Status
|
||||
|
||||
---
|
||||
|
||||
## BLK-001 | 2026-05-18 | pnpm not on PATH
|
||||
## BLK-001 — pnpm not on PATH (2026-05-18)
|
||||
|
||||
pnpm command not found on shell start.
|
||||
Root: corepack shim broken on Node 20.20.0 (ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING).
|
||||
@@ -13,7 +31,7 @@ Status: resolved.
|
||||
|
||||
---
|
||||
|
||||
## BLK-002 | 2026-05-18 | Pathology DB empty — pending content review
|
||||
## BLK-002 — Pathology DB empty — pending content review (2026-05-18)
|
||||
|
||||
40-60 equine entries needed; source-cited from Merck Vet Manual, IMAIOS, PubMed, EVJ, WikiVet, LCAO.
|
||||
Client osteo will review post-scaffold.
|
||||
@@ -21,7 +39,7 @@ Status: resolved 2026-05-21 — superseded by hierarchical v2.0 catalog, 26 zone
|
||||
|
||||
---
|
||||
|
||||
## BLK-003 | 2026-05-19 | Detail-popup zone clicks silently dropped
|
||||
## BLK-003 — Detail-popup zone clicks silently dropped (2026-05-19)
|
||||
|
||||
Friction: clicks on head detail SVG zones did nothing.
|
||||
Root: EditorRoute.onZoneClick looked up id in main-SVG bones map only → detail ids (point-*) undefined → early return.
|
||||
@@ -30,7 +48,7 @@ Status: resolved.
|
||||
|
||||
---
|
||||
|
||||
## BLK-004 | 2026-05-19 | PDF text loop assumed one line per array entry
|
||||
## BLK-004 — PDF text loop assumed one line per array entry (2026-05-19)
|
||||
|
||||
Friction: long zone string collided with following lines (pathologies, sévérité, commentaire).
|
||||
Root: pdf-lib maxWidth wraps glyph drawing but caller advanced cursor by `i * 14` based on block index — wrapped lines invisible to layout.
|
||||
@@ -39,7 +57,7 @@ Status: resolved.
|
||||
|
||||
---
|
||||
|
||||
## BLK-005 | 2026-05-21 | Docker build crash — ERR_UNKNOWN_BUILTIN_MODULE node:sqlite
|
||||
## BLK-005 — Docker build crash — ERR_UNKNOWN_BUILTIN_MODULE node:sqlite (2026-05-21)
|
||||
|
||||
Friction: VPS `docker compose up --build -d` crashed on pnpm install (fresh cold build).
|
||||
Root: `node:20-alpine` (Node 20.20.2) cannot load pnpm 11.x — pnpm 11 itself imports `node:sqlite` from `../store/index/lib/index.js`, and `node:sqlite` is a Node 22.13+ built-in. Crash: `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite`. Local dev was deceptive — host runs Node 20 too, but `pnpm install` never ran on host (lockfile already resolved); `pnpm run typecheck` / `pnpm run test` only spawn child scripts and never load the store-index module.
|
||||
@@ -52,7 +70,7 @@ Status: resolved (commit 990c8e7).
|
||||
|
||||
---
|
||||
|
||||
## BLK-006 | 2026-10-08 | Docker socket permission denied → no local Supabase stack for Claude
|
||||
## BLK-006 — Docker socket permission denied → no local Supabase stack for Claude (2026-10-08)
|
||||
|
||||
Friction: `supabase start` → "permission denied … /var/run/docker.sock"; daemon up (`docker info` client OK), user not in `docker` group. No psql/postgres on host either.
|
||||
Root: host group membership; needs `sudo usermod -aG docker $USER` + re-login (user runs, not Claude).
|
||||
@@ -61,7 +79,7 @@ Status: resolved 2026-10-08 (same day) — user added docker group; `supabase st
|
||||
|
||||
---
|
||||
|
||||
## BLK-007 | 2026-10-08 | Per-schema ALTER DEFAULT PRIVILEGES REVOKE is a no-op → private helpers kept PUBLIC EXECUTE
|
||||
## BLK-007 — Per-schema ALTER DEFAULT PRIVILEGES REVOKE is a no-op → private helpers kept PUBLIC EXECUTE (2026-10-08)
|
||||
|
||||
Friction: Step 4 verifier + security gate both found every `private.*` function executable by `authenticated` (incl. definer helpers taking a caller-supplied actor: assign_platform_role, insert_sheet_draft).
|
||||
Root: foundation ran `alter default privileges in schema private revoke execute on functions from public`; PostgreSQL adds per-schema defaults on top of the built-in PUBLIC EXECUTE, a per-schema REVOKE cannot remove it. Nothing reachable via API (PostgREST exposes public only, anon no USAGE on private) but the rule "EXECUTE revoked from public" was false.
|
||||
@@ -70,35 +88,42 @@ Status: resolved (commit on feature/step-04-anatomical-sheet-model).
|
||||
|
||||
---
|
||||
|
||||
## BLK-008 | 2026-10-10 | Schema v2 CHECK migration fails on a database holding a v1 draft
|
||||
## BLK-008 — Schema v2 CHECK migration fails on a database holding a v1 draft (2026-10-10)
|
||||
|
||||
Migration 20261010100000 replaces the CHECK with `document_schema_version = 2` without rewriting rows → errors on any DB seeded before 4c (dev only today). Cause: schema bump shipped as constraint change, not as data migration. Solution: before real data, data migration lifting stored documents (add `references: []`, `review_status` defaults) then CHECK; rule from user: incremental non-destructive migrations, never a reset. Documented ANATOMICAL_SHEET_MODEL.md §6.
|
||||
Status: open (no real data yet; treat before Step 7+ persistence of user reports).
|
||||
|
||||
---
|
||||
|
||||
## BLK-009 | 2026-10-11 | pdf-lib inflates PDF object streams without cap at `PDFDocument.load` (import path)
|
||||
## BLK-009 — pdf-lib inflates PDF object streams without cap at `PDFDocument.load` (import path) (2026-10-11)
|
||||
|
||||
Security audit Step 6 (MEDIUM, pre-existing since Step 1 import): `PDFDocument.load` decodes every `/ObjStm` and xref stream eagerly with its own uncapped FlateStream; measured 408 KB PDF → 400 MB in 1.4 s, 468 MB RSS; `MAX_PDF_BYTES` 50 MiB allows ~50 GB. Attachment cap (16 MiB) covers the attachment only. Impact: tab freeze/OOM for the practitioner on a crafted PDF, no code execution. Cannot refuse `/ObjStm` (pdf-lib `save()` emits object streams in our own PDFs). Options: parse in a Web Worker (bounded blast radius), or locate the attachment by scanning bytes without a full load, or a capped custom decoder. pdf-lib 1.17.1 unmaintained since 2021 (LOW in the same audit).
|
||||
Status: MITIGATED on the browser import path 2026-10-11 (60ee712: byte-scan attachment reader, no `PDFDocument.load` on untrusted bytes, export without object streams; ObjStm bomb read in 5 ms, +0.5 MiB RSS). Then 3a6e926: inflater fed in 16 KiB slices (Chromium read-ahead defeated the cancel: 4 GiB bomb +2.2 GB → +192 MB measured), shared 16 MiB candidate budget, bounded endstream search; final loop: candidates sorted by offset, JSON depth pre-scan. Audits ×3 PASS; worst measured costs on crafted files: +192 MB single bomb, ~0.5 s / ≤0.4 GB for 32 failing inflations, ~1 s deep JSON (before the pre-scan). GATE STILL OPEN before any external-user import (BDR-040): Firefox/Safari inflater read-ahead unmeasured (no browser test runner), Worker/server import with time+memory budget, pdf-lib replacement decision (unmaintained), report collection caps on read, `<use>` nesting budget, low-end phone measurement. Plan: docs/development/PDF_IMPORT_HARDENING.md §5. Never close on passing tests alone.
|
||||
|
||||
## BLK-010 | 2026-10-14 | Agent worktrees created on a stale base; their cleanup refused by the classifier
|
||||
## BLK-010 — Agent worktrees created on a stale base; their cleanup refused by the classifier (2026-10-14)
|
||||
|
||||
Friction: the three `isolation: worktree` forks of R2 started at 605ee7c (an old develop merge), not at the feature branch HEAD 22fea87; each fork noticed and moved its own temp branch (`git reset --hard` / `checkout -B` on the empty worktree, flagged by the classifier as a security warning). After merging their diffs by hand, `git worktree remove --force` + `git branch -d worktree-agent-*` refused by the auto-mode classifier.
|
||||
Root cause: harness side (base commit of the agent worktree), not reproducible from the repo; the removal refusal is the destructive-command policy.
|
||||
Solution: forks briefed with the exact base commit and told to verify `git log -1`; diffs collected uncommitted and copied by literal paths. Leftover: `.claude/worktrees/agent-{a0cefd439bff650a2,a3f684449d0776ad1,af6ebe79b8f742039}` (3.2 GB) + 3 local temp branches at 22fea87 (merged), owner removes them (`git worktree remove --force <path>`, `git branch -d <branch>`).
|
||||
Status: resolved 2026-10-14 — after R2 merged into develop (c3f28d8): 66 files checked blob by blob (60 identical to branch history, 6 = fork stub / merged mod lists / lifted `#[ignore]`), no process or agent on them, tip 22fea87 in develop → `git worktree remove --force` ×3 + `gitflow.sh delete` ×3 accepted this time. Harness base-commit cause stays upstream.
|
||||
|
||||
## BLK-011 | 2026-10-16 | Stopped-engine message promised "bilan conservé" with draft unsaved; dead "Réessayer" paths
|
||||
## BLK-011 — Stopped-engine message promised "bilan conservé" with draft unsaved; dead "Réessayer" paths (2026-10-16)
|
||||
|
||||
Friction: 0279953 picked `core.stopped` from `CoreRuntime.stopped` alone: with sessionStorage full, reload restored older draft, edits lost silently; save banner advised PDF export (needs core). CoreUnavailable, export, import, new report still offered retry after stop; failed recovery below cap = dead end (nothing called `retry()` in editor; canvas button only rebuilt).
|
||||
Root cause: terminal-state message not bound to persistence status (`saveFailed` existed, unread); retry labels audited only on the 8 alerts + canvas the patch touched, not every failure surface; runtime exit from `unavailable` only via explicit `retry()` called by useSheet alone.
|
||||
Solution: 6371523 (BDR-055): `isUnsaved` selector drives variant + copy; CoreStoppedNotice on all core pages; runtime self-restart below cap; FAILED not held; ESLint census. Verifier CONFORME 12/12 (pass 2), security PASS 2 LOW.
|
||||
Status: resolved 2026-10-16. Residuals: saveFailed also on refused archive (over-warns); offline restart never stops (copy on banner); beforeunload only in editor; trap-every-load draft → reload loop; GC finalizer of trapped-instance SheetHandle throws "memory access out of bounds" later (harmless, tests retain handles).
|
||||
|
||||
## BLK-012 | 2026-10-17 | Rescue copy not restorable; trapping draft stuck tab; work loss outside editor
|
||||
## BLK-012 — Rescue copy not restorable; trapping draft stuck tab; work loss outside editor (2026-10-17)
|
||||
|
||||
Friction: JSON copy (6371523) had no in-app restore (Home picker PDF only; devtools only). Draft trapping `draft.restore` → CoreUnavailable reload each load, New report/Import FAILED, every re-read spent a recovery. beforeunload only in editor; New report / Import replaced bilan in progress (memory or slot) silently.
|
||||
Root cause: copy shipped without restore path (round trip never tested in app); `internal` from draft read treated as transient core failure, no memory of trapping input; guard scoped to one route; session replacement unguarded since MVP.
|
||||
Solution: 9bd9aca (BDR-056). Evidence: round trip identical (3 golden reports, slot + import); fuzz 37k draft.restore 0 traps, OOM only ~50 MB drafts (5 MB worst = 0.4-0.8 GB wasm). Verifier CONFORME 10/10, security PASS 2 LOW, check:all green.
|
||||
Status: resolved 2026-10-17. Residuals: GC finalizer throws "memory access out of bounds" after stack-overflow trap (console only, live instance unaffected 50/50), ≤ 3 dead instances retained (~13.5 MB typical, ~4.5 MB each) until reload; raw lone surrogate in archive text quarantines readable draft (unreachable, session.rs); copy lacks archive envelope; iOS Safari likely ignores beforeunload (dialog + copy are protection there); Retry clicked during ms-long recovery → reload screen; re-importing copy of trapping draft re-traps (spends recovery); copy near 16 MiB may OOM low-memory device; storage full + confirmed replace + reload restores replaced draft; `internal` may come from handle rebuild (Retry reopens).
|
||||
|
||||
## BLK-013 — e2e:avatar on develop reached DEV (keys via supabase status, worker on DEV net, purge queue drained) (2026-11-02)
|
||||
- **Status**: resolved
|
||||
Friction: develop `pnpm e2e:avatar` = scripts/avatar-e2e.sh could reach DEV: keys via `supabase status -o env`, worker on supabase_network_faunosteo against DEV Kong, suite wrote accounts + drained whole purge queue (`expeditePurges` unscoped), psql on supabase_db_faunosteo. Same family as sheet-assets incidents 2026-11-01.
|
||||
Real cause: runner and suite knew no authorised target; URL, keys, container from env or DEV defaults.
|
||||
Solution: 3a4614b ports V1-2 sandbox runner (`db-sandbox.sh avatar-e2e`: loopback gateway 127.0.0.1:57800, worker in 600 env file, constants unconditional) + guarded suite (fixed URL, container, key issuer `db-sandbox`, per-run accounts); DEV runner deleted. d3dfd03: clients refuse redirects (`noRedirectFetch`, `redirect: 'error'`). Proofs a-j strace, 2 × 5/5, log `.claude/audits/2026-11-02-avatar-e2e-sandbox-only.md`.
|
||||
Status: resolved for develop path after merge. NOT fixed in old checkouts: main checkout /home/bchanot/Documents/faunosteo (feature/v1-1-clients-animals) and worktree old-958228a still hold scripts/avatar-e2e.sh + old alias; `pnpm e2e:avatar` there targets DEV. Agents never run them; owner decides their fate.
|
||||
+101
-81
@@ -1,10 +1,30 @@
|
||||
---
|
||||
format: 2
|
||||
type: decisions_registry
|
||||
entry_prefix: BDR
|
||||
schema:
|
||||
id: BDR-XXX
|
||||
date: YYYY-MM-DD
|
||||
title: string (<= 80 chars)
|
||||
decision: string (what was chosen)
|
||||
why: string (motivation, context)
|
||||
alternatives: list of strings (what was rejected + why)
|
||||
status: [proposed | accepted | deprecated | superseded]
|
||||
supersedes: BDR-XXX (optional)
|
||||
rules:
|
||||
- Append-only. Never rewrite past entries - add a new one with status superseded if needed.
|
||||
- One entry per non-trivial choice. Trivial = reversible in under 10 min with no cross-file impact.
|
||||
- Capture why more carefully than what - the what rots, the why lasts.
|
||||
- Entries in English, caveman format (BDR-009): drop articles + filler, fragments OK, technical terms exact.
|
||||
---
|
||||
|
||||
# Decisions Registry
|
||||
|
||||
Format: BDR-XXX | Date | Title | Rationale | Alternatives | Status
|
||||
|
||||
---
|
||||
|
||||
## BDR-001 | 2026-05-18 | React SPA exception for tool app
|
||||
## BDR-001 — React SPA exception for tool app (2026-05-18)
|
||||
|
||||
Tool is practitioner-only, no public indexing needed → SPA valid per CLAUDE.md rule.
|
||||
Alt: Next.js SSR rejected — no server, static deploy only.
|
||||
@@ -12,7 +32,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-002 | 2026-05-18 | SVG inline via DOMParser, not img/object
|
||||
## BDR-002 — SVG inline via DOMParser, not img/object (2026-05-18)
|
||||
|
||||
Inline SVG = full CSS control, pointer-events, data-* access.
|
||||
img/object = sandboxed, no DOM access, no click delegation.
|
||||
@@ -20,7 +40,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-003 | 2026-05-18 | PDF attachment via native pdf-lib attach()
|
||||
## BDR-003 — PDF attachment via native pdf-lib attach() (2026-05-18)
|
||||
|
||||
Native EmbeddedFiles (afRelationship:Data) = proper PDF spec, survives re-save in Acrobat.
|
||||
Alt: custom metadata → rejected (non-standard, stripped by some viewers).
|
||||
@@ -28,7 +48,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-004 | 2026-05-18 | Runtime identity via window.__APP_CONFIG__
|
||||
## BDR-004 — Runtime identity via window.__APP_CONFIG__ (2026-05-18)
|
||||
|
||||
Build-time VITE_APP_* → baked into bundle; runtime injection via entrypoint.sh → no rebuild needed for brand changes.
|
||||
Order: runtime > build-time > defaults.
|
||||
@@ -36,7 +56,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-005 | 2026-05-18 | Vertebra picker: region tabs + chip grid
|
||||
## BDR-005 — Vertebra picker: region tabs + chip grid (2026-05-18)
|
||||
|
||||
≥40px touch targets, multi-select, per-region toggle.
|
||||
Alt: flat list → too long for 54 total vertebrae.
|
||||
@@ -44,14 +64,14 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-006 | 2026-05-18 | Drag-reorder: up/down buttons, not DnD
|
||||
## BDR-006 — Drag-reorder: up/down buttons, not DnD (2026-05-18)
|
||||
|
||||
DnD on mobile unreliable; ↑/↓ buttons accessible + simple.
|
||||
Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-007 | 2026-05-18 | pnpm 11 used instead of pnpm 9
|
||||
## BDR-007 — pnpm 11 used instead of pnpm 9 (2026-05-18)
|
||||
|
||||
pnpm@9 not available on host; corepack resolved 11.1.3.
|
||||
Package.json engine constraint set to >=9 for Docker (Docker uses corepack latest).
|
||||
@@ -59,7 +79,7 @@ Status: closed — deviation accepted.
|
||||
|
||||
---
|
||||
|
||||
## BDR-008 | 2026-05-19 | PDF page layout — branded heading pattern
|
||||
## BDR-008 — PDF page layout — branded heading pattern (2026-05-19)
|
||||
|
||||
Each PDF page leads with bold-uppercase accent eyebrow (size 9), Times 22 title, 2pt × 48pt accent rule under title. Section labels follow same eyebrow style (uppercase bold accent) above their values. Observation severity rendered as filled color-coded pill (sage / amber / red) next to the obs number.
|
||||
Alts: plain text titles only — rejected (overlapped header rule + read unstyled).
|
||||
@@ -67,7 +87,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-009 | 2026-05-20 | Findings JSON keeps snake_case in TS, observation snapshot uses camelCase
|
||||
## BDR-009 — Findings JSON keeps snake_case in TS, observation snapshot uses camelCase (2026-05-20)
|
||||
|
||||
JSON catalog fields (name_fr/name_en/description_fr/requires_vet_referral/...) stay snake_case in TS types/Zod schema — no transform layer. Domain-expert authored, reads natural in JSON, zero remap cost. Observation Finding snapshot uses camelCase (labelFrSnapshot/labelEnSnapshot/requiresVetReferral) per app convention.
|
||||
Alt: Zod transform to camelCase everywhere — rejected (extra layer, hides JSON shape, no real upside for a static catalog).
|
||||
@@ -75,7 +95,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-010 | 2026-05-20 | Observation findings snapshot labels at selection time
|
||||
## BDR-010 — Observation findings snapshot labels at selection time (2026-05-20)
|
||||
|
||||
Finding stores labelFrSnapshot + labelEnSnapshot copied from leaf at click time. Exported reports remain readable years later even if catalog renames/restructures leaves. Path[] still carried for future re-link/migration.
|
||||
Alt: lookup labels on render via path — rejected (breaks already-exported PDFs if catalog edits).
|
||||
@@ -83,7 +103,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-011 | 2026-05-20 | v1 PDF import — hard-fail with version-specific FR message
|
||||
## BDR-011 — v1 PDF import — hard-fail with version-specific FR message (2026-05-20)
|
||||
|
||||
importReportFromPdf detects `data.version !== 2` BEFORE strict Zod parse, throws IncompatibleReportVersionError, wrapped into ImportError with explicit "v{n}, incompatible avec v2, réexportez..." message. No retro-compat shim (no prod PDFs in the wild).
|
||||
Alt: silent generic ImportError — rejected (user can't tell why import failed).
|
||||
@@ -92,7 +112,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-012 | 2026-05-20 | Species auto-discovery via Vite import.meta.glob
|
||||
## BDR-012 — Species auto-discovery via Vite import.meta.glob (2026-05-20)
|
||||
|
||||
`src/domain/species/registry.ts` uses `import.meta.glob('./*/index.ts', { eager: true })` and registers every module that default-exports a SpeciesManifest. Drop-folder onboarding: scaffold writes index.ts with `export default <id>`, no registry edit needed. Duplicate id → warn + first wins. Missing default export → silently skipped.
|
||||
Alt rejected: hardcoded SPECIES_REGISTRY map — forced edits in two places, broke "single source of truth" per species folder.
|
||||
@@ -101,7 +121,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-013 | 2026-05-20 | SVG↔JSON zone bridge via fuzzy FR/EN label match
|
||||
## BDR-013 — SVG↔JSON zone bridge via fuzzy FR/EN label match (2026-05-20)
|
||||
|
||||
SVG data-anno-id values stay opaque generator strings (point-mpb..., zone-...). JSON catalog keys are stable human zone names (sphenoid, atm). Bridge runs at observation render: matchZoneFindings normalizes both sides (lowercase + NFD-strip accents + alphanum-only) and scores EN-exact → FR-exact → substring → Levenshtein within max(2, floor(maxLen*0.25)) tolerance. EN first because no accent normalization edge cases.
|
||||
Alt rejected: rename SVG data-anno-id to JSON keys — couples opaque SVG generator output to human-meaningful catalog, brittle across SVG re-exports.
|
||||
@@ -110,7 +130,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-014 | 2026-05-20 | PDF locale = render preference, not Report schema field
|
||||
## BDR-014 — PDF locale = render preference, not Report schema field (2026-05-20)
|
||||
|
||||
exportReportToPdf takes explicit `{ locale }` option read from localeStore at call site. Locale lives outside Report — never persisted in schema. Rationale: Finding snapshots already carry labelFrSnapshot+labelEnSnapshot (per BDR-010), so render-time locale picks the correct snapshot; no schema bump needed; re-imported PDF can be re-exported in either locale without data migration; embedded JSON byte-identical between locale variants of the same Report.
|
||||
Alt rejected: store `locale` field on Report schema — would force v3 bump, complicate re-export ergonomics, duplicate state already in store.
|
||||
@@ -119,7 +139,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-015 | 2026-05-20 | Typed ImportError discriminant (kind + foundVersion) over localized messages
|
||||
## BDR-015 — Typed ImportError discriminant (kind + foundVersion) over localized messages (2026-05-20)
|
||||
|
||||
ImportError carries `kind: 'invalid_pdf' | 'incompatible_version' | 'no_attachment'` + optional `foundVersion`. Message field collapses to internal sentinel. UI layer (HomeRoute) resolves user-facing string via i18n dict using err.kind, with `{version}` template substitution. Rationale: review caught hardcoded FR in pdf/import.ts + pdf/attachment.ts leaking to EN UI; original "throw with localized message" coupled domain layer to one locale; typed discriminant moves message authoring to the UI layer where i18n lives.
|
||||
Alt rejected: keep FR messages, translate via err.message string match — brittle (any rewording breaks the lookup), spreads i18n knowledge into the catch site.
|
||||
@@ -128,7 +148,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-016 | 2026-05-21 | pathologies.json v2.0 — boolean source of truth, generic vet description_fr purged
|
||||
## BDR-016 — pathologies.json v2.0 — boolean source of truth, generic vet description_fr purged (2026-05-21)
|
||||
|
||||
Catalog bumped v1.2→v2.0. `requires_vet_referral: true` boolean = sole source of truth for vet flag. Generic "orienter vers vétérinaire" descriptions purged on 25 leaves where boolean alone sufficed. `description_fr` kept on 16 leaves carrying differential cue (cause neuro/sinusale/ligamentaire/rotulienne/etc.). Horse coverage extended placeholder 3 zones → full 26 zones (9 head + 17 body), 792 nodes, 612 leaves, 41 vet-referral leaves. Schema_version "2.0".
|
||||
**Why:** v1.2 had textual fallback (`description_fr.includes('vétérinaire')`) + boolean coexisting → redundant + ambiguous. v2.0 collapses to one signal.
|
||||
@@ -138,7 +158,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-017 | 2026-05-22 | SVG editor: vanilla JS wrap over React rewrite
|
||||
## BDR-017 — SVG editor: vanilla JS wrap over React rewrite (2026-05-22)
|
||||
|
||||
editor.html = ~1630-line standalone SVG annotation tool (DOM manipulation, drag/drop, polygon editing, zoom, categories, export). Integrated into React app via `useRef` + `useEffect` mounting all vanilla JS logic into container refs. Only CSS restyled to Faunosteo tokens.
|
||||
Alt rejected: full React rewrite (convert all state to Zustand/useState, all DOM ops to React) — massive effort ~10x, high risk of subtle behavior differences in drag/polygon/zoom interactions.
|
||||
@@ -146,7 +166,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-020 | 2026-05-22 | Pathology editor: standalone HTML, not React route
|
||||
## BDR-020 — Pathology editor: standalone HTML, not React route (2026-05-22)
|
||||
|
||||
pathology-editor.html = standalone tool at project root, same pattern as SVG editor integration. Vanilla JS/CSS, no build step, no deps. Decoupled from React app entirely — zero imports from src/.
|
||||
**Why:** tool for domain experts editing JSON, not practitioners using main app. No shared state needed. Standalone = deployable anywhere, no Vite required.
|
||||
@@ -155,7 +175,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-021 | 2026-05-22 | Port zoneMatch.ts inline into pathology editor
|
||||
## BDR-021 — Port zoneMatch.ts inline into pathology editor (2026-05-22)
|
||||
|
||||
Fuzzy matching logic (normalizeLabel, levenshtein, scorePair, matchZone) duplicated inline in pathology-editor.html rather than imported from src/lib/zoneMatch.ts.
|
||||
**Why:** standalone HTML cannot import TS modules. Keeping identical algorithm ensures matching consistency between main app and editor.
|
||||
@@ -164,7 +184,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-018 | 2026-05-27 | Vertebra picker confirm — target region replaces, other regions union
|
||||
## BDR-018 — Vertebra picker confirm — target region replaces, other regions union (2026-05-27)
|
||||
|
||||
VertebraPicker anchored on clicked spine zone but lets user switch region tabs. On confirm, `distributeVertebraeToZones` spreads picks across one spine zone per region. Target region (clicked zone) = REPLACE (picker seeded with its full set → unchecking deselects). Other regions = UNION with any pre-existing zone (picker didn't display them → side-tab pick must be purely additive, never wipe). Region with no SVG spine zone → fold verts back onto target (nothing lost).
|
||||
**Why:** picking verts in a non-target tab must behave as if that zone was also clicked — highlight + findings picker both flow from observation.zones. Replace-everywhere would silently wipe a cervical zone selected earlier when reopening lumbar picker.
|
||||
@@ -174,7 +194,7 @@ Status: SUPERSEDED by BDR-019 (same session) — additive-union model dropped on
|
||||
|
||||
---
|
||||
|
||||
## BDR-019 | 2026-05-27 | Vertebra picker = unified full-spine editor, authoritative confirm
|
||||
## BDR-019 — Vertebra picker = unified full-spine editor, authoritative confirm (2026-05-27)
|
||||
|
||||
User asked picker to SHOW selections from all regions when switching tabs. Once it displays + edits every region, additive-union confirm (BDR-018) breaks: unchecking a side-tab vert can't stick (union re-adds from existing zone). So model flipped to unified + authoritative.
|
||||
Seed: `collectSpineVertebrae(zones, bones, clickedBoneId)` = union of all spine-zone verts, clicked zone first.
|
||||
@@ -188,7 +208,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-022 | 2026-06-13 | Keep pathology-editor standalone — asymmetry vs svg-editor intentional
|
||||
## BDR-022 — Keep pathology-editor standalone — asymmetry vs svg-editor intentional (2026-06-13)
|
||||
|
||||
After 404 fix (moved pathology-editor.html root→public/, LRN-029), considered unifying it with svg-editor pattern (React route, vanilla wrapped in useEffect, BDR-017). Rejected. Two editors differ by COUPLING, not accident:
|
||||
- svg-editor REUSES app internals (getAllSpecies registry, useLocaleStore+getDict, AppHeader) → React route earns its keep (BDR-017).
|
||||
@@ -200,7 +220,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-023 | 2026-10-08 | Monorepo: apps/app + pnpm workspace, packages extracted on demand only
|
||||
## BDR-023 — Monorepo: apps/app + pnpm workspace, packages extracted on demand only (2026-10-08)
|
||||
|
||||
App moved to `apps/app` (`@faunosteo/app`, git mv, 144 pure renames). Root package.json delegates (`pnpm -r`). `packages/` = README only; a package is created when it has a clear owner + real code (plan Steps 3/4/6). `apps/public-web`, `apps/worker`, `supabase/` created by the step needing them.
|
||||
**Why:** root one-word commands, Docker filtered build, lockfile v9 already workspace-capable; moving later (after packages + 2nd app) costs more. Empty packages = config to maintain for nothing.
|
||||
@@ -209,7 +229,7 @@ Status: closed (user validated 2026-10-08).
|
||||
|
||||
---
|
||||
|
||||
## BDR-024 | 2026-10-08 | Node 24 LTS + pnpm 10.13.1 pinned, engine-strict
|
||||
## BDR-024 — Node 24 LTS + pnpm 10.13.1 pinned, engine-strict (2026-10-08)
|
||||
|
||||
Node 24 (`.nvmrc`, `.node-version`, `engines >=22.12 <25`, Dockerfile node:24-alpine, CI). pnpm 10.13.1 via `packageManager` + root devDependency (scripts find node_modules/.bin/pnpm under corepack or any install) + `engines <11`. `.npmrc engine-strict=true`.
|
||||
**Why:** Node 20 EOL 2026-04-30; dev host on 24; all checks ran on 24. pnpm 11 needs Node ≥22.13 and rewrites lockfile; 10.13.1 = Dockerfile-validated pin (BLK-005). Lockfile rewritten by 10.13.1 (libc fields from earlier pnpm 11 dropped) → coherent with pin.
|
||||
@@ -219,7 +239,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-025 | 2026-10-08 | Design records live in docs/history/superpowers, not docs/superpowers
|
||||
## BDR-025 — Design records live in docs/history/superpowers, not docs/superpowers (2026-10-08)
|
||||
|
||||
gitflow lib purges `docs/superpowers/{specs,plans}` at every `finish` (BDR-065, fixed path list). Step 1 finish deleted 9 design docs (8f217d8). Restored from history under `docs/history/superpowers/` (not purged); refs updated (CLAUDE.md, migration map, plan). Audit docs keep old path (frozen).
|
||||
Alt rejected: revert in place → purged again next finish; editing the lib list → global change for one repo.
|
||||
@@ -227,7 +247,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-026 | 2026-10-08 | platform_role enum = owner/admin/moderator/support only; professional statuses excluded
|
||||
## BDR-026 — platform_role enum = owner/admin/moderator/support only; professional statuses excluded (2026-10-08)
|
||||
|
||||
Business arch §4.1 lumps 7 values in `profile_roles.role` (practitioner/student/professor + 4 platform). User rule: never confuse platform roles with professional statuses. Table name kept `profile_roles` (plan + helper names unchanged), enum `platform_role` 4 values. practitioner/student/professor → verification outcome (identity step); cabinet roles → organization_members. Hierarchy for checks: owner ⊇ admin ⊇ moderator; support separate (§17.3). Deactivated profile (`active=false`) → all helpers false.
|
||||
Alt rejected: 7-value enum per arch doc → self-declared "practitioner" row readable as verified status.
|
||||
@@ -235,7 +255,7 @@ Status: closed (user instruction), name `profile_roles` open to rename if user p
|
||||
|
||||
---
|
||||
|
||||
## BDR-027 | 2026-10-08 | Role writes RPC-only + audited; column-level GRANT protects profiles.active / phone_verified_at
|
||||
## BDR-027 — Role writes RPC-only + audited; column-level GRANT protects profiles.active / phone_verified_at (2026-10-08)
|
||||
|
||||
No INSERT/UPDATE/DELETE policy on `profile_roles`; only `grant_platform_role` / `revoke_platform_role` (security definer, actor = auth.uid(), self-target refused, owner any role / admin moderator+support) → `private.assign/withdraw_platform_role` → `private.log_event`. Bootstrap first owner: `assign_platform_role(null, uid, 'owner')` from privileged SQL. Last active owner cannot be revoked. `profiles`: `grant update (display_name, first_name, last_name, phone, locale, timezone)` instead of a protect-columns trigger → `active`, `phone_verified_at` raise 42501 for API role, server functions untouched.
|
||||
Alt rejected: BEFORE UPDATE trigger checking auth.uid() → blocks future server RPC acting for the caller; column grants declarative, visible in `has_column_privilege`.
|
||||
@@ -243,7 +263,7 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-028 | 2026-10-08 | pgTAP single source of SQL tests; PGlite runner in vitest beside `supabase test db`
|
||||
## BDR-028 — pgTAP single source of SQL tests; PGlite runner in vitest beside `supabase test db` (2026-10-08)
|
||||
|
||||
Docker socket denied to user on dev host (BLK-006). PGlite 0.3.16 (PG17 WASM) ships pgtap extension → `packages/supabase/tests/db/` applies `supabase-shim.sql` (API roles, auth.users, auth.uid(), Supabase default privileges) + migrations, runs every `supabase/tests/*.sql`, fails on `not ok` / plan mismatch. Same files run by `supabase test db` on real stack (CI supabase job). Shim replicates permissive default privileges so a missing `revoke` fails.
|
||||
Alt rejected: TS-only RLS tests (duplicate harness, drift); waiting for Docker (no executed proof).
|
||||
@@ -251,14 +271,14 @@ Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-029 | 2026-10-08 | database.types.ts hand-written in `supabase gen types` format + schema↔types test
|
||||
## BDR-029 — database.types.ts hand-written in `supabase gen types` format + schema↔types test (2026-10-08)
|
||||
|
||||
CLI gen needs running stack. File written in generator format (Row/Insert/Update/Relationships/Functions/Enums/Constants). `schema-types.test.ts`: compile-time exhaustiveness (every Row column listed, every Args key listed) + runtime diff vs information_schema / pg_enum / pg_proc in PGlite; also pins RLS-on + no `using(true)` for every future public table. CI `db:types:check` diffs against real generator once Docker available; first real run may reformat (PostgrestVersion string) → regenerate + commit.
|
||||
Status: closed; column scalar types (uuid→string…) reviewed by hand, not executed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-030 | 2026-10-08 | Step 4 split: model + persistence now, importer → official equine DRAFT next
|
||||
## BDR-030 — Step 4 split: model + persistence now, importer → official equine DRAFT next (2026-10-08)
|
||||
|
||||
User brief: no full equine import yet; first official horse sheet = draft, business content verified before publication. Plan Step 4 bundled model + importer. Split: Step 4 = packages/domain document + validation + migration + pgTAP + docs; Step 4b = legacy importer → draft + IMPORT-REPORT, publish on user go. packages/anatomy created at 4b.
|
||||
Alt rejected: importer in same step → publishes seed v1 immutable before expert review (contradicts brief).
|
||||
@@ -266,7 +286,7 @@ Status: closed (plan note added under Step 4).
|
||||
|
||||
---
|
||||
|
||||
## BDR-031 | 2026-10-08 | Canonical sheet document shape (schema_version 1)
|
||||
## BDR-031 — Canonical sheet document shape (schema_version 1) (2026-10-08)
|
||||
|
||||
Labels `{ fr, en }` objects (one LocalizedText, new locale = optional key) instead of name_fr/name_en pairs. Strict Zod objects (unknown key rejected). Structural records explicit `null`; finding tree nodes lean on input, `.default()` fills description/sources/children/requires_vet_referral (612 leaves). Views = tree (`parent_view_id`), detail `svg_asset_id` nullable = crop parent via `view_box` (C9). Annotation discriminated union point|zone|detail_trigger; `laterality` 4 values explicit (unpaired/bilateral/left/right); spine = `vertebral_region_code` → ordered `vertebral_config.regions` with free codes (C1/Q3); findings link = inline `finding_zone_id` (no separate map, no label matching); finding categories carry `kind` dysfunction|observation|anamnesis|custom; node ids unique among siblings so `(zone, path[])` addressing survives Step 5. Two tiers: shape (Zod, every save) vs integrity (`validateSheetDocument`, 17 coded rules, publish gate).
|
||||
Alt rejected: name_fr/name_en flat (BDR-009 catalog style) → no locale extension; annotation_finding_map array → extra structure for a 1:N field; UUIDs as in-document ids → unreadable, legacy paths re-keyed.
|
||||
@@ -274,7 +294,7 @@ Status: closed; category kind `observation` vs report Observation collision (C7)
|
||||
|
||||
---
|
||||
|
||||
## BDR-032 | 2026-10-08 | Sheet persistence: trigger-enforced immutability, SQL publish re-check, content-addressed assets
|
||||
## BDR-032 — Sheet persistence: trigger-enforced immutability, SQL publish re-check, content-addressed assets (2026-10-08)
|
||||
|
||||
Tables species / anatomical_sheets / _versions / _assets. Published immutable via BEFORE UPDATE trigger (every role incl. owner; only published→deprecated with stamps); deprecated frozen; BEFORE DELETE trigger = preconditions (never published, never current, never base of active fork; reports join later) → no session flags, RPC just deletes. One draft per sheet (partial unique index, C8). Document↔row: CHECK `content->'schema_version' = to_jsonb(document_schema_version)`, trigger species match. `private.sheet_document_issues(jsonb)` re-checks the non-recursive error rules at publish + unknown asset ids → defense in depth, same codes as TS (BACKEND_ARCH "SQL doesn't re-implement Zod" kept for shape). Assets content-addressed (sha256, unique per sheet), Storage path `<sha256>.svg` by convention, fork = metadata copy + `remap_document_assets`. Draft autosave = column-level UPDATE (content, change_note) policy on own draft (unaudited by design); identity (name/slug/description) column policy; visibility via audited `set_sheet_visibility` RPC and draft deletion via `delete_sheet_version` after gate review (sharing + deletion = sensitive state); `last_version_number` counter (no number reuse); content ≤ 2 MiB, byte_size ≤ 20 MiB, reason ≤ 500; `require_actor` refuses deactivated profiles; authz before lookup (unknown id = same 42501); fork copies only referenced assets. can_use_sheet = active ∧ (public ∨ editor) until grants/follows. Official sheet = creator null + is_official, platform admins edit.
|
||||
Alt rejected: session-flag delete bypass (hacky); Zod-equivalent validation only in TS (browser not a boundary); per-sheet asset storage copy on fork (needs worker job).
|
||||
@@ -282,7 +302,7 @@ Status: closed; names (`anatomical_sheet_assets`, storage layout, official owner
|
||||
|
||||
---
|
||||
|
||||
## BDR-033 | 2026-10-09 | User decisions on the Step 4 open points (sheets: follow, verification, versions, official, naming, server validation, erasure)
|
||||
## BDR-033 — User decisions on the Step 4 open points (sheets: follow, verification, versions, official, naming, server validation, erasure) (2026-10-09)
|
||||
|
||||
User validated Step 4 and ruled: (1) public read by visibility, USE of a community sheet requires following its author, official sheets exempt → `can_use_sheet` + follow at community step; (2) private drafts for anyone, community publication only for authorised + verified accounts, student/professor keep own rules → gate in publish/set_visibility at verification step; (3) new publication = current, no auto-deprecation (current behaviour); (4) official sheets platform-owned, admin-run (current model); (5) finding kind `observation` → `consultation_reason` (done, packages/domain); (6) server-side validation mandatory for publication, frontend never a boundary → Zod shape check server-side before community step; (7) account deletion handles dependencies/transfer explicitly, nothing may block erasure forever → retention step anonymises authorship via a system path.
|
||||
Scope guard from user: implement along the planned steps, keep 4b (equine import) free of community/account features.
|
||||
@@ -291,7 +311,7 @@ Status: closed (recorded in ANATOMICAL_SHEET_MODEL.md §5).
|
||||
|
||||
---
|
||||
|
||||
## BDR-034 | 2026-10-09 | Equine import = generated seed, draft only; assets content-addressed in a private bucket read through the sheet
|
||||
## BDR-034 — Equine import = generated seed, draft only; assets content-addressed in a private bucket read through the sheet (2026-10-09)
|
||||
|
||||
Importer (packages/anatomy, one-off, deterministic) emits supabase/seed/anatomical-sheets/equine/v1: document.json, legacy-id-map.json, assets.json + SVG copies, IMPORT-REPORT.md (FR, for the osteopath), equine_v1.sql (idempotent: official platform-owned sheet `faunosteo-cheval` private + 2 asset rows + draft v1 via `private.insert_sheet_draft(null,…)`). Golden test = committed artifacts equal a fresh run. Ids: annotation = catalog zone key on exact FR+EN match (26/26), views main/head, trigger head-trigger, asset/sheet uuids derived from sha256 (uuid v5-like). No medical correction: ssb-dysfunctions kept + anomaly; only degraded slugs normalised and declared; 12 anomalies to validate, 6 informative. Seed listed in config sql_paths (every env) and applied by the PGlite harness (`seed/**`, never seed.sql). Storage: bucket anatomical-sheet-assets private, `<sha256>.svg`, SELECT policy via `private.can_read_sheet_asset_object` (published reference of usable sheet, or editor), no API writes, operator upload script with service key from env.
|
||||
Alt rejected: data migration for the sheet (immutable file for a draft meant to be edited); TS seeding via PostgREST (needs service key in a committed path); fuzzy zoneMatch at import (26/26 exact, strict equality + report suffices).
|
||||
@@ -299,7 +319,7 @@ Status: closed; publication of v1 = explicit user decision after report review.
|
||||
|
||||
---
|
||||
|
||||
## BDR-035 | 2026-10-09 | Docker resources prefixed `faunosteo_` (multi-SaaS VPS)
|
||||
## BDR-035 — Docker resources prefixed `faunosteo_` (multi-SaaS VPS) (2026-10-09)
|
||||
|
||||
User rule: every Faunosteo Docker resource (container, network, volume, image, future worker/self-hosted Supabase) named `faunosteo_*` when configurable → cohabitation on one VPS without collision. Applied: compose `name: faunosteo` + `container_name: faunosteo_app` (was `faunosteo-web`, stateless, no volume → rename safe). Supabase CLI hard-codes `supabase_<svc>_<project_id>` → suffix `faunosteo`, documented limit, no wrapper. Rule for future persistent volumes: keep volume name across renames.
|
||||
Alt rejected: wrapping `supabase start` to rename containers (fragile, breaks CLI status/stop).
|
||||
@@ -307,7 +327,7 @@ Status: closed (DEPLOY.md "Docker resource naming", SUPABASE.md §3, CLAUDE.md).
|
||||
|
||||
---
|
||||
|
||||
## BDR-036 | 2026-10-10 | Sheet document schema v2 + curation changeset as data (Step 4c)
|
||||
## BDR-036 — Sheet document schema v2 + curation changeset as data (Step 4c) (2026-10-10)
|
||||
|
||||
Schema v2: document `references` registry (id, type, citation, url|doi), `reference_ids` + `review_status` (inherited|reviewed|to_confirm) on finding nodes/categories/annotations, `count_range` on vertebral regions; rules `reference.id.duplicate`, `finding.reference.missing`, `region.count_range.invalid` on TS + SQL (jsonpath `**` descent); CHECK `document_schema_version = 2`. Curation = authored JSON changeset (`curation/changes.json`: CHG-nnn, level A|B|C, kind, FR/EN title, rationale, reference_ids, priority, question required for C; ops set/rename/add/remove/move/cite over string targets) applied by a deterministic pipeline to the 4b baseline → `draft/` (document, one cleaned SVG, head view = view_box crop, CHANGELOG with before/after per elementary edit, 10-section REVIEW-REPORT, `review/annotations-<view>.svg` before/after drawings, converging seed). Legacy baseline kept generated under `legacy-import/`, `v1/` removed. Nothing publishes.
|
||||
Alt rejected: editing `document.json` by hand (no traceability, golden test); TS code per change (reviewers read data, not code); per-node inline sources (792 copies → registry + ids); PNG renders in git (operator artifact, renderer-dependent).
|
||||
@@ -315,14 +335,14 @@ Status: closed; content awaits professional review (REVIEW-REPORT §10, 9 questi
|
||||
|
||||
---
|
||||
|
||||
## BDR-037 | 2026-10-10 | Step 4c validated: reference draft, review semantics, migration rule
|
||||
## BDR-037 — Step 4c validated: reference draft, review semantics, migration rule (2026-10-10)
|
||||
|
||||
User decisions: curated equine draft = reference draft of the app until published (no publication without professional review); technical integrity ≠ medical validation (`inherited` / `reviewed` / `to_confirm` stay visible, REVIEW-REPORT the hand-off doc for the osteopath, 11 open questions → next changeset); future schema changes = incremental non-destructive migrations (BLK-008); legal scope text re-read on consolidated Légifrance texts before publication; head view preserved as crop, per-view assets still possible. Docker `faunosteo_` rule permanent; `.env.example` change documented in DEPLOY.md (file denied to Claude). SaaS development continues without waiting for medical validation.
|
||||
Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-038 | 2026-10-10 | Step 5: app on the canonical sheet — bundled sheet, layer renderer, Report v3, migration map
|
||||
## BDR-038 — Step 5: app on the canonical sheet — bundled sheet, layer renderer, Report v3, migration map (2026-10-10)
|
||||
|
||||
Sheet source: `SheetProvider` interface; Step 5 implementation = Vite virtual module `virtual:faunosteo-sheet` built from the seed draft (`vite/sheet-bundle.ts`), mode `SHEET_BUNDLE=draft|none`, default draft for dev server, none for builds/CI/Docker (`--build-arg SHEET_BUNDLE=draft` = explicit preview) → unvalidated draft never ships by accident (D2). Markers: pure renderer `@faunosteo/anatomy/render` (element tree, no DOM) reproduces legacy look (hitbox r + twin r−12, opacities 0.65/0.5, spine 0.3, trigger 0.06 dashed); colours = document data (`categories[].color`, additive `annotations[].color` for the head shades, schema_version stays 2 for additive optional fields); same renderer feeds `draft/review/app-<view>.svg` for visual checks. Report v3 in packages/domain: `(annotationId, viewId)` zones with label snapshots, `(findingZoneId, path)` findings, severity codes, `sheet {sheetId, versionId|null, documentSha256}`, `unresolved: true` for what migration cannot place, `localAnnotations: []` reserved. Migration map generated by the pipeline from applier records (replay renames/moves/removals + unique re-homing): 792 nodes → 571/180/7/34. Interaction = pure service + reducers (BDR-019 kept); store = v3 + persistence adapter (v2 draft migrated on restore). D4 applied: registry, matchers, SVG parser, editors, pathology-editor, public species assets deleted; legacy sources moved to `supabase/seed/.../legacy-sources/` (importer input).
|
||||
Alt rejected: copying the draft into apps/app (duplication, drift); runtime fetch of `/sheets/*.json` (still public, no gain); UUID annotation ids (BDR-031); converting v3→v2 for attachments (lossy); per-view colour table in the app (horse knowledge in generic code).
|
||||
@@ -330,7 +350,7 @@ Status: closed; awaiting user validation of Step 5.
|
||||
|
||||
---
|
||||
|
||||
## BDR-039 | 2026-10-11 | Step 6: autonomous PDF archives — lean-document snapshot, envelope v1, archived branding + labels, explicit rebase
|
||||
## BDR-039 — Step 6: autonomous PDF archives — lean-document snapshot, envelope v1, archived branding + labels, explicit rebase (2026-10-11)
|
||||
|
||||
User-validated design (docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II). Attachment = envelope v1 `{format, envelopeVersion, exportedAt, locale, report v3, sheetSnapshot, branding, labels}` in one `osteo-report.json`, SVG inline as text. Snapshot = `{status, ref, document, assets}` where document = valid lean `AnatomicalSheetDocument` (all views/annotations/categories/regions, finding zones kept by id, trees pruned to used paths with ancestor labels, references emptied) → reuses sheet index, layer renderer, 21 integrity rules; no dedicated schema. Branding (logos base64/svg, credits, URLs) + label dict (fr+en) archived so future logo/wording changes never alter a re-render (user D7 adjustment). Engine `packages/pdf`: explicit inputs `{report, sheet, branding, labels, locale, rasterizer, exportedAt}`, no DOM lib, xmldom composition promoted from curation app-review, Rasterizer adapter (browser Image/canvas; resvg devDep for tests), per-view/per-logo degradation, export-side validation (caps, integrity, sheet invariant). Read = layered: report first (v3/v2 existing dispatch), envelope metadata tolerant, snapshot strict → `snapshotRejected` enum, report never lost; `attachment_stripped` via Info.Keywords stamp. Session: imported archive kept immutable (`osteo:archive`), working copy rebased explicitly on the loaded sheet (`rebaseReportOnSheet`, unresolved flags + labels from archived snapshot) (user D8 adjustment); re-export of the kept archive = technical support only, UX submitted after step. No CLI, no page change, no original v2 JSON re-embedded.
|
||||
Alt rejected: dedicated SheetSnapshotSchema (rewrites lookups, loses integrity rules); separate embedded files per asset (first-EmbeddedFile reader, stripping risk); pruning views/annotations (saves ~0 KB, breaks trigger titles); snapshot discarded on import (user: keep for faithful re-read); crypto hash check of assets (self-referential; sha copied from catalog manifest as provenance pointer instead).
|
||||
@@ -338,171 +358,171 @@ Status: closed (Step 6 validated by user 2026-10-11; D8 finalised in BDR-040).
|
||||
|
||||
---
|
||||
|
||||
## BDR-040 | 2026-10-11 | Step 6 closure: no "re-export the original archive" button, visible rebase, BLK-009 gate
|
||||
## BDR-040 — Step 6 closure: no "re-export the original archive" button, visible rebase, BLK-009 gate (2026-10-11)
|
||||
|
||||
User decisions after manual validation (logos and picker text confirmed OK on their side; Step 6 VALIDATED). (1) Re-export of the imported archive from the UI REFUSED permanently: the practitioner already holds the original PDF; no second button, no dedicated UX flow. Keep the archived snapshot, its integrity and the autonomy tests (engine `exportFromEnvelope` stays as the proof + future server use); the UI exports only the open working report. Do not propose this feature again. (2) Rebase on draft restore shown to the user (`editor.draft_rebased`) approved; import messages approved on principle with an explicit "full restoration" vs "partial recovery" headline. (3) BLK-009 treated now: byte-scan attachment extraction without pdf-lib load on import + export without object streams; remaining risks (worker/server import, pdf-lib replacement, read caps) stay an explicit BLOCKER gate before any external user import; never declared solved by passing tests alone.
|
||||
Alt rejected: a re-export action on the home screen after import (same objection); a toast system for import feedback (no component, alert pattern kept).
|
||||
Status: closed.
|
||||
|
||||
## BDR-041 | 2026-10-11 | Step 7 scope: zustand auth store (no TanStack), professional fields on profiles, MFA = documented gap, config-driven OAuth buttons, local tool stays open
|
||||
## BDR-041 — Step 7 scope: zustand auth store (no TanStack), professional fields on profiles, MFA = documented gap, config-driven OAuth buttons, local tool stays open (2026-10-11)
|
||||
|
||||
Step 7 brief (UX validated by user with external mockups, not versioned). Choices: (1) no TanStack Query: one profile read/update per section, zustand `authStore` + `localeSync` enough; query layer deferred to the first list screens. (2) `practice_name`, `professional_title`, `siret` added to `profiles` as declared free text (CHECKs, column grants), verification stays the Professional Verification domain (Step 11). (3) MFA: foundations had TOTP disabled, no `has_mfa()`, no admin table → TOTP enabled server-side, enforcement + enrolment UI documented as gap (IDENTITY.md §4), Security section shows a note, no fake UI. (4) OAuth buttons listed by `APP_AUTH_PROVIDERS` / `VITE_AUTH_PROVIDERS`; config.toml providers read `env()` ids, `enabled = false` until ids exist; `platform_invitations` not written. (5) Local tool routes untouched + unauthenticated (`LocalToolShell`, catch-all), Home header entry only when Supabase configured; `/app` guard sends to `/login?next=` with same-origin check. (6) Account locale wins over device locale once per sign-in; switches while signed in persist to `profiles.locale`.
|
||||
Alt rejected: TanStack now (YAGNI); MFA enrolment screen (unvalidated UI, nothing to protect); `/register` naming (`/signup` kept); nested `<a><button>` for card CTAs (ButtonLink instead).
|
||||
Status: active, awaiting user validation of the step.
|
||||
|
||||
## BDR-042 | 2026-10-12 | Step 7 validated; validated mockups versioned as permanent design reference; Home without sidebar accepted
|
||||
## BDR-042 — Step 7 validated; validated mockups versioned as permanent design reference; Home without sidebar accepted (2026-10-12)
|
||||
|
||||
User validated every Step 7 screen and flow (login, signup, recovery, dashboard, account, sidebar + drawer, logout, FR/EN, responsive), no UI correction. Decisions: (1) the mockup file the user produced (`docs/design/faunosteo-etape7-maquettes-validees.png`, 7 views) is the permanent graphic reference for the SaaS shell; `docs/design/README.md` lists what it shows beyond Step 7 with the owning step (Bilans/Clients/Animaux/Agenda/Fiches entries, stat tiles, bell, avatar photo → Step 8, Mon compte tabs, mobile tab bar) so no screen invents them early; a redesign needs a new validated file there. (2) Local-tool Home (`/`) shows no sidebar when signed in, only "Mon espace": accepted until the tool is integrated into `/app` (Step 14). (3) Password rule in the mockup (8 chars) does NOT override the server policy (12 + classes). (4) Follow-ups kept in TODO 7.10: MFA before sensitive admin features, professional verification ≠ SIRET format, real OAuth tests once ids exist, tool integration into /app.
|
||||
Status: closed; Step 7 finished into develop.
|
||||
|
||||
## BDR-043 | 2026-10-12 | Rust by default: permanent language rule + target architecture (study awaiting validation)
|
||||
## BDR-043 — Rust by default: permanent language rule + target architecture (study awaiting validation) (2026-10-12)
|
||||
|
||||
Owner rule: Rust preferred wherever equivalent or better; "already TS", "more work", "no perf gain" never reasons for C. Kept: React/TS UI + DOM + stores + vendor glue, Tailwind, SQL + RLS, Supabase Auth/Storage, Vite tooling. Study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 (61 challenger findings folded). Classification: A = domain contracts/rules, sheet handle + index data, reducers, data-building component rules, publish gate, layer renderer + compose, one SVG sanitiser, PDF reader + writer, CLI tools, curation pipeline + importer, upload script, Step 8 worker, every future backend/rule mirror; B = none; C = React render glue + display helpers, Zustand/storage adapters, supabase-js session + error shapes (no Rust GoTrue PKCE client), UI form schemas + dictionaries, clock/crypto/Intl screen dates, browser rasteriser (DOM), Vite tooling, SQL/RLS, public web (Astro, global rule). Target: 3 crates (`core` feature-gated lib + tool bins, `wasm` facade, `worker` bin), JSON strings across the boundary + `ts-rs` types (no serde-wasm-bindgen: writes absent optionals as null), `SheetHandle` built once, closed error kinds, ids/time injected, panic=abort handled TS-side (poison + reinstantiate), lazy init + `core_unavailable`, reader in terminated Web Worker. Worker: Rust binary, decode child = same binary dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist (Landlock dropped: redundant), pure-Rust decoders (`image`/zune-jpeg/png/image-webp) + `moxcms` ICC, lossy WebP via `libwebp-sys` ≥ 1.6 in the child only, parent parses RIFF header only (never decodes), 512 KiB output cap, per-stage deadlines; service key kept (dedicated role = Step 27 option). Roadmap: R0 workspace + worker image inside Step 8, R1 = Step 8 worker, R2 domain core before Step 9, R3 anatomy, R4 pdf reader + writer (Std14 AFM metrics, draw-log golden frozen first), R5 pipeline + importer + tools, all before Step 13; TTF fonts separate later change. Deploy prerequisites: CSP `'wasm-unsafe-eval'`, gzip wasm, images built in CI pulled by digest (VPS 1 GB never compiles), N-1 reader test, draft quarantine.
|
||||
Alt rejected: single `core` crate without features (worker would carry pdf deps) → features chosen; 6 crates (rev 1) → too many; resvg in browser (949 KB gz, visual change); wasm-pack (one maintainer, CLI lock); Edge Functions (limits, hand deploy); Prettier-chained sheet identity (hash only compared at runtime → one-time rebase accepted); parent re-decode of child output (breaks keyless-decoder invariant).
|
||||
Status: active, awaiting owner validation of the study + 13 decisions D-R1..D-R14 (D-R6 withdrawn); nothing implemented; release 0.2.0 untouched.
|
||||
|
||||
## BDR-044 | 2026-10-12 | Rust orientation validated by the owner; detailed decisions D-R1..D-R14 pending
|
||||
## BDR-044 — Rust orientation validated by the owner; detailed decisions D-R1..D-R14 pending (2026-10-12)
|
||||
|
||||
Owner validated the study's orientation + 10 principles: Rust worker at Step 8; Cargo workspace; native + WASM libs; progressive anatomy migration; PDF migration under complete compatibility proofs; React + PostgreSQL/Supabase kept; testable increments with rollback; no premature deletion of TS still used; fully dockerised, production builds outside the small VPS; WASM vs production CSP proven before activation. Requests: expanded decision table (Annex A), R0 scope with build tools reproducible in Docker and no Rust on the VPS (Annex B), serde/WASM/panic/musl hypotheses verified experimentally when they condition a choice (R0 proofs as permanent tests). Release 0.2.0 still waiting. R0 and Step 8 implementation NOT started until the 13 decisions are validated.
|
||||
Status: active; awaiting D-R1..D-R14 validation.
|
||||
|
||||
## BDR-045 | 2026-10-12 | Rust review rev 2 validated with amendments; R0 go
|
||||
## BDR-045 — Rust review rev 2 validated with amendments; R0 go (2026-10-12)
|
||||
|
||||
Owner validated D-R1/2/3/7/8/10/11/12/14 as recommended. Amended: D-R4 libwebp C only in the isolated child, parent validates result + limits before use, linked libwebp version known/controlled, no new unmanaged risk; D-R5 fingerprint → canonical JSON (RFC 8785 JCS or strictly defined alternative) independent of formatter, explicit compat with old fingerprints/archives, existing fingerprints untouched, decision prepared for R5; D-R9 Edge Functions → Rust services, shared code but distinct processes (worker vs HTTP endpoints), same image + subcommands, least privilege per service, Supabase Auth keeps OAuth; D-R13 CSP `'wasm-unsafe-eval'` proven experimentally without widening JS permissions, reproducible Docker builds in CI, digest images + rollback prepared, no auto-deploy, no image publication without workflow + validation, VPS never compiles Rust. R0 go per Annex B (7 proofs for real, unverified hypotheses tested, blockers reported not assumed); R1 NOT started without a go; release 0.2.0 pending; live deployment untouched.
|
||||
Status: closed (owner, 2026-10-12); R0 in progress on feature/rust-r0-foundation.
|
||||
|
||||
## BDR-046 | 2026-10-13 | R0 implementation choices (Rust foundation)
|
||||
## BDR-046 — R0 implementation choices (Rust foundation) (2026-10-13)
|
||||
|
||||
Choices made while building R0 (feature/rust-r0-foundation), within the validated review: (1) toolchain arbiter = Docker builder image (`docker/rust-builder.Dockerfile`, rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy baked in: official images ship rustup's minimal profile), `docker/rust-run.sh` with named volumes `faunosteo_cargo_registry` / `faunosteo_rust_target`; no rustup on the host, never on the VPS. (2) `serde_json` features `preserve_order` + `float_roundtrip` (default parser one ULP off, found by the proof). (3) Boundary = JSON strings + `ts-rs` types committed under `packages/core-wasm/types` with a CI drift check (no serde-wasm-bindgen/tsify). (4) Fresh wasm instance = cache-busting dynamic import of the glue (ESM cache returns the same instance otherwise); R2 must do the same in the browser or use a Worker per instance. (5) Worker: `RLIMIT_CPU` soft N / hard N+2 (soft = hard → SIGKILL first); seccomp allowlist = the 7 traced syscalls (read write mmap munmap mremap exit_group getrandom) + 7 abort-path ones, derived by strace in the Dockerfile `test` stage and compared on every build; dependencies optimised in the dev profile (4096² decode under the 10 s CPU cap); test hooks behind a cargo feature never in release; parent parses the RIFF container only (D-R4 amendment). (6) App `Dockerfile`, `docker/nginx.conf`, compose untouched at R0 (deviation from Annex B's "wasm stage built in CI": no consumer before R2, owner said live deployment untouched); CI `check` job builds the wasm itself (no artifact action dependency on the Gitea runner). (7) cargo-deny `allow-wildcard-paths = true` (a versionless path dep reads as a wildcard) and the core path dep declared per crate (workspace-inherited path dep hits a cargo-deny bug). (8) CSP proof committed as `docker/csp-proof/` (playwright-core outside the repo, documented).
|
||||
Alt rejected: rustup on the dev host (owner: builds reproducible in Docker); wasm-pack; artifact upload/download between CI jobs (unverified on the forge); Landlock + NPROC/FSIZE/NOFILE (redundant under the allowlist, challenge finding).
|
||||
Status: closed (R0 delivered, awaiting owner validation; R1 not started).
|
||||
|
||||
## BDR-047 | 2026-10-13 | Native Rust toolchain primary on the Ubuntu dev server; Docker builder = reproducible alternative; no CI active
|
||||
## BDR-047 — Native Rust toolchain primary on the Ubuntu dev server; Docker builder = reproducible alternative; no CI active (2026-10-13)
|
||||
|
||||
Owner brief after R0 delivery: dev machine = self-hosted Ubuntu native (not WSL, not VPS), Docker rootless. Decision: daily Rust = native user-level rustup (channel from `rust-toolchain.toml`, wasm32 target, wasm-bindgen-cli 0.2.129, cargo-deny 0.20.2 via `cargo install --locked`, no sudo, no global package). Root scripts `rust:check` / `wasm:build` run `scripts/rust-check.sh` / `scripts/wasm-build.sh` natively (moved from docker/, PATH guard `scripts/rust-env.sh`); `rust:check:docker` / `wasm:build:docker` = same files through the builder image (kept, reference for a future runner, proof VPS never compiles). `pnpm check:all` (`scripts/check-all.sh`) = single pre-merge gate: rust check, types drift, wasm, `pnpm check`, app image, `worker:test`, `worker:image` read-only. Docker keeps Supabase, worker container (isolation untouched), sandbox + seccomp tests, images. Workflow files kept, headers "prepared, never executed"; no runner / secret / registry. Supersedes BDR-046 (1) "no rustup on host, container = arbiter". Names: existing script names stay = native (main path), `:docker` suffix = alternative; `check` stays the Node gate, `check:all` the full one.
|
||||
Alt rejected: Docker as main path (owner: native loop; Docker for services only); scripts left under docker/ (misleading location); one script per environment (drift); `check:all` needing the Supabase stack (non-hermetic; `pnpm db:test` stays the complement after a supabase/ change).
|
||||
Status: active; awaiting the owner's final validation before R1.
|
||||
|
||||
## BDR-048 | 2026-10-13 | Step 8 / R1 implementation choices: lease token, SQL-side sweeps, ureq worker, no signed URL
|
||||
## BDR-048 — Step 8 / R1 implementation choices: lease token, SQL-side sweeps, ureq worker, no signed URL (2026-10-13)
|
||||
|
||||
Built on STEP8 D1–D9 (D1 = Rust worker, D3 = top-bar avatar + name → Mon compte). Choices beyond the analysis: (1) `assets.lock_token` uuid set by `claim_avatar_jobs`, required by complete/reject → stale worker after lease expiry refused (`invalid_state`), not only superseded rows; (2) complete refused → worker deletes nothing, purge queue owns every object of a terminal row (the analysis' "delete the clean object it wrote" would race a legit re-claim); (3) key-driven quarantine sweep = SQL anti-join RPC `claim_quarantine_leftovers` on `storage.objects` (same DB) instead of paginated Storage API listing; `expire_pending_uploads` RPC for the 24 h expiry; (4) closed refusals = SQLSTATE P0001 with the code as message, authz = 42501; TS/Rust map message → closed kind only when it has the code shape; (5) worker HTTP = `ureq` 3 (rustls + ring, webpki-roots), hand JSON log lines, 25-line base64url decoder: deviation from review Part V (tokio/reqwest/tracing/base64) justified by sequential loop + smaller keyed-process tree (34 → 84 crates, no aws-lc-rs/cmake); (6) Storage API v1.79 answers a missing object HTTP 400 + statusCode "404" → normalised to 404 = purge done (found by the e2e, queue entries looped otherwise); (7) e2e = vitest file outside the default include, runner script starts the worker container (5 s sweep, 0 grace), fresh admin-created user per run (10/h rate limit), purge clock shifted via `docker exec psql`; (8) `run --check` exit 0 when startable OR wholly unconfigured (check:all envless stage), 2 on partial config; (9) `.env.worker*` not writable here (file rule) → documented in DEPLOY.md, user creates it; (10) R1 branch cut from the R0 tip because `gitflow finish` of R0 was refused by the harness classifier.
|
||||
Alt rejected: profile column avatar pointer (D5 kept derived); signed read URL (bearer outlives row flip); Storage listing sweep (3-level prefix pagination); reqwest blocking (pulls tokio).
|
||||
Status: active; awaiting owner validation (TEST FONCTIONNEL + TEST GRAPHIQUE), no merge.
|
||||
|
||||
## BDR-049 | 2026-10-13 | Identity Faunosteo / faunosteo.com; DEV-STAGING-PROD; DEV reachable on the private network; R0+R1 validated and merged
|
||||
## BDR-049 — Identity Faunosteo / faunosteo.com; DEV-STAGING-PROD; DEV reachable on the private network; R0+R1 validated and merged (2026-10-13)
|
||||
|
||||
Owner decisions: (1) R1 validated 10/10 manual + graphic → R0 and R1 finished into develop (5cfb6f1, f5865f0; the earlier classifier refusal did not recur); (2) identity final: product/app/site = **Faunosteo**, domain **https://faunosteo.com**, no new brand name, logo/palette/mockups kept; (3) environments: DEV = self-hosted Ubuntu native (Claude Code, git, rustup, Vite, Docker rootless, local Supabase, worker), STAGING = `staging.faunosteo.com` planned not created, PROD = separate VPS, current site preserved, no DNS/cert/proxy/data change; isolation of DB/Storage/secrets/accounts/OAuth/payments/mails/files per env, prod data never copied to DEV, merge ≠ deploy, no CI/CD operational (workflows preparatory); (4) permanent rule: the owner tests from other devices (computer, phone) → every test surface addressed by the DEV origin (LAN address or private name), never 127.0.0.1/localhost, never hard-coded; implemented as `scripts/dev-env.sh` (`FAUNOSTEO_DEV_HOST`, detected via `hostname -I`, prod host refused) + `scripts/supabase.sh` wrapper (config.toml `env()` for api.external_url, auth.site_url, studio.api_url) + `scripts/dev.sh` (`pnpm dev` on the origin, `pnpm dev:offline` without backend) + private-network redirect URLs; (5) exposure: 5173/54321 needed by browsers, Studio 54323 + Mailpit 54324 unauthenticated → private subnet only, PostgreSQL 54322 published by the CLI on 0.0.0.0 (no bind option) → firewall restriction proposed to the owner, not applied; worker no port; (6) Rust native via Cargo, Docker for services/worker/sandbox/images/prod, VPS never compiles.
|
||||
Alt rejected: hard-coded IP in config.toml (first iteration, replaced the same day); Vite `dev:lan` variant (folded into `dev`); binding the CLI ports to loopback (impossible in config.toml).
|
||||
Status: active; `chore/dev-lan-access` awaiting the owner's LAN validation; R2 not started.
|
||||
|
||||
## BDR-050 | 2026-10-14 | R2 implementation choices: Zod semantics in serde, minimal index data, form edits stay Zustand, quarantine, lazy core
|
||||
## BDR-050 — R2 implementation choices: Zod semantics in serde, minimal index data, form edits stay Zustand, quarantine, lazy core (2026-10-14)
|
||||
|
||||
Built on review rev 2 + Annex C; plan `.claude/tasks/plans/2026-10-13-rust-r2-domain-core.md` rev 2 (3 challengers, 45 findings, 1 BLOCKER folded). Choices: (1) JSON read text → `serde_json::Value` (JSON.parse dup-key semantics) → typed; lone surrogate escape → U+FFFD pre-pass (L1, owner to confirm); (2) Zod reproduced by field helpers: `js::present` (optional: absent ok, null refused, skipped), `js::nullable` (required key), `JsInt` (any integer-valued number, JS print), hand-written patterns (no regex crate), `url` crate for `.url()`; unions = untagged enums + literal tag fields at Zod position → byte-equal with `JSON.stringify(Zod.parse(x),null,2)`; PDF label fields in engine dict order → frozen envelopes round-trip byte-equal; (3) quirks ported site by site (Map last-wins, find first-wins, JS truthiness, `??=`, malformed map entry still fails the read); (4) `SheetIndexData` minimal (positions, names, spineIds, nodeKeys as JSON `[zone,...path]`), TS `SheetIndex` = accessors only + `ops`; (5) one core call per user action; form-value observation edits (comment, severity, free text, finding removal) stay Zustand assignments (no per-keystroke wasm, D-R7); store actions answer `{ok}`, callers stop on failure; `hydrateReport` deleted; (6) runtime: sync calls, trap → poison → offline recovery from kept compiled module + pre-imported spare glue record, cap 3, per-generation sheet handles, retry clears all caches; `pkg/` shipped vs `pkg-proofs/`; BUILD_STAMP refuses stale module in tests; (7) quarantine only on content kinds, newest-only keys, source removed after successful copy, pre-rebase raw kept when unresolved > 0; editor never redirects in degraded states; (8) Home and /new read availability from the bundle, core loads at submit / import / editor; (9) import = TS byte scan (until R4) → core `archive.import` (read + rebase one call); export = core `archive.snapshot` → frozen TS engine; (10) publish gate takes the core validator (DI), fails closed; (11) report:compare CLI keeps the frozen domain (R4); practitioner prefill keeps a small Zod schema (D-R7, core not loaded on /new mount); (12) app image wasm stage + gzip_static; DEPLOY: CSP keyword before an R2 image, never built on VPS.
|
||||
Alt rejected: mutation corpus with full outputs (simplicity challenge: drift-free verdict table + characterisation instead); `report.replace_observation` per keystroke; serde internally tagged enums (tag first breaks byte equality); Web Worker for every call (async races in the click chain); unify duplicate-id policies (behaviour change).
|
||||
Status: active; R2 delivered on feature/rust-r2-domain-core, awaiting owner validation, no merge.
|
||||
|
||||
## BDR-051 | 2026-10-14 | L1 resolved: lone UTF-16 surrogate refused whole, never replaced (supersedes BDR-050 choice 1 on this point)
|
||||
## BDR-051 — L1 resolved: lone UTF-16 surrogate refused whole, never replaced (supersedes BDR-050 choice 1 on this point) (2026-10-14)
|
||||
|
||||
Owner refused U+FFFD replacement of lone surrogate escapes (silent alteration of historical user data). Chosen (owner, 2026-10-14): refusal + quarantine. `js::parse_json` no pre-pass; serde_json refuses escape like any error; failure classified by strict escape scan (on failure only) → `JsonReadError::LoneSurrogate` → closed kind `lone_surrogate` (parse_input, sheet.check, draft.restore, archive.import). App: draft → `osteo:quarantine:draft` verbatim + existing `editor.draft_quarantined`; session archive → `osteo:quarantine:archive`; import → `ImportError('lone_surrogate')` + new `home.import.error_lone_surrogate` (owner-chosen detailed wording FR/EN, file untouched); editor action → refused, report unchanged, `core.action_failed`; publish gate → `invalid_shape`. Oracles untouched: L1 cases now assert TS kept surrogate + Rust refuses; test loader spells lone escapes out as literal text (never U+FFFD).
|
||||
Alt rejected: faithful preservation (own JSON reader + lossless WTF-16 string type over ~150 contract fields + serialiser, oracles re-frozen; multi-day, for corrupted/pasted-UTF-16 data only; door stays open since nothing is lost); in-band tunnel (placeholder code points mapped back at facade output; collisions with sheet strings, UTF-16 length drift, every output path must be post-processed: hacky).
|
||||
Status: active; merged with R2.
|
||||
|
||||
## BDR-052 | 2026-10-14 | R2 maintenance: held session texts, resolution panel, save-failure banner
|
||||
## BDR-052 — R2 maintenance: held session texts, resolution panel, save-failure banner (2026-10-14)
|
||||
|
||||
Owner rule: no user data removed/overwritten implicitly when save or quarantine fails. Owner UI choice (AskUserQuestion): resolution panel in editor (download exact copy, delete permanently w/ confirmation, open adapted version w/ confirmation for pre-rebase draft, retry); New report / Import refused while held → alert + panel; storage-full banner on refused draft (or archive) write; set-aside texts UI = later. Code: occupied quarantine slot never replaced; draft+archive pair set aside together (rollback own copy); restore returns `held`, opens nothing; mirror writes only on report change; new session reads unread draft via core first (unreadable → set aside, readable → replaced as before); reset no-op without open report. rustls 0.23.46 (4 advisories, none reachable); `supabase/.temp/cli-latest` untracked.
|
||||
Alt rejected: dropping held texts after warning (owner rule); multi-slot quarantine (scope); refusing every New report over an unread readable draft (behaviour change, not asked).
|
||||
Status: closed (merged aab61c2).
|
||||
|
||||
## BDR-053 | 2026-10-15 | R3 design: one Rust SVG reader, constant canvas op, highlight unexposed, declared stricter rules
|
||||
## BDR-053 — R3 design: one Rust SVG reader, constant canvas op, highlight unexposed, declared stricter rules (2026-10-15)
|
||||
|
||||
Plan rev 2 after 3 challengers (32 findings). Reader = prescan (markup state machine, caps before parse: 2 MiB, BOM, DOCTYPE, depth 64, 20k elements, attrs 256/100k, 16 xmlns, raw `<` 100k `=` 200k) → roxmltree 0.21.1 → own tree (qualified names as written, TS allowlist parity) → allowlist + declared extras (SVG ns only, comments dropped, text only title/desc ≤ 4 KiB, root without class/style/transform/filter/mask/clip-path, id grammar, href/url( local only after ASCII/CSS whitespace) → reference graph (cycles refused, expansion ≤ 50k) → serialiser (control whitespace as char refs, output ≤ 4 MiB). Product drawing with any removal refused at load (LRN-055). Facade: only `view.canvas {viewId}` (stateless, memoised per view; data-state still restyled in place). Highlight composition = core fn proven vs TS (O3), no facade op until R4 (snapshot-based call). Behaviour = code where ANNOTATION-RENDERING.md differed (doc rewritten first). Canvas failure → existing degraded notice + retry.
|
||||
Alt rejected: roxmltree alone with nodes_limit (recursion overflows wasm stack, measured); `svg.sanitize` / `view.highlighted` ops now (no consumer, wrong source for R4); states in the canvas op (dead: restyle runs after every build); dangling-ref removal (rendering change); duplicate-id refusal; property tests (no generator crate).
|
||||
Status: active; R3 awaiting owner validation, not merged.
|
||||
|
||||
## BDR-054 | 2026-10-15 | R3 owner UX decisions: trigger names per language, three canvas failure states, retry policy
|
||||
## BDR-054 — R3 owner UX decisions: trigger names per language, three canvas failure states, retry policy (2026-10-15)
|
||||
|
||||
Owner validated after R3 review: (1) unnamed trigger → `data-anno-name-fr`/`-en` + title take opened view name per language, empty language falls back to other; display only (not identifier, not persisted); frozen oracles untouched, tests apply declared change (`with_trigger_names_per_language` / `withTriggerNamesPerLanguage`, MAKE refused). (2) canvas failures distinct: engine (core_unavailable, internal) → `sheet.core_unavailable` + Réessayer (fresh instance may succeed); view (svg_rejected, no_asset, unknown_view, invalid_character, parse) → `canvas.view_unavailable`, no retry; detail in core outcome + DEV console only. (3) recovery cap 3 kept; after it `CoreRuntime.stopped` → `core.stopped` ("reload the page, report kept in tab") in canvas and in the 8 action alerts (`coreFailureMessage`), no retry. Wording of the three messages accepted.
|
||||
Alt rejected: correcting the TS renderer too (engine/pipeline frozen until R4/R5; invisible in PDF: data-* dropped, title not rasterised); retry for deterministic view failures; editing goldens.
|
||||
Status: closed (decisions); R3 still awaiting owner LAN confirmation, not merged.
|
||||
|
||||
## BDR-055 | 2026-10-16 | Engine stopped vs unsaved draft: honest variant, core-free copy, restart not counted
|
||||
## BDR-055 — Engine stopped vs unsaved draft: honest variant, core-free copy, restart not counted (2026-10-16)
|
||||
|
||||
Owner audit of 0279953 (stopped state) not satisfactory → owner choices (AskUserQuestion 2026-10-15): stopped + `isUnsaved` (saveFailed && report) → `core.stopped_unsaved` + "Télécharger une copie" (in-memory report JSON, `lib/download.ts`, no core); save fine → `core.stopped` + `core.reload` button; copy button also on `editor.save_failed` banner (any engine state); `beforeunload` guard in editor while unsaved; "plusieurs erreurs" (counter = page lifetime, not successive). One `CoreStoppedNotice`: editor banner slot, top of Home / New report, CoreUnavailable full page; canvas stopped text without button. Runtime: failed recovery below cap restarted by next call / `ready()` (`restartable` = unavailable && !stopped && generation > 0), compiled module kept, restart not counted (cap = traps); deferred status listeners. Core failure reading unread draft → FAILED, never held. ESLint census on failure keys. Commit 6371523.
|
||||
Alt rejected: counting failed restarts toward cap (offline → stopped, reload offline fails too); retry button on every page (new UI, owner already removed dead retries); copy only once stopped (offline restart loop never reaches stopped, no rescue).
|
||||
Status: closed; R3 still awaiting owner LAN confirmation, not merged, R4 not started.
|
||||
|
||||
## BDR-056 | 2026-10-17 | R3 final checks: rescue copy importable, trapping draft held, replace confirmed, guard app-wide
|
||||
## BDR-056 — R3 final checks: rescue copy importable, trapping draft held, replace confirmed, guard app-wide (2026-10-17)
|
||||
|
||||
Owner brief 2026-10-16 + AskUserQuestion: (1) Home import also takes JSON rescue copy: sniff first KiB (`%PDF-` → PDF; `{` / .json → copy), cap MAX_ATTACHMENT_BYTES 16 MiB before read, fatal UTF-8, pure `readRescueCopy` → core `draft.restore` (no JS parse), then existing hydrateImport branch; UNREADABLE_DRAFT_KINDS → `invalid_copy`. (2) `internal` reading draft → held `engine_failure` row (+ archive companion), `TrapMemory` keyed on (draft, archive) pair: no re-read by mount / New report / Import, only panel Retry (`retryTrapped`); any discard clears; `held_blocked_engine` alert. SUPERSEDES BDR-055 "never held" for `internal` only (`core_unavailable` etc. stay FAILED). (3) ReplaceSessionDialog (Annuler / Ouvrir le bilan en cours / Remplacer, copy when unsaved) on New report submit + Home pick when report in memory or draft slot; Home picker clicked synchronously. (4) `useUnsavedGuard` once in App. Commit 9bd9aca.
|
||||
Alt rejected: new store action openCopy (dup of hydrateImport, session change before validation); JS JSON.parse of copy (depth; core reads raw text); copy cap MAX_PDF_BYTES (50 MiB file cap, not JSON bound); trapped memory on draft text only (archive parsed in same call); fixing GC finalizer via glue internals.
|
||||
Status: closed; R3 awaiting owner LAN validation, not merged, no R4, release 0.2.0 untouched.
|
||||
|
||||
## BDR-057 | 2026-10-18 | R4 plan validated: module workers, incremental export in main instance, JSON memory guard gated at R4.2
|
||||
## BDR-057 — R4 plan validated: module workers, incremental export in main instance, JSON memory guard gated at R4.2 (2026-10-18)
|
||||
|
||||
Context: R4.0 plan rev 2 (`.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md`: options §A.2, conditions §A.6), 3 challengers, owner approval 2026-10-18.
|
||||
Decision: OD-1 module workers everywhere; import needs Firefox 114 (today it already needs DecompressionStream: Firefox 113, Safari 16.4); import support documented per browser apart from app support, from real checks. OD-2 incremental ExportSession in main instance: PDF + one decode ≈ 0.37 MB/view vs TS ≈ 3.8 MB/view (RGB planes held until save) vs two calls ≈ 0.91; offline export kept; cleanup on error/cancel. OD-3 JSON value budget in linear pre-scan + module `--max-memory`, thresholds from R4.2 reproducible measurements; not shown → stop before R4.3 import switch. OD-4 overwritten duplicate key holding lone surrogate refused, file untouched. OD-5 PDF crash/timeout `error_generic`, copy crash/timeout `error_core_unavailable`, kinds keep technical / resource / invalid apart. OD-6 J1 matrix exact, unrun device never reported validated. OD-7 ~5 MB fixtures, no real data in git.
|
||||
Alt rejected: classic iife worker for Firefox 102-113 (dev/prod split for dead versions); two-call export (all PNGs in linear memory); disposable export worker (asset fetched at export breaks offline, protocol cost); throwaway main-thread instance (glue retains instances, LRN-060); own lossless JSON reader (R2 rejection holds).
|
||||
Status: active. Order: plan merge → Safari download bugfix (owner validation) → feature/rust-r4-pdf-core → R4.1.
|
||||
|
||||
## BDR-058 | 2026-10-18 | R4.2 validated: OD-3 thresholds fixed, R4.3 switch gated on large-file memory and leak series
|
||||
## BDR-058 — R4.2 validated: OD-3 thresholds fixed, R4.3 switch gated on large-file memory and leak series (2026-10-18)
|
||||
|
||||
Context: R4.2 report (RUST.md §10.3, §10.4): O7 144/144, O9 38/38, O8 47 + 4 declared, browsers 666/678; security gate BLOCK(1) fixed (prescan count past depth cap) → PASS. Owner validation 2026-10-18.
|
||||
Decision: `MAX_JSON_VALUES` = 400,000 (10 × CAP envelope 39,652) and `--max-memory` 1 GiB final for R4; existing depth / size / complexity / inflation caps kept, no raise without measurement. 1 GiB = safety net, never a tab memory guarantee. Leak criterion: first import = init cost, counted apart; then ≥ 5 consecutive imports + idle, recurring growth ≤ 10 MiB, in Chromium + Firefox + WebKit, GC fluctuations repeated and explained; global peaks kept beside. Three distinct subjects: no leak / low peak / ceiling guarantee. Before the app import switch: 20–50 MiB files (WebKit 324 MiB vs TS 76) must be fixed (fewer ArrayBuffer copies, fewer linear copies, early release, no retained refs, transfer / streaming when it pays) and re-measured on 3 engines, or an explicit size limit with controlled refusal proposed with numbers; no switch before that is solved or decided. OD-4 refusals accepted (L1); no legitimate corpus file may be refused; never rewrite source files or drop bilan data on error; oracles unchanged. Worker technical error / resource overflow / timeout never presented as proof of a corrupt PDF. TS reader deleted only after parity + non-regression. WebKit one-off worker `error`: not blocking, keep trace, repetition tests, never mask `error` events. J1 on real devices announced with "TEST FONCTIONNEL DISPONIBLE"; headless ≠ Safari/iPhone validation.
|
||||
Alt rejected: 1,000,000 values (25 × CAP; more headroom, weaker bound). Switch import before the large-file fix.
|
||||
Status: active. R4.3 started 2026-10-18 on feature/rust-r4-pdf-core; no R4 merge into develop, no R5, no 0.2.0, no deploy.
|
||||
|
||||
## BDR-059 | 2026-10-18 | J1 authorised with the two WebKit reserves; PDF cap kept at 50 MiB
|
||||
## BDR-059 — J1 authorised with the two WebKit reserves; PDF cap kept at 50 MiB (2026-10-18)
|
||||
|
||||
Context: R4.3 checkpoint report (RUST.md §10.5): WebKit 50 MiB file 145 MiB vs TS 76 (worker read was 324); WebKit leak series above 10 MiB but navigation control grows too, one-page series levels off; no forced GC headless. Owner decisions 2026-10-18.
|
||||
Decision: both WebKit reserves accepted provisionally; J1 device acceptance launched on `feature/rust-r4-pdf-core`. PDF cap stays 50 MiB; no streaming scanner in R4.3. Leak criterion unchanged (≤ 10 MiB recurring over ≥ 5 imports after init), same-page measures separated from navigation ones, a no-import control kept; any device overshoot documented and analysed before final acceptance. OD-3 400,000 / 1 GiB, copy cap 16 MiB, worker protections, validated messages kept. J1 focus: Safari iOS, large PDFs, repeated imports, timers. Deliverable: PASS / FAIL / NON TESTÉ per device and scenario, gaps, residual risks, argued recommendation. Not a final validation of R4.3; headless never sufficient; TS reader kept; no merge; stop at J1, no R4.4.
|
||||
Alt rejected: streaming scanner now; lowering the PDF cap; blocking J1 on the WebKit growth.
|
||||
Status: active. Kit generated at ../faunosteo-j1-kit; results template docs/development/R4_J1_RESULTS.md; waiting for the owner's device run.
|
||||
|
||||
## BDR-060 | 2026-10-18 | R4.3 accepted provisionally; iPhone J1 blocking before any R4 merge; R4.4 go
|
||||
## BDR-060 — R4.3 accepted provisionally; iPhone J1 blocking before any R4 merge; R4.4 go (2026-10-18)
|
||||
|
||||
Context: J1 partial (computer run, no failure; iPhone unavailable, deferred). Owner decision 2026-10-18.
|
||||
Decision: R4.3 provisionally accepted on the branch, only for scenarios actually run; Safari iOS J1 mandatory before any merge of R4 into develop; BDR-058/059 WebKit memory reserves stay open; headless ≠ device. R4.4 authorised on the same branch per plan: layout, text, AFM, dates, DrawLog, validated against O1, O4, O5 and the Step 6 goldens. No regression on R4.3: reader, worker and memory guarantees untouched unless demonstrated need + prior validation. Automated tests and parity checks at every step; TS reader kept until R4.8. End of R4.4: detailed report (changes, tests, parity, performance, risks, decisions), stop before R4.5.
|
||||
Status: active.
|
||||
|
||||
## BDR-061 | 2026-10-18 | R4.4 validated; R4.5 serialiser authorised with parity, tooling and compatibility gates
|
||||
## BDR-061 — R4.4 validated; R4.5 serialiser authorised with parity, tooling and compatibility gates (2026-10-18)
|
||||
|
||||
Context: R4.4 report (RUST.md §10.6: O1 12 runs 2,124 calls, O4/O5/O6 exact). Owner decision 2026-10-18.
|
||||
Decision: R4.5 on the branch: content emitter + numberToString, pdf-writer, PNG gate and decode, links, Info, attachment, self-check, from_envelope. Gates: parity with O2, O4, O6 and applicable goldens (declared differences kept, oracles never edited to hide a gap); `qpdf --check`, poppler 150 dpi 0 px vs R3, O11 reads; restoration compat: R4 PDF read by Rust reader + kept TS reader, envelope/N-1 copies, no bilan data loss on export → import; PNG and PDF structure protections before large allocations (plan caps), invalid cases and messages checked; measure performance, allocations, real wasm size with the writer linked (W1 600 KB per plan), compared with TS baselines on same files/conditions; R4.3 import and worker guarantees untouched; WebKit reserves and iOS recette still blocking merge; gates green; RUST.md documented. Stop at R4.5 checkpoint: components, oracle/golden results, compat, perf/memory, wasm size, gaps/risks, R4.6 recommendation.
|
||||
Status: active.
|
||||
|
||||
## BDR-062 | 2026-10-19 | R4.5 validated; R4.6 session export authorised; chunked file, decode on arrival, catalog last
|
||||
## BDR-062 — R4.5 validated; R4.6 session export authorised; chunked file, decode on arrival, catalog last (2026-10-19)
|
||||
|
||||
Context: owner decision 2026-10-19 on the R4.5 report (RUST.md §10.7). R4.6 brief: ExportSession + app driver, rasters as bytes one by one, OD-2 buffers documented, `view_raster_failed` on raster failure, parity + restoration (Rust → Rust, Rust → TS reader, N-1), E3/E4 three engines same data, shipped W1 measured, TS engine kept until R4.8, no merge, stop at R4.6.
|
||||
Decision (design, measured): session in main instance per OD-2. File written in chunks never reallocated (target 1 MiB doubling to 8 MiB), image object written at `add_raster` (PNG + planes freed in the call), logos kept until branding batch completes (slot order as engine), catalog + page tree objects written last, file handed to JS in parts → `new Blob(parts)`, self-check scans attachment chunk behind header. R4 digests (own bytes, not TS oracle) re-frozen once for it; O2 suite + qpdf + poppler re-run green. Hex strings upper-case as pdf-lib (B4). Alternatives measured and dropped: single `Vec` doubling (125 MiB for 44 MiB file, realloc spike), two buffers (2 × file at finish), 1 MiB fixed chunks (0.12 MB fragmentation per view).
|
||||
Status: active; owner checkpoint R4.6 pending.
|
||||
|
||||
## BDR-063 | 2026-10-19 | R4.6 accepted provisionally; R4.7 report-compare authorised; Chromium 10 MiB series = open reserve
|
||||
## BDR-063 — R4.6 accepted provisionally; R4.7 report-compare authorised; Chromium 10 MiB series = open reserve (2026-10-19)
|
||||
|
||||
Context: owner decision 2026-10-19 on the R4.6 report (RUST.md §10.8). Chromium per-export RSS growth on L (≈ 20 MiB, same in TS control, plateau after 8) accepted provisionally: not a leak validation, kept as open reserve; reports must split wasm linear memory / browser global / canvas-blob-URL retention / transient vs persistent; thresholds never changed, no FAIL turned PASS. J1 + J2 on real devices mandatory before any merge; NON TESTÉ kept. R4.7 per plan, no scope widening; S2 export worker not engaged without proof + new decision.
|
||||
Decision (R4.7 design): `pdf::compare` pure module behind feature `cli` (= pdf-read + pdf-write, never in wasm), `Files` trait for fs; binary `src/bin/report_compare.rs` only std::fs file; seed sheet read at run time from `CARGO_MANIFEST_DIR/../../supabase/seed/.../draft` (no drawing); root `report:compare` → `scripts/report-compare.sh` (rust-env + cargo run --release --features cli). A.3 closed lines chosen: `report document invalid: <serde detail>` (ZodError dumps), `attachment refused: lone UTF-16 surrogate escape at byte N` (surrogates kept/overwritten), `report version null cannot be read` (overflow → null, incl. envelopeVersion overflow where TS printed a rejected-envelope header). Alternatives dropped: `include_str!` of the seed (bakes content, rebuild on seed change); spawning the binary per O10 row in tests (230 spawns, slow): in-process `run` + 8 spawns instead.
|
||||
Status: active; owner checkpoint R4.7 pending.
|
||||
|
||||
## BDR-064 | 2026-10-19 | R4.7 validated; R4.8 deletions: test read-back on own PDF reader, N-1 scanner exported, in-process import helper
|
||||
## BDR-064 — R4.7 validated; R4.8 deletions: test read-back on own PDF reader, N-1 scanner exported, in-process import helper (2026-10-19)
|
||||
|
||||
Context: owner validated R4.7 (three A.3 lines accepted, 25 s first compile accepted, no prebuilt binary). R4.8 brief: delete packages/pdf, pdf-lib, TS CLI, redundant tests, generators; keep frozen oracles, goldens, reference PDFs, fixtures; `packages/anatomy` render until R5; audit consumers first; non-regression proofs; checks must fail on missing Rust component; no merge, no R5.
|
||||
Decision: vitest read-back of the app export without pdf-lib = `tests/helpers/pdfFile.ts`, a reader of the writer's own format (objects, inline dicts, Flate via node:zlib, Kids order, Info, annots, XObjects) + `buildPdfWithAttachment` for the rejection inputs; view goldens from the SVGs captured at the mocked rasteriser (request order = engine order; the bundled partner SVG logo comes first with real branding); `importReportFromPdf` for tests = module `SheetHandle.import_pdf` on a throwaway handle + worker's `pdfImportOf` (`tests/helpers/pdfImport.ts`; `GlueSheetHandle.free()` added to the interface); envelope + N-1 suites read attachments with the frozen O11 scanner, exported through `@faunosteo/core-wasm/n-1` (index re-export only, copies untouched); `pdf.export.app` deleted (re-export from envelope = cargo `export_from_envelope`, no sheet/branding in signature); `@faunosteo/domain` dropped from apps/app (two incidental test uses → core types / N-1 Zod); ledger script reads frozen cases from the committed TSV. Alternatives dropped: keep pdf-lib as test-only devDependency (review R4 row forbids it in apps/app lockfile); move all content-stream checks to cargo (loses app-path coverage of non-fixture reports); `importPdf` on main-thread SheetOps (breaks OD-1).
|
||||
Status: active; owner checkpoint R4.8 pending.
|
||||
|
||||
## BDR-065 | 2026-10-20 | R4.9: Chromium export reserve classified bounded browser raster path; no rasteriser change; recettes re-issued
|
||||
## BDR-065 — R4.9: Chromium export reserve classified bounded browser raster path; no rasteriser change; recettes re-issued (2026-10-20)
|
||||
|
||||
Context: owner R4.9 brief (R4.8 validated; final checks, memory bench before merge, import risk classes, J1/J2 re-issue, fresh audits; no merge, no R5). Bench `scripts/browser/r4-memory-bench.mjs` (5 dimensions + rest windows + Chromium pressure + raster-only control).
|
||||
Decision: Chromium ≈ 20 MiB/L export = browser raster path, not session: control with no core call grows same 20 MiB/step to same plateau (436 vs 437 MiB, 16 steps, last 5 within 10 MiB); linear flat after init, JS heap flat, 847/847 canvases + Blobs collected, 854/854 URLs revoked after 30 s; critical pressure returns nothing. Class: accepted temporarily (§6 row 7), device check J2.6/J2.7. Correction only if a device fails: one reused canvas / OffscreenCanvas, bench vs control first; rasteriser untouched (pixel parity pinned). Import risks: PDF_IMPORT_HARDENING §6, 20 rows; blocking before merge = J1 + J2 device runs + timer confirmation. Port 4173 recette surface closed by UFW by default; owner opens one rule per session.
|
||||
Alt rejected: reused canvas now (no measure says it helps; risk on pinned raster output); disposable export worker S2 (no device failure).
|
||||
Status: active; owner checkpoint R4.9 pending; gitleaks allowlist `[gated]` marker = owner action.
|
||||
|
||||
## BDR-066 | 2026-10-21 | R4.10 owner decisions final: J1.7 PASS with reserve, J2.3 option 1, logo bundle, gitleaks marker valid, 23 deletions, Safari iOS real device only
|
||||
## BDR-066 — R4.10 owner decisions final: J1.7 PASS with reserve, J2.3 option 1, logo bundle, gitleaks marker valid, 23 deletions, Safari iOS real device only (2026-10-21)
|
||||
|
||||
Context: owner verdict after R4.10 gates (verifier 8/8 + one formal scope gap = contract file itself; security PASS 3 LOW).
|
||||
Decision: J1.7 functional PASS, perf reserve (~60 s OS picker offline, same via Ctrl+O outside app); M1/M2 PASS ~60 s; M3 NON TESTÉ = complementary non-blocking, never PASS without run; M4/M5/M6 NON TESTÉ; no app work on 60 s without Faunosteo-specific proof; Cache-Control fix kept. J2.3 option 1 final: editor export = current branding even for logo-less archive; corrected expected result validated; data/oracles/goldens unchanged. ZenQuality logo bundle dcc7940 validated (same image, CSP intact, no zenquality.fr dependency); reintroduction tests + CSP proof (every violation fails, except refusal a negative test expects) kept. `[gated 2026-10-18]` marker valid: marker needs explicit owner decision, writing delegable (Claude wrote it under authorization). R4.8 authorization = exactly 23 test files of 0dc1ba2 (21 = census error, EVAL-025 superseded on count); no further deletion under it. Safari iOS NON TESTÉ until real iPhone results; simulator never memory proof.
|
||||
Recorded: RUST.md §10.11 (marker wording, count) + §10.12 D; R4_MINI_RECETTE, R4_J1/J2 + RESULTS. LEDGER.tsv untouched (generated byte for byte by `scripts/r4-ledger.mjs`).
|
||||
Status: active; R4 close still waits on Safari iOS real device; no merge, no R5, no release.
|
||||
|
||||
## BDR-067 | 2026-10-21 | R4 closed: owner accepts J1/J2 on computer + Android + real iPhone, validates R4.12, authorizes merge into develop with named residual risks
|
||||
## BDR-067 — R4 closed: owner accepts J1/J2 on computer + Android + real iPhone, validates R4.12, authorizes merge into develop with named residual risks (2026-10-21)
|
||||
|
||||
Context: owner brief « Validation finale de R4 et autorisation de fusion » after R4.12 checkpoint (verifier CONFORME 9/9, security PASS 3 LOW).
|
||||
Decision: J1 + J2 declared PASS as a whole on iPhone Safari iOS (no per-check split, no model/version/timing/memory given → recorded as missing, never invented); J1.7 PASS w/ picker-delay reserve; J2.3 PASS under approved rule (new export = current branding); M3 NON TESTÉ non-blocking. R4.12 D1/D3/D6 validated. Residual risks accepted for develop merge, open until own deadline (never closed by merge): base image by tag not digest + cosign unchecked (before prod image), semgrep partial parse 2 test files, guardrails WARN `species_select_active` outside diff, device timings/memory unreported (hardening §6 items 5/6/7/9/20), J1.7 cause unknown, BDR-063 Chromium raster growth, D2/D4/D5 deferred. Merge = `gitflow finish` after usual final checks; blocking defect → stop and report.
|
||||
@@ -510,40 +530,40 @@ Alternatives: wait for per-check iPhone measures (rejected by owner: device-leve
|
||||
Recorded: RUST.md §10.15 (risk table + checks), PDF_IMPORT_HARDENING.md §7, R4_J1/J2_RESULTS + MINI_RECETTE, CHANGELOG headers, TODO R4.13.
|
||||
Status: active; limits stay: no release 0.2.0, no deploy, no DNS/server change, no R5 before next owner signal, D2/D4/D5 deferred.
|
||||
|
||||
## BDR-068 | 2026-10-22 | R5 owner decisions: D-R5 = RFC 8785 of validated doc, aliases, F1 fix, byte-exact port, frozen SVG bytes
|
||||
## BDR-068 — R5 owner decisions: D-R5 = RFC 8785 of validated doc, aliases, F1 fix, byte-exact port, frozen SVG bytes (2026-10-22)
|
||||
|
||||
Context: owner validated R5.1 (« Validation R5.1, décision D-R5 et lancement du portage Rust »).
|
||||
Decision: D-R5 = option B, convention `sha256-rfc8785-validated-v1` = sha256 of RFC 8785 canonical JSON of the validated document (defaults filled, canonical model), real RFC 8785 (UTF-16 key sort, ES number print, UTF-8, no Unicode normalisation, I-JSON refusals, Rust/JS deterministic) proven by official vectors + edge cases + independent differential; `v1` freezes the construction and validation rules (later defaults/schema never change v1 identity retroactively). Alias mechanism approved: Report v3 `sheet.documentSha256` stays 64 hex; new reports stamp current convention; old reports open with no rebase on identical document; aliases only from trusted frozen historical documents, never from an archive or bundle; unknown fingerprint ≠ official sheet; real anatomical change still migrates; no archive/fixture/oracle rewritten. F1 fix authorised first. Port byte-exact by default, differences declared one by one; fingerprint-bearing artifacts regenerated once at R5.6 only. Historical SVG bytes (horse.svg) kept, never re-serialised. `.prettierignore` on Rust-written generated paths, narrow, with a reproducible check. Upload tool reuses `ureq` (no reqwest by default) at R5.5. Slicing R5.1b to R5.7 validated; stop after R5.2.
|
||||
Alternatives: A (Rust emitted bytes, re-ties identity to a serialiser), C (Rust reproduces Prettier bytes, keeps formatter chain); one-time visible rebase of every old archive (rejected: transparent alias possible).
|
||||
Status: active. R5.1b + R5.2 done 2026-10-22; documentSha256, seed, report contracts untouched until R5.6; no merge, no package deletion, no 0.2.0, no deploy.
|
||||
|
||||
## BDR-069 | 2026-10-24 | Refuse three non-canonical v3 report shapes at reader entry
|
||||
## BDR-069 — Refuse three non-canonical v3 report shapes at reader entry (2026-10-24)
|
||||
|
||||
Decision (owner go): `check_v3_shape` on raw value before `Report::deserialize`: `sheet`, `practitioner` must be objects, `severity` string. At `read_report_document` v3 + `parse_envelope`. Rationale: serde derives accepted positional arrays / one-key enum maps Zod refused → crafted file could swap same-typed fields silently. Alternatives: generic shape guard (draft/shape.rs style) on whole contract (wider, not authorised); `deserialize_with` in contract structs (touches contract). Status: applied d502dfa; v2 + other contracts keep serde leniency (not in go). Owner confirmed fingerprint convention `sha256-rfc8785-validated-v1`, one alias `27c7383c…2660`; R5.6 scope files approved, switch not authorised.
|
||||
|
||||
## BDR-070 | 2026-10-25 | D-R5.6 active: fingerprint `sha256-rfc8785-validated-v1`, registry alias, M1 option 1
|
||||
## BDR-070 — D-R5.6 active: fingerprint `sha256-rfc8785-validated-v1`, registry alias, M1 option 1 (2026-10-25)
|
||||
|
||||
Decision (owner, activation 9e87016): sheet fingerprint = SHA-256(JCS RFC 8785 of R2 typed reading, no integrity error, warnings allowed, depth 128). Equine canonical 12d78872…74e2; old 27c7383c…2660 = sole TRUSTED_ALIASES entry, bound to sheet 503dc301 + content. Alias honoured only via LoadedSheet::recognises_historical_stamp (loader-verified v1 private state + document recomputed at decision + one-way registry pair + same sheet id); equivalence pub(crate). M1 option 1: snapshot of old report keeps its stamp (build_sheet_snapshot); export, archive reader strict. v0 refs (no block) load unverified, no privilege; null/malformed block refused. Rust = sole seed writer, TS legacy until R5.7. Alternatives rejected: A file-bytes (Prettier-bound), C Prettier reproduction; re-stamp at rebase (rewrites reports); export-side alias (M1 defect, no proof). Status: active on feature branch; rollback not transparent for post-switch reports (rebased, nothing lost) → settle before user release.
|
||||
|
||||
## BDR-071 | 2026-10-25 | Product roadmap principle validated: P0 → V1-1 → V1-2 → V1-3 → V1-4 → V1-5
|
||||
## BDR-071 — Product roadmap principle validated: P0 → V1-1 → V1-2 → V1-3 → V1-4 → V1-5 (2026-10-25)
|
||||
|
||||
Decision (owner, brief « P0 : arbitrages documentaires et finalisation du contrat V1-1 »): order P0 docs → V1-1 clients + animals → V1-2 sheets from Supabase → V1-3 cloud bilans + history → V1-4 stored PDF + authorised sharing → V1-5 mobile + a11y pass; a11y + security apply at every step (IMPLEMENTATION_PLAN §0). Release readiness track RR-1..RR-10 stays separate: no V1 step authorises release or public exposure. C4 (records owned by workspace, no global client directory), C5 (writes = workspace members with write right), C6 (email confirmation ≠ pro verification) = owner orientations, awaiting business ratification. V1-1 orientations D1-D9, D16 recorded as proposals in `V1-1_OWNERS_ANIMALS.md` §9.1; no table, RPC, RLS or component before ratification. Owner also confirmed: anatomical reference changes only via curation sources + Rust pipeline until Step 17, no graphic sheet editor, equine draft unpublished until business review, no auto publication; bilan annotations ≠ reference changes.
|
||||
Alt: plan's numeric step order (verification, cabinets, entitlements before any client screen).
|
||||
Status: principle active; C4/C5/C6 + V1-1 orientations pending ratification; P0 merge awaits owner go.
|
||||
|
||||
## BDR-072 | 2026-10-25 | Correction of BDR-041: professional verification = plan Step 9, not Step 11
|
||||
## BDR-072 — Correction of BDR-041: professional verification = plan Step 9, not Step 11 (2026-10-25)
|
||||
|
||||
BDR-041 point (2) names Professional Verification "Step 11"; IMPLEMENTATION_PLAN numbers it Step 9 (Step 10 cabinets, Step 11 entitlement skeleton). Plan numbering kept. BDR-041 left as written (append-only); this entry supersedes its step number only, rest of BDR-041 unchanged. Docs cite Step 9: plan Step 7 note, V1-1 contract §5.2, OPEN_QUESTIONS C6.
|
||||
Status: active.
|
||||
|
||||
## BDR-073 | 2026-10-25 | V1-1 business decisions ratified by owner (BDR-071 proposals → approved)
|
||||
## BDR-073 — V1-1 business decisions ratified by owner (BDR-071 proposals → approved) (2026-10-25)
|
||||
|
||||
Decision (owner brief « V1-1 : ratification des décisions métier et préparation de l'implémentation »): D1 UI term « Clients », client = natural person or structure, Propriétaire/Détenteur/Contact = relation roles ≠ identity, no platform role reused as animal owner. D2/C4 `workspaces` + `workspace_members`, one personal workspace per practitioner, cabinet workspaces later w/o destructive transfer, no global directory, no cross-practitioner visibility, no sharing/invitations/cabinet perms in V1-1. D3 person | structure. D4 required = display name (person) / dénomination (structure), rest optional, no silent default country, no forced email/phone. D4a optional first/last names allowed, display name stays required reference, contract sets priority rule. D5 exactly 9 contract species + « Autre » w/ required detail; species ≠ sheet; equine draft never auto-published. D6 required name, species, sex w/ explicit unknown; optional breed, full birth date when known, year alone; D6a extras (neutering, identification, colour, notes, death date) + weight, photo deferred; no full vet record. D6b year never becomes date, precision kept, CHECK + tests. D7 many-to-many w/ explicit role, co-ownership, animal w/o owner OK, always in valid workspace, no fake client, never cross-workspace. D7a history: start date when known + nullable `ended_at`; no incoherent current duplicates, successive allowed; owner/keeper change never deletes history silently. D8 archive read-only reversible, relations kept, no cascade client→animals, archive ≠ erasure, no retention invented. D9/D9a temporary DEV guard vs account deletion leaving incoherent data, never permanent ban; lifecycle later. C5 V1-1 writes = practitioner in own personal workspace; finished bilans never changed silently. C6 email confirmed ≠ pro verified ≠ platform role; verification = Step 9. D16 staff no ordinary access, no admin screen, no impersonation/support access in V1-1; exceptional access = separate audited policy before publication. D15 technical caps ≠ commercial quotas; thresholds proposed before RPCs. Naming: explicit nomenclature, no generic `owner_id`.
|
||||
Still open: D10-D14, D17 (UI); technical design (SQL/RLS/RPC, N1-N9, D15 thresholds, U1-U3) awaits owner validation at V1-1 preparation checkpoint; no migration before. Contract restructured: verification now §6.2 (BDR-072 cites old §5.2).
|
||||
Alt: keep proposals open; global client record (2026-10-08 plan Step 12); `owner_user_id` column instead of workspaces.
|
||||
Status: active. Branch `feature/v1-1-clients-animals` off develop 5502617. Contract `docs/development/V1-1_OWNERS_ANIMALS.md` §13.1.
|
||||
|
||||
## BDR-074 | 2026-10-25 | V1-1 architecture + N1-N9 validated by owner; V1-1.1 M1 workspaces built in isolation
|
||||
## BDR-074 — V1-1 architecture + N1-N9 validated by owner; V1-1.1 M1 workspaces built in isolation (2026-10-25)
|
||||
|
||||
Decision (owner brief « Validation du contrat V1-1 et autorisation de V1-1.1 Workspaces »): V1-1 model accepted as target (workspaces + members, one personal ws per practitioner, cabinets later as shared ws, no organizations table, isolation per ws, clients person|structure, animals per ws, N-N relations, composite FKs, D-R7 TS forms + SQL CHECK boundary, RLS at creation, RPC writes). 6-step split accepted; only V1-1.1 authorised. N1 9 species + other, rows not enum, ids unchanged (Rust species_id free string, SQL CHECK fits). N2 no first/last names. N3 client notes deferred. N4 CHANGED: logical voiding (`voided_at`, `void_animal_client_relation`) ≠ end; voided never shown current/former, no invented `ended_on`, minimised audit; delete RPC dropped. N5 dates optional, never invented, ordered; CHECKs written in contract §5.3. N6 caps approved, write budget PER WORKSPACE (1000/h, 5000/day), concurrency-safe (no bare count+insert), mechanism fixed with M2. N7 service_role minimisation w/o claiming admin paths closed; existing tables/global privileges untouched. N8 sex none preselected. N9 no staff general view; audit = technical ids, op, time, result, bounded correlation; metadata `{workspace_id}` only (relation_role dropped). D10-D14, D17, U1-U3 stay contract-level; tab-bar contradiction → V1-1.3.
|
||||
M1 as built (`20261025100000_workspaces.sql`): creation = server init in sign-up tx (trigger on profiles → `private.ensure_personal_workspace` one-statement CTE, ON CONFLICT on named unique `workspaces_personal_user_unique`); deferred constraint triggers `workspaces_personal_holder`/`workspace_members_personal_holder` (personal ws = exactly its account as holder, any writer); backfill once; `caller_workspace_ids` (active + email confirmed, auth.uid only) EXECUTE authenticated; `writable_workspace_ids` EXECUTE none; revoke all incl. service_role on new tables/functions; log_event correlation cap + NOT VALID CHECK.
|
||||
@@ -551,7 +571,7 @@ Deviations: `packages/supabase/src/workspaces.ts` → V1-1.2 (no consumer); `db:
|
||||
Alt: workspace created at first authorised login (client-triggered, forgeable timing, partial-state risk); invariant only by grants (owner-role bugs undetected); per-actor budget (cabinet-blind).
|
||||
Status: active. M1 not applied to DEV (owner action, SUPABASE.md §3.3). Contract §5.3, §8.1, §9, §10, §13.2.
|
||||
|
||||
## BDR-075 | 2026-10-25 | V1-1.1 validated; V1-1.2 M2 clients built: budget counter, divergent replay, C-lower fold, sandbox tool
|
||||
## BDR-075 — V1-1.1 validated; V1-1.2 M2 clients built: budget counter, divergent replay, C-lower fold, sandbox tool (2026-10-25)
|
||||
|
||||
Decision (owner brief « Validation V1-1.1 et autorisation V1-1.2 Données clients »): V1-1.1 accepted (M1, grants, RLS, tests); MEDIUM scanner findings non-blocking, trust boundary kept documented; service_role / GoTrue admin indirect access never claimed closed. Sandbox tool kept in repo: `scripts/db-sandbox.sh` (`pnpm db:sandbox`), rootless, loopback, own ports, no volume, generated secrets outside Git, CLI runners via `--db-url`. M1 on DEV = owner procedure (SUPABASE.md §3.3), not Claude.
|
||||
M2 as built (`20261025110000_clients.sql`): budget = owner's transactional counter per workspace: `private.workspace_write_budgets` row upserted by `private.consume_write_budget`, fixed UTC hour/day windows (restart at 1 in a new window; 1000th passes, 1001st `rate_limited`; up to 2000 across an hour boundary, day 5000 holds), called LAST in every write RPC → lock order workspace → (animal → client in M3) → budget, no cycle; refused / replayed / no-op not counted (rollback). Divergent replay: `create_request_digest` (sha256 of normalised content, not API-readable) → `request_conflict`. Fold = unaccent then `lower(... collate "C")` (ASCII only) for PGlite/ICU parity. `search_clients` without `current_animal_count` until M3. Text rule via `private.is_clean_text`. Access layer → V1-1.5.
|
||||
@@ -559,32 +579,32 @@ Measured: search 20k clients p95 21 ms (no trigram index); held budget row delay
|
||||
Alt: count audit rows per workspace (needs index on metadata, count+insert race without extra lock); rolling windows (owner chose UTC windows); accept divergent replay as replay (silent divergence).
|
||||
Status: active. M1+M2 not on DEV.
|
||||
|
||||
## BDR-076 | 2026-10-25 | V1-1.2 validated; V1-1.3 UI foundations: native modal dialog, Playwright + axe on sandbox
|
||||
## BDR-076 — V1-1.2 validated; V1-1.3 UI foundations: native modal dialog, Playwright + axe on sandbox (2026-10-25)
|
||||
|
||||
Decision (owner brief « Validation V1-1.2 et autorisation V1-1.3 Socle UI »): V1-1.2 accepted (M1+M2 on isolated stack, budget 1000/h 5000/day UTC fixed windows, not to reopen without defect). D13 built on platform `<dialog>` + `showModal()` (`components/ui/ModalDialog.tsx`): no a11y primitive in deps, browser modal = proven one, no hand-written trap. Never self-closes: Escape keydown cancelled → onClose, cancel → onClose, forced close reported. First tabbable focused explicitly. Restore after commit (microtask) to opener else first control of nearest surviving container. Tab past last control → browser UI one step (platform; kept). Dialog: aria-labelledby + optional description. Drawer on same primitive, closes at lg. D14: Playwright 1.64.1 + axe 4.14.0 exact dev deps. Owner choices this run: e2e backend = sandbox (not DEV), `pnpm e2e:ui` + `pnpm e2e:shell`, drawer aligned, check:all runs e2e:ui if Chromium present else SKIPPED. D11: no tab bar in V1-1.3, three-way comparison in contract §11.6, decision before V1-1.6.
|
||||
Alt: `inert` + custom Tab loop (artisanal, contract's first wording); focus-trap / Radix (new dep); e2e on DEV (writes sessions to existing accounts); route-stubbed backend (not real GoTrue).
|
||||
Status: active. Contract §11.6, BROWSER_TESTS.md.
|
||||
|
||||
## BDR-077 | 2026-10-26 | V1-1.3 validated; V1-1.4 M3 animals + relations built: states, caps, lock order, scoped axe exceptions
|
||||
## BDR-077 — V1-1.3 validated; V1-1.4 M3 animals + relations built: states, caps, lock order, scoped axe exceptions (2026-10-26)
|
||||
|
||||
Decision (owner brief « Validation V1-1.3 et autorisation V1-1.4 Animaux et relations »): V1-1.3 accepted (native dialog, Playwright + axe, defects fixed); no JS focus trap without shown defect; D11 still open, 3 options before V1-1.6, none default. M3 `20261026100000_animals_relations.sql` as built (contract §8.3): species 8 + other rows (equine unchanged, rows not enum, Rust untouched); animals w/ D6b CHECKs, sex no default; relations w/ composite FKs (not deferrable), partial unique index current = `ended_at` and `voided_at` null; states current / ended (date known or unknown, `ended_at` discriminates, no contract change) / voided (frozen, shown nowhere). Caps: current ≤ 20 excludes ended+voided; totals 200/animal + 100 000/ws count every row (create-void loop bounded). `create_animal` + relation = 2 budget units (2 audit rows), relation reuses animal request id. Relation replay answered before `archived` (idempotence). Lock order M2+M3: workspace → animal → relation → client → budget last; relation RPCs read target ws unlocked among writable first (no lock outside ws). `search_animals` filter = `species_filter` (PG forbids param named like output col). `list_client_animals` cursor `sort_key` = '0'/'1' + name_key. Helpers `utc_tomorrow(timestamptz)` (pure, testable 31 Dec), parsers, `lock_relation_for_write`. No id-immutability trigger: privileged SQL may repoint within ws / move relation-less animal (§4 evolution path); composite FKs forbid cross-ws. Access layer → UI steps. Brief §2 follow-ups: axe KNOWN = rule + selector + opening markup + route; check:all prints PASSED / SKIPPED / NOT RUN, FAILED stage on error.
|
||||
Alt: 1 budget unit per create_animal (undercounts audit rows); totals excluding voided (unbounded create-void loop); replay after archived check (retry of committed create fails); trigger freezing ids (blocks §4 transfer path); keep `^dl$` route-free exceptions (new screens inherit).
|
||||
Status: active. M1-M3 not on DEV; procedure SUPABASE.md §3.3 (owner runs).
|
||||
|
||||
## BDR-078 | 2026-10-26 | V1-1.4 validated; V1-1.5 client screens: owner U1/U2 choices, workspace in authStore, leave guard on links
|
||||
## BDR-078 — V1-1.4 validated; V1-1.5 client screens: owner U1/U2 choices, workspace in authStore, leave guard on links (2026-10-26)
|
||||
|
||||
Decision (owner brief « Validation V1-1.4 et autorisation V1-1.5 Interface Clients »): V1-1.4 accepted (species_filter + replay order in scope). Owner choices asked before UI: U1 « Afficher plus » keyset (25 + 1 probe row, no count), U2 one « Afficher les archivés » switch, client page animals read-only (list_client_animals, no link/add), « premier animal » section → V1-1.6. Built: access layer `packages/supabase/src/{records,workspaces,clients,species}.ts` (closed RecordFailure = §9.4 kinds + session_expired + network; Zod on RPC answers; read by id explicit columns, non-uuid → null w/o request); personal workspace in authStore (loading/ready/inactive/unconfirmed/missing/error; account change resets profile+roles+avatar+workspace in one set; late answers of previous user dropped; ready kept during same-user re-read); RequireWorkspace remounts routes per workspace; leave guard = beforeunload + AppLayout capture on in-app links (ModalDialog), back/forward not interceptable (documented); heading focus on open (callback ref, waits drawer close); request id per form mount via generateUuid (getRandomValues; LAN http has no randomUUID). Shell suite: no HTML reporter (kept typed passwords).
|
||||
Alt: numbered pages (needs count), tabs for archived, data-router migration for blocking, global data cache lib, storing search term (PII) to survive back nav.
|
||||
Status: active. Client screens not checked on DEV (M1-M3 not applied; owner).
|
||||
|
||||
## BDR-079 | 2026-10-26 | V1-1.5 validated; V1-1.6 animal screens: D11 drawer only, first animal from client page, no default role, in-page link panel
|
||||
## BDR-079 — V1-1.5 validated; V1-1.6 animal screens: D11 drawer only, first animal from client page, no default role, in-page link panel (2026-10-26)
|
||||
|
||||
Decision (owner brief « Validation V1-1.5 et autorisation V1-1.6 Interface Animaux et clôture »): V1-1.5 accepted; reserves kept as product follow-up (search not kept on back, E.164 display, back/forward not guarded); no complex navigation manager for them. D11 = drawer only for V1-1, mockup tab bar not reproduced (later UX subject, mockup unchanged). Owner answers before UI: first animal from client page (« Ajouter un (premier) animal » → /app/animals/new, client id in navigation state, never URL, re-read and checked active; one atomic create_animal with relation; client form untouched); no relation role preselected (like sex N8); link client/animal = in-page panel (no modal form, contract §11.4), end/dates/void = ModalDialog confirmations pending until write + reload; U3 = full date fills and locks year. D12 tiles outside brief → not built, stays open. Built: access `animals.ts`, `relations.ts` (relations read by one select with client embedded via `animal_client_relations_client_fk`, `voided_at is null`, limit 200); one RequireWorkspace above clients + animals holding SpeciesProvider (species read once per workspace, dropped on account change); conflict/not_found on a relation write → reload + stale message (voided elsewhere surfaces as conflict: lock order archived → revision → voided). No new business rule in TS or Rust: RPCs decide, TS = D-R7 checks + display.
|
||||
Alt: section in client create form with two-call resume (contract §11.1 text; changes client form); role owner preselected; relation forms in modal or new routes; client id in query string; per-component species fetch; new `voided` failure kind (needs M3 change).
|
||||
Status: active. Not checked on DEV (M1-M3 pending, owner).
|
||||
|
||||
## BDR-080 | 2026-10-26 | V1-1.6 validated; DEV procedure: restore check on sandbox, fingerprints, e2e:avatar out of the run
|
||||
## BDR-080 — V1-1 DEV recette rehearsal only: restore check on sandbox db, md5 fingerprints, e2e:avatar excluded (2026-10-26)
|
||||
|
||||
Decision (owner brief « Validation finale V1-1 et préparation de la recette DEV »): V1-1.6 + V1-1 closure limits accepted; Claude reads DEV only, owner runs backup, `migration up`, acceptance, merge go. SUPABASE.md §3.3 rewritten: SQL through read-only helpers (`default_transaction_read_only`), step 2 counts + md5 row fingerprints + structure counts saved, Storage bytes by `docker cp …:/mnt -` tar, step 3b restore into `restore_check_v1_1` on sandbox db (same image) instead of DEV server, post.sql (workspaces, holders, species, grants, pgtap), before/after diff with exact expected deltas, `supabase status -o env | grep API_URL` (default output prints keys). `e2e:avatar` removed from run: writes beyond fixture. Browser acceptance = brief §11 (19 lines).
|
||||
Decision (owner brief « Validation finale V1-1 et préparation de la recette DEV »), scope = V1-1 recette on DEV only: closure limits accepted; owner runs backup, `migration up`, acceptance, merge go, Claude reads DEV. SUPABASE.md §3.3 rewritten: SQL through read-only helpers (`default_transaction_read_only`), step 2 counts + md5 row fingerprints + structure counts saved, Storage bytes by `docker cp …:/mnt -` tar, step 3b restore into `restore_check_v1_1` on sandbox db (same image) instead of DEV server, post.sql (workspaces, holders, species, grants, pgtap), before/after diff with exact expected deltas, `supabase status -o env | grep API_URL` (default output prints keys). `e2e:avatar` removed from run: writes beyond fixture. Browser acceptance = brief §11 (19 lines).
|
||||
Alt: createdb scratch on DEV server (rehearsed form, but writes DEV server, typo risk on dropdb); throwaway postgres container (unrehearsed init); cold volume copy (stops DEV, restore = volume overwrite); keep e2e:avatar (touches bob + purge queue).
|
||||
Status: active. Steps 0-4 not run on DEV (owner).
|
||||
+60
-41
@@ -1,10 +1,29 @@
|
||||
---
|
||||
format: 2
|
||||
type: evals_registry
|
||||
entry_prefix: EVAL
|
||||
schema:
|
||||
id: EVAL-XXX
|
||||
date: YYYY-MM-DD
|
||||
output: string (what was produced)
|
||||
method: string (how it was evaluated - manual read, test, benchmark, user feedback)
|
||||
anomalies: list of strings (what was wrong, missing, surprising)
|
||||
action: [keep | correct | deprecate]
|
||||
rules:
|
||||
- Log an eval whenever you validate the quality of something Claude produced (report, audit, plan, generated code).
|
||||
- Action keep - the output is fit for purpose as-is.
|
||||
- Action correct - needs revision; capture what.
|
||||
- Action deprecate - the approach itself is flawed; link to the decision that replaces it.
|
||||
- Entries in English, caveman format (BDR-009): drop articles + filler, fragments OK, technical terms exact.
|
||||
---
|
||||
|
||||
# Evals Registry
|
||||
|
||||
Format: EVAL-XXX | Date | What evaluated | Method | Result | Anomalies | Action
|
||||
|
||||
---
|
||||
|
||||
## EVAL-001 | 2026-05-18 | Scaffold build + test pass
|
||||
## EVAL-001 — Scaffold build + test pass (2026-05-18)
|
||||
|
||||
Method: pnpm install → pnpm build → pnpm test:run → pnpm typecheck.
|
||||
Result: all pass, 0 errors.
|
||||
@@ -13,7 +32,7 @@ Action: document in BDR-007, BLK-001.
|
||||
|
||||
---
|
||||
|
||||
## EVAL-002 | 2026-05-20 | B3 i18n — code review caught hardcoded FR in PDF import
|
||||
## EVAL-002 — B3 i18n — code review caught hardcoded FR in PDF import (2026-05-20)
|
||||
|
||||
Method: cavecrew-reviewer ran against full diff `0a05c47..HEAD` after self-review + analyzer agent both reported CLEAN.
|
||||
Result: reviewer flagged 3 CRITICAL: pdf/import.ts:9, pdf/attachment.ts:9-10, app/routes/HomeRoute.tsx:32 — hardcoded FR error messages leaking to EN UI.
|
||||
@@ -22,42 +41,42 @@ Action: fixed in d602726+next via typed ImportError discriminant (BDR-015). Futu
|
||||
|
||||
---
|
||||
|
||||
## EVAL-003 | 2026-05-21 | PDF vet-marker ⚠ WinAnsi crash slipped past CI
|
||||
## EVAL-003 — PDF vet-marker ⚠ WinAnsi crash slipped past CI (2026-05-21)
|
||||
|
||||
Method: user manual export of a v2.0 horse report containing requires_vet_referral leaves → `EditorRoute.tsx:263 PDF export failed Error: WinAnsi cannot encode "⚠" (0x26a0)`.
|
||||
Result: 154/154 tests stayed green; bug shipped to user-facing path. Static signal absent (the ⚠ literal was visible in the source but typecheck/lint don't flag font-encoding issues).
|
||||
Anomaly: pdf.roundtrip.test.ts exercised export with empty observations + no vet findings. The ⚠ prefix was added in 60e1b04-era (`observationPage.ts:407` ternary) without a regression case covering a flagged leaf.
|
||||
Action: hotfix swapped ⚠ → `(!) ` (WinAnsi-safe). Added regression `vet-referral marker is encodable by the body font` that calls `widthOfTextAtSize` on a prefixed label — would catch any future non-WinAnsi marker. LRN-021 captured the pdf-lib StandardFonts WinAnsi limitation. Follow-up: switch PDF body to embedded TTF (Inter/Fraunces per CLAUDE.md spec) so the catalog can carry arbitrary glyphs — out of hotfix scope.
|
||||
|
||||
## EVAL-004 | 2026-07-12 | Tour sweep converged 3 it. — agent spend-limit deaths resumable
|
||||
## EVAL-004 — Tour sweep converged 3 it. — agent spend-limit deaths resumable (2026-07-12)
|
||||
|
||||
Method: /tour full pipeline on faunosteo — semgrep floor ×3 + cso posture (it1) + full clean audit + fresh independent re-verify + doc-syncer. 13 fixed / 10 open residuals / 6 bugs quarantined; 11 commits on unmerged chore/tour-2026-07-12.
|
||||
Result: re-verify PASS (0 findings on 20 modified files); checks green throughout (typecheck, lint 0, 174/174, build, docker run non-root). Convergence honest: it2 surfaced 1 new tuning note (min-release-age 1440 < 10080 rec) → triaged open → it3 semgrep identical → converged at 3-iteration bound.
|
||||
Anomaly: both Phase A agents died mid-run on "monthly spend limit" — SendMessage to same agentId resumed from transcript, zero rework. PostToolUse hook false-positived 3× on 'dangerouslySetInnerHTML' as prose inside audit REPORTS (not code).
|
||||
Action: none blocking. Consider excluding .claude/audits/*.md from sink-pattern hook scan.
|
||||
|
||||
## EVAL-005 | 2026-10-08 | Step 1 characterisation suite (91 cases)
|
||||
## EVAL-005 — Step 1 characterisation suite (91 cases) (2026-10-08)
|
||||
|
||||
Method: 7 files on real assets (SVG, catalog, fixtures), oracle = audit tables (06 §4, 05 §2.4). Run typecheck/test/lint/build.
|
||||
Result: 271/271 green, 0 src change. Audit figures all confirmed (26 mappings score 0, 792/612/41, 48 attrs…).
|
||||
Anomalies: 4 assertions wrong on first run, all test-side (census regex, stale closure, ZONES drawn as bullet rows not ' · ' line, attachment names in object streams). None app-side.
|
||||
Action: LRN-033. Known quirks pinned as "KNOWN:" tests (orphan findings, no_attachment cause lost, sphenoid id, fuzzy FR pairs).
|
||||
|
||||
## EVAL-006 | 2026-10-08 | Step 3 Supabase foundation — PGlite suite
|
||||
## EVAL-006 — Step 3 Supabase foundation — PGlite suite (2026-10-08)
|
||||
|
||||
Method: 4 pgTAP files (81 checks: schema/privileges 24, profiles RLS 17, platform roles 28, audit 12) + schema↔types (6) + client (2) on PGlite; root typecheck/lint/build; app suite.
|
||||
Result: all green first run except plan count (27→28) and pgtap-in-public polluting function census; 278 app + 13 package tests. Zero app behaviour change.
|
||||
Anomalies: `set_config` rows appear in TAP line capture (noise, filtered by regex). `now()` constant in tx broke naive updated_at>created_at assertion.
|
||||
Action: LRN-035/036. Not executed: real Supabase image (`supabase test db`), `gen types` diff, seed.sql (needs auth.identities + extensions.crypt), REST manual script. Flagged in report + BLK-006.
|
||||
|
||||
## EVAL-007 | 2026-10-08 | Step 3 on the real Supabase stack
|
||||
## EVAL-007 — Step 3 on the real Supabase stack (2026-10-08)
|
||||
|
||||
Method: `supabase start` (postgres 17.11.0.004), `supabase test db`, `gen types --local` diff, REST curl script (SUPABASE.md §8) with seed users, psql on audit, `db reset`.
|
||||
Result: migrations + seed apply from zero; pgTAP 81/81 after fix; REST: alice 1 row, anon 42501, self-deactivate 42501 (column grant), self-grant 42501 (RPC message), cross-row PATCH 0 rows, owner grant → uuid, alice sees her role, owner reads 3 profiles; audit shows system bootstrap + owner grant.
|
||||
Anomalies: (1) 6 pgTAP counts assumed empty DB — seed rows on real stack (PGlite runs no seed) → scoped to fixture ids + neutralise foreign owners before last-owner test. (2) CLI gen output unformatted + `ComputedFields: never`, no `__InternalSupabase` → hand-written file replaced by generated+prettier; scripts pipe prettier. PGlite harness had hidden both: environment parity gap, not logic gap.
|
||||
Action: LRN-037 (tests must be seed-agnostic; generated files via deterministic formatter). BLK-006 resolved.
|
||||
|
||||
## EVAL-008 | 2026-10-08 | Step 4 sheet model — domain tests, pgTAP both engines, fresh verifier + security gates
|
||||
## EVAL-008 — Step 4 sheet model — domain tests, pgTAP both engines, fresh verifier + security gates (2026-10-08)
|
||||
|
||||
Method: packages/domain 61 vitest (schema 29 + integrity 32, one per rule code); pgTAP 005 (127 checks) + 001 census on PGlite and real stack (`db reset`, `db test` 210/210, `gen types` diff clean); root check (typecheck, 356 tests, lint 0, build); fresh verifier (contract C1–C13) + security-auditor (semgrep 725 rules 0 findings + checklist).
|
||||
Result: first gate pass → verifier ECARTS(5), security BLOCK(1): private EXECUTE not revoked (BLK-007), visibility change unaudited, 7 RPCs without non-editor denial test, doc/code mismatches, 75-line SQL function, `any` suppression in a test. All fixed same session: +32 pgTAP checks, hardening migration, visibility RPC, caps, authz-first, SQL check split in 4 functions, `set()/unset()` typed mutations. Second pass: fresh verifier (pending at write time).
|
||||
@@ -65,7 +84,7 @@ Anomalies: 6 test-side fixes on first pgTAP run (RLS hides rows → "no change"
|
||||
Action: LRN-038/039/040, BLK-007. Keep the two-gate pass on every migration step.
|
||||
|
||||
|
||||
## EVAL-009 | 2026-10-09 | Step 4b equine import — importer tests, pgTAP both engines, Docker build, gates
|
||||
## EVAL-009 — Step 4b equine import — importer tests, pgTAP both engines, Docker build, gates (2026-10-09)
|
||||
|
||||
Method: packages/anatomy 30 vitest (counts in=out on both sides, special cases, determinism, golden artifacts, guards); pgTAP 001–007 on PGlite and real stack (`db reset`, `db test` 256/256, `gen types` diff clean); root check (61+30+20+278, lint 0, build); `docker build` of the app image; Storage API end-to-end (owner 400 before confirmation → 200 after, alice/anon 400); fresh verifier (C1–C12) + security-auditor (semgrep 130 rules, 0 findings).
|
||||
Result: first pass verifier ECARTS(4) (self-referential in=out control, undeclared importer-authored labels, docs vs literal sql_paths, silent FR→EN fallback) + security PASS with MEDIUM hash-claim bypass (register_sheet_asset accepts any sha256 → editor reads foreign objects). All fixed: `uploaded_at` + `confirm_sheet_asset_upload` (service role) required by the read predicate, bob-claims-hash pgTAP, authored-label anomalies (27 anomalies now), seeds-listed test, Dockerfile missing workspace manifests (found by building, not by the gates).
|
||||
@@ -74,7 +93,7 @@ Action: fresh verifier re-dispatched on the delta; BDR-034, LRN-041.
|
||||
|
||||
---
|
||||
|
||||
## EVAL-010 | 2026-10-10 | Step 4c equine curation — research agents, changeset, gates
|
||||
## EVAL-010 — Step 4c equine curation — research agents, changeset, gates (2026-10-10)
|
||||
|
||||
Method: 4 research agents (skull, axial, limbs, osteo/legal), every citation tagged VERIFIED-fetched/snippet/UNVERIFIED; changeset authored in scratch python (44 changes / 679 ops / 48 refs) → pipeline Zod + 20 integrity rules; anatomy 100 vitest (ops, rename propagation, overlay, golden), pgTAP 001–008 on PGlite and real stack (`db reset`, `db test` 267/267, `gen types` diff clean); root check (68+21+100+278, lint 0, build); `docker build`; Storage e2e after upload (owner 200, alice/anon 400); gridded `magick` crops to verify point positions; fresh verifier ×3 + security-auditor ×1.
|
||||
Result: verifier pass 1 ECARTS(4): B changes left targets `inherited` (CHG-008/032/039 + partials), 3 stale doc numbers, lockfile outside contract scope (orchestrator omission), eslint-disable any in a test → executor: applier rule (B/C ⇒ touched findings/annotations `to_confirm`, `reviewed` refused in B/C), typed test reads, docs. Pass 2 ECARTS(2): JSAVA citation without author (completed from the PDF: Le Roux & Carstens 2018, DOI), DEPLOY.md stale `faunosteo-web`. Pass 3 ECARTS(1): 3 stale doc lines (migration list, "two assets", CLAUDE.md migrations) → fixed by hand, cap of 3 verifier passes reached, not re-verified. Security PASS, LOW: SQL gate did not check reference url scheme → `reference.url.scheme` added (migration still unmerged, pgTAP 008 10 cases); `.env.example` COMPOSE_PROJECT_NAME=osteo-report overrides compose `name:` → file denied to Claude, user action.
|
||||
@@ -83,14 +102,14 @@ Action: user validation of the draft content (REVIEW-REPORT §10: 11 questions);
|
||||
|
||||
---
|
||||
|
||||
## EVAL-011 | 2026-10-10 | Step 5 app on the canonical sheet — suites on the bundled sheet, archive PDFs, gates
|
||||
## EVAL-011 — Step 5 app on the canonical sheet — suites on the bundled sheet, archive PDFs, gates (2026-10-10)
|
||||
|
||||
Method: golden v2 PDFs frozen from the old pipeline before any change; suites rewritten on the bundled draft (domain 94, anatomy 107, supabase 21, app 168+: service branches 10/5/12/1, store + v2 draft migration, provider, canvas, pickers, card, route click chain, PDF v3 roundtrip FR/EN + both v2 fixtures + synthetic removed/unknown ids); root check, vite builds none/draft (grep of a draft label in dist = 0/1), docker build, real stack 267/267 + types; legacy-vs-app marker style diff by the verifier (0 differences); fresh verifier ×3 + security-auditor ×1.
|
||||
Result: verifier pass 1 ECARTS(36) = 4 real (golden test not pinning the new generated files, EditorRoute 398 lines, 5 stale doc lines, one eslint-disable) + my contract omissions (scope files, deleted legacy suites) + floor noise ("species" matched "spec"); pass 2 ECARTS(4) = replacement assertions missing for 4 deleted suites; pass 3 ECARTS(4) = doc counts + 3 more suites' assertions (PDF conclusion/metadata/attachment structure, ObservationCard, persistence). All closed by executors (two) and by hand (docs); cap of 3 passes reached → last lot not re-verified. Security PASS with LOW: prototype-key lookup on untrusted ids (fixed: Object.hasOwn + test), unbounded inflate on the primary attachment path + no file cap (fixed: 16 MiB attachment, 50 MB PDF + test), denylist SVG sanitiser acceptable while assets are repo-built (allowlist before Storage-served assets, Step 13).
|
||||
Anomalies: executor ran `pnpm format` repo-wide and reverted by hand (watch for `format` in briefs); foreign JSON attachment (no version) surfaced as incompatible_version → fixed to no_attachment (legacy message); verifier floor counts deleted legacy tests as findings until CLARIFICATIONS name them.
|
||||
Action: user validation of Step 5 (manual FR/EN flow, visual before/after); BDR-038, LRN-043.
|
||||
|
||||
## EVAL-012 | 2026-10-10 | Step 5 addendum during user manual validation — per-leaf migration tests, archive check tool, final controls
|
||||
## EVAL-012 — Step 5 addendum during user manual validation — per-leaf migration tests, archive check tool, final controls (2026-10-10)
|
||||
|
||||
Method: user asked (while testing) for final controls on last lot + per-leaf test beyond the map + simple v2/v3 PDF comparison method. Built: anatomy test all 612 legacy leaves through `migrateReportV2ToV3` with committed map vs draft document (442 identical / 141 moved = 134 category + 7 leaf renames / 29 removed, snapshots + vet flag verbatim, 26 annotations on right view, v3 re-read stable); app test same leaves via `sheetIndex.nodeAt` + v3 PDF roundtrip; CLI `pnpm report:compare` (pure module + entry, `readAttachedDocument` split out of `extractReportJson`, behaviour unchanged). Contract criteria 16-18 added, gates MET, fresh verifier ×3 + security ×2.
|
||||
Result: verifier pass 1 ECARTS(2) = floor only (EVAL-011 prose "eslint-disable" false positive → CLARIFICATIONS; 11 dropped `regionFromLabel` assertions → new `legacy.regions.test.ts` on `inferRegionCode`); security PASS + 2 MEDIUM (terminal control chars in untrusted strings; free text printed by default) → executor: `esc()` + `--full` privacy default; pass 2 ECARTS(1) (`--diff` still clear text, JSON.parse message echoed attachment fragment) + security PASS 4 LOW → executor: diff follows `--full`, generic reason, Cc/Cf escaping, regular files only; pass 3 CONFORME. Workspace 94/21/119/181, docker build OK.
|
||||
@@ -100,7 +119,7 @@ Action: await user manual validation of Step 5; residuals in TODO follow-up.
|
||||
|
||||
---
|
||||
|
||||
## EVAL-013 | 2026-10-11 | Step 6 autonomous PDF archives — 5 phases by executors, 3 verifier passes, 4 security audits
|
||||
## EVAL-013 — Step 6 autonomous PDF archives — 5 phases by executors, 3 verifier passes, 4 security audits (2026-10-11)
|
||||
|
||||
Method: analysis (3 analyzers + measurements) challenged by 3 plan-challengers (correctness/robustness/simplicity, 48 findings folded in) → user validation with D7/D8/D13 adjustments → Part II contract (exact types) → one executor per phase (0 freeze goldens, 1 domain, 2 anatomy compose, 3 engine, 4 app) with closed contracts, orchestrator commits → whole-step verifier + security auditor → fix loops.
|
||||
Result: Phase 0 froze 39 goldens (text/images/links per locale × logo mode, view facts) + 2 route characterisation tests with the OLD code; engine reproduced 36 goldens with 0 mismatch (views: data-* 2→0 and hidden-marker titles declared relaxed). Verifier pass 1 ECARTS(31) = all oracle/scope defects of MY contract (grep on parametrised table, xmldom filter, narrow FILE SCOPE, 3 deleted tests with moved coverage) → contract amended → pass 2 CONFORME 13/13. Security pass 1 BLOCK(1) HIGH real + PoC: archived branding URL written unescaped into `/URI` (PDF object injection via `exportFromEnvelope`), +3 MEDIUM/4 LOW → executor fixed (hex URI, strict URL schema, export re-validation, PNG IHDR budget, CSS-escape rules, NaN guard, file.size) → pass 2 PASS but 2 MEDIUM incl. a regression the fix introduced (UTF-16 BOM URI dead in poppler) + PNG double-IHDR bypass → executor → pass 3 PASS + 1 MEDIUM (UPNG nextZero spin on tEXt) → executor (chunk allowlist + IEND) → pass 4 PASS + 3 MEDIUM (UPNG `inflateRaw` spins on truncated IDAT with allowlisted chunks only; IHDR fields unvalidated; zero dimension) → executor: native bounded `inflateFlate` of the IDAT against the exact raw size, IHDR fields, sides ≥ 1, no interlace, raw ≤ 16 MiB → pass 5 focused. Lesson: a third-party decoder on untrusted bytes needs a native oracle in front, not a chunk allowlist. Final: 656 tests (194/21/130/88/223), typecheck, lint, build, docker ×4 green; goldens byte-identical since 8b86b92.
|
||||
@@ -109,159 +128,159 @@ Action: await user manual validation + UX decision on re-export of the kept arch
|
||||
|
||||
---
|
||||
|
||||
## EVAL-014 | 2026-10-11 | Step 6 closure round — manual-test feedback, BLK-009 scanner, final audits
|
||||
## EVAL-014 — Step 6 closure round — manual-test feedback, BLK-009 scanner, final audits (2026-10-11)
|
||||
|
||||
Method: user manual tests round 1 (logos absent, picker blurry) → reproduction attempts (headless Chromium dev/preview/Docker, Firefox 157 via esbuild harness + raw WebDriver BiDi client, CDP LayerTree, LCD-fringe metric, headed runs on the Wayland session) → fixes by executors → user round 2 confirmed both OK → closure decisions → BLK-009 implemented (byte-scan reader, no object streams) → verifier + 2 security audits + 1 fix loop.
|
||||
Result: neither visual defect reproduced here (4 environments, 2 engines, 2 PDF renderers); shipped the environment-independent fixes (branding bundled, no fetch; warnings surfaced) and the user confirmed logos + crisp text. Scanner: verifier CONFORME 7/7; audit 1 PASS + 2 MEDIUM (Chromium DecompressionStream read-ahead defeats the cancel: +2.2 GB on a 4 GiB bomb; ×32 candidate CPU) → executor (16 KiB slice feeding, shared 16 MiB budget, monotonic bounded endstream search, `{` pre-check; 133 pdf tests) → audit 2 focused. Workspace 710 tests, build, docker green.
|
||||
Anomalies: the blur fix of the previous round (will-change) had been marked PARTIALLY MET "desktop by user" — the user's "still blurry" came from that unverified half; this round could not verify real-GPU text rendering either (headless engines render grayscale AA, headed captures failed) → lesson: a screen-rendering defect needs the user's own capture + an A/B recipe early, not days of headless measurement. The Node vitest suite cannot observe browser stream read-ahead: record browser-only bounds as owed manual checks (PDF_IMPORT_HARDENING §5).
|
||||
Action: BLK-009 stays "mitigated, gate open" (BDR-040); Step 6 finished into develop; release/0.2.0 prepped for the user's go.
|
||||
|
||||
## EVAL-015 | 2026-10-11 | Step 7 identity — gates on the whole step
|
||||
## EVAL-015 — Step 7 identity — gates on the whole step (2026-10-11)
|
||||
|
||||
Method: contract with 16 criteria (`2026-10-11-step-07-verify.md`) → fresh verifier; security-auditor (semgrep 159 rules + checklist) on `c746952..HEAD`; headless e2e vs the local stack (playwright-core in scratchpad, Mailpit API); real-stack pgTAP + docker build by the orchestrator.
|
||||
Result: verifier pass 1 ECARTS(2): (a) real gap, `safeNextPath` prefix check let `/\host` and `/<TAB>/host` through (router `location.assign` fallback = open redirect after login) → fixed by resolving against a sentinel origin and rebuilding from parsed parts, 5 new cases; (b) contract regex over-matched other unions (`'google' | 'apple'`, `'fr' | 'en'`) → CHECK scoped. Pass 2 CONFORME 16/16. Security PASS, 1 MEDIUM (same redirect, already fixed) + 4 LOW: 3 closed same session (sign-out failure reported, `reauthentication_needed` phrased, exact prod redirect allowlist documented), 1 pre-existing (TOTP not enforced for staff = documented gap). E2E 20/20. Workspace 763 tests, lint 0, build, docker, real-stack pgTAP 280 green.
|
||||
Anomalies: both gates found the same redirect hole my own tests missed → a prefix check on a URL is never enough, parse it; the auditor misread the sign-out note ("this device") as "everywhere" but the LOW still pointed at a silent failure path worth phrasing. Mockups validated with ChatGPT are not in the repo: the screens follow the written direction and the existing tokens, pixel fidelity unverifiable here.
|
||||
Action: awaiting user validation of Step 7 (manual procedure IDENTITY.md §5); release/0.2.0 still open for the human go.
|
||||
|
||||
## EVAL-016 | 2026-10-12 | Rust-by-default architecture review — 4 analyzers + 3 researchers + 3 plan-challengers
|
||||
## EVAL-016 — Rust-by-default architecture review — 4 analyzers + 3 researchers + 3 plan-challengers (2026-10-12)
|
||||
|
||||
Method: 4 read-only analyzers (domain, anatomy, pdf + app pdf side, app logic + supabase) wrote factual inventories to the scratchpad; 3 general-purpose researchers verified crate versions/maintenance/advisories and Supabase facts on crates.io, RustSec, GitHub, supabase docs (2026-10-12), UNVERIFIED items listed; study rev 1 written from them, committed (6a078da); 3 plan-challengers (correctness FATAL(11), robustness FATAL(11), simplicity CONCERNS(9); 61 findings) → rev 2 with 56 folded, 2 declined with reasons (§0.2).
|
||||
Result: real blockers caught by the gates, not by me: (1) VI.4 deleted TS modules still imported by later-phase TS consumers (pipeline, engine); (2) production CSP `script-src 'self'` refuses wasm, VPS 1 GB compiles images; plus wrong premises: envelope byte-parity (integer-valued floats, insertion order), Prettier identity overstated (hash only compared), `catch_unwind` unusable on wasm32 (panic=abort), serde-wasm-bindgen null-for-absent, parent re-decode breaking the keyless invariant, Step 15 misread as server rendering. Simplicity: 6 crates → 3, dual-run harness → frozen goldens, Landlock + 3 rlimits redundant, constraints generator/schemars/cargo-chef/cargo-audit/infer/img-parts dropped.
|
||||
Anomalies: one analyzer had a read-only `find -exec cat | wc -l` refused (no rule named) and re-ran as `find | xargs wc -l` (already allowed earlier) — reported to the user as a possible workaround; agents flagged writing report files to the scratchpad against their default (orchestrator asked for it). Three challenger claims came from memory not code (json_compatible null, panic=abort, musl mprotect) → folded as "verify at R0/R1".
|
||||
Action: owner validates study + D-R1..D-R14; nothing implemented; CLAUDE.md rule section added; TODO roadmap lines.
|
||||
|
||||
## EVAL-017 | 2026-10-13 | Rust R0 foundation — proofs in the real environment, 3 verifier passes, 3 security passes
|
||||
## EVAL-017 — Rust R0 foundation — proofs in the real environment, 3 verifier passes, 3 security passes (2026-10-13)
|
||||
|
||||
Method: contract `2026-10-13-rust-r0-verify.md` (16 criteria, CHECK/EXPECT) → fresh verifier; security-auditor on `5fec065..HEAD` (semgrep p/security-audit + p/secrets + p/owasp-top-ten + checklist + manual Rust review); all cargo commands through the Docker builder (no Rust on the host); worker sandbox tests + strace derivation inside the Alpine test stage on the release-profile musl binary; wasm proofs in vitest on the built module; CSP proof with the production nginx image + headers in headless Chrome 156.
|
||||
Result: verifier pass 1 ECARTS(2), pass 2 CONFORME 16/16, pass 3 ECARTS(2) — every gap an oracle of MY contract (greps counting comment lines, the contract matching its own regex, the `[gated]` SAFETY form and a second refusal arm moved by the security fixes); code behaviour confirmed by reading each time. Security pass 1 BLOCK(1) HIGH real: shell injection via the `workflow_dispatch` input of release-images.yml, + 6 MEDIUM (shared BuildKit caches, tkill/tgkill without arg filters, core dumps, creds on the runner, no advisories gate, mutable action tag) → fixed; pass 2 PASS but 3 MEDIUM introduced by my fixes (ephemeral builder never used: GITHUB_ENV applied one step too late, silent fallback; `rm -rf "$VAR"`; content reaching the `Broken` outcome via `Reject::Internal`) → fixed; pass 3 PASS, 2 new MEDIUM (unpinned setup-node and `pnpm install` inside the token job) → gates moved to a secret-less job; remaining lows documented as R1/Step 27 follow-ups. Experimental findings (LRN-049): serde_json fast float path (float_roundtrip), traps leave the instance unusable + ESM cache, RLIMIT_CPU soft=hard → SIGKILL, minimal rustup profile, cargo-deny path wildcard, 7 traced syscalls, strace blind once dumpable=0 (marker became a syscall). Final: cargo 12+14 core tests, 9 unit + 16 sandbox worker tests on the release profile, 14 vitest proofs, root `pnpm check` 777 tests green, worker image 8.7 MB read-only/cap-drop, CSP refused/accepted as predicted, floor-guard clean ×3.
|
||||
Anomalies: my contract oracles cost two verifier passes (lesson repeated from EVAL-013: run every CHECK once before dispatch, and re-run them after any fix commit); two of my own security fixes created new findings (an env variable applied too late, a recursive delete through a variable: the exact pattern the destructive-tools rule forbids) → fixes to CI files need the same adversarial pass as code; a scripted edit silently aborted on a rustfmt-reformatted string and the commit went out with the old test (caught by the next build); the `[gated 2026-10-13]` SAFETY markers were placed by me at the auditor's request, not by the owner → surfaced in the report for the owner's confirmation; one security-auditor Bash call (`cat` of two files) was refused twice by the auto-mode hook, the agent used Read instead (reported, no workaround). Not proven here: the Gitea runner (caches, timings, workflow syntax such as job-level env, actions/cache), HTTPS from the worker (no HTTP client before R1), browser-side fresh-instance mechanism (R2).
|
||||
Action: owner validation of R0 (report with proved vs hypothetical); R1 not started.
|
||||
|
||||
## EVAL-018 | 2026-10-13 | R0 correction: native Rust toolchain on the Ubuntu dev server — 2 verifier passes, 2 security passes
|
||||
## EVAL-018 — R0 correction: native Rust toolchain on the Ubuntu dev server — 2 verifier passes, 2 security passes (2026-10-13)
|
||||
|
||||
Method: host audit first (rustup already user-level, 1.99.0 auto-installed by `rustup show`, system deps present, no sudo); installs `--locked`; scripts moved to `scripts/`, `pnpm check:all` gate; contract `2026-10-13-rust-r0-native-verify.md` (11 criteria) dry-run by me before dispatch (3 oracles fixed: comment prose matched a code grep, per-package vitest totals, README phrasing); fresh verifier ×2; security-auditor on `bd9c7d1..6e2bbec` then on the fix commits; full gate run twice (`check-all.log`, `check-all-2.log`).
|
||||
Result: verifier pass 1 ECARTS(2) = floor STUB hits on doc prose "(not implemented)" → reworded; pass 2 CONFORME 11/11, floor clean. Security pass 1 PASS + 1 MEDIUM (no advisory check has ever run: nightly job never executed) + 6 LOW (PATH prepend, `rm -rf "$out"` via variable, prctl comment overstating the kernel contract + i32 into variadic unsigned long, dormant CI triggers, native build.rs exposure, drift gate blind to untracked files) → fixed except the trigger question (owner's CI/CD step); pass 2 PASS + 1 MEDIUM (my ci.yml drift step failed open on a git error: `test -z "$(…)"` drops the exit status) + `--untracked-files=all` + stale comment → fixed (496f549), verified by execution + shellcheck, no third dispatch (3-line change). Numbers: native rust-check 32 s warm / 1 s incremental, cold workspace build 31.5 s, wasm 224 777 B (+64 B vs builder, path strings), 14 proofs, `check:all` 1 min 59 s then 1 min 39 s, 777 Node tests, 16 sandbox tests, allowlist covers the trace, worker read-only `run --check` OK.
|
||||
Anomalies: the R0 note "no cargo on the host" was stale, rustup had been installed 2026-10-12 23:27 (rtk) → always re-audit the host at session start; `rustup show` has a side effect (auto-install) → acceptable here (requested install) but say so; a fix I wrote for one security finding introduced the next MEDIUM (fail-open test) → the EVAL-017 lesson again: CI one-liners need the same scrutiny as code, prefer assign-then-test; the harness clock jumped 01:16 → 09:43 mid-session (timestamps in logs are not durations).
|
||||
Action: owner's final validation of the R0 correction; R1 not started; CI/CD decision separate (trigger mode, runner label, action pinning, advisories cadence).
|
||||
|
||||
## EVAL-019 | 2026-10-13 | Step 8 / R1 files foundation — 2 forks, verifier ×2, security ×5, e2e ×7, browser smoke
|
||||
## EVAL-019 — Step 8 / R1 files foundation — 2 forks, verifier ×2, security ×5, e2e ×7, browser smoke (2026-10-13)
|
||||
|
||||
Method: contract-level `STORAGE.md` written first; migration + pgTAP by me while fork A (Rust loop) and fork B (TS + UI) ran with full context; real-stack e2e (`pnpm e2e:avatar`, worker container, fresh admin user) + headless Chromium smoke (playwright-core in scratchpad, cached chromium, dev server :5174) for the browser canvas path; contract `2026-10-13-step-08-r1-verify.md` (15 criteria, oracles dry-run before dispatch) → fresh verifier; security-auditor on `3f1105b..HEAD` then focused passes on each fix commit; `pnpm check:all` ×4.
|
||||
Result: verifier pass 1 ECARTS(4) = oracle (`for update` row-lock grep) + FILE SCOPE (tracking files, lockfile) → rev 2 → CONFORME 15/15, floor clean. Security pass 1 PASS (2 MEDIUM: ceiling ratchet by rejected rows, cleartext http any host; 9 LOW) → fixed; pass 2 PASS but my fixes introduced 2 MEDIUM (bypassable host check `127.*`/numeric, ceiling undercount vs contract) → fixed; pass 3 BLOCK(1) HIGH: my purge-queue join let begin spam pin the ceiling with claims → ceiling rewritten on bytes present + cap per pending claim; pass 4 PASS (MEDIUM residual: per-account holding) → 64 MiB per-account budget; pass 5 PASS (LOW hygiene) → comments/doc. e2e 5/5 ×7 (found the Storage API 400-as-404 making purge acks loop: added queue-drained assertion); smoke 18/18 desktop+mobile; final: pgTAP 140 (real stack 420 total), app 300, supabase 37, worker 21+11 native, sandbox 16, allowlist = 7 syscalls unchanged, image 11.6 MB.
|
||||
Anomalies: EVAL-017 lesson again ×3 — each security fix needed its own adversarial pass and twice created a new finding (host check, ceiling join); a security control I added became the attack lever (BLOCK). Fork B's `database.types.ts` hand-write matched the generator byte-for-byte except ordering; fork A found the 400/404 only via e2e. `gitflow finish` of R0 and any `.env*` write refused by the harness classifier; `git config` reads refused too. Verifier sandbox intercepted the literal `pnpm lint` (rtk wrapper) → oracle uses the binary path.
|
||||
Action: owner's manual validation (TEST FONCTIONNEL + TEST GRAPHIQUE), owner runs `gitflow finish` for R0 then R1 after validation; no merge, no deploy, release 0.2.0 untouched.
|
||||
|
||||
## EVAL-020 | 2026-10-14 | Rust R2 domain core — 3 plan challengers, 4 forks, verifier, security ×2, CSP proof on the image
|
||||
## EVAL-020 — Rust R2 domain core — 3 plan challengers, 4 forks, verifier, security ×2, CSP proof on the image (2026-10-14)
|
||||
|
||||
Method: plan + contract written first (`.claude/tasks/plans/2026-10-13-rust-r2-domain-core.md`), 3 plan-challengers (correctness, robustness, simplicity) before code; freeze-then-switch: envelopes, Zod output oracles, characterisation and verdict tables written by the TS before trusting Rust; forks A/B/C in worktrees on disjoint files (sheet rules + conformance, report/archive rules, editor rules), runtime + app switch by me, fork D adapted the app suites in tree; browser checks with playwright-core from the scratchpad (dev server, prod build, real image under the DEPLOY CSP); contract `2026-10-14-rust-r2-verify.md` (12 criteria, every oracle dry-run before dispatch) → fresh verifier; security-auditor on the whole range, then a focused pass on the fix commit.
|
||||
Result: challengers 45 findings incl. 1 BLOCKER (degraded editor redirect could overwrite an unread draft) → plan rev 2 before any app code; contracts byte-equal to Zod on first run; forks merged with zero conflicts (one stub replaced); fork D found 2 real src bugs (Node source path under happy-dom, failed quarantine reported as success) → fixed with tests. Verifier: 12/12 MET, ECARTS(2) = floor DELETED_TEST (zoneInteraction suite ported to cargo; R0 skip helper replaced by a stricter global setup) → human micro-gate for the owner. Security: PASS (3 MEDIUM nginx false positives pre-existing, 5 LOW) → by-reference deserialisation (also −134 KB raw / −31 KB gzip module) + literal delete paths. Final: cargo core 135, worker+wasm 32, Node 906 (app 313), pgTAP PGlite 12 files / real stack 446, CSP proof 15/15, check:all green ×3, module 1,046,498 B raw / 340,929 B gzip.
|
||||
Anomalies: worktree base stale (BLK-010); harness decodes `\u` escapes in tool inputs (LRN-054); my first runtime test helper reused the pattern Vite rewrites; the CSP proof first failed on its own harness (EN locale, disclaimer modal, caught compile error logs nothing) — proof scripts need the same dry-run discipline as oracles; a security LOW fix improved size, measure before assuming a cost.
|
||||
Action: owner manual LAN validation, L1 decision, approve the 2 deleted test files (floor), then merge go; R3 next, not started.
|
||||
|
||||
## EVAL-021 | 2026-10-14 | R2 closure — L1 refusal, deletions proof, fresh verifier + security
|
||||
## EVAL-021 — R2 closure — L1 refusal, deletions proof, fresh verifier + security (2026-10-14)
|
||||
|
||||
Method: owner asked to fix L1 (no silent U+FFFD) + prove the 2 approved deletions + checks before merge. Mapped every JSON entry into the core (TS side always `JSON.stringify` → escapes reach Rust as ASCII); preservation costed (own JSON reader + lossless string type ~150 fields) → AskUserQuestion: refusal + quarantine chosen, detailed import wording chosen. Stale-module proof run before `wasm:build` (suites throw `pkg is stale`). Worktrees checked blob by blob vs branch history (60/66 identical, 6 = stub, merged mod lists, 2 lifted `#[ignore]`). Contract `2026-10-14-rust-r2-l1-verify.md` (13 criteria, each dry-run) → fresh verifier; fresh security-auditor on 36316cf..HEAD.
|
||||
Result: verifier CONFORME 13/13 (floor 2 = the approved deletions, authorised by REQUEST); security PASS, 6 LOW: wasm-bindgen `&str` would re-encode a raw lone surrogate (unreachable, JSON.stringify callers; documented invariant), `pretty_json` proof op refuses as invalid_json, scanner not string-aware (classification only), newest-only quarantine slot, archive quarantine failure under full storage lets a later reset remove it (pre-existing R2, reported to owner), semgrep partial parse. Final: core 142, Node 915 (app 320, supabase 40, core-wasm 26), PGlite pgTAP 12 files, real stack 446/446, types no drift, check:all green 1 min 32 s, module 1,040,784 B raw / 339,933 B gzip.
|
||||
Anomalies: refusal broke a test loader (oracle file freezes TS outputs with lone escapes) → loader spells escapes out, never normalises (LRN-055); `cargo deny advisories` (warn-only) shows RUSTSEC-2026-0346/0347/0348 on rustls 0.23.45 (worker, none applicable: no brotli, built-in session cache, no ECH) → bump follow-up; `supabase/.temp/cli-latest` tracked by mistake, rewritten by the CLI, restored; `export PATH=…` denied → absolute `~/.cargo/bin/cargo`; first commit with chained `git config` denied → plain commit OK.
|
||||
Action: gitflow finish into develop (owner authorised after L1 + checks), worktree cleanup (BLK-010), R3 summary only.
|
||||
|
||||
## EVAL-022 | 2026-10-15 | R2 maintenance + R3 anatomy core — challengers, oracles, Chromium, verifier ×2, security ×3
|
||||
## EVAL-022 — R2 maintenance + R3 anatomy core — challengers, oracles, Chromium, verifier ×2, security ×3 (2026-10-15)
|
||||
|
||||
Method: maintenance: AskUserQuestion for B UI, store rewrite + 27 tests, verifier (11/11, floor false positive on `cli-latest`) + security PASS (4 LOW fixed), check:all, merge. R3: 2 analyzers (facts), plan + 3 challengers (FATAL 3 / FATAL 6 / CONCERNS 4; blocker = roxmltree recursion, which I had measured independently) → rev 2; freeze O1–O6 with TS before any change; Rust reader/layer/compose; mutation checks per oracle test; wasm thresholds in fresh instances; app switch; Chromium DOM + 30 screenshots + perf vs develop baseline; CSP proof on image; verifier CONFORME 11/11; security PASS + MEDIUM (prescan closer desync) → fixed → pass 2 PASS (4M differential docs) + LOW (url whitespace) → fixed.
|
||||
Result: all oracles green (O2 exact incl. order, O1/O3 tree-equal, 42 hostile + 10 generated declared or equal, 4 product SVGs untouched); Chromium live trees = O1, 30/30 pixel-identical; module 395.5 KB gz (+56); editor 503 vs 476 ms, detail 143 vs 125 ms (CPU ×4); check:all green.
|
||||
Anomalies: my first prescan had the closer-overlap bug (security caught it, tests did not: corpus lacked overlapped closers); first wasm memory threshold measured leaked sessions (harness artefact) → per-case fresh instance; probe in perf script retained detached nodes (fake leak); `env` and `export` refused by harness → inline env vars; cargo fmt reformat broke python patch anchors ×3 (write whole file or re-read).
|
||||
Action: owner LAN validation (TEST FONCTIONNEL / TEST GRAPHIQUE), owner decisions (EN trigger name, degraded wording), then merge; R4 not started.
|
||||
|
||||
## EVAL-023 | 2026-10-16 | Owner-requested audit of 0279953 + bugfix — independent auditor, 3 challengers + confirm, verifier ×2, security
|
||||
## EVAL-023 — Owner-requested audit of 0279953 + bugfix — independent auditor, 3 challengers + confirm, verifier ×2, security (2026-10-16)
|
||||
|
||||
Method: fresh general-purpose auditor on commit only (5 owner axes); claims re-read in code; /bugfix: plan → 3 blind challengers → rev 2 → confirm pass → rev 3; owner AskUserQuestion ×3 batches; bugfixer; gates.sh 5/5; verifier; security; doc-syncer.
|
||||
Result: audit NOT satisfactory (3 defects: unsaved promise, 4 dead retries, recovery dead end) — all fixed 6371523; app 374 tests, core-wasm 37; verifier pass 1 ECARTS(3) (2 untested surfaces, helper out of scope) → pass 2 CONFORME 12/12; security PASS 2 LOW; docs NONE.
|
||||
Anomalies: previous session's commit + CHANGELOG claimed "never a retry that cannot work" without surface census; challengers converged on dead end the plan fixed only on canvas; confirm pass found offline restart never reaching stopped → copy moved to save banner (owner choice). Executor found latent GC finalizer throw (not fixed).
|
||||
Action: R3 stays unmerged until owner LAN confirmation; R4 not started.
|
||||
|
||||
## EVAL-024 | 2026-10-17 | R3 final checks — measurements, challengers ×3 + confirm, verifier, security, check:all
|
||||
## EVAL-024 — R3 final checks — measurements, challengers ×3 + confirm, verifier, security, check:all (2026-10-17)
|
||||
|
||||
Method: scratch round-trip test (3 golden reports); fuzz agent (37k draft.restore on shipped wasm + 40 worst cases, OOM threshold); GC agent (Node --expose-gc, 50 recoveries, WeakRef probes, mitigations in scratch); owner AskUserQuestion ×3; plan → 3 blind challengers → rev 2 → confirm → rev 3; bugfixer with negative controls; gates.sh 4/4; verifier; security; check:all; doc-syncer.
|
||||
Result: copy restorable in app; loop impossible with real drafts, defended anyway; work-loss paths closed; app 405 tests, check:all green (~75 s cached); verifier CONFORME 10/10 (1 floor ASSERT_DROP = guard test moved, authorized by plan); security PASS 2 LOW; docs NONE.
|
||||
Anomalies: challengers caught trap re-read spending recoveries (2 lenses), BDR-055 contradiction, wrong "parity" cap (50 MiB file vs 16 MiB JSON) only on confirm pass; executor found Retry-during-recovery edge.
|
||||
Action: owner LAN validation, then merge on owner go; no R4, no release, no deploy.
|
||||
|
||||
## EVAL-025 | 2026-10-20 | R4.9 gates — bench, verifier ×3, security ×4, check:all
|
||||
## EVAL-025 — R4.9 gates — bench, verifier ×3, security ×4, check:all (2026-10-20)
|
||||
|
||||
Method: memory bench 3 engines × demo/L × 6 exports + Chromium L 16 + raster control; contract 16 criteria (owner §2 list), fresh verifier per pass; full security gate on 168 R4 source files, then targeted re-gates on each fix; check:all.
|
||||
Result: verifier pass 1 ECARTS(1): core with no feature did not compile (`restore_copy` used gated `pdf::read` const; workspace feature unification via crates/wasm hid it in rust-check/check:all) → gated + no-feature clippy in rust-check; pass 2 ECARTS(1): §6 lacked J2 merge-gate row → added. Security pass 1 BLOCK(1): `.gitleaks.toml` allowlist (R4.1, owner-approved in journal) lacks owner `[gated]` marker → owner action; MEDIUM serve.mjs `--host ""` bound every interface.
|
||||
Anomalies: my first host fix = exact-string denylist → bypassed by `0`, `0::`, `::ffff:0.0.0.0`, scoped `::` (re-gate 1); rebuilt resolve-then-BlockList; re-gate 2 found post-bind check dead for IPv6 (`family` 'IPv6' vs 6) and my fstat-first CLI read opened FIFOs before the type check (regression). Each fix of a gate finding introduced the next finding: 3 re-gates for 2 small fixes. Contract CHECKs used root vitest path (absent): oracle defect.
|
||||
Action: owner checkpoint; floor 21 DELETED_TEST (R4.8 deletions, approved in brief §1) need owner `[gated]` clarification line to clear formally.
|
||||
|
||||
## EVAL-026 | 2026-10-22 | R5.1 freeze + D-R5 study — analyzers ×2, oracle generator, cross-stack digests
|
||||
## EVAL-026 — R5.1 freeze + D-R5 study — analyzers ×2, oracle generator, cross-stack digests (2026-10-22)
|
||||
|
||||
Method: 2 analyzer agents (pipeline inventory 43 files, fingerprint census: producers, consumers, 99 PDFs, docs), both refused to write files (role rule) → orchestrator saved reports; generator test (`MAKE_R5_ORACLES=1`) + freeze re-run green 6/6, anatomy 137, domain 262; Node scripts (matrix, PGlite jsonb) + scratchpad Rust binary on core crate: digests compared value by value; tie census 200k values.
|
||||
Anomalies: R2 oracle test self-referential on number printing (LRN-070) → F1 undetected since R2; docs contradict (BDR-045 vs RUST.md §10.10 / TODO "will change once") → cross-reference added; analyzer inventory counted "10 anomalies" wrong in orchestrator draft (actual 27, records 825 not 690, 16 ledger artifacts) → corrected from oracle counts before commit.
|
||||
Action: F1 fix proposed, owner go; D-R5 recommendation B + aliases; checkpoint delivered, STOP.
|
||||
|
||||
## EVAL-027 | 2026-10-22 | R5.1b + R5.2 gates: check:all, security, verifier
|
||||
## EVAL-027 — R5.1b + R5.2 gates: check:all, security, verifier (2026-10-22)
|
||||
|
||||
Method: check:all green 21:16:39 (app 434, core-wasm 58, domain 262, anatomy 141, supabase 40, curation suites, worker + images); security-auditor semgrep 129 rules / 36 files → PASS, 0 HIGH, 5 LOW; fresh verifier on contract `2026-10-22-rust-r5-f1-importer.md` → CONFORME 12/12 (ran cargo workspace + curation suites + import-equine --check itself, red-before proven by rustc probe).
|
||||
Anomalies: LOW report.rs `Map` index panics on hand-built ImportResult → fixed (get chain) after verdict, importer suite + --check rerun green; LOW quadratic vertebrae scan, symlink-following `listed()` in --check, lint allows (accepted, operator inputs). check:all ran on pre-commit tree (code identical to 03bdb5e). Verifier floor note: plan B.3.5 "(proposal, not implemented)" heading from R5.1, intended.
|
||||
Action: checkpoint R5.2 delivered, STOP before R5.3.
|
||||
|
||||
|
||||
## EVAL-028 | 2026-10-23 | R5.3 gates: fresh verifier ×4 + security; successive passes found real defects
|
||||
## EVAL-028 — R5.3 gates: fresh verifier ×4 + security; successive passes found real defects (2026-10-23)
|
||||
|
||||
Method: check:all after each fix round; security-auditor (semgrep 725 rules, checklist) → PASS, 6 LOW (3 fixed: Map index, destination claimed + canonicalised, INIT_CWD absolute only); fresh verifier each round, no history. Pass 1 ECARTS(1) (floor on a plan heading) + 2 unreachable divergences aligned; pass 2 null-on-optional (LRN-072); pass 3 (first attempt died on API credit error, rerun on Opus) repeated keys refused by serde derive, NUL touch-mark silent drop (LRN-073), `--out symlink/` trailing slash followed the link; pass 4 C1-C12 met, C13 docs gaps (lossy UTF-8 read, 2 contrived splits undeclared, stale counts).
|
||||
Anomalies: green byte parity on real data hid every finding: all were hostile-input or file-protection defects. A verdict reported after post-pass edits was not re-verified → owner required a fresh pass on the final state.
|
||||
Action: refusal tests now compare reasons by stage; Object.prototype characterised + tested; migration-map debt characterised; final fresh verifier + security on the final R5.3 state before R5.4. Next ports: budget ≥3 verifier passes, probe hostile inputs (null, duplicates, reserved names, symlinks, encodings) in the oracle from the start.
|
||||
|
||||
## EVAL-029 | 2026-10-23 | R5.4 gates: 14 rounds (verifier + security + check:all) to converge
|
||||
## EVAL-029 — R5.4 gates: 14 rounds (verifier + security + check:all) to converge (2026-10-23)
|
||||
|
||||
Method: each round fresh verifier (opus, contract from disk, own TS-vs-Rust differential) + fresh security-auditor (semgrep + checklist + memory probes) + `pnpm check:all`; superseded runs stopped. Rounds 1-5: Markdown guard families (denylist → allowlist at round 3); rounds 6-11: resource bounds (table amplification, records per op, string headers, drawings per annotation, fixed parts); 12-14: doc precision only. Final: c4e717d security PASS (LOW only), check:all green 16:41:34; eb667ad (docs/comments only over c4e717d) verifier all 9 clauses MET, ECARTS(13) = floor-guard hits on audit prose quoting suppression keywords (product paths clean).
|
||||
Anomalies: docs repeatedly claimed bounds "before any row is built" / "tens of MB" that the next audit disproved; counts drifted after each fix; FLOOR family needs a contract Clarification (human gate), never an audit edit.
|
||||
Action: LRN-074, LRN-075; checkpoint R5.4 to owner with decisions (FLOOR clarification, curation input cap vs 65× parse, bare URLs autolinked, 2 declared quadratic scans), STOP before R5.5.
|
||||
|
||||
## EVAL-030 | 2026-10-23/24 | R5.5 gates: 2 rounds + owner real-stack recette
|
||||
## EVAL-030 — R5.5 gates: 2 rounds + owner real-stack recette (2026-10-23/24)
|
||||
|
||||
Method: fresh verifier + security-auditor (opus; pinned Fable agents died on usage credits, re-dispatched), check:all per round; owner ran real-stack e2e by hand.
|
||||
Anomalies: round 1 verifier ECARTS(4) all real (oversize body → Network+retry, "retried 3×" = 3 attempts, runbook exit codes, FLOOR script never OK); security M1 key on argv in e2e script. Round 2 security 5 LOW (Protocol retried, broadcast DEV addr accepted). Census doc claim "earlier revisions" wrong → corrected before checkpoint.
|
||||
Action: fixes + negative tests; owner closed R5.5 2026-10-24 (e2e PASS 11/11, owner's run). LRN-076.
|
||||
|
||||
## EVAL-031 | 2026-10-24 | R5.6 prep: claimed rehearsal green after extending the patch
|
||||
## EVAL-031 — R5.6 prep: claimed rehearsal green after extending the patch (2026-10-24)
|
||||
|
||||
Method: fresh verifier applied patch in scratch copy, ran every feature set + switched-seed simulation; security read patch.
|
||||
Anomalies: docs/TODO said "rehearsed green"; green run covered 5-consumer wiring only, then generator + loaded.rs added without rerun → report-compare E0063, 4 curation tests failing unreported; switched seed never simulated (+3 failures incl. frozen R4 O7). Security M1: alias-path export writes report 27c7 + snapshot 12d7 → pre-switch/N-1 readers drop snapshot.
|
||||
Action: rerun gate after every patch extension, claim only measured state; patch fixed (build, strict block, NotCanonical); docs corrected; M1 to owner.
|
||||
|
||||
## EVAL-032 | 2026-10-25 | R5.6 rehearsal: docs claimed export guarded by fingerprint_verified
|
||||
## EVAL-032 — R5.6 rehearsal: docs claimed export guarded by fingerprint_verified (2026-10-25)
|
||||
|
||||
Method: isolated worktree (patch + switched seed), rust:check + check:all green, fresh security + verifier (opus), verifier probe on core export API.
|
||||
Anomalies: RUST.md said M1 "needs fingerprint_verified" for every consumer; export path (input.rs) never sees LoadedSheet → v0 sheet snapshot gets alias at export (app unreachable, API reachable). Fix needs snapshot_rules.rs, outside owner's 8-file scope → stopped. Also `pnpm format` rewrote append-only audits in worktree (reverted).
|
||||
Action: claim a guard per call site, not per design; owner decision on snapshot_rules.rs; never run format over .claude/.
|
||||
|
||||
## EVAL-033 | 2026-10-25 | R5.7 closure: deletion gates + pre-merge rerun
|
||||
## EVAL-033 — R5.7 closure: deletion gates + pre-merge rerun (2026-10-25)
|
||||
|
||||
Method: ledger 407 TS cases case by case before `git rm`; fresh verifier + security (opus) twice; check:all on R5.7 state, then rerun on 27bf59c after post-check edits; verifier ran 14 scratch reintroduction probes against census.
|
||||
Anomalies: round 1 verifier ECARTS(2): contract C6 "tsx gone" false vs pnpm optional peer (owner Clarification), digest typo `…dfe7` in docs. Two edits landed after first check:all → owner required full rerun. Census regex accepted `#[ignore]` targets (fixed) and still accepts ignore-before-test (LOW). Docs pointed to premerge record before it existed; `.bin/tsx` wording root-only; SUPABASE.md layout stale since R2. `pnpm audit` never run before this round (cargo advisories only): 57 pre-existing.
|
||||
Action: LRN-078, LRN-079; rerun gate after any post-check edit; run `pnpm audit` in every pre-merge round; checkpoint to owner, STOP before merge.
|
||||
|
||||
## EVAL-034 | 2026-10-25 | Functional inventory put form validation in Rust, against D-R7
|
||||
## EVAL-034 — Functional inventory put form validation in Rust, against D-R7 (2026-10-25)
|
||||
|
||||
Method: P0 doc census + V1-1 contract drafting; inventory `.claude/audits/2026-10-25-functional-inventory.md` cross-checked with RUST_ARCHITECTURE_REVIEW Annex A.
|
||||
Anomaly: inventory criterion 4 placed validation rules (formats, lengths, required fields) in `crates/core` behind wasm facade. D-R7: form constraints stay TypeScript (Zod, i18n keys), SQL CHECK = integrity boundary, constants module + PGlite parity test against `pg_constraint`. Contradiction caught and corrected before V1-1 implementation contract; no code written on it.
|
||||
Action: V1-1 contract §1 + §8.3 follow D-R7. Check every proposal against Annex A D-R rows before writing it.
|
||||
|
||||
## EVAL-035 | 2026-10-25 | V1-1 design draft: 3 fresh challengers found 3 false security claims
|
||||
## EVAL-035 — V1-1 design draft: 3 fresh challengers found 3 false security claims (2026-10-25)
|
||||
|
||||
Method: plan-challenger ×3 (correctness, robustness, simplicity) on `V1-1_OWNERS_ANIMALS.md` before owner checkpoint; evidence read from migrations, harness, worker config, react-router dist.
|
||||
Anomaly: draft claimed (1) N7 service_role revoke → "D16 holds at key level" (false: service key = GoTrue admin key → magic link / set password → user session); (2) identical 42501 while reusing `require_actor()` (two messages); (3) audit growth bounded (false: `log_event` stores attacker-sized `x-correlation-id`). Also phone search vs E.164 broken, OR search unindexable, backfill untestable, multi-call create duplicates, relation RPCs race, useBlocker needs data router.
|
||||
Action: all integrated into contract §6.3, §8-§12, §14 + TODO. Claims about key/role reach need proof via the auth admin API too, not only PostgREST grants.
|
||||
|
||||
## EVAL-036 | 2026-10-25 | V1-1.1 M1 workspaces: gates and isolated real stack
|
||||
## EVAL-036 — V1-1.1 M1 workspaces: gates and isolated real stack (2026-10-25)
|
||||
|
||||
Method: fresh verifier on contract `.claude/tasks/contracts/2026-10-25-v1-1-1-workspaces.md` + fresh security auditor (semgrep 3 rulesets + hand SQL review), PGlite + sandbox runs, 5 mutations of M1 (email check, ON CONFLICT, correlation cap, foreign-member guard, service_role EXECUTE) all caught by 012.
|
||||
Result: security PASS (2 MEDIUM scanner false positives: policy via helper, not raw auth.uid(); LOWs = table names in 42501, residual admin paths, NOT VALID CHECK, pre-existing bounded revoke reason). Verifier C1-C8 MET, C9 UNVERIFIABLE (forbidden to read DEV) → closed by `supabase migration list --local` (M1 remote empty).
|
||||
Anomalies: first mutation run misread (sed indentation miss, crash not printed) → rerun with crash capture; concurrency script pipefail printed false "UNEXPECTED" after real ERROR → fixed. GoTrue 500 on same-email concurrent sign-up = GoTrue race on users_email_partial_key, not M1.
|
||||
Action: contract for gates should name a read-only way to check DEV state (migration list) so C9-type clauses are verifiable.
|
||||
|
||||
## EVAL-037 | 2026-10-25 | V1-1.2 M2 clients: gates, mutations, sandbox hardening
|
||||
## EVAL-037 — V1-1.2 M2 clients: gates, mutations, sandbox hardening (2026-10-25)
|
||||
|
||||
Method: fresh verifier (contract 2026-10-25-v1-1-2-clients.md) + fresh security auditor; 5 M2 mutations (divergent replay, workspace auth, `_` escape, N9 filter, hourly limit) all caught by 013; real image fresh + upgrade (M2 alone, M1+M2 together).
|
||||
Result: security PASS (MEDIUM: secrets on argv in db-sandbox.sh, fixture password literal, policy false positive; LOW: empty-secret fallback risk, state dir in repo, uncapped cursor, no read limit). Verifier ECARTS(2): BDR-075 uncommitted (committed after), fresh-mode real run not reproducible by it (rerun after hardening: 661 PASS, types match, 28/28).
|
||||
@@ -269,28 +288,28 @@ Fixes applied: secrets via env files + PGPASSWORD name only, password-free --db-
|
||||
Anomalies: Write tool turned `
/
` escapes into raw chars (broke a JS regex) → check new files for raw line separators; prettier over tests/ touched 3 unrelated files → restored; real image adds GRANT hint to table denials.
|
||||
Action: write Unicode escapes via shell/python when exact bytes matter.
|
||||
|
||||
## EVAL-038 | 2026-10-25 | V1-1.3 UI foundations + db:sandbox final check
|
||||
## EVAL-038 — V1-1.3 UI foundations + db:sandbox final check (2026-10-25)
|
||||
|
||||
Method: sandbox scripted check (fresh, upgrade, types, argv scan of /proc cmdlines, negative args/secrets/state dir, DEV fingerprint before/after); 6 mutations on dialog/drawer/avatar; fresh verifier (contract 2026-10-25-v1-1-3-ui-foundations.md) + fresh security auditor.
|
||||
Result: sandbox 40/42 first pass → defect `up` bad mode/version started 4 containers + secrets before refusing → fixed 57922e0, 15/15 rerun, upgrade rerun green, DEV unchanged. Mutations: 5/6 caught at once; M5 (confirmation closed before removal) missed until RPC slowed. Verifier CONFORME 8/8. Security PASS (MEDIUM pre-existing fixture password literal; LOW seed SQL interpolation of generated values, env breadth to webServer, refused URLs unmasked → fixed). check:all green 23:41:29; e2e:ui 26, e2e:shell 6, vitest app 458.
|
||||
Anomalies: axe pre-existing serious findings (switcher, top-bar link label-in-name, dashboard dl) → KNOWN list + RR-7; the shell suite found a real focus defect in AvatarSection.
|
||||
Action: keep mutation pass for browser tests; slow async backends in focus tests.
|
||||
|
||||
## EVAL-039 | 2026-10-26 | V1-1.4 M3 animals + relations: gates, mutations, four migration states
|
||||
## EVAL-039 — V1-1.4 M3 animals + relations: gates, mutations, four migration states (2026-10-26)
|
||||
|
||||
Method: 14 mutations of M3 (PGlite pgTAP; M9 swapped into the sandbox, restored, md5 checked); 4 sandbox states (fresh, pre-M1→M1..M3, pre-M1→M1→M2+M3, M1+M2→M3): pgTAP 919, types --check, sandbox suites 46; e2e:ui 26, e2e:shell 6; import:equine --check 0 diff; check:all green 01:11:05 (e2e:ui PASSED, e2e:shell NOT RUN line); fresh verifier (contract 2026-10-26-v1-1-4-animals-relations.md) + fresh security auditor.
|
||||
Result: verifier CONFORME 11/11; security PASS (MEDIUM: sandbox fixture password literal pre-existing, policy-via-helper false positive; LOW: authz read then lock not re-checked (no membership change in V1-1), no-op/replay unmetered (as M2), reads reachable by GET (app convention), service_role ALL on species pre-existing). Mutations 12/14 caught first pass; M6 (voided-only link counted) + M9 (foreign client locked) survived → tests added (533a1c4), both caught after.
|
||||
Anomalies: pgTAP 014 green at first run (suspicious) → mutations proved it bites; axe route regex assumed /app/dashboard, dashboard is /app → shell suite failed until fixed (counter-mutations confirm scoping); permission layer refused sourcing sandbox secrets in shell → rehearsal via SQL + container env.
|
||||
Action: keep lock-wait probes for cross-tenant RPCs (LRN-084); check real route table before path-scoped test rules.
|
||||
|
||||
## EVAL-040 | 2026-10-26 | V1-1.5 client screens: gates, three verifier rounds, report check
|
||||
## EVAL-040 — V1-1.5 client screens: gates, three verifier rounds, report check (2026-10-26)
|
||||
|
||||
Method: unit (supabase 92, app 509), access layer vs real PostgREST (sandbox 54), Chromium e2e:shell 42 (36 client journeys), mutations on app (request id per submit, double-click guard, late-answer guard, account reset, re-read loading) all caught; visual pass desktop+375 via temp capture spec; impeccable detect 0; report scan (decoded embedded zip); check:all green twice (02:04:48, 02:15:51); import:equine 0 diff; pgTAP 919; types match. Fresh security auditor + verifier ×3.
|
||||
Result: security PASS (LOW: test SQL interpolation of sandbox uuids); noted USER_UPDATED reset of workspace unmounting forms → fixed e1c1980. Verifier 1 ECARTS (not-found heading unfocused → fixed 567ad40), verifier 2 ECARTS (docs counts uncommitted; floor assert drop of moved signIn → CLARIFICATIONS), verifier 3 CONFORME 11/11.
|
||||
Anomalies: Prettier over whole src reformatted 39 files → restored, edits re-applied on originals; duplicate h1 (pre-existing top bar) broke selectors; StrictMode ran listener cleanup; drawer exit kept page inert; shell HTML report held typed passwords (BROWSER_TESTS claim false since V1-1.3) → reporter removed; permission layer refused rm -rf via variable (correct) and secrets sourcing.
|
||||
Action: format new files only; dispatch verifier after committing docs; scan reports by content.
|
||||
|
||||
## EVAL-041 | 2026-10-26 | V1-1.6 animal screens and relations: gates, three verifier rounds
|
||||
## EVAL-041 — V1-1.6 animal screens and relations: gates, three verifier rounds (2026-10-26)
|
||||
|
||||
Method: access layer by fork (unit 35, real PostgREST sandbox 7); screens unit tests by fork (57); Chromium e2e:shell 82 (animals 40), 3 full runs; 12 unit + 2 browser mutations all caught; visual pass desktop+375 (one batch fix: relation actions bordered); impeccable detect 0; check:all green 17:19:26; import:equine 0 diff; pgTAP 919; types match; DEV restore step rehearsed on sandbox (counts equal, 26 expected privilege errors). Fresh security auditor + verifier ×3.
|
||||
Result: security PASS (MEDIUM pre-existing sandbox literal pw; LOW trace override by argv). Verifier 1 ECARTS: client journey failed after passing (late replay of the animal-section reload added by V1-1.6) → dropLateReplays for every shell spec. Verifier 2 ECARTS: pgTAP 014 #237 regex `20[0-9]{2}-` matched a workspace uuid on long-lived sandbox (latent V1-1.4 false positive; would stop DEV db:test) → metadata minus workspace_id. Verifier 3 CONFORME 12/12.
|
||||
|
||||
@@ -456,3 +456,9 @@ R5.4: `draft/{labels,changelog,review_report,drawing,overlay,app_review,svg_comp
|
||||
- Owner recette: 19 lines FR detailed, EN global + 4 at 375 px, isolation ok. RESP-01 global scroll = owner browser zoom (owner DEV measures). Real defect found on sandbox: long account e-mail widens dashboard cards (implicit grid track). Fix DashboardRoute + `e2e/shell/responsive.spec.ts` (fails on old code). LRN-094.
|
||||
- AVATAR-01 = class A: DEV worker stopped, row `uploaded` waits, message by design (STORAGE §4.4). Sandbox repro with temp gateway + worker on sandbox net: clean in 1.1 s. Side finding (pre-V1-1): full reload doesn't resume the waiting row, new save supersedes it. DEV read-only only.
|
||||
- Owner closure 2026-10-27: RESP-01 counter-check 6 PASS → closed; AVATAR-01 class A non-blocking, DEV worker stays off, Alice's waiting upload kept; AVATAR-02 ticket in TODO (no Gitea CLI). Pre-merge checkpoint, no merge.
|
||||
|
||||
## 2026-11-02
|
||||
- bugfix/avatar-e2e-sandbox-only: develop e2e:avatar → sandbox only (3a4614b, e8da0d9, d3dfd03). Proofs a-j strace with forged JWTs, 2 × 5/5, DEV untouched. Verifier CONFORME 10/10, security PASS ×2. BLK-013, LRN-095, TODO RR-11. Owner authorised merge into develop; worktree kept.
|
||||
|
||||
## 2026-11-14
|
||||
- chore/sandbox-rule-line: LRN-080 promotion made true, .claude/rules/database.md gains the db:sandbox line (block F claimed it 2026-11-13 without the line). Security PASS.
|
||||
+119
-93
@@ -1,10 +1,27 @@
|
||||
---
|
||||
format: 2
|
||||
type: learnings_registry
|
||||
entry_prefix: LRN
|
||||
schema:
|
||||
id: LRN-XXX
|
||||
date: YYYY-MM-DD
|
||||
pattern: string (what was observed, abstracted)
|
||||
context: string (where/when it happened - concrete)
|
||||
future_application: string (when to recall this)
|
||||
rules:
|
||||
- Capture learnings that apply beyond the current task.
|
||||
- Abstract from the incident - the pattern is what is reusable, not the one-shot fact.
|
||||
- Link to source (commit, file, PR) when possible.
|
||||
- Entries in English, caveman format (BDR-009): drop articles + filler, fragments OK, technical terms exact.
|
||||
---
|
||||
|
||||
# Learnings Registry
|
||||
|
||||
Format: LRN-XXX | Date | Pattern | Context | Future application
|
||||
|
||||
---
|
||||
|
||||
## LRN-001 | 2026-05-18 | Zod discriminatedUnion for nextAppointment
|
||||
## LRN-001 — Zod discriminatedUnion for nextAppointment (2026-05-18)
|
||||
|
||||
Report.nextAppointment uses discriminatedUnion('kind', [...]).
|
||||
Gives precise TS narrowing on .kind; avoids optional union type ambiguity.
|
||||
@@ -12,7 +29,7 @@ Apply: any polymorphic field with a literal discriminant.
|
||||
|
||||
---
|
||||
|
||||
## LRN-002 | 2026-05-18 | SVG hitbox+visible twin pattern
|
||||
## LRN-002 — SVG hitbox+visible twin pattern (2026-05-18)
|
||||
|
||||
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[].
|
||||
@@ -20,7 +37,7 @@ Apply: any SVG-based interactive map needing precise click areas.
|
||||
|
||||
---
|
||||
|
||||
## LRN-003 | 2026-05-18 | pnpm via corepack shim breaks on older Node 20
|
||||
## LRN-003 — pnpm via corepack shim breaks on older Node 20 (2026-05-18)
|
||||
|
||||
corepack shim on Node 20.20.0 throws ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.
|
||||
Fix: install pnpm directly via get.pnpm.io/install.sh.
|
||||
@@ -29,7 +46,7 @@ Apply: CI/dev envs without system pnpm.
|
||||
|
||||
---
|
||||
|
||||
## LRN-004 | 2026-05-19 | SVG behavior hints via free-form data-anno-special
|
||||
## LRN-004 — SVG behavior hints via free-form data-anno-special (2026-05-19)
|
||||
|
||||
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.
|
||||
@@ -37,7 +54,7 @@ Apply: any SVG-driven UI where authors add new annotation types regularly — us
|
||||
|
||||
---
|
||||
|
||||
## LRN-005 | 2026-05-19 | Detail-popup needs its own bones map
|
||||
## LRN-005 — Detail-popup needs its own bones map (2026-05-19)
|
||||
|
||||
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.
|
||||
@@ -45,7 +62,7 @@ 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
|
||||
## LRN-006 — Strip authoring annotations before rasterizing for print (2026-05-19)
|
||||
|
||||
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.
|
||||
@@ -53,21 +70,21 @@ Apply: any "screen → print" pipeline where the screen SVG has interaction laye
|
||||
|
||||
---
|
||||
|
||||
## LRN-007 | 2026-05-19 | pdf-lib maxWidth wraps glyphs, not your cursor
|
||||
## LRN-007 — pdf-lib maxWidth wraps glyphs, not your cursor (2026-05-19)
|
||||
|
||||
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
|
||||
## LRN-008 — pdf-lib eyebrow + title vertical spacing (2026-05-19)
|
||||
|
||||
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
|
||||
## LRN-009 — pdf-lib variable-count image layout — pre-rasterize, reserve text, then grid (2026-05-19)
|
||||
|
||||
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.
|
||||
@@ -75,7 +92,7 @@ Apply: any pdf-lib page where image count is data-driven and text must remain vi
|
||||
|
||||
---
|
||||
|
||||
## LRN-010 | 2026-05-19 | React effect that mutates async-appended DOM needs a "loaded" gate
|
||||
## LRN-010 — React effect that mutates async-appended DOM needs a "loaded" gate (2026-05-19)
|
||||
|
||||
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.
|
||||
@@ -83,21 +100,21 @@ Apply: any React component that mounts external DOM async and applies attribute/
|
||||
|
||||
---
|
||||
|
||||
## LRN-011 | 2026-05-20 | Zod recursive schema via z.lazy + explicit ZodType<T>
|
||||
## LRN-011 — Zod recursive schema via z.lazy + explicit ZodType<T> (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-012 — Once-per-session UX modal via sessionStorage flag (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-013 — Vite import.meta.glob + default-export = plugin discovery (2026-05-20)
|
||||
|
||||
`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.
|
||||
@@ -105,35 +122,35 @@ Apply: any registry-style module set where you want zero-touch onboarding — sp
|
||||
|
||||
---
|
||||
|
||||
## LRN-014 | 2026-05-20 | Cross-walk human strings via normalize + Levenshtein
|
||||
## LRN-014 — Cross-walk human strings via normalize + Levenshtein (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-015 — Per-source try/catch beats loop-wrapping try/catch (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-016 — PDF custom-font text is glyph-subset — bytes-grep won't find it (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-017 — i18n dict parity via Object.keys.sort equality (2026-05-20)
|
||||
|
||||
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
|
||||
## LRN-018 — useT hook: selector subscribe + closure-per-render (2026-05-20)
|
||||
|
||||
```ts
|
||||
export function useT() {
|
||||
@@ -147,7 +164,7 @@ Apply: any Zustand-state-driven derived computation that needs to re-render N co
|
||||
|
||||
---
|
||||
|
||||
## LRN-019 | 2026-05-20 | exhaustive-deps trap with closures over store values
|
||||
## LRN-019 — exhaustive-deps trap with closures over store values (2026-05-20)
|
||||
|
||||
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).
|
||||
@@ -156,7 +173,7 @@ Inline is simpler when the helper is one expression. Apply: any closure that bri
|
||||
|
||||
---
|
||||
|
||||
## LRN-021 | 2026-05-21 | pdf-lib StandardFonts use WinAnsi — Latin-1 only, throws on any non-WinAnsi char
|
||||
## LRN-021 — pdf-lib StandardFonts use WinAnsi — Latin-1 only, throws on any non-WinAnsi char (2026-05-21)
|
||||
|
||||
`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:
|
||||
@@ -167,21 +184,21 @@ Fix paths:
|
||||
|
||||
---
|
||||
|
||||
## LRN-020 | 2026-05-21 | Forward-compat Zod schema absorbs catalog version bump zero-code
|
||||
## LRN-020 — Forward-compat Zod schema absorbs catalog version bump zero-code (2026-05-21)
|
||||
|
||||
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
|
||||
## LRN-023 — DOMParser for safe SVG loading in React-wrapped vanilla editors (2026-05-22)
|
||||
|
||||
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`
|
||||
## LRN-022 — pnpm 11.x requires Node 22.13 — pin pnpm to ≤10.x when staying on Node 20, never use `@latest` (2026-05-21)
|
||||
|
||||
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.
|
||||
@@ -195,7 +212,7 @@ Fix paths:
|
||||
|
||||
---
|
||||
|
||||
## LRN-025 | 2026-05-22 | SVG importNode executes inline scripts — sanitize before append
|
||||
## LRN-025 — SVG importNode executes inline scripts — sanitize before append (2026-05-22)
|
||||
|
||||
`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.
|
||||
@@ -203,7 +220,7 @@ Fix paths:
|
||||
|
||||
---
|
||||
|
||||
## LRN-026 | 2026-05-22 | Standalone HTML tools: port logic inline, don't share modules
|
||||
## LRN-026 — Standalone HTML tools: port logic inline, don't share modules (2026-05-22)
|
||||
|
||||
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.
|
||||
@@ -211,7 +228,7 @@ When standalone .html tools (no build step) need logic from TS modules (zoneMatc
|
||||
|
||||
---
|
||||
|
||||
## LRN-027 | 2026-05-22 | CSS h-full fails in nested flex — use flex-1
|
||||
## LRN-027 — CSS h-full fails in nested flex — use flex-1 (2026-05-22)
|
||||
|
||||
`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.
|
||||
@@ -219,7 +236,7 @@ When standalone .html tools (no build step) need logic from TS modules (zoneMatc
|
||||
|
||||
---
|
||||
|
||||
## LRN-028 | 2026-05-27 | Drive derived UI by spawning the source-of-truth row, not patching each consumer
|
||||
## LRN-028 — Drive derived UI by spawning the source-of-truth row, not patching each consumer (2026-05-27)
|
||||
|
||||
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.
|
||||
@@ -227,19 +244,19 @@ Apply: any feature where "select X in modal → reflect in N places". Find the s
|
||||
|
||||
---
|
||||
|
||||
## LRN-029 | 2026-06-13 | Vite bundles only index.html — standalone HTML must live in public/
|
||||
## LRN-029 — Vite bundles only index.html — standalone HTML must live in public/ (2026-06-13)
|
||||
|
||||
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
|
||||
## LRN-030 — Dockerized SPA on port >=1024 — full non-root nginx works (2026-07-12)
|
||||
|
||||
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
|
||||
## LRN-031 — Build toolchain in dependencies inflates prod CVE audit surface (2026-07-12)
|
||||
|
||||
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.
|
||||
@@ -247,14 +264,14 @@ vite + @vitejs/plugin-react-swc + @tailwindcss/vite sat in dependencies → `pnp
|
||||
|
||||
---
|
||||
|
||||
## LRN-032 | 2026-10-08 | pnpm via corepack prepare, not ~/.local/bin
|
||||
## LRN-032 — pnpm via corepack prepare, not ~/.local/bin (2026-10-08)
|
||||
|
||||
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
|
||||
## LRN-033 — Characterise legacy via DOM + prototype spies, no refactor (2026-10-08)
|
||||
|
||||
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`.
|
||||
@@ -262,7 +279,7 @@ Apply: any "tests before migration" step on untested legacy code.
|
||||
|
||||
---
|
||||
|
||||
## LRN-034 | 2026-10-08 | pnpm 10.13 reads onlyBuiltDependencies, not allowBuilds
|
||||
## LRN-034 — pnpm 10.13 reads onlyBuiltDependencies, not allowBuilds (2026-10-08)
|
||||
|
||||
`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.
|
||||
@@ -270,68 +287,68 @@ Apply: any pnpm 10.x workspace; check `pnpm --version` vs key syntax before trus
|
||||
|
||||
---
|
||||
|
||||
## LRN-035 | 2026-10-08 | PGlite + pgtap = Dockerless Supabase RLS tests
|
||||
## LRN-035 — PGlite + pgtap = Dockerless Supabase RLS tests (2026-10-08)
|
||||
|
||||
`@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
|
||||
## LRN-036 — Supabase default privileges grant ALL to anon/authenticated on new public tables (2026-10-08)
|
||||
|
||||
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
|
||||
## LRN-037 — SQL tests seed-agnostic; generated files through a deterministic formatter (2026-10-08)
|
||||
|
||||
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
|
||||
## LRN-038 — RLS filters, never raises: test "no change", and trigger guards under the owner role (2026-10-08)
|
||||
|
||||
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
|
||||
## LRN-039 — Dual-runner parity: pin collation, grant pg_temp fixtures to API roles (2026-10-08)
|
||||
|
||||
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
|
||||
## LRN-040 — Function privileges: revoke per function, pin with a pg_proc census (2026-10-08)
|
||||
|
||||
`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
|
||||
## LRN-041 — Real Supabase image vs PGlite shim: storage triggers, pnpm script cwd (2026-10-09)
|
||||
|
||||
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
|
||||
## LRN-042 — Changeset authoring over a baseline: python modules per theme, stylised SVG audited by gridded crops (2026-10-10)
|
||||
|
||||
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
|
||||
## LRN-043 — Migrating an app onto a new data model: freeze goldens first, make ids + maps data, read fresh state in DOM handlers (2026-10-10)
|
||||
|
||||
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
|
||||
## LRN-044 — CLI over untrusted documents: escape before print, privacy default, generic parse errors (2026-10-10)
|
||||
|
||||
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.
|
||||
@@ -340,7 +357,7 @@ Apply: any future CLI/log over report content (Step 6 server import, worker). Te
|
||||
|
||||
---
|
||||
|
||||
## LRN-045 | 2026-10-10 | Permanent `will-change: transform` blurs text; promote only during the animation
|
||||
## LRN-045 — Permanent `will-change: transform` blurs text; promote only during the animation (2026-10-10)
|
||||
|
||||
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`.
|
||||
@@ -348,22 +365,22 @@ Apply: any `motion.*`/CSS transition on lists, cards, modals holding text; desig
|
||||
|
||||
---
|
||||
|
||||
## LRN-046 | 2026-10-11 | Refactor a render pipeline behind goldens frozen in two fixture modes; lean-document snapshot beats a new schema
|
||||
## LRN-046 — Refactor a render pipeline behind goldens frozen in two fixture modes; lean-document snapshot beats a new schema (2026-10-11)
|
||||
|
||||
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
|
||||
## LRN-047 — Supabase Auth in a SPA: initialize() + PKCE same-browser rule, GoTrue codes → closed kinds, pgTAP data-modifying CTE trap (2026-10-11)
|
||||
|
||||
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
|
||||
## LRN-048 — Before porting a module, list the hidden serialisation contracts; goldens on drawn primitives make an engine swap provable (2026-10-12)
|
||||
|
||||
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
|
||||
## LRN-049 — R0 experimental findings: serde_json fast float path, wasm traps and the ESM cache, RLIMIT_CPU soft=hard, minimal rustup profile, traced seccomp set (2026-10-13)
|
||||
|
||||
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.
|
||||
@@ -376,7 +393,7 @@ Facts proven on the real environment (docs/development/RUST.md §5), each one ch
|
||||
- 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
|
||||
## LRN-050 — Native vs Docker Rust: rustup auto-install, non-interactive PATH, path strings in the wasm, worker unit tests native (2026-10-13)
|
||||
|
||||
- `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.
|
||||
@@ -384,7 +401,7 @@ Apply: R1 (worker loop keeps the same child), R2 (browser loader: fresh-instance
|
||||
- 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
|
||||
## LRN-051 — Supabase Storage + worker facts: 400-as-404, RETURNS TABLE arg names, service_role cannot read private tables, pg_temp definer helpers in pgTAP (2026-10-13)
|
||||
|
||||
- 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.
|
||||
@@ -395,7 +412,7 @@ Apply: R1 (worker loop keeps the same child), R2 (browser loader: fresh-instance
|
||||
- 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
|
||||
## LRN-052 — Restrict Supabase CLI ports under Docker rootless without sudo: daemon default ip + gateway; rootless file-permission trap (2026-10-13)
|
||||
|
||||
- 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.
|
||||
@@ -404,7 +421,7 @@ Apply: every Storage call in later steps (documents, logos), every `returns tabl
|
||||
- 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
|
||||
## LRN-053 — Correction of LRN-052: Supabase CLI 2.120 binds 0.0.0.0 explicitly; rootless container probes cannot see the host LAN firewall (2026-10-13)
|
||||
|
||||
- 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).
|
||||
@@ -412,7 +429,7 @@ Apply: any DEV service exposure on this machine; future staging compose.
|
||||
- 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
|
||||
## LRN-054 — Porting Zod to serde without drift; wasm in Vite; agent and harness traps (2026-10-14)
|
||||
|
||||
- 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)`.
|
||||
@@ -422,12 +439,12 @@ Apply: any exposure work on this machine; staging compose (bind explicitly there
|
||||
- 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
|
||||
## LRN-055 — Lossy normalisation pre-pass hides user-data alteration; classify parser refusal instead (2026-10-14)
|
||||
|
||||
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.
|
||||
|
||||
## LRN-056 | 2026-10-15 | XML parser recursion, prescan closers, URL/CSS whitespace: three traps porting an SVG sanitiser
|
||||
## LRN-056 — XML parser recursion, prescan closers, URL/CSS whitespace: three traps porting an SVG sanitiser (2026-10-15)
|
||||
|
||||
- roxmltree 0.21.1 recurses per nesting level (parse_element ↔ parse_content); 1 MiB wasm stack overflows between 1,000 and 3,000 levels; nodes_limit checked too late. Measure parser depth on the real stack size before trusting "iterative" claims (plan rev 1 said iterative: false). Fix = own markup prescan before any parse; fixed release only in unreleased git.
|
||||
- A prescan must search each closer AFTER its whole opener (`-->` from +4, `]]>` from +9, `?>` from +2): searching from +1 let `<!-->` desync scanner vs XML grammar and hide 5,000 levels (security audit MEDIUM). Prove with differential fuzz vs the real parser (auditor ran ~4M docs) + calibrated small-stack run.
|
||||
@@ -437,7 +454,7 @@ Apply: any reader of user data (R3 SVG, R4 PDF reader, R5 pipeline) → refuse w
|
||||
- Visual parity: freeze happy-dom trees + Chromium screenshots BEFORE switch; same-build double capture gives the noise floor (30/30 identical); synthetic controls validate the comparator; baseline = `git archive develop` built in scratchpad (no worktree).
|
||||
Apply: R4 PDF reader/writer (byte scanners, inflate), Step 13 uploads (reader in worker child), any parser fed untrusted input.
|
||||
|
||||
## LRN-057 | 2026-10-16 | Terminal-failure UX: bind data-safety promises to save status, census every retry surface
|
||||
## LRN-057 — Terminal-failure UX: bind data-safety promises to save status, census every retry surface (2026-10-16)
|
||||
|
||||
- Message promising data kept ("report kept in this tab") must read real persistence status (quota flag); else variant + core-free rescue (download of in-memory state).
|
||||
- Capped recovery → enumerate EVERY failure surface (grep failure keys, retry handlers, full-page degraded states), not only those the patch touched; enforce with ESLint `no-restricted-syntax` on `t('<key>')` literals (dictionaries untouched, file-scoped exceptions; later block overrides earlier for same rule).
|
||||
@@ -446,7 +463,7 @@ Apply: R4 PDF reader/writer (byte scanners, inflate), Step 13 uploads (reader in
|
||||
- Status listeners from a state machine: notify via microtask, try/catch per listener, never inside load/recover try blocks; stable module-scope subscribe for useSyncExternalStore.
|
||||
Apply: R4 PDF worker failure states, Step 8 avatar upload errors, any capped retry or offline mode.
|
||||
|
||||
## LRN-058 | 2026-10-17 | Rescue paths need proven restore; remember trapping inputs; sniff and cap before read
|
||||
## LRN-058 — Rescue paths need proven restore; remember trapping inputs; sniff and cap before read (2026-10-17)
|
||||
|
||||
- "Download a copy" is no rescue until an in-app restore exists and a round-trip test proves equality; reuse the reader that already parses that format (here core `draft.restore`) instead of a new parser.
|
||||
- Input that trapped a recoverable engine must be remembered (key = every input of the trapping call, e.g. draft + archive) and re-read only on explicit Retry: each re-read spends a capped recovery and pins dead-instance memory.
|
||||
@@ -455,199 +472,208 @@ Apply: R4 PDF worker failure states, Step 8 avatar upload errors, any capped ret
|
||||
- Picker opened from a confirm dialog: call `input.click()` synchronously in the confirm handler (user activation, WebKit).
|
||||
Apply: any export/backup feature, R4 PDF reader worker failures, Step 13 uploads.
|
||||
|
||||
## LRN-059 | 2026-10-17 | Rust `from_utf8_lossy` matches TextDecoder; serde_json differs from JSON.parse on overflow and surrogates
|
||||
## LRN-059 — Rust `from_utf8_lossy` matches TextDecoder; serde_json differs from JSON.parse on overflow and surrogates (2026-10-17)
|
||||
|
||||
- `String::from_utf8_lossy` after stripping one BOM = `new TextDecoder().decode()` (non-fatal): 200,015 random + edge byte strings (overlong, UTF-8 surrogates, truncated, double BOM), 0 diff. Parity holds on tested sequences, not proven in general.
|
||||
- JSON.parse vs serde_json: `1e400` → JS Infinity (JSON.stringify writes `null`), serde_json "number out of range"; lone surrogate escape kept by JS, refused by serde_json; duplicate key last value at first position in both (preserve_order). A JS path that did parse → stringify has side effects (overflow → null, dropped duplicates): reproduce them or declare them.
|
||||
Apply: Rust ports of JS readers of untrusted text (R4 PDF reader, Step 13 uploads, Step 15 server validation).
|
||||
|
||||
## LRN-060 | 2026-10-17 | wasm-bindgen glue retains its instance until reload; only a terminated worker frees linear memory
|
||||
## LRN-060 — wasm-bindgen glue retains its instance until reload; only a terminated worker frees linear memory (2026-10-17)
|
||||
|
||||
- `--target web` glue keeps the instance in module scope (`let wasm`, `__wbg_finalize_init`); ES module records are never unloaded, so each fresh glue import (`?instance=n`) keeps its old instance and memory (BLK-012: dead instances retained until reload). Linear memory never shrinks.
|
||||
- Memory-heavy one-shot work: reuse the long-lived instance (high-water kept until reload) or run in a Worker terminated after (everything freed). A "disposable instance" on the main thread is a leak, not a release.
|
||||
Apply: R4 import worker and export placement, any future in-browser wasm batch job.
|
||||
|
||||
## LRN-061 | 2026-10-18 | A multi-budget pre-scan must keep every budget sound, even once another check already refuses
|
||||
## LRN-061 — A multi-budget pre-scan must keep every budget sound, even once another check already refuses (2026-10-18)
|
||||
|
||||
- R4.2 `json_js::prescan` returned early at depth > 64 with the partial value count; the PDF probe checked both verdicts, the rescue copy checked values only → a 16 MiB copy nested 65 deep reported 66 values, passed the budget, built 792 MiB (security gate BLOCK, fixed 593893a: count runs to the end, depth verdict kept).
|
||||
- Rule: one linear pass serving several guards finishes every measure; an early return for one verdict silently disarms the callers that rely on the others. Controls must never neutralise each other; a refusal path stays bounded in time and memory.
|
||||
Apply: any shared pre-scan / lexer feeding several caps (R4.3 worker, R5 pipeline, Step 13 uploads); test each guard alone with the other verdict already failing.
|
||||
|
||||
## LRN-062 | 2026-10-18 | Non-finite numbers: follow the JSON actually serialised, not the JS type before serialisation
|
||||
## LRN-062 — Non-finite numbers: follow the JSON actually serialised, not the JS type before serialisation (2026-10-18)
|
||||
|
||||
- `parseVersioned` tested `typeof version === 'number'` on `JSON.parse` output: `1e999` → `Infinity`, a number, so the probe accepted; `JSON.stringify` then wrote `null`, so the core saw no version → `no_attachment`. A Rust port that rewrote overflow → `null` before the probe gave `attachment_stripped` (3 O8 rows).
|
||||
- Fix: probe on a copy where overflowing tokens stay finite numbers (`rewrite_overflow_numbers_as_finite`, `0`), hand the `null` form to the core. Same family as LRN-059 (overflow, lone surrogates): every JS parse → stringify hop is a transformation to reproduce step by step, in order.
|
||||
Apply: porting any JS reader whose acceptance test ran between parse and stringify (R4 writer inputs, R5 pipeline, server validation).
|
||||
|
||||
## LRN-063 | 2026-10-19 | wasm linear memory: never grow one big Vec; long-lived chunks big enough not to interleave with transients
|
||||
## LRN-063 — wasm linear memory: never grow one big Vec; long-lived chunks big enough not to interleave with transients (2026-10-19)
|
||||
|
||||
- Growing `Vec<u8>` for a 44 MiB file in wasm (dlmalloc) peaked 125 MiB: realloc keeps old + new while copying; decode transients (≈ 10 MB per PNG) sit between file and heap top so no in-place growth. Linear memory never shrinks → spike is the high-water for the page.
|
||||
- Fixed chunks (never realloc) remove the spike. 1 MiB chunks still cost 0.12 MB per view (long-lived alloc every other raster interleaved with transients → fragmentation); 8 MiB chunks cost 0. Adaptive target 1 → 8 MiB: small files pay one small chunk, big files few long-lived allocs. `shrink_to_fit` on seal gives slack back.
|
||||
- Hand chunks to JS one by one (`take_part`, freed in module), `new Blob(parts)`: file never held twice across heaps.
|
||||
Apply: any wasm producer of large outputs (R5 pipeline, future image work): measure stage by stage with `memory.buffer.byteLength`, never trust the estimate.
|
||||
|
||||
## LRN-064 | 2026-10-19 | Test facts from the produced PDF, not from draw-call spies; recorder order ≠ file order
|
||||
## LRN-064 — Test facts from the produced PDF, not from draw-call spies; recorder order ≠ file order (2026-10-19)
|
||||
|
||||
- Step 6 goldens were recorded by spying pdf-lib `drawText`/`drawImage`: footers recorded after every page's content (global call order). Read back from content streams, facts come page by page. Same set, same within-page order: compare against the golden stably sorted by page.
|
||||
- `tests/helpers/pdfRead.ts`: pdf-lib loads the file, inflates each content stream, parses `Tf/Tm/Tj/ET` and `cm … Do`, resolves `/F1` through page resources, WinAnsi = windows-1252. Lets 16 roundtrip + 7 goldens cases run unchanged on the Rust output.
|
||||
Apply: when an implementation is swapped under a test that spied the old one, read the artefact instead of mocking the new one; keep the old generator pinned to the old engine (r4.writer-oracles → `exportReportArchive`).
|
||||
|
||||
## LRN-065 | 2026-10-20 | Feature unification hides no-default builds; host refusal by resolution, not spelling; control run isolates browser memory
|
||||
## LRN-065 — Feature unification hides no-default builds; host refusal by resolution, not spelling; control run isolates browser memory (2026-10-20)
|
||||
|
||||
- `cargo test --workspace` unifies features across members: crates/wasm enabling `pdf-read` made core compile in every gate while `cargo check -p faunosteo-core` (default = []) failed. Apply: gate runs one per-crate no-feature build (`cargo clippy -p <crate> --all-targets`) whenever a crate has optional features.
|
||||
- Refusing wildcard binds by string set fails: getaddrinfo accepts `0`, `0x0`, `0.0.0`, `0::`, `::ffff:0.0.0.0`, `::%lo`. Apply: `dns.lookup(host,{all:true})` → refuse if any result in `BlockList(0.0.0.0, ::)` (scope stripped, type from `net.isIPv6(address)`), listen on resolved literal, re-check `server.address()` (its `family` is 'IPv6', lookup's is 6).
|
||||
- Opening before stat-checking type blocks on a FIFO (O_RDONLY): stat path first, then open, then fstat recheck.
|
||||
- Browser RSS growth across exports: run the same raster steps with no core call (control) in the same page; same slope + same plateau = browser cache/allocator, not app retention. FinalizationRegistry counters + createObjectURL/revoke ledger + CDP `Performance.getMetrics` / heap census separate page-held objects from renderer memory; `Memory.simulatePressureNotification critical` tests reclaimability.
|
||||
|
||||
## LRN-066 | 2026-10-21 | Recette server must mirror production cache headers; headless never proves native dialogs
|
||||
## LRN-066 — Recette server must mirror production cache headers; headless never proves native dialogs (2026-10-21)
|
||||
|
||||
- Offline import (J1.7) failed on owner's Brave + Firefox but harness server `serve.mjs` sent no `Cache-Control` on `/assets/` while nginx sends `immutable`: Chromium refuses stale cache entry offline (`net::ERR_ABORTED`), Firefox offline mode serves it anyway, WebKit headless never serves worker script from cache offline. Apply: any test server standing in for prod copies prod's cache + CSP lines verbatim and the harness asserts them (`r4-offline-import.mjs`); test "offline" two ways (Playwright `setOffline` + server killed), they differ per engine.
|
||||
- Headless browsers replace OS file dialogs: a frozen `<input type=file>` picker cannot be reproduced or excluded headless. Apply: write a discriminating human step (Ctrl+O in empty tab offline, kit copied local) instead of claiming a cause.
|
||||
- Expected recette result written from an oracle fixture (`nologos` = fetch 404 mode) described the fixture, not the product rule (editor export always embeds bundled branding; archived branding only via `export_from_envelope`). Apply: before writing an expected result, trace which code path the recette step actually runs.
|
||||
|
||||
## LRN-067 | 2026-10-21 | "Known violation" excluded from a verdict hides a real defect; wait before calling a dialog frozen
|
||||
## LRN-067 — "Known violation" excluded from a verdict hides a real defect; wait before calling a dialog frozen (2026-10-21)
|
||||
|
||||
- Footer hotlinked `zenquality.fr` logo since 2026-05-21, same day DEPLOY.md CSP `img-src 'self'` written; R2 + R4 CSP proofs saw refusal on every page, harness listed it as `KNOWN_IMAGE_HOST` and excluded from verdict → nobody fixed it for 5 months. Live site sends no CSP yet, so symptom invisible. Apply: a harness never carries a "known" exception longer than one slice; either fix the cause or open a TODO line with owner date. Bundle third-party images (`?url`, exact remote bytes = no branding change) instead of widening CSP.
|
||||
- Owner's J1.7 "picker never opens, browser unusable" = OS file dialog taking ~60 s to open with system network cut (same from Ctrl+O in empty tab). Apply: recette step for any "hang" says wait 2 min before declaring FAIL and records time; a symptom reproduced outside the app closes the app-defect hypothesis, cause of delay stays unclaimed unless traced.
|
||||
|
||||
## LRN-068 | 2026-10-21 | Contract FILE SCOPE lists itself, memory files by name and every redaction; harness results carry repo-relative paths
|
||||
## LRN-068 — Contract FILE SCOPE lists itself, memory files by name and every redaction; harness results carry repo-relative paths (2026-10-21)
|
||||
|
||||
- R4.10 verifier: 8/8 MET but formal gap: contract's own file in the diff, absent from FILE SCOPE ("memory" written vaguely). Apply: FILE SCOPE names the contract path, each `.claude/memory/*.md` and TODO touched, and gets amended in the same commit as any later scope growth; never drop a CHECK to pass.
|
||||
- `scripts/browser/lib/app-build.mjs` wrote absolute `DIST_DIR` (user home) into committed results JSON from R4.6 on (older runs relative). Apply: any committed report names paths relative to repo or a placeholder; scan `git grep -E "/home/|-home-"` before each report commit.
|
||||
|
||||
## LRN-069 | 2026-10-21 | Runbook syntax fixes need the target's real version; URL sanitiser must re-check its own output
|
||||
## LRN-069 — Runbook syntax fixes need the target's real version; URL sanitiser must re-check its own output (2026-10-21)
|
||||
|
||||
- Context7 said nginx `listen ... http2` deprecated → `http2 on;`, but live VPS sends `Server: nginx/1.24.0` and 1.24 rejects `http2 on` (`unknown directive`). Apply: before changing a runbook directive, read the target's version (Server header, `nginx -v`) and `nginx -t` both forms in throwaway containers of each version; document both when the fleet straddles.
|
||||
- WHATWG URL normalisation can create the escape it was meant to catch (`/..//host` → pathname `//host`, same origin for the probe). Apply: sanitiser re-validates the value it returns (not only the input), plus an idempotence test; fuzz with dot segments, `%2e`, tabs inside `..`.
|
||||
|
||||
## LRN-070 | 2026-10-22 | Rust `{:e}` shortest digits ≠ ECMAScript on exact decimal ties; oracle that re-prints expected through the port cannot see it
|
||||
## LRN-070 — Rust `{:e}` shortest digits ≠ ECMAScript on exact decimal ties; oracle that re-prints expected through the port cannot see it (2026-10-22)
|
||||
|
||||
Found by R5.1 study. `js_number` (core json.rs) takes shortest digits from `format!("{:e}")` (Grisu): exact tie between two shortest candidates → Grisu picks upper, ECMAScript/Python/`zmij` pick even. `840.1692504882812` (= 840.16925048828125, float32-exact, Horse.svg legacy cx) → Rust `…813`. Rate: 7,401 / 100,000 float32-exact values in 0..2000, 769 / 100,000 random doubles, `zmij` (serde_json 1.0.154 formatter, locked) 0. Draft seed has no tie → every R2/R3/R4 suite green, but `sheet_contract.rs` `zod_oracle` computes expected = `to_js_pretty(oracle.output)` → same function both sides → blind. 134 JSON fixtures Node vs Rust pretty: 2 differ (legacy baseline, that value).
|
||||
Apply: shortest-float port → take digits from `zmij`/ryu-class crate, never `{:e}`; tie vectors (float32-exact values) in unit tests; oracle expected must be the recorded JS text, never re-printed by the port under test. Any R5 importer emitting legacy coordinates needs the fix first.
|
||||
|
||||
## LRN-071 | 2026-10-22 | Prettier byte parity for generated JSON/Markdown is cheap: four layout rules + one width table, oracle-probed
|
||||
## LRN-071 — Prettier byte parity for generated JSON/Markdown is cheap: four layout rules + one width table, oracle-probed (2026-10-22)
|
||||
|
||||
R5.2 reproduced Prettier 3.8.3 `parser: json` over `JSON.stringify(v, null, 2)` and markdown table alignment in ~350 lines Rust, byte-exact on 968 synthetic probes + 7 seed files + 3 reports. Rules that mattered: objects always expanded (stringify newline after `{`), array breaks when >1 element and all elements arrays >1, or child breaks, or flat form + trailing comma > 80 cols; broken all-number arrays use `fill`, others one per line; `printNumber` drops `e+`; width = length if all bytes 0x20..0x7F else per code point (controls/combining/VS16 = 0, East Asian wide/fullwidth = 2) after RGI emoji replaced by spaces. Emoji table not reproduced → refuse (`UnsupportedWidth`), declared. Probe generator in TS (vitest, `MAKE_R5_ORACLES=1`) sweeping depth × key width × count × digits around the 80-col boundary found both bugs (`e+21` form, width fast path) before any real file did.
|
||||
Apply: any port that must match a formatter's bytes: sweep the boundary with synthetic probes written by the formatter itself; transcribe tables from the installed package (same table lives in `index.mjs` and plugin), never from memory; refuse unreproduced classes loudly instead of approximating.
|
||||
|
||||
## LRN-072 | 2026-10-23 | serde `Option<T>` reads JSON `null` as absent; Zod `.optional()` refuses it
|
||||
## LRN-072 — serde `Option<T>` reads JSON `null` as absent; Zod `.optional()` refuses it (2026-10-23)
|
||||
|
||||
Found by R5.3 verifier pass 2: changeset `scope` / `position` / `field` declared `Option` + `#[serde(default)]` → `"scope": null` parsed as absent, Zod refused (`expected 'self' | 'subtree', received null`). Committed data had none → every parity test green, only a hostile input shows it. Core already had `js::present` (R2) for exactly this; port forgot it. Complement of LRN-048 (serializer side: `.optional()` absent vs nullable `null`).
|
||||
Apply: porting a Zod schema to serde: `.optional()` → `default, deserialize_with = "js::present"`; `.nullable()` → `js::nullable`; add one `null` refusal case per optional key to the differential oracle.
|
||||
|
||||
## LRN-073 | 2026-10-23 | In-band markers replacing object identity must be reserved keys refused at input
|
||||
## LRN-073 — In-band markers replacing object identity must be reserved keys refused at input (2026-10-23)
|
||||
|
||||
R5.3 applier replaced TS object identity (touched items) with a transient key `"\0touched"`, stripped after each change. Verifier pass 3: an authored value holding that key was taken for a mark and the cleanup deleted it silently, where TS refused it at the strict gate → silent author-data loss. Fix: refuse any NUL-prefixed key in the changeset at parse (`reserved key`), test it.
|
||||
Apply: any in-band sentinel (key, id prefix, magic value) gets a reserved namespace, a refusal at the input boundary and a test; never rely on "no author would write that". Prefer out-of-band state (side table by path) when the cost is similar.
|
||||
|
||||
## LRN-074 | 2026-10-23 | Formatter-parity guard: allowlist + generator sweep, never denylist
|
||||
## LRN-074 — Formatter-parity guard: allowlist + generator sweep, never denylist (2026-10-23)
|
||||
|
||||
R5.4 ported CHANGELOG/REVIEW-REPORT without a Markdown printer: reproduce Prettier's table alignment only, refuse text Prettier would rewrite. Denylist guard leaked every gate round (emphasis, links, autolinks, entities, strong pairs, URL underscores, image refs, nested padded wiki links, underscore paired across code spans, wiki opened in one field closed in another, field segment closing author `[` from a code span). Allowlist (letters, digits, single spaces, fixed punctuation, few ruled forms; code spans only the generator alphabet `[A-Za-z0-9_:/. -]`; list-item fields refuse `[[ ]] {% %}` whole) + TS-written sweep (798 probes, 400 seeded random, cross-field pairs) converged: rounds 11-14 found 0 silent over ~400,000 TS-vs-Rust cases.
|
||||
Apply: byte parity with a formatter you do not port → allowlist of what the real data uses, refuse rest loudly, sweep frozen by the formatter itself incl. random strings and constructs split across fields/lines; state guarantee as empirical; add each gate-found family to sweep.
|
||||
|
||||
## LRN-075 | 2026-10-23 | Resource bounds: charge at the allocation site, projection must be a tested upper bound
|
||||
## LRN-075 — Resource bounds: charge at the allocation site, projection must be a tested upper bound (2026-10-23)
|
||||
|
||||
R5.4 security rounds 6-11 each broke a bound that looked done: table bound checked after raw rows built; records bound checked after a whole op (one op records once per item, each record cloning change texts); weight counted 1/byte while each cloned String costs header + alloc (~56 B for 1-char id); drawings projected from cleaned SVG only, unnamed triggers copy opened view names ×4; projection 477 B under written for a draft with no annotations (fixed parts uncharged). Each time docs claimed "refused before built".
|
||||
Apply: bound = check before the clone/allocation, at every producer (record push, marking, subtree loop); weight ≈ real bytes (64 per node/String + bytes); output projection = upper bound per element + fixed part per file, with a test asserting projected ≥ written on real and degenerate inputs (empty, max-copy); measure hostile inputs at 1/10 of the read cap before claiming a bound in docs.
|
||||
|
||||
## LRN-076 | 2026-10-24 | Stub suite ≠ real-service recette; record both apart
|
||||
## LRN-076 — Stub suite ≠ real-service recette; record both apart (2026-10-24)
|
||||
|
||||
Context: R5.5 upload tool. 12 loopback-stub tests green; Claude's run vs real local stack refused by permission layer (transfer tool + service key). Owner ran `pnpm e2e:sheet-assets` by hand → PASS 11/11.
|
||||
Pattern: stub proves tool logic (plan, refusals, retries, no overwrite); only real service proves endpoints, status codes, grants (anon key refused at Storage, not stub). Ship a hand-run e2e script beside stub suite; record each result with its author (simulated by Claude / real by owner), never merge into one "tested".
|
||||
Apply: any tool touching a real service with a privileged key: stub tests in `cargo test`, owner-run e2e script, both results in RUST.md + TODO separately. Owner validated 2026-10-24.
|
||||
|
||||
## LRN-077 | 2026-10-25 | Privilege decision needs proof at the call site holding the evidence
|
||||
## LRN-077 — Privilege decision needs proof at the call site holding the evidence (2026-10-25)
|
||||
|
||||
Context: R5.6 M1. Alias granted at export from snapshot's claimed value; export never saw the loaded sheet. Load-time flag alone also insufficient (pub mutable document/reference).
|
||||
Pattern: put the decision where the evidence object lives (build_sheet_snapshot holds LoadedSheet), keep private verified state set only by the trusted constructor, and recompute the proof at decision time; every other site stays strict equality. Make the raw comparison crate-private so no caller can skip the proof.
|
||||
Apply: any equivalence/allowlist privilege (aliases, migrations, trust marks): one decision method on the verified object, recompute, strict elsewhere, negative tests on the direct API not just app paths.
|
||||
|
||||
## LRN-078 | 2026-10-25 | Before deleting old engine, census contracts only its test code checks
|
||||
## LRN-078 — Before deleting old engine, census contracts only its test code checks (2026-10-25)
|
||||
|
||||
Context: R5.7. Oracles + Rust parity looked full; case-by-case map of 407 TS cases found 15 anatomy + 1 domain contracts no Rust test checked (612-leaf fates, 26 legacy ids, region inference, R5.1 ledger rows, overlay removal, halo, CHG-000, dollar tag, viewBox, cite of added ref, move via renamed path, folder file list, map vs oracle per entry). Oracle generators' own asserts carried them.
|
||||
Pattern: ledger row per old case (contract, disposition, live target, oracle); census test checks target is non-ignored `#[test]` fn and oracle file exists; port gaps before `git rm`.
|
||||
Apply: any engine deletion (R-phases): map every case first, "oracle covers it" is a claim to prove per case. Owner validated 2026-10-25.
|
||||
|
||||
## LRN-079 | 2026-10-25 | Optional peer in lockfile ≠ live use of deleted engine
|
||||
## LRN-079 — Optional peer in lockfile ≠ live use of deleted engine (2026-10-25)
|
||||
|
||||
Context: R5.7 C6. After removing anatomy, `tsx` stayed in pnpm-lock.yaml as vite's optional peer (`optional: true`, no importer, no bin); `pnpm install` keeps it, `dedupe --check` clean; only hand edit/override would drop name. Contract said "tsx gone" → false NOT-MET.
|
||||
Pattern: prove use by `pnpm why <pkg> -r` path + importer blocks + manifest/script/source census, not lockfile name grep. Never hand-edit lockfile or add override just to drop a name.
|
||||
Apply: dependency-removal clauses state objective (no declared dep, no script, no import), allow transitive/optional peers; census guards declared deps and `optional: true`. Owner validated 2026-10-25.
|
||||
|
||||
## LRN-080 | 2026-10-25 | Throwaway Supabase stack beside DEV: test migrations, grants, sign-up and HTTP without touching DEV
|
||||
## LRN-080 — Throwaway Supabase stack beside DEV: test migrations, grants, sign-up and HTTP without touching DEV (2026-10-25)
|
||||
|
||||
Shown on this host (Docker rootless, daemon ip 127.0.0.1, CLI 2.120, images postgres 17.11.0.004, gotrue v2.197.0, storage v1.79.36, postgrest v16.4, mailpit v1.31.3): own network + `-p 127.0.0.1:<57xxx>` per service, no `-v` (images declare no VOLUME → nothing to drop at teardown, `docker rm -f` of literal names suffices). db needs the CLI's role-password init (`/etc/postgresql.schema.sql` via `--entrypoint sh -c`); GoTrue + storage-api migrate their schemas on start; then the CLI's own runners take `--db-url`: `migration up` (records history like DEV), `test db` (pg_prove, rows unchanged), `gen types`. Upgrade path = `--workdir` copy holding the older migrations, then `migration up` from the repo. Real sessions prove what PGlite cannot: concurrency (two psql sessions), GoTrue sign-up/confirm via Mailpit API, PostgREST role refusals, residual GoTrue-admin path. `pg_dump -Fc` as postgres with the container's `$POSTGRES_PASSWORD` dumps auth data too; restore with `--no-owner` keeps every row, prints only managed-object privilege errors.
|
||||
Limits: one host; not a hosted project; vault/realtime/edge absent; CLI may change bind/runner behaviour across versions.
|
||||
Apply: `scripts/db-sandbox.sh` (`pnpm db:sandbox`) for every migration step; DEV changes stay owner actions.
|
||||
- **Status (2026-11-13)**: implemented, promoted to rule line .claude/rules/database.md
|
||||
|
||||
## LRN-081 | 2026-10-25 | `supabase gen types --db-url` to the sandbox needs `?sslmode=disable`
|
||||
## LRN-081 — `supabase gen types --db-url` to the sandbox needs `?sslmode=disable` (2026-10-25)
|
||||
|
||||
CLI 2.120 against the sandbox PostgreSQL (127.0.0.1:57432, image 17.11.0.004, no TLS configured): without the option → `DbConnectError … tls error (The server does not support SSL connections)` and the error JSON lands on stdout (piping it to prettier gives a confusing syntax error). With `?sslmode=disable` the output matched the committed `database.types.ts` byte for byte for the pre-existing schema (same generator as `--local`). Same URL works for `migration up`, `test db`. Not checked: other CLI versions, TLS-enabled targets (keep TLS there).
|
||||
Apply: any `--db-url` to a local non-TLS Postgres; never pipe generator output without checking the exit code.
|
||||
|
||||
## LRN-082 | 2026-10-25 | Native modal `<dialog>` in Chromium: three traps, one test blind spot
|
||||
## LRN-082 — Native modal `<dialog>` in Chromium: three traps, one test blind spot (2026-10-25)
|
||||
|
||||
Shown on Chromium 156 (Playwright 1.64.1): (1) Escape cancelled only via `cancel` event → second Escape without user activation closes anyway (close-watcher anti-abuse); `preventDefault` on keydown Escape stops the close request entirely. (2) Initial focus = scrollable panel when content long, first button otherwise → focus first tabbable explicitly. (3) Tab past last control → `document.hasFocus()` false one step (browser UI), then back to first; page never reached. happy-dom: showModal only sets `open` (no inert, no focus) → unit tests prove wiring only. Exit animation (motion, 180 ms) masked async focus loss: a fast sandbox RPC settled before unmount, test green with defect → slow the RPC via `page.route` + `route.fallback()` to discriminate. axe color-contrast false positives while entrance animation runs → wait `document.getAnimations()` settled.
|
||||
Apply: any modal or async confirmation test; mutation-check browser tests.
|
||||
|
||||
## LRN-083 | 2026-10-26 | PL/pgSQL traps met writing M3
|
||||
## LRN-083 — PL/pgSQL traps met writing M3 (2026-10-26)
|
||||
|
||||
(1) A parameter cannot share a name with a `returns table` output column (`species_id` filter vs output): CREATE fails "parameter name used more than once" → rename the parameter. (2) SQL `or` does not promise left-to-right: `p !~ '^[0-9]{4}$' or p::integer > …` can cast first and raise 22P02 echoing the value → two IF statements. (3) `'2015-02-30'::date` raises 22008, not 22P02 → catch `data_exception` (class 22). (4) pgTAP audit rows of one transaction share `occurred_at` (now()) → order also by `action collate "C"`: ICU sorts `_` before `.`, C the reverse.
|
||||
Apply: any plpgsql RPC parsing text input; any pgTAP string_agg over same-transaction rows.
|
||||
|
||||
## LRN-084 | 2026-10-26 | FK backstop hides an authorisation-order bug; only a lock-wait probe shows it
|
||||
## LRN-084 — FK backstop hides an authorisation-order bug; only a lock-wait probe shows it (2026-10-26)
|
||||
|
||||
Context: M3 mutation M9 removed the workspace filter on the client lookup in `create_animal_client_relation`. pgTAP stayed green: the composite FK refused the row and the RPC mapped it to the same `not_found`. Real effect: B's call took FOR SHARE on A's client → B waited on A's lock (timing side channel, cross-tenant contention). Caught only by sandbox test: A holds the row FOR UPDATE 2 s, B's refusal must answer < 1 s (measured 15 ms; mutated 1 749 ms).
|
||||
Apply: for every RPC that locks rows, a real-session test where the victim holds the locks and the attacker's refusal must be fast; equal error text alone does not prove "no lock outside the workspace".
|
||||
|
||||
## LRN-085 | 2026-10-26 | Focus after drawer navigation: page inert during exit animation, StrictMode cleanup kills listeners
|
||||
## LRN-085 — Focus after drawer navigation: page inert during exit animation, StrictMode cleanup kills listeners (2026-10-26)
|
||||
|
||||
Context: V1-1.5 page heading focus on open. Drawer (native modal dialog + motion exit 200 ms) keeps page inert → heading.focus() fails; then dialog close restores focus to menu button. Fix: callback ref on heading; if `dialog:modal` present, one-shot `close` listener + setTimeout(0) → focus after ModalDialog's microtask restore. Trap: useEffect cleanup removing the listener ran in React StrictMode's simulated unmount (dev) → listener gone; keep one-shot listener, check `isConnected`, no cleanup. Also: a page that renders its h1 after loading needs a callback ref, not a mount effect. Traced with a temporary focusin/close logger spec.
|
||||
Apply: any focus-on-navigation or focus handoff next to a modal with exit animation; never rely on effect cleanup for listeners that must survive StrictMode.
|
||||
|
||||
## LRN-086 | 2026-10-26 | Playwright HTML report keeps every typed value in step titles
|
||||
## LRN-086 — Playwright HTML report keeps every typed value in step titles (2026-10-26)
|
||||
|
||||
Context: V1-1.5 report check. `locator.fill(value)` step titles hold the value; the shell suite's HTML report (embedded base64 zip) held the throwaway accounts' passwords, contrary to BROWSER_TESTS.md ("no trace" was thought enough). Found by decoding the zip in memory and counting fixture patterns.
|
||||
Apply: suites typing secrets → `reporter: [['list']]` (no html, no trace); audit reports by decoding the embedded zip, not by grepping the html. Also: never run Prettier on a whole src tree here (EVAL-037 repeat) — format new files only.
|
||||
|
||||
## LRN-087 | 2026-10-26 | TS does not type-check hyphenated props on components: Card dropped aria-labelledby silently
|
||||
## LRN-087 — TS does not type-check hyphenated props on components: Card dropped aria-labelledby silently (2026-10-26)
|
||||
|
||||
Context: V1-1.6 e2e locator `section[aria-labelledby=…]` found nothing. `Card` (props children/className/as) ignored `aria-labelledby`; TypeScript accepts any `aria-*`/`data-*` attribute on a component without declaring it, so every V1-1.5 section card shipped unnamed; axe never flags an unnamed section (no violation), unit tests queried by heading text. Fixed by declaring and passing the prop.
|
||||
Apply: wrapper components that render landmarks must declare and forward `aria-*` explicitly; test named regions by role + name (`getByRole('region', {name})` or the attribute selector), not only by heading text.
|
||||
|
||||
## LRN-088 | 2026-10-26 | useT() returns a new function each render: never a dependency of a data effect
|
||||
## LRN-088 — useT() returns a new function each render: never a dependency of a data effect (2026-10-26)
|
||||
|
||||
Context: V1-1.6 record picker. A search callback formatting rows with `t` would change every render → effect re-runs → request loop. Fix: search callbacks depend on ids only (`useCallback([workspaceId])`) and return raw rows; a `toItem(row)` prop formats at render (a language switch needs no new search).
|
||||
Apply: in this app, keep `t`/dict out of `useCallback`/`useEffect` deps of anything that fetches; format at render. Same for any hook returning fresh functions.
|
||||
|
||||
## LRN-089 | 2026-10-26 | Playwright on the sandbox: late replays fail after the test; axe target-size flags controls under a sticky bar
|
||||
## LRN-089 — Playwright on the sandbox: late replays fail after the test; axe target-size flags controls under a sticky bar (2026-10-26)
|
||||
|
||||
Context: V1-1.6 e2e. (1) `routeToSandbox` replays with `route.fetch` then `fulfill`; a request still in flight when the last assertion passed hit « Fetch response has been disposed » at context close → test failed after success. Fix: `afterEach(context.unrouteAll({ behavior: 'ignoreErrors' }))`; and end tests on a state that needs the last reload (e.g. relations reloaded). (2) At 375 px, axe `target-size` failed on 44 px buttons partly under the sticky top bar when the page was scrolled to the bottom state under test; scanning after `scrollTo(0,0)` passes; documented as a limit, not hidden.
|
||||
Apply: suites that proxy requests in route handlers → unrouteAll ignoreErrors per test; phone axe scans of bottom-of-page states → scan from top and say why in BROWSER_TESTS.
|
||||
|
||||
## LRN-090 | 2026-10-26 | Supabase CLI 2.120 side effects on a shared local stack: test db, status, migration up
|
||||
## LRN-090 — Supabase CLI 2.120 side effects on a shared local stack: test db, status, migration up (2026-10-26)
|
||||
|
||||
Context: V1-1 DEV preflight, CLI read from bundled binary strings, not docs. (1) `supabase test db` runs `create extension if not exists pgtap with schema extensions`, then `drop extension if exists pgtap` only when absent before: transient DDL; interrupted run leaves pgtap. (2) `supabase status` default output prints SERVICE_ROLE_KEY, SECRET_KEY, JWT_SECRET; `-o env | grep '^API_URL='` safe. (3) `pnpm db:types:check` without `-s` adds 2 `>` header lines from pnpm → count drift with `pnpm -s`. (4) pg_dump -Fc of `postgres` restored `--no-owner` into scratch db of same image: 26 privilege refusals only (vault, pg_stat_statements_reset, pg_reload_conf, default privileges, grant options); md5 of `t::text` per table (timezone UTC) identical after restore → good restore proof. (5) Storage file backend keeps bytes in container volume `/mnt`; DEV had 11 files for 2 rows (reset leftovers).
|
||||
Apply: any procedure on DEV → read CLI behaviour from installed binary; read-only SQL via PGOPTIONS default_transaction_read_only; compare fingerprints, not only counts.
|
||||
|
||||
## LRN-091 | 2026-10-26 | Restore with "expected errors" never validated by message count; filter TOC, exit 0
|
||||
## LRN-091 — Restore with "expected errors" never validated by message count; filter TOC, exit 0 (2026-10-26)
|
||||
|
||||
Context: V1-1 restore check. LRN-090 (4) called 26 pg_restore errors "privilege refusals" and report double-counted them (28): wrong frame. Real: 26 TOC entries `postgres` cannot replay under `--no-owner` on same Supabase image: 18 DEFAULT ACL of supabase_admin/supabase_auth_admin, 5 vault ACL (grant option to self), ACL pg_reload_conf + pg_stat_statements_reset, COPY vault.secrets = data load fail, lossless only with vault empty. Each failing entry also carries other grants (service_role, anon). `--no-acl` loses app grants; `--exit-on-error` alone stops at COPY. Fix: `pg_restore --list` → exclude exact entries by anchored regex → count per kind must equal catalog prediction (D default ACL rows + 8) → `--use-list --single-transaction --exit-on-error` → exit 0, empty log, rows md5 + effective ACL (`acldefault`) identical. pg_dump drops ACL equal to default → compare effective, not stored. Expected count is per-instance: DEV D=21 vs sandbox 18 (supabase_functions schema).
|
||||
Apply: any restore check → real exit status from shell, every failing command classified (object, cause, data impact), conditions explicit (empty table), prefer filtered TOC with exit 0; derive expected exclusions from target catalog, never from rehearsal host; never widen pattern to go green.
|
||||
|
||||
## LRN-092 | 2026-10-27 | Restore rehearsal on sandbox dump proves nothing about DEV-only objects; first real-dump run
|
||||
## LRN-092 — Restore rehearsal on sandbox dump proves nothing about DEV-only objects; first real-dump run (2026-10-27)
|
||||
|
||||
Context: V1-1 step 3b, first run on real DEV dump. Filtered TOC (29 = D+8) right, but exit 1: `GRANT USAGE ON SCHEMA supabase_functions` names cluster role `supabase_functions_admin`, absent in sandbox (roles are cluster-level, not in dump). Rehearsal on sandbox dump (LRN-091) could not see it. Fix: NOLOGIN no-privilege role in sandbox only → exit 0, empty log, 28+15 identical.
|
||||
Apply: restore check on real dump before trusting rehearsal; roles named by ACL/owner entries must exist in target cluster (`--no-owner` needs name, not powers); never widen exclusions, fix the target; create minimal role, never copy login/CREATEROLE/password.
|
||||
|
||||
## LRN-093 | 2026-10-27 | pgTAP on a used stack: global queue counts and fixed seed keys break; lease base work in-tx, scope to fixture
|
||||
## LRN-093 — pgTAP on a used stack: global queue counts and fixed seed keys break; lease base work in-tx, scope to fixture (2026-10-27)
|
||||
|
||||
Context: `db:test` on DEV after M1-M3. 007 inserted seed drawing key already uploaded (unique collision, 4 assertions never run); 010 counted 13 DEV due purge rows. Audit found more: claim_avatar_jobs takes oldest uploaded row, leftovers sweep whole bucket, expire_pending_uploads counts all stale rows. Clean sandbox / PGlite never show it.
|
||||
Fix: 007 seed key in pg_temp table, confirmation cleared in-tx, insert only if absent + assertion "object once"; 010 section 0 leases base's due purges + jobs and expires stale uploads in-tx (capped loop) + setup assertion, leftovers by fixture key prefix. Proof: reproduce on sandbox with fictitious conditions first, mutation run (mutation + suite body in one rolled-back tx) on clean and loaded base, old vs new detection sets compared.
|
||||
Apply: SQL test touching a worker queue or shared bucket → neutralise or scope pre-existing work inside the test tx, never count globally; validate on a sandbox seeded like the target before running on it.
|
||||
|
||||
## LRN-094 | 2026-10-27 | "Page scrolls sideways at 375 px": measure before CSS; zoom fakes it, implicit grid track hides a real one
|
||||
## LRN-094 — "Page scrolls sideways at 375 px": measure before CSS; zoom fakes it, implicit grid track hides a real one (2026-10-27)
|
||||
|
||||
Context: V1-1 DEV acceptance RESP-01. Owner saw whole-page sideways scroll everywhere at 375 px (DevTools responsive). Sandbox sweep (Chromium mobile + desktop with scrollbars shown via `ignoreDefaultArgs: ['--hide-scrollbars']`, WebKit iPhone, Firefox; 280-430 px) found none at 375; owner then measured DEV with a console snippet (cw/sw + topmost offending boxes, classes only): no overflow without zoom → browser zoom was the cause. Same sweep with long account e-mails found a real defect: dashboard `grid gap-4 md:grid-cols-2` has no explicit column below md → implicit `auto` track = cards' min-content → `truncate` e-mail never truncates, cards past screen from ~31 chars at 320 px.
|
||||
Fix: `grid-cols-1` (minmax(0,1fr)) + e-mail wraps (`min-w-0 [overflow-wrap:anywhere]`). Test sweeps 320-430 + desktop with long values, proven failing on old code.
|
||||
Apply: overflow report → ask how observed (zoom, preset, device type), give owner a read-only console probe for DEV, reproduce with realistic max-length values on sandbox; a grid used as a single column on phones needs `grid-cols-1`, else one unbreakable value widens every card.
|
||||
|
||||
## LRN-095 — Port a safe runner verbatim; prove refusals with forged JWTs + strace; one-line gates.sh oracles (2026-11-02)
|
||||
Context: porting safe runner V1-2 → develop (bugfix/avatar-e2e-sandbox-only, 2026-11-02).
|
||||
Pattern 1: port by verbatim block extraction (`sed -n 'a,bp'` from reference worktree, by function name), oracle = python "chunk in file" per block + forbidden names absent; keeps protections intact, later merge rule = take reference file whole, check diff empty.
|
||||
Pattern 2: refusal proofs with FORGED unsigned JWTs (`base64url(header).base64url(payload).x`, iss varied), never DEV or sandbox secrets; strace `-f -e trace=connect,sendto,sendmsg` on bash/vitest binary (never via pnpm), curl positive control, one case per guard clause + mixed-issuer case; hostile DEV exports on positive run; watcher with filtered docker templates only (raw inspect leaks keys).
|
||||
Pattern 3: `gates.sh` CHECK = one line; heredoc / multi-line python is NOT parsed (silent NOT-MET "wanted PY"); use `python3 -I -c '…'`. Oracle wording must match doc wording ("names it" vs "invokes it").
|
||||
Pattern 4: `pkill -f <name>` kills own shell when the command line contains <name> (exit 144); use pid files or self-timed servers.
|
||||
Apply: any runner port, any "no IP connection" proof, any contract oracle.
|
||||
@@ -15,6 +15,8 @@ paths: ["supabase/migrations/**", "supabase/tests/**", "packages/supabase/**", "
|
||||
from public and granted only to the roles that evaluate them.
|
||||
- A migration is never edited once applied. Each migration ships its pgTAP file with
|
||||
allowed AND denied cases, and a regenerated `database.types.ts`.
|
||||
- Every migration step runs first on the throwaway sandbox (`pnpm db:sandbox`,
|
||||
`scripts/db-sandbox.sh`), never against DEV; changes to DEV stay owner actions (LRN-080).
|
||||
- The browser holds the anon key only. The `service_role` key value never appears in env.js, .env.example or code;
|
||||
operator scripts under `packages/*/scripts/` read it from the environment and are never bundled.
|
||||
- pgTAP files run on PGlite and on the real image: scope counts to fixture ids, pin `collate "C"` on text ordering.
|
||||
@@ -1,5 +1,8 @@
|
||||
# TODO — Osteo Report MVP
|
||||
|
||||
## Actionable
|
||||
<!-- next items; the session digest shows the first 3 unchecked (else the first 3 of the file) -->
|
||||
|
||||
## Status (2026-05-21): catalog v2.0 + full 26-zone horse coverage in place — B4 polish + ship gate next
|
||||
|
||||
Domain pivot bundle (B0 schema, B1 report v2, B2 UI/PDF, B3 i18n) shipped on
|
||||
@@ -543,6 +546,11 @@ Inventory: `.claude/audits/2026-10-25-functional-inventory.md`. Each item: treat
|
||||
- [ ] RR-7 accessibility: WCAG target to set; dialog focus trap/restore (done V1-1.3, native modal dialog), close button 24 px, canvas zones keyboard-unreachable, axe test (done V1-1.3: e2e:ui, e2e:shell), D2/D5 Context7 items (RUST.md §10.14). Pre-existing serious axe findings let through by exact node in `apps/app/e2e/support/browser.ts` KNOWN_VIOLATIONS: LanguageSwitcher label-in-name (« FR » shown, « Passer en français » announced), top bar account link label-in-name (display name shown, « Mon compte » announced), DashboardRoute `dl` with a status row lacking dt/dd. Seen outside the scanned states: ObservationCard header `nested-interactive` + label-in-name (editor with an observation); moderate: duplicate `main` landmarks (App + routes), no h1 on Home
|
||||
- [ ] RR-8 mobile and end-to-end: real-browser e2e for sign-up, login, account, avatar, full editor flow, export, locale, mobile drawer (TEST_STRATEGY §1 `apps/app/e2e`); per-check device results (J1/J2 recorded as a whole)
|
||||
- [ ] RR-9 release 0.2.0 fate (Steps 3–6 on TS engines, 341 commits behind develop): ship, supersede, or rebase; sheet bundle default `none`
|
||||
- [ ] RR-11 sandbox-only e2e follow-ups (bugfix/avatar-e2e-sandbox-only 2026-11-02, BLK-013, LRN-095; audit `.claude/audits/2026-11-02-avatar-e2e-sandbox-only.md`):
|
||||
- [ ] V1-2 → develop merge: `scripts/db-sandbox.sh` conflicts (header, function block, dispatcher, sed range) → take V1-2's file whole, `git diff <V1-2 tip> -- scripts/db-sandbox.sh` empty; keep every protection (constants unconditional, `/dev/tcp` probe, `docker port` check, 600 worker env file); V1-2 adopts `noRedirectFetch` in the avatar suite (d3dfd03); doc lines reworded on develop → keep V1-2's text; registry IDs BLK-013 / LRN-095 collide with V1-2's numbering → renumber at integration
|
||||
- [ ] old checkouts still hold the DEV scripts (`scripts/avatar-e2e.sh`, old `sheet-assets-e2e.sh`): main checkout `/home/bchanot/Documents/faunosteo` (feature/v1-1-clients-animals, merged) and worktree `old-958228a`; `pnpm e2e:avatar` there targets DEV; agents never run them; owner decides (move main checkout to develop, `gitflow.sh delete`, worktree removal)
|
||||
- [ ] V1-2 session: rebuild `faunosteo_worker:dev` (`pnpm worker:image`, the tag now holds develop's build d841660a) and `pnpm db:sandbox up fresh` before its next sandbox run
|
||||
- [ ] residual LOW: every docker call follows `DOCKER_HOST` / context; `worker_env` read by the EXIT trap before assignment (`worker_env=` before `trap`); literal password of the two throwaway `up upgrade` accounts (db-sandbox.sh:182-184); gateway container less hardened than the worker (no `--cap-drop ALL` / `--read-only` / limits); shared container names across worktrees (a concurrent run is killed, fails closed); `NODE_USE_ENV_PROXY` proxy path (unset in every proof)
|
||||
- [ ] RR-10 census tools maintenance (LOW `#[ignore]` positions) and controlled oracle evolution on a new anatomical changeset
|
||||
|
||||
## Phase A — DONE (kept for reference)
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# CONTRACT — avatar-e2e-sandbox-only
|
||||
- date: 2026-11-02 | flow: bugfix | branch: bugfix/avatar-e2e-sandbox-only (off develop 6287e5b)
|
||||
- status: active
|
||||
- worktree: /tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar
|
||||
- reference worktree (V1-2 a15c35c): /tmp/claude-1000/-home-bchanot-Documents-faunosteo/e641af9a-743e-46d0-9804-99667836040e/scratchpad/v1-2
|
||||
- plan: .claude/tasks/plans/2026-11-02-avatar-e2e-sandbox-only-0215.md (revision 3)
|
||||
|
||||
## REQUEST (verbatim — IMMUTABLE)
|
||||
|
||||
Owner brief « Suite incident DEV et préparation de la validation graphique V1-2.4 » (2026-11-02), §1 and §3:
|
||||
|
||||
> ## 1. Nouveau bugfix urgent sur develop : e2e:avatar
|
||||
>
|
||||
> Je t'autorise à créer une branche `bugfix/*` dédiée depuis `develop`, dans un worktree sûr, afin de neutraliser l'ancien `pnpm e2e:avatar` qui peut encore écrire dans DEV.
|
||||
>
|
||||
> Appliquer la même approche prudente que pour `sheet-assets` :
|
||||
>
|
||||
> - Préférer un portage minimal du runner sûr déjà développé dans V1-2 si toutes ses dépendances sont disponibles.
|
||||
> - Sinon, remplacer le point d'entrée par un refus explicite sans effet de bord.
|
||||
> - Aucun accès automatique à DEV, ni lecture ni écriture.
|
||||
> - Aucune récupération implicite des clés par `supabase status`.
|
||||
> - Aucun repli sur les URL, bases, comptes ou buckets DEV.
|
||||
> - Refus avant toute connexion en cas de configuration absente ou invalide.
|
||||
> - Tests des refus avec preuve d'absence de connexion IP.
|
||||
> - Revue de sécurité indépendante ciblée.
|
||||
>
|
||||
> Après réussite de ces vérifications, je t'autorise à fusionner uniquement ce bugfix dans `develop`, selon Gitflow.
|
||||
>
|
||||
> Ne fusionne pas la branche V1-2.
|
||||
>
|
||||
> ## 3. Limites de sécurité du runner
|
||||
>
|
||||
> Conserver le suivi des LOW signalés.
|
||||
>
|
||||
> Le contrôle de l'émetteur d'un JWT n'équivaut pas à une vérification de signature. Ne le présenter ni comme une authentification cryptographique complète ni comme l'unique protection.
|
||||
>
|
||||
> La restriction stricte de destination et l'isolation du bac à sable restent obligatoires.
|
||||
>
|
||||
> Vérifier que les redirections, les variables héritées et les configurations ambiguës ne permettent pas de sortir du bac à sable.
|
||||
|
||||
Skill invocation: « develop: neutraliser `pnpm e2e:avatar` (scripts/avatar-e2e.sh lit les clés DEV via supabase status, démarre le worker sur le réseau DEV, écrit et accélère les purges). Porter le runner sûr de V1-2 (db-sandbox avatar-e2e + garde dans la suite) ou refus explicite. Branche bugfix/* depuis develop dans un worktree sûr, aucun accès DEV, refus prouvés sans connexion IP, revue sécurité indépendante, puis merge dans develop (autorisé par le propriétaire). »
|
||||
|
||||
## CLARIFICATIONS
|
||||
Q: port `cmd_sheet_assets_e2e` too (same gateway), so `pnpm e2e:sheet-assets` works on develop? / A: no, avatar only [gated 2026-11-02]
|
||||
Q (challengers): the port cannot make the later V1-2 → develop merge conflict-free in db-sandbox.sh / A: accepted, expectations and rule written in the plan ("take V1-2's file whole") [gated 2026-11-02]
|
||||
Q (owner, checkpoint 2026-11-02): close the redirect LOW before the merge / A: the suite's two client factories pass `global: { fetch: noRedirectFetch }` (`redirect: 'error'`, tests/e2e/noRedirectFetch.ts), a regression test with a real 302 in `pnpm --filter @faunosteo/supabase test:run`, live proof j; the suite file therefore differs from V1-2 by those lines only (V1-2 gets the same change at integration) [gated 2026-11-02]
|
||||
Q (executor): the plan's CLAUDE.md:490 and SUPABASE.md §6 wording names `scripts/avatar-e2e.sh` as removed, criterion 1 said "nothing names it" / A: criterion 1 narrowed to "nothing invokes it", lines containing `removed` or `the DEV script` (the SUPABASE.md note wraps before `removed`) excluded from the oracle (same wording as V1-2) [gated 2026-11-02, internal]
|
||||
Q (challengers): proof f (port taken) contains one loopback connect by construction / A: criterion for f = the only AF_INET connect is 127.0.0.1:57800; flagged to the owner [gated 2026-11-02]
|
||||
|
||||
## ACCEPTANCE CRITERIA
|
||||
1. The DEV runner is gone: `scripts/avatar-e2e.sh` no longer exists and nothing in the tree invokes or documents it as runnable; the only remaining mentions say it was removed (CLAUDE.md workflow line, SUPABASE.md §6 note, the V1-2 wording).
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; test ! -e "$W/scripts/avatar-e2e.sh" && ! git -C "$W" grep -n "avatar-e2e\.sh" -- . ':!.claude' | grep -v -i -E 'removed|the DEV script' | grep -q . && echo DEV_RUNNER_GONE
|
||||
EXPECT: DEV_RUNNER_GONE
|
||||
EVIDENCE: MET exit=0 marker-found :: DEV_RUNNER_GONE
|
||||
2. `pnpm e2e:avatar` is the sandbox alias and the runner dispatches it; the script parses.
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; grep -qF '"e2e:avatar": "bash scripts/db-sandbox.sh avatar-e2e"' "$W/package.json" && bash -n "$W/scripts/db-sandbox.sh" && grep -qF 'avatar-e2e) shift; cmd_avatar_e2e "$@" ;;' "$W/scripts/db-sandbox.sh" && echo ALIAS_OK
|
||||
EXPECT: ALIAS_OK
|
||||
EVIDENCE: MET exit=0 marker-found :: ALIAS_OK
|
||||
3. The ported blocks are the V1-2 bytes: the suite file is identical to V1-2's once the lines naming `noRedirectFetch` are dropped (the import and the two `global: { fetch: noRedirectFetch }` options, owner-gated); db-sandbox.sh contains V1-2 a15c35c lines 47-52 (variables), 58-61 (REPO check), 255 (down), 270-332 (gateway and worker helpers) and 342-359 (`cmd_avatar_e2e`) verbatim, and does NOT contain `cmd_verify_e2e` nor `cmd_sheet_assets_e2e`.
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; V=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/e641af9a-743e-46d0-9804-99667836040e/scratchpad/v1-2; python3 -I -c 'import sys; a=[l for l in open(sys.argv[1],encoding="utf-8") if "noRedirectFetch" not in l]; b=open(sys.argv[2],encoding="utf-8").readlines(); sys.exit("suite differs beyond noRedirectFetch lines") if a!=b else None' "$W/packages/supabase/tests/e2e/avatar-flow.e2e.ts" "$V/packages/supabase/tests/e2e/avatar-flow.e2e.ts" && python3 -I -c 'import sys; dev=open(sys.argv[1],encoding="utf-8").read(); ref=open(sys.argv[2],encoding="utf-8").read().split("\n"); bad=[f"{a}-{b}" for a,b in [(47,52),(58,61),(255,255),(270,332),(342,359)] if "\n".join(ref[a-1:b]) not in dev]; bad+=[n for n in ("cmd_verify_e2e","cmd_sheet_assets_e2e") if n in dev]; sys.exit("not verbatim / forbidden: "+" ".join(bad)) if bad else print("BLOCKS_IDENTICAL")' "$W/scripts/db-sandbox.sh" "$V/scripts/db-sandbox.sh"
|
||||
EXPECT: BLOCKS_IDENTICAL
|
||||
EVIDENCE: MET exit=0 marker-found :: BLOCKS_IDENTICAL
|
||||
4. No DEV identifier remains in the runner or the suite (no `supabase status`, no 54321, no DEV container or network name).
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; ! grep -rn "supabase status\|54321\|supabase_kong\|supabase_db_faunosteo\|supabase_network_faunosteo" "$W/scripts/db-sandbox.sh" "$W/packages/supabase/tests/e2e" && echo NO_DEV_IDS
|
||||
EXPECT: NO_DEV_IDS
|
||||
EVIDENCE: MET exit=0 marker-found :: NO_DEV_IDS
|
||||
5. Refusal before any connection, no environment (plan proof b): the suite throws at load and opens no AF_INET / AF_INET6 socket. Positive control: the same trace filter, run on `curl -s http://127.0.0.1:9/`, shows an AF_INET connect.
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; T="$(mktemp -d)"; strace -f -e trace=connect,sendto,sendmsg -o "$T/ctl" curl -s --max-time 2 http://127.0.0.1:9/ >/dev/null 2>&1; grep -q 'AF_INET' "$T/ctl" || { echo "positive control failed"; exit 1; }; (cd "$W/packages/supabase" && env -u SUPABASE_URL -u SUPABASE_ANON_KEY -u SUPABASE_SERVICE_ROLE_KEY -u AVATAR_E2E_DB_CONTAINER strace -f -e trace=connect,sendto,sendmsg -o "$T/run" node_modules/.bin/vitest run --config vitest.e2e.config.ts >"$T/out" 2>&1); rc=$?; [ "$rc" -ne 0 ] && grep -q "run it through pnpm e2e:avatar, on the sandbox stack only" "$T/out" && ! grep -q 'AF_INET' "$T/run" && echo REFUSED_NO_IP
|
||||
EXPECT: REFUSED_NO_IP
|
||||
EVIDENCE: MET exit=0 marker-found :: REFUSED_NO_IP
|
||||
6. The other refusals of the plan (a, c, d, e, f, h, i) and the straced positive sandbox run with hostile DEV exports are executed by the orchestrator (never a sub-agent), by absolute path, and recorded in `.claude/audits/2026-11-02-avatar-e2e-sandbox-only.md` with the strace criterion per case (f: the single loopback connect to 127.0.0.1:57800 named), the `docker ps` / `docker port` / `docker inspect` readings, the DEV containers' start times unchanged, and the hand-off to V1-2 (`down` at the end). Judged by the verifier against the log.
|
||||
7. Documentation names the sandbox path only and is true on develop: no instruction to run the worker or the suite against `supabase_network_faunosteo` / `supabase status` for the e2e, the removal date is 2026-11-02, no `verify-e2e`, no "V1-2.3" introduced; STORAGE.md §6 no longer tells the reader to run `pnpm --filter @faunosteo/supabase test:e2e` against the local stack. RUST.md:178, BROWSER_TESTS.md:103, SUPABASE.md:38 and CHANGELOG.md untouched. Judged by the verifier.
|
||||
8. The static gates pass in the worktree.
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; cd "$W" && corepack pnpm -s typecheck >/dev/null 2>&1 && corepack pnpm -s lint >/dev/null 2>&1 && echo STATIC_GREEN
|
||||
EXPECT: STATIC_GREEN
|
||||
EVIDENCE: MET exit=0 marker-found :: STATIC_GREEN
|
||||
9. The guard's limits are written where a reader meets them (brief §3), without touching the byte-copied code: the SUPABASE.md §5.1 row for `pnpm db:sandbox avatar-e2e` and the audit log state that the issuer check routes to the sandbox and is not a signature check, and name what the isolation rests on (fixed gateway URL in the worker's 600 env file, `max_redirects(0)` and `proxy(None)` in `crates/worker/src/http.rs`, sandbox-signed keys, upstreams by container name) and the redirect refusal of criterion 10 (the former residual LOW). Judged by the verifier.
|
||||
10. The suite's supabase-js clients refuse HTTP redirects: `tests/e2e/noRedirectFetch.ts` exports `noRedirectFetch` (`fetch(input, { ...init, redirect: 'error' })`, `redirect` set last), both client factories of the suite pass `global: { fetch: noRedirectFetch }`, no production client (`packages/supabase/src`, `apps/app/src`) changes, and the regression test `tests/no-redirect-fetch.test.ts` proves with two local `node:http` servers that a 302 from the first towards the second is not followed by auth, REST and Storage calls (the second server receives no request, the `apikey` header reaches only the first) while a control fetch with the default `follow` does reach the second. Live proof j (orchestrator): the suite with forged `iss: db-sandbox` keys against a 302 listener on 127.0.0.1:57800 pointing at 127.0.0.1:57801 opens no connect to 57801 (strace), logged in the audit file.
|
||||
CHECK: W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar; grep -qF "redirect: 'error'" "$W/packages/supabase/tests/e2e/noRedirectFetch.ts" && [ "$(grep -c 'global: { fetch: noRedirectFetch }' "$W/packages/supabase/tests/e2e/avatar-flow.e2e.ts")" = 2 ] && git -C "$W" diff --quiet 6287e5b -- packages/supabase/src apps/app/src && cd "$W/packages/supabase" && node_modules/.bin/vitest run tests/no-redirect-fetch.test.ts >/dev/null 2>&1 && echo NO_REDIRECT_OK
|
||||
EXPECT: NO_REDIRECT_OK
|
||||
EVIDENCE: MET exit=0 marker-found :: NO_REDIRECT_OK
|
||||
|
||||
## FILE SCOPE
|
||||
packages/supabase/tests/e2e/noRedirectFetch.ts (new), packages/supabase/tests/no-redirect-fetch.test.ts (new), scripts/db-sandbox.sh, scripts/avatar-e2e.sh (deleted), package.json, packages/supabase/tests/e2e/avatar-flow.e2e.ts, packages/supabase/vitest.e2e.config.ts, scripts/dev-env.sh, CLAUDE.md, README.md, docs/development/{STORAGE,SUPABASE,WORKSPACE,TEST_STRATEGY,ENVIRONMENTS,IDENTITY}.md, .claude/audits/2026-11-02-avatar-e2e-sandbox-only.md (new), .claude/tasks/{plans,contracts}/2026-11-02-avatar-e2e-sandbox-only-*.md
|
||||
@@ -0,0 +1,22 @@
|
||||
# CONTRACT — sandbox-rule-line (LRN-080 promotion made true)
|
||||
- date: 2026-11-14 | flow: hotfix | branch: chore/sandbox-rule-line (off develop)
|
||||
- status: active
|
||||
|
||||
## REQUEST (verbatim — IMMUTABLE)
|
||||
faunosteo: LRN-080 status (2026-11-13, block F) says "implemented, promoted to rule line .claude/rules/database.md" but that rule file has no sandbox line: the promotion claim is false. Add one bullet to .claude/rules/database.md from LRN-080's own Apply text: every migration step is tried first on the throwaway sandbox (`pnpm db:sandbox`, scripts/db-sandbox.sh), never on DEV; DEV changes stay owner actions. 1 file.
|
||||
|
||||
## CLARIFICATIONS
|
||||
- [gated 2026-11-14] wording = LRN-080 Apply line; no challenge (doc line, no behaviour); placed right after the "A migration is never edited once applied" bullet.
|
||||
|
||||
## ACCEPTANCE CRITERIA
|
||||
1. The rule file carries the sandbox line.
|
||||
CHECK: grep -c 'db:sandbox' .claude/rules/database.md
|
||||
EXPECT: 1
|
||||
EVIDENCE: PENDING
|
||||
2. Frontmatter unchanged, project rules check green.
|
||||
CHECK: git diff -U0 .claude/rules/database.md | grep -c '^[-+]paths:'
|
||||
EXPECT: 0
|
||||
EVIDENCE: PENDING
|
||||
|
||||
## FILE SCOPE
|
||||
.claude/rules/database.md
|
||||
@@ -0,0 +1,200 @@
|
||||
# PLAN — bugfix: `pnpm e2e:avatar` on develop can no longer reach DEV
|
||||
|
||||
- date: 2026-11-02 | flow: bugfix | branch: bugfix/avatar-e2e-sandbox-only (off develop 6287e5b)
|
||||
- revision 3: three challengers (correctness, robustness, simplicity: CONCERNS each, no BLOCKER), then one
|
||||
confirmation challenger (robustness, CONCERNS(5)); every MAJOR folded in as a named change
|
||||
- worktree: /tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar
|
||||
- reference (safe runner already built): feature/v1-2-anatomical-sheets at a15c35c, worktree
|
||||
/tmp/claude-1000/-home-bchanot-Documents-faunosteo/e641af9a-743e-46d0-9804-99667836040e/scratchpad/v1-2
|
||||
(commits cdd43ac, 2a84e37, 3c141c9, f924ad0)
|
||||
|
||||
## Bug
|
||||
|
||||
On develop, `pnpm e2e:avatar` = `bash scripts/avatar-e2e.sh`:
|
||||
- reads API_URL, ANON_KEY, SERVICE_ROLE_KEY from `supabase status -o env` (the DEV stack), lines 12-23;
|
||||
- starts the worker container on `supabase_network_faunosteo` against `http://supabase_kong_faunosteo:8000`
|
||||
(DEV Kong) with a 5 s sweep and a 0 s quarantine grace;
|
||||
- runs `packages/supabase/tests/e2e/avatar-flow.e2e.ts` with those keys: creates a confirmed account on DEV,
|
||||
signs in as the seeded `bob@faunosteo.local` with the DEV password written in the suite
|
||||
(`LocalDev-only-password-1`), uploads, and `expeditePurges()` moves EVERY due date of DEV's
|
||||
`private.object_purge_queue` to now; `psql` goes to `supabase_db_faunosteo` by default (suite :29-31, :175, :215).
|
||||
Root cause: neither the runner nor the suite knows an authorised target; URL, keys and container come
|
||||
from the environment or from DEV defaults. Same family as the sheet-assets incidents of 2026-11-01
|
||||
(fixed on develop by 6287e5b).
|
||||
|
||||
## Decisions already taken (constraints)
|
||||
|
||||
- Owner brief 2026-11-02 §1: minimal port of the V1-2 runner if its dependencies exist on develop, else an
|
||||
explicit refusal; no DEV access (read or write), no implicit key recovery through `supabase status`, no
|
||||
fallback to DEV URL / database / accounts / buckets; refusal before any connection when the configuration
|
||||
is absent or invalid; refusals proven without any IP connection; independent security review; merge into
|
||||
develop only (never V1-2).
|
||||
- Owner brief §3: a JWT issuer check is not a signature check; never present it as full cryptographic
|
||||
authentication nor as the only protection; strict destination restriction + sandbox isolation stay
|
||||
mandatory; check that redirects, inherited variables and ambiguous configurations cannot leave the sandbox.
|
||||
- Scope answer (gated 2026-11-02): avatar only; `cmd_sheet_assets_e2e` is NOT ported (`pnpm e2e:sheet-assets`
|
||||
keeps refusing on develop until the V1-2 merge).
|
||||
- LRN-110: absolute verified cwd for every command, no `cd X && cmd &`, quoted heredocs, env validated inside
|
||||
the script; agents never run the old scripts (develop's `scripts/avatar-e2e.sh`, the main checkout's or
|
||||
old-958228a's copies).
|
||||
- Each ported block is copied from the V1-2 text (same bytes) where develop has no conflicting need; this
|
||||
does NOT make the later V1-2 → develop merge conflict-free (see "Merge expectations").
|
||||
|
||||
Dependencies checked on develop: `scripts/db-sandbox.sh` (network, db/auth/rest/storage/mail containers,
|
||||
keys signed with issuer `db-sandbox` :80-81, `load_secrets` :50, `wait_for` :63, `with_sandbox_env` :229);
|
||||
the worker's default `run` logs `"event":"worker_start"` (`crates/worker/src/run.rs:121`, `main.rs:21-29`:
|
||||
`run` takes no argument on develop); the image is `static-debian13:nonroot` with `USER nonroot`
|
||||
(`crates/worker/Dockerfile:37-39`); `apps/app/e2e/support/sandbox.ts:111` creates its accounts with random
|
||||
passwords; `packages/supabase/src/assets.ts` identical on both branches.
|
||||
NOT ported (V1-2 only, with the reason): `SB_SEED_PW` / `seed_passwords` / `SANDBOX_SEED_PASSWORD`
|
||||
(develop's `packages/supabase/tests/sandbox/workspaces.sandbox.ts:197-199` signs in to
|
||||
`owner@faunosteo.local` with the seed password: rotating it would break `pnpm db:sandbox test`),
|
||||
`throwaway_password`, `verify-e2e` / `cmd_verify_e2e` (needs `run --jobs sheet-verify`, V1-2 worker only),
|
||||
`test` args pass-through, `cmd_sheet_assets_e2e` (scope answer).
|
||||
|
||||
## Fix plan (files in the bugfix worktree)
|
||||
|
||||
1. `scripts/db-sandbox.sh` — port from V1-2 a15c35c, copied by function name, bytes identical:
|
||||
- usage header: insert after develop line 16 the V1-2 `avatar-e2e [args]` three lines only (V1-2 :20-22);
|
||||
the usage fallback becomes `sed -n '2,26p'` (header grows by 3 lines);
|
||||
- variables: after `MAIL=…` insert V1-2 :47-51 verbatim (`GATEWAY=`, `WORKER=faunosteo_dbsandbox_worker_verify`,
|
||||
`AVATAR_WORKER=`, `GATEWAY_IMAGE=nginx:1.31-alpine`, `WORKER_IMAGE=faunosteo_worker:dev`); the PORT line
|
||||
becomes V1-2 :52 (`PORT_GATEWAY=57800` appended). `WORKER=` is inert on develop; it lets `down` remove a
|
||||
verify worker left by an interrupted V1-2 run (shared Docker names) and keeps the line identical;
|
||||
- the `REPO="$(realpath "$PWD")"` check: V1-2 :58-62 (comment, `REPO=`, `case`, pattern, `esac`) replace develop :45-47 (a STATE inside the repository
|
||||
reached through a symlink no longer passes; the port adds `$STATE/worker.XXXXXX` files holding the
|
||||
sandbox service key);
|
||||
- `cmd_down`: V1-2 :255 verbatim (`"$AVATAR_WORKER" "$WORKER" "$GATEWAY" "$REST" …`);
|
||||
- after `with_sandbox_env`: V1-2 :270-332 (`GATEWAY_CONF`, `start_gateway`, `start_worker`,
|
||||
`print_worker_log`, `worker_cleanup`, `worker_preflight`) and :342-359 (`cmd_avatar_e2e`, the comment
|
||||
above it through the closing brace, the suite invocation :356-358 included); NOT :333-341
|
||||
(`cmd_verify_e2e`) nor :361-376 (`cmd_sheet_assets_e2e`);
|
||||
- dispatcher: `avatar-e2e) shift; cmd_avatar_e2e "$@" ;;` between `e2e-shell` and `sql`.
|
||||
- `bash -n $W/scripts/db-sandbox.sh` and `bash $W/scripts/db-sandbox.sh` (usage, exit 1; absolute path, never a
|
||||
bare `pnpm db:sandbox`) prove the file parses and the header range is right.
|
||||
2. `scripts/avatar-e2e.sh` — deleted (`git rm`).
|
||||
3. `package.json` — `"e2e:avatar": "bash scripts/db-sandbox.sh avatar-e2e"`.
|
||||
4. `packages/supabase/tests/e2e/avatar-flow.e2e.ts` — replaced by the V1-2 file (same bytes): guard at
|
||||
module load: `SUPABASE_URL === 'http://127.0.0.1:57800'`, `AVATAR_E2E_DB_CONTAINER === 'faunosteo_dbsandbox_db'`,
|
||||
both keys' payload `iss === 'db-sandbox'`, else `throw` before any client is created; clients built on
|
||||
the constant, never on the env URL; `psql` on the constant container; a random password per run; two
|
||||
accounts created per run and deleted after; `expeditePurges(userId)` scoped to the account's objects;
|
||||
`describe.skipIf(!configured)` gone: a wrong environment is an error, not a skip. The guard checks the
|
||||
issuer, not the role and not the signature (brief §3): a role mix-up fails at the first admin call
|
||||
against the sandbox; a forged `iss: db-sandbox` key passes the guard and fails at the sandbox's GoTrue.
|
||||
5. `packages/supabase/vitest.e2e.config.ts`, `scripts/dev-env.sh` — the comment lines (V1-2 text).
|
||||
6. Docs: only the lines this fix makes false (dead `scripts/avatar-e2e.sh` references, DEV-target
|
||||
instructions), worded so they are true on develop (removal date 2026-11-02, no "V1-2.3", no `verify-e2e`):
|
||||
- `CLAUDE.md`: the `db:sandbox` line (add `avatar-e2e` only), the `e2e:avatar` line, the two folder-structure
|
||||
lines (tests/e2e, scripts list), the "Storage or worker change" workflow line;
|
||||
- `docs/development/STORAGE.md` §6: the DEV `docker run` keeps its place with the V1-2 comment ("the worker
|
||||
beside the local stack, for the manual photo flow (IDENTITY.md); the e2e suite refuses this stack"), the
|
||||
`pnpm --filter @faunosteo/supabase test:e2e` line is DELETED (it would always throw), the `e2e:avatar`
|
||||
line becomes the sandbox alias;
|
||||
- `docs/development/SUPABASE.md` §3.2 block and §6 DEV-acceptance note; §5.1 table: a develop-only row for
|
||||
`pnpm db:sandbox avatar-e2e` that describes the gateway on its own (no reference to a verify-e2e row);
|
||||
- `docs/development/WORKSPACE.md`, `docs/development/TEST_STRATEGY.md`, `README.md:114`,
|
||||
`docs/development/ENVIRONMENTS.md:38`, `docs/development/IDENTITY.md:130` (the manual photo flow points at
|
||||
the STORAGE §6 `docker run` line, not at the e2e container: it sits on the sandbox network and is removed
|
||||
at exit).
|
||||
- NOT touched (still true after the fix): `docs/development/RUST.md:178`, `BROWSER_TESTS.md:103`,
|
||||
`SUPABASE.md:38`, `CHANGELOG.md` (neither 6287e5b nor the V1-2 commits added a line).
|
||||
|
||||
7. (owner, checkpoint 2026-11-02) `packages/supabase/tests/e2e/noRedirectFetch.ts`: `export const noRedirectFetch: typeof fetch = (input, init) => fetch(input, { ...init, redirect: 'error' })`; the suite's `anonClient()` and `serviceClient()` add `global: { fetch: noRedirectFetch }` (supabase-js hands `global.fetch` raw to auth-js and through `fetchWithAuth` to REST and Storage; no layer sets `redirect`, our wrapper sets it last); regression test `tests/no-redirect-fetch.test.ts` (two `node:http` servers, 302 from A to B, auth + REST + Storage calls fail, B sees nothing, `apikey` only at A, control plain fetch reaches B); live proof j under strace. The suite now differs from V1-2 by those lines: V1-2 takes the same change at integration (merge rule amended).
|
||||
|
||||
## Merge expectations (V1-2 → develop, later)
|
||||
|
||||
Develop's `db-sandbox.sh` is the merge-base text (9135d73); the port changes base regions V1-2 changes
|
||||
differently. Expected conflicts: the usage header, the function block (V1-2 has `cmd_verify_e2e` and
|
||||
`cmd_sheet_assets_e2e` around `cmd_avatar_e2e`), the dispatcher, the usage `sed` range. Rule: take V1-2's
|
||||
file whole; check with an empty `git diff <V1-2 tip> -- scripts/db-sandbox.sh` after the merge. The suite,
|
||||
`package.json`, `dev-env.sh`, the vitest comment and the ported variable / `down` / `REPO` lines merge
|
||||
cleanly, except the suite: V1-2 adopts the `noRedirectFetch` lines (owner decision 2026-11-02). Doc lines reworded for develop conflict with V1-2's: keep V1-2's text (same rule as the
|
||||
sheet-assets lines in TODO).
|
||||
|
||||
## Proof (log committed as `.claude/audits/2026-11-02-avatar-e2e-sandbox-only.md` on this branch)
|
||||
|
||||
Who runs what: the executor applies the code and the static checks (contract criteria 1-5, 8); the LIVE proofs
|
||||
below (a, c-i, the positive run) and the audit log are run by the orchestrator in the main loop, never by a
|
||||
sub-agent (incident 1 of 2026-11-01 was an executor's backgrounded `cd`).
|
||||
`W=/tmp/claude-1000/-home-bchanot-Documents-faunosteo/573c6c77-7294-4d96-a518-83afaafef8d1/scratchpad/bugfix-avatar`.
|
||||
Every command names `$W` explicitly: `bash "$W/scripts/db-sandbox.sh" …`, `corepack pnpm --dir "$W" …`,
|
||||
`"$W/packages/supabase/node_modules/.bin/vitest" …`; NEVER a bare `pnpm e2e:avatar` / `pnpm db:sandbox` /
|
||||
`pnpm worker:image` (the shell's cwd resets to the main checkout, which still holds the DEV runner).
|
||||
Pre-flight before any live command: `test ! -e "$W/scripts/avatar-e2e.sh"` and `grep -F '"e2e:avatar": "bash
|
||||
scripts/db-sandbox.sh avatar-e2e"' "$W/package.json"`; `docker ps -a --filter name=^faunosteo_worker_e2e$`
|
||||
(a leftover of the old DEV runner; read-only; the owner removes it if present); the DEV containers' start
|
||||
times recorded (`docker inspect -f '{{.State.StartedAt}}'`, read-only) and compared at the end.
|
||||
Keys used in c, d, e, h, i are FORGED unsigned JWTs built in the shell (`base64url(header).base64url(payload).x`),
|
||||
never read from `~/.cache/faunosteo-db-sandbox/secrets.sh` and never the DEV keys.
|
||||
Trace: `strace -f -e trace=connect,sendto,sendmsg -o <file>` on `bash "$W/scripts/db-sandbox.sh" …` or on the
|
||||
vitest binary directly, never through `pnpm` (its own process would be inside the trace). Criterion for a-e
|
||||
and i: no `AF_INET` / `AF_INET6` in the trace, except where stated.
|
||||
a. `bash "$W/scripts/db-sandbox.sh" avatar-e2e` with `FAUNOSTEO_SANDBOX_DIR` pointing at an empty temp dir
|
||||
(no secrets file) → `db-sandbox: not running`, exit 1, no connect, no container started;
|
||||
b. the suite (`vitest run --config vitest.e2e.config.ts` in `$W/packages/supabase`) with no environment →
|
||||
throws at load, no connect (contract oracle 5, positive control on `curl 127.0.0.1:9`);
|
||||
c. the suite with `SUPABASE_URL=http://127.0.0.1:54321`, `AVATAR_E2E_DB_CONTAINER=supabase_db_faunosteo` and
|
||||
two forged JWTs saying `iss: supabase-demo` → throws at load, no connect;
|
||||
d. the suite with the sandbox URL and forged `iss: db-sandbox` keys but `AVATAR_E2E_DB_CONTAINER=supabase_db_faunosteo`
|
||||
→ throws, no connect;
|
||||
e. the suite with the sandbox URL and container and a key whose payload is not JSON → throws, no connect;
|
||||
i. the suite with the sandbox URL and container, a forged anon key `iss: db-sandbox` and a forged service
|
||||
key `iss: supabase-demo`, then the swap → throws, no connect. This is the only case that isolates the
|
||||
issuer comparison itself (c stops at the URL, d at the container, e in the JSON.parse catch).
|
||||
h. (sandbox NOT running, nothing listens on 57800) the suite with the sandbox URL and container and two
|
||||
forged JWTs saying `iss: db-sandbox` → the guard passes, `beforeAll` fails with ECONNREFUSED; strace shows
|
||||
connects to 127.0.0.1:57800 only. The brief §3 point made visible: the issuer check routes, it does not
|
||||
authenticate; whoever holds 127.0.0.1:57800 would receive the keys the environment supplies.
|
||||
f. (after the setup below, sandbox up from this branch, image present) `bash "$W/scripts/db-sandbox.sh"
|
||||
avatar-e2e` with 127.0.0.1:57800 held by a foreign listener (`python3 -I -m http.server` bound to
|
||||
127.0.0.1:57800) → `already in use`, exit 1, `docker ps` shows no gateway and no avatar worker.
|
||||
EXCEPTION, by construction: the probe `(exec 3<>"/dev/tcp/127.0.0.1/$PORT_GATEWAY")` is one
|
||||
`connect(AF_INET, 127.0.0.1:57800)`; the criterion for f is "the only AF_INET connect is 127.0.0.1:57800;
|
||||
none to :54321 / :54322 or the LAN address". Flagged to the owner. Known limitation (not exercised): a port
|
||||
held by another run's `faunosteo_dbsandbox_gateway` is torn down by `worker_preflight` before the probe
|
||||
(shared container names and default STATE dir across worktrees); fails closed, sandbox only.
|
||||
Setup (destroys the current sandbox and the V1-2 build of the worker image; the V1-2 worktree belongs to an
|
||||
earlier session at its checkpoint, no run in progress; listed at the approval gate): `corepack pnpm --dir "$W"
|
||||
worker:image` (develop's crates), `bash "$W/scripts/db-sandbox.sh" down`, `bash "$W/scripts/db-sandbox.sh" up fresh`.
|
||||
Positive run, ONCE, under strace, WITH hostile exports in the shell: `SUPABASE_URL=http://127.0.0.1:54321`,
|
||||
`SUPABASE_ANON_KEY` and `SUPABASE_SERVICE_ROLE_KEY` forged (`iss: supabase-demo`),
|
||||
`AVATAR_E2E_DB_CONTAINER=supabase_db_faunosteo`, `SUPABASE_NETWORK=supabase_network_faunosteo`,
|
||||
`SUPABASE_INTERNAL_URL=http://supabase_kong_faunosteo:8000`, `WORKER_IMAGE=faunosteo_worker:local` (the old
|
||||
runner's knobs; the script's constant wins) → `bash "$W/scripts/db-sandbox.sh" avatar-e2e` 5/5; trace
|
||||
criterion: no connect to :54321 / :54322 or the LAN address; every other AF_INET connect named in the log
|
||||
(expected: 127.0.0.1:57800 from the suite, the `/dev/tcp` probe). A watcher started beforehand in the
|
||||
background with absolute paths (`until docker inspect faunosteo_dbsandbox_worker_avatar; do sleep 1; done`)
|
||||
records, DURING the run and with filtered templates only: `docker port faunosteo_dbsandbox_gateway 8000/tcp`
|
||||
(= 127.0.0.1:57800), the worker's networks (`{{range $k,$v := .NetworkSettings.Networks}}{{println $k}}{{end}}`
|
||||
= faunosteo_dbsandbox_net) and `{{range .Config.Env}}{{println .}}{{end}} | grep '^SUPABASE_URL='`
|
||||
(= http://faunosteo_dbsandbox_gateway:8000). NEVER a raw `docker inspect` or `.Config.Env` in the log: the
|
||||
service key sits there. After the run: both containers gone, DEV start times unchanged.
|
||||
What the isolation rests on (stated in the log with file:line, not "only one network": `NET` is a plain
|
||||
bridge that can route to the host and the LAN where DEV's Kong publishes): the worker's URL is fixed to the
|
||||
gateway container in the 600 env file, `crates/worker/src/http.rs:31` `max_redirects(0)` and `:33 proxy(None)`,
|
||||
the gateway's upstreams are the sandbox containers by name, the sandbox keys are signed with a secret DEV
|
||||
does not hold; `scripts/dev-env.sh:23` exports `FAUNOSTEO_DEV_API_URL` into every child of db-sandbox.sh,
|
||||
the suite included, and nothing reads it.
|
||||
Residuals (LOW, for the owner, no code change here, fixed in V1-2 first then ported): the suite's supabase-js
|
||||
clients use Node's global fetch (`redirect: follow`; `HTTP(S)_PROXY` honoured when `NODE_USE_ENV_PROXY=1`):
|
||||
no endpoint the suite calls redirects today, a proxy would receive sandbox keys only; `worker_env` is read by
|
||||
the EXIT trap before `start_worker` assigns it (an inherited value would be `rm -f`'d on an early `die`);
|
||||
every docker call follows `DOCKER_HOST` / the current context.
|
||||
Static: `grep -rn "supabase status\|54321\|supabase_kong\|supabase_db_faunosteo\|supabase_network_faunosteo" "$W/scripts/db-sandbox.sh" "$W/packages/supabase/tests/e2e"` → nothing;
|
||||
`git -C "$W" grep -n avatar-e2e.sh -- ':!.claude'` → nothing (the historical contract of 2026-10-13 under
|
||||
`.claude/` keeps its citation).
|
||||
Hand-off (in the log and to the owner): end with `bash "$W/scripts/db-sandbox.sh" down`; the V1-2 session
|
||||
rebuilds `faunosteo_worker:dev` (`pnpm worker:image` there) and runs `pnpm db:sandbox up fresh` before its next
|
||||
sandbox run (the develop secrets file has no SB_SEED_PW, V1-2's `load_secrets` refuses it: fails closed).
|
||||
Copies that STILL reach DEV after the merge: the main checkout `/home/bchanot/Documents/faunosteo` (branch
|
||||
feature/v1-1-clients-animals, merged, holds `scripts/avatar-e2e.sh` and the old `e2e:avatar` line: `pnpm
|
||||
e2e:avatar` there targets DEV until that checkout moves to develop and the branch is deleted with
|
||||
`gitflow.sh delete`), and the worktree old-958228a (same two scripts). Agents never run them.
|
||||
|
||||
## Gates
|
||||
- `bash -n`, `pnpm typecheck`, `pnpm lint`, `pnpm --filter @faunosteo/supabase test:run` (PGlite) green in
|
||||
the worktree.
|
||||
- fresh verifier on the contract; fresh security-auditor on the diff (MODE: gate), both before commit.
|
||||
- merge into develop with `gitflow.sh finish` only after the owner's go (brief §1 authorises it after the
|
||||
verifications succeed); never V1-2.
|
||||
@@ -34,13 +34,15 @@ case "$br" in
|
||||
*) exit 0 ;; # working branch — allow
|
||||
esac
|
||||
|
||||
# whitelist: all-staged-under-.claude/ (memory/doc/deploy helpers) or
|
||||
# .githooks/ (the hooks themselves, refreshed by the lib) — allow
|
||||
if [ -z "$(git diff --cached --name-only | grep -vE '^\.(claude|githooks)/' | head -1)" ]; then
|
||||
# whitelist: every staged path under .claude/{memory,tasks,audits,deploy}/ or
|
||||
# .githooks/ (memory/doc/deploy helpers, the hooks themselves) — allow. Rules,
|
||||
# settings, agents, skills stay blocked. --no-renames lists a rename's source
|
||||
# too, so a git mv out of a blocked path cannot hide.
|
||||
if [ -z "$(git diff --cached --name-only --no-renames | grep -vE '^(\.claude/(memory|tasks|audits|deploy)|\.githooks)/' | head -1)" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "gitflow pre-commit: BLOCKED — direct commit on '$br'." >&2
|
||||
echo " Branch from the right base (feature/bugfix->develop, hotfix->main), or merge." >&2
|
||||
echo " (.claude/** and .githooks/** commits are exempt; foreign clone? git config gitflow.protect false)" >&2
|
||||
echo " (.claude/{memory,tasks,audits,deploy}/ and .githooks/ commits are exempt; foreign clone? git config gitflow.protect false)" >&2
|
||||
exit 1
|
||||
@@ -127,7 +127,7 @@ pnpm db:reset # replay from zero
|
||||
pnpm db:test # pgTAP on the real stack
|
||||
pnpm db:types # regenerate packages/supabase/src/database.types.ts
|
||||
pnpm db:types:check # CI diff
|
||||
pnpm db:sandbox up fresh|up upgrade <version> [<then>]|test-db|types [--check]|test|e2e-shell|down # throwaway stack (SUPABASE.md §5.1): migrations tested without touching DEV
|
||||
pnpm db:sandbox up fresh|up upgrade <version> [<then>]|test-db|types [--check]|test|e2e-shell|avatar-e2e|down # throwaway stack (SUPABASE.md §5.1): migrations tested without touching DEV
|
||||
|
||||
# Reference sheet in the app: the dev server bundles the curated draft; a build does not
|
||||
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
|
||||
@@ -135,7 +135,7 @@ pnpm preview:draft # same, then serves it
|
||||
pnpm import:equine --check | --out <dir> # since R5.6 the official seed writer: the Rust pipeline (same as `pnpm r5:import-equine`), fingerprint `sha256-rfc8785-validated-v1`; the TypeScript generator left at R5.7 (replayed from a historical revision only, RUST.md §11.23)
|
||||
pnpm r5:import-equine --check | --out <dir> # the Rust pipeline (R5.2 importer, R5.3 draft, R5.4 review files): compare the 18 generated files with the committed folders (bytes; app drawings under the declared R3 rule), or write <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
|
||||
pnpm assets:upload [--check] <seed folder> # R5.5: uploads the sheet drawings of a generated seed folder to the LOCAL stack's private bucket (Rust `upload-sheet-assets`, feature `upload`; SUPABASE_URL local with a port, SUPABASE_SERVICE_ROLE_KEY typed, never printed; no overwrite, confirm after verify; run by hand, scripts/upload-sheet-assets.sh)
|
||||
pnpm e2e:sheet-assets # scripts/sheet-assets-e2e.sh: that tool against the local stack (upload, rerun, anon and wrong key, refused destinations); run by hand
|
||||
pnpm e2e:sheet-assets # scripts/sheet-assets-e2e.sh: sandbox only, refuses before any request unless the sandbox gateway URL and keys naming the sandbox issuer are set (its runner `pnpm db:sandbox sheet-assets-e2e` arrives with V1-2); never DEV
|
||||
pnpm report:compare <pdf|dir>... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md); the core's `report-compare` binary since R4.7 (scripts/report-compare.sh, first run compiles)
|
||||
|
||||
# Rust (docs/development/RUST.md) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first
|
||||
@@ -147,7 +147,7 @@ pnpm rust:check:docker # the same rust-check.sh inside the builder image
|
||||
pnpm wasm:build:docker # the same wasm-build.sh inside the builder image
|
||||
pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, sandbox tests + seccomp derivation on the musl binary
|
||||
pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static, `run --check`)
|
||||
pnpm e2e:avatar # scripts/avatar-e2e.sh: worker container against the local stack + packages/supabase/tests/e2e (real-stack avatar flow)
|
||||
pnpm e2e:avatar # = pnpm db:sandbox avatar-e2e: the worker container and packages/supabase/tests/e2e on the throwaway stack only (the suite refuses any other target; no DEV variant since 2026-11-02)
|
||||
```
|
||||
|
||||
## Test commands
|
||||
@@ -268,7 +268,7 @@ faunosteo/
|
||||
├─ packages/supabase/ ← @faunosteo/supabase
|
||||
│ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds)
|
||||
│ ├─ src/{records,workspaces,clients,species,animals,relations,field-limits}.ts ← V1-1 record access (closed RecordFailure kinds, keyset pages), D-R7 bounds
|
||||
│ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar`), skipped without the stack env
|
||||
│ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar` = `pnpm db:sandbox avatar-e2e`), fails on any target but the sandbox gateway and database
|
||||
│ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test
|
||||
├─ supabase/
|
||||
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
|
||||
@@ -285,7 +285,7 @@ faunosteo/
|
||||
│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), curation/{text,ids,prettier_json,markdown,report_guard,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL, CHANGELOG, REVIEW-REPORT, review drawings), curation/upload.rs (R5.5, feature `upload`: the upload rules, pure) + bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`) + bin/upload_sheet_assets/ (`pnpm assets:upload`, ureq; the three tools allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, fixtures/svg/hostile); no I/O, no clock (lint-enforced)
|
||||
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle; trap exports in the proofs build only)
|
||||
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh
|
||||
├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e, the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`)
|
||||
├─ scripts/{rust-env,rust-check,wasm-build,check-all,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`)
|
||||
├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin
|
||||
├─ docker-compose.yml ← `app` service; `worker` service under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`)
|
||||
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proofs (R0 module, R2 app image: app-image.sh)
|
||||
@@ -487,7 +487,7 @@ release 0.2.0 unaffected.
|
||||
- After PDF roundtrip tests fail: check the attachment bytes (the N-1 scanner reads them in the envelope suites), then the layered reader (report first, envelope metadata, snapshot/branding/labels), then the core's inflation (`pdf/read/inflate.rs`). Goldens under `apps/app/tests/fixtures/goldens/step6` and the R4 digests under `goldens/r4` are never regenerated without a user decision.
|
||||
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
||||
- Rust: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes.
|
||||
- Storage or worker change: `pnpm e2e:avatar` (worker container against the local stack, `packages/supabase/tests/e2e`) in addition to `pnpm worker:test`; `docker compose --profile worker` serves the worker from `.env.worker` (never the app `.env`).
|
||||
- Storage or worker change: `pnpm db:sandbox avatar-e2e` (the avatar suite `packages/supabase/tests/e2e` and the real worker on the throwaway stack) in addition to `pnpm worker:test`; `pnpm e2e:avatar` is its alias (owner decision 2026-11-02: no avatar e2e against DEV, `scripts/avatar-e2e.sh` removed); `docker compose --profile worker` serves the worker from `.env.worker` (never the app `.env`).
|
||||
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
|
||||
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
|
||||
|
||||
|
||||
@@ -111,8 +111,8 @@ pinned toolchain from `rust-toolchain.toml` on first use; see
|
||||
`docs/development/RUST.md` §1 for the three `cargo install` / `rustup
|
||||
target add` lines and the Docker alternative. The files worker (profile
|
||||
photos, Step 8) runs as a container beside the local Supabase stack:
|
||||
`pnpm worker:image`, then `pnpm e2e:avatar` for the real-stack end-to-end
|
||||
run, or `docker compose --profile worker up worker` with a `.env.worker`
|
||||
`pnpm worker:image`, then `pnpm db:sandbox up fresh` and `pnpm e2e:avatar` (= `pnpm db:sandbox avatar-e2e`) for the
|
||||
real-stack end-to-end run on the throwaway stack, or `docker compose --profile worker up worker` with a `.env.worker`
|
||||
(`docs/development/STORAGE.md`).
|
||||
|
||||
Docker Compose (matches production topology):
|
||||
|
||||
@@ -35,7 +35,7 @@ never hard-coded in the sources.
|
||||
|
||||
Consumers: `scripts/supabase.sh` (every CLI call: `pnpm supabase …`,
|
||||
`pnpm db:start|stop|reset|test|types`), `scripts/dev.sh` (`pnpm dev`),
|
||||
`scripts/avatar-e2e.sh`. The address changes with `FAUNOSTEO_DEV_HOST=…`
|
||||
`scripts/db-sandbox.sh`. The address changes with `FAUNOSTEO_DEV_HOST=…`
|
||||
in front of the command, without touching a source file. Calling the CLI
|
||||
binary directly (`node_modules/.bin/supabase start`) leaves the literal
|
||||
`env(...)` text in the services: always go through `pnpm`.
|
||||
|
||||
@@ -126,8 +126,8 @@ VITE_AUTH_PROVIDERS=google pnpm dev # http://<host>:5173 from any device of th
|
||||
9. REST: anon cannot read profiles (`42501`), alice reads one row only
|
||||
(SUPABASE.md §8).
|
||||
10. Profile photo (Step 8, worker container running: `pnpm worker:image`
|
||||
then `docker compose --profile worker up worker` or the container of
|
||||
`scripts/avatar-e2e.sh`): Mon compte → Modifier la photo with a phone
|
||||
then `docker compose --profile worker up worker` or the `docker run` of
|
||||
STORAGE.md §6; `pnpm e2e:avatar` runs on the sandbox): Mon compte → Modifier la photo with a phone
|
||||
JPEG → preview → Enregistrer → "Traitement en cours…" → the photo in the
|
||||
circle, the sidebar, the drawer (mobile) and the top bar (name beside it
|
||||
on desktop, alone on mobile) linking to Mon compte; a renamed PNG is
|
||||
|
||||
@@ -327,9 +327,8 @@ docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges:true
|
||||
--network supabase_network_faunosteo \
|
||||
-e SUPABASE_URL=http://supabase_kong_faunosteo:8000 \
|
||||
-e SUPABASE_SERVICE_ROLE_KEY="$(pnpm -s supabase status -o env | sed -n 's/^SERVICE_ROLE_KEY="\(.*\)"/\1/p')" \
|
||||
faunosteo_worker:dev run
|
||||
pnpm --filter @faunosteo/supabase test:e2e # real-stack end-to-end (needs the worker above)
|
||||
pnpm e2e:avatar # scripts/avatar-e2e.sh: the three lines above in one, worker started with a 5 s sweep and no quarantine grace
|
||||
faunosteo_worker:dev run # the worker beside the local stack, for the manual photo flow (IDENTITY.md); the e2e suite refuses this stack
|
||||
pnpm e2e:avatar # = pnpm db:sandbox avatar-e2e: the suite and the worker (5 s sweep, no quarantine grace) on the throwaway stack only (SUPABASE.md §5.1); the DEV script was removed on 2026-11-02
|
||||
```
|
||||
|
||||
`docker compose --profile worker up worker` runs the same container from
|
||||
|
||||
@@ -156,8 +156,12 @@ destination, content, handshake, state, access), 2 an argument that is not
|
||||
UTF-8, 3 network. The DEV address counts only if it is an address of this
|
||||
machine. The key is
|
||||
never printed and goes through no proxy. `pnpm e2e:sheet-assets` runs the
|
||||
whole behaviour against the local stack (upload, rerun, anon and wrong key,
|
||||
refused destinations, unreachable port). The TypeScript tool
|
||||
whole behaviour (upload, rerun, anon and wrong key, refused destinations,
|
||||
unreachable port) on the throwaway sandbox only: since 2026-11-02 it refuses,
|
||||
before building or any request, every target but the sandbox gateway
|
||||
`http://127.0.0.1:57800` with keys naming the sandbox issuer (its runner
|
||||
`pnpm db:sandbox sheet-assets-e2e` arrives with V1-2); it never reads the DEV
|
||||
keys and never targets DEV. The TypeScript tool
|
||||
(`packages/supabase/scripts/upload-sheet-assets.ts`) was deleted at R5.7 (RUST.md §11.23).
|
||||
|
||||
### 3.2 Files worker (Storage, Step 8)
|
||||
@@ -167,7 +171,7 @@ User files land in private buckets and are processed by the Rust worker
|
||||
|
||||
```bash
|
||||
pnpm worker:image # faunosteo_worker:dev
|
||||
pnpm e2e:avatar # starts the container on supabase_network_faunosteo, runs tests/e2e, stops it
|
||||
pnpm e2e:avatar # = pnpm db:sandbox avatar-e2e: the suite and the worker on the throwaway stack (§5.1) only
|
||||
docker compose --profile worker up worker # the same container from docker-compose.yml, reading .env.worker
|
||||
```
|
||||
|
||||
@@ -514,8 +518,9 @@ the scripts:
|
||||
on the sandbox, clean and with those conditions reproduced (scenarios and
|
||||
mutations in the journal of 2026-10-27). DEV is not validated by `db:test`
|
||||
until a run there passes.
|
||||
- `pnpm e2e:avatar`: not part of this procedure; optional, the owner's call.
|
||||
It writes on DEV beyond its own fixture: it creates a temporary confirmed
|
||||
- `pnpm e2e:avatar`: not part of this procedure. Since 2026-11-02 it runs on
|
||||
the sandbox only (owner decision; the DEV script `scripts/avatar-e2e.sh` is
|
||||
removed). Its DEV run, as recorded on 2026-10-26, wrote on DEV beyond its own fixture: it creates a temporary confirmed
|
||||
account `e2e-avatar-<time>@faunosteo.local` (and, after M1, its workspace),
|
||||
deletes it at the end (a failed run leaves it), signs in as
|
||||
`bob@faunosteo.local` (sessions and `last_sign_in_at` of an existing
|
||||
@@ -800,6 +805,7 @@ Docker.
|
||||
| `pnpm db:sandbox types [--check]` | `supabase gen types --db-url ... --schema public` through Prettier, written or diffed with the committed file |
|
||||
| `pnpm db:sandbox test` | `packages/supabase/tests/sandbox/*.sandbox.ts`: real GoTrue and PostgREST sessions, concurrent SQL sessions |
|
||||
| `pnpm db:sandbox e2e-shell` (= `pnpm e2e:shell`) | the authenticated `/app` shell in Chromium (`apps/app/e2e/shell`, `docs/development/BROWSER_TESTS.md`): a loopback dev server whose Supabase calls are replayed on the sandbox, fictitious accounts per test |
|
||||
| `pnpm db:sandbox avatar-e2e` (= `pnpm e2e:avatar`) | the avatar flow on the sandbox alone: an nginx gateway (`nginx:1.31-alpine`; `/auth/v1/`, `/rest/v1/`, `/storage/v1/` to the sandbox containers, `return 404` elsewhere) published on `127.0.0.1:57800` only; the real worker `faunosteo_worker:dev run` (avatars and sweep, 5 s sweep, no quarantine grace, 512 MiB, read-only, no capability, `nonroot`) on the sandbox network, its service key in a 600 env file removed once started; then `packages/supabase/tests/e2e/avatar-flow.e2e.ts` through that port. The suite accepts only `http://127.0.0.1:57800`, the container `faunosteo_dbsandbox_db` and keys whose JWT payload carries `iss: db-sandbox`, else it throws before any request. The issuer check only routes the run to the sandbox: it is not a signature check and not an authentication. The isolation rests on the fixed gateway URL in the worker's env file, the worker's `max_redirects(0)` and `proxy(None)` (`crates/worker/src/http.rs`), sandbox-signed keys and upstreams reached by container name on the sandbox network. The suite's supabase-js clients refuse every HTTP redirect (`global.fetch` = `tests/e2e/noRedirectFetch.ts`, `redirect: 'error'`; regression test `tests/no-redirect-fetch.test.ts`) |
|
||||
| `pnpm db:sandbox sql` / `down` | psql as postgres on stdin / remove the stack |
|
||||
|
||||
Every CLI call passes `--db-url` with `sslmode=disable` (the sandbox has no
|
||||
|
||||
@@ -67,7 +67,7 @@ unit suites, 2 by the browser journeys.
|
||||
| CSP on the image (R2) | the real app image behind the DEPLOY.md CSP in headless Chromium: with `'wasm-unsafe-eval'` the core runs the editor path, without it the degraded state and an untouched draft; no module request on `/login`, `/app/account`, `/` | `docker/csp-proof/app-image.sh` | before a merge touching the core loading or the image; manual (needs Chromium) |
|
||||
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests/sandbox.rs`, Dockerfile stage `test` (`pnpm worker:test`, Docker only, never native) | every `crates/worker` commit, `pnpm check:all`; CI `docker` job prepared |
|
||||
| Worker job loop | native unit tests on a fake backend and a fake decoder: call order claim → download → decode → upload → commit → purge, every child outcome mapped to a closed code, no deletion on a refused commit, lease left on transport failures, sweeper targets and acks, key validation, config and secret redaction | `crates/worker/tests/job_loop.rs`, `crates/worker/src/*` unit tests (`pnpm rust:check`) | every Rust commit |
|
||||
| Files e2e (real stack) | the worker container against the local Supabase stack: clean upload and owner-only download (Bob, anon, quarantine, direct final-key write refused), replacement and purge after the grace (queue clock shifted through psql), late signed-upload bytes swept, hostile uploads rejected with closed codes, removal and drained queue | `packages/supabase/tests/e2e/avatar-flow.e2e.ts` (`pnpm e2e:avatar`, `scripts/avatar-e2e.sh`) | every Storage, worker or avatar change; not in `check:all` (needs the stack) |
|
||||
| Files e2e (real stack) | the worker container against the throwaway sandbox stack (since 2026-11-02; DEV before): clean upload and owner-only download (Bob, anon, quarantine, direct final-key write refused), replacement and purge after the grace (queue clock shifted through psql), late signed-upload bytes swept, hostile uploads rejected with closed codes, removal and drained queue | `packages/supabase/tests/e2e/avatar-flow.e2e.ts` (`pnpm e2e:avatar` = `pnpm db:sandbox avatar-e2e`, `scripts/db-sandbox.sh`) | every Storage, worker or avatar change; not in `check:all` (needs the sandbox) |
|
||||
|
||||
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
|
||||
happy-dom where sufficient and under Playwright when real rendering matters
|
||||
|
||||
@@ -101,7 +101,7 @@ works as `corepack pnpm <cmd>`.
|
||||
| `pnpm build` | typecheck + Vite build in every package |
|
||||
| `pnpm check` | typecheck, test:run, lint, build in sequence (the Node gate) |
|
||||
| `pnpm check:all` | the whole pre-merge gate: native Rust check, types drift, wasm build, `pnpm check`, application and worker images (`docs/development/RUST.md` §4; no CI runs it yet) |
|
||||
| `pnpm e2e:avatar` | real-stack end-to-end of the avatar flow: worker container against the local Supabase stack + `packages/supabase/tests/e2e` (`docs/development/STORAGE.md` §6; needs `pnpm db:start`) |
|
||||
| `pnpm e2e:avatar` | = `pnpm db:sandbox avatar-e2e`: real-stack end-to-end of the avatar flow, worker container + `packages/supabase/tests/e2e` on the throwaway stack only (`docs/development/STORAGE.md` §6; needs `pnpm db:sandbox up fresh` and `pnpm worker:image`) |
|
||||
| `pnpm format` | Prettier on the whole repository |
|
||||
|
||||
Package-scoped: `pnpm --filter @faunosteo/app <script>`.
|
||||
|
||||
+1
-1
@@ -46,7 +46,7 @@
|
||||
"wasm:build:docker": "bash docker/rust-run.sh bash scripts/wasm-build.sh",
|
||||
"worker:test": "docker build -f crates/worker/Dockerfile --target test -t faunosteo_worker:test .",
|
||||
"worker:image": "docker build -f crates/worker/Dockerfile -t faunosteo_worker:dev .",
|
||||
"e2e:avatar": "bash scripts/avatar-e2e.sh",
|
||||
"e2e:avatar": "bash scripts/db-sandbox.sh avatar-e2e",
|
||||
"e2e:ui": "pnpm --filter @faunosteo/app e2e:ui",
|
||||
"e2e:shell": "bash scripts/db-sandbox.sh e2e-shell"
|
||||
},
|
||||
|
||||
@@ -1,17 +1,21 @@
|
||||
/**
|
||||
* Avatar flow against the real local stack and the worker container
|
||||
* Avatar flow against a real stack and the worker container
|
||||
* (docs/development/STORAGE.md §4, §3; STEP8_FILES_ANALYSIS IV.2 "integration"
|
||||
* and "real-stack e2e"). Run through `pnpm e2e:avatar` (scripts/avatar-e2e.sh),
|
||||
* which starts the worker with a 5 s sweep and a 0 s quarantine grace.
|
||||
* and "real-stack e2e"). Run through `pnpm e2e:avatar` (= `pnpm db:sandbox
|
||||
* avatar-e2e`): the throwaway stack only, the worker started with a 5 s sweep and
|
||||
* a 0 s quarantine grace.
|
||||
*
|
||||
* Environment: SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
|
||||
* (the service key is used for inspection only: listing objects and shifting
|
||||
* the purge clock through psql in the database container).
|
||||
* the purge clock through psql) and AVATAR_E2E_DB_CONTAINER. The URL and the
|
||||
* container must be the sandbox's own: any other value, or a missing one, fails
|
||||
* the run before any request. Both accounts are made per run.
|
||||
*/
|
||||
import { createHash } from 'node:crypto'
|
||||
import { createHash, randomBytes } from 'node:crypto'
|
||||
import { execFileSync } from 'node:child_process'
|
||||
import { deflateSync } from 'node:zlib'
|
||||
import { createClient, type SupabaseClient } from '@supabase/supabase-js'
|
||||
import { noRedirectFetch } from './noRedirectFetch'
|
||||
import {
|
||||
beginAvatarUpload,
|
||||
confirmAssetUpload,
|
||||
@@ -26,16 +30,30 @@ import {
|
||||
const URL_ = process.env.SUPABASE_URL
|
||||
const ANON = process.env.SUPABASE_ANON_KEY
|
||||
const SERVICE = process.env.SUPABASE_SERVICE_ROLE_KEY
|
||||
const DB_CONTAINER = process.env.AVATAR_E2E_DB_CONTAINER ?? 'supabase_db_faunosteo'
|
||||
const PASSWORD = 'LocalDev-only-password-1'
|
||||
const BOB = 'bob@faunosteo.local'
|
||||
const DB_CONTAINER = process.env.AVATAR_E2E_DB_CONTAINER
|
||||
/** The only target accepted: the gateway and database of `pnpm db:sandbox avatar-e2e`. */
|
||||
const SANDBOX_URL = 'http://127.0.0.1:57800'
|
||||
const SANDBOX_DB = 'faunosteo_dbsandbox_db'
|
||||
/** The sandbox signs its keys with issuer `db-sandbox` (scripts/db-sandbox.sh); no other stack's key does. */
|
||||
const sandboxKey = (key: string | undefined): boolean => {
|
||||
try {
|
||||
return JSON.parse(Buffer.from(key?.split('.')[1] ?? '', 'base64url').toString()).iss === 'db-sandbox'
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
if (URL_ !== SANDBOX_URL || DB_CONTAINER !== SANDBOX_DB || !sandboxKey(ANON) || !sandboxKey(SERVICE))
|
||||
throw new Error('avatar e2e: run it through pnpm e2e:avatar, on the sandbox stack only')
|
||||
/** Per run, kept in memory only: both accounts are deleted after the suite. */
|
||||
const PASSWORD = randomBytes(18).toString('base64url')
|
||||
const WORKER_WAIT_MS = 60_000
|
||||
|
||||
type Client = SupabaseClient<Database>
|
||||
|
||||
function anonClient(): Client {
|
||||
return createClient<Database>(URL_ ?? '', ANON ?? '', {
|
||||
return createClient<Database>(SANDBOX_URL, ANON ?? '', {
|
||||
auth: { persistSession: false, autoRefreshToken: false },
|
||||
global: { fetch: noRedirectFetch },
|
||||
})
|
||||
}
|
||||
|
||||
@@ -47,8 +65,9 @@ async function signedIn(email: string): Promise<Client> {
|
||||
}
|
||||
|
||||
function serviceClient(): Client {
|
||||
return createClient<Database>(URL_ ?? '', SERVICE ?? '', {
|
||||
return createClient<Database>(SANDBOX_URL, SERVICE ?? '', {
|
||||
auth: { persistSession: false, autoRefreshToken: false },
|
||||
global: { fetch: noRedirectFetch },
|
||||
})
|
||||
}
|
||||
|
||||
@@ -166,19 +185,24 @@ async function objectExists(service: Client, bucket: string, key: string): Promi
|
||||
|
||||
function psql(sql: string): string {
|
||||
return execFileSync('docker', [
|
||||
'exec', DB_CONTAINER, 'psql', '-U', 'postgres', '-d', 'postgres', '-Atc', sql,
|
||||
'exec', SANDBOX_DB, 'psql', '-U', 'postgres', '-d', 'postgres', '-Atc', sql,
|
||||
]).toString().trim()
|
||||
}
|
||||
|
||||
/** Moves every due date of the purge queue to now (the grace is 48 h / 1 h in production). */
|
||||
function expeditePurges(): void {
|
||||
psql('update private.object_purge_queue set not_before = now() where not_before > now()')
|
||||
function accountPattern(userId: string): string {
|
||||
if (!/^[0-9a-f-]{36}$/.test(userId)) throw new Error('userId is not a uuid')
|
||||
return `'%/${userId}/%'`
|
||||
}
|
||||
|
||||
/** Moves an account's due dates of the purge queue to now (the grace is 48 h / 1 h in production). */
|
||||
function expeditePurges(userId: string): void {
|
||||
psql(`update private.object_purge_queue set not_before = now()
|
||||
where not_before > now() and object_name like ${accountPattern(userId)}`)
|
||||
}
|
||||
|
||||
/** Purge entries still queued for an account (served entries are acked, hence deleted). */
|
||||
function queuedPurges(userId: string): number {
|
||||
if (!/^[0-9a-f-]{36}$/.test(userId)) throw new Error('userId is not a uuid')
|
||||
return Number(psql(`select count(*) from private.object_purge_queue where object_name like '%/${userId}/%'`))
|
||||
return Number(psql(`select count(*) from private.object_purge_queue where object_name like ${accountPattern(userId)}`))
|
||||
}
|
||||
|
||||
async function downloadFails(client: Client, key: string): Promise<boolean> {
|
||||
@@ -192,31 +216,39 @@ function sha256(bytes: Uint8Array): string {
|
||||
|
||||
// --- suite ------------------------------------------------------------------
|
||||
|
||||
const configured = Boolean(URL_ && ANON && SERVICE)
|
||||
/** A confirmed throwaway account; resolves with its id. */
|
||||
async function newAccount(service: Client, tag: string, name: string): Promise<{ id: string; email: string }> {
|
||||
const email = `e2e-${tag}-${Date.now()}@faunosteo.local`
|
||||
const created = await service.auth.admin.createUser({
|
||||
email,
|
||||
password: PASSWORD,
|
||||
email_confirm: true,
|
||||
user_metadata: { display_name: name, locale: 'fr' },
|
||||
})
|
||||
if (created.error || !created.data.user) throw new Error(`createUser: ${created.error?.message}`)
|
||||
return { id: created.data.user.id, email }
|
||||
}
|
||||
|
||||
describe.skipIf(!configured)('avatar flow on the real stack', () => {
|
||||
describe('avatar flow on the sandbox stack', () => {
|
||||
const service = serviceClient()
|
||||
let alice: Client
|
||||
let aliceId: string
|
||||
let bob: Client
|
||||
let bobId: string
|
||||
|
||||
beforeAll(async () => {
|
||||
// A fresh account per run keeps the seeded accounts clean and the per-hour rate out of reach.
|
||||
const email = `e2e-avatar-${Date.now()}@faunosteo.local`
|
||||
const created = await service.auth.admin.createUser({
|
||||
email,
|
||||
password: PASSWORD,
|
||||
email_confirm: true,
|
||||
user_metadata: { display_name: 'E2E Avatar', locale: 'fr' },
|
||||
})
|
||||
if (created.error || !created.data.user) throw new Error(`createUser: ${created.error?.message}`)
|
||||
aliceId = created.data.user.id
|
||||
alice = await signedIn(email)
|
||||
bob = await signedIn(BOB)
|
||||
// Fresh accounts per run keep the seeded accounts out of the suite and the per-hour rate out of reach.
|
||||
const a = await newAccount(service, 'avatar', 'E2E Avatar')
|
||||
aliceId = a.id
|
||||
alice = await signedIn(a.email)
|
||||
const b = await newAccount(service, 'other', 'E2E Other')
|
||||
bobId = b.id
|
||||
bob = await signedIn(b.email)
|
||||
})
|
||||
|
||||
afterAll(async () => {
|
||||
if (aliceId) await service.auth.admin.deleteUser(aliceId)
|
||||
if (bobId) await service.auth.admin.deleteUser(bobId)
|
||||
})
|
||||
|
||||
it('cleans a valid upload, and only the owner can download the result', async () => {
|
||||
@@ -260,7 +292,7 @@ describe.skipIf(!configured)('avatar flow on the real stack', () => {
|
||||
expect(state.clean?.id).toBe(row.id)
|
||||
expect(await downloadFails(alice, previous!.object_key)).toBe(true)
|
||||
expect(await objectExists(service, 'avatars', previous!.object_key)).toBe(true)
|
||||
expeditePurges()
|
||||
expeditePurges(aliceId)
|
||||
await waitFor(
|
||||
async () => ((await objectExists(service, 'avatars', previous!.object_key)) ? null : true),
|
||||
30_000,
|
||||
@@ -316,7 +348,7 @@ describe.skipIf(!configured)('avatar flow on the real stack', () => {
|
||||
expect(await downloadFails(alice, row.object_key)).toBe(true)
|
||||
const state = await fetchOwnAvatarState(alice, aliceId)
|
||||
expect(state.clean).toBeNull()
|
||||
expeditePurges()
|
||||
expeditePurges(aliceId)
|
||||
await waitFor(
|
||||
async () => {
|
||||
const listed = await service.storage.from('avatars').list(`profiles/${aliceId}`, { limit: 100 })
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
/**
|
||||
* The suite's fetch: a 3xx answer is an error, never a request to another
|
||||
* origin (owner decision 2026-11-02). supabase-js hands `global.fetch` to its
|
||||
* auth, REST and Storage calls and spreads the caller's init before ours runs,
|
||||
* so `redirect` set here is final: nothing restores `follow`.
|
||||
*/
|
||||
export const noRedirectFetch: typeof fetch = (input, init) =>
|
||||
fetch(input, { ...init, redirect: 'error' })
|
||||
@@ -0,0 +1,95 @@
|
||||
import { createServer, type IncomingMessage, type Server } from 'node:http'
|
||||
import type { AddressInfo } from 'node:net'
|
||||
import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'
|
||||
import { createClient } from '@supabase/supabase-js'
|
||||
import type { Database } from '../src'
|
||||
import { noRedirectFetch } from './e2e/noRedirectFetch'
|
||||
|
||||
type Seen = { url?: string; apikey?: string | string[] }
|
||||
|
||||
const targetSeen: Seen[] = []
|
||||
const originSeen: Seen[] = []
|
||||
let target: Server
|
||||
let origin: Server
|
||||
let originUrl = ''
|
||||
|
||||
function listen(
|
||||
seen: Seen[],
|
||||
answer: (res: import('node:http').ServerResponse) => void,
|
||||
): Promise<Server> {
|
||||
const server = createServer((req: IncomingMessage, res) => {
|
||||
seen.push({ url: req.url, apikey: req.headers.apikey })
|
||||
answer(res)
|
||||
})
|
||||
return new Promise((resolve) => {
|
||||
server.listen(0, '127.0.0.1', () => resolve(server))
|
||||
})
|
||||
}
|
||||
|
||||
const portOf = (server: Server) => (server.address() as AddressInfo).port
|
||||
|
||||
function client() {
|
||||
return createClient<Database>(originUrl, 'test-key', {
|
||||
auth: { persistSession: false, autoRefreshToken: false },
|
||||
global: { fetch: noRedirectFetch },
|
||||
})
|
||||
}
|
||||
|
||||
function expectNotFollowed() {
|
||||
expect(targetSeen).toHaveLength(0)
|
||||
// supabase-js may retry a failed GET: count the origin hits, not their number
|
||||
expect(originSeen.length).toBeGreaterThan(0)
|
||||
expect(originSeen.every((r) => r.apikey === 'test-key')).toBe(true)
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
target = await listen(targetSeen, (res) => {
|
||||
res.writeHead(200, { 'content-type': 'application/json' }).end('{}')
|
||||
})
|
||||
origin = await listen(originSeen, (res) => {
|
||||
const landing = `http://127.0.0.1:${portOf(target)}/landed`
|
||||
res.writeHead(302, { location: landing }).end()
|
||||
})
|
||||
originUrl = `http://127.0.0.1:${portOf(origin)}`
|
||||
})
|
||||
|
||||
afterAll(async () => {
|
||||
await Promise.all(
|
||||
[target, origin].map((s) => new Promise((done) => s.close(done))),
|
||||
)
|
||||
})
|
||||
|
||||
beforeEach(() => {
|
||||
targetSeen.length = 0
|
||||
originSeen.length = 0
|
||||
})
|
||||
|
||||
describe('noRedirectFetch', () => {
|
||||
it('does not follow a redirect on a REST call', async () => {
|
||||
const { error } = await client().from('assets').select('id')
|
||||
expect(error).not.toBeNull()
|
||||
expectNotFollowed()
|
||||
})
|
||||
|
||||
it('does not follow a redirect on an auth call', async () => {
|
||||
const { error } = await client().auth.signInWithPassword({
|
||||
email: 'a@b.c',
|
||||
password: 'x',
|
||||
})
|
||||
expect(error).not.toBeNull()
|
||||
expectNotFollowed()
|
||||
})
|
||||
|
||||
it('does not follow a redirect on a storage call', async () => {
|
||||
const { error } = await client().storage.from('avatars').download('k')
|
||||
expect(error).not.toBeNull()
|
||||
expectNotFollowed()
|
||||
})
|
||||
|
||||
it('control: the default fetch follows the same redirect', async () => {
|
||||
const res = await fetch(`${originUrl}/control`)
|
||||
expect(res.status).toBe(200)
|
||||
expect(targetSeen).toHaveLength(1)
|
||||
expect(targetSeen[0].url).toBe('/landed')
|
||||
})
|
||||
})
|
||||
@@ -1,8 +1,8 @@
|
||||
import { defineConfig } from 'vitest/config'
|
||||
|
||||
/**
|
||||
* Real-stack end-to-end suite (tests/e2e/*.e2e.ts): needs the local Supabase
|
||||
* stack and the worker container (scripts/avatar-e2e.sh starts both sides).
|
||||
* Real-stack end-to-end suite (tests/e2e/*.e2e.ts): the throwaway stack and the
|
||||
* worker container, both started by `pnpm e2e:avatar` (scripts/db-sandbox.sh).
|
||||
* Kept out of the default `test:run` include on purpose.
|
||||
*/
|
||||
export default defineConfig({
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Real-stack end-to-end run of the avatar flow (docs/development/STORAGE.md §6):
|
||||
# starts the worker container against the local Supabase stack with a fast sweep
|
||||
# and no quarantine grace, runs packages/supabase/tests/e2e, stops the container.
|
||||
# Needs: `pnpm db:start` done, Docker, the worker image (`pnpm worker:image`,
|
||||
# built here when absent). The keys come from `supabase status`; the service key
|
||||
# reaches the container through a 600-mode temporary env file, never the command line.
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
network="${SUPABASE_NETWORK:-supabase_network_faunosteo}"
|
||||
kong="${SUPABASE_INTERNAL_URL:-http://supabase_kong_faunosteo:8000}"
|
||||
image="${WORKER_IMAGE:-faunosteo_worker:dev}"
|
||||
name="faunosteo_worker_e2e"
|
||||
|
||||
. scripts/dev-env.sh
|
||||
status="$(node_modules/.bin/supabase status -o env 2>/dev/null)" \
|
||||
|| { echo "avatar-e2e: the local stack is not running (pnpm db:start)" >&2; exit 1; }
|
||||
value() { printf '%s\n' "$status" | sed -n "s/^$1=\"\(.*\)\"$/\1/p"; }
|
||||
api_url="$(value API_URL)"
|
||||
anon_key="$(value ANON_KEY)"
|
||||
service_key="$(value SERVICE_ROLE_KEY)"
|
||||
[ -n "$api_url" ] && [ -n "$anon_key" ] && [ -n "$service_key" ] \
|
||||
|| { echo "avatar-e2e: could not read the keys from supabase status" >&2; exit 1; }
|
||||
|
||||
if ! docker image inspect "$image" >/dev/null 2>&1; then
|
||||
echo "== building $image"
|
||||
docker build -f crates/worker/Dockerfile -t "$image" .
|
||||
fi
|
||||
|
||||
env_file="$(mktemp)"
|
||||
chmod 600 "$env_file"
|
||||
cleanup() {
|
||||
echo "== worker log (last lines)"
|
||||
docker logs --tail 40 "$name" 2>/dev/null || true
|
||||
docker rm -f "$name" >/dev/null 2>&1 || true
|
||||
rm -f "$env_file"
|
||||
}
|
||||
trap cleanup EXIT
|
||||
{
|
||||
echo "SUPABASE_URL=$kong"
|
||||
echo "SUPABASE_SERVICE_ROLE_KEY=$service_key"
|
||||
echo "WORKER_ID=e2e"
|
||||
echo "WORKER_POLL_SECONDS=1"
|
||||
echo "WORKER_SWEEP_SECONDS=5"
|
||||
echo "WORKER_QUARANTINE_GRACE_SECONDS=0"
|
||||
} > "$env_file"
|
||||
|
||||
docker rm -f "$name" >/dev/null 2>&1 || true
|
||||
echo "== starting $name on $network"
|
||||
docker run -d --name "$name" --read-only --cap-drop ALL \
|
||||
--security-opt no-new-privileges:true --memory 512m --cpus 1 --pids-limit 64 \
|
||||
--network "$network" --env-file "$env_file" "$image" run >/dev/null
|
||||
|
||||
echo "== e2e suite"
|
||||
SUPABASE_URL="$api_url" SUPABASE_ANON_KEY="$anon_key" SUPABASE_SERVICE_ROLE_KEY="$service_key" \
|
||||
pnpm --filter @faunosteo/supabase test:e2e
|
||||
+97
-4
@@ -14,6 +14,9 @@
|
||||
# pnpm db:sandbox types [--check] generated types (write, or diff with the committed file)
|
||||
# pnpm db:sandbox test packages/supabase/tests/sandbox (HTTP, concurrency)
|
||||
# pnpm db:sandbox e2e-shell [args] = pnpm e2e:shell: the /app shell in Chromium (apps/app/e2e); args go to Playwright (a spec file, --grep)
|
||||
# pnpm db:sandbox avatar-e2e [args] (= pnpm e2e:avatar) the avatar worker (default mode: avatars + sweep) against the
|
||||
# sandbox: a gateway on 127.0.0.1:$PORT_GATEWAY, the worker
|
||||
# container, then tests/e2e/avatar-flow.e2e.ts (args go to vitest)
|
||||
# pnpm db:sandbox sql psql as postgres on stdin
|
||||
# pnpm db:sandbox down
|
||||
#
|
||||
@@ -36,14 +39,21 @@ AUTH=faunosteo_dbsandbox_auth
|
||||
REST=faunosteo_dbsandbox_rest
|
||||
STORAGE=faunosteo_dbsandbox_storage
|
||||
MAIL=faunosteo_dbsandbox_mail
|
||||
PORT_DB=57432 PORT_AUTH=57999 PORT_REST=57300 PORT_STORAGE=57500 PORT_MAIL=57025
|
||||
GATEWAY=faunosteo_dbsandbox_gateway
|
||||
WORKER=faunosteo_dbsandbox_worker_verify
|
||||
AVATAR_WORKER=faunosteo_dbsandbox_worker_avatar
|
||||
GATEWAY_IMAGE=nginx:1.31-alpine
|
||||
WORKER_IMAGE=faunosteo_worker:dev
|
||||
PORT_DB=57432 PORT_AUTH=57999 PORT_REST=57300 PORT_STORAGE=57500 PORT_MAIL=57025 PORT_GATEWAY=57800
|
||||
STATE="${FAUNOSTEO_SANDBOX_DIR:-$HOME/.cache/faunosteo-db-sandbox}"
|
||||
SECRETS="$STATE/secrets.sh"
|
||||
CLI=node_modules/.bin/supabase
|
||||
|
||||
die() { echo "db-sandbox: $*" >&2; exit 1; }
|
||||
# Both sides resolved: a repository reached through a symlink is still the repository.
|
||||
REPO="$(realpath "$PWD")"
|
||||
case "$(realpath -m "$STATE")" in
|
||||
"$PWD" | "$PWD"/*) die "FAUNOSTEO_SANDBOX_DIR must be outside the repository" ;;
|
||||
"$REPO" | "$REPO"/*) die "FAUNOSTEO_SANDBOX_DIR must be outside the repository" ;;
|
||||
esac
|
||||
# Every value must be present: an empty password would turn --db-url into an
|
||||
# argument the CLI might read as absent and fall back to the DEV database.
|
||||
@@ -219,7 +229,7 @@ cmd_up() {
|
||||
}
|
||||
|
||||
cmd_down() {
|
||||
docker rm -f "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB" >/dev/null 2>&1 || true
|
||||
docker rm -f "$AVATAR_WORKER" "$WORKER" "$GATEWAY" "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB" >/dev/null 2>&1 || true
|
||||
docker network rm "$NET" >/dev/null 2>&1 || true
|
||||
rm -f "$SECRETS" "$STATE/db.env" "$STATE/auth.env" "$STATE/storage.env" "$STATE/rest.env" "$STATE/service-header"
|
||||
echo "== sandbox removed"
|
||||
@@ -234,6 +244,88 @@ with_sandbox_env() (
|
||||
"$@"
|
||||
)
|
||||
|
||||
# The Kong routes of the CLI stack (/auth/v1/, /rest/v1/, /storage/v1/) on the
|
||||
# sandbox network; host port only for avatar-e2e, on 127.0.0.1 like the services.
|
||||
GATEWAY_CONF='server {
|
||||
listen 8000;
|
||||
client_max_body_size 8m;
|
||||
proxy_http_version 1.1;
|
||||
location /auth/v1/ { proxy_pass http://'"$AUTH"':9999/; }
|
||||
location /rest/v1/ { proxy_pass http://'"$REST"':3000/; }
|
||||
location /storage/v1/ { proxy_pass http://'"$STORAGE"':5000/; }
|
||||
location / { return 404; }
|
||||
}'
|
||||
|
||||
start_gateway() { # [docker run options]
|
||||
docker run -d --name "$GATEWAY" --network "$NET" --security-opt no-new-privileges:true "$@" \
|
||||
--entrypoint sh "$GATEWAY_IMAGE" -c 'printf "%s\n" "$0" > /etc/nginx/conf.d/default.conf && exec nginx -g "daemon off;"' \
|
||||
"$GATEWAY_CONF" >/dev/null
|
||||
wait_for "gateway" docker exec "$GATEWAY" wget -q -O /dev/null http://127.0.0.1:8000/rest/v1/
|
||||
}
|
||||
|
||||
# The service key reaches the container through a 600 file removed once it started;
|
||||
# memory as the compose service of the same mode (docker-compose.yml).
|
||||
start_worker() { # name worker-id memory extra-env-lines args...
|
||||
local name="$1" id="$2" memory="$3" extra="$4"; shift 4
|
||||
worker_env="$(umask 077; mktemp "$STATE/worker.XXXXXX")"
|
||||
printf 'SUPABASE_URL=http://%s:8000\nSUPABASE_SERVICE_ROLE_KEY=%s\nWORKER_ID=%s\nWORKER_POLL_SECONDS=1\n%s' \
|
||||
"$GATEWAY" "$SB_SERVICE_KEY" "$id" "$extra" > "$worker_env"
|
||||
docker run -d --name "$name" --network "$NET" --env-file "$worker_env" \
|
||||
--read-only --cap-drop ALL --security-opt no-new-privileges:true \
|
||||
--memory "$memory" --cpus 1 --pids-limit 64 --user nonroot \
|
||||
"$WORKER_IMAGE" "$@" >/dev/null
|
||||
rm -f "$worker_env"; worker_env=
|
||||
for _ in $(seq 1 30); do
|
||||
docker logs "$name" 2>&1 | grep -q '"event":"worker_start"' && break
|
||||
[ "$(docker inspect -f '{{.State.Running}}' "$name")" = true ] || die "worker exited before worker_start"
|
||||
sleep 1
|
||||
done
|
||||
docker logs "$name" 2>&1 | grep -q '"event":"worker_start"' || die "timeout waiting for worker_start"
|
||||
echo "== worker up ($WORKER_IMAGE, $*, via $GATEWAY)"
|
||||
}
|
||||
|
||||
# The worker's JSON lines hold no secret by design (crates/worker log allowlist);
|
||||
# they are printed only after checking that neither key appears in them.
|
||||
print_worker_log() { # name
|
||||
local lines
|
||||
lines="$(docker logs "$1" 2>&1)" || return 0
|
||||
case "$lines" in
|
||||
*"$SB_SERVICE_KEY"* | *"$SB_ANON_KEY"*) echo "== worker log withheld: it contains a key" ;;
|
||||
*) echo "== worker log"; printf '%s\n' "$lines" ;;
|
||||
esac
|
||||
}
|
||||
|
||||
worker_cleanup() { # name
|
||||
[ -n "${worker_env:-}" ] && rm -f "$worker_env"
|
||||
print_worker_log "$1"
|
||||
docker rm -f "$1" "$GATEWAY" >/dev/null 2>&1 || true
|
||||
}
|
||||
|
||||
worker_preflight() { # name
|
||||
load_secrets
|
||||
docker image inspect "$WORKER_IMAGE" >/dev/null 2>&1 || die "$WORKER_IMAGE missing (pnpm worker:image)"
|
||||
docker rm -f "$1" "$GATEWAY" >/dev/null 2>&1 || true
|
||||
}
|
||||
|
||||
# The avatar suite drives supabase-js through the gateway's loopback port; its
|
||||
# psql calls name the sandbox database container. The suite accepts no other
|
||||
# target, and a port already taken stops the run before anything starts.
|
||||
cmd_avatar_e2e() {
|
||||
worker_preflight "$AVATAR_WORKER"
|
||||
if (exec 3<>"/dev/tcp/127.0.0.1/$PORT_GATEWAY") 2>/dev/null; then
|
||||
die "port 127.0.0.1:$PORT_GATEWAY is already in use: free it, nothing was started"
|
||||
fi
|
||||
trap 'worker_cleanup "$AVATAR_WORKER"' EXIT
|
||||
start_gateway -p 127.0.0.1:$PORT_GATEWAY:8000
|
||||
[ "$(docker port "$GATEWAY" 8000/tcp)" = "127.0.0.1:$PORT_GATEWAY" ] \
|
||||
|| die "the gateway is not published on 127.0.0.1:$PORT_GATEWAY only"
|
||||
start_worker "$AVATAR_WORKER" sandbox-avatar 512m \
|
||||
$'WORKER_SWEEP_SECONDS=5\nWORKER_QUARANTINE_GRACE_SECONDS=0\n' run
|
||||
SUPABASE_URL="http://127.0.0.1:$PORT_GATEWAY" SUPABASE_ANON_KEY="$SB_ANON_KEY" \
|
||||
SUPABASE_SERVICE_ROLE_KEY="$SB_SERVICE_KEY" AVATAR_E2E_DB_CONTAINER="$DB" \
|
||||
node_modules/.bin/pnpm --filter @faunosteo/supabase test:e2e "$@"
|
||||
}
|
||||
|
||||
case "${1:-}" in
|
||||
up) shift; cmd_up "$@" ;;
|
||||
down) cmd_down ;;
|
||||
@@ -248,6 +340,7 @@ case "${1:-}" in
|
||||
fi ;;
|
||||
test) load_secrets; with_sandbox_env node_modules/.bin/pnpm --filter @faunosteo/supabase test:sandbox ;;
|
||||
e2e-shell) shift; load_secrets; with_sandbox_env node_modules/.bin/pnpm --filter @faunosteo/app e2e:shell "$@" ;;
|
||||
avatar-e2e) shift; cmd_avatar_e2e "$@" ;;
|
||||
sql) load_secrets; sb_psql ;;
|
||||
*) sed -n '2,23p' "$0"; exit 1 ;;
|
||||
*) sed -n '2,26p' "$0"; exit 1 ;;
|
||||
esac
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
#!/usr/bin/env bash
|
||||
# shellcheck shell=bash
|
||||
# The one place the DEV origin is decided (docs/development/ENVIRONMENTS.md §2).
|
||||
# Sourced by the wrappers (scripts/supabase.sh, scripts/dev.sh, scripts/avatar-e2e.sh):
|
||||
# Sourced by the wrappers (scripts/supabase.sh, scripts/dev.sh, scripts/db-sandbox.sh):
|
||||
# every service the browser of another device must reach is addressed by the
|
||||
# host's LAN address, never by 127.0.0.1 or localhost.
|
||||
#
|
||||
|
||||
+27
-12
@@ -1,8 +1,10 @@
|
||||
#!/usr/bin/env bash
|
||||
# `pnpm e2e:sheet-assets`: the sheet-asset upload tool against the LOCAL Supabase stack (R5.5,
|
||||
# docs/development/SUPABASE.md §3.1). Needs `pnpm db:start`. Run by hand: it uploads the equine
|
||||
# draft drawing to the local bucket and confirms its row (idempotent; a rerun changes nothing).
|
||||
# The keys are read from `pnpm supabase status`, held in variables, never printed.
|
||||
# `pnpm e2e:sheet-assets` (= `pnpm db:sandbox sheet-assets-e2e`): the sheet-asset upload tool against the
|
||||
# throwaway SANDBOX stack (docs/development/SUPABASE.md §3.1, §5.1), never DEV. It uploads the equine draft
|
||||
# drawing to the sandbox bucket and confirms its row (idempotent; a rerun changes nothing).
|
||||
# The runner (scripts/db-sandbox.sh) starts the gateway and passes SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
|
||||
# and SUPABASE_ANON_KEY in the environment; this script refuses anything else before building or any
|
||||
# request, and never prints a key.
|
||||
#
|
||||
# Checks: --check writes nothing; a first run uploads and confirms; a rerun has nothing to do;
|
||||
# the anon key and a wrong key are refused; a destination that is not a local stack is refused
|
||||
@@ -10,17 +12,30 @@
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
SANDBOX_URL=http://127.0.0.1:57800
|
||||
SERVICE=${SUPABASE_SERVICE_ROLE_KEY:-}
|
||||
ANON=${SUPABASE_ANON_KEY:-}
|
||||
# A key is accepted only when its JWT payload names the sandbox issuer; nothing is printed.
|
||||
sandbox_key() { printf '%s' "$1" | python3 -I -c '
|
||||
import base64, json, sys
|
||||
try:
|
||||
p = sys.stdin.read().split(".")[1]
|
||||
sys.exit(0 if json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4))).get("iss") == "db-sandbox" else 1)
|
||||
except Exception:
|
||||
sys.exit(1)'; }
|
||||
if [ "${SUPABASE_URL:-}" != "$SANDBOX_URL" ] || ! sandbox_key "$SERVICE" || ! sandbox_key "$ANON"; then
|
||||
echo "sheet-assets-e2e: refused, nothing was run. Sandbox only: the sandbox gateway URL and keys naming" >&2
|
||||
echo "the sandbox issuer, set by pnpm db:sandbox sheet-assets-e2e where that runner exists; it never targets DEV." >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
. scripts/rust-env.sh
|
||||
SEED=supabase/seed/anatomical-sheets/equine/draft
|
||||
BIN=target/release/upload-sheet-assets
|
||||
FAIL=0
|
||||
|
||||
env -u SUPABASE_SERVICE_ROLE_KEY cargo build --release --locked -q -p faunosteo-core --features upload --bin upload-sheet-assets || exit 2
|
||||
STATUS=$(bash scripts/supabase.sh status -o json 2>/dev/null) || { echo "stack not running (pnpm db:start)"; exit 2; }
|
||||
field() { printf '%s' "$STATUS" | python3 -c "import json,sys;print(json.load(sys.stdin)['$1'])"; }
|
||||
SERVICE=$(field SERVICE_ROLE_KEY)
|
||||
ANON=$(field ANON_KEY)
|
||||
LOCAL=http://127.0.0.1:54321
|
||||
env -u SUPABASE_SERVICE_ROLE_KEY -u SUPABASE_ANON_KEY cargo build --release --locked -q -p faunosteo-core --features upload --bin upload-sheet-assets || exit 2
|
||||
LOCAL=$SANDBOX_URL
|
||||
|
||||
# expect <name> <expected exit> <url> <key> <args...>; output kept to grep, keys never echoed.
|
||||
expect() {
|
||||
@@ -42,8 +57,8 @@ expect "rerun" 0 "$LOCAL" "$SERVICE" "$SEED"
|
||||
grep -q "nothing to do" <<<"$LAST" && echo "PASS rerun has nothing to do" || { echo "FAIL rerun did work"; FAIL=1; }
|
||||
expect "anon key refused" 1 "$LOCAL" "$ANON" "$SEED"
|
||||
expect "wrong key refused" 1 "$LOCAL" "not-a-valid-key" "$SEED"
|
||||
expect "https refused" 1 "https://127.0.0.1:54321" "$SERVICE" "$SEED"
|
||||
expect "non-local host refused" 1 "http://example.test:54321" "$SERVICE" "$SEED"
|
||||
expect "https refused" 1 "https://127.0.0.1:57800" "$SERVICE" "$SEED"
|
||||
expect "non-local host refused" 1 "http://example.test:57800" "$SERVICE" "$SEED"
|
||||
expect "no port refused" 1 "http://127.0.0.1" "$SERVICE" "$SEED"
|
||||
expect "unreachable port" 3 "http://127.0.0.1:9" "$SERVICE" "$SEED"
|
||||
expect "folder outside the seed" 1 "$LOCAL" "$SERVICE" --check crates/core/src
|
||||
|
||||
Reference in new issue
Block a user