docs(docs): V1-2.6 UX owner ratification recorded, independent checks
This commit is contained in:
1 parent
e10f167a6d
commit
bd444d6906
6 files changed
+713
-273
No files matched your search
@@ -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 |
|
||||
Reference in new issue
Block a user