# V1-2.6 UX redesign: old / new schema compatibility matrix 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) and the brief « Autorisation U0 uniquement » (T4 SQL checks approved, T5 defaults, T10 option B; BDR-101). 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" | "navigation" (navigation: T10 option B, ratified) 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, 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. Under T10 option B (ratified, BDR-101), 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: - **Old**: any document saved or published before U6 (equine historical, equine working copy, sandbox sheets, seed, oracles, PDF snapshots). - **New-absent**: a document handled by the new core that carries neither key (every old document re-saved, any sheet whose editor never set them). - **New-present**: a document carrying `role` and/or `fill_opacity` (every new sheet after U6, through `sheet.empty`; any edited category). ## 2. Core readers and writers | Artefact | Old | New-absent | New-present | Evidence | |---|---|---|---|---| | Strict reading, current core (before U6) | read | read | `invalid_shape` / `invalid_document` / `invalid_sheet` | VERIFIED `schema.rs:4-6`, `219-228`; `ops.rs:121-124`, `175-190`; `preview.rs:150-151`; `facade.rs:52-58` | | 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, 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 | |---|---|---|---|---| | Layer (practitioner and editor canvas) | identical | identical (constants 0.65 / 0.5 / 0.3 / 0.06) | point twin and zone fill use `fill_opacity`; strokes and triggers unchanged | VERIFIED constants `layer.rs:94`, `242`, `297-315`; REQUIRED: R3 trees equal | | R3 oracles `crates/core/tests/oracles/r3/{layer,highlight}.json` | pass | pass | not used (frozen inputs) | VERIFIED tree comparison `tests/common/svg_tree.rs:12-37`; `anatomy_layer.rs:54-85`; `anatomy_compose.rs:60-103` | | Canvas goldens `apps/app/tests/fixtures/goldens/r3/canvas.*` | pass | pass | pass while the seed carries no key | VERIFIED `anatomy_compose.rs:119-140`; `anatomy_canvas_op.rs:27` reads the seed | | Selected state (CSS) | accent at 0.85 | same | same: overrides any category opacity | VERIFIED `apps/app/src/styles/index.css:14` | | Marker isolation vectors | closed | closed | closed: the layer writes only `fill-opacity` on its own elements | VERIFIED `svg_marker_isolation.rs:30-53`, `228-257`; REQUIRED: suite green | ## 4. PDF and archives | 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 (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 | | `release/0.2.0` (never released, TypeScript reader identical to N-1) | read | read | read | snapshot rejected, report kept | VERIFIED branch tip `f8d9425`, `CHANGELOG.md:9-14` | | 0.1.0 (production faunosteo.com) | NOT VERIFIED | NOT VERIFIED | NOT VERIFIED | NOT VERIFIED | to read before any production release | | R4 digests, cargo and wasm paths (frozen R3 envelopes) | unchanged | unchanged | unchanged | unchanged | VERIFIED `pdf_serialize.rs:67`, `124-140`; `pdf-export.test.ts:163-184` | | R4 digests, app path, and step6 goldens (built from the bundled seed) | unchanged | unchanged | unchanged while the seed carries no key | changed | VERIFIED `pdf.goldens.test.ts:184-229`; `helpers/sheet.ts:19-20` | | Old bilan PDFs (envelope v1, Report v2/v3) | read and reproduced | same | same | same | rule kept: an archive reader never drops a version | ## 5. Server | Artefact | Old | New-absent | New-present | Evidence | |---|---|---|---|---| | `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 approved declared check, refuses a save where a role is carried twice, a role-bearing category lacks its fixed names or a role of the stored draft is lost | same | VERIFIED no category check today `20261028110000:593-623`; REQUIRED U6 pgTAP (T4, contract §12.2) | | 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` | | 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 §6.4 (worded at U0) | | 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` | ## 6. Old drafts and local copies | Case | Outcome | Evidence | |---|---|---| | 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 by the approved declared check (T4, contract §12.2), the stored draft unchanged; a draft that never carried roles still saves and is 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, 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 the curves lot (and any later change of the reader, the rules, the caps or the fingerprint): 1. SQL: the U6 migration, which withdraws the rounds of draft versions in `verifying`, `open`, `approved` (contract §6.4, worded at U0: rounds of draft versions; the approved round linked to each published version stays approved, T4) and adds the core gate, the rules epoch, the publication check and the save check (T4, contract §12.2). 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 the new model is activated on an environment, and before U6 or U8 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 | 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 refused when it duplicates, renames away or loses a role; `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 |