Files
faunosteo/docs/development/RUST_ARCHITECTURE_REVIEW.md
T

106 KiB
Raw Blame History

Rust by default: architecture review and migration roadmap

Status: study for the owner's decision, 2026-10-12, revision 2 after three independent plan challenges (correctness, robustness, simplicity: 61 findings, 2 blockers; what changed is listed in §0.2). Nothing implemented. Applies the owner's brief of 2026-10-12: Rust becomes the preferred language for everything that can reasonably be written in Rust, for new work and for existing code; equivalence suffices; "already in TypeScript" and "more work" are not reasons to keep TypeScript; a component kept in another language needs a concrete constraint.

Part I states the facts (inventory, the hidden contracts a port must honour, the state of the Rust ecosystem on 2026-10-12, verified by three research agents against crates.io, RustSec, GitHub and the Supabase docs). Part II classifies every module (A now, B later with a trigger, C exception). Part III is the target architecture (workspace, boundary, bindings). Part IV is the Step 8 worker in Rust. Part V lists the libraries retained and their limits. Part VI is the progressive migration with end criteria and rollback. Part VII adapts the development plan. Part VIII covers Docker, Supabase and CI. Part IX gives validation criteria and risks. Part X lists the decisions the owner has to take. §0 states what this study pushes back on and what the challenges changed.

Companion material: STEP8_FILES_ANALYSIS.md (the design this review keeps, with the worker runtime replaced), PDF-FORMAT.md, ANNOTATION-RENDERING.md, ANATOMICAL_SHEET_MODEL.md (contracts that stay as they are).


0. Pushbacks and revision notes

0.1 What this study pushes back on

  1. Where Rust buys something here. The browser already runs memory-safe code, so "Rust is safer" is no argument for the SPA. The gains the study claims: one core that runs identically in the worker, the CLI tools and the browser (server-side archive validation at Step 15 needs the reader the browser has); untrusted bytes (images, SVG, PDF attachments) parsed on the server with hard allocation caps and without libvips, libpng, xmldom or UPNG in the trusted base; the removal of three dependencies the project already distrusts (pdf-lib unmaintained since 2021, BLK-009; UPNG trusting its input; DecompressionStream as the only inflater on every read path); and the unification of what the inventory found duplicated (two SVG sanitisers, two view compositions, three copies of the bilingual label fallback in rule code). Screen-only helpers (formatDate for the UI, pickLabel in JSX) stay TypeScript and are not counted as unified.
  2. The rule has a standing cost the project must own. Two toolchains in CI and Docker, a WASM boundary to design, debug and keep safe, Rust skills on a one-person team, oracles to freeze before every switch. Each cost is made visible (Parts VIII, IX) instead of hidden in "equivalent".
  3. Rust does not remove the SQL mirror. private.sheet_document_issues stays SQL because managed Supabase runs no custom pgrx extension; Rust replaces the TypeScript side of the pair; the pair itself remains.
  4. The sheet identity hash changes once. documentSha256 is today the sha256 of the Prettier-formatted document text. It is computed once by the pipeline and only compared at runtime; a different hash sends an old archive through the rebase path (visible import message, nothing lost), exactly as any content changeset does. The study therefore does not chain the pipeline to Prettier (D-R5); it states the one-time effect.
  5. One global rule conflicts with the new one. The global CLAUDE.md mandates Astro for public sites; the Rust rule would prefer a Rust static generator. The study recommends keeping Astro and records the conflict as a decision (D-R8).
  6. Form validation stays TypeScript by the owner's own retained list (code directly tied to React). The constraints themselves are written in two places today (Zod and SQL CHECKs) and already drift; a small chore outside this roadmap gives them one home (D-R7).
  7. The production surface decides more than the language. Two of the blockers found by the challenges were deployment facts: the documented CSP refuses WebAssembly, and the VPS (1 vCPU, 1 GB) compiles the images it runs. Both are fixed in the roadmap before any wasm reaches production (D-R13, VIII.1).

0.2 Changes after the challenges (revision 2)

Folded: three crates instead of six (one feature-gated core, one wasm facade, one worker binary with tool binaries); no throwaway dual-run parity harness (unpinned outputs frozen as goldens with the old code, oracle suites ported to cargo on the fixtures in place); consumer-driven deletion schedule (a TypeScript module is deleted in the phase that switches its last consumer, frozen and parity-tested in between; revision 1 deleted modules that later phases still imported); the PDF writer and the curation pipeline reclassified A with technical dependencies only (revision 1 deferred them for reasons the brief excludes); a two-call export (compose views, the caller rasterises, pure writer) that removes the async rasteriser from the boundary and the need for resvg in the browser; a Rust-owned sheet handle instead of re-shipping the sheet per click; JSON strings across the boundary with generated types (no serde-wasm-bindgen, whose json_compatible preset would write absent optionals as null); panic = abort on wasm32 handled on the TypeScript side (poison and re-instantiate); lazy wasm initialisation with a degraded state so the auth shell never depends on the module; the PDF reader in a Web Worker with the BLK-009 browser measurements as exit criteria; CSP 'wasm-unsafe-eval' and gzip for the module; images built in CI and pulled by digest, never compiled on the VPS; per-phase rollback rows and draft quarantine instead of silent discard; the keyed worker parent never decodes (fixed-size read, RIFF header allowlist, no pixel decode); seccomp allowlist derived by tracing, applied before any thread exists, Landlock and three rlimits dropped as redundant; worker credential kept as validated (service key), the dedicated role moved to a hardening option with its exact prerequisites; display helpers and isIdentityComplete kept in TypeScript; constraints.json, schemars, cargo-chef, cargo-audit, infer, img-parts, fuzzing-now and the DEV footer removed; five JavaScript semantics on reader paths added to the contract list; Step 15 no longer cited as a rendering trigger; decisions merged from 14 to 13.

Not folded (with the reason): "split R2 into three gates" is kept as an option for the implementation contract, since each sub-phase would create a short-lived TS-to-wasm seam inside the store; "keep the Landlock layer best-effort" is replaced by dropping it (the seccomp allowlist already denies every file and process syscall, so the layer would test nothing).


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, pipeline, scripts pure: no JSON.stringify, no Date, no ids, no I/O; host APIs structuredClone, TextEncoder, Object.hasOwn, new URL() via Zod
packages/anatomy 43 files, 4,897 lines: legacy importer 1,842, curation 2,329, render 553, cli 119 15 files, 130 cases (run: 130/130) render only at application runtime (app canvas, PDF composition); the other 4,344 lines run for pnpm import:equine, the pipeline and tests render is pure (plain LayerElement tree); importer and pipeline use xmldom, node:fs, node:crypto, Prettier
packages/pdf 27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom 9 files, 137 cases browser (export, import), CLI, tests explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: DecompressionStream on every read path and in the PNG gate, Intl.DateTimeFormat, TextEncoder/Decoder
packages/supabase 949 lines (596 generated database.types.ts) + scripts/upload-sheet-assets.ts (99 lines, operator, service key) 6 files; PGlite harness runs 9 pgTAP files, 280 assertions browser, CI, operator two rules only: GoTrue code → closed AuthFailure kind (23 → 13), publish gate (Zod + assertPublishable before the RPC); the rest wraps supabase-js
apps/app/src logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) 37 files, 2,476 lines (1,708 without the two 281-key dictionaries) 42 files, 214 cases + 7 .each blocks browser services/zoneInteraction.ts (213 lines) pure; stores are Zustand glue around domain calls; drawing.ts is DOM (DOMParser, importNode) with an app-local denylist sanitiser
apps/app/src UI (components, routes, styles) 65 files, 4,838 lines component and route suites browser React; carries some data-building rules (I.2)
apps/app/src/pdf + scripts/ 4 files, 235 lines + 2 files, 549 lines 65 PDF-related app cases + 11 CLI cases browser / Node branding from bundled logos, Image + canvas rasterizer; CLI report:compare on the engine scanner
apps/app/vite/sheet-bundle.ts 102 lines 7 Vite build 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 at the Step 7 closure: 763 vitest cases, lint 0, build and Docker green.

I.2 Hidden contracts a port must honour

These facts decide feasibility, not the line counts. Each one gets a fixture or a golden before the phase that touches it (Part VI).

