# 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/.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-.svg` (before/after drawing per view), `review/app-.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:`, `reference:`, `category:`, `view:`, `annotation:`, `zone:`, `finding:/[/…]`. `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:.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 `.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).