From 562039949214926982e83ac17707e9a9539bcd30 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 28 Oct 2026 20:08:19 +0100 Subject: [PATCH] docs(docs): V1-2.1 size bound on numbers, M7 note in 9.5, old measure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contract §1 and §9.5 aligned with the text measure and the Git fixture, §12.2 says where the size vectors live and how numbers are bounded. --- docs/development/V1-2_ANATOMICAL_SHEETS.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/development/V1-2_ANATOMICAL_SHEETS.md b/docs/development/V1-2_ANATOMICAL_SHEETS.md index f5670c04..49d86083 100644 --- a/docs/development/V1-2_ANATOMICAL_SHEETS.md +++ b/docs/development/V1-2_ANATOMICAL_SHEETS.md @@ -54,7 +54,7 @@ repository on 2026-10-28. Line numbers refer to | Integrity | `validate_sheet_document`: 21 codes, 19 errors and 2 warnings (`annotation.no_findings`, `finding_zone.unreferenced`). SQL mirror `private.sheet_document_issues`: 17 of the 19 errors plus `document.shape` and `reference.url.scheme`; `publish_sheet_version` adds `view.asset.unknown` (inventory in §12.2). | | Fingerprint | `sha256-rfc8785-validated-v1`, computed by the core only, refused for a document with an error-level issue (`fingerprint.rs` l.260-265); SQL cannot compute it. It covers `svg_asset_id` values, not the drawings' sha256. Equine draft `12d78872…`; the v0 alias is bound to sheet `503dc301…` only (`fingerprint.rs` l.44-49, `rebase.rs` l.42-45). | | Creation | `create_empty_sheet_document(species_id, name)`: one main view `view-main` without drawing, empty collections. No other authoring operation exists in the core. | -| Tables | `species` (10 rows: nine species and `other`; column `active`), `anatomical_sheets` (monolingual `name`, `slug`, `description`; `visibility`; status `active`, `archived`, `deleted`; slug unique per `coalesce(creator_user_id, zero uuid)` among non-deleted sheets, official sheets have a null creator), `anatomical_sheet_versions` (`draft`, `published`, `deprecated`; one draft per sheet; numbers never reused; `published_by`, `published_at` exist; content capped by `pg_column_size`, l.108, a compressed size), `anatomical_sheet_assets` (rows unique per sheet and sha256; `uploaded_at` null until confirmed; no immutability trigger). | +| Tables | `species` (10 rows: nine species and `other`; column `active`), `anatomical_sheets` (monolingual `name`, `slug`, `description`; `visibility`; status `active`, `archived`, `deleted`; slug unique per `coalesce(creator_user_id, zero uuid)` among non-deleted sheets, official sheets have a null creator), `anatomical_sheet_versions` (`draft`, `published`, `deprecated`; one draft per sheet; numbers never reused; `published_by`, `published_at` exist; content capped by `pg_column_size`, l.108, the binary `jsonb` size, replaced in M5 by the text measure of §12.2), `anatomical_sheet_assets` (rows unique per sheet and sha256; `uploaded_at` null until confirmed; no immutability trigger). | | Species access | Policy `species_select_active`: authenticated callers see active rows only. The animal forms read species through `fetchSpeciesLabels` under that policy; `create_animal` and `update_animal` refuse an inactive species; `create_anatomical_sheet` requires an active one (l.713). Table comment: « no API write path ». | | Immutability | `guard_sheet_version_update` freezes published rows except the deprecation transition, comparing a fixed column list (l.219-232), and lets a draft become published with any column change (l.234-238). `guard_sheet_version_delete` refuses `published` only (l.275-278): a deprecated version can be deleted physically today (pgTAP `005_anatomical_sheets.sql` l.551 asserts it). | | RPCs | 12 for authenticated callers (create, create_draft, publish, deprecate, delete_version, fork, archive, restore, delete_sheet, set_visibility, register_asset, delete_asset) plus `confirm_sheet_asset_upload` (service role). `register_sheet_asset` returns the existing row of the same sheet and sha256 or inserts one (l.1021). `create_sheet_draft` accepts any non-draft source (l.756). The fork copies asset rows (`copy_sheet_assets`) and rewrites the document's drawing ids (`remap_document_assets`). | @@ -1360,8 +1360,10 @@ A drawing never blocks authoring: only the round waits for its verdict. - The DEV equine row (bytes at `.svg`, confirmed by the operator tool) keeps its state; no migration rewrites it. The working copy (§14.3) registers the same bytes for its own sheet after the storage check. The - migrations are rehearsed on a sandbox holding a copy of that object, not - only on an empty upgrade. + migrations are rehearsed on a sandbox holding that object, not only on an + empty upgrade; for M4 and M5 (V1-2.1) the owner accepted a Git fixture with + the same sha256 in place of a copy of the DEV object, which leaves the live + object's integrity undemonstrated (§12.3, §17.3). - `pnpm assets:upload` stays the seed tool of local and sandbox stacks. With the service role's table privileges revoked (F12), the same step gives the tool a narrow read RPC for its planning and reruns `pnpm e2e:sheet-assets`. @@ -1561,9 +1563,14 @@ of the document's JSON text in one form, the same for every layer: computes this same form, never the length of `JSON.stringify` or of a compact `serde_json` output: the compact text is shorter by one byte per object member and per separator, so a compact measure under the cap is - necessary, not sufficient. The core's tests share vectors with pgTAP 017 - (cap − 1, cap, cap + 1, multi-byte and astral characters, a dense document, - numbers that JavaScript prints with an exponent). + necessary, not sufficient. pgTAP 017 holds the vectors (cap − 1, cap, + cap + 1, multi-byte and astral characters, a dense document, numbers that + JavaScript prints with an exponent); the core's size tests of V1-2.2 reuse + them. +- The numbers' printed lengths are summed first, one number at a time, and + the whole text is built only once they fit the cap: a small payload of + numbers with huge exponents (`1e131071` prints 131 072 digits) answers + `document.too_large`, never an out-of-memory error. ### 12.3 Migrations (names provisional)