132 KiB
V1-2 Anatomical sheets: contract
Status: decisions RATIFIED, contract consolidated for the owner's final review (V1-2.0, 2026-10-28), with ONE OPEN ARBITRATION REQUEST (AR-1, §17.2). 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 needs the owner (AR-1). 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 open 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 <zoneId>/<path…> (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, a compressed size), 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 <sha256>.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 <sha256>.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 <sha256>.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:
- 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;
- a traceable review workflow with progressive reviews (§6.3), a server verdict computed by the Rust worker (§6.4) and an atomic publication gate;
- explicit rights: three capabilities and a provisional catalogue access, granted by the owner, with MFA for every administrative operation (§5);
- a read-only catalogue of published official sheets for accounts with catalogue access (§5.3);
- 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;
- hardening of the existing SQL lifecycle, and the Rust core as the only authority on document rules (§12.2);
- new species created inactive by editors and activated by the owner (§7);
- 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) | Historical sheet (Git pipeline) | 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 | Capability | right sheet_editor, sheet_reviewer, sheet_publisher (§5.2) |
| Relecteur, 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.
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 |
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 |
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)andrevoke_catalog_right(grant_id, reason), platform owner withaal2, 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_atorexpires_atin 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_editorandsheet_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.
- 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.invalidand the round staysapproveduntil 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)andhas_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 activecatalog_readergrant or an active capability). Anything unknown or missing answers false. Platform roles grant nothing by themselves. catalog_readergrants follow §5.2 (owner only, reason required, verification note and verified factor not required, expiry optional, audited, noaal2needed 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. Thevisibilitybranch ofcan_use_sheetis 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 excludelast_version_number,updated_atandworking_copy_source_version_id. - The predicate gates the catalogue list, the published and deprecated versions by id, archived sheets included (O8), and their drawings.
- 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 namecatalog.read, added to the Step 11 capability catalogue); an owner decision then sets the predicate to (entitlement or capability), says what becomes of the provisionalcatalog_readergrants, 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_readerand 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.
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):
- The owner enrols two TOTP factors, steps up, grants itself
sheet_editorandsheet_publisherwith a reason. - The business reviewer signs up, confirms the e-mail address and enrols a
TOTP factor; the owner then grants
sheet_reviewerwith a reason, a verification note and possibly an expiry. - The owner creates the sheet, edits, uploads, saves and submits; the worker verifies the revision; the round opens.
- 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.
- The owner publishes the approved round.
5.6 Strong authentication (O4 A)
private.has_mfa()reads(auth.jwt() ->> 'aal') = 'aal2'. Throughcaller_hasit 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. Supabase requires an
aal2session to remove a verified factor. V1-2.5 proves that anaal1session of an account with a verified factor cannot enrol another factor; if Supabase allowed it, the step stops for an owner decision, since MFA would then be bypassable with the password alone. - Step-up: entering
/app/adminwith anaal1session opens the challenge; success upgrades the session; no admin data is requested before. - Sessions:
aal2belongs to the session. A token refresh keeps it, sign-out ends it, a new sign-in starts ataal1(Supabase behaviour, proven by a V1-2.5 browser test). The access token livesjwt_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 stolenaal2session 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
aal1access (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:
- the owner confirms the requester's identity out of band and records the reason;
- the owner revokes the account's capabilities (§5.2);
- 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_resetthroughprivate.log_event(null actor, subject, reason, operator named in the detail); - 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.mdand is rehearsed on the sandbox in V1-2.9.
- Platform roles (O4-D):
grant_platform_roleandrevoke_platform_rolerequire noaal2, and an owner may grant the owner role. The first revision of this contract claimed that the catalogue stays closed without O4-D; the security challenge of §19.3 showed it does not (anaal1owner session grants owner to another account, which enrols its own factor and grants itself every capability). O4-D was not ratified, so the contract does not extendaal2to those RPCs: the choice is the open arbitration AR-1 (§17.2).
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,openorapproved, the draft content is frozen (trigger, every role, seed included). The terminal states (changes_requested,withdrawn,verification_failed) unfreeze it; a published round staysapprovedand 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 apublishedversion with apublished_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 version and revision, 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 andaal2, that the version is a draft of an active official sheet other than the historical sheet, that no round freezes it, the revision, the structural guards of §12.2 (shape, serialised size at most 2 MiB measured asoctet_length(content::text), species), and refuses an unchanged document. It incrementsrevision, the trigger adds the actor to the author set, and the audit recordsanatomical_sheet_version.savedwith the revision. A draft may hold integrity errors while it is being written; the verdict refuses them at submission. - A trigger bumps
revisionon any content write, so no write slips under a round unseen. - The direct UPDATE grants on
content,change_note,name,sluganddescriptionare revoked (M4). The sheet row'snameanddescriptionare 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_revisionanswersdraft_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:<viewId>: the view and the annotations located in it;zone:<zoneId>: the finding zone, its categories and nodes;- removal groups: a
view:orzone: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
openround, against the verdict's digest of that group. A group that still holds ato_confirmorinheritedelement 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), without backoff. Submission sets the round
verifying. Worker RPCs, service role only (M6):
claim_sheet_verifications(limit):for update skip lockedover roundsverifyingwith no live lease; sets the token andlocked_at, incrementsattempts; 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 isverifying, the token is the live one, the verdict names the round's sheet, version, revision and review, its group keys equalgeneral, 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 answersstaleormalformedand writes nothing. Moves the round toopenor toverification_failed(§6.5) and audits.fail_sheet_verification(review_id, lease_token, code): a technical failure; the round stays claimable until the attempt limit, then becomesverification_failedwith outcomeunavailable.
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 in
verifying, open or approved, with the reason recorded; 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.
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 | 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 or needing a removal, 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, worker restart | stays verifying, code recorded |
yes, up to the limit | automatic |
| Timeout or resource limit | child over its wall-clock or memory limit | stays verifying, code recorded |
yes, up to the limit | reduce the document or the drawing if it repeats |
| Interruption | worker crash, lease expired | claimable again; 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 |
| Definitive failure | attempt limit reached (five, proposal, tuned in V1-2.3) | 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,openorapproved, 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.
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,reviewedorinherited; - 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 meansinherited. 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 <zoneId>/<categoryId>/<nodeId>… |
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_confirmorinherited. 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
reviewedchanges its group's digest, so the group must be acknowledged again; aninheritedelement 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_confirmnorinherited.
6.7 Submission, approval and publication rules (C7)
Four stages, each a superset of the previous:
- Structurally valid, that is submittable: the verdict passes the
submission rules below. Elements may still be
to_confirmorinherited. - Approvable: structurally valid, publishable content, groups covered.
- Approved: a reviewer outside the author set decided so.
- Publishable: approved, with every binding still intact.
| Rule | Submit | Approve | Publish | Code |
|---|---|---|---|---|
| Strict parse and the 19 error codes | yes | verification.validation.* |
||
| 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 | yes | verification.integrity.* |
||
| Fingerprint computed | yes | verification.integrity.fingerprint |
||
| 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 five lines come from the stored verdict. SQL checks relations, states, rights, separation, the verdict's structure (§6.4), and the declared defensive check of statuses on the stored document (§12.2).
- 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
publishedonly with apublished_review_idnaming anapprovedround 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
deprecatedfor 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_idbecomes 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 withaal2, audited. Inserts the row withactive = false. The id follows the existing CHECK and is never renamed; an existing id gets one answer.update_inactive_species(id, name_fr, name_en, sort_order): sheet editor withaal2, inactive rows only, audited.activate_species(id): platform owner withaal2, audited; the only way a species becomes active.rename_species(id, name_fr, name_en): platform owner withaal2, 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_activeis not widened, sofetchSpeciesLabels,create_animalandupdate_animalkeep seeing active species only, for every account, editors included. The admin space lists species throughlist_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 andother(§6.7). - A species row holds an id, two names and an order. 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.
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
PreviewSheethandle (§10): drawings read once per sha256, the document replaced and re-indexed after each change,view.canvascomposing the view on that handle as onLoadedSheet, 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 only what would break strict parsing; referential gaps are left to the validation panel. Adependents(key)query feeds the delete confirmations. TypeScript holds no schema of its own and no Zod copy; it reads the ts-rs types. - Ids are generated by the page (
<prefix>-<10 lowercase base32 characters>, alphabeta-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 serialised size against the 2 MiB server cap.
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_boxvalues 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.
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.
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 |
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,sha256andbyte_sizeand letsuploaded_atgo 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_atnull 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) |
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, <style> elements, class or style on the root, ids outside the grammar, unsupported elements such as symbol, oversized title or desc) |
cleaning offered: « Nettoyer et utiliser cette version », after the composed preview of the cleaned drawing and one confirmation; a removed <style> element is named, since the class attributes it styled then render unstyled |
| No removal | used as is |
- The classification and the cleaning are core functions (V1-2.2), tested on committed vector-tool exports (tool and version named in the fixture) and on the hostile corpus; a property test proves that cleaned output reads back with no removal.
- Before confirming, the admin sees the cleaned drawing composed by the core and the removed names. The original file is never rendered, since it may hold active content.
- The cleaned bytes are the ones hashed and uploaded; they must fit 2 MiB. Stored drawings are never repaired afterwards (LRN-055).
- The server control stays mandatory: the verdict reads every reachable drawing again and refuses any removal (§6.4).
9.3 Upload
register_sheet_asset(sheet_id, sha256, byte_size, file_name)(editor,aal2, extended in M5 and its old signature dropped): returns the existing row of the same sheet and hash with its state, or creates one withuploaded_atnull; refused on the historical sheet.- If the object
<sha256>.svgdoes not exist yet, the page uploads it there. An INSERT policy onstorage.objectsallows exactly that key for the caller of a pending row, bucket literal pinned; no UPDATE or DELETE policy. If the object already exists (shared drawing), nothing is uploaded. confirm_sheet_asset_upload(asset_id)(editor withaal2, or the service role for the operator tool): checks instorage.objectsthat the object exists and that its size equals the row's, then setsuploaded_at(F7). The editor'sPreviewSheetthen checks the sha256 at every load (§10), so bytes that do not match their key showdrawing_hash_mismatchbefore any submission.- The verification of each submitted revision re-reads every reachable drawing in place: size, sha256, read without removal.
- Bytes under a key that do not hash to it (written by a faulty page or a
malicious editor, since the key is chosen by the uploader) block that hash
for every sheet: code
object_conflict. Exit: an operator runbook, run on the owner's authorisation, re-hashes the object, deletes it only if its bytes do not hash to its key, writes an audit row, and lets the editor upload again. It is the one Storage deletion of V1-2. - Closed codes shown to the editor:
size_mismatch,hash_mismatch,svg_rejected(with the reader's reason),svg_active_content,too_large,upload_missing,object_conflict.
A drawing never blocks authoring: only the round waits for its verdict.
9.4 Read path
- Catalogue readers: drawings referenced by a published or deprecated version of a sheet that passes the row predicate of §5.3, whatever the sheet's status (D8).
- Editors, reviewers and publishers with
aal2: every uploaded drawing of the sheet. - Nobody reads the object of a pending row through the API.
9.5 Existing rows and tools
- The DEV equine row (bytes at
<sha256>.svg, confirmed by the operator tool) keeps its state; no migration rewrites it. The working copy (§14.3) registers the same bytes for its own sheet after the storage check. The migrations are rehearsed on a sandbox holding a copy of that object, not only on an empty upgrade. pnpm assets:uploadstays the seed tool of local and sandbox stacks. With the service role's table privileges revoked (F12), the same step gives the tool a narrow read RPC for its planning and rerunspnpm e2e:sheet-assets.- Objects are never deleted by the worker: its purge guard refuses any purge
whose bucket is
anatomical-sheet-assets, and no trigger enqueues a sheet object. verified_withrecords the core of each verdict; a release that changes the SVG reader or the integrity rules replays every published version and drawing before shipping (§15).
10. Loading into the core and the application
get_sheet_version(version_id)returns the sheet id, version id and number, status, species, document,revision, the fingerprint (published only) and the drawings (asset id, sha256, size). Published and deprecated versions answer under the reader predicate (§5.3), drafts under a capability withaal2; unknown and forbidden versions get one answer.- The page downloads each drawing under RLS and builds a payload. A new core
handle,
PreviewSheet, serves the catalogue, the admin preview and the editor. At load it checks the strict document, each drawing's sha256 against its row, the fingerprint recomputed against the stored one (published), the caps, and each drawing throughread_svg; it reads each drawing once and accepts a replaced document afterwards (§8.1). It needs no report migration map and can never open a report session. Closed failure kinds:not_found_or_denied,drawing_missing,drawing_hash_mismatch,fingerprint_mismatch,invalid_document,caps,core_unavailable,unavailable. A draft with integrity errors previews with its issues and no fingerprint. LoadedSheet(the report editor's sheet) keeps its mandatory migration map;archive::SheetStatusis not extended; a deprecated version previews like a published one with a « retirée » mark. The readers of user data (report/rebase,report/read,archive/read,session,pdf/{read, json_js,import}) are not modified in V1-2.- The report editor stays on the bundled sheet (D7).
- The catalogue's read-only view reuses the editor canvas without observations, plus a browsable finding catalogue.
- Supabase unavailable: the catalogue and the admin space show the unavailable notice; the report editor keeps working on its bundle.
11. Screens and journeys
11.1 Routes (ratified, O16)
| Route | Who | Content |
|---|---|---|
/app/anatomy |
catalogue readers | catalogue by species: sheets with a published version |
/app/anatomy/:sheetId |
catalogue readers | current version: views, annotations, finding catalogue, references, disclaimer; earlier versions listed |
/app/anatomy/:sheetId/versions/:number |
catalogue readers | one published or deprecated version |
/app/admin/sheets |
E, V, P | every official sheet, the historical and working-copy badges; filters species, sheet status, version status, round status |
/app/admin/sheets/new |
E | species (inline creation of an inactive species), names, slug |
/app/admin/sheets/:sheetId |
E, V, P | overview: versions, rounds, history, actions per capability; « Créer une copie de travail » on the historical sheet |
/app/admin/sheets/:sheetId/draft |
E (V, P read-only) | editor tabs: Général, Vues et illustrations, Annotations, Constats, Références, Vertèbres, Vérification |
/app/admin/sheets/:sheetId/reviews/:round |
E, V, P | round: verification state, preview, verdict, groups with their changes and acknowledgments, authors, comments, decision, publication |
/app/admin/species |
E, V, P, O | catalogue species, active and inactive; creation (E), activation and renaming (O) |
/app/admin/access |
O | rights: grant, revoke, expiry |
11.2 Journeys
- A0 bootstrap: the owner enrols two factors, steps up, grants itself editor and publisher; a business reviewer's confirmed account enrols a factor and receives the reviewer capability with reason and verification note.
- S1 species: in the creation form or the species list, « Nouvelle espèce » creates an inactive species; the owner activates it from the species list; the animal forms are unchanged until then.
- A1 create: Fiches officielles → Nouvelle fiche → species, names, slug → draft v1 opens in the editor.
- A2 drawings: Vues et illustrations → choose a file → clean if offered → upload → attach to the main view; add a detail view by its crop values.
- A3 annotations: choose a view → draw points, zones, detail view links → set properties → link to finding zones.
- A4 findings: Constats → build zones, categories and nodes, cite references, flag vet referrals.
- A5 check and submit: Vérification → fix issues → Prévisualiser → Soumettre à la revue with a note → verification → round open, or failure with its codes and a resubmission path.
- R1 review: list « À relire » (no e-mail in V1-2) → preview, verdict, groups and their changes → comment; request changes; once the editor has marked a group, acknowledge it; approve with a note when every group is covered.
- A6 publish: Publier on an approved round → confirmation showing the version, revision, approver, acknowledgments, fingerprint → published; the catalogue shows it.
- A7 correct: on a published sheet → Nouvelle version → edit → A5, R1, A6; the earlier version stays readable; only changed groups need acknowledging.
- A8 retire: deprecate a version (the confirmation names the version that becomes current, or says the sheet leaves the catalogue), archive or restore a sheet.
- W1 equine working copy: on the historical sheet, « Créer une copie de travail » → slug → the copy opens as a draft with its badge (§14.3).
- P1 reader: Fiches anatomiques → species → sheet → views, zones, findings; no draft is ever listed.
11.3 Design
The catalogue, the admin lists and the forms follow the V1-1 precedent: existing components and shell, no new mockup. The editor canvas, the review screen with its groups, and the sidebar entry of the admin space are new interaction patterns: step V1-2.4 wireframes them through the design toolchain and the owner validates them before V1-2.6 and V1-2.7.
12. SQL defects, SQL authority and planned migrations
12.1 Defects
None was reproduced by execution in V1-2.0, which ran no stack. « Confirmed by reading » means the source shows the behaviour; V1-2.1 turns each line into a test that fails on the current code before fixing it.
| Id | Defect | Evidence | State | Fix |
|---|---|---|---|---|
| F1 | create_anatomical_sheet lets any active account create a non-official sheet, public at once, for any active species including other; contradicts V1-1 §5.4 |
l.692 | confirmed by reading | M4 (personal creation refused), M5 (official creation RPC) |
| F2 | publish_sheet_version ignores the sheet status: the draft of an archived sheet can be published; create_sheet_draft opens drafts on archived sheets |
l.735, l.764 | confirmed by reading | M4, M5 |
| F3 | the fork copies asset rows without uploaded_at; the copy reads its drawings only through the source's row, so they become unreadable once the source is archived or made private |
copy_sheet_assets l.638-660, storage predicate |
confirmed by reading | M4 closes the fork; M5's working copy confirms its rows after the storage check |
| F4 | publication accepts registered but unconfirmed drawings (only view.asset.unknown is checked) |
l.764 | confirmed by reading | M5 (publication on a verdict that reads every drawing) |
| F5 | require_actor checks the active profile, not the confirmed email |
l.537 | confirmed by reading | M4 |
| F6 | set_sheet_visibility has no verification gate (BDR-033) |
l.998 | confirmed by reading | M4 (refused in V1-2) |
| F7 | confirm_sheet_asset_upload stamps a row without checking the object (R5.5 L5); its audit actor is null |
20261009100000 l.34 |
confirmed by reading | M5 |
| F8 | archiving a sheet hides its published versions from every non-editor | l.513, version select policy | confirmed by reading | M4 |
| F9 | draft content and sheet name, slug, description change by direct UPDATE: no audit, last write wins | grant lines | confirmed by reading | M4 |
| F10 | view.parent.cycle and finding.id.duplicate are not checked in SQL |
code lists | confirmed by reading | none: the server verdict carries every core rule, and the SQL mirror is removed (§12.2) |
| F11 | the client publication gate checks, then publishes in a separate call | packages/supabase/src/anatomical-sheets.ts |
confirmed by reading | M5, client gate deleted |
| F12 | service_role keeps the default table privileges on sheet tables (the revokes name public, anon, authenticated only), unlike V1-1 N7; with it, a direct UPDATE could publish a draft (l.234-238) |
l.1157-1160; 20261025100000 l.311-314 |
confirmed by reading; effective grants checked on the sandbox in V1-2.1 | M4, unconditional, for every catalogue table old and new; the operator tool's read RPC |
| F13 | a deprecated version can be deleted physically, so a historical version can vanish | l.275-278; pgTAP 005 l.551 | confirmed by reading and by an existing passing test | M4 |
| F14 | can_edit_sheet gives every owner and admin full rights on official sheets, with no capability and no MFA |
l.494-510 | confirmed by reading | M4 |
| F15 | the sheet policy reads can_use_sheet, whose public branch opens rows to every authenticated account, outside any catalogue right |
l.513-526, l.1183-1190 | confirmed by reading | M4 (reader row predicate, §5.3) |
| F16 | asset rows have no immutability trigger: a privileged UPDATE of sha256 changes the drawing of a published version, which its fingerprint does not cover |
asset table; fingerprint.rs |
confirmed by reading | M4 (asset-row trigger), M5 (publication compares sha256) |
12.2 Rust authority and SQL guards (O22)
The Rust core is the only authority on business and anatomical rules of the document. SQL keeps what belongs to the database: authentication, authorisation, RLS, relational integrity, state transitions, revisions, locking, atomicity, and the existence and identity of a valid server verdict.
Inventory of the current SQL checks and their fate:
| Check | Where today | Class | V1-2 |
|---|---|---|---|
document.shape (each id-bearing collection is an array, the document is an object) |
sheet_document_has_shape |
storage structure | kept, applied at creation and save |
document_schema_version = 2 |
table CHECK | storage structure | kept |
| content size | pg_column_size CHECK (compressed) |
storage structure | kept; save and working copy add octet_length(content::text) ≤ 2 MiB |
| document species = sheet species | trigger (l.176) | relational | kept |
view.asset.unknown: every drawing id registered for the sheet |
sheet_document_unknown_assets |
relational | kept at submission and publication |
view.main.count, view.parent.missing, view.unreachable, view.asset.missing |
sheet_document_view_issues |
business rule, duplicate of the core | removed in M5 |
view.id.duplicate, annotation.id.duplicate, category.id.duplicate, finding_zone.id.duplicate, reference.id.duplicate, region.code.duplicate |
sheet_document_duplicate_issues |
business rule, duplicate | removed in M5 |
annotation.view.missing, annotation.category.missing, annotation.opens_view.invalid, annotation.finding_zone.missing, annotation.region.missing |
sheet_document_annotation_issues |
business rule, duplicate | removed in M5 |
finding.reference.missing, region.count_range.invalid |
sheet_document_reference_issues |
business rule, duplicate | removed in M5 |
reference.url.scheme |
sheet_document_reference_issues |
duplicate of the core's strict parse | removed in M5 |
| verdict structure: group keys and drawings match the document (§6.4) | completion RPC (new) | relational | added in M5 and M6 |
statuses: no to_confirm, no inherited, an absent review_status counting as inherited (new) |
publication and approval | declared defensive check | added in M5 |
- The status check is the one remaining mirror, declared as such: a
structural walk over
annotations[*],finding_zones[*].categories[*]and everychildren[*]below them, refusing an element whosereview_statusis absent,to_confirmorinherited. It is kept in SQL so that a worker defect can never make unread content official, and it follows the schema's default (inherited), which is why the absent case is explicit. A pgTAP case uses an omitted status. No other rule is mirrored. - Transition without an unprotected window: M5 replaces the publication gate by the verdict-based one and drops the mirror functions in the same migration. From M5 until M6 provides the worker RPCs, no verdict can be written outside pgTAP fixtures, so nothing can be published. DEV receives M4 to M6 together at the closure.
- Tests: the cases of pgTAP 008 and 011 that exercise mirror codes are deleted with the functions; the core's conformance fixtures already cover those codes. Pgtap 007 keeps a shape check of the seed; the curation tests keep checking its integrity with the core. The guards kept above get their own allowed and denied cases.
.claude/rules/sheet-model.mdno longer asks to add a rule « on both sides »: new rules go to the core only.
12.3 Migrations (names provisional)
| Id | Step | Content | Data on DEV |
|---|---|---|---|
M4 sheet_access_hardening |
V1-2.1 | anatomical_catalog_grants and its RPCs; has_mfa, grant_active, caller_has; can_read_official_catalog and the reader row predicate; can_edit_sheet redefined (F14); F1, F2, F3 (fork closed), F5, F6, F8, F9, F12 (every catalogue table), F13, F15; asset-row immutability trigger (F16); historical-sheet protection trigger (§14.2); reader column grants narrowed; personal creation and visibility changes refused |
no row changes |
M5 sheet_review_workflow |
V1-2.1 | version columns revision, authors, source_version_id, published_review_id, document_fingerprint; sheet column working_copy_source_version_id; revision, author and freeze triggers, the historical-sheet write rule; extended immutability guard (§6.8); rounds, comments, acknowledgments; create_official_sheet, create_sheet_draft adapted, save_sheet_draft, submit, withdraw, comment, acknowledge, decide, publish; create_sheet_working_copy; species RPCs; catalogue and version read RPCs; upload: register_sheet_asset extended, confirm_sheet_asset_upload with the storage check (F7), INSERT policy, bucket limit 2 MiB; mirror removal and status check (§12.2); superseded signatures dropped |
new columns take their defaults on the equine v1 row (revision 0, empty author set); its document, status, number and assets unchanged; bucket limit lowered; no round, no grant |
M6 sheet_verification_jobs |
V1-2.3 | worker RPCs (claim, input, complete with the verdict structure check, fail), service role only | none |
Each migration ships its pgTAP file (allowed and denied cases), regenerated
database.types.ts, a db:sandbox up upgrade run from the DEV state (with a
copy of the DEV drawing object), and is applied to DEV by the owner at the
closure, after a backup (SUPABASE.md §3.3 pattern). BLK-008 stays the rule:
no document schema bump in V1-2; verdicts, groups, authors and keys all live
outside the document.
13. Security
| Threat | Control |
|---|---|
| Privilege escalation through the catalogue | default deny; rights in their own table, written by the owner only with aal2; can_edit_sheet redefined; no table privilege for API roles or the service role; security definer functions with search_path = '', EXECUTE revoked from public and anon; superseded signatures dropped |
| Escalation through platform roles | open: AR-1 (§17.2) |
| Takeover of an admin or reviewer account | aal2 in RPCs and in the capability branches of policies; a verified factor required before a capability is granted; deactivation, expiry and revocation cut access at the next request; two factors for the owner |
| Recovery as a back door | no application path resets a factor; operator procedure with out-of-band identity check, capabilities revoked and sessions signed out first, an audit row (§5.6) |
| Self-approval | author set maintained by trigger and frozen at submission; no author acknowledges or approves; empty saves refused; content writes without an actor refused |
| Approval without reading | per-group acknowledgments against digests, refused on groups that still hold unread elements; any change re-opens the group; the server never relies on page rules such as « Marquer comme relu » |
| Unread content made official | to_confirm and inherited (absent statuses included) refused at approval and publication, in the verdict and in the SQL status check; the historical import is never a base; a base must have been published through a V1-2 round |
| Browser-supplied verdict | no RPC accepts a verdict, fingerprint or hash from a page; publication takes a round id only |
| Publishing outside the gate | the version guard requires an approved round with a passed verdict for any transition to published, for every role |
| Publishing something other than what was reviewed | frozen draft, round bound to a revision, verdict bound to sheet, version, revision and round and checked against the document's groups and drawings, fingerprint from the verdict, drawings' sha256 compared at publication, rounds withdrawn by core releases, atomic gate |
| Stale or replayed worker result | lease token, round state and revision checked at completion |
| Malicious SVG | core reader in the page before upload, refusal of active and external content, verification in the worker's sandboxed child, reading at every load and at export; the page never inserts stored bytes (core-composed tree only); production CSP |
| Wrong bytes under a hash | size checked in SQL at confirmation; sha256 at every load and in the verdict; asset rows immutable; no overwrite; object_conflict runbook |
| Concurrent edits | revision checks on save and submit, one draft per sheet, one non-terminal round per draft, one lock order |
| Draft leak to readers | reader row predicate on sheets, versions, assets and objects (only sheets with a published or deprecated version); reader column grants narrowed; one answer for unknown and forbidden; tests per actor |
| Catalogue read by any confirmed account | explicit catalogue access, fail-closed (§5.3) |
| Animal forms altered by a new species | species created inactive; policy not widened; activation by the owner |
| Historical equine sheet altered or removed | trigger and RPC refusals of saves, submissions, publications, deletions, archive, restore and asset changes on it, for every role; content writes without an actor allowed only there, for the seed |
| Labels and references in the UI | React escaping; the core escapes annotation titles; reference URLs http(s) only, opened with rel="noopener noreferrer" |
| Audit gaps | every RPC calls private.log_event (rights, species, saves, rounds, verifications, acknowledgments, comments, decisions, uploads, publications) |
| Service key | the worker and the operator tool only, through RPCs |
| Size and volume | content 2 MiB serialised, drawing 2 MiB, comment 4 000 characters, change note 1 000, verdict bounded; per-actor write budget as V1-1 D15 (thresholds in V1-2.1) |
Residual risks:
- AR-1 until the owner decides (§17.2);
- the service key is also a GoTrue admin credential: whoever holds it can delete factors and sign in as anyone, so MFA does not protect against a service-key holder; the key stays on the server, in the worker and in the operator's environment;
- a capability does not prove a professional qualification: the owner's verification note is a declaration until Step 9;
- the owner can create and habilitate a second account of its own; traced, not detectable (§5.5);
- a stolen
aal2session stays usable until it ends, since no freshness window or session limit is set (§5.6); - a capability holder can still ask Storage for a signed URL to a draft drawing through the API; such a URL outlives a later revocation until it expires;
- reviews depend on a running worker; without it, they wait (fail-closed);
- a later core change could make published versions unloadable, which the replay gate of §15 catches before release;
- raising the archive caps later is an archive contract change: older readers refuse bigger snapshots;
- RR-2 stays open (§16.12).
14. Equine sheet
14.1 Inventory, and what it is not
839 status-bearing elements: 28 annotations, 81 finding categories, 730 nodes.
188 to_confirm, 31 reviewed, 620 inherited (omitted in the file, the
schema's default). None of these numbers is a scientific validation:
- the 31
reviewedwere set by the R5 curation changeset in Git, never by an approved round with a business reviewer: they still need the coverage of an acknowledged group in an approved round (the working copy has no base, so every group is to cover); - the 188
to_confirmare open doubts; - the 620
inheritedare the historical content, used in the former tool but never reviewed; 26 of them, on the carpus, were added by a level B change and carry the wrong label.
Under O3 B, every one of the 839 elements is read and covered by an approved round before any first publication of an equine sheet.
14.2 The historical sheet
- Sheet
503dc301-a8b1-50d4-9e44-0919b2fc2916, its draft v1, its asset row and object stay as they are on DEV and in Git. No V1-2 step modifies, submits, publishes, archives or deletes them. - The server identifies it by its fixed id, which the core's alias registry
already pins. Every lifecycle RPC refuses it (
sheet.historical_read_only: save, submit, publish, delete version or sheet, archive, restore, register or delete an asset), and a trigger (M4) refuses, for every role, the deletion of its versions and asset rows and any change of its sheet row's status. A content write without an authenticated actor is allowed on it only, so the converging seed keeps working. - The admin space shows it with the badge « Fiche historique (pipeline Git) », read-only: views, findings, preview, completeness, and the action « Créer une copie de travail ».
- The Git pipeline stays unchanged during V1-2: no changeset is applied, no
file of
legacy-import/ordraft/is regenerated, andpnpm r5:import-equine --checkkeeps reporting no difference. The oracles are preserved; any regeneration (RR-10) needs a dedicated owner checkpoint. - Conservation: never deleted (the core's v0 alias and the legacy lineage depend on its id, and the seed would not recreate a soft-deleted row), never published, never submitted. At the earliest, it is archived at the V1-3 switch, by an owner decision and a migration that lifts the trigger for that act only.
- Freeze and seed (C11): the historical sheet never enters a round, so the freeze trigger never blocks the converging seed; the seed targets that one sheet id, so it never writes the working copy.
14.3 The working copy (O17 C)
create_sheet_working_copy(source_version_id, slug), a server operation:
- caller: sheet editor with
aal2; - source: a version of the historical sheet, and no other sheet. This restriction keeps it distinct from the deferred general copy (O11) and from packages (O13);
- at most one
activeworking copy per historical sheet; archiving a copy frees the slot; - every asset row the source document references must be uploaded, with an object of the recorded size in Storage; otherwise one closed answer and nothing is created;
- creates a new official sheet: null creator, the source's species, the given
slug, the name from the document,
working_copy_source_version_idset; - registers the source drawings for the new sheet (same sha256, size and file
name,
uploaded_atset after the storage check; no upload, the objects are shared); - creates its draft v1: the source document verbatim (size checked as in
§6.2), drawing ids remapped to the new rows (
remap_document_assets), review statuses kept as they are, no base, author set {caller}, revision 0, a change note naming the source sheet, version and revision; - audits
anatomical_sheet.working_copy_createdwith the source sheet, version and revision; - creates no round, no approval, no publication, and writes nothing to the source.
The copy's fingerprint differs from the bundle's, since its drawing ids differ. The admin space shows it with the badge « Copie de travail ». No step of V1-2.0 runs it; on DEV it is an owner-authorised operation (§16.11).
14.4 One source of truth
- Before the working copy exists, the Git pipeline is the only place where equine content changes, as today.
- The working copy created on DEV, after the owner's authorisation, is the single source of truth of equine work. Working copies on the sandbox are rehearsals; nothing done there, acknowledgments included, carries to DEV, since packages are deferred (O13).
- Once the DEV copy exists, equine content changes only in it, through the application; the Git pipeline and the historical sheet stay unchanged.
- The report editor keeps the bundled Git draft until V1-3 (D7).
- At V1-3, an owner checkpoint chooses the reference sheet. The expected candidate is the working copy's first published version, after the full business review. The historical sheet is then archived; old bilans keep their snapshots; the v0 alias stays bound to the historical sheet's id.
- An abandoned working copy is archived (or deleted while it has no round); a new one can then be created.
14.5 Corrections and open decisions (O18)
Certain corrections, documentary or technical, made in the working copy and its review dossier, rehearsed in V1-2.8 on the sandbox and made on DEV only after owner authorisation:
- the 26 carpus elements labelled
inheritedare requalifiedto_confirm; - the 11 level B changes missing from
REVIEW-REPORT.mdare listed in the review dossier; the Git file stays as it is, the pipeline being unchanged; - the dossier, posted by the editor as comments of the first round with the
group key and the element keys in the body: the 11 open questions, the 11
level B changes, the legal text to re-read on Légifrance; the 188
to_confirmneed no list, the verdict gives them per group.
Open anatomical decisions, left to business reviewers: the overlapping carpus
and elbow areas, the 10 moved points, every anatomical choice, the content of
every inherited element. An editor carries out a decision only from a
reviewer's comment that names the element, and the reviewer's acknowledgment
of the changed group validates it (§6.3). No administrator, and not Claude,
decides one.
No equine content changes in V1-2.0. No scientific validation is invented.
14.6 Progressive review of the equine sheet
The working copy's first round has 30 groups and lists all 839 elements (no
base). The expected course, over several rounds: the reviewer reads a few
zones and answers in comments, then requests changes; the editor applies the
answers, marks the read zones reviewed and resubmits; the reviewer
acknowledges the zones that are now finished and reads the next ones. A
finished zone that does not change keeps its acknowledgment in later rounds.
The final approval needs all 30 groups acknowledged, no to_confirm and no
inherited left. Publication of the equine sheet stays outside V1-2.
15. Tests and Definition of Done
- SQL (pgTAP on PGlite and on the real image):
- every RPC allowed and denied per actor class of §5.4, including « owner
or admin without capability », « capability without
aal2», expired, revoked and renewed grants, and a grant refused to an account without a verified factor; - catalogue access per §5.3; a draft-only sheet invisible to readers; drafts, rounds, grants and pending objects unreadable to readers;
- an author can neither acknowledge nor approve; a reviewer cannot publish; an approval by a revoked reviewer cannot be published, and counts again after a renewal;
- moderator, support, unconfirmed, deactivated, anonymous refused;
- frozen draft; revision conflict on save and submit; content write without an actor refused, except on the historical sheet;
- each rule of §6.7 failing alone, the status check with an omitted status included; each failure of §6.5 (fixture completions with a stale token, another revision, after withdrawal, wrong groups, wrong drawings);
- a direct UPDATE to
publishedrefused for every role, the service role included; asset-row changes refused; - acknowledgments: digest mismatch refused, refused on a group with unread elements, carry over an unchanged group, no carry after a change or for an author, removal groups to cover;
- base: set only from a version published through a round;
- species: an inactive species invisible to
fetchSpeciesLabels's query for every account, refused bycreate_animal, accepted for an official draft, refused at publication; activation and renaming by the owner only; - working copy: source restricted to the historical sheet, one active at a time, archiving frees the slot, source rows unchanged, statuses verbatim, no base;
- historical sheet: every lifecycle RPC and the trigger refuse it;
- deprecated version deletion refused; D8 reads after archive and deprecation; superseded signatures and mirror functions absent; upgrade from the DEV state.
- every RPC allowed and denied per actor class of §5.4, including « owner
or admin without capability », « capability without
- Concurrency on the real stack, two sessions: two saves, save against submit, publish against withdraw, two publishers, deprecate against publish, completion against withdrawal.
- Performance, on a synthetic document at the caps (1 024 annotations, 8 192 nodes): save, submit and publish under 2 s each, verification under 120 s (proposed budgets, measured in V1-2.1 and V1-2.3 and fixed at the V1-2.3 checkpoint).
- Core: every edit primitive outputs a strictly parseable document, keeps
existing keys and applies the status rules (property tests); groups,
digests and removal groups; the change list; the verdict function;
PreviewSheetchecks (hash, fingerprint, caps) and redraw after a document replacement, an invalid draft included; the SVG classification and cleaning on the committed vector-tool exports and the hostile corpus, and the cleaning fixpoint; caps fixtures at cap − 1, cap, cap + 1 and with astral characters; wasm facade and ts-rs types; the N-1 reader untouched; the frozen oracles green. - Worker: the verification mode, verdicts accepted and each failure, the
hostile SVG corpus in the sandboxed child, per-command limits and watchdog,
the purge guard by bucket, sandbox tests and seccomp derivation, an e2e on
the sandbox stack with the verification worker running;
pnpm e2e:avatarandpnpm e2e:sheet-assetsunchanged in outcome. - Release replay: a script loads every published version and drawing of a stack through the new core and fails on any regression.
- Application: failure codes to FR and EN messages, editor state (undo,
conflict, local recovery, leave guard), rights-driven actions, MFA
enrolment, step-up and refresh behaviour, no
aal1enrolment of a second factor. - Browser (
e2e:shellon the sandbox, never DEV): journeys A0 to A8, S1, W1, R1, P1 with two accounts (an editor and publisher, a reviewer) plus reader assertions, TOTP codes generated by a test helper (NodecryptoHMAC, no dependency, V1-2.5); axe; 320 to 430 px for the catalogue, 375 px for admin screens; FR and EN. - Each step:
pnpm check:all, fresh verifier against this contract, fresh security audit.
16. Implementation steps
Every step works on the sandbox stack only; DEV changes are owner actions
listed in §16.11. All steps are MVP: D9 and the fundamental requirement make
administration essential. Rollback for every code step: nothing reaches DEV
before the closure, so a rejected step is reverted on the branch and the
sandbox rebuilt with pnpm db:sandbox up fresh; on DEV, migrations are
forward-only, applied after a backup, and a failed application is restored
from that backup by the owner.
The brief's twelve items map to the steps: 1 contract → V1-2.0; 2 SQL hardening, 3 review workflow, 4 catalogue, draft, version and asset API → V1-2.1; 5 core loading and validation → V1-2.2; the server verdict → V1-2.3; 6 catalogue, 7 administration → V1-2.5; 8 drafts, 9 drawings, annotations, categories, references → V1-2.6; 10 preview and validation → V1-2.7; 11 equine → V1-2.8; 12 acceptance and closure → V1-2.9.
Owner checkpoints: V1-2.0 (final review of this contract, AR-1), V1-2.3 (server workflow and verdict), V1-2.4 (wireframes), V1-2.6, V1-2.7, V1-2.8 (with the business reviewer), V1-2.9 (closure, merge), and each DEV operation of §16.11.
Critical path: V1-2.1 and V1-2.2 in parallel, then V1-2.5, V1-2.6, V1-2.7. The worker step V1-2.3 runs beside V1-2.5 and V1-2.6 and is needed from V1-2.7 on.
16.1 V1-2.0 Contract and decisions
- Objective: this document, the ratified decisions (§17), the documents of §18, the challenge record (§19).
- Dependencies: D1 to D9 (BDR-081), O1 to O23 (BDR-082).
- Security prerequisites: none (documents only).
- Application changes: none. SQL changes: none.
- Tests: documentary checks only (cross-references, ids, tables).
- Acceptance: the owner's final review finds no contradiction; AR-1 decided; ratification recorded.
- Rollback: revert the documentary commits.
- Checkpoint: owner, final review; V1-2.1 starts only on the owner's go.
16.2 V1-2.1 Server access, workflow and uploads (M4, M5)
- Objective: rights, catalogue access and MFA predicates; lifecycle hardening
(F1 to F16); drafts with revisions and author sets; rounds, comments,
acknowledgments, decisions; the publication gate on a verdict (verdicts
written by pgTAP fixtures until V1-2.3); species RPCs; the working copy RPC;
the historical-sheet protection; the upload RPCs and policy; removal of the
SQL mirror and the status check;
packages/supabase/src/sheets.tswith closed failure kinds; the client gate deleted. - Dependencies: V1-2.0 go, AR-1 decided.
- Security prerequisites: effective grants of the service role recorded on
the sandbox before F12's fix; census of private functions updated (pgTAP
001); every RPC requires
aal2except the reader RPCs. - Application changes:
packages/supabaseaccessors and regenerated types; no screen. - SQL changes: M4, M5 (§12.3).
- Tests: one test per defect red on the old code then green (F1, F2, F3, F5, F6, F8, F9, F12, F13, F14, F15, F16); the SQL list of §15; pgTAP 005 to 008 and 011 adapted where they asserted the old behaviour (005 l.551 flips, mirror cases removed); concurrency; performance at the caps.
- Acceptance: on the sandbox, with two accounts, the whole cycle runs in SQL:
grants, create, save, conflict, register and confirm a drawing, submit,
fixture verdict, comment, acknowledge, request changes, carry, approve,
publish, deprecate, archive, read by id; every refusal of §15 proven;
working copy created from the seeded historical sheet with its drawing; an
inactive species invisible to the animal path; types check clean;
pnpm check:allgreen. - Rollback: branch revert; sandbox rebuilt.
- Checkpoint: gates only (owner at V1-2.3).
16.3 V1-2.2 Core: verdict, preview handle, edit primitives, SVG cleaning
- Objective, in this order: the verdict function (strict parse, issues, caps,
drawings, fingerprint, completeness, groups, digests, removal groups, change
list) and
PreviewSheetas the catalogue, preview and editor handle, withview.canvason it; thensheet.editprimitives with the status rules of §6.6,dependents, SVG classification and cleaning (§9.2). - Dependencies: V1-2.0 go; runs in parallel with V1-2.1.
- Security prerequisites: none of the protected readers is touched; any need to change one stops the step for an owner decision.
- Application changes: wasm facade and ts-rs types only. SQL changes: none.
- Tests: cargo units and properties, caps fixtures, committed vector-tool exports, hostile corpus, cleaning fixpoint, wasm proofs, N-1 test, oracles.
- Acceptance: hash and fingerprint mismatches refused; the equine draft previews with the same index and fingerprint as from the bundle; an invalid draft draws with its issues; a document replacement redraws without re-reading the drawings; the groups of a derived version that deletes a zone include its removal group; vector-tool exports cleaned and hostile files refused.
- Rollback: branch revert.
- Checkpoint: gates only.
16.4 V1-2.3 Worker verification (M6)
- Objective: the verification mode of the worker (§6.4) and its failures (§6.5); the verification worker running against the sandbox stack.
- Dependencies: V1-2.1, V1-2.2 (verdict part).
- Security prerequisites: the verdict runs in the keyless sandboxed child; per-command limits; seccomp derived again; purge guard by bucket; no worker started on DEV.
- Application changes: worker mode, child command, spawner limits per
command, compose service under the
workerprofile, sandbox start of the verification worker; no screen. - SQL changes: M6 (§12.3).
- Tests:
pnpm worker:test, hostile corpus, e2e on the sandbox, each failure of §6.5, upgrade rehearsal with a copy of the DEV object;pnpm e2e:avatarandpnpm e2e:sheet-assetsunchanged. - Acceptance: verdict accepted on a clean sheet; each failure produced and its exit working; a stale or malformed completion writes nothing; avatars and purges unaffected; publication refused without a current passed verdict; the sandbox working copy verified in place with its shared drawing; verification time at the caps within budget.
- Rollback: branch revert; the worker image exists on the sandbox only.
- Checkpoint: owner validates the server workflow (V1-2.1 to V1-2.3).
16.5 V1-2.4 Wireframes (parallel to V1-2.1 to V1-2.3)
- Objective: editor canvas, review screen with groups and acknowledgments, admin entry in the sidebar; the new state labels of §3.
- Dependencies: V1-2.0 go.
- Security prerequisites: none. Application and SQL changes: none.
- Tests: none; design toolchain review.
- Acceptance: owner-validated file in
docs/design/with its README line. - Rollback: none needed.
- Checkpoint: owner validation of these screens.
16.6 V1-2.5 Administration space, rights, species, MFA, catalogue
- Objective, in this order: MFA enrolment, step-up and factor management;
admin list and filters, sheet creation, overview, rights screen, species
list with creation, activation and renaming, sidebar entries, failure codes
in FR and EN; then
/app/anatomy(P1). - Dependencies: V1-2.1, V1-2.2; V1-2.4 for the admin entry.
- Security prerequisites: server rules of V1-2.1 in place; the UI is never the boundary.
- Application changes: routes and screens of §11.1 except the editor and the review screen; Mon compte, Sécurité; the TOTP test helper. SQL changes: none.
- Tests: unit;
e2e:shellA0, A1, S1, P1; access per right; MFA required; refresh keepsaal2; noaal1enrolment of a second factor; axe; 320 to 430 px for the catalogue, 375 px for admin screens; FR/EN. - Acceptance: the owner with MFA grants rights and creates a sheet; an editor creates an inactive species that the animal forms do not show until the owner activates it; a sheet published on the sandbox through SQL fixtures is browsable by a catalogue reader and refused to a confirmed account without access; drafts never listed; archived sheets absent from the list and readable by id; every other actor refused in the UI and in SQL.
- Rollback: branch revert.
- Checkpoint: gates only (owner at V1-2.6).
16.7 V1-2.6 Editor level 1
- Objective: §8.2: structured tabs, drawing upload with cleaning, views and crops, point, zone and link drawing, annotation properties, finding tree, review markings, local recovery, conflicts, narrow-screen read-only mode.
- Dependencies: V1-2.1, V1-2.2, V1-2.4, V1-2.5 (not V1-2.3).
- Security prerequisites: stored bytes never inserted into the page; only core-composed trees rendered.
- Application changes: the draft editor. SQL changes: none.
- Tests:
e2e:shellA2, A3, A4 with a conflict and a local recovery; keyboard path through numeric fields; axe; read-only below 1 024 px. - Acceptance: a sheet for a species other than the horse, with a drawing
exported from a vector tool and cleaned, a detail view, points, zones,
links and a finding catalogue, is built from scratch in the UI on the
sandbox, saved and submitted; its validation panel shows no error while its
elements are still
to_confirm(C7), and the round reachesverifying. - Rollback: branch revert.
- Checkpoint: owner tries it.
16.8 V1-2.7 Preview, review and publication UI
- Objective: preview as a practitioner, verification states and failures, round screen with groups, changes, acknowledgments, comments and decision, withdrawal, publication confirmation, deprecation and archive.
- Dependencies: V1-2.3, V1-2.6.
- Security prerequisites: separation of duties enforced in SQL, shown in the UI.
- Application changes: review and publication screens. SQL changes: none.
- Tests:
e2e:shellA5, R1, A6, A7, A8 with two accounts and the verification worker running; S1 refusals; a verification failure and its resubmission. - Acceptance (fundamental requirement): on the sandbox, an editor and publisher creates a sheet for a non-equine species, prepares its views, annotations and categories, submits; the verification passes (structurally valid); a reviewer comments on some groups and requests changes; the editor applies them, marks the read groups and resubmits; the reviewer acknowledges them, and in a later round the remaining ones while the first acknowledgments carry; the reviewer approves; the editor publishes; a catalogue reader sees the version. The round columns required for each state of §6.3 are filled. A new version corrects it, only its changed groups need acknowledging, and the first version stays readable by id.
- Rollback: branch revert.
- Checkpoint: owner runs the journey with a second account.
16.9 V1-2.8 Equine working copy and review preparation (rehearsal)
- Objective: §14 on the sandbox: the working copy (W1), the certain corrections of O18, the review dossier, the first submission. A rehearsal of what the owner authorises later on DEV (§16.11).
- Dependencies: V1-2.7.
- Security prerequisites: the historical sheet protected on the server.
- Application changes: none beyond V1-2.7, unless the dossier reveals a gap. SQL changes: none.
- Tests: content hash of the historical version before and after;
pnpm r5:import-equine --checkwith no difference; oracles untouched. - Acceptance: on the sandbox, the working copy exists with statuses equal to the source except the 26 requalified elements; its first round is open with 30 groups and the dossier comments; nothing approved or published; the historical sheet byte-identical.
- Rollback: rebuild the sandbox.
- Checkpoint: owner and the business reviewer.
16.10 V1-2.9 FR/EN acceptance, documents and closure
- Objective: full journeys in FR and EN; documents (
ANATOMICAL_SHEET_MODEL,SUPABASE,STORAGE,IDENTITYwith the MFA and recovery runbook,IMPLEMENTATION_PLAN,CLAUDE.md,.claude/rules/sheet-model.md,CHANGELOG); the DEV procedure for M4 to M6, the worker activation runbook and theobject_conflictrunbook; the release replay; the closure inventory. - Dependencies: V1-2.1 to V1-2.8.
- Security prerequisites: fresh security audit of the whole branch; recovery runbook rehearsed on the sandbox.
- Application and SQL changes: fixes only.
- Tests:
pnpm check:all,e2e:shell, release replay. - Acceptance: every gate green; fresh verifier conformant; the DEV procedure rehearsed on a sandbox upgraded from the DEV state. Running the fundamental journey and the equine work on DEV follows the owner's authorisations of §16.11 and is not a closure criterion.
- Rollback: branch revert; nothing merged.
- Checkpoint: owner; merge only on the owner's go.
16.11 Operations on DEV that need their own owner authorisation
Each is an owner action, never run by Claude, after its own checkpoint:
- applying M4 to M6, after a backup and a sandbox rehearsal from the DEV state;
- enrolling the owner's two TOTP factors and the first rights grants;
- starting the verification worker on DEV: a separate operating checkpoint that first inventories the queues (the avatar upload waiting since AVATAR-01, the due purge rows, quarantine leftovers), states the expected effects of each worker mode and the image version, and gets the owner's go;
- creating, activating or renaming a species;
- creating the equine working copy and applying the O18 corrections;
- any submission, approval, publication, deprecation or archive;
- any factor reset (§5.6) and any
object_conflictdeletion (§9.3); - rerunning the equine seed.
16.12 Deferred (not V1-2)
Level 2 editor (§8.3); copy of a finding catalogue between sheets (O11);
package export and import (O13); authoring in production; the reference sheet
per species and the switch of the report editor, version links in bilans and
storage of report migration maps (V1-3); personal and community sheets,
sharing, follows, forks, students; rights scoped by species or sheet; review
quorum (O5); e-mail notifications; species deactivation and deletion; Storage
object deletion beyond the object_conflict runbook; offline cache;
professional verification (Step 9); entitlements (Step 11, switch of §5.3); a
synchronous verification service. RR-2 (fingerprint rollback limit, RUST.md
§11.22) stays open on the release track: before any release to users, a gate
requires it settled, by shipping the switch with the release or the alias
registry in any build that can be rolled back to; V1-2 does not resolve it.
17. Ratified decisions and open arbitration
17.1 Ratified decisions O1 to O23
Ratified by the owner on 2026-10-28 (BDR-082). Options B of O15 and C of O4, which would have accepted a browser verdict or deferred MFA, are rejected.
| Id | Decision | Where |
|---|---|---|
| O1 | A + D: three explicit capabilities (sheet_editor, sheet_reviewer, sheet_publisher), granted and revoked by the owner; editor and publisher need a platform role owner or admin; reviewers may be confirmed non-admin accounts; every grant audited, with a required reason, a verification note, a date and an optional expiry; e-mail confirmation is no proof of competence |
§5.1, §5.2 |
| O2 | A: no author acknowledges or approves; author set frozen at submission and checked on the server; two people suffice; the publisher may be the approver; no silent override for a sole owner | §5.5 |
| O3 | B: no to_confirm and no inherited (absent statuses included) at approval or publication; the historical import is never a base; new elements start to_confirm; changes re-open coverage |
§6.6, §6.7, §14 |
| O4 | A: aal2 for every catalogue operation except reading the published catalogue; enrolment, step-up, sessions, loss and operator recovery documented; O4-D evaluated, not ratified, now the subject of AR-1 |
§5.6, §17.2 |
| O5 | A: one approval closes a round; trace kept for a future quorum | §6.3 |
| O6 | A: scope disclaimer required, present in FR and EN and non-blank after trimming; equine texts untouched | §6.7 |
| O7 | A: new elements start to_confirm; nothing assigns reviewed or inherited automatically; draft state, element marking and business approval distinguished |
§6.6 |
| O8 | A: published and deprecated versions immutable, never deleted physically, readable by id under catalogue access after archive or a newer publication | §6.9 |
| O9 | C: editors create inactive species; the owner activates (and may correct names); inactive species invisible in animal forms and refused at publication; ids never renamed; other refused; nothing generated; N1 amended |
§7.2 |
| O10 | A: several official sheets per species, each with its identity, slug, versions and rounds; the reference sheet is a V1-3 decision | §7.3 |
| O11 | B: copy of a finding catalogue between sheets deferred; the equine working copy is a distinct operation | §2, §7.4 |
| O12 | A: explicit save, leave guard, local recovery, revision conflicts, author sets | §6.2 |
| O13 | A: package export and import deferred; consequences for transfers and production authoring recorded; the server-side working copy stays allowed | §2, §14.4, §16.12 |
| O14 | A: draft editor read-only below 1 024 px; catalogue, preview and admin screens usable on narrow screens | §8.4 |
| O15 | A: verdict computed by the asynchronous Rust worker in its sandboxed child, bound to sheet, version, revision, canonical document, drawings, results and round; no browser verdict; no HTTP service; worker activation on DEV is a separate checkpoint | §6.4 |
| O16 | A, adjusted: routes and labels as proposed, inherited shown « Hérité, non relu » / « Inherited, not reviewed »; messages for errors, states and validations in FR and EN |
§3, §11.1 |
| O17 | C: the historical sheet stays intact in its pipeline and protected on the server; a server-side working copy carries the equine work in the application; the DEV copy is the single source of truth; reference chosen at V1-3; the copy is not run in V1-2.0 | §14.2 to §14.4 |
| O18 | Mixed: carpus requalified to_confirm and the 11 level B changes listed in the dossier (certain); overlaps, moved points and anatomical choices to business reviewers (open); oracles preserved |
§14.5 |
| O19 | A: cleaning before upload with preview and confirmation, refusal of active and external content, server check kept, no silent change of a stored drawing | §9.2 |
| O20 | Deferred to the release track; RR-2 open; gate before any release to users | §16.12 |
| O21 | Catalogue access as an explicit, provisional, fail-closed right until the entitlements of Step 11; layers distinguished; reader row predicate; tests per actor | §5.1, §5.3 |
| O22 | Rust core the only authority on document rules; SQL keeps access, relations, states, revisions, locks, atomicity and the verdict's identity; the business mirror is removed in M5 without an unprotected window; one declared status check kept | §12.2 |
| O23 | Fail-closed verification: explicit states and outcomes, closed codes per category, idempotent retries under a limit, withdrawal always possible, audit, no partial publication | §6.5 |
17.2 Open arbitration AR-1: MFA on platform role grants (O4-D)
Finding (security challenge, §19.3, confirmed by reading
20261008100200_platform_roles.sql l.83-95 and l.189-238): an owner may grant
any platform role, owner included, and grant_platform_role does not check the
assurance level. From a stolen owner session at aal1 (password only), an
attacker grants owner to an account of their own; that account enrols its
own TOTP factor, reaches aal2, grants itself every capability (§5.2) and a
reviewer capability to a third account, then may revoke the real owner. Every
aal2 control of the catalogue is bypassed. O4-D (extending aal2 to these
RPCs) was explicitly left unratified, so this contract cannot close the gap on
its own.
Options for the owner:
- A (recommended): ratify O4-D at least for granting and revoking
ownerandadmin, the roles that make an account eligible forsheet_editorandsheet_publisher:has_mfa()ingrant_platform_roleandrevoke_platform_rolefor those roles, in M4, with pgTAP cases. Cost: one predicate; it changes a V1 identity contract and requires the owner's session ataal2to manage those roles. - B: ratify O4-D for every platform role. Same cost, broader.
- C: keep the RPCs unchanged and accept the residual explicitly. Then the catalogue's MFA protects against a stolen editor or reviewer password, not against a stolen owner password.
Until the owner chooses, V1-2.1 does not start (§16.2).
18. Documents touched by V1-2.0
First revision (2026-10-27):
docs/development/V1-2_ANATOMICAL_SHEETS.md(this file, new).docs/development/V1-1_OWNERS_ANIMALS.md: status lines (applied to DEV, browser acceptance, merged intodevelop9135d73).CLAUDE.md: the stale « not applied to Supabase DEV » sentence of the roadmap paragraph, and a pointer to this contract..claude/tasks/TODO.md: V1-1 closed and merged; V1-2 entry..claude/memory/decisions.md(BDR-081),.claude/memory/journal.md.
Consolidation (2026-10-28):
- this file: decisions ratified, contradictions resolved, steps restated, second challenge round integrated, AR-1 open;
docs/development/IMPLEMENTATION_PLAN.md: §0 roadmap row of V1-2, Steps 13 and 17 notes (editor scope moved into V1-2 for official sheets), Step 13's stalecontent_jsonb;docs/development/ANATOMICAL_SHEET_MODEL.md: stale Zod and TypeScript mentions fixed, pointers to the V1-2 rules that will replace the lifecycle, access and validation tiers (the file keeps describing the model as built until V1-2.9);docs/development/OPEN_QUESTIONS.md: conflicts 1 and 2 updated by D9, D3 and O17;docs/development/V1-1_OWNERS_ANIMALS.md: pointer from §5.4 to the amendment of §7.2;.claude/rules/sheet-model.md: rule source in the core only, uploads through the application after M5, the historical sheet and its working copy;CLAUDE.md: roadmap pointer updated;.claude/tasks/TODO.md,.claude/memory/decisions.md(BDR-082),.claude/memory/journal.md.
Not touched, with stale content_jsonb mentions left for V1-2.9:
BACKEND_ARCHITECTURE.md l.110, DOMAIN_MAP.md l.119.
19. Challenge record
19.1 First round (2026-10-27)
Three fresh plan challengers read the first draft against the repository.
| Lens | Verdict | Main findings and what changed |
|---|---|---|
| Correctness | FATAL (2 blockers) | Deprecated versions deletable (F13 added, §6.9); to_confirm relabelled inherited bypassed D2 (§6.6); finding ids unique among siblings only (element keys); client fingerprint stored unchecked (verdict, §6.4); S1 too narrow (author set); sheet metadata outside review (row refreshed at publication); old publish signature kept (dropped); can_edit_sheet unchanged (F14); optional map would touch protected readers (PreviewSheet); map unbound to review (map storage moved to V1-3); seed tool broken by F12 (read RPC); code counts corrected (19 errors, 17 mirrored); F3 reworded |
| Robustness | FATAL (1 blocker) | Quarantine-only job could never verify the DEV drawing (in-place verification, no quarantine copy, §9); commit order, retries and shared keys (no overwrite, object_conflict, existence and size check in SQL); stopped worker blocked authoring (authoring needs uploaded only); fingerprint and deprecation guard (verdict value, extended guard); caps only partly on the server (verdict carries all caps); converging seed and ids across environments (packages and production authoring deferred); lock order; MFA in policies and recovery; local recovery, undo by size, lowercase ids; timing at the caps; release replay; worker isolation and purge guard; no species deactivation |
| Simplicity | CONCERNS | Steps cut by vertical; single verdict instead of a growing SQL mirror; quarantine pipeline dropped; package import and production authoring deferred; review rows slimmed; « Marquer comme relu » on subtrees; SVG cleaning before upload; wireframes only for new patterns; no sheet-row metadata RPC; map storage to V1-3; generic edit primitives. Kept against the finding: three capabilities and the worker verdict, later ratified as O1 and O15 |
19.2 Contradictions found at the owner's review (2026-10-28)
| Id | Contradiction | Resolution |
|---|---|---|
| C1 | §14 called the legacy import the equine base, §6.4 said a new sheet has none | the historical import is never a base; a first publication needs a real review of every element (§6.6, §14.1) |
| C2 | under the former rule, an inherited element edited in place kept its status and escaped the change list |
inherited blocks acknowledgment, approval and publication whatever the base; edits set to_confirm; coverage rests on group digests (§6.3, §6.6) |
| C3 | the former option O15 B trusted browser computations | rejected; worker verdict only (§6.4) |
| C4 | the former option O4 C deferred MFA | rejected; aal2 everywhere except catalogue reading (§5.6) |
| C5 | the former proposal reserved species to the owner and made them visible at once | inactive creation by editors, owner activation, policy not widened (§7.2) |
| C6 | the former acceptance relied on copying a finding catalogue | copy deferred, absent from every acceptance criterion (§7.4, §16) |
| C7 | the former V1-2.6 acceptance « passes every verdict rule except review » conflicted with new elements in to_confirm |
four stages: structurally valid, approvable, approved, publishable (§6.7); acceptance rewritten (§16.7) |
| C8 | the former text kept the SQL mirror « as it is » beside the verdict | inventory and removal in M5, structural guards and one declared status check kept (§12.2) |
| C9 | no state for a failed verification | verifying and verification_failed with outcomes and codes, retries, withdrawal (§6.1, §6.5) |
| C10 | the worker dependency on DEV was implicit | stated, with a separate operating checkpoint because of AVATAR-01 (§6.4, §16.11) |
| C11 | freeze against the converging seed under the former O17 A | the historical sheet never enters a round; the seed never writes the working copy (§14.2) |
| C12 | consequences of moving a node were unstated | moving to another parent deferred to level 2 (delete and re-create in level 1); keys, statuses, comments, descendants and earlier validations stated (§6.6) |
| C13 | scope of the capabilities was unstated | global rights, owner attribution, eligibility, per-sheet rules (§5.2) |
| C14 | step dependencies ignored O9, O17, O21, O23 | steps restated with their prerequisites; the core step before the worker step; the editor independent of the worker (§16) |
Two defects of the first revision were also corrected: M4 redefined
can_edit_sheet on a capability table that M5 created (the rights table now
lives in M4), and the worker step depended on a core step planned after it
(the core is now V1-2.2, the worker V1-2.3).
19.3 Second round (2026-10-28)
Three fresh challengers read the consolidated revision: business coherence (correctness lens), security and data (robustness lens), simplicity and feasibility (simplicity lens). Each finding was checked against the repository before being integrated; none changed a ratified decision.
| Lens | Verdict | Main findings and what changed |
|---|---|---|
| Business coherence | CONCERNS (3 major, no blocker, no arbitration) | Acknowledgments voided by the later marking, so every equine group acknowledged twice (protocol « editor marks, then reviewer acknowledges », acknowledgment refused on groups with unread elements, §6.3, §14.6); removed zone or view had no group to cover (removal groups); working copy slot blocked by an archived copy (only active copies count); anatomical decisions carried out by editors from reviewer comments (§14.5); grant expiry and renewal semantics (§5.2); owner missing from the species list (§5.4); round columns per state (§6.3); base from deprecated or pre-V1-2 versions (base only from a V1-2-published version, §6.2); deprecating the last published version (§6.9); DEV copy as the single source of truth, sandbox copies as rehearsals (§14.4); cleaning table misdescribed the reader (§9.2); published_by already exists (M5); O6 « structure » defined; active species names (owner renaming) |
| Security and data | FATAL (1 blocker as arbitration request, 6 major) | AR-1: an aal1 owner session grants the owner role and bypasses every catalogue MFA control (§17.2, open); the defensive status check could not see omitted statuses (structural walk, absent = inherited, §12.2); service-role privileges and direct publication (F12 unconditional, guard requires an approved round with a passed verdict, asset-row immutability F16, sha256 compared at publication, GoTrue residual in §13); readers could list draft-only sheets through the public branch (reader row predicate, F15); historical sheet deletable or archivable (RPC refusals and trigger, §14.2); poisoned content-addressed key without exit (object_conflict runbook with an audited scoped deletion, earlier detection by PreviewSheet, §9.3); first-factor trust on first use (verified factor required before a capability, recovery revokes and signs out first, aal1 enrolment test); minor: serialised size, worker body cap, base from legacy publications, verdict structure checked in SQL, predicates split by caller and stored actor, signed URLs (residual), cleaning fixpoint |
| Simplicity and feasibility | CONCERNS (5 major, no arbitration) | Editor step waited for the worker step (uploads moved to M5, editor independent of V1-2.3, verification passing moved to V1-2.7); worker changes understated (separate verification mode and container, per-command limits, avatar lease reused without backoff, sandbox worker a deliverable); no editor render path (PreviewSheet as the editor handle with document replacement and view.canvas); overlapping coverage rules (one rule on group digests, change list for display only, no earlier digests sent to the worker); status check blind to omitted statuses (fixed as above); minor: core step ordered verdict first; level 1 trimmed (no move to another parent, no dragged vertices, numeric crop); two cleaning classes; rules epoch replaced by release migrations withdrawing rounds; two failure outcomes with categorised codes; comments with a group key only; time budgets and named fixtures; TOTP test helper; register_sheet_asset extended instead of a new RPC; purge guard by bucket. Not taken: moving the working copy RPC to V1-2.8 (it stays in M5 so DEV receives one set of migrations) |