907 lines
57 KiB
Markdown
907 lines
57 KiB
Markdown
# Rust in the Faunosteo monorepo
|
||
|
||
Status: plan R0 (foundation, validated 2026-10-13), R1 (the Step 8 worker,
|
||
validated 2026-10-13) and R2 (the domain core, validated and merged 2026-10-14) and R3 (the anatomy core,
|
||
validated after the owner's LAN acceptance and merged 2026-10-17). Rule and
|
||
roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III
|
||
boundary rules, Part IV the worker, Part VI phases R0–R5, Annex B R0 scope,
|
||
Annex C owner amendments). R0 shipped the toolchain, the workspace skeleton,
|
||
the worker's sandboxed child, the browser module loader and seven
|
||
experimental proofs; R1 ships the worker's job loop and sweeper for the
|
||
avatar pipeline (`STORAGE.md` §3); R2 moves the application's domain rules
|
||
into `crates/core` and switches the application to them (§8).
|
||
|
||
## 1. Toolchain: native on the development machine, reproducible in Docker, never on the VPS
|
||
|
||
Three environments, three roles (owner decision of 2026-10-13, review Annex C
|
||
addendum). The development machine is a self-hosted Ubuntu server (native,
|
||
not WSL, not the VPS) with Docker rootless.
|
||
|
||
| Environment | Role | Rust |
|
||
|---|---|---|
|
||
| Ubuntu development machine, native | daily development (`cargo check / test / build / clippy / fmt`), the browser module build, every check before a merge (`pnpm check:all`) | user-level `rustup` in `~/.cargo` and `~/.rustup`, channel pinned by `rust-toolchain.toml` |
|
||
| Docker on that machine | the Supabase stack, the worker's sandbox tests and seccomp derivation, integration tests, the application and worker images, and the reproducible run of the same Rust scripts through the builder image | inside images only |
|
||
| Production VPS | runs images; never compiles | none |
|
||
|
||
### 1.1 Native toolchain (the primary path)
|
||
|
||
Everything lives in the user's home: no global package, no `sudo`. Checked on
|
||
2026-10-13 (Ubuntu 26.04.1, x86_64): `build-essential` (gcc 15, the C
|
||
compiler that builds the worker's vendored libwebp), `libc6-dev`,
|
||
`pkg-config`, `libssl-dev` and `strace` were already installed; no system
|
||
package is missing.
|
||
|
||
```bash
|
||
# once: rustup, the user-level installer (https://rustup.rs); ~/.bashrc and ~/.profile source ~/.cargo/env
|
||
rustup show # from the repository: installs 1.99.0 + rustfmt + clippy
|
||
rustup target add wasm32-unknown-unknown # browser build of crates/wasm
|
||
cargo install wasm-bindgen-cli --version 0.2.129 --locked # = the wasm-bindgen crate in Cargo.lock
|
||
cargo install cargo-deny --version 0.20.2 --locked
|
||
```
|
||
|
||
`rustup show` run inside the repository installs the channel of
|
||
`rust-toolchain.toml` (rustup auto-install), so `cargo` here is always
|
||
1.99.0 whatever the default toolchain of the machine. Non-interactive
|
||
shells (editor tasks, git hooks, agent shells) skip `~/.bashrc` and start
|
||
without `~/.cargo/bin` on PATH: the scripts source `scripts/rust-env.sh`,
|
||
which prepends it when `cargo` is not found.
|
||
|
||
| Piece | Native | Builder image | Pinned by |
|
||
|---|---|---|---|
|
||
| Rust 1.99.0, edition 2024, rustfmt, clippy | `rustup show` (auto-install) | `FROM rust:1.99.0-bookworm` + `rustup component add` | `rust-toolchain.toml` |
|
||
| `wasm32-unknown-unknown` | `rustup target add` | `RUN rustup target add` | same channel |
|
||
| `wasm-bindgen-cli` 0.2.129 | `cargo install --locked` | same | `wasm-bindgen = "=0.2.129"` in `Cargo.toml`; `scripts/wasm-build.sh` refuses to run when `Cargo.lock` and the CLI on PATH differ |
|
||
| `cargo-deny` 0.20.2 | `cargo install --locked` | same | `deny.toml` |
|
||
| worker builder (musl, libwebp) | not native: sandbox tests run in Docker only | `crates/worker/Dockerfile` (`FROM rust:1.99.0-alpine3.24`, `build-base`) | same channel |
|
||
|
||
Commands (root `package.json`; every Rust script is one file run natively
|
||
or inside the builder image):
|
||
|
||
```bash
|
||
pnpm rust:check # scripts/rust-check.sh, native: fmt --check, clippy -D warnings (all targets),
|
||
# cargo test (core, wasm, worker unit tests), ts-rs export, cargo deny licenses/bans/sources
|
||
pnpm wasm:build # scripts/wasm-build.sh, native: crates/wasm → packages/core-wasm/pkg (git-ignored), sizes printed
|
||
pnpm check:all # scripts/check-all.sh: the pre-merge gate (§4): rust:check, types drift, wasm:build,
|
||
# pnpm check, application image, worker:test, worker:image started read-only
|
||
pnpm rust:check:docker # the same rust-check.sh inside the builder image (reproducible run)
|
||
pnpm wasm:build:docker # the same wasm-build.sh inside the builder image
|
||
pnpm rust:builder # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold)
|
||
pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, 16 sandbox tests + seccomp derivation
|
||
pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static:nonroot)
|
||
bash docker/rust-run.sh cargo <anything> # any cargo command in the builder
|
||
cargo check | test | build | clippy | fmt # the inner loop, from the repository root
|
||
```
|
||
|
||
The native `target/` (git-ignored, `.dockerignore`d) and the builder's named
|
||
volumes `faunosteo_cargo_registry` / `faunosteo_rust_target` are two
|
||
separate caches; neither invalidates the other.
|
||
|
||
### 1.2 What stays in Docker, and why
|
||
|
||
- The worker's sandbox tests (`crates/worker/tests/sandbox.rs`) are gated by
|
||
the `test-hooks` feature: a native `cargo test` compiles that target empty
|
||
and runs the worker's unit tests only. The seccomp allowlist is derived by
|
||
`strace` on the **musl static binary that ships**, inside the Alpine
|
||
`test` stage, and glibc would need other syscalls (`brk`, `mprotect`,
|
||
`futex`): running the sandbox natively would either kill a legitimate
|
||
decode or prove nothing about the shipped binary. `pnpm worker:test` is
|
||
the only path, and the worker keeps running in its container.
|
||
- The Supabase stack, the application image, the worker image and the
|
||
integration tests on them: `pnpm db:start`, `docker build -t faunosteo .`,
|
||
`pnpm worker:image`.
|
||
- The builder image stays as the reproducible alternative (same compiler,
|
||
same tools, a clean environment) and as the reference a future runner
|
||
uses; it is not needed for a compile or a test on the development
|
||
machine.
|
||
|
||
Exposure change, stated for the record: a native build runs the build
|
||
scripts and proc-macros of the dependencies under the user account (the
|
||
builder container ran them with the repository mounted read-write, so the
|
||
difference is the rest of the home directory). Mitigations in place:
|
||
`--locked` everywhere, `deny.toml` `[sources]` limited to crates.io with
|
||
unknown registries and git sources denied, `cargo deny check licenses bans
|
||
sources` in every check.
|
||
|
||
## 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 + url (Zod's .url())
|
||
crates/wasm faunosteo-wasm: cdylib facade over core (wasm-bindgen)
|
||
crates/worker faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit)
|
||
packages/core-wasm runtime (lazy, poison, recovery), Node source, generated types (committed), N-1 reader, tests
|
||
```
|
||
|
||
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` and
|
||
`call_with_sheet(sheet, op, json)`: one operation name, one JSON text in,
|
||
the outcome envelope out (`{"ok":true,"value":…}` or
|
||
`{"ok":false,"kind":…,"detail":…[, "found":<number>]}`), never a panic on
|
||
content. The operations of R2 are listed in §8.2 (`crates/core/src/ops.rs`).
|
||
- `faunosteo_core::json`: `js_number(f64)` prints floats as ECMAScript
|
||
`Number::toString`; `to_js_pretty` / `to_js_compact` produce
|
||
`JSON.stringify(v, null, 2)` / `JSON.stringify(v)` byte for byte (proof
|
||
§5.2). Every facade output goes through them.
|
||
- `faunosteo_core::domain::js`: the JavaScript and Zod semantics the
|
||
contracts depend on (`JSON.parse` duplicate keys, a lone surrogate escape
|
||
refused as `lone_surrogate` (L1, §8.7), `.int()` as `JsInt`, UTF-16
|
||
lengths, the id / region / colour /
|
||
sha256 / base64 / uuid / URL patterns, optional fields absent and never
|
||
`null`, nullable fields required). Fields are declared in the Zod schema
|
||
order (D-R11). `cargo test -p faunosteo-core --features ts` writes the
|
||
TypeScript types to `packages/core-wasm/types` (committed; the drift gate
|
||
of `check:all` fails on any change).
|
||
- `packages/core-wasm`: `CoreRuntime` (browser-safe) and the Node source
|
||
(`@faunosteo/core-wasm/node`); a fresh instance is a new glue module record
|
||
(cache-busting import), never the trapped one (§8.3).
|
||
|
||
## 3. The worker (R0 sandboxed child, 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. R1 (Step 8) adds the keyed parent:
|
||
`run` polls `claim_avatar_jobs` through PostgREST every 2 s, downloads the
|
||
quarantine object, feeds it to a `decode` child, uploads the 512 × 512 WebP
|
||
at the final key, commits the row (`complete_avatar_job` with the lease
|
||
token), deletes the quarantine object, and sweeps (expired uploads, the
|
||
purge queue, quarantine leftovers) every 10 minutes. Modules: `config` (env,
|
||
secret newtype that no Debug output prints, JWT expiry), `log` (JSON lines,
|
||
field allowlist, child stderr escaped and cut at 200 bytes), `keys` (strict
|
||
four-segment key shapes validated before any URL), `backend` (trait, closed
|
||
`BackendError`), `http` (ureq 3 on rustls + ring with the bundled roots, 30 s
|
||
global / 5 s connect timeouts, no redirect, `P0001` bodies → closed
|
||
refusals, the Storage API's HTTP 400 + `statusCode` 404 → 404), `decoder`,
|
||
`job` (the STORAGE.md §3.4 mapping), `sweep` (§3.5), `watchdog` (per-stage
|
||
deadlines, exit 21 on overrun; `Broken` child → exit 20), `run`
|
||
(`WORKER_ONCE`, `--check`). Library choice recorded against the review's
|
||
Part V list: `ureq` instead of `tokio` + `reqwest`, hand-written JSON lines
|
||
instead of `tracing`, a 25-line base64url decoder instead of `base64`: the
|
||
loop is sequential, nothing needs an async runtime, and the keyed process
|
||
keeps a smaller dependency tree (34 → 84 crates, `aws-lc-rs` absent, no
|
||
cmake on Alpine). The decode child's traced syscall set did not change with
|
||
the parent's TLS code (§5.4 re-run at R1: the same seven). Image 11.6 MB
|
||
(8.7 MB at R0: ring + rustls). Tests: `crates/worker/tests/job_loop.rs` (11,
|
||
fake backend + fake decoder) and the module unit tests run natively; the
|
||
real-stack end-to-end runs through `pnpm e2e:avatar` (`STORAGE.md` §6).
|
||
|
||
The sandboxed child, unchanged from R0:
|
||
|
||
- `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–19, never 1, 101 or a signal number); every decode-time
|
||
error maps to a content code (`unsupported_type`, `decode_failed`,
|
||
`dimensions`, `resource_limit`), so no upload can produce a broken-environment
|
||
code.
|
||
- 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
|
||
(`exit_codes::is_content_rejection`, an explicit list), `Broken{code}` when
|
||
the child could not run properly (usage, non-empty environment, sandbox
|
||
failure, encode or output failure, internal: R1 alerts instead of blaming
|
||
the upload; no content can produce it), `Signalled{signal}`,
|
||
`OutputOverflow`, `Timeout`, `Failed`). The
|
||
parent **never decodes**: `webp_check::inspect` parses the RIFF container
|
||
only (chunk allowlist `VP8X`, `VP8 `, `VP8L`, `ALPH`; the encoder's structure
|
||
enforced: optional `VP8X` first, optional `ALPH` only in an extended file,
|
||
exactly one frame; 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, the
|
||
JWT expiry of the service key); exit 0 when startable or when no worker
|
||
variable is set at all, 2 on a partial configuration. `run` starts the loop
|
||
(STORAGE.md §3.2 for the variables).
|
||
- `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. Checks before a merge, and the workflow files (prepared, no CI active)
|
||
|
||
No CI/CD runs on the forge today (2026-10-13): no runner, no secret, no
|
||
registry. The YAML files under `.gitea/workflows/` are kept as prepared
|
||
material for that separate decision; a green workflow is never claimed
|
||
until one has actually run on the forge. Until then the gate is local:
|
||
|
||
```bash
|
||
pnpm check:all # scripts/check-all.sh, stops at the first failure
|
||
```
|
||
|
||
Stages, in order: `scripts/rust-check.sh` (native), the ts-rs types drift
|
||
(`git status --porcelain --untracked-files=all -- packages/core-wasm/types`
|
||
must be empty: a modified or a new type file both fail, whatever the git
|
||
configuration), `cargo deny check advisories`
|
||
(warn-only: out of the blocking path by design, review VIII.3, but printed
|
||
here because no nightly job runs yet; needs the network), `scripts/wasm-build.sh`
|
||
(native), `pnpm check` (typecheck, tests including the `core-wasm` proofs on
|
||
the module just built and the pgTAP suite on PGlite, lint, build), the
|
||
application image, `pnpm worker:test` (sandbox tests and seccomp derivation
|
||
on the musl binary), `pnpm worker:image` started once with `--read-only
|
||
--cap-drop ALL`. The local Supabase stack is not required; `pnpm db:test`
|
||
is the real-stack complement after a change under `supabase/`.
|
||
|
||
Workflow files, each mapping onto those stages so a future runner calls the
|
||
same scripts:
|
||
|
||
- `ci.yml` (push on main/develop, pull requests): job `rust` (builder image,
|
||
`scripts/rust-check.sh`, types drift, `scripts/wasm-build.sh`), job `check`
|
||
(module built the same way, then the Node pipeline), job `docker`
|
||
(application image, worker `test` stage, worker runtime started read-only),
|
||
job `supabase` (real stack, pgTAP, generated types diff).
|
||
- `rust-advisories.yml`: nightly and manual `cargo deny check advisories`,
|
||
out of the blocking path on purpose.
|
||
- `release-images.yml`: manual only; the dispatch input is a typed choice
|
||
re-validated through an environment variable; the RustSec and npm
|
||
(`pnpm audit --prod`) advisories gates run first in a job without
|
||
secrets; a named ephemeral `buildx` builder (`--builder`, no silent
|
||
fallback) with its own cache builds the images; the registry token
|
||
reaches the login step only, into a per-job `DOCKER_CONFIG` under
|
||
`RUNNER_TEMP` created before any step and removed by a literal path;
|
||
digests read from the build metadata; `actions/checkout` pinned to a
|
||
commit. The `if: github.ref` line is not a boundary (push access and the
|
||
token's scope are; a dedicated release runner label is the Step 27
|
||
operation). It would push `faunosteo_app:<sha>` and
|
||
`faunosteo_worker:<sha>` and print their digests. Deploys nothing
|
||
(DEPLOY.md "Image deploy by digest").
|
||
|
||
Target of the future CI/CD step (planned, not yet built; recorded so the
|
||
scripts stay compatible): tests on every push and pull request, Rust and
|
||
TypeScript checks, PostgreSQL/RLS tests, Docker builds, security checks,
|
||
branch verification before a merge, image publication only in an
|
||
explicitly authorised workflow.
|
||
|
||
Not measured: the forge runner's cache behaviour, cold build times and the
|
||
workflow syntax (job-level `env`, `GITHUB_ENV` path) have never run. 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: 16 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; negative
|
||
proofs of the argument filters: `--signal-parent` (`tkill` to the parent)
|
||
and `--mmap-exec` → SIGSYS; an `iCCP` bomb of 300 MB inflated → a content
|
||
rejection, never a broken-environment outcome).
|
||
- 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 `<script>`
|
||
variant stayed blocked under both headers. nginx serves `.wasm` as
|
||
`application/wasm` out of the box.
|
||
|
||
### 5.6 Served size and instantiate time (`tests/size.test.ts`)
|
||
|
||
`faunosteo_wasm_bg.wasm`: 224 713 bytes raw, 85 396 bytes gzip-9 (with
|
||
`float_roundtrip`; 186 805 / 72 917 without), instantiate 2.7 ms in Node 24.
|
||
The D-R13 budget (600 KB compressed) is asserted by the test from R0 on.
|
||
|
||
### 5.7 Runner caches and build times
|
||
|
||
Not measurable from this host (no forge runner here). Recorded instead:
|
||
builder image cold build about 6 minutes; worker test stage cold about 2
|
||
minutes, warm under 30 s with the BuildKit cache mounts; the wasm build
|
||
under 10 s warm. The first run on the forge records its own numbers here.
|
||
|
||
### 5.8 Native toolchain run (2026-10-13, Ubuntu 26.04.1, rustup 1.29.1, 16 cores)
|
||
|
||
Same proofs, native toolchain (`rustc 1.99.0 (b940084d7 2026-09-28)`,
|
||
`cargo 1.99.0`, `clippy 0.1.99`, `rustfmt 1.10.0-stable`, `wasm-bindgen
|
||
0.2.129`, `cargo-deny 0.20.2`), compared with the builder image runs above:
|
||
|
||
| Measure | Native | Builder image (R0) |
|
||
|---|---|---|
|
||
| cold `cargo build --workspace --all-targets` (libwebp compiled by gcc 15) | 31.5 s | not timed at R0 |
|
||
| cold wasm release build | 4.3 s | under 10 s warm |
|
||
| `scripts/rust-check.sh` warm (fmt, clippy, tests, ts export, deny) | 32 s | 2.2 s warm volumes (same script, same results) |
|
||
| cargo tests | core 10 + 2, worker unit 9, core with `ts` 14 + 2, all green | identical counts |
|
||
| committed ts-rs types | unchanged after the export | unchanged |
|
||
| `faunosteo_wasm_bg.wasm` raw | 224 777 B | 224 713 B |
|
||
| gzip -9 | 84 924 B (`gzip`), 85 390 B (the vitest measure) | 84 927 B / 85 396 B |
|
||
| sha256 | `2d559a6b…bb3a` | `451d49c1…a752` |
|
||
| core-wasm proofs | 14 passed, instantiate 3.9 ms | 14 passed, 2.7 ms |
|
||
|
||
The 64-byte difference and the distinct hashes come from the source paths
|
||
embedded in the panic locations (`/home/<user>/Documents/faunosteo/…`
|
||
natively, `/w/…` in the builder): the module is not bit-reproducible across
|
||
build roots without `--remap-path-prefix`, which R0 does not set. The
|
||
builder image is the reference when two builds must match byte for byte.
|
||
`cargo deny` prints the same warnings in both environments
|
||
(`license-not-encountered` for six allowed licences, duplicate `miniz_oxide`
|
||
and `syn`): policy `warn`, not failures.
|
||
|
||
## 6. Reproduction
|
||
|
||
```bash
|
||
pnpm rust:check # §2, §5.2 (cargo side), native
|
||
pnpm wasm:build && pnpm --filter @faunosteo/core-wasm test:run # §5.1, §5.2, §5.6, native module
|
||
pnpm rust:builder && pnpm rust:check:docker && pnpm wasm:build:docker # the same, reproducible in the builder
|
||
pnpm worker:test # §5.3, §5.4 (tests + derivation in the build log)
|
||
pnpm worker:image && docker run --rm --read-only --cap-drop ALL faunosteo_worker:dev # §3
|
||
CHROME=<chromium binary> bash docker/csp-proof/run.sh # §5.5 (playwright-core on NODE_PATH)
|
||
CHROME=<chromium> PLAYWRIGHT_NODE_MODULES=<dir> bash docker/csp-proof/app-image.sh # §8.5, the R2 image
|
||
pnpm check:all # everything above but the CSP proofs, in one command
|
||
```
|
||
|
||
## 7. What stays hypothetical after R0
|
||
|
||
- Follow-ups from the R0 security audit, owned by R1 unless stated: base
|
||
images pinned by digest in the three Dockerfiles (today by tag, as the
|
||
existing `Dockerfile`); a verification decode of the child's output in a
|
||
second sandboxed child (the RIFF check validates the container, not the
|
||
bitstream); the shared BuildKit cache mounts of the CI builds (the
|
||
release workflow already uses its own builder); `actions/*@v4` tags in
|
||
`ci.yml` (pre-existing practice) to pin by commit at Step 27.
|
||
- The browser-side fresh-instance mechanism is built at R2 (§8.3): the glue
|
||
is a Vite asset imported with a query per instance, one spare record
|
||
imported in advance.
|
||
- HTTPS from the worker: R1 links `ureq` with rustls and the bundled
|
||
`webpki-roots` (distroless has no CA bundle; none is needed), but every
|
||
run so far targets the local stack over plain HTTP on the Docker network;
|
||
the first managed (HTTPS) target proves the roots.
|
||
- The forge runner's cache and timings (§5.7), and the workflow files
|
||
themselves: no runner exists, none of the three workflows has ever run
|
||
(§4).
|
||
- The allowlist is x86_64; an aarch64 host would need its own derivation
|
||
(`target_arch` selects the seccomp architecture, the syscall numbers come
|
||
from `libc`).
|
||
|
||
## 8. R2: the domain core in Rust, used by the application (2026-10-14)
|
||
|
||
Plan and contract: `.claude/tasks/plans/2026-10-13-rust-r2-domain-core.md`
|
||
(revision 2 after three plan challenges). The application's domain rules run
|
||
in `crates/core`, reached through `crates/wasm` and `packages/core-wasm`;
|
||
React, the DOM, the forms, Zustand and supabase-js stay TypeScript.
|
||
|
||
### 8.1 What runs in Rust, and who calls it
|
||
|
||
| Former TypeScript | Rust (`crates/core/src`) | Application consumer |
|
||
|---|---|---|
|
||
| sheet document schema (Zod, strict) | `domain/sheet/schema.rs` | `SheetHandle` load (`useSheet`), snapshot gate, publish check |
|
||
| `validateSheetDocument` (21 rules), `isPublishable`, `createEmptySheetDocument` | `domain/sheet/{validate,check,create}.rs` | `sheet.check` → `publishSheetVersion` (packages/supabase), snapshot integrity |
|
||
| `buildSheetIndex` (closures over Maps) | `domain/sheet/{index,index_data}.rs`, `SheetHandle` | `useSheet` → `SheetIndex` (precomputed tables, no call in a render) |
|
||
| report v3 / v2 / identity / migration map (Zod) | `domain/report/{v3,v2,identity,migration_map}.rs` | every op that takes or returns a report |
|
||
| `migrateReportV2ToV3`, `readReportDocument` | `domain/report/read.rs` | draft restore, import |
|
||
| `rebaseReportOnSheet` (gated, D-R12) | `domain/report/rebase.rs` | draft restore, import |
|
||
| snapshot / branding / labels / envelope schemas, `buildSheetSnapshot`, `assertSnapshot`, `readArchiveDocument` (gated, D-R12) | `domain/archive/*` | export (`archive.snapshot`), import (`archive.import`), draft restore (archive kept beside the draft) |
|
||
| `services/zoneInteraction.ts` (click decision, 7 reducers, `collectVertebrae`, `syncVertebrae`) | `domain/editor/zone.rs` | `EditorRoute` click chain, `ObservationPickers`, zone chips |
|
||
| `FindingsTreePicker.toggleLeaf` (Finding builder) | `domain/editor/finding.rs` | `ObservationCard` → findings picker |
|
||
| `VertebraPicker` toggle / all / none | `domain/editor/vertebra.rs` | `VertebraPicker` tap handlers |
|
||
| store `newReport`, `emptyObservation`, add / remove / move | `domain/editor/report_ops.rs` | `reportStore` actions (answer `{ ok }`) |
|
||
| `persistence` draft / archive parsing | `domain/session.rs` (`restore_draft`) | `reportStore.restoreDraft` (quarantine on content kinds) |
|
||
| engine `readReportArchive` (layered part) | `domain/session.rs` (`import_archive`) | `HomeRoute` import after the engine's byte scan |
|
||
|
||
### 8.2 Facade operations (`crates/core/src/ops.rs`, `facade.rs`)
|
||
|
||
Free (`call`): `sheet.check`, `report.new`, `report.add_observation`,
|
||
`report.remove_observation`, `report.move_observation`, `vertebra.select`;
|
||
R0 proofs kept: `core_version`, `pretty_json`, `sheet_ref`, `report_zone`.
|
||
On the session's sheet (`SheetHandle.call`): `index_data`, `zone.click`,
|
||
`zone.add_sides`, `zone.remove_at`, `vertebra.initial`, `vertebra.sync`,
|
||
`finding.toggle`, `draft.restore`, `archive.import`, `archive.snapshot`.
|
||
Closed failure kinds: `invalid_json`, `invalid_shape`, `unknown_op`,
|
||
`internal`, `invalid_sheet` (handle), `invalid` / `unsupported_version` /
|
||
`rebase_failed` (restore), `incompatible_version` (with `found`) /
|
||
`no_attachment` / `invalid` (import), `unknown_annotation`, `unknown_zone`,
|
||
`unknown_node`, `invalid_index`, `invalid_count` (editor); the runtime adds
|
||
`core_unavailable`. Input contracts are exported as TypeScript types.
|
||
|
||
### 8.3 Runtime in the browser (`packages/core-wasm/src/runtime.ts`, `apps/app/src/core/`)
|
||
|
||
- Lazy: the glue (10 KB) and the module are Vite assets (`?url`), never in
|
||
a route chunk; nothing is fetched before `ready()`. Callers: the editor
|
||
(`useSheet`), the new-report submit, the PDF import. `/login`, `/app/*`,
|
||
Mon compte and Home never request it (proven, §8.5); Home and `/new` read
|
||
the sheet availability from the bundle alone.
|
||
- Synchronous calls once ready. A `WebAssembly.RuntimeError` poisons the
|
||
instance: the call answers `internal`, the instance is dropped, a fresh one
|
||
is created from the compiled module kept in memory and a glue record
|
||
imported in advance (no network needed), at most 3 times per page; calls
|
||
made meanwhile answer `core_unavailable`. Sheet handles carry the instance
|
||
generation and are rebuilt from the retained payload, never called on a
|
||
dropped instance. A recovery that fails below the cap (network lost, spare
|
||
record missing) is not final: the next call or `ready()` restarts the
|
||
runtime, reusing the compiled module; a restart is not a recovery and does
|
||
not touch the counter. A failed first load is restarted by `retry()` only.
|
||
`subscribe(listener)` reports status changes after a microtask (a throwing
|
||
listener changes nothing); the pages follow `stopped` through it.
|
||
- A load failure (CSP, network, old browser) gives `core_unavailable`; the
|
||
editor and the new-report page show the notice with "Réessayer" (the retry
|
||
clears the runtime, `useSheet` and provider caches), never redirect, never
|
||
read or write the draft. Once the engine stopped, the notice is the stopped
|
||
one (§9.4 item 7), without a retry.
|
||
- Editor, storage full while the engine runs: the `editor.save_failed` banner
|
||
gains the engine-free "Télécharger une copie" button, and a `beforeunload`
|
||
guard (`app/useUnsavedGuard.ts`, called once in `App`, on every page) asks
|
||
before a reload, a close or a full-page redirect while the report is only
|
||
in memory.
|
||
- Two builds: `pkg/` ships (no trap export, checked by `scripts/wasm-build.sh`
|
||
and a test), `pkg-proofs/` carries the trap exports for the tests. Both
|
||
carry `BUILD_STAMP` (hash of the Rust sources); the vitest global setup of
|
||
`core-wasm`, `app` and `supabase` refuses to run on a missing or stale
|
||
module (`pnpm wasm:build` first).
|
||
|
||
### 8.4 TypeScript deleted, kept, frozen (census)
|
||
|
||
- Deleted at R2: `apps/app/src/services/zoneInteraction.ts` and its suite
|
||
(13 cases ported to `crates/core/tests/editor_rules.rs`), the Finding
|
||
builder of `FindingsTreePicker`, the selection rules of `VertebraPicker`,
|
||
the store's report construction and list rules, the Zod parsing in
|
||
`persistence.ts` and `sheets/provider.ts`, the domain re-exports of
|
||
`services/sheetIndex.ts`, `hydrateReport`, the publish gate's
|
||
`assertPublishable` call.
|
||
- Kept TypeScript, each with its constraint (review II.2 class C): display
|
||
helpers over core data (`zoneLabel`, `describeZone`, `zoneTrees`,
|
||
`unresolvedFindings`, the findings picker's `matches` / `isLeafSelected` /
|
||
`countSelectedUnder`, the vertebra grid extent and chip state, import
|
||
message lines, `isIdentityComplete`, `pickLabel` = `pickLocaleLabel`);
|
||
form glue (D-R7: identity, texts, comment, severity and free-findings
|
||
assignments, `FreeTextFindingInput` trimming, the practitioner prefill
|
||
schema of `practitionerCache.ts`); storage adapters (`persistence.ts`,
|
||
quarantine writes); `isObservable` (a type guard); the `SheetIndex` class
|
||
(reads precomputed tables only); the runtime and its sources (Vite asset
|
||
URLs, dynamic import).
|
||
- Frozen TypeScript, still used, never extended: `packages/domain` (PDF
|
||
engine and `apps/app/scripts/compare-reports.ts` until R4, pipeline until
|
||
R5), `packages/pdf` (byte scan and writer, R4), `packages/anatomy/render`
|
||
(canvas and engine, R3). The `report:compare` CLI reads the sheet with
|
||
the frozen domain (`apps/app/scripts/compare/sheet.ts`).
|
||
- Census: `grep -rn "@faunosteo/domain" apps/app/src` returns nothing,
|
||
enforced by ESLint (`no-restricted-imports` on `apps/app/src`).
|
||
|
||
### 8.5 Proofs and tests (2026-10-14)
|
||
|
||
- Cargo: 135 core tests (contracts byte-equal to the Zod output on the
|
||
curated and legacy sheets, the demo report and the three frozen archive
|
||
envelopes; the ported domain suites; 49 editor cases, 84 report and
|
||
archive cases and 765 Zod verdicts frozen from the TypeScript; 26
|
||
conformance fixtures; the 612 legacy leaves), 32 wasm + worker unit tests.
|
||
- Node: 906 tests (`app` 313 on the real core, `core-wasm` 25 incl. the
|
||
runtime, trap, size and measurement tests, `supabase` 39 incl. the publish
|
||
gate on the real core, `domain` 262 incl. the oracle generators, `pdf`
|
||
137, `anatomy` 130); the 39 step6 goldens and the seed golden unchanged.
|
||
- SQL: `supabase/tests/011_sheet_conformance.sql` generated from the
|
||
fixtures (cargo drift test), PGlite 12/12 files, real stack 446/446.
|
||
- N-1: the Zod schemas of develop 1a7ee7d (`packages/core-wasm/tests/n-1`)
|
||
parse every draft and archive the core-fed application writes; the three
|
||
frozen envelopes are deep-equal to the R2 exports.
|
||
- CSP on the real image (`docker/csp-proof/app-image.sh`, Chrome for Testing
|
||
156, DEPLOY.md header): with `'wasm-unsafe-eval'` a report is created and a
|
||
zone click is applied by the core with no script or wasm violation; without
|
||
it the browser refuses the module (`script-src wasm-eval`), the editor
|
||
shows the notice, stays on `/editor` and leaves the draft byte-identical;
|
||
`/login`, `/app/account` and `/` request neither the glue nor the module
|
||
(15/15). Recovery after a forced trap checked in the browser on the dev
|
||
server and the production build; real traps on the proofs build in Node.
|
||
- `pnpm check:all`: green in 2 min 17 s.
|
||
|
||
### 8.6 Measurements (development machine, Node 24, Chrome 156)
|
||
|
||
| Measure | Value |
|
||
|---|---|
|
||
| shipped module | 1,044,559 B raw (native), **340,154 B gzip -9** (budget 600 KB); before the by-reference deserialisation of the security follow-up: 1,180,153 B raw / 372,275 B served by the image; after L1 (no rewrite pass, §8.7): 1,040,784 B raw / 339,933 B gzip -9 |
|
||
| glue | 10,171 B |
|
||
| load (compile + instantiate) | 6 to 8 ms |
|
||
| sheet handle + index data (bundle 0.5 MB) | 22 to 27 ms (TypeScript parse + index on the same input: 12 to 15 ms) |
|
||
| `zone.click` | 0.03 ms |
|
||
| `draft.restore` (demo report) | 0.26 ms |
|
||
| `archive.import` (demo envelope, 184 KiB) | 2.4 ms (TypeScript layered read, without rebase: 1.0 to 1.1 ms) |
|
||
| `archive.snapshot` | 0.4 to 0.5 ms |
|
||
| linear memory after the editor path | 4.1 MiB |
|
||
| app image | 104 MB (wasm stage: the Rust toolchain stays in the builder) |
|
||
|
||
Pages without the core load nothing more than before R2; the sheet pages
|
||
fetch about 351 KB more (glue + gzip module) once per session. JSON inputs
|
||
are deserialised by reference (`T::deserialize(&Value)`): the imported
|
||
attachment is never copied as a whole value (its strings are copied once
|
||
into the typed contract), and one deserialiser instead of two keeps the
|
||
module smaller. Operation inputs (`parse_input`) keep the parsed value alive
|
||
while their strings are copied out: a transient, linear peak on inputs the
|
||
application itself builds.
|
||
|
||
### 8.7 Behaviour differences (declared)
|
||
|
||
1. **L1** (owner decision 2026-10-14, BDR-051): a JSON text that escapes a
|
||
lone UTF-16 surrogate is refused whole with the closed kind
|
||
`lone_surrogate`, never altered (TypeScript kept the surrogate; a Rust
|
||
string cannot hold it, and the U+FFFD replacement delivered first was
|
||
refused). serde_json rejects the escape like any other error and
|
||
`js::parse_json` classifies the failure with a strict escape scan, run on
|
||
failures only. A draft goes to `osteo:quarantine:draft` verbatim with the
|
||
existing quarantine notice; an archive kept beside a draft goes to
|
||
`osteo:quarantine:archive`; an import is refused with
|
||
`home.import.error_lone_surrogate` and the file is not modified; an
|
||
editor action on a report holding one (only a pasted malformed text can
|
||
bring it) is refused with `core.action_failed` and the report is left as
|
||
it was; the publish gate reads it as `invalid_shape`. Keeping such a
|
||
string byte for byte would need a JSON reader of our own and a lossless
|
||
string type across the contracts (rejected for R2, the refusal leaves
|
||
that door open: nothing is lost). Invariant of the boundary: callers pass
|
||
`JSON.stringify` output only, which escapes a lone surrogate as `\uXXXX`;
|
||
a raw JavaScript string handed to a wasm-bindgen `&str` parameter would be
|
||
re-encoded with U+FFFD before the core sees it. The `pretty_json` proof
|
||
op reads with serde_json directly and refuses such text as `invalid_json`.
|
||
2. Drafts and the attachment's report are written in contract order instead
|
||
of insertion order (D-R11); values unchanged, the N-1 reader parses them.
|
||
3. An unreadable draft or archive is set aside under `osteo:quarantine:*`
|
||
with the `editor.draft_quarantined` alert, instead of being dropped
|
||
silently; a draft rebased with unresolved items keeps its raw text under
|
||
`osteo:quarantine:draft-pre-rebase`. An unreadable draft goes there with
|
||
the archive kept beside it, both or neither. A slot already holding
|
||
another text is never replaced. Owner rule of 2026-10-14 (maintenance B):
|
||
no session text is removed or overwritten implicitly when a save or a
|
||
set-aside fails. Such a text stays in place and is held: nothing is
|
||
opened over it (`RestoreResult` `held`: an unreadable draft, its
|
||
companion archive, an unreadable archive, or the original of a draft to
|
||
rebase), and the editor shows the resolution panel (download an exact
|
||
copy, delete permanently or open the adapted version after a
|
||
confirmation, retry). A new report or an import refuses to start
|
||
(`reason: 'held'`, alert, then the panel) while such a text is held, and
|
||
first reads through the core any draft this page never opened: an
|
||
unreadable one is set aside before the new session replaces it, a
|
||
readable one is replaced as before. R3 final checks (2026-10-17): a draft
|
||
the engine traps on (`draft.restore` answering `internal`, an out-of-memory
|
||
trap on a very large draft) is held too, as the `engine_failure` row with
|
||
its archive as `companion` (`session.held.notice_engine`), kept as is; the
|
||
store remembers the (draft, archive) pair that trapped and answers held
|
||
without calling the core again, from the editor, New report and Import
|
||
alike (`ActionResult.engine`, alert `session.held_blocked_engine`), until
|
||
the panel's "Réessayer" (`retryTrapped`) or a confirmed discard; other core
|
||
failures keep their behaviour (`core_unavailable`: the reload screen). New
|
||
report and the Home file pick ask first (`ReplaceSessionDialog`: cancel,
|
||
open the bilan in progress, replace) whenever a report is in memory or a
|
||
draft sits in the slot. The draft mirror is written only
|
||
when the report changes (an unrelated store change never removes it);
|
||
a refused write keeps the previous text and shows the `editor.save_failed`
|
||
banner until a write succeeds; a refused archive write at a new session
|
||
removes the replaced session's archive rather than leave it paired with
|
||
the new draft, and shows the same banner (the tab's copy lacks it). The
|
||
rescue download and the PDF export keep their object URL alive 30 s
|
||
(WebKit cancels a download whose URL is revoked at once; both go through
|
||
`downloadBlob`, `apps/app/src/lib/download.ts`).
|
||
4. A core that cannot load leaves the editor on the degraded notice
|
||
(before R2 a failed sheet chunk left it on "loading").
|
||
5. Home and `/new` no longer load the sheet into memory on mount.
|
||
6. Inputs the interface never produced get typed errors where the
|
||
TypeScript would throw or corrupt a list (`invalid_index` on a move past
|
||
the end, `invalid_count` beyond 65,535 vertebrae, `unknown_*`).
|
||
7. A click on an existing spine zone no longer writes an identical
|
||
observation back (the value is the same).
|
||
8. The publish gate throws `SheetPublishError` with closed kinds
|
||
(`invalid_shape`, `not_publishable` with the same message as before,
|
||
`validator_unavailable`), never a raw ZodError.
|
||
9. Superseded by item 3 (maintenance B, 2026-10-14): an unreadable draft
|
||
that cannot be set aside shows the resolution panel, no longer the
|
||
engine notice.
|
||
|
||
### 8.8 Residual risks
|
||
|
||
- The import reads up to the 16 MiB attachment cap inside the long-lived
|
||
instance (linear memory never shrinks) until R4 moves the reader into a
|
||
terminated Web Worker.
|
||
- No React error boundary: every core entry point catches, but an uncaught
|
||
error elsewhere still blanks the page (unchanged since before R2).
|
||
- The CSP proof runs Chromium only (no Firefox or WebKit build on this
|
||
machine): the owner's manual run of the image on other browsers and the
|
||
phone covers Safari and Firefox.
|
||
- The module grows with each phase (340 KB of the 600 KB budget at R2; the
|
||
`url` crate's IDNA tables are part of it): R3/R4 must keep measuring.
|
||
- The quarantine slots (`osteo:quarantine:*`) keep verbatim copies of drafts
|
||
(practitioner, owner and animal data) until the tab closes, the same
|
||
exposure as `osteo:draft` itself (sessionStorage, tab and origin scoped);
|
||
nothing clears them on a new report, by design (they exist to survive it).
|
||
They have no interface yet: the practitioner cannot see or download a
|
||
set-aside text, and it disappears when the tab closes (owner decision
|
||
2026-10-14: follow-up, not part of the maintenance fix).
|
||
- "New report" from Home replaces the tab's readable draft without asking,
|
||
as before R2 (a single draft per tab, the PDF is the saved copy); the
|
||
maintenance fix only guards texts that are unreadable or held.
|
||
- Base images by tag, the new `rust:1.99.0-bookworm` included (digest pinning
|
||
is the Step 27 follow-up of R0).
|
||
- The documented CSP refuses the footer's external credit logo
|
||
(`img-src`), an older matter seen by the proof.
|
||
|
||
## 9. R3: the anatomy core in Rust, drawn by the editor canvas (2026-10-15)
|
||
|
||
Plan and contract: `.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md`
|
||
(revision 2 after three plan challenges, 32 findings folded). Status: validated by
|
||
the owner's LAN acceptance (functional and graphical) and merged into `develop` on 2026-10-17. Residual risks are
|
||
tracked in the project's blocker registry (BLK-011, BLK-012).
|
||
|
||
### 9.1 What runs in Rust, and who calls it
|
||
|
||
| Former TypeScript | Rust (`crates/core/src/anatomy`) | Consumer |
|
||
|---|---|---|
|
||
| `apps/app/src/anatomy/drawing.ts` denylist + `DOMParser` parse of the asset (deleted) | `svg/{prescan,tree,sanitize,refs,number,serialize}.rs`, `svg::read_svg` | the sheet load (`LoadedSheet`, each drawing read once) |
|
||
| `packages/anatomy/src/render/layer.ts` (`renderAnnotationLayer`, `viewBoxOf`) | `layer.rs` | `view.canvas`; the highlight |
|
||
| the canvas composition of `drawing.ts` (fresh root, viewBox rules, layer last) | `compose.rs` `compose_canvas` | `view.canvas` → `SheetIndex.canvasSvg` → `AnatomyCanvas` |
|
||
| `packages/anatomy/src/render/compose.ts` (`composeViewSvg`, `highlightLayer`, halo) | `compose.rs` `compose_highlight` | none yet: proven against the engine (O3), wired at R4 in R4's snapshot-based call |
|
||
| `packages/pdf/src/svg/sanitize.ts` allowlist and value rules | `svg/sanitize.rs` (same lists, same rules, declared additions 9.4) | the canvas now; the engine keeps its TypeScript copy until R4 |
|
||
|
||
One facade operation on the sheet handle: `view.canvas { viewId } → { svg }`,
|
||
failures `unknown_view`, `no_asset`, `svg_rejected` (reason in `detail`:
|
||
`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`,
|
||
`too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, or
|
||
`removed <names>` when the allowlist would take something out of a product
|
||
drawing), `invalid_character`. The result is constant for a loaded sheet:
|
||
`SheetIndex` memoises it per view; `AnatomyCanvas` parses it with `DOMParser`,
|
||
imports it and restyles `data-state` in place as before.
|
||
|
||
### 9.2 The SVG reader (`read_svg`)
|
||
|
||
1. Bounds before any parser (`prescan.rs`, a markup state machine: comments,
|
||
CDATA, PIs and quoted values skipped by the grammar, each closer searched
|
||
after its whole opener so `<!-->` cannot hide markup, no regex): 2 MiB, a
|
||
leading BOM refused, `<!DOCTYPE`/`<!ENTITY` anywhere, depth 64, 20,000
|
||
elements, 256 attributes per element and 100,000 in all, 16 namespace
|
||
declarations, 100,000 raw `<` and 200,000 raw `=`. Reason: roxmltree 0.21.1
|
||
builds its tree recursively (measured: a 1 MiB stack overflows between
|
||
1,000 and 3,000 nesting levels; the iterative fix is unreleased), and it
|
||
pre-allocates on the raw `<`/`=` counts, checks duplicate attributes
|
||
quadratically and copies inherited namespaces per declaring element.
|
||
2. roxmltree 0.21.1 (DTD refused, node limit 200,000 as a backstop) into the
|
||
core's own tree, names as written (the allowlist matches qualified names
|
||
like the engine).
|
||
3. The allowlist (`sanitize.rs`): the engine's 28 elements, 74 attributes, 27
|
||
presentation attributes and value rules (no backslash, every `url(` local,
|
||
`href` to `#id` only, `style` without forbidden tokens or functions, the
|
||
`stdDeviation` clamp with JavaScript `Number()` reproduced by hand), and the
|
||
`<use>` count cap 256.
|
||
4. The reference graph (`refs.rs`): tree edges plus every `href`/`xlink:href`
|
||
and `url(#id)` to the first element of that id; a cycle is refused, and so
|
||
is an expanded size over 50,000 elements (each reference adds its target's
|
||
expanded subtree, saturating, iterative, early exit).
|
||
5. The serialiser (`serialize.rs`): XML 1.0, `& < > "` and `\t \n \r` as
|
||
references in attributes, `& < >` and `\r` in text; a re-read gives the
|
||
same tree. A composed view over 4 MiB is refused.
|
||
|
||
### 9.3 Proofs and tests (oracles frozen with the TypeScript first)
|
||
|
||
- O1 (`apps/app/tests/fixtures/goldens/r3/canvas.*.json`, 47c5f49): the canvas
|
||
tree of each view and the layer of 14 state sets per view (the three
|
||
reference reports). Green on the Rust composition in cargo
|
||
(`tests/anatomy_compose.rs`), in the app suite on the mounted canvas
|
||
(`canvas.trees.test.tsx`) and in Chromium 156 on the live page
|
||
(`scripts/visual-canvas.mjs dom`): equal for both views.
|
||
- O2 (`oracles/r3/layer.json`): 8 layer trees with attribute order (draft +
|
||
an edge document: twin radius floor, `1e+21`, path geometry, circle trigger
|
||
without a name, colour fallback, laterality): exact, order included.
|
||
- O3 (`oracles/r3/highlight.json`): 36 highlighted compositions (every
|
||
observation and view of the three reports, an existing nested `<defs>`, a
|
||
detail view with its own asset and no viewBox): tree-equal.
|
||
- O4/O5 (`oracles/r3/sanitiser.json`): 42 hostile files
|
||
(`tests/fixtures/svg/hostile`) and 10 generated cases: equal to the
|
||
TypeScript verdict or a declared one (9.4); the 4 product SVGs (horse
|
||
drawing, partner logo, 2 public logos) untouched, tree-equal. Mutation
|
||
checks run on the oracle tests (a cap, the namespace rule, the twin floor,
|
||
the halo placement): each mutant failed the suite.
|
||
- Security audit pass 1: PASS with one MEDIUM in the prescan (a closer
|
||
searched from inside its own opener: `<!-->` let crafted markup hide 5,000
|
||
nesting levels or 3,000 attributes, then roxmltree overflowed the stack),
|
||
fixed with regression cases in cargo and through the shipped wasm; two LOW
|
||
(Unicode-spaced `href`, root painting attributes) fixed the same way. Pass 2
|
||
on the fix: PASS (about 4 million differential documents, prescan against
|
||
roxmltree: no undercount, no cap breach, no stack overflow on a 64 KiB stack;
|
||
the old desync and its variants answer `too_deep` on the shipped module); its
|
||
LOW (the same Unicode-space tolerance inside `url(`) fixed.
|
||
- Shipped wasm (`packages/core-wasm/tests/anatomy.test.ts`): the corpus plus
|
||
floods (99,000 nesting levels, 20,001 nodes, 150,000 `<` in a comment, 257
|
||
attributes, 2 MiB + 1, a 12 × 20 `<use>` chain, 1.9 MiB of `>`), each in a
|
||
fresh instance (50 cases): a closed outcome, no trap, slowest 24 to 37 ms over runs, largest linear
|
||
memory growth 10.1 MiB.
|
||
- Runtime: the `SheetHandle` constructor's closed refusal (`<kind>: <detail>`
|
||
from a plain `Error`) is `invalid_sheet`; any other throw (RangeError,
|
||
InternalError, a trap) poisons the instance (`runtime.test.ts`).
|
||
- Visual, Chromium 156 (`scripts/visual-canvas.mjs`): 30 captures before
|
||
(TypeScript canvas) and after (Rust), desktop 1280 × 800 and phone
|
||
390 × 844, no selection, each demo observation active, hover, main and
|
||
head: 30/30 pixel-identical. The method's own noise floor: two captures of
|
||
the same build 30/30 identical; its classifier flags a 10 × 10 change as a
|
||
regression and a one-pixel edge nudge as anti-aliasing.
|
||
- The Step 6 goldens (39) and the seed and review-drawing goldens are
|
||
untouched: the engine and the pipeline still run the TypeScript renderer.
|
||
|
||
### 9.4 Behaviour differences (declared; none touches a product SVG)
|
||
|
||
1. An element outside the SVG namespace is removed (`<path xmlns="…">`), and
|
||
`xlink:href` must be in the xlink namespace whatever its prefix.
|
||
2. Comments and processing instructions are dropped; non-whitespace text is
|
||
kept only in `title`/`desc`, each at most 4 KiB (longer: refused whole).
|
||
3. The root loses `class` and `style` (an inline SVG lives under the page's
|
||
CSS: `class="fixed inset-0 …"` would cover the application) and
|
||
`transform`, `filter`, `mask`, `clip-path` (they can paint outside the
|
||
canvas box); an `id` outside `[A-Za-z_][\w.:-]*` is removed; an `href` is
|
||
local only when it reads `#name` once ASCII whitespace is stripped, as the
|
||
URL parser strips it (the TypeScript also trimmed Unicode spaces, so a
|
||
no-break space before `#a` passed and resolved as a relative URL); inside
|
||
`url(` only CSS whitespace is skipped before `#`, for the same reason.
|
||
4. A reference cycle, an expansion over 50,000 elements, and the floods of
|
||
9.2 step 1 are refused; the TypeScript accepted them (size counted on the
|
||
raw text, refused subtrees included).
|
||
5. A product drawing the allowlist would alter is refused at sheet load for
|
||
the views on that asset (`svg_rejected`, `removed …`); the TypeScript canvas
|
||
dropped such parts silently.
|
||
6. A label or path the document holds with a code point XML 1.0 cannot carry
|
||
is refused (`invalid_character`); the DOM path drew it.
|
||
7. When the canvas cannot be drawn, it says why, inside the canvas (owner
|
||
decision 2026-10-15): the engine did not run (`core_unavailable`,
|
||
`internal`: the existing `sheet.core_unavailable` notice with "Réessayer",
|
||
the retry builds again on a fresh instance), the engine stopped after its
|
||
three recoveries (`CoreRuntime.stopped`: no retry anywhere; the canvas shows
|
||
the stopped text, and `CoreStoppedNotice` sits in the editor's banner slot
|
||
in place of the storage-full text, at the top of Home and New report, and
|
||
replaces the full-page `CoreUnavailable` retry. Two variants: the tab's
|
||
copy of the report is saved, `core.stopped` with "Recharger la page"; the
|
||
tab's storage refused the last write (`saveFailed`), `core.stopped_unsaved`
|
||
with "Télécharger une copie" (the in-memory report as JSON, no engine
|
||
needed), never the reload button. Action, export, import and new-report
|
||
alerts say the same text instead of "try again"; "Réessayer" on the canvas
|
||
restarts the engine before building again) or the view itself cannot be
|
||
drawn (`svg_rejected`,
|
||
`no_asset`, `unknown_view`, `invalid_character`, a parse failure: the
|
||
`canvas.view_unavailable` notice, no retry since nothing would change). The
|
||
technical kind and detail stay in the core's outcome and the DEV console;
|
||
the refused drawing and the session are left as they are. Before R3 a
|
||
failure there left the canvas blank (an uncaught error).
|
||
8. A trigger without a name carries the opened view's name in each language
|
||
(owner decision 2026-10-15: until then both name attributes and its title
|
||
held the French name). Display only; the frozen oracles stay as frozen and
|
||
the tests apply this declared change before comparing.
|
||
9. R3 final checks (owner decisions 2026-10-17). The rescue copy (the
|
||
"Télécharger une copie" JSON, byte format of `osteo:draft`) is importable:
|
||
the Home picker accepts it beside the PDF, routed by content from the first
|
||
KiB (`%PDF-` goes the PDF path), refused above `MAX_ATTACHMENT_BYTES`,
|
||
decoded as strict UTF-8, read by the core's `draft.restore` (no archive) and
|
||
opened like an import; a copy the core refuses is `home.import.error_invalid_copy`
|
||
(file and session untouched), a rebased one shows `editor.draft_rebased`.
|
||
The copy lacks the archive envelope, which the original PDF keeps. A draft
|
||
that traps the engine opens the resolution panel and is read once (§8.7
|
||
item 3); importing the copy of a trapping draft runs the same input again.
|
||
|
||
### 9.5 Measurements
|
||
|
||
| Measure | Value |
|
||
|---|---|
|
||
| shipped module | 1,188,310 B raw, **395,613 B gzip -9** at 23895b9 (+55.7 KB over R2; budget 600 KB; the app image's build root gives 395,541 B) |
|
||
| sheet handle with the drawing read (Node) | 8 to 10 ms |
|
||
| `view.canvas` main, first (Node) | 1.2 to 1.4 ms; head warm median 0.85 ms; 143 KiB of SVG |
|
||
| Chromium, preview build, CPU × 4, medians of 3 | editor to canvas 503 ms (476 ms before R3); detail open 143 ms (125 ms before R3, runs 109 to 157); browser parse + import of the canvas text 21 ms (22 ms) |
|
||
| 50 detail open/close cycles, CPU × 4 | JS heap +0.72 MiB (+0.89 MiB before R3), DOM nodes +0 (+0) |
|
||
|
||
### 9.6 TypeScript deleted, kept
|
||
|
||
- Deleted: the canvas denylist `sanitizeSvg`, `parseDrawing`, the parse
|
||
cache, `assetOfView`, the states input of the canvas build, the
|
||
`assets` field of `SheetIndex`, the app's dependency on
|
||
`@faunosteo/anatomy`.
|
||
- Kept, with their consumers: `packages/anatomy/src/render/**` (PDF engine
|
||
until R4, curation pipeline until R5), `packages/pdf/src/svg/**` (engine
|
||
until R4), the R3 oracle generators (`packages/anatomy/tests/
|
||
r3.layer-oracles.test.ts`, `packages/pdf/tests/r3.{highlight,sanitiser}-
|
||
oracles.test.ts`: they still pass on the TypeScript and keep the freeze
|
||
honest until R4/R5).
|
||
|
||
### 9.7 Residual risks
|
||
|
||
- The engine (PDF) still sanitises with the TypeScript allowlist and has no
|
||
reference budget: the `<use>` expansion gate of `PDF_IMPORT_HARDENING.md`
|
||
§5 is met in the core, closed for the PDF path only when R4 switches it.
|
||
- roxmltree's recursion: safe behind the prescan depth cap (differentially
|
||
fuzzed, 9.3); pin the release with the iterative parser when it ships.
|
||
- References are checked inside one drawing; in the page `#id` resolves against
|
||
the whole document (the detail modal imports a second copy of the drawing,
|
||
as before R3). Drawings with their own assets (Step 13) should get ids
|
||
scoped per view before external uploads are drawn.
|
||
- Firefox and WebKit: not run here (no browser build); the owner's LAN run on
|
||
the phone covers WebKit.
|
||
- The worker's TLS path has not run against a real HTTPS endpoint (every run
|
||
targets the local stack over HTTP): exercise it before the deployment that
|
||
needs it.
|
||
- WASM budget: 396 KB of 600 KB used; R4 adds the PDF reader and writer.
|