Contract Where Consequence for Rust
documentSha256 = sha256 of the Prettier-formatted lean document text, computed once by the pipeline (pipeline.ts:163, format.ts), only compared at runtime (rebase.ts:119, envelope.ts:100, pdf export.ts:88); a mismatch sends the report through rebaseReportOnSheet, which keeps every datum and flags only ids the sheet lacks packages/anatomy, every Report v3 sheet.documentSha256 identity = sha256 of whatever bytes the pipeline emits; when the Rust pipeline emits different bytes, the hash changes once and every older archive rebases on import, as after any content changeset (D-R5)
Generated coordinates and layer attributes are raw JS number strings (1715.4285714285713, "1118", "0.85"); CoordinateSchema is z.number().finite() and most values are integer-valued floats ("cx": 1523) pipeline outputs, review SVGs, layer attributes, snapshot in the archive serde_json prints 1523.0; a js_number formatter (shortest round-trip, JS rules for .0, -0, exponents at 1e21 / 1e-7) is installed as a custom serde_json::Formatter for every JSON output and used by the SVG serialiser; tested on the committed overlays
Attachment JSON: report, branding and labels are serialised in insertion order as passed (pdf export.ts:112-115); only the snapshot is re-parsed (Zod schema order); zones are built {annotationId, viewId, labelFrSnapshot, labelEnSnapshot, side} with vertebrae appended last engine, store reducers the attachment bytes change at R2 when Rust emits struct-ordered objects: declared as a new contract (D-R11); what must hold is that every previous reader (the shipped Zod schemas, frozen as a test fixture) parses what Rust writes
Optional vs nullable: .optional() fields are absent when unset (side, unresolved, severity, nextAppointment), versionId is required and null for bundled-draft reports packages/domain/src/report/v3.ts per-field serde attributes (skip_serializing_if = "Option::is_none" for optional, plain Option for nullable); a boundary that writes absent as null breaks every existing reader
Text layout x positions depend on widthOfTextAtSize, which sums AFM widths plus kerning pairs, while drawText writes unkerned glyphs engine render, 39 goldens (12 text, 12 images, 12 links, 3 views) the Rust engine embeds the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so exact reproduction is provable
Dates through Intl.DateTimeFormat (ICU): 11 octobre 2026, November 20, 2026, UTC; Date.UTC maps years 26–99 to 19xx packages/pdf/src/render/dates.ts explicit fr/en month tables; the two-digit-year quirk is decided (tighten) with a fixture
toUpperCase() on labels before safeText; wrapLines splits on /\s+/ (keeps a trailing empty word; JS \s ≠ char::is_whitespace on U+FEFF, U+0085) engine same Unicode upper-casing in Rust; whitespace class written explicitly; fixtures for both
Reader leniency: TextDecoder non-fatal (invalid UTF-8 → U+FFFD, BOM stripped, scan.ts:498); JSON.parse keeps the last duplicate key; Zod .int() accepts 2.0 engine reader, domain serde_json rejects all three; each is decided (keep lenient with a custom step, or tighten) and pinned by a hostile fixture before R4
One inflater: DecompressionStream('deflate') on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size engine read path, branding miniz_oxide bounded inflate replaces it everywhere (no Web API on the read path)
Two sanitisers: app canvas denylist (drawing.ts: 5 tags, on*, javascript:) and engine allowlist with caps; the engine's "zero-removal" oracle is xmldom's own re-serialisation app vs engine one Rust sanitiser; the oracle becomes a DOM-equivalence check (parsed trees compared), not bytes
Two view compositions: composeViewSvg mutates an xmldom element passed by the engine; the app composes with the browser DOM; the review/app-*.svg byte goldens are xmldom XMLSerializer output (declaration, whitespace nodes, xlink: prefixes) engine vs app vs pipeline one Rust compose_view_svg for app and engine; the xmldom-byte goldens stay owned by the TS pipeline until R5, where their regeneration is a decided change
buildSheetIndex returns ten closures over four private Maps and the whole LoadedSheet (296 KB document, 130 KB drawing, 84 KB map), called per render by ~14 modules and taken by the reducers domain sheet-index, app the sheet lives once in Rust memory as a handle; React reads a precomputed plain-data index (names, node-by-path) built once
Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (codes only) and adds 3 of its own domain validate.ts, migrations the Rust validator takes the TS role; SQL stays; conformance fixtures carry two expectation sets (Rust: codes + paths; SQL: codes)
instanceof on three domain error classes in pdf and app scripts domain errors closed kind discriminants at the boundary (BDR-015 pattern)
Report ids crypto.randomUUID(), createdAt / exportedAt from new Date() apps/app ids and timestamps are inputs of the core
Store takes hydrateReport(report) as is, no parse; initReport only trims reportStore.ts the Rust parser becomes the single entry for any report entering the store
Rules living in UI files that build data: FindingsTreePicker.toggleLeaf (Finding with snapshots and the vet flag), VertebraPicker selection rules components move to the core with the reducers (R2); display helpers (zoneLabel, zoneTrees, describeZone, import message lines, isIdentityComplete) stay TypeScript glue over precomputed data
Draft persistence drops an unparseable draft silently (persistence.ts:55-58, DEV warning only) app a draft the running build cannot parse is kept under a quarantine key with a visible notice (needed by every phase's rollback, VI.3)
The wasm module is a new single point of failure: useSheet.ts caches a rejected promise for the session and has no error state app lazy initialisation behind the sheet and import paths only, a core_unavailable state with retry, auth shell independent of the module

I.3 Toolchain, host and deployment facts

  • No cargo, rustc or rustup on the development host (checked 2026-10-12). Rust stable 1.99.0 (2026-10-01); edition 2024 since 1.85. On wasm32-unknown-unknown the shipped standard library is panic = abort: a panic traps the instance and catch_unwind never returns (verify at R0; consequence handled in III.3).
  • Docker 29.8.2 rootless on the host (seccomp builtin, rootless, cgroupns), kernel 7.0. Docker's default seccomp profile (rootless included) allows seccomp, prctl, setrlimit, prlimit64 unconditionally; unshare and clone3 with namespace flags need CAP_SYS_ADMIN. A seccomp + rlimit child works inside a container; user-namespace isolation does not.
  • Production: DEPLOY.md sizes the VPS at 1 vCPU / 1 GB / 10 GB (the Node build already ran out of memory on DEV1-XS), deploys with docker compose up --build on the VPS, documents a rebuild as the rollback, and sets script-src 'self' without 'wasm-unsafe-eval' in both the nginx and the Caddy examples; docker/nginx.conf has no gzip directive.
  • CI runs on a Gitea act_runner; JavaScript actions need node in the job image; dtolnay/rust-toolchain and taiki-e/install-action are shell composites; Swatinem/rust-cache relies on actions/cache (Gitea runner 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; "UNVERIFIED" items are in IX.4.

Core and bindings:

Need Crate Version (date) Status Limits
JSON serde / serde_json 1.0.229 / 1.0.154 (2026-10-11) serde-rs org pretty printer matches JSON.stringify(v,null,2) except integer-valued floats (3.0) and -0.0: custom Formatter (I.2)
Hashing, base64 sha2 0.11.1, base64 0.23.1, hex 0.4.3 RustCrypto / marshallpierce none open
Inflate miniz_oxide 0.9.1 (2026-03), flate2 1.1.10 pure Rust decompress_to_vec_zlib_with_limit, streaming Decompress for incremental cancel
WASM glue wasm-bindgen 0.2.129 (2026-09-25), js-sys / web-sys 0.3.106 org wasm-bindgen (Cloudflare maintainers), monthly releases, MSRV 1.81 since 0.2.128 the crate and the CLI must be the same version: the CI and Docker install lines read it from Cargo.lock
WASM build cargo build --target wasm32-unknown-unknown + wasm-bindgen-cli; wasm-pack 0.15.0 (one maintainer, 335 open issues) cargo + CLI, pinned; wasm-opt (npm binaryen 132) only when the size budget needs it
Types for TypeScript ts-rs 12.0.1 (2026-01): .ts files written by cargo test; Option<T> → T | null, #[ts(optional)] → t?: T active types only; the payloads cross as JSON strings (III.3); tsify 0.5.8 and serde-wasm-bindgen 0.6.5 (no release in 2.5 years, writes absent optionals as null in its JSON preset) are not used
Vite 7 --target web output: await init() + ?url, no plugin .wasm served raw unless nginx gzips it (VIII.1)

PDF, SVG, XML, fonts:

Need Crate Version (date) Status Limits
PDF writing pdf-writer 0.15.0 (2026-05-27) typst org, 4 pure-Rust deps, no advisory EmbeddedFile + EmbeddingParams, FileSpec::association_kind(Data), Names::embedded_files, Catalog::associated_files, Type1 fonts with WinAnsiEncoding + explicit widths, image XObjects with SMask, Action::uri, Info dates, classic xref table; cannot write object streams at all (BLK-009 option B by construction); coordinates are f32 (the links golden keeps a read-back oracle, VI.2)
PDF writing, higher level krilla 0.8.2 (2026-06) one maintainer page text is OpenType only (no Standard 14), merges CreationDate/ModDate: candidate for the TTF step, not for the parity step
PDF read-back in tests lopdf 0.45 (HIGH advisory patched ≥ 0.42) test-only reads /Annots of the written file for the links golden
Standard 14 metrics no credible crate vendor the Adobe Core 14 AFM files (SPDX APAFML: redistribution allowed with MustRead.html, edits noted); @pdf-lib/standard-fonts bundles the same files (WX, N, KernPairs)
TTF later subsetter 0.2.6, skrifa 0.48, harfrust 0.14; ttf-parser and rustybuzz are RustSec-unmaintained Inter and Fraunces are OFL
SVG raster (native only) resvg / usvg 0.48.1 (2026-08), tiny-skia 0.12 linebender org since 0.45 only cap is 1,000,000 elements, allow_dtd: true: our sanitiser runs first; the head-view crop needs the render-full-box-then-crop workaround (LRN-046); not shipped to the browser (949 KB gzip measured on resvg-wasm 2.6.2)
XML parse roxmltree 0.21.1 (2025-10) RazrFalcon, 27M/90d read-only, refuses DTD by default, nodes_limit; unreleased fix (2026-09-22) for a stack overflow on deep nesting: depth capped by a byte pre-scan until the fixed release is pinned
XML write hand-written serialiser for the allowlisted tree ~100 lines; quick-xml not needed
PNG png 0.18.1 (2026-02) image-rs, no unsafe, OSS-fuzz encoder writes only IHDR/IDAT/IEND unless asked

Worker (image pipeline, sandbox, transport):

Need Crate Version (date) Status Limits
Decode + resize + orientation image 0.25.10 (2026-03-10), MSRV 1.88 image-rs org orientation(), icc_profile(), set_limits (max_alloc advisory 512 MiB), apply_orientation, resize_to_fill, guess_format; JPEG = zune-jpeg, PNG = png, WebP = image-webp; no ICC application API; resolves moxcms ^0.8 (use that version, not 0.9)
JPEG zune-jpeg 0.5.15 one very active maintainer unsafe only in SIMD (togglable), default cap 16536×16535, CMYK ok, "panics are okay" policy → child process justified
WebP decode image-webp 0.2.4 (2025-08) image-rs, forbid(unsafe) lossy, lossless, alpha, animation, ICC/EXIF/XMP; memory limit has a documented TODO; encoder is lossless only
WebP lossy encode libwebp-sys 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, cc build) C no established pure-Rust lossy encoder (oxideav-webp 0.3.1 created 2026-04, zenwebp AGPL); webp 0.3.1 pins libwebp 1.3.1 + one fix (not used)
ICC → sRGB moxcms (version resolved by image) pure Rust, one maintainer, SIMD unsafe on by default; lcms2 6.2 (C) alternative no documented ICC input limits: profile size capped by us (1 MiB)
Sandbox seccompiler 0.5.0 (rust-vmm, sets no_new_privs, TSYNC available), rlimit 0.11 landlock not used (redundant under the allowlist); extrasafe dormant; wasmtime carries ~2 advisories/month in 2026
Runtime, HTTP tokio 1.53, reqwest 0.13.5 (rustls, webpki-roots compiled in), tracing 0.1.44
Supabase clients postgrest 1.6.0 (2023-07), supabase-rs 0.8.0 (PostgREST only) weak hand-written reqwest calls to PostgREST /rpc/<fn> and Storage /storage/v1 (~10 endpoints)
Toolchain rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}, cargo-deny 0.20.2, distroless/static:nonroot (Debian 13, CA bundle included)

Baseline for comparison, sharp 0.35.5 (2026-09-27): libvips 8.18.7, libwebp 1.6.0, libpng 1.6.58, mozjpeg; strips metadata and converts to sRGB by default, limitInputPixels 268 MP, WebP q80; EXIF orientation only with autoOrient/rotate(). libvips had three High CVEs in July and August 2026, libpng twelve CVEs since late 2025. The Rust pipeline's advantage is the loader surface (three formats, pure-Rust decoders, hard caps), not the encoder (still libwebp, confined to the child process).

Supabase platform facts:

  • Edge Functions (managed: 2 s CPU, 256 MB, 150 s wall clock; self-hosted: edge-runtime container, hand-deployed) run Deno, which can execute a wasm build of the core; the rule retires them from the plan for those limits, the hand deployment and the preference for one Rust runtime (D-R9). The language alone would allow them.
  • A dedicated Postgres role is honoured by PostgREST and storage-api (official custom-roles guide), with a JWT minted from the legacy HS256 JWT_SECRET or an imported ES256 standby key; on managed the imported key must become a signing key of the project. Recorded as a hardening option (IV.4), not adopted.
  • pg_jsonschema 0.3.3 exists on managed and in the supabase/postgres image but not in PGlite; custom pgrx extensions have no documented path on managed.

Part II. Classification of every module

II.1 Criteria

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 and display formatting, routing, DOM access, store subscription, vendor SDK calls, build tooling. The owner's brief keeps glue in TypeScript; everything else is Rust unless a concrete loss is named on the brief's list (features, UX, graphics, data compatibility, security, reliability, useful performance, resources, portability, maintainability, deployment). Absence of a performance gain is never a reason for C.

Classes: A = Rust, scheduled on technical dependencies only; B = Rust, waiting for a named external trigger; C = exception with its concrete constraint.

II.2 Module table

