# V1-2 Anatomical sheets: contract Status: decisions RATIFIED, contract consolidated for the owner's final review (V1-2.0, 2026-10-28). The arbitration AR-1 is closed: the owner ratified option B (`aal2` for every platform role change, §5.7, §17.2, BDR-083). The owner approved the orientations D1 to D8 and added the mandatory requirement D9 (BDR-081, 2026-10-27), then ratified the decisions O1 to O23 in the brief « V1-2.0 : ratification des arbitrages O1 à O23 et consolidation du contrat » (2026-10-28, BDR-082). This revision writes those decisions into the rules, resolves the contradictions C1 to C14 found at the review of the first revision (§19.2), restates the step plan (§16) and integrates a second round of fresh challenges (§19.3), one finding of which needed the owner (AR-1, decided) and a third review of the AR-1 B text (§19.4). It authorises no implementation: V1-2.1 starts only on the owner's explicit go. V1-2.0 changes no code, migration, policy, RPC, anatomical data or DEV state. Branch: `feature/v1-2-anatomical-sheets` (off `develop` 9135d73, the V1-1 merge). Roadmap position: `IMPLEMENTATION_PLAN.md` §0, V1-2. This contract absorbs plan Step 13 (provider over Supabase, sheet library) and, for official sheets only, the editor of plan Step 17 at the level described in §8.2. The community parts of Steps 17 and 18 (personal sheets, sharing, follows, forks) stay out. Fundamental requirement (owner, 2026-10-28): by the end of V1-2, a habilitated administrator creates and edits a complete official sheet from the application, prepares its SVG views, annotations and categories, submits it to review and publishes the approved version. No deferral of this contract makes that journey impossible; V1-2.7 proves it end to end with two accounts on the sandbox, and the same journey runs on DEV once the owner has authorised the operations of §16.11. Parts: 1 facts, 2 scope, 3 nomenclature, 4 decisions D1 to D9, 5 access, roles and permissions, 6 lifecycle, review, verification and publication, 7 species and new sheets, 8 editor, 9 drawings, 10 loading, 11 screens and journeys, 12 SQL defects, SQL authority and migrations, 13 security, 14 equine sheet, 15 tests, 16 implementation steps, 17 ratified decisions and arbitration, 18 documents touched by V1-2.0, 19 challenge record. --- ## 1. Facts the contract rests on State of `develop` 9135d73 and of Supabase DEV, read on 2026-10-27 in a read-only session (`default_transaction_read_only=on`), completed from the repository on 2026-10-28. Line numbers refer to `supabase/migrations/20261008110000_anatomical_sheets.sql` unless named. | Area | State | |---|---| | Document model | Rust core, `crates/core/src/domain/sheet/schema.rs`, schema version 2, strict (`deny_unknown_fields`; reference URLs must be http or https at parse). Root: `species_id`, `name`, `description`, `scope_disclaimer` (FR/EN), `attribution`, `vertebral_config.regions` (ordered, `count`, optional `count_range`), `references`, annotation `categories`, `views` (one main, details with `parent_view_id`, own drawing or `view_box` crop), `annotations` (`point`, `zone`, `detail_trigger`; geometry circle, polygon or path, optional: an annotation without geometry draws nothing), `finding_zones` (categories of kind `dysfunction`, `consultation_reason`, `anamnesis`, `custom`; recursive nodes with `requires_vet_referral`, `reference_ids`). | | Element identity | Annotation ids are unique in the document. Finding category and node ids are unique among siblings only (`validate.rs` l.409-421): in the equine draft, the 811 categories and nodes share 310 distinct ids (`mechanical` appears 19 times). A finding element is identified by its path key `/` (`report/migration_map.rs`), which changes when a node moves. | | Review metadata | `review_status` (`inherited`, `reviewed`, `to_confirm`) on annotations, finding categories and nodes only. The field is `#[serde(default)]` with default `inherited` (`schema.rs` l.186-188, 427, 453, 553): an omitted status means `inherited`. Stored, read by no gate (SQL, app, PDF). | | 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, 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`). | | Access | `can_edit_sheet` (l.494-510) = creator of a non-deleted sheet, or any platform owner or admin on an official sheet; it gates every lifecycle RPC, the draft, version and asset policies and the Storage read. `can_use_sheet` (l.513-526) = active sheet and (`public` or editable); the sheet policy reads it (l.1183-1190). Editors update draft `content` and `change_note`, and sheet `name`, `slug`, `description`, by direct table UPDATE: no RPC, no audit, no concurrency check. | | Service role | The sheet migration revokes table privileges from `public, anon, authenticated` only (l.1157-1160); Supabase default privileges give `service_role` everything (`20261025100000_workspaces.sql` l.311-314, which revokes them for V1-1 tables). The service key is also a GoTrue admin credential. | | Platform roles | `platform_role`: owner, admin, moderator, support. DEV holds one owner. An owner may grant or revoke any role, owner included (`can_manage_platform_role`, `20261008100200_platform_roles.sql` l.83-95); `grant_platform_role` and `revoke_platform_role` check the caller's role, not its assurance level (l.189-238); the last owner cannot be revoked. No professional status (plan Step 9). | | Storage | Bucket `anatomical-sheet-assets`: private, SVG only, 20 MiB. Object key `.svg`, shared by every sheet that registers the same bytes. Read through `private.can_read_sheet_asset_object` (confirmed row, editor or non-draft version of a usable sheet). No write policy for API roles. The operator tool `pnpm assets:upload` (local stacks only) reads the asset table with the service key over PostgREST, writes `.svg`, re-hashes an existing object, and confirms (`crates/core/src/bin/upload_sheet_assets/storage.rs`). | | SVG reader | Hard rejections (`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, `too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`) and allowlist removals listed as `tag` or `tag@attribute` (`sanitize.rs`); `class`, `style` and font attributes are allowed except on the root (l.44, l.109-116, l.178-183). A drawing with any removal is refused at load, never repaired (`loaded.rs`, LRN-055). Typical vector-tool exports are therefore refused; the equine drawing passes because the R5 pipeline cleaned it (`curation/draft/drawing.rs`). | | Publication gate | Server: `publish_sheet_version` runs the SQL mirror and the unknown-asset check. Client: `packages/supabase/src/anatomical-sheets.ts` `publishSheetVersion` runs the core's `sheet.check`, then publishes. | | Application | No access to sheet tables. The report editor renders the bundled sheet (`SHEET_BUNDLE=draft` in the dev server and preview builds, `none` in a default build). Every sheet-bound core operation, `view.canvas` included, takes a `LoadedSheet` (`ops.rs` l.209), which requires a report migration map passed to the report and archive readers (`session.rs` l.85, l.120); drawing bytes are not checked against their sha256 at load. | | Archive caps | `SnapshotCaps`: 64 views, 1 024 annotations, 8 192 finding nodes (categories counted), depth 8, labels 512 UTF-16 units, 4 drawings, 2 MiB per drawing, 6 MiB in total. A PDF snapshot carries every view and every reachable drawing, so these caps bound any sheet that must stay exportable. `archive::SheetStatus` is `draft` or `published`, part of the strict snapshot contract. | | Entitlements | Plan Step 11 (plans, `entitlement_grants`, `has_active_entitlement`) is not built: no offer, plan or subscription exists in the model. | | MFA | TOTP enrolment and verification enabled server-side (up to 10 factors); `jwt_expiry = 3600` and no `[auth.sessions]` limit in `supabase/config.toml`; no `has_mfa()` helper, no enrolment UI (`IDENTITY.md` §4). Owner follow-up 7.10 (2026-10-12): MFA mandatory before any sensitive admin feature. | | Worker | Rust worker R1 (keyed job loop, keyless sandboxed decode child), built around avatars: the backend trait holds avatar operations (`backend.rs` l.82), the spawner expects a 512² WebP (`spawn.rs` l.160), child caps 5 MiB in and 512 KiB out (`limits.rs` l.6, l.8), RPC bodies capped at 1 MiB (`http.rs` l.18), a broken child stops the process (`run.rs` l.113), purges carry their bucket (`backend.rs`). It links no core module. `pnpm db:sandbox` starts no worker. Stopped on DEV (AVATAR-01): an avatar upload of the V1-1 acceptance waits in state `uploaded`, kept on the owner's decision, and the purge queue holds due rows (13 at the 2026-10-26 preflight). A worker started on DEV would process them. | | Seed | `equine_draft.sql` converges: it overwrites the draft's content whenever it differs and the sheet has one version, and inserts the sheet with `on conflict (id) do nothing`. It is listed for every environment (`SUPABASE.md` §3); outside local stacks it is applied by hand by the owner. The report editor's bundle reads the same seed folder. | | DEV data | 12 migrations. One sheet `503dc301-a8b1-50d4-9e44-0919b2fc2916` (equine, official, `private`, `active`, null creator, slug `faunosteo-cheval`, no current version), one version v1 `draft` (schema 2, content identical to the seed draft), one drawing row `7f767f74…` confirmed 2026-10-23, its object at `.svg`. Audit: `version.created`, `asset.uploaded`. | | Equine draft | 839 status-bearing elements: 28 annotations (22 points, 5 zones, 1 detail view link, all with a geometry), 81 finding categories, 730 nodes; 188 `to_confirm`, 31 `reviewed`, 620 `inherited`, of which only 219 statuses are written in `document.json` (the 620 `inherited` are omitted as the default). Also 2 views (`main`, `head`), 27 finding zones, 48 references, 5 vertebral regions, 5 annotation categories; scope disclaimer present in FR (521 characters) and EN (488). | | Design | The validated mockup (`docs/design/`) shows a sidebar entry « Fiches anatomiques »; no sheet screen and no administration screen are drawn. V1-1 built its client and animal screens from existing components without a new mockup. | --- ## 2. Scope In V1-2: 1. an administration space where habilitated staff list, filter and create official sheets, edit drafts (structured editor and minimal visual tool, §8.2), upload and clean drawings, preview, read the completeness report, submit to review, review, publish, deprecate and archive, with the full history; 2. a traceable review workflow with progressive reviews (§6.3), a server verdict computed by the Rust worker (§6.4) and an atomic publication gate; 3. explicit rights: three capabilities and a provisional catalogue access, granted by the owner, with MFA for every administrative operation (§5); 4. a read-only catalogue of published official sheets for accounts with catalogue access (§5.3); 5. loading of a stored version into the Rust core for preview, editing and catalogue, with integrity checks on the document, the fingerprint and the drawings; 6. hardening of the existing SQL lifecycle, and the Rust core as the only authority on document rules (§12.2); 7. new species created inactive by editors and activated by the owner (§7); 8. a working copy of the equine historical sheet and the preparation of its review, without publication (§14). Out of V1-2: personal and community sheets, sharing, follows, forks, marketplace, editing by students, rights scoped by species or by sheet, the level 2 editor (§8.3), the copy of a finding catalogue between sheets (O11), package export and import between environments (O13), a synchronous verification service (O15), review quorum (O5), e-mail notifications, species deactivation and deletion, authoring in production, the switch of the report editor to stored sheets and the link from bilans to versions (V1-3), storage of report migration maps (V1-3), offline cache (plan Step 16), professional verification (plan Step 9), entitlements and offers (plan Step 11), deletion of Storage objects (one audited exception: §9.3), and the publication of any equine sheet (an owner act after the business review, never inside V1-2). Consequences of the deferrals. None of them is needed by the fundamental journey. Without packages (O13), content prepared on one stack never moves to another: the sandbox serves the tests and rehearsals, DEV becomes the authoring stack after the closure, and authoring for production (a production stack, a running worker, either authoring there or a package import that preserves ids) is decided before any production use. Without a catalogue copy (O11), each new species' finding catalogue is entered by hand from cited sources. --- ## 3. Nomenclature | FR (UI) | EN (UI) | Code | |---|---|---| | Fiche anatomique | Anatomical sheet | sheet | | Fiche officielle | Official sheet | `is_official` | | Fiche historique (« pipeline Git » in a tooltip if needed, 2026-11-02) | Historical sheet | the equine sheet `503dc301…` (§14.2) | | Copie de travail | Working copy | `working_copy_source_version_id` (§14.3) | | Version : brouillon, publiée, retirée | Version: draft, published, withdrawn | `draft`, `published`, `deprecated` | | Revue, soumission | Review, submission | review round (§6.3) | | Vérification en cours, à relire, approuvée, modifications demandées, soumission retirée, vérification échouée | Verifying, awaiting review, approved, changes requested, submission withdrawn, verification failed | round status `verifying`, `open`, `approved`, `changes_requested`, `withdrawn`, `verification_failed` | | Groupe de revue, groupe lu | Review group, group read | review group, acknowledgment (§6.3) | | Accès au catalogue | Catalogue access | right `catalog_reader` (§5.3) | | Habilitation | Permission (owner, 2026-11-02, BDR-097: `capability` stays the technical term) | right `sheet_editor`, `sheet_reviewer`, `sheet_publisher` (§5.2) | | Relecteur ou relectrice | Reviewer | `sheet_reviewer` | | Éditeur de fiches | Sheet editor | `sheet_editor` | | Responsable de publication | Publisher | `sheet_publisher` | | À confirmer, relu, hérité, non relu | To confirm, reviewed, inherited, not reviewed | `to_confirm`, `reviewed`, `inherited` | | Complétude | Completeness | verdict counts (§6.4) | | Illustration | Drawing | asset row + Storage object | | Vue principale, vue détaillée | Main view, detail view | `main`, `detail` | | Point, zone, accès à une vue détaillée | Point, zone, detail view link | `point`, `zone`, `detail_trigger` | | Catalogue des constats | Finding catalogue | `finding_zones` | | Empreinte | Fingerprint | `sha256-rfc8785-validated-v1` | | Clé d'élément | Element key | §6.6 | Routes and the labels of this table are ratified (O16), with « Hérité, non relu » / « Inherited, not reviewed » for `inherited`. The labels added by this revision for the states of O17, O21 and O23 and the route `/app/admin/species` (O9) follow the same convention and are confirmed on the V1-2.4 wireframes (approved by the owner on 2026-11-02, §17.9). Every failure code, round state and validation code has an FR and an EN message (§6.5, §15). --- ## 4. Decisions D1 to D9 Owner orientations, approved (BDR-081). The column « Contract » says where each one becomes rules. | Id | Owner orientation (summary) | Contract | |---|---|---| | D1 | Official publication is reserved to habilitated platform administrators. Business validation is identified and traced separately from the technical act of publishing. `platform_role` is never a professional status. | §5.2 capabilities, §5.5 separation, §6.3 rounds | | D2 | No official publication while blocking `to_confirm` items remain. `to_confirm` never becomes `reviewed` automatically. Completeness rules and validation conditions are defined. | §6.6, §6.7 (O3 B: `inherited` blocks too) | | D3 | Official drafts are visible only to administrators, editors and explicitly authorised reviewers. Ordinary practitioners never see a sheet in preparation. The equine sheet stays a draft. | §5.2, §5.3 row predicate, §9.4, §10, §14 | | D4 | Published official sheets are readable by authenticated, authorised users whatever their workspace, under the retained RLS. Reading is separate from editing. | §5.3 catalogue access (O21), §5.4 | | D5 | At launch, creating official sheets and the related administration is reserved to habilitated administrators. Personal and community sheets are not opened in the MVP. | §5.4, §12.3 M4 | | D6 | A traceable review before official publication identifies the draft's authors, the submitter, the reviewers, the decisions and comments, the publisher, and the exact version validated. A simple but really usable review interface. | §6.3, §11 journeys R1, A6 | | D7 | The report editor keeps working as today during V1-2. Loading published versions from Supabase is prepared; the switch and the adaptation of bilans are framed in V1-3. The readers of historical data are not modified early. | §10 | | D8 | Published versions are immutable; changing a published sheet creates a new draft. Versions referenced by bilans stay readable by authorised users after archiving or a newer publication, never exposed to users without the needed permissions. | §6.8, §6.9, §9.4, F13 | | D9 | Administrators create, read, edit, version and prepare the publication of official sheets from the application, for any species, without editing the database or the project sources. Rust stays the validation authority; no divergent schema copy. | §7, §8, §9, §11, §12.2 | Reading of D3 and D9 retained by O1: « administrators » means habilitated administrators, that is a platform owner or admin holding the matching capability. A platform admin without a capability sees no draft. --- ## 5. Access, roles and permissions ### 5.1 Layers Each layer is checked on the server; none implies the next. | Layer | Established by | Gives | |---|---|---| | Authentication | a Supabase Auth session | nothing by itself | | Email confirmation | `email_confirmed_at` | proves control of a mailbox; a precondition of every right below, never a proof of competence | | Catalogue access | `private.can_read_official_catalog(uid)` (§5.3) | the catalogue list and the current published versions | | Historical reads | the same predicate (O8) | published and deprecated versions by id, archived sheets included | | Draft reads | a capability and `aal2` | drafts, rounds, verdicts, comments, history, drawings of drafts | | Capabilities | `anatomical_catalog_grants` (§5.2) and `aal2` | edit, review, publish, per the matrix of §5.4 | | Platform role | `profile_roles`, changed only with `aal2` (§5.7) | a precondition of `sheet_editor` and `sheet_publisher`; no catalogue right by itself | | Professional status | plan Step 9, not built | none; never inferred from a right or a role | | Workspace membership | V1-1 tables | none: no catalogue rule reads workspace tables and no V1-1 rule reads catalogue tables | ### 5.2 Capabilities (O1 A + D) Three explicit, independent capabilities: `sheet_editor`, `sheet_reviewer`, `sheet_publisher`. They live in `anatomical_catalog_grants` (M4) with the provisional catalogue access of §5.3, one row per grant: | Column | Meaning | |---|---| | `user_id`, `grant_kind` | the account and the right (`sheet_editor`, `sheet_reviewer`, `sheet_publisher`, `catalog_reader`) | | `reason` | required motive, 1 to 1 000 characters | | `verification_note` | required for the three capabilities: the qualification declared and what the owner verified, 1 to 1 000 characters (for `sheet_reviewer`, the professional elements the owner checked; never a certification) | | `granted_by`, `granted_at` | the platform owner, the time | | `expires_at` | optional end; later than `granted_at`; the administration form sends the last millisecond of the chosen day in Europe/Paris (§17.11) | | `revoked_by`, `revoked_at`, `revocation_reason` | set once by a revocation, reason required | - Writes: `grant_catalog_right(user_id, kind, reason, verification_note, expires_at)` and `revoke_catalog_right(grant_id, reason)`, platform owner with `aal2`, audited with every field. Rows are never updated otherwise and never deleted; a renewal is a new row. One active row per account and kind. - Active grant: not revoked, and no `expires_at` or `expires_at` in the future, read at every request. - Eligibility, checked at grant and at every use: active profile and confirmed email for every kind; for the three capabilities, a verified TOTP factor at grant time, so a capability is never handed to an account whose first factor anyone holding its password could still enrol; an active platform role owner or admin for `sheet_editor` and `sheet_publisher`. A reviewer need not hold any platform role: partner veterinarians and 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. 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, not grants: separation of duties per round (§5.5), the protected historical sheet (§14.2), the frozen draft (§6.1), one draft per sheet. - Expiry and revocation take effect at the next request: - an editor loses draft reads and writes; the saves already made stay in the author sets (history); - a reviewer's acknowledgments and approvals count only while the reviewer holds an active grant, checked at approval and at publication; a renewal makes them count again; while they do not count, publication answers `publish.approval.invalid` and the round stays `approved` until an editor withdraws it or the grant is renewed; published versions are untouched; - a publisher can no longer publish, deprecate or archive. - The rights screen shows active, expiring (within 30 days), expired and revoked grants with their reason and verification note. No e-mail in V1-2. Predicates (M4), kept apart so no check tests the wrong account: - `private.grant_active(uid, kind)`: the grant and its eligibility, without any assurance level; used for stored actors (acknowledgers, approver). - `private.caller_has(kind)`: `grant_active(auth.uid(), kind)` and `has_mfa()`; used for the calling session. `private.can_edit_sheet` is redefined for official sheets (M4) on `caller_has('sheet_editor')`: owner and admin without the capability lose draft reads, lifecycle RPCs and draft drawing reads. Every predicate built on it inherits the change, and pgTAP proves « admin without capability refused » for each RPC and policy (§15). ### 5.3 Catalogue access (O21) Reading the published catalogue is a right of its own, distinct from authentication, from email confirmation, from the capabilities and from any platform role. - Predicate `private.can_read_official_catalog(uid)`, provisional and fail-closed: active profile, and confirmed email, and (an active `catalog_reader` grant or an active capability). Anything unknown or missing answers false. Platform roles grant nothing by themselves. - `catalog_reader` grants follow §5.2 (owner only, reason required, verification note and verified factor not required, expiry optional, audited, no `aal2` needed to use them). - Row predicate for readers, the same on sheets, versions, asset rows and Storage objects: an official, non-deleted sheet with at least one published or deprecated version, and `can_read_official_catalog`. The `visibility` branch of `can_use_sheet` is dropped from every catalogue predicate. A sheet that only has a draft, and an inactive species' id through it, are invisible to readers. Reader column grants exclude `last_version_number`, `updated_at` and `working_copy_source_version_id`. - The predicate gates the catalogue list, the published and deprecated versions by id, archived sheets included (O8), and their drawings. - Screens (owner, 2026-11-02, BDR-094): a signed-in account without the right sees no « Fiches anatomiques » entry in the sidebar or the drawer; a direct URL under `/app/anatomy` shows a page « Accès non autorisé » with an explanation and a link back to `/app`, the same whether the sheet exists or not. A visitor who is not signed in goes to `/login?next=` (`RequireAuth`), never to that page. The hidden entry protects nothing: the predicate, the capabilities and RLS decide. The entry's visibility may read the caller's own grant rows (select policy `user_id = auth.uid()`); the page acts on the server's answer, never on that hint. - Definitive rights belong to the entitlement engine of plan Step 11 (offers, `has_active_entitlement`), which does not exist. Nothing in V1-2 simulates it. Switch conditions: Step 11 ships a catalogue capability (proposed name `catalog.read`, added to the Step 11 capability catalogue); an owner decision then sets the predicate to (entitlement or capability), says what becomes of the provisional `catalog_reader` grants, and comes with its own pgTAP matrix. If V1-3 needs every practitioner to load sheets before Step 11 exists, V1-3 decides between provisional grants per practitioner and building Step 11 first. - Tests (pgTAP, §15): anonymous, authenticated unconfirmed, confirmed without grant, expired and revoked `catalog_reader`, deactivated, platform admin, moderator and support without grant: refused; `catalog_reader` and capability holders: allowed; a draft-only sheet invisible to every reader. ### 5.4 Matrix R = catalogue reader (§5.3, without capability), E = sheet editor, V = sheet reviewer, P = sheet publisher, O = platform owner acting as owner (rights, species activation and renaming). A person may hold several rights; the owner acts on sheets only through capabilities it granted itself. Every operation except the first two lines requires an `aal2` session (§5.6), in RPCs and in the table and Storage policies alike. | Operation | R | E | V | P | O | |---|---|---|---|---|---| | List the catalogue, read the current published version | yes | yes | yes | yes | no | | Read a published or deprecated version by id, archived sheet included | yes | yes | yes | yes | no | | Read drafts, rounds, verdicts, comments, history, drawings of drafts | no | yes | yes | yes | no | | List catalogue species, active and inactive | no | yes | yes | yes | yes | | Create an inactive species, edit an inactive species' names and order | no | yes | no | no | no | | Activate a species, correct an active species' names | no | no | no | no | yes | | Create an official sheet, a working copy (§14.3), a draft; save; register and upload drawings; delete a draft without rounds | no | yes | no | no | no | | Submit a draft, withdraw a submission | no | yes | no | no | no | | Comment a round | no | yes | yes | yes | no | | Acknowledge review groups, approve or request changes (never as an author, §5.5) | no | no | yes | no | no | | Publish an approved round, deprecate a version, archive and restore a sheet | no | no | no | yes | no | | Grant and revoke rights | no | no | no | no | yes | | Create a personal sheet, fork, change visibility | closed in V1-2 (D5) | Moderator, support, unconfirmed, deactivated and anonymous accounts, and platform admins without a right: nothing. Service role: only the worker RPCs of §6.4, the upload confirmation and the narrow read RPC of the operator tool (§9.5); no table privilege on any catalogue table (F12, §12.1). ### 5.5 Separation of duties (O2 A) and the first publication - The author set of a draft is maintained by a trigger: the account that created the draft version (new sheet, working copy or draft from a published version) and every account that changed its content since. It is frozen into the round at submission and checked on the server. - No member of a round's author set acknowledges a group of that round or approves it. - A content write without an authenticated actor is refused for every sheet except the historical sheet (§14.2), so no write escapes the author set. - A save whose content equals the stored content is refused (no revision bump), so an empty save cannot move authorship. - Publication needs `sheet_publisher`; the publisher may be an author or the approver. Two distinct people suffice: one who wrote the draft, one habilitated to review and approve it. - 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 path is not silent, since the grant, its reason and verification note, and every acknowledgment and decision are audited and shown on the round, but it cannot be detected technically until professional verification exists (plan Step 9). First publication with one owner and one business reviewer (journey A0, then A1 to A6): 1. The owner enrols two TOTP factors, steps up, grants itself `sheet_editor` and `sheet_publisher` with a reason. 2. The business reviewer signs up, confirms the e-mail address and enrols a TOTP factor; the owner then grants `sheet_reviewer` with a reason, a verification note and possibly an expiry. 3. The owner creates the sheet, edits, uploads, saves and submits; the worker verifies the revision; the round opens. 4. The reviewer reads and comments, over as many rounds as needed (§6.3); the owner applies the answers and marks the read groups; the reviewer acknowledges every group, then approves with a note. 5. The owner publishes the approved round. ### 5.6 Strong authentication (O4 A) - `private.has_mfa()` reads `(auth.jwt() ->> 'aal') = 'aal2'`. Through `caller_has` it is required by every catalogue RPC except the reader RPCs, by the capability branches of the version, round, comment, acknowledgment and asset policies and of the Storage read, by the rights RPCs, by the species RPCs and by the working copy. The reader branches never read it. - Enrolment (V1-2.5, Mon compte, Sécurité): add a TOTP factor (QR code, the secret shown once and never stored or logged by the application), verify it with a code (a factor counts only once verified), name, list and remove factors. GoTrue v2.197.0 requires `aal2` to enrol a factor once one is verified and to remove a verified factor (§5.7.3, from its source). V1-2.5 proves that an `aal1` session of an account with a verified factor can neither enrol another factor nor remove one; if the sandbox shows otherwise, the step stops for an owner decision, since MFA would then be bypassable with the password alone. - Step-up: entering `/app/admin` with an `aal1` session opens the challenge; success upgrades the session; no admin data is requested before. - Sessions: `aal2` belongs to the session. A token refresh keeps it, sign-out ends the session (an access token already issued stays valid until `jwt_expiry`), a new sign-in starts at `aal1` (Supabase behaviour, proven by a V1-2.5 browser test). The access token lives `jwt_expiry` (3 600 s in the local configuration; V1-2.1 records the values of the sandbox and DEV). No session time box or inactivity limit is configured, and V1-2 adds no freshness window: a stolen `aal2` session stays usable until it ends (residual, §13). V1-2.5 records what removing a factor does to the account's other open sessions. - Loss of a factor: Supabase Auth issues no recovery codes. The owner enrols two factors on two devices before the first grant on any stack. Another account that loses its factor keeps its `aal1` access (catalogue, rest of the application) and loses the administration until recovery. - Recovery is an operator procedure, never an application feature: no RPC, screen or service path resets another account's factor, so recovery opens no application back door. Steps: 1. the owner confirms the requester's identity out of band and records the reason; 2. the owner revokes the account's capabilities (§5.2); 3. an operator with server access signs out every session of the account and deletes the factor (Supabase admin API with the service key on the server, or SQL on the database container for DEV), and in the same session writes the audit row `auth.mfa_factor_reset` through `private.log_event` (null actor, subject, reason, operator named in the detail); 4. the person enrols a new factor; the owner grants the capabilities again. The owner's own loss follows the same procedure, run by the owner at the server. The runbook goes to `IDENTITY.md` and is rehearsed on the sandbox in V1-2.9. - Platform roles (AR-1 B, ratified 2026-10-28): `grant_platform_role` and `revoke_platform_role` require `aal2` for every platform role; see §5.7. The earlier option O4-D, left unratified by O4, is superseded by that arbitration. ### 5.7 Platform role changes and MFA (AR-1 B) Ratified by the owner on 2026-10-28 (BDR-083). It completes the security contract of O4; it replaces none of O1 to O23. **Rule.** Every grant, revocation, replacement, promotion, demotion or equivalent change of a platform role (`owner`, `admin`, `moderator`, `support`) requires a valid `aal2` session, checked on the server when the operation runs. A hidden button is not a control. There is no exception for the owner, the first administrator, accounts already privileged, older accounts, the administration screens or direct RPC calls; the only path without a session is the audited operator path outside the application (§5.7.5), used for a bootstrap or a recovery. `aal2` is necessary and never sufficient: `can_manage_platform_role`, the self-target refusal and the last-owner guard still apply. Ordinary accounts are not asked for MFA; the requirement covers the operations of this contract (platform roles, catalogue rights, catalogue administration, protected drafts, review, publication). Reading the published catalogue follows O21. **The flaw and the chain it closes.** `grant_platform_role` and `revoke_platform_role` check the caller's role, not its assurance level: 1. an attacker learns the password of an owner; 2. they open a session, which is `aal1`; 3. they call `grant_platform_role` directly and give `owner` or `admin` to an account they control (or revoke the real owner); 4. that account enrols its own TOTP factor (a first factor is enrolled at `aal1`) and reaches `aal2`; 5. it grants itself `sheet_editor`, `sheet_reviewer`, `sheet_publisher` (§5.2) and reviews and publishes official sheets. With AR-1 B, step 3 is refused with no write, so steps 4 and 5 never start. **Why B and not A.** A (owner and admin only) leaves `moderator` and `support` changeable from a password-only session. They give no catalogue right today; `support` opens staff reads (`profiles_select_staff`), and any future role-based rule would inherit a weak path; revoking them is also a nuisance attack. B costs the same one predicate and removes the list of roles from the rule. **Inventory of the paths that change platform privileges** (read from the migrations and `seed.sql` on 2026-10-28; V1-2.1 re-runs the census in pgTAP 001): | Path | Who may call it today | Controls today | Added by M4 | Audit | |---|---|---|---|---| | `public.grant_platform_role(target, role)` | `authenticated` (and `service_role`, which fails at `auth.uid()` null) | authenticated, not self, `can_manage_platform_role` (owner: any role; admin: moderator and support), not already active | `has_mfa()` as the second check; `EXECUTE` revoked from `service_role` | `platform_role.granted` | | `public.revoke_platform_role(target, role, reason)` | same | same, plus the last-owner guard | same, plus the guard made race-free (F18) | `platform_role.revoked` | | `private.assign_platform_role`, `private.withdraw_platform_role` | no API role (`EXECUTE` revoked from public, schema `private` not exposed); RPCs above and privileged SQL sessions | none of their own | a non-null actor must equal `auth.uid()` and pass `has_mfa()`; a null actor is accepted only when the request carries no JWT (`auth.role()` null), so neither an API session nor `service_role` reaches the operator path (§5.7.5) | same events | | `private.can_manage_platform_role` and the `has_platform_role` family | predicates, no write | n/a | unchanged; `is_platform_*` do not read the assurance level (policies that use them for reads are out of AR-1, see reserves) | none | | table `public.profile_roles` | `authenticated`: SELECT only, no write policy; `service_role`: default table privileges never revoked (F17) | RLS, privileges | `REVOKE ALL` from `service_role` on `profile_roles` and `profiles` (F17) | none | | `profiles.active` (deactivation changes who counts as a role holder) | no user path: not in the column grant of UPDATE | column grants | F17 covers `service_role` | none | | triggers and `handle_new_auth_user` | none writes `profile_roles` | n/a | census asserts it stays so | none | | `seed.sql` bootstrap (`assign_platform_role(null, ...)`) | local stacks, privileged SQL | none | unchanged, local only (§5.7.5) | `platform_role.granted`, null actor | | deletion of an auth user (cascade `on delete cascade` to `profile_roles`) | GoTrue admin API with the service key | none | operator procedure only (§5.7.5) | auth log | | `grant_catalog_right`, `revoke_catalog_right` (M4, §5.2) | owner | owner, `aal2` | already `aal2` | per §5.2 | No other path reachable from a user session was found: PostgREST exposes the `public` schema only, and every write to `profile_roles` goes through the two RPCs. A claim that this closes service-key abuse would be false: see §5.7.5. **Order of checks in both RPCs** (M4), all before any write: 1. `auth.uid()` is not null; 2. `has_mfa()`; otherwise a refusal with the closed kind `mfa_required`; 3. the caller is not the target; 4. `can_manage_platform_role`; 5. the operation is valid: target exists and is active; for a grant, the target holds a verified factor (the eligibility predicate of §5.2), so no role lands on an account whose first factor a password or mailbox holder could still enrol; role not already active, or active for a revocation; last active owner kept; 6. the write and its audit row, in the same transaction. The assurance check comes before the role checks so that a password-only session gets the same answer whatever role it holds: no oracle on who is owner or admin. A refusal raises, so it leaves no row (neither the role nor an audit row); attempted escalations are therefore visible in the API logs, not in the audit table. With `[analytics] enabled = false` a raised refusal reaches the PostgreSQL log only (residual). Returning the refusal as a closed kind after a committed `log_event` is an option V1-2.1 may propose, not a decision taken here. **Race on the last owner (F18).** `withdraw_platform_role` counts owner rows without a lock and without `profiles.active`, so two simultaneous revocations of two owners can both pass and leave none (or only a deactivated one). M4 takes one transaction-scoped advisory lock at the start of both RPCs and of the private functions, before checks 3 to 5, and counts owners with the `has_platform_role` semantics (active profile). Two-session tests: mutual revocation, revoke against grant. #### 5.7.1 First enrolment and the bootstrap of the first owner GoTrue v2.197.0 (the image pinned by the local stack; source read on 2026-10-28, behaviour to be proven on the sandbox by V1-2.5): `EnrollFactor` refuses with `insufficient_aal` when the user already has a verified factor and the session is not `aal2`. With no verified factor, a first factor is enrolled from an `aal1` session. Enrolling, verifying and reaching `aal2` are three steps: a factor counts once verified, and verification upgrades the session and invalidates the user's sessions below `aal2`. Ordinary journey: password sign-in (`aal1`) → Mon compte, Sécurité → enrol TOTP → verify with a code → `aal2`. Enrolling a factor grants no role and no capability; MFA is a condition, never a substitute for the checks of §5.2 and §5.7. New environment (no owner, no `aal2` session anywhere), in this order, never the reverse: 1. the operator creates the account through the sign-up path or the admin API, email confirmed, and hands over the initial secret out of band; 2. the future owner signs in, enrols two TOTP factors on two devices and verifies both; no role exists yet, so nothing is at stake in the window; 3. the operator checks, read-only, that the account has verified factors and that their names and creation times match what the owner did; 4. only then the operator assigns the owner role from a privileged SQL session (`assign_platform_role(null, ...)`) and records, in the same session, an audit row with the reason and the operator's name through `private.log_event`; 5. the owner signs in again, passes the step-up, and proves an `aal2` call works and an `aal1` call is refused. No public RPC creates an owner, none disables MFA, and no permanent bypass exists. The `seed.sql` bootstrap (role assigned before any factor, known password) is a local-fixture exception to this order, acceptable only on a stack no untrusted party can reach (§5.7.2). Assigning the role last is what closes trust on first use for the owner account. #### 5.7.2 DEV: preconditions of the future transition The DEV owner is the seed account, it has no factor, and nothing changes on DEV during V1-2.0. Two facts of DEV defeat AR-1 B as long as they hold: - the stack signs tokens with the Supabase CLI's public default JWT secret, its `service_role` key is the public demo key, and port 54321 is open to the LAN (`ENVIRONMENTS.md` §3.6, risk accepted by the owner on 2026-10-24 « before any untrusted device or user »). Anyone on the network can mint an `aal2` token for the owner, or act as `service_role`; `has_mfa()` proves nothing there; - the owner account's password is the seed's, committed in Git. So, before the owner applies M4 on DEV or makes the first grants (§16.11): 0. the §3.6 hardening is done (own JWT secret or signing keys, or 54321 narrowed to the test devices; the owner's choice), and the seed owner's password is changed, or a separate owner is bootstrapped per §5.7.1 and the seed owner revoked; every active `profile_roles` row of DEV is listed, and each holder enrols and verifies a factor before M4 or loses the role; 1. read-only check of every factor of each role holder, verified or not (an unknown one is deleted, and an unknown verified one means a reset first, §5.7.7); 2. the owner enrols two factors and verifies both from the branch's Mon compte; this needs no migration, and until M4 is applied every existing right is unchanged; 3. on the sandbox rehearsal of M4 from the DEV state, `aal2` is shown to work and `aal1` to be refused for the same account; 4. the recovery of §5.7.7 has been rehearsed on the sandbox; 5. a backup exists. Any `db:reset`, or `db:start` on a fresh volume, of DEV after M4 reruns the seed and reopens these preconditions. A failed transition is never a lockout: an owner without a verified factor still signs in and uses the application at `aal1`, only role and rights management waits, and the first factor can always be enrolled at `aal1`. #### 5.7.3 Additional, removed and replaced factors Native behaviour of GoTrue v2.197.0 (source read, V1-2.5 proves it; measured on the sandbox: `IDENTITY.md` §4.1, V1-2.5): - a second factor: `EnrollFactor` needs `aal2` once a verified factor exists (403 `insufficient_aal`). A stolen password therefore cannot add a factor; - removing a verified factor: `UnenrollFactor` needs `aal2` (422 `insufficient_aal`); an unverified factor can be removed from `aal1`. An unverified factor gives no `aal2` until verified, so a dormant one left by an earlier password holder is a path: factor checks list unverified factors too, and V1-2.5 tests a dormant factor verified later (GoTrue appears to delete unverified factors of the same type on verification; not assumed). Assumption: TOTP is the only enabled factor type; - removing the last factor: allowed from `aal2`. The account then returns to the first-factor case, where an `aal1` session can enrol; a role holder in that state keeps the role (residual, §13). A stolen `aal2` session can therefore replace factors; this is the stolen-session residual (§5.7.8), not a bypass from the password alone; - GoTrue downgrades the sessions of a removed factor to `aal1` (`DowngradeSessionsToAAL1`); its exact scope and the lifetime of already-issued access tokens are recorded by V1-2.5, not assumed; - freshness: tokens carry `amr` entries (method and time), so a recent-TOTP check on the rare role RPCs is technically possible; adopting it is an owner choice under O4, not part of this contract (§5.7.9). If the sandbox shows `aal1` can enrol a second factor or remove a verified one, V1-2.5 stops for an owner decision (as §5.6 already says). It did not fire (`IDENTITY.md` §4.1). #### 5.7.4 Password change and reset A reset or change of password yields an `aal1` session. For an account with a verified factor it cannot add or remove a factor (§5.7.3) and cannot change a platform role (rule above). For an account without a verified factor, the reset lets whoever holds the mailbox enrol a first factor: this is the accepted first-factor case, harmless while no role or capability is held, and the reason the owner role is assigned after enrolment (§5.7.1) and a capability only to an account with a verified factor (§5.2). Email change and identity linking stay as configured (`enable_manual_linking = false`); V1-2.5 adds a test that none of them raises a session to `aal2` (measured on the sandbox: `IDENTITY.md` §4.1, V1-2.5; with a verified factor, a password change or reset is itself refused at `aal1`, so the recovery screens step up first). #### 5.7.5 Operator path The technical paths are the service key (RLS bypass and GoTrue admin) and a privileged SQL session on the database container. They are not exceptions usable from the application: the app never holds the service key; the worker holds it and can call worker RPCs only; the role RPCs refuse `service_role` (no `auth.uid()`, and `EXECUTE` revoked in M4). Each use is an owner-authorised operation (§16.11), written down with its reason, and leaves an audit row (`private.log_event`, null actor, operator in the detail) in the same session. #### 5.7.6 Actors | Actor | Can change platform roles | Note | |---|---|---| | Ordinary account | no | no MFA requirement for ordinary use | | Owner or admin at `aal1` | no | refused at check 2 whatever the role | | Owner or admin at `aal2` | within `can_manage_platform_role` | admin: moderator and support only | | Moderator or support at `aal2` | no | `aal2` is not sufficient | | Worker | no | worker RPCs only (M6) | | `service_role` key holder | not through the RPCs; yes through GoTrue admin and SQL | outside MFA, §5.7.5 and §13 | | Operator SQL session | yes | audited by procedure, not by the database | #### 5.7.7 Recovery Complements the procedure of §5.6, which stands (operator only, out-of-band identity, reason recorded, no RPC, no screen). - Lost phone, account with other factors or another admin: the person uses the second factor. A person whose only factor is lost follows §5.6 steps 1 to 4. - Loss of every factor of the last owner: no application path exists, by design. On a single-owner platform the operator is the owner acting at the server, and the real control is server access, not a second person. Order: 1. the operator signs out every session, deletes every factor (verified or not), bans the account and writes the audit row `auth.mfa_factor_reset`; 2. with the owner present, the operator sets a new password with the owner and lifts the ban; 3. the owner signs in at once, enrols and verifies two factors; 4. the operator lists every factor of the account; any it does not recognise sends the procedure back to step 1. The owner role and the owner's capabilities stay in place: inert at `aal1`, since `caller_has` and the role RPCs need `aal2`. Nothing is re-granted. (For another account, §5.6 step 2 applies: the owner revokes its capabilities first.) - Return to a safe state: `aal2` proven and `aal1` refused again on that account; the audit rows exist; no temporary bypass was left. - Rehearsed on the sandbox in V1-2.9; the runbook goes to `IDENTITY.md`. Secrets (QR codes, TOTP seeds) never go in Git, documents, logs or tickets. Prevention: two factors on two independent devices for every owner. #### 5.7.8 Sessions, tokens and stale rights - Roles and capabilities are read from the tables at every call; the project adds no claim to the JWT (no access-token hook), so a revoked right or role is refused at the next call whatever the token says. - The `aal` claim lives as long as the access token (`jwt_expiry`, 3 600 s locally). For the role and rights RPCs only (rare, administrative), V1-2.1 adds a check that the session named by the token's `session_id` still exists in `auth.sessions` at `aal2`. The columns and the claim are verified on the pinned image first; if one is missing, V1-2.1 stops for an owner decision (claim alone with the residual of up to one token lifetime after a downgrade, or another check). Nothing here is assumed present. - A stolen `aal2` session is a distinct risk this design does not remove: it keeps working until it ends. Reducing it (freshness window, session limit) is not part of V1-2. - Concurrent role changes: unique active row per (user, role), lock on the owner count (F18), one transaction per write. #### 5.7.9 Reserves recorded, not decided - `is_platform_admin` and the staff read policies (`profiles_select_staff`, `audit_logs_select_admin`) do not read the assurance level. AR-1 B covers changes of roles, not those reads; IDENTITY.md §4 foresaw folding `has_mfa` into them. Left for an owner decision; V1-2.1 does not change them. - Refused escalation attempts are not in the audit table (§5.7 order of checks). - A recent-TOTP freshness check on the role RPCs through `amr` (§5.7.3). - The DEV hardening of `ENVIRONMENTS.md` §3.6 becomes a precondition of M4 on DEV (§5.7.2 step 0); the owner chooses its form. --- ## 6. Lifecycle, review, verification and publication ### 6.1 States Versions keep their three statuses. Rounds are separate rows, so the version enum and its immutability stay untouched. ``` version: draft ──publish──▶ published ──deprecate──▶ deprecated round (on a draft): submit ──▶ verifying ──verdict passed──▶ open ──approve──▶ approved ──publish──▶ (version published) │ └──request changes──▶ changes_requested └──verdict failed, or unavailable──▶ verification_failed verifying | open | approved ──withdraw──▶ withdrawn ``` - While a round is `verifying`, `open` or `approved`, the draft content is frozen (trigger, every role, seed included). The terminal states (`changes_requested`, `withdrawn`, `verification_failed`) unfreeze it; a published round stays `approved` and is referenced by the version. - One non-terminal round per draft at a time. A change after approval needs a withdrawal, which voids the approval; the next submission opens a new round. - A draft that has rounds cannot be deleted (foreign key `restrict`), so the D6 trail survives. - Every lifecycle RPC locks in one order: sheet, then version, then round. Deadlock and serialization errors map to a closed, retryable failure. ### 6.2 Drafts and saving (O12 A) - A draft is created from the empty document (§7.4), from an earlier version of the same sheet (`create_sheet_draft`), or by the working copy (§14.3). Its base (`source_version_id`) is set only when the source is a `published` version with a `published_review_id`, that is a version published through a V1-2 round; any other source (deprecated, published before M5, working copy, empty document) gives no base, and every group is to cover (§6.3). - Unsaved changes stay in the page. The leave guard of V1-1 protects them; a local recovery copy, keyed by account and version with the revision recorded in the copy (wording matched to the code at V1-2.6 U0, §17.12), is kept in the browser with the report editor's persistence pattern and offered back after a crash or an expired session, never sent automatically. - Validation while editing: the page runs the core's checks and shows the validation panel (§8.1). It is advisory; the server verdict decides (§6.4). - Saving is explicit (« Enregistrer »): `save_sheet_draft(version_id, 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, 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; the verdict refuses them at submission. - From V1-2.6 U6 (owner 2026-11-05, §17.12; not built yet), the save also applies the declared fixed-category check of §12.2: no role carried by two categories, a category carrying a role keeps that role's fixed names, no role of the stored draft lost. A draft that carries no role (every draft saved before U6, the equine working copy) still saves. - A trigger bumps `revision` on any content write, so no write slips under a round unseen. - The direct UPDATE grants on `content`, `change_note`, `name`, `slug` and `description` are revoked (M4). The sheet row's `name` and `description` are set at creation and refreshed from the document at publication; the catalogue shows the published document's FR and EN texts (§10). The slug is set at creation and never shown in routes. - Concurrency: a stale `expected_revision` answers `draft_conflict`. The page shows the server revision with its author and time and offers « recharger » or « garder ma version »; the second saves the local document on the new revision after an explicit confirmation naming what it replaces. Nothing is overwritten silently. - A per-actor write budget follows V1-1 D15 (thresholds in V1-2.1). ### 6.3 Review rounds, review groups and acknowledgments `anatomical_sheet_reviews` (M5), one row per round: | Column | Meaning | Set in | |---|---|---| | `version_id`, `round` | the draft and the round number | every state | | `revision` | the revision submitted; with the freeze, `(version_id, revision)` is the « exact version » of D6 | every state | | `authors` | the author set of §5.5, frozen at submission | every state | | `submitted_by`, `submitted_at`, `submission_note` | the submitter | every state | | `status` | §6.1 | every state | | `attempts`, `lease_token`, `locked_at` | the verification job (§6.4) | while `verifying`; kept after | | `verdict`, `verified_at`, `verified_with` | the server verdict for this revision, written by the worker RPC only | `open`, `approved`, `changes_requested`, and `verification_failed` with outcome `failed` | | `failure_outcome`, `failure_code` | `failed` or `unavailable` and the closed code (§6.5) | `verification_failed` | | `decided_by`, `decided_at`, `decision_note` | the approver or the reviewer who requested changes; the note is required | `approved`, `changes_requested` | | `withdrawn_by`, `withdrawn_at`, `withdrawal_note` | the editor who withdrew | `withdrawn` | Review groups. The verdict splits the document into groups: - `general`: names, description, scope disclaimer, attribution, references, vertebral regions, annotation categories; - `view:`: the view and the annotations located in it; - `zone:`: the finding zone, its categories and nodes; - removal groups: a `view:` or `zone:` group of the base absent from the draft, whose content is « removed ». The equine draft has 30 groups (general, 2 views, 27 zones). Each group gets a digest: the sha256 of the canonical JSON of its elements, statuses included, with absent statuses written out; a removal group gets a digest of its removal. Groups to cover (the one coverage rule): every group when the draft has no base; for a derived version, every group whose digest differs from the base's group of the same key, removal groups included. A group equal to its base holds only elements the base's approved round covered. Acknowledgments (`anatomical_sheet_review_acknowledgments`, M5, append-only): - A reviewer outside the round's author set records « groupe lu » for one group of an `open` round, against the verdict's digest of that group. A group that still holds a `to_confirm` or `inherited` element cannot be acknowledged: there is nothing to approve in it yet. - An acknowledgment from an earlier round of the same draft carries to the next round while the group's digest is unchanged and its reviewer is not an author of the new round; the round screen shows it with its round and date. SQL compares the stored digests; the worker needs no earlier data. - Approval requires a current or carried acknowledgment of every group to cover, each by a reviewer whose grant is active at that moment (§5.2). Progressive review. The reviewer reads groups and answers in comments; the editor applies the answers, marks the read groups `reviewed` and resubmits; the reviewer then acknowledges each finished group. Groups that do not change afterwards keep their acknowledgments across rounds. The final approval is one decision, resting on per-group acknowledgments that each carry a reviewer and a time: no single action approves a whole structure unread. An anatomical decision is applied by an editor only from a reviewer comment that names the element; the reviewer's acknowledgment of the changed group is its validation. The change list (added, removed, changed and status-changed elements against the base, a move appearing as removed plus added) is shown per group on the review screen. It is a reading aid; coverage rests on the groups. Comments (`anatomical_sheet_review_comments`, M5, append-only): author, body (at most 4 000 characters), optional group key, time. Element keys, when needed, are written in the body. Editors, reviewers and publishers comment. Decision (O5 A): one decision, approve or request changes with a required note, closes the round. The decision on the round, the acknowledgments per reviewer and the audit keep enough trace for a future quorum, which would add decision rows without changing the meaning of past rounds. The publication is recorded on the version (`published_review_id`, `published_by`, `published_at`), not duplicated on the round. `submit_sheet_review(version_id, expected_revision, note)` refuses a stale revision, the historical sheet, an archived sheet and a draft that already has a non-terminal round. ### 6.4 Server verdict (O15 A) The verdict that approval and publication rely on is computed by the Rust worker from data read on the server side. The browser is never a validation authority: its validation panel is advisory, and no RPC accepts a verdict, a fingerprint or a document hash from a page. Job. The round row is the job, with the avatar lease pattern of `20261013100000_files_foundation.sql` (lease token, `locked_at`, fixed lease, attempts below a limit), plus a progressive delay for technical retries only (owner decision 2026-11-01). Submission sets the round `verifying`. Worker RPCs, service role only (M6): - `claim_sheet_verifications(limit)`: `for update skip locked` over rounds `verifying` with no live lease and no pending delay (`not_before` null or reached); sets the token and `locked_at`, increments `attempts`, clears `not_before`; returns round, version, sheet, revision and token. - `get_sheet_verification_input(review_id, lease_token)`: the document at the round's revision (frozen) and the base document, both as text; the drawings the document references among the rows registered for the sheet (asset id, sha256, byte size, object key). - `complete_sheet_verification(review_id, lease_token, verdict)`: accepted only while the round is `verifying`, the token is the live one, the verdict names the round's sheet, version, revision and review, its group keys equal `general`, the document's view and zone ids and the base's removed ones, and its drawings equal the document's asset ids with the rows' sha256; anything else answers `stale` or `malformed` and writes nothing. Moves the round to `open` or to `verification_failed` (§6.5) and audits. - `fail_sheet_verification(review_id, lease_token, code)`: a technical failure, closed by cause (2026-11-01, `private.sheet_worker_final_codes`). A definitive code (`verification.worker.resource_limit`, cause intrinsic to the frozen input or the contract caps; `verification.worker.verdict_refused`) closes the round at its first occurrence: `verification_failed`, outcome `unavailable`, the code kept, no delay, never claimed again. A transient code (`timeout`, `unavailable`, `lease_expired`): the round stays `verifying` and becomes claimable after a delay that grows with the attempt (2 s after attempt 1, 5 s after 2, 10 s after 3, 20 s after 4; `private.sheet_verification_retry_delay`), kept in the round's `not_before` (a column the API roles cannot read, set here, cleared by the claim); the fifth failure of a transient code becomes `verification_failed` with outcome `unavailable` and clears it. The audit payload says which rule closed the round (`closed_by`: `definitive` or `attempt_limit`). Nothing is written for a stale call. The delay is persisted, so no worker sleeps and any worker honours it; the effective wait is the delay plus up to one poll interval of the worker (2 s by default). Only these technical failures wait: a validation or integrity refusal is a verdict and is never retried, and a dead lease is claimed again at once (the 10-minute lease is its wait). Processing. Verification runs as its own mode of the worker image (`run --jobs sheet-verify`), in its own container under the `worker` compose profile, so a fault in it never stops avatar or purge processing. The keyed parent downloads the drawings and passes the document texts and drawing bytes unparsed to the keyless sandboxed child, the only process allowed to parse untrusted bytes. The child runs the core's verdict function (V1-2.2) and returns a JSON verdict. The spawner takes its limits per command: about 13 MiB of input (document, base, four drawings of 2 MiB) and a verdict output cap sized on the at-caps fixture; the RPC body cap of this mode is raised to match. Memory and CPU limits and a wall-clock watchdog bound the child; the seccomp profile is derived again for the new code path. Verdict content, bound to the round: `sheet_id`, `version_id`, `revision`, `review_id`; the fingerprint `sha256-rfc8785-validated-v1` of the validated document (absent when the document has an error); each reachable drawing checked (asset id, sha256, byte size, result); issues (code, severity, path); caps; completeness counts (statuses, vet referrals, uncited elements); the groups and their digests; the change list; `verified_with` (core version). Core changes. A release that changes the SVG reader, the integrity rules, the caps or the fingerprint ships a migration that withdraws every round of a draft version in `verifying`, `open` or `approved`, with the reason recorded (the round of a published version stays `approved`, §6.1, and `withdraw_sheet_review` refuses it with `draft.not_a_draft`; worded at V1-2.6 U0); editors submit again and the new worker verifies. The release replay (§15) runs before such a release. Availability. Reviews and publications need a running, health-checked verification worker on the stack where they happen. Without one, authoring continues, submissions stay `verifying`, nothing is approved or published (fail-closed), and the editor can withdraw at any time. The worker code authorises nothing on DEV: starting it there is an operating checkpoint of its own (§16.11), because a started DEV worker also processes the avatar upload waiting since the V1-1 acceptance (AVATAR-01) and the due rows of the purge queue. Implemented in V1-2.3 (2026-11-01, migration `20261101100000_sheet_verification_jobs.sql`, `crates/worker` mode `sheet-verify`, STORAGE.md §3.6): lease 10 minutes, attempt limit five, verdict text at most 4 MiB; the completion also refuses an unknown verdict format or code, a duplicated group key and a drawing whose result is not `ok`, and accepts a failed verdict without groups or drawings; worker codes `verification.worker.unavailable`, `.timeout`, `.resource_limit`, `.lease_expired` (a dead lease), `.verdict_refused` (a completion answered `malformed`), a closed list in SQL (`private.sheet_worker_codes`); the definitive ones are `.resource_limit` and `.verdict_refused` (`private.sheet_worker_final_codes`). These values and codes are the implementer's, for the owner's confirmation. The service role executes these four RPCs besides the two upload ones (pgTAP 018). Rejected: a verdict computed in browsers (contrary to the owner's rule), a synchronous HTTP verification service (a public endpoint holding the service key, a sandbox to rebuild; not in the MVP), an operator command-line verifier. ### 6.5 Verdict failures (O23) Fail-closed: no round is approved and no version published while its verdict is missing, failed, stale or in error. Two outcomes close a verification that did not pass; the closed codes keep the categories apart. | Category | Example | Outcome | Retry | Exit | |---|---|---|---|---| | Business validation | integrity error, caps exceeded, annotation without geometry, annotation outside its view's frame | `verification_failed`, outcome `failed`, codes `verification.validation.*` and the issues | no | fix the draft, submit again | | Integrity | strict parse refused, drawing missing, size or sha256 mismatch, SVG refused, needing a removal or outside the stored form (§9.2), `object_conflict` | `verification_failed`, outcome `failed`, codes `verification.integrity.*` | no | fix or upload again; `object_conflict` follows §9.3 | | Transient worker error | database or Storage unreachable, broken child, child killed from outside (SIGKILL or any signal not listed below: OOM killer, stop), worker restart | `verification.worker.unavailable`, stays `verifying`, code recorded | yes, after 2 s, 5 s, 10 s, 20 s, up to the limit | automatic | | Timeout | child over its wall-clock deadline | `verification.worker.timeout`, stays `verifying`, code recorded | yes, same delays, up to the limit | reduce the document or the drawing if it repeats | | Resource limit intrinsic to the content | frame refused, input over the child cap, output over its cap, CPU budget (SIGXCPU), memory budget (SIGABRT), seccomp (SIGSYS) | `verification_failed`, outcome `unavailable`, `verification.worker.resource_limit`, closed at the first occurrence | no (the same input ends the same way) | reduce the document or the drawings, submit again | | Verdict refused | completion answered `malformed` | `verification_failed`, outcome `unavailable`, `verification.worker.verdict_refused`, closed at the first occurrence | no | submit again later; reported to the operator | | Interruption | worker crash, lease expired | claimable again at once (the lease was the wait); counts as an attempt | yes, up to the limit | automatic | | Stale result | completion with an old token, after a withdrawal, or naming another revision | nothing written, logged | no | none needed | | Attempt limit | a transient code at its fifth attempt (five; V1-2.3 implements five, for the owner's confirmation) | `verification_failed`, outcome `unavailable`, last code | no | submit again later | | Core change | release that changes rules or reader | rounds withdrawn by the release migration | no | submit again | - Withdrawal is always available: the submitter or any editor withdraws a round in `verifying`, `open` or `approved`, with a note; the draft unfreezes. No round stays frozen without an exit. - The round screen shows « vérification en attente depuis N min » with the attempts and the last code. - Every code maps to an FR and an EN message from a closed list; no stack trace, internal path or database error reaches a page. - Audit: submitted, verification passed or failed (outcome, codes), attempt failed, withdrawn, decided, published. - No partial publication: §6.8 is one transaction. - Divergence recorded (owner, 2026-11-02, BDR-094): the « reported to the operator » exit of « Verdict refused » is not implemented. The worker writes an error line (`complete_malformed`, `crates/worker/src/verify_job.rs`) and `fail_sheet_verification` keeps the code on the round and in the audit; no notification is sent. No alert mechanism is planned in V1-2; the user message says « l'incident est enregistré » / « the incident is logged ». ### 6.6 Element statuses, keys and coverage (O3 B, O7 A) Three distinct notions (O7): - the draft's state: draft, revision, frozen or not by a round; - the review marking of an element, a statement made by an editor: `to_confirm`, `reviewed` or `inherited`; - the business approval of the version: a reviewer outside the author set approves a round after acknowledging its groups. A marking validates nothing by itself. An author who sets `reviewed` on an element makes a statement that only an acknowledgment and an approval can cover. Meanings: - `to_confirm` (« À confirmer »): a doubt, or content created and not yet read. Every element created in the editor starts there. - `inherited` (« Hérité, non relu »): carried over from the historical import, never reviewed; an omitted status means `inherited`. No editor path assigns it. It is never acknowledgeable, approvable or publishable, whatever the base (C2). - `reviewed` (« Relu »): marked by an editor; it counts only when covered. Keys: | Element | Key | Stable under | |---|---|---| | Annotation | its id, unique in the document | label changes, geometry changes, moves between views | | Finding zone | its id | label changes | | Finding category or node | path key `//…` | label changes and reordering among siblings | | View, reference, annotation category | id | label changes | | Vertebral region | code | label and count changes | Ids are generated by the page (§8.1), never derived from labels, never edited, never reused. Rules of the core's edit commands: | Change | Key | Status | |---|---|---| | Create | new | `to_confirm` | | Edit content: labels FR or EN, description, vet referral flag, cited references, geometry, laterality, view, annotation category, finding zone, region | same | `to_confirm` | | Rename (labels only) | same | `to_confirm` | | Reorder among siblings | same | unchanged; the group digest changes | | Replace a view's drawing or crop | same | `to_confirm` for every annotation of that view | | Edit a shared element (sheet texts, reference, region, annotation category) | same | unchanged; the `general` group digest changes | | Status change | same | any element to `to_confirm`; `to_confirm` or `inherited` to `reviewed` only through « Marquer comme relu » on one element, one category or one finding zone, never the whole sheet; never to `inherited` | | Delete | gone, with descendants | listed as removed; a removed zone or view becomes a removal group when a base exists | Moving a node to another parent is not offered in level 1 (§8.3): an editor deletes and re-creates it, with new keys and `to_confirm` statuses. Comments that named the old keys keep them in their body. Base and coverage: - The base is the version of §6.2 or none. The historical import is never a base: a first publication rests on a real review of every element (C1). - Coverage: every group to cover (§6.3) is acknowledged, and no element is `to_confirm` or `inherited`. An element validated in an earlier published version and left untouched keeps its validation through the base's approved round, because its group's digest is unchanged; any change, move or status change in the group re-opens it. - The edit commands apply the status rules for the editor; the server does not trust them. A page that saves a modified element still marked `reviewed` changes its group's digest, so the group must be acknowledged again; an `inherited` element anywhere blocks approval and publication. - A version derived from a base copies its statuses; the base was published through a V1-2 round, so it holds neither `to_confirm` nor `inherited`. ### 6.7 Submission, approval and publication rules (C7) Four stages, each a superset of the previous: 1. Structurally valid, that is submittable: the verdict passes the submission rules below. Elements may still be `to_confirm` or `inherited`. 2. Approvable: structurally valid, publishable content, groups covered. 3. Approved: a reviewer outside the author set decided so. 4. Publishable: approved, with every binding still intact. | Rule | Submit | Approve | Publish | Code | |---|---|---|---|---| | Strict parse of the document and, for a derived version, of its base (§6.5; owner decision 2026-10-29) | yes | | | `verification.integrity.document`, `verification.integrity.base` | | The 19 error codes | yes | | | `verification.validation.rules` | | Caps of §1, all of them | yes | | | `verification.validation.caps` | | Every annotation has a geometry | yes | | | `verification.validation.no_geometry` | | Every reachable drawing present, size and sha256 equal to its row, read without removal, in the stored form of §9.2 | yes | | | `verification.integrity.*` | | Every annotation entirely inside the frame of its view, edges included: the view's `view_box`, else the `viewBox` of the drawing it draws, read as a browser reads it (four numbers, positive width and height) and usable within the range rules browsers draw faithfully (owner brief 2026-11-01: edges within 2²⁰, spans from 1 unit, aspect at most 100, farthest edge at most 256 smaller spans); curves and arcs measured on their shape; path data a browser would not read whole refused; a view drawn on a clean drawing without either has no frame. Measured on the views whose drawing reads clean; the document is never rewritten (owner brief 2026-10-30, RUST.md §12.11) | yes | | | `verification.validation.out_of_frame` (issues `annotation.geometry.out_of_frame`, `view.frame.unknown`) | | Every annotation in frame shows at least 4 CSS px on the smallest preview, the editor at 320 × 568 (main view box 286 × 310, detail view box 254 × 191, `xMidYMid meet`): a point's visible disc (`2 × max(2, r − 12)`), a trigger circle's diameter, a polygon's or a path's smaller side (curves and arcs on their shape). Same views, same frame; the document is never rewritten (owner brief 2026-11-01, RUST.md §12.13) | yes | | | `verification.validation.marker_too_small` (issue `annotation.geometry.too_small`) | | Every polygon or path annotation in frame fills a disc of 4 CSS px on the same preview: under the `nonzero` rule the layer fills with, its stroke left out, a centre inside the fill at least the radius from every edge (closing edges included), curves and arcs cut into chords whose deviation is taken off; arcs modelled as browsers store them (`f32` endpoints, a radius other than zero at least `2⁻²⁰`, the spread of one `f32` ulp added); measured within `interior::MAX_OUTLINE_VERTICES` 4 096 vertices and one budget of `2²⁵` edge distances per sheet, refused past them; refused in doubt (owner brief « fermeture du dernier MEDIUM » 2026-11-01, RUST.md §12.14) | yes | | | `verification.validation.marker_interior_too_small` (issue `annotation.geometry.interior_too_small`) | | Fingerprint computed | yes | | | `verification.integrity.fingerprint` | | Fixed categories (from V1-2.6 U6, §17.12; not built yet): each of `bone`, `joint`, `vertebra` carried by exactly one category with its fixed FR and EN names, `navigation` by at most one with its fixed names; judged on drafts, never on a published version (the §15 replay filters it) | yes | yes | yes | submission: issues `category.fixed.*` under `verification.validation.rules`; approval and publication: the declared check of §12.2 (closed code fixed at U6) | | Verdict passed, on the current revision | | yes | yes | `verdict.missing`, `verdict.failed`, `verdict.stale` | | No `to_confirm` element (D2) | | yes | yes | `publish.to_confirm.open` | | No `inherited` element, an omitted status counting as `inherited` (O3 B) | | yes | yes | `publish.inherited.present` | | Scope disclaimer present in FR and EN, non-blank after trimming (O6) | | yes | yes | `publish.disclaimer.missing` | | Every group to cover acknowledged by a reviewer outside the author set with an active grant | | yes | yes | `review.groups.uncovered` | | Approver outside the author set, grant active | | yes | yes | `review.separation`, `publish.approval.invalid` | | An `approved` round on the version's current revision | | | yes | `publish.review.missing` | | Each drawing's row sha256 equal to the verdict's | | | yes | `publish.drawing.changed` | | Sheet active, official, other than the historical sheet | yes | yes | yes | `sheet.inactive`, `sheet.historical_read_only` | | Species active and other than `other` | | | yes | `publish.species.inactive`, `publish.species.other` | | Caller capability (E, V, P) and `aal2` | yes | yes | yes | `rights.capability`, `rights.mfa` | - The rules of the first six lines come from the stored verdict. SQL checks relations, states, rights, separation, the verdict's structure (§6.4), and the declared defensive checks on the stored document (§12.2): statuses and, from V1-2.6 U6, the fixed categories. - Shown, never blocking: uncited elements, the two warning codes, the number of vet referral nodes. - Approval never changes the document. - Approval does not check the species: an approved round of an inactive species waits for its activation (§7.2). ### 6.8 Publication (atomic) `publish_sheet_version(review_id)`, in one transaction: lock sheet, version, round; check every publication rule of §6.7; set the version `published` with `published_by`, `published_at`, `published_review_id` and the fingerprint taken from the verdict, never from a client parameter; refresh the sheet row's `name` and `description` from the document; move `current_version_id`; audit `anatomical_sheet_version.published` with the revision, the fingerprint and the round. The old signature `publish_sheet_version(uuid)` is dropped in the same migration (`CREATE OR REPLACE` with new arguments would leave it callable), as is every superseded RPC signature, each proven absent by pgTAP. The client gate `publishSheetVersion` is deleted in the same step. `guard_sheet_version_update` is extended in two ways, for every role: - a draft becomes `published` only with a `published_review_id` naming an `approved` round of the same version and revision whose verdict passed, so no direct UPDATE, even with a privileged key, publishes outside the gate; - the deprecation transition cannot change any column added by V1-2 (fingerprint, review link, revision, authors, base, working-copy provenance). A wrong published version is repaired only by deprecating it and publishing a corrected one. ### 6.9 Deprecation, archive, deletion, historical reads (O8 A) - A version that was ever published is never modified or deleted physically: M4 extends the delete guard to `deprecated` for every role (F13). - Deprecation keeps the version readable by id. Deprecating the current version makes the latest remaining published one current again; the A8 confirmation names it. When none remains, the confirmation says that the sheet leaves the catalogue list; `current_version_id` becomes null and the versions stay readable by id. - Archiving an official sheet removes it from the catalogue list; its published and deprecated versions stay readable by id under catalogue access (§5.3). Historical reads never bypass §5.3. - An official sheet that ever had a published version cannot be deleted; drafts without rounds can. - Narrowing the read of archived versions to « referenced by a bilan the reader can see » needs the bilan table of V1-3 and is reviewed there. --- ## 7. Species and new sheets ### 7.1 What the current model allows Nothing in the document schema is equine-specific: `species_id` is a free stable id, vertebral regions are data, labels are FR/EN pairs. The equine specifics found are the report migration map (a legacy equine concept, kept as is; §10 adds a load path without it), `NewReportRoute.DEFAULT_SPECIES_ID = 'equine'` and the bundle plugin (local tool, unchanged until V1-3), the curation pipeline (an equine tool), and the archive caps (4 drawings), which bind every species. ### 7.2 Species rows (O9 C) - `create_species(id, name_fr, name_en, sort_order)`: sheet editor with `aal2`, audited. Inserts the row with `active = false`. The id follows the existing CHECK and is never renamed; an existing id gets one answer. `sort_order` an integer from 0 to 9 999, or null for the default 100; outside → `invalid_input` (M7, §17.11). - `update_inactive_species(id, name_fr, name_en, sort_order)`: sheet editor with `aal2`, inactive rows only, audited. `sort_order` 0 to 9 999, null keeps the stored order (M7, §17.11). - `activate_species(id)`: platform owner with `aal2`, audited; the only way a species becomes active. - `rename_species(id, name_fr, name_en)`: platform owner with `aal2`, audited; corrects an active species' names, never its id. - No deactivation and no deletion in V1-2: an unused inactive species stays invisible. - The animal forms do not change. The policy `species_select_active` is not widened, so `fetchSpeciesLabels`, `create_animal` and `update_animal` keep seeing active species only, for every account, editors included. The admin space lists species through `list_catalog_species()` (E, V, P, O, `aal2`), which returns active and inactive rows with their state. Widening the policy instead would show inactive species in an editor's own animal forms. - Creating an official sheet accepts an active or an inactive species, never `other`, and never activates a species. Publication refuses an inactive species and `other` (§6.7). - A species row holds an id, two names and an order (0 to 9 999). No vertebral formula, zone, finding or drawing is generated for it. Amendment of V1-1 N1 and §5.4 (ratified with O9, 2026-10-28): « The list of species is no longer fixed by migration. A species is added by an audited RPC: created inactive by a habilitated sheet editor, activated by the platform owner. Its id never changes; an inactive species is invisible in the animal forms; `other` stays refused for anatomical sheets. » The V1-1 contract carries a pointer to this amendment; the table comment « no API write path » changes with M5. ### 7.3 Several official sheets per species (O10 A) Allowed. Each sheet has its own id, slug (unique among official sheets, which share the null creator of the existing unique index), versions, rounds and completeness. The catalogue lists every sheet with a published version under its species, with its FR and EN names and description. Which sheet a bilan uses, and whether a species gets a default sheet, is decided with V1-3. ### 7.4 Starting a sheet - From the empty document of the core (`create_empty_sheet_document`): species, FR and EN names, slug; everything else is entered in the editor. - The copy of a finding catalogue from another sheet is deferred (O11), so no finding of one species is ever reused automatically for another. The working copy of the historical equine sheet (§14.3) is a distinct operation, restricted to that sheet. - No template of scientific content is shipped. Vertebral formulas, zones and findings of a new species are entered by the editor from sources cited in the references registry. - From V1-2.6 U6 (owner 2026-11-05, §17.12) the empty document carries the three fixed categories `cat-bone` (« Os » / « Bones »), `cat-joint` (« Articulations » / « Joints ») and `cat-vertebra` (« Vertèbres » / « Vertebrae »), with their roles and default colours; nothing else is pre-filled. - Scope and limits (choice 7, decision T12): the editor may insert a versioned common text once into the FR and EN scope fields while both are empty; the fields stay free text afterwards, and no later version of the common text changes a draft or a published version. No common text exists yet: its FR and EN wording, its source and its validation record are supplied by the owner before U7, and nothing is written in their place meanwhile. It is never presented as veterinary or legal advice approved by the platform. ### 7.5 Species-specific checks The core checks structure only: unique region codes, order as given, `count ≥ 1`, coherent `count_range`, region codes used by annotations exist. Expected vertebral formulas per species would be veterinary data nobody has supplied; they are not invented. --- ## 8. Editor ### 8.1 Architecture - The page holds the draft document as one JSON string, loaded in a `PreviewSheet` handle (§10): drawings read once per sha256, the document replaced and re-indexed after each change, `view.canvas` composing the view on that handle as on `LoadedSheet`, and a draft with referential gaps still drawn with its issues. - Every change is a Rust core command (`sheet.edit`, V1-2.2): generic primitives (insert, update, remove, reorder) over element keys, applying the status rules of §6.6 and refusing what would break strict parsing or leave an element named by another behind (owner decision 2026-10-29, below); other referential gaps are left to the validation panel. A `dependents(key)` query feeds the delete confirmations. TypeScript holds no schema of its own and no Zod copy; it reads the ts-rs types. - As built in V1-2.2, strict validation of the commands confirmed by the owner (2026-10-29): the wire ops are `insert`, `update`, `remove`, `move` (the reorder), `set_status` and `mark_reviewed`; besides what breaks strict parsing they refuse what would leave an element unaddressable or outside the editor's offer (`duplicate_key`, `unknown_key`, `invalid_target`, `id_changed`, `invalid_position`, `too_deep` beyond 8 finding levels). - Removal, owner decision 2026-10-29 (atomic refusal): `remove` takes the element with its descendants (a zone with its categories and nodes, a category or node with its children: §6.6 « with descendants ») and is refused as a whole, the document unchanged, with `has_dependents` while anything else names the element: a view with annotations drawn in it, detail views under it or a link that opens it; an annotation category or a vertebral region used by an annotation; a finding zone linked from an annotation; a reference cited by a category or a node. The page shows the `dependents` list; the editor detaches or deletes those first. No cascade deletion is offered in level 1. An `insert` or `update` that names an element absent from the document stays allowed (left to the validation panel), as does a document saved with gaps: the verdict refuses them. Structural rules that name nothing (`view.unreachable` after the last link to a view goes, `view.main.count` after the main view goes) are left to the validation panel too. - Ids are generated by the page (`-<10 lowercase base32 characters>`, alphabet `a-z2-7`, inside the stable-id rule), passed to the core, never derived from labels, never editable, never reused. - Pointer moves update the page's preview only; the core command runs on pointer-up. - Undo and redo: a stack bounded by size (8 MiB of document strings). - 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 document size against the 2 MiB server cap, in the measure of §12.2. ### 8.2 Level 1, in the MVP An editor can, from the application only: - set the general information: FR and EN name, description and scope disclaimer, attribution (authors, licence, notes); - manage the references registry: add, edit, delete; type, citation, URL (http or https only), DOI; - manage the vertebral regions: add, edit, reorder, delete; - manage annotation categories: name FR/EN, colour; - manage views: the main view, detail views (parent, own drawing or crop of the parent entered as numeric `view_box` values over the parent's preview), rename, delete; - upload and clean a drawing (§9), see its state, attach it to a view; - on a view's drawing, as the practitioner sees it: - place a point by clicking, set its radius in a field; - draw a zone as a polygon by successive clicks, close it; correct, add or remove vertices in the vertex list; - draw a detail view link the same way and choose the view it opens; - select an annotation on the drawing or in the list, move it, delete it; - zoom and pan; - enter or correct every coordinate in numeric fields (keyboard alternative and precision); - set each annotation's FR and EN name, kind, category, laterality, finding zone, vertebral region, colour and review marking; - edit the finding catalogue as a tree: zones, categories (kind), nodes up to depth 8; add, rename FR/EN, describe FR/EN, flag vet referral, cite references, set the review marking of one element or « Marquer comme relu » on one category or one zone, reorder among siblings, delete with a confirmation listing the dependents; - preview the draft exactly as a practitioner (§10), read the completeness report, submit, follow the round and its verification, read comments, withdraw. Amended for the V1-2.6 redesign (owner 2026-11-05, §17.12; built in sub-steps U1 to U6, each on its own authorisation). The functions above stay; the way they are reached changes: - four tabs, Général, Annotations, Constats and Vérification; views, drawings, annotation categories and vertebral regions in Annotations; the references registry in a side panel opened from the header or from a finding; undo and redo in the header on every tab; - geometry by direct manipulation on the drawing: a point moved, and sized with a slider snapped to the sizes of its view, the core's minimum shown; a polygon's vertices dragged, added with « + » on a segment, removed with « − »; a zone moved (with the mouse once selected, in an explicit mode by touch) or redrawn, the old shape kept until the new one is accepted; the keyboard alternative goes through the handles. No coordinate field remains in the normal journey; - a detail view drawn as a rectangle over its parent's drawing, its name proposed from the annotations inside and editable (U5); its access placed from the view's menu (U4), or created with the view from U6 when no annotation overlaps the rectangle, in the internal navigation category `cat-access`; - annotation categories: the three fixed categories keep their names and roles, their colour and fill opacity adjustable (from U6); other categories stay free; an annotation's own colour is shown only when set, with « Revenir à la couleur de la catégorie »; a new annotation inherits its category's colour; - replacing the drawing of a crop view asks first: keep the positions, reposition the annotations or cancel, each offered only under the conditions of decision T9, never an approximate transformation. ### 8.3 Level 2, deferred Curves (`path` drawn or edited by handles; existing paths are displayed and can be replaced by a polygon), dragging vertices and drawing a crop rectangle on the canvas, moving a finding node to another parent, snapping, left and right mirroring, multi-selection and group moves, scale and rotation, copying annotations between views or sheets, creating zones from the drawing's own SVG shapes, side-by-side visual diff of two versions, comments pinned on the drawing or on elements, drag and drop in the finding tree, bulk import of findings, species templates, collaborative live editing, package export and import. Amended 2026-11-05 (§17.12): dragging vertices and drawing a crop rectangle on the canvas move into V1-2.6 (§8.2 as amended); the size slider snaps to the sizes already used in the view, other snapping stays deferred. Curves form the curves lot (decision T16), which precedes package import, zones from the drawing's own shapes and any curve drawing tool. Until then a stored path keeps its data byte for byte and is never converted; an operation that would change it is refused with the document unchanged. « Remplacer par un polygone » stays its one exit, as an explicit replacement only: the editor traces the polygon, the core validates it, the old path stays until the polygon is accepted, and the change is undone and redone as one entry. ### 8.4 What level 1 does not do, and narrow screens (O14 A) Level 1 never edits the drawing itself, accepts no raster image, draws no curves and does not let two people edit one draft at the same time (one draft per sheet, revision conflicts). | Surface | 1 024 px and wider | Narrower | |---|---|---| | Catalogue and sheet consultation (P1) | full | full, tested from 320 to 430 px | | Preview (practitioner view, admin preview) | full | full, read-only canvas with zoom and pan | | Draft editor, every tab, graphic and structured | full | read-only with a notice naming the 1 024 px minimum | | Admin lists, overview, rights, species, review screen (read, comment, acknowledge, decide), publication confirmation, deprecation, archive | full | usable, tested at 375 px | Amended 2026-11-05 (§17.12): O14 A is kept. Editing on a phone (boards 14 to 16 of `docs/design/v1-2-6`) is a future lot after V1-2. From 1 024 px the editor works with the mouse, the keyboard and touch (a tablet in landscape, handles of at least 44 px); below 1 280 px the application's sidebar is hidden in the editor, its menu one tap away. --- ## 9. Drawings (SVG assets) ### 9.1 Principles - Content-addressed and immutable: a new drawing is a new sha256, a new row and a new object. A published version references its asset ids; an asset-row trigger (M4) refuses any change of `sheet_id`, `sha256` and `byte_size` and lets `uploaded_at` go only from null to a value, for every role; no policy allows an UPDATE or DELETE of an object. - A file is at most 2 MiB (archive cap); the bucket limit drops from 20 MiB to 2 MiB (M5). A sheet reaches at most 4 distinct drawings (§1). - Row state stays the existing column: `uploaded_at` null means pending, set means uploaded. No state column is added, so existing rows are not rewritten. - The application never creates signed URLs on this bucket; drawings are downloaded under RLS (§9.4). - The avatar pipeline is not reused: no transcoding, no per-user key, no quarantine copy, no automatic replacement. Closed codes and the worker's lease pattern are reused where they fit. ### 9.2 Cleaning before upload (O19 A) The page reads the file with the core SVG reader before anything is stored. | Reader outcome | Treatment | |---|---| | Hard rejection (`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, `too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, `dangling_reference`, `reserved_id`, `root_visibility`) | refused, with the reason in FR or EN; no cleaning offered | | Any removal of active or external content: `script`, `foreignObject`, event-handler attributes, `image`, animation elements, a reference that does not point inside the document (`href` or `url(…)` not starting with `#`), `@import` or `javascript:` values | refused (`svg_active_content`): such a file is hostile or incompatible; no cleaning offered | | Any other removal (editor metadata and namespaces, `data-*` attributes, `