77 KiB
Rust by default: architecture review and migration roadmap
Status: study for the owner's decision, 2026-10-12, revision 1 (three independent plan challenges follow; their findings will be folded into a revision 2). Nothing implemented. Applies the owner's brief of 2026-10-12: Rust becomes the preferred language for everything that can reasonably be written in Rust, for new work and for existing code; equivalence suffices; "already in TypeScript" and "more work" are not reasons to keep TypeScript; a component kept in another language needs a concrete constraint.
Part I states the facts (inventory of the code, the hidden contracts a port must honour, the state of the Rust ecosystem on 2026-10-12, verified by three research agents against crates.io, RustSec, GitHub and the Supabase docs). Part II classifies every module (A now, B later with a trigger, C exception). Part III is the target Rust architecture (workspace, boundaries, bindings). Part IV is the Step 8 worker in Rust. Part V lists the libraries retained and their limits. Part VI is the progressive migration with end criteria. Part VII adapts the development plan. Part VIII covers Docker, Supabase and CI. Part IX gives validation criteria and risks. Part X lists the decisions the owner has to take. Section 0 states what this study pushes back on.
Companion material: STEP8_FILES_ANALYSIS.md (the design this review keeps,
with the worker runtime replaced), PDF-FORMAT.md, ANNOTATION-RENDERING.md,
ANATOMICAL_SHEET_MODEL.md (contracts that stay as they are).
0. What this study pushes back on (read first)
- Where Rust actually buys something here. The browser already runs
memory-safe code, so "Rust is safer" is not an argument for the SPA. The
real gains are elsewhere: one core that runs identically in the worker, in
CLI tools and in the browser (server-side PDF import and rendering arrive at
Step 15 and need exactly the engine the browser has); untrusted bytes
(images, SVG, PDF attachments) parsed on the server in a language with
hard allocation caps and without libvips, libpng or xmldom in the trusted
base; the removal of three dependencies the project already distrusts
(
pdf-libunmaintained since 2021, BLK-009; UPNG trusting its input;DecompressionStreamas the only inflater on every read path); and the unification of two things the inventory found duplicated today (two SVG sanitisers, two view compositions, twoformatDate, four copies of the bilingual fallback). The study claims these gains and no others. - The rule has a standing cost the project must own. Two toolchains in CI and Docker, a WASM boundary to design and debug, Rust skills on a one-person team, parity harnesses to write and then delete. The study makes each cost visible (Part VIII, Part IX) instead of hiding it in the word "equivalent".
- The PDF engine is the riskiest migration and has the least standalone value until a server consumes it. It is classified B with an explicit trigger (Step 15 or the TTF font change, whichever comes first), not A. Moving it now would spend the largest effort on the module with the strongest goldens and no product change.
- Rust does not remove the SQL mirror.
private.sheet_document_issuesstays SQL because managed Supabase runs no custompgrxextension; Rust replaces the TypeScript side of the pair, not the pair. - Two hidden contracts bind the curation pipeline to the JavaScript
toolchain. The sheet identity
documentSha256is the sha256 of the Prettier-formatted JSON text, and generated coordinates are raw JavaScript number strings. A Rust pipeline either keeps a Prettier formatting step (recommended) or changes the identity rule under a schema migration. - One global rule conflicts with the new one. The global CLAUDE.md mandates Astro for public sites; the Rust rule would prefer a Rust static site generator. The study recommends keeping Astro and records the conflict as a decision (D-R8), not a silent choice.
- Form validation stays TypeScript by the owner's own retained list (code directly tied to React). The constraints themselves must stop being written in two places (Zod and SQL CHECKs); the study proposes where the single source lives.
Part I. Facts
I.1 Inventory of the existing code
Sizes are TypeScript lines (wc -l, .d.ts excluded), HEAD aae0b39.
Test counts are static (it plus .each rows), except where a suite was run.
| Unit | Source | Tests | Runs where | Purity today |
|---|---|---|---|---|
packages/domain |
18 files, 2,298 lines; zod 3.25 only | 9 files, 162 cases (194 at runtime, one file re-imports another) | browser (app), engine, scripts | entirely pure: no JSON.stringify, no Date, no ids, no I/O; host APIs structuredClone, TextEncoder, Object.hasOwn, new URL() via Zod |
packages/anatomy |
43 files, 4,897 lines: legacy importer 1,842, curation 2,329, render 553, cli 119 | 15 files, 130 cases (run: 130/130) | render only at application runtime (app canvas, PDF composition); the other 4,344 lines run for pnpm import:equine, the pipeline and tests |
render is pure (plain LayerElement tree); importer and pipeline use xmldom, node:fs, node:crypto, Prettier |
packages/pdf |
27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom | 9 files, 137 cases | browser (export, import), CLI, tests | explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: DecompressionStream on every read path, Intl.DateTimeFormat for dates, TextEncoder/Decoder |
packages/supabase |
949 lines (596 generated database.types.ts) |
6 files; PGlite harness runs 9 pgTAP files, 280 assertions | browser, CI | two rules only: GoTrue error code → closed AuthFailure kind (23 codes → 13 kinds), publish gate (Zod + assertPublishable before the RPC); the rest wraps supabase-js |
apps/app/src logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) |
37 files, 2,476 lines (1,708 without the two 281-key dictionaries) | 42 files, 214 cases + 7 .each blocks |
browser | services/zoneInteraction.ts (213 lines) is pure; stores are Zustand glue around domain calls; drawing.ts is DOM (DOMParser, importNode) with an app-local denylist sanitiser |
apps/app/src UI (components, routes, styles) |
65 files, 4,838 lines | component and route suites | browser | React; carries some business rules (I.3) |
apps/app/src/pdf + scripts/ |
4 files, 235 lines + 2 files, 549 lines | 65 PDF-related app cases + 11 CLI cases | browser / Node | branding from bundled logos, Image + canvas rasterizer; CLI report:compare on the engine scanner |
apps/app/vite/sheet-bundle.ts |
102 lines | 7 | Vite build | Vite plugin: virtual module embedding ~510 KB of seed JSON |
supabase/ |
7 migrations, 9 pgTAP files, seed | 280 assertions (PGlite and real stack) | PostgreSQL | SQL; stays |
Workspace total measured on the Step 7 closure: 763 vitest cases, lint 0, build and Docker green.
I.2 Hidden contracts a port must honour (found by the inventories)
These are the facts that decide feasibility, not the line counts.
| Contract | Where | Consequence for Rust |
|---|---|---|
documentSha256 = sha256 of the Prettier-formatted lean document JSON (Prettier 3.8.3 collapses short arrays), computed by the pipeline; compared at runtime by rebase.ts:119, envelope.ts:100, pdf export.ts:88 |
packages/anatomy curation, every Report v3 sheet.documentSha256 |
a Rust pipeline must emit byte-identical text or the sheet identity changes under every existing report and archive; Prettier's fitting algorithm is not a serde option (Part II, D-R5) |
Generated coordinates printed as raw JS Number → String (1715.4285714285713), never rounded |
pipeline outputs, review SVGs, layer attributes ("1118", "0.85" in the step6 view goldens) |
integer-valued floats print without .0 in JS, serde_json prints 3.0; a JS-compatible number formatter (shortest round-trip, JS exponent thresholds) is required and must be golden-tested |
Zod rebuilds parsed objects in schema key order; the archive snapshot written into PDFs inherits that order through assertSnapshot + JSON.stringify(…, null, 2) |
packages/domain, packages/pdf attachment |
Rust structs declare fields in the Zod schema order; serde_json pretty output otherwise matches JSON.stringify(v, null, 2) (2 spaces, ": ", []/{}, raw non-ASCII, \u00XX controls); no test pins the attachment bytes today, so this is a choice to make explicit (D-R11) |
Text layout x positions depend on widthOfTextAtSize, which sums AFM widths plus kerning pairs, while drawText writes unkerned glyphs |
packages/pdf render, 39 goldens (12 text, 12 images, 12 links, 3 views) |
the Rust engine must embed the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so an exact reproduction is provable |
Dates through Intl.DateTimeFormat (ICU): 11 octobre 2026, November 20, 2026, UTC |
packages/pdf/src/render/dates.ts, apps/app/src/lib/dates.ts (a second, different implementation) |
explicit fr/en month tables in Rust; the goldens pin the strings |
Labels upper-cased with JS toUpperCase() before safeText |
engine | Rust to_uppercase applies the same full Unicode mapping; goldens pin É È Ê Ï |
One inflater: DecompressionStream('deflate') on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size |
engine read path and branding | miniz_oxide bounded inflate replaces it everywhere, which is a portability gain (no Web API on the read path) |
Two sanitisers: app canvas denylist (drawing.ts: 5 tags, on*, javascript:) and engine allowlist with caps |
app vs engine | one Rust sanitiser serves both; the engine's "zero-removal" test takes xmldom's own re-serialisation as oracle and needs a committed oracle instead |
Two view compositions: composeViewSvg mutates an xmldom element passed by the engine; the app composes with the browser DOM |
engine vs app | one Rust compose_view_svg(asset, document, view, states) → String serves both |
buildSheetIndex returns ten closures over four private Maps, called per render by about 14 app modules |
packages/domain sheet-index, app |
the WASM boundary cannot export closures; the index becomes plain data built once (Part III.3) |
| Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (no path, codes only) and adds 3 of its own | domain validate.ts, migrations |
the Rust validator takes the TS role; SQL stays; a shared conformance fixture set pins both |
instanceof on three domain error classes in pdf and app scripts |
domain errors | replaced by closed kind discriminants (the BDR-015 pattern) at the boundary |
Report ids crypto.randomUUID(), createdAt and exportedAt from new Date() in the store and the app export |
apps/app |
ids and timestamps are injected into the core, never generated inside it (keeps the core deterministic and testable) |
Zustand store takes hydrateReport(report) as is, no Zod parse; initReport only trims |
reportStore.ts |
the Rust parser becomes the single entry for any report entering the store (closes a CLAUDE.md drift the inventory found) |
Business rules living in UI files: FindingsTreePicker.toggleLeaf (builds a Finding with snapshots and the vet flag), ObservationCard.zoneLabel/zoneTrees/unresolvedFindings, VertebraPicker selection rules, isIdentityComplete twice |
components | these move into the core at the same phase as the observation reducers (Part II, R2) |
I.3 Toolchain and host facts
- No
cargo,rustcorrustupon the development host today (checked 2026-10-12). Rust stable is 1.99.0 (2026-10-01), edition 2024 since 1.85. - Docker 29.8.2 rootless on the host (
seccompbuiltin profile,rootless,cgroupns), kernel 7.0 with the Landlock LSM enabled and seccomp filters. The VPS kernel is not verified; Landlock needs 5.13+ (Ubuntu 24.04 ships 6.8). - Docker's default seccomp profile (rootless included) allows
seccomp,landlock_create_ruleset,landlock_add_rule,landlock_restrict_self,prctl,setrlimit,prlimit64unconditionally;unshareandclone3with namespace flags needCAP_SYS_ADMIN. A seccomp + Landlock + rlimit child works inside a container; user-namespace isolation does not. - CI runs on a Gitea
act_runner; JavaScript actions neednodein the job image;dtolnay/rust-toolchainandtaiki-e/install-actionare shell composites;Swatinem/rust-cacherelies onactions/cache(Gitea runner v5 has a per-runner cache server; not verified on this forge).
I.4 Ecosystem facts (as of 2026-10-12)
Verified on crates.io, docs.rs, GitHub and RustSec by the research agents; "UNVERIFIED" items are listed in Part IX.4.
Core and bindings:
| Need | Crate | Version (date) | Status | Limits |
|---|---|---|---|---|
| JSON | serde / serde_json |
1.0.229 / 1.0.154 (2026-10-11) | serde-rs org | pretty printer matches JSON.stringify(v,null,2) except integer-valued floats (3.0) and -0.0; preserve_order feature |
| Hashing, base64 | sha2 0.11.1, base64 0.23.1, hex 0.4.3 |
RustCrypto / marshallpierce | none open | |
| Inflate | miniz_oxide 0.9.1 (2026-03), flate2 1.1.10 |
pure Rust | decompress_to_vec_zlib_with_limit, streaming Decompress for incremental cancel |
|
| WASM glue | wasm-bindgen 0.2.129 (2026-09-25), wasm-bindgen-futures 0.4.79, js-sys / web-sys 0.3.106 |
org wasm-bindgen (Cloudflare maintainers), monthly releases, MSRV 1.81 |
since 0.2.128 the crate and the CLI must be the same version | |
| WASM build | cargo build --target wasm32-unknown-unknown + wasm-bindgen-cli; wasm-pack 0.15.0 (2026-05, one maintainer, 335 open issues); wasm-opt via npm binaryen 132 |
prefer cargo + CLI, pinned, over wasm-pack | ||
| Typed boundary | tsify 0.5.8 (2026-08-23, active; tsify-next deprecated in its favour), serde-wasm-bindgen 0.6.5 (preferred over JSON glue; json_compatible() preset) |
generates .d.ts from serde structs, plain JS objects in and out |
||
.ts generation outside the wasm package |
ts-rs 12.0.1 (2026-01) |
Option<T> → T | null, #[ts(optional)] → t?: T |
||
| JSON Schema | schemars 1.2.2 (2026-07), 2020-12 default |
Zod 4 imports JSON Schema (experimental since 4.2); the repo runs Zod 3 | ||
| Randomness on wasm | getrandom ≥ 0.3.4 (wasm_js feature only) |
ids are injected anyway | ||
| Panic hook | console_error_panic_hook 0.1.7 (repo archived 2025-08) |
small, vendorable; wee_alloc archived, default allocator |
||
| Vite 7 | --target web output: await init() + ?url, no plugin |
vite-plugin-wasm only for the bundler target |
PDF, SVG, XML, fonts:
| Need | Crate | Version (date) | Status | Limits |
|---|---|---|---|---|
| PDF writing | pdf-writer |
0.15.0 (2026-05-27) | typst org, 4 pure-Rust deps, no advisory | has EmbeddedFile + EmbeddingParams, FileSpec::association_kind(Data), Names::embedded_files, Catalog::associated_files, Type1 fonts with WinAnsiEncoding + explicit widths, image XObjects with SMask, Action::uri, Info dates, classic xref table; cannot write object streams at all (BLK-009 option B by construction) |
| PDF writing, higher level | krilla 0.8.2 (2026-06) |
one maintainer (typst-pdf backend) | page text is OpenType only (no Standard 14), merges CreationDate/ModDate: not suitable for the parity step; candidate for the TTF step | |
| PDF reading | none needed (byte scan stays); lopdf 0.45 for tests only (HIGH advisory patched ≥ 0.42) |
|||
| PDF verification in CI | pdfium-render 0.9.4 (C++ binaries), or poppler already used in Step 6 audits |
CI only | ||
| Standard 14 metrics | no credible crate (pdf-core-14-font-afms 0.1.1, pdf-base14-metrics 0.0.2, < 4k downloads) |
vendor the Adobe Core 14 AFM files (SPDX APAFML: redistribution allowed with MustRead.html, edits noted); @pdf-lib/standard-fonts bundles the same files (WX, N, KernPairs) so the numbers can be identical |
||
| TTF later | subsetter 0.2.6 (typst), skrifa 0.48 (googlefonts), harfrust 0.14 (harfbuzz); ttf-parser and rustybuzz are RustSec-unmaintained (2026-0192 / -0206) |
Inter and Fraunces are OFL | ||
| SVG raster | resvg / usvg 0.48.1 (2026-08-02), tiny-skia 0.12 |
linebender org since 0.45 (2025-02), Apache/MIT | README claims pixel-identical output across platforms (not measured here); @resvg/resvg-wasm 2.6.2 measures 2.48 MB raw / 949 KB gzip; text support needs fontdb + embedded fonts (+400 KiB); only cap is a hard-coded 1,000,000 elements; usvg parses with allow_dtd: true |
|
| XML parse | roxmltree 0.21.1 (2025-10) |
RazrFalcon, 27M/90d | read-only, refuses DTD by default (DtdDetected), nodes_limit, entity loop checks; an unreleased fix (2026-09-22) for a stack overflow on deep nesting: pin the next release or cap depth before parsing |
|
| XML write | hand-written serialiser for the allowlisted tree (recommended), or quick-xml 0.42 (two HIGH advisories patched ≥ 0.41) |
xmlwriter archived |
||
| PNG | png 0.18.1 (2026-02) |
image-rs, no unsafe, OSS-fuzz, Limits.bytes default 64 MiB |
encoder writes only IHDR/IDAT/IEND unless asked | |
| Canonical JSON | serde_jcs 0.2 (RFC 8785) |
compact and key-sorted: not the pretty form the archive uses |
Worker (image pipeline, sandbox, transport):
| Need | Crate | Version (date) | Status | Limits |
|---|---|---|---|---|
| Decode + resize + orientation | image 0.25.10 (2026-03-10), MSRV 1.88 |
image-rs org | orientation(), icc_profile(), exif_metadata(), set_limits (max_alloc advisory 512 MiB), apply_orientation, resize_to_fill; JPEG = zune-jpeg, PNG = png, WebP = image-webp; no ICC application API |
|
| JPEG | zune-jpeg 0.5.15 |
one very active maintainer | unsafe only in SIMD (togglable), default cap 16536×16535, CMYK ok, "panics are okay" policy → child process justified |
|
| WebP decode | image-webp 0.2.4 (2025-08) |
image-rs, forbid(unsafe) |
lossy, lossless, alpha, animation, ICC/EXIF/XMP; memory limit has a documented TODO; encoder is lossless only | |
| WebP lossy encode | libwebp-sys 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, cc build); webp 0.3.1 pins libwebp-sys 0.9.6 = libwebp 1.3.1 + the CVE-2023-4863 fix (frozen line) |
C | no established pure-Rust lossy encoder (oxideav-webp 0.3.1 MIT created 2026-04, zenwebp AGPL) |
|
| ICC → sRGB | moxcms 0.9.1 (2026-09) pure Rust, required dep of image, one maintainer, SIMD unsafe on by default; lcms2 6.2 (C) |
no documented ICC input limits in moxcms: cap the profile size ourselves |
||
| Resize quality | fast_image_resize 6.1 (optional) |
image::imageops suffices for 512 px |
||
| Magic bytes | infer 0.22 (forbid(unsafe)) |
|||
| Sandbox | seccompiler 0.5.0 (rust-vmm, sets no_new_privs), landlock 0.4.7 (ABI V1..V9, best-effort), rlimit 0.11 / nix 0.31 |
extrasafe dormant and needs unshare; wasmtime 49 works (fuel, epoch, StoreLimits) but carries ~2 advisories/month in 2026 |
||
| Runtime, HTTP | tokio 1.53, reqwest 0.13.5 (rustls default, multipart opt-in), tracing 0.1.44 |
|||
| Supabase clients | postgrest 1.6.0 (2023-07), supabase-rs 0.8.0 (2026-10, PostgREST only, no auth) |
weak | hand-written reqwest calls to PostgREST /rpc/<fn> and Storage /storage/v1 are lower risk |
|
| Toolchain | rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}, cargo-chef 0.1.78, cargo-deny 0.20.2, cargo-audit 0.22.2, distroless/static (Debian 13, nonroot) |
musl static with the cc-built libwebp needs musl-dev on Alpine |
Baseline for comparison, sharp 0.35.5 (2026-09-27): libvips 8.18.7,
libwebp 1.6.0, libpng 1.6.58, mozjpeg; by default strips metadata and
converts to sRGB, limitInputPixels 268 MP, WebP q80; EXIF orientation only
with autoOrient/rotate(). libvips had three High CVEs in July and August
2026 (TIFF and loaders), libpng twelve CVEs since late 2025. The Rust
pipeline's advantage is the loader surface (three formats, pure-Rust
decoders, hard caps), not the encoder (still libwebp).
Supabase platform facts that shape the worker and the contracts:
- A dedicated Postgres role is honoured by PostgREST (
SET LOCAL ROLE, needsGRANT <role> TO authenticator) and by storage-api (official custom-roles guide: grant toauthenticator, grantanonto the role, RLS onstorage.objectsto <role>, mint a JWT withroleandsub). - Minting such a JWT needs the legacy HS256
JWT_SECRET(self-hosted: still inJWT_KEYS/JWT_JWKS; managed: "available for backward compatibility", extractable, not deletable) or an imported ES256 standby key (supabase gen signing-key). New managed projects default to asymmetric keys since 2025-10-01. pg_jsonschema0.3.3 ships in thesupabase/postgresimage and on managed; it is not in the PGlite extension list, so a JSON Schema CHECK would not run under the Dockerless pgTAP harness. Custompgrxextensions have no documented path on managed.- Edge Functions on managed: 2 s CPU, 256 MB, 150 s wall clock (free),
Deno/TypeScript only. Self-hosted:
edge-runtimecontainer, hand-deployed. Not a home for Rust code; the rule retires them from the plan (Part VII).
Part II. Classification of every module
II.1 Criteria applied
Business logic = anything that interprets or transforms the sheet, report or archive data, encodes a product rule (what a click does, how a finding is built, how a report migrates), parses untrusted bytes, or runs as a job or a service. Glue = React rendering, routing, DOM access, store subscription, vendor SDK calls, build tooling. The owner's brief keeps glue in TypeScript; everything else is Rust unless a concrete loss is named. "Loss" is measured on the brief's list: features, UX, graphics, data compatibility, security, reliability, useful performance, resources, portability, maintainability, deployment. Absence of a performance gain is never a reason for C.
Classes: A = Rust now (clean migration possible, no functional step needed first); B = Rust later, with a named trigger or dependency; C = exception with its concrete constraint.
II.2 Module table
The ten points of the brief (role, technology, feasibility, crates, WASM, frontend consequences, compatibility risk, tests, recommendation, timing) are given per row; the parity tests are detailed in Part VI.
| Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Parity tests needed | Class | When |
|---|---|---|---|---|---|---|---|---|---|
packages/domain sheet document schema + validateSheetDocument (21 rules) + createEmptySheetDocument |
shape and integrity of the canonical sheet | Zod | full: serde structs (strict = deny_unknown_fields, defaults via #[serde(default)]), hand-written rules returning SheetIssue {code, severity, path, message} |
yes (app load, publish gate) + native (worker, tools) | app and publish gate call parse_sheet_document / validate_sheet_document; TS types generated by tsify |
low: codes and paths are pinned by the validate tests; strict/strip policy per schema must be reproduced | validate suite (exact code + path lists), fixture horse-slice, the draft document (0 issues), conformance fixtures shared with pgTAP |
A (first core crate) | R2 |
packages/domain report v3 + v2 input + migrateReportV2ToV3 + readReportDocument |
report contract and migration | Zod | full; migration map as data; "never throws on content" made true (today a malformed map entry can throw a raw ZodError) |
yes + native | store hydrates only through the Rust parser (closes the no-parse path) | medium: strip semantics (unknown keys dropped), requiresVetReferral: false disappearing in v3 (keep as is, pinned), unresolved flags |
612-leaf migration (anatomy + app + PDF roundtrip), golden v2 fixtures, report-migration-map.json |
A | R2 |
packages/domain rebaseReportOnSheet |
rebase on another sheet | TS over the closure index | full; takes the sheet source and builds its own index | yes | called from store restore and import | gated by CLAUDE.md ("ask before changing"): behaviour preserved exactly, rebase tests are exact-object oracles | rebase suite | A (with the owner's explicit go for the gated function) | R2 |
packages/domain archive: buildSheetSnapshot, assertSnapshot (caps, integrity, sheet invariant), envelope v1 readArchiveDocument (layered), branding + labels schemas |
archive contract | Zod | full; caps count UTF-16 units for strings and UTF-8 bytes for assets (reproduce both); closed snapshotRejected reasons |
yes + native | app import path and engine use it | medium: snapshot key order (Zod schema order) must be kept if attachment bytes are to stay stable (D-R11); origin quirk for unknown envelope versions preserved |
envelope decision-table suite, branding/labels suite, size test (< 250 KB stored), re-export test | A | R2 |
packages/domain buildSheetIndex |
lookups by id | closures over Maps | different shape: Rust returns a plain-data index (views, annotations, finding zones, regions by id; main view; annotations per view; spine annotation per region+view) built once; nodeAt and name as small functions over that data |
yes | ~14 app modules read object properties instead of calling closures; ObservationCard per-render lookups become property reads (cheaper) |
low: lookup semantics pinned by the service and component tests; duplicate-id policy (index last-wins vs validate first-wins) made explicit | sheet-index tests + component suites unchanged in intent | A | R2 |
apps/app/src/services/zoneInteraction.ts (7 decision kinds, 11 reducers) |
click decision and observation reducers | pure TS | full; (observation, annotation, …) → observation with the index data |
yes | EditorRoute.onZoneClick and ObservationPickers call the core per click (≤ 1 ms serialisation on a few-KB observation) |
low | the 13-case service suite as a black-box table, route click-chain characterisation | A | R2 |
Business rules in UI files: toggleLeaf (Finding builder), zoneLabel / zoneTrees / unresolvedFindings, VertebraPicker rules, isIdentityComplete ×2, isDegradedImport / message line builders |
product rules inside components | TSX | full; become core functions (build_finding, describe_zone, zone_trees, vertebra_selection, identity_complete, import_outcome_lines) |
yes | components keep rendering; the rule moves out (also removes the duplicates) | low | component suites keep their assertions; new unit tables | A | R2 (same phase, same data model) |
apps/app/src/state/reportStore.ts actions (initReport, addObservation, moveObservationUp/Down, setters) |
Report construction and edits | Zustand | the rules move to the core (new_report(draft, sheet, id, created_at), swap), the store stays Zustand (React glue); ids and timestamps injected from TS |
yes | store actions become one-line delegations | low | store suite | A (logic) / C (Zustand subscription, sessionStorage adapters: DOM glue) | R2 |
apps/app/src/state/persistence.ts, practitionerCache.ts, localeStore.ts, authStore.ts, localeSync.ts |
storage adapters, GoTrue event glue | TS | adapters are DOM/vendor glue; the only rules (isLocale, "account locale wins once per sign-in") are trivial and tied to supabase-js events |
no | none | none | existing suites | C: browser storage and supabase-js session glue; no Rust GoTrue client with PKCE and refresh exists | n/a |
packages/anatomy/src/render (layer renderer, composeViewSvg, highlight, viewBoxOf) |
markers from the document; view composition with highlight | pure tree + DOM mutation | full: render_annotation_layer(document, view, states) → LayerElement (plain JSON, same contract) and compose_view_svg(asset_svg, document, view, highlight) → String on the Rust XML tree |
yes (app canvas, browser export) + native (worker, tools) | app receives either the layer tree (DOM materialisation stays TS) or the composed SVG string; the app canvas and the PDF stop composing differently | low on the layer (attribute strings pinned by the step6 view goldens and render.compose byte goldens); the composed SVG serialisation needs a committed oracle (xmldom's output today) |
render.compose.test.ts (app-main / app-head byte goldens), step6 views.*.json, security SVG cases |
A | R3 |
packages/pdf/src/svg/{parse,sanitize,view} (allowlist sanitiser, caps, view crop) + apps/app/src/anatomy/drawing.ts denylist |
untrusted SVG → safe tree | xmldom / DOMParser | full: roxmltree parse with DTD refused and a pre-parse depth/size cap, own allowlisted tree, own serialiser; one sanitiser for the canvas, the PDF, the Step 13 upload processor and the Step 6 branding SVG |
yes + native | drawing.ts parses a sanitised string with DOMParser and keeps importNode + click delegation (DOM glue stays) |
medium: "zero-removal" oracle changes (commit the canonical serialisation of horse.svg); attribute order and escaping differences vs xmldom show in view goldens |
7 hostile cases + zero-removal + caps, new committed oracle, app canvas suite | A | R3 |
packages/anatomy curation pipeline (changeset Zod, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) |
changeset → draft artifacts | TS + xmldom + Prettier + node:fs |
logic fully portable; byte identity of 18 generated files is the golden: Prettier formatting (JSON and markdown tables), JS number strings, document_sha256 over the Prettier text; a Rust pipeline keeps a Prettier formatting step as its last stage (Node, dev-time) or the identity rule changes under a schema migration (D-R5) |
native (tools) | none (operator tool) | high on bytes, nil on semantics | seed.golden.test.ts (byte-exact, 18 files), determinism tests, counts tests, 612-leaf test |
B: after R2 (needs the domain crate) and at the next content changeset; Prettier step retained (dev tool, D-R5) | R5 |
packages/anatomy legacy importer (Horse.svg + Horse_head.svg + pathologies.json → baseline) |
one-off import re-run at every regeneration | TS + xmldom | full (sha-derived uuid "v5-like", strict label equality, region inference) | native | none | same byte constraint as the pipeline (legacy-import files are goldens) | legacy suites (27 annotations, 792 nodes, 612 leaves, 41 vet, anomalies) | B with the pipeline; if the equine sheet is published and the importer retired, delete instead of migrate (decision at R5) | R5 |
packages/pdf engine: layout + pages + footer + links + attachment + metadata (export), exportFromEnvelope |
A4 archive writer | pdf-lib | full with pdf-writer (every primitive verified, no object streams by construction); layout split from serialisation so the draw-call log is golden-comparable; AFM data vendored (APAFML); fr/en month tables; png crate decodes the archived logos under the existing gate |
yes (browser export) + native (Step 15 server rendering, tools) | the app calls export_report_archive in the wasm; rasteriser stays an injected adapter (browser canvas first) |
medium: goldens reproduce drawn primitives exactly only if widths (kerning included), rounding (Math.round half-up) and date strings match; drawLine/drawRectangle, colours and z-order are not golden-covered (add a draw-log golden before porting); attachment Flate bytes differ (never pinned) |
39 goldens through a Rust draw-log recorder, re-export test, size test, roundtrip suites, poppler/pdfium render diff in CI | B: trigger = Step 15 (server-side rendering/import) or the TTF font change, whichever first; sequencing in Part VI | R4 |
packages/pdf reader: attachment/scan.ts byte scan, bounded inflate, JSON depth pre-scan, stamp detection, readReportArchive layering |
untrusted PDF → archive outcome | TS + DecompressionStream |
full and simpler: miniz_oxide bounded streaming inflate replaces the slice-fed DecompressionStream; same candidate ordering and budgets |
yes + native (Step 15 server import, CLI) | app import calls the wasm | low: scan suite (39 cases) is a byte-level oracle; the PNG idat gate semantics (exact raw size) reproduced |
scan + inflate + read suites, bombs regenerated in Rust tests | A (independent of the writer; security value on the Step 15 server path) | R4a |
packages/pdf branding PNG gate, safeText, wrapLines, labels (25 keys) |
text safety, caps | TS | full (WinAnsi table from the AFM/encoding data) | with the engine | low | text suite, security PNG cases (28) | B with the engine | R4 | |
apps/app/src/pdf/browserRasterizer.ts |
SVG → PNG via Image + canvas |
DOM | the adapter is DOM glue; the alternative resvg in a lazy-loaded second wasm module (949 KB gzip measured) gives deterministic, DOM-free rasterisation (what the tests already use) at the cost of bundle size and a visual change (anti-aliasing) |
optional | lazy load on first export only | visual: pixels differ from the canvas rendering; no raster golden exists | raster facts test, user visual check | C today (DOM adapter), B option D-R3 once the engine is Rust | R4 / decision |
apps/app/src/pdf/export.ts, import.ts, branding.ts |
wiring: bundled logos, outcomes → UI kinds | TS | wiring stays; branding.ts is Vite asset glue (?inline / ?raw) |
no | thin | none | existing suites | C: Vite asset imports and DOM download are build/DOM glue | n/a |
apps/app/scripts/compare-reports.ts + compare/report.ts |
archive check CLI | tsx + Node | full: faunosteo-tools report-compare on the Rust reader and domain (escaping rules LRN-044 ported) |
native | none | low | 11 CLI cases | B: with R4a (reader) | R4a |
packages/supabase classifyAuthError (23 codes → 13 kinds), publish gate |
closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue (23 string literals) | partial | gate delegates | none | existing suites | gate A (R2); code map C (supabase-js error shapes) | R2 |
packages/supabase client factory, profile/auth wrappers, database.types.ts, PGlite harness |
vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser (PKCE, refresh, onAuthStateChange); PGlite is a JS/WASM library |
no | none | none | C: vendor SDK and test infrastructure | n/a | |
apps/app/src/auth/validation.ts, account/validation.ts (Zod, i18n keys) |
form field rules | Zod | portable, but React-bound by the owner's retained list; the constraints themselves (lengths, E.164, SIRET 14 digits, password policy) are duplicated in SQL CHECKs and config.toml and already drift (trim, UTF-16 vs char_length, '' accepted on names) |
no | the existing 8 cases + a constants parity test | C: UI form schemas; action: one constants file generated from the SQL CHECKs (or a Rust constants export) so the rule has one home |
R2 follow-up | ||
apps/app/src/lib/{dates,id}.ts |
nowIso, todayIso, formatDate (UI), generateId |
Web APIs | id and clock stay in TS and are injected into the core; UI date display stays Intl (screen only, not archived) |
no | C (platform clock, crypto, Intl for screen) | n/a | |||
apps/app/src/i18n/* (281 keys ×2, useT) |
UI strings | TS | data + React hook; pickLabel bilingual fallback moves to the core with the labels it serves |
no | parity test | C: UI dictionaries; the engine's 25 archived labels move with the engine | n/a | ||
apps/app/src/config/env.ts, lib/supabase.ts, providers, guards, routes, components, styles |
runtime config, React | TS | glue | no | C: React, DOM, window, router | n/a | |||
apps/app/vite/sheet-bundle.ts, ESLint, Vite, vitest configs |
build tooling | Node | Vite plugin API is JavaScript | no | C: build tooling | n/a | |||
supabase/migrations, pgTAP, private.sheet_document_issues |
database | SQL | SQL by the retained list; the TS/SQL rule pair becomes Rust/SQL with one conformance fixture set | no | shared fixtures | C (retained) | n/a | ||
| Step 8 worker (planned Node + sharp) | file processing | not built | native Rust (Part IV) | native | none | none (new) | Part IV tests | A | R1 (Step 8) |
| Step 13 SVG upload processor, Step 15 server-side import and PDF rendering, Step 19 notifications and job queue, Step 21 travel engine and calendar sync, Step 23 Stripe webhook, Step 24 import adapters, Step 26 export/archive jobs | future backend | not built | Rust in the same worker binary (jobs) or a sibling HTTP service (webhooks, OAuth callbacks) sharing the core crates | native | none | none | per step | A at design time (rule applies from design) | their steps |
Step 17 sheet editor document operations (undo, geometry: bbox + margin → view_box, polygon edits, mapping validation), Step 20 agenda rule mirrors (expiry 48/24/1 h) |
future app logic | not built | core crate functions through WASM; UI in React | yes | editor store holds plain documents, calls the core | none | per step | A at design time | their steps |
| Step 22 public web | marketing site, public profiles, SEO | not built | Rust static generators exist (Zola) but the global rule mandates Astro for indexed sites (SEO/GEO, islands); public RPC reads are SQL | n/a | C proposed, decision D-R8 | Step 22 |
II.3 Summary by class
- A (Rust now): the domain contracts (sheet, report, migration, rebase, archive), the sheet index as data, the interaction reducers and the rules stranded in components, the publish gate, the layer renderer and view composition, the SVG sanitiser, the PDF reader and the CLI, the Step 8 worker, and every future backend or rule-mirror listed above.
- B (Rust later, trigger named): the PDF writer (trigger: Step 15 or the TTF fonts; after R2 and R3 in any case), the curation pipeline and the legacy importer (after R2, at the next content changeset, Prettier step kept or identity rule changed), the resvg rasteriser (after R4, visual decision).
- C (exceptions, each with its constraint): React/DOM/router glue, Zustand subscriptions and browser storage adapters, supabase-js session and error shapes (no Rust GoTrue client for PKCE in the browser), UI form schemas (React-bound; single source of constraints to add), UI dictionaries, platform clock/crypto/Intl for screen display, Vite and ESLint tooling, SQL and RLS, the public web framework (decision D-R8).
Part III. Target Rust architecture
III.1 Cargo workspace
faunosteo/
├─ Cargo.toml workspace: members crates/*, shared [workspace.dependencies],
│ lints (clippy pedantic subset, unwrap_used = deny in libs)
├─ rust-toolchain.toml channel pinned (1.99.0 at adoption), targets wasm32-unknown-unknown
├─ deny.toml cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0 for
│ tiny-skia deps, APAFML for the AFM data), advisories, bans
├─ crates/
│ ├─ domain/ faunosteo-domain: sheet document, integrity rules, report v3 + v2
│ │ migration, rebase, sheet index data, archive (snapshot, envelope,
│ │ branding, labels), interaction reducers, observation rules.
│ │ serde + thiserror only. No I/O, no clock, no ids (injected).
│ ├─ anatomy/ faunosteo-anatomy: XML tree + allowlist sanitiser + serialiser,
│ │ layer renderer, view composition; feature `curation` (pipeline,
│ │ legacy importer, later). roxmltree, sha2, serde.
│ ├─ pdf/ faunosteo-pdf: reader (byte scan, bounded inflate, layered read)
│ │ first; later writer (layout → draw log → pdf-writer), AFM tables,
│ │ PNG gate, labels. miniz_oxide, png, pdf-writer.
│ ├─ wasm/ faunosteo-wasm: the single wasm-bindgen facade over the three
│ │ crates (tsify types, closed error kinds), published to
│ │ packages/core-wasm by the build. Optional second module
│ │ `wasm-raster` (resvg) only if D-R3 is accepted.
│ ├─ worker/ faunosteo-worker (bin): job loop, Storage/PostgREST transport,
│ │ sweeper, `decode` subcommand = the sandboxed child. Step 15 adds
│ │ the pdf feature; Step 19 adds mail and jobs.
│ └─ tools/ faunosteo-tools (bin): report-compare, later import-equine and
│ the curation pipeline, asset upload (operator CLI).
└─ packages/core-wasm/ generated: faunosteo_wasm.js, .d.ts, .wasm (build artifact,
git-ignored; CI and Docker build it)
Six crates, one per dependency or deployment boundary, none per module: the
domain crate pulls no XML or PDF code, the worker does not compile the PDF
writer before Step 15, the wasm facade is the only place that knows
JavaScript. A single faunosteo-core crate with feature flags was weighed
and rejected: it would compile pdf-writer and roxmltree into the worker
image from day one and blur the "domain has no I/O" rule that makes the
core testable (D-R1 for the owner).
III.2 Native and WASM: who runs what
| Crate | Native (worker, tools, tests) | WASM (browser) |
|---|---|---|
| domain | worker (Step 15 import validation), tools, cargo tests, parity harness | app: parse/validate/migrate/rebase/snapshot/envelope, reducers, rules |
| anatomy | worker (Step 13 upload sanitiser, Step 15 rendering), tools (pipeline) | app: sanitise + compose views for the canvas and the export |
| worker (Step 15), tools (report-compare) | app: import (reader) now, export (writer) at R4 | |
| worker | container faunosteo_worker |
never |
| tools | developer and operator machines, CI | never |
The same crate code runs in both worlds; only the facade and the binaries
differ. Platform access (clock, ids, storage, network, DOM, rasterisation) is
injected: the core never calls std::time, rand, fs or fetch.
III.3 Boundary rules ("Rust computes, TypeScript reads")
- Calls are coarse and synchronous. One call per user action or per
load (
parse_sheet,build_index,apply_click,sync_vertebrae,export_archive,read_archive), never per render. The index, the report and the outcomes cross the boundary as plain JSON-compatible objects (serde-wasm-bindgenwithjson_compatible()), typed bytsify-generated.d.ts. React components read properties; nothing in the render path calls into the wasm. - The sheet index becomes data.
build_sheet_index(sheet) → SheetIndexDatawithviews,annotations,finding_zones,regionskeyed by id,annotations_by_view,spine_by_region_view,main_view_id. The ten closures disappear;nodeAtandnamebecome small functions on both sides (Rust for the core, a generated TS helper for components), with one duplicate policy (document order, first wins, same asvalidate). - Errors are closed kinds, not classes. Every fallible call returns a
tagged result (
{ ok: true, value } | { ok: false, kind, detail }) with the kinds already named in the code (invalid_pdf,no_attachment,incompatible_version,snapshotRejectedreasons,ArchiveExportErrorkinds). Theinstanceofchecks in pdf and the scripts go away with the TS classes. - Ids and time are inputs.
new_report(draft, sheet, id, created_at),export_archive(…, exported_at); the TS side keepscrypto.randomUUID()andnew Date(). - No panic on content.
#![deny(clippy::unwrap_used, clippy::expect_used)]in the libraries,catch_unwindat the facade turning any panic into akind: 'internal'result, andcargo-fuzztargets onread_archive,parse_sheet,sanitize_svgand the image decode (native only). - Deterministic serialisation. Struct fields in the Zod schema order;
integer fields typed as integers; a
js_numberformatter for floats (shortest round-trip, JS rules for.0and exponents) used by the SVG serialiser and the pipeline;serde_jsonpretty printer for the archive. A parity test compares the envelope JSON produced by the TS engine and by Rust byte for byte on the three golden reports during R2 and R4.
III.4 Contracts: one source of truth
- Rust is the source for the sheet document, the report, the migration
map, the envelope, the snapshot, the branding and the labels.
tsifyemits the TypeScript types next to the wasm;packages/domainshrinks to re-exports of those types and of the wasm facade, then disappears once no TS importer remains. The Zod schemas of these contracts are deleted at the end of R2 (no duplicate logic kept). - JSON Schema as documentation and optional DB check.
schemarsemits the 2020-12 schema of each contract intodocs/contracts/*.schema.json(committed, diffed by CI). Enforcing it in PostgreSQL throughpg_jsonschemais possible on both hostings but not on PGlite, so it is recorded as an option for the step that first stores reports (Step 14), not adopted here. - SQL keeps its mirror.
private.sheet_document_issuesstays; a conformance fixture set (crates/domain/tests/conformance/*.json: document- expected codes) is run by cargo tests and by a pgTAP file, so the two implementations are pinned to the same expectations.
- UI form constraints get one home: a generated
constraints.json(lengths, regexes, password policy) produced from the SQL migrations andconfig.tomlby a small tools command, consumed by the Zod form schemas. This closes the drifts the inventory found (trim,char_length, empty names) without moving React code to Rust. - Generated database types stay
supabase gen types(unchanged).
III.5 Build and packaging of the wasm
cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknownthenwasm-bindgen --target web --out-dir packages/core-wasm/pkg, both pinned to the samewasm-bindgenversion (cargo install wasm-bindgen-cli --version <x>in CI and Docker;taiki-e/install-actionsupports it);wasm-opt -Ozfrom the npmbinaryenpackage. Root scriptpnpm wasm:build.- Vite 7:
import init, * as core from '@faunosteo/core-wasm'withawait init()at application start (theSheetProvideris already async),?urlresolution of the.wasm, no plugin. Vitest: same package,init(readFileSync(wasmPath)). - Expected size: the domain + anatomy + reader core is estimated under
600 KB gzip (UNVERIFIED until built;
serde_jsonandroxmltreeare small, no fonts, no raster);resvgwould add 949 KB gzip (measured on resvg-wasm 2.6.2) and is kept out of the main module. - Debugging:
--keep-debugbuilds in development, Chrome DWARF extension;console_error_panic_hookvendored (archived upstream, 30 lines).
Part IV. Step 8 worker in Rust
Everything in STEP8_FILES_ANALYSIS.md Part II stays (buckets, assets
table, RPCs, keys, quarantine, purge queue, backups, migration runbook, UI,
D1 to D9). What changes is II.1's runtime and II.8's package: one Rust
binary replaces the Node process and sharp.
IV.1 Process model
container faunosteo_worker (distroless/static, non-root, read-only, no port)
faunosteo-worker run ← keyed parent: tokio, reqwest, token
poll every 2 s: POST /rest/v1/rpc/claim_avatar_jobs {max_jobs: 1}
GET /storage/v1/object/avatars/<quarantine_key> (≤ 5 MiB, 30 s timeout)
spawn faunosteo-worker decode ← same binary, subcommand, empty env, stdin/stdout only
child: rlimits (AS 512 MiB, CPU 10 s, FSIZE 0, NPROC 0, NOFILE 8), Landlock
(no filesystem), seccomp allowlist (read, write, mmap, munmap, brk, mremap,
futex, exit_group, sigaltstack, rt_sigaction, rt_sigprocmask, sched_yield,
clock_gettime, getrandom), PR_SET_NO_NEW_PRIVS; parent SIGKILLs at 20 s
decode: magic bytes → format ∈ {jpeg, png, webp} else unsupported_type
image::ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB}
dimensions from the header before decode (64 ≤ sides ≤ 4096 else dimensions)
decode (first frame of an animated WebP), apply_orientation(EXIF),
ICC → sRGB through moxcms when a profile ≤ 1 MiB is present, else assume sRGB
resize_to_fill 512×512 (Lanczos3), alpha kept
encode lossy WebP q=82 via libwebp-sys (C, confined to this child)
stdout: 512×512 WebP bytes, exit code = closed reason
parent: re-decode the output with image-webp (pure Rust, limits), assert 512×512, assert
no EXIF/XMP/ICCP chunk (img-parts), sha256, size
PUT /storage/v1/object/avatars/<object_key> (upsert) → POST rpc/complete_avatar_job
→ DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job
sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep
watchdog: one loop iteration > 60 s → process exits, Docker restarts it
The crash matrix, the write order (PUT clean → commit → DELETE quarantine), the lease and attempt rules, the purge grace periods and the fairness rule of the Step 8 analysis apply unchanged.
IV.2 Comparison with the Node proposal
| Aspect | Node 24 + sharp (STEP8 II.8) | Rust worker | Verdict |
|---|---|---|---|
| Decoders on untrusted bytes | libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 | zune-jpeg (SIMD unsafe, togglable), png (no unsafe, fuzzed), image-webp (forbid(unsafe)), hard Limits |
Rust better: smaller trusted base, caps by construction |
| Encoder | libwebp via sharp | libwebp via libwebp-sys 0.14 (C), in the sandboxed child, on a buffer the child itself decoded; output re-verified by a pure-Rust decoder in the parent |
equivalent; the C surface is the encoder only (D-R4 lists the pure-Rust and lossless alternatives) |
| Orientation, ICC, metadata | rotate(), ICC → sRGB and stripping by default |
apply_orientation, moxcms ICC → sRGB, stripping by construction (the encoder writes no chunks), plus an explicit chunk check |
equivalent, verified rather than assumed |
| Isolation | two Node processes, child without env | one static binary, child without env plus rlimits, Landlock, seccomp (allowed by Docker's default profile, rootless included) | Rust better |
| Resource bounds | limitInputPixels, mem_limit 512m, 20 s kill |
Limits, RLIMIT_AS, RLIMIT_CPU, 20 s kill, mem_limit |
equivalent or better |
| Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB; no runtime | Rust better on resources |
| Transport to Supabase | supabase-js with the service key over PostgREST and Storage | reqwest calls to the same two APIs; token = a dedicated faunosteo_worker role JWT (D-R6) or the service key |
equivalent; least privilege possible |
| Maintenance | sharp Renovate rule |
cargo-deny + cargo-audit in CI; image crate releases |
equivalent |
| Managed Supabase | URL + key only | same | equivalent |
| Build complexity | none | Rust toolchain stage, cc for libwebp, musl |
cost accepted by the rule |
IV.3 Worker crates
tokio (rt, process, time, io), reqwest (rustls, json, stream), serde /
serde_json, image (default-features off; jpeg, png, webp),
image-webp (parent verification), moxcms, libwebp-sys (child only,
behind a feature), img-parts (chunk check), infer, sha2, rlimit,
landlock, seccompiler, tracing + tracing-subscriber (JSON logs, field
allowlist, control characters escaped: LRN-044), thiserror. No database
driver (same reasoning as STEP8 II.8: one transport, no open DB port on
managed).
IV.4 Credentials (D-R6)
The analysis gave the worker the service key. The research confirms a
narrower option at the same cost: a Postgres role faunosteo_worker granted
to authenticator, holding EXECUTE on the eight worker RPCs only and the
storage.objects policies it needs on the avatars bucket; a JWT
{role: "faunosteo_worker", sub: <fixed uuid>, exp: <1 year>} minted once
by the operator with JWT_SECRET (self-hosted) or an imported ES256 standby
key (managed) and placed in .env.worker. The worker never holds the
secret; a leaked token cannot read profiles, sheets or other buckets. The
pgTAP census already pins what authenticated may execute; it extends to
faunosteo_worker. Fallback: the service key as analysed (no code change,
one env variable).
IV.5 Tests specific to the Rust worker
- Decode child fixtures (the STEP8 IV.2 list, unchanged): JPEG/PNG/WebP accepted, renamed PNG, GIF/BMP/SVG/PDF/HTML refused, truncated, 32 px, 20 000² header, 5000², EXIF-rotated → upright and chunk-free, PNG trailer after IEND, progressive JPEG with many scans and a large ICC under the deadline with RSS asserted, sleeping child killed at 20 s.
- Sandbox tests (native, Linux): the child cannot open
/etc/passwd(Landlock), cannotfork(NPROC 0), cannot write a file (FSIZE 0), has an empty environment (/proc/self/environ), dies on a disallowed syscall (seccomp), and the parent maps each death toprocessing_error. - Parent verification: a child returning a 511×511 image, an image with an
EXIFchunk, or garbage → rejected before any PUT. - Fuzz:
cargo-fuzztarget on the decode entry with theimagelimits (CI nightly, time-boxed). - Integration against the local stack (CI
supabasejob): Alice's full flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2.
Part V. Libraries retained and their limits
| Area | Retained | Alternatives rejected | Known limits to manage |
|---|---|---|---|
| Serialisation | serde, serde_json, thiserror |
json-canon, serde_jcs (compact only) |
float printing (custom js_number), key order by struct order |
| XML | roxmltree + own tree and serialiser |
quick-xml (advisories patched, but a writer is not needed), usvg as sanitiser (allows DTD, drops silently, rewrites the drawing) |
pin roxmltree to the release containing the deep-nesting fix; pre-parse byte and depth caps |
| PDF write | pdf-writer |
krilla (no Std14 page text, merged dates), printpdf (no attachments), lopdf (object model heavier than needed) |
writes classic xref only (desired); layout is ours |
| PDF read | own byte scan + miniz_oxide |
lopdf, pdf |
none; same caps as today |
| Fonts | vendored Core 14 AFM (APAFML notice committed); later skrifa + subsetter + harfrust |
ttf-parser, rustybuzz (RustSec unmaintained) |
kerning-inclusive width rule reproduced from pdf-lib |
| PNG | png |
UPNG semantics | gate stays ours; decoder under Limits |
| Raster (option) | resvg + tiny-skia (lazy module) |
canvas kept as default until decided | 949 KB gzip; allow_dtd and 1M-element cap belong to our sanitiser upstream; text needs embedded fonts (none in the drawings today, to be asserted by the sanitiser) |
| Images (worker) | image, image-webp, moxcms, libwebp-sys, img-parts, infer |
webp crate (libwebp 1.3.1 line), wasmtime sandbox (advisory cadence), extrasafe (dormant) |
Limits.max_alloc advisory → RLIMIT_AS is the hard cap; moxcms profile size capped by us; zune-jpeg panics contained by the child |
| Sandbox | seccompiler, landlock, rlimit |
user namespaces (blocked in Docker) | Landlock best-effort on older kernels: the worker logs the ABI it got and refuses to start below V1 in production (config flag) |
| Runtime | tokio, reqwest, tracing |
postgrest, supabase-rs |
hand-written calls: ~10 endpoints, tested against the local stack |
| WASM | wasm-bindgen + CLI, tsify, serde-wasm-bindgen, binaryen (npm) |
wasm-pack |
crate/CLI version lock; getrandom not needed in the core |
| Hygiene | cargo-deny, cargo-audit, cargo-fuzz, cargo-chef |
cargo vet (later) |
Part VI. Progressive migration strategy
VI.1 Principles
- One phase = one crate boundary moved, with a parity harness that runs the existing fixtures through both implementations and compares outputs (deep-equal JSON, byte-equal where bytes are the contract) until the switch; the TypeScript implementation and the harness are deleted in the same phase, never later (no two concurrent implementations past a phase).
- Goldens are never regenerated silently: a phase that must change a golden format (the PDF draw-log recorder) states it in its end criteria and the owner decides (the Step 6 rule stays).
- Every phase ends with
pnpm checkgreen,cargo test --workspace,cargo clippy -D warnings,cargo deny check, Docker builds green, the real-stack pgTAP when SQL changed, the verifier and security gates, and a manual validation script for the owner. - Phases are gitflow branches (
feature/rust-r<n>-<slug>for behaviour,chore/rust-r0-workspacefor the foundation).
VI.2 Phases and end criteria
| Phase | Content | Depends on | End criteria (verifiable) |
|---|---|---|---|
| R0 Foundation | Cargo.toml workspace, rust-toolchain.toml, deny.toml, lints, crates/domain skeleton with the first contract (SheetRef + Locale) and the wasm facade exporting core_version(); pnpm wasm:build; CI job rust; app Dockerfile stage; docs/development/RUST.md (setup, commands, boundary rules of III.3); rustup on the dev host (owner) |
none | cargo test, clippy, deny green in CI; the app loads the wasm in dev and in the Docker image (core_version() shown on the dashboard footer in DEV only); pnpm check unchanged; CI time measured and recorded |
| R1 Step 8 worker (Rust from the start) | Part IV: crates/worker, decode child, sandbox, transport, sweeper, compose service, .env.worker.example, the Step 8 migration and app work as analysed |
R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests, local-stack integration, real-stack e2e); worker image < 30 MB, non-root, cap_drop ALL, read-only; owner manual validation of the avatar flow |
| R2 Domain core | crates/domain: sheet document + rules, report v3/v2 + migration, rebase (owner go for the gated function), snapshot/envelope/branding/labels, index data, reducers, the rules extracted from components, new_report; wasm facade; app switched (SheetProvider parses through Rust, store hydrates through Rust, click chain through Rust); publish gate on Rust; TS Zod contracts deleted; conformance fixtures for SQL; constraints.json for forms |
R0 | parity harness: 0 difference on every domain fixture, the 612 leaves, the three golden reports' envelopes (byte-equal), the rebase and envelope decision tables; app suites green with the same assertions; packages/domain/src contains only generated types and re-exports; no instanceof on domain errors; bundle size delta recorded; owner manual FR/EN flow |
| R3 Anatomy core | crates/anatomy: XML tree, sanitiser (one for all), serialiser, layer renderer, compose_view_svg; app canvas and engine composition on it; committed serialisation oracle for horse.svg; app denylist deleted |
R2 | render.compose byte goldens unchanged; step6 views.*.json unchanged (relaxed fields as today); 7 hostile cases + caps; canvas suite green; one sanitiser in the repo (grep) |
| R4a PDF reader + CLI | crates/pdf reader: scan, bounded inflate, layered read; app import on the wasm; faunosteo-tools report-compare; TS reader and scripts/compare* deleted |
R2 | scan (39), inflate (9), read (13) suites reproduced in Rust; bombs: 64 MiB ObjStm in ms, EmbeddedFile bomb cancelled at 16 MiB, RSS flat (asserted natively); CLI 11 cases; DecompressionStream absent from the repo |
| R4b PDF writer (B, trigger: Step 15 or TTF) | layout → draw log → pdf-writer; AFM vendored; PNG gate + png; dates tables; exportFromEnvelope; draw-log recorder as the new golden producer (same JSON shape as the spies); pdf-lib, UPNG, standard-fonts, xmldom removed |
R3, R4a | the 39 goldens reproduced exactly through the Rust draw log (text x/y/size/font, images, links, views); new draw-log golden covering lines, rectangles and colours frozen with the TS engine before the port (owner decision to add); poppler/pdfium render diff of the three reports ≤ a stated threshold; re-export test; attachment stored size < 250 KB; pnpm report:compare --diff identical on the fixture PDFs; no pdf-lib in the lockfile |
| R4c Rasteriser option (D-R3) | wasm-raster module with resvg, lazy-loaded; canvas adapter kept as fallback for one release |
R4b | owner visual validation of the three reports; raster facts test green; main bundle size unchanged |
| R5 Curation pipeline + importer (B) | crates/anatomy feature curation and crates/tools import-equine; Prettier formatting kept as the last Node step (D-R5) or identity rule changed under a schema migration |
R2, R3, next content changeset | seed.golden.test.ts byte-exact on all 18 files (or the knowingly regenerated set with the new identity rule and a data migration for documentSha256); determinism and count tests; TS pipeline deleted |
| R6 Hygiene | retire packages/domain, packages/anatomy, packages/pdf TS packages when no importer remains; CLAUDE.md folder map; packages/README.md; CHANGELOG |
R2..R5 | no TypeScript business logic outside UI glue (grep census documented in RUST.md); workspace test count reconciled with a "deleted tests" list (TEST_STRATEGY §6) |
Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 immediately after Step 8 and before Step 9, so that every later step writes its rules in Rust rather than adding TypeScript logic to migrate twice. R3 and R4a follow in that order, interleaved with Steps 9 to 12 (they touch no backend table). R4b waits for its trigger. R5 waits for the next content changeset (the eleven open questions for the osteopath will produce one). R6 closes.
VI.3 Parity harness design
A vitest file per phase (tests/parity/<phase>.test.ts) imports the TS
implementation and the wasm, runs every fixture through both and
toEquals the outputs; for byte contracts (envelope JSON, composed SVG,
generated seed files) it compares strings. The harness is deleted with the
TS implementation. Cargo tests carry the same fixtures (copied under
crates/*/tests/fixtures, listed in a manifest checked against the TS
fixture directory by a test, so the two sets cannot drift during the
transition).
VI.4 What is deleted when
| Phase | Deleted |
|---|---|
| R2 | packages/domain/src/** Zod schemas and functions (types stay generated), rules inside components, services/zoneInteraction.ts, services/sheetIndex.ts shim |
| R3 | anatomy/drawing.ts denylist, packages/anatomy/src/render/**, packages/pdf/src/svg/** |
| R4a | packages/pdf/src/attachment/**, read.ts, apps/app/scripts/**, the DecompressionStream inflater |
| R4b | the rest of packages/pdf/src, pdf-lib, UPNG, standard-fonts, xmldom |
| R5 | packages/anatomy/src/{legacy,curation,cli}/** |
| R6 | the three TS packages |
Part VII. Adaptations to the development plan
| Step | Plan text today | Adaptation under the rule |
|---|---|---|
| 8 Files | Node worker + sharp (STEP8 D1) | D1 becomes "native Rust worker" (confirmed by the owner); R0 + R1 inside the step; apps/worker is not created; crates/worker is |
| 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors written in crates/domain and called through the wasm; UI unchanged |
| 13 Sheets in DB | SVG processor "from packages/pdf" | the Rust sanitiser of R3 runs in the worker's decode child (same isolation as images); the Supabase SheetProvider stays TS glue, parsing through the Rust core |
| 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; document diff/throttle rules in Rust; optional pg_jsonschema CHECK from the schemars output (decision at the step) |
| 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row" | the Rust worker validates the attachment with crates/domain + crates/pdf reader (R4a) and renders artifacts with the writer (R4b trigger); no Edge Function |
| 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in Rust |
| 17 Sheet editor | editor store with undo, geometry | document operations and geometry in crates/domain (or a crates/editor if the dependency boundary differs), UI React |
| 19 Notifications/worker | apps/worker Node, EmailProvider, private.jobs |
extends crates/worker: private.jobs loop (SKIP LOCKED through an RPC), templates rendered in Rust (packages/i18n split not needed for templates: the dictionaries used by templates move to Rust data) |
| 20–21 Agenda, travel | expiry rule TS mirror, routing adapter in the worker | mirror in Rust/wasm; routing provider adapter and calendar sync in crates/worker; the Google OAuth callback is the first inbound HTTP endpoint: a small axum service in the worker binary (serve subcommand) behind the reverse proxy, one route, no other port |
| 22 Public web | Q8 framework | Astro recommended (global rule, SEO/GEO, islands); D-R8 |
| 23 Billing | "Edge Function stripe-webhook" | the serve subcommand hosts the webhook (async-stripe or hand-written signature check); idempotency table unchanged |
| 24 Imports | adapters in the Node worker | adapters in Rust (csv, calamine, zip), same ImportAdapter contract |
| 26 Lifecycle | export/archive/restore jobs in the Node worker | Rust jobs in the same binary |
| 27 Hardening | adds cargo-audit, cargo-deny, fuzz results and the sandbox tests to the release gate |
|
| BACKEND_ARCHITECTURE §6 | Edge Function row | replaced by "Rust service (worker serve)"; PostgreSQL rows unchanged |
| WORKSPACE.md, packages/README.md | apps/worker Node, @faunosteo/i18n for the worker |
crates/*; the i18n package stays UI-only |
| TEST_STRATEGY.md | layers | adds the cargo layer, the parity harness rule and the conformance fixtures shared with pgTAP |
Part VIII. Docker, Supabase and CI impacts
VIII.1 Docker
- App image: a new first stage
FROM rust:1.99.0-bookworm AS wasm(cargo-chefprepare/cook for layer caching,wasm32-unknown-unknowntarget, pinnedwasm-bindgen-cli,binaryenvia npm or apt) producingpackages/core-wasm/pkg; the Node builder copies it beforepnpm build. The runner stage (nginx) is unchanged;.wasmserved withapplication/wasm(nginx mime types include it) and the existing no-cache rule onenv.jsuntouched. - Worker image:
rust:1.99.0-alpine3.24builder (musl,musl-dev,build-basefor libwebp'sccbuild) →gcr.io/distroless/static:nonroot(orscratch), one static binary,USER nonroot, no shell. Compose serviceworker(containerfaunosteo_worker):read_only: true,tmpfs: /tmp,cap_drop: [ALL],security_opt: [no-new-privileges:true],mem_limit: 512m,cpus: 1,pids_limit: 64, noports, Supabase internal network only,restart: unless-stopped,env_file: .env.worker. The default Docker seccomp profile stays (it permits the inner sandbox). - Naming:
faunosteo_worker, imagefaunosteo/worker, volumes as in STEP8 (BDR-035). - Build time: a cold Rust build of the wasm and of the worker is minutes
(UNVERIFIED on this runner);
cargo-chefand the registry cache mount make incremental builds seconds. R0 records the measured numbers.
VIII.2 Supabase
- No schema change comes from the rule itself. Step 8's migration gains the
optional
faunosteo_workerrole and grants (D-R6). - Conformance fixtures for
sheet_document_issuesland as a pgTAP file reading JSON fixtures (PGlite and real stack), owned by R2. - Managed migration: the worker container is hosting-agnostic (URL + token); the worker token on managed is minted with an imported ES256 standby key or the legacy secret while it exists.
VIII.3 CI (.gitea/workflows/ci.yml)
- New job
rust(runs beforecheck): toolchain fromrust-toolchain.toml(dtolnay/rust-toolchain),cargo fmt --check,cargo clippy --workspace --all-targets -D warnings,cargo test --workspace --locked,cargo deny check,pnpm wasm:build, artifactpackages/core-wasm/pkguploaded. Cache:Swatinem/rust-cacheif the Gitea cache server works (verify at R0), else a~/.cargo+targetdirectory cache on the runner host. checkdownloads the artifact beforepnpm install(or rebuilds it: R0 picks the faster on this runner).dockerbuilds both images.supabaseruns the worker integration test against the local stack.- Nightly:
cargo audit, a time-boxedcargo fuzzrun on the four targets. - The Node pipeline (
typecheck,test:run,lint,build) is unchanged in content; its duration shrinks as TS suites are deleted.
VIII.4 Local development
- Owner action: install
rustup(no global package;rustuplives in~/.cargo), the pinned toolchain installs itself fromrust-toolchain.tomlon firstcargo;wasm32-unknown-unknowntarget;cargo install wasm-bindgen-cli --version <pinned>andcargo-deny. pnpm devkeeps working:pnpm wasm:buildonce (and after Rust changes; acargo watchrecipe inRUST.md); Vite serves the.wasmfrom the package.- The worker runs against the local stack with
cargo run -p faunosteo-worker -- runand.env.worker(token minted by the SUPABASE.md §8 recipe).
Part IX. Validation criteria and risks
IX.1 Validation criteria of the orientation (beyond the per-phase ones)
- No regression on the owner's list: Report v3, v2 PDF import, autonomous archives, immutable sheet versions, RLS, unresolved findings, FR/EN, file security, graphics. Proof = the existing suites kept with their assertions (one-to-one migrations named in commits, TEST_STRATEGY §6), the goldens unchanged except where a decision regenerates them, the pgTAP suites unchanged.
- No duplicate business logic at the end of a phase (grep census of rule
names in TS outside UI glue, recorded in
RUST.md). - Security gates: the security-auditor runs on every phase; the worker
sandbox tests are part of the suite;
cargo-denyandcargo-auditare release gates. - Operability: worker image size, start time, memory ceiling and the sandbox ABI logged at start; a runbook line per failure mode in STORAGE.md.
- Cost visibility: CI duration and app bundle size before and after each phase recorded in the phase's TODO note.
IX.2 Risks
| Risk | Likelihood | Effect | Mitigation |
|---|---|---|---|
| Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; the parity harness catches what review misses |
| Dual toolchain in CI and Docker (minutes per build) | certain | CI time | caches (cargo-chef, registry mounts, runner cache); wasm artifact reused by check |
| WASM bundle growth | medium | first load | core without raster or fonts; resvg lazy; sizes recorded per phase; budget set at R0 (proposal: core ≤ 600 KB gzip) |
| Hidden JS semantics in outputs (float printing, upper-casing, ICU dates, kerning widths, rounding) | high | golden mismatches | the exact list of I.2; a draw-log golden on lines/rectangles/colours frozen before R4b; js_number tested on the committed overlays |
| Prettier-dependent sheet identity | certain for R5 | identity change breaks every report's sheet match |
keep the Prettier step (D-R5) or migrate the identity rule with the pending BLK-008 data migration |
| Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; recorder format change is a named deliverable |
Crates maintained by one person (zune-jpeg, moxcms, libwebp-sys, krilla, pdfium-render) |
medium | abandonment | cargo-deny unmaintained advisories; alternatives listed in Part V; decoders confined to the child |
roxmltree deep-nesting overflow (fix unreleased) |
known | DoS of the parser | depth cap by a byte pre-scan before parsing; pin the fixed release when out |
| Landlock absent on the VPS kernel | unverified | weaker child isolation | seccomp + rlimits still apply; worker logs the ABI; the runbook checks /sys/kernel/security/lsm |
| Gitea runner caches for Rust | unverified | slow CI | measured at R0; host-level cache fallback |
wasm-bindgen crate/CLI version lock |
certain | broken builds on drift | one pinned version in Cargo.lock and in the CI/Docker install line, checked by a script |
| Two implementations lingering | medium | drift, double maintenance | deletion list per phase (VI.4) is part of the Definition of Done |
| Edge-Function assumptions elsewhere in the plan | low | plan inconsistency | Part VII table applied to the plan text at R0 |
| Public web framework conflict | certain | decision needed | D-R8 |
IX.3 Explicit non-goals of the rule
- Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos, Dioxus): excluded by the owner's retained list and by the Step 7 validated mockups.
- Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer: excluded (retained list; RLS stays the boundary).
- Running Rust inside PostgreSQL (
pgrx): excluded by managed compatibility. - Moving the SQL rules to Rust: excluded; SQL keeps transactional rules.
IX.4 Unverified items (to settle at R0 or at the phase that needs them)
image0.25 onwasm32targets (not needed: images decode only in the worker).resvgbyte-identical output native vs wasm (README claim).- Exact libwebp version string in
libwebp-sys0.14.4 (≥ 1.6.0 confirmed by API presence). serde_json/zmijfloat exponent thresholds vs JavaScript (thejs_numberformatter is tested on the committed overlays regardless).- Gitea runner support for
Swatinem/rust-cache; cold build times. - Landlock on the Scaleway VPS kernel; distroless
nonrootUID. - Core wasm size and instantiate time (measured at R0/R2).
- Whether the attachment JSON bytes must stay identical across engines (no test pins them; D-R11 makes it a stated choice).
Part X. Decisions for the owner
| Id | Question | Recommendation |
|---|---|---|
| D-R1 | Workspace layout | Six crates (domain, anatomy, pdf, wasm, worker, tools), one per dependency or deployment boundary; not one core crate with features |
| D-R2 | PDF writer sequencing | R4b on the trigger (Step 15 or TTF fonts), after R3/R4a; port with the Standard 14 AFM metrics first (goldens exact), TTF as a separate later change with its own golden regeneration; not both at once |
| D-R3 | Rasteriser | Keep the browser canvas adapter at R4b; evaluate resvg in a lazy-loaded module afterwards with a visual validation (R4c); the Node tests already render with resvg |
| D-R4 | Lossy WebP encoder in the worker | libwebp-sys 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child, output re-verified by a pure-Rust decoder; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (ravif, pure Rust, changes D4's format) |
| D-R5 | Curation pipeline identity | Rust pipeline emits the data, a Node Prettier step formats the files, document_sha256 keeps its definition (byte golden intact); alternative: new identity rule (sha256 of canonical JSON) shipped with the BLK-008 data migration and a map of old → new hashes |
| D-R6 | Worker credential | Dedicated faunosteo_worker Postgres role + minted JWT (least privilege, no secret in the container); fallback service key as analysed |
| D-R7 | Form validation schemas | Stay TypeScript (React-bound); add the generated constraints.json so lengths, regexes and the password policy have one source |
| D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the public site needs no islands |
| D-R9 | Edge Functions | Retired from the plan; webhooks and OAuth callbacks served by the worker's serve subcommand behind the reverse proxy |
| D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4a interleaved with Steps 9–12; R4b/R5 on their triggers |
| D-R11 | Archive attachment bytes | Treat the pretty JSON with Zod-order keys as a contract (struct order mirrors it, parity test byte-equal); no test pins it today, so this is a choice, not a repair |
| D-R12 | Gated functions | Explicit go to port readArchiveDocument, readReportArchive, readAttachedDocument and rebaseReportOnSheet with behaviour preserved (CLAUDE.md gate) |
| D-R13 | Draw-log golden before R4b | Add a golden for lines, rectangles and colours with the current TS engine before the port (one regeneration decision, strictly additive) |
| D-R14 | WASM size budget | Core module ≤ 600 KB gzip, measured and enforced by a CI check from R2 |
The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native Rust worker" from this review on.