Module Role today Tech Rust feasibility and crates WASM? Frontend consequence Compatibility risk Oracle for the switch Class Phase
domain: sheet document schema, validateSheetDocument (21 rules), createEmptySheetDocument shape and integrity of the sheet Zod serde structs (strict = deny_unknown_fields, defaults), hand-written rules returning SheetIssue {code, severity, path, message} yes + native app load and publish gate call the core; types from ts-rs low: codes and paths pinned by the validate suite; strict/strip policy per schema reproduced validate suite (exact code + path lists), horse-slice fixture (converted to JSON), the draft document (0 issues) A R2
domain: report v3, v2 input, migrateReportV2ToV3, readReportDocument report contract and migration Zod full; "never throws on content" made true (today a malformed map entry can throw a raw ZodError) yes + native store hydrates only through the core medium: strip semantics, requiresVetReferral: false dropped in v3 (kept, pinned), optional vs nullable fields 612-leaf migration suites, golden v2 fixtures, migration map A R2
domain: rebaseReportOnSheet rebase on another sheet TS over the index full; takes the sheet handle yes store restore and import CLAUDE.md gate: behaviour preserved exactly rebase suite (exact objects) A (owner go, D-R12) R2
domain archive: buildSheetSnapshot, assertSnapshot, envelope v1 layered read, branding + labels schemas archive contract Zod full; UTF-16 string caps and UTF-8 asset caps reproduced; closed snapshotRejected reasons yes + native app import and export medium: attachment bytes change once (D-R11); origin quirk for unknown envelope versions preserved envelope decision table, branding/labels suite, size test, three envelopes frozen as goldens A R2
domain: buildSheetIndex lookups by id closures over Maps different shape: a Rust-owned SheetHandle (built once per session) for the core calls, plus SheetIndexData exported once for React (views, annotations, finding zones, regions by id; annotations per view; spine per region and view; precomputed name per annotation in both languages; node_by_path) yes ~14 modules read properties instead of calling closures; no wasm call in a render low; one duplicate-id policy (document order, first wins) service and component suites A R2
apps/app/src/services/zoneInteraction.ts click decision, observation reducers pure TS full; apply_click(handle, observation, annotation_id, view_id), sync_vertebrae(handle, …) yes EditorRoute.onZoneClick and ObservationPickers call the core per click with the observation only (the sheet stays in the handle) low 13-case service suite, route click-chain characterisation A R2
data-building rules in components: toggleLeaf (Finding builder), VertebraPicker selection product rules inside components TSX build_finding, vertebra_selection in the core yes components call the core on the user action low component suites keep their assertions A R2
display helpers in components and routes: zoneLabel, zoneTrees, unresolvedFindings, describeZone, import message lines, isIdentityComplete, pickLabel in JSX formatting of core data for the screen TSX portable, but run inside renders and useMemo with t(); moving them means wasm calls in the render path or a view-model layer no none; they read SheetIndexData none existing suites C: React render glue over precomputed data (the sheet names and node_by_path they need come from the core) n/a
reportStore.ts actions report construction and edits Zustand rules in the core (new_report(draft, sheet, id, created_at), swap, set_* validation); the store stays Zustand yes one-line delegations low store suite A (rules) / C (Zustand, adapters) R2
persistence.ts, practitionerCache.ts, localeStore.ts, authStore.ts, localeSync.ts storage adapters, GoTrue event glue TS glue; the only rules (isLocale, "account locale wins once per sign-in") are tied to supabase-js events no none none existing suites C: browser storage and supabase-js session glue (no Rust GoTrue client with PKCE and refresh) n/a
anatomy render: layer renderer, composeViewSvg, highlight, viewBoxOf markers from the document; composition with highlight pure tree + DOM mutation render_annotation_layer(document, view, states) → LayerElement (same plain contract) and compose_view_svg(asset, document, view, highlight) → String yes + native app canvas and engine use one composition; drawing.ts parses a sanitised string with DOMParser and keeps importNode + click delegation low on the layer (step6 view facts); the composed string is compared as parsed trees, not bytes step6 views.*.json, DOM-equivalence of the composed views for the three reports (frozen with the TS code), security SVG cases A R3
pdf svg/{parse,sanitize,view} + app drawing.ts denylist untrusted SVG → safe tree xmldom / DOMParser roxmltree with DTD refused and a byte pre-scan for depth and size, own allowlisted tree, own serialiser; one sanitiser for canvas, PDF, Step 13 uploads and branding SVG yes + native denylist deleted medium: the "zero-removal" oracle becomes a DOM-equivalence test on horse.svg 7 hostile cases, caps, zero-removal (tree compare) A R3
pdf reader: byte scan, bounded inflate, JSON depth pre-scan, stamp, layered read; PNG gate inflater untrusted PDF → archive outcome TS + DecompressionStream miniz_oxide streaming inflate with cancel; same candidate ordering and budgets; the leniency decisions of I.2 pinned yes (in a Web Worker) + native (Step 15 server validation, CLI) app import runs the core in a dedicated Web Worker terminated after each import low: scan (39), inflate (9), read (13) suites are byte-level oracles the same suites in cargo on the fixtures in place; BLK-009 browser measurements A R4
pdf writer: layout, pages, footer, links, attachment, metadata, exportFromEnvelope, branding PNG gate, safeText, wrapLines, labels (25 keys) A4 archive writer pdf-lib pdf-writer; layout split from serialisation (draw log = the golden format); AFM vendored; png decodes the archived logos under the existing gate; fr/en month tables yes + native two synchronous calls: compose_export_views(report, snapshot, branding) → [{key, svg, size}], the caller rasterises (canvas in the browser, resvg natively), then write_archive(input, pngs) → {pdf, warnings}; no rasteriser callback crosses the boundary medium: widths with kerning, Math.round half-up, dates, upper-casing; lines, rectangles and colours are not golden-covered today (D-R2 adds that golden with the TS engine first) 39 goldens through the Rust draw log, links read back from the written file with lopdf, re-export test, size test, poppler/pdfium render diff A (after R3 and the reader; same phase as the reader) R4
apps/app/src/pdf/browserRasterizer.ts SVG → PNG via Image + canvas DOM DOM adapter between the two core calls; a native rasteriser (resvg) serves the worker and tools if a server-side rendering need appears no unchanged none raster facts test C: browser rasterisation is DOM; no resvg in the browser bundle (D-R3) n/a
apps/app/src/pdf/export.ts, import.ts, branding.ts wiring, Vite asset imports, download TS glue no thin none existing suites C: Vite asset imports, Web Worker and DOM download n/a
apps/app/scripts/compare-reports.ts + compare/report.ts archive check CLI tsx + Node faunosteo-tools report-compare on the core (LRN-044 escaping ported) native none low 11 CLI cases A R4
anatomy curation pipeline (changeset, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) + legacy importer changeset → draft artifacts; baseline import re-run at every regeneration TS + xmldom + Prettier + node:fs full (sha-derived "v5-like" uuid, strict label equality, region inference, ops); outputs emitted by Rust with js_number; markdown tables written by Rust; Prettier no longer touches generated files (.prettierignore) native (tools) none the 18 generated files and documentSha256 change once (D-R5); counts, determinism and the 612-leaf semantics are the oracles seed.golden.test (regenerated once, decided), determinism and count suites, 612-leaf test, review drawings compared as parsed trees against the xmldom-era files A (after R2, R3) R5
packages/supabase/scripts/upload-sheet-assets.ts operator upload of sheet SVGs (service key) tsx + Node faunosteo-tools upload-sheet-assets (reqwest) native none none manual operator check (SUPABASE.md §3.1) A R5
packages/supabase classifyAuthError, publish gate closed failure kinds; gate before RPC TS the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue partial gate delegates none existing suites gate A (R2); code map C (supabase-js error shapes) R2
packages/supabase client factory, auth/profile wrappers, database.types.ts, PGlite harness vendor SDK, generated types, test infra TS no Rust GoTrue client for the browser; PGlite is a JS/WASM library no none none C n/a
auth/validation.ts, account/validation.ts (Zod, i18n keys) form field rules Zod portable but React-bound (retained list); the constraints are duplicated in SQL CHECKs and config.toml and drift (trim, UTF-16 vs char_length, '' on names) no one constants module + a PGlite test reading pg_constraint and config.toml with the counting rule recorded (separate chore, D-R7) C chore
lib/{dates,id}.ts nowIso, todayIso, formatDate (screen), generateId Web APIs clock and ids injected into the core; screen dates stay Intl no C n/a
apps/app/src/editor/references/{filter,citations,panel}.ts Références tab and citations panel: search match on citation, DOI and URL (folded); who cites each reference (citersOf); the citations and the path of one finding TS over the validated document portable (pure functions), but display lists over the document the core already validated; the one rule nearby, which finding depends on a reference, stays the core's sheet.dependents no none; read in useMemo on the parsed document none existing unit suites (editor-references-view, editor-citations) C: display-only search and listing over validated data, no business rule, no mutation; owner decision BDR-114 (A) 2026-11-12 n/a
apps/app/src/editor/references/{sort,view,referenceTypes}.ts the four display orders of the Références tab (sheet, citation A to Z, count, type), the shown set after the finding filter, the search and the sort (R2F-6: the ids a finding cites narrow the list; no pin under a filter) TS, Intl.Collator of the current language the collation needs the browser's ICU data (a Rust equivalent would ship its own); a pure function of positions that never writes the document, the stored order or the history no none none editor-reference-sort.test.ts (stable, equal keys keep the stored order, inputs untouched), view suites C: display-only ordering, no business rule, no mutation; BDR-114 (A) n/a
apps/app/src/editor/references/safeLink.ts http and https link target for a URL, https://doi.org/ target for a well-formed DOI TS (URL) portable; it builds a display link, and its http/https test also backs the reference dialog's precheck of the stored URL field (UI form validation: the same refusal the core makes, shown on the field; the core's reference rules stay authoritative and refuse anything else) no none none editor-safe-link.test.ts C: display-only link building over validated data; BDR-114 (A) n/a
apps/app/src/components/editor/references/useReferenceView.ts search text and sort choice (React state), the finding filter read from the history view (navigation, not typed text), tile order handed to the tab React hook holds view state only and calls the pure functions above; it reaches no wasm call and no document write no none none editor-references-view.test.tsx C: React state of a display view; BDR-114 (A) n/a
apps/app/src/admin/sheetList.ts (searchSheets, sortSheets, SHEET_SORTS) and matchesSheetName in apps/app/src/catalogue/useCatalogue.ts the admin official sheet list (R3): search on the name in French or English (folded, the catalogue's rule, now shared), sort by last_modified_at (newest first) or by name, ties by name then id TS, Intl.Collator of the current language portable, but the collation needs the browser's ICU data (a Rust equivalent would ship its own); filters and orders the loaded list for display, never writes; the date itself is computed by the server (M9) and checked at the client boundary no none; called in the render of the list page and the home card none admin.sheetList.test.ts, the catalogue suites C: display-only search and ordering over server data, no business rule, no mutation; owner validation of the R3 plan, 2026-11-16 (as BDR-114 (A)); shortcut: until RR-13 pages the list on the server, where search and sort move n/a
formatShortParisDateTime in apps/app/src/admin/labels.ts the « 9 nov. 2026, 12:06 » / « 9 Nov 2026, 12:06 » date of the admin list and home card (A8), Paris time TS, Intl.DateTimeFormat (fr-FR, en-GB, Europe/Paris), one formatter per language screen date formatting needs the browser's ICU and time zone data no none none admin.labels.test.ts (ratified strings, the Paris summer offset) C: screen date formatting (as lib/dates.ts); owner validation of the R3 plan, 2026-11-16 n/a
cardFailure in apps/app/src/catalogue/failure.ts, apps/app/src/components/catalogue/CardFailure.tsx how a catalogue card shows the closed failure kind of its version (R4, board 30): integrity class (A10 text, no retry), size limits (D1), other kinds with « Réessayer », tone and glyph TS, React portable (a set lookup), but it only maps kinds the core already decided to a line, a tone and a button; the check itself stays the core's check_published no none; called in the card's render none routes.catalogue.test.tsx (test 11 lists every member of CatalogueFailure), components.Notice.test.tsx C: display formatting of closed kinds, no business rule, no mutation; owner validation of the R4 plan, 2026-11-17 (R-8) n/a
i18n/* (281 keys ×2, useT, pickLocaleLabel) UI strings TS UI data and hook; the engine's 25 archived labels move with the engine no parity test C n/a
config/env.ts, lib/supabase.ts, providers, guards, routes, components, styles runtime config, React TS glue no C n/a
vite/sheet-bundle.ts, ESLint, Vite, vitest configs build tooling Node Vite plugin API is JavaScript no C n/a
supabase/migrations, pgTAP, private.sheet_document_issues database SQL retained; the TS/SQL rule pair becomes Rust/SQL with conformance fixtures (two expectation sets) no fixtures inlined into a generated pgTAP file with a drift test (the PGlite harness has no file access) C (retained) n/a
Step 8 worker (planned Node + sharp) file processing not built native Rust (Part IV) native none none (new) Part IV tests A R1 (Step 8)
Step 13 SVG upload processor; Step 15 server-side archive validation; Step 19 notifications and job queue; Step 21 travel engine and calendar sync; Step 23 Stripe webhook; Step 24 import adapters; Step 26 export/archive jobs future backend not built the worker binary (jobs) and its serve subcommand (inbound HTTP) sharing the core crate native none none per step A at design time their steps
Step 17 editor document operations (undo, geometry: bbox + margin → view_box, polygon edits, mapping validation); Step 20 agenda rule mirrors (48/24/1 h) future app logic not built core functions through the wasm; UI in React yes editor store holds plain documents, calls the core on actions none per step A at design time their steps
Step 22 public web marketing site, public profiles, SEO not built Rust static generators exist (Zola); the global rule mandates Astro for indexed sites (islands, SEO/GEO tooling) n/a C proposed, D-R8 Step 22

II.3 Summary by class

  • A: domain contracts and rules, the sheet handle and index data, reducers and data-building rules, publish gate, layer renderer and view composition, the one sanitiser, the PDF reader and writer, the CLI tools, the curation pipeline and importer, the asset upload script, the Step 8 worker, every future backend job, service or rule mirror.
  • B: none left after the challenges; every migratable component is scheduled on technical dependencies (VI.2).
  • C (each with its constraint): React render glue and display helpers, Zustand subscriptions and browser storage adapters, supabase-js session and error shapes, UI form schemas and dictionaries, platform clock/crypto and screen date formatting, the browser rasteriser (DOM), Vite asset wiring and tooling, SQL and RLS, the public web framework (D-R8). Exception for the Références tab (owner decision BDR-114 (A), 2026-11-12): search, sort, citer lists and link building under apps/app/src/editor/references/ stay in TypeScript. They only order, filter and format the document the core has already validated, hold no business rule and never mutate it. The limit: any rule that would change the document, or that the PDF or the server must share (what may be deleted, what a citation requires, a count stored or archived), moves to crates/core. Same exception for the admin sheet list (R3, owner validation of the plan, 2026-11-16): search, sort and the short Paris date of apps/app/src/admin/{sheetList,labels}.ts only filter, order and format the list the server answered; the last-modification date is the server's (M9). A rule the server must share moves to SQL or crates/core. Same exception for the catalogue card's failure line (R4, owner validation of the plan, 2026-11-17, R-8): it shows the kind the core answered, never decides or bypasses the check.

Part III. Target Rust architecture

III.1 Cargo workspace (three crates)

faunosteo/
├─ Cargo.toml                 workspace: members crates/*, [workspace.dependencies], lints
│                             (unwrap_used / expect_used = deny in the library,
│                             disallowed_methods for std::time, std::fs, rand in core)
├─ rust-toolchain.toml        channel pinned (1.99.0 at adoption), target wasm32-unknown-unknown
├─ deny.toml                  cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0,
│                             APAFML for the AFM data), bans (duplicate versions), sources
├─ crates/
│  ├─ core/                   faunosteo-core (lib). Modules: domain (sheet, report, archive,
│  │                          index, reducers, rules), anatomy (xml tree, sanitiser,
│  │                          serialiser, layer, compose), pdf (reader, writer, afm, png gate,
│  │                          labels), curation (pipeline, importer). Features: `xml`,
│  │                          `pdf-read`, `pdf-write`, `curation`, `cli`. No I/O, no clock,
│  │                          no ids in any module (lint-enforced). [[bin]] targets behind
│  │                          `cli`: report-compare, import-equine, upload-sheet-assets.
│  ├─ wasm/                   faunosteo-wasm (cdylib): the wasm-bindgen facade over core
│  │                          (features xml + pdf-read + pdf-write), JSON strings in and out,
│  │                          closed error kinds, `ts-rs` types emitted into
│  │                          packages/core-wasm/types.
│  └─ worker/                 faunosteo-worker (bin): `run` (job loop, transport, sweeper,
│                             watchdog), `decode` (the sandboxed child), later `serve`
│                             (inbound HTTP). Depends on core without the pdf features
│                             until Step 15.
└─ packages/core-wasm/        committed package.json (exports → pkg/) and generated types;
                              pkg/ (js, wasm, d.ts) is git-ignored and built by
                              `pnpm wasm:build`

Why three: one library keeps every rule in one dependency graph and one test run; features keep pdf-writer and roxmltree out of the worker build until it needs them (cargo build -p faunosteo-worker compiles only the features it enables); the facade and the binary are the two deployment boundaries. A crates/editor for Step 17 is not planned; editor operations are a module of core (D-R1).

III.2 Native and WASM: who runs what

Code Native WASM
core domain worker (Step 15 validation), tools, cargo tests app: parse, validate, index, reducers, rules, snapshot, envelope
core anatomy worker (Step 13 uploads), tools (pipeline) app: sanitise, compose views for the canvas and the export
core pdf worker (Step 15), tools (report-compare) app: reader (in a Web Worker), writer
core curation tools only never
worker container faunosteo_worker never

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. Coarse calls, JSON strings. One call per user action or per load, never per render. Payloads cross as JSON strings (serde_json with the js_number formatter, JSON.parse on the TypeScript side); types come from ts-rs (packages/core-wasm/types). No serde-wasm-bindgen, no tsify: zero extra crates on the boundary, no null-for-absent trap, payloads readable in the debugger. The kilobyte-sized observations and outcomes make the string cost irrelevant; the sheet never crosses more than once.
  2. The sheet is a handle. SheetHandle is a #[wasm_bindgen] struct built once per session from the loaded sheet (document, assets, migration map); every core call that needs the sheet takes the handle by reference. handle.index_data() returns SheetIndexData once (plain data: views, annotations, finding zones, regions by id, annotations per view, spine per region and view, main_view_id, name_fr/name_en per annotation, node_by_path); React reads properties.
  3. Errors are closed kinds. Every fallible call returns { ok: true, value } | { ok: false, kind, detail } with the kinds already named in the code (invalid_pdf, no_attachment, incompatible_version, snapshotRejected reasons, ArchiveExportError kinds, internal). The instanceof checks on domain errors go away with the TS classes.
  4. Ids and time are inputs. new_report(draft, sheet, id, created_at), write_archive(…, exported_at); TypeScript keeps crypto.randomUUID() and new Date().
  5. Panics are traps, handled outside. On wasm32 the core is panic = abort, so catch_unwind is native-only. Libraries deny unwrap/expect; every TypeScript facade call catches WebAssembly.RuntimeError, marks the instance poisoned, re-instantiates it (and rebuilds the sheet handle) before the next call, and surfaces kind: 'internal'. The hostile corpus (security and scan suites) runs through the wasm build at the shipped shadow-stack size (set explicitly with -C link-arg=-zstack-size), not only natively.
  6. Lazy, degradable initialisation. The module loads behind the sheet and import paths only; /login, /app/* and Mon compte never touch it. A failed load yields a core_unavailable state with a retry that evicts the cached promise. The import path runs the reader in a dedicated Web Worker with its own instance, terminated after each import (linear memory never shrinks; BLK-009 wants a bounded blast radius).
  7. Deterministic serialisation. Struct fields in a declared order (the Zod schema order for the snapshot, the store's insertion order for the report), integer fields as integers, js_number for floats; optional fields skip_serializing_if = "Option::is_none", nullable fields plain Option. A permanent compatibility test parses every Rust-written envelope and draft fixture with a frozen copy of the last shipped Zod schemas (the "N-1 reader" test, VI.3).

III.4 Contracts: one source of truth

  • Rust is the source for the sheet document, the report, the migration map, the envelope, the snapshot, the branding and the labels. ts-rs emits the TypeScript types; the Zod schemas of these contracts are deleted in the phase that switches their last consumer (VI.4), and packages/domain is deleted at R5 (its app importers are codemodded to @faunosteo/core-wasm at R2).
  • SQL keeps its mirror. Conformance fixtures (crates/core/tests/ conformance/*.json: document, expected Rust issues with paths, expected SQL codes) are run by cargo and by a pgTAP file generated with the fixtures inlined (PGlite runs SQL text only); a drift test regenerates and compares the pgTAP file.
  • JSON Schema is not produced until a consumer exists (pg_jsonschema CHECK is an option for Step 14, which stores reports).
  • Generated database types stay supabase gen types.

III.5 Build and serving of the wasm

  • cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown, then wasm-bindgen --target web --out-dir packages/core-wasm/pkg; the CLI version is read from Cargo.lock by the install line in CI and Docker. Root script pnpm wasm:build; cargo test -p faunosteo-wasm writes the ts-rs types.
  • Vite 7: await init() lazily (III.3 rule 6), ?url resolution of the .wasm, no plugin. Vitest: init(readFileSync(wasmPath)).
  • Production serving (D-R13): CSP script-src 'self' 'wasm-unsafe-eval' in both DEPLOY.md examples with a sanity-check row; nginx serves a precompressed .wasm.gz (gzip_static) or adds application/wasm to gzip_types; the hashed file name invalidates caches at each deploy. The size budget counts bytes actually served (curl --compressed), proposal: core module ≤ 600 KB compressed, measured at R2 and enforced by a CI check.
  • Debugging: --keep-debug builds in development, Chrome DWARF extension; a vendored 30-line panic hook (the upstream crate is archived).

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 the runtime of II.1 and II.8: one Rust binary replaces the Node process and sharp. The keyless-decoder invariant of STEP8 IV.3 ("the keyed process never decodes") is kept.

IV.1 Process model

container faunosteo_worker (distroless/static:nonroot, read-only, no port, default seccomp)
  faunosteo-worker run                      ← keyed parent (tokio, reqwest, service key)
     poll every 2 s: POST /rest/v1/rpc/claim_avatar_jobs {max_jobs: 1}
     GET  /storage/v1/object/avatars/<quarantine_key>  (≤ 5 MiB, 30 s timeout)
     spawn  faunosteo-worker decode  ← same binary; `decode` is dispatched from a plain fn main
                                       BEFORE any runtime or thread exists; empty env; stdin/stdout
        child: assert Threads: 1 (/proc/self/status) → RLIMIT_AS 512 MiB, RLIMIT_CPU 10 s →
               seccomp allowlist installed with TSYNC, kill on violation (list derived by strace
               over the fixture corpus at the caps on the production image, not hand-written)
        decode: image::guess_format ∈ {jpeg, png, webp} else unsupported_type
                ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB}
                header dimensions before decode (64 ≤ sides ≤ 4096 else dimensions)
                decode (first frame of an animated WebP), apply_orientation (EXIF),
                ICC → sRGB through moxcms when a profile ≤ 1 MiB is present, else assume sRGB
                resize_to_fill 512×512 (Lanczos3), alpha kept
                encode lossy WebP q=82 via libwebp-sys (C, confined to this process)
                stdout: WebP bytes; exit code from a reserved table (never 101, never a signal number)
     parent: read stdout up to 512 KiB (kill past it); parse the RIFF container only: size field =
             byte length, chunk FourCC allowlist {VP8X, VP8, VP8L, ALPH}, canvas 512×512 from the
             VP8X/VP8 header, no EXIF/XMP/ICCP chunk; sha256; size. NO pixel decode in the parent.
     PUT /storage/v1/object/avatars/<object_key> (upsert) → POST rpc/complete_avatar_job
     → DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job
     SIGSYS, SIGKILL (deadline) and RLIMIT deaths are logged with their own internal code
     (syscall number for SIGSYS) and mapped to processing_error; after 20 s the parent SIGKILLs
  sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep
  watchdog: per-stage deadlines (claim 35 s, download 35 s, decode 25 s, upload 35 s, commit 35 s);
            a stage past its deadline exits the process; Docker restarts it
  start-up log: libwebp version (WebPGetEncoderVersion, CI fails below 1.6.0), seccomp status,
            token expiry (service key: none)

The crash matrix, the write order, the lease and attempt rules, the purge grace periods and the fairness rule of the Step 8 analysis apply unchanged. The 60 s single watchdog of the Node proposal is replaced by per-stage deadlines, because one iteration's worst case (three 30 s network calls plus the 20 s child) exceeded it and would have burnt leases during a slow Storage.

IV.2 Comparison with the Node proposal

Aspect Node 24 + sharp (STEP8 II.8) Rust worker Verdict
Decoders on untrusted bytes libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 zune-jpeg (SIMD unsafe, togglable), png (no unsafe, fuzzed), image-webp (forbid(unsafe)), hard Limits Rust better: smaller trusted base, caps by construction
Encoder libwebp via sharp libwebp via libwebp-sys 0.14 (C), in the same sandboxed child, on a buffer that child decoded; the parent checks the container header only equivalent; the C surface is the encoder, process-confined (D-R4 lists the alternatives)
Orientation, ICC, metadata rotate(), ICC → sRGB and stripping by default apply_orientation, moxcms ICC → sRGB, stripping by construction (the encoder writes no metadata chunk) plus the parent's chunk allowlist equivalent, verified rather than assumed
Isolation two Node processes, child without env one static binary, child without env plus rlimits and a traced seccomp allowlist installed before any thread Rust better
Resource bounds limitInputPixels, mem_limit 512m, 20 s kill Limits, RLIMIT_AS, RLIMIT_CPU, 20 s kill, output cap 512 KiB, mem_limit better
Image size and start node:24-alpine + sharp prebuilt ≈ 150 MB distroless/static + one binary ≈ 15 MB Rust better on resources
Transport to Supabase supabase-js with the service key over PostgREST and Storage reqwest calls to the same two APIs with the same key (webpki-roots compiled in for HTTPS on managed) equivalent
Maintenance sharp Renovate rule cargo deny in CI (licences, bans, sources blocking; advisories nightly) equivalent
Managed Supabase URL + key only same equivalent
Build complexity none Rust toolchain stage, cc for libwebp, musl cost accepted by the rule; built in CI, pulled by digest (VIII.1)

IV.3 Worker crates

tokio (rt, process, time, io), reqwest (rustls, json, stream, webpki-roots), serde / serde_json, image (default-features off; jpeg, png, webp), moxcms (version resolved by image), libwebp-sys, sha2, rlimit, seccompiler, tracing + tracing-subscriber (JSON logs, field allowlist, control characters escaped: LRN-044), thiserror. No database driver (one transport, no open DB port on managed, as in STEP8 II.8).

IV.4 Credential: as validated, with one hardening option recorded

The worker holds the service key in .env.worker as the owner validated (STEP8 D1, II.8). A dedicated faunosteo_worker Postgres role with a minted JWT would narrow a leak, but it is independent of the language and is not "at the same cost": it needs the role granted to authenticator (the PGlite shim defines only anon, authenticated, service_role), EXECUTE on the nine worker RPCs plus a new RPC for the key-driven sweep lookup, SELECT, INSERT, UPDATE and DELETE policies on storage.objects for the role (which breaks the pinned census "2 / 1 / 0 per bucket" and the assertion "no UPDATE / DELETE policy exists"), token expiry handling (log exp at start, warn 30 days before, re-mint), a revocation path (REVOKE faunosteo_worker FROM authenticator plus re-mint), and on managed an operator-held signing key. Recorded as a Step 27 hardening option with those prerequisites; not a decision of this study.

IV.5 Tests specific to the Rust worker

  • Decode child fixtures (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 (Linux, on the production image in CI): every accepted fixture passes through the fully sandboxed child (the allowlist is derived, then proven on the corpus at the caps: 4096² RGBA, 16-bit PNG, CMYK JPEG, ICC through moxcms); a disallowed syscall kills the child and the parent logs SIGSYS with the syscall number; /proc/self/environ is empty; Threads: 1 holds when the filter is installed.
  • Parent checks: a child returning 511×511, an EXIF chunk, a wrong RIFF size, 513 KiB of output, or garbage → rejected before any PUT; the child is killed on output overflow.
  • Integration against the local stack (CI supabase job): Alice's full flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2; one HTTPS call in CI proves the CA bundle.

Part V. Libraries retained and their limits

Area Retained Rejected Limits to manage
Serialisation serde, serde_json (custom formatter), thiserror, ts-rs serde-wasm-bindgen, tsify, schemars (until a consumer exists), serde_jcs float printing owned by js_number; field order declared per struct
XML roxmltree + own tree and serialiser quick-xml, usvg as sanitiser (allows DTD, drops silently, rewrites the drawing) depth and size pre-scan until the deep-nesting fix is released
PDF write pdf-writer krilla (no Standard 14 page text, merged dates; candidate for TTF), printpdf (no attachments), lopdf as writer classic xref only (wanted); f32 coordinates (links read back)
PDF read own byte scan + miniz_oxide; lopdf test-only pdf, pdfium in the app same caps as today
Fonts vendored Core 14 AFM (APAFML notice committed); later skrifa + subsetter + harfrust ttf-parser, rustybuzz (RustSec unmaintained) kerning-inclusive width rule reproduced from pdf-lib
PNG png UPNG semantics gate stays ours; decoder under Limits
Raster browser canvas (DOM adapter); resvg native in tools/worker when a need appears resvg in the browser bundle allow_dtd, 1M-element cap and the crop workaround handled by our sanitiser and adapter
Images (worker) image, moxcms, libwebp-sys webp crate, image-webp in the parent, img-parts, infer, wasmtime, extrasafe Limits.max_alloc advisory → RLIMIT_AS is the hard cap; profile size capped
Sandbox seccompiler, rlimit landlock (redundant under the allowlist), user namespaces allowlist derived by tracing, proven on the corpus
Runtime tokio, reqwest (webpki-roots), tracing postgrest, supabase-rs ~10 hand-written endpoints tested against the local stack
WASM wasm-bindgen + CLI (version from Cargo.lock), binaryen when needed wasm-pack crate/CLI lock
Hygiene cargo-deny (licences, bans, sources blocking; advisories nightly and at release) cargo-audit (same database), cargo-chef (BuildKit cache mounts suffice), cargo-fuzz before Step 27 (nightly toolchain; our own parsers only)

Part VI. Progressive migration strategy

VI.1 Principles

  • Freeze with the old code, then switch. Before a phase ports a module, every output that no test pins yet is committed as a golden produced by the TypeScript code (LRN-046): the three archive envelopes, the composed views as parsed trees, the draw log of lines, rectangles and colours. The oracle suites are then ported to cargo on the fixtures in place (JSON fixtures under apps/app/tests/fixtures and packages/*/tests/fixtures, read by path; the two TypeScript fixtures horse-slice.ts and mini-sheet.ts converted to JSON once). No dual-run harness.
  • Consumer-driven deletion. A TypeScript module is deleted in the phase that switches its last consumer; until then it is frozen (no new logic) and its existing goldens keep proving it. The table in VI.4 names the last consumer of every module so nothing is deleted while imported (revision 1 broke this twice).
  • Goldens are never regenerated silently. A phase that changes an oracle (the attachment bytes at R2, the generated seed files at R5) says so in its end criteria and the owner decides.
  • Every phase ends with pnpm check, cargo test --workspace --locked, cargo clippy -D warnings, cargo deny check (licences, bans, sources), Docker builds green, the real-stack pgTAP when SQL changed, the verifier and security gates, the rollback row of VI.3 proven, and a manual validation script for the owner.
  • Phases are gitflow branches (feature/rust-r<n>-<slug>; chore/rust-r0-workspace for the foundation).

