852 lines
81 KiB
Markdown
852 lines
81 KiB
Markdown
# 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>` → `T \| null`, `#[ts(optional)]` → `t?: T` | active | types only; the payloads cross as JSON strings (III.3); `tsify` 0.5.8 and `serde-wasm-bindgen` 0.6.5 (no release in 2.5 years, writes absent optionals as `null` in its JSON preset) are not used |
|
||
| Vite 7 | `--target web` output: `await init()` + `?url`, no plugin | | `.wasm` served raw unless nginx gzips it (VIII.1) |
|
||
|
||
PDF, SVG, XML, fonts:
|
||
|
||
| Need | Crate | Version (date) | Status | Limits |
|
||
|---|---|---|---|---|
|
||
| PDF writing | `pdf-writer` | 0.15.0 (2026-05-27) | typst org, 4 pure-Rust deps, no advisory | `EmbeddedFile` + `EmbeddingParams`, `FileSpec::association_kind(Data)`, `Names::embedded_files`, `Catalog::associated_files`, Type1 fonts with `WinAnsiEncoding` + explicit widths, image XObjects with `SMask`, `Action::uri`, Info dates, classic xref table; **cannot write object streams at all** (BLK-009 option B by construction); coordinates are `f32` (the links golden keeps a read-back oracle, VI.2) |
|
||
| PDF writing, higher level | `krilla` 0.8.2 (2026-06) | one maintainer | page text is OpenType only (no Standard 14), merges CreationDate/ModDate: candidate for the TTF step, not for the parity step |
|
||
| PDF read-back in tests | `lopdf` 0.45 (HIGH advisory patched ≥ 0.42) | test-only | reads `/Annots` of the written file for the links golden |
|
||
| Standard 14 metrics | **no credible crate** | | vendor the Adobe Core 14 AFM files (SPDX `APAFML`: redistribution allowed with `MustRead.html`, edits noted); `@pdf-lib/standard-fonts` bundles the same files (WX, N, KernPairs) |
|
||
| TTF later | `subsetter` 0.2.6, `skrifa` 0.48, `harfrust` 0.14; **`ttf-parser` and `rustybuzz` are RustSec-unmaintained** | | Inter and Fraunces are OFL |
|
||
| SVG raster (native only) | `resvg` / `usvg` 0.48.1 (2026-08), `tiny-skia` 0.12 | linebender org since 0.45 | only cap is 1,000,000 elements, `allow_dtd: true`: our sanitiser runs first; the head-view crop needs the render-full-box-then-crop workaround (LRN-046); not shipped to the browser (949 KB gzip measured on resvg-wasm 2.6.2) |
|
||
| XML parse | `roxmltree` 0.21.1 (2025-10) | RazrFalcon, 27M/90d | read-only, refuses DTD by default, `nodes_limit`; **unreleased fix (2026-09-22) for a stack overflow on deep nesting**: depth capped by a byte pre-scan until the fixed release is pinned |
|
||
| XML write | hand-written serialiser for the allowlisted tree | | ~100 lines; `quick-xml` not needed |
|
||
| PNG | `png` 0.18.1 (2026-02) | image-rs, no `unsafe`, OSS-fuzz | encoder writes only IHDR/IDAT/IEND unless asked |
|
||
|
||
Worker (image pipeline, sandbox, transport):
|
||
|
||
| Need | Crate | Version (date) | Status | Limits |
|
||
|---|---|---|---|---|
|
||
| Decode + resize + orientation | `image` 0.25.10 (2026-03-10), MSRV 1.88 | image-rs org | `orientation()`, `icc_profile()`, `set_limits` (max_alloc advisory 512 MiB), `apply_orientation`, `resize_to_fill`, `guess_format`; JPEG = `zune-jpeg`, PNG = `png`, WebP = `image-webp`; no ICC application API; resolves `moxcms` ^0.8 (use that version, not 0.9) |
|
||
| JPEG | `zune-jpeg` 0.5.15 | one very active maintainer | `unsafe` only in SIMD (togglable), default cap 16536×16535, CMYK ok, "panics are okay" policy → child process justified |
|
||
| WebP decode | `image-webp` 0.2.4 (2025-08) | image-rs, `forbid(unsafe)` | lossy, lossless, alpha, animation, ICC/EXIF/XMP; memory limit has a documented TODO; **encoder is lossless only** |
|
||
| WebP lossy encode | `libwebp-sys` 0.14.4 (2026-04, vendored libwebp ≥ 1.6.0, `cc` build) | C | no established pure-Rust lossy encoder (`oxideav-webp` 0.3.1 created 2026-04, `zenwebp` AGPL); `webp` 0.3.1 pins libwebp 1.3.1 + one fix (not used) |
|
||
| ICC → sRGB | `moxcms` (version resolved by `image`) pure Rust, one maintainer, SIMD `unsafe` on by default; `lcms2` 6.2 (C) alternative | | no documented ICC input limits: profile size capped by us (1 MiB) |
|
||
| Sandbox | `seccompiler` 0.5.0 (rust-vmm, sets `no_new_privs`, TSYNC available), `rlimit` 0.11 | | `landlock` not used (redundant under the allowlist); `extrasafe` dormant; `wasmtime` carries ~2 advisories/month in 2026 |
|
||
| Runtime, HTTP | `tokio` 1.53, `reqwest` 0.13.5 (rustls, `webpki-roots` compiled in), `tracing` 0.1.44 | | |
|
||
| Supabase clients | `postgrest` 1.6.0 (2023-07), `supabase-rs` 0.8.0 (PostgREST only) | weak | hand-written `reqwest` calls to PostgREST `/rpc/<fn>` and Storage `/storage/v1` (~10 endpoints) |
|
||
| Toolchain | `rust:1.99.0-{trixie,bookworm,slim-*,alpine3.24}`, `cargo-deny` 0.20.2, `distroless/static:nonroot` (Debian 13, CA bundle included) | | |
|
||
|
||
Baseline for comparison, `sharp` 0.35.5 (2026-09-27): libvips 8.18.7,
|
||
libwebp 1.6.0, libpng 1.6.58, mozjpeg; strips metadata and converts to sRGB
|
||
by default, `limitInputPixels` 268 MP, WebP q80; EXIF orientation only with
|
||
`autoOrient`/`rotate()`. libvips had three High CVEs in July and August 2026,
|
||
libpng twelve CVEs since late 2025. The Rust pipeline's advantage is the
|
||
loader surface (three formats, pure-Rust decoders, hard caps), not the
|
||
encoder (still libwebp, confined to the child process).
|
||
|
||
Supabase platform facts:
|
||
|
||
- Edge Functions (managed: 2 s CPU, 256 MB, 150 s wall clock; self-hosted:
|
||
`edge-runtime` container, hand-deployed) run Deno, which can execute a
|
||
wasm build of the core; the rule retires them from the plan for those
|
||
limits, the hand deployment and the preference for one Rust runtime
|
||
(D-R9). The language alone would allow them.
|
||
- A dedicated Postgres role is honoured by PostgREST and storage-api
|
||
(official custom-roles guide), with a JWT minted from the legacy HS256
|
||
`JWT_SECRET` or an imported ES256 standby key; on managed the imported
|
||
key must become a signing key of the project. Recorded as a hardening
|
||
option (IV.4), not adopted.
|
||
- `pg_jsonschema` 0.3.3 exists on managed and in the `supabase/postgres`
|
||
image but not in PGlite; custom `pgrx` extensions have no documented path
|
||
on managed.
|
||
|
||
---
|
||
|
||
## Part II. Classification of every module
|
||
|
||
### II.1 Criteria
|
||
|
||
Business logic = anything that interprets or transforms the sheet, report or
|
||
archive data, encodes a product rule (what a click does, how a finding is
|
||
built, how a report migrates), parses untrusted bytes, or runs as a job or a
|
||
service. Glue = React rendering and display formatting, routing, DOM
|
||
access, store subscription, vendor SDK calls, build tooling. The owner's
|
||
brief keeps glue in TypeScript; everything else is Rust unless a concrete
|
||
loss is named on the brief's list (features, UX, graphics, data
|
||
compatibility, security, reliability, useful performance, resources,
|
||
portability, maintainability, deployment). Absence of a performance gain is
|
||
never a reason for C.
|
||
|
||
Classes: **A** = Rust, scheduled on technical dependencies only; **B** =
|
||
Rust, waiting for a named external trigger; **C** = exception with its
|
||
concrete constraint.
|
||
|
||
### II.2 Module table
|
||
|
||
| Module | Role today | Tech | Rust feasibility and crates | WASM? | Frontend consequence | Compatibility risk | Oracle for the switch | Class | Phase |
|
||
|---|---|---|---|---|---|---|---|---|---|
|
||
| domain: sheet document schema, `validateSheetDocument` (21 rules), `createEmptySheetDocument` | shape and integrity of the sheet | Zod | serde structs (strict = `deny_unknown_fields`, defaults), hand-written rules returning `SheetIssue {code, severity, path, message}` | yes + native | app load and publish gate call the core; types from `ts-rs` | low: codes and paths pinned by the validate suite; strict/strip policy per schema reproduced | validate suite (exact code + path lists), `horse-slice` fixture (converted to JSON), the draft document (0 issues) | **A** | R2 |
|
||
| domain: report v3, v2 input, `migrateReportV2ToV3`, `readReportDocument` | report contract and migration | Zod | full; "never throws on content" made true (today a malformed map entry can throw a raw `ZodError`) | yes + native | store hydrates only through the core | medium: strip semantics, `requiresVetReferral: false` dropped in v3 (kept, pinned), optional vs nullable fields | 612-leaf migration suites, golden v2 fixtures, migration map | **A** | R2 |
|
||
| domain: `rebaseReportOnSheet` | rebase on another sheet | TS over the index | full; takes the sheet handle | yes | store restore and import | CLAUDE.md gate: behaviour preserved exactly | rebase suite (exact objects) | **A** (owner go, D-R12) | R2 |
|
||
| domain archive: `buildSheetSnapshot`, `assertSnapshot`, envelope v1 layered read, branding + labels schemas | archive contract | Zod | full; UTF-16 string caps and UTF-8 asset caps reproduced; closed `snapshotRejected` reasons | yes + native | app import and export | medium: attachment bytes change once (D-R11); `origin` quirk for unknown envelope versions preserved | envelope decision table, branding/labels suite, size test, three envelopes frozen as goldens | **A** | R2 |
|
||
| domain: `buildSheetIndex` | lookups by id | closures over Maps | different shape: a Rust-owned `SheetHandle` (built once per session) for the core calls, plus `SheetIndexData` exported once for React (views, annotations, finding zones, regions by id; annotations per view; spine per region and view; precomputed `name` per annotation in both languages; `node_by_path`) | yes | ~14 modules read properties instead of calling closures; no wasm call in a render | low; one duplicate-id policy (document order, first wins) | service and component suites | **A** | R2 |
|
||
| `apps/app/src/services/zoneInteraction.ts` | click decision, observation reducers | pure TS | full; `apply_click(handle, observation, annotation_id, view_id)`, `sync_vertebrae(handle, …)` | yes | `EditorRoute.onZoneClick` and `ObservationPickers` call the core per click with the observation only (the sheet stays in the handle) | low | 13-case service suite, route click-chain characterisation | **A** | R2 |
|
||
| data-building rules in components: `toggleLeaf` (Finding builder), `VertebraPicker` selection | product rules inside components | TSX | `build_finding`, `vertebra_selection` in the core | yes | components call the core on the user action | low | component suites keep their assertions | **A** | R2 |
|
||
| display helpers in components and routes: `zoneLabel`, `zoneTrees`, `unresolvedFindings`, `describeZone`, import message lines, `isIdentityComplete`, `pickLabel` in JSX | formatting of core data for the screen | TSX | portable, but run inside renders and `useMemo` with `t()`; moving them means wasm calls in the render path or a view-model layer | no | none; they read `SheetIndexData` | none | existing suites | **C**: React render glue over precomputed data (the sheet names and `node_by_path` they need come from the core) | n/a |
|
||
| `reportStore.ts` actions | report construction and edits | Zustand | rules in the core (`new_report(draft, sheet, id, created_at)`, `swap`, `set_*` validation); the store stays Zustand | yes | one-line delegations | low | store suite | **A** (rules) / C (Zustand, adapters) | R2 |
|
||
| `persistence.ts`, `practitionerCache.ts`, `localeStore.ts`, `authStore.ts`, `localeSync.ts` | storage adapters, GoTrue event glue | TS | glue; the only rules (`isLocale`, "account locale wins once per sign-in") are tied to supabase-js events | no | none | none | existing suites | **C**: browser storage and supabase-js session glue (no Rust GoTrue client with PKCE and refresh) | n/a |
|
||
| anatomy render: layer renderer, `composeViewSvg`, highlight, `viewBoxOf` | markers from the document; composition with highlight | pure tree + DOM mutation | `render_annotation_layer(document, view, states) → LayerElement` (same plain contract) and `compose_view_svg(asset, document, view, highlight) → String` | yes + native | app canvas and engine use one composition; `drawing.ts` parses a sanitised string with `DOMParser` and keeps `importNode` + click delegation | low on the layer (step6 view facts); the composed string is compared as parsed trees, not bytes | step6 `views.*.json`, DOM-equivalence of the composed views for the three reports (frozen with the TS code), security SVG cases | **A** | R3 |
|
||
| pdf `svg/{parse,sanitize,view}` + app `drawing.ts` denylist | untrusted SVG → safe tree | xmldom / DOMParser | `roxmltree` with DTD refused and a byte pre-scan for depth and size, own allowlisted tree, own serialiser; one sanitiser for canvas, PDF, Step 13 uploads and branding SVG | yes + native | denylist deleted | medium: the "zero-removal" oracle becomes a DOM-equivalence test on `horse.svg` | 7 hostile cases, caps, zero-removal (tree compare) | **A** | R3 |
|
||
| pdf reader: byte scan, bounded inflate, JSON depth pre-scan, stamp, layered read; PNG gate inflater | untrusted PDF → archive outcome | TS + `DecompressionStream` | `miniz_oxide` streaming inflate with cancel; same candidate ordering and budgets; the leniency decisions of I.2 pinned | yes (in a Web Worker) + native (Step 15 server validation, CLI) | app import runs the core in a dedicated Web Worker terminated after each import | low: scan (39), inflate (9), read (13) suites are byte-level oracles | the same suites in cargo on the fixtures in place; BLK-009 browser measurements | **A** | R4 |
|
||
| pdf writer: layout, pages, footer, links, attachment, metadata, `exportFromEnvelope`, branding PNG gate, `safeText`, `wrapLines`, labels (25 keys) | A4 archive writer | pdf-lib | `pdf-writer`; layout split from serialisation (draw log = the golden format); AFM vendored; `png` decodes the archived logos under the existing gate; fr/en month tables | yes + native | two synchronous calls: `compose_export_views(report, snapshot, branding) → [{key, svg, size}]`, the caller rasterises (canvas in the browser, resvg natively), then `write_archive(input, pngs) → {pdf, warnings}`; no rasteriser callback crosses the boundary | medium: widths with kerning, `Math.round` half-up, dates, upper-casing; lines, rectangles and colours are not golden-covered today (D-R2 adds that golden with the TS engine first) | 39 goldens through the Rust draw log, links read back from the written file with `lopdf`, re-export test, size test, poppler/pdfium render diff | **A** (after R3 and the reader; same phase as the reader) | R4 |
|
||
| `apps/app/src/pdf/browserRasterizer.ts` | SVG → PNG via `Image` + canvas | DOM | DOM adapter between the two core calls; a native rasteriser (`resvg`) serves the worker and tools if a server-side rendering need appears | no | unchanged | none | raster facts test | **C**: browser rasterisation is DOM; no resvg in the browser bundle (D-R3) | n/a |
|
||
| `apps/app/src/pdf/export.ts`, `import.ts`, `branding.ts` | wiring, Vite asset imports, download | TS | glue | no | thin | none | existing suites | **C**: Vite asset imports, Web Worker and DOM download | n/a |
|
||
| `apps/app/scripts/compare-reports.ts` + `compare/report.ts` | archive check CLI | tsx + Node | `faunosteo-tools report-compare` on the core (LRN-044 escaping ported) | native | none | low | 11 CLI cases | **A** | R4 |
|
||
| anatomy curation pipeline (changeset, applier 687 ops, migration map, CHANGELOG, REVIEW-REPORT, review overlays, seed SQL) + legacy importer | changeset → draft artifacts; baseline import re-run at every regeneration | TS + xmldom + Prettier + `node:fs` | full (sha-derived "v5-like" uuid, strict label equality, region inference, ops); outputs emitted by Rust with `js_number`; markdown tables written by Rust; Prettier no longer touches generated files (`.prettierignore`) | native (tools) | none | the 18 generated files and `documentSha256` change once (D-R5); counts, determinism and the 612-leaf semantics are the oracles | `seed.golden.test` (regenerated once, decided), determinism and count suites, 612-leaf test, review drawings compared as parsed trees against the xmldom-era files | **A** (after R2, R3) | R5 |
|
||
| `packages/supabase/scripts/upload-sheet-assets.ts` | operator upload of sheet SVGs (service key) | tsx + Node | `faunosteo-tools upload-sheet-assets` (reqwest) | native | none | none | manual operator check (SUPABASE.md §3.1) | **A** | R5 |
|
||
| `packages/supabase` `classifyAuthError`, publish gate | closed failure kinds; gate before RPC | TS | the gate calls the Rust validator (R2); the GoTrue code map is vendor-SDK glue | partial | gate delegates | none | existing suites | gate **A** (R2); code map **C** (supabase-js error shapes) | R2 |
|
||
| `packages/supabase` client factory, auth/profile wrappers, `database.types.ts`, PGlite harness | vendor SDK, generated types, test infra | TS | no Rust GoTrue client for the browser; PGlite is a JS/WASM library | no | none | none | | **C** | n/a |
|
||
| `auth/validation.ts`, `account/validation.ts` (Zod, i18n keys) | form field rules | Zod | portable but React-bound (retained list); the constraints are duplicated in SQL CHECKs and `config.toml` and drift (trim, UTF-16 vs `char_length`, `''` on names) | no | | | one constants module + a PGlite test reading `pg_constraint` and `config.toml` with the counting rule recorded (separate chore, D-R7) | **C** | chore |
|
||
| `lib/{dates,id}.ts` | `nowIso`, `todayIso`, `formatDate` (screen), `generateId` | Web APIs | clock and ids injected into the core; screen dates stay `Intl` | no | | | | **C** | n/a |
|
||
| `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/<quarantine_key> (≤ 5 MiB, 30 s timeout)
|
||
spawn faunosteo-worker decode ← same binary; `decode` is dispatched from a plain fn main
|
||
BEFORE any runtime or thread exists; empty env; stdin/stdout
|
||
child: assert Threads: 1 (/proc/self/status) → RLIMIT_AS 512 MiB, RLIMIT_CPU 10 s →
|
||
seccomp allowlist installed with TSYNC, kill on violation (list derived by strace
|
||
over the fixture corpus at the caps on the production image, not hand-written)
|
||
decode: image::guess_format ∈ {jpeg, png, webp} else unsupported_type
|
||
ImageReader with Limits {width ≤ 4096, height ≤ 4096, max_alloc 256 MiB}
|
||
header dimensions before decode (64 ≤ sides ≤ 4096 else dimensions)
|
||
decode (first frame of an animated WebP), apply_orientation (EXIF),
|
||
ICC → sRGB through moxcms when a profile ≤ 1 MiB is present, else assume sRGB
|
||
resize_to_fill 512×512 (Lanczos3), alpha kept
|
||
encode lossy WebP q=82 via libwebp-sys (C, confined to this process)
|
||
stdout: WebP bytes; exit code from a reserved table (never 101, never a signal number)
|
||
parent: read stdout up to 512 KiB (kill past it); parse the RIFF container only: size field =
|
||
byte length, chunk FourCC allowlist {VP8X, VP8, VP8L, ALPH}, canvas 512×512 from the
|
||
VP8X/VP8 header, no EXIF/XMP/ICCP chunk; sha256; size. NO pixel decode in the parent.
|
||
PUT /storage/v1/object/avatars/<object_key> (upsert) → POST rpc/complete_avatar_job
|
||
→ DELETE quarantine object → POST rpc/mark_quarantine_purged; a refusal → rpc/reject_avatar_job
|
||
SIGSYS, SIGKILL (deadline) and RLIMIT deaths are logged with their own internal code
|
||
(syscall number for SIGSYS) and mapped to processing_error; after 20 s the parent SIGKILLs
|
||
sweeper every 10 min: rpc/claim_purges → DELETE objects → rpc/ack_purge; key-driven quarantine sweep
|
||
watchdog: per-stage deadlines (claim 35 s, download 35 s, decode 25 s, upload 35 s, commit 35 s);
|
||
a stage past its deadline exits the process; Docker restarts it
|
||
start-up log: libwebp version (WebPGetEncoderVersion, CI fails below 1.6.0), seccomp status,
|
||
token expiry (service key: none)
|
||
```
|
||
|
||
The crash matrix, the write order, the lease and attempt rules, the purge
|
||
grace periods and the fairness rule of the Step 8 analysis apply unchanged.
|
||
The 60 s single watchdog of the Node proposal is replaced by per-stage
|
||
deadlines, because one iteration's worst case (three 30 s network calls plus
|
||
the 20 s child) exceeded it and would have burnt leases during a slow Storage.
|
||
|
||
### IV.2 Comparison with the Node proposal
|
||
|
||
| Aspect | Node 24 + sharp (STEP8 II.8) | Rust worker | Verdict |
|
||
|---|---|---|---|
|
||
| Decoders on untrusted bytes | libvips + libjpeg-turbo/mozjpeg + libpng + libwebp (C); three High libvips CVEs in 2026, twelve libpng CVEs since late 2025 | `zune-jpeg` (SIMD `unsafe`, togglable), `png` (no `unsafe`, fuzzed), `image-webp` (`forbid(unsafe)`), hard `Limits` | Rust better: smaller trusted base, caps by construction |
|
||
| Encoder | libwebp via sharp | libwebp via `libwebp-sys` 0.14 (C), in the same sandboxed child, on a buffer that child decoded; the parent checks the container header only | equivalent; the C surface is the encoder, process-confined (D-R4 lists the alternatives) |
|
||
| Orientation, ICC, metadata | `rotate()`, ICC → sRGB and stripping by default | `apply_orientation`, `moxcms` ICC → sRGB, stripping by construction (the encoder writes no metadata chunk) plus the parent's chunk allowlist | equivalent, verified rather than assumed |
|
||
| Isolation | two Node processes, child without env | one static binary, child without env **plus** rlimits and a traced seccomp allowlist installed before any thread | Rust better |
|
||
| Resource bounds | `limitInputPixels`, `mem_limit` 512m, 20 s kill | `Limits`, `RLIMIT_AS`, `RLIMIT_CPU`, 20 s kill, output cap 512 KiB, `mem_limit` | better |
|
||
| Image size and start | node:24-alpine + sharp prebuilt ≈ 150 MB | distroless/static + one binary ≈ 15 MB | Rust better on resources |
|
||
| Transport to Supabase | supabase-js with the service key over PostgREST and Storage | `reqwest` calls to the same two APIs with the same key (`webpki-roots` compiled in for HTTPS on managed) | equivalent |
|
||
| Maintenance | `sharp` Renovate rule | `cargo deny` in CI (licences, bans, sources blocking; advisories nightly) | equivalent |
|
||
| Managed Supabase | URL + key only | same | equivalent |
|
||
| Build complexity | none | Rust toolchain stage, `cc` for libwebp, musl | cost accepted by the rule; built in CI, pulled by digest (VIII.1) |
|
||
|
||
### IV.3 Worker crates
|
||
|
||
`tokio` (rt, process, time, io), `reqwest` (rustls, json, stream,
|
||
`webpki-roots`), `serde` / `serde_json`, `image` (default-features off;
|
||
`jpeg`, `png`, `webp`), `moxcms` (version resolved by `image`),
|
||
`libwebp-sys`, `sha2`, `rlimit`, `seccompiler`, `tracing` +
|
||
`tracing-subscriber` (JSON logs, field allowlist, control characters escaped:
|
||
LRN-044), `thiserror`. No database driver (one transport, no open DB port on
|
||
managed, as in STEP8 II.8).
|
||
|
||
### IV.4 Credential: as validated, with one hardening option recorded
|
||
|
||
The worker holds the service key in `.env.worker` as the owner validated
|
||
(STEP8 D1, II.8). A dedicated `faunosteo_worker` Postgres role with a minted
|
||
JWT would narrow a leak, but it is independent of the language and is not
|
||
"at the same cost": it needs the role granted to `authenticator` (the PGlite
|
||
shim defines only `anon`, `authenticated`, `service_role`), EXECUTE on the
|
||
nine worker RPCs plus a new RPC for the key-driven sweep lookup, `SELECT`,
|
||
`INSERT`, `UPDATE` and `DELETE` policies on `storage.objects` for the role
|
||
(which breaks the pinned census "2 / 1 / 0 per bucket" and the assertion
|
||
"no UPDATE / DELETE policy exists"), token expiry handling (log `exp` at
|
||
start, warn 30 days before, re-mint), a revocation path (`REVOKE
|
||
faunosteo_worker FROM authenticator` plus re-mint), and on managed an
|
||
operator-held signing key. Recorded as a Step 27 hardening option with
|
||
those prerequisites; not a decision of this study.
|
||
|
||
### IV.5 Tests specific to the Rust worker
|
||
|
||
- Decode child fixtures (STEP8 IV.2 list, unchanged): JPEG/PNG/WebP
|
||
accepted, renamed PNG, GIF/BMP/SVG/PDF/HTML refused, truncated, 32 px,
|
||
20 000² header, 5000², EXIF-rotated → upright and chunk-free, PNG trailer
|
||
after IEND, progressive JPEG with many scans and a large ICC under the
|
||
deadline with RSS asserted, sleeping child killed at 20 s.
|
||
- Sandbox tests (Linux, on the production image in CI): every accepted
|
||
fixture passes through the **fully** sandboxed child (the allowlist is
|
||
derived, then proven on the corpus at the caps: 4096² RGBA, 16-bit PNG,
|
||
CMYK JPEG, ICC through `moxcms`); a disallowed syscall kills the child and
|
||
the parent logs SIGSYS with the syscall number; `/proc/self/environ` is
|
||
empty; `Threads: 1` holds when the filter is installed.
|
||
- Parent checks: a child returning 511×511, an `EXIF` chunk, a wrong RIFF
|
||
size, 513 KiB of output, or garbage → rejected before any PUT; the child
|
||
is killed on output overflow.
|
||
- Integration against the local stack (CI `supabase` job): Alice's full
|
||
flow, replace, remove, sweep, late-landing bytes, as in STEP8 IV.2; one
|
||
HTTPS call in CI proves the CA bundle.
|
||
|
||
---
|
||
|
||
## Part V. Libraries retained and their limits
|
||
|
||
| Area | Retained | Rejected | Limits to manage |
|
||
|---|---|---|---|
|
||
| Serialisation | `serde`, `serde_json` (custom formatter), `thiserror`, `ts-rs` | `serde-wasm-bindgen`, `tsify`, `schemars` (until a consumer exists), `serde_jcs` | float printing owned by `js_number`; field order declared per struct |
|
||
| XML | `roxmltree` + own tree and serialiser | `quick-xml`, `usvg` as sanitiser (allows DTD, drops silently, rewrites the drawing) | depth and size pre-scan until the deep-nesting fix is released |
|
||
| PDF write | `pdf-writer` | `krilla` (no Standard 14 page text, merged dates; candidate for TTF), `printpdf` (no attachments), `lopdf` as writer | classic xref only (wanted); `f32` coordinates (links read back) |
|
||
| PDF read | own byte scan + `miniz_oxide`; `lopdf` test-only | `pdf`, `pdfium` in the app | same caps as today |
|
||
| Fonts | vendored Core 14 AFM (APAFML notice committed); later `skrifa` + `subsetter` + `harfrust` | `ttf-parser`, `rustybuzz` (RustSec unmaintained) | kerning-inclusive width rule reproduced from pdf-lib |
|
||
| PNG | `png` | UPNG semantics | gate stays ours; decoder under `Limits` |
|
||
| Raster | browser canvas (DOM adapter); `resvg` native in tools/worker when a need appears | `resvg` in the browser bundle | `allow_dtd`, 1M-element cap and the crop workaround handled by our sanitiser and adapter |
|
||
| Images (worker) | `image`, `moxcms`, `libwebp-sys` | `webp` crate, `image-webp` in the parent, `img-parts`, `infer`, `wasmtime`, `extrasafe` | `Limits.max_alloc` advisory → `RLIMIT_AS` is the hard cap; profile size capped |
|
||
| Sandbox | `seccompiler`, `rlimit` | `landlock` (redundant under the allowlist), user namespaces | allowlist derived by tracing, proven on the corpus |
|
||
| Runtime | `tokio`, `reqwest` (`webpki-roots`), `tracing` | `postgrest`, `supabase-rs` | ~10 hand-written endpoints tested against the local stack |
|
||
| WASM | `wasm-bindgen` + CLI (version from `Cargo.lock`), `binaryen` when needed | `wasm-pack` | crate/CLI lock |
|
||
| Hygiene | `cargo-deny` (licences, bans, sources blocking; advisories nightly and at release) | `cargo-audit` (same database), `cargo-chef` (BuildKit cache mounts suffice), `cargo-fuzz` before Step 27 (nightly toolchain; our own parsers only) | |
|
||
|
||
---
|
||
|
||
## Part VI. Progressive migration strategy
|
||
|
||
### VI.1 Principles
|
||
|
||
- **Freeze with the old code, then switch.** Before a phase ports a module,
|
||
every output that no test pins yet is committed as a golden produced by
|
||
the TypeScript code (LRN-046): the three archive envelopes, the composed
|
||
views as parsed trees, the draw log of lines, rectangles and colours. The
|
||
oracle suites are then ported to cargo on the fixtures in place (JSON
|
||
fixtures under `apps/app/tests/fixtures` and `packages/*/tests/fixtures`,
|
||
read by path; the two TypeScript fixtures `horse-slice.ts` and
|
||
`mini-sheet.ts` converted to JSON once). No dual-run harness.
|
||
- **Consumer-driven deletion.** A TypeScript module is deleted in the phase
|
||
that switches its last consumer; until then it is frozen (no new logic)
|
||
and its existing goldens keep proving it. The table in VI.4 names the
|
||
last consumer of every module so nothing is deleted while imported
|
||
(revision 1 broke this twice).
|
||
- **Goldens are never regenerated silently.** A phase that changes an
|
||
oracle (the attachment bytes at R2, the generated seed files at R5) says
|
||
so in its end criteria and the owner decides.
|
||
- **Every phase** ends with `pnpm check`, `cargo test --workspace --locked`,
|
||
`cargo clippy -D warnings`, `cargo deny check` (licences, bans, sources),
|
||
Docker builds green, the real-stack pgTAP when SQL changed, the verifier
|
||
and security gates, the rollback row of VI.3 proven, and a manual
|
||
validation script for the owner.
|
||
- Phases are gitflow branches (`feature/rust-r<n>-<slug>`;
|
||
`chore/rust-r0-workspace` for the foundation).
|
||
|
||
### VI.2 Phases and end criteria
|
||
|
||
| Phase | Content | Depends on | End criteria (verifiable) |
|
||
|---|---|---|---|
|
||
| **R0 Foundation** (inside Step 8) | `Cargo.toml` workspace, `rust-toolchain.toml`, `deny.toml`, lints, `crates/core` skeleton (no app consumer yet), `crates/worker` skeleton, CI job `rust`, worker image build, `docs/development/RUST.md` (setup, commands, boundary rules), `DEPLOY.md`: images built in CI and pulled by digest, CSP line with `'wasm-unsafe-eval'`, gzip for `.wasm`, VPS disk and RAM headroom recorded; `rustup` on the dev host (owner) | none | `cargo test`, `clippy`, `deny` green in CI; worker image builds (< 30 MB) and starts against the local stack with no job; panic strategy on wasm32 verified and written in `RUST.md`; CI duration and runner cache behaviour measured and recorded; no production artifact changed yet |
|
||
| **R1 Step 8 worker** | Part IV: decode child, sandbox, transport, sweeper, per-stage deadlines, compose service, `.env.worker.example`, the Step 8 migration and app work as analysed | R0, Step 8 go | STEP8 IV.2 scenarios green (pgTAP, worker fixtures, sandbox tests on the production image, local-stack integration, real-stack e2e); image non-root, `cap_drop ALL`, read-only; libwebp ≥ 1.6.0 logged; owner manual validation of the avatar flow |
|
||
| **R2 Domain core** | `crates/core` domain: sheet document + rules, report v3/v2 + migration, rebase (owner go, D-R12), snapshot/envelope/branding/labels, `SheetHandle` + `SheetIndexData`, reducers, `build_finding`, `vertebra_selection`, `new_report`; `crates/wasm` facade (JSON strings, `ts-rs` types, poison-and-reinstantiate, lazy init, `core_unavailable`); `packages/core-wasm` package; app Dockerfile wasm stage; app switched (`SheetProvider`, store, click chain, pickers, publish gate); app importers codemodded from `@faunosteo/domain` to `@faunosteo/core-wasm`; `packages/domain` frozen for the TS engine and pipeline; three envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP | R0 | the domain, service, store, component and route suites pass with their assertions on the core; the three frozen envelopes parse with the frozen Zod schemas and compare semantically equal (bytes differ by decision D-R11); the 39 step6 goldens and the seed golden are untouched (the TS engine and pipeline still run on frozen TS); `pnpm build` with the wasm; the app boots under the exact production headers (CSP) in a headless check; a wasm load failure leaves `/login` and `/app` usable and shows the degraded state in the editor; a deliberate trap re-instantiates the module; served module size ≤ 600 KB compressed; owner manual FR/EN flow |
|
||
| **R3 Anatomy core** | `crates/core` anatomy: tree, sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas on the core (denylist deleted); the TS engine still composes with its frozen TS copy; composed-view trees for the three reports frozen with the TS code first | R2 | step6 `views.*.json` unchanged through the app path; composed views DOM-equivalent to the frozen trees; 7 hostile cases + caps + zero-removal (tree compare) in cargo; canvas suite green; one sanitiser reachable from the app (grep) |
|
||
| **R4 PDF core** (reader + writer + CLI) | `crates/core` pdf: scan, bounded inflate, layered read; layout → draw log → `pdf-writer`; AFM vendored; `png` + gate; dates tables; the leniency decisions of I.2 pinned by fixtures; draw-log golden for lines, rectangles and colours frozen with the TS engine first (D-R2); app import in a Web Worker, app export on the two-call design; `report-compare` tool; `packages/pdf` deleted (last consumer); frozen TS `render/` deleted with it only if the pipeline no longer imports it (it does: kept until R5) | R3 | 39 goldens reproduced exactly through the Rust draw log (text, images), links read back from the written files with `lopdf`, views via the app path; the new draw-log golden reproduced; scan (39), inflate (9), read (13), security (55), text (5), size (2) suites in cargo; the hostile corpus through the wasm build; BLK-009 browser measurements (Chromium, Firefox, Safari, one low-end phone) recorded in `PDF_IMPORT_HARDENING.md` §5 as done items (the gate itself stays open until every §5 item is done); poppler or pdfium render diff of the three reports within a stated threshold; the last TS scanner, kept as a test fixture, and the previous release's reader read every R4 fixture PDF; stored attachment < 250 KB; no `pdf-lib`, `@pdf-lib/*`, `@xmldom/xmldom` in the lockfile of `apps/app` or `packages/pdf` |
|
||
| **R5 Curation pipeline, importer, operator tools** | `crates/core` curation + `cli` bins: import-equine, upload-sheet-assets; outputs emitted by Rust (`js_number`, markdown tables); `.prettierignore` on generated dirs; seed golden regenerated once (decided); review drawings compared as parsed trees against the xmldom-era files; `packages/anatomy` and `packages/domain` deleted (last consumers); CLAUDE.md folder map, `packages/README.md`, `WORKSPACE.md`, CHANGELOG | R2, R3, R4 | `seed.golden.test` green on the regenerated set; determinism (two runs byte-equal), counts (27/792/612/41, 811 nodes), 612-leaf semantics unchanged; `documentSha256` changed once and the import of an older archive shows the rebase message with 0 unresolved items on identical content; no TypeScript business logic outside UI glue (grep census in `RUST.md`); workspace test count reconciled with the deleted-tests list (TEST_STRATEGY §6) |
|
||
|
||
Order: R0 and R1 inside Step 8 (R1 is Step 8). R2 right after Step 8 and
|
||
before Step 9, so that every later step writes its rules in Rust. R3, R4 and
|
||
R5 before Step 13 (which needs the sanitiser in the worker), interleaved with
|
||
Steps 9 to 12, which touch no module these phases move. The TTF font change
|
||
is a separate later change with its own golden regeneration (D-R2).
|
||
|
||
### VI.3 Rollback per phase
|
||
|
||
Production rollback is "deploy the previous image by digest" (VIII.1), so
|
||
each phase states what the previous build must still read.
|
||
|
||
| Phase | Artifacts written by the new build | What N-1 must read | Proof |
|
||
|---|---|---|---|
|
||
| R1 | avatars (WebP) | the app only displays them; the Node proposal never shipped | none needed |
|
||
| R2 | drafts in `osteo:draft` and archives in `osteo:archive` written by the core (struct order, `js_number`); PDFs still written by the frozen TS engine from core-produced reports | N-1 (Step 7 build) parses the draft and the envelope with its Zod schemas | N-1 reader test on the frozen fixtures; a draft N-1 cannot parse goes to the quarantine key with a notice (never discarded) |
|
||
| R3 | none persisted (canvas only) | n/a | |
|
||
| R4 | PDFs from `pdf-writer` (classic xref, same attachment, same stamp) | N-1 scanner finds the attachment and the stamp; Step 6 build reads bare v3 and envelope | the kept TS scanner fixture and the previous release's reader read every R4 fixture PDF; `DEPLOY.md` rollback note updated as for Step 6 |
|
||
| R5 | regenerated seed (new `documentSha256`) | N-1 app bundles the old seed and rebases archives written on the new one (visible message, nothing lost); reports written on the old seed rebase on the new build | rebase tests both ways on the two seeds |
|
||
|
||
### VI.4 What is deleted when (last consumer named)
|
||
|
||
| Module | Consumers today | Last consumer switched at | Deleted at |
|
||
|---|---|---|---|
|
||
| `services/zoneInteraction.ts`, component data-building rules, store rules | app | R2 | R2 |
|
||
| `packages/domain` Zod contracts and functions | app (R2), TS engine (R4), TS pipeline (R5), scripts (R4) | R5 | R5 (`packages/domain` removed; app imports codemodded at R2) |
|
||
| `anatomy/drawing.ts` denylist | app canvas | R3 | R3 |
|
||
| `packages/pdf/src/svg/**` (sanitiser, view) | TS engine | R4 | R4 |
|
||
| `packages/anatomy/src/render/**` | app (R3), TS engine (R4), TS pipeline `app-review.ts` (R5) | R5 | R5 |
|
||
| `packages/pdf/src/**` (reader, writer, attachment, branding gate), `apps/app/scripts/**`, `browserRasterizer.ts` stays | app, CLI | R4 | R4 (`browserRasterizer.ts` kept as the DOM adapter) |
|
||
| `packages/anatomy/src/{legacy,curation,cli}/**`, `packages/supabase/scripts/upload-sheet-assets.ts` | operator | R5 | R5 |
|
||
| `packages/anatomy`, `packages/domain`, `packages/pdf` packages | | | R4 (pdf), R5 (anatomy, domain) |
|
||
|
||
---
|
||
|
||
## Part VII. Adaptations to the development plan
|
||
|
||
| Step | Plan text today | Adaptation under the rule |
|
||
|---|---|---|
|
||
| 8 Files | Node worker + sharp (STEP8 D1) | D1 reads "native Rust worker"; R0 + R1 inside the step; `apps/worker` is not created; `crates/worker` is; service key kept (IV.4) |
|
||
| 9–12 | TS mirrors of SQL rules (verification status machine, contact normalisation) | mirrors in `crates/core` domain, called through the wasm; UI unchanged |
|
||
| 13 Sheets in DB | SVG processor "from packages/pdf" | the R3 sanitiser runs in the worker's decode child (same isolation as images); the Supabase `SheetProvider` stays TS glue, parsing through the core |
|
||
| 14 Cloud reports | autosave, revisions, TS persistence adapter | adapters TS; diff/throttle rules in the core; optional `pg_jsonschema` CHECK from a `schemars` export (decision at the step, first consumer of JSON Schema) |
|
||
| 15 PDF artifacts + import | "Zod validation server-side: Edge Function or staging row"; artifacts = PDFs generated by the browser | the worker validates the attachment with the core reader (R4); no Edge Function; server-side rendering is not in the plan; if a need appears, `resvg` native between the two core calls |
|
||
| 16 Offline | outbox in TS | IndexedDB glue TS; replay/dedupe/conflict rules in the core |
|
||
| 17 Sheet editor | editor store with undo, geometry | document operations and geometry as a core module, UI React |
|
||
| 19 Notifications/worker | `apps/worker` Node, EmailProvider, `private.jobs`, `packages/i18n` for templates | `crates/worker` `run` gains the `private.jobs` loop (RPC with `SKIP LOCKED`) and templates rendered in Rust from Rust-side dictionaries; `packages/i18n` stays UI-only |
|
||
| 20–21 Agenda, travel | expiry rule TS mirror, routing adapter, "Edge Function or worker endpoint" for the Google OAuth callback | mirror in the core; routing and calendar sync in the worker; the callback is the first inbound route of the worker's `serve` subcommand (axum, one route, behind the reverse proxy) |
|
||
| 22 Public web | Q8 framework | Astro (global rule), D-R8 |
|
||
| 23 Billing | "Edge Function stripe-webhook" | `serve` hosts the webhook (signature check, idempotency table unchanged) |
|
||
| 24 Imports | adapters in the Node worker | Rust adapters (`csv`, `calamine`, `zip`), same `ImportAdapter` contract |
|
||
| 26 Lifecycle | export/archive/restore jobs in the Node worker | Rust jobs in the same binary |
|
||
| 27 Hardening | | adds `cargo deny` advisories, the sandbox tests and the `cargo-fuzz` run (nightly toolchain, our own parsers) to the release gate; the worker-role option of IV.4 evaluated here |
|
||
| BACKEND_ARCHITECTURE §6 | Edge Function row | "Rust service (worker `serve`)"; PostgreSQL rows unchanged |
|
||
| WORKSPACE.md, packages/README.md | `apps/worker` Node, `@faunosteo/i18n` for the worker | `crates/*`; i18n package UI-only |
|
||
| TEST_STRATEGY.md | layers | adds the cargo layer, the freeze-then-switch rule, the N-1 reader test and the conformance fixtures shared with pgTAP |
|
||
|
||
---
|
||
|
||
## Part VIII. Docker, Supabase and CI impacts
|
||
|
||
### VIII.1 Docker and deployment
|
||
|
||
- **Images are built in CI (or on the dev host) and pulled by digest.** The
|
||
VPS (1 vCPU, 1 GB) never compiles Rust: `docker compose up --build` on the
|
||
VPS is replaced by `docker compose pull && up -d` on tagged images
|
||
(registry: the Gitea container registry of the forge, or Scaleway's);
|
||
rollback = the previous digest. This is a prerequisite recorded in R0 and
|
||
written into `DEPLOY.md` (routine deploys, rollback, disk headroom).
|
||
- **App image**: a first stage `FROM rust:1.99.0-bookworm AS wasm` (BuildKit
|
||
cache mounts on `~/.cargo` and `target`, pinned `wasm-bindgen-cli`)
|
||
producing `packages/core-wasm/pkg`; the committed
|
||
`packages/core-wasm/package.json` is in the manifest COPY list so
|
||
`pnpm install --frozen-lockfile` keeps working; the Node builder copies
|
||
`pkg/` before `pnpm build`; nginx serves `.wasm` (and `.wasm.gz` with
|
||
`gzip_static`) with the hashed name.
|
||
- **Worker image**: `rust:1.99.0-alpine3.24` builder (musl, `musl-dev`,
|
||
`build-base` for libwebp's `cc` build) → `distroless/static:nonroot` (CA
|
||
bundle present; `scratch` rejected), one static binary. Compose service
|
||
`worker` (container `faunosteo_worker`): `read_only: true`, `tmpfs: /tmp`,
|
||
`cap_drop: [ALL]`, `security_opt: [no-new-privileges:true]`,
|
||
`mem_limit: 512m`, `cpus: 1`, `pids_limit: 64`, no `ports`, Supabase
|
||
internal network only, `restart: unless-stopped`, `env_file: .env.worker`.
|
||
The default Docker seccomp profile stays (it permits the inner filter).
|
||
- **Naming**: `faunosteo_worker`, image `faunosteo/worker` (BDR-035).
|
||
|
||
### VIII.2 Supabase
|
||
|
||
- No schema change comes from the rule itself.
|
||
- Conformance fixtures for `sheet_document_issues` land as a generated
|
||
pgTAP file with inlined fixtures (PGlite and real stack), owned by R2.
|
||
- Managed migration: the worker container is hosting-agnostic (URL + key);
|
||
HTTPS works out of the box (`webpki-roots`, distroless CA bundle, one
|
||
HTTPS call tested in CI).
|
||
|
||
### VIII.3 CI (`.gitea/workflows/ci.yml`)
|
||
|
||
- New job `rust` (runs before `check`): toolchain from `rust-toolchain.toml`
|
||
(`dtolnay/rust-toolchain`), `cargo fmt --check`, `cargo clippy --workspace
|
||
--all-targets -D warnings`, `cargo test --workspace --locked`, `cargo deny
|
||
check licenses bans sources`, `pnpm wasm:build`, artifact
|
||
`packages/core-wasm/pkg` uploaded. Cache: `Swatinem/rust-cache` if the
|
||
Gitea cache server works (verified at R0), else a directory cache on the
|
||
runner host.
|
||
- `check` downloads the artifact before `pnpm install`. `docker` builds both
|
||
images and pushes them by tag and digest on `main` and `develop`.
|
||
`supabase` runs the worker integration test against the local stack.
|
||
- Nightly: `cargo deny check advisories`; from Step 27, the fuzz run.
|
||
|
||
### VIII.4 Local development
|
||
|
||
- Owner action: install `rustup` (lives in `~/.cargo`, no global package);
|
||
the pinned toolchain installs itself from `rust-toolchain.toml`;
|
||
`wasm32-unknown-unknown` target; `cargo install wasm-bindgen-cli
|
||
--version <from Cargo.lock>` and `cargo-deny`.
|
||
- `pnpm dev` keeps working: `pnpm wasm:build` once and after Rust changes
|
||
(a `cargo watch` recipe in `RUST.md`); Vite serves the `.wasm` from the
|
||
package.
|
||
- The worker runs against the local stack with `cargo run -p
|
||
faunosteo-worker -- run` and `.env.worker` (SUPABASE.md §8 recipe).
|
||
|
||
---
|
||
|
||
## Part IX. Validation criteria and risks
|
||
|
||
### IX.1 Validation criteria of the orientation (beyond the per-phase ones)
|
||
|
||
1. No regression on the owner's list: Report v3, v2 PDF import, autonomous
|
||
archives, immutable sheet versions, RLS, unresolved findings, FR/EN, file
|
||
security, graphics. Proof = the existing suites kept with their
|
||
assertions (one-to-one migrations named in commits, TEST_STRATEGY §6),
|
||
goldens unchanged except where a decision regenerates them, pgTAP
|
||
unchanged, the N-1 reader test green at every phase.
|
||
2. No duplicate business logic at the end of a phase, by the consumer-driven
|
||
deletion table (grep census in `RUST.md`); hand-written TS mirrors of
|
||
core helpers are not allowed (the core precomputes what React needs).
|
||
3. Security gates: the security-auditor runs on every phase; the worker
|
||
sandbox tests run on the production image; `cargo deny` licences, bans
|
||
and sources block, advisories gate releases.
|
||
4. Operability: worker image size, start time, memory ceiling, libwebp and
|
||
seccomp status logged at start; a runbook line per failure mode in
|
||
STORAGE.md; deploy and rollback never compile.
|
||
5. Cost visibility: CI duration and the served module size recorded in each
|
||
phase's TODO note.
|
||
|
||
### IX.2 Risks
|
||
|
||
| Risk | Likelihood | Effect | Mitigation |
|
||
|---|---|---|---|
|
||
| Rust skills and velocity on a one-person team | high at first | slower steps 8 to 12 | R0 small; executors briefed with the boundary rules; clippy and deny as guardrails; frozen oracles catch what review misses |
|
||
| Dual toolchain in CI and Docker | certain | CI minutes | caches; wasm artifact reused by `check`; images built once, pulled by digest |
|
||
| WASM module as a point of failure (CSP, 404 after deploy, trap, memory growth) | medium | editor unusable or tab memory | CSP line and headless check at R2; lazy init with `core_unavailable`; poison-and-reinstantiate; reader in a terminated Web Worker; hashed file name |
|
||
| Hidden JS semantics in outputs and readers (float printing, upper-casing, ICU dates, kerning widths, rounding, lenient decoding, duplicate keys, `.int()`, `\s`) | high | golden mismatches or stricter readers refusing old files | the I.2 list with a fixture each before the owning phase; leniency decisions recorded; N-1 reader test |
|
||
| Sheet identity hash changes at R5 | certain | every older archive rebases once on import (message, nothing lost) | stated in R5's criteria and in the CHANGELOG; rebase tested both ways |
|
||
| Goldens regeneration governance | medium | silent layout drift | the Step 6 rule: owner decision per regeneration; relaxed fields never widened without a decision |
|
||
| Crates maintained by one person (`zune-jpeg`, `moxcms`, `libwebp-sys`, `ts-rs`, `krilla`) | medium | abandonment | `cargo deny` `unmaintained` advisories; alternatives in Part V; decoders confined to the child; the boundary has no third-party crate |
|
||
| `roxmltree` deep-nesting overflow (fix unreleased) | known | parser DoS | depth cap by byte pre-scan; pin the fixed release |
|
||
| seccomp allowlist killing a valid decode | medium if hand-written | valid photos rejected after three leases | derived by tracing, proven on the corpus at the caps in CI, SIGSYS logged with the syscall number |
|
||
| VPS resources | certain | OOM or full disk during a build | never build on the VPS (VIII.1); disk headroom recorded |
|
||
| Gitea runner caches for Rust | unverified | slow CI | measured at R0; host-level cache fallback |
|
||
| `wasm-bindgen` crate/CLI version lock | certain | broken builds on drift | one version read from `Cargo.lock` by the install lines |
|
||
| Two implementations lingering | medium | drift, double maintenance | VI.4 last-consumer table is part of each Definition of Done |
|
||
| Public web framework conflict | certain | decision needed | D-R8 |
|
||
|
||
### IX.3 Explicit non-goals of the rule
|
||
|
||
- Rewriting React screens, stores, routing or styling in Rust (Yew, Leptos,
|
||
Dioxus): excluded by the owner's retained list and the validated mockups.
|
||
- Replacing supabase-js in the browser or PostgREST/RLS by a Rust API layer:
|
||
excluded (retained list; RLS stays the boundary).
|
||
- Running Rust inside PostgreSQL (`pgrx`): excluded by managed compatibility.
|
||
- Moving SQL transactional rules to Rust: excluded.
|
||
- Shipping `resvg` to the browser: excluded (size, no visual change wanted).
|
||
|
||
### IX.4 Unverified items (settled at R0 or at the phase that needs them)
|
||
|
||
- Panic strategy and `catch_unwind` on stable `wasm32-unknown-unknown` for
|
||
the pinned toolchain (handled as abort regardless).
|
||
- `resvg` byte-identical output native vs the Node test adapter (README
|
||
claim; matters only if a server-side rendering need appears).
|
||
- Exact libwebp version string in `libwebp-sys` 0.14.4 (≥ 1.6.0 by API
|
||
presence; logged at start, checked in CI).
|
||
- `serde_json`/`zmij` exponent thresholds vs JavaScript (the `js_number`
|
||
formatter is tested on the committed overlays regardless).
|
||
- Gitea runner support for `Swatinem/rust-cache`; cold build times on the
|
||
runner; registry choice for images.
|
||
- Core wasm size and instantiate time (measured at R2).
|
||
- The syscalls a static-musl decoder needs (`mprotect`, `madvise`,
|
||
`rt_sigreturn`, `tkill`…): derived by tracing at R1, never assumed.
|
||
|
||
---
|
||
|
||
## Part X. Decisions for the owner
|
||
|
||
| Id | Question | Recommendation |
|
||
|---|---|---|
|
||
| D-R1 | Workspace layout | Three crates: `core` (feature-gated library with tool binaries), `wasm` (facade), `worker` (binary); no crate per module, no `crates/editor` |
|
||
| D-R2 | PDF engine | Reader and writer ported together at R4 with the Standard 14 AFM metrics (goldens exact); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port (additive); TTF fonts as a separate later change with its own regeneration |
|
||
| D-R3 | Rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle |
|
||
| D-R4 | Lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; alternatives: lossless WebP (pure Rust, 5 to 10× larger files) or AVIF (`ravif`, pure Rust, changes D4's format) |
|
||
| D-R5 | Sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives rebase on import with a visible message and 0 unresolved items (as any content changeset); no Prettier dependency kept |
|
||
| D-R7 | Form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home: a hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, with the counting rule recorded |
|
||
| D-R8 | Public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception; revisit only if the site needs no islands |
|
||
| D-R9 | Edge Functions | Retired from the plan (limits, hand deployment, one Rust runtime); webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy |
|
||
| D-R10 | Order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9–12 |
|
||
| D-R11 | Archive attachment bytes | New contract adopted at R2 (declared field order, `js_number`, optional absent / nullable null); every previous reader keeps parsing it (N-1 reader test, permanent); the bytes of existing PDFs are untouched |
|
||
| D-R12 | Gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) |
|
||
| D-R13 | Serving the wasm in production | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples, gzip for `.wasm`, images built in CI and pulled by digest (no compile on the VPS), served module ≤ 600 KB compressed enforced in CI |
|
||
| D-R14 | BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the §5 browser measurements; the external-user import gate (BDR-040) stays open until every §5 item is done, never closed by R4 alone |
|
||
|
||
The owner's confirmed Step 8 decisions D1 to D9 are kept; D1 reads "native
|
||
Rust worker" from this review on; the worker credential stays the service
|
||
key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1
|
||
(that role) is therefore no longer a decision of this study, which is why
|
||
the numbering skips it.
|