diff --git a/.claude/tasks/contracts/2026-11-05-v1-2-6-ux-ratification.md b/.claude/tasks/contracts/2026-11-05-v1-2-6-ux-ratification.md new file mode 100644 index 00000000..98a17c1d --- /dev/null +++ b/.claude/tasks/contracts/2026-11-05-v1-2-6-ux-ratification.md @@ -0,0 +1,69 @@ +# CONTRACT: V1-2.6 UX, owner ratification of the technical decisions recorded in the docs (2026-11-05) + +- REQUEST (owner brief « FAUNOSTEO — V1-2.6 UX — Ratification des décisions techniques », 2026-11-05): record the + owner's answers to T11, T16, T2/T3, T4, T5, T9/T10 and T12 in `docs/development/V1-2-6_UX_DECISIONS.md` and the + associated documents; update risks, dependencies, blocking criteria and tests; add the wasm measuring learning to + the learnings registry, its wording checked against the size test really in the repository; independent review; + exact verdict and remaining blocking points. Documentation only; stop at the final technical checkpoint. The + validated UX choices are not reopened. +- OWNER ANSWERS (summary of the brief): + - T11 approved: stop the complementary trials of the old UX; keep the anomalies and the untested items in + tracking; never declare the old V1-2.6 fully validated. + - T16 conditional deferral: defer curve handle editing only if the audit confirms that no existing curved + annotation and no journey available today needs it; guarantee exact geometry; prevent any destructive + conversion; record full curve editing in an identified future lot. + - T2/T3 agreement in principle, conditional on proofs: optional fields in schema v2, omitted when absent, never + serialised as null by default; fill opacity 10 to 100 %; controlled widening of the snapshot reader; + demonstrate effects on fingerprints, Rust, SQL, PDF, worker, N-1 reader, R3/R4 and BDR-068; document that the + old application cannot be returned to after the new fields are written; never call it full backward + compatibility. + - T4 no residual gap allowed: define the fixed-category checks in the core and at the appropriate server + boundaries for save and publication; do not enable writing the new model before the necessary checks exist; + progressive rollout or functional lock if needed. + - T5 historical preservation: keep ids, names, colours, particular annotations and fingerprints of the historical + equine versions; role adaptation only on a working copy; test the conversion without mutating the originals. + - T9 explicit choice when an SVG is replaced: keep positions only if the framing is compatible and the checks + pass; reposition when the operation is safely supported; cancel without any change; no approximate automatic + transformation. + - T10 automatic access: prefer a system navigation type distinct from the visible anatomical taxonomy; check the + existing schema constraints before choosing an internal id or category; never categorise it arbitrarily as Os, + Articulations or Vertèbres. + - T12: principle of one versioned copy kept; final legal text, source and validation still to be supplied; U7 + delivers no invented or unapproved normative text. + - Wasm learning: margin measured with the exact method of the budget test (Node gzipSync with the same + parameters), never a system gzip; reference 592 143 B for a limit of 600 000 B, margin 7 857 B; measure after + each core change; never raise the ceiling silently. +- ACCEPTANCE CRITERIA: + - K1 T11: DECISIONS records the approval; level 1 explicitly not declared validated; the anomalies and untested + items are listed with their sources and tracked in `.claude/tasks/TODO.md`. + - K2 T16: the audit evidence is present and exact (counts and file:line hold in the code); the guarantee of exact + geometry and of no conversion is written, with tests; any limit of the audit is stated rather than hidden; the + future lot is identified in TODO.md with its dependency rule; stale « U9 in V1-2.6 » wording is gone outside + historical records. + - K3 T2/T3: the serialisation rule, the 10-100 range and a bounded definition of the snapshot widening are + written; a proof is listed for each of fingerprints, Rust, SQL, PDF, worker, N-1, R3/R4, BDR-068; the + impossibility of returning to the old application is documented; no text calls the change full backward + compatibility (or equivalent) without that qualifier. + - K4 T4: checks are defined in the core and at server boundaries for both save and publication; no residual gap + is accepted silently (any remaining choice is stated as an open owner question); writing the new model is gated + on the checks being live (order or lock written). + - K5 T5: the preservation list, the working-copy-only rule and a conversion test that proves the originals + unchanged are written. + - K6 T9: the three actions with their conditions are written; no automatic or approximate transformation remains + anywhere in the docs. + - K7 T10: the schema constraints are checked with evidence before a choice; the choice is a navigation type or + internal category outside the visible taxonomy; nothing assigns the access to Os, Articulations or Vertèbres; an + unratified part is stated as open. + - K8 T12: U7 is blocked until the text, its source and its validation exist; no normative wording is written. + - K9 The learnings registry holds the wasm entry, written through `memory.sh`; its wording matches + `packages/core-wasm/tests/size.test.ts` (call, parameters, file, limit, comparison) and the figures. + - K10 Risks, dependencies, blocking criteria and tests are updated and consistent with K1-K9. + - K11 No contradiction across the five docs, TODO.md and BDR-100 (superseded recommendations are marked as + withdrawn, not left active). + - K12 Scope: the change set touches only the FILE SCOPE; no validated UX choice is reopened. +- FILE SCOPE: `docs/development/V1-2-6_UX_{DECISIONS,COMPATIBILITY,TESTS,RISKS,PLAN}.md`, `.claude/tasks/TODO.md`, + `.claude/memory/{learnings,decisions,journal}.md` (through `memory.sh`), this contract. +- OUT OF SCOPE: any change under `crates/`, `apps/`, `packages/`, `supabase/`, `scripts/`; SQL; worker; Supabase + DEV; contract amendments of U0 (`V1-2_ANATOMICAL_SHEETS.md`, the level-1 contract, `.claude/rules/`); merge; + deploy; V1-2.7; any implementation sub-step. +- ABANDON: if a criterion needs a change outside the file scope, stop and report. diff --git a/docs/development/V1-2-6_UX_COMPATIBILITY.md b/docs/development/V1-2-6_UX_COMPATIBILITY.md index 2f0b6df4..4a88c064 100644 --- a/docs/development/V1-2-6_UX_COMPATIBILITY.md +++ b/docs/development/V1-2-6_UX_COMPATIBILITY.md @@ -1,26 +1,44 @@ # 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. +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). 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" -fill_opacity?: integer percent (range: decision T3) +role?: "bone" | "joint" | "vertebra" (+ "navigation" if T10 option B is confirmed) +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; 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. +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. + +If T10 option B is confirmed, 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: @@ -39,14 +57,18 @@ Document kinds used below: | 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) | 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 | +| 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 | @@ -59,11 +81,11 @@ Document kinds used below: ## 4. PDF and archives -| Artefact | Old | New-absent | New-present, snapshot stripped (T7) | New-present, snapshot carrying keys (rejected option) | Evidence | +| 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 | accepts | accepts | accepts | accepts | REQUIRED U6 | +| 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 | @@ -79,11 +101,15 @@ Document kinds used below: |---|---|---|---|---| | `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 recommended non-regression check, refuses a save that removes or duplicates a role of the stored draft or renames its category | same | VERIFIED no category check today `20261028110000:593-623`; REQUIRED U6 pgTAP if the owner confirms (T4) | | 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` | +| 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 `V1-2_ANATOMICAL_SHEETS.md:945-949` | +| 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` | @@ -91,32 +117,65 @@ Document kinds used below: | Case | Outcome | Evidence | |---|---|---| -| Draft saved before U6, opened after | read as New-absent | REQUIRED U6 | +| 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 if the owner confirms the non-regression check; otherwise saved, 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 and rollback +## 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 U9 (and any later change of the reader, the rules, the caps or the -fingerprint): +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 round-withdrawal migration (contract `V1-2_ANATOMICAL_SHEETS.md:945-949`). No verdict code is added, so - no change to `sheet_verdict_codes`. +1. SQL: the U6 migration, which withdraws the rounds of draft versions in `verifying`, `open`, `approved` (contract + `V1-2_ANATOMICAL_SHEETS.md:945-949` says « every round »; the approved round linked to each published version + stays approved, T4) and adds the core gate, the rules epoch, the publication check and, if confirmed, the save + check (T4). 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 U6 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 | 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 | +| 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 non-regression if confirmed; `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 | diff --git a/docs/development/V1-2-6_UX_DECISIONS.md b/docs/development/V1-2-6_UX_DECISIONS.md index 2249e26d..d79b07fa 100644 --- a/docs/development/V1-2-6_UX_DECISIONS.md +++ b/docs/development/V1-2-6_UX_DECISIONS.md @@ -1,156 +1,324 @@ -# V1-2.6 UX redesign: technical decisions still needed +# V1-2.6 UX redesign: technical decisions -Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`; this is the -single table of what blocks what. The 11 UX choices and the direct SVG interactions validated by the owner on -2026-11-05 are not reopened. Each item is a technical question they leave open, with a recommendation. +Status: OWNER ANSWERS RECORDED, 2026-11-05 (brief « FAUNOSTEO — V1-2.6 UX — Ratification des décisions +techniques »). Companion of `V1-2-6_UX_PLAN.md`; this is the single table of what blocks what. The 11 UX choices and +the direct SVG interactions validated by the owner on 2026-11-05 are not reopened. Nothing here authorises code: U0 +(docs) and every later sub-step start only on a new explicit authorisation. ## Owner decisions -| Id | Question | Blocks | Recommendation | -|---|---|---|---| -| T1 | Fallback if the wasm budget is exceeded | U5 and U6 only if the measure exceeds 600 000 B; U9 certainly | `wasm-opt -Oz` as a pinned build tool, then a small D-R13 raise; the PDF split stays a separate track | -| T2 | Doctrine for optional category keys, and the owner's agreement to widen the snapshot reader | U6 | route A, no version bump, `v1` convention kept, rules amended | -| T3 | Opacity semantics | U6 | integer percent 10-100, point twins and zone fills, constants when absent | -| T4 | Tier of the fixed-category rules; residual gap on a first version | U6 | `edit.rs` refusals + `sheet_report` issues (existing verdict code), round-withdrawal migration; residual gap accepted and covered by review | -| T5 | Fixed categories of a new sheet: ids, names, default colours | U6 | `cat-bone`, `cat-joint`, `cat-vertebra`; Os / Bones, Articulations / Joints, Vertèbres / Vertebrae; equine colours | -| T6 | Equine working copy conversion | V1-2.8 | proposal below, decided at V1-2.8 | -| T9 | Replacing a crop by its own drawing | U5 | explicit choice when the `viewBox` differs, positions kept when equal | -| T10 | Category of an automatic access; sheet without category | U5 | the Joints category after U6; before U6 the first category; none → box unchecked | -| T11 | Fate of the level-1 owner trial | U1 | skip it; trial the redesign at U2 and U8 | -| T12 | Common text: source, versions, wording, responsibility | U7 | versioned module; wording supplied and validated by the owner | -| T14 | Multi-tab notice | none (follow-up) | not in V1-2.6; track as a follow-up | -| T15 | Header « Annuler » next to form « Annuler » | none | keep the label; accessible name « Annuler la dernière modification » | -| T16 | Curve handle editing in V1-2.6 | U9 | defer to the lot that first lets a path enter a document | -| T17 | Vertebral regions entry when no category has the vertebra role | U6 | keep a « Régions vertébrales » entry in the Annotations panel in that case only | +| Id | Question | Owner answer (2026-11-05) | State | Blocks | +|---|---|---|---|---| +| T1 | Fallback if the wasm budget is exceeded | not asked this round; measuring rule recorded (LRN-118) | open, used only if a measure exceeds 600 000 B | U5, U6 if a measure exceeds | +| T2 | Optional category keys; widening of the snapshot reader | agreement in principle, conditional on the proofs | ratified with conditions (§ T2 and T3) | writing the keys (U6 write lock) | +| T3 | Opacity semantics | integer percent from 10 to 100 | ratified with T2's conditions | U6 | +| T4 | Fixed-category checks | no residual gap; checks in the core and at the server boundaries of save and publication; nothing written before they are live | ratified; design below; the two declared SQL checks (save non-regression, publication) to confirm | U6 | +| T5 | Equine history; categories of a new sheet | historical preservation mandatory; roles on a working copy only; conversion tested without mutating the originals | ratified for the history; new-sheet ids, EN names and colours still to ratify | U6 (defaults), V1-2.8 | +| T6 | Equine working copy conversion | not asked | open, decided at V1-2.8 under T4 and T5 | V1-2.8 | +| T9 | Replacing a crop view's drawing | explicit choice: keep positions, reposition, cancel; no approximate automatic transformation | ratified; design below | U5 | +| T10 | Automatic access to a detail view | system navigation type distinct from the visible taxonomy; schema checked first; never Os, Articulations or Vertèbres | principle ratified; internal category to confirm | automatic access (moved to U6) | +| T11 | Fate of the level-1 owner trial | approved: old-UX trials stopped; anomalies and untested items tracked; level 1 not declared validated | ratified | none | +| T12 | Common text | principle of one versioned copy kept; legal text, source and validation to be supplied | principle ratified; text missing | U7 | +| T14 | Multi-tab notice | not asked | open, follow-up | none | +| T15 | Header « Annuler » wording | not asked | open | U1 (accessible name and tooltip) | +| T16 | Curve handle editing | deferral only if the audit confirms it; exact geometry; no destructive conversion; identified future lot | ratified: deferred to the curves lot | none in V1-2.6; the database count before U6 or U8 reaches any environment beyond the throwaway sandbox | +| T17 | Vertebral regions entry without a vertebra role | not asked | open | U6 | ## Implementer decisions (recorded at U0, no owner question) | Id | Decision | Reason | |---|---|---| | T7 | Strip `role` and `fill_opacity` from every envelope snapshot, at `lean_document` and at the export gate | the PDF needs neither; the only alternative breaks N-1 reading of new PDFs | -| T8 | Path ops (U9) compute on the written decimal digits; output precision = max(input precision, 2 decimals for a user move) | keeps « no other point moves » and exact round trips | +| T8 | Path ops (curves lot) compute on the written decimal digits; output precision = max(input precision, 2 decimals for a user move) | keeps « no other point moves » and exact round trips | | T13 | No sub-branches: commit in place on `feature/v1-2-anatomical-sheets`, rollback by reverting a sub-step's commits | the gitflow lib branches only from develop and `finish` merges into develop | | T18 | Handle cap per shape (constant fixed at U2 from the equine maxima with margin); above it, outline and a message | bounded DOM for oversized shapes saved directly | | T19 | Sliders and arrow moves commit on release, Enter or blur | BDR-050; the 8 MiB history holds about 20 equine documents | -## T1 · Wasm budget fallback +## T1 · Wasm budget fallback (open) -- Facts: the gate measures Node `gzipSync` level 9 (`packages/core-wasm/tests/size.test.ts:12-25`): 592 143 B of - 600 000 B, margin 7 857 B (measured 2026-11-05). Without curves the new core code is estimated at 4.5 to 13.5 KB. - The plan builds `annotations_in_rect` first and measures, then `remap_view`, then the U6 changes. +- Facts: the gate is `packages/core-wasm/tests/size.test.ts:12-25`: Node `gzipSync(bytes, { level: 9 })` on the + shipped build `packages/core-wasm/pkg/faunosteo_wasm_bg.wasm`, at most `COMPRESSED_BUDGET_BYTES = 600_000`. + Re-measured 2026-11-05 with that exact call: 1 569 864 B raw, 592 143 B, margin 7 857 B (build of 2026-11-04, + after the last core change `bbab0e6`). GNU `gzip -9` gives a different figure and is never used (LRN-118). + Without curves the new core code is estimated at 4.5 to 13.5 KB. The plan builds `annotations_in_rect` first and + measures, then `remap_view`, then the U6 changes. - Options if a measure exceeds the budget: - (a) `wasm-opt -Oz`: gain unknown; `wasm-opt` is not installed (`RUST.md:4054`), so it becomes a pinned tool in `scripts/wasm-build.sh`, the builder image and the release workflow. - - (b) raise the budget (D-R13) by the measured excess plus a margin: no work; a slightly slower first load. + - (b) raise the budget (D-R13) by the measured excess plus a margin. - (c) lighter URL check (about 23 KB): must keep `new URL()` equivalence. - (d) PDF code in a lazily loaded second module (about 55-60 KB): touches R4, the import worker, the CSP proof, trap recovery and the readers of user data; its own track with its own owner checkpoint, never a prerequisite. +- Rule: the budget is never raised silently. (b) is an owner decision taken on the measured figure; a sub-step whose + measure exceeds stops for T1. - Recommendation: (a), then (b) if still short. (d) only as a separate decision. -## T2 · Doctrine for optional category keys +## T2 and T3 · Optional category keys and opacity (ratified with conditions) -- Facts: `.claude/rules/schemas.md:9-11` (« additive optional fields keep it ») against `.claude/rules/sheet-model.md` - (« Document schema change → bump … No bump during V1-2 (BLK-008) ») and BDR-068 (`v1` freezes construction and - validation). Route B (v3) is excluded by contract §12.3 (`V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and needs a data - migration and a `save_sheet_draft` change. The snapshot reader (`assert_snapshot`, used by `archive/read.rs`) is a - reader of user data: CLAUDE.md requires the owner's agreement before widening it. -- Recommendation: route A as specified in `V1-2-6_UX_COMPATIBILITY.md` §1: an additive optional change of the v2 - document, no version bump, the `sha256-rfc8785-validated-v1` construction unchanged (existing values proven equal - by tests); `sheet-model.md` amended to say that an optional key omitted when absent is not a version change, with - the proof list. Route C (reserved ids, no opacity) contradicts choice 5. +- Owner answer: agreement in principle, conditional on proofs. Two optional keys in the v2 schema, omitted when + absent, never serialised as `null` by default; fill opacity an integer percent from 10 to 100; a controlled + widening of the snapshot reader. The effects on fingerprints, Rust, SQL, PDF, worker, the N-1 reader, R3/R4 and + BDR-068 are demonstrated; the impossibility of returning to the old application after the keys are written is + documented; this is never called full backward compatibility. +- Conditions, all met before any document carrying a key is written outside a test (the U6 write lock, T4): + 1. every proof of `V1-2-6_UX_COMPATIBILITY.md` §8 green and reviewed; + 2. the one-way compatibility written down (below, and COMPATIBILITY §0 and §7); + 3. the snapshot reader widened only as bounded below. +- Serialisation: `#[serde(default, deserialize_with = "js::present", skip_serializing_if = "Option::is_none")]` and + `ts(optional)`, the `LocalizedOptionalText` pattern (`schema.rs:162-180`). An absent key is omitted on output; an + explicit `null` is refused on input. The serde readers also accept a struct written as a positional array and an + enum value written as a one-key map (`RUST.md:3326-3346`): the U6 proofs cover these shapes for both keys. No `SHEET_DOCUMENT_SCHEMA_VERSION` bump. +- One-way compatibility, not full backward compatibility. Old to new holds: the new core reads, writes and + fingerprints every existing document as today. New to old does not: once a document carries a key, the + application, the worker and the core of any earlier commit refuse it (`invalid_document`, + `verification.integrity.document`). Returning to the old application after the first write is impossible: + published versions are immutable and migrations forward-only (COMPATIBILITY §7). +- Controlled widening of the snapshot reader (`assert_snapshot`, used by `archive/read.rs`). It follows from the + shared `AnnotationCategory` type and is bounded: it accepts exactly `role` and `fill_opacity` with the document + reader's types and range; any other unknown key, an explicit `null`, an unknown role or an out-of-range opacity + still gives `SnapshotRejection::Schema` with the report kept (the positional-array and one-key-map shapes above + included in the proofs); no version is dropped (envelope v1, Report v2 and v3, + sheet document v2); the frozen N-1 copies are never edited. Writers still strip both keys (T7), so no envelope the + product writes carries them. +- BDR-068. The `sha256-rfc8785-validated-v1` construction and the validation rules stay frozen: no new + `validate.rs` error (T4 rules live in `edit.rs` and `sheet_report`), and an absent key is never filled with a + default in the validated document the fingerprint hashes (the layer applies its constants at render time). Every + existing identity stays equal, pinned by tests; a document carrying a key gets a new fingerprint under the same + convention, like any content change. Aliases still come only from frozen historical documents. +- Opacity (T3): when present it drives the fill of point twins and of zones; when absent the current constants stay + (0.65 main and 0.5 detail for twins, 0.3 for zones), so existing renders are identical. Below 10 a marker becomes + invisible while the 4 px rules assume it visible. Detail triggers keep 0.06; the selected state keeps its accent + at 0.85 (`apps/app/src/styles/index.css:14`). Written first in `docs/ANNOTATION-RENDERING.md`. The layer writes it + as `fill-opacity`, which the PDF highlight overwrites: no PDF effect. +- Doctrine: `.claude/rules/sheet-model.md` amended at U0 (an optional key omitted when absent is not a version + change, with this proof list). Route B (schema v3, excluded by contract §12.3, `V1-2_ANATOMICAL_SHEETS.md:1779-1781`) + and route C (reserved ids without opacity, contradicts choice 5) stay excluded. -## T3 · Opacity semantics +## T4 · Fixed-category checks (ratified: no residual gap) -- Recommendation: integer percent from 10 to 100 (below 10 a marker becomes invisible on the drawing while the 4 px - rules assume it visible). When present it drives the fill of point twins and of zones alike; when absent the - current constants stay (0.65 main and 0.5 detail for twins, 0.3 for zones), so existing renders are identical. - Detail triggers keep 0.06. The selected state keeps its accent at 0.85 (`apps/app/src/styles/index.css:14`). - Written first in `docs/ANNOTATION-RENDERING.md`. The layer writes it as `fill-opacity`, which the PDF highlight - overwrites: no PDF effect. +- Owner answer: no residual gap allowed. The fixed-category checks are defined in the core and at the appropriate + server boundaries for save and publication; the new model is not written before the necessary checks are live; + a progressive rollout or a functional lock is used if needed. The earlier recommendation (issues relative to the + base, residual first-version gap accepted) is withdrawn. +- Property guaranteed: no review round opens and no version is published on a draft whose categories break the + fixed model, whoever wrote the draft (the editor, a direct `save_sheet_draft`, « Garder ma version », a tab + running an older bundle). Fixed model: each role `bone`, `joint`, `vertebra` carried by exactly one category, + and that category carries its fixed FR and EN names (T5). -## T4 · Tier of the fixed-category rules +| Tier | Check | Where | New code | +|---|---|---|---| +| Core, verdict | absolute rule on the draft, no base needed: missing role, duplicate role, wrong name on a role-bearing category; error issues of their own code family `category.fixed.*`, mapped to the existing `verification.validation.rules` | `sheet_report` on the draft (`verdict.rs:188`), mapping `verdict.rs:277-296` | Rust; no verdict code, no `validate.rs` error | +| Core, editor | giving a role writes the fixed FR and EN names in the same update; renaming a role-bearing category is allowed only to its fixed names; removing it, changing or clearing its role and a duplicate role are refused; `navigation` (T10 B) is never assignable by an edit; repair commands insert a missing fixed category, restore the fixed names and clear a duplicate role, so every state a direct save can write is repairable | `edit.rs` | Rust | +| Server, save | non-regression check (recommended): a save that removes or duplicates a role present in the stored draft, or renames its category away from the fixed names, is refused; drafts without roles (pre-U6, equine working copy) still save | U6 migration, `save_sheet_draft`, a second declared SQL check under O22 | SQL, pgTAP; owner confirmation | +| Server, verification | the worker computes the verdict with the core above; a round opens only on a passed verdict | `complete_sheet_verification` (`20261101100000_sheet_verification_jobs.sql:300-345`) | none | +| Server, core gate | a passed verdict computed by a core older than the U6 core is refused at completion, so an old worker (rollback, stale image, second instance) never opens a round | U6 migration, keyed on `verified_with` | SQL, pgTAP | +| Server, publication | a declared SQL check `private.sheet_fixed_categories_ok(content)` (each role once, fixed names) at approval and at publication, beside the existing status checks, so a worker defect cannot publish a draft outside the fixed model (the reason O22 keeps declared SQL checks, contract `V1-2_ANATOMICAL_SHEETS.md:1705-1711`, `20261028110000:146-149`); the existing preconditions stay (`verdict.missing`, `verdict.stale`, `:984-990`; approved round on the current revision, `:1028-1072`) | U6 migration, `decide_sheet_review`, `publish_sheet_version` | SQL, pgTAP; O22 amended at U0 | +| Server, rounds in flight | rounds in `verifying`, `open`, `approved` of draft versions withdrawn with the reason; the approved round linked to each published version stays approved | U6 migration (contract `V1-2_ANATOMICAL_SHEETS.md:945-949`) | SQL, pgTAP | -- Facts: edit refusals act only in the editor (`edit.rs:1-4`); a direct save is checked structurally only. A - `validate.rs` error would invalidate existing documents (fingerprint, snapshot gate). Issues added in - `sheet_report` (the `GEOMETRY_MISSING` pattern, `report.rs:17-19`) map to the existing - `verification.validation.rules` (`verdict.rs:277-296`), so no SQL code change. The contract requires a migration - withdrawing rounds in `verifying`, `open` or `approved` when the integrity rules change - (`V1-2_ANATOMICAL_SHEETS.md:945-949`). -- Options: (a) `edit.rs` refusals only; (b) (a) + report issues relative to the base (a role of the base must remain; - a role appears once) + the withdrawal migration. -- Residual in both: a first version has no base; a direct save, or « Garder ma version » from a tab running an older - bundle, can strip the roles before the first publication. It shows in the review of the `general` group. -- Recommendation: (b), consistent with O22, and the residual accepted. +- Save boundary: the earlier text left save fully permissive and cited BDR-043; the governing rule is O22 (contract + `V1-2_ANATOMICAL_SHEETS.md:1683-1711`), which allows a declared SQL check. An absolute check at save would lock the + equine working copy and every pre-U6 draft; the non-regression check above locks none of them and stops stripping + by a direct save, « Garder ma version » or an older tab at the source. Recommended; owner confirmation requested + for both declared SQL checks: the contract says today « No other rule is mirrored » + (`V1-2_ANATOMICAL_SHEETS.md:1711`), so O22 is amended at U0 only on that confirmation. +- Core gate detail: every core so far reports `faunosteo-core 0.1.0` (`verdict.rs:164-166`, workspace version + `Cargo.toml:10`), so the gate needs a marker that tells the U6 core apart: a core version bump (owner's call) or a + rules epoch added to `verified_with` (free text of at most 100 characters for SQL today). Chosen at U6, pinned by + pgTAP. +- Functional write lock: the U6 migration exposes the rules epoch (a read-only RPC); the application reads it and + writes no key and creates no sheet with the new model until the epoch is present: an application deployed too + early creates sheets through the plain v2 path (no categories, as today) and the repair adds the fixed ones later. Order SQL, worker, application (COMPATIBILITY §7), with SQL first + mandatory: only the orders that start with SQL fail closed. Worker before SQL leaves rounds already `approved` on + old verdicts publishable until the U6 migration lands; that is why SQL goes first. U6 stays + on the sandbox until the owner decides otherwise. +- Scope: the rule judges drafts submitted after U6, never a published version. The historical equine version has no + roles and stays as it is (T5); the release replay (contract §15) filters the `category.fixed.*` family, so it + checks published versions on reading, fingerprint, validation and drawings only. Consequences: the equine working + copy cannot pass verification until V1-2.8 converts it (T6), which is that lot's scope; the existing tests that + expect a passed verdict or an `open` round on a role-less document flip and move to converted in-memory copies + (`V1-2-6_UX_TESTS.md` U6), the seed itself unchanged. -## T5 · Fixed categories of a new sheet +## T5 · Equine history and the categories of a new sheet -- Recommendation: `sheet.empty` creates `cat-bone`, `cat-joint`, `cat-vertebra` (core-chosen, unlike the page's - `cat-<10 base32>` ids, `apps/app/src/editor/ids.ts:1-21`, so no collision); names FR « Os », « Articulations », - « Vertèbres », EN « Bones », « Joints », « Vertebrae »; roles `bone`, `joint`, `vertebra`; default colours, shown - as « Couleur d'origine » (board 07 A), taken from the equine categories: `#a41e65`, `#ff9500`, `#e100ff`. Names stay - stored (old readers show them) and the edit rules refuse changing them. +- Owner answer: historical preservation mandatory. The historical equine versions keep their ids, names, colours, + particular annotations and fingerprints; any role adaptation applies to a working copy only, and the conversion is + tested without mutating the originals. +- Untouched: the five equine categories (`articulations`, `os`, `charnieres-vertebrales`, `zone-colonne`, + `cadrans-du-crane`) with their ids, names and colours; the three own colours (atm and ssb `#ff8800`, hyoid + `#d507c4`); every annotation; the fingerprint `12d78872…` and the alias `27c7383c…`; every file under + `supabase/seed/anatomical-sheets/equine/` (`pnpm r5:import-equine --check` clean); the published historical + version (immutable, `sheet.historical_read_only`). +- Test: a conversion of an in-memory copy of the seed draft document (roles on the T6 categories) asserts before and + after that the seed bytes, the fingerprint, the alias and every review digest are unchanged, and that the copy + differs only in the converted categories (`V1-2-6_UX_TESTS.md` U6). +- New-sheet defaults, still to ratify (blocks U6): ids `cat-bone`, `cat-joint`, `cat-vertebra`, chosen by the core + (suffixes of 4 to 8 characters, so never a page id `cat-<10 chars a-z2-7>`, `apps/app/src/editor/ids.ts:1-21`); + names FR « Os », « Articulations », « Vertèbres » (validated on board 07, `docs/design/v1-2-6/ARBITRAGES.md:60`), + EN « Bones », « Joints », « Vertebrae » (proposal); default colours `#a41e65`, `#ff9500`, `#e100ff`, copied from the + equine categories (copying mutates nothing) and shown as « Couleur d'origine » (board 07 A). Names stay stored, so + old readers show them. ## T6 · Equine working copy conversion (V1-2.8) - Facts: five categories (`articulations` 12 annotations, `os` 2, `charnieres-vertebrales` 4, `zone-colonne` 5, `cadrans-du-crane` 5). `os` and `articulations` already carry the fixed names; `zone-colonne` is « Segments vertébraux / Vertebral segments ». Three own colours: atm and ssb `#ff8800`, hyoid `#d507c4`. +- Bound by T5 (working copy only, originals never mutated) and T4 (the copy passes verification only with the three + roles on categories carrying the fixed names). - Proposal: roles on `os`, `articulations`, `zone-colonne`; `zone-colonne` renamed « Vertèbres / Vertebrae » in the working copy only (id unchanged); the two other categories stay free; own colours kept (choice 11) unless the - business review decides otherwise. The historical sheet and the Git seed never change. + business review decides otherwise. Decided at V1-2.8. -## T9 · Replacing a crop by its own drawing +## T9 · Replacing a crop view's drawing (ratified) -- Facts: the seed head drawing has exactly the crop's `viewBox` and the full drawing's path data: keeping positions - is right for it. A remap is right only for a drawing re-based on another `viewBox`. -- Recommendation: V equal to R → positions kept, no question. V different → the dialog asks « Même repère : garder - les positions » or « Dessin recadré : transposer les annotations », no default selected; transposition is uniform - (`meet`), centred, annotations to confirm. Labels to confirm by the owner. +- Owner answer: an explicit choice when an SVG is replaced, with three actions: keep the positions, only if the + framing is compatible and the checks pass; reposition the annotations when the operation is safely supported; + cancel without any change. No approximate automatic transformation. The earlier recommendation (no question when + the `viewBox` equals the crop) is withdrawn. +- R (the view's crop rectangle) is written in the coordinates of the drawing the view shows today; V (the + candidate's `viewBox`) in the candidate's own. The core cannot check that the candidate was cut from the same + master or shows exactly region R: both actions rest on a premise the dialog states, and both fail closed. +- Two core calls (the cleaning output has no `viewBox`, `clean.rs:50-68`; the asset id exists only after + registration, `drawingUpload.ts:124-169`): + 1. Offer, before any upload: input = the document, the view id and the cleaned candidate text; the core reads V + from the candidate root and runs the frame checks on it; output = the actions offered, each with its reason. + 2. Batch, after the drawing is registered and held: input = the view id and the asset id; output = the + `sheet.edit` commands of the chosen action, committed as one undo entry under the geometry accept + (`issues.ts:123-175`). A refusal there leaves the document unchanged and a registered drawing that nothing + references, as today's refused attach (`drawingUpload.ts:195-196`). +- The dialog opens on every replacement of a crop view's drawing, before the upload, no action preselected: + - « Conserver les positions »: offered only when V equals R (the seed head drawing case); the dialog states the + premise « ce dessin utilise le repère de la vue parente ». Applied as today's attach (`attachToView`, + `drawingUpload.ts:184-192`); the view's annotations turn `to_confirm` (redrawn-view rule, `edit.rs:792-857`). + - « Repositionner les annotations »: offered only when V differs from R with the same aspect ratio (compared on + the values rounded to the editor's 0.01 grid; any other case refused, `remap.aspect`, never centred), no path in + the view (`remap.path`), no descendant crop (`remap.descendant_crop`), numbers in range. Premise stated: + « ce dessin montre exactement la zone de la vue ». One scale and one translation; numbers on the 0.01 grid; a + point pushed out of the frame by the rounding refuses the whole remap; every moved annotation turns `to_confirm`. + - « Annuler »: always offered; nothing is uploaded, the document and the history are untouched. +- An action that is not available stays visible, disabled, with its reason. A candidate without a `viewBox` gets + neither keep nor reposition, only « Annuler »: stricter than today's attach, which accepts it (stated in U5). +- Labels: the owner's French words above; EN « Keep positions », « Reposition annotations », « Cancel » proposed. -## T10 · Category of an automatic access +## T10 · Automatic access to a detail view (principle ratified) -- Recommendation: after U6, the Joints category (the equine access to « Tête » belongs to Articulations); before U6, - the first category of the sheet; a sheet without any category → the box is unchecked with the reason, the access - is placed later. Changeable in the properties. +- Owner answer: prefer a system navigation type distinct from the visible anatomical taxonomy; check the existing + schema constraints before choosing an internal id or category; never categorise this access arbitrarily as Os, + Articulations or Vertèbres. The earlier recommendation (the Joints category) is withdrawn. +- Constraints checked (2026-11-05): + - The navigation type exists: `detail_trigger` (`crates/core/src/domain/sheet/schema.rs:439-462`, « Navigation + only: a trigger opens a detail view and never carries findings »). + - It requires `category_id` (`schema.rs:449`), which must name an existing category: + `annotation.category.missing` is an error (`validate.rs:287-292`), and an error blocks the fingerprint, the + snapshot and publication. + - Snapshots copy annotations and categories whole (`lean_document`, `snapshot_rules.rs:141-165`): every trigger + reaches the PDF envelope and the frozen N-1 reader, whose schema requires `category_id`. + - Page ids are `-<10 chars a-z2-7>` (`ids.ts:1-21`); a stable id has 1 to 64 characters (`js.rs:158`). + - The catalogue shows a selected annotation's category name (`ZonePanel.tsx:45-48`); the layer colours a trigger + from its own colour or its category (`layer.rs:142-150`). +- Options: + - (A) `category_id` optional on `detail_trigger`. A required key becomes optional: the ts-rs type is no longer + assignable to the N-1 type (`contracts.types.test.ts:53-61` fails by construction), and a trigger without a + category in a snapshot makes N-1 drop the snapshot unless triggers are stripped from snapshots, which touches + the readers of user data again. + - (B) one internal navigation category, created by the core, outside the visible taxonomy: id `cat-access` (a + 6-character suffix, never a page id), role `navigation` (a fourth value of the T2 key), fixed names FR « Accès + aux vues détaillées », EN « Detail view access », colour `null`. Old readers and N-1 read it as an ordinary + category (the role is stripped from snapshots, T7). The editor lists it in no category panel and no picker; + only detail triggers use it (an edit refusal and a verdict issue for an observable annotation in it, and for a + second category with that role). +- Recommendation: (B). It needs the owner's confirmation: a fourth role value and an internal category go beyond + the T2 approval, and its names are visible to old readers. +- Effect on the plan: automatic access moves from U5 to U6 (it needs the role). U5 keeps the name proposal and the + overlap list. Until U6, « Ajouter un accès » (U4) asks the editor for the category as level 1 does: an explicit + choice by the editor, never an automatic one. Existing triggers keep their category (the equine « Tête » access + stays in `articulations`, T5); moving the working copy's access is a V1-2.8 question. +- Automatic creation (U6): only when the overlap list is empty; the view, its access and, if missing, the navigation + category inserted in one batch; otherwise the box is unchecked with the reason and the access is placed from the + view's menu. -## T11 · Fate of the level-1 owner trial +## T11 · Level-1 owner trial (ratified) -- Facts: level 1 is built and served for the trial (`V1-2-6_OWNER_TRIAL.md`); not tried yet. U1 and U2 replace its - tab structure and numeric journeys. -- Recommendation: skip the level-1 trial; keep its infrastructure (store, save, recovery, conflicts, upload, modes) - as the base; trial the redesign at U2 and U8. Level-1 criteria the redesign does not touch (C13 recovery, C14 undo - bound, C16 narrow read-only, C34, C41) stay in force and are re-tested. +- Owner answer: approved. Complementary trials of the old UX stop and the redesign preparation continues; the + anomalies and the untested items stay tracked; the old V1-2.6 is not declared fully validated. +- Level 1 (lots A to O, criteria C1 to C48): built and gated (`.claude/tasks/plans/2026-11-04-v1-2-6-checkpoint.md`), + never tried by the owner, NOT functionally validated. Its infrastructure (store, save, recovery, conflicts, + upload, modes) is the base of the redesign. The criteria the redesign does not touch (C13, C14, C16, C34, C41) + stay in force and are re-tested at U1 and U8. +- Tracked in TODO.md (level-1 line), from the checkpoint report, the execution ledger and the trial guide: + - owner manual trial: not run, stopped by this decision; + - a real second device on the LAN: not tested; + - editing specs at 375 px skipped (C16 waiver), and 8 admin journeys at 375 px skipped; + - worker-gated sandbox suite skipped (no worker by contract); + - the keyboard spec focuses programmatically (no Tab walk); + - free-path attach repair covered by automated tests only (no trial step); + - Safari iOS `beforeunload` unreliable (only « Enregistrer » protects work); + - LOW security items kept by the fresh auditor (checkpoint report, « Audits and reviews »: cleartext LAN trial + traffic including the TOTP enrolment key, allow list including tests and node_modules, first `hostname -I` + address as default trial host, template SQL in e2e helpers, trial gateway without a Host check, an unproven + sign-out copy-rewrite window); + - review minors m4, m6, m7, m8, m10 (execution ledger); + - path point correction (`.claude/tasks/plans/2026-11-04-v1-2-6-path-repair-core-proposal.md`, not built), now in + the curves lot (T16). -## T12 · Common text +## T12 · Common text (principle ratified, text missing) -- Recommendation: a versioned module in the application (id, version, FR, EN), changed only by a reviewed commit; - wording supplied and validated by the owner or a person the owner names; the editor shows « texte commun, - version n » and never presents it as veterinary or legal advice approved by the platform. U7 starts only when the - wording exists. Contract §7.4 amended at U0. +- Owner answer: the principle of one versioned copy is kept; the final legal text, its source and its validation are + still to be supplied; U7 delivers no invented or unapproved normative text. +- Design: a versioned module in the application (id, version, FR, EN), changed only by a reviewed commit; inserted + once into empty fields; the editor shows « texte commun, version n » and never presents it as veterinary or legal + advice approved by the platform. +- U7 is blocked until the owner supplies the FR and EN text, its source, and who validated it and when. The commit + that adds the text cites that record. Until then no such wording is written in the application, the dictionaries + or the docs; U7's tests use a fixture text marked as a test value, kept under `tests/`, never shipped. +- Contract §7.4 amended at U0 to state this, without any normative wording. -## T14 · Multi-tab notice +## T14 · Multi-tab notice (open) - Facts: no multi-tab detection exists; the server revision check and the conflict dialog prevent silent loss; the boards show no such notice. - Recommendation: out of V1-2.6, tracked as a follow-up. If kept later: heartbeat-based (a crashed tab never says goodbye), wording consistent with « Garder ma version ». -## T15 · « Annuler » wording +## T15 · « Annuler » wording (open, needed by U1) - Recommendation: keep the validated label; give the header button the accessible name and tooltip « Annuler la dernière modification » / « Undo the last change ». -## T16 · Curve handle editing +## T16 · Curve handle editing (ratified: deferred to the curves lot) -- Facts: no document of the project holds a path; no product path creates one; the validated guarantee « aucune - courbe convertie » is held by display-only paths and the C45 refusal; board 05 shows curves as « exemple d'une - autre fiche ». The three path ops are the plan's heaviest work (610 to 1 020 lines, 10 to 21 KB) and need a - certain size lever and a round-withdrawal migration. -- Recommendation: defer U9 to the lot that first lets a path into a document (package import, zones from drawing - shapes, or a curve drawing tool), keep its specification (`V1-2-6_UX_PLAN.md` §2 D) and keep C45 and the closed - `remap.path` refusal meanwhile. +- Owner answer: defer the curve handle editing only if the audit confirms that no existing curved annotation and no + journey available today needs it; keep geometries exactly; prevent any destructive conversion; record full curve + editing in an identified future lot. +- Audit (2026-11-05, at `e10f167`): + - Tracked documents: the seed draft holds 22 circles, 6 polygons, 0 paths; the legacy import 21 circles, 6 + polygons, 0 paths (`supabase/seed/anatomical-sheets/equine/{draft,legacy-import}/document.json`). The historical + sheet and its working copy derive from them. + - Journeys that write geometry: creation makes points and polygons only (`apps/app/src/editor/annotations/creation.ts:90-97`); + the editable geometries are circle and polygon (`geometryEdit.ts:9`, `34`); package import, zones from the + drawing's shapes and curve drawing are level 2 (contract §8.3, `V1-2_ANATOMICAL_SHEETS.md:1328-1338`). + - Journeys that meet a path: display by the core layer; the attach repair returns a path unchanged and keeps the + attach refused, document unchanged byte for byte (`repair.ts:55-69`, blocked ids `95-100`, C45, `editor-geometry.spec.ts:317`); + « Remplacer par un polygone » (`PropertiesPanel.tsx:138`, contract §8.3). + - Not inspected: the database contents of DEV and of the sandbox (docs-only brief, no query run). A path there can + only come from a direct RPC save or a test fixture. Before U6 or U8 reaches any environment beyond the throwaway sandbox, a + read-only count of path geometries in its drafts and published versions is run, by the owner or under an explicit authorisation; a + non-zero count reopens T16. +- Conclusion: the condition holds for every tracked document and every product journey; the deferral is adopted. +- Guarantee until the curves lot: + - a stored path keeps its `d` text byte for byte; no TypeScript parses it (C45); no operation moves, scales, + remaps, simplifies, samples or converts it; + - every operation that would have to change a path is refused with the document unchanged: attach repair (C45), + remap (`remap.path`), the U2 handle layer and zone move (a path gets no handle and no move); + - « Remplacer par un polygone » is the one way a path leaves a document: the editor draws a new polygon by hand, + one undo entry, published versions untouched. It replaces the curve by the editor's choice; nothing converts + it. It stays as ratified in contract §8.3 unless the owner removes it. +- Future lot « Courbes » (ex-U9): specification in `V1-2-6_UX_PLAN.md` §2 D, tests in `V1-2-6_UX_TESTS.md` + (« Curves lot »), with the path point-correction proposal. Recorded in TODO.md with its dependency rule: no + feature that lets a path enter a document (package import, zones from the drawing's shapes, a curve drawing tool) + ships before or without it. It needs a size lever (T1) and a round-withdrawal migration. -## T17 · Vertebral regions entry without a vertebra role +## T17 · Vertebral regions entry without a vertebra role (open, needed by U6) - Facts: board 09 opens the regions from the Vertèbres category; the equine working copy has no role before V1-2.8. - Recommendation: when no category carries the vertebra role, the Annotations panel keeps a « Régions diff --git a/docs/development/V1-2-6_UX_PLAN.md b/docs/development/V1-2-6_UX_PLAN.md index 86c1863d..77859735 100644 --- a/docs/development/V1-2-6_UX_PLAN.md +++ b/docs/development/V1-2-6_UX_PLAN.md @@ -1,15 +1,16 @@ # V1-2.6 UX redesign: technical implementation plan -Status: PROPOSAL for the owner, 2026-11-05. Nothing in this file authorises code. No application, Rust, SQL or -worker change is made before the owner approves this plan and the blocking decisions of -`V1-2-6_UX_DECISIONS.md`. Branch `feature/v1-2-anatomical-sheets`, worktree `/home/bchanot/Documents/faunosteo-v1-2`, -audited at `f58cf23`. +Status: PROPOSAL for the owner, 2026-11-05, revised the same day with the owner's answers to T2/T3, T4, T5, T9/T10, +T11, T12 and T16 (brief « V1-2.6 UX — Ratification des décisions techniques », recorded in +`V1-2-6_UX_DECISIONS.md`). Nothing in this file authorises code. No application, Rust, SQL or worker change is made +before the owner authorises U0 and then each sub-step explicitly. Branch `feature/v1-2-anatomical-sheets`, worktree +`/home/bchanot/Documents/faunosteo-v1-2`, audited at `f58cf23`. Companion files: | File | Content | |---|---| -| `V1-2-6_UX_PLAN.md` | This plan: inventory, sensitive points A to I, sub-steps U0 to U9 | +| `V1-2-6_UX_PLAN.md` | This plan: inventory, sensitive points A to I, sub-steps U0 to U8, curves lot (ex-U9) | | `V1-2-6_UX_COMPATIBILITY.md` | Old / new schema matrix: core, SQL, worker, PDF, snapshots, N-1, oracles, rollback | | `V1-2-6_UX_TESTS.md` | Test matrix per sub-step | | `V1-2-6_UX_RISKS.md` | Risks, dependencies, blocking points | @@ -74,7 +75,7 @@ Page-only, each ending in `sheet.edit` and judged by the core on commit (`issues header undo and redo; the references side panel; sidebar collapse; point move; point size slider (the page reads the radii present in the view, the core still refuses `marker_too_small`); polygon vertex drag; « + » on a segment; « − » on a vertex; zone move (mouse direct, touch mode); zone redraw keeping the old shape until validation; the -rectangle gesture that sets a detail view's `view_box`; « replace by a specific SVG » without remap; per-annotation +rectangle gesture that sets a detail view's `view_box`; the « replace by a specific SVG » dialog (page work; its offer comes from a new core call, U5, T9); per-annotation colour shown only when set, with « back to the category colour » (an `update` with `color: null`); keyboard alternatives; 44 px touch handles; the `pointerId` guard; a multi-tab notice if the owner wants one (T14). @@ -85,7 +86,7 @@ alternatives; 44 px touch handles; the `pointerId` guard; a multi-tab notice if | `sheet.annotations_in_rect` | name proposal of a detail view (choice 6), automatic access only without overlap | `PreviewSheet` op | 80-150 lines, 1.5-4 KB gzip | | `sheet.remap_view` | a crop view receiving a re-based drawing (point E) | `PreviewSheet` op returning `sheet.edit` commands | 120-250 lines, 2-5 KB | | per-view minimum visible radius | the red « minimum touchable » mark of the size slider (choice 3) | value in `PreviewState` | 20-40 lines, < 0.5 KB | -| `sheet.path_points` | curve handles (point D, U9, deferral proposed) | free op | 250-400 lines, 4-8 KB | +| `sheet.path_points` | curve handles (point D, curves lot, T16) | free op | 250-400 lines, 4-8 KB | | `sheet.path_move_points` | move anchors and controls without simplifying | free op | 300-500 lines, 5-10 KB | | `sheet.path_translate` | move a curved zone whole | free op | 60-120 lines, 1-3 KB | | fixed-category rules + opacity in the layer | choices 4 and 5 | schema + `edit.rs` + `sheet_report` issues + `layer.rs` | 1-3 KB | @@ -111,9 +112,10 @@ study). Facts that govern it: - The fingerprint and the snapshot gate also require no validation **error** (`fingerprint.rs:262-265`, `snapshot_rules.rs:334-340`). A new unconditional `validate.rs` error (for example « three roles required ») would strip the fingerprint of every existing document and reject old PDF snapshots. Fixed-category rules must live in - `edit.rs` (editor refusals) and in a verdict-only tier relative to the base (precedent `GEOMETRY_MISSING`, - `core/domain/sheet/report.rs:17-19`, `54-55`), never as an unconditional `validate.rs` error. -- Doctrine conflict to settle (decision T2): `.claude/rules/schemas.md:9-11` says additive optional fields keep the + `edit.rs` (editor refusals) and in a verdict-only tier (precedent `GEOMETRY_MISSING`, + `core/domain/sheet/report.rs:17-19`, `54-55`), never as an unconditional `validate.rs` error. (The first version + of this plan made the verdict tier relative to the base; withdrawn by T4, see §2 A.) +- Doctrine conflict, settled by the owner under T2 (route A, ratified with conditions): `.claude/rules/schemas.md:9-11` says additive optional fields keep the contract; `.claude/rules/sheet-model.md` says a document schema change bumps `SHEET_DOCUMENT_SCHEMA_VERSION`, with no bump during V1-2 (BLK-008); BDR-068 says `v1` freezes the construction and the validation. Route B (schema v3) is excluded by the contract during V1-2 (`docs/development/V1-2_ANATOMICAL_SHEETS.md:1779-1781`) and would need a @@ -126,14 +128,15 @@ study). Facts that govern it: Measured on the shipped build (`packages/core-wasm/pkg/faunosteo_wasm_bg.wasm`, built 2026-11-04 after the last core change of 2026-11-02): 1 569 864 B raw, **592 143 B** with Node `gzipSync` level 9, which is what the gate measures (`packages/core-wasm/tests/size.test.ts:12-25`). Budget 600 000 B (D-R13), **margin 7 857 B**. GNU `gzip -9` -gives 583 126 B; the earlier study's « about 17 KB left » used that figure. Without the curve operations (U9, -deferral proposed) the new core code is estimated at about 4.5 to 13.5 KB: it may fit or exceed the margin, so the -plan measures after each op and holds a fallback ready (decision T1). With U9 the total reaches 14 to 31 KB and a +gives 583 126 B; the earlier study's « about 17 KB left » used that figure. Without the curve operations (curves lot, +out of V1-2.6) the new core code is estimated at about 4.5 to 13.5 KB: it may fit or exceed the margin, so the +plan measures after each op and holds a fallback ready (decision T1). With the curves lot the total reaches 14 to 31 KB and a lever is certain. Documented levers, none applied: `wasm-opt -Oz` (never measured; `wasm-opt` is not installed, `RUST.md:4054`, so it is a new pinned build tool), a lighter URL check (about 23 KB), the PDF writer, reader and inflater in a lazily loaded second module (about 55-60 KB, `RUST.md:4050-4054`; touches the R4 paths, the import worker, the CSP proof and trap recovery, and the readers of user data that need an explicit owner ask). Raising the -budget is an owner decision (D-R13). +budget is an owner decision (D-R13), never silent. Every figure in this plan is taken with the gate's exact call, +Node `gzipSync(bytes, { level: 9 })` on the `pkg` build, re-measured on 2026-11-05 at 592 143 B (LRN-118). ### 1.7 Corrections to the earlier study @@ -166,9 +169,10 @@ budget is an owner decision (D-R13). - App and worker images are built from one `GIT_SHA` by `.gitea/workflows/release-images.yml:103-120` (prepared, never run). The sandbox reuses `faunosteo_worker:dev` without checking it matches the checkout (`scripts/db-sandbox.sh:335-347`): every model step rebuilds it explicitly. -- The only SQL the redesign needs is the round-withdrawal migration the contract requires when the integrity rules - or the SVG reader change (`V1-2_ANATOMICAL_SHEETS.md:945-949`): U6 (verdict-tier rules, decision T4) and U9 (path - reader). References are in the document; own drawings use the existing upload path, capped at +- The only SQL the redesign needs is the U6 migration (decision T4): the round withdrawal the contract requires + when the integrity rules change (`V1-2_ANATOMICAL_SHEETS.md:945-949`), the core gate, the rules epoch, the + declared publication check and, if confirmed, the save non-regression check. The curves lot will need its own + withdrawal (path reader). References are in the document; own drawings use the existing upload path, capped at 4 drawings per sheet, 2 MiB each, 6 MiB in all (`core/domain/archive/snapshot.rs:21-28`). ### 1.9 Concurrency, multi-tab, recovery @@ -199,27 +203,35 @@ budget is an owner decision (D-R13). ### A. Non-destructive migration for fixed categories and opacity -- Route A: `role` (`bone` | `joint` | `vertebra`) and `fill_opacity` (integer percent, decision T3) on - `AnnotationCategory`, both `Option` + `#[serde(default)]` + `js::present` (an explicit `null` refused, one canonical - form) + `skip_serializing_if = "Option::is_none"` + `ts(optional)`, the `LocalizedOptionalText` pattern. No - `SHEET_DOCUMENT_SCHEMA_VERSION` bump, no SQL schema change, no data migration (decision T2). -- Existing documents carry neither key: they read, write and fingerprint as today. Proven by tests, never assumed: - equine fingerprint `12d78872…` and alias `27c7383c…` recomputed equal, every seed review digest pinned and equal, - R4 app-path digests unchanged (`V1-2-6_UX_TESTS.md` U6). +- Route A, ratified in principle with conditions (T2, T3): `role` (`bone` | `joint` | `vertebra`) and + `fill_opacity` (integer percent 10 to 100) on `AnnotationCategory`, both `Option` + `#[serde(default)]` + + `js::present` (an explicit `null` refused, one canonical form) + `skip_serializing_if = "Option::is_none"` + + `ts(optional)`, the `LocalizedOptionalText` pattern; never serialised as `null`; an absent key never defaulted in + the fingerprinted document. No `SHEET_DOCUMENT_SCHEMA_VERSION` bump, no SQL schema change, no data migration. The + owner's conditions are the proof list of `V1-2-6_UX_COMPATIBILITY.md` §8, green before any key is written. +- One-way compatibility, never called full backward compatibility: existing documents carry neither key and read, + write and fingerprint as today (proven by the pins: equine fingerprint `12d78872…`, alias `27c7383c…`, every seed + review digest, R4 app-path digests, `V1-2-6_UX_TESTS.md` U6); a document carrying a key cannot be read by any + earlier application, worker or core, so the first such write is a point of no return (COMPATIBILITY §0, §7). - New sheets: `sheet.empty` creates the three fixed categories with roles, core-chosen ids (precedent `view-main`, - `core/domain/sheet/create.rs:9`, `28`), fixed names and default colours (decision T5). -- Rules in two tiers, never as an unconditional `validate.rs` error (that would strip fingerprints and reject old - snapshots): `edit.rs` refuses removing a role-bearing category, changing or clearing its role, a duplicate role, - and renaming a role-bearing category; `sheet_report` issues, relative to the base when there is one, report a role - of the base that disappeared and any duplicate role. They map to the existing `verification.validation.rules` - (`verdict.rs:277-296`): no new verdict code (decision T4). -- Residual gap, stated: a sheet's first version has no base, so a direct `save_sheet_draft` (or « Garder ma - version » from a tab still running an older bundle) can strip the three roles before the first publication; the - edit refusals do not see it. It shows in the review of the `general` group, where every group of a first version - must be covered. Decision T4 records whether this residual is accepted. -- No expand-then-write split: every environment where U6 runs is a throwaway sandbox, and `sheet.empty` writes the - keys from the first new sheet, so a split would not protect anything. The rollback limit is stated instead - (`V1-2-6_UX_COMPATIBILITY.md` §7) and recorded as a release-readiness item. + `core/domain/sheet/create.rs:9`, `28`), fixed names and default colours (T5; ids, EN names and colours still to + ratify). +- Fixed-category checks, no residual gap (T4), never as a `validate.rs` error (that would strip fingerprints and + reject old snapshots): + - core, verdict tier: `sheet_report` on the draft gives error issues for a missing role, a duplicate role or a + wrong name on a role-bearing category, with no base needed, so a first version is judged like any other; they + map to the existing `verification.validation.rules` (`verdict.rs:277-296`), no new verdict code; + - core, editor tier: `edit.rs` refuses removing a role-bearing category, changing or clearing its role, a duplicate + role, a rename away from the fixed names and any `navigation` assignment; giving a role writes the fixed names + in the same update; repair commands insert a missing fixed category, restore the fixed names and clear a + duplicate role (DECISIONS T4); + - server: the U6 migration withdraws the rounds of draft versions in flight, adds a core gate at + `complete_sheet_verification` that refuses a passed verdict from a pre-U6 core, and adds a declared SQL check + of the fixed model at approval and publication (O22 amended at U0); recommended, to confirm: a non-regression + check at `save_sheet_draft` (no role removed, duplicated or renamed away; role-less drafts still save). +- Functional write lock instead of an expand-then-write split: the U6 migration exposes a rules epoch and the + application writes no key and creates no new-model sheet before it reads it; SQL first is mandatory, the only + order that fails closed (COMPATIBILITY §7). U6 runs on the sandbox only until the owner decides otherwise. ### B. Historical equine sheet and published documents @@ -230,6 +242,10 @@ budget is an owner decision (D-R13). - Category ids never change (`id_changed`, `edit.rs:486-489`). Converting the equine working copy (roles on `os`, `articulations`, `zone-colonne`, the renaming of `zone-colonne`, the three own colours) is V1-2.8 content work, a reviewed edit of its draft, after decision T6. Nothing in V1-2.6 converts it. +- Historical preservation is mandatory (T5): the historical versions keep their category ids, names, colours, the + three own colours, every annotation and their fingerprints. Roles go on a working copy only; U6 proves on an + in-memory copy of the seed that a conversion leaves the originals' bytes, fingerprint, alias and review digests + unchanged. Under T4 the working copy cannot pass verification until V1-2.8 converts it. ### C. Proof of compatibility: N-1, PDF snapshots, worker, old drafts @@ -243,8 +259,10 @@ budget is an owner decision (D-R13). - Worker: the image is rebuilt from the same commit, checked against `git rev-parse HEAD` before the run (U1 adds that guard), and `verify-e2e` runs a New-absent and a New-present draft. - Old drafts and recovery copies are plain document texts read by the same strict reader. -- The readers of user data widen (`assert_snapshot`, used by `archive/read.rs`, accepts the keys): CLAUDE.md asks for - the owner's agreement before such a change; it is part of decision T2. +- The readers of user data widen (`assert_snapshot`, used by `archive/read.rs`, accepts the keys): the owner agreed to + a controlled widening (T2). It 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 still rejects the snapshot (report kept); no version is + dropped; the frozen N-1 copies are never edited. ### D. Editing and translating curves without geometric degradation @@ -254,8 +272,14 @@ a path (the seed has 22 circles, 6 polygons, 0 paths), and no product path can c and polygons only (`creation.ts:93-97`), package import and zones from the drawing's shapes stay deferred (`V1-2_ANATOMICAL_SHEETS.md:1330-1338`). Board 05 labels its curve card « exemple d'une autre fiche ». -Handle editing of curves (anchors, controls, translation) is therefore U9, proposed for deferral to the lot that -first lets a path enter a document (decision T16). Its specification is kept so it can start without a new study: +Handle editing of curves (anchors, controls, translation) is deferred out of V1-2.6 to the curves lot (ex-U9, +decision T16). The owner made the deferral conditional on an audit: it confirms that no tracked document holds a +path and no product journey needs one changed; the database contents of DEV and the sandbox were not queried, so a +read-only count runs before U6 or U8 reaches any environment beyond the throwaway sandbox (DECISIONS T16). Until the curves lot, a stored path keeps its +`d` text byte for byte, no operation converts it, and every operation that would change it is refused with the +document unchanged; « Remplacer par un polygone » (contract §8.3) stays the one, explicit, undoable way a path +leaves a document. The curves lot precedes any feature that lets a path enter a document. Its specification is kept +so it can start without a new study: - Built on the existing reader (`path.rs`), extended to keep each number's byte span and a segment model (command, absolute or relative, origin, anchor, explicit controls). @@ -270,29 +294,36 @@ first lets a path enter a document (decision T16). Its specification is kept so - Preview during a drag: page-side transform of the drawn path element (an SVG `transform` on the preview only), one core call on pointer-up (BDR-050), never a core call per move. - Implicit S/T controls are listed as non-editable; a control outside the frame is never judged on its own. -- Remap of a crop view holding a path is refused with a closed code until U9. +- Remap of a crop view holding a path is refused with a closed code until the curves lot. ### E. Annotations when a crop view receives its own SVG - Today the attach keeps the old `view_box` and changes only `svg_asset_id` (`drawingUpload.ts:185-192`): the frame stays the crop rectangle R, read in the new drawing's space. For a drawing cut from the same master (the seed head drawing has exactly the crop's `viewBox`), this is already right and annotations stay on their anatomy. -- For a re-based drawing (another export with a different `viewBox`), positions must be transposed. The editor - therefore offers an explicit choice when the new drawing's `viewBox` V differs from R: « Même repère : garder les - positions » or « Dessin recadré : transposer les annotations ». V equal to R: no question, positions kept - (decision T9 on wording and default). -- `sheet.remap_view {view_id, asset_id}` on the preview handle returns a batch of `sheet.edit` commands (the view - update and one `update` per remapped annotation), committed by the existing `commitBatch` as one undo entry under - the geometry accept (`editorEdit.ts:45-61`). The core reads R and V itself; the page supplies no number. Mapping: - one uniform scale and translation (`xMidYMid meet`, the composer's default); circles move their centre and scale - `r`; polygons every point; numbers on the 0.01 grid of the page; every remapped annotation `to_confirm` (by the - `update` rule, `edit.rs:495-509`). +- For a re-based drawing (another export with a different `viewBox`), positions must be transposed. The owner + ratified an explicit choice on every replacement, with no approximate automatic transformation (T9). The dialog + opens before the upload, no action preselected. Two core calls (DECISIONS T9): an offer computed before the + upload from the document and the cleaned candidate text (the core reads V from the candidate root), then the + batch, after the drawing is registered and held, from the view id and the asset id. R is the crop rectangle, V + the candidate's `viewBox`; both actions rest on a premise the dialog states and both fail closed: + - « Conserver les positions »: only when V equals R (« ce dessin utilise le repère de la vue parente »); + - « Repositionner les annotations »: only when V differs from R with the same aspect ratio on the 0.01 grid, no + path, no descendant crop, numbers in range (« ce dessin montre exactement la zone de la vue »); + - « Annuler »: always; nothing uploaded, document and history untouched. + An unavailable action stays visible, disabled, with its reason; a candidate without `viewBox` gets « Annuler » + only, stricter than today's attach. +- `sheet.remap_view` (the batch call) returns the `sheet.edit` commands (the view update and one `update` per + remapped annotation), committed by the existing `commitBatch` as one undo entry under the geometry accept + (`editorEdit.ts:45-61`); a refusal there leaves the document unchanged and an unreferenced registered drawing. + The core reads R and V itself; the page supplies no number. Mapping: one scale and one translation (a different + ratio is refused, `remap.aspect`, never centred); circles move their centre and scale `r`; polygons every point; + numbers on the 0.01 grid of the page, and a point pushed out of the frame by the rounding refuses the whole remap; every remapped annotation `to_confirm` (by the `update` rule, `edit.rs:495-509`). - Scope: the view's own annotations, including the detail triggers drawn in it. Descendant views with their own - drawing are untouched. Refused as a whole, with closed codes: a descendant crop view without its own drawing - (`remap.descendant_crop`; no sheet has one), a path in the view (`remap.path`, until U9), `unknown_view`, - `no_frame`, `out_of_range`. A refusal or a remap whose end state fails the geometry accept leaves the document - unchanged and the uploaded drawing held, with a message; the editor can then attach with « garder les positions » - or abandon. + drawing are untouched. Refused as a whole, with closed codes: a different aspect ratio (`remap.aspect`), a + descendant crop view without its own drawing (`remap.descendant_crop`; no sheet has one), a path in the view + (`remap.path`, until the curves lot), `unknown_view`, `no_frame`, `out_of_range`. A keep or a repositioning whose + end state fails the geometry accept leaves the document unchanged, with a message. - Fixed user-unit sizes (twin offset 12, floor 2, strokes) do not scale, so `too_small` can change after a downscale; the geometry accept and the repair dialog judge the end state. @@ -308,10 +339,16 @@ first lets a path enter a document (decision T16). Its specification is kept so - Name proposal (page, display formatting from the core's list): FR and EN names of the `inside` annotations, in document order, joined by the locale's list format, the first three then « … »; none inside → « Vue détaillée n » / « Detail view n », n = number of detail views + 1. Both fields stay editable. -- Access: the view and its access are inserted in one batch. The access is created automatically, with the drawn - rectangle as its polygon in the parent view, only when the overlap list is empty and the sheet has a category for - it (decision T10). Otherwise the box is unchecked with the reason stated, and the access is placed explicitly from - the view's menu (« Ajouter un accès »), which replaces the « Accès à une vue détaillée » toolbar tool (choice 6). +- Access category (T10, principle ratified): a navigation access is never put in Os, Articulations or Vertèbres by + the system. The navigation type exists (`detail_trigger`, `schema.rs:439-462`) but requires an existing category + (`schema.rs:449`, `validate.rs:287-292`), and snapshots carry triggers to N-1 (`snapshot_rules.rs:141-165`). + Recommended, pending the owner's confirmation: one internal category `cat-access`, role `navigation`, created by + the core, absent from every visible panel and picker (DECISIONS T10 option B). +- Access: automatic creation needs that role, so it lands in U6, not U5. Then the view, its access (the drawn + rectangle as its polygon in the parent view) and, if missing, the navigation category are inserted in one batch, + only when the overlap list is empty. Otherwise the box is unchecked with the reason stated, and the access is + placed explicitly from the view's menu (« Ajouter un accès »), which replaces the « Accès à une vue détaillée » + toolbar tool (choice 6). Before U6, « Ajouter un accès » asks the editor for the category, as level 1 does. Until an access exists the view is `view.unreachable`, an error in the validation panel that blocks submission, not saving; the creation flow says so and links to the placement. @@ -352,17 +389,19 @@ seed untouched, axe, keyboard and touch journeys, sandbox and worker runs. ### I. Decisions that block before any code -Each sub-step lists the decisions it consumes; the single table is in `V1-2-6_UX_DECISIONS.md`. Before U1: T11. -Before U5: T9, T10 (and T1 if the measure exceeds the budget). Before U6: T2, T3, T4, T5, T17. Before U7: T12. -Before U9: T16. +Each sub-step lists the decisions it consumes; the single table is in `V1-2-6_UX_DECISIONS.md` and the blocking +criteria in `V1-2-6_UX_RISKS.md`. Answered 2026-11-05: T2/T3 (with conditions), T4, T5 (history), T9, T10 +(principle), T11, T12 (principle), T16. Still open: before U1, T15; before U5, T1 only if a measure exceeds the +budget; before U6, the two T4 SQL checks, the T5 new-sheet defaults, T10 option B, T17; before U7, the T12 text; +at V1-2.8, T6. --- ## 3. Sub-steps Order: U0, U1, then U2 to U4 (frontend), U5 (first core queries, consumer-driven), U6 (model), U7 (common text, -when its wording exists), U8 (closure). U9 (curves) is proposed for deferral. Each sub-step ends at an owner -checkpoint; the next starts after the owner accepts it. +when its wording exists), U8 (closure). Curves are deferred to the curves lot (ex-U9, T16). Each sub-step ends at +an owner checkpoint; the next starts only on a new explicit owner authorisation. Common rules for every sub-step that touches code: @@ -395,8 +434,8 @@ Common rules for every sub-step that touches code: C32, C33, C40); `docs/design/README.md` (v1-2-6 boards replace V1-2.4 boards 04 and 05 for the editor, BDR-096); `.claude/rules/sheet-model.md` (optional keys under T2; rules may also live in `edit.rs` and `sheet_report`) and `schemas.md`; the implementer decisions (T7, T8, handle cap, branch policy); `.claude/memory/decisions.md` via - `memory.sh`. -- Dependencies: owner answers. + `memory.sh`. §7.4 records T12 without any normative wording; §8.3 records the curves lot (T16). +- Dependencies: owner answers (recorded 2026-11-05, BDR-100) and the owner's authorisation to start U0. - Rust ops: none. Tests: a fresh verifier checks the amendments against the answers. - Acceptance: each decision recorded once and cited where it applies; no contradiction left between the contract, the level-1 criteria and the boards. @@ -414,7 +453,8 @@ Common rules for every sub-step that touches code: `app/editor/verification.ts:64-131`, `PropertiesPanel.tsx:169`, `components/shell/AppLayout.tsx:72-123`, `ToolColumn.tsx`, i18n; `scripts/db-sandbox.sh` (image check, demo sheet), `crates/worker/Dockerfile` (commit label). -- Dependencies: U0, T11. +- Dependencies: U0, T11 (ratified: level-1 trial stopped, level 1 not declared validated, residuals tracked), T15 + (header undo accessible name). - Rust ops: none. - Tests: `V1-2-6_UX_TESTS.md` U1. - Acceptance: four tabs at 1 024 px and wider; every existing editor journey green on the new shell; narrow-width @@ -426,7 +466,7 @@ Common rules for every sub-step that touches code: ### U2 · Direct manipulation of points and polygons -- Objective: boards 02 to 06 and 13 for points and polygons (curve handles excluded, U9): point move and size +- Objective: boards 02 to 06 and 13 for points and polygons (curve handles excluded, curves lot): point move and size slider snapping to the radii of the view with the red minimum mark; vertex drag; « + » per segment; « − » on the chosen vertex; zone drag directly with the mouse once selected, explicit « Déplacer la zone » mode by touch; redraw keeping the old shape until accepted; 44 px touch handles; pointer rules and keyboard of §2 G; the toast; @@ -467,8 +507,9 @@ Common rules for every sub-step that touches code: ### U4 · Detail view by rectangle (manual) - Objective: « Créer une vue détaillée » draws a rectangle on the parent drawing (handles, keyboard resize) and sets - the new view's `view_box`; names typed; the access placed from the view's menu (« Ajouter un accès »); the toolbar - tool « Accès à une vue détaillée » and the numeric crop editor leave the normal journey. + the new view's `view_box`; names typed; the access placed from the view's menu (« Ajouter un accès »), which asks + the editor for the category until U6 (T10); the toolbar tool « Accès à une vue détaillée » and the numeric crop + editor leave the normal journey. - Files: `CropCanvas.tsx`, `DetailViewForm.tsx`, `CropEditor.tsx`, `DetailViewRow.tsx`, `ToolColumn.tsx`, `app/editor/viewBox.ts`, `viewUpdate.ts`, i18n. - Dependencies: U2. @@ -480,55 +521,68 @@ Common rules for every sub-step that touches code: - Rollback: revert. - Checkpoint: owner. -### U5 · Detail view assisted: `annotations_in_rect`, `remap_view`, name, access, specific SVG +### U5 · Detail view assisted: `annotations_in_rect`, `remap_view`, name, specific SVG -- Objective: the two core queries, consumed in the same sub-step: proposed FR/EN name, automatic access only - without overlap, explicit placement otherwise; « Remplacer par un SVG spécifique » with the explicit choice of §2 E. +- Objective: the two core queries, consumed in the same sub-step: proposed FR/EN name and the overlap list; explicit + access placement (automatic access moves to U6, T10); « Remplacer par un SVG spécifique » with the three-action + dialog of §2 E (T9). - Files: core `anatomy/frame.rs` (`from_numbers`, `holds` to `pub(crate)`), new `domain/sheet/rect.rs` and `domain/sheet/remap.rs`, `ops.rs` (`call_with_preview`), types, `packages/core-wasm/src`, `app/core/*`, `DetailViewForm.tsx`, `CropCanvas.tsx`, `drawingUpload.ts:184-192`, `ViewDrawing.tsx`, `RepairDialog.tsx`, i18n, `RUST.md` §12. -- Dependencies: U4; T9, T10; T1 if the measure exceeds the budget. -- Rust ops: `sheet.annotations_in_rect`, `sheet.remap_view` (§2 E, F). Order: `annotations_in_rect` first, size +- Dependencies: U4; T9 (ratified); T1 if the measure exceeds the budget. +- Rust ops: `sheet.annotations_in_rect`, the replacement offer (name fixed at U5, before upload, from the candidate + text) and `sheet.remap_view` (the batch after hold) (§2 E, F; the offer is a small read, inside the U5 size measure). Order: `annotations_in_rect` first, size measured; then `remap_view`, size measured; a budget excess stops the sub-step for T1. - Tests: `V1-2-6_UX_TESTS.md` U5. -- Acceptance: board 08; no access ever created over an annotation; « garder les positions » and « transposer » both - proven on fixtures; one undo entry per remap; size within budget or T1 applied. -- Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop (positions kept, no question); - attach a re-based fixture drawing (transposition offered). +- Acceptance: board 08 with explicit placement; the replacement dialog on every replacement, « Conserver les + positions », « Repositionner les annotations » and « Annuler » each proven on fixtures, a different aspect ratio + refused, « Annuler » sending no request; one undo entry per remap; size within budget or T1 applied. +- Owner demo: board 08 on the demo sheet; attach the seed head drawing to a crop (keep offered); attach a re-based + fixture drawing (reposition offered); cancel a replacement. - Risk: size; bounds over-report. Rollback: revert (documents written are plain v2). - Checkpoint: owner. ### U6 · Category model: fixed categories, fill opacity, vertebral regions from the category -- Objective: route A (§2 A); `sheet.empty` creates the three categories; edit refusals and report issues; the layer - applies `fill_opacity` (decision T3); snapshot and export gate strip both keys; the panel locks the fixed - categories (no delete, name read-only, role badge, « Couleur d'origine » from T5) and gains the opacity slider and - field; board 09: regions open from the vertebra-role category, the region picker of a zone filtered to the - vertebra-role category's annotations (page filter, no rule), staged « Appliquer » with the error count; fallback - per T17 when no category has the role (the equine copy before V1-2.8). `docs/ANNOTATION-RENDERING.md` amended - first; round-withdrawal migration (contract `945-949`) if T4 adds report issues. -- Files: core `domain/sheet/schema.rs`, `create.rs`, `edit.rs`, `report.rs`, `anatomy/layer.rs` (`layer()` 85-102, - `Context::point` 242, `zone_visual` 297-304), `domain/archive/snapshot_rules.rs:141-165`, - `pdf/write/input.rs:174-181`, `export.rs:27-37`, types; app `refusal.ts`, the category panel, the regions dialog - (`components/editor/vertebrae/*`), i18n; SQL `supabase/migrations/_sheet_rounds_withdraw_v1_2_6.sql` - (name provisional); docs `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md` (spec table), `RUST.md`, - `DEPLOY.md` (order). -- Dependencies: U3, U5; T2, T3, T4, T5, T17. -- Rust ops: schema fields, edit refusal kinds, report issues, layer reading, snapshot stripping. -- Tests: `V1-2-6_UX_TESTS.md` U6; each row of `V1-2-6_UX_COMPATIBILITY.md` is an acceptance line. -- Acceptance: compatibility matrix proven row by row; oracles, goldens and seed unchanged; N-1 reads New-present - PDFs; worker verdict on both kinds of draft; the contract §16.7 journey on a non-equine sheet with the new UX - reaches `open` after the worker verdict. -- Owner demo: new species sheet with its three categories, custom opacity, regions from Vertèbres, PDF exported and - reopened. -- Deploy order and rollback: `V1-2-6_UX_COMPATIBILITY.md` §7. Rolling back below U6 is impossible once a document - with the keys exists (sandbox only until the owner decides otherwise). +- Objective: route A (§2 A) under the owner's conditions (T2, T3); `sheet.empty` creates the three categories; the + T4 checks (absolute verdict rule, edit refusals with the repair path, the U6 migration with round withdrawal, + core gate, publication check, rules epoch and the save check if confirmed) live before any key is written (write + lock); the layer applies `fill_opacity`; snapshot and export + gate strip both keys; the snapshot reader widened only as bounded in §2 C; the panel locks the fixed categories + (no delete, name read-only, role badge, « Couleur d'origine » from T5) and gains the opacity slider and field; + automatic access with the navigation category if T10 option B is confirmed; board 09: regions open from the + vertebra-role category, the region picker of a zone filtered to the vertebra-role category's annotations (page + filter, no rule), staged « Appliquer » with the error count; fallback per T17 when no category has the role (the + equine copy before V1-2.8). `docs/ANNOTATION-RENDERING.md` amended first. +- Files: core `domain/sheet/schema.rs`, `create.rs`, `edit.rs`, `report.rs`, `verdict.rs` (gate marker in + `verified_with`), `anatomy/layer.rs` (`layer()` 85-102, `Context::point` 242, `zone_visual` 297-304), + `domain/archive/snapshot_rules.rs:141-165`, `pdf/write/input.rs:174-181`, `export.rs:27-37`, types; app + `refusal.ts`, the category panel, the repair action, the regions dialog (`components/editor/vertebrae/*`), + `DetailViewForm.tsx` (automatic access), i18n; SQL `supabase/migrations/_sheet_rounds_withdraw_v1_2_6.sql` + (name provisional: round withdrawal, core gate, rules epoch, publication check, save check if confirmed); docs `ANNOTATION-RENDERING.md`, `ANATOMICAL_SHEET_MODEL.md` + (spec table), `RUST.md`, `DEPLOY.md` (order, write lock). +- Dependencies: U3, U5; T2 and T3 (ratified with conditions), T4 (ratified; the save and publication SQL checks to confirm), T5 (history + ratified; new-sheet defaults to ratify), T10 option B (to confirm, automatic access only), T17. +- Rust ops: schema fields, edit refusal kinds, verdict-tier issues, layer reading, snapshot stripping, verdict + marker. +- Tests: `V1-2-6_UX_TESTS.md` U6; each row of `V1-2-6_UX_COMPATIBILITY.md` is an acceptance line, and §8 lists the + proofs the owner required before the write lock is lifted. +- Acceptance: compatibility matrix proven row by row and §8 green; oracles, goldens and seed unchanged; N-1 reads + New-present PDFs; worker verdict on the three kinds of draft (role-less fails, repaired passes, New-present + passes); the contract §16.7 journey on a non-equine sheet with the new UX reaches `open` after the worker verdict; + a role-stripped draft never reaches a round. +- Owner demo: new species sheet with its three categories, custom opacity, regions from Vertèbres, automatic access, + PDF exported and reopened; a role-stripped direct save refused at save (if confirmed) or at verification. +- Deploy order, write lock and rollback: `V1-2-6_UX_COMPATIBILITY.md` §7. Returning to the old application is + impossible once a document with the keys exists (point of no return; sandbox only until the owner decides + otherwise). - Checkpoint: owner. ### U7 · Scope and limits: one-time copy of a versioned common text -- Starts only when the owner has supplied the validated wording (T12); no text is written by the implementer. +- Starts only when the owner has supplied the FR and EN text, its source and its validation record (T12); no + normative text is written or invented by the implementer, and tests use a fixture text kept under `tests/`. - Objective: when both disclaimer fields are empty, « Insérer le texte commun (version n) » copies FR and EN once; afterwards the fields are free text; a read-only comparison shows the current version; no automatic change ever reaches a draft or a published version. @@ -543,22 +597,26 @@ Common rules for every sub-step that touches code: ### U8 · Closure - Objective: recovery and conflict journeys re-run on the new UX; the contract §16.7 acceptance on the sandbox; - documents and TODO closed; `V1-2-6_OWNER_TRIAL.md` updated. -- Dependencies: U1 to U6 (U7 when its wording exists; U9 per T16). + the level-1 residuals tracked under T11 re-checked one by one (level 1 still not declared validated as a whole); + the T16 path count recorded for any environment beyond the sandbox; documents and TODO closed; + `V1-2-6_OWNER_TRIAL.md` updated. +- Dependencies: U1 to U6 (U7 when its text exists; curves in their own lot, T16). - Tests: `V1-2-6_UX_TESTS.md` U8. - Checkpoint: owner trial of the redesigned editor; V1-2.7 stays closed until the owner opens it. -### U9 · Curves (deferral proposed, decision T16) +### Curves lot (ex-U9, deferred out of V1-2.6, decision T16) -- Objective, if the owner keeps it in V1-2.6: board 05 curve handles (§2 D), curved zone move, remap of paths, the - C45 refusal replaced by real correction. +- Out of V1-2.6 by the owner's conditional decision; recorded in TODO.md as a future lot that precedes any feature + letting a path enter a document. Kept here so it can start without a new study. +- Objective: board 05 curve handles (§2 D), curved zone move, remap of paths, the C45 refusal replaced by real + correction (with the path point-correction proposal `.claude/tasks/plans/2026-11-04-v1-2-6-path-repair-core-proposal.md`). - Files: core `anatomy/path.rs`, `ops.rs`, types, wrappers; app `AnnotationOverlay.tsx`, `useMoveGesture.ts`, `repair.ts:60-100`; SQL round-withdrawal migration (the path reader feeds the frame and interior verdict rules, `frame.rs:25`, `interior.rs:23`); `RUST.md`. -- Dependencies: U2, U5; T16, T1 (a lever is certain). +- Dependencies: U2, U5; T1 (a lever is certain); its own owner authorisation. - Rust ops: `sheet.path_points`, `sheet.path_move_points`, `sheet.path_translate`. -- Tests: `V1-2-6_UX_TESTS.md` U9, including a frozen pre-U9 oracle of `number_list`, `path_bounds` and - `path_outline` on a corpus, compared byte for byte after the change. +- Tests: `V1-2-6_UX_TESTS.md` « Curves lot », including a frozen oracle of `number_list`, `path_bounds` and + `path_outline` on a corpus taken before the change, compared byte for byte after it. - Acceptance: a path of a fixture sheet (never the seed) edited point by point, saved, reloaded with every untouched number byte-identical. - Rollback: revert; paths go back to display only. @@ -575,10 +633,10 @@ Common rules for every sub-step that touches code: | U2 | yes | one read-only value | no | no | no | | U3, U4 | yes | no | no | no | no | | U5 | yes | two queries | no | no | no (the worker calls neither) | -| U6 | yes | yes | optional keys | round withdrawal (T4) | rebuilt, deployed before the app | +| U6 | yes | yes | optional keys | round withdrawal, core gate, rules epoch, publication check, save check if confirmed (T4) | rebuilt, deployed before the app | | U7 | yes | no | no | no | no | | U8 | no | no | no | no | rebuilt for the final run | -| U9 | yes | path ops | no | round withdrawal | rebuilt, deployed before the app | +| Curves lot (out of V1-2.6) | yes | path ops | no | round withdrawal | rebuilt, deployed before the app | ## 5. Out of scope, tracked separately @@ -587,8 +645,9 @@ Common rules for every sub-step that touches code: - Full touch editing on the phone (boards 14 to 16 kept as the reference of that future lot); O14 A stays. - A multi-tab notice (not in the validated boards; the server revision check and the conflict dialog already guard against lost writes): proposed as a follow-up, decision T14. +- The curves lot (ex-U9, T16), a prerequisite of any feature that lets a path enter a document. -The first three are in `.claude/tasks/TODO.md` (V1-2 section); T14 is added there if the owner keeps it. +All five are in `.claude/tasks/TODO.md` (V1-2 section); T14 stays a follow-up candidate until the owner answers. ## 6. Independent review record (2026-11-05) @@ -621,3 +680,39 @@ robustness CONCERNS(9), simplicity CONCERNS(6); no BLOCKER. Integrated: Not adopted: the simplicity lens recommended `edit.rs` refusals only (T4 option a). The plan keeps report issues because they cost no SQL code once mapped to the existing verdict code and keep the core as the authority (O22); the owner decides under T4. No second review was run on the corrected version. + +## 7. Owner answers recorded (2026-11-05) + +Brief « FAUNOSTEO — V1-2.6 UX — Ratification des décisions techniques ». The UX choices are not reopened. Changes +to this plan and its companions: + +- T11 approved: level-1 trial stopped, level 1 not declared validated, residuals tracked (DECISIONS T11, TODO.md). +- T16 conditional deferral: audit recorded, path guarantee written, curves lot out of V1-2.6, database count before + U6 or U8 reaches any environment beyond the throwaway sandbox. +- T2/T3 agreement in principle with conditions: proof list (COMPATIBILITY §8), one-way compatibility and point of + no return stated (COMPATIBILITY §0, §7), bounded widening of the snapshot reader, BDR-068 effects. +- T4 without residual gap: absolute verdict-tier rule replaces the base-relative one; repairable editor rules; + core gate, declared publication check and functional write lock added; save non-regression check recommended, + confirmation requested (revised after the second independent review, §8). +- T5 historical preservation: history untouched, conversion tested on a copy; new-sheet defaults still to ratify. +- T9 three explicit actions on every replacement; exact same-aspect repositioning only. +- T10 navigation type: constraints checked; internal navigation category recommended, to confirm; automatic + access moved to U6. +- T12 principle kept; U7 blocked until the text, its source and its validation exist. +- Wasm measuring rule recorded as LRN-118; the decisions as BDR-100. + +## 8. Second independent review (2026-11-05, after the owner's answers) + +A fresh correctness challenger on the revised docs: CONCERNS(5) MAJOR and 7 MINOR, all integrated: a declared SQL +check of the fixed model at approval and publication (a worker defect can no longer publish); editor rules made +repairable (a role brings its fixed names, repairs for names and duplicate roles, `navigation` never assignable); +a functional write lock (rules epoch read by the application) and the statement that only SQL-first orders fail +closed; T9 split into an offer call before the upload and a batch call after it, keep limited to V equal to R, +premises stated in the dialog, a candidate without `viewBox` refused; withdrawal limited to draft rounds; the +`category.fixed.*` family filtered by the release replay; the flipped suites listed; single-component rollback +rows; the save non-regression variant offered under O22. A fresh verifier on the contract +`.claude/tasks/contracts/2026-11-05-v1-2-6-ux-ratification.md`: ECARTS(2) (tests and cross-references still on the +older T4 scope, BDR-100 superseded on T4 and T9), fixed, then a targeted re-check (ECARTS(2): one U6 test and the deploy-order line still assumed a permissive save and an all-rounds withdrawal), fixed. A third, independent check +before the commit (2026-11-05): ECARTS(2) on K10 and K11 (the R-3 mitigation and the U6 objective still on the +older T4 scope, the write-lock test assuming a stripping save succeeds, two forms of the T16 count scope), fixed, +then a fresh targeted re-check (result in TODO.md). diff --git a/docs/development/V1-2-6_UX_RISKS.md b/docs/development/V1-2-6_UX_RISKS.md index 7f732de4..a35091ee 100644 --- a/docs/development/V1-2-6_UX_RISKS.md +++ b/docs/development/V1-2-6_UX_RISKS.md @@ -1,25 +1,25 @@ # V1-2.6 UX redesign: risk register -Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md`. Blocking -decisions live in `V1-2-6_UX_DECISIONS.md` (single table); sub-step dependencies in the plan (§3, each sub-step's -« Dependencies »); deploy order and rollback in `V1-2-6_UX_COMPATIBILITY.md` §7. Probability and impact: H high, -M medium, L low. +Status: PROPOSAL, 2026-11-05, revised after the independent review and after the owner's answers of 2026-11-05. +Companion of `V1-2-6_UX_PLAN.md`. Decisions live in `V1-2-6_UX_DECISIONS.md` (single table); sub-step dependencies +in the plan (§3, each sub-step's « Dependencies »); deploy order, write lock and rollback in +`V1-2-6_UX_COMPATIBILITY.md` §7. Probability and impact: H high, M medium, L low. | Id | Risk | P | I | Mitigation | Where checked | |---|---|---|---|---|---| -| R-1 | New category keys written as `null` when absent: every fingerprint, review digest, equine sheet-ref, alias and R4 app-path digest changes | H without a pin | H | `skip_serializing_if` + `js::present`; tests pin fingerprint `12d78872…`, alias `27c7383c…`, seed digests | U6 | -| R-2 | An unconditional `validate.rs` rule on roles strips fingerprints of existing documents and rejects old PDF snapshots | H if done | H | rules only in `edit.rs` and `sheet_report` | U6 review | -| R-3 | Direct save, or « Garder ma version » from an older bundle, strips roles of a never-published sheet | M | M | report issues against the base; residual accepted under T4, visible in the `general` review | U6 | +| R-1 | New category keys written as `null` when absent: every fingerprint, review digest, equine sheet-ref, alias and R4 app-path digest changes | H without a pin | H | `skip_serializing_if` + `js::present`; tests pin fingerprint `12d78872…`, alias `27c7383c…`, seed digests (T2) | U6 | +| R-2 | An unconditional `validate.rs` rule on roles strips fingerprints of existing documents and rejects old PDF snapshots | H if done | H | rules only in `edit.rs` and `sheet_report` (T4) | U6 review | +| R-3 | Direct save, « Garder ma version » or an older bundle strips the roles of a sheet before its first publication | M | H | closed (T4): absolute verdict rule on the draft, no base needed; core gate at verification completion; declared publication check `private.sheet_fixed_categories_ok` at approval and publication; save non-regression check if confirmed | U6 | | R-4 | Worker older than the app reads a New-present draft: definitive `integrity.document` | H on skew | M | one commit for both images; worker before app; `verify-e2e` refuses a stale image | U1 guard, U6 | -| R-5 | Rounds in flight across a rule or reader change keep a verdict of the old core | M | M | round-withdrawal migration in U6 (T4) and U9, tested with `up upgrade` and live rounds | U6, U9 | +| R-5 | Rounds in flight across a rule or reader change keep a verdict of the old core | M | M | round-withdrawal migration in U6 (T4) and the curves lot, tested with `up upgrade` and live rounds | U6 | | R-6 | A caller-built snapshot or `export_from_envelope` carries the keys: N-1 and older apps drop the snapshot | M | M | strip at both points (T7); N-1 test on a New-present fixture | U6 | | R-7 | Opacity written as anything but `fill-opacity` would reach the PDF (category colour already reaches strokes) | L | M | layer writes `fill-opacity` only | U6 | -| R-8 | Budget exceeded mid-sub-step | M | M | measure after each op; T1 fallback; PDF split never on the critical path | U5, U6 | -| R-9 | Rollback below U6 impossible once a New-present document exists (drafts unreadable by the old app and worker, published rows immutable, migrations forward-only) | certain after U6 | H | sandbox only until the owner decides; release-readiness item (new RR id, reconciled with develop where RR-11 is taken) | U6 | +| R-8 | Budget exceeded mid-sub-step, or measured with another tool than the gate's | M | M | measure after each op with the gate's exact method (LRN-118); T1 fallback; never raised silently; PDF split never on the critical path | U5, U6 | +| R-9 | Return to the old application impossible once a New-present document exists (drafts unreadable by the old app and worker, published rows immutable, migrations forward-only); not full backward compatibility | certain after the first write | H | point of no return stated (COMPATIBILITY §0, §7); write lock (T4); sandbox only until the owner decides; release-readiness item (new RR id, reconciled with develop where RR-11 is taken) | U6 | | R-10 | An executor follows the CLAUDE.md SQL line (`db:reset`, `db:test`, `db:types`) and reaches DEV | M | H | plan forbids them and lists the sandbox commands; LRN-110 absolute-path rule in every brief | every SQL sub-step | | R-11 | Shared sandbox and worker tag: another checkout replaces the stack or image between rebuild and test | M | M | no other checkout runs them during V1-2.6; image label checked against `HEAD` | U1 guard | | R-12 | Rebuilding the sandbox wipes the owner-trial stack | M | L | tell the owner before any `down` or `up fresh` | every sub-step | -| R-13 | Automatic remap moves correct annotations of a drawing cut from the same master | H if automatic | M | explicit choice; positions kept when `viewBox` equals the crop (T9) | U5 | +| R-13 | Keeping positions for a re-based drawing, or an approximate remap, misplaces annotations | M | M | explicit three-action dialog on every replacement (T9); keep only when V equals R, reposition only for a same-aspect mapping, each with its stated premise; both fail closed; every affected annotation `to_confirm` | U5 | | R-14 | Remap of a subtree with descendant crops or paths | L | M | closed refusals `remap.descendant_crop`, `remap.path` | U5 | | R-15 | A pinch with finger 1 on a handle moves the handle | H on touch | M | a second pointerdown cancels the armed drag; two-touch test starting on a handle | U2 | | R-16 | Undo, redo or a document replacement during a pending preview resurrects a change or moves the wrong vertex | M | H | pending previews cancelled before any of them | U2, U3 | @@ -38,6 +38,40 @@ M medium, L low. | R-29 | Undo crosses a save; `addDrawing` outside history | L | L | kept as built; stated in the trial guide | U8 | | R-30 | 0.1.0 production reader behaviour on new PDFs unknown | unknown | M | read before any production release carrying U6 | release track | | R-31 | Bounds-based overlap over-reports for concave shapes | M | L | conservative by design | U5 | +| R-32 | An old worker (rollback, stale image, second instance) passes a draft without the fixed categories | M | H | core gate at completion refuses a passed verdict from a pre-U6 core (T4); `verified_with` needs a U6 marker since every core reports `0.1.0` | U6 | +| R-33 | The release replay judges published versions with the fixed-category rule and flags the historical equine version | M | M | the rule is a submission rule on drafts; the replay checks reading, fingerprint, validation, drawings (COMPATIBILITY §5) | release track | +| R-34 | The equine working copy and every pre-U6 draft fail verification under the absolute rule | certain | L | intended (T4); repair action in the editor; working copy converted at V1-2.8 (T6) | U6, V1-2.8 | +| R-35 | The navigation category (T10 B) shows up in the anatomical taxonomy or is used by a point or zone | M | M | absent from panels and pickers; edit refusal and verdict issue for an observable annotation in it; old readers see an ordinary category | U6 | +| R-36 | Invented or unapproved normative text ships with U7 | L | H | U7 blocked until the owner's text, source and validation record; test fixtures only under `tests/`; review gate (T12) | U7 | +| R-37 | A future feature lets a path into a document before the curves lot exists | M | H | dependency recorded in TODO.md (T16); path guarantee tests stay in the suites | future lots | +| R-38 | A path already sits in a database (direct RPC save or test fixture) that U6 or U8 reaches | L | M | read-only count before U6 or U8 reaches any environment beyond the throwaway sandbox; non-zero reopens T16 | U8, deploy | +| R-39 | The halted level-1 trial leaves defects unseen; level 1 read as validated | M | M | level 1 not declared validated (T11); residuals tracked in TODO.md; untouched criteria re-tested at U1 and U8 | U1, U8 | + +## Blocking criteria + +Each line holds until its condition is met; nothing in this list authorises a sub-step by itself. + +| Criterion | Holds | Condition to lift | +|---|---|---| +| U0 and every sub-step | all code and contract amendments | a new explicit owner authorisation (brief 2026-11-05) | +| T15 answered | U1 (header undo accessible name and tooltip) | owner answer | +| T2/T3 proofs (COMPATIBILITY §8) | writing a key outside a test | every proof green and reviewed | +| T4 checks live on the environment | the U6 write lock | U6 migration (withdrawal, core gate, publication check, rules epoch) first, then the U6 worker | +| T4 SQL checks confirmed | U6 | owner confirms the declared publication check and the recommended save non-regression check (O22 amended at U0) | +| T5 new-sheet defaults | U6 (`sheet.empty`) | owner ratifies ids, EN names, default colours | +| T10 option B | automatic access (U6) | owner confirms the internal category (id, names, role `navigation`) | +| T17 answered | U6 (regions entry) | owner answer | +| T1 | U5 or U6 only if a measure exceeds 600 000 B | owner decision on the measured figure | +| T12 text | U7 | owner supplies the FR and EN text, its source and its validation record | +| T16 database count | U6 or U8 on any environment beyond the throwaway sandbox | read-only count of paths is zero | +| 0.1.0 reader check and release replay | any production release carrying U6 | R-30 read and recorded; replay green | + +## Dependencies outside the plan + +- V1-2.8 (equine working copy) depends on U6 (roles, repair action) and on T6. +- The curves lot depends on U2 and U5 (handles, remap) and on T1 (a size lever is certain); it precedes any feature + that lets a path enter a document. +- The registry id reconciliation with develop (LRN-095, BLK-013, RR-11 and RR-12) precedes the V1-2 merge. ## Separate tracks (kept out, tracked in TODO.md) @@ -45,3 +79,4 @@ M medium, L low. - Historical equine drawings missing on the sandbox, which block the working copy. - Full phone editing, a future lot after V1-2 (boards 14 to 16 kept as its reference). - RR-12, the AAL2 token after factor removal (production prerequisite, unchanged by this plan). +- The curves lot (T16). diff --git a/docs/development/V1-2-6_UX_TESTS.md b/docs/development/V1-2-6_UX_TESTS.md index 12b31cab..87e3f8d9 100644 --- a/docs/development/V1-2-6_UX_TESTS.md +++ b/docs/development/V1-2-6_UX_TESTS.md @@ -1,8 +1,8 @@ # V1-2.6 UX redesign: test matrix per sub-step -Status: PROPOSAL, 2026-11-05, revised after the independent review. Companion of `V1-2-6_UX_PLAN.md` (the common -rules of §3 apply: absolute paths, sandbox-only database commands, forbidden commands). No test is written before -the owner approves the plan. +Status: PROPOSAL, 2026-11-05, revised after the independent review and after the owner's answers of 2026-11-05. +Companion of `V1-2-6_UX_PLAN.md` (the common rules of §3 apply: absolute paths, sandbox-only database commands, +forbidden commands). No test is written before the owner authorises the sub-step that carries it. ## Common gates @@ -10,12 +10,12 @@ the owner approves the plan. |---|---|---| | Core | `pnpm rust:check` then `pnpm wasm:build` | any change under `crates/` | | App and packages | `pnpm typecheck`, `pnpm test:run`, `pnpm lint`, `pnpm build` | always | -| Size | `packages/core-wasm/tests/size.test.ts` (Node gzip ≤ 600 000 B), figure recorded in RUST.md | any change under `crates/core` or `crates/wasm` | +| Size | `packages/core-wasm/tests/size.test.ts`: Node `gzipSync(bytes, { level: 9 })` on `packages/core-wasm/pkg/faunosteo_wasm_bg.wasm`, at most 600 000 B; the figure printed by that test recorded in RUST.md; never a system `gzip` figure; the budget never raised silently (T1, LRN-118) | any change under `crates/core` or `crates/wasm` | | Seed and pipeline | `pnpm r5:import-equine --check` with no difference | always | | Frozen references | no change under `crates/core/tests/oracles/`, `apps/app/tests/fixtures/goldens/`, `supabase/seed/` (`git diff --stat` on those paths is empty) | always | | Browser, no backend | `pnpm e2e:ui` | always | | Sandbox | `pnpm db:sandbox up fresh`, then `test-db → e2e-shell → test` (LRN-113) | always | -| Worker | `pnpm worker:image`, then `pnpm db:sandbox verify-e2e` (refuses an image not built from `HEAD` after U1) | U1, U6, U8, U9 | +| Worker | `pnpm worker:image`, then `pnpm db:sandbox verify-e2e` (refuses an image not built from `HEAD` after U1) | U1, U6, U8 | | Pre-checkpoint | `pnpm check:all` | every code sub-step | | Reviews | fresh verifier on the sub-step contract; fresh security review on the diff | every sub-step | @@ -27,21 +27,24 @@ Accessibility: axe with zero serious or critical violations per state (`docs/dev keyboard-only journeys, a text next to every colour, visible focus on every handle. Chromium only until V1-5; WebKit and real tablets are owner trials. +Path guarantee (T16), every sub-step that touches geometry: a fixture sheet holding paths (never the seed) keeps +every path's `d` text byte for byte through the sub-step's journeys, save and reload. + ## U0 · Contract and decisions | Kind | Test | |---|---| -| Review | fresh verifier: each answer recorded once and cited where it applies; no contradiction between contract §7.4, §8.2-8.4, §16.7, the level-1 criteria (C3, C4, C6, C7, C8, C13, C32, C33, C40) and the boards | +| Review | fresh verifier: each owner answer of 2026-11-05 recorded once and cited where it applies; no contradiction between contract §7.4, §8.2-8.4, §16.7, the level-1 criteria (C3, C4, C6, C7, C8, C13, C32, C33, C40) and the boards; no normative common text written (T12) | ## U1 · Shell | Kind | Tests | |---|---| -| Unit | four-tab model, initial tab, width tiers (replaces `editor-route.test.tsx:66`, `128-170`, `editor-mode.test.ts:99-110`); header undo and redo states; undo from each tab reverts the last commit made on another tab; a typed field is flushed before the header undo (behaviour pinned); references panel open, close, return focus; « Aller à » target for every issue kind (`verification.ts:64-131`) | +| Unit | four-tab model, initial tab, width tiers (replaces `editor-route.test.tsx:66`, `128-170`, `editor-mode.test.ts:99-110`); header undo and redo states; undo from each tab reverts the last commit made on another tab; a typed field is flushed before the header undo (behaviour pinned); header undo accessible name and tooltip as decided under T15; references panel open, close, return focus; « Aller à » target for every issue kind (`verification.ts:64-131`) | | E2E shell | helpers rewritten (`e2e/support/editor.ts:326-330`, `warm-up.ts:43-45`, `editor-access.spec.ts:34-42`); every existing editor journey green on the new shell; sidebar hidden in the editor at 1 024, 1 180, 1 279 px, shown at 1 280 px, menu reachable in one tap; narrow-width read-only unchanged | | Tooling | `verify-e2e` refuses an image whose commit label differs from `HEAD`; the trial command provisions the demo sheet through the application upload path | | Accessibility | axe on the four tabs and on the open references panel; Tab order header → tabs → panel → canvas | -| Regression | recovery and conflict specs unchanged; each removed assertion mapped to its replacement in the commit message | +| Regression | recovery and conflict specs unchanged; level-1 criteria C13, C14, C16, C34, C41 re-run (T11); each removed assertion mapped to its replacement in the commit message | ## U2 · Points and polygons @@ -53,6 +56,7 @@ and real tablets are owner trials. | E2E mouse | drag a vertex, « + », « − », zone drag on a selected zone, redraw accepted, redraw refused by `interior_too_small` restores the old shape, undo and redo of each, toast « Annuler » undoes the same entry as the header | | E2E touch (`hasTouch`, 1 024, 1 180, 1 280 px) | one-finger handle drag; explicit « Déplacer la zone » mode; finger 1 on a vertex handle then finger 2 elsewhere: the pinch zooms, the drag is cancelled, no commit (CDP `Input.dispatchTouchEvent` with two points); page scroll over the canvas with a selection and outside it | | Keyboard | create a zone, add and remove a vertex, move the zone, validate, without a pointer; Ctrl+Z on a focused handle after arrow moves restores the pre-move shape | +| Paths (T16) | a path annotation gets no handle, no « + » or « − », no zone move in either mode, no keyboard move; its `d` is byte-identical after every gesture on its neighbours, a save and a reload; « Remplacer par un polygone » stays the only change, one undo entry restoring the exact `d` | | Accessibility | axe on selection, tracing and move states; handle names (« sommet 3 de Thoraciques »); live-region message after a move | | Performance | commit latency under the 500 ms budget (`editor-equine.spec.ts:25-34`) for drag, insert, remove | @@ -68,8 +72,8 @@ and real tablets are owner trials. | Kind | Tests | |---|---| -| Unit | rectangle normalised from any drag direction and clamped to the parent frame; keyboard resize of its handles; toolbar without the access tool; view menu « Ajouter un accès » | -| E2E | create a detail view by mouse and by keyboard, `view.unreachable` until its access exists, place the access, open the view in the practitioner preview | +| Unit | rectangle normalised from any drag direction and clamped to the parent frame; keyboard resize of its handles; toolbar without the access tool; view menu « Ajouter un accès » asks the editor for the category (no default category, T10 interim) | +| E2E | create a detail view by mouse and by keyboard, `view.unreachable` until its access exists, place the access with an explicitly chosen category, open the view in the practitioner preview | | Core regression | `compose.rs` tests and canvas goldens unchanged | | Accessibility | axe on creation and placement states | @@ -78,38 +82,46 @@ and real tablets are owner trials. | Kind | Tests | |---|---| | Rust `annotations_in_rect` | circle, polygon, path, trigger; inside, partial, none; rect on an edge; empty view; unknown view; invalid rect | -| Rust `remap_view` | same aspect, different aspect (uniform, centred); triggers drawn in the view remapped; descendant view with its own drawing untouched; descendant crop refused (`remap.descendant_crop`); path refused (`remap.path`); no frame refused; output = command batch; numbers on the 0.01 grid | +| Rust replacement options (T9) | offer call before upload reads V from the candidate text; keep offered iff V equals R; reposition offered iff V differs from R, same aspect ratio on the 0.01 grid; no `viewBox` → only cancel; a point pushed out of frame by rounding refuses the remap; no path, no descendant crop, numbers in range; different aspect refused `remap.aspect`; path refused `remap.path`; descendant crop refused `remap.descendant_crop`; no frame refused; reposition output = command batch; numbers on the 0.01 grid; triggers drawn in the view remapped; descendant view with its own drawing untouched | | Properties (seeded) | identity mapping returns the geometry exactly; mapping then inverse within 0.01 per number; `inside` ⇒ bounds within the rect; a rect equal to the frame ⇒ every annotation of the view `inside` | | Hostile (op level) | non-finite and out-of-range rect, unknown ids, oversized command output bounded; no panic | | Wasm | core-wasm proofs through the preview handle; size gate after each op, figure printed | -| Unit app | name formatting FR and EN (one, two, three, more with « … », none → « Vue détaillée n »); access box checked only with an empty overlap list and a category available; view and access inserted in one batch | -| E2E | board 08: rectangle over the elbow, proposed name, access unchecked with its reason, explicit placement, preview; rectangle over an empty area: access created, no annotation under it; attach the seed head drawing to a crop with the same `viewBox`: no question, positions kept; attach a re-based fixture drawing: choice offered, transposition, all remapped annotations `to_confirm`, one undo entry; a remap failing the geometry accept leaves the document unchanged and the drawing held | -| Accessibility | axe on the dialogs; the reason of the unchecked box is announced | +| Unit app | name formatting FR and EN (one, two, three, more with « … », none → « Vue détaillée n »); the replacement dialog: opens on every replacement, before any upload, no action preselected, unavailable actions disabled with their reason, « Annuler » sends no request and leaves document and history unchanged | +| E2E | board 08 without automatic access: rectangle over the elbow, proposed name, explicit placement, preview; replacement dialog: the seed head drawing on a crop with the same `viewBox` → keep and cancel offered, keep applied, annotations `to_confirm`; a re-based fixture drawing with the same aspect → reposition applied, all moved annotations `to_confirm`, one undo entry; a fixture with another aspect → reposition disabled with its reason; cancel → no upload request, document byte-identical; a keep or reposition failing the geometry accept → document unchanged, message | +| Accessibility | axe on the dialogs; the reason of a disabled action is announced | ## U6 · Category model | Kind | Tests | |---|---| -| Rust serialisation | both keys round-trip; absent keys not written (no `role` or `fill_opacity` text in the re-serialised seed); explicit `null` refused; out-of-range opacity and unknown role refused | -| Rust identity pins | equine fingerprint `12d78872…` and alias `27c7383c…` recomputed equal; every seed review digest equal to its value pinned before the change; `characterisation_serde_tolerance.rs`, `sheet_fingerprint.rs`, `r5_6_switch.rs` green unchanged | -| Rust rules | edit refusals (remove, role change, duplicate role, rename of a role-bearing category); report issues against a base (role disappears, duplicate role) mapped to `verification.validation.rules`; none fires on the seed, the oracles or any fixture; `validate.rs` issue lists identical before and after on every fixture | -| Rust empty sheet | `sheet.empty` creates the three categories with the T5 ids, names, roles and colours and passes `sheet.check` | +| Rust serialisation | both keys round-trip; absent keys not written (no `role` or `fill_opacity` text in the re-serialised seed); explicit `null` refused; opacity outside 10-100 or not an integer refused; unknown role refused | +| Rust identity pins (T2, BDR-068) | equine fingerprint `12d78872…` and alias `27c7383c…` recomputed equal; every seed review digest equal to its value pinned before the change; `characterisation_serde_tolerance.rs`, `sheet_fingerprint.rs`, `r5_6_switch.rs` green unchanged; `fingerprint.rs` construction unchanged in the diff | +| Rust rules, verdict tier (T4) | absolute on the draft: missing role, duplicate role, wrong FR or EN name on a role-bearing category each give an error issue mapped to `verification.validation.rules`; a first version with no base is judged the same; the base is never judged; `validate.rs` issue lists identical before and after on every fixture | +| Rust rules, editor tier (T4) | refused: remove a role-bearing category, change or clear its role, a duplicate role, a rename away from the fixed names, any `navigation` assignment; giving a role writes the fixed names in the same update; repair commands (insert a missing fixed category, restore fixed names, clear a duplicate role) turn every state a direct save can write into one that passes the rule | +| Rust empty sheet | `sheet.empty` creates the three categories with the ratified T5 ids, names, roles and colours and passes `sheet.check` and the T4 rule | | Rust layer | absent keys → R3 trees identical; present `fill_opacity` changes only the twin and zone fill attributes; triggers unchanged; `svg_marker_isolation.rs` green | -| Rust snapshot | `lean_document` and the export gate strip both keys; a snapshot from a New-present document passes the gate and the N-1 shape | +| Rust snapshot (T2, T7) | `lean_document` and the export gate strip both keys; controlled widening: the snapshot reader accepts exactly the two keys with their types and range, and gives `Schema` (report kept) for any other unknown key, `null`, unknown role, out-of-range opacity | +| Equine history (T5) | conversion of an in-memory copy of the seed draft (roles on the T6 categories): seed bytes, fingerprint, alias and every review digest equal before and after; the copy differs only in the converted categories; `pnpm r5:import-equine --check` clean | | App and N-1 | New-present sheet fixture and harness: exported PDFs pass the assertions of `n-1.reader.test.ts:178-196`; `contracts.types.test.ts` green with `ts(optional)`; `measure.test.ts` green; PDF goldens unchanged | -| SQL | the round-withdrawal migration: pgTAP with rounds in `verifying`, `open`, `approved` before it and withdrawn after with the reason; `pnpm db:sandbox up upgrade` from the current migration set; `types --check` | -| Worker | image rebuilt from `HEAD`; `verify-e2e` with a New-absent and a New-present draft; verdict passes for both | -| Unit and E2E app | board 07 locks (no delete, name read-only, role badge, « Couleur d'origine »); opacity slider and field synchronised, commit on release; board 09: regions from the vertebra-role category, picker filtered, staged « Appliquer (n erreurs) »; fallback entry when no category has the role (T17) | -| Acceptance journey | a new non-equine sheet with the new UX (drawing, rectangle view, points, zones, access, findings, custom opacity), saved, submitted, worker verdict passes, round `open`; its PDF exported, reopened by the app and read by N-1 (archive kept) | -| Recovery | a copy taken before an opacity edit restored after reload; conflict journey on a role-bearing category; « Garder ma version » with a keyless document shows the report issue | -| Security | fresh review: no path writes the keys into an envelope; no new SQL business rule | +| SQL | the U6 migration: pgTAP with rounds of draft versions in `verifying`, `open`, `approved` before it and withdrawn after with the reason; core gate: a passed verdict with an older `verified_with` refused, the U6 marker accepted; `save_sheet_draft` accepts a draft without roles; if the owner confirms the non-regression check, it refuses a save that removes or duplicates a role of the stored draft or renames its category away from the fixed names; `private.sheet_fixed_categories_ok` refuses approval and publication outside the fixed model; the rules epoch RPC answers; draft rounds withdrawn while the approved round of each published version stays approved; approval and publication refused without a current passed verdict; `pnpm db:sandbox up upgrade` from the current migration set; `types --check` | +| Worker | image rebuilt from `HEAD`; `verify-e2e` with a New-absent draft (fails on `verification.validation.rules`), the same draft repaired, which then carries roles (passes), and a sheet created by the U6 `sheet.empty` (passes) | +| Write lock (T4) | on a sandbox with the old worker image and the U6 SQL: a role-less draft's round (or, without the confirmed save check, a role-stripped one) never opens (gate); the U6 app on a stack without the rules epoch writes no key and creates no new-model sheet; publication and approval refused outside the fixed model even with a forged passed verdict (pgTAP) | +| Flipped suites | `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 in the commit message; seed unchanged | +| Navigation access (T10, if B is confirmed) | `cat-access` with role `navigation` created on demand in the same batch as the view and its access, only when the overlap list is empty; absent from the category panel and the pickers; an observable annotation in it and a second navigation category refused (edit) and reported (verdict); its role stripped from snapshots, N-1 reads the category | +| Unit and E2E app | board 07 locks (no delete, name read-only, role badge, « Couleur d'origine »); opacity slider and field synchronised, commit on release; board 09: regions from the vertebra-role category, picker filtered, staged « Appliquer (n erreurs) »; fallback entry when no category has the role (T17); board 08 automatic access | +| Acceptance journey | a new non-equine sheet with the new UX (drawing, rectangle view, automatic access, points, zones, findings, custom opacity), saved, submitted, worker verdict passes, round `open`; its PDF exported, reopened by the app and read by N-1 (archive kept); the same journey with the roles stripped by a direct save: refused at save if the owner confirms the non-regression check, otherwise saved with verdict failing and no round; in both branches no publication | +| Recovery | a copy taken before an opacity edit restored after reload; conflict journey on a role-bearing category; « Garder ma version » with a role-less document: on a sheet whose stored draft carries roles, the save is refused under the confirmed non-regression check (otherwise saved, report issue and repair shown); on a role-less sheet it saves and shows the issue and the repair | +| Security | fresh review: no path writes the keys into an envelope; the SQL checks are exactly those declared under T4 and O22 as amended at U0 (publication check, save non-regression if confirmed); the core gate checks a version marker only | | Accessibility | axe on board 07 and 09 states; the opacity value is exposed to assistive technology | ## U7 · Common text +Starts only with the owner's text, its source and its validation record (T12). + | Kind | Tests | |---|---| -| Unit | insertion only into empty FR and EN fields; never overwrites; template id and version in the change note; comparison read-only | +| Unit | insertion only into empty FR and EN fields; never overwrites; template id and version in the change note; comparison read-only; tests use a fixture text marked as a test value, under `tests/` only | +| Review | the shipped template module holds exactly the owner-supplied text; the commit cites the validation record; no other normative wording in `src/` or the dictionaries | | E2E | insert, edit, undo, save, reload | | Accessibility | axe on General with the comparison open | @@ -119,9 +131,11 @@ and real tablets are owner trials. |---|---| | Full run | common gates, `check:all`, sandbox order, `verify-e2e`, N-1 suite, frozen references unchanged, axe on every tab and state, keyboard-only journey, tablet touch journey | | Acceptance | contract §16.7 journey re-run on the redesigned editor | +| Level-1 residuals (T11) | each tracked item re-checked and its state recorded (closed, still open, superseded by the redesign); level 1 still not declared validated as a whole | +| Paths (T16) | before U6 or U8 reaches any environment beyond the throwaway sandbox: read-only count of path geometries in its drafts and published versions recorded (owner or explicit authorisation) | | Owner trial | `V1-2-6_OWNER_TRIAL.md` updated; WebKit iPad and a real tablet by the owner | -## U9 · Curves (if kept, T16) +## Curves lot (ex-U9, deferred out of V1-2.6, T16) | Kind | Tests | |---|---|