11 KiB
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.
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.
1. The change under study (route A, decision T2)
Two optional keys on AnnotationCategory (crates/core/src/domain/sheet/schema.rs:219-228):
role?: "bone" | "joint" | "vertebra"
fill_opacity?: integer percent (range: decision 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.
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
roleand/orfill_opacity(every new sheet after U6, throughsheet.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 |
| 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 |
sheet.empty |
n/a | n/a | three role-bearing categories | REQUIRED U6 |
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 (rejected option) | 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 |
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 |
| 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 |
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 | REQUIRED U6 |
| 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
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):
- SQL: the round-withdrawal migration (contract
V1-2_ANATOMICAL_SHEETS.md:945-949). No verdict code is added, so no change tosheet_verdict_codes. - Worker image, built from the same commit as the app (
.gitea/workflows/release-images.yml:103-120). - Application.
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 |
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).