docs(docs): R5.5 upload tool runbook, caps, serde tolerance characterisation, contract

This commit is contained in:
bchanot committed 2026-10-23 21:16:59 +02:00
1 parent 2c445063a4
commit a481af52c7
5 files changed
+221 -2

No files matched your search

@@ -0,0 +1,71 @@
# 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.