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