VI.2 Phases and end criteria

Phase Content Depends on End criteria (verifiable)
R0 Foundation (inside Step 8) Cargo.toml workspace, rust-toolchain.toml, deny.toml, lints, crates/core skeleton (no app consumer yet), crates/worker skeleton, CI job rust, worker image build, docs/development/RUST.md (setup, commands, boundary rules), DEPLOY.md: images built in CI and pulled by digest, CSP line with 'wasm-unsafe-eval', gzip for .wasm, VPS disk and RAM headroom recorded; rustup on the dev host (owner) none cargo test, clippy, deny green in CI; worker image builds (< 30 MB) and starts against the local stack with no job; panic strategy on wasm32 verified and written in RUST.md; CI duration and runner cache behaviour measured and recorded; no production artifact changed yet
R1 Step 8 worker Part IV: decode child, sandbox, transport, sweeper, per-stage deadlines, compose service, .env.worker.example, the Step 8 migration and app work as analysed R0, Step 8 go STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests on the production image, local-stack integration, real-stack e2e); image non-root, cap_drop ALL, read-only; libwebp ≥ 1.6.0 logged; owner manual validation of the avatar flow
R2 Domain core crates/core domain: sheet document + rules, report v3/v2 + migration, rebase (owner go, D-R12), snapshot/envelope/branding/labels, SheetHandle + SheetIndexData, reducers, build_finding, vertebra_selection, new_report; crates/wasm facade (JSON strings, ts-rs types, poison-and-reinstantiate, lazy init, core_unavailable); packages/core-wasm package; app Dockerfile wasm stage; app switched (SheetProvider, store, click chain, pickers, publish gate); app importers codemodded from @faunosteo/domain to @faunosteo/core-wasm; packages/domain frozen for the TS engine and pipeline; three envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP R0 the domain, service, store, component and route suites pass with their assertions on the core; the three frozen envelopes parse with the frozen Zod schemas and compare semantically equal (bytes differ by decision D-R11); the 39 step6 goldens and the seed golden are untouched (the TS engine and pipeline still run on frozen TS); pnpm build with the wasm; the app boots under the exact production headers (CSP) in a headless check; a wasm load failure leaves /login and /app usable and shows the degraded state in the editor; a deliberate trap re-instantiates the module; served module size ≤ 600 KB compressed; owner manual FR/EN flow
R3 Anatomy core crates/core anatomy: tree, sanitiser, serialiser, layer renderer, compose_view_svg; app canvas on the core (denylist deleted); the TS engine still composes with its frozen TS copy; composed-view trees for the three reports frozen with the TS code first R2 step6 views.*.json unchanged through the app path; composed views DOM-equivalent to the frozen trees; 7 hostile cases + caps + zero-removal (tree compare) in cargo; canvas suite green; one sanitiser reachable from the app (grep)
R4 PDF core (reader + writer + CLI) crates/core pdf: scan, bounded inflate, layered read; layout → draw log → pdf-writer; AFM vendored; png + gate; dates tables; the leniency decisions of I.2 pinned by fixtures; draw-log golden for lines, rectangles and colours frozen with the TS engine first (D-R2); app import in a Web Worker, app export on the two-call design; report-compare tool; packages/pdf deleted (last consumer); frozen TS render/ deleted with it only if the pipeline no longer imports it (it does: kept until R5) R3 39 goldens reproduced exactly through the Rust draw log (text, images), links read back from the written files with lopdf, views via the app path; the new draw-log golden reproduced; scan (39), inflate (9), read (13), security (55), text (5), size (2) suites in cargo; the hostile corpus through the wasm build; BLK-009 browser measurements (Chromium, Firefox, Safari, one low-end phone) recorded in PDF_IMPORT_HARDENING.md §5 as done items (the gate itself stays open until every §5 item is done); poppler or pdfium render diff of the three reports within a stated threshold; the last TS scanner, kept as a test fixture, and the previous release's reader read every R4 fixture PDF; stored attachment < 250 KB; no pdf-lib, @pdf-lib/*, @xmldom/xmldom in the lockfile of apps/app or packages/pdf
R5 Curation pipeline, importer, operator tools crates/core curation + cli bins: import-equine, upload-sheet-assets; outputs emitted by Rust (js_number, markdown tables); .prettierignore on generated dirs; seed golden regenerated once (decided); review drawings compared as parsed trees against the xmldom-era files; packages/anatomy and packages/domain deleted (last consumers); CLAUDE.md folder map, packages/README.md, WORKSPACE.md, CHANGELOG R2, R3, R4 seed.golden.test green on the regenerated set; determinism (two runs byte-equal), counts (27/792/612/41, 811 nodes), 612-leaf semantics unchanged; documentSha256 changed once and the import of an older archive shows the rebase message with 0 unresolved items on identical content; no TypeScript business logic outside UI glue (grep census in RUST.md); workspace test count reconciled with the deleted-tests list (TEST_STRATEGY §6)

Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 right after Step 8 and before Step 9, so that every later step writes its rules in Rust. R3, R4 and R5 before Step 13 (which needs the sanitiser in the worker), interleaved with Steps 9 to 12, which touch no module these phases move. The TTF font change is a separate later change with its own golden regeneration (D-R2).

