# Rust by default: architecture review and migration roadmap Status: study for the owner's decision, 2026-10-12, revision 2 after three independent plan challenges (correctness, robustness, simplicity: 61 findings, 2 blockers; what changed is listed in §0.2). Nothing implemented. Applies the owner's brief of 2026-10-12: Rust becomes the preferred language for everything that can reasonably be written in Rust, for new work and for existing code; equivalence suffices; "already in TypeScript" and "more work" are not reasons to keep TypeScript; a component kept in another language needs a concrete constraint. Part I states the facts (inventory, the hidden contracts a port must honour, the state of the Rust ecosystem on 2026-10-12, verified by three research agents against crates.io, RustSec, GitHub and the Supabase docs). Part II classifies every module (A now, B later with a trigger, C exception). Part III is the target architecture (workspace, boundary, bindings). Part IV is the Step 8 worker in Rust. Part V lists the libraries retained and their limits. Part VI is the progressive migration with end criteria and rollback. Part VII adapts the development plan. Part VIII covers Docker, Supabase and CI. Part IX gives validation criteria and risks. Part X lists the decisions the owner has to take. §0 states what this study pushes back on and what the challenges changed. Companion material: `STEP8_FILES_ANALYSIS.md` (the design this review keeps, with the worker runtime replaced), `PDF-FORMAT.md`, `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md` (contracts that stay as they are). --- ## 0. Pushbacks and revision notes ### 0.1 What this study pushes back on 1. **Where Rust buys something here.** The browser already runs memory-safe code, so "Rust is safer" is no argument for the SPA. The gains the study claims: one core that runs identically in the worker, the CLI tools and the browser (server-side archive validation at Step 15 needs the reader the browser has); untrusted bytes (images, SVG, PDF attachments) parsed on the server with hard allocation caps and without libvips, libpng, xmldom or UPNG in the trusted base; the removal of three dependencies the project already distrusts (`pdf-lib` unmaintained since 2021, BLK-009; UPNG trusting its input; `DecompressionStream` as the only inflater on every read path); and the unification of what the inventory found duplicated (two SVG sanitisers, two view compositions, three copies of the bilingual label fallback in rule code). Screen-only helpers (`formatDate` for the UI, `pickLabel` in JSX) stay TypeScript and are not counted as unified. 2. **The rule has a standing cost the project must own.** Two toolchains in CI and Docker, a WASM boundary to design, debug and keep safe, Rust skills on a one-person team, oracles to freeze before every switch. Each cost is made visible (Parts VIII, IX) instead of hidden in "equivalent". 3. **Rust does not remove the SQL mirror.** `private.sheet_document_issues` stays SQL because managed Supabase runs no custom `pgrx` extension; Rust replaces the TypeScript side of the pair; the pair itself remains. 4. **The sheet identity hash changes once.** `documentSha256` is today the sha256 of the Prettier-formatted document text. It is computed once by the pipeline and only compared at runtime; a different hash sends an old archive through the rebase path (visible import message, nothing lost), exactly as any content changeset does. The study therefore does not chain the pipeline to Prettier (D-R5); it states the one-time effect. 5. **One global rule conflicts with the new one.** The global CLAUDE.md mandates Astro for public sites; the Rust rule would prefer a Rust static generator. The study recommends keeping Astro and records the conflict as a decision (D-R8). 6. **Form validation stays TypeScript by the owner's own retained list** (code directly tied to React). The constraints themselves are written in two places today (Zod and SQL CHECKs) and already drift; a small chore outside this roadmap gives them one home (D-R7). 7. **The production surface decides more than the language.** Two of the blockers found by the challenges were deployment facts: the documented CSP refuses WebAssembly, and the VPS (1 vCPU, 1 GB) compiles the images it runs. Both are fixed in the roadmap before any wasm reaches production (D-R13, VIII.1). ### 0.2 Changes after the challenges (revision 2) Folded: three crates instead of six (one feature-gated core, one wasm facade, one worker binary with tool binaries); no throwaway dual-run parity harness (unpinned outputs frozen as goldens with the old code, oracle suites ported to cargo on the fixtures in place); consumer-driven deletion schedule (a TypeScript module is deleted in the phase that switches its last consumer, frozen and parity-tested in between; revision 1 deleted modules that later phases still imported); the PDF writer and the curation pipeline reclassified A with technical dependencies only (revision 1 deferred them for reasons the brief excludes); a two-call export (compose views, the caller rasterises, pure writer) that removes the async rasteriser from the boundary and the need for resvg in the browser; a Rust-owned sheet handle instead of re-shipping the sheet per click; JSON strings across the boundary with generated types (no `serde-wasm-bindgen`, whose `json_compatible` preset would write absent optionals as `null`); panic = abort on wasm32 handled on the TypeScript side (poison and re-instantiate); lazy wasm initialisation with a degraded state so the auth shell never depends on the module; the PDF reader in a Web Worker with the BLK-009 browser measurements as exit criteria; CSP `'wasm-unsafe-eval'` and gzip for the module; images built in CI and pulled by digest, never compiled on the VPS; per-phase rollback rows and draft quarantine instead of silent discard; the keyed worker parent never decodes (fixed-size read, RIFF header allowlist, no pixel decode); seccomp allowlist derived by tracing, applied before any thread exists, Landlock and three rlimits dropped as redundant; worker credential kept as validated (service key), the dedicated role moved to a hardening option with its exact prerequisites; display helpers and `isIdentityComplete` kept in TypeScript; `constraints.json`, `schemars`, `cargo-chef`, `cargo-audit`, `infer`, `img-parts`, fuzzing-now and the DEV footer removed; five JavaScript semantics on reader paths added to the contract list; Step 15 no longer cited as a rendering trigger; decisions merged from 14 to 13. Not folded (with the reason): "split R2 into three gates" is kept as an option for the implementation contract, since each sub-phase would create a short-lived TS-to-wasm seam inside the store; "keep the Landlock layer best-effort" is replaced by dropping it (the seccomp allowlist already denies every file and process syscall, so the layer would test nothing). --- ## Part I. Facts ### I.1 Inventory of the existing code Sizes are TypeScript lines (`wc -l`, `.d.ts` excluded), HEAD `aae0b39`. Test counts are static (`it` plus `.each` rows) except where a suite was run. | Unit | Source | Tests | Runs where | Purity today | |---|---|---|---|---| | `packages/domain` | 18 files, 2,298 lines; zod 3.25 only | 9 files, 162 cases (194 at runtime, one file re-imports another) | browser (app), engine, pipeline, scripts | pure: no `JSON.stringify`, no `Date`, no ids, no I/O; host APIs `structuredClone`, `TextEncoder`, `Object.hasOwn`, `new URL()` via Zod | | `packages/anatomy` | 43 files, 4,897 lines: legacy importer 1,842, curation 2,329, render 553, cli 119 | 15 files, 130 cases (run: 130/130) | **render only** at application runtime (app canvas, PDF composition); the other 4,344 lines run for `pnpm import:equine`, the pipeline and tests | render is pure (plain `LayerElement` tree); importer and pipeline use xmldom, `node:fs`, `node:crypto`, Prettier | | `packages/pdf` | 27 files, 3,122 lines; pdf-lib 1.17, @pdf-lib/standard-fonts, @xmldom/xmldom | 9 files, 137 cases | browser (export, import), CLI, tests | explicit inputs (report, snapshot, branding, labels, locale, rasterizer, exportedAt); platform APIs: `DecompressionStream` on every read path and in the PNG gate, `Intl.DateTimeFormat`, `TextEncoder/Decoder` | | `packages/supabase` | 949 lines (596 generated `database.types.ts`) + `scripts/upload-sheet-assets.ts` (99 lines, operator, service key) | 6 files; PGlite harness runs 9 pgTAP files, 280 assertions | browser, CI, operator | two rules only: GoTrue code → closed `AuthFailure` kind (23 → 13), publish gate (Zod + `assertPublishable` before the RPC); the rest wraps supabase-js | | `apps/app/src` logic layer (services, state, sheets, anatomy/drawing, auth, account, config, lib, i18n, providers, guards) | 37 files, 2,476 lines (1,708 without the two 281-key dictionaries) | 42 files, 214 cases + 7 `.each` blocks | browser | `services/zoneInteraction.ts` (213 lines) pure; stores are Zustand glue around domain calls; `drawing.ts` is DOM (DOMParser, importNode) with an app-local denylist sanitiser | | `apps/app/src` UI (components, routes, styles) | 65 files, 4,838 lines | component and route suites | browser | React; carries some data-building rules (I.2) | | `apps/app/src/pdf` + `scripts/` | 4 files, 235 lines + 2 files, 549 lines | 65 PDF-related app cases + 11 CLI cases | browser / Node | branding from bundled logos, `Image` + canvas rasterizer; CLI `report:compare` on the engine scanner | | `apps/app/vite/sheet-bundle.ts` | 102 lines | 7 | Vite build | virtual module embedding ~510 KB of seed JSON | | `supabase/` | 7 migrations, 9 pgTAP files, seed | 280 assertions (PGlite and real stack) | PostgreSQL | SQL; stays | Workspace total at the Step 7 closure: 763 vitest cases, lint 0, build and Docker green. ### I.2 Hidden contracts a port must honour These facts decide feasibility, not the line counts. Each one gets a fixture or a golden before the phase that touches it (Part VI). | Contract | Where | Consequence for Rust | |---|---|---| | `documentSha256` = sha256 of the Prettier-formatted lean document text, computed once by the pipeline (`pipeline.ts:163`, `format.ts`), only **compared** at runtime (`rebase.ts:119`, `envelope.ts:100`, pdf `export.ts:88`); a mismatch sends the report through `rebaseReportOnSheet`, which keeps every datum and flags only ids the sheet lacks | `packages/anatomy`, every Report v3 `sheet.documentSha256` | identity = sha256 of whatever bytes the pipeline emits; when the Rust pipeline emits different bytes, the hash changes once and every older archive rebases on import, as after any content changeset (D-R5) | | Generated coordinates and layer attributes are raw JS number strings (`1715.4285714285713`, `"1118"`, `"0.85"`); `CoordinateSchema` is `z.number().finite()` and most values are integer-valued floats (`"cx": 1523`) | pipeline outputs, review SVGs, layer attributes, snapshot in the archive | `serde_json` prints `1523.0`; a `js_number` formatter (shortest round-trip, JS rules for `.0`, `-0`, exponents at 1e21 / 1e-7) is installed as a custom `serde_json::Formatter` for **every** JSON output and used by the SVG serialiser; tested on the committed overlays | | Attachment JSON: `report`, `branding` and `labels` are serialised in **insertion order** as passed (pdf `export.ts:112-115`); only the snapshot is re-parsed (Zod schema order); zones are built `{annotationId, viewId, labelFrSnapshot, labelEnSnapshot, side}` with `vertebrae` appended last | engine, store reducers | the attachment bytes change at R2 when Rust emits struct-ordered objects: declared as a new contract (D-R11); what must hold is that every previous reader (the shipped Zod schemas, frozen as a test fixture) parses what Rust writes | | Optional vs nullable: `.optional()` fields are **absent** when unset (`side`, `unresolved`, `severity`, `nextAppointment`), `versionId` is required and `null` for bundled-draft reports | `packages/domain/src/report/v3.ts` | per-field serde attributes (`skip_serializing_if = "Option::is_none"` for optional, plain `Option` for nullable); a boundary that writes absent as `null` breaks every existing reader | | Text layout x positions depend on `widthOfTextAtSize`, which sums AFM widths **plus kerning pairs**, while `drawText` writes unkerned glyphs | engine render, 39 goldens (12 text, 12 images, 12 links, 3 views) | the Rust engine embeds the same AFM data (WX, N, KPX) and the same width rule; the goldens record drawn primitives, never PDF bytes, so exact reproduction is provable | | Dates through `Intl.DateTimeFormat` (ICU): `11 octobre 2026`, `November 20, 2026`, UTC; `Date.UTC` maps years 26–99 to 19xx | `packages/pdf/src/render/dates.ts` | explicit fr/en month tables; the two-digit-year quirk is decided (tighten) with a fixture | | `toUpperCase()` on labels before `safeText`; `wrapLines` splits on `/\s+/` (keeps a trailing empty word; JS `\s` ≠ `char::is_whitespace` on U+FEFF, U+0085) | engine | same Unicode upper-casing in Rust; whitespace class written explicitly; fixtures for both | | Reader leniency: `TextDecoder` non-fatal (invalid UTF-8 → U+FFFD, BOM stripped, `scan.ts:498`); `JSON.parse` keeps the last duplicate key; Zod `.int()` accepts `2.0` | engine reader, domain | `serde_json` rejects all three; each is decided (keep lenient with a custom step, or tighten) and pinned by a hostile fixture before R4 | | One inflater: `DecompressionStream('deflate')` on browser, Node tests and CLI; the PNG gate inflates IDAT natively against the exact raw size | engine read path, branding | `miniz_oxide` bounded inflate replaces it everywhere (no Web API on the read path) | | Two sanitisers: app canvas denylist (`drawing.ts`: 5 tags, `on*`, `javascript:`) and engine allowlist with caps; the engine's "zero-removal" oracle is xmldom's own re-serialisation | app vs engine | one Rust sanitiser; the oracle becomes a DOM-equivalence check (parsed trees compared), not bytes | | Two view compositions: `composeViewSvg` mutates an xmldom element passed by the engine; the app composes with the browser DOM; the `review/app-*.svg` byte goldens are xmldom `XMLSerializer` output (declaration, whitespace nodes, `xlink:` prefixes) | engine vs app vs pipeline | one Rust `compose_view_svg` for app and engine; the xmldom-byte goldens stay owned by the TS pipeline until R5, where their regeneration is a decided change | | `buildSheetIndex` returns ten closures over four private `Map`s and the whole `LoadedSheet` (296 KB document, 130 KB drawing, 84 KB map), called per render by ~14 modules and taken by the reducers | domain sheet-index, app | the sheet lives once in Rust memory as a handle; React reads a precomputed plain-data index (names, node-by-path) built once | | Integrity rules: 21 TS codes with paths; SQL mirrors 17 error codes (codes only) and adds 3 of its own | domain `validate.ts`, migrations | the Rust validator takes the TS role; SQL stays; conformance fixtures carry two expectation sets (Rust: codes + paths; SQL: codes) | | `instanceof` on three domain error classes in pdf and app scripts | domain errors | closed kind discriminants at the boundary (BDR-015 pattern) | | Report ids `crypto.randomUUID()`, `createdAt` / `exportedAt` from `new Date()` | `apps/app` | ids and timestamps are inputs of the core | | Store takes `hydrateReport(report)` as is, no parse; `initReport` only trims | `reportStore.ts` | the Rust parser becomes the single entry for any report entering the store | | Rules living in UI files that **build data**: `FindingsTreePicker.toggleLeaf` (Finding with snapshots and the vet flag), `VertebraPicker` selection rules | components | move to the core with the reducers (R2); display helpers (`zoneLabel`, `zoneTrees`, `describeZone`, import message lines, `isIdentityComplete`) stay TypeScript glue over precomputed data | | Draft persistence drops an unparseable draft silently (`persistence.ts:55-58`, DEV warning only) | app | a draft the running build cannot parse is kept under a quarantine key with a visible notice (needed by every phase's rollback, VI.3) | | The wasm module is a new single point of failure: `useSheet.ts` caches a rejected promise for the session and has no error state | app | lazy initialisation behind the sheet and import paths only, a `core_unavailable` state with retry, auth shell independent of the module | ### I.3 Toolchain, host and deployment facts - No `cargo`, `rustc` or `rustup` on the development host (checked 2026-10-12). Rust stable 1.99.0 (2026-10-01); edition 2024 since 1.85. On `wasm32-unknown-unknown` the shipped standard library is panic = abort: a panic traps the instance and `catch_unwind` never returns (verify at R0; consequence handled in III.3). - Docker 29.8.2 rootless on the host (seccomp builtin, `rootless`, `cgroupns`), kernel 7.0. Docker's default seccomp profile (rootless included) allows `seccomp`, `prctl`, `setrlimit`, `prlimit64` unconditionally; `unshare` and `clone3` with namespace flags need `CAP_SYS_ADMIN`. A seccomp + rlimit child works inside a container; user-namespace isolation does not. - Production: `DEPLOY.md` sizes the VPS at 1 vCPU / 1 GB / 10 GB (the Node build already ran out of memory on DEV1-XS), deploys with `docker compose up --build` **on the VPS**, documents a rebuild as the rollback, and sets `script-src 'self'` without `'wasm-unsafe-eval'` in both the nginx and the Caddy examples; `docker/nginx.conf` has no `gzip` directive. - CI runs on a Gitea `act_runner`; JavaScript actions need `node` in the job image; `dtolnay/rust-toolchain` and `taiki-e/install-action` are shell composites; `Swatinem/rust-cache` relies on `actions/cache` (Gitea runner v5 has a per-runner cache server; not verified on this forge). ### I.4 Ecosystem facts (as of 2026-10-12) Verified on crates.io, docs.rs, GitHub and RustSec; "UNVERIFIED" items are in IX.4. Core and bindings: | Need | Crate | Version (date) | Status | Limits | |---|---|---|---|---| | JSON | `serde` / `serde_json` | 1.0.229 / 1.0.154 (2026-10-11) | serde-rs org | pretty printer matches `JSON.stringify(v,null,2)` except integer-valued floats (`3.0`) and `-0.0`: custom `Formatter` (I.2) | | Hashing, base64 | `sha2` 0.11.1, `base64` 0.23.1, `hex` 0.4.3 | | RustCrypto / marshallpierce | none open | | Inflate | `miniz_oxide` 0.9.1 (2026-03), `flate2` 1.1.10 | pure Rust | | `decompress_to_vec_zlib_with_limit`, streaming `Decompress` for incremental cancel | | WASM glue | `wasm-bindgen` 0.2.129 (2026-09-25), `js-sys` / `web-sys` 0.3.106 | org `wasm-bindgen` (Cloudflare maintainers), monthly releases, MSRV 1.81 | since 0.2.128 the crate and the CLI must be the same version: the CI and Docker install lines read it from `Cargo.lock` | | WASM build | `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen-cli`; `wasm-pack` 0.15.0 (one maintainer, 335 open issues) | | cargo + CLI, pinned; `wasm-opt` (npm `binaryen` 132) only when the size budget needs it | | Types for TypeScript | `ts-rs` 12.0.1 (2026-01): `.ts` files written by `cargo test`; `Option` → `T \| 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/` and Storage `/storage/v1` (~10 endpoints) | | Toolchain | `rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}`, `cargo-deny` 0.20.2, `distroless/static:nonroot` (Debian 13, CA bundle included) | | | Baseline for comparison, `sharp` 0.35.5 (2026-09-27): libvips 8.18.7, libwebp 1.6.0, libpng 1.6.58, mozjpeg; strips metadata and converts to sRGB by default, `limitInputPixels` 268 MP, WebP q80; EXIF orientation only with `autoOrient`/`rotate()`. libvips had three High CVEs in July and August 2026, libpng twelve CVEs since late 2025. The Rust pipeline's advantage is the loader surface (three formats, pure-Rust decoders, hard caps), not the encoder (still libwebp, confined to the child process). Supabase platform facts: - Edge Functions (managed: 2 s CPU, 256 MB, 150 s wall clock; self-hosted: `edge-runtime` container, hand-deployed) run Deno, which can execute a wasm build of the core; the rule retires them from the plan for those limits, the hand deployment and the preference for one Rust runtime (D-R9). The language alone would allow them. - A dedicated Postgres role is honoured by PostgREST and storage-api (official custom-roles guide), with a JWT minted from the legacy HS256 `JWT_SECRET` or an imported ES256 standby key; on managed the imported key must become a signing key of the project. Recorded as a hardening option (IV.4), not adopted. - `pg_jsonschema` 0.3.3 exists on managed and in the `supabase/postgres` image but not in PGlite; custom `pgrx` extensions have no documented path on managed. --- ## Part II. Classification of every module ### II.1 Criteria Business logic = anything that interprets or transforms the sheet, report or archive data, encodes a product rule (what a click does, how a finding is built, how a report migrates), parses untrusted bytes, or runs as a job or a service. Glue = React rendering and display formatting, routing, DOM access, store subscription, vendor SDK calls, build tooling. The owner's brief keeps glue in TypeScript; everything else is Rust unless a concrete loss is named on the brief's list (features, UX, graphics, data compatibility, security, reliability, useful performance, resources, portability, maintainability, deployment). Absence of a performance gain is never a reason for C. Classes: **A** = Rust, scheduled on technical dependencies only; **B** = Rust, waiting for a named external trigger; **C** = exception with its concrete constraint. ### II.2 Module table | Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Oracle for the switch | Class | Phase | |---|---|---|---|---|---|---|---|---|---| | domain: sheet document schema, `validateSheetDocument` (21 rules), `createEmptySheetDocument` | shape and integrity of the sheet | Zod | serde structs (strict = `deny_unknown_fields`, defaults), hand-written rules returning `SheetIssue {code, severity, path, message}` | yes + native | app load and publish gate call the core; types from `ts-rs` | low: codes and paths pinned by the validate suite; strict/strip policy per schema reproduced | validate suite (exact code + path lists), `horse-slice` fixture (converted to JSON), the draft document (0 issues) | **A** | R2 | | domain: report v3, v2 input, `migrateReportV2ToV3`, `readReportDocument` | report contract and migration | Zod | full; "never throws on content" made true (today a malformed map entry can throw a raw `ZodError`) | yes + native | store hydrates only through the core | medium: strip semantics, `requiresVetReferral: false` dropped in v3 (kept, pinned), optional vs nullable fields | 612-leaf migration suites, golden v2 fixtures, migration map | **A** | R2 | | domain: `rebaseReportOnSheet` | rebase on another sheet | TS over the index | full; takes the sheet handle | yes | store restore and import | CLAUDE.md gate: behaviour preserved exactly | rebase suite (exact objects) | **A** (owner go, D-R12) | R2 | | domain archive: `buildSheetSnapshot`, `assertSnapshot`, envelope v1 layered read, branding + labels schemas | archive contract | Zod | full; UTF-16 string caps and UTF-8 asset caps reproduced; closed `snapshotRejected` reasons | yes + native | app import and export | medium: attachment bytes change once (D-R11); `origin` quirk for unknown envelope versions preserved | envelope decision table, branding/labels suite, size test, three envelopes frozen as goldens | **A** | R2 | | domain: `buildSheetIndex` | lookups by id | closures over Maps | different shape: a Rust-owned `SheetHandle` (built once per session) for the core calls, plus `SheetIndexData` exported once for React (views, annotations, finding zones, regions by id; annotations per view; spine per region and view; precomputed `name` per annotation in both languages; `node_by_path`) | yes | ~14 modules read properties instead of calling closures; no wasm call in a render | low; one duplicate-id policy (document order, first wins) | service and component suites | **A** | R2 | | `apps/app/src/services/zoneInteraction.ts` | click decision, observation reducers | pure TS | full; `apply_click(handle, observation, annotation_id, view_id)`, `sync_vertebrae(handle, …)` | yes | `EditorRoute.onZoneClick` and `ObservationPickers` call the core per click with the observation only (the sheet stays in the handle) | low | 13-case service suite, route click-chain characterisation | **A** | R2 | | data-building rules in components: `toggleLeaf` (Finding builder), `VertebraPicker` selection | product rules inside components | TSX | `build_finding`, `vertebra_selection` in the core | yes | components call the core on the user action | low | component suites keep their assertions | **A** | R2 | | display helpers in components and routes: `zoneLabel`, `zoneTrees`, `unresolvedFindings`, `describeZone`, import message lines, `isIdentityComplete`, `pickLabel` in JSX | formatting of core data for the screen | TSX | portable, but run inside renders and `useMemo` with `t()`; moving them means wasm calls in the render path or a view-model layer | no | none; they read `SheetIndexData` | none | existing suites | **C**: React render glue over precomputed data (the sheet names and `node_by_path` they need come from the core) | n/a | | `reportStore.ts` actions | report construction and edits | Zustand | rules in the core (`new_report(draft, sheet, id, created_at)`, `swap`, `set_*` validation); the store stays Zustand | yes | one-line delegations | low | store suite | **A** (rules) / C (Zustand, adapters) | R2 | | `persistence.ts`, `practitionerCache.ts`, `localeStore.ts`, `authStore.ts`, `localeSync.ts` | storage adapters, GoTrue event glue | TS | glue; the only rules (`isLocale`, "account locale wins once per sign-in") are tied to supabase-js events | no | none | none | existing suites | **C**: browser storage and supabase-js session glue (no Rust GoTrue client with PKCE and refresh) | n/a | | anatomy render: layer renderer, `composeViewSvg`, highlight, `viewBoxOf` | markers from the document; composition with highlight | pure tree + DOM mutation | `render_annotation_layer(document, view, states) → LayerElement` (same plain contract) and `compose_view_svg(asset, document, view, highlight) → String` | yes + native | app canvas and engine use one composition; `drawing.ts` parses a sanitised string with `DOMParser` and keeps `importNode` + click delegation | low on the layer (step6 view facts); the composed string is compared as parsed trees, not bytes | step6 `views.*.json`, DOM-equivalence of the composed views for the three reports (frozen with the TS code), security SVG cases | **A** | R3 | | pdf `svg/{parse,sanitize,view}` + app `drawing.ts` denylist | untrusted SVG → safe tree | xmldom / DOMParser | `roxmltree` with DTD refused and a byte pre-scan for depth and size, own allowlisted tree, own serialiser; one sanitiser for canvas, PDF, Step 13 uploads and branding SVG | yes + native | denylist deleted | medium: the "zero-removal" oracle becomes a DOM-equivalence test on `horse.svg` | 7 hostile cases, caps, zero-removal (tree compare) | **A** | R3 | | pdf reader: byte scan, bounded inflate, JSON depth pre-scan, stamp, layered read; PNG gate inflater | untrusted PDF → archive outcome | TS + `DecompressionStream` | `miniz_oxide` streaming inflate with cancel; same candidate ordering and budgets; the leniency decisions of I.2 pinned | yes (in a Web Worker) + native (Step 15 server validation, CLI) | app import runs the core in a dedicated Web Worker terminated after each import | low: scan (39), inflate (9), read (13) suites are byte-level oracles | the same suites in cargo on the fixtures in place; BLK-009 browser measurements | **A** | R4 | | pdf writer: layout, pages, footer, links, attachment, metadata, `exportFromEnvelope`, branding PNG gate, `safeText`, `wrapLines`, labels (25 keys) | A4 archive writer | pdf-lib | `pdf-writer`; layout split from serialisation (draw log = the golden format); AFM vendored; `png` decodes the archived logos under the existing gate; fr/en month tables | yes + native | two synchronous calls: `compose_export_views(report, snapshot, branding) → [{key, svg, size}]`, the caller rasterises (canvas in the browser, resvg natively), then `write_archive(input, pngs) → {pdf, warnings}`; no rasteriser callback crosses the boundary | medium: widths with kerning, `Math.round` half-up, dates, upper-casing; lines, rectangles and colours are not golden-covered today (D-R2 adds that golden with the TS engine first) | 39 goldens through the Rust draw log, links read back from the written file with `lopdf`, re-export test, size test, poppler/pdfium render diff | **A** (after R3 and the reader; same phase as the reader) | R4 | | `apps/app/src/pdf/browserRasterizer.ts` | SVG → PNG via `Image` + canvas | DOM | DOM adapter between the two core calls; a native rasteriser (`resvg`) serves the worker and tools if a server-side rendering need appears | no | unchanged | none | raster facts test | **C**: browser rasterisation is DOM; no resvg in the browser bundle (D-R3) | n/a | | `apps/app/src/pdf/export.ts`, `import.ts`, `branding.ts` | wiring, Vite asset imports, download | TS | glue | no | thin | none | existing suites | **C**: Vite asset imports, Web Worker and DOM download | n/a | | `apps/app/scripts/compare-reports.ts` + `compare/report.ts` | archive check CLI | tsx + Node | `faunosteo-tools report-compare` on the core (LRN-044 escaping ported) | native | none | low | 11 CLI cases | **A** | R4 | | anatomy curation pipeline (changeset, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) + legacy importer | changeset → draft artifacts; baseline import re-run at every regeneration | TS + xmldom + Prettier + `node:fs` | full (sha-derived "v5-like" uuid, strict label equality, region inference, ops); outputs emitted by Rust with `js_number`; markdown tables written by Rust; Prettier no longer touches generated files (`.prettierignore`) | native (tools) | none | the 18 generated files and `documentSha256` change once (D-R5); counts, determinism and the 612-leaf semantics are the oracles | `seed.golden.test` (regenerated once, decided), determinism and count suites, 612-leaf test, review drawings compared as parsed trees against the xmldom-era files | **A** (after R2, R3) | R5 | | `packages/supabase/scripts/upload-sheet-assets.ts` | operator upload of sheet SVGs (service key) | tsx + Node | `faunosteo-tools upload-sheet-assets` (reqwest) | native | none | none | manual operator check (SUPABASE.md §3.1) | **A** | R5 | | `packages/supabase` `classifyAuthError`, publish gate | closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue | partial | gate delegates | none | existing suites | gate **A** (R2); code map **C** (supabase-js error shapes) | R2 | | `packages/supabase` client factory, auth/profile wrappers, `database.types.ts`, PGlite harness | vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser; PGlite is a JS/WASM library | no | none | none | | **C** | n/a | | `auth/validation.ts`, `account/validation.ts` (Zod, i18n keys) | form field rules | Zod | portable but React-bound (retained list); the constraints are duplicated in SQL CHECKs and `config.toml` and drift (trim, UTF-16 vs `char_length`, `''` on names) | no | | | one constants module + a PGlite test reading `pg_constraint` and `config.toml` with the counting rule recorded (separate chore, D-R7) | **C** | chore | | `lib/{dates,id}.ts` | `nowIso`, `todayIso`, `formatDate` (screen), `generateId` | Web APIs | clock and ids injected into the core; screen dates stay `Intl` | no | | | | **C** | n/a | | `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). --- ## Part III. Target Rust architecture ### III.1 Cargo workspace (three crates) ```text faunosteo/ ├─ Cargo.toml workspace: members crates/*, [workspace.dependencies], lints │ (unwrap_used / expect_used = deny in the library, │ disallowed_methods for std::time, std::fs, rand in core) ├─ rust-toolchain.toml channel pinned (1.99.0 at adoption), target wasm32-unknown-unknown ├─ deny.toml cargo-deny: licences allow-list (MIT, Apache-2.0, BSD, MPL-2.0, │ APAFML for the AFM data), bans (duplicate versions), sources ├─ crates/ │ ├─ core/ faunosteo-core (lib). Modules: domain (sheet, report, archive, │ │ index, reducers, rules), anatomy (xml tree, sanitiser, │ │ serialiser, layer, compose), pdf (reader, writer, afm, png gate, │ │ labels), curation (pipeline, importer). Features: `xml`, │ │ `pdf-read`, `pdf-write`, `curation`, `cli`. No I/O, no clock, │ │ no ids in any module (lint-enforced). [[bin]] targets behind │ │ `cli`: report-compare, import-equine, upload-sheet-assets. │ ├─ wasm/ faunosteo-wasm (cdylib): the wasm-bindgen facade over core │ │ (features xml + pdf-read + pdf-write), JSON strings in and out, │ │ closed error kinds, `ts-rs` types emitted into │ │ packages/core-wasm/types. │ └─ worker/ faunosteo-worker (bin): `run` (job loop, transport, sweeper, │ watchdog), `decode` (the sandboxed child), later `serve` │ (inbound HTTP). Depends on core without the pdf features │ until Step 15. └─ packages/core-wasm/ committed package.json (exports → pkg/) and generated types; pkg/ (js, wasm, d.ts) is git-ignored and built by `pnpm wasm:build` ``` Why three: one library keeps every rule in one dependency graph and one test run; features keep `pdf-writer` and `roxmltree` out of the worker build until it needs them (`cargo build -p faunosteo-worker` compiles only the features it enables); the facade and the binary are the two deployment boundaries. A `crates/editor` for Step 17 is not planned; editor operations are a module of core (D-R1). ### III.2 Native and WASM: who runs what | Code | Native | WASM | |---|---|---| | core domain | worker (Step 15 validation), tools, cargo tests | app: parse, validate, index, reducers, rules, snapshot, envelope | | core anatomy | worker (Step 13 uploads), tools (pipeline) | app: sanitise, compose views for the canvas and the export | | core pdf | worker (Step 15), tools (report-compare) | app: reader (in a Web Worker), writer | | core curation | tools only | never | | worker | container `faunosteo_worker` | never | Platform access (clock, ids, storage, network, DOM, rasterisation) is injected; the core never calls `std::time`, `rand`, `fs` or `fetch`. ### III.3 Boundary rules ("Rust computes, TypeScript reads") 1. **Coarse calls, JSON strings.** One call per user action or per load, never per render. Payloads cross as JSON strings (`serde_json` with the `js_number` formatter, `JSON.parse` on the TypeScript side); types come from `ts-rs` (`packages/core-wasm/types`). No `serde-wasm-bindgen`, no `tsify`: zero extra crates on the boundary, no `null`-for-absent trap, payloads readable in the debugger. The kilobyte-sized observations and outcomes make the string cost irrelevant; the sheet never crosses more than once. 2. **The sheet is a handle.** `SheetHandle` is a `#[wasm_bindgen]` struct built once per session from the loaded sheet (document, assets, migration map); every core call that needs the sheet takes the handle by reference. `handle.index_data()` returns `SheetIndexData` once (plain data: views, annotations, finding zones, regions by id, annotations per view, spine per region and view, `main_view_id`, `name_fr`/`name_en` per annotation, `node_by_path`); React reads properties. 3. **Errors are closed kinds.** Every fallible call returns `{ ok: true, value } | { ok: false, kind, detail }` with the kinds already named in the code (`invalid_pdf`, `no_attachment`, `incompatible_version`, `snapshotRejected` reasons, `ArchiveExportError` kinds, `internal`). The `instanceof` checks on domain errors go away with the TS classes. 4. **Ids and time are inputs.** `new_report(draft, sheet, id, created_at)`, `write_archive(…, exported_at)`; TypeScript keeps `crypto.randomUUID()` and `new Date()`. 5. **Panics are traps, handled outside.** On wasm32 the core is panic = abort, so `catch_unwind` is native-only. Libraries deny `unwrap`/`expect`; every TypeScript facade call catches `WebAssembly.RuntimeError`, marks the instance poisoned, re-instantiates it (and rebuilds the sheet handle) before the next call, and surfaces `kind: 'internal'`. The hostile corpus (security and scan suites) runs through the wasm build at the shipped shadow-stack size (set explicitly with `-C link-arg=-zstack-size`), not only natively. 6. **Lazy, degradable initialisation.** The module loads behind the sheet and import paths only; `/login`, `/app/*` and Mon compte never touch it. A failed load yields a `core_unavailable` state with a retry that evicts the cached promise. The import path runs the reader in a dedicated Web Worker with its own instance, terminated after each import (linear memory never shrinks; BLK-009 wants a bounded blast radius). 7. **Deterministic serialisation.** Struct fields in a declared order (the Zod schema order for the snapshot, the store's insertion order for the report), integer fields as integers, `js_number` for floats; optional fields `skip_serializing_if = "Option::is_none"`, nullable fields plain `Option`. A permanent compatibility test parses every Rust-written envelope and draft fixture with a frozen copy of the last shipped Zod schemas (the "N-1 reader" test, VI.3). ### III.4 Contracts: one source of truth - **Rust is the source** for the sheet document, the report, the migration map, the envelope, the snapshot, the branding and the labels. `ts-rs` emits the TypeScript types; the Zod schemas of these contracts are deleted in the phase that switches their last consumer (VI.4), and `packages/domain` is deleted at R5 (its app importers are codemodded to `@faunosteo/core-wasm` at R2). - **SQL keeps its mirror.** Conformance fixtures (`crates/core/tests/ conformance/*.json`: document, expected Rust issues with paths, expected SQL codes) are run by cargo and by a pgTAP file generated with the fixtures inlined (PGlite runs SQL text only); a drift test regenerates and compares the pgTAP file. - **JSON Schema** is not produced until a consumer exists (`pg_jsonschema` CHECK is an option for Step 14, which stores reports). - **Generated database types** stay `supabase gen types`. ### III.5 Build and serving of the wasm - `cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown`, then `wasm-bindgen --target web --out-dir packages/core-wasm/pkg`; the CLI version is read from `Cargo.lock` by the install line in CI and Docker. Root script `pnpm wasm:build`; `cargo test -p faunosteo-wasm` writes the `ts-rs` types. - Vite 7: `await init()` lazily (III.3 rule 6), `?url` resolution of the `.wasm`, no plugin. Vitest: `init(readFileSync(wasmPath))`. - Production serving (D-R13): CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples with a sanity-check row; nginx serves a precompressed `.wasm.gz` (`gzip_static`) or adds `application/wasm` to `gzip_types`; the hashed file name invalidates caches at each deploy. The size budget counts bytes actually served (`curl --compressed`), proposal: core module ≤ 600 KB compressed, measured at R2 and enforced by a CI check. - Debugging: `--keep-debug` builds in development, Chrome DWARF extension; a vendored 30-line panic hook (the upstream crate is archived). --- ## Part IV. Step 8 worker in Rust Everything in `STEP8_FILES_ANALYSIS.md` Part II stays (buckets, `assets` table, RPCs, keys, quarantine, purge queue, backups, migration runbook, UI, D1 to D9). What changes is the runtime of II.1 and II.8: one Rust binary replaces the Node process and `sharp`. The keyless-decoder invariant of STEP8 IV.3 ("the keyed process never decodes") is kept. ### IV.1 Process model ```text 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/ (≤ 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/ (upsert) → POST rpc/complete_avatar_job → DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job SIGSYS, SIGKILL (deadline) and RLIMIT deaths are logged with their own internal code (syscall number for SIGSYS) and mapped to processing_error; after 20 s the parent SIGKILLs sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep watchdog: per-stage deadlines (claim 35 s, download 35 s, decode 25 s, upload 35 s, commit 35 s); a stage past its deadline exits the process; Docker restarts it start-up log: libwebp version (WebPGetEncoderVersion, CI fails below 1.6.0), seccomp status, token expiry (service key: none) ``` The crash matrix, the write order, the lease and attempt rules, the purge grace periods and the fairness rule of the Step 8 analysis apply unchanged. The 60 s single watchdog of the Node proposal is replaced by per-stage deadlines, because one iteration's worst case (three 30 s network calls plus the 20 s child) exceeded it and would have burnt leases during a slow Storage. ### IV.2 Comparison with the Node proposal | Aspect | Node 24 + sharp (STEP8 II.8) | Rust worker | Verdict | |---|---|---|---| | Decoders on untrusted bytes | libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 | `zune-jpeg` (SIMD `unsafe`, togglable), `png` (no `unsafe`, fuzzed), `image-webp` (`forbid(unsafe)`), hard `Limits` | Rust better: smaller trusted base, caps by construction | | Encoder | libwebp via sharp | libwebp via `libwebp-sys` 0.14 (C), in the same sandboxed child, on a buffer that child decoded; the parent checks the container header only | equivalent; the C surface is the encoder, process-confined (D-R4 lists the alternatives) | | Orientation, ICC, metadata | `rotate()`, ICC → sRGB and stripping by default | `apply_orientation`, `moxcms` ICC → sRGB, stripping by construction (the encoder writes no metadata chunk) plus the parent's chunk allowlist | equivalent, verified rather than assumed | | Isolation | two Node processes, child without env | one static binary, child without env **plus** rlimits and a traced seccomp allowlist installed before any thread | Rust better | | Resource bounds | `limitInputPixels`, `mem_limit` 512m, 20 s kill | `Limits`, `RLIMIT_AS`, `RLIMIT_CPU`, 20 s kill, output cap 512 KiB, `mem_limit` | better | | Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB | Rust better on resources | | Transport to Supabase | supabase-js with the service key over PostgREST and Storage | `reqwest` calls to the same two APIs with the same key (`webpki-roots` compiled in for HTTPS on managed) | equivalent | | Maintenance | `sharp` Renovate rule | `cargo deny` in CI (licences, bans, sources blocking; advisories nightly) | equivalent | | Managed Supabase | URL + key only | same | equivalent | | Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule; built in CI, pulled by digest (VIII.1) | ### IV.3 Worker crates `tokio` (rt, process, time, io), `reqwest` (rustls, json, stream, `webpki-roots`), `serde` / `serde_json`, `image` (default-features off; `jpeg`, `png`, `webp`), `moxcms` (version resolved by `image`), `libwebp-sys`, `sha2`, `rlimit`, `seccompiler`, `tracing` + `tracing-subscriber` (JSON logs, field allowlist, control characters escaped: LRN-044), `thiserror`. No database driver (one transport, no open DB port on managed, as in STEP8 II.8). ### IV.4 Credential: as validated, with one hardening option recorded The worker holds the service key in `.env.worker` as the owner validated (STEP8 D1, II.8). A dedicated `faunosteo_worker` Postgres role with a minted JWT would narrow a leak, but it is independent of the language and is not "at the same cost": it needs the role granted to `authenticator` (the PGlite shim defines only `anon`, `authenticated`, `service_role`), EXECUTE on the nine worker RPCs plus a new RPC for the key-driven sweep lookup, `SELECT`, `INSERT`, `UPDATE` and `DELETE` policies on `storage.objects` for the role (which breaks the pinned census "2 / 1 / 0 per bucket" and the assertion "no UPDATE / DELETE policy exists"), token expiry handling (log `exp` at start, warn 30 days before, re-mint), a revocation path (`REVOKE faunosteo_worker FROM authenticator` plus re-mint), and on managed an operator-held signing key. Recorded as a Step 27 hardening option with those prerequisites; not a decision of this study. ### IV.5 Tests specific to the Rust worker - Decode child fixtures (STEP8 IV.2 list, unchanged): JPEG/PNG/WebP accepted, renamed PNG, GIF/BMP/SVG/PDF/HTML refused, truncated, 32 px, 20 000² header, 5000², EXIF-rotated → upright and chunk-free, PNG trailer after IEND, progressive JPEG with many scans and a large ICC under the deadline with RSS asserted, sleeping child killed at 20 s. - Sandbox tests (Linux, on the production image in CI): every accepted fixture passes through the **fully** sandboxed child (the allowlist is derived, then proven on the corpus at the caps: 4096² RGBA, 16-bit PNG, CMYK JPEG, ICC through `moxcms`); a disallowed syscall kills the child and the parent logs SIGSYS with the syscall number; `/proc/self/environ` is empty; `Threads: 1` holds when the filter is installed. - Parent checks: a child returning 511×511, an `EXIF` chunk, a wrong RIFF size, 513 KiB of output, or garbage → rejected before any PUT; the child is killed on output overflow. - Integration against the local stack (CI `supabase` job): Alice's full flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2; one HTTPS call in CI proves the CA bundle. --- ## Part V. Libraries retained and their limits | Area | Retained | Rejected | Limits to manage | |---|---|---|---| | Serialisation | `serde`, `serde_json` (custom formatter), `thiserror`, `ts-rs` | `serde-wasm-bindgen`, `tsify`, `schemars` (until a consumer exists), `serde_jcs` | float printing owned by `js_number`; field order declared per struct | | XML | `roxmltree` + own tree and serialiser | `quick-xml`, `usvg` as sanitiser (allows DTD, drops silently, rewrites the drawing) | depth and size pre-scan until the deep-nesting fix is released | | PDF write | `pdf-writer` | `krilla` (no Standard 14 page text, merged dates; candidate for TTF), `printpdf` (no attachments), `lopdf` as writer | classic xref only (wanted); `f32` coordinates (links read back) | | PDF read | own byte scan + `miniz_oxide`; `lopdf` test-only | `pdf`, `pdfium` in the app | same caps as today | | Fonts | vendored Core 14 AFM (APAFML notice committed); later `skrifa` + `subsetter` + `harfrust` | `ttf-parser`, `rustybuzz` (RustSec unmaintained) | kerning-inclusive width rule reproduced from pdf-lib | | PNG | `png` | UPNG semantics | gate stays ours; decoder under `Limits` | | Raster | browser canvas (DOM adapter); `resvg` native in tools/worker when a need appears | `resvg` in the browser bundle | `allow_dtd`, 1M-element cap and the crop workaround handled by our sanitiser and adapter | | Images (worker) | `image`, `moxcms`, `libwebp-sys` | `webp` crate, `image-webp` in the parent, `img-parts`, `infer`, `wasmtime`, `extrasafe` | `Limits.max_alloc` advisory → `RLIMIT_AS` is the hard cap; profile size capped | | Sandbox | `seccompiler`, `rlimit` | `landlock` (redundant under the allowlist), user namespaces | allowlist derived by tracing, proven on the corpus | | Runtime | `tokio`, `reqwest` (`webpki-roots`), `tracing` | `postgrest`, `supabase-rs` | ~10 hand-written endpoints tested against the local stack | | WASM | `wasm-bindgen` + CLI (version from `Cargo.lock`), `binaryen` when needed | `wasm-pack` | crate/CLI lock | | Hygiene | `cargo-deny` (licences, bans, sources blocking; advisories nightly and at release) | `cargo-audit` (same database), `cargo-chef` (BuildKit cache mounts suffice), `cargo-fuzz` before Step 27 (nightly toolchain; our own parsers only) | | --- ## Part VI. Progressive migration strategy ### VI.1 Principles - **Freeze with the old code, then switch.** Before a phase ports a module, every output that no test pins yet is committed as a golden produced by the TypeScript code (LRN-046): the three archive envelopes, the composed views as parsed trees, the draw log of lines, rectangles and colours. The oracle suites are then ported to cargo on the fixtures in place (JSON fixtures under `apps/app/tests/fixtures` and `packages/*/tests/fixtures`, read by path; the two TypeScript fixtures `horse-slice.ts` and `mini-sheet.ts` converted to JSON once). No dual-run harness. - **Consumer-driven deletion.** A TypeScript module is deleted in the phase that switches its last consumer; until then it is frozen (no new logic) and its existing goldens keep proving it. The table in VI.4 names the last consumer of every module so nothing is deleted while imported (revision 1 broke this twice). - **Goldens are never regenerated silently.** A phase that changes an oracle (the attachment bytes at R2, the generated seed files at R5) says so in its end criteria and the owner decides. - **Every phase** ends with `pnpm check`, `cargo test --workspace --locked`, `cargo clippy -D warnings`, `cargo deny check` (licences, bans, sources), Docker builds green, the real-stack pgTAP when SQL changed, the verifier and security gates, the rollback row of VI.3 proven, and a manual validation script for the owner. - Phases are gitflow branches (`feature/rust-r-`; `chore/rust-r0-workspace` for the foundation). ### VI.2 Phases and end criteria | Phase | Content | Depends on | End criteria (verifiable) | |---|---|---|---| | **R0 Foundation** (inside Step 8) | `Cargo.toml` workspace, `rust-toolchain.toml`, `deny.toml`, lints, `crates/core` skeleton (no app consumer yet), `crates/worker` skeleton, CI job `rust`, worker image build, `docs/development/RUST.md` (setup, commands, boundary rules), `DEPLOY.md`: images built in CI and pulled by digest, CSP line with `'wasm-unsafe-eval'`, gzip for `.wasm`, VPS disk and RAM headroom recorded; `rustup` on the dev host (owner) | none | `cargo test`, `clippy`, `deny` green in CI; worker image builds (< 30 MB) and starts against the local stack with no job; panic strategy on wasm32 verified and written in `RUST.md`; CI duration and runner cache behaviour measured and recorded; no production artifact changed yet | | **R1 Step 8 worker** | Part IV: decode child, sandbox, transport, sweeper, per-stage deadlines, compose service, `.env.worker.example`, the Step 8 migration and app work as analysed | R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests on the production image, local-stack integration, real-stack e2e); image non-root, `cap_drop ALL`, read-only; libwebp ≥ 1.6.0 logged; owner manual validation of the avatar flow | | **R2 Domain core** | `crates/core` domain: sheet document + rules, report v3/v2 + migration, rebase (owner go, D-R12), snapshot/envelope/branding/labels, `SheetHandle` + `SheetIndexData`, reducers, `build_finding`, `vertebra_selection`, `new_report`; `crates/wasm` facade (JSON strings, `ts-rs` types, poison-and-reinstantiate, lazy init, `core_unavailable`); `packages/core-wasm` package; app Dockerfile wasm stage; app switched (`SheetProvider`, store, click chain, pickers, publish gate); app importers codemodded from `@faunosteo/domain` to `@faunosteo/core-wasm`; `packages/domain` frozen for the TS engine and pipeline; three envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP | R0 | the domain, service, store, component and route suites pass with their assertions on the core; the three frozen envelopes parse with the frozen Zod schemas and compare semantically equal (bytes differ by decision D-R11); the 39 step6 goldens and the seed golden are untouched (the TS engine and pipeline still run on frozen TS); `pnpm build` with the wasm; the app boots under the exact production headers (CSP) in a headless check; a wasm load failure leaves `/login` and `/app` usable and shows the degraded state in the editor; a deliberate trap re-instantiates the module; served module size ≤ 600 KB compressed; owner manual FR/EN flow | | **R3 Anatomy core** | `crates/core` anatomy: tree, sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas on the core (denylist deleted); the TS engine still composes with its frozen TS copy; composed-view trees for the three reports frozen with the TS code first | R2 | step6 `views.*.json` unchanged through the app path; composed views DOM-equivalent to the frozen trees; 7 hostile cases + caps + zero-removal (tree compare) in cargo; canvas suite green; one sanitiser reachable from the app (grep) | | **R4 PDF core** (reader + writer + CLI) | `crates/core` pdf: scan, bounded inflate, layered read; layout → draw log → `pdf-writer`; AFM vendored; `png` + gate; dates tables; the leniency decisions of I.2 pinned by fixtures; draw-log golden for lines, rectangles and colours frozen with the TS engine first (D-R2); app import in a Web Worker, app export on the two-call design; `report-compare` tool; `packages/pdf` deleted (last consumer); frozen TS `render/` deleted with it only if the pipeline no longer imports it (it does: kept until R5) | R3 | 39 goldens reproduced exactly through the Rust draw log (text, images), links read back from the written files with `lopdf`, views via the app path; the new draw-log golden reproduced; scan (39), inflate (9), read (13), security (55), text (5), size (2) suites in cargo; the hostile corpus through the wasm build; BLK-009 browser measurements (Chromium, Firefox, Safari, one low-end phone) recorded in `PDF_IMPORT_HARDENING.md` §5 as done items (the gate itself stays open until every §5 item is done); poppler or pdfium render diff of the three reports within a stated threshold; the last TS scanner, kept as a test fixture, and the previous release's reader read every R4 fixture PDF; stored attachment < 250 KB; no `pdf-lib`, `@pdf-lib/*`, `@xmldom/xmldom` in the lockfile of `apps/app` or `packages/pdf` | | **R5 Curation pipeline, importer, operator tools** | `crates/core` curation + `cli` bins: import-equine, upload-sheet-assets; outputs emitted by Rust (`js_number`, markdown tables); `.prettierignore` on generated dirs; seed golden regenerated once (decided); review drawings compared as parsed trees against the xmldom-era files; `packages/anatomy` and `packages/domain` deleted (last consumers); CLAUDE.md folder map, `packages/README.md`, `WORKSPACE.md`, CHANGELOG | R2, R3, R4 | `seed.golden.test` green on the regenerated set; determinism (two runs byte-equal), counts (27/792/612/41, 811 nodes), 612-leaf semantics unchanged; `documentSha256` changed once and the import of an older archive shows the rebase message with 0 unresolved items on identical content; no TypeScript business logic outside UI glue (grep census in `RUST.md`); workspace test count reconciled with the deleted-tests list (TEST_STRATEGY §6) | Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 right after Step 8 and before Step 9, so that every later step writes its rules in Rust. R3, R4 and R5 before Step 13 (which needs the sanitiser in the worker), interleaved with Steps 9 to 12, which touch no module these phases move. The TTF font change is a separate later change with its own golden regeneration (D-R2). ### VI.3 Rollback per phase Production rollback is "deploy the previous image by digest" (VIII.1), so each phase states what the previous build must still read. | Phase | Artifacts written by the new build | What N-1 must read | Proof | |---|---|---|---| | R1 | avatars (WebP) | the app only displays them; the Node proposal never shipped | none needed | | R2 | drafts in `osteo:draft` and archives in `osteo:archive` written by the core (struct order, `js_number`); PDFs still written by the frozen TS engine from core-produced reports | N-1 (Step 7 build) parses the draft and the envelope with its Zod schemas | N-1 reader test on the frozen fixtures; a draft N-1 cannot parse goes to the quarantine key with a notice (never discarded) | | R3 | none persisted (canvas only) | n/a | | | R4 | PDFs from `pdf-writer` (classic xref, same attachment, same stamp) | N-1 scanner finds the attachment and the stamp; Step 6 build reads bare v3 and envelope | the kept TS scanner fixture and the previous release's reader read every R4 fixture PDF; `DEPLOY.md` rollback note updated as for Step 6 | | R5 | regenerated seed (new `documentSha256`) | N-1 app bundles the old seed and rebases archives written on the new one (visible message, nothing lost); reports written on the old seed rebase on the new build | rebase tests both ways on the two seeds | ### VI.4 What is deleted when (last consumer named) | Module | Consumers today | Last consumer switched at | Deleted at | |---|---|---|---| | `services/zoneInteraction.ts`, component data-building rules, store rules | app | R2 | R2 | | `packages/domain` Zod contracts and functions | app (R2), TS engine (R4), TS pipeline (R5), scripts (R4) | R5 | R5 (`packages/domain` removed; app imports codemodded at R2) | | `anatomy/drawing.ts` denylist | app canvas | R3 | R3 | | `packages/pdf/src/svg/**` (sanitiser, view) | TS engine | R4 | R4 | | `packages/anatomy/src/render/**` | app (R3), TS engine (R4), TS pipeline `app-review.ts` (R5) | R5 | R5 | | `packages/pdf/src/**` (reader, writer, attachment, branding gate), `apps/app/scripts/**`, `browserRasterizer.ts` stays | app, CLI | R4 | R4 (`browserRasterizer.ts` kept as the DOM adapter) | | `packages/anatomy/src/{legacy,curation,cli}/**`, `packages/supabase/scripts/upload-sheet-assets.ts` | operator | R5 | R5 | | `packages/anatomy`, `packages/domain`, `packages/pdf` packages | | | R4 (pdf), R5 (anatomy, domain) | --- ## Part VII. Adaptations to the development plan | Step | Plan text today | Adaptation under the rule | |---|---|---| | 8 Files | Node worker + sharp (STEP8 D1) | D1 reads "native Rust worker"; R0 + R1 inside the step; `apps/worker` is not created; `crates/worker` is; service key kept (IV.4) | | 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors in `crates/core` domain, called through the wasm; UI unchanged | | 13 Sheets in DB | SVG processor "from packages/pdf" | the R3 sanitiser runs in the worker's decode child (same isolation as images); the Supabase `SheetProvider` stays TS glue, parsing through the core | | 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; diff/throttle rules in the core; optional `pg_jsonschema` CHECK from a `schemars` export (decision at the step, first consumer of JSON Schema) | | 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row"; artifacts = PDFs generated by the browser | the worker validates the attachment with the core reader (R4); no Edge Function; server-side rendering is not in the plan; if a need appears, `resvg` native between the two core calls | | 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in the core | | 17 Sheet editor | editor store with undo, geometry | document operations and geometry as a core module, UI React | | 19 Notifications/worker | `apps/worker` Node, EmailProvider, `private.jobs`, `packages/i18n` for templates | `crates/worker` `run` gains the `private.jobs` loop (RPC with `SKIP LOCKED`) and templates rendered in Rust from Rust-side dictionaries; `packages/i18n` stays UI-only | | 20–21 Agenda, travel | expiry rule TS mirror, routing adapter, "Edge Function or worker endpoint" for the Google OAuth callback | mirror in the core; routing and calendar sync in the worker; the callback is the first inbound route of the worker's `serve` subcommand (axum, one route, behind the reverse proxy) | | 22 Public web | Q8 framework | Astro (global rule), D-R8 | | 23 Billing | "Edge Function stripe-webhook" | `serve` hosts the webhook (signature check, idempotency table unchanged) | | 24 Imports | adapters in the Node worker | Rust adapters (`csv`, `calamine`, `zip`), same `ImportAdapter` contract | | 26 Lifecycle | export/archive/restore jobs in the Node worker | Rust jobs in the same binary | | 27 Hardening | | adds `cargo deny` advisories, the sandbox tests and the `cargo-fuzz` run (nightly toolchain, our own parsers) to the release gate; the worker-role option of IV.4 evaluated here | | BACKEND_ARCHITECTURE §6 | Edge Function row | "Rust service (worker `serve`)"; PostgreSQL rows unchanged | | WORKSPACE.md, packages/README.md | `apps/worker` Node, `@faunosteo/i18n` for the worker | `crates/*`; i18n package UI-only | | TEST_STRATEGY.md | layers | adds the cargo layer, the freeze-then-switch rule, the N-1 reader test and the conformance fixtures shared with pgTAP | --- ## Part VIII. Docker, Supabase and CI impacts ### VIII.1 Docker and deployment - **Images are built in CI (or on the dev host) and pulled by digest.** The VPS (1 vCPU, 1 GB) never compiles Rust: `docker compose up --build` on the VPS is replaced by `docker compose pull && up -d` on tagged images (registry: the Gitea container registry of the forge, or Scaleway's); rollback = the previous digest. This is a prerequisite recorded in R0 and written into `DEPLOY.md` (routine deploys, rollback, disk headroom). - **App image**: a first stage `FROM rust:1.99.0-bookworm AS wasm` (BuildKit cache mounts on `~/.cargo` and `target`, pinned `wasm-bindgen-cli`) producing `packages/core-wasm/pkg`; the committed `packages/core-wasm/package.json` is in the manifest COPY list so `pnpm install --frozen-lockfile` keeps working; the Node builder copies `pkg/` before `pnpm build`; nginx serves `.wasm` (and `.wasm.gz` with `gzip_static`) with the hashed name. - **Worker image**: `rust:1.99.0-alpine3.24` builder (musl, `musl-dev`, `build-base` for libwebp's `cc` build) → `distroless/static:nonroot` (CA bundle present; `scratch` rejected), one static binary. Compose service `worker` (container `faunosteo_worker`): `read_only: true`, `tmpfs: /tmp`, `cap_drop: [ALL]`, `security_opt: [no-new-privileges:true]`, `mem_limit: 512m`, `cpus: 1`, `pids_limit: 64`, no `ports`, Supabase internal network only, `restart: unless-stopped`, `env_file: .env.worker`. The default Docker seccomp profile stays (it permits the inner filter). - **Naming**: `faunosteo_worker`, image `faunosteo/worker` (BDR-035). ### VIII.2 Supabase - No schema change comes from the rule itself. - Conformance fixtures for `sheet_document_issues` land as a generated pgTAP file with inlined fixtures (PGlite and real stack), owned by R2. - Managed migration: the worker container is hosting-agnostic (URL + key); HTTPS works out of the box (`webpki-roots`, distroless CA bundle, one HTTPS call tested in CI). ### VIII.3 CI (`.gitea/workflows/ci.yml`) - New job `rust` (runs before `check`): toolchain from `rust-toolchain.toml` (`dtolnay/rust-toolchain`), `cargo fmt --check`, `cargo clippy --workspace --all-targets -D warnings`, `cargo test --workspace --locked`, `cargo deny check licenses bans sources`, `pnpm wasm:build`, artifact `packages/core-wasm/pkg` uploaded. Cache: `Swatinem/rust-cache` if the Gitea cache server works (verified at R0), else a directory cache on the runner host. - `check` downloads the artifact before `pnpm install`. `docker` builds both images and pushes them by tag and digest on `main` and `develop`. `supabase` runs the worker integration test against the local stack. - Nightly: `cargo deny check advisories`; from Step 27, the fuzz run. ### VIII.4 Local development - Owner action: install `rustup` (lives in `~/.cargo`, no global package); the pinned toolchain installs itself from `rust-toolchain.toml`; `wasm32-unknown-unknown` target; `cargo install wasm-bindgen-cli --version ` and `cargo-deny`. - `pnpm dev` keeps working: `pnpm wasm:build` once and after Rust changes (a `cargo watch` recipe in `RUST.md`); Vite serves the `.wasm` from the package. - The worker runs against the local stack with `cargo run -p faunosteo-worker -- run` and `.env.worker` (SUPABASE.md §8 recipe). --- ## Part IX. Validation criteria and risks ### IX.1 Validation criteria of the orientation (beyond the per-phase ones) 1. No regression on the owner's list: Report v3, v2 PDF import, autonomous archives, immutable sheet versions, RLS, unresolved findings, FR/EN, file security, graphics. Proof = the existing suites kept with their assertions (one-to-one migrations named in commits, TEST_STRATEGY §6), goldens unchanged except where a decision regenerates them, pgTAP unchanged, the N-1 reader test green at every phase. 2. No duplicate business logic at the end of a phase, by the consumer-driven deletion table (grep census in `RUST.md`); hand-written TS mirrors of core helpers are not allowed (the core precomputes what React needs). 3. Security gates: the security-auditor runs on every phase; the worker sandbox tests run on the production image; `cargo deny` licences, bans and sources block, advisories gate releases. 4. Operability: worker image size, start time, memory ceiling, libwebp and seccomp status logged at start; a runbook line per failure mode in STORAGE.md; deploy and rollback never compile. 5. Cost visibility: CI duration and the served module size recorded in each phase's TODO note. ### IX.2 Risks | Risk | Likelihood | Effect | Mitigation | |---|---|---|---| | Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; frozen oracles catch what review misses | | Dual toolchain in CI and Docker | certain | CI minutes | caches; wasm artifact reused by `check`; images built once, pulled by digest | | WASM module as a point of failure (CSP, 404 after deploy, trap, memory growth) | medium | editor unusable or tab memory | CSP line and headless check at R2; lazy init with `core_unavailable`; poison-and-reinstantiate; reader in a terminated Web Worker; hashed file name | | Hidden JS semantics in outputs and readers (float printing, upper-casing, ICU dates, kerning widths, rounding, lenient decoding, duplicate keys, `.int()`, `\s`) | high | golden mismatches or stricter readers refusing old files | the I.2 list with a fixture each before the owning phase; leniency decisions recorded; N-1 reader test | | Sheet identity hash changes at R5 | certain | every older archive rebases once on import (message, nothing lost) | stated in R5's criteria and in the CHANGELOG; rebase tested both ways | | Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; relaxed fields never widened without a decision | | Crates maintained by one person (`zune-jpeg`, `moxcms`, `libwebp-sys`, `ts-rs`, `krilla`) | medium | abandonment | `cargo deny` `unmaintained` advisories; alternatives in Part V; decoders confined to the child; the boundary has no third-party crate | | `roxmltree` deep-nesting overflow (fix unreleased) | known | parser DoS | depth cap by byte pre-scan; pin the fixed release | | seccomp allowlist killing a valid decode | medium if hand-written | valid photos rejected after three leases | derived by tracing, proven on the corpus at the caps in CI, SIGSYS logged with the syscall number | | VPS resources | certain | OOM or full disk during a build | never build on the VPS (VIII.1); disk headroom recorded | | Gitea runner caches for Rust | unverified | slow CI | measured at R0; host-level cache fallback | | `wasm-bindgen` crate/CLI version lock | certain | broken builds on drift | one version read from `Cargo.lock` by the install lines | | Two implementations lingering | medium | drift, double maintenance | VI.4 last-consumer table is part of each Definition of Done | | Public web framework conflict | certain | decision needed | D-R8 | ### IX.3 Explicit non-goals of the rule - Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos, Dioxus): excluded by the owner's retained list and the validated mockups. - Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer: excluded (retained list; RLS stays the boundary). - Running Rust inside PostgreSQL (`pgrx`): excluded by managed compatibility. - Moving SQL transactional rules to Rust: excluded. - Shipping `resvg` to the browser: excluded (size, no visual change wanted). ### IX.4 Unverified items (settled at R0 or at the phase that needs them) - Panic strategy and `catch_unwind` on stable `wasm32-unknown-unknown` for the pinned toolchain (handled as abort regardless). - `resvg` byte-identical output native vs the Node test adapter (README claim; matters only if a server-side rendering need appears). - Exact libwebp version string in `libwebp-sys` 0.14.4 (≥ 1.6.0 by API presence; logged at start, checked in CI). - `serde_json`/`zmij` exponent thresholds vs JavaScript (the `js_number` formatter is tested on the committed overlays regardless). - Gitea runner support for `Swatinem/rust-cache`; cold build times on the runner; registry choice for images. - Core wasm size and instantiate time (measured at R2). - The syscalls a static-musl decoder needs (`mprotect`, `madvise`, `rt_sigreturn`, `tkill`…): derived by tracing at R1, never assumed. --- ## Part X. Decisions for the owner | Id | Question | Recommendation | |---|---|---| | D-R1 | Workspace layout | Three crates: `core` (feature-gated library with tool binaries), `wasm` (facade), `worker` (binary); no crate per module, no `crates/editor` | | D-R2 | PDF engine | Reader and writer ported together at R4 with the Standard 14 AFM metrics (goldens exact); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port (additive); TTF fonts as a separate later change with its own regeneration | | D-R3 | Rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | | D-R4 | Lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (`ravif`, pure Rust, changes D4's format) | | D-R5 | Sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives rebase on import with a visible message and 0 unresolved items (as any content changeset); no Prettier dependency kept | | D-R7 | Form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home: a hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, with the counting rule recorded | | D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the site needs no islands | | D-R9 | Edge Functions | Retired from the plan (limits, hand deployment, one Rust runtime); webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | | D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9–12 | | D-R11 | Archive attachment bytes | New contract adopted at R2 (declared field order, `js_number`, optional absent / nullable null); every previous reader keeps parsing it (N-1 reader test, permanent); the bytes of existing PDFs are untouched | | D-R12 | Gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | | D-R13 | Serving the wasm in production | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples, gzip for `.wasm`, images built in CI and pulled by digest (no compile on the VPS), served module ≤ 600 KB compressed enforced in CI | | D-R14 | BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the §5 browser measurements; the external-user import gate (BDR-040) stays open until every §5 item is done, never closed by R4 alone | The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native Rust worker" from this review on; the worker credential stays the service key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1 (that role) is therefore no longer a decision of this study, which is why the numbering skips it. --- ## Annex A. Decision table (expanded for the owner's validation, 2026-10-12) Orientation validated by the owner on 2026-10-12 with ten principles (Rust worker at Step 8, Cargo workspace, native and WASM libraries, progressive anatomy migration, PDF migration under complete compatibility proofs, React and PostgreSQL/Supabase kept, testable increments with rollback, no premature deletion of TypeScript still in use, fully dockerised infrastructure with production builds outside the small VPS, WASM compatibility with the production CSP proven before activation). The detailed decisions below await validation. Impact tags: SEC security, HIST historical data, PERF browser performance, UI interfaces, DEPLOY deployment. | Id, subject | Recommendation | Relevant alternatives | Advantages / drawbacks | Risks | If validated | Impacts | |---|---|---|---|---|---|---| | D-R1 workspace layout | Three crates: `core` (feature-gated library, tool binaries behind `cli`), `wasm` (cdylib facade), `worker` (binary) | Six crates per boundary (rev 1); one crate holding the facade too (wasm-bindgen would pollute native builds); one crate per module | One dependency graph and one test run; features keep the worker lean / feature combinations must be tested in CI (`--no-default-features`, `--all-features`); core compile time grows with modules | Accidental I/O or clock in core (lint `disallowed_methods`); feature creep | R0 creates the three crates and the lint set | none | | D-R2 PDF engine | Reader and writer ported together at R4 on `pdf-writer` with the Standard 14 AFM metrics (kerning-inclusive widths); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port; TTF fonts as a separate later change | Reader first, writer later (two phases, longer hybrid); writer on `krilla` + TTF at once (no Standard 14 page text, goldens regenerated blind); keep pdf-lib for writing (unmaintained, contradicts the rule) | The 39 goldens stay the exact oracle; `packages/pdf` deleted in one phase; no object streams by construction / largest single phase; AFM files vendored under the APAFML notice | Kerning, rounding, ICU dates or `f32` coordinates moving a run (caught by goldens and the `lopdf` read-back); viewer compatibility of classic xref (standard) | Golden regeneration decision for the additive draw-log golden; the gated functions port (D-R12); rollback note in DEPLOY.md as for Step 6 | HIST, DEPLOY | | D-R3 rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | `resvg` lazy-loaded in the browser (949 KB gzip, anti-aliasing change, new raster goldens); `resvg` everywhere for identical bytes server and browser | No bundle growth, no visual change, no golden change / browser and future server renderings would differ (only matters if server rendering appears) | Browser rasteriser limits unmeasured (true today already) | Export becomes `compose_export_views` → rasterise → `write_archive`; `browserRasterizer.ts` kept as DOM adapter | PERF, UI | | D-R4 lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; output checked by the parent at container level only | Lossless WebP via `image-webp` (pure Rust; avatars 5 to 10× larger); AVIF via `ravif` (pure Rust, slower encode, changes D4's format); wait for a pure-Rust lossy encoder (`oxideav-webp`, months old) | Standard output, small files, mature encoder / C compiled in the worker build (Alpine `build-base`), vendored version invisible to RustSec (logged at start, checked in CI) | libwebp CVEs (historically decoder side); mitigation = process confinement, rlimits, seccomp, version check | R0 spike proves the musl static build with `cc`; R1 implements | SEC, DEPLOY | | D-R5 sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives and drafts rebase once with a visible message and 0 unresolved items | Keep a Node Prettier step to preserve the bytes (rev 1; chains the identity to a JS formatter); hash of canonical JSON (RFC 8785, `serde_jcs`): identity independent of formatting forever, one more concept | Simplest rule, matches today's semantics (the file is the identity) / one import notice per old archive after R5 | None on data (rebase keeps everything); user confusion if the message is not worded for "identical content" | R5 regenerates the seed golden knowingly; CHANGELOG entry; the import and restore messages re-read for the 0-unresolved case | HIST, UI | | D-R7 form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home (hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, counting rule recorded) | Rust validation through the wasm per field (render-path calls on every keystroke); constants generated from the SQL migrations (rev 1: a DDL interpreter for eleven numbers) | Forms stay responsive and simple; the drift found by the inventory is closed / constants hand-written (kept honest by the test) | low | A small chore branch, any time; no UI change | UI | | D-R8 public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception | Zola (Rust static generator, no islands, no React); Leptos/Dioxus SSR (immature SEO tooling, contradicts "React stays"); Next.js (global rule names Astro) | SEO/GEO tooling and islands / a TypeScript app in a Rust-by-default repository | none now | Exception recorded; Step 22 brainstorm re-checks per the global rule | DEPLOY | | D-R9 Edge Functions | Retired from the plan; webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | Edge Functions (Deno can run the wasm core; limits, hand deployment on self-hosted); a separate HTTP container; `pg_net`/`pg_cron` for some jobs | One runtime, one image, Rust / the worker gains an inbound route at Steps 21 and 23 and uptime expectations | Inbound surface (signature checks, proxy rate limits, monitoring at Step 27) | `BACKEND_ARCHITECTURE.md` §6 updated; Steps 21 and 23 designs change | SEC, DEPLOY | | D-R10 order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9 to 12 | R2 after Steps 9 to 12 (more TypeScript rules to migrate twice); R3 to R5 after Step 13 (impossible: the Rust worker needs the Rust sanitiser at Step 13) | Every later step writes its rules in Rust once / Steps 9 to 12 slowed by the migrations | Velocity of the functional steps | TODO order; Step 9 starts after R2 | DEPLOY | | D-R11 archive attachment bytes | New contract adopted at R2: declared field order (struct order), `js_number` floats, optional absent, nullable `null`; every previous reader keeps parsing it (permanent N-1 reader test); existing PDFs untouched. At R2 the frozen TS engine still writes the attachment from the core's objects (order changes, floats printed by JS); at R4 the Rust writer serialises fully | Reproduce the insertion order of the TS store exactly (fragile mirror); keep TS serialisation of the attachment until R4 (same end state, same key-order change) | Declared and testable order / byte diff against pre-R2 exports (no reader depends on order; Zod ignores it) | A reader depending on key order (none known) | Struct field orders documented; N-1 reader test added at R2 and kept | HIST | | D-R12 gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | Keep the TypeScript readers and rebase permanently (two implementations, contradicts the rule) | One reader for browser, worker and tools / the highest-stakes port (user data) | Behaviour drift on archives; mitigation = exact-object oracles, all fixtures, hostile corpus through the wasm build, N-1 test | The port follows the oracle suites; any behaviour change needs its own decision | SEC, HIST | | D-R13 serving the wasm | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples; gzip for `.wasm`; images built in CI and pulled by digest (no compile on the VPS); served module ≤ 600 KB compressed enforced in CI; registry = the forge's Gitea container registry (recommended; Scaleway Container Registry as alternative) | `'unsafe-eval'` (broader, rejected); inline the module as base64 (CSP still applies, bigger); Brotli (nginx module needed); build on the VPS (rejected) | Minimal CSP relaxation specific to WebAssembly; deploy and rollback never compile / `'wasm-unsafe-eval'` needs Chrome 97+, Firefox 102+, Safari 16+ (Vite 7 baseline); an older browser lands in `core_unavailable` | Registry credentials on the VPS; CSP forgotten on one proxy (sanity-check row) | DEPLOY.md rewritten at R0 (procedure prepared, applied at the first image deployed: worker at R1); the deploy procedure change is validated separately | SEC, PERF, DEPLOY | | D-R14 BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the `PDF_IMPORT_HARDENING.md` §5 browser measurements (Chromium, Firefox, Safari, one low-end phone); the external-user import gate (BDR-040) stays open until every §5 item is done | Main-thread synchronous reader (memory never shrinks, UI blocked); server-side import only (Step 15) | Bounded blast radius, measurable, import off the main thread / a second instantiation per import; a browser runner (Playwright) introduced for the measurements | Safari worker + wasm specifics; measurement effort | R4 includes the browser measurement campaign; the gate stays open | SEC, PERF | ## Annex B. R0 scope (owner's clarification request, 2026-10-12) R0 is the foundation phase inside Step 8. It changes no production artifact, implements no feature and starts only on the owner's go. ### B.1 Toolchain, reproducible in Docker - Reference build environment = a Docker builder image (`docker/rust-builder.Dockerfile`, `FROM rust:1.99.0-bookworm`, plus `wasm32-unknown-unknown`, `wasm-bindgen-cli` at the version in `Cargo.lock`, `cargo-deny`, `binaryen` for `wasm-opt`), used by CI and by the application and worker image builds. The worker's own builder stays `rust:1.99.0-alpine3.24` (musl, `build-base` for libwebp). - The development host may install `rustup` for the inner loop (same `rust-toolchain.toml`, so the same compiler); the containerised build is the arbiter. Root scripts: `pnpm rust:check` (fmt, clippy, test, deny) and `pnpm wasm:build`, each runnable locally or through the builder image (`docker run --rm -v "$PWD":/w`). - The production VPS never gets Rust: it pulls images by digest. ### B.2 Workspace - `Cargo.toml` (workspace, `[workspace.dependencies]`, `[workspace.lints]`: `unwrap_used`, `expect_used`, `disallowed_methods` for `std::time`, `std::fs`, `std::env` in core), `rust-toolchain.toml`, `rustfmt.toml`, `clippy.toml`, `deny.toml`, `.cargo/config.toml` (wasm stack size, `-C link-arg=-zstack-size`). - `crates/core` (modules declared, `SheetRef` + `Locale` types, the `js_number` formatter, the conformance fixture loader), `crates/wasm` (facade exporting `core_version()` and one JSON round-trip call), `crates/worker` (binary with `run` printing its configuration and `decode` wired to the sandbox spike, no job logic). - `packages/core-wasm/package.json` committed, `pkg/` ignored. ### B.3 Docker and CI - Worker image built from the skeleton (Alpine musl builder → `distroless/static:nonroot`), started once in CI against the local stack with no job (proves transport configuration, CA bundle, non-root, read-only). - Application image: the wasm stage added and exercised in CI, its output not loaded by the application until R2. - CI job `rust` before `check`: fmt, clippy, test, `cargo deny check licenses bans sources`, wasm build artifact; `docker` job builds both images; registry push by tag and digest prepared (registry decision in D-R13); nightly advisories job; CI duration and runner cache behaviour recorded in `RUST.md`. ### B.4 Feasibility proofs (experimental, each one a permanent test) | Proof | Why it conditions a choice | How | Lives on as | |---|---|---|---| | Panic strategy on wasm32 | III.3 rule 5 (poison and re-instantiate) | a facade call that panics; observe `WebAssembly.RuntimeError`; re-instantiate; call again; try a deep recursion at the configured stack size | vitest in `packages/core-wasm` | | Serialisation contract | D-R11, I.2 (`js_number`, optional vs nullable) | parse `report-v3.demo.json` and `document.json` with serde, re-emit through the custom formatter, compare byte for byte with `JSON.stringify(JSON.parse(x), null, 2)`; a struct with optional and nullable fields parsed by the current Zod schemas | cargo test + vitest N-1 reader seed | | musl static binary with libwebp (`cc`) | D-R4 | build the worker skeleton with `libwebp-sys` on the Alpine builder; log `WebPGetEncoderVersion` | the worker image build in CI | | seccomp allowlist derivation and application | Part IV (traced allowlist, `Threads: 1`, TSYNC) | `decode` spike: minimal `image` decode of one JPEG, one PNG, one WebP at the caps, traced with `strace -f` in the production image under Docker rootless; filter installed before any thread; disallowed syscall kills the child; environment empty | the sandbox test of R1 | | CSP with `'wasm-unsafe-eval'` | D-R13, owner principle "proven before activation" | serve the wasm artifact under the production nginx config with the DEPLOY.md headers in headless Chromium: instantiation succeeds with the keyword, fails without it; result written in DEPLOY.md | CI headless check | | Served size and instantiate time | D-R13 budget | measure raw and gzip bytes of the skeleton module and its instantiate time; set the budget check | CI size check | | Runner caches and build times | VIII.3 | time the cold and warm `rust` job with and without `Swatinem/rust-cache` on the Gitea runner | `RUST.md` numbers | ### B.5 R0 exit criteria `cargo test`, `clippy`, `deny` green in CI through the builder image; worker image < 30 MB, non-root, starts against the local stack; the seven proofs recorded in `RUST.md` with their numbers; `DEPLOY.md` rewritten (pull by digest, CSP line, gzip, VPS headroom, rollback = previous digest) without touching the live deployment; `pnpm check` unchanged; no production artifact changed. Owner validation closes R0; R1 (the Step 8 worker) starts on a separate go. --- ## Annex C. Owner validation and amendments (2026-10-12) Revision 2 validated with the amendments below. The rule stays definitive: Rust by default whenever it gives an equivalent or better result with no functional, practical, graphical, security or reliability loss. R0 may start; R1 waits for a separate go; release 0.2.0 waits for its own validation. Validated as recommended: D-R1 (three crates), D-R2 (reader and writer at R4 after the oracles exist), D-R3 (browser canvas, no resvg in wasm), D-R7 (form validation in TypeScript), D-R8 (Astro exception, re-evaluated at Step 22), D-R10 (order R0–R5), D-R11 (deterministic serialisation with old-reader compatibility), D-R12 (gated PDF functions ported with identical behaviour), D-R14 (import in a Web Worker, security controls kept before public opening). Amended: | Id | Amendment | |---|---| | D-R4 WebP | libwebp in C is allowed only inside the isolated processing child. The parent checks the validity and the limits of the produced result before any use (container structure, dimensions, size, absence of metadata). The native libwebp version actually linked into the build is known and controlled (logged at start, checked in CI). The migration must not introduce new unmanaged risks. | | D-R5 sheet fingerprint | Preference for a deterministic fingerprint over a canonical JSON representation independent of the formatter (Prettier or Rust): study RFC 8785 (JCS) or a strictly defined alternative, so that a purely technical serialisation change never causes needless rebases. Explicit compatibility with the fingerprints and archives already produced. Existing fingerprints are not changed now: the decision is prepared for R5 and its implications verified before the switch. | | D-R9 Rust HTTP services | Business Edge Functions replaced by Rust services where appropriate. Shared code but distinct processes for the job worker and the future exposed HTTP endpoints; they may come from the same Docker image run with different subcommands. Each service holds only the secrets, permissions, resources and protections it strictly needs. Supabase Auth keeps the OAuth mechanisms it already handles. | | D-R13 WASM, CI, deployment | CSP compatibility with `'wasm-unsafe-eval'` validated experimentally, without widening JavaScript permissions. Rust/WASM builds reproducible in Docker and run in CI. Images identified by digest and a rollback strategy prepared. No automatic deployment to the VPS; no publication or promotion of a production image without an appropriate workflow and a validation; the VPS never needs to compile the Rust project. | R0 scope confirmed as Annex B, with these instructions: the seven proofs run in the real environment as far as possible, the unconfirmed hypotheses (serialisation, wasm panics, musl, seccomp) verified experimentally, a proof that cannot be obtained reported as a blocker rather than assumed; during R0 the React application, Report v3, PDF v2/v3, Supabase, the interfaces and the existing tests stay unchanged; the WASM integration does not force the frontend to load the module; no anatomy, PDF or business validation migration (R2–R5); no avatar processing (R1); everything dockerised, the production image produced in CI and pulled by the VPS; the live deployment untouched; no tag or merge into main. ### C.1 Addendum 2026-10-13: development environment and CI status (owner brief after R0) R0 delivered and validated on the architecture. The owner corrected the development organisation before closing R0; these points amend Annex B §B.1 and VIII.4 and are implemented on `feature/rust-r0-foundation`: - Three environments, three roles. The development machine is a self-hosted Ubuntu server (native, not WSL, not the VPS) with Docker rootless: Rust is developed and compiled **natively** there (user-level `rustup`, channel of `rust-toolchain.toml`, `wasm32-unknown-unknown`, `wasm-bindgen-cli` and `cargo-deny` at the pinned versions; `cargo check / test / build / clippy / fmt` and the browser module build run without Docker). Docker on that machine runs the Faunosteo services (Supabase), the worker in its hardened container, the integration tests, the sandbox and seccomp proofs, and builds the deployment images (multi-stage). The production VPS is separate and never compiles. - The R0 builder image is kept as the reproducible alternative (`pnpm rust:check:docker`, `pnpm wasm:build:docker`) and as the reference for a future runner; it is no longer the arbiter of daily work and is not required for a compile or a test. The worker's isolation is unchanged. - No CI/CD is operational on the forge (no runner, secret or registry). The workflow files are prepared material for a separate CI/CD decision; a workflow is never reported as passed before it has run on the forge. The pre-merge gate is local: `pnpm check:all` (`scripts/check-all.sh`), which a future runner calls as is. - Target of that future step (planned, not yet built): tests on every push and pull request, Rust and TypeScript checks, PostgreSQL/RLS tests, Docker builds, security checks, branch verification before a merge, image publication only in an explicitly authorised workflow. - R1 (the Step 8 worker) waits for the owner's final validation of this correction; no deployment, no release 0.2.0.