From 7eca44167b31dc28fadd7c18947a04b08feb7627 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 28 Oct 2026 19:32:57 +0100 Subject: [PATCH] docs(docs): V1-2.1 owner decisions M6, M7 fixture and the size measure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contract §5.2, §5.5 (owner may review others' drafts), §12.2 (one text measure for SQL, TypeScript and Rust), §12.3 and §16.2 (Git fixture for the upgrade, live DEV object not read), §15 tests, §17.3 decisions. --- docs/development/V1-2_ANATOMICAL_SHEETS.md | 83 +++++++++++++++++++--- 1 file changed, 75 insertions(+), 8 deletions(-) diff --git a/docs/development/V1-2_ANATOMICAL_SHEETS.md b/docs/development/V1-2_ANATOMICAL_SHEETS.md index 9df422bb..f5670c04 100644 --- a/docs/development/V1-2_ANATOMICAL_SHEETS.md +++ b/docs/development/V1-2_ANATOMICAL_SHEETS.md @@ -229,7 +229,11 @@ provisional catalogue access of §5.3, one row per grant: osteopaths are reviewers without being administrators. Losing the platform role suspends an editor or publisher capability without deleting the grant row. -- The owner grants itself at first use; no migration grants anything. +- The owner grants itself at first use; no migration grants anything. It may + grant itself any of the three capabilities, `sheet_reviewer` included + (M6, owner decision 2026-10-28, §17.3), under the same `aal2`, factor and + eligibility checks as any grant; no other account grants itself anything. + The separation of duties stays a per-round rule (§5.5). - Scope: every capability is global, over every official sheet. A reviewer named for one species reads the drafts of all species. Rights scoped by species or by sheet are deferred. The per-sheet controls of V1-2 are rules, @@ -344,6 +348,10 @@ of §6.4, the upload confirmation and the narrow read RPC of the operator tool - The review screen shows the author set, the acknowledgments and the approver with the reason and verification note of each reviewer's grant. +An owner holding `sheet_reviewer` reviews and approves drafts written by +other authors; on a round it authored, the acknowledgment and the approval +are refused (`review.separation`) and, should an author's approval ever be +stored, publication refuses it again (`publish.approval.invalid`). A sole owner cannot publish: as an author it can neither acknowledge nor approve its own draft. The system offers no override. One residual remains: the owner could create a second account and grant it `sheet_reviewer`; that @@ -756,8 +764,9 @@ round (on a draft): expected_revision, document, change_note)`. The server checks the caller's capability and `aal2`, that the version is a draft of an active official sheet other than the historical sheet, that no round freezes it, the - revision, the structural guards of §12.2 (shape, serialised size at most - 2 MiB measured as `octet_length(content::text)`, species), and refuses an + revision, the structural guards of §12.2 (shape, size at most 2 MiB as the + UTF-8 bytes of the document's JSON text, `octet_length(content::text)`, + defined in §12.2, species), and refuses an unchanged document. It increments `revision`, the trigger adds the actor to the author set, and the audit records `anatomical_sheet_version.saved` with the revision. A draft may hold integrity errors while it is being written; @@ -1200,7 +1209,8 @@ supplied; they are not invented. - Saving, leave guard, local recovery and conflicts: §6.2. - The validation panel lists the core issues and the completeness report with FR and EN messages per code, a link to the element, the statuses per - group, and the serialised size against the 2 MiB server cap. + group, and the document size against the 2 MiB server cap, in the measure + of §12.2. ### 8.2 Level 1, in the MVP @@ -1500,7 +1510,7 @@ Inventory of the current SQL checks and their fate: |---|---|---|---| | `document.shape` (each id-bearing collection is an array, the document is an object) | `sheet_document_has_shape` | storage structure | kept, applied at creation and save | | `document_schema_version = 2` | table CHECK | storage structure | kept | -| content size | `pg_column_size` CHECK (compressed) | storage structure | kept; save and working copy add `octet_length(content::text)` ≤ 2 MiB | +| content size | `pg_column_size` CHECK (binary jsonb, uncompressed when the row is written) | storage structure | replaced in M5 by `octet_length(content::text) <= 2 097 152` (owner decision 2026-10-28, §17.3); creation, save and working copy check the same measure first and answer `document.too_large` | | document species = sheet species | trigger (l.176) | relational | kept | | `view.asset.unknown`: every drawing id registered for the sheet | `sheet_document_unknown_assets` | relational | kept at submission and publication | | `view.main.count`, `view.parent.missing`, `view.unreachable`, `view.asset.missing` | `sheet_document_view_issues` | business rule, duplicate of the core | removed in M5 | @@ -1531,6 +1541,30 @@ Inventory of the current SQL checks and their fate: - `.claude/rules/sheet-model.md` no longer asks to add a rule « on both sides »: new rules go to the core only. +Measure of the document cap (owner decision 2026-10-28, §17.3). The cap is +2 097 152 bytes (2 MiB), unchanged. What is measured is the UTF-8 byte length +of the document's JSON text in one form, the same for every layer: + +- The form is the text PostgreSQL prints for the stored `jsonb` + (`content::text`): object keys in `jsonb` order (shorter first, then by + bytes), a repeated key kept once (the last), `": "` after each key and + `", "` between members and elements, strings escaped as JSON with + non-ASCII characters left as UTF-8, numbers as PostgreSQL's `numeric` + prints them (plain digits, never an exponent). +- PostgreSQL: `octet_length(content::text) <= 2097152`, in the table CHECK + and, first, in `private.check_document_structure` (creation, save, working + copy), which answers `document.too_large`. The binary size of the `jsonb` + (`pg_column_size`, larger than the text for a document of many small + values) is never the measure. +- TypeScript and Rust: no client-side size check exists in V1-2.1. When the + core reports the size (V1-2.2, read by the validation panel of V1-2.6), it + 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). + ### 12.3 Migrations (names provisional) | Id | Step | Content | Data on DEV | @@ -1542,7 +1576,18 @@ Inventory of the current SQL checks and their fate: Each migration ships its pgTAP file (allowed and denied cases), regenerated `database.types.ts`, a `db:sandbox up upgrade` run from the DEV state (with a copy of the DEV drawing object), and is applied to DEV by the owner at the -closure, after a backup (`SUPABASE.md` §3.3 pattern). BLK-008 stays the rule: +closure, after a backup (`SUPABASE.md` §3.3 pattern). + +M4 and M5 (V1-2.1, owner decision 2026-10-28, §17.3): the upgrade rehearsal +uses a representative Git fixture in place of a copy of the DEV object: the +committed file `supabase/seed/anatomical-sheets/equine/draft/assets/horse.svg`, +whose sha256 equals the one referenced by the DEV metadata (the asset row of +the historical sheet). Its bytes, its Storage metadata and its relations +(asset row, sheet, version) are checked before and after the migration. No +file was read from the real Storage of DEV, so the current integrity of that +DEV object is not demonstrated by this rehearsal; it is checked when the +owner applies M4 to M6 on DEV (§16.11). The substitution is accepted for +V1-2.1 only. BLK-008 stays the rule: no document schema bump in V1-2; verdicts, groups, authors and keys all live outside the document. @@ -1573,7 +1618,7 @@ outside the document. | Labels and references in the UI | React escaping; the core escapes annotation titles; reference URLs http(s) only, opened with `rel="noopener noreferrer"` | | Audit gaps | every RPC calls `private.log_event` (rights, species, saves, rounds, verifications, acknowledgments, comments, decisions, uploads, publications) | | Service key | the worker and the operator tool only, through RPCs | -| Size and volume | content 2 MiB serialised, drawing 2 MiB, comment 4 000 characters, change note 1 000, verdict bounded; per-actor write budget as V1-1 D15 (thresholds in V1-2.1) | +| Size and volume | content 2 MiB (UTF-8 bytes of its JSON text, §12.2), drawing 2 MiB, comment 4 000 characters, change note 1 000, verdict bounded; per-actor write budget as V1-1 D15 (thresholds in V1-2.1) | Residual risks: @@ -1775,7 +1820,14 @@ The final approval needs all 30 groups acknowledged, no `to_confirm` and no - historical sheet: every lifecycle RPC and the trigger refuse it; - deprecated version deletion refused; D8 reads after archive and deprecation; superseded signatures and mirror functions absent; upgrade - from the DEV state. + from the DEV state (for M4 and M5, with the Git fixture of §12.3); + - document size in the measure of §12.2: cap − 1, cap and cap + 1 bytes, + multi-byte and astral characters, a dense document within the cap as + text but over it as binary `jsonb` (accepted), refusals answering + `document.too_large`; + - an owner granting itself `sheet_reviewer`, approving a version written + by another author, refused on its own version, and an author's approval + refused at publication (§5.2, §5.5). - AR-1 B (SQL, per §5.7; PGlite sets the `aal` claim through the JWT settings, the `auth.sessions` check needs the real image): - matrix: no role, owner, admin, moderator, support, each at `aal1` and @@ -1919,6 +1971,10 @@ V1-2.7 on. working copy created from the seeded historical sheet with its drawing; an inactive species invisible to the animal path; types check clean; `pnpm check:all` green. +- Acceptance, upgrade: a stack upgraded from the M3 state with the Git + fixture of §12.3 (sha256 equal to the DEV metadata's) keeps the object's + bytes, metadata and relations; this does not show the integrity of the + live DEV object, which no V1-2.1 run read. - Acceptance, AR-1 B: the tests of §15 for §5.7 pass on the sandbox; a stack upgraded from the DEV state with an owner holding two verified factors keeps working at `aal2` and is refused at `aal1`; the same upgrade @@ -2191,6 +2247,17 @@ DEV operations in §16.11. Reserves left to the owner, not decided here: `aal2` on the staff read policies (§5.7.9). +### 17.3 V1-2.1 final decisions (owner, 2026-10-28) + +Brief « V1-2.1 : décisions finales du propriétaire », on the corrections +checkpoint `2af61e7`: + +| Item | Decision | Where | +|---|---|---| +| M6 | Option A: the `grant.self_review` refusal is removed; an owner at `aal2` with a verified factor may grant itself `sheet_reviewer`. Kept: no author acknowledges or approves a round it authored, the check again at publication, the MFA and eligibility checks, no self-grant for an account that is not owner | §5.2, §5.5, M4 | +| M7 | The Git fixture is accepted for the V1-2.1 upgrade rehearsal (sha256 equal to the DEV metadata's; bytes, metadata and relations before and after); no DEV Storage read, so the live DEV object's integrity is not demonstrated | §12.3, §16.2 | +| Size | The SQL check follows the contract's measure, the UTF-8 bytes of the JSON text; the binary `jsonb` size is not the measure; the cap stays 2 MiB | §12.2, M5 | + --- ## 18. Documents touched by V1-2.0