Files
faunosteo/docs/development/ANATOMICAL_SHEET_MODEL.md
T

439 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Anatomical sheet model (Step 4)
Status: Step 4 deliverable, 2026-10-08. Source of truth for the canonical
"fiche anatomique": the JSON document, its validation rules, the PostgreSQL
tables that persist it, and the lifecycle rules (versions, copies, deletion).
Decisions it applies: business architecture §2.6–§2.9, §7, §16, §17.3,
§23.2; `OPEN_QUESTIONS.md` C1, C2, C8, C9, Q3, Q5, Q9 as decided on
2026-10-08 (equine only, two SVG assets, import anomalies land in a draft,
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.
## 1. Two layers
| Layer | Where | Role |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Canonical document | `packages/domain/src/anatomical-sheet/` (Zod) | The sheet content: views, annotations, finding tree, vertebral regions, translations. Self-describing (`schema_version`). |
| 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
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.
## 2. Canonical document (schema_version 2)
Every id is a **stable id**: `^[a-z0-9][a-z0-9_-]{0,63}$`, never derived
from a label, never changed by a translation. Vertebral region codes are
the one exception: `^[A-Za-z0-9][A-Za-z0-9_-]{0,15}$`, because the
practitioner reads them as-is (`C`, `T`, `L`, `S`, `Cd`). Labels are `LocalizedText`
objects `{ fr, en }` (both required) or `LocalizedOptionalText` `{ fr?, en? }`.
Adding a locale later means adding an optional key, not a new field family.
```text
AnatomicalSheetDocument
├─ schema_version: 2
├─ species_id: stable id (row of public.species)
├─ name: LocalizedText display name of the sheet
├─ description: LocalizedOptionalText
├─ scope_disclaimer: LocalizedOptionalText legal scope text shown once per session and in the PDF
├─ attribution: { authors: string[], license: string | null, notes: string | null }
├─ vertebral_config: { regions: VertebralRegion[] } ORDERED; codes free (C/T/L/S/Cd for the horse)
│ VertebralRegion = { code, name: LocalizedText, count ≥ 1, count_range: { min, max } | null }
│ count = usual number (picker default); count_range = documented individual variation (Cd 15–21)
├─ references: Reference[] shared bibliography, cited by id from the finding tree
│ Reference = { id, type: book | journal | standard | legal | web | manual, citation, url | null, doi | null }
├─ categories: AnnotationCategory[] { id, name: LocalizedText, color: '#rrggbb' | null }
├─ views: SheetView[]
│ main: { id, kind: 'main', name, svg_asset_id: uuid | null, view_box: ViewBox | null }
│ detail: { id, kind: 'detail', name, parent_view_id, svg_asset_id: uuid | null, view_box: ViewBox | null }
│ ViewBox = { min_x, min_y, width > 0, height > 0 }
├─ annotations: Annotation[]
│ common: { id, view_id, category_id, laterality, geometry: Geometry | null, review_status }
│ review_status ∈ inherited | reviewed | to_confirm (default inherited)
│ point | zone: + { name: LocalizedText, finding_zone_id: id | null, vertebral_region_code: code | null }
│ detail_trigger: + { name: LocalizedText | null, opens_view_id }
│ laterality ∈ unpaired | bilateral | left | right
│ Geometry = circle { cx, cy, r } | polygon { points: [x, y][] ≥ 3 } | path { d }
└─ finding_zones: FindingZone[]
FindingZone = { id, name: LocalizedText, categories: FindingCategory[] }
FindingCategory = { id, kind: dysfunction | consultation_reason | anamnesis | custom, name, description?, reference_ids?, review_status?, children: FindingNode[] }
FindingNode = { id, name, description?, requires_vet_referral?, reference_ids?, review_status?, children? } (recursive)
```
Version 2 (Step 4c) replaced the inline `sources` of version 1 by the
`references` registry + `reference_ids` (one atlas backs hundreds of
entries, declared once), added `review_status` (what was checked against
references versus inherited from the legacy catalog) and `count_range`
(individual variation of a vertebral region). No version 1 document was
ever published: the SQL CHECK accepts version 2 only and the one draft is
regenerated by its seed.
Why these shapes:
- **Views are a tree**, not a `details.head` field. A detail view names its
parent; a `detail_trigger` annotation in the parent opens it. Nesting depth
is free (§7.3). `svg_asset_id` is nullable on a detail view: null means
"render the parent's asset with this `view_box`" (C9). The legacy import
keeps two assets (Q5); the curated draft keeps one and its head view is a
crop, so both forms are exercised.
- **Laterality is explicit** on every annotation. `bilateral` = one drawing
stands for both sides, the report picks the side (today's behaviour);
`left` / `right` = the drawing shows one side; `unpaired` = no side.
Absence of attribute no longer carries meaning.
- **Spine regions are data.** `vertebral_config.regions` is an ordered list
with free codes (C1, Q3). An annotation that opens the vertebra picker
carries `vertebral_region_code`; no label parsing (`regionFromLabel` stays
in the importer).
- **Annotation → findings is one explicit field**, `finding_zone_id`. No
FR/EN matching at runtime (§23.2). Several annotations may share a zone;
a `detail_trigger` never has one (it is navigation, not an observation).
- **Finding categories carry a `kind`** so the three business buckets
(dysfonctions ostéopathiques, observations / motifs de consultation,
anamnèse / facteurs rapportés) are typed, and creators may add `custom`
ones (§7.4). Node ids are unique among siblings; a finding is referenced
by `(finding_zone_id, path[])` exactly as `Finding.path` does today, so
the Step 5 report adapter is a rename, not a re-keying.
- **Tree nodes are lean on input, total on output**: `description`,
`requires_vet_referral`, `reference_ids`, `review_status`, `children` are
optional in the JSON and defaulted by the parser (612 leaves would
otherwise carry five empty keys each). Structural records (views, annotations) use explicit `null`.
- The parser is **strict**: unknown keys are rejected. A canonical document
must not silently carry fields no version of the schema defines.
### 2.1 Validation tiers
| Tier | Function | When |
| ---------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| Shape | `AnatomicalSheetDocumentSchema.parse()` | every save (draft included) |
| Integrity | `validateSheetDocument(doc): SheetIssue[]` | 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
path names the offending field (`annotations[0].category_id`), the later
entry for a duplicate, the item itself for `view.unreachable` and
`finding_zone.unreferenced`.
Integrity rules (error unless stated):
| Code | Rule |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `view.main.count` | exactly one `main` view |
| `view.id.duplicate` | view ids unique |
| `view.parent.missing` / `view.parent.cycle` | detail parent exists; the parent chain reaches the main view |
| `view.unreachable` | every detail view is opened by ≥1 `detail_trigger` located in its parent view |
| `view.asset.missing` | the main view has an asset; a detail view without asset has a `view_box` |
| `annotation.id.duplicate` | annotation ids unique across the whole sheet (all views) |
| `annotation.view.missing` | `view_id` exists |
| `annotation.category.missing` | `category_id` exists |
| `annotation.opens_view.invalid` | trigger target exists, is `detail`, and its parent is the trigger's view |
| `annotation.finding_zone.missing` | `finding_zone_id` exists |
| `annotation.region.missing` | `vertebral_region_code` exists in `vertebral_config` |
| `annotation.no_findings` (warning) | point / zone without `finding_zone_id` |
| `region.code.duplicate`, `category.id.duplicate`, `finding_zone.id.duplicate` | uniqueness |
| `finding.id.duplicate` | node ids unique among siblings (per zone, per children array) |
| `finding_zone.unreferenced` (warning) | zone no annotation points to |
| `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://` |
A draft may be saved with errors. Publishing a document with errors is
refused in TypeScript (`assertPublishable`) 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`.
## 3. Relational model
```text
public.species reference data, seeded by the migration (equine)
public.anatomical_sheets identity, owner, visibility, status, provenance, current version
public.anatomical_sheet_versions numbered versions, status draft | published | deprecated, content jsonb
public.anatomical_sheet_assets SVG files, content-addressed (sha256), per sheet
audit.audit_logs every lifecycle event (private.log_event)
```
### `species`
`id text` (stable id), `name_fr`, `name_en`, `sort_order`, `active`. Read by
any authenticated user; no write path through the API (platform step later).
### `anatomical_sheets`
| Column | Notes |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `id uuid` | |
| `species_id` | FK species |
| `name text`, `slug text`, `description text` | slug `^[a-z0-9][a-z0-9-]{1,79}$`, unique per owner scope among non-deleted sheets |
| `creator_user_id uuid null` | null = platform-owned (official sheets, seeds) |
| `is_official boolean` | only a platform admin can create one; editable by platform admins |
| `visibility` | enum `sheet_visibility`: `private` \| `public` |
| `status` | enum `sheet_status`: `active` \| `archived` \| `deleted` (soft) |
| `based_on_sheet_id`, `based_on_version_id` | provenance of a copy (fork); FK `on delete set null` so the copy survives the source |
| `current_version_id` | latest published version (nullable while draft-only) |
| `last_version_number` | monotonic counter: a deleted version's number is never reused |
| `archived_at`, `deleted_at`, `created_at`, `updated_at` | |
### `anatomical_sheet_versions`
| Column | Notes |
| ----------------------------------------------------------- | --------------------------------------------------------------------------- |
| `id uuid`, `sheet_id` | |
| `version_number int` | unique per sheet, assigned by the server from the sheet's monotonic counter |
| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` |
| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `2` now (CHECK `= 2`) |
| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB |
| `change_note text` | what changed in this version |
| `created_by`, `published_by`, `deprecated_by` | profile ids, `on delete set null` |
| `published_at`, `deprecated_at`, `created_at`, `updated_at` | |
Rules enforced by triggers (every role, including the table owner):
- **One draft per sheet** (partial unique index, C8).
- **Published rows are immutable**: the only accepted UPDATE on a
`published` row is the transition to `deprecated` (status, `deprecated_at`,
`deprecated_by`); a change to any compared column (content, schema
version, number, sheet, note, authorship, timestamps) raises `42501` for
every role, table owner included. Through the API the row is simply
invisible to UPDATE (zero rows touched). A `deprecated` row is frozen.
- **Deletion preconditions** (BEFORE DELETE): never a `published` row; never
the `current_version_id` of its sheet; never a version a non-deleted sheet
is `based_on`; (reports: added when the table exists, §16). A `draft` has
no dependents and is dropped by its editor through `delete_sheet_version`.
- **Document ↔ row**: `content->>'species_id'` equals the sheet's species.
### `anatomical_sheet_assets`
`id uuid`, `sheet_id`, `sha256 text` (64 hex), `byte_size int`,
`content_type text` (`image/svg+xml` only for now), `file_name text`,
`created_by`, `created_at`. Unique `(sheet_id, sha256)`. Assets are
immutable and **content-addressed**: the bytes live in Storage under
`anatomical-sheet-assets/<sha256>.svg` (bucket and policies arrive with the
importer step; until then the path is a convention, not a row). Two sheets
with the same SVG share one object; a copy of a sheet copies only the
metadata rows its copied version references. Deleting an asset referenced by
a version is refused (FK restrict is not possible on a JSONB reference, so
`delete_sheet_asset` checks every version's views). Asset rows follow the
sheet's visibility, drafts included: the future Storage policy must
authorise through the sheet, never through a sha256 alone.
### 3.1 Lifecycle (RPCs, security definer, audited)
| RPC | Actor | Effect |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_anatomical_sheet(species_id, name, slug, document, description, visibility, official)` | any active account; `official = true` needs platform admin | sheet + draft v1 |
| `create_sheet_draft(sheet_id, from_version_id, change_note)` | editor | new draft (next counter value), content copied from `from_version_id` (default: current version); refused if a draft exists |
| `publish_sheet_version(version_id)` | editor | draft → published; relational checks; sheet `current_version_id` ← version. Previous published versions stay `published` (historical reports keep rendering) |
| `deprecate_sheet_version(version_id, reason)` | editor | published → deprecated (not offered for new reports; still readable) |
| `delete_sheet_version(version_id)` | editor | physical delete, trigger preconditions |
| `fork_anatomical_sheet(source_version_id, name, slug, visibility)` | any user who can use the source | new sheet (`based_on_*` set, `creator = actor`), asset rows copied, draft v1 = source content with `svg_asset_id`s remapped. The source rows are not touched |
| `archive_anatomical_sheet(sheet_id)` / `restore_anatomical_sheet` | editor | status archived ↔ active; archived sheets are hidden from "use" but readable by their editor |
| `delete_anatomical_sheet(sheet_id)` | editor | soft delete; refused while a non-deleted copy derives from the sheet |
| `set_sheet_visibility(sheet_id, visibility)` | editor | private ↔ public, audited (sharing is sensitive state) |
| `register_sheet_asset(sheet_id, sha256, byte_size, file_name)` | editor | asset row (idempotent on `(sheet, sha256)`) |
| `delete_sheet_asset(asset_id)` | editor | refused while any version references the asset |
Direct table access for `authenticated`: SELECT through the policies below;
UPDATE of `name` / `slug` / `description` on own sheets and of `content` /
`change_note` on **own draft** rows (the future editor autosaves with a
PATCH; the autosave itself is not audited, the publication is). Everything
else is RPC. Every RPC takes its actor from `auth.uid()`, refuses a
deactivated profile, checks `can_edit_sheet` before reading anything else
(unknown and foreign ids get the same `42501`), and calls
`private.log_event`.
### 3.2 Access helpers (`private`, security definer)
| Helper | True when |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `can_edit_sheet(uid, sheet_id)` | sheet not deleted and (creator = uid, or `is_official` and platform admin) |
| `can_use_sheet(uid, sheet_id)` | sheet `active` and (`public`, or `can_edit_sheet`), grants and follows plug in here at the community step |
Policies:
| Table | SELECT | INSERT / UPDATE / DELETE |
| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
| `species` | authenticated, `active` rows | none |
| `anatomical_sheets` | `can_use_sheet` or `can_edit_sheet` | UPDATE `name`, `slug`, `description` for editors; everything else RPC |
| `anatomical_sheet_versions` | published / deprecated of usable sheets; drafts for editors | UPDATE `content`, `change_note` on own drafts; INSERT and DELETE via RPC |
| `anatomical_sheet_assets` | same visibility as the sheet | none (RPC) |
`anon` gets nothing. Every `private` function has EXECUTE revoked from
PUBLIC; `authenticated` executes only the policy predicates (the two above
plus the five platform-role predicates of Step 3); pgTAP 001 keeps a census. Public discovery views for the public site come
with the community step (§17.4).
## 4. What the model guarantees (acceptance criteria)
| Criterion | Where it is proven |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| A sheet with several views and annotations explicitly linked to findings | `packages/domain/tests/fixtures/horse-slice.ts` (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 |
| 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 |
| Validation detects inconsistencies | domain tests, one per rule (missing references, duplicate ids, invalid relations) + SQL `sheet_document_issues` |
| Security rules tested | pgTAP allowed + denied paths: other user, anon, direct writes, official sheets, archived/deleted sheets |
| Migrations reproducible | PGlite replays from zero in `pnpm test:run`; `pnpm db:reset` on the real stack |
| Previous tests pass | root `pnpm check` |
## 5. Business decisions (user, 2026-10-09)
The open points of Step 4 were decided as follows. Each line names where
the decision lands; only the naming one is implemented in this document.
| # | Decision | Where it lands |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Public sheets are readable according to their visibility, but **using** a community sheet for a report requires following its author. Official Faunosteo sheets need no follow. | `can_use_sheet` gains the follow predicate at the community step; official sheets (`is_official`) bypass it. Until then every active account may use any public sheet. |
| 2 | Any account may prepare private drafts; **community publication** is reserved to authorised, verified accounts. Student and professor roles keep their own rules. | `publish_sheet_version` + `set_sheet_visibility('public')` gain a verification check at the identity / verification step. |
| 3 | A new publication becomes the current version; older versions are **not deprecated automatically** and stay readable under the access rules. | Already the behaviour of `publish_sheet_version`; deprecation stays a manual act. |
| 4 | Official sheets are **platform-owned**, administered by authorised accounts. | Already the model: `creator_user_id = null`, `is_official = true`, platform admins edit. |
| 5 | Name anatomical findings apart from the observations typed during a report. | Finding category kind `observation` renamed **`consultation_reason`** (`dysfunction` / `consultation_reason` / `anamnesis` / `custom`). The report-side object keeps the name Observation. |
| 6 | Server-side validation and integrity for every publication; the frontend is never a security boundary. | SQL already re-checks references, sizes and species. The full shape check (Zod) moves server-side before community publication: plpgsql shape rules or an Edge Function gate, decided at the community step. |
| 7 | Account deletion handles dependencies and transfers explicitly (RGPD); no dependency may block the erasure of personal data forever. | Retention step (§16): published versions get their `created_by` / `published_by` anonymised through a dedicated system path (the immutability guard will allow that single transition), personal sheets are transferred or archived, `creator_user_id` keeps `on delete restrict` only as the backstop that forces the explicit path. |
## 6. Official equine sheet: import (Step 4b) and curation (Step 4c)
`packages/anatomy` holds a deterministic pipeline (`pnpm import:equine`)
that reads the historical files kept under
`supabase/seed/anatomical-sheets/equine/legacy-sources/` (`Horse.svg`,
`Horse_head.svg`, `pathologies.json`, `vertebrae.ts`, never edited), then the
authored curation files, and writes under
`supabase/seed/anatomical-sheets/equine/`:
| Folder | Nature | Content |
| ---------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy-import/` | generated baseline | canonical `document.json`, `legacy-id-map.json` (every legacy `data-anno-id`, category slug and view key → new id), `assets.json` + byte-identical SVG copies, `IMPORT-REPORT.md` (French, for the osteopath: volumes, mappings, anomalies). No SQL. |
| `curation/` | authored, committed | `references.json` (the references registry) and `changes.json` (the changeset) |
| `draft/` | generated working revision | curated `document.json`, `assets.json` + `assets/horse.svg`, `sheet-ref.json` (sheet id, null version id, sha256 of the document), `report-migration-map.json` (legacy ids and finding paths → the draft, for Report v2 imports), `CHANGELOG.md`, `REVIEW-REPORT.md`, `review/annotations-<view>.svg` (before/after drawing per view), `review/app-<view>.svg` (the application's own rendering), `equine_draft.sql` |
Changeset (`packages/anatomy/src/curation/schema.ts`): each change has an
id `CHG-nnn`, a level (A demonstrated error, B supported improvement, C
uncertain: a `question` is then required), a kind (correction,
terminology, translation, restructure, enrichment, reference, geometry,
removal, technical), a FR/EN title, a French rationale, the
`reference_ids` it relies on (declared in `references.json`), a priority and
ops: `set` (dot field path, `scope: subtree` on findings), `rename` (every
link follows: annotations, views, citations), `add`, `remove`, `move`,
`cite`. Targets are strings: `document`, `region:<code>`, `reference:<id>`,
`category:<id>`, `view:<id>`, `annotation:<id>`, `zone:<id>`,
`finding:<zone>/<category>[/<node>…]`. `needs_confirmation` is derived (B
and C). Any op that cannot apply as written, and any integrity error left at
the end, stops the run; every elementary edit is a CHANGELOG row.
Asset cleaning: both legacy files carry the same drawing, so the draft keeps
one, `horse.svg`, with every element carrying `data-anno-id` removed (the
markers are document data now); the head view has no asset and a
`view_box` (`60 100 500 380`) cropping it. This step is the reserved change
`CHG-000`, listed like the others.
Review drawings: `review/annotations-main.svg` and `review/annotations-head.svg`
draw the cleaned anatomy with every curated annotation (blue unchanged,
green moved or added, red dashed = previous position or removed), ids as
labels, framed on the view's box. Pure data generated by the same command,
readable in a browser; the PNG renders of the review are made by the
operator (ImageMagick) and are not committed.
Step 4c content (2026-10-10, `curation/changes.json`, 44 changes + CHG-000,
48 references): research-backed audit of the legacy data (NAV 2017, Sisson,
Spoormakers 2021, Degueurce 2004, Dyson & Pollard 2023, Code rural R. 243-6 /
R. 243-8, ECOP glossary…). Level A fixes: sphenoid zone restructured (it
duplicated the SSB tree), sutures absent in the horse removed, FR grammar,
NAV terms (caudal vertebrae, thoraco-lombaire, atlanto-occipitale,
supra-/infra-épineux, fibularis tertius), vertebral ranges (T 17–19, L 5–6,
Cd 15–21, no fixed 18), 62 descriptions translated, view and document
labels. Level B (integrated, `to_confirm`): ten annotation points moved
onto the drawn structures (hip ↔ sacroiliac swap, C7-T1 / T18-L1 / L6-S1
onto the column, skull points), carpus zone + point added, veterinary red
flags on the distal joints, legal disclaimer anchored on the articles,
osteopathic-model status written on the sacral, Fryette and intra-osseous
nodes, pain-behaviour descriptions. Level C (questions, data kept): SSB
patterns, sacral lateralization, NSR, accessory motions, sesamoid zone,
"charnière", "fixation", two-tier referral, duplicate reasons. Nothing is
published; the professional review starts from `REVIEW-REPORT.md` §10.
11 changes carry a question. The applier enforces the review rule: after a
level B or C change, every finding, finding category and annotation it
touched is left at `to_confirm` (recorded in the CHANGELOG), and an explicit
`reviewed` in such a change throws.
Head view after the single-asset switch (checked 2026-10-10): the `head`
detail view still exists (`parent_view_id: main`, opened by `head-trigger`),
keeps its 9 annotations with the same ids (parietal, frontal, occipital and
hyoid at their legacy position, the five others moved by CHG-044), and is
rendered as the `view_box` crop of the shared drawing. `svg_asset_id` stays
nullable per view, so a future revision can give any view its own drawing
again (CHG with `set view:<id>.svg_asset_id`), nothing in the model assumes
one asset.
Status semantics: technical integrity (zero issue) is not anatomical or
clinical validation. `inherited` = taken over from the legacy catalog
without review; `reviewed` = checked against a cited source by a level A
change; `to_confirm` = changed or added on documented grounds, awaiting the
partner osteopath. The draft is the reference draft of the application until
a platform admin publishes it after that review (REVIEW-REPORT §10, 11 open
questions; the legal scope text must be re-read on the consolidated
Légifrance articles first).
Known limit of migration 20261010100000: it tightens the CHECK to
`document_schema_version = 2` without rewriting stored rows, so it fails on a
database that still holds a schema 1 draft (a dev database seeded before Step
4c). It is safe with `db reset`; before any database with real data, write a
data migration that lifts stored documents to the current schema, then
tightens the CHECK (BLK-008). Future schema bumps follow that order.
Report migration map (Step 5): `draft/report-migration-map.json` replays the
applier's rename, move and removal records over every node of the legacy
baseline (792 nodes: 571 identical, 180 renamed or moved, 7 re-homed under
another category when the match is unique, 34 removed = `null`), maps the 27
legacy `data-anno-id` to annotation ids with the legacy names, and the `head`
detail key to the view. `migrateReportV2ToV3` (packages/domain) reads it; a
report keeps what the map cannot place, flagged `unresolved`.
Annotation colour (Step 5, additive, schema_version stays 2): `annotations[].color`
overrides `categories[].color` for the marker drawn by the application
(docs/ANNOTATION-RENDERING.md); the curation changeset CHG-045 carries the
legacy colours.
Seed: `equine_draft.sql` is idempotent and converging. On a fresh database
it inserts the sheet, the cleaned asset row and the draft through
`private.insert_sheet_draft`; when the sheet's only version is a draft
whose content differs, it replaces that content in place. It never touches
a published row and never publishes.
Rules of the import:
- ids are explicit and stable: annotation id = catalog zone key when FR and
EN names match exactly (26 / 26), finding zone id = catalog key, views
`main` and `head`, trigger `head-trigger`; nothing matches by label at
runtime;
- no medical correction in the import (only the changeset changes content):
catalog ids and labels are kept verbatim
(`ssb-dysfunctions` under `sphenoid` included) and every doubt is an entry
of the report; only technical slugs (degraded category ids) are
normalised, and the report says so;
- no publication: the seed inserts a draft through
`private.insert_sheet_draft` (audited with a null actor) and never calls
`publish_sheet_version`; only a platform admin can publish it, after the
business review of `REVIEW-REPORT.md` (pgTAP 007 pins both);
- the source files live under
`supabase/seed/anatomical-sheets/equine/legacy-sources/`, are never edited,
and the application no longer reads them (it bundles the draft).
Storage: bucket `anatomical-sheet-assets` (private, SVG only, 20 MiB cap),
objects `<sha256>.svg`, read policy `anatomical_sheet_assets_read` through
`private.can_read_sheet_asset_object`: the asset row must be **confirmed**
(`uploaded_at`, set only by `confirm_sheet_asset_upload` with the service
role once the bytes are in the bucket) and either edited by the caller or
referenced by a non-draft version of a usable sheet. A hash a user registers
on their own sheet therefore opens nothing. No API writes (operator upload,
`SUPABASE.md` §3.1).