2994 lines
218 KiB
Markdown
2994 lines
218 KiB
Markdown
# V1-2 Anatomical sheets: contract
|
||
|
||
Status: decisions RATIFIED, contract consolidated for the owner's final
|
||
review (V1-2.0, 2026-10-28). The arbitration AR-1 is closed: the owner
|
||
ratified option B (`aal2` for every platform role change, §5.7, §17.2,
|
||
BDR-083).
|
||
The owner approved the orientations D1 to D8 and added the mandatory
|
||
requirement D9 (BDR-081, 2026-10-27), then ratified the decisions O1 to O23 in
|
||
the brief « V1-2.0 : ratification des arbitrages O1 à O23 et consolidation du
|
||
contrat » (2026-10-28, BDR-082). This revision writes those decisions into the
|
||
rules, resolves the contradictions C1 to C14 found at the review of the first
|
||
revision (§19.2), restates the step plan (§16) and integrates a second round
|
||
of fresh challenges (§19.3), one finding of which needed the owner (AR-1,
|
||
decided) and a third review of the AR-1 B text (§19.4). It
|
||
authorises no implementation: V1-2.1 starts only on the owner's explicit go.
|
||
V1-2.0 changes no code, migration, policy, RPC, anatomical data or DEV state.
|
||
|
||
Branch: `feature/v1-2-anatomical-sheets` (off `develop` 9135d73, the V1-1
|
||
merge). Roadmap position: `IMPLEMENTATION_PLAN.md` §0, V1-2. This contract
|
||
absorbs plan Step 13 (provider over Supabase, sheet library) and, for official
|
||
sheets only, the editor of plan Step 17 at the level described in §8.2. The
|
||
community parts of Steps 17 and 18 (personal sheets, sharing, follows, forks)
|
||
stay out.
|
||
|
||
Fundamental requirement (owner, 2026-10-28): by the end of V1-2, a
|
||
habilitated administrator creates and edits a complete official sheet from the
|
||
application, prepares its SVG views, annotations and categories, submits it to
|
||
review and publishes the approved version. No deferral of this contract makes
|
||
that journey impossible; V1-2.7 proves it end to end with two accounts on the
|
||
sandbox, and the same journey runs on DEV once the owner has authorised the
|
||
operations of §16.11.
|
||
|
||
Parts: 1 facts, 2 scope, 3 nomenclature, 4 decisions D1 to D9, 5 access, roles
|
||
and permissions, 6 lifecycle, review, verification and publication, 7 species
|
||
and new sheets, 8 editor, 9 drawings, 10 loading, 11 screens and journeys,
|
||
12 SQL defects, SQL authority and migrations, 13 security, 14 equine sheet,
|
||
15 tests, 16 implementation steps, 17 ratified decisions and arbitration,
|
||
18 documents touched by V1-2.0, 19 challenge record.
|
||
|
||
---
|
||
|
||
## 1. Facts the contract rests on
|
||
|
||
State of `develop` 9135d73 and of Supabase DEV, read on 2026-10-27 in a
|
||
read-only session (`default_transaction_read_only=on`), completed from the
|
||
repository on 2026-10-28. Line numbers refer to
|
||
`supabase/migrations/20261008110000_anatomical_sheets.sql` unless named.
|
||
|
||
| Area | State |
|
||
|---|---|
|
||
| Document model | Rust core, `crates/core/src/domain/sheet/schema.rs`, schema version 2, strict (`deny_unknown_fields`; reference URLs must be http or https at parse). Root: `species_id`, `name`, `description`, `scope_disclaimer` (FR/EN), `attribution`, `vertebral_config.regions` (ordered, `count`, optional `count_range`), `references`, annotation `categories`, `views` (one main, details with `parent_view_id`, own drawing or `view_box` crop), `annotations` (`point`, `zone`, `detail_trigger`; geometry circle, polygon or path, optional: an annotation without geometry draws nothing), `finding_zones` (categories of kind `dysfunction`, `consultation_reason`, `anamnesis`, `custom`; recursive nodes with `requires_vet_referral`, `reference_ids`). |
|
||
| Element identity | Annotation ids are unique in the document. Finding category and node ids are unique among siblings only (`validate.rs` l.409-421): in the equine draft, the 811 categories and nodes share 310 distinct ids (`mechanical` appears 19 times). A finding element is identified by its path key `<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, the binary `jsonb` size, replaced in M5 by the text measure of §12.2), `anatomical_sheet_assets` (rows unique per sheet and sha256; `uploaded_at` null until confirmed; no immutability trigger). |
|
||
| Species access | Policy `species_select_active`: authenticated callers see active rows only. The animal forms read species through `fetchSpeciesLabels` under that policy; `create_animal` and `update_animal` refuse an inactive species; `create_anatomical_sheet` requires an active one (l.713). Table comment: « no API write path ». |
|
||
| Immutability | `guard_sheet_version_update` freezes published rows except the deprecation transition, comparing a fixed column list (l.219-232), and lets a draft become published with any column change (l.234-238). `guard_sheet_version_delete` refuses `published` only (l.275-278): a deprecated version can be deleted physically today (pgTAP `005_anatomical_sheets.sql` l.551 asserts it). |
|
||
| RPCs | 12 for authenticated callers (create, create_draft, publish, deprecate, delete_version, fork, archive, restore, delete_sheet, set_visibility, register_asset, delete_asset) plus `confirm_sheet_asset_upload` (service role). `register_sheet_asset` returns the existing row of the same sheet and sha256 or inserts one (l.1021). `create_sheet_draft` accepts any non-draft source (l.756). The fork copies asset rows (`copy_sheet_assets`) and rewrites the document's drawing ids (`remap_document_assets`). |
|
||
| Access | `can_edit_sheet` (l.494-510) = creator of a non-deleted sheet, or any platform owner or admin on an official sheet; it gates every lifecycle RPC, the draft, version and asset policies and the Storage read. `can_use_sheet` (l.513-526) = active sheet and (`public` or editable); the sheet policy reads it (l.1183-1190). Editors update draft `content` and `change_note`, and sheet `name`, `slug`, `description`, by direct table UPDATE: no RPC, no audit, no concurrency check. |
|
||
| Service role | The sheet migration revokes table privileges from `public, anon, authenticated` only (l.1157-1160); Supabase default privileges give `service_role` everything (`20261025100000_workspaces.sql` l.311-314, which revokes them for V1-1 tables). The service key is also a GoTrue admin credential. |
|
||
| Platform roles | `platform_role`: owner, admin, moderator, support. DEV holds one owner. An owner may grant or revoke any role, owner included (`can_manage_platform_role`, `20261008100200_platform_roles.sql` l.83-95); `grant_platform_role` and `revoke_platform_role` check the caller's role, not its assurance level (l.189-238); the last owner cannot be revoked. No professional status (plan Step 9). |
|
||
| Storage | Bucket `anatomical-sheet-assets`: private, SVG only, 20 MiB. Object key `<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:
|
||
|
||
1. an administration space where habilitated staff list, filter and create
|
||
official sheets, edit drafts (structured editor and minimal visual tool,
|
||
§8.2), upload and clean drawings, preview, read the completeness report,
|
||
submit to review, review, publish, deprecate and archive, with the full
|
||
history;
|
||
2. a traceable review workflow with progressive reviews (§6.3), a server
|
||
verdict computed by the Rust worker (§6.4) and an atomic publication gate;
|
||
3. explicit rights: three capabilities and a provisional catalogue access,
|
||
granted by the owner, with MFA for every administrative operation (§5);
|
||
4. a read-only catalogue of published official sheets for accounts with
|
||
catalogue access (§5.3);
|
||
5. loading of a stored version into the Rust core for preview, editing and
|
||
catalogue, with integrity checks on the document, the fingerprint and the
|
||
drawings;
|
||
6. hardening of the existing SQL lifecycle, and the Rust core as the only
|
||
authority on document rules (§12.2);
|
||
7. new species created inactive by editors and activated by the owner (§7);
|
||
8. a working copy of the equine historical sheet and the preparation of its
|
||
review, without publication (§14).
|
||
|
||
Out of V1-2: personal and community sheets, sharing, follows, forks,
|
||
marketplace, editing by students, rights scoped by species or by sheet, the
|
||
level 2 editor (§8.3), the copy of a finding catalogue between sheets (O11),
|
||
package export and import between environments (O13), a synchronous
|
||
verification service (O15), review quorum (O5), e-mail notifications, species
|
||
deactivation and deletion, authoring in production, the switch of the report
|
||
editor to stored sheets and the link from bilans to versions (V1-3), storage
|
||
of report migration maps (V1-3), offline cache (plan Step 16), professional
|
||
verification (plan Step 9), entitlements and offers (plan Step 11), deletion
|
||
of Storage objects (one audited exception: §9.3), and the publication of any
|
||
equine sheet (an owner act after the business review, never inside V1-2).
|
||
|
||
Consequences of the deferrals. None of them is needed by the fundamental
|
||
journey. Without packages (O13), content prepared on one stack never moves to
|
||
another: the sandbox serves the tests and rehearsals, DEV becomes the
|
||
authoring stack after the closure, and authoring for production (a production
|
||
stack, a running worker, either authoring there or a package import that
|
||
preserves ids) is decided before any production use. Without a catalogue copy
|
||
(O11), each new species' finding catalogue is entered by hand from cited
|
||
sources.
|
||
|
||
---
|
||
|
||
## 3. Nomenclature
|
||
|
||
| FR (UI) | EN (UI) | Code |
|
||
|---|---|---|
|
||
| Fiche anatomique | Anatomical sheet | sheet |
|
||
| Fiche officielle | Official sheet | `is_official` |
|
||
| Fiche historique (« pipeline Git » in a tooltip if needed, 2026-11-02) | Historical sheet | the equine sheet `503dc301…` (§14.2) |
|
||
| Copie de travail | Working copy | `working_copy_source_version_id` (§14.3) |
|
||
| Version : brouillon, publiée, retirée | Version: draft, published, withdrawn | `draft`, `published`, `deprecated` |
|
||
| Revue, soumission | Review, submission | review round (§6.3) |
|
||
| Vérification en cours, à relire, approuvée, modifications demandées, soumission retirée, vérification échouée | Verifying, awaiting review, approved, changes requested, submission withdrawn, verification failed | round status `verifying`, `open`, `approved`, `changes_requested`, `withdrawn`, `verification_failed` |
|
||
| Groupe de revue, groupe lu | Review group, group read | review group, acknowledgment (§6.3) |
|
||
| Accès au catalogue | Catalogue access | right `catalog_reader` (§5.3) |
|
||
| Habilitation | Permission (owner, 2026-11-02, BDR-097: `capability` stays the technical term) | right `sheet_editor`, `sheet_reviewer`, `sheet_publisher` (§5.2) |
|
||
| Relecteur ou relectrice | Reviewer | `sheet_reviewer` |
|
||
| Éditeur de fiches | Sheet editor | `sheet_editor` |
|
||
| Responsable de publication | Publisher | `sheet_publisher` |
|
||
| À confirmer, relu, hérité, non relu | To confirm, reviewed, inherited, not reviewed | `to_confirm`, `reviewed`, `inherited` |
|
||
| Complétude | Completeness | verdict counts (§6.4) |
|
||
| Illustration | Drawing | asset row + Storage object |
|
||
| Vue principale, vue détaillée | Main view, detail view | `main`, `detail` |
|
||
| Point, zone, accès à une vue détaillée | Point, zone, detail view link | `point`, `zone`, `detail_trigger` |
|
||
| Catalogue des constats | Finding catalogue | `finding_zones` |
|
||
| Empreinte | Fingerprint | `sha256-rfc8785-validated-v1` |
|
||
| Clé d'élément | Element key | §6.6 |
|
||
|
||
Routes and the labels of this table are ratified (O16), with « Hérité, non
|
||
relu » / « Inherited, not reviewed » for `inherited`. The labels added by this
|
||
revision for the states of O17, O21 and O23 and the route `/app/admin/species`
|
||
(O9) follow the same convention and are confirmed on the V1-2.4 wireframes
|
||
(approved by the owner on 2026-11-02, §17.9).
|
||
Every failure code, round state and validation code has an FR and an EN
|
||
message (§6.5, §15).
|
||
|
||
---
|
||
|
||
## 4. Decisions D1 to D9
|
||
|
||
Owner orientations, approved (BDR-081). The column « Contract » says where
|
||
each one becomes rules.
|
||
|
||
| Id | Owner orientation (summary) | Contract |
|
||
|---|---|---|
|
||
| D1 | Official publication is reserved to habilitated platform administrators. Business validation is identified and traced separately from the technical act of publishing. `platform_role` is never a professional status. | §5.2 capabilities, §5.5 separation, §6.3 rounds |
|
||
| D2 | No official publication while blocking `to_confirm` items remain. `to_confirm` never becomes `reviewed` automatically. Completeness rules and validation conditions are defined. | §6.6, §6.7 (O3 B: `inherited` blocks too) |
|
||
| D3 | Official drafts are visible only to administrators, editors and explicitly authorised reviewers. Ordinary practitioners never see a sheet in preparation. The equine sheet stays a draft. | §5.2, §5.3 row predicate, §9.4, §10, §14 |
|
||
| D4 | Published official sheets are readable by authenticated, authorised users whatever their workspace, under the retained RLS. Reading is separate from editing. | §5.3 catalogue access (O21), §5.4 |
|
||
| D5 | At launch, creating official sheets and the related administration is reserved to habilitated administrators. Personal and community sheets are not opened in the MVP. | §5.4, §12.3 M4 |
|
||
| D6 | A traceable review before official publication identifies the draft's authors, the submitter, the reviewers, the decisions and comments, the publisher, and the exact version validated. A simple but really usable review interface. | §6.3, §11 journeys R1, A6 |
|
||
| D7 | The report editor keeps working as today during V1-2. Loading published versions from Supabase is prepared; the switch and the adaptation of bilans are framed in V1-3. The readers of historical data are not modified early. | §10 |
|
||
| D8 | Published versions are immutable; changing a published sheet creates a new draft. Versions referenced by bilans stay readable by authorised users after archiving or a newer publication, never exposed to users without the needed permissions. | §6.8, §6.9, §9.4, F13 |
|
||
| D9 | Administrators create, read, edit, version and prepare the publication of official sheets from the application, for any species, without editing the database or the project sources. Rust stays the validation authority; no divergent schema copy. | §7, §8, §9, §11, §12.2 |
|
||
|
||
Reading of D3 and D9 retained by O1: « administrators » means habilitated
|
||
administrators, that is a platform owner or admin holding the matching
|
||
capability. A platform admin without a capability sees no draft.
|
||
|
||
---
|
||
|
||
## 5. Access, roles and permissions
|
||
|
||
### 5.1 Layers
|
||
|
||
Each layer is checked on the server; none implies the next.
|
||
|
||
| Layer | Established by | Gives |
|
||
|---|---|---|
|
||
| Authentication | a Supabase Auth session | nothing by itself |
|
||
| Email confirmation | `email_confirmed_at` | proves control of a mailbox; a precondition of every right below, never a proof of competence |
|
||
| Catalogue access | `private.can_read_official_catalog(uid)` (§5.3) | the catalogue list and the current published versions |
|
||
| Historical reads | the same predicate (O8) | published and deprecated versions by id, archived sheets included |
|
||
| Draft reads | a capability and `aal2` | drafts, rounds, verdicts, comments, history, drawings of drafts |
|
||
| Capabilities | `anatomical_catalog_grants` (§5.2) and `aal2` | edit, review, publish, per the matrix of §5.4 |
|
||
| Platform role | `profile_roles`, changed only with `aal2` (§5.7) | a precondition of `sheet_editor` and `sheet_publisher`; no catalogue right by itself |
|
||
| Professional status | plan Step 9, not built | none; never inferred from a right or a role |
|
||
| Workspace membership | V1-1 tables | none: no catalogue rule reads workspace tables and no V1-1 rule reads catalogue tables |
|
||
|
||
### 5.2 Capabilities (O1 A + D)
|
||
|
||
Three explicit, independent capabilities: `sheet_editor`, `sheet_reviewer`,
|
||
`sheet_publisher`. They live in `anatomical_catalog_grants` (M4) with the
|
||
provisional catalogue access of §5.3, one row per grant:
|
||
|
||
| Column | Meaning |
|
||
|---|---|
|
||
| `user_id`, `grant_kind` | the account and the right (`sheet_editor`, `sheet_reviewer`, `sheet_publisher`, `catalog_reader`) |
|
||
| `reason` | required motive, 1 to 1 000 characters |
|
||
| `verification_note` | required for the three capabilities: the qualification declared and what the owner verified, 1 to 1 000 characters (for `sheet_reviewer`, the professional elements the owner checked; never a certification) |
|
||
| `granted_by`, `granted_at` | the platform owner, the time |
|
||
| `expires_at` | optional end; later than `granted_at`; the administration form sends the last millisecond of the chosen day in Europe/Paris (§17.11) |
|
||
| `revoked_by`, `revoked_at`, `revocation_reason` | set once by a revocation, reason required |
|
||
|
||
- Writes: `grant_catalog_right(user_id, kind, reason, verification_note,
|
||
expires_at)` and `revoke_catalog_right(grant_id, reason)`, platform owner
|
||
with `aal2`, audited with every field. Rows are never updated otherwise and
|
||
never deleted; a renewal is a new row. One active row per account and kind.
|
||
- Active grant: not revoked, and no `expires_at` or `expires_at` in the
|
||
future, read at every request.
|
||
- Eligibility, checked at grant and at every use: active profile and
|
||
confirmed email for every kind; for the three capabilities, a verified TOTP
|
||
factor at grant time, so a capability is never handed to an account whose
|
||
first factor anyone holding its password could still enrol; an active
|
||
platform role owner or admin for `sheet_editor` and `sheet_publisher`. A
|
||
reviewer need not hold any platform role: partner veterinarians and
|
||
osteopaths are reviewers without being administrators. Losing the platform
|
||
role suspends an editor or publisher capability without deleting the grant
|
||
row.
|
||
- The owner grants itself at first use; no migration grants anything. It may
|
||
grant itself any of the three capabilities, `sheet_reviewer` included
|
||
(M6, owner decision 2026-10-28, §17.3), under the same `aal2`, factor and
|
||
eligibility checks as any grant; no other account grants itself anything.
|
||
The separation of duties stays a per-round rule (§5.5).
|
||
- Scope: every capability is global, over every official sheet. A reviewer
|
||
named for one species reads the drafts of all species. Rights scoped by
|
||
species or by sheet are deferred. The per-sheet controls of V1-2 are rules,
|
||
not grants: separation of duties per round (§5.5), the protected historical
|
||
sheet (§14.2), the frozen draft (§6.1), one draft per sheet.
|
||
- Expiry and revocation take effect at the next request:
|
||
- an editor loses draft reads and writes; the saves already made stay in
|
||
the author sets (history);
|
||
- a reviewer's acknowledgments and approvals count only while the reviewer
|
||
holds an active grant, checked at approval and at publication; a renewal
|
||
makes them count again; while they do not count, publication answers
|
||
`publish.approval.invalid` and the round stays `approved` until an editor
|
||
withdraws it or the grant is renewed; published versions are untouched;
|
||
- a publisher can no longer publish, deprecate or archive.
|
||
- The rights screen shows active, expiring (within 30 days), expired and
|
||
revoked grants with their reason and verification note. No e-mail in V1-2.
|
||
|
||
Predicates (M4), kept apart so no check tests the wrong account:
|
||
|
||
- `private.grant_active(uid, kind)`: the grant and its eligibility, without
|
||
any assurance level; used for stored actors (acknowledgers, approver).
|
||
- `private.caller_has(kind)`: `grant_active(auth.uid(), kind)` and
|
||
`has_mfa()`; used for the calling session.
|
||
|
||
`private.can_edit_sheet` is redefined for official sheets (M4) on
|
||
`caller_has('sheet_editor')`: owner and admin without the capability lose
|
||
draft reads, lifecycle RPCs and draft drawing reads. Every predicate built on
|
||
it inherits the change, and pgTAP proves « admin without capability
|
||
refused » for each RPC and policy (§15).
|
||
|
||
### 5.3 Catalogue access (O21)
|
||
|
||
Reading the published catalogue is a right of its own, distinct from
|
||
authentication, from email confirmation, from the capabilities and from any
|
||
platform role.
|
||
|
||
- Predicate `private.can_read_official_catalog(uid)`, provisional and
|
||
fail-closed: active profile, and confirmed email, and (an active
|
||
`catalog_reader` grant or an active capability). Anything unknown or
|
||
missing answers false. Platform roles grant nothing by themselves.
|
||
- `catalog_reader` grants follow §5.2 (owner only, reason required,
|
||
verification note and verified factor not required, expiry optional,
|
||
audited, no `aal2` needed to use them).
|
||
- Row predicate for readers, the same on sheets, versions, asset rows and
|
||
Storage objects: an official, non-deleted sheet with at least one published
|
||
or deprecated version, and `can_read_official_catalog`. The `visibility`
|
||
branch of `can_use_sheet` is dropped from every catalogue predicate. A sheet
|
||
that only has a draft, and an inactive species' id through it, are
|
||
invisible to readers. Reader column grants exclude `last_version_number`,
|
||
`updated_at` and `working_copy_source_version_id`.
|
||
- The predicate gates the catalogue list, the published and deprecated
|
||
versions by id, archived sheets included (O8), and their drawings.
|
||
- Screens (owner, 2026-11-02, BDR-094): a signed-in account without the
|
||
right sees no « Fiches anatomiques » entry in the sidebar or the drawer; a
|
||
direct URL under `/app/anatomy` shows a page « Accès non autorisé » with an
|
||
explanation and a link back to `/app`, the same whether the sheet exists or
|
||
not. A visitor who is not signed in goes to `/login?next=` (`RequireAuth`),
|
||
never to that page. The hidden entry protects nothing: the predicate, the
|
||
capabilities and RLS decide. The entry's visibility may read the caller's own
|
||
grant rows (select policy `user_id = auth.uid()`); the page acts on the
|
||
server's answer, never on that hint.
|
||
- Definitive rights belong to the entitlement engine of plan Step 11 (offers,
|
||
`has_active_entitlement`), which does not exist. Nothing in V1-2 simulates
|
||
it. Switch conditions: Step 11 ships a catalogue capability (proposed name
|
||
`catalog.read`, added to the Step 11 capability catalogue); an owner
|
||
decision then sets the predicate to (entitlement or capability), says what
|
||
becomes of the provisional `catalog_reader` grants, and comes with its own
|
||
pgTAP matrix. If V1-3 needs every practitioner to load sheets before Step 11
|
||
exists, V1-3 decides between provisional grants per practitioner and
|
||
building Step 11 first.
|
||
- Tests (pgTAP, §15): anonymous, authenticated unconfirmed, confirmed without
|
||
grant, expired and revoked `catalog_reader`, deactivated, platform admin,
|
||
moderator and support without grant: refused; `catalog_reader` and
|
||
capability holders: allowed; a draft-only sheet invisible to every reader.
|
||
|
||
### 5.4 Matrix
|
||
|
||
R = catalogue reader (§5.3, without capability), E = sheet editor, V = sheet
|
||
reviewer, P = sheet publisher, O = platform owner acting as owner (rights,
|
||
species activation and renaming). A person may hold several rights; the owner
|
||
acts on sheets only through capabilities it granted itself. Every operation
|
||
except the first two lines requires an `aal2` session (§5.6), in RPCs and in
|
||
the table and Storage policies alike.
|
||
|
||
| Operation | R | E | V | P | O |
|
||
|---|---|---|---|---|---|
|
||
| List the catalogue, read the current published version | yes | yes | yes | yes | no |
|
||
| Read a published or deprecated version by id, archived sheet included | yes | yes | yes | yes | no |
|
||
| Read drafts, rounds, verdicts, comments, history, drawings of drafts | no | yes | yes | yes | no |
|
||
| List catalogue species, active and inactive | no | yes | yes | yes | yes |
|
||
| Create an inactive species, edit an inactive species' names and order | no | yes | no | no | no |
|
||
| Activate a species, correct an active species' names | no | no | no | no | yes |
|
||
| Create an official sheet, a working copy (§14.3), a draft; save; register and upload drawings; delete a draft without rounds | no | yes | no | no | no |
|
||
| Submit a draft, withdraw a submission | no | yes | no | no | no |
|
||
| Comment a round | no | yes | yes | yes | no |
|
||
| Acknowledge review groups, approve or request changes (never as an author, §5.5) | no | no | yes | no | no |
|
||
| Publish an approved round, deprecate a version, archive and restore a sheet | no | no | no | yes | no |
|
||
| Grant and revoke rights | no | no | no | no | yes |
|
||
| Create a personal sheet, fork, change visibility | closed in V1-2 (D5) |
|
||
|
||
Moderator, support, unconfirmed, deactivated and anonymous accounts, and
|
||
platform admins without a right: nothing. Service role: only the worker RPCs
|
||
of §6.4, the upload confirmation and the narrow read RPC of the operator tool
|
||
(§9.5); no table privilege on any catalogue table (F12, §12.1).
|
||
|
||
### 5.5 Separation of duties (O2 A) and the first publication
|
||
|
||
- The author set of a draft is maintained by a trigger: the account that
|
||
created the draft version (new sheet, working copy or draft from a
|
||
published version) and every account that changed its content since. It is
|
||
frozen into the round at submission and checked on the server.
|
||
- No member of a round's author set acknowledges a group of that round or
|
||
approves it.
|
||
- A content write without an authenticated actor is refused for every sheet
|
||
except the historical sheet (§14.2), so no write escapes the author set.
|
||
- A save whose content equals the stored content is refused (no revision
|
||
bump), so an empty save cannot move authorship.
|
||
- Publication needs `sheet_publisher`; the publisher may be an author or the
|
||
approver. Two distinct people suffice: one who wrote the draft, one
|
||
habilitated to review and approve it.
|
||
- The review screen shows the author set, the acknowledgments and the
|
||
approver with the reason and verification note of each reviewer's grant.
|
||
|
||
An owner holding `sheet_reviewer` reviews and approves drafts written by
|
||
other authors; on a round it authored, the acknowledgment and the approval
|
||
are refused (`review.separation`) and, should an author's approval ever be
|
||
stored, publication refuses it again (`publish.approval.invalid`).
|
||
A sole owner cannot publish: as an author it can neither acknowledge nor
|
||
approve its own draft. The system offers no override. One residual remains:
|
||
the owner could create a second account and grant it `sheet_reviewer`; that
|
||
path is not silent, since the grant, its reason and verification note, and
|
||
every acknowledgment and decision are audited and shown on the round, but it
|
||
cannot be detected technically until professional verification exists
|
||
(plan Step 9).
|
||
|
||
First publication with one owner and one business reviewer (journey A0, then
|
||
A1 to A6):
|
||
|
||
1. The owner enrols two TOTP factors, steps up, grants itself `sheet_editor`
|
||
and `sheet_publisher` with a reason.
|
||
2. The business reviewer signs up, confirms the e-mail address and enrols a
|
||
TOTP factor; the owner then grants `sheet_reviewer` with a reason, a
|
||
verification note and possibly an expiry.
|
||
3. The owner creates the sheet, edits, uploads, saves and submits; the worker
|
||
verifies the revision; the round opens.
|
||
4. The reviewer reads and comments, over as many rounds as needed (§6.3); the
|
||
owner applies the answers and marks the read groups; the reviewer
|
||
acknowledges every group, then approves with a note.
|
||
5. The owner publishes the approved round.
|
||
|
||
### 5.6 Strong authentication (O4 A)
|
||
|
||
- `private.has_mfa()` reads `(auth.jwt() ->> 'aal') = 'aal2'`. Through
|
||
`caller_has` it is required by every catalogue RPC except the reader RPCs,
|
||
by the capability branches of the version, round, comment, acknowledgment
|
||
and asset policies and of the Storage read, by the rights RPCs, by the
|
||
species RPCs and by the working copy. The reader branches never read it.
|
||
- Enrolment (V1-2.5, Mon compte, Sécurité): add a TOTP factor (QR code, the
|
||
secret shown once and never stored or logged by the application), verify
|
||
it with a code (a factor counts only once verified), name, list and remove
|
||
factors. GoTrue v2.197.0 requires `aal2` to enrol a factor once one is
|
||
verified and to remove a verified factor (§5.7.3, from its source).
|
||
V1-2.5 proves that an `aal1` session of an account with a verified factor
|
||
can neither enrol another factor nor remove one; if the sandbox shows
|
||
otherwise, the step stops for an owner decision, since MFA would then be
|
||
bypassable with the password alone.
|
||
- Step-up: entering `/app/admin` with an `aal1` session opens the challenge;
|
||
success upgrades the session; no admin data is requested before.
|
||
- Sessions: `aal2` belongs to the session. A token refresh keeps it, sign-out
|
||
ends the session (an access token already issued stays valid until
|
||
`jwt_expiry`), a new sign-in starts at `aal1` (Supabase behaviour, proven by a
|
||
V1-2.5 browser test). The access token lives `jwt_expiry` (3 600 s in the
|
||
local configuration; V1-2.1 records the values of the sandbox and DEV). No
|
||
session time box or inactivity limit is configured, and V1-2 adds no
|
||
freshness window: a stolen `aal2` session stays usable until it ends
|
||
(residual, §13). V1-2.5 records what removing a factor does to the
|
||
account's other open sessions.
|
||
- Loss of a factor: Supabase Auth issues no recovery codes. The owner enrols
|
||
two factors on two devices before the first grant on any stack. Another
|
||
account that loses its factor keeps its `aal1` access (catalogue, rest of
|
||
the application) and loses the administration until recovery.
|
||
- Recovery is an operator procedure, never an application feature: no RPC,
|
||
screen or service path resets another account's factor, so recovery opens
|
||
no application back door. Steps:
|
||
1. the owner confirms the requester's identity out of band and records the
|
||
reason;
|
||
2. the owner revokes the account's capabilities (§5.2);
|
||
3. an operator with server access signs out every session of the account
|
||
and deletes the factor (Supabase admin API with the service key on the
|
||
server, or SQL on the database container for DEV), and in the same
|
||
session writes the audit row `auth.mfa_factor_reset` through
|
||
`private.log_event` (null actor, subject, reason, operator named in the
|
||
detail);
|
||
4. the person enrols a new factor; the owner grants the capabilities again.
|
||
The owner's own loss follows the same procedure, run by the owner at the
|
||
server. The runbook goes to `IDENTITY.md` and is rehearsed on the sandbox in
|
||
V1-2.9.
|
||
- Platform roles (AR-1 B, ratified 2026-10-28): `grant_platform_role` and
|
||
`revoke_platform_role` require `aal2` for every platform role; see §5.7.
|
||
The earlier option O4-D, left unratified by O4, is superseded by that
|
||
arbitration.
|
||
|
||
### 5.7 Platform role changes and MFA (AR-1 B)
|
||
|
||
Ratified by the owner on 2026-10-28 (BDR-083). It completes the security
|
||
contract of O4; it replaces none of O1 to O23.
|
||
|
||
**Rule.** Every grant, revocation, replacement, promotion, demotion or
|
||
equivalent change of a platform role (`owner`, `admin`, `moderator`,
|
||
`support`) requires a valid `aal2` session, checked on the server when the
|
||
operation runs. A hidden button is not a control. There is no exception for
|
||
the owner, the first administrator, accounts already privileged, older
|
||
accounts, the administration screens or direct RPC calls; the only path
|
||
without a session is the audited operator path outside the application
|
||
(§5.7.5), used for a bootstrap or a recovery. `aal2` is necessary
|
||
and never sufficient: `can_manage_platform_role`, the self-target refusal and
|
||
the last-owner guard still apply. Ordinary accounts are not asked for MFA; the
|
||
requirement covers the operations of this contract (platform roles, catalogue
|
||
rights, catalogue administration, protected drafts, review, publication).
|
||
Reading the published catalogue follows O21.
|
||
|
||
**The flaw and the chain it closes.** `grant_platform_role` and
|
||
`revoke_platform_role` check the caller's role, not its assurance level:
|
||
|
||
1. an attacker learns the password of an owner;
|
||
2. they open a session, which is `aal1`;
|
||
3. they call `grant_platform_role` directly and give `owner` or `admin` to an
|
||
account they control (or revoke the real owner);
|
||
4. that account enrols its own TOTP factor (a first factor is enrolled at
|
||
`aal1`) and reaches `aal2`;
|
||
5. it grants itself `sheet_editor`, `sheet_reviewer`, `sheet_publisher`
|
||
(§5.2) and reviews and publishes official sheets.
|
||
|
||
With AR-1 B, step 3 is refused with no write, so steps 4 and 5 never start.
|
||
|
||
**Why B and not A.** A (owner and admin only) leaves `moderator` and `support`
|
||
changeable from a password-only session. They give no catalogue right today;
|
||
`support` opens staff reads (`profiles_select_staff`), and any future
|
||
role-based rule would inherit a weak path; revoking them is also a nuisance
|
||
attack. B
|
||
costs the same one predicate and removes the list of roles from the rule.
|
||
|
||
**Inventory of the paths that change platform privileges** (read from the
|
||
migrations and `seed.sql` on 2026-10-28; V1-2.1 re-runs the census in pgTAP
|
||
001):
|
||
|
||
| Path | Who may call it today | Controls today | Added by M4 | Audit |
|
||
|---|---|---|---|---|
|
||
| `public.grant_platform_role(target, role)` | `authenticated` (and `service_role`, which fails at `auth.uid()` null) | authenticated, not self, `can_manage_platform_role` (owner: any role; admin: moderator and support), not already active | `has_mfa()` as the second check; `EXECUTE` revoked from `service_role` | `platform_role.granted` |
|
||
| `public.revoke_platform_role(target, role, reason)` | same | same, plus the last-owner guard | same, plus the guard made race-free (F18) | `platform_role.revoked` |
|
||
| `private.assign_platform_role`, `private.withdraw_platform_role` | no API role (`EXECUTE` revoked from public, schema `private` not exposed); RPCs above and privileged SQL sessions | none of their own | a non-null actor must equal `auth.uid()` and pass `has_mfa()`; a null actor is accepted only when the request carries no JWT (`auth.role()` null), so neither an API session nor `service_role` reaches the operator path (§5.7.5) | same events |
|
||
| `private.can_manage_platform_role` and the `has_platform_role` family | predicates, no write | n/a | unchanged; `is_platform_*` do not read the assurance level (policies that use them for reads are out of AR-1, see reserves) | none |
|
||
| table `public.profile_roles` | `authenticated`: SELECT only, no write policy; `service_role`: default table privileges never revoked (F17) | RLS, privileges | `REVOKE ALL` from `service_role` on `profile_roles` and `profiles` (F17) | none |
|
||
| `profiles.active` (deactivation changes who counts as a role holder) | no user path: not in the column grant of UPDATE | column grants | F17 covers `service_role` | none |
|
||
| triggers and `handle_new_auth_user` | none writes `profile_roles` | n/a | census asserts it stays so | none |
|
||
| `seed.sql` bootstrap (`assign_platform_role(null, ...)`) | local stacks, privileged SQL | none | unchanged, local only (§5.7.5) | `platform_role.granted`, null actor |
|
||
| deletion of an auth user (cascade `on delete cascade` to `profile_roles`) | GoTrue admin API with the service key | none | operator procedure only (§5.7.5) | auth log |
|
||
| `grant_catalog_right`, `revoke_catalog_right` (M4, §5.2) | owner | owner, `aal2` | already `aal2` | per §5.2 |
|
||
|
||
No other path reachable from a user session was found: PostgREST exposes the
|
||
`public` schema only, and every write to `profile_roles` goes through the two
|
||
RPCs. A claim that this closes service-key abuse would be false: see §5.7.5.
|
||
|
||
**Order of checks in both RPCs** (M4), all before any write:
|
||
|
||
1. `auth.uid()` is not null;
|
||
2. `has_mfa()`; otherwise a refusal with the closed kind `mfa_required`;
|
||
3. the caller is not the target;
|
||
4. `can_manage_platform_role`;
|
||
5. the operation is valid: target exists and is active; for a grant, the
|
||
target holds a verified factor (the eligibility predicate of §5.2), so no
|
||
role lands on an account whose first factor a password or mailbox holder
|
||
could still enrol; role not already active, or active for a revocation;
|
||
last active owner kept;
|
||
6. the write and its audit row, in the same transaction.
|
||
|
||
The assurance check comes before the role checks so that a password-only
|
||
session gets the same answer whatever role it holds: no oracle on who is
|
||
owner or admin. A refusal raises, so it leaves no row (neither the role nor an
|
||
audit row); attempted escalations are therefore visible in the API logs, not
|
||
in the audit table. With `[analytics] enabled = false` a raised refusal
|
||
reaches the PostgreSQL log only (residual). Returning the refusal as a
|
||
closed kind after a committed `log_event` is an option V1-2.1 may propose,
|
||
not a decision taken here.
|
||
|
||
**Race on the last owner (F18).** `withdraw_platform_role` counts owner rows
|
||
without a lock and without `profiles.active`, so two simultaneous
|
||
revocations of two owners can both pass and leave none (or only a deactivated
|
||
one). M4 takes one transaction-scoped advisory lock at the start of both RPCs
|
||
and of the private functions, before checks 3 to 5, and counts owners with
|
||
the `has_platform_role` semantics (active profile). Two-session tests: mutual
|
||
revocation, revoke against grant.
|
||
|
||
#### 5.7.1 First enrolment and the bootstrap of the first owner
|
||
|
||
GoTrue v2.197.0 (the image pinned by the local stack; source read on
|
||
2026-10-28, behaviour to be proven on the sandbox by V1-2.5):
|
||
`EnrollFactor` refuses with `insufficient_aal` when the user already has a
|
||
verified factor and the session is not `aal2`. With no verified factor, a first
|
||
factor is enrolled from an `aal1` session. Enrolling, verifying and reaching
|
||
`aal2` are three steps: a factor counts once verified, and verification
|
||
upgrades the session and invalidates the user's sessions below `aal2`.
|
||
|
||
Ordinary journey: password sign-in (`aal1`) → Mon compte, Sécurité → enrol
|
||
TOTP → verify with a code → `aal2`. Enrolling a factor grants no role and no
|
||
capability; MFA is a condition, never a substitute for the checks of §5.2 and
|
||
§5.7.
|
||
|
||
New environment (no owner, no `aal2` session anywhere), in this order, never
|
||
the reverse:
|
||
|
||
1. the operator creates the account through the sign-up path or the admin
|
||
API, email confirmed, and hands over the initial secret out of band;
|
||
2. the future owner signs in, enrols two TOTP factors on two devices and
|
||
verifies both; no role exists yet, so nothing is at stake in the window;
|
||
3. the operator checks, read-only, that the account has verified factors and
|
||
that their names and creation times match what the owner did;
|
||
4. only then the operator assigns the owner role from a privileged SQL
|
||
session (`assign_platform_role(null, ...)`) and records, in the same
|
||
session, an audit row with the reason and the operator's name through
|
||
`private.log_event`;
|
||
5. the owner signs in again, passes the step-up, and proves an `aal2` call
|
||
works and an `aal1` call is refused.
|
||
|
||
No public RPC creates an owner, none disables MFA, and no permanent bypass
|
||
exists. The `seed.sql` bootstrap (role assigned before any factor, known
|
||
password) is a local-fixture exception to this order, acceptable only on a
|
||
stack no untrusted party can reach (§5.7.2). Assigning the role last is what closes trust on first use for the
|
||
owner account.
|
||
|
||
#### 5.7.2 DEV: preconditions of the future transition
|
||
|
||
The DEV owner is the seed account, it has no factor, and nothing changes on
|
||
DEV during V1-2.0. Two facts of DEV defeat AR-1 B as long as they hold:
|
||
|
||
- the stack signs tokens with the Supabase CLI's public default JWT secret,
|
||
its `service_role` key is the public demo key, and port 54321 is open to
|
||
the LAN (`ENVIRONMENTS.md` §3.6, risk accepted by the owner on 2026-10-24
|
||
« before any untrusted device or user »). Anyone on the network can mint an
|
||
`aal2` token for the owner, or act as `service_role`; `has_mfa()` proves
|
||
nothing there;
|
||
- the owner account's password is the seed's, committed in Git.
|
||
|
||
So, before the owner applies M4 on DEV or makes the first grants (§16.11):
|
||
|
||
0. the §3.6 hardening is done (own JWT secret or signing keys, or 54321
|
||
narrowed to the test devices; the owner's choice), and the seed owner's
|
||
password is changed, or a separate owner is bootstrapped per §5.7.1 and
|
||
the seed owner revoked; every active `profile_roles` row of DEV is listed,
|
||
and each holder enrols and verifies a factor before M4 or loses the role;
|
||
1. read-only check of every factor of each role holder, verified or not (an
|
||
unknown one is deleted, and an unknown verified one means a reset first,
|
||
§5.7.7);
|
||
2. the owner enrols two factors and verifies both from the branch's Mon
|
||
compte; this needs no migration, and until M4 is applied every existing
|
||
right is unchanged;
|
||
3. on the sandbox rehearsal of M4 from the DEV state, `aal2` is shown to
|
||
work and `aal1` to be refused for the same account;
|
||
4. the recovery of §5.7.7 has been rehearsed on the sandbox;
|
||
5. a backup exists.
|
||
|
||
Any `db:reset`, or `db:start` on a fresh volume, of DEV after M4 reruns the
|
||
seed and reopens these preconditions.
|
||
|
||
A failed transition is never a lockout: an owner without a verified factor
|
||
still signs in and uses the application at `aal1`, only role and rights
|
||
management waits, and the first factor can always be enrolled at `aal1`.
|
||
|
||
#### 5.7.3 Additional, removed and replaced factors
|
||
|
||
Native behaviour of GoTrue v2.197.0 (source read, V1-2.5 proves it; measured
|
||
on the sandbox: `IDENTITY.md` §4.1, V1-2.5):
|
||
|
||
- a second factor: `EnrollFactor` needs `aal2` once a verified factor exists
|
||
(403 `insufficient_aal`). A stolen password therefore cannot add a factor;
|
||
- removing a verified factor: `UnenrollFactor` needs `aal2` (422
|
||
`insufficient_aal`); an unverified factor can be removed from `aal1`. An
|
||
unverified factor gives no `aal2` until verified, so a dormant one left by
|
||
an earlier password holder is a path: factor checks list unverified
|
||
factors too, and V1-2.5 tests a dormant factor verified later (GoTrue
|
||
appears to delete unverified factors of the same type on verification;
|
||
not assumed). Assumption: TOTP is the only enabled factor type;
|
||
- removing the last factor: allowed from `aal2`. The account then returns to
|
||
the first-factor case, where an `aal1` session can enrol; a role holder in
|
||
that state keeps the role (residual, §13). A stolen `aal2`
|
||
session can therefore replace factors; this is the stolen-session residual
|
||
(§5.7.8), not a bypass from the password alone;
|
||
- GoTrue downgrades the sessions of a removed factor to `aal1`
|
||
(`DowngradeSessionsToAAL1`); its exact scope and the lifetime of
|
||
already-issued access tokens are recorded by V1-2.5, not assumed;
|
||
- freshness: tokens carry `amr` entries (method and time), so a recent-TOTP
|
||
check on the rare role RPCs is technically possible; adopting it is an
|
||
owner choice under O4, not part of this contract (§5.7.9).
|
||
|
||
If the sandbox shows `aal1` can enrol a second factor or remove a verified
|
||
one, V1-2.5 stops for an owner decision (as §5.6 already says). It did not
|
||
fire (`IDENTITY.md` §4.1).
|
||
|
||
#### 5.7.4 Password change and reset
|
||
|
||
A reset or change of password yields an `aal1` session. For an account with a
|
||
verified factor it cannot add or remove a factor (§5.7.3) and cannot change a
|
||
platform role (rule above). For an account without a verified factor, the
|
||
reset lets whoever holds the mailbox enrol a first factor: this is the
|
||
accepted first-factor case, harmless while no role or capability is held, and
|
||
the reason the owner role is assigned after enrolment (§5.7.1) and a
|
||
capability only to an account with a verified factor (§5.2). Email change and
|
||
identity linking stay as configured (`enable_manual_linking = false`); V1-2.5
|
||
adds a test that none of them raises a session to `aal2` (measured on the
|
||
sandbox: `IDENTITY.md` §4.1, V1-2.5; with a verified factor, a password change
|
||
or reset is itself refused at `aal1`, so the recovery screens step up first).
|
||
|
||
#### 5.7.5 Operator path
|
||
|
||
The technical paths are the service key (RLS bypass and GoTrue admin) and a
|
||
privileged SQL session on the database container. They are not exceptions
|
||
usable from the application: the app never holds the service key; the worker
|
||
holds it and can call worker RPCs only; the role RPCs refuse `service_role`
|
||
(no `auth.uid()`, and `EXECUTE` revoked in M4). Each use is an owner-authorised
|
||
operation (§16.11), written down with its reason, and leaves an audit row
|
||
(`private.log_event`, null actor, operator in the detail) in the same
|
||
session.
|
||
|
||
#### 5.7.6 Actors
|
||
|
||
| Actor | Can change platform roles | Note |
|
||
|---|---|---|
|
||
| Ordinary account | no | no MFA requirement for ordinary use |
|
||
| Owner or admin at `aal1` | no | refused at check 2 whatever the role |
|
||
| Owner or admin at `aal2` | within `can_manage_platform_role` | admin: moderator and support only |
|
||
| Moderator or support at `aal2` | no | `aal2` is not sufficient |
|
||
| Worker | no | worker RPCs only (M6) |
|
||
| `service_role` key holder | not through the RPCs; yes through GoTrue admin and SQL | outside MFA, §5.7.5 and §13 |
|
||
| Operator SQL session | yes | audited by procedure, not by the database |
|
||
|
||
#### 5.7.7 Recovery
|
||
|
||
Complements the procedure of §5.6, which stands (operator only, out-of-band
|
||
identity, reason recorded, no RPC, no screen).
|
||
|
||
- Lost phone, account with other factors or another admin: the person uses
|
||
the second factor. A person whose only factor is lost follows §5.6 steps 1
|
||
to 4.
|
||
- Loss of every factor of the last owner: no application path exists, by
|
||
design. On a single-owner platform the operator is the owner acting at the
|
||
server, and the real control is server access, not a second person. Order:
|
||
1. the operator signs out every session, deletes every factor (verified or
|
||
not), bans the account and writes the audit row `auth.mfa_factor_reset`;
|
||
2. with the owner present, the operator sets a new password with the owner
|
||
and lifts the ban;
|
||
3. the owner signs in at once, enrols and verifies two factors;
|
||
4. the operator lists every factor of the account; any it does not
|
||
recognise sends the procedure back to step 1.
|
||
The owner role and the owner's capabilities stay in place: inert at
|
||
`aal1`, since `caller_has` and the role RPCs need `aal2`. Nothing is
|
||
re-granted. (For another account, §5.6 step 2 applies: the owner revokes
|
||
its capabilities first.)
|
||
- Return to a safe state: `aal2` proven and `aal1` refused again on that
|
||
account; the audit rows exist; no temporary bypass was left.
|
||
- Rehearsed on the sandbox in V1-2.9; the runbook goes to `IDENTITY.md`.
|
||
Secrets (QR codes, TOTP seeds) never go in Git, documents, logs or tickets.
|
||
Prevention: two factors on two independent devices for every owner.
|
||
|
||
#### 5.7.8 Sessions, tokens and stale rights
|
||
|
||
- Roles and capabilities are read from the tables at every call; the project
|
||
adds no claim to the JWT (no access-token hook), so a revoked right or role
|
||
is refused at the next call whatever the token says.
|
||
- The `aal` claim lives as long as the access token (`jwt_expiry`, 3 600 s
|
||
locally). For the role and rights RPCs only (rare, administrative), V1-2.1
|
||
adds a check that the session named by the token's `session_id` still
|
||
exists in `auth.sessions` at `aal2`. The columns and the claim are verified
|
||
on the pinned image first; if one is missing, V1-2.1 stops for an owner
|
||
decision (claim alone with the residual of up to one token lifetime after
|
||
a downgrade, or another check). Nothing here is assumed present.
|
||
- A stolen `aal2` session is a distinct risk this design does not remove:
|
||
it keeps working until it ends. Reducing it (freshness window, session
|
||
limit) is not part of V1-2.
|
||
- Concurrent role changes: unique active row per (user, role), lock on the
|
||
owner count (F18), one transaction per write.
|
||
|
||
#### 5.7.9 Reserves recorded, not decided
|
||
|
||
- `is_platform_admin` and the staff read policies (`profiles_select_staff`,
|
||
`audit_logs_select_admin`) do not read the assurance level. AR-1 B covers
|
||
changes of roles, not those reads; IDENTITY.md §4 foresaw folding `has_mfa`
|
||
into them. Left for an owner decision; V1-2.1 does not change them.
|
||
- Refused escalation attempts are not in the audit table (§5.7 order of
|
||
checks).
|
||
- A recent-TOTP freshness check on the role RPCs through `amr` (§5.7.3).
|
||
- The DEV hardening of `ENVIRONMENTS.md` §3.6 becomes a precondition of M4
|
||
on DEV (§5.7.2 step 0); the owner chooses its form.
|
||
|
||
---
|
||
|
||
## 6. Lifecycle, review, verification and publication
|
||
|
||
### 6.1 States
|
||
|
||
Versions keep their three statuses. Rounds are separate rows, so the version
|
||
enum and its immutability stay untouched.
|
||
|
||
```
|
||
version: draft ──publish──▶ published ──deprecate──▶ deprecated
|
||
|
||
round (on a draft):
|
||
submit ──▶ verifying ──verdict passed──▶ open ──approve──▶ approved ──publish──▶ (version published)
|
||
│ └──request changes──▶ changes_requested
|
||
└──verdict failed, or unavailable──▶ verification_failed
|
||
verifying | open | approved ──withdraw──▶ withdrawn
|
||
```
|
||
|
||
- While a round is `verifying`, `open` or `approved`, the draft content is
|
||
frozen (trigger, every role, seed included). The terminal states
|
||
(`changes_requested`, `withdrawn`, `verification_failed`) unfreeze it; a
|
||
published round stays `approved` and is referenced by the version.
|
||
- One non-terminal round per draft at a time. A change after approval needs
|
||
a withdrawal, which voids the approval; the next submission opens a new
|
||
round.
|
||
- A draft that has rounds cannot be deleted (foreign key `restrict`), so the
|
||
D6 trail survives.
|
||
- Every lifecycle RPC locks in one order: sheet, then version, then round.
|
||
Deadlock and serialization errors map to a closed, retryable failure.
|
||
|
||
### 6.2 Drafts and saving (O12 A)
|
||
|
||
- A draft is created from the empty document (§7.4), from an earlier version
|
||
of the same sheet (`create_sheet_draft`), or by the working copy (§14.3).
|
||
Its base (`source_version_id`) is set only when the source is a
|
||
`published` version with a `published_review_id`, that is a version
|
||
published through a V1-2 round; any other source (deprecated, published
|
||
before M5, working copy, empty document) gives no base, and every group is
|
||
to cover (§6.3).
|
||
- Unsaved changes stay in the page. The leave guard of V1-1 protects them;
|
||
a local recovery copy, keyed by account and version with the revision
|
||
recorded in the copy (wording matched to the code at V1-2.6 U0, §17.12), is
|
||
kept in the browser with the report editor's persistence pattern and offered
|
||
back after a crash or an expired session, never sent automatically.
|
||
- Validation while editing: the page runs the core's checks and shows the
|
||
validation panel (§8.1). It is advisory; the server verdict decides (§6.4).
|
||
- Saving is explicit (« Enregistrer »): `save_sheet_draft(version_id,
|
||
expected_revision, document, change_note)`. The server checks the caller's
|
||
capability and `aal2`, that the version is a draft of an active official
|
||
sheet other than the historical sheet, that no round freezes it, the
|
||
revision, the structural guards of §12.2 (shape, size at most 2 MiB as the
|
||
UTF-8 bytes of the document's JSON text, `octet_length(content::text)`,
|
||
defined in §12.2, species), and refuses an
|
||
unchanged document. It increments `revision`, the trigger adds the actor to
|
||
the author set, and the audit records `anatomical_sheet_version.saved` with
|
||
the revision. A draft may hold integrity errors while it is being written;
|
||
the verdict refuses them at submission.
|
||
- From V1-2.6 U6 (owner 2026-11-05, §17.12; not built yet), the save also
|
||
applies the declared fixed-category check of §12.2: no role carried by two
|
||
categories, a category carrying a role keeps that role's fixed names, no
|
||
role of the stored draft lost. A draft that carries no role (every draft
|
||
saved before U6, the equine working copy) still saves.
|
||
- A trigger bumps `revision` on any content write, so no write slips under a
|
||
round unseen.
|
||
- The direct UPDATE grants on `content`, `change_note`, `name`, `slug` and
|
||
`description` are revoked (M4). The sheet row's `name` and `description`
|
||
are set at creation and refreshed from the document at publication; the
|
||
catalogue shows the published document's FR and EN texts (§10). The slug
|
||
is set at creation and never shown in routes.
|
||
- Concurrency: a stale `expected_revision` answers `draft_conflict`. The page
|
||
shows the server revision with its author and time and offers « recharger »
|
||
or « garder ma version »; the second saves the local document on the new
|
||
revision after an explicit confirmation naming what it replaces. Nothing is
|
||
overwritten silently.
|
||
- A per-actor write budget follows V1-1 D15 (thresholds in V1-2.1).
|
||
|
||
### 6.3 Review rounds, review groups and acknowledgments
|
||
|
||
`anatomical_sheet_reviews` (M5), one row per round:
|
||
|
||
| Column | Meaning | Set in |
|
||
|---|---|---|
|
||
| `version_id`, `round` | the draft and the round number | every state |
|
||
| `revision` | the revision submitted; with the freeze, `(version_id, revision)` is the « exact version » of D6 | every state |
|
||
| `authors` | the author set of §5.5, frozen at submission | every state |
|
||
| `submitted_by`, `submitted_at`, `submission_note` | the submitter | every state |
|
||
| `status` | §6.1 | every state |
|
||
| `attempts`, `lease_token`, `locked_at` | the verification job (§6.4) | while `verifying`; kept after |
|
||
| `verdict`, `verified_at`, `verified_with` | the server verdict for this revision, written by the worker RPC only | `open`, `approved`, `changes_requested`, and `verification_failed` with outcome `failed` |
|
||
| `failure_outcome`, `failure_code` | `failed` or `unavailable` and the closed code (§6.5) | `verification_failed` |
|
||
| `decided_by`, `decided_at`, `decision_note` | the approver or the reviewer who requested changes; the note is required | `approved`, `changes_requested` |
|
||
| `withdrawn_by`, `withdrawn_at`, `withdrawal_note` | the editor who withdrew | `withdrawn` |
|
||
|
||
Review groups. The verdict splits the document into groups:
|
||
|
||
- `general`: names, description, scope disclaimer, attribution, references,
|
||
vertebral regions, annotation categories;
|
||
- `view:<viewId>`: the view and the annotations located in it;
|
||
- `zone:<zoneId>`: the finding zone, its categories and nodes;
|
||
- removal groups: a `view:` or `zone:` group of the base absent from the
|
||
draft, whose content is « removed ».
|
||
|
||
The equine draft has 30 groups (general, 2 views, 27 zones). Each group gets a
|
||
digest: the sha256 of the canonical JSON of its elements, statuses included,
|
||
with absent statuses written out; a removal group gets a digest of its
|
||
removal.
|
||
|
||
Groups to cover (the one coverage rule): every group when the draft has no
|
||
base; for a derived version, every group whose digest differs from the base's
|
||
group of the same key, removal groups included. A group equal to its base
|
||
holds only elements the base's approved round covered.
|
||
|
||
Acknowledgments (`anatomical_sheet_review_acknowledgments`, M5, append-only):
|
||
|
||
- A reviewer outside the round's author set records « groupe lu » for one
|
||
group of an `open` round, against the verdict's digest of that group. A
|
||
group that still holds a `to_confirm` or `inherited` element cannot be
|
||
acknowledged: there is nothing to approve in it yet.
|
||
- An acknowledgment from an earlier round of the same draft carries to the
|
||
next round while the group's digest is unchanged and its reviewer is not an
|
||
author of the new round; the round screen shows it with its round and date.
|
||
SQL compares the stored digests; the worker needs no earlier data.
|
||
- Approval requires a current or carried acknowledgment of every group to
|
||
cover, each by a reviewer whose grant is active at that moment (§5.2).
|
||
|
||
Progressive review. The reviewer reads groups and answers in comments; the
|
||
editor applies the answers, marks the read groups `reviewed` and resubmits;
|
||
the reviewer then acknowledges each finished group. Groups that do not change
|
||
afterwards keep their acknowledgments across rounds. The final approval is one
|
||
decision, resting on per-group acknowledgments that each carry a reviewer and a
|
||
time: no single action approves a whole structure unread. An anatomical
|
||
decision is applied by an editor only from a reviewer comment that names the
|
||
element; the reviewer's acknowledgment of the changed group is its validation.
|
||
|
||
The change list (added, removed, changed and status-changed elements against
|
||
the base, a move appearing as removed plus added) is shown per group on the
|
||
review screen. It is a reading aid; coverage rests on the groups.
|
||
|
||
Comments (`anatomical_sheet_review_comments`, M5, append-only): author, body
|
||
(at most 4 000 characters), optional group key, time. Element keys, when
|
||
needed, are written in the body. Editors, reviewers and publishers comment.
|
||
|
||
Decision (O5 A): one decision, approve or request changes with a required
|
||
note, closes the round. The decision on the round, the acknowledgments per
|
||
reviewer and the audit keep enough trace for a future quorum, which would add
|
||
decision rows without changing the meaning of past rounds. The publication is
|
||
recorded on the version (`published_review_id`, `published_by`,
|
||
`published_at`), not duplicated on the round.
|
||
|
||
`submit_sheet_review(version_id, expected_revision, note)` refuses a stale
|
||
revision, the historical sheet, an archived sheet and a draft that already
|
||
has a non-terminal round.
|
||
|
||
### 6.4 Server verdict (O15 A)
|
||
|
||
The verdict that approval and publication rely on is computed by the Rust
|
||
worker from data read on the server side. The browser is never a validation
|
||
authority: its validation panel is advisory, and no RPC accepts a verdict, a
|
||
fingerprint or a document hash from a page.
|
||
|
||
Job. The round row is the job, with the avatar lease pattern of
|
||
`20261013100000_files_foundation.sql` (lease token, `locked_at`, fixed lease,
|
||
attempts below a limit), plus a progressive delay for technical retries only
|
||
(owner decision 2026-11-01). Submission sets the round `verifying`. Worker RPCs, service role only (M6):
|
||
|
||
- `claim_sheet_verifications(limit)`: `for update skip locked` over rounds
|
||
`verifying` with no live lease and no pending delay (`not_before` null or
|
||
reached); sets the token and `locked_at`, increments `attempts`, clears
|
||
`not_before`; returns round, version, sheet, revision and token.
|
||
- `get_sheet_verification_input(review_id, lease_token)`: the document at the
|
||
round's revision (frozen) and the base document, both as text; the drawings
|
||
the document references among the rows registered for the sheet (asset id,
|
||
sha256, byte size, object key).
|
||
- `complete_sheet_verification(review_id, lease_token, verdict)`: accepted
|
||
only while the round is `verifying`, the token is the live one, the verdict
|
||
names the round's sheet, version, revision and review, its group keys equal
|
||
`general`, the document's view and zone ids and the base's removed ones, and
|
||
its drawings equal the document's asset ids with the rows' sha256; anything
|
||
else answers `stale` or `malformed` and writes nothing. Moves the round to
|
||
`open` or to `verification_failed` (§6.5) and audits.
|
||
- `fail_sheet_verification(review_id, lease_token, code)`: a technical
|
||
failure, closed by cause (2026-11-01, `private.sheet_worker_final_codes`).
|
||
A definitive code (`verification.worker.resource_limit`, cause intrinsic to
|
||
the frozen input or the contract caps; `verification.worker.verdict_refused`)
|
||
closes the round at its first occurrence: `verification_failed`, outcome
|
||
`unavailable`, the code kept, no delay, never claimed again. A transient
|
||
code (`timeout`, `unavailable`, `lease_expired`): the round stays `verifying`
|
||
and becomes claimable after a delay
|
||
that grows with the attempt (2 s after attempt 1, 5 s after 2, 10 s after 3,
|
||
20 s after 4; `private.sheet_verification_retry_delay`), kept in the round's
|
||
`not_before` (a column the API roles cannot read, set here, cleared by the
|
||
claim); the fifth failure of a transient code becomes `verification_failed`
|
||
with outcome `unavailable` and clears it. The audit payload says which rule
|
||
closed the round (`closed_by`: `definitive` or `attempt_limit`). Nothing is written for a stale call. The delay
|
||
is persisted, so no worker sleeps and any worker honours it; the effective
|
||
wait is the delay plus up to one poll interval of the worker (2 s by
|
||
default). Only these technical failures wait: a validation or integrity
|
||
refusal is a verdict and is never retried, and a dead lease is claimed again
|
||
at once (the 10-minute lease is its wait).
|
||
|
||
Processing. Verification runs as its own mode of the worker image (`run
|
||
--jobs sheet-verify`), in its own container under the `worker` compose
|
||
profile, so a fault in it never stops avatar or purge processing. The keyed
|
||
parent downloads the drawings and passes the document texts and drawing bytes
|
||
unparsed to the keyless sandboxed child, the only process allowed to parse
|
||
untrusted bytes. The child runs the core's verdict function (V1-2.2) and
|
||
returns a JSON verdict. The spawner takes its limits per command: about
|
||
13 MiB of input (document, base, four drawings of 2 MiB) and a verdict output
|
||
cap sized on the at-caps fixture; the RPC body cap of this mode is raised to
|
||
match. Memory and CPU limits and a wall-clock watchdog bound the child; the
|
||
seccomp profile is derived again for the new code path.
|
||
|
||
Verdict content, bound to the round: `sheet_id`, `version_id`, `revision`,
|
||
`review_id`; the fingerprint `sha256-rfc8785-validated-v1` of the validated
|
||
document (absent when the document has an error); each reachable drawing
|
||
checked (asset id, sha256, byte size, result); issues (code, severity, path);
|
||
caps; completeness counts (statuses, vet referrals, uncited elements); the
|
||
groups and their digests; the change list; `verified_with` (core version).
|
||
|
||
Core changes. A release that changes the SVG reader, the integrity rules, the
|
||
caps or the fingerprint ships a migration that withdraws every round of a
|
||
draft version in `verifying`, `open` or `approved`, with the reason recorded
|
||
(the round of a published version stays `approved`, §6.1, and
|
||
`withdraw_sheet_review` refuses it with `draft.not_a_draft`; worded at V1-2.6
|
||
U0); editors submit again and the new worker verifies. The release replay (§15) runs before such a
|
||
release.
|
||
|
||
Availability. Reviews and publications need a running, health-checked
|
||
verification worker on the stack where they happen. Without one, authoring
|
||
continues, submissions stay `verifying`, nothing is approved or published
|
||
(fail-closed), and the editor can withdraw at any time. The worker code
|
||
authorises nothing on DEV: starting it there is an operating checkpoint of its
|
||
own (§16.11), because a started DEV worker also processes the avatar upload
|
||
waiting since the V1-1 acceptance (AVATAR-01) and the due rows of the purge
|
||
queue.
|
||
|
||
Implemented in V1-2.3 (2026-11-01, migration `20261101100000_sheet_verification_jobs.sql`,
|
||
`crates/worker` mode `sheet-verify`, STORAGE.md §3.6): lease 10 minutes, attempt limit
|
||
five, verdict text at most 4 MiB; the completion also refuses an unknown verdict format
|
||
or code, a duplicated group key and a drawing whose result is not `ok`, and accepts a
|
||
failed verdict without groups or drawings; worker codes `verification.worker.unavailable`,
|
||
`.timeout`, `.resource_limit`, `.lease_expired` (a dead lease), `.verdict_refused` (a
|
||
completion answered `malformed`), a closed list in SQL (`private.sheet_worker_codes`); the
|
||
definitive ones are `.resource_limit` and `.verdict_refused` (`private.sheet_worker_final_codes`).
|
||
These values and codes are the implementer's, for the owner's confirmation. The
|
||
service role executes these four RPCs besides the two upload ones (pgTAP 018).
|
||
|
||
Rejected: a verdict computed in browsers (contrary to the owner's rule), a
|
||
synchronous HTTP verification service (a public endpoint holding the service
|
||
key, a sandbox to rebuild; not in the MVP), an operator command-line
|
||
verifier.
|
||
|
||
### 6.5 Verdict failures (O23)
|
||
|
||
Fail-closed: no round is approved and no version published while its verdict
|
||
is missing, failed, stale or in error. Two outcomes close a verification that
|
||
did not pass; the closed codes keep the categories apart.
|
||
|
||
| Category | Example | Outcome | Retry | Exit |
|
||
|---|---|---|---|---|
|
||
| Business validation | integrity error, caps exceeded, annotation without geometry, annotation outside its view's frame | `verification_failed`, outcome `failed`, codes `verification.validation.*` and the issues | no | fix the draft, submit again |
|
||
| Integrity | strict parse refused, drawing missing, size or sha256 mismatch, SVG refused, needing a removal or outside the stored form (§9.2), `object_conflict` | `verification_failed`, outcome `failed`, codes `verification.integrity.*` | no | fix or upload again; `object_conflict` follows §9.3 |
|
||
| Transient worker error | database or Storage unreachable, broken child, child killed from outside (SIGKILL or any signal not listed below: OOM killer, stop), worker restart | `verification.worker.unavailable`, stays `verifying`, code recorded | yes, after 2 s, 5 s, 10 s, 20 s, up to the limit | automatic |
|
||
| Timeout | child over its wall-clock deadline | `verification.worker.timeout`, stays `verifying`, code recorded | yes, same delays, up to the limit | reduce the document or the drawing if it repeats |
|
||
| Resource limit intrinsic to the content | frame refused, input over the child cap, output over its cap, CPU budget (SIGXCPU), memory budget (SIGABRT), seccomp (SIGSYS) | `verification_failed`, outcome `unavailable`, `verification.worker.resource_limit`, closed at the first occurrence | no (the same input ends the same way) | reduce the document or the drawings, submit again |
|
||
| Verdict refused | completion answered `malformed` | `verification_failed`, outcome `unavailable`, `verification.worker.verdict_refused`, closed at the first occurrence | no | submit again later; reported to the operator |
|
||
| Interruption | worker crash, lease expired | claimable again at once (the lease was the wait); counts as an attempt | yes, up to the limit | automatic |
|
||
| Stale result | completion with an old token, after a withdrawal, or naming another revision | nothing written, logged | no | none needed |
|
||
| Attempt limit | a transient code at its fifth attempt (five; V1-2.3 implements five, for the owner's confirmation) | `verification_failed`, outcome `unavailable`, last code | no | submit again later |
|
||
| Core change | release that changes rules or reader | rounds withdrawn by the release migration | no | submit again |
|
||
|
||
- Withdrawal is always available: the submitter or any editor withdraws a
|
||
round in `verifying`, `open` or `approved`, with a note; the draft
|
||
unfreezes. No round stays frozen without an exit.
|
||
- The round screen shows « vérification en attente depuis N min » with the
|
||
attempts and the last code.
|
||
- Every code maps to an FR and an EN message from a closed list; no stack
|
||
trace, internal path or database error reaches a page.
|
||
- Audit: submitted, verification passed or failed (outcome, codes), attempt
|
||
failed, withdrawn, decided, published.
|
||
- No partial publication: §6.8 is one transaction.
|
||
- Divergence recorded (owner, 2026-11-02, BDR-094): the « reported to the
|
||
operator » exit of « Verdict refused » is not implemented. The worker writes
|
||
an error line (`complete_malformed`, `crates/worker/src/verify_job.rs`) and
|
||
`fail_sheet_verification` keeps the code on the round and in the audit; no
|
||
notification is sent. No alert mechanism is planned in V1-2; the user
|
||
message says « l'incident est enregistré » / « the incident is logged ».
|
||
|
||
### 6.6 Element statuses, keys and coverage (O3 B, O7 A)
|
||
|
||
Three distinct notions (O7):
|
||
|
||
- the draft's state: draft, revision, frozen or not by a round;
|
||
- the review marking of an element, a statement made by an editor:
|
||
`to_confirm`, `reviewed` or `inherited`;
|
||
- the business approval of the version: a reviewer outside the author set
|
||
approves a round after acknowledging its groups.
|
||
|
||
A marking validates nothing by itself. An author who sets `reviewed` on an
|
||
element makes a statement that only an acknowledgment and an approval can
|
||
cover.
|
||
|
||
Meanings:
|
||
|
||
- `to_confirm` (« À confirmer »): a doubt, or content created and not yet
|
||
read. Every element created in the editor starts there.
|
||
- `inherited` (« Hérité, non relu »): carried over from the historical
|
||
import, never reviewed; an omitted status means `inherited`. No editor path
|
||
assigns it. It is never acknowledgeable, approvable or publishable, whatever
|
||
the base (C2).
|
||
- `reviewed` (« Relu »): marked by an editor; it counts only when covered.
|
||
|
||
Keys:
|
||
|
||
| Element | Key | Stable under |
|
||
|---|---|---|
|
||
| Annotation | its id, unique in the document | label changes, geometry changes, moves between views |
|
||
| Finding zone | its id | label changes |
|
||
| Finding category or node | path key `<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_confirm` or `inherited`. An element validated in an earlier published
|
||
version and left untouched keeps its validation through the base's approved
|
||
round, because its group's digest is unchanged; any change, move or status
|
||
change in the group re-opens it.
|
||
- The edit commands apply the status rules for the editor; the server does
|
||
not trust them. A page that saves a modified element still marked
|
||
`reviewed` changes its group's digest, so the group must be acknowledged
|
||
again; an `inherited` element anywhere blocks approval and publication.
|
||
- A version derived from a base copies its statuses; the base was published
|
||
through a V1-2 round, so it holds neither `to_confirm` nor `inherited`.
|
||
|
||
### 6.7 Submission, approval and publication rules (C7)
|
||
|
||
Four stages, each a superset of the previous:
|
||
|
||
1. Structurally valid, that is submittable: the verdict passes the
|
||
submission rules below. Elements may still be `to_confirm` or `inherited`.
|
||
2. Approvable: structurally valid, publishable content, groups covered.
|
||
3. Approved: a reviewer outside the author set decided so.
|
||
4. Publishable: approved, with every binding still intact.
|
||
|
||
| Rule | Submit | Approve | Publish | Code |
|
||
|---|---|---|---|---|
|
||
| Strict parse of the document and, for a derived version, of its base (§6.5; owner decision 2026-10-29) | yes | | | `verification.integrity.document`, `verification.integrity.base` |
|
||
| The 19 error codes | yes | | | `verification.validation.rules` |
|
||
| Caps of §1, all of them | yes | | | `verification.validation.caps` |
|
||
| Every annotation has a geometry | yes | | | `verification.validation.no_geometry` |
|
||
| Every reachable drawing present, size and sha256 equal to its row, read without removal, in the stored form of §9.2 | yes | | | `verification.integrity.*` |
|
||
| Every annotation entirely inside the frame of its view, edges included: the view's `view_box`, else the `viewBox` of the drawing it draws, read as a browser reads it (four numbers, positive width and height) and usable within the range rules browsers draw faithfully (owner brief 2026-11-01: edges within 2²⁰, spans from 1 unit, aspect at most 100, farthest edge at most 256 smaller spans); curves and arcs measured on their shape; path data a browser would not read whole refused; a view drawn on a clean drawing without either has no frame. Measured on the views whose drawing reads clean; the document is never rewritten (owner brief 2026-10-30, RUST.md §12.11) | yes | | | `verification.validation.out_of_frame` (issues `annotation.geometry.out_of_frame`, `view.frame.unknown`) |
|
||
| Every annotation in frame shows at least 4 CSS px on the smallest preview, the editor at 320 × 568 (main view box 286 × 310, detail view box 254 × 191, `xMidYMid meet`): a point's visible disc (`2 × max(2, r − 12)`), a trigger circle's diameter, a polygon's or a path's smaller side (curves and arcs on their shape). Same views, same frame; the document is never rewritten (owner brief 2026-11-01, RUST.md §12.13) | yes | | | `verification.validation.marker_too_small` (issue `annotation.geometry.too_small`) |
|
||
| Every polygon or path annotation in frame fills a disc of 4 CSS px on the same preview: under the `nonzero` rule the layer fills with, its stroke left out, a centre inside the fill at least the radius from every edge (closing edges included), curves and arcs cut into chords whose deviation is taken off; arcs modelled as browsers store them (`f32` endpoints, a radius other than zero at least `2⁻²⁰`, the spread of one `f32` ulp added); measured within `interior::MAX_OUTLINE_VERTICES` 4 096 vertices and one budget of `2²⁵` edge distances per sheet, refused past them; refused in doubt (owner brief « fermeture du dernier MEDIUM » 2026-11-01, RUST.md §12.14) | yes | | | `verification.validation.marker_interior_too_small` (issue `annotation.geometry.interior_too_small`) |
|
||
| Fingerprint computed | yes | | | `verification.integrity.fingerprint` |
|
||
| Fixed categories (from V1-2.6 U6, §17.12; not built yet): each of `bone`, `joint`, `vertebra` carried by exactly one category with its fixed FR and EN names, `navigation` by at most one with its fixed names; judged on drafts, never on a published version (the §15 replay filters it) | yes | yes | yes | submission: issues `category.fixed.*` under `verification.validation.rules`; approval and publication: the declared check of §12.2 (closed code fixed at U6) |
|
||
| Verdict passed, on the current revision | | yes | yes | `verdict.missing`, `verdict.failed`, `verdict.stale` |
|
||
| No `to_confirm` element (D2) | | yes | yes | `publish.to_confirm.open` |
|
||
| No `inherited` element, an omitted status counting as `inherited` (O3 B) | | yes | yes | `publish.inherited.present` |
|
||
| Scope disclaimer present in FR and EN, non-blank after trimming (O6) | | yes | yes | `publish.disclaimer.missing` |
|
||
| Every group to cover acknowledged by a reviewer outside the author set with an active grant | | yes | yes | `review.groups.uncovered` |
|
||
| Approver outside the author set, grant active | | yes | yes | `review.separation`, `publish.approval.invalid` |
|
||
| An `approved` round on the version's current revision | | | yes | `publish.review.missing` |
|
||
| Each drawing's row sha256 equal to the verdict's | | | yes | `publish.drawing.changed` |
|
||
| Sheet active, official, other than the historical sheet | yes | yes | yes | `sheet.inactive`, `sheet.historical_read_only` |
|
||
| Species active and other than `other` | | | yes | `publish.species.inactive`, `publish.species.other` |
|
||
| Caller capability (E, V, P) and `aal2` | yes | yes | yes | `rights.capability`, `rights.mfa` |
|
||
|
||
- The rules of the first six lines come from the stored verdict. SQL checks
|
||
relations, states, rights, separation, the verdict's structure (§6.4), and
|
||
the declared defensive checks on the stored document (§12.2): statuses and,
|
||
from V1-2.6 U6, the fixed categories.
|
||
- Shown, never blocking: uncited elements, the two warning codes, the number
|
||
of vet referral nodes.
|
||
- Approval never changes the document.
|
||
- Approval does not check the species: an approved round of an inactive
|
||
species waits for its activation (§7.2).
|
||
|
||
### 6.8 Publication (atomic)
|
||
|
||
`publish_sheet_version(review_id)`, in one transaction: lock sheet, version,
|
||
round; check every publication rule of §6.7; set the version `published` with
|
||
`published_by`, `published_at`, `published_review_id` and the fingerprint
|
||
taken from the verdict, never from a client parameter; refresh the sheet row's
|
||
`name` and `description` from the document; move `current_version_id`; audit
|
||
`anatomical_sheet_version.published` with the revision, the fingerprint and
|
||
the round. The old signature `publish_sheet_version(uuid)` is dropped in the
|
||
same migration (`CREATE OR REPLACE` with new arguments would leave it
|
||
callable), as is every superseded RPC signature, each proven absent by pgTAP.
|
||
The client gate `publishSheetVersion` is deleted in the same step.
|
||
|
||
`guard_sheet_version_update` is extended in two ways, for every role:
|
||
|
||
- a draft becomes `published` only with a `published_review_id` naming an
|
||
`approved` round of the same version and revision whose verdict passed, so
|
||
no direct UPDATE, even with a privileged key, publishes outside the gate;
|
||
- the deprecation transition cannot change any column added by V1-2
|
||
(fingerprint, review link, revision, authors, base, working-copy
|
||
provenance).
|
||
|
||
A wrong published version is repaired only by deprecating it and publishing a
|
||
corrected one.
|
||
|
||
### 6.9 Deprecation, archive, deletion, historical reads (O8 A)
|
||
|
||
- A version that was ever published is never modified or deleted physically:
|
||
M4 extends the delete guard to `deprecated` for every role (F13).
|
||
- Deprecation keeps the version readable by id. Deprecating the current
|
||
version makes the latest remaining published one current again; the A8
|
||
confirmation names it. When none remains, the confirmation says that the
|
||
sheet leaves the catalogue list; `current_version_id` becomes null and the
|
||
versions stay readable by id.
|
||
- Archiving an official sheet removes it from the catalogue list; its
|
||
published and deprecated versions stay readable by id under catalogue
|
||
access (§5.3). Historical reads never bypass §5.3.
|
||
- An official sheet that ever had a published version cannot be deleted;
|
||
drafts without rounds can.
|
||
- Narrowing the read of archived versions to « referenced by a bilan the
|
||
reader can see » needs the bilan table of V1-3 and is reviewed there.
|
||
|
||
---
|
||
|
||
## 7. Species and new sheets
|
||
|
||
### 7.1 What the current model allows
|
||
|
||
Nothing in the document schema is equine-specific: `species_id` is a free
|
||
stable id, vertebral regions are data, labels are FR/EN pairs. The equine
|
||
specifics found are the report migration map (a legacy equine concept, kept
|
||
as is; §10 adds a load path without it), `NewReportRoute.DEFAULT_SPECIES_ID =
|
||
'equine'` and the bundle plugin (local tool, unchanged until V1-3), the
|
||
curation pipeline (an equine tool), and the archive caps (4 drawings), which
|
||
bind every species.
|
||
|
||
### 7.2 Species rows (O9 C)
|
||
|
||
- `create_species(id, name_fr, name_en, sort_order)`: sheet editor with
|
||
`aal2`, audited. Inserts the row with `active = false`. The id follows the
|
||
existing CHECK and is never renamed; an existing id gets one answer.
|
||
`sort_order` an integer from 0 to 9 999, or null for the default 100;
|
||
outside → `invalid_input` (M7, §17.11).
|
||
- `update_inactive_species(id, name_fr, name_en, sort_order)`: sheet editor
|
||
with `aal2`, inactive rows only, audited. `sort_order` 0 to 9 999, null keeps
|
||
the stored order (M7, §17.11).
|
||
- `activate_species(id)`: platform owner with `aal2`, audited; the only way a
|
||
species becomes active.
|
||
- `rename_species(id, name_fr, name_en)`: platform owner with `aal2`, audited;
|
||
corrects an active species' names, never its id.
|
||
- No deactivation and no deletion in V1-2: an unused inactive species stays
|
||
invisible.
|
||
- The animal forms do not change. The policy `species_select_active` is not
|
||
widened, so `fetchSpeciesLabels`, `create_animal` and `update_animal` keep
|
||
seeing active species only, for every account, editors included. The admin
|
||
space lists species through `list_catalog_species()` (E, V, P, O, `aal2`),
|
||
which returns active and inactive rows with their state. Widening the
|
||
policy instead would show inactive species in an editor's own animal forms.
|
||
- Creating an official sheet accepts an active or an inactive species, never
|
||
`other`, and never activates a species. Publication refuses an inactive
|
||
species and `other` (§6.7).
|
||
- A species row holds an id, two names and an order (0 to 9 999). No vertebral formula,
|
||
zone, finding or drawing is generated for it.
|
||
|
||
Amendment of V1-1 N1 and §5.4 (ratified with O9, 2026-10-28): « The list of
|
||
species is no longer fixed by migration. A species is added by an audited RPC:
|
||
created inactive by a habilitated sheet editor, activated by the platform
|
||
owner. Its id never changes; an inactive species is invisible in the animal
|
||
forms; `other` stays refused for anatomical sheets. » The V1-1 contract
|
||
carries a pointer to this amendment; the table comment « no API write path »
|
||
changes with M5.
|
||
|
||
### 7.3 Several official sheets per species (O10 A)
|
||
|
||
Allowed. Each sheet has its own id, slug (unique among official sheets, which
|
||
share the null creator of the existing unique index), versions, rounds and
|
||
completeness. The catalogue lists every sheet with a published version under
|
||
its species, with its FR and EN names and description. Which sheet a bilan
|
||
uses, and whether a species gets a default sheet, is decided with V1-3.
|
||
|
||
### 7.4 Starting a sheet
|
||
|
||
- From the empty document of the core (`create_empty_sheet_document`):
|
||
species, FR and EN names, slug; everything else is entered in the editor.
|
||
- The copy of a finding catalogue from another sheet is deferred (O11), so no
|
||
finding of one species is ever reused automatically for another. The
|
||
working copy of the historical equine sheet (§14.3) is a distinct operation,
|
||
restricted to that sheet.
|
||
- No template of scientific content is shipped. Vertebral formulas, zones and
|
||
findings of a new species are entered by the editor from sources cited in
|
||
the references registry.
|
||
- From V1-2.6 U6 (owner 2026-11-05, §17.12) the empty document carries the
|
||
three fixed categories `cat-bone` (« Os » / « Bones »), `cat-joint`
|
||
(« Articulations » / « Joints ») and `cat-vertebra` (« Vertèbres » /
|
||
« Vertebrae »), with their roles and default colours; nothing else is
|
||
pre-filled.
|
||
- Scope and limits (choice 7, decision T12): the editor may insert a
|
||
versioned common text once into the FR and EN scope fields while both are
|
||
empty; the fields stay free text afterwards, and no later version of the
|
||
common text changes a draft or a published version. No common text exists
|
||
yet: its FR and EN wording, its source and its validation record are
|
||
supplied by the owner before U7, and nothing is written in their place
|
||
meanwhile. It is never presented as veterinary or legal advice approved by
|
||
the platform.
|
||
|
||
### 7.5 Species-specific checks
|
||
|
||
The core checks structure only: unique region codes, order as given,
|
||
`count ≥ 1`, coherent `count_range`, region codes used by annotations exist.
|
||
Expected vertebral formulas per species would be veterinary data nobody has
|
||
supplied; they are not invented.
|
||
|
||
---
|
||
|
||
## 8. Editor
|
||
|
||
### 8.1 Architecture
|
||
|
||
- The page holds the draft document as one JSON string, loaded in a
|
||
`PreviewSheet` handle (§10): drawings read once per sha256, the document
|
||
replaced and re-indexed after each change, `view.canvas` composing the view
|
||
on that handle as on `LoadedSheet`, and a draft with referential gaps still
|
||
drawn with its issues.
|
||
- Every change is a Rust core command (`sheet.edit`, V1-2.2): generic
|
||
primitives (insert, update, remove, reorder) over element keys, applying the
|
||
status rules of §6.6 and refusing what would break strict parsing or leave
|
||
an element named by another behind (owner decision 2026-10-29, below);
|
||
other referential gaps are left to the validation panel. A `dependents(key)`
|
||
query feeds the delete confirmations. TypeScript holds no schema of its own
|
||
and no Zod copy; it reads the ts-rs types.
|
||
- As built in V1-2.2, strict validation of the commands confirmed by the owner
|
||
(2026-10-29): the wire ops are `insert`, `update`, `remove`, `move` (the
|
||
reorder), `set_status` and `mark_reviewed`; besides what breaks strict
|
||
parsing they refuse what would leave an element unaddressable or outside the
|
||
editor's offer (`duplicate_key`, `unknown_key`, `invalid_target`,
|
||
`id_changed`, `invalid_position`, `too_deep` beyond 8 finding levels).
|
||
- Removal, owner decision 2026-10-29 (atomic refusal): `remove` takes the
|
||
element with its descendants (a zone with its categories and nodes, a
|
||
category or node with its children: §6.6 « with descendants ») and is
|
||
refused as a whole, the document unchanged, with `has_dependents` while
|
||
anything else names the element: a view with annotations drawn in it,
|
||
detail views under it or a link that opens it; an annotation category or a
|
||
vertebral region used by an annotation; a finding zone linked from an
|
||
annotation; a reference cited by a category or a node. The page shows the
|
||
`dependents` list; the editor detaches or deletes those first. No cascade
|
||
deletion is offered in level 1. An `insert` or `update` that names an
|
||
element absent from the document stays allowed (left to the validation
|
||
panel), as does a document saved with gaps: the verdict refuses them.
|
||
Structural rules that name nothing (`view.unreachable` after the last link
|
||
to a view goes, `view.main.count` after the main view goes) are left to
|
||
the validation panel too.
|
||
- Ids are generated by the page (`<prefix>-<10 lowercase base32
|
||
characters>`, alphabet `a-z2-7`, inside the stable-id rule), passed to the
|
||
core, never derived from labels, never editable, never reused.
|
||
- Pointer moves update the page's preview only; the core command runs on
|
||
pointer-up.
|
||
- Undo and redo: a stack bounded by size (8 MiB of document strings).
|
||
- Saving, leave guard, local recovery and conflicts: §6.2.
|
||
- The validation panel lists the core issues and the completeness report
|
||
with FR and EN messages per code, a link to the element, the statuses per
|
||
group, and the document size against the 2 MiB server cap, in the measure
|
||
of §12.2.
|
||
|
||
### 8.2 Level 1, in the MVP
|
||
|
||
An editor can, from the application only:
|
||
|
||
- set the general information: FR and EN name, description and scope
|
||
disclaimer, attribution (authors, licence, notes);
|
||
- manage the references registry: add, edit, delete; type, citation, URL
|
||
(http or https only), DOI;
|
||
- manage the vertebral regions: add, edit, reorder, delete;
|
||
- manage annotation categories: name FR/EN, colour;
|
||
- manage views: the main view, detail views (parent, own drawing or crop of
|
||
the parent entered as numeric `view_box` values over the parent's preview),
|
||
rename, delete;
|
||
- upload and clean a drawing (§9), see its state, attach it to a view;
|
||
- on a view's drawing, as the practitioner sees it:
|
||
- place a point by clicking, set its radius in a field;
|
||
- draw a zone as a polygon by successive clicks, close it; correct, add or
|
||
remove vertices in the vertex list;
|
||
- draw a detail view link the same way and choose the view it opens;
|
||
- select an annotation on the drawing or in the list, move it, delete it;
|
||
- zoom and pan;
|
||
- enter or correct every coordinate in numeric fields (keyboard
|
||
alternative and precision);
|
||
- set each annotation's FR and EN name, kind, category, laterality, finding
|
||
zone, vertebral region, colour and review marking;
|
||
- edit the finding catalogue as a tree: zones, categories (kind), nodes up to
|
||
depth 8; add, rename FR/EN, describe FR/EN, flag vet referral, cite
|
||
references, set the review marking of one element or « Marquer comme relu »
|
||
on one category or one zone, reorder among siblings, delete with a
|
||
confirmation listing the dependents;
|
||
- preview the draft exactly as a practitioner (§10), read the completeness
|
||
report, submit, follow the round and its verification, read comments,
|
||
withdraw.
|
||
|
||
Amended for the V1-2.6 redesign (owner 2026-11-05, §17.12; built in sub-steps
|
||
U1 to U6, each on its own authorisation). The functions above stay; the way
|
||
they are reached changes:
|
||
|
||
- four tabs, Général, Annotations, Constats and Vérification; views,
|
||
drawings, annotation categories and vertebral regions in Annotations; the
|
||
references registry in a side panel opened from the header or from a
|
||
finding; undo and redo in the header on every tab;
|
||
- geometry by direct manipulation on the drawing: a point moved, and sized
|
||
with a slider snapped to the sizes of its view, the core's minimum shown; a
|
||
polygon's vertices dragged, added with « + » on a segment, removed with
|
||
« − »; a zone moved (with the mouse once selected, in an explicit mode by
|
||
touch) or redrawn, the old shape kept until the new one is accepted; the
|
||
keyboard alternative goes through the handles. No coordinate field remains
|
||
in the normal journey;
|
||
- a detail view drawn as a rectangle over its parent's drawing, its name
|
||
proposed from the annotations inside and editable (U5); its access placed
|
||
from the view's menu (U4), or created with the view from U6 when no
|
||
annotation overlaps the rectangle, in the internal navigation category
|
||
`cat-access`;
|
||
- annotation categories: the three fixed categories keep their names and
|
||
roles, their colour and fill opacity adjustable (from U6); other categories
|
||
stay free; an annotation's own colour is shown only when set, with
|
||
« Revenir à la couleur de la catégorie »; a new annotation inherits its
|
||
category's colour;
|
||
- replacing the drawing of a crop view asks first: keep the positions,
|
||
reposition the annotations or cancel, each offered only under the
|
||
conditions of decision T9, never an approximate transformation.
|
||
|
||
### 8.3 Level 2, deferred
|
||
|
||
Curves (`path` drawn or edited by handles; existing paths are displayed and
|
||
can be replaced by a polygon), dragging vertices and drawing a crop rectangle
|
||
on the canvas, moving a finding node to another parent, snapping, left and
|
||
right mirroring, multi-selection and group moves, scale and rotation, copying
|
||
annotations between views or sheets, creating zones from the drawing's own SVG
|
||
shapes, side-by-side visual diff of two versions, comments pinned on the
|
||
drawing or on elements, drag and drop in the finding tree, bulk import of
|
||
findings, species templates, collaborative live editing, package export and
|
||
import.
|
||
|
||
Amended 2026-11-05 (§17.12): dragging vertices and drawing a crop rectangle
|
||
on the canvas move into V1-2.6 (§8.2 as amended); the size slider snaps to
|
||
the sizes already used in the view, other snapping stays deferred. Curves
|
||
form the curves lot (decision T16), which precedes package import, zones from
|
||
the drawing's own shapes and any curve drawing tool. Until then a stored path
|
||
keeps its data byte for byte and is never converted; an operation that would
|
||
change it is refused with the document unchanged. « Remplacer par un
|
||
polygone » stays its one exit, as an explicit replacement only: the editor
|
||
traces the polygon, the core validates it, the old path stays until the
|
||
polygon is accepted, and the change is undone and redone as one entry.
|
||
|
||
### 8.4 What level 1 does not do, and narrow screens (O14 A)
|
||
|
||
Level 1 never edits the drawing itself, accepts no raster image, draws no
|
||
curves and does not let two people edit one draft at the same time (one draft
|
||
per sheet, revision conflicts).
|
||
|
||
| Surface | 1 024 px and wider | Narrower |
|
||
|---|---|---|
|
||
| Catalogue and sheet consultation (P1) | full | full, tested from 320 to 430 px |
|
||
| Preview (practitioner view, admin preview) | full | full, read-only canvas with zoom and pan |
|
||
| Draft editor, every tab, graphic and structured | full | read-only with a notice naming the 1 024 px minimum |
|
||
| Admin lists, overview, rights, species, review screen (read, comment, acknowledge, decide), publication confirmation, deprecation, archive | full | usable, tested at 375 px |
|
||
|
||
Amended 2026-11-05 (§17.12): O14 A is kept. Editing on a phone (boards 14 to
|
||
16 of `docs/design/v1-2-6`) is a future lot after V1-2. From 1 024 px the
|
||
editor works with the mouse, the keyboard and touch (a tablet in landscape,
|
||
handles of at least 44 px); below 1 280 px the application's sidebar is
|
||
hidden in the editor, its menu one tap away.
|
||
|
||
---
|
||
|
||
## 9. Drawings (SVG assets)
|
||
|
||
### 9.1 Principles
|
||
|
||
- Content-addressed and immutable: a new drawing is a new sha256, a new row
|
||
and a new object. A published version references its asset ids; an
|
||
asset-row trigger (M4) refuses any change of `sheet_id`, `sha256` and
|
||
`byte_size` and lets `uploaded_at` go only from null to a value, for every
|
||
role; no policy allows an UPDATE or DELETE of an object.
|
||
- A file is at most 2 MiB (archive cap); the bucket limit drops from 20 MiB to
|
||
2 MiB (M5). A sheet reaches at most 4 distinct drawings (§1).
|
||
- Row state stays the existing column: `uploaded_at` null means pending, set
|
||
means uploaded. No state column is added, so existing rows are not
|
||
rewritten.
|
||
- The application never creates signed URLs on this bucket; drawings are
|
||
downloaded under RLS (§9.4).
|
||
- The avatar pipeline is not reused: no transcoding, no per-user key, no
|
||
quarantine copy, no automatic replacement. Closed codes and the worker's
|
||
lease pattern are reused where they fit.
|
||
|
||
### 9.2 Cleaning before upload (O19 A)
|
||
|
||
The page reads the file with the core SVG reader before anything is stored.
|
||
|
||
| Reader outcome | Treatment |
|
||
|---|---|
|
||
| Hard rejection (`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, `too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, `dangling_reference`, `reserved_id`, `root_visibility`) | refused, with the reason in FR or EN; no cleaning offered |
|
||
| Any removal of active or external content: `script`, `foreignObject`, event-handler attributes, `image`, animation elements, a reference that does not point inside the document (`href` or `url(…)` not starting with `#`), `@import` or `javascript:` values | refused (`svg_active_content`): such a file is hostile or incompatible; no cleaning offered |
|
||
| Any other removal (editor metadata and namespaces, `data-*` attributes, `<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, in the stored form (below) |
|
||
|
||
- Stricter than the table, as built in V1-2.2 and kept (owner brief
|
||
2026-10-29: active content and constructions a browser could read otherwise
|
||
stay refused): an `<a>` link is refused even when it points inside the document, and so is
|
||
a value holding a backslash (a CSS escape can spell `url(` or `javascript:`),
|
||
`expression(`, `image-set(` or `behavior:`, an HTML element (XHTML namespace,
|
||
or a fetcher such as `img`, `meta`, `form`) and an HTML fetching attribute
|
||
(`src`, `srcset`, `action`, `http-equiv`…).
|
||
- A processing instruction other than the XML declaration (`<?xml-stylesheet …?>`)
|
||
is refused as active content: the reader's tree never sees it, but the stored
|
||
bytes would keep it; the verdict refuses a stored drawing that carries one
|
||
(V1-2.2, security audit).
|
||
- An oversized `title` or `desc` is a removal for the cleaning only: the reader
|
||
of stored drawings refuses such a file whole (`too_complex`), so it reaches
|
||
Storage only cleaned (V1-2.2).
|
||
- 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.
|
||
- Stored form (owner decision 2026-10-29; replaces « clean = original
|
||
bytes »): whatever the outcome, clean or cleanable, the bytes hashed and
|
||
uploaded are the drawing's stored form, never the original file: the XML
|
||
declaration `<?xml version="1.0" encoding="UTF-8"?>`, a line feed, then the
|
||
tree as the core serialises it (one spelling of every escape, double
|
||
quotes, no comment, processing instruction, CDATA section or entity, no
|
||
other declared encoding). It must fit 2 MiB and read back to itself with no
|
||
removal, or the cleaning answers `cleaning_unstable`. A file already in that
|
||
form keeps its bytes and its sha256: the equine drawing
|
||
(`0ea5202f…`, the DEV object) is one. Stored drawings are never repaired
|
||
afterwards (LRN-055): the verdict and `PreviewSheet` refuse a drawing read
|
||
without removal but not in the stored form (`svg_not_canonical`,
|
||
`verification.integrity.svg_not_canonical`), so bytes uploaded by another
|
||
path than the page's cleaning never reach a round. No stored object is
|
||
rewritten and no published version changes: a drawing is content-addressed,
|
||
so a new form is a new sha256, a new row and a new object.
|
||
- Local references (owner decision 2026-10-29): every `href="#id"`,
|
||
`xlink:href="#id"` and `url(#id)` must name an id the drawing itself
|
||
defines, and a `url(` is a local reference only in its strict spelling
|
||
(CSS whitespace, an optional quote, `#`, an id in the reference grammar,
|
||
the same quote, CSS whitespace, `)`): `url(#%61)`, a tab, a space or an
|
||
unbalanced quote inside, an empty or non-ASCII id are active content and
|
||
refuse the file, since a browser normalises them (security review of the
|
||
checkpoint); a reference to an absent id is a hard rejection
|
||
(`dangling_reference`) for the reader of stored drawings, the cleaning
|
||
(after active content is classified, so a hostile file is still named as
|
||
such), the verdict and the preview. Valid internal references keep working.
|
||
- Reserved ids (owner brief 2026-10-30): the PDF view keeps the drawing's ids
|
||
and the engine writes its halo filter `osteo-halo` next to them, so a drawing
|
||
holding that id, on any element and in any letter case, is a hard rejection
|
||
(`reserved_id`) for the same readers and for the PDF snapshot gate; both
|
||
composers refuse such a tree. Exact names only: the historical drawings keep
|
||
`osteo-overlays` (RUST.md §12.9).
|
||
- Root visibility (owner brief 2026-10-30): the marker layer is the root's last
|
||
child, so a root `visibility` other than `visible` (any letter case, CSS-wide
|
||
keywords and unreadable values included) is a hard rejection
|
||
(`root_visibility`) for the same readers and the PDF snapshot gate; a root
|
||
`style` or `class` and `<style>` elements are already removed, and `opacity`
|
||
or `display` on the root act on the drawing and the markers alike
|
||
(RUST.md §12.10).
|
||
- Colours (owner decision 2026-10-29): presentation attributes and `style`
|
||
keep the strict colour functions cairo writes, lowercase `rgb(` with three
|
||
and `rgba(` with four components, all bare numbers up to 255 or all
|
||
percentages up to 100, an alpha up to 1 or 100 %, commas, CSS whitespace,
|
||
nothing glued before the name (a non-ASCII letter included) and nothing
|
||
after the `)` but the end, a space, `;`, `,` or `!`. Every other function (`url(` outside the
|
||
document, `expression(`, `var(`, `hsl(`, an escaped name, an uppercase
|
||
name…) is removed or refused as before; scripts and active CSS stay
|
||
refused.
|
||
- The server control stays mandatory: the verdict reads every reachable
|
||
drawing again and refuses any removal (§6.4).
|
||
|
||
### 9.3 Upload
|
||
|
||
1. `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 with
|
||
`uploaded_at` null; refused on the historical sheet.
|
||
2. If the object `<sha256>.svg` does not exist yet, the page uploads it there.
|
||
An INSERT policy on `storage.objects` allows 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.
|
||
3. `confirm_sheet_asset_upload(asset_id)` (editor with `aal2`, or the service
|
||
role for the operator tool): checks in `storage.objects` that the object
|
||
exists and that its size equals the row's, then sets `uploaded_at` (F7).
|
||
The editor's `PreviewSheet` then checks the sha256 at every load (§10), so
|
||
bytes that do not match their key show `drawing_hash_mismatch` before any
|
||
submission.
|
||
4. The verification of each submitted revision re-reads every reachable
|
||
drawing in place: size, sha256, read without removal, in the stored form
|
||
(§9.2).
|
||
5. 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.
|
||
6. Closed codes shown to the editor: `size_mismatch`, `hash_mismatch`,
|
||
`svg_rejected` (with the reader's reason, `dangling_reference`,
|
||
`reserved_id` and `root_visibility` included),
|
||
`svg_active_content`, `svg_not_canonical`, `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 that object, not only on an
|
||
empty upgrade; for M4 and M5 (V1-2.1) the owner accepted a Git fixture with
|
||
the same sha256 in place of a copy of the DEV object, which leaves the live
|
||
object's integrity undemonstrated (§12.3, §17.3).
|
||
- `pnpm assets:upload` stays the seed tool of local and sandbox stacks. With
|
||
the service role's table privileges revoked (F12), the same step gives the
|
||
tool a narrow read RPC for its planning. `pnpm e2e:sheet-assets` runs on the
|
||
sandbox stack (`pnpm db:sandbox sheet-assets-e2e`, owner brief 2026-11-02);
|
||
V1-2.1 did not run it, the tool's switch to that RPC is covered by its
|
||
stub-server tests and pgTAP 006, and the sandbox run closes V1-2.3.
|
||
- 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_with` records 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
|
||
and deprecated: owner decision 2026-11-02, BDR-098, M7; a draft has none)
|
||
and the drawings (asset id, sha256, size). Published and deprecated
|
||
versions answer under the reader predicate (§5.3), drafts under a
|
||
capability with `aal2`; 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 through `read_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. For a draft, a caps excess and a referenced drawing that was not
|
||
given are reported in the state, never a load failure; `caps` and
|
||
`drawing_missing` refuse a published or deprecated version only (owner
|
||
decision 2026-10-29). A hash mismatch and an unreadable document refuse every
|
||
mode, and so do the handle's own resource bounds (V1-2.2): a drawing over
|
||
2 MiB (`caps: drawing_bytes`) and more than 16 drawings held
|
||
(`caps: drawings`).
|
||
- Isolation of views (owner decision 2026-10-29): `view.canvas`, on
|
||
`PreviewSheet` as on `LoadedSheet`, writes `fv.<view id>.` in front of every
|
||
`id` of the drawing and of every local reference to it (`href`,
|
||
`xlink:href`, `url(#…)`) in the composed tree. Stable ids hold no `.`, so a
|
||
view's scope is never the start of another's and no page id starts with
|
||
`fv.`: once several views are inlined in one page, a reference resolves
|
||
only inside its own view, never in another view or in the page. The
|
||
transformation runs at composition only: stored bytes, their sha256, the
|
||
published versions, the archive snapshot and the PDF views (each rasterised
|
||
as a document of its own) keep the drawing's ids. Composition is
|
||
deterministic and applied once per call; the composer refuses a canvas
|
||
that would keep a reference outside its scope (`unscoped_reference`).
|
||
The scope is unique within one document only: a page that inlines
|
||
canvases of two documents at once (two versions or two sheets side by
|
||
side) adds a per-document prefix first. A drawing outside the stored form
|
||
(§9.2) shows `rejected` with `not_canonical` and draws nothing, as the
|
||
verdict refuses it.
|
||
- `LoadedSheet` (the report editor's sheet) keeps its mandatory migration map;
|
||
`archive::SheetStatus` is 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 |
|
||
|
||
Navigation (owner, 2026-11-02, BDR-094): « Fiches anatomiques » shows only to
|
||
catalogue readers (§5.3). One « Administration » entry shows to holders of a
|
||
capability and to the owner role; inside it, each account sees only the
|
||
entries and actions its capabilities allow. A reviewer-only account keeps the
|
||
entry to reach its rounds (R1) and sees no « Nouvelle fiche », « Créer une
|
||
copie de travail », « Accès et habilitations », species creation or
|
||
activation. Visibility never replaces the server checks.
|
||
|
||
### 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. Validated on 2026-11-02
|
||
(§17.9): `docs/design/v1-2-4/` is the reference for V1-2.5 to 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) |
|
||
| F17 | `service_role` keeps the default table privileges on `profile_roles` and `profiles` (the revokes name `public, anon, authenticated`), so a service-key session can write platform roles directly; `grant_platform_role` and `revoke_platform_role` are also granted to `service_role` without use | `20261008100200` l.247-248 and the revoke on `profile_roles`; `20261008100100` l.100 | confirmed by reading; effective grants checked on the sandbox in V1-2.1 | M4 (`REVOKE ALL` from `service_role` on both tables, `EXECUTE` revoked on the two RPCs) |
|
||
| F18 | `withdraw_platform_role` counts active owners without a lock: two concurrent revocations of two owners can both pass the guard and leave none | `20261008100200` l.143-181 (count l.165-169) | confirmed by reading | M4 (advisory lock in both RPCs and the private functions, count on active profiles, two-session tests) |
|
||
| F19 | `grant_platform_role` and `revoke_platform_role` do not check the assurance level (AR-1); a grant does not check that the target holds a verified factor; the private write functions trust a null actor from any session | `20261008100200` l.108-181, l.189-238 | confirmed by reading | M4 (`has_mfa()` as the second check, §5.7) |
|
||
|
||
### 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 (binary jsonb, uncompressed when the row is written) | storage structure | replaced in M5 by `octet_length(content::text) <= 2 097 152` (owner decision 2026-10-28, §17.3); creation, save and working copy check the same measure first and answer `document.too_large` |
|
||
| document species = sheet species | trigger (l.176) | relational | kept |
|
||
| `view.asset.unknown`: every drawing id registered for the sheet | `sheet_document_unknown_assets` | relational | kept at submission and publication |
|
||
| `view.main.count`, `view.parent.missing`, `view.unreachable`, `view.asset.missing` | `sheet_document_view_issues` | business rule, duplicate of the core | removed in M5 |
|
||
| `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 |
|
||
| fixed categories at save: no role carried by two categories, a category carrying a role keeps that role's fixed FR and EN names, no role of the stored draft lost; a document without roles saves when the stored draft has none (owner 2026-11-05, §17.12) | `save_sheet_draft` | declared defensive check | planned at V1-2.6 U6, not built |
|
||
| fixed model at approval and publication: each of `bone`, `joint`, `vertebra` carried by exactly one category with its fixed FR and EN names, `navigation` by at most one with its fixed names (owner 2026-11-05, §17.12) | `private.sheet_fixed_categories_ok(content)` (name provisional), called by `decide_sheet_review` and `publish_sheet_version` | declared defensive check | planned at V1-2.6 U6, not built |
|
||
|
||
- The status check is the first declared mirror (the fixed-category checks
|
||
below are the others, from V1-2.6 U6): a
|
||
structural walk over `annotations[*]`, `finding_zones[*].categories[*]` and
|
||
every `children[*]` below them, refusing an element whose `review_status`
|
||
is absent, `to_confirm` or `inherited`. 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. Besides it, only the two fixed-category checks
|
||
below are mirrored (O22 amended 2026-11-05).
|
||
- The fixed-category checks (owner 2026-11-05, §17.12; planned at U6, not
|
||
built) are declared mirrors of the category model's invariants only: the
|
||
fixed roles, their uniqueness, their presence and their fixed names, read
|
||
from `categories[*].role` and `categories[*].name`. At save they stop a
|
||
direct save, an older tab or « Garder ma version » from stripping,
|
||
duplicating or renaming the fixed categories of a draft; at approval and
|
||
publication they keep a worker defect from making a draft outside the model
|
||
official. The core keeps the authority and the same rule with its messages
|
||
(the verdict issues `category.fixed.*`, the editor's refusals and repairs);
|
||
no other part of the core's validation is mirrored (no annotation, view,
|
||
finding or reference rule). A draft that carries no role still saves when
|
||
the stored draft carries none, so no draft saved before U6 is locked, and every state a save can reach stays
|
||
repairable in the editor. Closed codes and pgTAP allowed and denied cases
|
||
come with U6.
|
||
- 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.md` no longer asks to add a rule « on both
|
||
sides »: new rules go to the core only.
|
||
|
||
Measure of the document cap (owner decision 2026-10-28, §17.3). The cap is
|
||
2 097 152 bytes (2 MiB), unchanged. What is measured is the UTF-8 byte length
|
||
of the document's JSON text in one form, the same for every layer:
|
||
|
||
- The form is the text PostgreSQL prints for the stored `jsonb`
|
||
(`content::text`): object keys in `jsonb` order (shorter first, then by
|
||
bytes), a repeated key kept once (the last), `": "` after each key and
|
||
`", "` between members and elements, strings escaped as JSON with
|
||
non-ASCII characters left as UTF-8, numbers as PostgreSQL's `numeric`
|
||
prints them (plain digits, never an exponent).
|
||
- PostgreSQL: `octet_length(content::text) <= 2097152`, in the table CHECK
|
||
and, first, in `private.check_document_structure` (creation, save, working
|
||
copy), which answers `document.too_large`. The binary size of the `jsonb`
|
||
(`pg_column_size`, larger than the text for a document of many small
|
||
values) is never the measure.
|
||
- TypeScript and Rust: no client-side size check exists in V1-2.1. When the
|
||
core reports the size (V1-2.2, read by the validation panel of V1-2.6), it
|
||
computes this same form, never the length of `JSON.stringify` or of a
|
||
compact `serde_json` output: the compact text is shorter by one byte per
|
||
object member and per separator, so a compact measure under the cap is
|
||
necessary, not sufficient. pgTAP 017 holds the vectors (cap − 1, cap,
|
||
cap + 1, multi-byte and astral characters, a dense document, numbers that
|
||
JavaScript prints with an exponent); the core's size tests of V1-2.2 reuse
|
||
them.
|
||
- The numbers' printed lengths are summed first (one linear walk, each number
|
||
added in turn), and the whole text is built only once they fit the cap: a
|
||
small payload of
|
||
numbers with huge exponents (`1e131071` prints 131 072 digits) answers
|
||
`document.too_large`, never an out-of-memory error.
|
||
|
||
### 12.3 Migrations (names provisional)
|
||
|
||
| 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); AR-1 B on the platform role RPCs and the private write functions (F19, §5.7), F17, F18; 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; the content-size CHECK replaced by the text measure (`octet_length(content::text)`, §12.2) | new columns take their defaults on the equine v1 row (`revision` 0, empty author set); its document, status, number and assets unchanged; the new size CHECK is validated against the existing rows when M5 is applied (the equine document measures 184 105 bytes as `content::text`, measured on the sandbox); 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, with the retry delay (hidden `not_before` column on the round, `private.sheet_verification_retry_delay`: owner decision 2026-11-01, replaces « without backoff ») and the retry by cause (definitive codes close at the first occurrence, `private.sheet_worker_final_codes`); written as `20261101100000_sheet_verification_jobs.sql`, pgTAP `021`, rehearsed on the sandbox from the state before M4 (M4 to M6 in one `migration up`) and from the state before M6 | none |
|
||
| M7 `sheet_admin_reads` | V1-2.5 | read RPCs of the admin space (owner decision 2026-11-02, BDR-097): the official sheet list with its badges (historical, working copy), statuses and round counts, and one sheet's overview (versions, rounds); `get_sheet_version` redefined to return the fingerprint of deprecated versions too (BDR-098); the admin reads for capability holders at `aal2` only (`caller_can_see_official_sheet`); no new write path (it redefines two existing write RPCs), no new grant, no policy change; the one rule change is the species sort order: `create_species` and `update_inactive_species` are redefined to refuse an order outside 0..9 999 with `invalid_input` (null keeps today's meaning, owner 2026-11-02), `security definer`, `search_path = ''` and their privileges restated; pgTAP allowed and denied cases | none |
|
||
| M8 `sheet_draft_last_save` | V1-2.6 | read migration (owner decision 2026-11-03, sandbox only): `get_official_sheet_admin` redefined to answer `draft_last_save` = `{revision, saved_at, saved_by}` (the account that saved the draft's current revision, from the newest `anatomical_sheet_version.saved` audit row of that revision), null when no save wrote it; the list and the summary helper untouched; no write path, no new grant, no policy change, privileges restated as M7; pgTAP allowed and denied cases | 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).
|
||
|
||
M4 and M5 (V1-2.1, owner decision 2026-10-28, §17.3): the upgrade rehearsal
|
||
uses a representative Git fixture in place of a copy of the DEV object: the
|
||
committed file `supabase/seed/anatomical-sheets/equine/draft/assets/horse.svg`,
|
||
whose sha256 equals the one referenced by the DEV metadata (the asset row of
|
||
the historical sheet). Its bytes, its Storage metadata and its relations
|
||
(asset row, sheet, version) are checked before and after the migration. No
|
||
file was read from the real Storage of DEV, so the current integrity of that
|
||
DEV object is not demonstrated by this rehearsal; it is checked when the
|
||
owner applies M4 to M6 on DEV (§16.11). The substitution is accepted for
|
||
V1-2.1 only. BLK-008 stays the rule:
|
||
no document schema bump in V1-2; verdicts, groups, authors and keys all live
|
||
outside the document.
|
||
|
||
---
|
||
|
||
## 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 | AR-1 B: `aal2` on every grant and revocation of a platform role, checked in the RPCs before any role check and in the private write functions for a non-null actor; `service_role` has no table privilege and no `EXECUTE` on them; owner count race closed; first factor enrolled before the owner role is assigned (§5.7) |
|
||
| 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 and of references to ids a drawing does not define, one stored form for every uploaded drawing, verification in the worker's sandboxed child, reading at every load and at export; the page never inserts stored bytes (core-composed tree only), and each composed canvas scopes its ids to its view (§10); 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 (UTF-8 bytes of its JSON text, §12.2), drawing 2 MiB, comment 4 000 characters, change note 1 000, verdict bounded; per-actor write budget as V1-1 D15 (thresholds in V1-2.1) |
|
||
|
||
Residual risks:
|
||
|
||
- the token's `aal` claim outlives a factor removal for up to one token
|
||
lifetime unless the session check of §5.7.8 is confirmed on the pinned
|
||
image; a stolen `aal2` session can also change platform roles and replace
|
||
factors (same residual as below). The catalogue RPCs, the V1-2.6 editor's
|
||
saves and submissions included, check the token's `aal2` claim, not the
|
||
live session, until that token expires. Not fixed in V1-2.6 (no
|
||
authentication change in that step); closing it, or confirming the
|
||
session check of §5.7.8, is a production prerequisite (owner 2026-11-03);
|
||
- a role holder who removes the last factor from `aal2` keeps the role in
|
||
the first-factor case (§5.7.3);
|
||
- refused escalation attempts leave no audit row (the transaction raises);
|
||
- staff reads gated by `is_platform_admin` stay at `aal1` (§5.7.9);
|
||
- 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, except on DEV today, where it is the public demo
|
||
key and the JWT secret is the CLI default (`ENVIRONMENTS.md` §3.6), so
|
||
AR-1 B is forgeable on DEV until that hardening (§5.7.2 step 0);
|
||
- 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 `aal2` session stays usable until it ends, since no freshness
|
||
window or session limit is set (§5.6);
|
||
- TOTP code reuse within its window (measured, `IDENTITY.md` §4.1): GoTrue
|
||
accepts a used code again, from the same or another session of the account,
|
||
in its own 30 s step and the next, and refuses it from the step after; no
|
||
mitigation is added, the span is 30 to 60 s;
|
||
- production prerequisite: the lost-factor recovery is not rehearsed and no
|
||
recovery code exists (`IDENTITY.md` §4.2); the runbook of §5.7.7 is rehearsed
|
||
on the sandbox and written before any production use of MFA-protected rights;
|
||
- production prerequisite (owner 2026-11-03, recorded at V1-2.6, not fixed): the catalogue and sheet RPCs and the
|
||
Storage policies check the token's `aal2` claim (`private.has_mfa()`), not the live session; only the platform
|
||
role and rights RPCs use `private.has_aal2_session()`. A JWT issued at `aal2` therefore keeps passing them after
|
||
a factor is removed (or the session is downgraded) until it expires. A live-session check or a revocation
|
||
strategy compatible with Supabase / GoTrue is studied before production; V1-2.6 changes no authentication;
|
||
- 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).
|
||
|
||
### 13.1 Accepted risks of the verification worker (register, V1-2.3)
|
||
|
||
Owner decisions of 2026-11-02 (BDR-093): accepted for the sandbox scope, not
|
||
fixed, and no authorisation to deploy. Each line is re-examined before
|
||
`worker-verify` runs on DEV or verification reaches external users.
|
||
|
||
| Id | Severity | Scenario | Existing limits | Effect on attempts and resources | Re-examination |
|
||
|---|---|---|---|---|---|
|
||
| VR-1 | MEDIUM | A document whose verdict needs about 60 s of CPU, on a host where the child gets less than one full core (the VPS shares its cores with the Supabase stack; `--cpus 1` is a ceiling, not a guarantee), reaches the 90 s wall deadline before the 60 s CPU budget: the parent kills it, the end reads `Timeout`, reported `verification.worker.timeout`, a transient code. Reproduce: a document at the CPU budget on a loaded host. | child RLIMIT_AS 1 GiB, CPU 60 s (SIGXCPU, definitive), wall 90 s; one child at a time per worker; five attempts; delays 2, 5, 10, 20 s | up to five runs of about 90 s plus 37 s of delays, about 8 min of worker time for one round, instead of one run for a definitive close; other rounds wait behind it on a single worker; no effect on publication (the round closes `unavailable` at the limit) | before `worker-verify` on DEV or external users: measure the child's CPU time at the end (`wait4` rusage, an `unsafe` exception the owner deferred) or reserve a core for the worker |
|
||
| VR-2 | LOW | A frame header over 64 KiB (several hundred drawings named) is reported `resource_limit` instead of `caps` | definitive at first occurrence | one run | when the editor screens show worker codes (V1-2.7) |
|
||
| VR-3 | LOW | An object larger than the policy is passed without bytes: failures `[caps, drawing_missing]`, never `size_mismatch` | bucket limit 2 MiB prevents it in practice | none (verdict failed at once) | same |
|
||
| VR-4 | LOW | SIGABRT also covers a child panic and a host ENOMEM, both closed `resource_limit` | panic deterministic on a frozen input | one run; a host ENOMEM needs a resubmission | before DEV activation |
|
||
| VR-5 | LOW | A verdict bound to another round, sent with a valid token, answers `stale` and waits for the lease | only after a core or worker regression | up to five leases of 10 min before `lease_expired` closes it | before DEV activation |
|
||
|
||
---
|
||
|
||
## 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 `reviewed` were 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_confirm` are open doubts;
|
||
- the 620 `inherited` are 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 » in a tooltip if needed, 2026-11-02),
|
||
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/` or `draft/` is regenerated, and `pnpm
|
||
r5:import-equine --check` keeps 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 `active` working 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_id` set;
|
||
- registers the source drawings for the new sheet (same sha256, size and file
|
||
name, `uploaded_at` set 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_created` with 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 `inherited` are requalified `to_confirm`;
|
||
- the 11 level B changes missing from `REVIEW-REPORT.md` are 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_confirm` need 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 `published` refused 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 by `create_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 (for M4 and M5, with the Git fixture of §12.3);
|
||
- document size in the measure of §12.2: cap − 1, cap and cap + 1 bytes,
|
||
multi-byte and astral characters, a dense document within the cap as
|
||
text but over it as binary `jsonb` (accepted), refusals answering
|
||
`document.too_large`;
|
||
- an owner granting itself `sheet_reviewer`, approving a version written
|
||
by another author, refused on its own version, and an author's approval
|
||
refused at publication (§5.2, §5.5).
|
||
- AR-1 B (SQL, per §5.7; PGlite sets the `aal` claim through the JWT
|
||
settings, the `auth.sessions` check needs the real image):
|
||
- matrix: no role, owner, admin, moderator, support, each at `aal1` and
|
||
`aal2`, plus a deactivated account, on grant and on revoke, for each of
|
||
the four roles, on self and on another account; expected: `aal1` always
|
||
refused with `mfa_required`, `aal2` allowed only where
|
||
`can_manage_platform_role` allows (owner any role, admin moderator and
|
||
support), a moderator or support at `aal2` refused;
|
||
- regression of the chain: an owner at `aal1` calls the grant RPC directly
|
||
for an attacker-controlled account; refused, no `profile_roles` row, no
|
||
audit row, no capability grantable to it; same for revoking the real
|
||
owner and for a demotion;
|
||
- the private functions refused for a non-null actor at `aal1`, the null
|
||
actor path still working for the seed; `service_role` refused on the RPCs
|
||
and on both tables (F17); the last-owner guard under two concurrent
|
||
revocations (F18);
|
||
- no partial write on refusal; audit row on success with no secret in it;
|
||
- a role revoked then a call with the old token: refused at the next call;
|
||
- an account with no role, enrolling a factor, gains nothing; a first owner
|
||
initialised on a fresh stack in the order of §5.7.1;
|
||
- grant to a target without a verified factor refused; a null actor from
|
||
an API session and from `service_role` refused in the private functions;
|
||
`aal` claim absent, null or wrongly cased refused; mutual owner
|
||
revocation and revoke against grant in two sessions;
|
||
- fixtures that call the role RPCs (pgTAP 004 and others, the sandbox
|
||
`workspaces.sandbox.ts` seed owner at `aal1`) moved to `aal2` claims or to
|
||
the operator path; the PGlite shim gains stand-ins for `auth.sessions` and
|
||
`auth.mfa_factors` with columns checked against the pinned image;
|
||
- V1-1 regression: workspaces, clients, animals, relations, sign-in and a
|
||
practitioner without role unchanged; pgTAP 001 to 014 green with the
|
||
existing identity fixtures (adapted only where they assert the old
|
||
behaviour of the role RPCs).
|
||
- MFA on the sandbox stack (real GoTrue): first enrolment at `aal1`, verify,
|
||
`aal2`; second factor from `aal1` refused; removal of a verified factor
|
||
from `aal1` refused; removal from `aal2` and the session consequences;
|
||
password reset does not reach `aal2`; refresh keeps `aal2`; revoked session
|
||
and old token; recovery rehearsal of §5.7.7. Expectations are what the
|
||
pinned image really does; any gap with §5.7.3 is written up and decided by
|
||
the owner.
|
||
- 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;
|
||
`PreviewSheet` checks (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; dangling references refused, ids scoped per view,
|
||
the stored form required, removals with dependents refused; 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; the avatar suite
|
||
unchanged in outcome on the sandbox (`pnpm db:sandbox avatar-e2e`, owner
|
||
decision 2026-11-01: `pnpm e2e:avatar` is now its alias, the DEV script removed); `pnpm e2e:sheet-assets` now runs on the sandbox
|
||
(`pnpm db:sandbox sheet-assets-e2e`, gateway on 127.0.0.1:57800, refuses DEV).
|
||
- 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 `aal1` enrolment of a second
|
||
factor.
|
||
- Browser (`e2e:shell` on 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 (Node `crypto` HMAC, no
|
||
dependency, built in V1-2.1 for the real-GoTrue acceptance of §16.2 and
|
||
reused in 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), 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
|
||
(B, BDR-083); 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.ts` with
|
||
closed failure kinds; the client gate deleted.
|
||
- Dependencies: V1-2.0 go; AR-1 B decided (BDR-083).
|
||
- 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 `aal2` except the reader RPCs.
|
||
- Application changes: `packages/supabase` accessors 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:all` green.
|
||
- Acceptance, upgrade: a stack upgraded from the M3 state with the Git
|
||
fixture of §12.3 (sha256 equal to the DEV metadata's) keeps the object's
|
||
bytes, metadata and relations; this does not show the integrity of the
|
||
live DEV object, which no V1-2.1 run read.
|
||
- Acceptance, AR-1 B: the tests of §15 for §5.7 pass on the sandbox; a
|
||
stack upgraded from the DEV state with an owner holding two verified
|
||
factors keeps working at `aal2` and is refused at `aal1`; the same upgrade
|
||
with an owner holding none stays usable at `aal1` for everything but role
|
||
and rights management; the census lists no other write path to
|
||
`profile_roles`.
|
||
- Rollback: branch revert; sandbox rebuilt.
|
||
- Checkpoint: gates only (owner at V1-2.3).
|
||
- State 2026-10-29: VERIFIED by the owner at `ac71c5b` (brief « Autorisation de
|
||
démarrer V1-2.2 »); M4 and M5 unchanged since.
|
||
|
||
### 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 `PreviewSheet` as the catalogue, preview and editor handle, with
|
||
`view.canvas` on it; then `sheet.edit` primitives 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 `worker` profile, 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:avatar`
|
||
unchanged; `pnpm e2e:sheet-assets` on the sandbox (`pnpm db:sandbox
|
||
sheet-assets-e2e`).
|
||
- 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).
|
||
- State 2026-11-01: built and tested on the sandbox (RUST.md §13); DEV untouched.
|
||
|
||
### 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.
|
||
- State 2026-11-02: GRAPHICAL APPROVED by the owner (BDR-096, §17.9): the
|
||
twelve boards and the complementary page « Accès non autorisé » in
|
||
`docs/design/v1-2-4/`, with its README line.
|
||
|
||
### 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 (from V1-2.1).
|
||
« Créer une copie de travail » on the Administration page and the
|
||
historical sheet's overview (W1 start, owner decision 2026-11-02, BDR-097):
|
||
the copy lands on its overview, the editor link arrives with V1-2.6; a new
|
||
sheet (A1) also lands on its overview until V1-2.6. SQL changes: M7 admin
|
||
reads only (§12.3, owner decision 2026-11-02, BDR-097; was « none »). Scope split: M4 (V1-2.1) holds every server control of AR-1 B; this
|
||
step holds the frontend journey only (enrolment, step-up, factor list, the
|
||
`mfa_required` message in FR and EN).
|
||
- Tests: unit; `e2e:shell` A0, A1, S1, P1; access per right; MFA required;
|
||
refresh keeps `aal2`; no `aal1` enrolment of a second factor; axe; 320 to
|
||
430 px for the catalogue, 375 px for admin screens; FR/EN.
|
||
- Acceptance: the owner enrols two factors from Mon compte, reaches `aal2`,
|
||
and only then manages platform roles and rights (an `aal1` attempt is
|
||
refused in the UI and in SQL); 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).
|
||
- State 2026-11-02: built and tested on the sandbox, slices A to J of the step
|
||
plan: A GoTrue MFA behaviour measured (`IDENTITY.md` §4.1), B M7
|
||
`sheet_admin_reads` (with BDR-098), C core op `sheet.empty`, D the
|
||
`packages/supabase` accessors (MFA, species, rights, admin and catalogue
|
||
reads), E navigation, `RequireCatalog`, `RequireAdmin` and « Accès non
|
||
autorisé », F TOTP factors in Mon compte with the step-up, G administration
|
||
page, species and rights, H sheet list, creation, overview and working copy,
|
||
I catalogue list, sheet and version pages, J the `e2e:shell` journeys.
|
||
pgTAP 1941, unit 864, `e2e:shell` 108 passed (6 skipped by design). DEV
|
||
untouched; the checkpoint gates are pending.
|
||
|
||
### 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: M8 `sheet_draft_last_save`, a read
|
||
migration for the conflict dialog (§12.3, owner decision 2026-11-03; was « none »).
|
||
- Tests: `e2e:shell` A2, A3, A4 with a conflict and a local recovery;
|
||
keyboard path through numeric fields (amended 2026-11-05, U0: from V1-2.6
|
||
U2 through the handles, from U4 through the crop rectangle, §8.2 as
|
||
amended); 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 reaches `verifying`.
|
||
- Rollback: branch revert.
|
||
- Checkpoint: owner tries it.
|
||
- State 2026-11-04: built and tested on the sandbox, lots A to M of the step
|
||
plan (`.claude/tasks/plans/2026-11-03-v1-2-6-editor.md`, resume ledger
|
||
`2026-11-03-v1-2-6-execution.md`): A M8 `draft_last_save`, B drawing
|
||
accessors, C editable preview and edit operations, D store, undo and local
|
||
recovery, E route, modes and conflict, F to J the seven tabs and the
|
||
submission, K the `e2e:shell` journeys, L the owner trial commands
|
||
(`pnpm db:sandbox trial`) and `docs/development/V1-2-6_OWNER_TRIAL.md`.
|
||
One fresh sandbox in the order `test-db → e2e:shell → test`: pgTAP 1992,
|
||
`e2e:shell` 151 passed (49 skipped by design: editing needs 1 024 px),
|
||
`db:sandbox test` 105 passed (10 skipped); unit app 1085, supabase 159,
|
||
core-wasm 66 (after the owner's decisions of 2026-11-04, lots N and O);
|
||
`check:all` and `r5:import-equine --check` green on the final code. The
|
||
owner trial is served on the LAN address (`http://192.168.1.100:5193`, the
|
||
sandbox kept on loopback behind it); a free path outside a new frame blocks
|
||
the attachment (its point correction needs a core operation, proposed, not
|
||
built). Commit latency on the equine copy
|
||
under 61 ms (budget 500 ms). Only measured views are editable (owner
|
||
2026-11-04); the AAL2 residual of §13 stays open. DEV untouched; the owner
|
||
has not tried the editor yet.
|
||
- State 2026-11-05: the owner stopped the level-1 trials (decision T11):
|
||
level 1 is not declared validated as a whole, its residuals stay tracked in
|
||
`.claude/tasks/TODO.md`. The editor is redesigned on the validated boards of
|
||
`docs/design/v1-2-6` (§8.2 to §8.4 as amended, §17.12) in sub-steps U0 to
|
||
U8 of `docs/development/V1-2-6_UX_PLAN.md`, each started on its own owner
|
||
authorisation; U0 (contract and decisions, documents only) was authorised
|
||
on 2026-11-05. SQL changes planned for the redesign: one U6 migration (the
|
||
round withdrawal of §6.4, a core gate, a rules epoch, the fixed-category
|
||
checks of §12.2). The acceptance above is re-run on the redesigned editor at
|
||
U6 and U8, with the verification worker on the sandbox, up to a round
|
||
`open`.
|
||
|
||
### 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.
|
||
- Round lists (owner, 2026-11-02, BDR-095): `verification_failed` stays the
|
||
technical status. A list tells a content failure from a technical
|
||
unavailability only where the data establish it
|
||
(`anatomical_sheet_reviews.failure_outcome` = `failed` or `unavailable`;
|
||
the column is nullable and no CHECK ties it to the status); otherwise it
|
||
shows an exact generic label and never infers a cause. No migration for it.
|
||
- Tests: `e2e:shell` A5, 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 --check` with 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`, `IDENTITY` with 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 the `object_conflict` runbook; 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:
|
||
|
||
1. applying M4 to M6, after a backup and a sandbox rehearsal from the DEV
|
||
state; M4 is not applied before the preconditions of §5.7.2 (DEV hardening
|
||
of `ENVIRONMENTS.md` §3.6, seed owner password, role holders listed,
|
||
item 2's factors enrolled and verified), nor before the recovery of §5.7.7 is rehearsed; M4's checks take
|
||
effect when it is applied, with no flag that could be left open;
|
||
2. enrolling the owner's two TOTP factors (before item 1, §5.7.2) and the
|
||
first rights grants (after it);
|
||
3. 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;
|
||
4. creating, activating or renaming a species;
|
||
5. creating the equine working copy and applying the O18 corrections;
|
||
6. any submission, approval, publication, deprecation or archive;
|
||
7. any factor reset (§5.6, §5.7.7) and any `object_conflict` deletion (§9.3);
|
||
8. rerunning the equine seed;
|
||
9. uploading the equine drawing to DEV with the operator tool
|
||
`pnpm assets:upload` once M4 to M6 are applied (§9.5); `pnpm e2e:sheet-assets`
|
||
is sandbox-only and not part of this list.
|
||
|
||
### 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; the curves lot (§8.3 as amended, decision
|
||
T16); editing on a phone (§8.4 as amended); a multi-tab notice (decision T14,
|
||
a follow-up candidate). 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 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 at the time; the arbitration AR-1 then extended `aal2` to every platform role change (§17.2) | §5.6, §5.7 |
|
||
| 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; amended 2026-11-05: two declared fixed-category checks, at save and at approval and publication (§17.12) | §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 Arbitration AR-1: MFA on platform role changes (ratified, option B)
|
||
|
||
Finding (security challenge, §19.3, confirmed by reading
|
||
`20261008100200_platform_roles.sql`, the two RPCs): an owner could grant any
|
||
platform role, owner included, with no check of the assurance level. From a
|
||
stolen password-only owner session, an attacker grants a role to an account
|
||
of their own, which enrols its own factor, reaches `aal2` and grants itself
|
||
every catalogue capability; every `aal2` control of the catalogue was
|
||
bypassed. The chain is written out in §5.7.
|
||
|
||
Options put to the owner: A (`aal2` for `owner` and `admin` only), B (`aal2`
|
||
for every platform role), C (leave the RPCs and accept the residual).
|
||
|
||
Decision (owner, 2026-10-28, BDR-083): **B**. Every grant, revocation or
|
||
change of a platform role requires a valid `aal2` session checked on the
|
||
server, with no permanent exception. It complements O4 and leaves D1 to D9
|
||
and O1 to O23 unchanged (O1, O2 and O4 are applied, not amended: a role gives
|
||
no capability, `aal2` replaces no permission, §5.2, §5.5, §5.7). Where it
|
||
lands: rule, inventory, bootstrap, recovery and session rules in §5.7; M4 in
|
||
§12.3 (F17, F18, F19); tests in §15; acceptance in §16.2, §16.6; the order of
|
||
DEV operations in §16.11.
|
||
|
||
Reserves left to the owner, not decided here: `aal2` on the staff read
|
||
policies (§5.7.9).
|
||
|
||
### 17.3 V1-2.1 final decisions (owner, 2026-10-28)
|
||
|
||
Brief « V1-2.1 : décisions finales du propriétaire », on the corrections
|
||
checkpoint `2af61e7`:
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| M6 | Option A: the `grant.self_review` refusal is removed; an owner at `aal2` with a verified factor may grant itself `sheet_reviewer`. Kept: no author acknowledges or approves a round it authored, the check again at publication, the MFA and eligibility checks, no self-grant for an account that is not owner | §5.2, §5.5, M4 |
|
||
| M7 | The Git fixture is accepted for the V1-2.1 upgrade rehearsal (sha256 equal to the DEV metadata's; bytes, metadata and relations before and after); no DEV Storage read, so the live DEV object's integrity is not demonstrated | §12.3, §16.2 |
|
||
| Size | The SQL check follows the contract's measure, the UTF-8 bytes of the JSON text; the binary `jsonb` size is not the measure; the cap stays 2 MiB | §12.2, M5 |
|
||
|
||
### 17.4 V1-2.2 decisions (owner, 2026-10-29)
|
||
|
||
Asked before the code of V1-2.2, on the brief « Autorisation de démarrer V1-2.2 », then (last six rows) at the V1-2.2 checkpoint, brief « V1-2.2 : arbitrages du propriétaire et finalisation »:
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| Vector-tool exports | The owner supplies the editors' exports (Inkscape, Illustrator, Figma, Affinity) under `crates/core/tests/fixtures/svg/exports/owner/` (scope amended in §17.6); the cairo and ImageMagick exports of the development machine are committed meanwhile, tool and version in the file name | §9.2, §15 |
|
||
| Strict-parse code | `verification.integrity.document` (and `.base` for the base), as §6.5 files it; the 19 rule errors are `verification.validation.rules` | §6.5, §6.7 |
|
||
| Draft load | caps excess and missing drawings reported for a draft, refused for a published or deprecated version | §10 |
|
||
| SVG references | a local reference to an id the drawing does not define is refused (`dangling_reference`); the composed canvas scopes every id and reference to its view (`fv.<view>.`), at composition only, stored bytes and fingerprints untouched; implemented in V1-2.2, not deferred to V1-2.6; the PDF halo's id `osteo-halo` is reserved (`reserved_id`, owner brief 2026-10-30) | §9.2, §10 |
|
||
| SVG serialisation | one stored form for every uploaded drawing (declaration + core serialisation), « clean = original bytes » withdrawn; verdict and preview refuse another form (`verification.integrity.svg_not_canonical`); no stored object rewritten, the equine object already in that form | §6.5, §6.7, §9.2, §9.3 |
|
||
| cairo colours | strict numeric `rgb()` / `rgba()` kept in presentation attributes and `style`; every other function, external `url(`, `expression(`, scripts and active CSS still removed or refused | §9.2 |
|
||
| Edit commands | strict command validation confirmed; `remove` refused atomically (`has_dependents`) while another element names the element; descendants of a finding go with it; no cascade in level 1 | §8.1 |
|
||
| Inkscape exports | the Ubuntu archive package of Inkscape 1.4.3 unpacked in the session scratch folder (no install) produces real exports, committed with their generator; Illustrator and Figma stay owner-supplied (A6 scope final in §17.6) | §9.2, §15 |
|
||
| Module size | the shipped module drops wasm-bindgen's debug `name` section (`--remove-name-section`); the 600 000-byte cap and its test are kept | RUST.md §12 |
|
||
|
||
### 17.5 V1-2.2 finalisation (owner, 2026-10-30)
|
||
|
||
Brief « V1-2.2 : finalisation et intégration A6 Figma », after the final independent review of `05de816`:
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| Editor exports required for A6 | Inkscape (covered, §17.4), Figma (required: the owner's two raw exports `owner/figma-web-20261030-{default,ids}.svg`) and Illustrator (required: the real Adobe Illustrator; VectorCraft or any look-alike is not equivalent). Affinity is optional. Superseded by §17.6: Illustrator is optional too | §9.2, §15 |
|
||
| Mask and clip units | `maskUnits`, `maskContentUnits` and `clipPathUnits` kept with the keywords `userSpaceOnUse` and `objectBoundingBox` only, any other value removed: removing Figma's `maskUnits="userSpaceOnUse"` re-read the mask region in bounding-box units and cut the drawing's edge | §9.2 |
|
||
| Glued `url(` | a `url(` glued to a longer name (`xurl(#a)`) is removed from any attribute, not only from presentation attributes and `style`, so the reader, the cleaning, the verdict, the preview, the canvas and the PDF view accept the same drawings | §9.2, §10 |
|
||
| Document instances | the per-document prefix (§10) stays a requirement before any page draws two documents at once | §10 |
|
||
|
||
### 17.6 V1-2.2 final arbitration (owner, 2026-10-30)
|
||
|
||
Brief « V1-2.2 : arbitrage définitif A6 et correction visibility », on `81f7639`:
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| A6 tested perimeter | Figma (two raw exports), Inkscape 1.4.3, cairo 1.18.4 and ImageMagick 7.1.2-18, all real exports read by the suite. Adobe Illustrator and Affinity are optional: never declared compatible or validated without a real export; their absence does not block V1-2.2. The `owner/` folder and its procedure stay for a later test | §9.2, §15 |
|
||
| Root visibility | a drawing whose root carries a `visibility` other than `visible` is a hard rejection (`root_visibility`): the marker layer, appended as the root's last child, inherits it while the drawing's children can set `visible` back. Refused by the reader before verification or publication, by the cleaning, the verdict, the preview, the canvas and the PDF snapshot gate; both composers refuse such a root | §9.2, §10 |
|
||
|
||
### 17.7 V1-2.2 closure (owner, 2026-11-01)
|
||
|
||
Briefs « V1-2.2 : décisions et poursuite des corrections », « fermeture du dernier MEDIUM » and
|
||
« Validation définitive V1-2.2 » (BDR-091, BDR-092). V1-2.2 is VERIFIED; the code state is `c73415a`.
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| Visible size | every annotation in frame shows at least 4 CSS px on the 320 × 568 preview; codes `annotation.geometry.too_small`, `verification.validation.marker_too_small` | §6.7, RUST.md §12.13 |
|
||
| Canvas order | « the visible wins » on the editor canvas only; the PDF view keeps the document order and its bytes | ANNOTATION-RENDERING |
|
||
| Zone interior | a zone or trigger drawn as a polygon or a path must fill a disc of 4 px diameter at 320 × 568, nonzero rule, stroke never counted, conservative measure with compute caps, refused in doubt; codes `annotation.geometry.interior_too_small`, `verification.validation.marker_interior_too_small` approved; the equine sheet accepted unchanged | §6.7, RUST.md §12.14 |
|
||
| Accepted LOWs, still tracked | fully overlapping marker discs (human review finds them before publication; no claim that each marker stays selectable); arc rotation sub-pixel error; an arc tangent to the frame refused; the `f32` arc margin a bounded estimate; verification cost of an all-arc sheet (about 1.8 s natively); relative path commands accumulated in `f32`. Not fixed, never declared fixed; the duration of complex sheets is watched during the editor validations on real devices | RUST.md §12.13, §12.14, TODO |
|
||
| Chromium touch | taps up to about 10 px around a point's disc went to the point in the Chromium touch bench, not under WebKit: an observation (LRN-108), never a basis of the selection contract | RUST.md §12.14 |
|
||
|
||
### 17.8 V1-2.4 maquettes, decisions so far (owner, 2026-11-02)
|
||
|
||
Briefs « corrections G1/G2 et préparation de la validation propriétaire », « validation de la
|
||
décision UX n° 3 » (BDR-094) and « dernières corrections graphiques » (after an external review of the
|
||
boards), « arbitrages propriétaire et préparation de validation finale » (BDR-095). The maquettes were a
|
||
proposal until §17.9: the owner approved them on 2026-11-02 and settled there L20 EN, L32 EN and the
|
||
French `object_conflict` message, which this table lists as open.
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| G1, G2 | corrections validated: no warning the core cannot raise on board 06, « Mark as reviewed » left to arbitrate at the time, ratified since (L31), fingerprint and `verdict_refused` messages true to the code; conformance check 8/8 acknowledged | `docs/design/v1-2-4/REVUE.md` |
|
||
| UX decisions | items 2 to 11 of the checkpoint list ratified, then item 4 withdrawn and item 6 settled (next rows); item 1 (labels) open | contract `2026-11-02-v1-2-4-maquettes.md` |
|
||
| Catalogue search | by sheet name only, « Rechercher une fiche »; no search by zone; replaces the zone search ratified as item 4 (BDR-095) | board 01 |
|
||
| Verification outcomes | distinct titles: `failed` « Vérification échouée » / « Verification failed », `unavailable` « Vérification indisponible » / « Verification unavailable »; each keeps its explanation and exits (BDR-095). §3 unchanged: the round status `verification_failed` keeps « vérification échouée »; lists follow §16.8 (cause shown only when `failure_outcome` establishes it) | board 06 |
|
||
| Published sheet on a phone, draft read-only below 1 024 px | the whole drawing is visible at opening (framing fitted to the screen), zoom and pan afterwards; the drawing itself is never modified | boards 03, 05 |
|
||
| Narrow-screen notice | names the 1 024 px minimum width, never a kind of device | board 05 |
|
||
| « Accès non autorisé » page | drawn on a complementary board, outside the twelve; button « Retour au tableau de bord » / « Back to dashboard » to `/app` ratified, EN title and explanation still proposals (L32) | `complement-acces-non-autorise.png` |
|
||
| FR/EN labels (owner, brief « arbitrages propriétaire et préparation de validation finale ») | 24 wordings common to both reviews ratified after a check against this contract and the code (L30 is a note, not a label); owner arbitrations L2, L3, L14 (« Access and permissions » on the card; §3 « Capability » unchanged), L15 (title), L20 (FR), L32 (button), `size_mismatch`, `marker_too_small`, `marker_interior_too_small`; still open: L15 second sentence, L20 EN, L32 EN title and explanation, `object_conflict` and the other closed-code messages | `docs/design/v1-2-4/REVUE.md`, board 12 |
|
||
| Catalogue access (item 3, O21) | entry hidden without the right, « Accès non autorisé » on a direct URL, signed out → login, server checks unchanged | §5.3 |
|
||
| Administration for a reviewer-only account | entry kept to reach its rounds, only the entries and actions its capability allows | §11.1 |
|
||
| `verdict_refused` exit | « reported to the operator » not implemented: logged and audited, no notification, none planned | §6.5 |
|
||
|
||
### 17.9 V1-2.4 graphic approval (owner, 2026-11-02)
|
||
|
||
Brief « Validation propriétaire V1-2.4 » (BDR-096), after the owner examined the archive
|
||
`faunosteo-v1-2-4-maquettes-arbitrages-3.zip` (the files of `docs/design/v1-2-4/` at `74aa8f6`, SHA-256 in
|
||
its `REVUE.md`). **V1-2.4 GRAPHICAL APPROVED.** This record changes no board, no source and no rule.
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| Approval | the twelve boards `01` to `12` and the complementary page « Accès non autorisé » are approved; they are the design reference of V1-2.5 to V1-2.7 (§11.3); a redesign needs a demonstrated defect or a new owner decision | `docs/design/README.md`, `docs/design/v1-2-4/` |
|
||
| `object_conflict` | FR « Le contenu du fichier de l'illustration ne correspond pas à son empreinte SHA-256 enregistrée. »; EN ratified 2026-11-02 (§17.11); board 12 keeps the earlier proposal | §9.3, board 12 |
|
||
| L14 | « Access and permissions » in the interface; `capability` stays a technical term | board 10 |
|
||
| L20 | « Corriger le brouillon » / « Fix the draft » (content failure); « Modifier le brouillon » / « Edit the draft » (size limit) | board 06 |
|
||
| L32 | « Accès non autorisé » / « Access denied », with the explanation and the « Retour au tableau de bord » / « Back to dashboard » link already decided (wordings of board 12) | complementary page, §5.3 |
|
||
| Other technical messages | the 16 other closed-code messages and the refusal messages (L30) are checked when each is integrated; they do not hold back the graphic closure | board 12, §6.5 |
|
||
| Not arbitrated by the brief | L15 second sentence (« Ici, consultation seule. » / « Sur cet écran, consultation seule. »): stays open, settled before the narrow-screen read-only mode is built (V1-2.6) | board 05, `REVUE.md` |
|
||
| Minor documentary remarks | fixed without a new graphic review, provided the boards are not modified | `REVUE.md` |
|
||
| Next step | V1-2.5 authorised once the steps it depends on (§16.6) are VERIFIED, within this contract | §16.6 |
|
||
|
||
### 17.10 V1-2.5 start (owner, 2026-11-02)
|
||
|
||
Prerequisites of §16.6 checked on `994b04e`: V1-2.1 VERIFIED at `ac71c5b` (M4 and M5 unchanged since), V1-2.2
|
||
VERIFIED (BDR-092), V1-2.4 approved (§17.9); V1-2.3 VERIFIED as well (BDR-093). V1-2.5 started under the brief
|
||
« Validation propriétaire V1-2.4 ». Owner answers to the questions raised at the start (BDR-097):
|
||
|
||
| Item | Decision | Where |
|
||
|---|---|---|
|
||
| Admin reads | the admin list needs the working-copy badge and round counts, which no table grant gives (§5.3) and no RPC returned: one read migration M7, capability holders at `aal2`, no new write path | §12.3, §16.6 |
|
||
| Working copy action | « Créer une copie de travail » built in V1-2.5 (board 10), landing on the copy's overview; the editor link arrives with V1-2.6 | §11.1, §16.6 |
|
||
| EN term | « Habilitation » reads « Permission » in the English interface; `capability` stays the technical term | §3 |
|
||
| Deprecated fingerprint | found while building the catalogue: `PreviewSheet` checks the fingerprint of published and deprecated versions, `get_sheet_version` returned it for published only, so no withdrawn version could open; `get_sheet_version` now returns it for both (redefined in M7, BDR-098) | §10, §12.3 |
|
||
| Species RPCs | M7 also redefines `create_species` and `update_inactive_species` with the 0..9 999 order range (§17.11), privileges restated; M5 and earlier migrations untouched (forward-only) | §12.3 |
|
||
|
||
|
||
### 17.11 V1-2.5 checkpoint decisions (owner, 2026-11-02)
|
||
|
||
The owner accepted the technical results of V1-2.5 at `14ff890` and ratified the following; corrections built
|
||
in V1-2.5 lots 1 to 3.
|
||
|
||
**Permission states.** Three situations are told apart, never one deduced from a technical error. On
|
||
`/app/admin/sheets/new` the order is: own grants `loading` (waiting status); the server refused (the species
|
||
read answered a `rights.*` kind): « Accès non autorisé » (BDR-094), the server's refusal wins over a failed
|
||
client read; own grants `failed`: « Impossible de vérifier vos autorisations », a short explanation and
|
||
« Réessayer », never the form; `ready` with an active `sheet_editor` grant: the form; `ready` without it
|
||
(reviewer-only, publisher-only, owner without the capability): « Accès non autorisé ». Retry re-reads the
|
||
platform roles and the own grants (and the species list when it failed) and keeps the profile, roles and
|
||
workspace already held when it fails again. The Administration home replaces its « Vos habilitations » line
|
||
with the same notice and Retry while the read failed (waiting status while loading, never « aucune »). The
|
||
sheet and species lists keep their grant-dependent actions hidden on a failed read, without a notice. Server
|
||
checks and RLS stay mandatory.
|
||
|
||
**Accepted UX deviations** (the historical boards are unchanged, no graphic redesign; `docs/design/README.md`):
|
||
the selection is shown in the zone panel instead of a tag over the drawing, on condition that it stays
|
||
identifiable and accessible (an `aria-live` region mounted before any pick, naming the picked zone); the
|
||
« Références » card is not collapsible on a phone, on condition that it does not hide the anatomical area
|
||
(it starts at or below the drawing's bottom, measured at 320 and 375 px).
|
||
|
||
**Ratified choices.** MFA factor name: 64 characters at most. TOTP setup key: no Copy button, displayed readable
|
||
and selectable while enrolment is open. Capability expiry: valid until the end of the chosen day in
|
||
Europe/Paris (the instant stored is 23:59:59.999 of that day with the offset in force then, DST-aware; the
|
||
date picker and the display use Paris dates; the backend compares instants, `expires_at > now()`; historical
|
||
rows untouched). Species order: an integer from 0 to 9 999, checked server-side (M7). Terminology:
|
||
« relecteur ou relectrice ».
|
||
|
||
**Labels.** L14: « Access and permissions » in the interface, `capability` stays technical. L15: the title
|
||
alone, the redundant second sentence is dropped (for V1-2.6). `object_conflict` (EN): « The illustration
|
||
file's contents do not match its recorded SHA-256 hash. ». The roughly 350 new labels of V1-2.5 are NOT
|
||
approved: they get a separate owner review (`.claude/audits/2026-11-02-v1-2-5-label-proposals.md`). The
|
||
wordings ratified in V1-2.4 are kept.
|
||
|
||
**MFA.** TOTP code reuse is recorded as measured (`IDENTITY.md` §4.1, §13). The lost-authenticator paths are
|
||
reviewed in `IDENTITY.md` §4.2; no safe, rehearsed recovery exists yet, which is a production prerequisite
|
||
(§13). No MFA bypass, no `aal2` weakening, no new path that resets a factor.
|
||
|
||
### 17.12 V1-2.6 UX redesign decisions (owner, 2026-11-05)
|
||
|
||
Three owner briefs of 2026-11-05: « V1-2.6 — Validation UX définitive et
|
||
préparation technique » (the sixteen boards of `docs/design/v1-2-6` and the
|
||
eleven choices of its `ARBITRAGES.md`), « V1-2.6 UX — Ratification des
|
||
décisions techniques » (BDR-100) and « V1-2.6 UX — Autorisation U0
|
||
uniquement » (BDR-101). The technical detail, the single decision table and
|
||
the sub-steps U0 to U8 (plus the curves lot, ex-U9) live in
|
||
`docs/development/V1-2-6_UX_{DECISIONS,PLAN,COMPATIBILITY,TESTS,RISKS}.md`.
|
||
Nothing below is built yet; each sub-step starts on its own authorisation.
|
||
|
||
**Level 1 (T11).** Built (lots A to O, level-1 criteria C1 to C48), never
|
||
tried by the owner, not declared validated as a whole; its trials stop and its
|
||
residuals stay tracked in `.claude/tasks/TODO.md`, re-checked at U8.
|
||
|
||
**Validated UX (choices 1 to 11).** Four tabs, references in a side panel,
|
||
undo and redo in the header on every tab; direct manipulation of points and
|
||
polygons, a zone moved with the mouse once selected and in an explicit mode
|
||
by touch, a size slider snapped to the sizes of the view; no coordinate field
|
||
in the normal journey; a detail view drawn as a rectangle, its name proposed,
|
||
its access never laid over an existing annotation; fixed categories Os,
|
||
Articulations, Vertèbres (names and roles fixed, colour and fill opacity
|
||
adjustable); a one-time copy of a versioned common text; explicit save with
|
||
the local copy; O14 A kept, touch drawing on a tablet in landscape, the
|
||
sidebar hidden in the editor below 1 280 px, phone editing a future lot; an
|
||
annotation's own colour shown only when set. Amended accordingly: §6.2, §7.4,
|
||
§8.2 to §8.4, §16.7, §16.12, and the level-1 contract
|
||
(`.claude/tasks/contracts/2026-11-03-v1-2-6-editor-1509.md`: C3, C4, C5, C6,
|
||
C7, C8, C11, C13, C16, C18, C20, C25, C28, C32, C33, C40, the undo question of
|
||
its CLARIFICATIONS, and a precedence rule in its header; the board differences
|
||
left to the owner are listed in `V1-2-6_UX_DECISIONS.md`).
|
||
|
||
**Category model (T2, T3, T4, T5, T10).**
|
||
- Two optional keys on a category, `role` (`bone`, `joint`, `vertebra`,
|
||
`navigation`) and `fill_opacity` (an integer percent from 10 to 100),
|
||
omitted when absent, never `null`, no schema version bump. Written only once
|
||
the proofs of `V1-2-6_UX_COMPATIBILITY.md` §8 are green and reviewed and the
|
||
checks below are live (write lock). Compatibility runs one way: once a
|
||
document carries a key, no earlier application, worker or core reads it,
|
||
and returning to the old application is impossible.
|
||
- Fixed model: each of `bone`, `joint`, `vertebra` carried by exactly one
|
||
category, with its fixed names; `navigation` by at most one.
|
||
- New-sheet defaults (T5): `cat-bone` « Os » / « Bones » `#a41e65`,
|
||
`cat-joint` « Articulations » / « Joints » `#ff9500`, `cat-vertebra`
|
||
« Vertèbres » / « Vertebrae » `#e100ff`, colours shown as « Couleur
|
||
d'origine ». The names Bones and Joints and the three colours come from the
|
||
equine categories `os`, `articulations` and `zone-colonne`; no existing
|
||
category is named Vertebrae, which follows the editor's tab pair
|
||
« Vertèbres » / « Vertebrae ».
|
||
- Navigation category (T10 option B): `cat-access`, role `navigation`,
|
||
« Accès aux vues détaillées » / « Detail view access », no colour; never
|
||
shown as an anatomical category (no panel, no picker); holds detail
|
||
triggers only; created by the core with the first automatic access (U6).
|
||
- Checks (T4, no residual gap): the core's verdict issues `category.fixed.*`
|
||
(§6.7) and editor refusals with repairs; a core gate at verification
|
||
completion that refuses a passed verdict of a core older than U6; the
|
||
round withdrawal of §6.4; the two declared SQL checks of §12.2 (O22
|
||
amended), at save and at approval and publication, holding the
|
||
fixed-category invariants only.
|
||
- History (T5): the historical equine versions keep their ids, names,
|
||
colours, own colours, annotations and fingerprints; roles go on the working
|
||
copy only (V1-2.8, decision T6); the seed and the published historical
|
||
version never change.
|
||
|
||
**Detail views (T9, T10).** Replacing a crop view's drawing opens a dialog
|
||
before any upload with three actions: keep the positions (only when the
|
||
candidate's `viewBox` equals the crop), reposition the annotations (only for
|
||
the same aspect ratio, with no path and no descendant crop), cancel; never an
|
||
approximate automatic transformation. The automatic access needs the
|
||
navigation role, so it comes at U6, not U5, and only when no annotation
|
||
overlaps the rectangle; until then the access is placed explicitly from the
|
||
view's menu (U4).
|
||
|
||
**Curves (T16).** Curve handle editing is deferred to the curves lot, which
|
||
precedes any feature letting a path into a document. Stored paths keep their
|
||
data byte for byte and are never converted; an operation that would change
|
||
one is refused with the document unchanged. « Remplacer par un polygone » is
|
||
kept as an explicit replacement only (§8.3 as amended). Before the new model
|
||
is activated on an environment, and before U6 or U8 reaches any environment
|
||
beyond the throwaway sandbox, a read-only count of path geometries in its
|
||
drafts and published versions is recorded (DEV and shared environments by the
|
||
owner or under an explicit authorisation, never during U0); a non-zero count
|
||
reopens T16.
|
||
|
||
**Common text (T12).** One versioned copy inserted once into empty fields
|
||
(§7.4); U7 blocked until the owner supplies the FR and EN text, its source and
|
||
its validation record; no normative wording before that.
|
||
|
||
**Vertebral regions (T17, owner 2026-11-06, BDR-102).** With no category
|
||
carrying the role `vertebra`, Annotations offers a fallback « Régions
|
||
vertébrales » entry; once a Vertèbres category exists, the regions are
|
||
configured from it (board 09), never in two places.
|
||
|
||
**Wording (T15).** « Annuler la dernière modification » names the history
|
||
command (header button, tooltip and accessible name, the toast after a
|
||
gesture); « Abandonner » or « Abandonner les modifications » names leaving a
|
||
form or discarding unsaved changes (level-1 C11).
|
||
|
||
**Open.** T1 (only if a measure exceeds the 600 000 B wasm budget), T6
|
||
(V1-2.8), T14 (multi-tab notice, follow-up), the T12 text (blocks U7), and the category of an access placed by hand after U6 when annotations
|
||
overlap the rectangle (a U6 design point, DECISIONS T10).
|
||
|
||
**Implementer decisions** (no owner question): T7 both keys stripped from
|
||
every envelope snapshot; T8 path operations on the written digits (curves
|
||
lot); T13 commits in place on `feature/v1-2-anatomical-sheets`, rollback by
|
||
revert; T18 a handle cap per shape, fixed at U2 from the equine maxima (17
|
||
vertices today) with a margin; T19 sliders and arrow moves commit on release,
|
||
Enter or blur.
|
||
|
||
---
|
||
|
||
## 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 into `develop` 9135d73).
|
||
- `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 decided (B) and integrated in §5.7;
|
||
- `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
|
||
stale `content_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`.
|
||
|
||
AR-1 B integration (2026-10-28):
|
||
|
||
- this file: §5.7 (rule, scenario, inventory, bootstrap, factors, password,
|
||
recovery, sessions), F17 to F19, M4, tests, steps and DEV order, §17.2
|
||
closed;
|
||
- `.claude/memory/decisions.md` (BDR-083), `.claude/tasks/TODO.md`,
|
||
`.claude/memory/journal.md`;
|
||
- `docs/development/IDENTITY.md` §4: one pointer to §5.7, no other change.
|
||
|
||
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) |
|
||
|
||
### 19.4 AR-1 B review (2026-10-28)
|
||
|
||
One fresh challenger (robustness and security lens) read the AR-1 B text
|
||
against the migrations, the seed, the PGlite shim and `ENVIRONMENTS.md`.
|
||
|
||
| Lens | Verdict | Findings and what changed |
|
||
|---|---|---|
|
||
| Security | FATAL (1 blocker, 3 major, 6 minor) | DEV signs tokens with the public default secret and exposes 54321 to the LAN, so `aal2` is forgeable there (precondition §5.7.2 step 0, §16.11, §13 corrected); a grant to an account without a factor reopened the chain (target factor required, check 5); seed owner with a committed password and re-seed after M4 (password change or new owner, reset reopens the preconditions, seed declared a local-fixture exception); recovery runbook unrunnable under a ban and silent on the owner's capabilities (reordered, capabilities inert at `aal1`); minor: unverified factors, null actor keyed on the argument, owner race beyond the count and on inactive profiles, `amr` freshness overclaim, session-check fallback made a stop, sign-out wording, API-log claim, harness gaps (shim, fixtures, TOTP helper moved to V1-2.1), cross-references. None changed a ratified decision |
|