docs(docs): Rust-by-default architecture review rev 1 — inventory, hidden contracts, A/B/C classification, Rust worker, workspace, roadmap R0–R6, 14 owner decisions

This commit is contained in:
bchanot committed 2026-10-12 22:21:49 +02:00
1 parent aae0b392f8
commit 6a078dab74
1 file changed
+789
@@ -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>` → `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/<fn>` 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 <role> TO authenticator`) and by storage-api (official custom-roles
guide: grant to `authenticator`, grant `anon` to the role, RLS on
`storage.objects` `to <role>`, 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 <x>` 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/<quarantine_key> (≤ 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/<object_key> (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: <fixed uuid>, 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<n>-<slug>` 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/<phase>.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 <pinned>` 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.