# Rust in the Faunosteo monorepo Status: plan R0 (foundation), 2026-10-12, on `feature/rust-r0-foundation`. Rule and roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III boundary rules, Part VI phases R0–R5, Annex B R0 scope, Annex C owner amendments). R0 ships the toolchain, the workspace skeleton, the worker's sandboxed child, the browser module loader and seven experimental proofs. No application behaviour, interface, archive or database changes; the frontend does not load the module before R2; the worker's job loop arrives at R1. ## 1. Toolchain: reproducible in Docker, never on the VPS Every cargo command runs inside the reference builder image, so CI and a developer machine use the same compiler and the production VPS never needs Rust (images are built in CI and pulled by digest, DEPLOY.md "Image deploy by digest"). | Piece | Where | Pinned by | |---|---|---| | Rust 1.99.0, edition 2024, rustfmt, clippy, `wasm32-unknown-unknown` | `docker/rust-builder.Dockerfile` (`FROM rust:1.99.0-bookworm`) | `rust-toolchain.toml` (same channel; a difference would make rustup download inside the container) | | `wasm-bindgen-cli` 0.2.129 | same image | `wasm-bindgen = "=0.2.129"` in `Cargo.toml`; `docker/wasm-build.sh` refuses to run when `Cargo.lock` and the CLI differ | | `cargo-deny` 0.20.2 | same image | `deny.toml` | | worker builder | `crates/worker/Dockerfile` (`FROM rust:1.99.0-alpine3.24`, `build-base` for libwebp) | same channel | Commands (root `package.json`): ```bash pnpm rust:builder # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold) pnpm rust:check # docker/rust-check.sh: fmt --check, clippy -D warnings (all targets), # cargo test (core, wasm), ts-rs export, cargo deny licenses/bans/sources pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored), prints raw and gzip sizes pnpm worker:test # crates/worker/Dockerfile stage test: 13 sandbox tests + seccomp derivation pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static:nonroot) bash docker/rust-run.sh cargo # any cargo command in the builder ``` `docker/rust-run.sh` mounts the repository at `/w` and keeps Cargo's registry and the target directory in the named volumes `faunosteo_cargo_registry` and `faunosteo_rust_target` (incremental builds take seconds). A local `rustup` is optional for the inner loop (same `rust-toolchain.toml`); the container is the arbiter. ## 2. Workspace ```text Cargo.toml workspace (resolver 3), pinned [workspace.dependencies], lints, profiles rust-toolchain.toml channel 1.99.0, components rustfmt + clippy rustfmt.toml edition 2024, max_width 100 clippy.toml disallowed-methods: std::time::*::now, std::fs::*, std::env::var* (the core) deny.toml licences allow-list, bans (duplicates warn, wildcards deny, path deps allowed), sources .cargo/config.toml wasm shadow stack 1 MiB (explicit), TS_RS_EXPORT_DIR = packages/core-wasm/types crates/core faunosteo-core: lib, no I/O (lint), serde + serde_json only crates/wasm faunosteo-wasm: cdylib facade over core (wasm-bindgen) crates/worker faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit) packages/core-wasm loader, generated types (committed), vitest proofs ``` Lints: `unwrap_used`, `expect_used` and `disallowed_methods` are errors in the libraries (tests allow them explicitly at the top of the file); `unsafe_code` is forbidden everywhere except the worker (libwebp FFI, each block with a `SAFETY` comment). Dependencies are optimised even in debug builds (`profile.dev.package."*"`) because the sandbox tests decode 4096² images under a 10 s CPU limit. ### 2.1 Boundary rules in code (review III.3) - `faunosteo_core::facade::call(op, json) -> json`: one operation name, one JSON text in, the outcome envelope out (`{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`), never a panic on content. R0 ops: `core_version`, `pretty_json`, `sheet_ref`, `report_zone`. - `faunosteo_core::json`: `js_number(f64)` prints floats as ECMAScript `Number::toString`; `JsPrettyFormatter` is `serde_json`'s pretty formatter with that rule; `to_js_pretty` and `pretty_js_round_trip` produce `JSON.stringify(v, null, 2)` byte for byte (proof §5.2). - `faunosteo_core::domain::report`: `SheetRef`, `ReportZone`, `Vertebra`, `LateralSide`, `Unresolved`, field order of the Zod schemas, optional fields `skip_serializing_if = "Option::is_none"`, nullable fields plain `Option`, unknown keys ignored where Zod strips them. `cargo test -p faunosteo-core --features ts` writes the TypeScript types to `packages/core-wasm/types` (committed; CI fails on drift). - `packages/core-wasm/src/index.ts`: `loadCore()` instantiates a **fresh** module each time (cache-busting import of the glue), `callCore()` parses the envelope, `isCoreBuilt()` lets the proofs skip when `pkg/` is absent. ## 3. The worker (R0 skeleton, R1 job loop) `faunosteo-worker` is one static musl binary with subcommands dispatched by a plain `main` (no async runtime, no thread), so `decode` installs its sandbox in a single-threaded process: - `decode`: refuses a non-empty environment; checks `Threads: 1` in `/proc/self/status`; disables core dumps (`PR_SET_DUMPABLE 0`, `RLIMIT_CORE 0`: a dump would hold the uploaded photo); `RLIMIT_AS` 512 MiB, `RLIMIT_CPU` 10 s soft / 12 s hard (soft = hard made the kernel SIGKILL first, finding §5.4); seccomp allowlist installed with TSYNC, `KillProcess` on anything else, with argument filters: `tkill`/`tgkill` may only send SIGABRT to the child's own pid (never a signal to the keyed parent or a sibling), `mmap` may not map `PROT_EXEC`; then reads ≤ 5 MiB on stdin, sniffs the format (JPEG, PNG, WebP), decodes with `image::Limits` (sides ≤ 4096, alloc 256 MiB), applies the EXIF orientation, `resize_to_fill` 512 × 512, encodes lossy WebP (q 82) through `libwebp-sys` (C, this process only), writes stdout. Exit codes in `exit_codes.rs` (10–18, never 1, 101 or a signal number). - the parent side (`spawn::Spawner`, used by the tests now and by R1): `env_clear`, stdin/stdout/stderr piped, output read up to 512 KiB (the child is killed past it), 20 s deadline, classification of every exit (`Produced`, `Rejected{code}` for the content codes 12 to 17, `Broken{code}` when the child could not even start (usage, non-empty environment, sandbox failure, internal: R1 alerts instead of blaming the upload), `Signalled{signal}`, `OutputOverflow`, `Timeout`, `Failed`). The parent **never decodes**: `webp_check::inspect` parses the RIFF container only (chunk allowlist `VP8X`, `VP8 `, `VP8L`, `ALPH`; canvas size from the headers, the frame size must agree with the canvas; any `EXIF`, `XMP `, `ICCP` or unknown chunk refuses the output; owner amendment of D-R4). The child's stderr (≤ 4 KiB) is child-controlled text: R1 never logs it raw (LRN-044). - `run --check`: prints the resolved configuration without secrets (which variables are set, the linked libwebp version, refused below 1.6.0). A plain `run` does nothing before R1 and says so. - `version`: binary, workspace and libwebp versions. - test hooks (`--features test-hooks`, never in a release build): fixtures generated in memory (no binary in git), `--no-seccomp` (rlimits only, prints the `SECCOMP-MARKER` line for the strace derivation), `--violate` (`getcwd` after the filter), `--flood`, `--alloc-gib n`, `--spin`, `print-allowlist`. Image: `crates/worker/Dockerfile`, stages `build` (release, static), `test` (sandbox tests and `scripts/derive-seccomp.sh` on the **release profile** with the `test-hooks` feature, so the binary under test differs from the shipped one by the feature-gated hooks only), `runtime` (`gcr.io/distroless/static-debian12:nonroot`, `USER nonroot`, `ENTRYPOINT /faunosteo-worker`, `CMD run --check`). Measured 2026-10-12: image 8.7 MB (one static binary), `run --check` exits 0 with `--read-only --cap-drop ALL --security-opt no-new-privileges:true`. ## 4. CI - Job `rust` (before `check`): builds the builder image, runs `docker/rust-check.sh`, checks the committed ts-rs types for drift, builds the browser module (size printed). - Job `check`: builds the module the same way, then the existing Node pipeline; the `core-wasm` proofs run because `pkg/` exists. - Job `docker`: application image, worker `test` stage (sandbox tests and seccomp derivation on the musl binary that ships), worker runtime image started once with `--read-only --cap-drop ALL`. - `rust-advisories.yml`: nightly and manual `cargo deny check advisories`, out of the blocking path on purpose. - `release-images.yml`: manual only, on `main` or `develop`; the dispatch input is a typed choice re-validated through an environment variable; the RustSec advisories gate runs first; an ephemeral `buildx` builder with its own cache builds the images (nothing a PR build left in the daemon's cache mounts or volumes can reach a release image); secrets reach the shell through env only, the login lives in a per-job `DOCKER_CONFIG` removed at the end; `actions/checkout` pinned to a commit. It pushes `faunosteo_app:` and `faunosteo_worker:` and prints their digests. Deploys nothing (DEPLOY.md "Image deploy by digest"). Not measured here: the forge runner's cache behaviour and cold build times (the runner was not available from this host). The builder image build took about 6 minutes cold on the development host; both image builds reuse BuildKit cache mounts (`faunosteo_cargo_registry_musl`, `faunosteo_target_musl`). ## 5. R0 proofs (2026-10-12, development host, Docker 29.8 rootless, kernel 7.0) Each proof is a permanent test; the numbers are what the run produced. ### 5.1 Panic strategy on wasm32 (`packages/core-wasm/tests/panic.test.ts`) - A Rust panic reaches JavaScript as `WebAssembly.RuntimeError` (`unreachable`): the module is panic = abort, `catch_unwind` cannot be used there. - Exhausting the 1 MiB shadow stack (2 000 000 frames of 128 bytes) traps (`RuntimeError`) instead of corrupting memory. - After a stack-exhaustion trap, the next call on the same instance fails in the allocator (`memory access out of bounds`, deterministic). After a plain panic the same instance *still answers*, with a stack pointer that was never unwound: the dangerous case. Rule for R2: no instance is reused after any trap; a fresh instance is a new module record (the wasm-bindgen glue caches its instance in a module variable, and the ESM cache returns the same module for the same URL: `loadCore()` imports with a cache-busting query; in the browser the glue must be a static asset imported the same way, or the core runs in a Worker recreated on trap). ### 5.2 Serialisation contract (`tests/serialisation.test.ts`, `crates/core/tests`) - Byte equality with `JSON.stringify(JSON.parse(text), null, 2)` on `report-v3.demo.json`, `report-v2.full.json`, the 296 KB equine `document.json` and the 84 KB `report-migration-map.json`, plus a number corpus (`1523`, `1715.4285714285713`, `0.85`, `1e+21`, `1e-7`, `0.000001`, `-0` → `0`, `123456789012345680000`, `5e-324`, `1.7976931348623157e+308`). - Finding: `serde_json`'s default float parser is a documented fast path that can be one ULP off; the first run printed `1715.428571428571` and `123456789012345670000`. The `float_roundtrip` feature (enabled in `Cargo.toml`) fixes it; the module grew from 187 KB to 225 KB raw. - Optional fields absent, nullable fields `null`, unknown keys ignored, `unresolved: false` refused; the current `ReportZoneSchema` and `SheetRefSchema` (Zod 3, `@faunosteo/domain`) parse what the core writes. ### 5.3 musl static binary with libwebp (`crates/worker/Dockerfile`) Builds on `rust:1.99.0-alpine3.24` with `build-base`; `libwebp-sys` 0.14.4 compiles its vendored libwebp with `cc`; `WebPGetEncoderVersion()` reports **1.6.0** (logged by `run --check`, test `the_linked_libwebp_is_recent_enough`). The runtime image carries the one static binary. ### 5.4 seccomp allowlist, derived and proven (`crates/worker/tests/sandbox.rs`) - Derivation (`scripts/derive-seccomp.sh`, strace over png, jpeg, webp, a 4096 × 4096 JPEG and a 3000 × 3000 PNG, after the marker): exactly `read write mmap munmap mremap exit_group getrandom`. musl's mallocng used neither `brk` nor `mprotect`; no `futex` in a single-threaded decode. The allowlist is that set plus the abort path (`rt_sigaction`, `rt_sigprocmask`, `getpid`, `gettid`, `tkill`, `tgkill`, `exit`). - Proven on the release-profile musl binary with the test hooks, inside Docker's default seccomp profile: 13 tests green (`png_jpeg_and_webp_decode_through_the_full_sandbox`, `inputs_at_the_caps_decode_within_the_limits` (4096²), dimensions 32 px and 20 000² header, GIF and SVG refused, truncated PNG, non-empty environment refused, `--violate` → SIGSYS 31, `--flood` → output cut, `--alloc-gib 2` → SIGABRT 6 under `RLIMIT_AS`, `--spin` → parent deadline, `--spin` → SIGXCPU 24 at the CPU soft limit, libwebp ≥ 1.6.0). - Findings: with `RLIMIT_CPU` soft = hard the kernel sends SIGKILL (hard limit checked first), indistinguishable from the parent's deadline kill; the soft limit is now two seconds below the hard one. The 4096² decode exceeded 10 s of CPU in an unoptimised debug build: dependencies are optimised in every profile. ### 5.5 CSP with `'wasm-unsafe-eval'` (`docker/csp-proof/run.sh`) Served `packages/core-wasm/pkg` through `nginx:1.31-alpine` with `docker/nginx.conf` plus the exact `Content-Security-Policy` of `DEPLOY.md`, loaded by headless Chrome for Testing 156: | Header | Result | |---|---| | production (`script-src 'self'`) | `FAIL WebAssembly.instantiateStreaming(): Compiling or instantiating WebAssembly module violates the following Content Security policy directive because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"` | | `script-src 'self' 'wasm-unsafe-eval'` | `OK 0.1.0` (module instantiated, `core_version()` answered) | The keyword allows WebAssembly compilation only: an inline `