docs(docs): Rust review annexes — expanded decision table D-R1..D-R14 and R0 scope (Docker builder toolchain, 7 experimental proofs); chore(memory): BDR-044 orientation validated, journal, TODO R0

This commit is contained in:
bchanot committed 2026-10-12 22:58:09 +02:00
1 parent 3fbf34f663
commit 51667788e5
4 files changed
+108 -2

No files matched your search

@@ -849,3 +849,103 @@ 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.