7.9 KiB
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
crates/worker/Cargo.toml:faunosteo-core = { path = "../core" }. Updatemain.rs::versionandfaunosteo_core_versionto printfaunosteo_core::CORE_VERSION(the comment saying the worker links no core becomes false: remove it).limits.rs, per command (decode constants unchanged):VERIFY_MAX_INPUT_BYTES12 MiB (document 2 MiB + base 2 MiB, SQL CHECK; four drawings, 6 MiB total,SnapshotCaps::ASSETS*; header and margin);VERIFY_MAX_HEADER_BYTES64 KiB;VERIFY_MAX_OUTPUT_BYTES4 MiB (= SQLsheet_verification_max_verdict_bytes);VERIFY_ADDRESS_SPACE_BYTES1 GiB,VERIFY_CPU_SECONDS60,VERIFY_DEADLINE90 s (contract budget: verification under 120 s at the caps);- drawing download policy: at most
SnapshotCaps::ASSETSdrawings fetched, each at mostSnapshotCaps::ASSET_BYTES, total at mostSnapshotCaps::ASSETS_TOTAL_BYTES.
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<u8>anddecode(&[u8]) -> Result<Frame<'_>, 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.verify.rs,pub fn main(args, stdin, stdout, stderr) -> i32mirroringdecode::main: empty environment check;--no-seccomptest hook like decode (only undertest-hooks);sandbox::apply(&Limits { VERIFY_ADDRESS_SPACE_BYTES, VERIFY_CPU_SECONDS }, seccomp); read stdintake(cap + 1); over cap →INPUT_TOO_LARGE; frame error → new exit codeFRAME_INVALID(a parent bug: Broken, not content); buildfaunosteo_core::domain::sheet::verdict::VerdictInputand runcompute_verdict;serde_json::to_vec(&verdict)to stdout. A failing verdict is still exit 0 (it is content, judged by the core).exit_codes.rs: addFRAME_INVALID(next free number), its name; NOT a content rejection.main.rs:Some("verify") => verify::main(...); usage line updated.spawn.rs: the spawner takes the command and its limits: add aChildCommand(or fields) soSpawner::for_decode(exe)keeps today's values andSpawner::for_verify(exe)usesVERIFY_DEADLINE,VERIFY_MAX_OUTPUT_BYTES, subcommandverify. Output classification per command: decode keepswebp_check; verify exit 0 →Produced(bytes)only if the bytes parse as a JSON object (serde_json::from_slice::<serde_json::Map<..>>), elseFailed. Keep the decode path byte-for-byte equivalent in behaviour (existing tests must pass unchanged).- Sandbox / seccomp: the verify child must run under the same filter
(
sandbox::ALLOWED_SYSCALLS). Extendcrates/worker/scripts/derive-seccomp.shto also traceverify --no-seccompon a test-hooks fixture (addfixture verify-cleanandfixture verify-capstofixtures.rs: framed inputs built from a small valid document + drawing, and the at-caps document ofcrates/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). 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
run.rs::main: accept--jobs sheet-verify(and keeprun/run --checkunchanged: default mode = avatars + sweep, exactly as today). Verification mode: no sweep, its own loopverify_loop(config, backend, verifier, watchdog);--checkmay combine (run --jobs sheet-verify --check) and prints the mode.backend.rs: new traitVerifyBackend(keepBackenduntouched):claim_verifications(max) -> Vec<VerifyJob>,verification_input(review_id, token) -> Option<VerifyInput>,download_drawing(bucket, key, max_bytes) -> Vec<u8>(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.http.rs: implement it onHttpBackend(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 keepMAX_RPC_BODY; complete RPC request body up toVERIFY_MAX_OUTPUT_BYTES+ small envelope; drawing download capped atmax_bytes + 1.verify_job.rs: one job: validate ids are UUIDs (keys::is_uuid), read the input (None → logverify_stale_input, end); drawings: bucket must beanatomical-sheet-assets, key must be<64 hex>.svgequal tosha256 + ".svg"(else that drawing is passed without bytes); rows notuploaded, 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 orOverflow→ without bytes, logged; transport error →fail(verification.worker.unavailable). Build the frame, spawn, classify:Produced→ complete; completemalformed→fail(verification.worker.verdict_refused);stale→ log, end. ChildTimeout→fail(timeout);Signalled(SIGXCPU, SIGKILL, SIGABRT, SIGSYS) andOutputOverflowandRejected(input too large) →fail(resource_limit);Broken/Failed→fail(unavailable)then stop the loop (exitCHILD_BROKEN), as the avatar loop does. Every log line throughlogwith the allowlist (addreviewfield if needed, never document text, never child stderr raw).tests/verify_loop.rs(fakeVerifyBackend, real child binary liketests/job_loop.rsdoes): passed verdict completes; failed verdict (unreadable document) completesfailed; stale input; complete answers stale/malformed; drawing 404 → verdict failed withdrawing_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.docker-compose.yml: serviceworker-verifyunder profileworker, same image, same hardening asworker(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.