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

19 KiB

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

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