Files
faunosteo/docs/development/V1-2-6_UX_COMPATIBILITY.md
T

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 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
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):

  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.
  2. Worker image, built from the same commit as the app (.gitea/workflows/release-images.yml:103-120).
  3. 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).