docs(docs): consolidate V1-2 contract with ratified O1-O23, open AR-1
This commit is contained in:
1 parent
397d6007b4
commit
7fec2ce86f
7 files changed
+1621
-646
No files matched your search
@@ -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 |
|
||||
|
||||
Reference in new issue
Block a user