Files
faunosteo/docs/development/RUST_ARCHITECTURE_REVIEW.md
T

77 KiB
Raw Blame History

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 Maps, 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

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

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 toEquals 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.