docs(docs): consolidate V1-2 contract with ratified O1-O23, open AR-1

This commit is contained in:
bchanot committed 2026-10-28 11:35:51 +01:00
1 parent 397d6007b4
commit 7fec2ce86f
7 files changed
+1621 -646

No files matched your search

+21 -10
View File
@@ -1,17 +1,28 @@
---
paths: ["crates/core/src/domain/sheet/**", "docs/development/ANATOMICAL_SHEET_MODEL.md", "supabase/seed/anatomical-sheets/**", "crates/core/src/bin/upload_sheet_assets/**"]
paths: ["crates/core/src/domain/sheet/**", "docs/development/ANATOMICAL_SHEET_MODEL.md", "docs/development/V1-2_ANATOMICAL_SHEETS.md", "supabase/seed/anatomical-sheets/**", "crates/core/src/bin/upload_sheet_assets/**"]
---
# Anatomical sheet model (crates/core/src/domain/sheet + migration 20261008110000)
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth: document shape, issue codes, tables, RPCs.
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth for the model as built: document shape, issue
codes, tables, RPCs. `docs/development/V1-2_ANATOMICAL_SHEETS.md` holds the ratified V1-2 rules (O1-O23, BDR-082):
every V1-2 change follows it, and V1-2.9 folds it back into the model file.
- Ids are stable slugs never derived from labels; labels are `{ fr, en }` objects. Annotation → findings is the
explicit `finding_zone_id`; vertebral regions are ordered data with free codes. No label matching at runtime.
- A published version is immutable (trigger, every role). Change = new draft (`create_sheet_draft`) then
`publish_sheet_version`. Integrity rule codes are shared by `validate_sheet_document` (Rust core) and
`private.sheet_document_issues` (SQL); add a rule on both sides and in the spec table.
- A published version is immutable (trigger, every role) and, from V1-2, never deleted, even deprecated. Change = new
draft (`create_sheet_draft`) then publication; from V1-2, publication only from an approved round on a server
verdict of the core.
- The Rust core is the only authority on document rules (O22): add a rule to `validate_sheet_document` and to the spec
table only. Never extend `private.sheet_document_issues`: V1-2 (M5) removes its business rules and keeps the
structural and relational guards.
- Document schema change → bump `SHEET_DOCUMENT_SCHEMA_VERSION`, extend the SQL CHECK on `document_schema_version`.
- Official equine sheet = generated seed `draft/` (`pnpm import:equine --out` into an empty folder, then reviewed and copied; never edit `legacy-import/` or `draft/` by hand;
`curation_draft` / `curation_review` fail on drift, `pnpm import:equine --check` lists it). Every content change goes through `curation/changes.json` (traced in CHANGELOG.md).
It is a DRAFT until a platform admin publishes it after business review of `REVIEW-REPORT.md`.
- Sheet SVG bytes live in Storage bucket `anatomical-sheet-assets` as `<sha256>.svg`; uploads are an operator task
(`pnpm assets:upload <seed dir>` with the service key in env), never from the browser.
No bump during V1-2 (BLK-008).
- Historical equine sheet `503dc301…` = generated seed `draft/` (`pnpm import:equine --out` into an empty folder, then
reviewed and copied; never edit `legacy-import/` or `draft/` by hand; `curation_draft` / `curation_review` fail on
drift, `pnpm import:equine --check` lists it). Its content changes only through `curation/changes.json` (traced in
CHANGELOG.md), and the pipeline stays unchanged during V1-2. It is never published; equine work moves to an
application working copy (O17), whose publication is an owner act after the business review.
- Sheet SVG bytes live in Storage bucket `anatomical-sheet-assets` as `<sha256>.svg`, never overwritten. Until M5
(V1-2.1) uploads are an operator task (`pnpm assets:upload <seed dir>`, local stacks, service key in env); from M5,
editors upload from the application after the core's cleaning, and the worker verifies every submitted revision (M6).
- Omitted `review_status` means `inherited` (`#[serde(default)]`): any check on statuses treats an absent value as
`inherited`.
+2 -1
View File
@@ -55,7 +55,8 @@ business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validate
`pnpm db:sandbox`, applied to Supabase DEV 2026-10-27 by the owner procedure (SUPABASE.md §3.3); V1-1.3 the native modal dialog (D13) and the Playwright + axe suites
(D14, `docs/development/BROWSER_TESTS.md`); V1-1.5 the client screens (`/app/clients`, contract §11.7) and V1-1.6
the animal screens and the relations (`/app/animals`, contract §11.8; D11: drawer only, no tab bar)).
V1-2 contract (draft, owner review pending): `docs/development/V1-2_ANATOMICAL_SHEETS.md`, branch `feature/v1-2-anatomical-sheets`.
V1-2 contract (decisions O1-O23 ratified 2026-10-28, BDR-082; contract under the owner's final review, no implementation before
the owner's go): `docs/development/V1-2_ANATOMICAL_SHEETS.md`, branch `feature/v1-2-anatomical-sheets`.
---
+21 -8
View File
@@ -11,6 +11,15 @@ manual report points confirmed).
Out of scope here: the legacy importer and the official equine draft
(next step), the visual editor, cloud reports, community, booking.
V1-2 (decisions ratified 2026-10-28, `V1-2_ANATOMICAL_SHEETS.md`, BDR-082)
replaces the validation tiers of §2.1, the lifecycle of §3.1 and the access
helpers of §3.2: explicit rights with MFA, drafts saved through an RPC with
revisions, review rounds verified by the Rust worker, the SQL mirror of the
integrity rules removed (the core is the only authority), species created
inactive, the historical equine sheet kept read-only beside an application
working copy. Until V1-2.9 rewrites those parts, this file describes the
model as built.
## 1. Two layers
| Layer | Where | Role |
@@ -19,8 +28,9 @@ Out of scope here: the legacy importer and the official equine draft
| Relational identity | `supabase/migrations/20261008110000_anatomical_sheets.sql` | Who owns the sheet, visibility, versions and their status, provenance of copies, assets, audit. |
The database stores the document as JSONB in
`anatomical_sheet_versions.content`. Zod is the shape contract at the
application boundary; SQL checks what only SQL can know (species of the
`anatomical_sheet_versions.content`. The Rust core's strict parser is the
shape contract (`crates/core/src/domain/sheet/schema.rs`, through wasm in the
browser); SQL checks what only SQL can know (species of the
parent sheet, assets registered for the sheet, immutability, numbering) plus
the referential rules of §3 at publication time, so a browser cannot publish
a dangling document.
@@ -109,8 +119,8 @@ Why these shapes:
| Tier | Function | When |
| ---------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| Shape | `AnatomicalSheetDocumentSchema.parse()` | every save (draft included) |
| Integrity | `validateSheetDocument(doc): SheetIssue[]` | editor feedback; `publishable` = no issue with `severity: 'error'` |
| Shape | strict parse of the Rust core (`schema.rs`) | every load and every check |
| Integrity | `validate_sheet_document(doc)` (core; `sheet.check` through wasm) | editor feedback; `publishable` = no issue with `severity: 'error'` |
| Relational | `publish_sheet_version()` in SQL | publication: species matches the sheet, assets exist, referential rules below |
`SheetIssue = { code, severity: 'error' | 'warning', path, message }`; the
@@ -140,17 +150,20 @@ Integrity rules (error unless stated):
| `reference.id.duplicate` | reference ids unique |
| `finding.reference.missing` | every `reference_ids` entry (categories and nodes, any depth) is declared |
| `region.count_range.invalid` | `count_range.min ≤ count ≤ count_range.max` when a range is given |
| `reference.url.scheme` (SQL only; Zod refuses it at parse) | every `references[].url` is null or starts with `http://` / `https://` |
| `reference.url.scheme` (SQL only; the core's strict parse refuses it) | every `references[].url` is null or starts with `http://` / `https://` |
A draft may be saved with errors. Publishing a document with errors is
refused in TypeScript (`assertPublishable`) and in SQL:
refused on the client (`publishSheetVersion` in `packages/supabase` runs the
core's `sheet.check`) and in SQL:
`private.sheet_document_issues` re-checks every error-level rule except
parent cycles and sibling uniqueness (citations are walked recursively with
a `jsonpath` `**` descent) and reports
`document.shape` when an id-bearing collection is not an array;
`private.sheet_document_unknown_assets` adds `view.asset.unknown` when a
view points at an asset not registered for the sheet. Both run inside
`publish_sheet_version`.
`publish_sheet_version`. V1-2 removes the business part of this mirror and the
client gate, keeps the structural and relational guards, and publishes only on
a server verdict of the core (contract §12.2, O22).
## 3. Relational model
@@ -277,7 +290,7 @@ with the community step (§17.4).
| Criterion | Where it is proven |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| A sheet with several views and annotations explicitly linked to findings | `crates/core/tests/fixtures/horse-slice.json` (from `horse-slice.ts`, deleted at R5.7; 2 views, trigger, spine region, bilateral joint, 3 finding kinds); schema + integrity tests |
| Ids stable under translation | test: renaming every label leaves ids, references and `validateSheetDocument` output unchanged |
| Ids stable under translation | test: renaming every label leaves ids, references and `validate_sheet_document` output unchanged |
| Published versions immutable | pgTAP: UPDATE of content / status / number on a published row → `42501` for the table owner; zero rows touched through the API role |
| New version leaves old ones intact | pgTAP: v2 draft then publish; v1 row byte-identical, `current_version_id` moves |
| Copies keep provenance, source untouched | pgTAP: fork → `based_on_*` set, source rows and assets unchanged; editing the copy leaves the source unchanged |
+15 -2
View File
@@ -29,7 +29,7 @@ computer. Inventory: `.claude/audits/2026-10-25-functional-inventory.md`.
|---|---|---|
| P0 | Documents realigned on the code, decisions recorded (`OPEN_QUESTIONS.md` statuses) | none |
| V1-1 | Clients and animals of a practitioner's workspace, with the permission frame of future cabinets (`V1-1_OWNERS_ANIMALS.md`) | 12 reduced, frame of 10 |
| V1-2 | Anatomical sheets loaded from Supabase under control (no publication of the equine draft without the owner) | 13 reduced |
| V1-2 | Official anatomical sheets administered from the application: rights, structured editor, server-verified review and publication, catalogue; the equine sheet prepared, never published inside V1-2 (`V1-2_ANATOMICAL_SHEETS.md`, decisions ratified 2026-10-28, BDR-082) | 13, and 17 reduced to official sheets |
| V1-3 | Bilans persisted, linked to an animal, history | 14 (+ 11 skeleton if a quota applies) |
| V1-4 | Stored PDF artifacts and authorised sharing | 15 reduced, sharing part of 12 |
| V1-5 | Cross-cutting mobile and accessibility validation | design README, `TEST_STRATEGY.md` |
@@ -367,7 +367,7 @@ Name: Anatomical sheets in the database and official equine seed
Objective: Sheet and version tables with immutability, SVG assets in Storage, seed of the official equine sheet as a draft, SheetProvider over Supabase, read-only sheet library in the app.
Dependencies: Step 3, Step 4, Step 8
Changes expected:
- supabase: anatomical_sheets, anatomical_sheet_versions (content_jsonb + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), operator upload of the drawings (`pnpm assets:upload`) and the generated draft seed. Publication of the official equine sheet is an explicit act of a platform admin after the business review of REVIEW-REPORT.md (BDR-034, BDR-037); no step publishes it automatically.
- supabase: anatomical_sheets, anatomical_sheet_versions (content + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), operator upload of the drawings (`pnpm assets:upload`) and the generated draft seed. Publication of the official equine sheet is an explicit act of a platform admin after the business review of REVIEW-REPORT.md (BDR-034, BDR-037); no step publishes it automatically.
- packages/supabase: typed accessors; apps/app: SheetProvider.supabase replaces the bundled seed in production builds (bundled kept for tests), /app/anatomy read-only list and preview.
Tests: pgTAP: UPDATE on published content raises; v2 numbering; GC preconditions each individually; non-creator cannot read a private sheet; integration: seed is idempotent and byte-faithful (checksums).
Manual validation: open /app/anatomy, see "Faunosteo / Cheval / officielle" with its draft or published status, preview both views, click zones (no report yet).
@@ -384,6 +384,11 @@ candidates. Roadmap item V1-2 reduces the step to a controlled loading of the
sheets; whether a signed-in practitioner may load the unpublished draft is an
owner decision taken at V1-2.
Step 13 note (2026-10-28): V1-2 absorbs the provider and the library
(`V1-2_ANATOMICAL_SHEETS.md` §10, §11). Drafts are never served to readers
(D3); the catalogue is read under an explicit, provisional catalogue access
until the entitlements of Step 11 (O21). The GC candidates stay with Step 18.
```text
Step 14
Name: Cloud reports
@@ -444,6 +449,14 @@ Definition of Done: architecture Sprint 6 (except "promote manual point", added
Risks: largest UI step; split into sub-branches (canvas tools / panels / publish) each merged green behind a "beta" flag; feature parity gaps with the vanilla tool found late (mitigate with the reference tests first).
```
Step 17 note (2026-10-28): requirement D9 (BDR-081) moves the editor of
official sheets into V1-2, at the level 1 of `V1-2_ANATOMICAL_SHEETS.md` §8.2,
with server-verified review and publication. It supersedes, for official
sheets, the 2026-10-25 rule « no graphic editor until Step 17 »: the curation
pipeline stays the authority of the historical equine sheet only, whose work
moves to an application working copy (O17). Step 17 keeps personal sheets, the
level 2 editor (§8.3) and the community parts.
```text
Step 18
Name: Community
+11
View File
@@ -49,12 +49,23 @@ Step 5).
sources and the Rust pipeline, reviewed, tested and versioned. Annotating a
bilan is distinct from changing the anatomical reference and never touches
`curation/changes.json`.
Superseded for official sheets (owner, 2026-10-27, D9, BDR-081; decisions
ratified 2026-10-28, BDR-082): V1-2 brings the editor of official sheets,
with server-verified review and publication (`V1-2_ANATOMICAL_SHEETS.md`).
The curation pipeline stays the authority of the historical equine sheet
only; equine work moves to an application working copy (O17).
2. Publication of the official equine sheet: the plan's Step 13 used to expect
"v1 published"; BDR-034 and BDR-037 keep it a draft until a platform admin
publishes after business review. Confirmed (owner, 2026-10-25): the equine
sheet stays a draft until business validation, and nothing publishes it
automatically. Still open for V1-2: who triggers the review, and whether
V1-2 may serve the unpublished draft to signed-in practitioners.
Resolved (owner, 2026-10-27 and 2026-10-28; BDR-081, BDR-082): drafts are
never served to readers (D3); an editor submits, a reviewer outside the
author set approves, a publisher publishes (O1, O2); the historical equine
sheet is never published and its review is prepared on a working copy,
whose publication stays an owner act after the business review, outside
V1-2 (O17, O18).
3. Recorded decision BDR-041 calls professional verification "Step 11"; the
plan numbers it Step 9. Resolved: the plan's numbering is kept and the
correction is the new entry BDR-072 (the registry is append-only, BDR-041
+3
View File
@@ -320,6 +320,9 @@ which needs the clock and is checked by the RPCs (tomorrow's UTC date, §9.3):
Reference data written by migration: the nine species of the contract (the
existing `equine` row plus eight) and « Autre ». No other species is added.
(Amended by V1-2 O9, ratified 2026-10-28: a habilitated sheet editor creates a
species inactive, invisible in the animal forms, and the platform owner
activates it; `V1-2_ANATOMICAL_SHEETS.md` §7.2.)
Slugs, names and order approved by the owner (§13.2 N1). Compatibility,
checked on 2026-10-25: species are rows of `public.species` (text `id`,
CHECK `^[a-z0-9][a-z0-9_-]{0,63}$`, which every slug below satisfies), never a
File diff suppressed because it is too large. Load diff