docs(docs): RUST.md with the R0 proofs, DEPLOY image deploy by digest + CSP note, workspace/test strategy/packages/CLAUDE.md, CHANGELOG; chore(memory): TODO R0

This commit is contained in:
bchanot committed 2026-10-13 00:01:27 +02:00
1 parent 4833fd29ef
commit 9d3e0294e2
8 files changed
+376 -3

No files matched your search

+11 -1
View File
@@ -135,7 +135,17 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
- [ ] 8.5 docs: STORAGE.md (model, keys, statuses, purge/grace rules, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker, env file, network, CSP connect-src), SUPABASE.md, CLAUDE.md, CHANGELOG, plan note (worker early, SVG processor → Step 13); CI jobs
- [ ] 8.6 verify: root check, PGlite + real stack pgTAP, types, docker builds (app + worker), real-stack e2e (sign allowed/denied), gates verifier + security; memory; stop for user validation
- [ ] Rust by default (rule adopted 2026-10-12, BDR-043; orientation + 10 principles VALIDATED by the owner 2026-10-12, BDR-044; study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 + Annex A decision table + Annex B R0 scope on chore/step-08-files-analysis; AWAITING the owner's validation of decisions D-R1..D-R14 (D-R6 withdrawn); R0 and Step 8 NOT started until then). Roadmap (each phase: oracles frozen with the old code, consumer-driven deletion, rollback row, gates):
- [ ] R0 foundation (inside Step 8, Annex B): Docker builder image = reference toolchain (rustup optional locally, never on the VPS), Cargo workspace (`crates/core`, `wasm`, `worker` skeletons), toolchain pin, deny.toml, lints, CI job `rust`, worker image started once against the local stack, app wasm stage built but not loaded, `docs/development/RUST.md`, DEPLOY.md (images pulled by digest, CSP `'wasm-unsafe-eval'`, gzip wasm, VPS headroom, rollback = previous digest); 7 experimental proofs kept as tests (wasm panic/re-instantiate, js_number + optional/nullable vs Zod, musl + libwebp build, traced seccomp child, CSP headless, size/instantiate, runner caches)
- [ ] R0 foundation (GO 2026-10-12, BDR-045; branch feature/rust-r0-foundation; Annex B; owner constraints: builds reproducible in Docker, no Rust on the VPS, live deployment untouched, frontend never loads the module, no R1):
- [x] R0.1 toolchain: `docker/rust-builder.Dockerfile` (rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy), `docker/rust-run.sh` (named volumes faunosteo_cargo_registry / faunosteo_rust_target), `docker/rust-check.sh`, `docker/wasm-build.sh` (CLI/crate version lock), root scripts rust:builder / rust:check / wasm:build / worker:test / worker:image
- [x] R0.2 workspace: Cargo.toml (3 members, pinned deps, lints unwrap/expect/disallowed_methods, dev deps optimised), rust-toolchain.toml 1.99.0, rustfmt/clippy/deny config, .cargo/config.toml (wasm stack 1 MiB, TS_RS_EXPORT_DIR), Cargo.lock, .gitignore/.dockerignore (target, pkg)
- [x] R0.3 crates/core: js_number + JsPrettyFormatter (JSON.stringify semantics), report contract types (SheetRef, ReportZone, Vertebra, LateralSide, Unresolved) with optional-absent / nullable-null, facade `call(op, json)` with closed kinds; 12 cargo tests + ts-rs export (4 types committed under packages/core-wasm/types)
- [x] R0.4 crates/wasm: facade (core_version, call, panic_for_test, recurse_for_test); build 224,713 B raw / 85 KB gzip (float_roundtrip on), instantiate ≈ 3 ms in Node
- [x] R0.5 crates/worker: plain main, `decode` child (env check → rlimits AS 512 MiB / CPU 10 s soft, 12 s hard → seccomp allowlist TSYNC kill) → image decode with Limits → orientation → resize_to_fill 512 → libwebp-sys lossy; parent `Spawner` (env_clear, 512 KiB output cap, deadline, signal classification) + `webp_check` (RIFF allowlist, dims, no metadata); `run --check`, `version`; test-hooks (fixtures, violate, flood, alloc, spin, print-allowlist); Dockerfile alpine musl → test stage (sandbox tests + strace derivation) → distroless/static:nonroot
- [x] R0.6 packages/core-wasm: loader (lazy, Node bytes), generated types, vitest proofs (facade, serialisation byte-equal with JSON.stringify on 4 real documents + number cases + Zod readers, panic/stack traps, size budget) skipped with a notice when pkg/ is absent
- [ ] R0.7 proofs recorded with numbers in RUST.md: panic=abort + fresh instance path; float_roundtrip finding; musl static + libwebp ≥ 1.6 build; seccomp allowlist derived by strace and proven on the corpus; CSP with/without 'wasm-unsafe-eval' under the production nginx config (headless Chromium); size/instantiate; runner cache (not measurable here: documented as pending on the forge)
- [ ] R0.8 CI: job `rust` (builder image, fmt/clippy/test/deny, wasm build, types drift), worker test stage + runtime image build in the docker job, nightly advisories, manual `release-images` workflow (digest output, no auto deploy)
- [ ] R0.9 docs: docs/development/RUST.md, DEPLOY.md (prepared: pull by digest, CSP line, gzip wasm, rollback = previous digest; live deployment unchanged), WORKSPACE.md, packages/README.md, CLAUDE.md (stack, map, commands), TEST_STRATEGY.md, CHANGELOG
- [ ] R0.10 gates: `pnpm check` (existing suites untouched), verifier contract, security-auditor; memory (BDR/LRN/EVAL/journal); stop for owner validation, R1 not started
- [ ] R1 = Step 8 worker in Rust (replaces 8.2 below): decode child dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist, `image` + `moxcms` + `libwebp-sys` in the child, parent RIFF-header check only, 512 KiB output cap, per-stage deadlines, service key
- [ ] R2 domain core (before Step 9): sheet/report/archive contracts, `SheetHandle` + `SheetIndexData`, reducers, Finding builder, vertebra selection, publish gate; wasm facade (JSON strings, ts-rs types, poison + reinstantiate, lazy init); app switched; 3 envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP; `packages/domain` frozen for engine/pipeline
- [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first
+4
View File
@@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added (Rust foundation, plan R0)
- **Rust by default** (rule adopted 2026-10-12, `docs/development/RUST_ARCHITECTURE_REVIEW.md`): Cargo workspace with three crates, `crates/core` (contracts and the JavaScript-compatible JSON formatter, no I/O by lint), `crates/wasm` (browser facade built into `packages/core-wasm/pkg`) and `crates/worker` (the future file-processing worker: sandboxed `decode` child with rlimits and a seccomp allowlist derived by `strace`, image decoding in pure Rust, lossy WebP through libwebp confined to the child, parent-side container check; `run --check` only, no job loop before R1). Reference toolchain in Docker (`docker/rust-builder.Dockerfile`, `pnpm rust:check`, `pnpm wasm:build`), worker image on `distroless/static`, CI job `rust`, nightly advisories, manual digest-tagged image workflow (no deploy). R0 proofs recorded in `docs/development/RUST.md`: `float_roundtrip` required for JSON parity, traps leave a wasm instance unusable (fresh instance per recovery), CSP needs `'wasm-unsafe-eval'`. No application behaviour, interface, archive or database change; the frontend does not load the module.
### Added (SaaS migration, plan Step 7)
- **Identity (Step 7)** — sign-in and sign-up by email/password (confirmation mandatory, policy 12 chars + lower/upper/digit), password recovery, OAuth buttons (Google, Apple) driven by `APP_AUTH_PROVIDERS`, landing route for confirmation / OAuth links; the guarded `/app` shell (desktop sidebar, light top bar, mobile drawer) with a dashboard (greeting, profile completeness, local tool, account) and **Mon compte** (personal, professional, preferences, security). Profile columns `practice_name`, `professional_title`, `siret` (migration `20261011100000`, pgTAP 009), language synced with `profiles.locale`, platform roles shown read-only. GoTrue TOTP enabled server-side; MFA enforcement for platform roles documented as a gap (`docs/development/IDENTITY.md`). The local tool (`/`, `/new`, `/editor`) stays unauthenticated; the Home header links to the space only when Supabase is configured.
+19 -1
View File
@@ -52,6 +52,9 @@ MVP species: equine only. Open-source MIT.
| DB client | @supabase/supabase-js (packages/supabase) | 2.x |
| SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 |
| Deploy | Docker multi-stage → nginx:alpine | — |
| Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; every cargo command runs in `docker/rust-builder.Dockerfile` (`pnpm rust:check`, `pnpm wasm:build`), never on the VPS | 1.99.0 |
| WASM glue | wasm-bindgen crate = CLI version (locked in `docker/wasm-build.sh`), `ts-rs` types committed under `packages/core-wasm/types` | 0.2.129 / 12 |
| Worker image | `crates/worker/Dockerfile`: `rust:1.99.0-alpine3.24` (musl, libwebp via `cc`) → `distroless/static:nonroot`; sandbox tests + seccomp derivation in the `test` stage | — |
---
@@ -99,6 +102,13 @@ pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview de
pnpm preview:draft # same, then serves it
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings)
pnpm report:compare <pdf|dir>... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md)
# Rust (docs/development/RUST.md) — all through the builder image, no toolchain on the host
pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0)
pnpm rust:check # fmt --check, clippy -D warnings, cargo test (core, wasm), ts-rs export, cargo deny
pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run
pnpm worker:test # crates/worker/Dockerfile stage test: sandbox tests + seccomp derivation on the musl binary
pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static, `run --check`)
```
## Docker commands
@@ -244,7 +254,14 @@ faunosteo/
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
├─ packages/README.md ← shared packages index
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
├─ packages/core-wasm/ ← @faunosteo/core-wasm: loader of the browser module (pkg/ built, git-ignored), ts-rs types (committed), R0 proofs (panic, serialisation, size)
├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root)
│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced)
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs)
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check, `run --check`; Dockerfile, scripts/derive-seccomp.sh
├─ docker/rust-builder.Dockerfile, rust-run.sh, rust-check.sh, wasm-build.sh, csp-proof/ ← reference Rust toolchain + the CSP proof
├─ .gitea/workflows/ci.yml ← CI: rust job (builder image, fmt/clippy/test/deny, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime)
├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy)
├─ .claude/{tasks/TODO.md,memory/,audits/}
├─ Dockerfile, docker-compose.yml, docker/
├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json
@@ -492,6 +509,7 @@ the owner's validation before any implementation; release 0.2.0 unaffected).
- Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040).
- After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision.
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
- Rust: never on the host or the VPS; `pnpm rust:check` and `pnpm wasm:build` run inside the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed, the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes.
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
+65
View File
@@ -21,6 +21,13 @@ The host should publish only ports `22`, `80`, `443` to the internet. The
container port (`8080` by default) should stay loopback-only — the host
reverse proxy reads from it on `127.0.0.1:8080`.
Rust (plan R0, `docs/development/RUST.md`): the repository also builds a
worker image (`crates/worker/Dockerfile`, static musl binary on
`distroless/static`, container `faunosteo_worker`). It is not deployed yet
(its job loop arrives at R1); the live deployment above is unchanged. The
production VPS never needs a Rust toolchain: images are built in CI and
pulled by digest ("Image deploy by digest", prepared below).
### Reference sheet in the image (SHEET_BUNDLE)
The application needs an anatomical sheet to work. Until sheets are served by
@@ -563,6 +570,64 @@ already exported are unaffected.
---
## Image deploy by digest (prepared at R0, not yet applied)
Decision D-R13 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Annex A and
C): production images are built in CI and the VPS pulls them; it never
compiles the Rust project, and the DEV1-XS memory limit stops mattering for
builds. The procedure below is prepared and documented now; it replaces
"Routine deploys" and "Rollback" above **only when the first image built
this way is deployed, after a separate validation**. Until then the live
deployment keeps building on the VPS as documented above.
1. Build and publish: run the manual workflow `release-images`
(`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on
push) on the forge. It pushes `faunosteo_app:<sha>` and
`faunosteo_worker:<sha>` to the container registry named by the
`REGISTRY` secret (the forge's own Gitea registry is the recommended
choice, Scaleway Container Registry the alternative) and prints their
digests in the job summary. No workflow deploys anything.
2. Pin: `docker-compose.yml` on the VPS references the images by digest
(`image: <registry>/<owner>/faunosteo_app@sha256:…`); the digest is the
only thing that changes at a deploy, by hand, after validation.
3. Deploy: `docker compose pull && docker compose up -d` (no `--build`), then
the post-deploy checks of "Routine deploys".
4. Rollback: set the previous digest back in `docker-compose.yml` and run
step 3 again; nothing is rebuilt and nothing needs crates.io or npm.
5. Registry credentials on the VPS: a read-only token in `~/.docker/config.json`
of the deploy user, never in the repository.
Prerequisites checked at R0 and to re-check before the first digest deploy:
disk headroom on the VPS for two image generations (app ≈ 100 MB,
worker ≈ 9 MB, measured at R0), the registry reachable from the VPS, `docker compose pull`
working with the read-only token.
### WebAssembly and the CSP (from R2 on)
The application does not load the Rust core module before plan R2. When it
does, the two `Content-Security-Policy` headers of this file (nginx and
Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`:
```text
script-src 'self' 'wasm-unsafe-eval';
```
Proven at R0 under the production nginx image and headers with headless
Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in
`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses
to compile the module ("Compiling or instantiating WebAssembly module
violates the following Content Security policy directive"); with the keyword
the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation
only, never `eval` or inline scripts (the proof's inline variant was still
blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16
(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by
`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains
`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types
application/wasm`) and the served, compressed size is what the D-R13 budget
counts.
---
## Health checks
| URL | Expected |
+260
View File
@@ -0,0 +1,260 @@
# 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 <anything> # 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`; `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; 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}`, `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; any `EXIF`, `XMP `, `ICCP` or unknown
chunk refuses the output; owner amendment of D-R4).
- `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 + `scripts/derive-seccomp.sh`), `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; builds and pushes `faunosteo_app:<sha>`
and `faunosteo_worker:<sha>` to the registry of the `REGISTRY` secret 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 musl binary that ships, 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 `<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.
## 6. Reproduction
```bash
pnpm rust:builder && pnpm rust:check # §2, §5.2 (cargo side)
pnpm wasm:build && pnpm --filter @faunosteo/core-wasm test:run # §5.1, §5.2, §5.6
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)
```
## 7. What stays hypothetical after R0
- The browser-side fresh-instance mechanism (static glue URL with a
cache-busting query under Vite, or a Worker per instance) is designed, not
built: R2 builds and tests it.
- HTTPS from the worker (CA bundle of distroless, `webpki-roots`): no HTTP
client in the R0 binary; R1 adds `reqwest` and the CI HTTPS call.
- The forge runner's cache and timings (§5.7).
- 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`).
+3
View File
@@ -17,6 +17,9 @@ Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
| Migration | `supabase db reset` from zero + seed + regression fixtures | CI | every PR touching `supabase/` |
| PDF regression | vitest golden tests: text extraction of generated PDFs, attachment roundtrip, raster hash on fixed inputs | `packages/pdf/tests` | CI |
| SQL/TS contract | generated types diff check | CI | every PR touching `supabase/` |
| Rust core and facade | `cargo test` (unit + fixture tests reading the repository JSON in place), `clippy -D warnings`, `cargo deny`; ts-rs types drift check | `crates/*`, CI job `rust` through the builder image | CI on every PR |
| Rust/TS contract | vitest proofs on the built module: byte equality with `JSON.stringify(…, null, 2)` on the real documents, optional/nullable shape read by the current Zod schemas, panic and stack traps, served size budget | `packages/core-wasm/tests` (skipped with a notice when `pkg/` is absent) | CI `check` after `wasm:build` |
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests`, Dockerfile stage `test` | CI `docker` job |
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
happy-dom where sufficient and under Playwright when real rendering matters
+8 -1
View File
@@ -34,8 +34,15 @@ Future units, created only by the step that needs them:
| Path | Role | Created at |
|---|---|---|
| `apps/public-web` | SSR public site (landing, practitioner profiles, search) | plan Step 22 |
| `apps/worker` | Node job runner (emails, expiry, calendar sync, imports) | plan Step 19 |
| `crates/worker` | Rust job runner (avatars at R1, then emails, expiry, calendar sync, imports) — created at R0, replaces the planned `apps/worker` | R0 (2026-10-12) |
| `packages/*` | shared domain, anatomy, pdf, i18n, supabase, config, ui | see `packages/README.md` |
Rust workspace (plan R0, `docs/development/RUST.md`): `Cargo.toml` at the
root with `crates/core` (library), `crates/wasm` (browser facade, built into
`packages/core-wasm/pkg`) and `crates/worker` (binary). Every cargo command
runs through the builder image (`pnpm rust:check`, `pnpm wasm:build`); the
pnpm workspace gains `packages/core-wasm` (loader, generated types, proofs),
whose tests skip with a notice when the module has not been built.
| `supabase/` | migrations, functions, seed, tests | plan Step 3 |
## 2. Why this layout now
+6
View File
@@ -13,6 +13,12 @@ Planned packages and the step that creates each one:
| `@faunosteo/pdf` | browser-free PDF engine (**created**, Step 6): report archive export from explicit inputs (report, sheet snapshot, branding, labels, rasterizer), layered archive reading, SVG sanitiser, page renderers | Step 6 (PDF archives) |
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 |
| `@faunosteo/core-wasm` | loader of the Rust core compiled to WebAssembly (`pkg/` built by `pnpm wasm:build`, git-ignored), TypeScript types of the contracts generated by ts-rs (committed), the R0 proofs (panic and stack traps, JSON.stringify parity, Zod readers, size budget) | **created**, R0 (Rust review) |
From R2 on, the Rust core (`crates/core`) replaces the TypeScript business
logic of `domain`, `anatomy` and `pdf` phase by phase
(`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part VI); each TypeScript
package is deleted in the phase that switches its last consumer.
| `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |
| `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |