docs(docs): V1-2.6 UX owner ratification recorded, independent checks

This commit is contained in:
bchanot committed 2026-11-05 19:06:48 +01:00
1 parent e10f167a6d
commit bd444d6906
6 files changed
+713 -273

No files matched your search

+84 -25
View File
@@ -1,26 +1,44 @@
# V1-2.6 UX redesign: old / new schema compatibility matrix
Status: PROPOSAL, 2026-11-05, audited at `f58cf23`, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`. Each cell states the outcome
the code gives today (VERIFIED, file:line) or the outcome the plan requires and must prove by a test (REQUIRED,
test in `V1-2-6_UX_TESTS.md`). Nothing here is proven by assertion alone.
Status: PROPOSAL, 2026-11-05, audited at `f58cf23`, revised after the independent review and after the owner's
answers of 2026-11-05 (T2/T3 ratified with conditions, T4 without residual gap, T5 historical preservation, T10
navigation type). Companion of `V1-2-6_UX_PLAN.md`. Each cell states the outcome the code gives today (VERIFIED,
file:line) or the outcome the plan requires and must prove by a test (REQUIRED, test in `V1-2-6_UX_TESTS.md`).
Nothing here is proven by assertion alone.
Only sub-step U6 changes the document model. Every other sub-step writes plain v2 documents through `sheet.edit`
and leaves every row of this matrix unchanged.
## 0. Direction of compatibility (owner, T2)
The change is compatible in one direction only, and these documents never call it full backward compatibility.
- Old to new: holds. The new core reads, writes and fingerprints every existing document as today (§2 to §6).
- New to old: does not hold. Once a document carries `role` or `fill_opacity`, the application, the worker and the
core of any commit before U6 refuse it (§5). Returning to the old application after the first such write is
impossible (§7). PDF archives are the exception by construction: the keys are stripped from every snapshot (T7),
so old archive readers keep reading new PDFs (§4).
## 1. The change under study (route A, decision T2)
Two optional keys on `AnnotationCategory` (`crates/core/src/domain/sheet/schema.rs:219-228`):
```text
role?: "bone" | "joint" | "vertebra"
fill_opacity?: integer percent (range: decision T3)
role?: "bone" | "joint" | "vertebra" (+ "navigation" if T10 option B is confirmed)
fill_opacity?: integer percent, 10 to 100 (T3)
```
Serde form required: `#[serde(default, deserialize_with = "js::present", skip_serializing_if = "Option::is_none")]`
and `ts(optional)`, the `LocalizedOptionalText` pattern (`schema.rs:162-180`). Absent = omitted on output; an
explicit `null` refused. No `SHEET_DOCUMENT_SCHEMA_VERSION` bump. If the keys were written as `null` when absent
(the `count_range` and annotation `color` precedent, `schema.rs:215-216`, `429-430`), every fingerprint, review
digest and R4 app-path digest would change: that serialisation is forbidden by this plan and pinned by tests.
and `ts(optional)`, the `LocalizedOptionalText` pattern (`schema.rs:162-180`). Absent = omitted on output, never
serialised as `null`; an explicit `null` refused on input; an absent key never filled with a default in the
validated document the fingerprint hashes (the layer applies its constants at render time). No
`SHEET_DOCUMENT_SCHEMA_VERSION` bump. If the keys were written as `null` when absent (the `count_range` and
annotation `color` precedent, `schema.rs:215-216`, `429-430`), every fingerprint, review digest and R4 app-path
digest would change: that serialisation is forbidden and pinned by tests.
If T10 option B is confirmed, the automatic access adds, on demand, one internal category
`cat-access` with role `navigation`: an ordinary `{id, name, color}` category for every reader before U6 once the
role is stripped (§4).
Document kinds used below:
@@ -39,14 +57,18 @@ Document kinds used below:
| Strict reading, new core | read | read | read | REQUIRED U6: parse every fixture, the seed, the oracles |
| Canonical writing, new core | as today | as today (keys omitted) | keys written | REQUIRED U6: re-serialise the seed, no `role`/`fill_opacity` text |
| Fingerprint `sha256-rfc8785-validated-v1` | unchanged | unchanged | new value, same construction | VERIFIED construction `fingerprint.rs:246-273`; REQUIRED: equine `12d78872…` and alias `27c7383c…` recomputed equal |
| BDR-068 (`v1` freezes construction and validation) | holds | holds | holds: same construction, no new `validate.rs` error, absent keys not defaulted | REQUIRED U6: construction code unchanged in the diff; issue lists equal on every fixture; pins above |
| Convention constant | unchanged | unchanged | unchanged (no bump under T2) | VERIFIED `check_declared` accepts v1 only, `fingerprint.rs:109-111` |
| Review digests (`general` holds categories) | unchanged | unchanged | `general` changes, change list reports `Category{id}` | VERIFIED `review.rs:96-124`, `210-216`, `375-378`; REQUIRED: seed digests unchanged |
| Size measure (2 MiB) | unchanged | unchanged | + about 16-20 B per key | VERIFIED `size.rs:21-42` |
| Validation (`validate.rs`) | unchanged | unchanged | unchanged (no new error; T4) | REQUIRED: same issues on every fixture before and after |
| Report issues (`sheet_report`, verdict only) | none new | none new | role disappeared vs base, duplicate role → `verification.validation.rules` | VERIFIED mapping `verdict.rs:277-296`; REQUIRED U6 |
| Edit refusals (role-bearing category) | n/a | n/a | refused remove / role change / duplicate / name change | REQUIRED U6, new kinds |
| Report issues (`sheet_report`, verdict only, draft only) | fire: no fixed categories | fire: no fixed categories | fire on a missing role, a duplicate role, a wrong name on a role-bearing category; mapped to `verification.validation.rules` | VERIFIED report on the draft `verdict.rs:188`, mapping `verdict.rs:277-296`; REQUIRED U6 (T4) |
| Edit refusals | n/a | giving a missing role allowed, with the fixed names written in the same update | refused: remove, role change or clear, duplicate, rename away from the fixed names, any `navigation` assignment; repairs: insert a missing fixed category, restore fixed names, clear a duplicate role | REQUIRED U6, new kinds (DECISIONS T4) |
| `sheet.empty` | n/a | n/a | three role-bearing categories | REQUIRED U6 |
The report issues firing on Old documents is intended (T4): an Old draft cannot pass verification until it carries
the fixed categories. Published versions are never re-judged by this rule (§5, release replay).
## 3. Rendering
| Artefact | Old | New-absent | New-present | Evidence |
@@ -59,11 +81,11 @@ Document kinds used below:
## 4. PDF and archives
| Artefact | Old | New-absent | New-present, snapshot stripped (T7) | New-present, snapshot carrying keys (rejected option) | Evidence |
| Artefact | Old | New-absent | New-present, snapshot stripped (T7) | New-present, snapshot carrying keys (no product writer) | Evidence |
|---|---|---|---|---|---|
| PDF highlight raster | unchanged | unchanged | fill unchanged (overwritten); stroke = category colour as today | same | VERIFIED `compose.rs:41-42`, `259-267` |
| Envelope snapshot categories | `{id,name,color}` | same | same (stripped) | carries keys | VERIFIED `lean_document` copies whole, `snapshot_rules.rs:160`; REQUIRED: strip in `lean_document` and at the export gate `pdf/write/input.rs:174-181`, `export.rs:27-37` |
| Snapshot gate, new core | accepts | accepts | accepts | accepts | REQUIRED U6 |
| Snapshot gate, new core (controlled widening, T2) | accepts | accepts | accepts | accepts exactly the two keys with the document reader's types and range; any other unknown key, `null`, unknown role or out-of-range opacity → `SnapshotRejection::Schema`, report kept | REQUIRED U6 |
| Archive reader at `f58cf23` (rollback build) | archive kept | archive kept | archive kept | `snapshot_rejected: Schema`, report kept | VERIFIED `read.rs:86-89`, `snapshot_rules.rs:225` |
| Frozen N-1 reader | read | read | read | `snapshotRejected 'schema'`, report kept, degraded alert | VERIFIED `n-1/domain/anatomical-sheet/schema.ts:65-72`, `n-1/domain/archive/envelope.ts:104-121`; REQUIRED: a New-present sheet fixture and harness whose PDFs pass the assertions of `n-1.reader.test.ts:178-196` (that test runs on the seed only) |
| ts-rs ↔ N-1 type test (assignability, `toMatchTypeOf`) | green | green | green with `ts(optional)` on both keys | green with `ts(optional)` (a type test cannot see runtime stripping) | VERIFIED `contracts.types.test.ts:53-61`; the runtime proof is the N-1 fixture row above |
@@ -79,11 +101,15 @@ Document kinds used below:
|---|---|---|---|---|
| `check_document_structure` | pass | pass | pass (category members never read) | VERIFIED `20261028110000_sheet_review_workflow.sql:411-441` |
| CHECKs `schema_known`, `schema_matches` | pass | pass | pass | VERIFIED `20261010100000:10-12`, `20261008110000:120-121` |
| `save_sheet_draft` | saves | saves a draft without roles; with the recommended non-regression check, refuses a save that removes or duplicates a role of the stored draft or renames its category | same | VERIFIED no category check today `20261028110000:593-623`; REQUIRED U6 pgTAP if the owner confirms (T4) |
| Status walk, disclaimer, group keys | unchanged | unchanged | unchanged | VERIFIED `20261028110000:150-215`, `20261101100000:107-181` |
| `sheet_verdict_codes` | unchanged | unchanged | unchanged: report issues map to the existing `verification.validation.rules`; SQL checks only top-level failure codes | VERIFIED `20261101100000:57-69`, `360-368`; `verdict.rs:277-296` |
| Rounds in flight when the rules change | n/a | n/a | withdrawn by the U6 migration (T4) | REQUIRED U6 pgTAP; contract `V1-2_ANATOMICAL_SHEETS.md:945-949` |
| Worker at `f58cf23` (old image) | verdict as today | verdict as today | definitive `verification.integrity.document` (draft) or `.base` (base) | VERIFIED `verify.rs:93-97`, `verdict.rs:169-185`, `264-274`; `20261101100000:355-378` |
| Worker of U6 | verdict as today | same | reads; applies the report issues | REQUIRED `verify-e2e` with an image checked against `HEAD` |
| Core gate at completion (T4) | n/a | a passed verdict from a core older than U6 refused | same | REQUIRED U6 migration and pgTAP; `verified_with` today `faunosteo-core 0.1.0` for every core (`verdict.rs:164-166`, `Cargo.toml:10`), so a U6 marker is added |
| Rounds in flight when the rules change | rounds of draft versions withdrawn by the U6 migration; the approved round of each published version stays approved (`20261028110000:102-104`, `704-705`) | same | same | REQUIRED U6 pgTAP; contract `V1-2_ANATOMICAL_SHEETS.md:945-949` |
| Worker at `f58cf23` (old image) | verdict as today, without the fixed-category rule (refused by the core gate) | same | definitive `verification.integrity.document` (draft) or `.base` (base) | VERIFIED `verify.rs:93-97`, `verdict.rs:169-185`, `264-274`; `20261101100000:355-378` |
| Worker of U6 | verdict with the fixed-category rule: fails until the draft carries the fixed categories | same | reads; passes when the fixed model holds | REQUIRED `verify-e2e` with an image checked against `HEAD` |
| Approval and publication | need a verdict on the current revision and an approved round on it; U6 adds the declared check `private.sheet_fixed_categories_ok(content)` at both | refused without the fixed categories | pass when the fixed model holds | VERIFIED `20261028110000:984-990`, `1028-1072`; REQUIRED U6 pgTAP (T4, O22 amended at U0) |
| Release replay (contract §15) of published versions | read, fingerprint, validation, drawings | n/a | n/a | REQUIRED: the replay filters the `category.fixed.*` issue family, so a published version is never judged by the submission rule (the historical equine version has no roles, T5) |
| App at `f58cf23` after rollback | reads | reads | `invalid_document`: the draft cannot open | VERIFIED `preview.rs:150-151` |
| Published versions | immutable | immutable | immutable: cannot be edited back | VERIFIED `20261028110000:274-292` |
@@ -91,32 +117,65 @@ Document kinds used below:
| Case | Outcome | Evidence |
|---|---|---|
| Draft saved before U6, opened after | read as New-absent | REQUIRED U6 |
| Draft saved before U6, opened after | read as New-absent; verification fails until the fixed categories are added (repair action, T4) | REQUIRED U6 |
| Draft stripped of its roles by a direct save or an older tab | refused at save if the owner confirms the non-regression check; otherwise saved, shown with the issue and the repair; in both cases no round opens and no publication | REQUIRED U6 (T4) |
| Recovery copy (sessionStorage) taken before U6, restored after | document text read by the same strict reader | VERIFIED storage `recovery.ts:10-57`; REQUIRED U6 |
| Recovery copy taken after U6, restored by a rolled-back app | refused like any `invalid_document`; the copy is kept, not deleted | REQUIRED: test that a refused copy is not purged |
| Undo history across the U6 release | history is per page session, never persisted | VERIFIED `undo.ts`, `editorLoad.ts:136-152` |
## 7. Deploy order and rollback
## 7. Deploy order, write lock and rollback
This section is the single statement of the order; the plan and the risk register point here.
Order for any environment, for U6 and U9 (and any later change of the reader, the rules, the caps or the
fingerprint):
Order for any environment, for U6 and the curves lot (and any later change of the reader, the rules, the caps or
the fingerprint):
1. SQL: the round-withdrawal migration (contract `V1-2_ANATOMICAL_SHEETS.md:945-949`). No verdict code is added, so
no change to `sheet_verdict_codes`.
1. SQL: the U6 migration, which withdraws the rounds of draft versions in `verifying`, `open`, `approved` (contract
`V1-2_ANATOMICAL_SHEETS.md:945-949` says « every round »; the approved round linked to each published version
stays approved, T4) and adds the core gate, the rules epoch, the publication check and, if confirmed, the save
check (T4). No verdict code is added, so no
change to `sheet_verdict_codes`.
2. Worker image, built from the same commit as the app (`.gitea/workflows/release-images.yml:103-120`).
3. Application.
Functional write lock (T4): the U6 migration exposes a rules epoch (read-only RPC); the application writes no key
and creates no new-model sheet until it reads that epoch, so an application deployed too early keeps writing plain
v2. SQL first is mandatory: only the orders that start with SQL fail closed (an old worker's passed verdicts
refused by the gate, the publication check refusing a draft outside the fixed model). Worker before SQL leaves
rounds already `approved` on old verdicts publishable until the U6 migration lands; that is why SQL goes first. U6 runs on the sandbox only until the owner decides
otherwise. Before U6 reaches any environment beyond the throwaway sandbox: the read-only count of path geometries (T16) and, for production,
the 0.1.0 reader check below.
Rollback:
| From → to | Possible | Limit |
|---|---|---|
| Any frontend-only sub-step (U1, U3, U4, U7) | yes | none: no document changes form |
| U2, U5 (additive read-only core value and queries) | yes | documents written are plain v2 |
| U6 → before U6, no New-present document exists | yes | none |
| U6 → before U6, a New-present document exists (any sheet created after U6) | **no** | drafts unreadable by the old app (`invalid_document`) and the old worker (`integrity.document`); published rows immutable; migrations forward-only (`docs/development/SUPABASE.md:595-603`). Same class as RR-2; recorded as a release-readiness item (id reconciled with develop) |
| U9 → before U9 | yes | paths go back to display only; documents stay plain v2 |
| U6 → before U6, no New-present document exists | yes | app, worker and gate go back together, the gate lowered by a new forward migration; an old worker under the U6 gate sees every passed verdict refused, so no round opens (fails closed) |
| U6 → before U6, a New-present document exists (any sheet created after U6) | **no: point of no return** | drafts unreadable by the old app (`invalid_document`) and the old worker (`integrity.document`); published rows immutable; migrations forward-only (`docs/development/SUPABASE.md:595-603`). Same class as RR-2; recorded as a release-readiness item (id reconciled with develop) |
| U6 application alone → before U6 | no in practice | the old `sheet.empty` creates sheets with `categories: []` (`create.rs:14-35`), which the U6 worker always fails and the old editor cannot repair |
| U6 worker alone → before U6 | no | the gate refuses every verdict, the worker reports `verdict_refused` (`verify_job.rs:325-329`), which closes the round at once (`20261101100000:87-90`): a full review outage |
| Curves lot → before it | yes | paths go back to display only; documents stay plain v2 |
Before any production release carrying U6: read the 0.1.0 reader and record its behaviour on New-present snapshots
(NOT VERIFIED today), and run the release replay of published versions (contract §15).
## 8. Proof obligations before the write lock is lifted (owner, T2)
Each line is green and reviewed (fresh verifier) before any document carrying a key is written outside a test.
Tests in `V1-2-6_UX_TESTS.md` U6.
| Area named by the owner | Proof |
|---|---|
| Fingerprints | equine `12d78872…` and alias `27c7383c…` recomputed equal; every seed review digest equal to its pre-U6 pin; `sheet_fingerprint.rs`, `r5_6_switch.rs`, `characterisation_serde_tolerance.rs` green unchanged; a New-present document hashed twice gives one value |
| Rust | both keys round-trip; absent keys not written; explicit `null`, unknown role and out-of-range opacity refused; positional-array and one-key-map shapes handled as decided at U6; `validate.rs` issue lists equal before and after on every fixture; rules and refusals of T4 |
| SQL | U6 migration: draft rounds withdrawn with the reason, published versions' rounds still approved, core gate refusing an older `verified_with`, rules epoch exposed, publication and approval refused outside the fixed model, save non-regression if confirmed; `up upgrade` from the current migration set; `types --check`; publication refused without a current passed U6 verdict |
| PDF | `lean_document` and the export gate strip both keys; PDF goldens and R4 digests unchanged; a New-present sheet's PDF exported and reopened (archive kept) |
| Worker | image rebuilt from `HEAD`; `verify-e2e` with a New-absent draft (fails on the fixed-category rule), the same draft once converted, which then carries roles (passes), and a sheet created by the U6 `sheet.empty` (passes) |
| N-1 reader | New-present fixture and harness: PDFs pass `n-1.reader.test.ts:178-196`; `contracts.types.test.ts` green; frozen copies unchanged in the diff |
| R3 / R4 | R3 trees equal on every Old and New-absent input; oracles and goldens unchanged (`git diff --stat` empty on their paths); R4 digests unchanged |
| BDR-068 | construction code of `fingerprint.rs` unchanged in the diff; validation unchanged (Rust line above); no default filled for an absent key, proven by the fingerprint pins (a filled default would change them) |
| Snapshot widening | the bounded acceptance of §4 (exact keys, types, range; every other case `Schema`, report kept) |
| Flipped suites | every existing test that expects a passed verdict or an `open` round on a role-less document (`sheet_verdict.rs:39-52`, `80-90`; `sheet-verification.sandbox.ts:27`, `209-211`, `373`; worker fixtures and `tests/verify_loop.rs`) moved to converted in-memory copies, each change mapped; seed unchanged |
| One-way compatibility | the rollback-build rows of §4 and §5 re-checked on a New-present fixture; this document's §0 and §7 reviewed against the final code |