docs(docs): Ubuntu native development, Docker for services and isolation, separate VPS; pnpm check:all; CI status

RUST.md §1 (three environments, native install recipe, what stays in Docker
and why), §4 (pre-merge gate, workflow files prepared and never run), §5.8
(native run numbers against the builder image), §6; CLAUDE.md stack row,
commands, map, workflow rule; README quick start and verification; DEPLOY.md
CI status; WORKSPACE.md; TEST_STRATEGY.md; CHANGELOG; review Annex C.1
addendum of 2026-10-13.
This commit is contained in:
bchanot committed 2026-10-13 01:19:15 +02:00
1 parent 981a66f33b
commit 6e2bbec4b0
8 files changed
+233 -68

No files matched your search

+4
View File
@@ -10,6 +10,10 @@ Versions follow [Semantic Versioning](https://semver.org/).
- **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.
### Changed (Rust foundation, R0 correction 2026-10-13)
- **Native Rust toolchain as the primary path** on the Ubuntu development machine (user-level rustup, channel of `rust-toolchain.toml`, `wasm32-unknown-unknown`, `wasm-bindgen-cli` 0.2.129, `cargo-deny` 0.20.2): `pnpm rust:check` and `pnpm wasm:build` run `scripts/rust-check.sh` and `scripts/wasm-build.sh` natively (moved from `docker/`, PATH guard `scripts/rust-env.sh`); the builder image stays the reproducible alternative (`pnpm rust:check:docker`, `pnpm wasm:build:docker`). The native check now covers the worker's unit tests; the sandbox tests and the seccomp derivation stay Docker-only (`pnpm worker:test`). New `pnpm check:all` (`scripts/check-all.sh`): every check a branch must pass before a merge, in one command. The Gitea workflow files are kept but marked prepared and never executed (no runner, secret or registry on the forge). Worker `unsafe` blocks: SAFETY comments rewritten as verifiable invariants (no approval marker), WebP stride computed with checked arithmetic. `docs/development/RUST.md` §1 and §4 describe the three environments (Ubuntu native development, Docker for services and isolation, separate production VPS).
### 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.
+15 -11
View File
@@ -52,8 +52,8 @@ 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 |
| Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; native user-level rustup on the Ubuntu development machine (`pnpm rust:check`, `pnpm wasm:build`, plain `cargo`), the builder image `docker/rust-builder.Dockerfile` as the reproducible alternative (`:docker` scripts), never on the VPS | 1.99.0 |
| WASM glue | wasm-bindgen crate = CLI version (locked in `scripts/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 | — |
---
@@ -103,12 +103,15 @@ 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`)
# Rust (docs/development/RUST.md) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first
pnpm rust:check # scripts/rust-check.sh: fmt --check, clippy -D warnings, cargo test (core, wasm, worker unit), ts-rs export, cargo deny
pnpm wasm:build # scripts/wasm-build.sh: crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run
pnpm check:all # scripts/check-all.sh: the whole pre-merge gate (rust:check, types drift, wasm:build, check, app image, worker:test, worker:image)
pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0), the reproducible alternative
pnpm rust:check:docker # the same rust-check.sh inside the builder image
pnpm wasm:build:docker # the same wasm-build.sh inside the builder image
pnpm worker:test # Docker only: crates/worker/Dockerfile stage test, sandbox tests + seccomp derivation on the musl binary
pnpm worker:image # Docker only: runtime image faunosteo_worker:dev (distroless/static, `run --check`)
```
## Docker commands
@@ -259,8 +262,9 @@ faunosteo/
│ ├─ 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)
├─ scripts/{rust-env,rust-check,wasm-build,check-all}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`)
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proof
├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, 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/
@@ -509,7 +513,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.
- Rust: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. 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`).
+8 -3
View File
@@ -25,8 +25,11 @@ 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).
production VPS never needs a Rust toolchain: Rust is compiled on the Ubuntu
development machine (native toolchain) or inside Docker builder images, and
production images will be pulled by digest ("Image deploy by digest",
prepared below) once a runner and a registry exist on the forge. No CI/CD is
operational today (2026-10-13).
### Reference sheet in the image (SHEET_BUNDLE)
@@ -582,7 +585,9 @@ 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
push) on the forge. Prerequisite not met yet: no runner, registry or
secret is configured on the forge (2026-10-13); the workflow has never
run, which is the CI/CD step to decide separately. 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
+11
View File
@@ -63,6 +63,11 @@ cp .env.example .env # edit APP_* vars if desired
pnpm dev # http://localhost:5173
```
Rust (core, browser module, worker): a user-level `rustup` installs the
pinned toolchain from `rust-toolchain.toml` on first use; see
`docs/development/RUST.md` §1 for the three `cargo install` / `rustup
target add` lines and the Docker alternative.
Docker Compose (matches production topology):
```bash
@@ -81,8 +86,14 @@ pnpm lint # ESLint 9 flat config, 0 warnings
pnpm test:run # vitest run (domain, anatomy, supabase/PGlite, app)
pnpm build # tsc + vite build → apps/app/dist/
pnpm report:compare <pdf|dir>... # archive PDF vs its v3 reading, unresolved items flagged
pnpm rust:check # native: fmt, clippy -D warnings, cargo test, ts-rs export, cargo deny
pnpm wasm:build # native: browser module → packages/core-wasm/pkg (the core-wasm proofs run on it)
pnpm check:all # everything a branch must pass before a merge, in one command (needs Docker for the image stages)
```
No CI/CD runs on the forge yet: the workflow files under `.gitea/workflows/`
are prepared for a future runner and call these same scripts.
---
## Build & deploy
+157 -50
View File
@@ -8,37 +8,88 @@ 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
## 1. Toolchain: native on the development machine, 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").
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.
| Piece | Where | Pinned by |
| Environment | Role | Rust |
|---|---|---|
| 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 |
| 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 |
Commands (root `package.json`):
### 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
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
# 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
```
`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.
`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.
## 2. Workspace
@@ -140,35 +191,60 @@ from the shipped one by the feature-gated hooks only), `runtime`
binary), `run --check` exits 0 with `--read-only --cap-drop ALL
--security-opt no-new-privileges:true`.
## 4. CI
## 4. Checks before a merge, and the workflow files (prepared, no CI active)
- 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`.
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 diff --exit-code -- packages/core-wasm/types`), `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; 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 pushes `faunosteo_app:<sha>`
and `faunosteo_worker:<sha>` and prints their digests. Deploys nothing
(`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").
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`,
Target of the future CI/CD step (not implemented, 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)
@@ -267,14 +343,43 @@ 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: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 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 binary> bash docker/csp-proof/run.sh # §5.5 (playwright-core on NODE_PATH)
pnpm check:all # everything above but the CSP proof, in one command
```
## 7. What stays hypothetical after R0
@@ -291,7 +396,9 @@ CHROME=<chromium binary> bash docker/csp-proof/run.sh # §5.5 (playwright-core
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 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`).
@@ -985,3 +985,35 @@ frontend to load the module; no anatomy, PDF or business validation
migration (R2–R5); no avatar processing (R1); everything dockerised, the
production image produced in CI and pulled by the VPS; the live deployment
untouched; no tag or merge into main.
### C.1 Addendum 2026-10-13: development environment and CI status (owner brief after R0)
R0 delivered and validated on the architecture. The owner corrected the
development organisation before closing R0; these points amend Annex B §B.1
and VIII.4 and are implemented on `feature/rust-r0-foundation`:
- Three environments, three roles. The development machine is a self-hosted
Ubuntu server (native, not WSL, not the VPS) with Docker rootless: Rust is
developed and compiled **natively** there (user-level `rustup`, channel of
`rust-toolchain.toml`, `wasm32-unknown-unknown`, `wasm-bindgen-cli` and
`cargo-deny` at the pinned versions; `cargo check / test / build / clippy /
fmt` and the browser module build run without Docker). Docker on that
machine runs the Faunosteo services (Supabase), the worker in its hardened
container, the integration tests, the sandbox and seccomp proofs, and
builds the deployment images (multi-stage). The production VPS is separate
and never compiles.
- The R0 builder image is kept as the reproducible alternative
(`pnpm rust:check:docker`, `pnpm wasm:build:docker`) and as the reference
for a future runner; it is no longer the arbiter of daily work and is not
required for a compile or a test. The worker's isolation is unchanged.
- No CI/CD is operational on the forge (no runner, secret or registry). The
workflow files are prepared material for a separate CI/CD decision; a
workflow is never reported as passed before it has run on the forge. The
pre-merge gate is local: `pnpm check:all` (`scripts/check-all.sh`), which a
future runner calls as is.
- Target of that future step (not implemented): 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.
- R1 (the Step 8 worker) waits for the owner's final validation of this
correction; no deployment, no release 0.2.0.
+3 -3
View File
@@ -17,9 +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 |
| 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/*`, `pnpm rust:check` (native, `scripts/rust-check.sh`; same file in the builder image), `pnpm check:all` | before every Rust commit and every merge; CI job `rust` prepared, no runner yet |
| 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) | `pnpm check:all` (after the native `wasm:build`); CI `check` prepared |
| 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` (`pnpm worker:test`, Docker only, never native) | every `crates/worker` commit, `pnpm check:all`; CI `docker` job prepared |
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
happy-dom where sufficient and under Playwright when real rendering matters
+3 -1
View File
@@ -40,7 +40,9 @@ Future units, created only by the step that needs them:
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
runs on the native toolchain of the development machine (`pnpm rust:check`,
`pnpm wasm:build`; user-level rustup, channel of `rust-toolchain.toml`) or,
for a reproducible run, through the builder image (`:docker` variants); 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 |