72 lines
5.6 KiB
Markdown
72 lines
5.6 KiB
Markdown
# 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.
|