From 3fbf34f66343c12b72976702929205f7c2eef9e2 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 12 Oct 2026 22:48:48 +0200 Subject: [PATCH] =?UTF-8?q?docs(docs):=20Rust=20review=20rev=202=20?= =?UTF-8?q?=E2=80=94=2061=20challenger=20findings=20folded=20(3=20crates,?= =?UTF-8?q?=20frozen=20oracles,=20consumer-driven=20deletion,=20keyless=20?= =?UTF-8?q?parent,=20CSP/digest=20deploy);=20CLAUDE.md=20Rust-by-default?= =?UTF-8?q?=20rule;=20chore(memory):=20BDR-043,=20LRN-048,=20EVAL-016,=20j?= =?UTF-8?q?ournal,=20TODO=20Rust=20roadmap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/decisions.md | 6 + .claude/memory/evals.md | 7 + .claude/memory/journal.md | 4 + .claude/memory/learnings.md | 5 + .claude/tasks/TODO.md | 10 +- CLAUDE.md | 30 + docs/development/RUST_ARCHITECTURE_REVIEW.md | 1138 +++++++++--------- 7 files changed, 661 insertions(+), 539 deletions(-) diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index da5969c1..1c045504 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -354,3 +354,9 @@ Status: active, awaiting user validation of the step. 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) + +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. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index d1e7cf7d..a7dca81f 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -122,3 +122,10 @@ Method: contract with 16 criteria (`2026-10-11-step-07-verify.md`) → fresh ver Result: verifier pass 1 ECARTS(2): (a) real gap, `safeNextPath` prefix check let `/\host` and `//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 + +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. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index ea47752a..0d613fc4 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -223,3 +223,7 @@ User validated Step 7 (all screens, flows, FR/EN, responsive; Home-without-sideb ## 2026-10-12 (Step 8 analysis) User: Step 7 closed; Step 8 = files foundation + Storage, analysis before implementation; Q2 settled (self-hosted first, managed later); 8 private buckets closed by default; quarantine + server validation; allowlist SVG; avatar in Mon compte; release 0.2.0 kept = Steps 3–6, identity → 0.3.0, check deploy triggers before finishing. Done on chore/step-08-files-analysis: docs/development/STEP8_FILES_ANALYSIS.md (assets table authority, server-built keys, quarantine prefix, worker `faunosteo_worker` sharp + pdf sanitiser, policies through assets, Storage API signing under RLS, sweeper/reconcile, file volume + restic backups, managed migration by rows, 10 security answers, scope, tests, risks, D1–D8); 3 plan-challengers dispatched. Release check: CI on push main/develop only, no tag trigger, no deploy job; hooks push only; VPS deploy manual; default 0.2.0 build has no sheet → never redeploy the live tool from main without SHEET_BUNDLE=draft. Awaiting user: D1–D8 + Step 8 go; release finish go. + +## 2026-10-12 (Rust-by-default review) + +User: new permanent rule, Rust preferred for everything equivalent or better, existing code included; study + roadmap before Step 8 or any migration; nothing implemented. On chore/step-08-files-analysis: 4 analyzers + 3 researchers (scratchpad reports) → `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 1 (6a078da) → 3 plan-challengers (61 findings, 2 blockers: deletion schedule vs surviving TS consumers; CSP/VPS deployment facts) → rev 2 folded. Outcome: A/B/C classification (B empty), 3-crate workspace, Rust worker design (keyless parent, traced seccomp, libwebp in child), roadmap R0–R5 with end criteria + rollback rows, 13 decisions D-R1..D-R14. Memory: BDR-043, LRN-048, EVAL-016; CLAUDE.md "Rust by default" section; TODO Rust block. No cargo on the dev host (owner installs rustup at R0). Awaiting owner validation; release 0.2.0 untouched. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index b44d7872..ee3c8c58 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -357,3 +357,8 @@ Apply: any pipeline extraction (Step 13 Supabase provider, Step 14 worker); any 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.`; 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:`, `/api/v1/message/`) makes the confirmation + recovery flows scriptable headlessly; playwright-core installed in the scratchpad + cached `ms-playwright` chromium via `executablePath` = no project dependency. Apply: every future Supabase auth surface (Step 14 gating, invitations), any pgTAP write assertion, any e2e of email flows. + +## LRN-048 | 2026-10-12 | Before porting a module, list the hidden serialisation contracts; goldens on drawn primitives make an engine swap provable + +Context: Rust review inventories. Facts found: `documentSha256` = sha256 of Prettier-formatted text (only compared at runtime → mismatch = rebase, not loss); coordinates = raw JS number strings (serde_json prints `1523.0`); attachment = insertion-order JSON, snapshot = Zod schema order; `.optional()` absent vs nullable `null` (serde-wasm-bindgen json preset writes null → breaks readers); text x positions = AFM widths + kerning pairs; dates = ICU; `toUpperCase`, `/\s+/`, non-fatal TextDecoder, last-dup-key JSON.parse, Zod `.int()` accepting 2.0. The 39 PDF goldens record draw calls (spies), never bytes → a Rust engine with a draw-log layer can match them exactly; byte goldens (xmldom XMLSerializer, Prettier files) cannot be matched by another stack → compare parsed trees or regenerate by decision. +Apply: any port (R2–R5): freeze unpinned outputs with the old code (LRN-046), write the contract list with a fixture each, decide lenient-vs-strict per item, keep an N-1 reader test permanently. Challengers found 2 blockers rev 1: deletion schedule vs surviving consumers (name the last consumer per module), and deployment facts (CSP without 'wasm-unsafe-eval', VPS compiling images) → check the serving path before the language. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b12acae0..47711a04 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -129,11 +129,19 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [ ] Step 8 — files foundation + Supabase Storage (analysis 2026-10-12 on chore/step-08-files-analysis: docs/development/STEP8_FILES_ANALYSIS.md; 3 plan-challengers (47 findings folded, rev 2); AWAITING USER DECISIONS D1–D9 + go; nothing implemented). User brief: 8 private buckets closed by default, quarantine + server validation, allowlist SVG, avatar in Mon compte (upload/preview/replace/delete/header), JPEG/PNG/WebP ≤ 5 MB resized + metadata stripped, no SVG avatar, service role never in the browser, portable self-hosted → managed, allowed + denied access tests - [x] 8.0 analysis: facts (existing bucket + policy pattern, sanitiser, edge runtime off, CSP, deploy), design (assets table authority, server-built keys, quarantine prefix, worker `faunosteo_worker` with sharp + pdf sanitiser, storage.objects policies through assets, Storage API signing under RLS, sweeper/reconcile, backups file volume + restic, managed migration by rows), 10 security answers, scope, tests, risks, D1–D8 - [ ] 8.1 migration 20261012100000_files_foundation (asset_status, assets, 7 buckets, avatar predicates, avatars policies, purge queue + triggers, storage ceiling, 9 RPCs, revokes) + pgTAP 010 allowed/denied + policy census (one bucket literal per policy) + 001 census + types regen - - [ ] 8.2 apps/worker: keyed I/O loop + keyless decode child (sharp, 20 s SIGKILL), lease claim, PUT→complete→DELETE order, sweeper (purge queue + quarantine by key), watchdog, Dockerfile + compose service (read-only, cpus 1, internal network) + .env.worker.example, fixtures tests with time/RSS asserts, local-stack integration test + - [ ] 8.2 worker → SUPERSEDED by Rust R1 (RUST_ARCHITECTURE_REVIEW Part IV, D1 = native Rust worker): `crates/worker` keyed `run` loop + keyless `decode` child, lease claim, PUT→complete→DELETE order, sweeper (purge queue + quarantine by key), per-stage deadlines, Dockerfile (distroless/static) + compose service (read-only, cpus 1, internal network) + .env.worker.example, fixtures + sandbox tests on the production image, local-stack integration test - [ ] 8.3 packages/supabase assets service (begin/upload/confirm/remove/fetchOwnAvatar/downloadAvatar, closed failure kinds; no signed URL) - [ ] 8.4 app: avatar block in Mon compte (picker, canvas ≤1024 JPEG transport, preview, save, processing, supersede, delete), UserBadge photo, top bar avatar (D3), authStore blob URL, i18n, tests; design toolchain + impeccable detect - [ ] 8.5 docs: STORAGE.md (model, keys, statuses, purge/grace rules, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker, env file, network, CSP connect-src), SUPABASE.md, CLAUDE.md, CHANGELOG, plan note (worker early, SVG processor → Step 13); CI jobs - [ ] 8.6 verify: root check, PGlite + real stack pgTAP, types, docker builds (app + worker), real-stack e2e (sign allowed/denied), gates verifier + security; memory; stop for user validation +- [ ] Rust by default (rule adopted 2026-10-12, BDR-043; study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 on chore/step-08-files-analysis, 3 challengers folded; AWAITING OWNER VALIDATION + decisions D-R1..D-R14; nothing implemented). Roadmap once validated (each phase: oracles frozen with the old code, consumer-driven deletion, rollback row, gates): + - [ ] R0 foundation (inside Step 8): Cargo workspace (`crates/core`, `wasm`, `worker`), toolchain pin, deny.toml, lints, CI job `rust`, worker image, `docs/development/RUST.md`, DEPLOY.md (images pulled by digest, CSP `'wasm-unsafe-eval'`, gzip wasm, VPS headroom); owner installs rustup; verify panic strategy on wasm32 + - [ ] R1 = Step 8 worker in Rust (replaces 8.2 below): decode child dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist, `image` + `moxcms` + `libwebp-sys` in the child, parent RIFF-header check only, 512 KiB output cap, per-stage deadlines, service key + - [ ] R2 domain core (before Step 9): sheet/report/archive contracts, `SheetHandle` + `SheetIndexData`, reducers, Finding builder, vertebra selection, publish gate; wasm facade (JSON strings, ts-rs types, poison + reinstantiate, lazy init); app switched; 3 envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP; `packages/domain` frozen for engine/pipeline + - [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first + - [ ] R4 pdf core: reader (Web Worker, BLK-009 browser measurements) + writer (`pdf-writer`, Std14 AFM, draw log; lines/rects/colours golden frozen with the TS engine first, D-R2) + `report-compare` tool; `packages/pdf` deleted; N-1 scanner reads R4 PDFs + - [ ] R5 curation pipeline + importer + upload tool: seed golden regenerated once (new `documentSha256`, D-R5), `packages/anatomy` + `packages/domain` deleted, docs map; all before Step 13 + - [ ] separate chore (D-R7): form constraints module + PGlite `pg_constraint`/config.toml parity test - [ ] Release 0.2.0 (branch release/0.2.0 = Steps 3–6, version.txt + package versions 0.2.0, CHANGELOG [0.2.0] 2026-10-11): deploy-trigger check done 2026-10-12 (CI = branches main/develop only, no tag trigger, no deploy job, docker job builds `faunosteo:ci` locally; hooks push only; DEPLOY.md deploy = manual on the VPS). Default 0.2.0 build carries NO sheet (SHEET_BUNDLE=none) → the live local tool must not be redeployed from main without `--build-arg SHEET_BUNDLE=draft`. Finish via /release-candidate (finish + tag span, tag push on explicit go); CHANGELOG back-merge conflict expected (Unreleased Step 7 above [0.2.0]). Awaiting the user's go. --- diff --git a/CLAUDE.md b/CLAUDE.md index 07516633..bd05dd49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -424,6 +424,36 @@ Database (Supabase) --- +## Rust by default (rule adopted 2026-10-12, BDR-043) + +Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (awaiting +the owner's validation before any implementation; release 0.2.0 unaffected). + +- Any logic that can run in Rust with no significant loss (features, UX, + graphics, data compatibility, security, reliability, useful performance, + resources, portability, maintainability, operations) is written in Rust: + native for services, jobs and tools, WebAssembly for the browser. + Equivalence suffices; "already in TypeScript", "more work" and "no + performance gain" are never reasons to keep TypeScript. +- Kept as is: React + TypeScript for UI, DOM, routing, Zustand stores, + display formatting and vendor-SDK glue (supabase-js); UI form schemas + (Zod, i18n keys) and dictionaries; Tailwind; PostgreSQL/SQL + RLS; + Supabase Auth and Storage; Vite/ESLint tooling. A component kept in + TypeScript needs the concrete constraint recorded in the review's + exception table (Part II). +- New business logic (rules, data transformations, parsers, validators, + jobs, services, rule mirrors of SQL) is designed in `crates/` first and + reached from TypeScript through the wasm facade; Edge Functions are not + used. Boundary rules: "Rust computes, TypeScript reads" (review Part + III.3: coarse calls, JSON strings, sheet handle, closed error kinds, ids + and time injected, no call in a render path). +- Existing code migrates along the review's phases (R0–R5), each with + oracles frozen with the old code before the switch and a consumer-driven + deletion of the TypeScript it replaces; two implementations never outlive + the phase that switches the last consumer. + +--- + ## Key dependencies | Package | Purpose | diff --git a/docs/development/RUST_ARCHITECTURE_REVIEW.md b/docs/development/RUST_ARCHITECTURE_REVIEW.md index 153a977f..1d4c8e0e 100644 --- a/docs/development/RUST_ARCHITECTURE_REVIEW.md +++ b/docs/development/RUST_ARCHITECTURE_REVIEW.md @@ -1,23 +1,25 @@ # Rust by default: architecture review and migration roadmap -Status: study for the owner's decision, 2026-10-12, revision 1 (three -independent plan challenges follow; their findings will be folded into a -revision 2). Nothing implemented. Applies the owner's brief of 2026-10-12: -Rust becomes the preferred language for everything that can reasonably be -written in Rust, for new work and for existing code; equivalence suffices; -"already in TypeScript" and "more work" are not reasons to keep TypeScript; -a component kept in another language needs a concrete constraint. +Status: study for the owner's decision, 2026-10-12, revision 2 after three +independent plan challenges (correctness, robustness, simplicity: 61 +findings, 2 blockers; what changed is listed in §0.2). Nothing implemented. +Applies the owner's brief of 2026-10-12: Rust becomes the preferred language +for everything that can reasonably be written in Rust, for new work and for +existing code; equivalence suffices; "already in TypeScript" and "more work" +are not reasons to keep TypeScript; a component kept in another language +needs a concrete constraint. -Part I states the facts (inventory of the code, the hidden contracts a port -must honour, the state of the Rust ecosystem on 2026-10-12, verified by three -research agents against crates.io, RustSec, GitHub and the Supabase docs). -Part II classifies every module (A now, B later with a trigger, C exception). -Part III is the target Rust architecture (workspace, boundaries, bindings). -Part IV is the Step 8 worker in Rust. Part V lists the libraries retained -and their limits. Part VI is the progressive migration with end criteria. +Part I states the facts (inventory, the hidden contracts a port must honour, +the state of the Rust ecosystem on 2026-10-12, verified by three research +agents against crates.io, RustSec, GitHub and the Supabase docs). Part II +classifies every module (A now, B later with a trigger, C exception). Part +III is the target architecture (workspace, boundary, bindings). Part IV is +the Step 8 worker in Rust. Part V lists the libraries retained and their +limits. Part VI is the progressive migration with end criteria and rollback. Part VII adapts the development plan. Part VIII covers Docker, Supabase and CI. Part IX gives validation criteria and risks. Part X lists the decisions -the owner has to take. Section 0 states what this study pushes back on. +the owner has to take. §0 states what this study pushes back on and what the +challenges changed. Companion material: `STEP8_FILES_ANALYSIS.md` (the design this review keeps, with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, @@ -25,47 +27,89 @@ with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, --- -## 0. What this study pushes back on (read first) +## 0. Pushbacks and revision notes -1. **Where Rust actually buys something here.** The browser already runs - memory-safe code, so "Rust is safer" is not an argument for the SPA. The - real gains are elsewhere: one core that runs identically in the worker, in - CLI tools and in the browser (server-side PDF import and rendering arrive at - Step 15 and need exactly the engine the browser has); untrusted bytes - (images, SVG, PDF attachments) parsed on the server in a language with - hard allocation caps and without libvips, libpng or xmldom in the trusted - base; the removal of three dependencies the project already distrusts - (`pdf-lib` unmaintained since 2021, BLK-009; UPNG trusting its input; - `DecompressionStream` as the only inflater on every read path); and the - unification of two things the inventory found duplicated today (two SVG - sanitisers, two view compositions, two `formatDate`, four copies of the - bilingual fallback). The study claims these gains and no others. +### 0.1 What this study pushes back on + +1. **Where Rust buys something here.** The browser already runs memory-safe + code, so "Rust is safer" is no argument for the SPA. The gains the study + claims: one core that runs identically in the worker, the CLI tools and + the browser (server-side archive validation at Step 15 needs the reader + the browser has); untrusted bytes (images, SVG, PDF attachments) parsed on + the server with hard allocation caps and without libvips, libpng, xmldom + or UPNG in the trusted base; the removal of three dependencies the + project already distrusts (`pdf-lib` unmaintained since 2021, BLK-009; + UPNG trusting its input; `DecompressionStream` as the only inflater on + every read path); and the unification of what the inventory found + duplicated (two SVG sanitisers, two view compositions, three copies of + the bilingual label fallback in rule code). Screen-only helpers + (`formatDate` for the UI, `pickLabel` in JSX) stay TypeScript and are not + counted as unified. 2. **The rule has a standing cost the project must own.** Two toolchains in - CI and Docker, a WASM boundary to design and debug, Rust skills on a - one-person team, parity harnesses to write and then delete. The study - makes each cost visible (Part VIII, Part IX) instead of hiding it in the - word "equivalent". -3. **The PDF engine is the riskiest migration and has the least standalone - value until a server consumes it.** It is classified B with an explicit - trigger (Step 15 or the TTF font change, whichever comes first), not A. - Moving it now would spend the largest effort on the module with the - strongest goldens and no product change. -4. **Rust does not remove the SQL mirror.** `private.sheet_document_issues` + CI and Docker, a WASM boundary to design, debug and keep safe, Rust + skills on a one-person team, oracles to freeze before every switch. Each + cost is made visible (Parts VIII, IX) instead of hidden in "equivalent". +3. **Rust does not remove the SQL mirror.** `private.sheet_document_issues` stays SQL because managed Supabase runs no custom `pgrx` extension; Rust - replaces the TypeScript side of the pair, not the pair. -5. **Two hidden contracts bind the curation pipeline to the JavaScript - toolchain.** The sheet identity `documentSha256` is the sha256 of the - Prettier-formatted JSON text, and generated coordinates are raw JavaScript - number strings. A Rust pipeline either keeps a Prettier formatting step - (recommended) or changes the identity rule under a schema migration. -6. **One global rule conflicts with the new one.** The global CLAUDE.md + replaces the TypeScript side of the pair; the pair itself remains. +4. **The sheet identity hash changes once.** `documentSha256` is today the + sha256 of the Prettier-formatted document text. It is computed once by + the pipeline and only compared at runtime; a different hash sends an old + archive through the rebase path (visible import message, nothing lost), + exactly as any content changeset does. The study therefore does not + chain the pipeline to Prettier (D-R5); it states the one-time effect. +5. **One global rule conflicts with the new one.** The global CLAUDE.md mandates Astro for public sites; the Rust rule would prefer a Rust static - site generator. The study recommends keeping Astro and records the - conflict as a decision (D-R8), not a silent choice. -7. **Form validation stays TypeScript by the owner's own retained list** - (code directly tied to React). The constraints themselves must stop being - written in two places (Zod and SQL CHECKs); the study proposes where the - single source lives. + generator. The study recommends keeping Astro and records the conflict as + a decision (D-R8). +6. **Form validation stays TypeScript by the owner's own retained list** + (code directly tied to React). The constraints themselves are written in + two places today (Zod and SQL CHECKs) and already drift; a small chore + outside this roadmap gives them one home (D-R7). +7. **The production surface decides more than the language.** Two of the + blockers found by the challenges were deployment facts: the documented + CSP refuses WebAssembly, and the VPS (1 vCPU, 1 GB) compiles the images + it runs. Both are fixed in the roadmap before any wasm reaches + production (D-R13, VIII.1). + +### 0.2 Changes after the challenges (revision 2) + +Folded: three crates instead of six (one feature-gated core, one wasm +facade, one worker binary with tool binaries); no throwaway dual-run parity +harness (unpinned outputs frozen as goldens with the old code, oracle suites +ported to cargo on the fixtures in place); consumer-driven deletion schedule +(a TypeScript module is deleted in the phase that switches its last +consumer, frozen and parity-tested in between; revision 1 deleted modules +that later phases still imported); the PDF writer and the curation pipeline +reclassified A with technical dependencies only (revision 1 deferred them +for reasons the brief excludes); a two-call export (compose views, the +caller rasterises, pure writer) that removes the async rasteriser from the +boundary and the need for resvg in the browser; a Rust-owned sheet handle +instead of re-shipping the sheet per click; JSON strings across the boundary +with generated types (no `serde-wasm-bindgen`, whose `json_compatible` +preset would write absent optionals as `null`); panic = abort on wasm32 +handled on the TypeScript side (poison and re-instantiate); lazy wasm +initialisation with a degraded state so the auth shell never depends on the +module; the PDF reader in a Web Worker with the BLK-009 browser measurements +as exit criteria; CSP `'wasm-unsafe-eval'` and gzip for the module; images +built in CI and pulled by digest, never compiled on the VPS; per-phase +rollback rows and draft quarantine instead of silent discard; the keyed +worker parent never decodes (fixed-size read, RIFF header allowlist, no +pixel decode); seccomp allowlist derived by tracing, applied before any +thread exists, Landlock and three rlimits dropped as redundant; worker +credential kept as validated (service key), the dedicated role moved to a +hardening option with its exact prerequisites; display helpers and +`isIdentityComplete` kept in TypeScript; `constraints.json`, `schemars`, +`cargo-chef`, `cargo-audit`, `infer`, `img-parts`, fuzzing-now and the DEV +footer removed; five JavaScript semantics on reader paths added to the +contract list; Step 15 no longer cited as a rendering trigger; decisions +merged from 14 to 13. + +Not folded (with the reason): "split R2 into three gates" is kept as an +option for the implementation contract, since each sub-phase would create a +short-lived TS-to-wasm seam inside the store; "keep the Landlock layer +best-effort" is replaced by dropping it (the seccomp allowlist already +denies every file and process syscall, so the layer would test nothing). --- @@ -74,58 +118,68 @@ with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, ### I.1 Inventory of the existing code Sizes are TypeScript lines (`wc -l`, `.d.ts` excluded), HEAD `aae0b39`. -Test counts are static (`it` plus `.each` rows), except where a suite was run. +Test counts are static (`it` plus `.each` rows) except where a suite was run. | Unit | Source | Tests | Runs where | Purity today | |---|---|---|---|---| -| `packages/domain` | 18 files, 2,298 lines; zod 3.25 only | 9 files, 162 cases (194 at runtime, one file re-imports another) | browser (app), engine, scripts | entirely pure: no `JSON.stringify`, no `Date`, no ids, no I/O; host APIs `structuredClone`, `TextEncoder`, `Object.hasOwn`, `new URL()` via Zod | +| `packages/domain` | 18 files, 2,298 lines; zod 3.25 only | 9 files, 162 cases (194 at runtime, one file re-imports another) | browser (app), engine, pipeline, scripts | pure: no `JSON.stringify`, no `Date`, no ids, no I/O; host APIs `structuredClone`, `TextEncoder`, `Object.hasOwn`, `new URL()` via Zod | | `packages/anatomy` | 43 files, 4,897 lines: legacy importer 1,842, curation 2,329, render 553, cli 119 | 15 files, 130 cases (run: 130/130) | **render only** at application runtime (app canvas, PDF composition); the other 4,344 lines run for `pnpm import:equine`, the pipeline and tests | render is pure (plain `LayerElement` tree); importer and pipeline use xmldom, `node:fs`, `node:crypto`, Prettier | -| `packages/pdf` | 27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom | 9 files, 137 cases | browser (export, import), CLI, tests | explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: `DecompressionStream` on every read path, `Intl.DateTimeFormat` for dates, `TextEncoder/Decoder` | -| `packages/supabase` | 949 lines (596 generated `database.types.ts`) | 6 files; PGlite harness runs 9 pgTAP files, 280 assertions | browser, CI | two rules only: GoTrue error code → closed `AuthFailure` kind (23 codes → 13 kinds), publish gate (Zod + `assertPublishable` before the RPC); the rest wraps supabase-js | -| `apps/app/src` logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) | 37 files, 2,476 lines (1,708 without the two 281-key dictionaries) | 42 files, 214 cases + 7 `.each` blocks | browser | `services/zoneInteraction.ts` (213 lines) is pure; stores are Zustand glue around domain calls; `drawing.ts` is DOM (DOMParser, importNode) with an app-local denylist sanitiser | -| `apps/app/src` UI (components, routes, styles) | 65 files, 4,838 lines | component and route suites | browser | React; carries some business rules (I.3) | +| `packages/pdf` | 27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom | 9 files, 137 cases | browser (export, import), CLI, tests | explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: `DecompressionStream` on every read path and in the PNG gate, `Intl.DateTimeFormat`, `TextEncoder/Decoder` | +| `packages/supabase` | 949 lines (596 generated `database.types.ts`) + `scripts/upload-sheet-assets.ts` (99 lines, operator, service key) | 6 files; PGlite harness runs 9 pgTAP files, 280 assertions | browser, CI, operator | two rules only: GoTrue code → closed `AuthFailure` kind (23 → 13), publish gate (Zod + `assertPublishable` before the RPC); the rest wraps supabase-js | +| `apps/app/src` logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) | 37 files, 2,476 lines (1,708 without the two 281-key dictionaries) | 42 files, 214 cases + 7 `.each` blocks | browser | `services/zoneInteraction.ts` (213 lines) pure; stores are Zustand glue around domain calls; `drawing.ts` is DOM (DOMParser, importNode) with an app-local denylist sanitiser | +| `apps/app/src` UI (components, routes, styles) | 65 files, 4,838 lines | component and route suites | browser | React; carries some data-building rules (I.2) | | `apps/app/src/pdf` + `scripts/` | 4 files, 235 lines + 2 files, 549 lines | 65 PDF-related app cases + 11 CLI cases | browser / Node | branding from bundled logos, `Image` + canvas rasterizer; CLI `report:compare` on the engine scanner | -| `apps/app/vite/sheet-bundle.ts` | 102 lines | 7 | Vite build | Vite plugin: virtual module embedding ~510 KB of seed JSON | +| `apps/app/vite/sheet-bundle.ts` | 102 lines | 7 | Vite build | virtual module embedding ~510 KB of seed JSON | | `supabase/` | 7 migrations, 9 pgTAP files, seed | 280 assertions (PGlite and real stack) | PostgreSQL | SQL; stays | -Workspace total measured on the Step 7 closure: 763 vitest cases, lint 0, -build and Docker green. +Workspace total at the Step 7 closure: 763 vitest cases, lint 0, build and +Docker green. -### I.2 Hidden contracts a port must honour (found by the inventories) +### I.2 Hidden contracts a port must honour -These are the facts that decide feasibility, not the line counts. +These facts decide feasibility, not the line counts. Each one gets a fixture +or a golden before the phase that touches it (Part VI). | Contract | Where | Consequence for Rust | |---|---|---| -| `documentSha256` = sha256 of the **Prettier**-formatted lean document JSON (Prettier 3.8.3 collapses short arrays), computed by the pipeline; compared at runtime by `rebase.ts:119`, `envelope.ts:100`, `pdf export.ts:88` | `packages/anatomy` curation, every Report v3 `sheet.documentSha256` | a Rust pipeline must emit byte-identical text or the sheet identity changes under every existing report and archive; Prettier's fitting algorithm is not a serde option (Part II, D-R5) | -| Generated coordinates printed as raw JS `Number → String` (`1715.4285714285713`), never rounded | pipeline outputs, review SVGs, layer attributes (`"1118"`, `"0.85"` in the step6 view goldens) | integer-valued floats print without `.0` in JS, `serde_json` prints `3.0`; a JS-compatible number formatter (shortest round-trip, JS exponent thresholds) is required and must be golden-tested | -| Zod rebuilds parsed objects in **schema key order**; the archive snapshot written into PDFs inherits that order through `assertSnapshot` + `JSON.stringify(…, null, 2)` | `packages/domain`, `packages/pdf` attachment | Rust structs declare fields in the Zod schema order; `serde_json` pretty output otherwise matches `JSON.stringify(v, null, 2)` (2 spaces, `": "`, `[]`/`{}`, raw non-ASCII, `\u00XX` controls); no test pins the attachment bytes today, so this is a choice to make explicit (D-R11) | -| Text layout x positions depend on `widthOfTextAtSize`, which sums AFM widths **plus kerning pairs**, while `drawText` writes unkerned glyphs | `packages/pdf` render, 39 goldens (12 text, 12 images, 12 links, 3 views) | the Rust engine must embed the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so an exact reproduction is provable | -| Dates through `Intl.DateTimeFormat` (ICU): `11 octobre 2026`, `November 20, 2026`, UTC | `packages/pdf/src/render/dates.ts`, `apps/app/src/lib/dates.ts` (a second, different implementation) | explicit fr/en month tables in Rust; the goldens pin the strings | -| Labels upper-cased with JS `toUpperCase()` before `safeText` | engine | Rust `to_uppercase` applies the same full Unicode mapping; goldens pin `É È Ê Ï` | -| One inflater: `DecompressionStream('deflate')` on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size | engine read path and branding | `miniz_oxide` bounded inflate replaces it everywhere, which is a portability gain (no Web API on the read path) | -| Two sanitisers: app canvas denylist (`drawing.ts`: 5 tags, `on*`, `javascript:`) and engine allowlist with caps | app vs engine | one Rust sanitiser serves both; the engine's "zero-removal" test takes xmldom's own re-serialisation as oracle and needs a committed oracle instead | -| Two view compositions: `composeViewSvg` mutates an xmldom element passed by the engine; the app composes with the browser DOM | engine vs app | one Rust `compose_view_svg(asset, document, view, states) → String` serves both | -| `buildSheetIndex` returns ten closures over four private `Map`s, called per render by about 14 app modules | `packages/domain` sheet-index, app | the WASM boundary cannot export closures; the index becomes plain data built once (Part III.3) | -| Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (no path, codes only) and adds 3 of its own | domain `validate.ts`, migrations | the Rust validator takes the TS role; SQL stays; a shared conformance fixture set pins both | -| `instanceof` on three domain error classes in pdf and app scripts | domain errors | replaced by closed kind discriminants (the BDR-015 pattern) at the boundary | -| Report ids `crypto.randomUUID()`, `createdAt` and `exportedAt` from `new Date()` in the store and the app export | `apps/app` | ids and timestamps are injected into the core, never generated inside it (keeps the core deterministic and testable) | -| Zustand store takes `hydrateReport(report)` as is, no Zod parse; `initReport` only trims | `reportStore.ts` | the Rust parser becomes the single entry for any report entering the store (closes a CLAUDE.md drift the inventory found) | -| Business rules living in UI files: `FindingsTreePicker.toggleLeaf` (builds a `Finding` with snapshots and the vet flag), `ObservationCard.zoneLabel/zoneTrees/unresolvedFindings`, `VertebraPicker` selection rules, `isIdentityComplete` twice | components | these move into the core at the same phase as the observation reducers (Part II, R2) | +| `documentSha256` = sha256 of the Prettier-formatted lean document text, computed once by the pipeline (`pipeline.ts:163`, `format.ts`), only **compared** at runtime (`rebase.ts:119`, `envelope.ts:100`, pdf `export.ts:88`); a mismatch sends the report through `rebaseReportOnSheet`, which keeps every datum and flags only ids the sheet lacks | `packages/anatomy`, every Report v3 `sheet.documentSha256` | identity = sha256 of whatever bytes the pipeline emits; when the Rust pipeline emits different bytes, the hash changes once and every older archive rebases on import, as after any content changeset (D-R5) | +| Generated coordinates and layer attributes are raw JS number strings (`1715.4285714285713`, `"1118"`, `"0.85"`); `CoordinateSchema` is `z.number().finite()` and most values are integer-valued floats (`"cx": 1523`) | pipeline outputs, review SVGs, layer attributes, snapshot in the archive | `serde_json` prints `1523.0`; a `js_number` formatter (shortest round-trip, JS rules for `.0`, `-0`, exponents at 1e21 / 1e-7) is installed as a custom `serde_json::Formatter` for **every** JSON output and used by the SVG serialiser; tested on the committed overlays | +| Attachment JSON: `report`, `branding` and `labels` are serialised in **insertion order** as passed (pdf `export.ts:112-115`); only the snapshot is re-parsed (Zod schema order); zones are built `{annotationId, viewId, labelFrSnapshot, labelEnSnapshot, side}` with `vertebrae` appended last | engine, store reducers | the attachment bytes change at R2 when Rust emits struct-ordered objects: declared as a new contract (D-R11); what must hold is that every previous reader (the shipped Zod schemas, frozen as a test fixture) parses what Rust writes | +| Optional vs nullable: `.optional()` fields are **absent** when unset (`side`, `unresolved`, `severity`, `nextAppointment`), `versionId` is required and `null` for bundled-draft reports | `packages/domain/src/report/v3.ts` | per-field serde attributes (`skip_serializing_if = "Option::is_none"` for optional, plain `Option` for nullable); a boundary that writes absent as `null` breaks every existing reader | +| Text layout x positions depend on `widthOfTextAtSize`, which sums AFM widths **plus kerning pairs**, while `drawText` writes unkerned glyphs | engine render, 39 goldens (12 text, 12 images, 12 links, 3 views) | the Rust engine embeds the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so exact reproduction is provable | +| Dates through `Intl.DateTimeFormat` (ICU): `11 octobre 2026`, `November 20, 2026`, UTC; `Date.UTC` maps years 26–99 to 19xx | `packages/pdf/src/render/dates.ts` | explicit fr/en month tables; the two-digit-year quirk is decided (tighten) with a fixture | +| `toUpperCase()` on labels before `safeText`; `wrapLines` splits on `/\s+/` (keeps a trailing empty word; JS `\s` ≠ `char::is_whitespace` on U+FEFF, U+0085) | engine | same Unicode upper-casing in Rust; whitespace class written explicitly; fixtures for both | +| Reader leniency: `TextDecoder` non-fatal (invalid UTF-8 → U+FFFD, BOM stripped, `scan.ts:498`); `JSON.parse` keeps the last duplicate key; Zod `.int()` accepts `2.0` | engine reader, domain | `serde_json` rejects all three; each is decided (keep lenient with a custom step, or tighten) and pinned by a hostile fixture before R4 | +| One inflater: `DecompressionStream('deflate')` on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size | engine read path, branding | `miniz_oxide` bounded inflate replaces it everywhere (no Web API on the read path) | +| Two sanitisers: app canvas denylist (`drawing.ts`: 5 tags, `on*`, `javascript:`) and engine allowlist with caps; the engine's "zero-removal" oracle is xmldom's own re-serialisation | app vs engine | one Rust sanitiser; the oracle becomes a DOM-equivalence check (parsed trees compared), not bytes | +| Two view compositions: `composeViewSvg` mutates an xmldom element passed by the engine; the app composes with the browser DOM; the `review/app-*.svg` byte goldens are xmldom `XMLSerializer` output (declaration, whitespace nodes, `xlink:` prefixes) | engine vs app vs pipeline | one Rust `compose_view_svg` for app and engine; the xmldom-byte goldens stay owned by the TS pipeline until R5, where their regeneration is a decided change | +| `buildSheetIndex` returns ten closures over four private `Map`s and the whole `LoadedSheet` (296 KB document, 130 KB drawing, 84 KB map), called per render by ~14 modules and taken by the reducers | domain sheet-index, app | the sheet lives once in Rust memory as a handle; React reads a precomputed plain-data index (names, node-by-path) built once | +| Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (codes only) and adds 3 of its own | domain `validate.ts`, migrations | the Rust validator takes the TS role; SQL stays; conformance fixtures carry two expectation sets (Rust: codes + paths; SQL: codes) | +| `instanceof` on three domain error classes in pdf and app scripts | domain errors | closed kind discriminants at the boundary (BDR-015 pattern) | +| Report ids `crypto.randomUUID()`, `createdAt` / `exportedAt` from `new Date()` | `apps/app` | ids and timestamps are inputs of the core | +| Store takes `hydrateReport(report)` as is, no parse; `initReport` only trims | `reportStore.ts` | the Rust parser becomes the single entry for any report entering the store | +| Rules living in UI files that **build data**: `FindingsTreePicker.toggleLeaf` (Finding with snapshots and the vet flag), `VertebraPicker` selection rules | components | move to the core with the reducers (R2); display helpers (`zoneLabel`, `zoneTrees`, `describeZone`, import message lines, `isIdentityComplete`) stay TypeScript glue over precomputed data | +| Draft persistence drops an unparseable draft silently (`persistence.ts:55-58`, DEV warning only) | app | a draft the running build cannot parse is kept under a quarantine key with a visible notice (needed by every phase's rollback, VI.3) | +| The wasm module is a new single point of failure: `useSheet.ts` caches a rejected promise for the session and has no error state | app | lazy initialisation behind the sheet and import paths only, a `core_unavailable` state with retry, auth shell independent of the module | -### I.3 Toolchain and host facts +### I.3 Toolchain, host and deployment facts -- No `cargo`, `rustc` or `rustup` on the development host today (checked - 2026-10-12). Rust stable is 1.99.0 (2026-10-01), edition 2024 since 1.85. -- Docker 29.8.2 rootless on the host (`seccomp` builtin profile, `rootless`, - `cgroupns`), kernel 7.0 with the Landlock LSM enabled and seccomp filters. - The VPS kernel is not verified; Landlock needs 5.13+ (Ubuntu 24.04 ships - 6.8). -- Docker's default seccomp profile (rootless included) allows `seccomp`, - `landlock_create_ruleset`, `landlock_add_rule`, `landlock_restrict_self`, - `prctl`, `setrlimit`, `prlimit64` unconditionally; `unshare` and `clone3` - with namespace flags need `CAP_SYS_ADMIN`. A seccomp + Landlock + rlimit - child works inside a container; user-namespace isolation does not. +- No `cargo`, `rustc` or `rustup` on the development host (checked + 2026-10-12). Rust stable 1.99.0 (2026-10-01); edition 2024 since 1.85. On + `wasm32-unknown-unknown` the shipped standard library is panic = abort: a + panic traps the instance and `catch_unwind` never returns (verify at R0; + consequence handled in III.3). +- Docker 29.8.2 rootless on the host (seccomp builtin, `rootless`, + `cgroupns`), kernel 7.0. Docker's default seccomp profile (rootless + included) allows `seccomp`, `prctl`, `setrlimit`, `prlimit64` + unconditionally; `unshare` and `clone3` with namespace flags need + `CAP_SYS_ADMIN`. A seccomp + rlimit child works inside a container; + user-namespace isolation does not. +- Production: `DEPLOY.md` sizes the VPS at 1 vCPU / 1 GB / 10 GB (the Node + build already ran out of memory on DEV1-XS), deploys with `docker compose + up --build` **on the VPS**, documents a rebuild as the rollback, and sets + `script-src 'self'` without `'wasm-unsafe-eval'` in both the nginx and + the Caddy examples; `docker/nginx.conf` has no `gzip` directive. - CI runs on a Gitea `act_runner`; JavaScript actions need `node` in the job image; `dtolnay/rust-toolchain` and `taiki-e/install-action` are shell composites; `Swatinem/rust-cache` relies on `actions/cache` (Gitea runner @@ -133,299 +187,282 @@ These are the facts that decide feasibility, not the line counts. ### I.4 Ecosystem facts (as of 2026-10-12) -Verified on crates.io, docs.rs, GitHub and RustSec by the research agents; -"UNVERIFIED" items are listed in Part IX.4. +Verified on crates.io, docs.rs, GitHub and RustSec; "UNVERIFIED" items are in +IX.4. Core and bindings: | Need | Crate | Version (date) | Status | Limits | |---|---|---|---|---| -| JSON | `serde` / `serde_json` | 1.0.229 / 1.0.154 (2026-10-11) | serde-rs org | pretty printer matches `JSON.stringify(v,null,2)` except integer-valued floats (`3.0`) and `-0.0`; `preserve_order` feature | +| JSON | `serde` / `serde_json` | 1.0.229 / 1.0.154 (2026-10-11) | serde-rs org | pretty printer matches `JSON.stringify(v,null,2)` except integer-valued floats (`3.0`) and `-0.0`: custom `Formatter` (I.2) | | Hashing, base64 | `sha2` 0.11.1, `base64` 0.23.1, `hex` 0.4.3 | | RustCrypto / marshallpierce | none open | | Inflate | `miniz_oxide` 0.9.1 (2026-03), `flate2` 1.1.10 | pure Rust | | `decompress_to_vec_zlib_with_limit`, streaming `Decompress` for incremental cancel | -| WASM glue | `wasm-bindgen` 0.2.129 (2026-09-25), `wasm-bindgen-futures` 0.4.79, `js-sys` / `web-sys` 0.3.106 | org `wasm-bindgen` (Cloudflare maintainers), monthly releases, MSRV 1.81 | since 0.2.128 the crate and the CLI must be the same version | -| WASM build | `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen-cli`; `wasm-pack` 0.15.0 (2026-05, one maintainer, 335 open issues); `wasm-opt` via npm `binaryen` 132 | | prefer cargo + CLI, pinned, over wasm-pack | -| Typed boundary | `tsify` 0.5.8 (2026-08-23, active; `tsify-next` deprecated in its favour), `serde-wasm-bindgen` 0.6.5 (preferred over JSON glue; `json_compatible()` preset) | | generates `.d.ts` from serde structs, plain JS objects in and out | -| `.ts` generation outside the wasm package | `ts-rs` 12.0.1 (2026-01) | | `Option` → `T \| null`, `#[ts(optional)]` → `t?: T` | -| JSON Schema | `schemars` 1.2.2 (2026-07), 2020-12 default | | Zod 4 imports JSON Schema (experimental since 4.2); the repo runs Zod 3 | -| Randomness on wasm | `getrandom` ≥ 0.3.4 (`wasm_js` feature only) | | ids are injected anyway | -| Panic hook | `console_error_panic_hook` 0.1.7 (repo archived 2025-08) | | small, vendorable; `wee_alloc` archived, default allocator | -| Vite 7 | `--target web` output: `await init()` + `?url`, no plugin | | `vite-plugin-wasm` only for the `bundler` target | +| WASM glue | `wasm-bindgen` 0.2.129 (2026-09-25), `js-sys` / `web-sys` 0.3.106 | org `wasm-bindgen` (Cloudflare maintainers), monthly releases, MSRV 1.81 | since 0.2.128 the crate and the CLI must be the same version: the CI and Docker install lines read it from `Cargo.lock` | +| WASM build | `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen-cli`; `wasm-pack` 0.15.0 (one maintainer, 335 open issues) | | cargo + CLI, pinned; `wasm-opt` (npm `binaryen` 132) only when the size budget needs it | +| Types for TypeScript | `ts-rs` 12.0.1 (2026-01): `.ts` files written by `cargo test`; `Option` → `T \| null`, `#[ts(optional)]` → `t?: T` | active | types only; the payloads cross as JSON strings (III.3); `tsify` 0.5.8 and `serde-wasm-bindgen` 0.6.5 (no release in 2.5 years, writes absent optionals as `null` in its JSON preset) are not used | +| Vite 7 | `--target web` output: `await init()` + `?url`, no plugin | | `.wasm` served raw unless nginx gzips it (VIII.1) | PDF, SVG, XML, fonts: | Need | Crate | Version (date) | Status | Limits | |---|---|---|---|---| -| PDF writing | `pdf-writer` | 0.15.0 (2026-05-27) | typst org, 4 pure-Rust deps, no advisory | has `EmbeddedFile` + `EmbeddingParams`, `FileSpec::association_kind(Data)`, `Names::embedded_files`, `Catalog::associated_files`, Type1 fonts with `WinAnsiEncoding` + explicit widths, image XObjects with `SMask`, `Action::uri`, Info dates, classic xref table; **cannot write object streams at all** (BLK-009 option B by construction) | -| PDF writing, higher level | `krilla` 0.8.2 (2026-06) | one maintainer (typst-pdf backend) | page text is OpenType only (no Standard 14), merges CreationDate/ModDate: not suitable for the parity step; candidate for the TTF step | -| PDF reading | none needed (byte scan stays); `lopdf` 0.45 for tests only (HIGH advisory patched ≥ 0.42) | | | -| PDF verification in CI | `pdfium-render` 0.9.4 (C++ binaries), or poppler already used in Step 6 audits | | CI only | -| Standard 14 metrics | **no credible crate** (`pdf-core-14-font-afms` 0.1.1, `pdf-base14-metrics` 0.0.2, < 4k downloads) | | vendor the Adobe Core 14 AFM files (SPDX `APAFML`: redistribution allowed with `MustRead.html`, edits noted); `@pdf-lib/standard-fonts` bundles the same files (WX, N, KernPairs) so the numbers can be identical | -| TTF later | `subsetter` 0.2.6 (typst), `skrifa` 0.48 (googlefonts), `harfrust` 0.14 (harfbuzz); **`ttf-parser` and `rustybuzz` are RustSec-unmaintained (2026-0192 / -0206)** | | Inter and Fraunces are OFL | -| SVG raster | `resvg` / `usvg` 0.48.1 (2026-08-02), `tiny-skia` 0.12 | linebender org since 0.45 (2025-02), Apache/MIT | README claims pixel-identical output across platforms (not measured here); `@resvg/resvg-wasm` 2.6.2 measures 2.48 MB raw / 949 KB gzip; text support needs `fontdb` + embedded fonts (+400 KiB); only cap is a hard-coded 1,000,000 elements; `usvg` parses with `allow_dtd: true` | -| XML parse | `roxmltree` 0.21.1 (2025-10) | RazrFalcon, 27M/90d | read-only, refuses DTD by default (`DtdDetected`), `nodes_limit`, entity loop checks; **an unreleased fix (2026-09-22) for a stack overflow on deep nesting**: pin the next release or cap depth before parsing | -| XML write | hand-written serialiser for the allowlisted tree (recommended), or `quick-xml` 0.42 (two HIGH advisories patched ≥ 0.41) | | `xmlwriter` archived | -| PNG | `png` 0.18.1 (2026-02) | image-rs, no `unsafe`, OSS-fuzz, `Limits.bytes` default 64 MiB | encoder writes only IHDR/IDAT/IEND unless asked | -| Canonical JSON | `serde_jcs` 0.2 (RFC 8785) | | compact and key-sorted: not the pretty form the archive uses | +| PDF writing | `pdf-writer` | 0.15.0 (2026-05-27) | typst org, 4 pure-Rust deps, no advisory | `EmbeddedFile` + `EmbeddingParams`, `FileSpec::association_kind(Data)`, `Names::embedded_files`, `Catalog::associated_files`, Type1 fonts with `WinAnsiEncoding` + explicit widths, image XObjects with `SMask`, `Action::uri`, Info dates, classic xref table; **cannot write object streams at all** (BLK-009 option B by construction); coordinates are `f32` (the links golden keeps a read-back oracle, VI.2) | +| PDF writing, higher level | `krilla` 0.8.2 (2026-06) | one maintainer | page text is OpenType only (no Standard 14), merges CreationDate/ModDate: candidate for the TTF step, not for the parity step | +| PDF read-back in tests | `lopdf` 0.45 (HIGH advisory patched ≥ 0.42) | test-only | reads `/Annots` of the written file for the links golden | +| Standard 14 metrics | **no credible crate** | | vendor the Adobe Core 14 AFM files (SPDX `APAFML`: redistribution allowed with `MustRead.html`, edits noted); `@pdf-lib/standard-fonts` bundles the same files (WX, N, KernPairs) | +| TTF later | `subsetter` 0.2.6, `skrifa` 0.48, `harfrust` 0.14; **`ttf-parser` and `rustybuzz` are RustSec-unmaintained** | | Inter and Fraunces are OFL | +| SVG raster (native only) | `resvg` / `usvg` 0.48.1 (2026-08), `tiny-skia` 0.12 | linebender org since 0.45 | only cap is 1,000,000 elements, `allow_dtd: true`: our sanitiser runs first; the head-view crop needs the render-full-box-then-crop workaround (LRN-046); not shipped to the browser (949 KB gzip measured on resvg-wasm 2.6.2) | +| XML parse | `roxmltree` 0.21.1 (2025-10) | RazrFalcon, 27M/90d | read-only, refuses DTD by default, `nodes_limit`; **unreleased fix (2026-09-22) for a stack overflow on deep nesting**: depth capped by a byte pre-scan until the fixed release is pinned | +| XML write | hand-written serialiser for the allowlisted tree | | ~100 lines; `quick-xml` not needed | +| PNG | `png` 0.18.1 (2026-02) | image-rs, no `unsafe`, OSS-fuzz | encoder writes only IHDR/IDAT/IEND unless asked | Worker (image pipeline, sandbox, transport): | Need | Crate | Version (date) | Status | Limits | |---|---|---|---|---| -| Decode + resize + orientation | `image` 0.25.10 (2026-03-10), MSRV 1.88 | image-rs org | `orientation()`, `icc_profile()`, `exif_metadata()`, `set_limits` (max_alloc advisory 512 MiB), `apply_orientation`, `resize_to_fill`; JPEG = `zune-jpeg`, PNG = `png`, WebP = `image-webp`; no ICC application API | +| Decode + resize + orientation | `image` 0.25.10 (2026-03-10), MSRV 1.88 | image-rs org | `orientation()`, `icc_profile()`, `set_limits` (max_alloc advisory 512 MiB), `apply_orientation`, `resize_to_fill`, `guess_format`; JPEG = `zune-jpeg`, PNG = `png`, WebP = `image-webp`; no ICC application API; resolves `moxcms` ^0.8 (use that version, not 0.9) | | JPEG | `zune-jpeg` 0.5.15 | one very active maintainer | `unsafe` only in SIMD (togglable), default cap 16536×16535, CMYK ok, "panics are okay" policy → child process justified | | WebP decode | `image-webp` 0.2.4 (2025-08) | image-rs, `forbid(unsafe)` | lossy, lossless, alpha, animation, ICC/EXIF/XMP; memory limit has a documented TODO; **encoder is lossless only** | -| WebP lossy encode | `libwebp-sys` 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, `cc` build); `webp` 0.3.1 pins `libwebp-sys` 0.9.6 = libwebp 1.3.1 + the CVE-2023-4863 fix (frozen line) | C | no established pure-Rust lossy encoder (`oxideav-webp` 0.3.1 MIT created 2026-04, `zenwebp` AGPL) | -| ICC → sRGB | `moxcms` 0.9.1 (2026-09) pure Rust, required dep of `image`, one maintainer, SIMD `unsafe` on by default; `lcms2` 6.2 (C) | | no documented ICC input limits in `moxcms`: cap the profile size ourselves | -| Resize quality | `fast_image_resize` 6.1 (optional) | | `image::imageops` suffices for 512 px | -| Magic bytes | `infer` 0.22 (`forbid(unsafe)`) | | | -| Sandbox | `seccompiler` 0.5.0 (rust-vmm, sets `no_new_privs`), `landlock` 0.4.7 (ABI V1..V9, best-effort), `rlimit` 0.11 / `nix` 0.31 | | `extrasafe` dormant and needs `unshare`; `wasmtime` 49 works (fuel, epoch, `StoreLimits`) but carries ~2 advisories/month in 2026 | -| Runtime, HTTP | `tokio` 1.53, `reqwest` 0.13.5 (rustls default, multipart opt-in), `tracing` 0.1.44 | | | -| Supabase clients | `postgrest` 1.6.0 (2023-07), `supabase-rs` 0.8.0 (2026-10, PostgREST only, no auth) | weak | hand-written `reqwest` calls to PostgREST `/rpc/` and Storage `/storage/v1` are lower risk | -| Toolchain | `rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}`, `cargo-chef` 0.1.78, `cargo-deny` 0.20.2, `cargo-audit` 0.22.2, `distroless/static` (Debian 13, `nonroot`) | | musl static with the `cc`-built libwebp needs `musl-dev` on Alpine | +| WebP lossy encode | `libwebp-sys` 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, `cc` build) | C | no established pure-Rust lossy encoder (`oxideav-webp` 0.3.1 created 2026-04, `zenwebp` AGPL); `webp` 0.3.1 pins libwebp 1.3.1 + one fix (not used) | +| ICC → sRGB | `moxcms` (version resolved by `image`) pure Rust, one maintainer, SIMD `unsafe` on by default; `lcms2` 6.2 (C) alternative | | no documented ICC input limits: profile size capped by us (1 MiB) | +| Sandbox | `seccompiler` 0.5.0 (rust-vmm, sets `no_new_privs`, TSYNC available), `rlimit` 0.11 | | `landlock` not used (redundant under the allowlist); `extrasafe` dormant; `wasmtime` carries ~2 advisories/month in 2026 | +| Runtime, HTTP | `tokio` 1.53, `reqwest` 0.13.5 (rustls, `webpki-roots` compiled in), `tracing` 0.1.44 | | | +| Supabase clients | `postgrest` 1.6.0 (2023-07), `supabase-rs` 0.8.0 (PostgREST only) | weak | hand-written `reqwest` calls to PostgREST `/rpc/` and Storage `/storage/v1` (~10 endpoints) | +| Toolchain | `rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}`, `cargo-deny` 0.20.2, `distroless/static:nonroot` (Debian 13, CA bundle included) | | | Baseline for comparison, `sharp` 0.35.5 (2026-09-27): libvips 8.18.7, -libwebp 1.6.0, libpng 1.6.58, mozjpeg; by default strips metadata and -converts to sRGB, `limitInputPixels` 268 MP, WebP q80; EXIF orientation only -with `autoOrient`/`rotate()`. libvips had three High CVEs in July and August -2026 (TIFF and loaders), libpng twelve CVEs since late 2025. The Rust -pipeline's advantage is the loader surface (three formats, pure-Rust -decoders, hard caps), not the encoder (still libwebp). +libwebp 1.6.0, libpng 1.6.58, mozjpeg; strips metadata and converts to sRGB +by default, `limitInputPixels` 268 MP, WebP q80; EXIF orientation only with +`autoOrient`/`rotate()`. libvips had three High CVEs in July and August 2026, +libpng twelve CVEs since late 2025. The Rust pipeline's advantage is the +loader surface (three formats, pure-Rust decoders, hard caps), not the +encoder (still libwebp, confined to the child process). -Supabase platform facts that shape the worker and the contracts: +Supabase platform facts: -- A dedicated Postgres role is honoured by PostgREST (`SET LOCAL ROLE`, needs - `GRANT TO authenticator`) and by storage-api (official custom-roles - guide: grant to `authenticator`, grant `anon` to the role, RLS on - `storage.objects` `to `, mint a JWT with `role` and `sub`). -- Minting such a JWT needs the legacy HS256 `JWT_SECRET` (self-hosted: still - in `JWT_KEYS` / `JWT_JWKS`; managed: "available for backward - compatibility", extractable, not deletable) or an imported ES256 standby key - (`supabase gen signing-key`). New managed projects default to asymmetric - keys since 2025-10-01. -- `pg_jsonschema` 0.3.3 ships in the `supabase/postgres` image and on - managed; it is **not** in the PGlite extension list, so a JSON Schema CHECK - would not run under the Dockerless pgTAP harness. Custom `pgrx` extensions - have no documented path on managed. -- Edge Functions on managed: 2 s CPU, 256 MB, 150 s wall clock (free), - Deno/TypeScript only. Self-hosted: `edge-runtime` container, hand-deployed. - Not a home for Rust code; the rule retires them from the plan (Part VII). +- Edge Functions (managed: 2 s CPU, 256 MB, 150 s wall clock; self-hosted: + `edge-runtime` container, hand-deployed) run Deno, which can execute a + wasm build of the core; the rule retires them from the plan for those + limits, the hand deployment and the preference for one Rust runtime + (D-R9). The language alone would allow them. +- A dedicated Postgres role is honoured by PostgREST and storage-api + (official custom-roles guide), with a JWT minted from the legacy HS256 + `JWT_SECRET` or an imported ES256 standby key; on managed the imported + key must become a signing key of the project. Recorded as a hardening + option (IV.4), not adopted. +- `pg_jsonschema` 0.3.3 exists on managed and in the `supabase/postgres` + image but not in PGlite; custom `pgrx` extensions have no documented path + on managed. --- ## Part II. Classification of every module -### II.1 Criteria applied +### II.1 Criteria Business logic = anything that interprets or transforms the sheet, report or archive data, encodes a product rule (what a click does, how a finding is built, how a report migrates), parses untrusted bytes, or runs as a job or a -service. Glue = React rendering, routing, DOM access, store subscription, -vendor SDK calls, build tooling. The owner's brief keeps glue in TypeScript; -everything else is Rust unless a concrete loss is named. "Loss" is measured -on the brief's list: features, UX, graphics, data compatibility, security, -reliability, useful performance, resources, portability, maintainability, -deployment. Absence of a performance gain is never a reason for C. +service. Glue = React rendering and display formatting, routing, DOM +access, store subscription, vendor SDK calls, build tooling. The owner's +brief keeps glue in TypeScript; everything else is Rust unless a concrete +loss is named on the brief's list (features, UX, graphics, data +compatibility, security, reliability, useful performance, resources, +portability, maintainability, deployment). Absence of a performance gain is +never a reason for C. -Classes: **A** = Rust now (clean migration possible, no functional step -needed first); **B** = Rust later, with a named trigger or dependency; **C** -= exception with its concrete constraint. +Classes: **A** = Rust, scheduled on technical dependencies only; **B** = +Rust, waiting for a named external trigger; **C** = exception with its +concrete constraint. ### II.2 Module table -The ten points of the brief (role, technology, feasibility, crates, WASM, -frontend consequences, compatibility risk, tests, recommendation, timing) -are given per row; the parity tests are detailed in Part VI. - -| Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Parity tests needed | Class | When | +| Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Oracle for the switch | Class | Phase | |---|---|---|---|---|---|---|---|---|---| -| `packages/domain` sheet document schema + `validateSheetDocument` (21 rules) + `createEmptySheetDocument` | shape and integrity of the canonical sheet | Zod | full: serde structs (strict = `deny_unknown_fields`, defaults via `#[serde(default)]`), hand-written rules returning `SheetIssue {code, severity, path, message}` | yes (app load, publish gate) + native (worker, tools) | app and publish gate call `parse_sheet_document` / `validate_sheet_document`; TS types generated by tsify | low: codes and paths are pinned by the validate tests; strict/strip policy per schema must be reproduced | validate suite (exact code + path lists), fixture `horse-slice`, the draft document (0 issues), conformance fixtures shared with pgTAP | **A** (first core crate) | R2 | -| `packages/domain` report v3 + v2 input + `migrateReportV2ToV3` + `readReportDocument` | report contract and migration | Zod | full; migration map as data; "never throws on content" made true (today a malformed map entry can throw a raw `ZodError`) | yes + native | store hydrates only through the Rust parser (closes the no-parse path) | medium: strip semantics (unknown keys dropped), `requiresVetReferral: false` disappearing in v3 (keep as is, pinned), `unresolved` flags | 612-leaf migration (anatomy + app + PDF roundtrip), golden v2 fixtures, `report-migration-map.json` | **A** | R2 | -| `packages/domain` `rebaseReportOnSheet` | rebase on another sheet | TS over the closure index | full; takes the sheet source and builds its own index | yes | called from store restore and import | gated by CLAUDE.md ("ask before changing"): behaviour preserved exactly, rebase tests are exact-object oracles | rebase suite | **A** (with the owner's explicit go for the gated function) | R2 | -| `packages/domain` archive: `buildSheetSnapshot`, `assertSnapshot` (caps, integrity, sheet invariant), envelope v1 `readArchiveDocument` (layered), branding + labels schemas | archive contract | Zod | full; caps count UTF-16 units for strings and UTF-8 bytes for assets (reproduce both); closed `snapshotRejected` reasons | yes + native | app import path and engine use it | medium: snapshot key order (Zod schema order) must be kept if attachment bytes are to stay stable (D-R11); `origin` quirk for unknown envelope versions preserved | envelope decision-table suite, branding/labels suite, size test (< 250 KB stored), re-export test | **A** | R2 | -| `packages/domain` `buildSheetIndex` | lookups by id | closures over Maps | different shape: Rust returns a plain-data index (views, annotations, finding zones, regions by id; main view; annotations per view; spine annotation per region+view) built once; `nodeAt` and `name` as small functions over that data | yes | ~14 app modules read object properties instead of calling closures; `ObservationCard` per-render lookups become property reads (cheaper) | low: lookup semantics pinned by the service and component tests; duplicate-id policy (index last-wins vs validate first-wins) made explicit | sheet-index tests + component suites unchanged in intent | **A** | R2 | -| `apps/app/src/services/zoneInteraction.ts` (7 decision kinds, 11 reducers) | click decision and observation reducers | pure TS | full; `(observation, annotation, …) → observation` with the index data | yes | `EditorRoute.onZoneClick` and `ObservationPickers` call the core per click (≤ 1 ms serialisation on a few-KB observation) | low | the 13-case service suite as a black-box table, route click-chain characterisation | **A** | R2 | -| Business rules in UI files: `toggleLeaf` (Finding builder), `zoneLabel` / `zoneTrees` / `unresolvedFindings`, `VertebraPicker` rules, `isIdentityComplete` ×2, `isDegradedImport` / message line builders | product rules inside components | TSX | full; become core functions (`build_finding`, `describe_zone`, `zone_trees`, `vertebra_selection`, `identity_complete`, `import_outcome_lines`) | yes | components keep rendering; the rule moves out (also removes the duplicates) | low | component suites keep their assertions; new unit tables | **A** | R2 (same phase, same data model) | -| `apps/app/src/state/reportStore.ts` actions (`initReport`, `addObservation`, `moveObservationUp/Down`, setters) | Report construction and edits | Zustand | the rules move to the core (`new_report(draft, sheet, id, created_at)`, `swap`), the store stays Zustand (React glue); ids and timestamps injected from TS | yes | store actions become one-line delegations | low | store suite | **A** (logic) / C (Zustand subscription, sessionStorage adapters: DOM glue) | R2 | -| `apps/app/src/state/persistence.ts`, `practitionerCache.ts`, `localeStore.ts`, `authStore.ts`, `localeSync.ts` | storage adapters, GoTrue event glue | TS | adapters are DOM/vendor glue; the only rules (`isLocale`, "account locale wins once per sign-in") are trivial and tied to supabase-js events | no | none | none | existing suites | **C**: browser storage and supabase-js session glue; no Rust GoTrue client with PKCE and refresh exists | n/a | -| `packages/anatomy/src/render` (layer renderer, `composeViewSvg`, highlight, `viewBoxOf`) | markers from the document; view composition with highlight | pure tree + DOM mutation | full: `render_annotation_layer(document, view, states) → LayerElement` (plain JSON, same contract) and `compose_view_svg(asset_svg, document, view, highlight) → String` on the Rust XML tree | yes (app canvas, browser export) + native (worker, tools) | app receives either the layer tree (DOM materialisation stays TS) or the composed SVG string; the app canvas and the PDF stop composing differently | low on the layer (attribute strings pinned by the step6 view goldens and `render.compose` byte goldens); the composed SVG serialisation needs a committed oracle (xmldom's output today) | `render.compose.test.ts` (app-main / app-head byte goldens), step6 `views.*.json`, security SVG cases | **A** | R3 | -| `packages/pdf/src/svg/{parse,sanitize,view}` (allowlist sanitiser, caps, view crop) + `apps/app/src/anatomy/drawing.ts` denylist | untrusted SVG → safe tree | xmldom / DOMParser | full: `roxmltree` parse with DTD refused and a pre-parse depth/size cap, own allowlisted tree, own serialiser; one sanitiser for the canvas, the PDF, the Step 13 upload processor and the Step 6 branding SVG | yes + native | `drawing.ts` parses a sanitised string with `DOMParser` and keeps `importNode` + click delegation (DOM glue stays) | medium: "zero-removal" oracle changes (commit the canonical serialisation of `horse.svg`); attribute order and escaping differences vs xmldom show in view goldens | 7 hostile cases + zero-removal + caps, new committed oracle, app canvas suite | **A** | R3 | -| `packages/anatomy` curation pipeline (changeset Zod, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) | changeset → draft artifacts | TS + xmldom + Prettier + `node:fs` | logic fully portable; **byte identity of 18 generated files is the golden**: Prettier formatting (JSON and markdown tables), JS number strings, `document_sha256` over the Prettier text; a Rust pipeline keeps a Prettier formatting step as its last stage (Node, dev-time) or the identity rule changes under a schema migration (D-R5) | native (tools) | none (operator tool) | high on bytes, nil on semantics | `seed.golden.test.ts` (byte-exact, 18 files), determinism tests, counts tests, 612-leaf test | **B**: after R2 (needs the domain crate) and at the next content changeset; Prettier step retained (dev tool, D-R5) | R5 | -| `packages/anatomy` legacy importer (Horse.svg + Horse_head.svg + pathologies.json → baseline) | one-off import re-run at every regeneration | TS + xmldom | full (sha-derived uuid "v5-like", strict label equality, region inference) | native | none | same byte constraint as the pipeline (legacy-import files are goldens) | legacy suites (27 annotations, 792 nodes, 612 leaves, 41 vet, anomalies) | **B** with the pipeline; if the equine sheet is published and the importer retired, delete instead of migrate (decision at R5) | R5 | -| `packages/pdf` engine: layout + pages + footer + links + attachment + metadata (export), `exportFromEnvelope` | A4 archive writer | pdf-lib | full with `pdf-writer` (every primitive verified, no object streams by construction); layout split from serialisation so the draw-call log is golden-comparable; AFM data vendored (APAFML); fr/en month tables; `png` crate decodes the archived logos under the existing gate | yes (browser export) + native (Step 15 server rendering, tools) | the app calls `export_report_archive` in the wasm; rasteriser stays an injected adapter (browser canvas first) | medium: goldens reproduce drawn primitives exactly only if widths (kerning included), rounding (`Math.round` half-up) and date strings match; `drawLine`/`drawRectangle`, colours and z-order are not golden-covered (add a draw-log golden before porting); attachment Flate bytes differ (never pinned) | 39 goldens through a Rust draw-log recorder, re-export test, size test, roundtrip suites, poppler/pdfium render diff in CI | **B**: trigger = Step 15 (server-side rendering/import) or the TTF font change, whichever first; sequencing in Part VI | R4 | -| `packages/pdf` reader: `attachment/scan.ts` byte scan, bounded inflate, JSON depth pre-scan, stamp detection, `readReportArchive` layering | untrusted PDF → archive outcome | TS + `DecompressionStream` | full and simpler: `miniz_oxide` bounded streaming inflate replaces the slice-fed `DecompressionStream`; same candidate ordering and budgets | yes + native (Step 15 server import, CLI) | app import calls the wasm | low: scan suite (39 cases) is a byte-level oracle; the PNG `idat` gate semantics (exact raw size) reproduced | scan + inflate + read suites, bombs regenerated in Rust tests | **A** (independent of the writer; security value on the Step 15 server path) | R4a | -| `packages/pdf` branding PNG gate, `safeText`, `wrapLines`, labels (25 keys) | text safety, caps | TS | full (WinAnsi table from the AFM/encoding data) | with the engine | | low | text suite, security PNG cases (28) | **B** with the engine | R4 | -| `apps/app/src/pdf/browserRasterizer.ts` | SVG → PNG via `Image` + canvas | DOM | the adapter is DOM glue; the alternative `resvg` in a lazy-loaded second wasm module (949 KB gzip measured) gives deterministic, DOM-free rasterisation (what the tests already use) at the cost of bundle size and a visual change (anti-aliasing) | optional | lazy load on first export only | visual: pixels differ from the canvas rendering; no raster golden exists | raster facts test, user visual check | **C** today (DOM adapter), **B** option D-R3 once the engine is Rust | R4 / decision | -| `apps/app/src/pdf/export.ts`, `import.ts`, `branding.ts` | wiring: bundled logos, outcomes → UI kinds | TS | wiring stays; `branding.ts` is Vite asset glue (`?inline` / `?raw`) | no | thin | none | existing suites | **C**: Vite asset imports and DOM download are build/DOM glue | n/a | -| `apps/app/scripts/compare-reports.ts` + `compare/report.ts` | archive check CLI | tsx + Node | full: `faunosteo-tools report-compare` on the Rust reader and domain (escaping rules LRN-044 ported) | native | none | low | 11 CLI cases | **B**: with R4a (reader) | R4a | -| `packages/supabase` `classifyAuthError` (23 codes → 13 kinds), publish gate | closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue (23 string literals) | partial | gate delegates | none | existing suites | gate **A** (R2); code map **C** (supabase-js error shapes) | R2 | -| `packages/supabase` client factory, profile/auth wrappers, `database.types.ts`, PGlite harness | vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser (PKCE, refresh, `onAuthStateChange`); PGlite is a JS/WASM library | no | none | none | | **C**: vendor SDK and test infrastructure | n/a | -| `apps/app/src/auth/validation.ts`, `account/validation.ts` (Zod, i18n keys) | form field rules | Zod | portable, but React-bound by the owner's retained list; the constraints themselves (lengths, E.164, SIRET 14 digits, password policy) are duplicated in SQL CHECKs and `config.toml` and already drift (trim, UTF-16 vs `char_length`, `''` accepted on names) | no | | | the existing 8 cases + a constants parity test | **C**: UI form schemas; action: one constants file generated from the SQL CHECKs (or a Rust `constants` export) so the rule has one home | R2 follow-up | -| `apps/app/src/lib/{dates,id}.ts` | `nowIso`, `todayIso`, `formatDate` (UI), `generateId` | Web APIs | id and clock stay in TS and are injected into the core; UI date display stays `Intl` (screen only, not archived) | no | | | | **C** (platform clock, crypto, Intl for screen) | n/a | -| `apps/app/src/i18n/*` (281 keys ×2, `useT`) | UI strings | TS | data + React hook; `pickLabel` bilingual fallback moves to the core with the labels it serves | no | | | parity test | **C**: UI dictionaries; the engine's 25 archived labels move with the engine | n/a | -| `apps/app/src/config/env.ts`, `lib/supabase.ts`, providers, guards, routes, components, styles | runtime config, React | TS | glue | no | | | | **C**: React, DOM, window, router | n/a | -| `apps/app/vite/sheet-bundle.ts`, ESLint, Vite, vitest configs | build tooling | Node | Vite plugin API is JavaScript | no | | | | **C**: build tooling | n/a | -| `supabase/migrations`, pgTAP, `private.sheet_document_issues` | database | SQL | SQL by the retained list; the TS/SQL rule pair becomes Rust/SQL with one conformance fixture set | no | | | shared fixtures | **C** (retained) | n/a | +| domain: sheet document schema, `validateSheetDocument` (21 rules), `createEmptySheetDocument` | shape and integrity of the sheet | Zod | serde structs (strict = `deny_unknown_fields`, defaults), hand-written rules returning `SheetIssue {code, severity, path, message}` | yes + native | app load and publish gate call the core; types from `ts-rs` | low: codes and paths pinned by the validate suite; strict/strip policy per schema reproduced | validate suite (exact code + path lists), `horse-slice` fixture (converted to JSON), the draft document (0 issues) | **A** | R2 | +| domain: report v3, v2 input, `migrateReportV2ToV3`, `readReportDocument` | report contract and migration | Zod | full; "never throws on content" made true (today a malformed map entry can throw a raw `ZodError`) | yes + native | store hydrates only through the core | medium: strip semantics, `requiresVetReferral: false` dropped in v3 (kept, pinned), optional vs nullable fields | 612-leaf migration suites, golden v2 fixtures, migration map | **A** | R2 | +| domain: `rebaseReportOnSheet` | rebase on another sheet | TS over the index | full; takes the sheet handle | yes | store restore and import | CLAUDE.md gate: behaviour preserved exactly | rebase suite (exact objects) | **A** (owner go, D-R12) | R2 | +| domain archive: `buildSheetSnapshot`, `assertSnapshot`, envelope v1 layered read, branding + labels schemas | archive contract | Zod | full; UTF-16 string caps and UTF-8 asset caps reproduced; closed `snapshotRejected` reasons | yes + native | app import and export | medium: attachment bytes change once (D-R11); `origin` quirk for unknown envelope versions preserved | envelope decision table, branding/labels suite, size test, three envelopes frozen as goldens | **A** | R2 | +| domain: `buildSheetIndex` | lookups by id | closures over Maps | different shape: a Rust-owned `SheetHandle` (built once per session) for the core calls, plus `SheetIndexData` exported once for React (views, annotations, finding zones, regions by id; annotations per view; spine per region and view; precomputed `name` per annotation in both languages; `node_by_path`) | yes | ~14 modules read properties instead of calling closures; no wasm call in a render | low; one duplicate-id policy (document order, first wins) | service and component suites | **A** | R2 | +| `apps/app/src/services/zoneInteraction.ts` | click decision, observation reducers | pure TS | full; `apply_click(handle, observation, annotation_id, view_id)`, `sync_vertebrae(handle, …)` | yes | `EditorRoute.onZoneClick` and `ObservationPickers` call the core per click with the observation only (the sheet stays in the handle) | low | 13-case service suite, route click-chain characterisation | **A** | R2 | +| data-building rules in components: `toggleLeaf` (Finding builder), `VertebraPicker` selection | product rules inside components | TSX | `build_finding`, `vertebra_selection` in the core | yes | components call the core on the user action | low | component suites keep their assertions | **A** | R2 | +| display helpers in components and routes: `zoneLabel`, `zoneTrees`, `unresolvedFindings`, `describeZone`, import message lines, `isIdentityComplete`, `pickLabel` in JSX | formatting of core data for the screen | TSX | portable, but run inside renders and `useMemo` with `t()`; moving them means wasm calls in the render path or a view-model layer | no | none; they read `SheetIndexData` | none | existing suites | **C**: React render glue over precomputed data (the sheet names and `node_by_path` they need come from the core) | n/a | +| `reportStore.ts` actions | report construction and edits | Zustand | rules in the core (`new_report(draft, sheet, id, created_at)`, `swap`, `set_*` validation); the store stays Zustand | yes | one-line delegations | low | store suite | **A** (rules) / C (Zustand, adapters) | R2 | +| `persistence.ts`, `practitionerCache.ts`, `localeStore.ts`, `authStore.ts`, `localeSync.ts` | storage adapters, GoTrue event glue | TS | glue; the only rules (`isLocale`, "account locale wins once per sign-in") are tied to supabase-js events | no | none | none | existing suites | **C**: browser storage and supabase-js session glue (no Rust GoTrue client with PKCE and refresh) | n/a | +| anatomy render: layer renderer, `composeViewSvg`, highlight, `viewBoxOf` | markers from the document; composition with highlight | pure tree + DOM mutation | `render_annotation_layer(document, view, states) → LayerElement` (same plain contract) and `compose_view_svg(asset, document, view, highlight) → String` | yes + native | app canvas and engine use one composition; `drawing.ts` parses a sanitised string with `DOMParser` and keeps `importNode` + click delegation | low on the layer (step6 view facts); the composed string is compared as parsed trees, not bytes | step6 `views.*.json`, DOM-equivalence of the composed views for the three reports (frozen with the TS code), security SVG cases | **A** | R3 | +| pdf `svg/{parse,sanitize,view}` + app `drawing.ts` denylist | untrusted SVG → safe tree | xmldom / DOMParser | `roxmltree` with DTD refused and a byte pre-scan for depth and size, own allowlisted tree, own serialiser; one sanitiser for canvas, PDF, Step 13 uploads and branding SVG | yes + native | denylist deleted | medium: the "zero-removal" oracle becomes a DOM-equivalence test on `horse.svg` | 7 hostile cases, caps, zero-removal (tree compare) | **A** | R3 | +| pdf reader: byte scan, bounded inflate, JSON depth pre-scan, stamp, layered read; PNG gate inflater | untrusted PDF → archive outcome | TS + `DecompressionStream` | `miniz_oxide` streaming inflate with cancel; same candidate ordering and budgets; the leniency decisions of I.2 pinned | yes (in a Web Worker) + native (Step 15 server validation, CLI) | app import runs the core in a dedicated Web Worker terminated after each import | low: scan (39), inflate (9), read (13) suites are byte-level oracles | the same suites in cargo on the fixtures in place; BLK-009 browser measurements | **A** | R4 | +| pdf writer: layout, pages, footer, links, attachment, metadata, `exportFromEnvelope`, branding PNG gate, `safeText`, `wrapLines`, labels (25 keys) | A4 archive writer | pdf-lib | `pdf-writer`; layout split from serialisation (draw log = the golden format); AFM vendored; `png` decodes the archived logos under the existing gate; fr/en month tables | yes + native | two synchronous calls: `compose_export_views(report, snapshot, branding) → [{key, svg, size}]`, the caller rasterises (canvas in the browser, resvg natively), then `write_archive(input, pngs) → {pdf, warnings}`; no rasteriser callback crosses the boundary | medium: widths with kerning, `Math.round` half-up, dates, upper-casing; lines, rectangles and colours are not golden-covered today (D-R2 adds that golden with the TS engine first) | 39 goldens through the Rust draw log, links read back from the written file with `lopdf`, re-export test, size test, poppler/pdfium render diff | **A** (after R3 and the reader; same phase as the reader) | R4 | +| `apps/app/src/pdf/browserRasterizer.ts` | SVG → PNG via `Image` + canvas | DOM | DOM adapter between the two core calls; a native rasteriser (`resvg`) serves the worker and tools if a server-side rendering need appears | no | unchanged | none | raster facts test | **C**: browser rasterisation is DOM; no resvg in the browser bundle (D-R3) | n/a | +| `apps/app/src/pdf/export.ts`, `import.ts`, `branding.ts` | wiring, Vite asset imports, download | TS | glue | no | thin | none | existing suites | **C**: Vite asset imports, Web Worker and DOM download | n/a | +| `apps/app/scripts/compare-reports.ts` + `compare/report.ts` | archive check CLI | tsx + Node | `faunosteo-tools report-compare` on the core (LRN-044 escaping ported) | native | none | low | 11 CLI cases | **A** | R4 | +| anatomy curation pipeline (changeset, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) + legacy importer | changeset → draft artifacts; baseline import re-run at every regeneration | TS + xmldom + Prettier + `node:fs` | full (sha-derived "v5-like" uuid, strict label equality, region inference, ops); outputs emitted by Rust with `js_number`; markdown tables written by Rust; Prettier no longer touches generated files (`.prettierignore`) | native (tools) | none | the 18 generated files and `documentSha256` change once (D-R5); counts, determinism and the 612-leaf semantics are the oracles | `seed.golden.test` (regenerated once, decided), determinism and count suites, 612-leaf test, review drawings compared as parsed trees against the xmldom-era files | **A** (after R2, R3) | R5 | +| `packages/supabase/scripts/upload-sheet-assets.ts` | operator upload of sheet SVGs (service key) | tsx + Node | `faunosteo-tools upload-sheet-assets` (reqwest) | native | none | none | manual operator check (SUPABASE.md §3.1) | **A** | R5 | +| `packages/supabase` `classifyAuthError`, publish gate | closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue | partial | gate delegates | none | existing suites | gate **A** (R2); code map **C** (supabase-js error shapes) | R2 | +| `packages/supabase` client factory, auth/profile wrappers, `database.types.ts`, PGlite harness | vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser; PGlite is a JS/WASM library | no | none | none | | **C** | n/a | +| `auth/validation.ts`, `account/validation.ts` (Zod, i18n keys) | form field rules | Zod | portable but React-bound (retained list); the constraints are duplicated in SQL CHECKs and `config.toml` and drift (trim, UTF-16 vs `char_length`, `''` on names) | no | | | one constants module + a PGlite test reading `pg_constraint` and `config.toml` with the counting rule recorded (separate chore, D-R7) | **C** | chore | +| `lib/{dates,id}.ts` | `nowIso`, `todayIso`, `formatDate` (screen), `generateId` | Web APIs | clock and ids injected into the core; screen dates stay `Intl` | no | | | | **C** | n/a | +| `i18n/*` (281 keys ×2, `useT`, `pickLocaleLabel`) | UI strings | TS | UI data and hook; the engine's 25 archived labels move with the engine | no | | | parity test | **C** | n/a | +| `config/env.ts`, `lib/supabase.ts`, providers, guards, routes, components, styles | runtime config, React | TS | glue | no | | | | **C** | n/a | +| `vite/sheet-bundle.ts`, ESLint, Vite, vitest configs | build tooling | Node | Vite plugin API is JavaScript | no | | | | **C** | n/a | +| `supabase/migrations`, pgTAP, `private.sheet_document_issues` | database | SQL | retained; the TS/SQL rule pair becomes Rust/SQL with conformance fixtures (two expectation sets) | no | | | fixtures inlined into a generated pgTAP file with a drift test (the PGlite harness has no file access) | **C** (retained) | n/a | | Step 8 worker (planned Node + sharp) | file processing | not built | native Rust (Part IV) | native | none | none (new) | Part IV tests | **A** | R1 (Step 8) | -| Step 13 SVG upload processor, Step 15 server-side import and PDF rendering, Step 19 notifications and job queue, Step 21 travel engine and calendar sync, Step 23 Stripe webhook, Step 24 import adapters, Step 26 export/archive jobs | future backend | not built | Rust in the same worker binary (jobs) or a sibling HTTP service (webhooks, OAuth callbacks) sharing the core crates | native | none | none | per step | **A** at design time (rule applies from design) | their steps | -| Step 17 sheet editor document operations (undo, geometry: bbox + margin → `view_box`, polygon edits, mapping validation), Step 20 agenda rule mirrors (expiry 48/24/1 h) | future app logic | not built | core crate functions through WASM; UI in React | yes | editor store holds plain documents, calls the core | none | per step | **A** at design time | their steps | -| Step 22 public web | marketing site, public profiles, SEO | not built | Rust static generators exist (Zola) but the global rule mandates Astro for indexed sites (SEO/GEO, islands); public RPC reads are SQL | n/a | | | | **C** proposed, decision D-R8 | Step 22 | +| Step 13 SVG upload processor; Step 15 server-side archive validation; Step 19 notifications and job queue; Step 21 travel engine and calendar sync; Step 23 Stripe webhook; Step 24 import adapters; Step 26 export/archive jobs | future backend | not built | the worker binary (jobs) and its `serve` subcommand (inbound HTTP) sharing the core crate | native | none | none | per step | **A** at design time | their steps | +| Step 17 editor document operations (undo, geometry: bbox + margin → `view_box`, polygon edits, mapping validation); Step 20 agenda rule mirrors (48/24/1 h) | future app logic | not built | core functions through the wasm; UI in React | yes | editor store holds plain documents, calls the core on actions | none | per step | **A** at design time | their steps | +| Step 22 public web | marketing site, public profiles, SEO | not built | Rust static generators exist (Zola); the global rule mandates Astro for indexed sites (islands, SEO/GEO tooling) | n/a | | | | **C** proposed, D-R8 | Step 22 | ### II.3 Summary by class -- **A (Rust now)**: the domain contracts (sheet, report, migration, rebase, - archive), the sheet index as data, the interaction reducers and the rules - stranded in components, the publish gate, the layer renderer and view - composition, the SVG sanitiser, the PDF reader and the CLI, the Step 8 - worker, and every future backend or rule-mirror listed above. -- **B (Rust later, trigger named)**: the PDF writer (trigger: Step 15 or - the TTF fonts; after R2 and R3 in any case), the curation pipeline and the - legacy importer (after R2, at the next content changeset, Prettier step - kept or identity rule changed), the resvg rasteriser (after R4, visual - decision). -- **C (exceptions, each with its constraint)**: React/DOM/router glue, +- **A**: domain contracts and rules, the sheet handle and index data, + reducers and data-building rules, publish gate, layer renderer and view + composition, the one sanitiser, the PDF reader and writer, the CLI tools, + the curation pipeline and importer, the asset upload script, the Step 8 + worker, every future backend job, service or rule mirror. +- **B**: none left after the challenges; every migratable component is + scheduled on technical dependencies (VI.2). +- **C** (each with its constraint): React render glue and display helpers, Zustand subscriptions and browser storage adapters, supabase-js session - and error shapes (no Rust GoTrue client for PKCE in the browser), UI form - schemas (React-bound; single source of constraints to add), UI - dictionaries, platform clock/crypto/Intl for screen display, Vite and - ESLint tooling, SQL and RLS, the public web framework (decision D-R8). + and error shapes, UI form schemas and dictionaries, platform clock/crypto + and screen date formatting, the browser rasteriser (DOM), Vite asset + wiring and tooling, SQL and RLS, the public web framework (D-R8). --- ## Part III. Target Rust architecture -### III.1 Cargo workspace +### III.1 Cargo workspace (three crates) ```text faunosteo/ -├─ Cargo.toml workspace: members crates/*, shared [workspace.dependencies], -│ lints (clippy pedantic subset, unwrap_used = deny in libs) -├─ rust-toolchain.toml channel pinned (1.99.0 at adoption), targets wasm32-unknown-unknown -├─ deny.toml cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0 for -│ tiny-skia deps, APAFML for the AFM data), advisories, bans +├─ Cargo.toml workspace: members crates/*, [workspace.dependencies], lints +│ (unwrap_used / expect_used = deny in the library, +│ disallowed_methods for std::time, std::fs, rand in core) +├─ rust-toolchain.toml channel pinned (1.99.0 at adoption), target wasm32-unknown-unknown +├─ deny.toml cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0, +│ APAFML for the AFM data), bans (duplicate versions), sources ├─ crates/ -│ ├─ domain/ faunosteo-domain: sheet document, integrity rules, report v3 + v2 -│ │ migration, rebase, sheet index data, archive (snapshot, envelope, -│ │ branding, labels), interaction reducers, observation rules. -│ │ serde + thiserror only. No I/O, no clock, no ids (injected). -│ ├─ anatomy/ faunosteo-anatomy: XML tree + allowlist sanitiser + serialiser, -│ │ layer renderer, view composition; feature `curation` (pipeline, -│ │ legacy importer, later). roxmltree, sha2, serde. -│ ├─ pdf/ faunosteo-pdf: reader (byte scan, bounded inflate, layered read) -│ │ first; later writer (layout → draw log → pdf-writer), AFM tables, -│ │ PNG gate, labels. miniz_oxide, png, pdf-writer. -│ ├─ wasm/ faunosteo-wasm: the single wasm-bindgen facade over the three -│ │ crates (tsify types, closed error kinds), published to -│ │ packages/core-wasm by the build. Optional second module -│ │ `wasm-raster` (resvg) only if D-R3 is accepted. -│ ├─ worker/ faunosteo-worker (bin): job loop, Storage/PostgREST transport, -│ │ sweeper, `decode` subcommand = the sandboxed child. Step 15 adds -│ │ the pdf feature; Step 19 adds mail and jobs. -│ └─ tools/ faunosteo-tools (bin): report-compare, later import-equine and -│ the curation pipeline, asset upload (operator CLI). -└─ packages/core-wasm/ generated: faunosteo_wasm.js, .d.ts, .wasm (build artifact, - git-ignored; CI and Docker build it) +│ ├─ core/ faunosteo-core (lib). Modules: domain (sheet, report, archive, +│ │ index, reducers, rules), anatomy (xml tree, sanitiser, +│ │ serialiser, layer, compose), pdf (reader, writer, afm, png gate, +│ │ labels), curation (pipeline, importer). Features: `xml`, +│ │ `pdf-read`, `pdf-write`, `curation`, `cli`. No I/O, no clock, +│ │ no ids in any module (lint-enforced). [[bin]] targets behind +│ │ `cli`: report-compare, import-equine, upload-sheet-assets. +│ ├─ wasm/ faunosteo-wasm (cdylib): the wasm-bindgen facade over core +│ │ (features xml + pdf-read + pdf-write), JSON strings in and out, +│ │ closed error kinds, `ts-rs` types emitted into +│ │ packages/core-wasm/types. +│ └─ worker/ faunosteo-worker (bin): `run` (job loop, transport, sweeper, +│ watchdog), `decode` (the sandboxed child), later `serve` +│ (inbound HTTP). Depends on core without the pdf features +│ until Step 15. +└─ packages/core-wasm/ committed package.json (exports → pkg/) and generated types; + pkg/ (js, wasm, d.ts) is git-ignored and built by + `pnpm wasm:build` ``` -Six crates, one per dependency or deployment boundary, none per module: the -domain crate pulls no XML or PDF code, the worker does not compile the PDF -writer before Step 15, the wasm facade is the only place that knows -JavaScript. A single `faunosteo-core` crate with feature flags was weighed -and rejected: it would compile `pdf-writer` and `roxmltree` into the worker -image from day one and blur the "domain has no I/O" rule that makes the -core testable (D-R1 for the owner). +Why three: one library keeps every rule in one dependency graph and one test +run; features keep `pdf-writer` and `roxmltree` out of the worker build +until it needs them (`cargo build -p faunosteo-worker` compiles only the +features it enables); the facade and the binary are the two deployment +boundaries. A `crates/editor` for Step 17 is not planned; editor operations +are a module of core (D-R1). ### III.2 Native and WASM: who runs what -| Crate | Native (worker, tools, tests) | WASM (browser) | +| Code | Native | WASM | |---|---|---| -| domain | worker (Step 15 import validation), tools, cargo tests, parity harness | app: parse/validate/migrate/rebase/snapshot/envelope, reducers, rules | -| anatomy | worker (Step 13 upload sanitiser, Step 15 rendering), tools (pipeline) | app: sanitise + compose views for the canvas and the export | -| pdf | worker (Step 15), tools (report-compare) | app: import (reader) now, export (writer) at R4 | +| core domain | worker (Step 15 validation), tools, cargo tests | app: parse, validate, index, reducers, rules, snapshot, envelope | +| core anatomy | worker (Step 13 uploads), tools (pipeline) | app: sanitise, compose views for the canvas and the export | +| core pdf | worker (Step 15), tools (report-compare) | app: reader (in a Web Worker), writer | +| core curation | tools only | never | | worker | container `faunosteo_worker` | never | -| tools | developer and operator machines, CI | never | -The same crate code runs in both worlds; only the facade and the binaries -differ. Platform access (clock, ids, storage, network, DOM, rasterisation) is -injected: the core never calls `std::time`, `rand`, `fs` or `fetch`. +Platform access (clock, ids, storage, network, DOM, rasterisation) is +injected; the core never calls `std::time`, `rand`, `fs` or `fetch`. ### III.3 Boundary rules ("Rust computes, TypeScript reads") -1. **Calls are coarse and synchronous.** One call per user action or per - load (`parse_sheet`, `build_index`, `apply_click`, `sync_vertebrae`, - `export_archive`, `read_archive`), never per render. The index, the - report and the outcomes cross the boundary as plain JSON-compatible - objects (`serde-wasm-bindgen` with `json_compatible()`), typed by - `tsify`-generated `.d.ts`. React components read properties; nothing in - the render path calls into the wasm. -2. **The sheet index becomes data.** `build_sheet_index(sheet) → SheetIndexData` - with `views`, `annotations`, `finding_zones`, `regions` keyed by id, - `annotations_by_view`, `spine_by_region_view`, `main_view_id`. The ten - closures disappear; `nodeAt` and `name` become small functions on both - sides (Rust for the core, a generated TS helper for components), with one - duplicate policy (document order, first wins, same as `validate`). -3. **Errors are closed kinds, not classes.** Every fallible call returns a - tagged result (`{ ok: true, value } | { ok: false, kind, detail }`) with - the kinds already named in the code (`invalid_pdf`, `no_attachment`, - `incompatible_version`, `snapshotRejected` reasons, `ArchiveExportError` - kinds). The `instanceof` checks in pdf and the scripts go away with the - TS classes. +1. **Coarse calls, JSON strings.** One call per user action or per load, + never per render. Payloads cross as JSON strings (`serde_json` with the + `js_number` formatter, `JSON.parse` on the TypeScript side); types come + from `ts-rs` (`packages/core-wasm/types`). No `serde-wasm-bindgen`, no + `tsify`: zero extra crates on the boundary, no `null`-for-absent trap, + payloads readable in the debugger. The kilobyte-sized observations and + outcomes make the string cost irrelevant; the sheet never crosses more + than once. +2. **The sheet is a handle.** `SheetHandle` is a `#[wasm_bindgen]` struct + built once per session from the loaded sheet (document, assets, + migration map); every core call that needs the sheet takes the handle by + reference. `handle.index_data()` returns `SheetIndexData` once (plain + data: views, annotations, finding zones, regions by id, annotations per + view, spine per region and view, `main_view_id`, `name_fr`/`name_en` per + annotation, `node_by_path`); React reads properties. +3. **Errors are closed kinds.** Every fallible call returns + `{ ok: true, value } | { ok: false, kind, detail }` with the kinds already + named in the code (`invalid_pdf`, `no_attachment`, `incompatible_version`, + `snapshotRejected` reasons, `ArchiveExportError` kinds, `internal`). The + `instanceof` checks on domain errors go away with the TS classes. 4. **Ids and time are inputs.** `new_report(draft, sheet, id, created_at)`, - `export_archive(…, exported_at)`; the TS side keeps `crypto.randomUUID()` + `write_archive(…, exported_at)`; TypeScript keeps `crypto.randomUUID()` and `new Date()`. -5. **No panic on content.** `#![deny(clippy::unwrap_used, clippy::expect_used)]` - in the libraries, `catch_unwind` at the facade turning any panic into a - `kind: 'internal'` result, and `cargo-fuzz` targets on `read_archive`, - `parse_sheet`, `sanitize_svg` and the image decode (native only). -6. **Deterministic serialisation.** Struct fields in the Zod schema order; - integer fields typed as integers; a `js_number` formatter for floats - (shortest round-trip, JS rules for `.0` and exponents) used by the SVG - serialiser and the pipeline; `serde_json` pretty printer for the archive. - A parity test compares the envelope JSON produced by the TS engine and by - Rust byte for byte on the three golden reports during R2 and R4. +5. **Panics are traps, handled outside.** On wasm32 the core is panic = + abort, so `catch_unwind` is native-only. Libraries deny `unwrap`/`expect`; + every TypeScript facade call catches `WebAssembly.RuntimeError`, marks + the instance poisoned, re-instantiates it (and rebuilds the sheet handle) + before the next call, and surfaces `kind: 'internal'`. The hostile corpus + (security and scan suites) runs through the wasm build at the shipped + shadow-stack size (set explicitly with `-C link-arg=-zstack-size`), not + only natively. +6. **Lazy, degradable initialisation.** The module loads behind the sheet + and import paths only; `/login`, `/app/*` and Mon compte never touch it. + A failed load yields a `core_unavailable` state with a retry that evicts + the cached promise. The import path runs the reader in a dedicated Web + Worker with its own instance, terminated after each import (linear memory + never shrinks; BLK-009 wants a bounded blast radius). +7. **Deterministic serialisation.** Struct fields in a declared order (the + Zod schema order for the snapshot, the store's insertion order for the + report), integer fields as integers, `js_number` for floats; optional + fields `skip_serializing_if = "Option::is_none"`, nullable fields plain + `Option`. A permanent compatibility test parses every Rust-written + envelope and draft fixture with a frozen copy of the last shipped Zod + schemas (the "N-1 reader" test, VI.3). ### III.4 Contracts: one source of truth - **Rust is the source** for the sheet document, the report, the migration - map, the envelope, the snapshot, the branding and the labels. `tsify` - emits the TypeScript types next to the wasm; `packages/domain` shrinks to - re-exports of those types and of the wasm facade, then disappears once no - TS importer remains. The Zod schemas of these contracts are deleted at the - end of R2 (no duplicate logic kept). -- **JSON Schema as documentation and optional DB check.** `schemars` emits - the 2020-12 schema of each contract into `docs/contracts/*.schema.json` - (committed, diffed by CI). Enforcing it in PostgreSQL through - `pg_jsonschema` is possible on both hostings but not on PGlite, so it is - recorded as an option for the step that first stores reports (Step 14), - not adopted here. -- **SQL keeps its mirror.** `private.sheet_document_issues` stays; a - conformance fixture set (`crates/domain/tests/conformance/*.json`: document - + expected codes) is run by cargo tests and by a pgTAP file, so the two - implementations are pinned to the same expectations. -- **UI form constraints** get one home: a generated `constraints.json` - (lengths, regexes, password policy) produced from the SQL migrations and - `config.toml` by a small tools command, consumed by the Zod form schemas. - This closes the drifts the inventory found (trim, `char_length`, empty - names) without moving React code to Rust. -- **Generated database types** stay `supabase gen types` (unchanged). + map, the envelope, the snapshot, the branding and the labels. `ts-rs` + emits the TypeScript types; the Zod schemas of these contracts are + deleted in the phase that switches their last consumer (VI.4), and + `packages/domain` is deleted at R5 (its app importers are codemodded to + `@faunosteo/core-wasm` at R2). +- **SQL keeps its mirror.** Conformance fixtures (`crates/core/tests/ + conformance/*.json`: document, expected Rust issues with paths, expected + SQL codes) are run by cargo and by a pgTAP file generated with the + fixtures inlined (PGlite runs SQL text only); a drift test regenerates and + compares the pgTAP file. +- **JSON Schema** is not produced until a consumer exists (`pg_jsonschema` + CHECK is an option for Step 14, which stores reports). +- **Generated database types** stay `supabase gen types`. -### III.5 Build and packaging of the wasm +### III.5 Build and serving of the wasm -- `cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown` - then `wasm-bindgen --target web --out-dir packages/core-wasm/pkg`, both - pinned to the same `wasm-bindgen` version (`cargo install wasm-bindgen-cli - --version ` in CI and Docker; `taiki-e/install-action` supports it); - `wasm-opt -Oz` from the npm `binaryen` package. Root script `pnpm wasm:build`. -- Vite 7: `import init, * as core from '@faunosteo/core-wasm'` with - `await init()` at application start (the `SheetProvider` is already - async), `?url` resolution of the `.wasm`, no plugin. Vitest: same package, - `init(readFileSync(wasmPath))`. -- Expected size: the domain + anatomy + reader core is estimated under - 600 KB gzip (UNVERIFIED until built; `serde_json` and `roxmltree` are - small, no fonts, no raster); `resvg` would add 949 KB gzip (measured on - resvg-wasm 2.6.2) and is kept out of the main module. -- Debugging: `--keep-debug` builds in development, Chrome DWARF extension; - `console_error_panic_hook` vendored (archived upstream, 30 lines). +- `cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown`, + then `wasm-bindgen --target web --out-dir packages/core-wasm/pkg`; the + CLI version is read from `Cargo.lock` by the install line in CI and + Docker. Root script `pnpm wasm:build`; `cargo test -p faunosteo-wasm` + writes the `ts-rs` types. +- Vite 7: `await init()` lazily (III.3 rule 6), `?url` resolution of the + `.wasm`, no plugin. Vitest: `init(readFileSync(wasmPath))`. +- Production serving (D-R13): CSP `script-src 'self' 'wasm-unsafe-eval'` in + both `DEPLOY.md` examples with a sanity-check row; nginx serves a + precompressed `.wasm.gz` (`gzip_static`) or adds `application/wasm` to + `gzip_types`; the hashed file name invalidates caches at each deploy. The + size budget counts bytes actually served (`curl --compressed`), proposal: + core module ≤ 600 KB compressed, measured at R2 and enforced by a CI + check. +- Debugging: `--keep-debug` builds in development, Chrome DWARF extension; a + vendored 30-line panic hook (the upstream crate is archived). --- @@ -433,117 +470,129 @@ injected: the core never calls `std::time`, `rand`, `fs` or `fetch`. Everything in `STEP8_FILES_ANALYSIS.md` Part II stays (buckets, `assets` table, RPCs, keys, quarantine, purge queue, backups, migration runbook, UI, -D1 to D9). What changes is II.1's runtime and II.8's package: one Rust -binary replaces the Node process and `sharp`. +D1 to D9). What changes is the runtime of II.1 and II.8: one Rust binary +replaces the Node process and `sharp`. The keyless-decoder invariant of +STEP8 IV.3 ("the keyed process never decodes") is kept. ### IV.1 Process model ```text -container faunosteo_worker (distroless/static, non-root, read-only, no port) - faunosteo-worker run ← keyed parent: tokio, reqwest, token +container faunosteo_worker (distroless/static:nonroot, read-only, no port, default seccomp) + faunosteo-worker run ← keyed parent (tokio, reqwest, service key) poll every 2 s: POST /rest/v1/rpc/claim_avatar_jobs {max_jobs: 1} GET /storage/v1/object/avatars/ (≤ 5 MiB, 30 s timeout) - spawn faunosteo-worker decode ← same binary, subcommand, empty env, stdin/stdout only - child: rlimits (AS 512 MiB, CPU 10 s, FSIZE 0, NPROC 0, NOFILE 8), Landlock - (no filesystem), seccomp allowlist (read, write, mmap, munmap, brk, mremap, - futex, exit_group, sigaltstack, rt_sigaction, rt_sigprocmask, sched_yield, - clock_gettime, getrandom), PR_SET_NO_NEW_PRIVS; parent SIGKILLs at 20 s - decode: magic bytes → format ∈ {jpeg, png, webp} else unsupported_type - image::ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB} - dimensions from the header before decode (64 ≤ sides ≤ 4096 else dimensions) - decode (first frame of an animated WebP), apply_orientation(EXIF), + spawn faunosteo-worker decode ← same binary; `decode` is dispatched from a plain fn main + BEFORE any runtime or thread exists; empty env; stdin/stdout + child: assert Threads: 1 (/proc/self/status) → RLIMIT_AS 512 MiB, RLIMIT_CPU 10 s → + seccomp allowlist installed with TSYNC, kill on violation (list derived by strace + over the fixture corpus at the caps on the production image, not hand-written) + decode: image::guess_format ∈ {jpeg, png, webp} else unsupported_type + ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB} + header dimensions before decode (64 ≤ sides ≤ 4096 else dimensions) + decode (first frame of an animated WebP), apply_orientation (EXIF), ICC → sRGB through moxcms when a profile ≤ 1 MiB is present, else assume sRGB resize_to_fill 512×512 (Lanczos3), alpha kept - encode lossy WebP q=82 via libwebp-sys (C, confined to this child) - stdout: 512×512 WebP bytes, exit code = closed reason - parent: re-decode the output with image-webp (pure Rust, limits), assert 512×512, assert - no EXIF/XMP/ICCP chunk (img-parts), sha256, size + encode lossy WebP q=82 via libwebp-sys (C, confined to this process) + stdout: WebP bytes; exit code from a reserved table (never 101, never a signal number) + parent: read stdout up to 512 KiB (kill past it); parse the RIFF container only: size field = + byte length, chunk FourCC allowlist {VP8X, VP8, VP8L, ALPH}, canvas 512×512 from the + VP8X/VP8 header, no EXIF/XMP/ICCP chunk; sha256; size. NO pixel decode in the parent. PUT /storage/v1/object/avatars/ (upsert) → POST rpc/complete_avatar_job → DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job + SIGSYS, SIGKILL (deadline) and RLIMIT deaths are logged with their own internal code + (syscall number for SIGSYS) and mapped to processing_error; after 20 s the parent SIGKILLs sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep - watchdog: one loop iteration > 60 s → process exits, Docker restarts it + watchdog: per-stage deadlines (claim 35 s, download 35 s, decode 25 s, upload 35 s, commit 35 s); + a stage past its deadline exits the process; Docker restarts it + start-up log: libwebp version (WebPGetEncoderVersion, CI fails below 1.6.0), seccomp status, + token expiry (service key: none) ``` -The crash matrix, the write order (PUT clean → commit → DELETE quarantine), -the lease and attempt rules, the purge grace periods and the fairness rule -of the Step 8 analysis apply unchanged. +The crash matrix, the write order, the lease and attempt rules, the purge +grace periods and the fairness rule of the Step 8 analysis apply unchanged. +The 60 s single watchdog of the Node proposal is replaced by per-stage +deadlines, because one iteration's worst case (three 30 s network calls plus +the 20 s child) exceeded it and would have burnt leases during a slow Storage. ### IV.2 Comparison with the Node proposal | Aspect | Node 24 + sharp (STEP8 II.8) | Rust worker | Verdict | |---|---|---|---| | Decoders on untrusted bytes | libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 | `zune-jpeg` (SIMD `unsafe`, togglable), `png` (no `unsafe`, fuzzed), `image-webp` (`forbid(unsafe)`), hard `Limits` | Rust better: smaller trusted base, caps by construction | -| Encoder | libwebp via sharp | libwebp via `libwebp-sys` 0.14 (C), in the sandboxed child, on a buffer the child itself decoded; output re-verified by a pure-Rust decoder in the parent | equivalent; the C surface is the encoder only (D-R4 lists the pure-Rust and lossless alternatives) | -| Orientation, ICC, metadata | `rotate()`, ICC → sRGB and stripping by default | `apply_orientation`, `moxcms` ICC → sRGB, stripping by construction (the encoder writes no chunks), plus an explicit chunk check | equivalent, verified rather than assumed | -| Isolation | two Node processes, child without env | one static binary, child without env **plus** rlimits, Landlock, seccomp (allowed by Docker's default profile, rootless included) | Rust better | -| Resource bounds | `limitInputPixels`, `mem_limit` 512m, 20 s kill | `Limits`, `RLIMIT_AS`, `RLIMIT_CPU`, 20 s kill, `mem_limit` | equivalent or better | -| Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB; no runtime | Rust better on resources | -| Transport to Supabase | supabase-js with the service key over PostgREST and Storage | `reqwest` calls to the same two APIs; token = a dedicated `faunosteo_worker` role JWT (D-R6) or the service key | equivalent; least privilege possible | -| Maintenance | `sharp` Renovate rule | `cargo-deny` + `cargo-audit` in CI; `image` crate releases | equivalent | +| Encoder | libwebp via sharp | libwebp via `libwebp-sys` 0.14 (C), in the same sandboxed child, on a buffer that child decoded; the parent checks the container header only | equivalent; the C surface is the encoder, process-confined (D-R4 lists the alternatives) | +| Orientation, ICC, metadata | `rotate()`, ICC → sRGB and stripping by default | `apply_orientation`, `moxcms` ICC → sRGB, stripping by construction (the encoder writes no metadata chunk) plus the parent's chunk allowlist | equivalent, verified rather than assumed | +| Isolation | two Node processes, child without env | one static binary, child without env **plus** rlimits and a traced seccomp allowlist installed before any thread | Rust better | +| Resource bounds | `limitInputPixels`, `mem_limit` 512m, 20 s kill | `Limits`, `RLIMIT_AS`, `RLIMIT_CPU`, 20 s kill, output cap 512 KiB, `mem_limit` | better | +| Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB | Rust better on resources | +| Transport to Supabase | supabase-js with the service key over PostgREST and Storage | `reqwest` calls to the same two APIs with the same key (`webpki-roots` compiled in for HTTPS on managed) | equivalent | +| Maintenance | `sharp` Renovate rule | `cargo deny` in CI (licences, bans, sources blocking; advisories nightly) | equivalent | | Managed Supabase | URL + key only | same | equivalent | -| Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule | +| Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule; built in CI, pulled by digest (VIII.1) | ### IV.3 Worker crates -`tokio` (rt, process, time, io), `reqwest` (rustls, json, stream), `serde` / -`serde_json`, `image` (default-features off; `jpeg`, `png`, `webp`), -`image-webp` (parent verification), `moxcms`, `libwebp-sys` (child only, -behind a feature), `img-parts` (chunk check), `infer`, `sha2`, `rlimit`, -`landlock`, `seccompiler`, `tracing` + `tracing-subscriber` (JSON logs, field -allowlist, control characters escaped: LRN-044), `thiserror`. No database -driver (same reasoning as STEP8 II.8: one transport, no open DB port on -managed). +`tokio` (rt, process, time, io), `reqwest` (rustls, json, stream, +`webpki-roots`), `serde` / `serde_json`, `image` (default-features off; +`jpeg`, `png`, `webp`), `moxcms` (version resolved by `image`), +`libwebp-sys`, `sha2`, `rlimit`, `seccompiler`, `tracing` + +`tracing-subscriber` (JSON logs, field allowlist, control characters escaped: +LRN-044), `thiserror`. No database driver (one transport, no open DB port on +managed, as in STEP8 II.8). -### IV.4 Credentials (D-R6) +### IV.4 Credential: as validated, with one hardening option recorded -The analysis gave the worker the service key. The research confirms a -narrower option at the same cost: a Postgres role `faunosteo_worker` granted -to `authenticator`, holding EXECUTE on the eight worker RPCs only and the -`storage.objects` policies it needs on the `avatars` bucket; a JWT -`{role: "faunosteo_worker", sub: , exp: <1 year>}` minted once -by the operator with `JWT_SECRET` (self-hosted) or an imported ES256 standby -key (managed) and placed in `.env.worker`. The worker never holds the -secret; a leaked token cannot read profiles, sheets or other buckets. The -pgTAP census already pins what `authenticated` may execute; it extends to -`faunosteo_worker`. Fallback: the service key as analysed (no code change, -one env variable). +The worker holds the service key in `.env.worker` as the owner validated +(STEP8 D1, II.8). A dedicated `faunosteo_worker` Postgres role with a minted +JWT would narrow a leak, but it is independent of the language and is not +"at the same cost": it needs the role granted to `authenticator` (the PGlite +shim defines only `anon`, `authenticated`, `service_role`), EXECUTE on the +nine worker RPCs plus a new RPC for the key-driven sweep lookup, `SELECT`, +`INSERT`, `UPDATE` and `DELETE` policies on `storage.objects` for the role +(which breaks the pinned census "2 / 1 / 0 per bucket" and the assertion +"no UPDATE / DELETE policy exists"), token expiry handling (log `exp` at +start, warn 30 days before, re-mint), a revocation path (`REVOKE +faunosteo_worker FROM authenticator` plus re-mint), and on managed an +operator-held signing key. Recorded as a Step 27 hardening option with +those prerequisites; not a decision of this study. ### IV.5 Tests specific to the Rust worker -- Decode child fixtures (the STEP8 IV.2 list, unchanged): JPEG/PNG/WebP +- Decode child fixtures (STEP8 IV.2 list, unchanged): JPEG/PNG/WebP accepted, renamed PNG, GIF/BMP/SVG/PDF/HTML refused, truncated, 32 px, 20 000² header, 5000², EXIF-rotated → upright and chunk-free, PNG trailer after IEND, progressive JPEG with many scans and a large ICC under the deadline with RSS asserted, sleeping child killed at 20 s. -- Sandbox tests (native, Linux): the child cannot open `/etc/passwd` - (Landlock), cannot `fork` (NPROC 0), cannot write a file (FSIZE 0), has an - empty environment (`/proc/self/environ`), dies on a disallowed syscall - (seccomp), and the parent maps each death to `processing_error`. -- Parent verification: a child returning a 511×511 image, an image with an - `EXIF` chunk, or garbage → rejected before any PUT. -- Fuzz: `cargo-fuzz` target on the decode entry with the `image` limits - (CI nightly, time-boxed). +- Sandbox tests (Linux, on the production image in CI): every accepted + fixture passes through the **fully** sandboxed child (the allowlist is + derived, then proven on the corpus at the caps: 4096² RGBA, 16-bit PNG, + CMYK JPEG, ICC through `moxcms`); a disallowed syscall kills the child and + the parent logs SIGSYS with the syscall number; `/proc/self/environ` is + empty; `Threads: 1` holds when the filter is installed. +- Parent checks: a child returning 511×511, an `EXIF` chunk, a wrong RIFF + size, 513 KiB of output, or garbage → rejected before any PUT; the child + is killed on output overflow. - Integration against the local stack (CI `supabase` job): Alice's full - flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2. + flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2; one + HTTPS call in CI proves the CA bundle. --- ## Part V. Libraries retained and their limits -| Area | Retained | Alternatives rejected | Known limits to manage | +| Area | Retained | Rejected | Limits to manage | |---|---|---|---| -| Serialisation | `serde`, `serde_json`, `thiserror` | `json-canon`, `serde_jcs` (compact only) | float printing (custom `js_number`), key order by struct order | -| XML | `roxmltree` + own tree and serialiser | `quick-xml` (advisories patched, but a writer is not needed), `usvg` as sanitiser (allows DTD, drops silently, rewrites the drawing) | pin `roxmltree` to the release containing the deep-nesting fix; pre-parse byte and depth caps | -| PDF write | `pdf-writer` | `krilla` (no Std14 page text, merged dates), `printpdf` (no attachments), `lopdf` (object model heavier than needed) | writes classic xref only (desired); layout is ours | -| PDF read | own byte scan + `miniz_oxide` | `lopdf`, `pdf` | none; same caps as today | +| Serialisation | `serde`, `serde_json` (custom formatter), `thiserror`, `ts-rs` | `serde-wasm-bindgen`, `tsify`, `schemars` (until a consumer exists), `serde_jcs` | float printing owned by `js_number`; field order declared per struct | +| XML | `roxmltree` + own tree and serialiser | `quick-xml`, `usvg` as sanitiser (allows DTD, drops silently, rewrites the drawing) | depth and size pre-scan until the deep-nesting fix is released | +| PDF write | `pdf-writer` | `krilla` (no Standard 14 page text, merged dates; candidate for TTF), `printpdf` (no attachments), `lopdf` as writer | classic xref only (wanted); `f32` coordinates (links read back) | +| PDF read | own byte scan + `miniz_oxide`; `lopdf` test-only | `pdf`, `pdfium` in the app | same caps as today | | Fonts | vendored Core 14 AFM (APAFML notice committed); later `skrifa` + `subsetter` + `harfrust` | `ttf-parser`, `rustybuzz` (RustSec unmaintained) | kerning-inclusive width rule reproduced from pdf-lib | | PNG | `png` | UPNG semantics | gate stays ours; decoder under `Limits` | -| Raster (option) | `resvg` + `tiny-skia` (lazy module) | canvas kept as default until decided | 949 KB gzip; `allow_dtd` and 1M-element cap belong to our sanitiser upstream; text needs embedded fonts (none in the drawings today, to be asserted by the sanitiser) | -| Images (worker) | `image`, `image-webp`, `moxcms`, `libwebp-sys`, `img-parts`, `infer` | `webp` crate (libwebp 1.3.1 line), `wasmtime` sandbox (advisory cadence), `extrasafe` (dormant) | `Limits.max_alloc` advisory → `RLIMIT_AS` is the hard cap; `moxcms` profile size capped by us; `zune-jpeg` panics contained by the child | -| Sandbox | `seccompiler`, `landlock`, `rlimit` | user namespaces (blocked in Docker) | Landlock best-effort on older kernels: the worker logs the ABI it got and refuses to start below V1 in production (config flag) | -| Runtime | `tokio`, `reqwest`, `tracing` | `postgrest`, `supabase-rs` | hand-written calls: ~10 endpoints, tested against the local stack | -| WASM | `wasm-bindgen` + CLI, `tsify`, `serde-wasm-bindgen`, `binaryen` (npm) | `wasm-pack` | crate/CLI version lock; `getrandom` not needed in the core | -| Hygiene | `cargo-deny`, `cargo-audit`, `cargo-fuzz`, `cargo-chef` | `cargo vet` (later) | | +| Raster | browser canvas (DOM adapter); `resvg` native in tools/worker when a need appears | `resvg` in the browser bundle | `allow_dtd`, 1M-element cap and the crop workaround handled by our sanitiser and adapter | +| Images (worker) | `image`, `moxcms`, `libwebp-sys` | `webp` crate, `image-webp` in the parent, `img-parts`, `infer`, `wasmtime`, `extrasafe` | `Limits.max_alloc` advisory → `RLIMIT_AS` is the hard cap; profile size capped | +| Sandbox | `seccompiler`, `rlimit` | `landlock` (redundant under the allowlist), user namespaces | allowlist derived by tracing, proven on the corpus | +| Runtime | `tokio`, `reqwest` (`webpki-roots`), `tracing` | `postgrest`, `supabase-rs` | ~10 hand-written endpoints tested against the local stack | +| WASM | `wasm-bindgen` + CLI (version from `Cargo.lock`), `binaryen` when needed | `wasm-pack` | crate/CLI lock | +| Hygiene | `cargo-deny` (licences, bans, sources blocking; advisories nightly and at release) | `cargo-audit` (same database), `cargo-chef` (BuildKit cache mounts suffice), `cargo-fuzz` before Step 27 (nightly toolchain; our own parsers only) | | --- @@ -551,63 +600,72 @@ one env variable). ### VI.1 Principles -- One phase = one crate boundary moved, with a **parity harness** that runs - the existing fixtures through both implementations and compares outputs - (deep-equal JSON, byte-equal where bytes are the contract) until the - switch; the TypeScript implementation and the harness are deleted in the - same phase, never later (no two concurrent implementations past a phase). -- Goldens are never regenerated silently: a phase that must change a golden - format (the PDF draw-log recorder) states it in its end criteria and the - owner decides (the Step 6 rule stays). -- Every phase ends with `pnpm check` green, `cargo test --workspace`, - `cargo clippy -D warnings`, `cargo deny check`, Docker builds green, the - real-stack pgTAP when SQL changed, the verifier and security gates, and a - manual validation script for the owner. -- Phases are gitflow branches (`feature/rust-r-` for behaviour, +- **Freeze with the old code, then switch.** Before a phase ports a module, + every output that no test pins yet is committed as a golden produced by + the TypeScript code (LRN-046): the three archive envelopes, the composed + views as parsed trees, the draw log of lines, rectangles and colours. The + oracle suites are then ported to cargo on the fixtures in place (JSON + fixtures under `apps/app/tests/fixtures` and `packages/*/tests/fixtures`, + read by path; the two TypeScript fixtures `horse-slice.ts` and + `mini-sheet.ts` converted to JSON once). No dual-run harness. +- **Consumer-driven deletion.** A TypeScript module is deleted in the phase + that switches its last consumer; until then it is frozen (no new logic) + and its existing goldens keep proving it. The table in VI.4 names the + last consumer of every module so nothing is deleted while imported + (revision 1 broke this twice). +- **Goldens are never regenerated silently.** A phase that changes an + oracle (the attachment bytes at R2, the generated seed files at R5) says + so in its end criteria and the owner decides. +- **Every phase** ends with `pnpm check`, `cargo test --workspace --locked`, + `cargo clippy -D warnings`, `cargo deny check` (licences, bans, sources), + Docker builds green, the real-stack pgTAP when SQL changed, the verifier + and security gates, the rollback row of VI.3 proven, and a manual + validation script for the owner. +- Phases are gitflow branches (`feature/rust-r-`; `chore/rust-r0-workspace` for the foundation). ### VI.2 Phases and end criteria | Phase | Content | Depends on | End criteria (verifiable) | |---|---|---|---| -| **R0 Foundation** | `Cargo.toml` workspace, `rust-toolchain.toml`, `deny.toml`, lints, `crates/domain` skeleton with the first contract (`SheetRef` + `Locale`) and the wasm facade exporting `core_version()`; `pnpm wasm:build`; CI job `rust`; app Dockerfile stage; `docs/development/RUST.md` (setup, commands, boundary rules of III.3); `rustup` on the dev host (owner) | none | `cargo test`, `clippy`, `deny` green in CI; the app loads the wasm in dev and in the Docker image (`core_version()` shown on the dashboard footer in DEV only); `pnpm check` unchanged; CI time measured and recorded | -| **R1 Step 8 worker** (Rust from the start) | Part IV: `crates/worker`, decode child, sandbox, transport, sweeper, compose service, `.env.worker.example`, the Step 8 migration and app work as analysed | R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests, local-stack integration, real-stack e2e); worker image < 30 MB, non-root, `cap_drop ALL`, read-only; owner manual validation of the avatar flow | -| **R2 Domain core** | `crates/domain`: sheet document + rules, report v3/v2 + migration, rebase (owner go for the gated function), snapshot/envelope/branding/labels, index data, reducers, the rules extracted from components, `new_report`; wasm facade; app switched (`SheetProvider` parses through Rust, store hydrates through Rust, click chain through Rust); publish gate on Rust; TS Zod contracts deleted; conformance fixtures for SQL; `constraints.json` for forms | R0 | parity harness: 0 difference on every domain fixture, the 612 leaves, the three golden reports' envelopes (byte-equal), the rebase and envelope decision tables; app suites green with the same assertions; `packages/domain/src` contains only generated types and re-exports; no `instanceof` on domain errors; bundle size delta recorded; owner manual FR/EN flow | -| **R3 Anatomy core** | `crates/anatomy`: XML tree, sanitiser (one for all), serialiser, layer renderer, `compose_view_svg`; app canvas and engine composition on it; committed serialisation oracle for `horse.svg`; app denylist deleted | R2 | `render.compose` byte goldens unchanged; step6 `views.*.json` unchanged (relaxed fields as today); 7 hostile cases + caps; canvas suite green; one sanitiser in the repo (grep) | -| **R4a PDF reader + CLI** | `crates/pdf` reader: scan, bounded inflate, layered read; app import on the wasm; `faunosteo-tools report-compare`; TS reader and `scripts/compare*` deleted | R2 | scan (39), inflate (9), read (13) suites reproduced in Rust; bombs: 64 MiB ObjStm in ms, EmbeddedFile bomb cancelled at 16 MiB, RSS flat (asserted natively); CLI 11 cases; `DecompressionStream` absent from the repo | -| **R4b PDF writer** (B, trigger: Step 15 or TTF) | layout → draw log → `pdf-writer`; AFM vendored; PNG gate + `png`; dates tables; `exportFromEnvelope`; draw-log recorder as the new golden producer (same JSON shape as the spies); pdf-lib, UPNG, standard-fonts, xmldom removed | R3, R4a | the 39 goldens reproduced exactly through the Rust draw log (text x/y/size/font, images, links, views); new draw-log golden covering lines, rectangles and colours frozen **with the TS engine before the port** (owner decision to add); poppler/pdfium render diff of the three reports ≤ a stated threshold; re-export test; attachment stored size < 250 KB; `pnpm report:compare --diff` identical on the fixture PDFs; no `pdf-lib` in the lockfile | -| **R4c Rasteriser option** (D-R3) | `wasm-raster` module with `resvg`, lazy-loaded; canvas adapter kept as fallback for one release | R4b | owner visual validation of the three reports; raster facts test green; main bundle size unchanged | -| **R5 Curation pipeline + importer** (B) | `crates/anatomy` feature `curation` and `crates/tools import-equine`; Prettier formatting kept as the last Node step (D-R5) or identity rule changed under a schema migration | R2, R3, next content changeset | `seed.golden.test.ts` byte-exact on all 18 files (or the knowingly regenerated set with the new identity rule and a data migration for `documentSha256`); determinism and count tests; TS pipeline deleted | -| **R6 Hygiene** | retire `packages/domain`, `packages/anatomy`, `packages/pdf` TS packages when no importer remains; CLAUDE.md folder map; `packages/README.md`; CHANGELOG | R2..R5 | no TypeScript business logic outside UI glue (grep census documented in `RUST.md`); workspace test count reconciled with a "deleted tests" list (TEST_STRATEGY §6) | +| **R0 Foundation** (inside Step 8) | `Cargo.toml` workspace, `rust-toolchain.toml`, `deny.toml`, lints, `crates/core` skeleton (no app consumer yet), `crates/worker` skeleton, CI job `rust`, worker image build, `docs/development/RUST.md` (setup, commands, boundary rules), `DEPLOY.md`: images built in CI and pulled by digest, CSP line with `'wasm-unsafe-eval'`, gzip for `.wasm`, VPS disk and RAM headroom recorded; `rustup` on the dev host (owner) | none | `cargo test`, `clippy`, `deny` green in CI; worker image builds (< 30 MB) and starts against the local stack with no job; panic strategy on wasm32 verified and written in `RUST.md`; CI duration and runner cache behaviour measured and recorded; no production artifact changed yet | +| **R1 Step 8 worker** | Part IV: decode child, sandbox, transport, sweeper, per-stage deadlines, compose service, `.env.worker.example`, the Step 8 migration and app work as analysed | R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests on the production image, local-stack integration, real-stack e2e); image non-root, `cap_drop ALL`, read-only; libwebp ≥ 1.6.0 logged; owner manual validation of the avatar flow | +| **R2 Domain core** | `crates/core` domain: sheet document + rules, report v3/v2 + migration, rebase (owner go, D-R12), snapshot/envelope/branding/labels, `SheetHandle` + `SheetIndexData`, reducers, `build_finding`, `vertebra_selection`, `new_report`; `crates/wasm` facade (JSON strings, `ts-rs` types, poison-and-reinstantiate, lazy init, `core_unavailable`); `packages/core-wasm` package; app Dockerfile wasm stage; app switched (`SheetProvider`, store, click chain, pickers, publish gate); app importers codemodded from `@faunosteo/domain` to `@faunosteo/core-wasm`; `packages/domain` frozen for the TS engine and pipeline; three envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP | R0 | the domain, service, store, component and route suites pass with their assertions on the core; the three frozen envelopes parse with the frozen Zod schemas and compare semantically equal (bytes differ by decision D-R11); the 39 step6 goldens and the seed golden are untouched (the TS engine and pipeline still run on frozen TS); `pnpm build` with the wasm; the app boots under the exact production headers (CSP) in a headless check; a wasm load failure leaves `/login` and `/app` usable and shows the degraded state in the editor; a deliberate trap re-instantiates the module; served module size ≤ 600 KB compressed; owner manual FR/EN flow | +| **R3 Anatomy core** | `crates/core` anatomy: tree, sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas on the core (denylist deleted); the TS engine still composes with its frozen TS copy; composed-view trees for the three reports frozen with the TS code first | R2 | step6 `views.*.json` unchanged through the app path; composed views DOM-equivalent to the frozen trees; 7 hostile cases + caps + zero-removal (tree compare) in cargo; canvas suite green; one sanitiser reachable from the app (grep) | +| **R4 PDF core** (reader + writer + CLI) | `crates/core` pdf: scan, bounded inflate, layered read; layout → draw log → `pdf-writer`; AFM vendored; `png` + gate; dates tables; the leniency decisions of I.2 pinned by fixtures; draw-log golden for lines, rectangles and colours frozen with the TS engine first (D-R2); app import in a Web Worker, app export on the two-call design; `report-compare` tool; `packages/pdf` deleted (last consumer); frozen TS `render/` deleted with it only if the pipeline no longer imports it (it does: kept until R5) | R3 | 39 goldens reproduced exactly through the Rust draw log (text, images), links read back from the written files with `lopdf`, views via the app path; the new draw-log golden reproduced; scan (39), inflate (9), read (13), security (55), text (5), size (2) suites in cargo; the hostile corpus through the wasm build; BLK-009 browser measurements (Chromium, Firefox, Safari, one low-end phone) recorded in `PDF_IMPORT_HARDENING.md` §5 as done items (the gate itself stays open until every §5 item is done); poppler or pdfium render diff of the three reports within a stated threshold; the last TS scanner, kept as a test fixture, and the previous release's reader read every R4 fixture PDF; stored attachment < 250 KB; no `pdf-lib`, `@pdf-lib/*`, `@xmldom/xmldom` in the lockfile of `apps/app` or `packages/pdf` | +| **R5 Curation pipeline, importer, operator tools** | `crates/core` curation + `cli` bins: import-equine, upload-sheet-assets; outputs emitted by Rust (`js_number`, markdown tables); `.prettierignore` on generated dirs; seed golden regenerated once (decided); review drawings compared as parsed trees against the xmldom-era files; `packages/anatomy` and `packages/domain` deleted (last consumers); CLAUDE.md folder map, `packages/README.md`, `WORKSPACE.md`, CHANGELOG | R2, R3, R4 | `seed.golden.test` green on the regenerated set; determinism (two runs byte-equal), counts (27/792/612/41, 811 nodes), 612-leaf semantics unchanged; `documentSha256` changed once and the import of an older archive shows the rebase message with 0 unresolved items on identical content; no TypeScript business logic outside UI glue (grep census in `RUST.md`); workspace test count reconciled with the deleted-tests list (TEST_STRATEGY §6) | -Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 immediately after Step 8 -and before Step 9, so that every later step writes its rules in Rust rather -than adding TypeScript logic to migrate twice. R3 and R4a follow in that -order, interleaved with Steps 9 to 12 (they touch no backend table). R4b -waits for its trigger. R5 waits for the next content changeset (the eleven -open questions for the osteopath will produce one). R6 closes. +Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 right after Step 8 and +before Step 9, so that every later step writes its rules in Rust. R3, R4 and +R5 before Step 13 (which needs the sanitiser in the worker), interleaved with +Steps 9 to 12, which touch no module these phases move. The TTF font change +is a separate later change with its own golden regeneration (D-R2). -### VI.3 Parity harness design +### VI.3 Rollback per phase -A vitest file per phase (`tests/parity/.test.ts`) imports the TS -implementation and the wasm, runs every fixture through both and -`toEqual`s the outputs; for byte contracts (envelope JSON, composed SVG, -generated seed files) it compares strings. The harness is deleted with the -TS implementation. Cargo tests carry the same fixtures (copied under -`crates/*/tests/fixtures`, listed in a manifest checked against the TS -fixture directory by a test, so the two sets cannot drift during the -transition). +Production rollback is "deploy the previous image by digest" (VIII.1), so +each phase states what the previous build must still read. -### VI.4 What is deleted when +| Phase | Artifacts written by the new build | What N-1 must read | Proof | +|---|---|---|---| +| R1 | avatars (WebP) | the app only displays them; the Node proposal never shipped | none needed | +| R2 | drafts in `osteo:draft` and archives in `osteo:archive` written by the core (struct order, `js_number`); PDFs still written by the frozen TS engine from core-produced reports | N-1 (Step 7 build) parses the draft and the envelope with its Zod schemas | N-1 reader test on the frozen fixtures; a draft N-1 cannot parse goes to the quarantine key with a notice (never discarded) | +| R3 | none persisted (canvas only) | n/a | | +| R4 | PDFs from `pdf-writer` (classic xref, same attachment, same stamp) | N-1 scanner finds the attachment and the stamp; Step 6 build reads bare v3 and envelope | the kept TS scanner fixture and the previous release's reader read every R4 fixture PDF; `DEPLOY.md` rollback note updated as for Step 6 | +| R5 | regenerated seed (new `documentSha256`) | N-1 app bundles the old seed and rebases archives written on the new one (visible message, nothing lost); reports written on the old seed rebase on the new build | rebase tests both ways on the two seeds | -| Phase | Deleted | -|---|---| -| R2 | `packages/domain/src/**` Zod schemas and functions (types stay generated), rules inside components, `services/zoneInteraction.ts`, `services/sheetIndex.ts` shim | -| R3 | `anatomy/drawing.ts` denylist, `packages/anatomy/src/render/**`, `packages/pdf/src/svg/**` | -| R4a | `packages/pdf/src/attachment/**`, `read.ts`, `apps/app/scripts/**`, the `DecompressionStream` inflater | -| R4b | the rest of `packages/pdf/src`, pdf-lib, UPNG, standard-fonts, xmldom | -| R5 | `packages/anatomy/src/{legacy,curation,cli}/**` | -| R6 | the three TS packages | +### VI.4 What is deleted when (last consumer named) + +| Module | Consumers today | Last consumer switched at | Deleted at | +|---|---|---|---| +| `services/zoneInteraction.ts`, component data-building rules, store rules | app | R2 | R2 | +| `packages/domain` Zod contracts and functions | app (R2), TS engine (R4), TS pipeline (R5), scripts (R4) | R5 | R5 (`packages/domain` removed; app imports codemodded at R2) | +| `anatomy/drawing.ts` denylist | app canvas | R3 | R3 | +| `packages/pdf/src/svg/**` (sanitiser, view) | TS engine | R4 | R4 | +| `packages/anatomy/src/render/**` | app (R3), TS engine (R4), TS pipeline `app-review.ts` (R5) | R5 | R5 | +| `packages/pdf/src/**` (reader, writer, attachment, branding gate), `apps/app/scripts/**`, `browserRasterizer.ts` stays | app, CLI | R4 | R4 (`browserRasterizer.ts` kept as the DOM adapter) | +| `packages/anatomy/src/{legacy,curation,cli}/**`, `packages/supabase/scripts/upload-sheet-assets.ts` | operator | R5 | R5 | +| `packages/anatomy`, `packages/domain`, `packages/pdf` packages | | | R4 (pdf), R5 (anatomy, domain) | --- @@ -615,88 +673,87 @@ transition). | Step | Plan text today | Adaptation under the rule | |---|---|---| -| 8 Files | Node worker + sharp (STEP8 D1) | D1 becomes "native Rust worker" (confirmed by the owner); R0 + R1 inside the step; `apps/worker` is not created; `crates/worker` is | -| 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors written in `crates/domain` and called through the wasm; UI unchanged | -| 13 Sheets in DB | SVG processor "from packages/pdf" | the Rust sanitiser of R3 runs in the worker's decode child (same isolation as images); the Supabase `SheetProvider` stays TS glue, parsing through the Rust core | -| 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; document diff/throttle rules in Rust; optional `pg_jsonschema` CHECK from the `schemars` output (decision at the step) | -| 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row" | the Rust worker validates the attachment with `crates/domain` + `crates/pdf` reader (R4a) and renders artifacts with the writer (R4b trigger); no Edge Function | -| 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in Rust | -| 17 Sheet editor | editor store with undo, geometry | document operations and geometry in `crates/domain` (or a `crates/editor` if the dependency boundary differs), UI React | -| 19 Notifications/worker | `apps/worker` Node, EmailProvider, `private.jobs` | extends `crates/worker`: `private.jobs` loop (`SKIP LOCKED` through an RPC), templates rendered in Rust (`packages/i18n` split not needed for templates: the dictionaries used by templates move to Rust data) | -| 20–21 Agenda, travel | expiry rule TS mirror, routing adapter in the worker | mirror in Rust/wasm; routing provider adapter and calendar sync in `crates/worker`; the Google OAuth callback is the first inbound HTTP endpoint: a small `axum` service in the worker binary (`serve` subcommand) behind the reverse proxy, one route, no other port | -| 22 Public web | Q8 framework | Astro recommended (global rule, SEO/GEO, islands); D-R8 | -| 23 Billing | "Edge Function stripe-webhook" | the `serve` subcommand hosts the webhook (`async-stripe` or hand-written signature check); idempotency table unchanged | -| 24 Imports | adapters in the Node worker | adapters in Rust (`csv`, `calamine`, `zip`), same `ImportAdapter` contract | +| 8 Files | Node worker + sharp (STEP8 D1) | D1 reads "native Rust worker"; R0 + R1 inside the step; `apps/worker` is not created; `crates/worker` is; service key kept (IV.4) | +| 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors in `crates/core` domain, called through the wasm; UI unchanged | +| 13 Sheets in DB | SVG processor "from packages/pdf" | the R3 sanitiser runs in the worker's decode child (same isolation as images); the Supabase `SheetProvider` stays TS glue, parsing through the core | +| 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; diff/throttle rules in the core; optional `pg_jsonschema` CHECK from a `schemars` export (decision at the step, first consumer of JSON Schema) | +| 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row"; artifacts = PDFs generated by the browser | the worker validates the attachment with the core reader (R4); no Edge Function; server-side rendering is not in the plan; if a need appears, `resvg` native between the two core calls | +| 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in the core | +| 17 Sheet editor | editor store with undo, geometry | document operations and geometry as a core module, UI React | +| 19 Notifications/worker | `apps/worker` Node, EmailProvider, `private.jobs`, `packages/i18n` for templates | `crates/worker` `run` gains the `private.jobs` loop (RPC with `SKIP LOCKED`) and templates rendered in Rust from Rust-side dictionaries; `packages/i18n` stays UI-only | +| 20–21 Agenda, travel | expiry rule TS mirror, routing adapter, "Edge Function or worker endpoint" for the Google OAuth callback | mirror in the core; routing and calendar sync in the worker; the callback is the first inbound route of the worker's `serve` subcommand (axum, one route, behind the reverse proxy) | +| 22 Public web | Q8 framework | Astro (global rule), D-R8 | +| 23 Billing | "Edge Function stripe-webhook" | `serve` hosts the webhook (signature check, idempotency table unchanged) | +| 24 Imports | adapters in the Node worker | Rust adapters (`csv`, `calamine`, `zip`), same `ImportAdapter` contract | | 26 Lifecycle | export/archive/restore jobs in the Node worker | Rust jobs in the same binary | -| 27 Hardening | | adds `cargo-audit`, `cargo-deny`, fuzz results and the sandbox tests to the release gate | -| BACKEND_ARCHITECTURE §6 | Edge Function row | replaced by "Rust service (worker `serve`)"; PostgreSQL rows unchanged | -| WORKSPACE.md, packages/README.md | `apps/worker` Node, `@faunosteo/i18n` for the worker | `crates/*`; the i18n package stays UI-only | -| TEST_STRATEGY.md | layers | adds the cargo layer, the parity harness rule and the conformance fixtures shared with pgTAP | +| 27 Hardening | | adds `cargo deny` advisories, the sandbox tests and the `cargo-fuzz` run (nightly toolchain, our own parsers) to the release gate; the worker-role option of IV.4 evaluated here | +| BACKEND_ARCHITECTURE §6 | Edge Function row | "Rust service (worker `serve`)"; PostgreSQL rows unchanged | +| WORKSPACE.md, packages/README.md | `apps/worker` Node, `@faunosteo/i18n` for the worker | `crates/*`; i18n package UI-only | +| TEST_STRATEGY.md | layers | adds the cargo layer, the freeze-then-switch rule, the N-1 reader test and the conformance fixtures shared with pgTAP | --- ## Part VIII. Docker, Supabase and CI impacts -### VIII.1 Docker +### VIII.1 Docker and deployment -- **App image**: a new first stage `FROM rust:1.99.0-bookworm AS wasm` - (`cargo-chef` prepare/cook for layer caching, `wasm32-unknown-unknown` - target, pinned `wasm-bindgen-cli`, `binaryen` via npm or apt) producing - `packages/core-wasm/pkg`; the Node builder copies it before `pnpm build`. - The runner stage (nginx) is unchanged; `.wasm` served with - `application/wasm` (nginx mime types include it) and the existing no-cache - rule on `env.js` untouched. +- **Images are built in CI (or on the dev host) and pulled by digest.** The + VPS (1 vCPU, 1 GB) never compiles Rust: `docker compose up --build` on the + VPS is replaced by `docker compose pull && up -d` on tagged images + (registry: the Gitea container registry of the forge, or Scaleway's); + rollback = the previous digest. This is a prerequisite recorded in R0 and + written into `DEPLOY.md` (routine deploys, rollback, disk headroom). +- **App image**: a first stage `FROM rust:1.99.0-bookworm AS wasm` (BuildKit + cache mounts on `~/.cargo` and `target`, pinned `wasm-bindgen-cli`) + producing `packages/core-wasm/pkg`; the committed + `packages/core-wasm/package.json` is in the manifest COPY list so + `pnpm install --frozen-lockfile` keeps working; the Node builder copies + `pkg/` before `pnpm build`; nginx serves `.wasm` (and `.wasm.gz` with + `gzip_static`) with the hashed name. - **Worker image**: `rust:1.99.0-alpine3.24` builder (musl, `musl-dev`, - `build-base` for libwebp's `cc` build) → `gcr.io/distroless/static:nonroot` - (or `scratch`), one static binary, `USER nonroot`, no shell. Compose - service `worker` (container `faunosteo_worker`): `read_only: true`, - `tmpfs: /tmp`, `cap_drop: [ALL]`, `security_opt: [no-new-privileges:true]`, + `build-base` for libwebp's `cc` build) → `distroless/static:nonroot` (CA + bundle present; `scratch` rejected), one static binary. Compose service + `worker` (container `faunosteo_worker`): `read_only: true`, `tmpfs: /tmp`, + `cap_drop: [ALL]`, `security_opt: [no-new-privileges:true]`, `mem_limit: 512m`, `cpus: 1`, `pids_limit: 64`, no `ports`, Supabase internal network only, `restart: unless-stopped`, `env_file: .env.worker`. - The default Docker seccomp profile stays (it permits the inner sandbox). -- **Naming**: `faunosteo_worker`, image `faunosteo/worker`, volumes as in - STEP8 (BDR-035). -- **Build time**: a cold Rust build of the wasm and of the worker is minutes - (UNVERIFIED on this runner); `cargo-chef` and the registry cache mount - make incremental builds seconds. R0 records the measured numbers. + The default Docker seccomp profile stays (it permits the inner filter). +- **Naming**: `faunosteo_worker`, image `faunosteo/worker` (BDR-035). ### VIII.2 Supabase -- No schema change comes from the rule itself. Step 8's migration gains the - optional `faunosteo_worker` role and grants (D-R6). -- Conformance fixtures for `sheet_document_issues` land as a pgTAP file - reading JSON fixtures (PGlite and real stack), owned by R2. -- Managed migration: the worker container is hosting-agnostic (URL + token); - the worker token on managed is minted with an imported ES256 standby key - or the legacy secret while it exists. +- No schema change comes from the rule itself. +- Conformance fixtures for `sheet_document_issues` land as a generated + pgTAP file with inlined fixtures (PGlite and real stack), owned by R2. +- Managed migration: the worker container is hosting-agnostic (URL + key); + HTTPS works out of the box (`webpki-roots`, distroless CA bundle, one + HTTPS call tested in CI). ### VIII.3 CI (`.gitea/workflows/ci.yml`) - New job `rust` (runs before `check`): toolchain from `rust-toolchain.toml` (`dtolnay/rust-toolchain`), `cargo fmt --check`, `cargo clippy --workspace --all-targets -D warnings`, `cargo test --workspace --locked`, `cargo deny - check`, `pnpm wasm:build`, artifact `packages/core-wasm/pkg` uploaded. - Cache: `Swatinem/rust-cache` if the Gitea cache server works (verify at R0), - else a `~/.cargo` + `target` directory cache on the runner host. -- `check` downloads the artifact before `pnpm install` (or rebuilds it: R0 - picks the faster on this runner). `docker` builds both images. `supabase` - runs the worker integration test against the local stack. -- Nightly: `cargo audit`, a time-boxed `cargo fuzz` run on the four targets. -- The Node pipeline (`typecheck`, `test:run`, `lint`, `build`) is unchanged - in content; its duration shrinks as TS suites are deleted. + check licenses bans sources`, `pnpm wasm:build`, artifact + `packages/core-wasm/pkg` uploaded. Cache: `Swatinem/rust-cache` if the + Gitea cache server works (verified at R0), else a directory cache on the + runner host. +- `check` downloads the artifact before `pnpm install`. `docker` builds both + images and pushes them by tag and digest on `main` and `develop`. + `supabase` runs the worker integration test against the local stack. +- Nightly: `cargo deny check advisories`; from Step 27, the fuzz run. ### VIII.4 Local development -- Owner action: install `rustup` (no global package; `rustup` lives in - `~/.cargo`), the pinned toolchain installs itself from - `rust-toolchain.toml` on first `cargo`; `wasm32-unknown-unknown` target; - `cargo install wasm-bindgen-cli --version ` and `cargo-deny`. -- `pnpm dev` keeps working: `pnpm wasm:build` once (and after Rust changes; - a `cargo watch` recipe in `RUST.md`); Vite serves the `.wasm` from the +- Owner action: install `rustup` (lives in `~/.cargo`, no global package); + the pinned toolchain installs itself from `rust-toolchain.toml`; + `wasm32-unknown-unknown` target; `cargo install wasm-bindgen-cli + --version ` and `cargo-deny`. +- `pnpm dev` keeps working: `pnpm wasm:build` once and after Rust changes + (a `cargo watch` recipe in `RUST.md`); Vite serves the `.wasm` from the package. - The worker runs against the local stack with `cargo run -p - faunosteo-worker -- run` and `.env.worker` (token minted by the SUPABASE.md - §8 recipe). + faunosteo-worker -- run` and `.env.worker` (SUPABASE.md §8 recipe). --- @@ -708,61 +765,64 @@ transition). archives, immutable sheet versions, RLS, unresolved findings, FR/EN, file security, graphics. Proof = the existing suites kept with their assertions (one-to-one migrations named in commits, TEST_STRATEGY §6), - the goldens unchanged except where a decision regenerates them, the - pgTAP suites unchanged. -2. No duplicate business logic at the end of a phase (grep census of rule - names in TS outside UI glue, recorded in `RUST.md`). + goldens unchanged except where a decision regenerates them, pgTAP + unchanged, the N-1 reader test green at every phase. +2. No duplicate business logic at the end of a phase, by the consumer-driven + deletion table (grep census in `RUST.md`); hand-written TS mirrors of + core helpers are not allowed (the core precomputes what React needs). 3. Security gates: the security-auditor runs on every phase; the worker - sandbox tests are part of the suite; `cargo-deny` and `cargo-audit` are - release gates. -4. Operability: worker image size, start time, memory ceiling and the - sandbox ABI logged at start; a runbook line per failure mode in - STORAGE.md. -5. Cost visibility: CI duration and app bundle size before and after each - phase recorded in the phase's TODO note. + sandbox tests run on the production image; `cargo deny` licences, bans + and sources block, advisories gate releases. +4. Operability: worker image size, start time, memory ceiling, libwebp and + seccomp status logged at start; a runbook line per failure mode in + STORAGE.md; deploy and rollback never compile. +5. Cost visibility: CI duration and the served module size recorded in each + phase's TODO note. ### IX.2 Risks | Risk | Likelihood | Effect | Mitigation | |---|---|---|---| -| Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; the parity harness catches what review misses | -| Dual toolchain in CI and Docker (minutes per build) | certain | CI time | caches (`cargo-chef`, registry mounts, runner cache); wasm artifact reused by `check` | -| WASM bundle growth | medium | first load | core without raster or fonts; `resvg` lazy; sizes recorded per phase; budget set at R0 (proposal: core ≤ 600 KB gzip) | -| Hidden JS semantics in outputs (float printing, upper-casing, ICU dates, kerning widths, rounding) | high | golden mismatches | the exact list of I.2; a draw-log golden on lines/rectangles/colours frozen before R4b; `js_number` tested on the committed overlays | -| Prettier-dependent sheet identity | certain for R5 | identity change breaks every report's `sheet` match | keep the Prettier step (D-R5) or migrate the identity rule with the pending BLK-008 data migration | -| Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; recorder format change is a named deliverable | -| Crates maintained by one person (`zune-jpeg`, `moxcms`, `libwebp-sys`, `krilla`, `pdfium-render`) | medium | abandonment | `cargo-deny` `unmaintained` advisories; alternatives listed in Part V; decoders confined to the child | -| `roxmltree` deep-nesting overflow (fix unreleased) | known | DoS of the parser | depth cap by a byte pre-scan before parsing; pin the fixed release when out | -| Landlock absent on the VPS kernel | unverified | weaker child isolation | seccomp + rlimits still apply; worker logs the ABI; the runbook checks `/sys/kernel/security/lsm` | +| Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; frozen oracles catch what review misses | +| Dual toolchain in CI and Docker | certain | CI minutes | caches; wasm artifact reused by `check`; images built once, pulled by digest | +| WASM module as a point of failure (CSP, 404 after deploy, trap, memory growth) | medium | editor unusable or tab memory | CSP line and headless check at R2; lazy init with `core_unavailable`; poison-and-reinstantiate; reader in a terminated Web Worker; hashed file name | +| Hidden JS semantics in outputs and readers (float printing, upper-casing, ICU dates, kerning widths, rounding, lenient decoding, duplicate keys, `.int()`, `\s`) | high | golden mismatches or stricter readers refusing old files | the I.2 list with a fixture each before the owning phase; leniency decisions recorded; N-1 reader test | +| Sheet identity hash changes at R5 | certain | every older archive rebases once on import (message, nothing lost) | stated in R5's criteria and in the CHANGELOG; rebase tested both ways | +| Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; relaxed fields never widened without a decision | +| Crates maintained by one person (`zune-jpeg`, `moxcms`, `libwebp-sys`, `ts-rs`, `krilla`) | medium | abandonment | `cargo deny` `unmaintained` advisories; alternatives in Part V; decoders confined to the child; the boundary has no third-party crate | +| `roxmltree` deep-nesting overflow (fix unreleased) | known | parser DoS | depth cap by byte pre-scan; pin the fixed release | +| seccomp allowlist killing a valid decode | medium if hand-written | valid photos rejected after three leases | derived by tracing, proven on the corpus at the caps in CI, SIGSYS logged with the syscall number | +| VPS resources | certain | OOM or full disk during a build | never build on the VPS (VIII.1); disk headroom recorded | | Gitea runner caches for Rust | unverified | slow CI | measured at R0; host-level cache fallback | -| `wasm-bindgen` crate/CLI version lock | certain | broken builds on drift | one pinned version in `Cargo.lock` and in the CI/Docker install line, checked by a script | -| Two implementations lingering | medium | drift, double maintenance | deletion list per phase (VI.4) is part of the Definition of Done | -| Edge-Function assumptions elsewhere in the plan | low | plan inconsistency | Part VII table applied to the plan text at R0 | +| `wasm-bindgen` crate/CLI version lock | certain | broken builds on drift | one version read from `Cargo.lock` by the install lines | +| Two implementations lingering | medium | drift, double maintenance | VI.4 last-consumer table is part of each Definition of Done | | Public web framework conflict | certain | decision needed | D-R8 | ### IX.3 Explicit non-goals of the rule - Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos, - Dioxus): excluded by the owner's retained list and by the Step 7 validated - mockups. + Dioxus): excluded by the owner's retained list and the validated mockups. - Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer: excluded (retained list; RLS stays the boundary). - Running Rust inside PostgreSQL (`pgrx`): excluded by managed compatibility. -- Moving the SQL rules to Rust: excluded; SQL keeps transactional rules. +- Moving SQL transactional rules to Rust: excluded. +- Shipping `resvg` to the browser: excluded (size, no visual change wanted). -### IX.4 Unverified items (to settle at R0 or at the phase that needs them) +### IX.4 Unverified items (settled at R0 or at the phase that needs them) -- `image` 0.25 on `wasm32` targets (not needed: images decode only in the - worker). `resvg` byte-identical output native vs wasm (README claim). -- Exact libwebp version string in `libwebp-sys` 0.14.4 (≥ 1.6.0 confirmed - by API presence). -- `serde_json`/`zmij` float exponent thresholds vs JavaScript (the `js_number` +- Panic strategy and `catch_unwind` on stable `wasm32-unknown-unknown` for + the pinned toolchain (handled as abort regardless). +- `resvg` byte-identical output native vs the Node test adapter (README + claim; matters only if a server-side rendering need appears). +- Exact libwebp version string in `libwebp-sys` 0.14.4 (≥ 1.6.0 by API + presence; logged at start, checked in CI). +- `serde_json`/`zmij` exponent thresholds vs JavaScript (the `js_number` formatter is tested on the committed overlays regardless). -- Gitea runner support for `Swatinem/rust-cache`; cold build times. -- Landlock on the Scaleway VPS kernel; distroless `nonroot` UID. -- Core wasm size and instantiate time (measured at R0/R2). -- Whether the attachment JSON bytes must stay identical across engines (no - test pins them; D-R11 makes it a stated choice). +- Gitea runner support for `Swatinem/rust-cache`; cold build times on the + runner; registry choice for images. +- Core wasm size and instantiate time (measured at R2). +- The syscalls a static-musl decoder needs (`mprotect`, `madvise`, + `rt_sigreturn`, `tkill`…): derived by tracing at R1, never assumed. --- @@ -770,20 +830,22 @@ transition). | Id | Question | Recommendation | |---|---|---| -| D-R1 | Workspace layout | Six crates (domain, anatomy, pdf, wasm, worker, tools), one per dependency or deployment boundary; not one `core` crate with features | -| D-R2 | PDF writer sequencing | R4b on the trigger (Step 15 or TTF fonts), after R3/R4a; port with the Standard 14 AFM metrics first (goldens exact), TTF as a separate later change with its own golden regeneration; not both at once | -| D-R3 | Rasteriser | Keep the browser canvas adapter at R4b; evaluate `resvg` in a lazy-loaded module afterwards with a visual validation (R4c); the Node tests already render with resvg | -| D-R4 | Lossy WebP encoder in the worker | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child, output re-verified by a pure-Rust decoder; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (`ravif`, pure Rust, changes D4's format) | -| D-R5 | Curation pipeline identity | Rust pipeline emits the data, a Node Prettier step formats the files, `document_sha256` keeps its definition (byte golden intact); alternative: new identity rule (sha256 of canonical JSON) shipped with the BLK-008 data migration and a map of old → new hashes | -| D-R6 | Worker credential | Dedicated `faunosteo_worker` Postgres role + minted JWT (least privilege, no secret in the container); fallback service key as analysed | -| D-R7 | Form validation schemas | Stay TypeScript (React-bound); add the generated `constraints.json` so lengths, regexes and the password policy have one source | -| D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the public site needs no islands | -| D-R9 | Edge Functions | Retired from the plan; webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | -| D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4a interleaved with Steps 9–12; R4b/R5 on their triggers | -| D-R11 | Archive attachment bytes | Treat the pretty JSON with Zod-order keys as a contract (struct order mirrors it, parity test byte-equal); no test pins it today, so this is a choice, not a repair | +| D-R1 | Workspace layout | Three crates: `core` (feature-gated library with tool binaries), `wasm` (facade), `worker` (binary); no crate per module, no `crates/editor` | +| D-R2 | PDF engine | Reader and writer ported together at R4 with the Standard 14 AFM metrics (goldens exact); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port (additive); TTF fonts as a separate later change with its own regeneration | +| D-R3 | Rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | +| D-R4 | Lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (`ravif`, pure Rust, changes D4's format) | +| D-R5 | Sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives rebase on import with a visible message and 0 unresolved items (as any content changeset); no Prettier dependency kept | +| D-R7 | Form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home: a hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, with the counting rule recorded | +| D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the site needs no islands | +| D-R9 | Edge Functions | Retired from the plan (limits, hand deployment, one Rust runtime); webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | +| D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9–12 | +| D-R11 | Archive attachment bytes | New contract adopted at R2 (declared field order, `js_number`, optional absent / nullable null); every previous reader keeps parsing it (N-1 reader test, permanent); the bytes of existing PDFs are untouched | | D-R12 | Gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | -| D-R13 | Draw-log golden before R4b | Add a golden for lines, rectangles and colours with the current TS engine before the port (one regeneration decision, strictly additive) | -| D-R14 | WASM size budget | Core module ≤ 600 KB gzip, measured and enforced by a CI check from R2 | +| D-R13 | Serving the wasm in production | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples, gzip for `.wasm`, images built in CI and pulled by digest (no compile on the VPS), served module ≤ 600 KB compressed enforced in CI | +| D-R14 | BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the §5 browser measurements; the external-user import gate (BDR-040) stays open until every §5 item is done, never closed by R4 alone | The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native -Rust worker" from this review on. +Rust worker" from this review on; the worker credential stays the service +key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1 +(that role) is therefore no longer a decision of this study, which is why +the numbering skips it.