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

+83
View File
@@ -3266,3 +3266,86 @@ service key from the environment, bucket `anatomical-sheet-assets`, key `<sha256
`upsert: false`, bytes verified against `assets.json`, RPC `confirm_sheet_asset_upload`) run
against the local stack only, with its runbook.
### 11.16 R5.5: the sheet-asset upload tool, the R5.4 closing adjustments (2026-10-23)
Contract `.claude/tasks/contracts/2026-10-23-rust-r5-upload.md`. Owner brief « Validation R5.4 et
autorisation conditionnelle R5.5 ».
**Tool.** `upload-sheet-assets` (`crates/core`, feature `upload` = `curation` + `ureq`, the version
the worker already uses; `pnpm assets:upload [--check] <seed folder>`). The rules are the core's
(`curation::upload`: manifest, destination, bytes through the one SVG reader, plan from the observed
state, closed error kinds); the binary owns the file system, the environment and the network, split
in `main.rs` (flow, files) and `storage.rs` (HTTP). It replaces `packages/supabase/scripts/
upload-sheet-assets.ts`, kept as `assets:upload:legacy` until the R5.7 census. Behaviour and runbook:
SUPABASE.md §3.1. Differences from the TypeScript tool, all refusals added: no default destination
(a local address with an explicit port is required); an existing object is hashed, not trusted by its
name; a missing or foreign asset row stops the run instead of failing after the upload; the whole run
is planned before the first write; the file must pass the SVG reader with nothing removed; sizes and
entry counts are capped; nothing is overwritten, deleted or made public, ever (`x-upsert: false`, no
DELETE, no bucket call but the read).
**Destination rule.** `http`, explicit port, no credentials, path, query or fragment; host `localhost`,
a loopback address, or the private IPv4 address equal to `FAUNOSTEO_DEV_HOST`. A name other than
`localhost` is never accepted (it cannot be proven local without resolving it). The handshake then
checks the private bucket and the key before any object is read or written. A local port held by
something else would receive the key: accepted on a single-user machine, the same stance as the
worker's `SUPABASE_URL`.
**Tests.** `curation_upload` (7: manifest family, bytes, 15 destination refusals + DEV host rule,
plan), `upload_tool` (10, the binary against a loopback stub with a made-up key: `--check` writes
nothing, run then rerun, different bytes never overwritten, missing and foreign row stop before any
write, 401/403, resume after a failed confirmation, unreachable port, refused destinations, folder
outside the seed, usage), `curation_caps` (4). **Not run by the assistant**: the session against the
real local stack (`pnpm e2e:sheet-assets`: upload, rerun, anon key, wrong key, refused destinations,
unreachable port); the assistant's own run of the tool with the service key was refused by the
permission layer (CLAUDE.md: no transfer tool run by Claude) and was not retried by another route.
The owner runs it.
**Read caps (owner §3).** `changes.json` and `references.json` are refused above 4 MiB, by name, in
the core (`MAX_CURATION_FILE_BYTES`, checked before the parse) and in the binary (bounded read, the
bytes read are counted as well as the size seen). Measured: 221.5 KB and 17.3 KB committed (about 19 and 240
times under the cap); `--check` peaks at 18.5 MB resident; a synthetic changeset of 765 changes
(3.98 MB, ids renumbered) parses at +39 MB over a 7 MB baseline, about 10 times the text. The 65 times
of the R5.4 round-9 security gate (§11.15) is a worst-case shape of many tiny values; at the 4 MiB cap
that is about 260 MB where the 16 MiB read cap allowed about 1 GB. Other budgets (document depth and
values, records, drawings, the 16 MiB read cap for every other source) unchanged. 4 MiB leaves a
wide margin; a future multi-species changeset is a business-contract question and is not decided
here.
**Owner decisions applied.** Quadratic scans (§5): kept, debt recorded in §11.15, no rewrite without
a measured problem. URLs in titles, questions and justifications (§4): kept verbatim in the data and
in the Markdown reports, no active HTML produced; an interface shows them as untrusted text. Divergent
refusals (§6): invalid field segments, ids outside the stable-id grammar, inputs over the budgets, each
a controlled `PipelineError::Source` or `Guard`, none dropping authored data; the grammar is the
sheet contract's `^[a-z0-9][a-z0-9_-]{0,63}$`, species-neutral (`curation_caps` checks ids of other
species). Markdown stays an allowlist: an unreproduced form is a loud refusal, never a different file.
FLOOR (§2): the clarification is in the R5.4 contract, with `scripts/floor-clarification-check.sh`.
**Serde tolerance of the R2 contracts (owner §7), characterisation only; nothing changed.**
Structures: every serde-derived contract of `domain/{sheet,report,archive}`, read by the gated
readers (`report/read.rs`: `Report::deserialize` for v3, `ReportV2::deserialize` for v2;
`archive/read.rs`; the PDF import path). Two tolerances: a struct is read from a positional array,
and a unit enum variant from a one-key map. Probed on Report v3 (test
`characterisation_serde_tolerance`, which pins today's verdict):
| Input (minimal change of `report-v3.demo.json`) | Rust now | Historical Zod contract |
|---|---|---|
| `"sheet": [sheetId, null, documentSha256]` | accepted | refused |
| `"practitioner": [name, cabinet, contact, siret]` | accepted | refused |
| `observations[0].severity` = `{"mild": null}` | accepted | refused |
| a zone written as an array | refused only when the order is wrong, accepted when it matches the field order | refused |
| `"extra": 1` (unknown field) | accepted | accepted (non-strict objects) |
Consequence of accepting: a hand-built or foreign attachment imports; the report is re-serialised in
the canonical object form, so nothing stored is non-canonical, but a positional array read in the
wrong order assigns values to the wrong fields without an error when the types agree (an integrity
risk for crafted files, not a memory or code-execution one). Consequence of refusing: only files the
application never produced are turned away. Risk for R2, R3 and R4 archives: none either way, every
archive the product wrote is in object form (the frozen envelopes round-trip, `report_contract`, and the
N-1 suites), so a strict reading rejects no golden and no fixture. Proposal: the guard already used for
the authored files (`draft/shape.rs`: compare the input with its typed reading serialised back) at the
three reader entries, per-file go of the owner, decided before R5.6 since the membership test touches
the same readers there; until then the gated readers are unchanged.
Open points carried: debt list of §11.12 and §11.13 stands (migration map cascade replay, `clippy.toml`
I/O list); the upload tool is not run against the real stack by the assistant.