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 -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 |