V1-2-6_R2_LABELS.md: the 45 i18n keys R2 adds, changes or removes (FR, provisional EN, where, status) with the ambiguities and the pending add-draft cancel question. RUST_ARCHITECTURE_REVIEW Part II: class C rows for the display-only reference modules (BDR-114 A). U1_CORRECTIONS §R2 status; BROWSER_TESTS: the two new specs, five tabs, editor-equine never run, the admin.spec crash risk; OWNER_TRIAL §4.10 db:trial protocol for R2 and stale four-tab / old-panel text updated; CLAUDE.md tree.
103 KiB
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
- 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-libunmaintained since 2021, BLK-009; UPNG trusting its input;DecompressionStreamas 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 (formatDatefor the UI,pickLabelin JSX) stay TypeScript and are not counted as unified. - 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".
- 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; the pair itself remains. - The sheet identity hash changes once.
documentSha256is 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. - 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).
- 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).
- 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,rustcorrustupon the development host (checked 2026-10-12). Rust stable 1.99.0 (2026-10-01); edition 2024 since 1.85. Onwasm32-unknown-unknownthe shipped standard library is panic = abort: a panic traps the instance andcatch_unwindnever 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) allowsseccomp,prctl,setrlimit,prlimit64unconditionally;unshareandclone3with namespace flags needCAP_SYS_ADMIN. A seccomp + rlimit child works inside a container; user-namespace isolation does not. - Production:
DEPLOY.mdsizes the VPS at 1 vCPU / 1 GB / 10 GB (the Node build already ran out of memory on DEV1-XS), deploys withdocker compose up --buildon the VPS, documents a rebuild as the rollback, and setsscript-src 'self'without'wasm-unsafe-eval'in both the nginx and the Caddy examples;docker/nginx.confhas nogzipdirective. - 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; "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-runtimecontainer, 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_SECRETor 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_jsonschema0.3.3 exists on managed and in thesupabase/postgresimage but not in PGlite; custompgrxextensions 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 search and sort | 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, it validates no stored field (the core's reference rules stay authoritative) | 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), 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 |
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 tocrates/core.
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")
- Coarse calls, JSON strings. One call per user action or per load,
never per render. Payloads cross as JSON strings (
serde_jsonwith thejs_numberformatter,JSON.parseon the TypeScript side); types come fromts-rs(packages/core-wasm/types). Noserde-wasm-bindgen, notsify: zero extra crates on the boundary, nonull-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. - The sheet is a handle.
SheetHandleis 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()returnsSheetIndexDataonce (plain data: views, annotations, finding zones, regions by id, annotations per view, spine per region and view,main_view_id,name_fr/name_enper annotation,node_by_path); React reads properties. - 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,snapshotRejectedreasons,ArchiveExportErrorkinds,internal). Theinstanceofchecks on domain errors go away with the TS classes. - Ids and time are inputs.
new_report(draft, sheet, id, created_at),write_archive(…, exported_at); TypeScript keepscrypto.randomUUID()andnew Date(). - Panics are traps, handled outside. On wasm32 the core is panic =
abort, so
catch_unwindis native-only. Libraries denyunwrap/expect; every TypeScript facade call catchesWebAssembly.RuntimeError, marks the instance poisoned, re-instantiates it (and rebuilds the sheet handle) before the next call, and surfaceskind: '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. - 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 acore_unavailablestate 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). - 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_numberfor floats; optional fieldsskip_serializing_if = "Option::is_none", nullable fields plainOption. 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-rsemits the TypeScript types; the Zod schemas of these contracts are deleted in the phase that switches their last consumer (VI.4), andpackages/domainis deleted at R5 (its app importers are codemodded to@faunosteo/core-wasmat 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_jsonschemaCHECK 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, thenwasm-bindgen --target web --out-dir packages/core-wasm/pkg; the CLI version is read fromCargo.lockby the install line in CI and Docker. Root scriptpnpm wasm:build;cargo test -p faunosteo-wasmwrites thets-rstypes.- Vite 7:
await init()lazily (III.3 rule 6),?urlresolution of the.wasm, no plugin. Vitest:init(readFileSync(wasmPath)). - Production serving (D-R13): CSP
script-src 'self' 'wasm-unsafe-eval'in bothDEPLOY.mdexamples with a sanity-check row; nginx serves a precompressed.wasm.gz(gzip_static) or addsapplication/wasmtogzip_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-debugbuilds 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/environis empty;Threads: 1holds when the filter is installed. - Parent checks: a child returning 511×511, an
EXIFchunk, 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
supabasejob): 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/fixturesandpackages/*/tests/fixtures, read by path; the two TypeScript fixtureshorse-slice.tsandmini-sheet.tsconverted 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-workspacefor 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 --buildon the VPS is replaced bydocker compose pull && up -don 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 intoDEPLOY.md(routine deploys, rollback, disk headroom). - App image: a first stage
FROM rust:1.99.0-bookworm AS wasm(BuildKit cache mounts on~/.cargoandtarget, pinnedwasm-bindgen-cli) producingpackages/core-wasm/pkg; the committedpackages/core-wasm/package.jsonis in the manifest COPY list sopnpm install --frozen-lockfilekeeps working; the Node builder copiespkg/beforepnpm build; nginx serves.wasm(and.wasm.gzwithgzip_static) with the hashed name. - Worker image:
rust:1.99.0-alpine3.24builder (musl,musl-dev,build-basefor libwebp'sccbuild) →distroless/static:nonroot(CA bundle present;scratchrejected), one static binary. 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 filter). - Naming:
faunosteo_worker, imagefaunosteo/worker(BDR-035).
VIII.2 Supabase
- No schema change comes from the rule itself.
- Conformance fixtures for
sheet_document_issuesland 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 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 licenses bans sources,pnpm wasm:build, artifactpackages/core-wasm/pkguploaded. Cache:Swatinem/rust-cacheif the Gitea cache server works (verified at R0), else a directory cache on the runner host. checkdownloads the artifact beforepnpm install.dockerbuilds both images and pushes them by tag and digest onmainanddevelop.supabaseruns 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 fromrust-toolchain.toml;wasm32-unknown-unknowntarget;cargo install wasm-bindgen-cli --version <from Cargo.lock>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(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), goldens unchanged except where a decision regenerates them, pgTAP unchanged, the N-1 reader test green at every phase.
- 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). - Security gates: the security-auditor runs on every phase; the worker
sandbox tests run on the production image;
cargo denylicences, bans and sources block, advisories gate releases. - 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.
- 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
resvgto 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_unwindon stablewasm32-unknown-unknownfor the pinned toolchain (handled as abort regardless). resvgbyte-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-sys0.14.4 (≥ 1.6.0 by API presence; logged at start, checked in CI). serde_json/zmijexponent thresholds vs JavaScript (thejs_numberformatter 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, pluswasm32-unknown-unknown,wasm-bindgen-cliat the version inCargo.lock,cargo-deny,binaryenforwasm-opt), used by CI and by the application and worker image builds. The worker's own builder staysrust:1.99.0-alpine3.24(musl,build-basefor libwebp). - The development host may install
rustupfor the inner loop (samerust-toolchain.toml, so the same compiler); the containerised build is the arbiter. Root scripts:pnpm rust:check(fmt, clippy, test, deny) andpnpm 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_methodsforstd::time,std::fs,std::envin 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+Localetypes, thejs_numberformatter, the conformance fixture loader),crates/wasm(facade exportingcore_version()and one JSON round-trip call),crates/worker(binary withrunprinting its configuration anddecodewired to the sandbox spike, no job logic).packages/core-wasm/package.jsoncommitted,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
rustbeforecheck: fmt, clippy, test,cargo deny check licenses bans sources, wasm build artifact;dockerjob 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 inRUST.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 ofrust-toolchain.toml,wasm32-unknown-unknown,wasm-bindgen-cliandcargo-denyat the pinned versions;cargo check / test / build / clippy / fmtand 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.