From 6a078dab74ba3d4bbbe0ec44af02b52504deceb9 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 12 Oct 2026 22:21:49 +0200 Subject: [PATCH] =?UTF-8?q?docs(docs):=20Rust-by-default=20architecture=20?= =?UTF-8?q?review=20rev=201=20=E2=80=94=20inventory,=20hidden=20contracts,?= =?UTF-8?q?=20A/B/C=20classification,=20Rust=20worker,=20workspace,=20road?= =?UTF-8?q?map=20R0=E2=80=93R6,=2014=20owner=20decisions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/RUST_ARCHITECTURE_REVIEW.md | 789 +++++++++++++++++++ 1 file changed, 789 insertions(+) create mode 100644 docs/development/RUST_ARCHITECTURE_REVIEW.md diff --git a/docs/development/RUST_ARCHITECTURE_REVIEW.md b/docs/development/RUST_ARCHITECTURE_REVIEW.md new file mode 100644 index 00000000..153a977f --- /dev/null +++ b/docs/development/RUST_ARCHITECTURE_REVIEW.md @@ -0,0 +1,789 @@ +# 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. + +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 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. + +Companion material: `STEP8_FILES_ANALYSIS.md` (the design this review keeps, +with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, +`ANATOMICAL_SHEET_MODEL.md` (contracts that stay as they are). + +--- + +## 0. What this study pushes back on (read first) + +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. +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` + 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 + 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. + +--- + +## Part I. Facts + +### 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. + +| 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/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) | +| `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 | +| `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. + +### I.2 Hidden contracts a port must honour (found by the inventories) + +These are the facts that decide feasibility, not the line counts. + +| 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) | + +### I.3 Toolchain and host 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. +- 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 + v5 has a per-runner cache server; not verified on this forge). + +### 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. + +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 | +| 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 | + +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 | + +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 | +| 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 | + +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). + +Supabase platform facts that shape the worker and the contracts: + +- 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). + +--- + +## Part II. Classification of every module + +### II.1 Criteria applied + +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. + +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. + +### 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 | +|---|---|---|---|---|---|---|---|---|---| +| `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 | +| 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 | + +### 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, + 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). + +--- + +## Part III. Target Rust architecture + +### III.1 Cargo workspace + +```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 +├─ 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) +``` + +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). + +### III.2 Native and WASM: who runs what + +| Crate | Native (worker, tools, tests) | WASM (browser) | +|---|---|---| +| 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 | +| 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`. + +### 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. +4. **Ids and time are inputs.** `new_report(draft, sheet, id, created_at)`, + `export_archive(…, exported_at)`; the TS side 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. + +### 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). + +### III.5 Build and packaging 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). + +--- + +## Part IV. Step 8 worker in Rust + +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`. + +### IV.1 Process model + +```text +container faunosteo_worker (distroless/static, non-root, read-only, no port) + faunosteo-worker run ← keyed parent: tokio, reqwest, token + 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), + 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 + 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 + 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 +``` + +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. + +### 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 | +| Managed Supabase | URL + key only | same | equivalent | +| Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule | + +### 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). + +### IV.4 Credentials (D-R6) + +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). + +### IV.5 Tests specific to the Rust worker + +- Decode child fixtures (the 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). +- Integration against the local stack (CI `supabase` job): Alice's full + flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2. + +--- + +## Part V. Libraries retained and their limits + +| Area | Retained | Alternatives rejected | Known 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 | +| 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) | | + +--- + +## Part VI. Progressive migration strategy + +### 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, + `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) | + +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. + +### VI.3 Parity harness design + +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). + +### VI.4 What is deleted when + +| 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 | + +--- + +## Part VII. Adaptations to the development plan + +| 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 | +| 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 | + +--- + +## Part VIII. Docker, Supabase and CI impacts + +### VIII.1 Docker + +- **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. +- **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]`, + `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. + +### 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. + +### 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. + +### 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 + 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). + +--- + +## Part IX. Validation criteria and risks + +### IX.1 Validation criteria of the orientation (beyond the per-phase ones) + +1. No regression on the owner's list: Report v3, v2 PDF import, autonomous + 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`). +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. + +### 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` | +| 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 | +| 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. +- 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. + +### IX.4 Unverified items (to settle 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` + 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). + +--- + +## Part X. Decisions for the owner + +| 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-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 | + +The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native +Rust worker" from this review on.