VI.3 Rollback per phase

Production rollback is "deploy the previous image by digest" (VIII.1), so each phase states what the previous build must still read.

Phase Artifacts written by the new build What N-1 must read Proof
R1 avatars (WebP) the app only displays them; the Node proposal never shipped none needed
R2 drafts in osteo:draft and archives in osteo:archive written by the core (struct order, js_number); PDFs still written by the frozen TS engine from core-produced reports N-1 (Step 7 build) parses the draft and the envelope with its Zod schemas N-1 reader test on the frozen fixtures; a draft N-1 cannot parse goes to the quarantine key with a notice (never discarded)
R3 none persisted (canvas only) n/a
R4 PDFs from pdf-writer (classic xref, same attachment, same stamp) N-1 scanner finds the attachment and the stamp; Step 6 build reads bare v3 and envelope the kept TS scanner fixture and the previous release's reader read every R4 fixture PDF; DEPLOY.md rollback note updated as for Step 6
R5 regenerated seed (new documentSha256) N-1 app bundles the old seed and rebases archives written on the new one (visible message, nothing lost); reports written on the old seed rebase on the new build rebase tests both ways on the two seeds

VI.4 What is deleted when (last consumer named)

Module Consumers today Last consumer switched at Deleted at
services/zoneInteraction.ts, component data-building rules, store rules app R2 R2
packages/domain Zod contracts and functions app (R2), TS engine (R4), TS pipeline (R5), scripts (R4) R5 R5 (packages/domain removed; app imports codemodded at R2)
anatomy/drawing.ts denylist app canvas R3 R3
packages/pdf/src/svg/** (sanitiser, view) TS engine R4 R4
packages/anatomy/src/render/** app (R3), TS engine (R4), TS pipeline app-review.ts (R5) R5 R5
packages/pdf/src/** (reader, writer, attachment, branding gate), apps/app/scripts/**, browserRasterizer.ts stays app, CLI R4 R4 (browserRasterizer.ts kept as the DOM adapter)
packages/anatomy/src/{legacy,curation,cli}/**, packages/supabase/scripts/upload-sheet-assets.ts operator R5 R5
packages/anatomy, packages/domain, packages/pdf packages R4 (pdf), R5 (anatomy, domain)

Part VII. Adaptations to the development plan

Step Plan text today Adaptation under the rule
8 Files Node worker + sharp (STEP8 D1) D1 reads "native Rust worker"; R0 + R1 inside the step; apps/worker is not created; crates/worker is; service key kept (IV.4)
9–12 TS mirrors of SQL rules (verification status machine, contact normalisation) mirrors in crates/core domain, called through the wasm; UI unchanged
13 Sheets in DB SVG processor "from packages/pdf" the R3 sanitiser runs in the worker's decode child (same isolation as images); the Supabase SheetProvider stays TS glue, parsing through the core
14 Cloud reports autosave, revisions, TS persistence adapter adapters TS; diff/throttle rules in the core; optional pg_jsonschema CHECK from a schemars export (decision at the step, first consumer of JSON Schema)
15 PDF artifacts + import "Zod validation server-side: Edge Function or staging row"; artifacts = PDFs generated by the browser the worker validates the attachment with the core reader (R4); no Edge Function; server-side rendering is not in the plan; if a need appears, resvg native between the two core calls
16 Offline outbox in TS IndexedDB glue TS; replay/dedupe/conflict rules in the core
17 Sheet editor editor store with undo, geometry document operations and geometry as a core module, UI React
19 Notifications/worker apps/worker Node, EmailProvider, private.jobs, packages/i18n for templates crates/worker run gains the private.jobs loop (RPC with SKIP LOCKED) and templates rendered in Rust from Rust-side dictionaries; packages/i18n stays UI-only
20–21 Agenda, travel expiry rule TS mirror, routing adapter, "Edge Function or worker endpoint" for the Google OAuth callback mirror in the core; routing and calendar sync in the worker; the callback is the first inbound route of the worker's serve subcommand (axum, one route, behind the reverse proxy)
22 Public web Q8 framework Astro (global rule), D-R8
23 Billing "Edge Function stripe-webhook" serve hosts the webhook (signature check, idempotency table unchanged)
24 Imports adapters in the Node worker Rust adapters (csv, calamine, zip), same ImportAdapter contract
26 Lifecycle export/archive/restore jobs in the Node worker Rust jobs in the same binary
27 Hardening adds cargo deny advisories, the sandbox tests and the cargo-fuzz run (nightly toolchain, our own parsers) to the release gate; the worker-role option of IV.4 evaluated here
BACKEND_ARCHITECTURE §6 Edge Function row "Rust service (worker serve)"; PostgreSQL rows unchanged
WORKSPACE.md, packages/README.md apps/worker Node, @faunosteo/i18n for the worker crates/*; i18n package UI-only
TEST_STRATEGY.md layers adds the cargo layer, the freeze-then-switch rule, the N-1 reader test and the conformance fixtures shared with pgTAP

Part VIII. Docker, Supabase and CI impacts

VIII.1 Docker and deployment

  • Images are built in CI (or on the dev host) and pulled by digest. The VPS (1 vCPU, 1 GB) never compiles Rust: docker compose up --build on the VPS is replaced by docker compose pull && up -d on tagged images (registry: the Gitea container registry of the forge, or Scaleway's); rollback = the previous digest. This is a prerequisite recorded in R0 and written into DEPLOY.md (routine deploys, rollback, disk headroom).
  • App image: a first stage FROM rust:1.99.0-bookworm AS wasm (BuildKit cache mounts on ~/.cargo and target, pinned wasm-bindgen-cli) producing packages/core-wasm/pkg; the committed packages/core-wasm/package.json is in the manifest COPY list so pnpm install --frozen-lockfile keeps working; the Node builder copies pkg/ before pnpm build; nginx serves .wasm (and .wasm.gz with gzip_static) with the hashed name.
  • Worker image: rust:1.99.0-alpine3.24 builder (musl, musl-dev, build-base for libwebp's cc build) → distroless/static:nonroot (CA bundle present; scratch rejected), one static binary. Compose service worker (container faunosteo_worker): read_only: true, tmpfs: /tmp, cap_drop: [ALL], security_opt: [no-new-privileges:true], mem_limit: 512m, cpus: 1, pids_limit: 64, no ports, Supabase internal network only, restart: unless-stopped, env_file: .env.worker. The default Docker seccomp profile stays (it permits the inner filter).
  • Naming: faunosteo_worker, image faunosteo/worker (BDR-035).

VIII.2 Supabase

  • No schema change comes from the rule itself.
  • Conformance fixtures for sheet_document_issues land as a generated pgTAP file with inlined fixtures (PGlite and real stack), owned by R2.
  • Managed migration: the worker container is hosting-agnostic (URL + key); HTTPS works out of the box (webpki-roots, distroless CA bundle, one HTTPS call tested in CI).

VIII.3 CI (.gitea/workflows/ci.yml)

  • New job rust (runs before check): toolchain from rust-toolchain.toml (dtolnay/rust-toolchain), cargo fmt --check, cargo clippy --workspace --all-targets -D warnings, cargo test --workspace --locked, cargo deny check licenses bans sources, pnpm wasm:build, artifact packages/core-wasm/pkg uploaded. Cache: Swatinem/rust-cache if the Gitea cache server works (verified at R0), else a directory cache on the runner host.
  • check downloads the artifact before pnpm install. docker builds both images and pushes them by tag and digest on main and develop. supabase runs the worker integration test against the local stack.
  • Nightly: cargo deny check advisories; from Step 27, the fuzz run.

VIII.4 Local development

  • Owner action: install rustup (lives in ~/.cargo, no global package); the pinned toolchain installs itself from rust-toolchain.toml; wasm32-unknown-unknown target; cargo install wasm-bindgen-cli --version <from Cargo.lock> 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 (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), goldens unchanged except where a decision regenerates them, pgTAP unchanged, the N-1 reader test green at every phase.
  2. No duplicate business logic at the end of a phase, by the consumer-driven deletion table (grep census in RUST.md); hand-written TS mirrors of core helpers are not allowed (the core precomputes what React needs).
  3. Security gates: the security-auditor runs on every phase; the worker sandbox tests run on the production image; cargo deny licences, bans and sources block, advisories gate releases.
  4. Operability: worker image size, start time, memory ceiling, libwebp and seccomp status logged at start; a runbook line per failure mode in STORAGE.md; deploy and rollback never compile.
  5. Cost visibility: CI duration and the served module size recorded in each phase's TODO note.

IX.2 Risks

Risk Likelihood Effect Mitigation
Rust skills and velocity on a one-person team high at first slower steps 8 to 12 R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; frozen oracles catch what review misses
Dual toolchain in CI and Docker certain CI minutes caches; wasm artifact reused by check; images built once, pulled by digest
WASM module as a point of failure (CSP, 404 after deploy, trap, memory growth) medium editor unusable or tab memory CSP line and headless check at R2; lazy init with core_unavailable; poison-and-reinstantiate; reader in a terminated Web Worker; hashed file name
Hidden JS semantics in outputs and readers (float printing, upper-casing, ICU dates, kerning widths, rounding, lenient decoding, duplicate keys, .int(), \s) high golden mismatches or stricter readers refusing old files the I.2 list with a fixture each before the owning phase; leniency decisions recorded; N-1 reader test
Sheet identity hash changes at R5 certain every older archive rebases once on import (message, nothing lost) stated in R5's criteria and in the CHANGELOG; rebase tested both ways
Goldens regeneration governance medium silent layout drift the Step 6 rule: owner decision per regeneration; relaxed fields never widened without a decision
Crates maintained by one person (zune-jpeg, moxcms, libwebp-sys, ts-rs, krilla) medium abandonment cargo deny unmaintained advisories; alternatives in Part V; decoders confined to the child; the boundary has no third-party crate
roxmltree deep-nesting overflow (fix unreleased) known parser DoS depth cap by byte pre-scan; pin the fixed release
seccomp allowlist killing a valid decode medium if hand-written valid photos rejected after three leases derived by tracing, proven on the corpus at the caps in CI, SIGSYS logged with the syscall number
VPS resources certain OOM or full disk during a build never build on the VPS (VIII.1); disk headroom recorded
Gitea runner caches for Rust unverified slow CI measured at R0; host-level cache fallback
wasm-bindgen crate/CLI version lock certain broken builds on drift one version read from Cargo.lock by the install lines
Two implementations lingering medium drift, double maintenance VI.4 last-consumer table is part of each Definition of Done
Public web framework conflict certain decision needed D-R8

IX.3 Explicit non-goals of the rule

  • Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos, Dioxus): excluded by the owner's retained list and the validated mockups.
  • Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer: excluded (retained list; RLS stays the boundary).
  • Running Rust inside PostgreSQL (pgrx): excluded by managed compatibility.
  • Moving SQL transactional rules to Rust: excluded.
  • Shipping resvg to the browser: excluded (size, no visual change wanted).

IX.4 Unverified items (settled at R0 or at the phase that needs them)

  • Panic strategy and catch_unwind on stable wasm32-unknown-unknown for the pinned toolchain (handled as abort regardless).
  • resvg byte-identical output native vs the Node test adapter (README claim; matters only if a server-side rendering need appears).
  • Exact libwebp version string in libwebp-sys 0.14.4 (≥ 1.6.0 by API presence; logged at start, checked in CI).
  • serde_json/zmij exponent thresholds vs JavaScript (the js_number formatter is tested on the committed overlays regardless).
  • Gitea runner support for Swatinem/rust-cache; cold build times on the runner; registry choice for images.
  • Core wasm size and instantiate time (measured at R2).
  • The syscalls a static-musl decoder needs (mprotect, madvise, rt_sigreturn, tkill…): derived by tracing at R1, never assumed.

Part X. Decisions for the owner

Id Question Recommendation
D-R1 Workspace layout Three crates: core (feature-gated library with tool binaries), wasm (facade), worker (binary); no crate per module, no crates/editor
D-R2 PDF engine Reader and writer ported together at R4 with the Standard 14 AFM metrics (goldens exact); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port (additive); TTF fonts as a separate later change with its own regeneration
D-R3 Rasteriser Browser canvas stays the app's rasteriser between the two core calls; resvg native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle
D-R4 Lossy WebP encoder libwebp-sys 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (ravif, pure Rust, changes D4's format)
D-R5 Sheet identity at R5 documentSha256 = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives rebase on import with a visible message and 0 unresolved items (as any content changeset); no Prettier dependency kept
D-R7 Form validation Stays TypeScript (React-bound); a separate chore gives the constraints one home: a hand-written constants module checked by a PGlite test against pg_constraint and config.toml, with the counting rule recorded
D-R8 Public web (Step 22) Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the site needs no islands
D-R9 Edge Functions Retired from the plan (limits, hand deployment, one Rust runtime); webhooks and OAuth callbacks served by the worker's serve subcommand behind the reverse proxy
D-R10 Order R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9–12
D-R11 Archive attachment bytes New contract adopted at R2 (declared field order, js_number, optional absent / nullable null); every previous reader keeps parsing it (N-1 reader test, permanent); the bytes of existing PDFs are untouched
D-R12 Gated functions Explicit go to port readArchiveDocument, readReportArchive, readAttachedDocument and rebaseReportOnSheet with behaviour preserved (CLAUDE.md gate)
D-R13 Serving the wasm in production CSP script-src 'self' 'wasm-unsafe-eval' in both DEPLOY.md examples, gzip for .wasm, images built in CI and pulled by digest (no compile on the VPS), served module ≤ 600 KB compressed enforced in CI
D-R14 BLK-009 and the reader R4 runs the reader in a terminated Web Worker and records the §5 browser measurements; the external-user import gate (BDR-040) stays open until every §5 item is done, never closed by R4 alone

The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native Rust worker" from this review on; the worker credential stays the service key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1 (that role) is therefore no longer a decision of this study, which is why the numbering skips it.


Annex A. Decision table (expanded for the owner's validation, 2026-10-12)

Orientation validated by the owner on 2026-10-12 with ten principles (Rust worker at Step 8, Cargo workspace, native and WASM libraries, progressive anatomy migration, PDF migration under complete compatibility proofs, React and PostgreSQL/Supabase kept, testable increments with rollback, no premature deletion of TypeScript still in use, fully dockerised infrastructure with production builds outside the small VPS, WASM compatibility with the production CSP proven before activation). The detailed decisions below await validation. Impact tags: SEC security, HIST historical data, PERF browser performance, UI interfaces, DEPLOY deployment.

Id, subject Recommendation Relevant alternatives Advantages / drawbacks Risks If validated Impacts
D-R1 workspace layout Three crates: core (feature-gated library, tool binaries behind cli), wasm (cdylib facade), worker (binary) Six crates per boundary (rev 1); one crate holding the facade too (wasm-bindgen would pollute native builds); one crate per module One dependency graph and one test run; features keep the worker lean / feature combinations must be tested in CI (--no-default-features, --all-features); core compile time grows with modules Accidental I/O or clock in core (lint disallowed_methods); feature creep R0 creates the three crates and the lint set none
D-R2 PDF engine Reader and writer ported together at R4 on pdf-writer with the Standard 14 AFM metrics (kerning-inclusive widths); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port; TTF fonts as a separate later change Reader first, writer later (two phases, longer hybrid); writer on krilla + TTF at once (no Standard 14 page text, goldens regenerated blind); keep pdf-lib for writing (unmaintained, contradicts the rule) The 39 goldens stay the exact oracle; packages/pdf deleted in one phase; no object streams by construction / largest single phase; AFM files vendored under the APAFML notice Kerning, rounding, ICU dates or f32 coordinates moving a run (caught by goldens and the lopdf read-back); viewer compatibility of classic xref (standard) Golden regeneration decision for the additive draw-log golden; the gated functions port (D-R12); rollback note in DEPLOY.md as for Step 6 HIST, DEPLOY
D-R3 rasteriser Browser canvas stays the app's rasteriser between the two core calls; resvg native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle resvg lazy-loaded in the browser (949 KB gzip, anti-aliasing change, new raster goldens); resvg everywhere for identical bytes server and browser No bundle growth, no visual change, no golden change / browser and future server renderings would differ (only matters if server rendering appears) Browser rasteriser limits unmeasured (true today already) Export becomes compose_export_views → rasterise → write_archive; browserRasterizer.ts kept as DOM adapter PERF, UI
D-R4 lossy WebP encoder libwebp-sys 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; output checked by the parent at container level only Lossless WebP via image-webp (pure Rust; avatars 5 to 10× larger); AVIF via ravif (pure Rust, slower encode, changes D4's format); wait for a pure-Rust lossy encoder (oxideav-webp, months old) Standard output, small files, mature encoder / C compiled in the worker build (Alpine build-base), vendored version invisible to RustSec (logged at start, checked in CI) libwebp CVEs (historically decoder side); mitigation = process confinement, rlimits, seccomp, version check R0 spike proves the musl static build with cc; R1 implements SEC, DEPLOY
D-R5 sheet identity at R5 documentSha256 = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives and drafts rebase once with a visible message and 0 unresolved items Keep a Node Prettier step to preserve the bytes (rev 1; chains the identity to a JS formatter); hash of canonical JSON (RFC 8785, serde_jcs): identity independent of formatting forever, one more concept Simplest rule, matches today's semantics (the file is the identity) / one import notice per old archive after R5 None on data (rebase keeps everything); user confusion if the message is not worded for "identical content" R5 regenerates the seed golden knowingly; CHANGELOG entry; the import and restore messages re-read for the 0-unresolved case HIST, UI
D-R7 form validation Stays TypeScript (React-bound); a separate chore gives the constraints one home (hand-written constants module checked by a PGlite test against pg_constraint and config.toml, counting rule recorded) Rust validation through the wasm per field (render-path calls on every keystroke); constants generated from the SQL migrations (rev 1: a DDL interpreter for eleven numbers) Forms stay responsive and simple; the drift found by the inventory is closed / constants hand-written (kept honest by the test) low A small chore branch, any time; no UI change UI
D-R8 public web (Step 22) Keep Astro (global SEO/GEO rule); record the Rust exception Zola (Rust static generator, no islands, no React); Leptos/Dioxus SSR (immature SEO tooling, contradicts "React stays"); Next.js (global rule names Astro) SEO/GEO tooling and islands / a TypeScript app in a Rust-by-default repository none now Exception recorded; Step 22 brainstorm re-checks per the global rule DEPLOY
D-R9 Edge Functions Retired from the plan; webhooks and OAuth callbacks served by the worker's serve subcommand behind the reverse proxy Edge Functions (Deno can run the wasm core; limits, hand deployment on self-hosted); a separate HTTP container; pg_net/pg_cron for some jobs One runtime, one image, Rust / the worker gains an inbound route at Steps 21 and 23 and uptime expectations Inbound surface (signature checks, proxy rate limits, monitoring at Step 27) BACKEND_ARCHITECTURE.md §6 updated; Steps 21 and 23 designs change SEC, DEPLOY
D-R10 order R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9 to 12 R2 after Steps 9 to 12 (more TypeScript rules to migrate twice); R3 to R5 after Step 13 (impossible: the Rust worker needs the Rust sanitiser at Step 13) Every later step writes its rules in Rust once / Steps 9 to 12 slowed by the migrations Velocity of the functional steps TODO order; Step 9 starts after R2 DEPLOY
D-R11 archive attachment bytes New contract adopted at R2: declared field order (struct order), js_number floats, optional absent, nullable null; every previous reader keeps parsing it (permanent N-1 reader test); existing PDFs untouched. At R2 the frozen TS engine still writes the attachment from the core's objects (order changes, floats printed by JS); at R4 the Rust writer serialises fully Reproduce the insertion order of the TS store exactly (fragile mirror); keep TS serialisation of the attachment until R4 (same end state, same key-order change) Declared and testable order / byte diff against pre-R2 exports (no reader depends on order; Zod ignores it) A reader depending on key order (none known) Struct field orders documented; N-1 reader test added at R2 and kept HIST
D-R12 gated functions Explicit go to port readArchiveDocument, readReportArchive, readAttachedDocument and rebaseReportOnSheet with behaviour preserved (CLAUDE.md gate) Keep the TypeScript readers and rebase permanently (two implementations, contradicts the rule) One reader for browser, worker and tools / the highest-stakes port (user data) Behaviour drift on archives; mitigation = exact-object oracles, all fixtures, hostile corpus through the wasm build, N-1 test The port follows the oracle suites; any behaviour change needs its own decision SEC, HIST
D-R13 serving the wasm CSP script-src 'self' 'wasm-unsafe-eval' in both DEPLOY.md examples; gzip for .wasm; images built in CI and pulled by digest (no compile on the VPS); served module ≤ 600 KB compressed enforced in CI; registry = the forge's Gitea container registry (recommended; Scaleway Container Registry as alternative) 'unsafe-eval' (broader, rejected); inline the module as base64 (CSP still applies, bigger); Brotli (nginx module needed); build on the VPS (rejected) Minimal CSP relaxation specific to WebAssembly; deploy and rollback never compile / 'wasm-unsafe-eval' needs Chrome 97+, Firefox 102+, Safari 16+ (Vite 7 baseline); an older browser lands in core_unavailable Registry credentials on the VPS; CSP forgotten on one proxy (sanity-check row) DEPLOY.md rewritten at R0 (procedure prepared, applied at the first image deployed: worker at R1); the deploy procedure change is validated separately SEC, PERF, DEPLOY
D-R14 BLK-009 and the reader R4 runs the reader in a terminated Web Worker and records the PDF_IMPORT_HARDENING.md §5 browser measurements (Chromium, Firefox, Safari, one low-end phone); the external-user import gate (BDR-040) stays open until every §5 item is done Main-thread synchronous reader (memory never shrinks, UI blocked); server-side import only (Step 15) Bounded blast radius, measurable, import off the main thread / a second instantiation per import; a browser runner (Playwright) introduced for the measurements Safari worker + wasm specifics; measurement effort R4 includes the browser measurement campaign; the gate stays open SEC, PERF

Annex B. R0 scope (owner's clarification request, 2026-10-12)

R0 is the foundation phase inside Step 8. It changes no production artifact, implements no feature and starts only on the owner's go.

B.1 Toolchain, reproducible in Docker

  • Reference build environment = a Docker builder image (docker/rust-builder.Dockerfile, FROM rust:1.99.0-bookworm, plus wasm32-unknown-unknown, wasm-bindgen-cli at the version in Cargo.lock, cargo-deny, binaryen for wasm-opt), used by CI and by the application and worker image builds. The worker's own builder stays rust:1.99.0-alpine3.24 (musl, build-base for libwebp).
  • The development host may install rustup for the inner loop (same rust-toolchain.toml, so the same compiler); the containerised build is the arbiter. Root scripts: pnpm rust:check (fmt, clippy, test, deny) and pnpm wasm:build, each runnable locally or through the builder image (docker run --rm -v "$PWD":/w).
  • The production VPS never gets Rust: it pulls images by digest.

B.2 Workspace

  • Cargo.toml (workspace, [workspace.dependencies], [workspace.lints]: unwrap_used, expect_used, disallowed_methods for std::time, std::fs, std::env in core), rust-toolchain.toml, rustfmt.toml, clippy.toml, deny.toml, .cargo/config.toml (wasm stack size, -C link-arg=-zstack-size).
  • crates/core (modules declared, SheetRef + Locale types, the js_number formatter, the conformance fixture loader), crates/wasm (facade exporting core_version() and one JSON round-trip call), crates/worker (binary with run printing its configuration and decode wired to the sandbox spike, no job logic).
  • packages/core-wasm/package.json committed, pkg/ ignored.

B.3 Docker and CI

  • Worker image built from the skeleton (Alpine musl builder → distroless/static:nonroot), started once in CI against the local stack with no job (proves transport configuration, CA bundle, non-root, read-only).
  • Application image: the wasm stage added and exercised in CI, its output not loaded by the application until R2.
  • CI job rust before check: fmt, clippy, test, cargo deny check licenses bans sources, wasm build artifact; docker job builds both images; registry push by tag and digest prepared (registry decision in D-R13); nightly advisories job; CI duration and runner cache behaviour recorded in RUST.md.

B.4 Feasibility proofs (experimental, each one a permanent test)

Proof Why it conditions a choice How Lives on as
Panic strategy on wasm32 III.3 rule 5 (poison and re-instantiate) a facade call that panics; observe WebAssembly.RuntimeError; re-instantiate; call again; try a deep recursion at the configured stack size vitest in packages/core-wasm
Serialisation contract D-R11, I.2 (js_number, optional vs nullable) parse report-v3.demo.json and document.json with serde, re-emit through the custom formatter, compare byte for byte with JSON.stringify(JSON.parse(x), null, 2); a struct with optional and nullable fields parsed by the current Zod schemas cargo test + vitest N-1 reader seed
musl static binary with libwebp (cc) D-R4 build the worker skeleton with libwebp-sys on the Alpine builder; log WebPGetEncoderVersion the worker image build in CI
seccomp allowlist derivation and application Part IV (traced allowlist, Threads: 1, TSYNC) decode spike: minimal image decode of one JPEG, one PNG, one WebP at the caps, traced with strace -f in the production image under Docker rootless; filter installed before any thread; disallowed syscall kills the child; environment empty the sandbox test of R1
CSP with 'wasm-unsafe-eval' D-R13, owner principle "proven before activation" serve the wasm artifact under the production nginx config with the DEPLOY.md headers in headless Chromium: instantiation succeeds with the keyword, fails without it; result written in DEPLOY.md CI headless check
Served size and instantiate time D-R13 budget measure raw and gzip bytes of the skeleton module and its instantiate time; set the budget check CI size check
Runner caches and build times VIII.3 time the cold and warm rust job with and without Swatinem/rust-cache on the Gitea runner RUST.md numbers

B.5 R0 exit criteria

cargo test, clippy, deny green in CI through the builder image; worker image < 30 MB, non-root, starts against the local stack; the seven proofs recorded in RUST.md with their numbers; DEPLOY.md rewritten (pull by digest, CSP line, gzip, VPS headroom, rollback = previous digest) without touching the live deployment; pnpm check unchanged; no production artifact changed. Owner validation closes R0; R1 (the Step 8 worker) starts on a separate go.


Annex C. Owner validation and amendments (2026-10-12)

Revision 2 validated with the amendments below. The rule stays definitive: Rust by default whenever it gives an equivalent or better result with no functional, practical, graphical, security or reliability loss. R0 may start; R1 waits for a separate go; release 0.2.0 waits for its own validation.

Validated as recommended: D-R1 (three crates), D-R2 (reader and writer at R4 after the oracles exist), D-R3 (browser canvas, no resvg in wasm), D-R7 (form validation in TypeScript), D-R8 (Astro exception, re-evaluated at Step 22), D-R10 (order R0–R5), D-R11 (deterministic serialisation with old-reader compatibility), D-R12 (gated PDF functions ported with identical behaviour), D-R14 (import in a Web Worker, security controls kept before public opening).

Amended:

Id Amendment
D-R4 WebP libwebp in C is allowed only inside the isolated processing child. The parent checks the validity and the limits of the produced result before any use (container structure, dimensions, size, absence of metadata). The native libwebp version actually linked into the build is known and controlled (logged at start, checked in CI). The migration must not introduce new unmanaged risks.
D-R5 sheet fingerprint Preference for a deterministic fingerprint over a canonical JSON representation independent of the formatter (Prettier or Rust): study RFC 8785 (JCS) or a strictly defined alternative, so that a purely technical serialisation change never causes needless rebases. Explicit compatibility with the fingerprints and archives already produced. Existing fingerprints are not changed now: the decision is prepared for R5 and its implications verified before the switch.
D-R9 Rust HTTP services Business Edge Functions replaced by Rust services where appropriate. Shared code but distinct processes for the job worker and the future exposed HTTP endpoints; they may come from the same Docker image run with different subcommands. Each service holds only the secrets, permissions, resources and protections it strictly needs. Supabase Auth keeps the OAuth mechanisms it already handles.
D-R13 WASM, CI, deployment CSP compatibility with 'wasm-unsafe-eval' validated experimentally, without widening JavaScript permissions. Rust/WASM builds reproducible in Docker and run in CI. Images identified by digest and a rollback strategy prepared. No automatic deployment to the VPS; no publication or promotion of a production image without an appropriate workflow and a validation; the VPS never needs to compile the Rust project.

R0 scope confirmed as Annex B, with these instructions: the seven proofs run in the real environment as far as possible, the unconfirmed hypotheses (serialisation, wasm panics, musl, seccomp) verified experimentally, a proof that cannot be obtained reported as a blocker rather than assumed; during R0 the React application, Report v3, PDF v2/v3, Supabase, the interfaces and the existing tests stay unchanged; the WASM integration does not force the frontend to load the module; no anatomy, PDF or business validation migration (R2–R5); no avatar processing (R1); everything dockerised, the production image produced in CI and pulled by the VPS; the live deployment untouched; no tag or merge into main.

C.1 Addendum 2026-10-13: development environment and CI status (owner brief after R0)

R0 delivered and validated on the architecture. The owner corrected the development organisation before closing R0; these points amend Annex B §B.1 and VIII.4 and are implemented on feature/rust-r0-foundation:

  • Three environments, three roles. The development machine is a self-hosted Ubuntu server (native, not WSL, not the VPS) with Docker rootless: Rust is developed and compiled natively there (user-level rustup, channel of rust-toolchain.toml, wasm32-unknown-unknown, wasm-bindgen-cli and cargo-deny at the pinned versions; cargo check / test / build / clippy / fmt and the browser module build run without Docker). Docker on that machine runs the Faunosteo services (Supabase), the worker in its hardened container, the integration tests, the sandbox and seccomp proofs, and builds the deployment images (multi-stage). The production VPS is separate and never compiles.
  • The R0 builder image is kept as the reproducible alternative (pnpm rust:check:docker, pnpm wasm:build:docker) and as the reference for a future runner; it is no longer the arbiter of daily work and is not required for a compile or a test. The worker's isolation is unchanged.
  • No CI/CD is operational on the forge (no runner, secret or registry). The workflow files are prepared material for a separate CI/CD decision; a workflow is never reported as passed before it has run on the forge. The pre-merge gate is local: pnpm check:all (scripts/check-all.sh), which a future runner calls as is.
  • Target of that future step (planned, not yet built): tests on every push and pull request, Rust and TypeScript checks, PostgreSQL/RLS tests, Docker builds, security checks, branch verification before a merge, image publication only in an explicitly authorised workflow.
  • R1 (the Step 8 worker) waits for the owner's final validation of this correction; no deployment, no release 0.2.0.