59 lines
10 KiB
Markdown
59 lines
10 KiB
Markdown
# CONTRACT — Rust R0 foundation (whole phase, for the fresh verifier)
|
||
- date: 2026-10-13 | flow: ad-hoc phase (owner go 2026-10-12, BDR-045) | branch: feature/rust-r0-foundation (base develop = 5fec065)
|
||
- status: active (amended 2026-10-13 after verifier pass 1: criteria 10 and 14 oracles counted comment lines; pass 2 CONFORME 16/16, criterion 16 oracle excludes the contract file itself; pass 3 after the security fixes: criteria 10 and 11 oracles updated to the gated SAFETY form and the second refusal arm; no code change)
|
||
- spec: docs/development/RUST_ARCHITECTURE_REVIEW.md (Part III, Annex B, Annex C), docs/development/RUST.md (what was built and proven)
|
||
- evidence logs (runs made by the orchestrator on this host, readable): <session scratchpad>/{pnpm-check.log,worker-test-build-5.log,worker-image-build-2.log,builder-build-2.log}
|
||
|
||
## REQUEST (owner brief 2026-10-12, condensed — IMMUTABLE)
|
||
Implement R0 per Annex B: Cargo workspace with crates core, wasm, worker; pinned Rust and dependencies; reproducible Docker builder (no Rust on the VPS); native and WebAssembly compilation; working TypeScript bindings; JSON contracts compatible with the current data; first wasm size and performance measurements; applicable security and isolation tests; CI integration; development and deployment documentation. The seven proofs run in the real environment where possible (serialisation, wasm panics, musl, seccomp verified experimentally; a proof that cannot be obtained is reported, not assumed). Compatibility: the React app, Report v3, PDF v2/v3, Supabase, the interfaces and the existing tests stay unchanged; the frontend does not load the module. No migration of anatomy, PDF or business validations (R2–R5); no avatar business processing (R1). Everything dockerised; production images built in CI and pulled by the VPS; live deployment unchanged; no tag or merge into main.
|
||
|
||
## ACCEPTANCE CRITERIA
|
||
1. Workspace with exactly three crates, toolchain pinned identically in the three places.
|
||
CHECK: grep -c '"crates/core", "crates/wasm", "crates/worker"' Cargo.toml; grep -c 'channel = "1.99.0"' rust-toolchain.toml; grep -c "FROM rust:1.99.0-bookworm" docker/rust-builder.Dockerfile; grep -c "FROM rust:1.99.0-alpine3.24" crates/worker/Dockerfile; ls crates
|
||
EXPECT: 1 ; 1 ; 1 ; 1 ; core wasm worker
|
||
2. wasm-bindgen crate and CLI locked to one version, refused up front on mismatch.
|
||
CHECK: grep -c 'wasm-bindgen = "=0.2.129"' Cargo.toml; grep -c "WASM_BINDGEN_VERSION=0.2.129" docker/rust-builder.Dockerfile; grep -c 'lock_version" != "$cli_version"' docker/wasm-build.sh
|
||
EXPECT: 1 ; 1 ; 1
|
||
3. The core takes ids, time and bytes as inputs: no I/O, clock or env in crates/core/src, lint-enforced.
|
||
CHECK: grep -rn "std::fs\|std::env\|std::time\|SystemTime\|Instant::now" crates/core/src | wc -l; grep -c "disallowed_methods = \"deny\"" Cargo.toml; grep -c "std::fs::read\|std::env::var\|SystemTime::now" clippy.toml; grep -c "^serde\|^serde_json\|^ts-rs" crates/core/Cargo.toml
|
||
EXPECT: 0 ; 1 ; >= 3 ; 3
|
||
4. JSON contract: preserve_order and float_roundtrip enabled; the JavaScript number formatter and the pretty formatter exist with their unit tests.
|
||
CHECK: grep -c '"preserve_order", "float_roundtrip"' Cargo.toml; grep -c "pub fn js_number\|pub struct JsPrettyFormatter\|pub fn to_js_pretty\|pub fn pretty_js_round_trip" crates/core/src/json.rs; bash docker/rust-run.sh cargo test -p faunosteo-core --locked 2>&1 | grep -E "^test result" | head -2
|
||
EXPECT: 1 ; 4 ; two lines "ok. 10 passed" and "ok. 2 passed"
|
||
5. Report contract types mirror the Zod rules: optional fields skipped when None, nullable field plain Option, Unresolved = literal true; committed ts-rs types equal a fresh export.
|
||
CHECK: grep -c 'skip_serializing_if = "Option::is_none"' crates/core/src/domain/report.rs; grep -c "pub version_id: Option<String>" crates/core/src/domain/report.rs; grep -c 'ts(optional, type = "true")' crates/core/src/domain/report.rs; bash docker/rust-run.sh cargo test -p faunosteo-core --features ts --locked 2>&1 | grep -c "test result: ok"; git diff --exit-code -- packages/core-wasm/types && echo SAME
|
||
EXPECT: 5 ; 1 ; 1 ; >= 1 ; SAME
|
||
6. Browser facade exposes exactly core_version, call, panic_for_test, recurse_for_test; the loader never imports pkg statically; every proof file skips when pkg is absent.
|
||
CHECK: grep -c "^pub fn core_version\|^pub fn call\|^pub fn panic_for_test\|^pub fn recurse_for_test" crates/wasm/src/lib.rs; grep -c "^import .* from '../pkg" packages/core-wasm/src/index.ts; grep -l "describe.skipIf(!coreBuilt)" packages/core-wasm/tests/*.test.ts | wc -l
|
||
EXPECT: 4 ; 0 ; 4
|
||
7. The wasm proofs pass on the built module (byte equality with JSON.stringify on the four documents, number corpus, Zod readers, panic and stack traps, fresh-instance recovery, size budget).
|
||
CHECK: ls packages/core-wasm/pkg/faunosteo_wasm_bg.wasm; corepack pnpm --filter @faunosteo/core-wasm test:run 2>&1 | grep -E "Tests |Test Files"; grep -c "float_roundtrip\|memory access out of bounds\|wasm-unsafe-eval" docs/development/RUST.md
|
||
EXPECT: file exists (built by the orchestrator; if absent run `pnpm wasm:build` first) ; "4 passed" and "14 passed" ; >= 3
|
||
8. Worker process model: plain main without an async runtime; decode checks the environment, then the thread count, then rlimits, then seccomp, before reading input.
|
||
CHECK: grep -c "tokio" crates/worker/Cargo.toml; grep -n "vars_os().next().is_some()\|sandbox::apply(\|read_to_end(&mut input)" crates/worker/src/decode.rs | head -3; grep -n "ensure_single_thread()?;\|set_rlimits(limits)?;\|install_seccomp()?;" crates/worker/src/sandbox.rs | head -3
|
||
EXPECT: 0 ; the three lines appear in that order (env check line < sandbox line < read line) ; the three calls appear in that order
|
||
9. seccomp allowlist is the traced set plus the abort path, denies every file and process syscall, and was derived and proven on the musl binary.
|
||
CHECK: sed -n '/^pub const ALLOWED_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs | grep -c '("'; sed -n '/^pub const ABORT_PATH_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs | grep -c '("'; grep -c "open\|execve\|clone\|socket" <(sed -n '/^pub const ALLOWED_SYSCALLS/,/^];/p' crates/worker/src/sandbox.rs); grep -E "test result: ok. 16 passed|allowlist covers the trace" <session scratchpad>/worker-test-build-11.log | sed -E 's/^#[0-9]+ [0-9.]+ //' | sort -u
|
||
EXPECT: 7 ; 7 ; 0 ; both lines present
|
||
10. The keyed parent never decodes: spawn.rs and webp_check.rs use no image decoder; output capped at 512 KiB; the RIFF check allowlists four chunk types and refuses the rest.
|
||
CHECK: grep -c "image::" crates/worker/src/spawn.rs crates/worker/src/webp_check.rs; grep -c "MAX_OUTPUT_BYTES: usize = 512 \* 1024" crates/worker/src/limits.rs; grep -c 'b"VP8X", b"VP8 ", b"VP8L", b"ALPH"' crates/worker/src/webp_check.rs; grep -c "return Err(WebpIssue::ForbiddenChunk(fourcc))" crates/worker/src/webp_check.rs
|
||
EXPECT: 0 for both files ; 1 ; 1 ; 2 (the allowlist gate and the defensive arm of the structure match, since a8b644a)
|
||
11. libwebp confined to the child and its version controlled: FFI only in decode.rs with SAFETY comments, minimum 1.6.0 checked by a test and by `run --check`.
|
||
CHECK: grep -l "libwebp_sys::" crates/worker/src/*.rs; grep -c "// SAFETY" crates/worker/src/decode.rs; grep -c "MIN_LIBWEBP_VERSION: (u8, u8, u8) = (1, 6, 0)" crates/worker/src/limits.rs; grep -c "the_linked_libwebp_is_recent_enough" crates/worker/tests/sandbox.rs
|
||
EXPECT: crates/worker/src/decode.rs only ; >= 4 ; 1 ; 1
|
||
12. Test hooks never ship: release build without features; the runtime image is distroless static, non-root, with `run --check` as its command.
|
||
CHECK: grep -n "cargo build -p faunosteo-worker --release --locked" crates/worker/Dockerfile | grep -c "features"; grep -c "FROM gcr.io/distroless/static-debian12:nonroot" crates/worker/Dockerfile; grep -c "^USER nonroot" crates/worker/Dockerfile; grep -c 'CMD \["run", "--check"\]' crates/worker/Dockerfile; tail -1 <session scratchpad>/worker-image-build-6.log
|
||
EXPECT: 0 ; 1 ; 1 ; 1 ; exit=0
|
||
13. Frontend, live deployment and database untouched; the existing suites still pass.
|
||
CHECK: git diff --stat 5fec065..HEAD -- apps/app Dockerfile docker-compose.yml docker/nginx.conf docker/entrypoint.sh supabase packages/domain packages/anatomy packages/pdf packages/supabase | wc -l; tail -1 <session scratchpad>/pnpm-check.log; grep -E "apps/app test:run:\s+Tests|packages/pdf test:run:\s+Tests|packages/anatomy test:run:\s+Tests" <session scratchpad>/pnpm-check.log
|
||
EXPECT: 0 ; exit=0 ; 278, 137, 130 passed
|
||
14. CI: rust job before check through the builder image with the types drift check; docker job builds the worker test stage and starts the runtime image read-only with every capability dropped; advisories nightly; release-images manual only and deploys nothing.
|
||
CHECK: grep -c "needs: rust" .gitea/workflows/ci.yml; grep -c "docker/rust-check.sh\|git diff --exit-code -- packages/core-wasm/types" .gitea/workflows/ci.yml; grep -c -- "--target test\|--read-only --cap-drop ALL" .gitea/workflows/ci.yml; grep -v "^#" .gitea/workflows/release-images.yml | grep -c "^ workflow_dispatch:"; grep -v "^#" .gitea/workflows/release-images.yml | grep -cE "^\s*(push|pull_request|schedule):|ssh |scp |compose (up|pull)"; grep -c "cron:" .gitea/workflows/rust-advisories.yml
|
||
EXPECT: 1 ; 2 ; 2 ; 1 ; 0 ; 1
|
||
15. Docs: RUST.md carries the seven proofs with numbers and the hypothetical list; DEPLOY.md carries the prepared digest procedure and the CSP note while the live procedure stays; CLAUDE.md, WORKSPACE.md, TEST_STRATEGY.md, packages/README.md, CHANGELOG updated.
|
||
CHECK: grep -c "^### 5\.[1-7]" docs/development/RUST.md; grep -c "^## 7. What stays hypothetical" docs/development/RUST.md; grep -c "^## Image deploy by digest (prepared at R0, not yet applied)" DEPLOY.md; grep -c "docker compose up --build -d" DEPLOY.md; grep -c "wasm-unsafe-eval" DEPLOY.md; grep -c "pnpm rust:check" CLAUDE.md; grep -c "crates/worker" docs/development/WORKSPACE.md; grep -c "Worker sandbox" docs/development/TEST_STRATEGY.md; grep -c "core-wasm" packages/README.md; grep -c "Rust foundation, plan R0" CHANGELOG.md
|
||
EXPECT: 7 ; 1 ; 1 ; >= 2 (live procedure kept) ; >= 2 ; >= 1 ; >= 1 ; 1 ; >= 1 ; 1
|
||
16. No secret and no credential in the new files; the worker's env check and the CI secrets usage are the only places naming keys.
|
||
CHECK: git diff 5fec065..HEAD -- . ':!.claude/tasks/contracts' | grep -E "^\+" | grep -Ei "eyJ[a-zA-Z0-9_-]{20,}|sk_live|service_role_key *= *\"[^\"]+\"|password *= *\"" | wc -l; grep -c "secrets.REGISTRY_TOKEN" .gitea/workflows/release-images.yml
|
||
EXPECT: 0 ; 1
|