diff --git a/.claude/tasks/plans/2026-11-01-v1-2-3-worker.md b/.claude/tasks/plans/2026-11-01-v1-2-3-worker.md new file mode 100644 index 00000000..1401ee71 --- /dev/null +++ b/.claude/tasks/plans/2026-11-01-v1-2-3-worker.md @@ -0,0 +1,104 @@ +# Plan: V1-2.3 worker verification mode (P2 child `verify`, P3 `run --jobs sheet-verify`) + +Contract `.claude/tasks/contracts/2026-11-01-v1-2-3-worker-verification.md` (W2-W5). SQL side +(M6) is `supabase/migrations/20261101100000_sheet_verification_jobs.sql`: read it first, the RPC +names, argument names, return shapes and the closed worker codes are fixed there. + +Style: follow `crates/worker` as it stands (plain `main`, no async, closed outcomes, `log` +allowlist, `Backend` trait + fake in tests, `#[allow(unsafe_code)]` never added). Functions +small, one responsibility, comments only for the why. No new dependency beyond `faunosteo-core` +(path dependency, default features: no `pdf-read`, no `curation`). + +## P2 child `verify` + +1. `crates/worker/Cargo.toml`: `faunosteo-core = { path = "../core" }`. Update `main.rs::version` + and `faunosteo_core_version` to print `faunosteo_core::CORE_VERSION` (the comment saying the + worker links no core becomes false: remove it). +2. `limits.rs`, per command (decode constants unchanged): + - `VERIFY_MAX_INPUT_BYTES` 12 MiB (document 2 MiB + base 2 MiB, SQL CHECK; four drawings, + 6 MiB total, `SnapshotCaps::ASSETS*`; header and margin); + - `VERIFY_MAX_HEADER_BYTES` 64 KiB; + - `VERIFY_MAX_OUTPUT_BYTES` 4 MiB (= SQL `sheet_verification_max_verdict_bytes`); + - `VERIFY_ADDRESS_SPACE_BYTES` 1 GiB, `VERIFY_CPU_SECONDS` 60, `VERIFY_DEADLINE` 90 s + (contract budget: verification under 120 s at the caps); + - drawing download policy: at most `SnapshotCaps::ASSETS` drawings fetched, each at most + `SnapshotCaps::ASSET_BYTES`, total at most `SnapshotCaps::ASSETS_TOTAL_BYTES`. +3. `verify_frame.rs` (shared by parent and child): the framed stdin input. + `[u32 LE header length][header JSON][document][base?][drawing bytes in header order]`. + Header: `{sheet_id, version_id, revision, review_id, document_len, base_len|null, + drawings:[{asset_id, sha256, byte_size, bytes_len|null}]}`. `encode(&FrameInput) -> Vec` + and `decode(&[u8]) -> Result, FrameError>` (borrowed slices; header over its cap, + lengths not summing exactly to the rest, document or base not UTF-8 → `FrameError`). Unit + tests: round trip, every malformed case, empty base, missing drawing bytes. +4. `verify.rs`, `pub fn main(args, stdin, stdout, stderr) -> i32` mirroring `decode::main`: + empty environment check; `--no-seccomp` test hook like decode (only under `test-hooks`); + `sandbox::apply(&Limits { VERIFY_ADDRESS_SPACE_BYTES, VERIFY_CPU_SECONDS }, seccomp)`; + read stdin `take(cap + 1)`; over cap → `INPUT_TOO_LARGE`; frame error → new exit code + `FRAME_INVALID` (a parent bug: Broken, not content); build + `faunosteo_core::domain::sheet::verdict::VerdictInput` and run `compute_verdict`; + `serde_json::to_vec(&verdict)` to stdout. A failing verdict is still exit 0 (it is content, + judged by the core). +5. `exit_codes.rs`: add `FRAME_INVALID` (next free number), its name; NOT a content rejection. +6. `main.rs`: `Some("verify") => verify::main(...)`; usage line updated. +7. `spawn.rs`: the spawner takes the command and its limits: add a `ChildCommand` (or fields) + so `Spawner::for_decode(exe)` keeps today's values and `Spawner::for_verify(exe)` uses + `VERIFY_DEADLINE`, `VERIFY_MAX_OUTPUT_BYTES`, subcommand `verify`. Output classification per + command: decode keeps `webp_check`; verify exit 0 → `Produced(bytes)` only if the bytes parse + as a JSON object (`serde_json::from_slice::>`), else `Failed`. Keep the + decode path byte-for-byte equivalent in behaviour (existing tests must pass unchanged). +8. Sandbox / seccomp: the verify child must run under the same filter + (`sandbox::ALLOWED_SYSCALLS`). Extend `crates/worker/scripts/derive-seccomp.sh` to also trace + `verify --no-seccomp` on a test-hooks fixture (add `fixture verify-clean` and + `fixture verify-caps` to `fixtures.rs`: framed inputs built from a small valid document + + drawing, and the at-caps document of `crates/core/tests/sheet_verdict.rs::at_caps`); if a + syscall is missing from the allowlist, add it ONLY if the trace proves it and say so in the + report (do not guess). +9. `tests/sandbox.rs` (Docker test stage): verify child exits 0 on the clean fixture with a + passed verdict, refuses a non-empty environment, kills on over-cap input, and a seccomp + violation still kills (reuse the decode patterns). + +## P3 mode `run --jobs sheet-verify` + +10. `run.rs::main`: accept `--jobs sheet-verify` (and keep `run` / `run --check` unchanged: + default mode = avatars + sweep, exactly as today). Verification mode: no sweep, its own loop + `verify_loop(config, backend, verifier, watchdog)`; `--check` may combine (`run --jobs + sheet-verify --check`) and prints the mode. +11. `backend.rs`: new trait `VerifyBackend` (keep `Backend` untouched): `claim_verifications(max) + -> Vec`, `verification_input(review_id, token) -> Option`, + `download_drawing(bucket, key, max_bytes) -> Vec` (404 → `Status(404)`; over max → + `Overflow`), `complete_verification(review_id, token, verdict_json) -> CompleteAnswer` + (`passed|failed|stale|malformed`), `fail_verification(review_id, token, code) -> FailAnswer` + (`retry|unavailable|stale`). Structs deserialize the M6 shapes exactly. +12. `http.rs`: implement it on `HttpBackend` (same client, auth headers, error mapping). Body + caps per call: input RPC response 16 MiB (two 2 MiB documents escaped in JSON can double), + other RPCs keep `MAX_RPC_BODY`; complete RPC request body up to `VERIFY_MAX_OUTPUT_BYTES` + + small envelope; drawing download capped at `max_bytes + 1`. +13. `verify_job.rs`: one job: validate ids are UUIDs (`keys::is_uuid`), read the input (None → + log `verify_stale_input`, end); drawings: bucket must be `anatomical-sheet-assets`, key must + be `<64 hex>.svg` equal to `sha256 + ".svg"` (else that drawing is passed without bytes); + rows not `uploaded`, over the per-drawing cap, past the count or total cap → passed without + bytes (the core reports missing / caps: a business failure, never a worker failure); + 404 or `Overflow` → without bytes, logged; transport error → `fail(verification.worker.unavailable)`. Build the frame, spawn, + classify: `Produced` → complete; complete `malformed` → `fail(verification.worker.verdict_refused)`; + `stale` → log, end. Child `Timeout` → `fail(timeout)`; `Signalled` (SIGXCPU, SIGKILL, + SIGABRT, SIGSYS) and `OutputOverflow` and `Rejected` (input too large) → + `fail(resource_limit)`; `Broken` / `Failed` → `fail(unavailable)` then stop the loop (exit + `CHILD_BROKEN`), as the avatar loop does. Every log line through `log` with the allowlist + (add `review` field if needed, never document text, never child stderr raw). +14. `tests/verify_loop.rs` (fake `VerifyBackend`, real child binary like `tests/job_loop.rs` + does): passed verdict completes; failed verdict (unreadable document) completes `failed`; + stale input; complete answers stale/malformed; drawing 404 → verdict failed with + `drawing_missing` (not a worker failure); transport error → `fail(unavailable)`; timeout + (test-hooks hang like decode, if present; else a deadline of 0 in a test spawner) → + `fail(timeout)`; output overflow → `fail(resource_limit)`; broken child → stop. +15. `docker-compose.yml`: service `worker-verify` under profile `worker`, same image, same + hardening as `worker` (read-only, `cap_drop: ALL`, no-new-privileges, user, tmpfs if any, + network), `command: ["run", "--jobs", "sheet-verify"]`, same `.env.worker`. Do not start it. + +## Gates the executor runs + +`pnpm rust:check` (fmt, clippy -D warnings, cargo test core + wasm + worker unit, ts-rs, deny); +`cargo test -p faunosteo-worker --features test-hooks` natively for the non-sandbox tests. Docker +stages (`pnpm worker:test`, `pnpm worker:image`) are run by the orchestrator, not the executor. +Never start a worker against any stack. Never touch `supabase/`, `apps/`, `packages/`, +`crates/core/src` (read only), DEV or production. No commit.