Files
faunosteo/.claude/tasks/contracts/2026-10-23-rust-r5-upload.md
T

5.6 KiB

CONTRACT: Rust R5.5, the sheet-asset upload tool (upload-sheet-assets) and the R5.4 closing adjustments

  • date: 2026-10-23 | branch feature/rust-r5-pipeline-core | plan .claude/tasks/plans/2026-10-22-rust-r5-pipeline-core.md §B.5 row R5.5
  • brief: owner 2026-10-23 « Validation R5.4 et autorisation conditionnelle R5.5 » §1 to §10 and §12
  • predecessor: .claude/tasks/contracts/2026-10-23-rust-r5-review.md (R5.4)

Scope

Port packages/supabase/scripts/upload-sheet-assets.ts into the core crate (crates/core, feature upload): rules in src/curation/upload.rs, binary in src/bin/upload_sheet_assets/{main,storage}.rs; scripts scripts/upload-sheet-assets.sh, scripts/sheet-assets-e2e.sh; pnpm assets:upload (Rust), e2e:sheet-assets, TypeScript kept as assets:upload:legacy until the R5.7 census. Plus the R5.4 closing adjustments (owner §2, §3, §6, §7). Out of scope: the fingerprint convention (R5.6), any seed or documentSha256 change, a gated reader change, deleting packages/anatomy or packages/domain, any deploy, any production or managed-Supabase access.

Clauses

C1. Core free of I/O. curation::upload takes values and returns values or UploadError; no std::fs, std::env, network or clock. ureq is an optional dependency enabled only by feature upload (never by the wasm facade or the worker); only the binary reads files, the environment and the network.

C2. Local destination only, verified first. There is no default destination. SUPABASE_URL must be http, carry an explicit port, no credentials, path, query or fragment, and a host that is localhost, a loopback address, or the private IPv4 address equal to FAUNOSTEO_DEV_HOST; anything else is refused (kind Destination) before any request. The key is never sent to a refused destination.

C3. Inputs verified before the first request. The folder lies under supabase/seed/anatomical-sheets (canonical path, symlinks resolved). assets.json is size-capped before parsing, strict on keys, plain .svg file names, lowercase sha256 and uuid, size range, no repeated file, hash or asset id, 1 to 64 entries. Each drawing is read under a cap and equals its entry (size, sha256) and is accepted by the core's SVG reader with nothing removed. A failure stops the run with no request.

C4. Handshake. Before any object read or write: the bucket anatomical-sheet-assets exists, is private, and the key is accepted (401/403 are Access).

C5. No overwrite, delete or visibility change. Objects are created with x-upsert: false; an object under the key is read back and hashed: other bytes refuse the run (State), never replaced. A missing asset row, or a row recording another hash, refuses the run. The tool issues no DELETE, no PUT, no bucket or policy change. The plan of every entry is computed (read-only) before the first write; a run that cannot complete writes nothing.

C6. Confirm after verify; safe resume. The row is confirmed only after the object is read back and hashes to its key. After any failure a rerun resumes: a verified object is kept, a confirmed row is left alone. Transport errors and 5xx are retried three times, refusals are final.

C7. Secrets. The service key comes from the environment only, is held in a type whose Debug is redacted, travels in two request headers, never in a URL, a message or a log; the agent uses no proxy and no redirect; server error text is not echoed.

C8. Closed errors and exit codes. Failures fall in Manifest | Destination | Content | Handshake | State | Access | Network; exit 0 done, 1 refused, 2 usage (argument not UTF-8), 3 network. No failure silently drops an entry.

C9. Identity and bytes preserved. The object key is <sha256>.svg with the manifest hash, the row is addressed by the manifest svg_asset_id, the bytes uploaded are the file's bytes (no re-cleaning, no re-serialisation).

C10. Tests. tests/curation_upload.rs (manifest, bytes, destination, plan), tests/upload_tool.rs (the binary against a loopback stub: check writes nothing, run then rerun, different bytes, missing and foreign row, 401/403, resume after a failed confirm, unreachable port, refused destinations, folder outside the seed, usage), tests/curation_caps.rs; scripts/sheet-assets-e2e.sh for the real local stack (run by the owner; the assistant's own run was refused by the permission layer and is reported as such). scripts/rust-check.sh runs clippy and the tests with --features upload.

C11. Runbook. docs/development/SUPABASE.md §3.1, docs/development/RUST.md §11.16, CHANGELOG, CLAUDE.md commands.

C12. Frozen references untouched. No change under supabase/seed/**, apps/app/tests/fixtures/**, packages/core-wasm/tests/n-1/**, crates/core/src/domain/**, crates/core/src/pdf/**, crates/core/tests/oracles/**; documentSha256 stays 27c7383c…2660; pnpm r5:import-equine --check still reports 0 differences on 18 files.

C13. R5.4 closing adjustments. (a) changes.json and references.json are refused above 4 MiB before any parse allocation with an explicit message, in the core (MAX_CURATION_FILE_BYTES) and in the binary read; other budgets unchanged; (b) the FLOOR clarification of the R5.4 contract holds with its negative proof (scripts/floor-clarification-check.sh); (c) no gated reader and no serde tolerance is changed (characterisation only, RUST.md §11.16).

C14. Gates and limits. pnpm rust:check and pnpm check:all green; security auditor PASS on the diff; this contract CONFORME by a fresh verifier. No merge, no R5.6, no release, no deploy, nothing outside the local stack.