docs(docs): R4 plan rev 3 validated, contract
This commit is contained in:
1 parent
b895ecf136
commit
7575c67c47
2 files changed
+167
-24
No files matched your search
@@ -1,10 +1,14 @@
|
||||
# R4 Catalogue Card Integrity Warning Implementation Plan (V1-2.6), rev 2
|
||||
# R4 Catalogue Card Integrity Warning Implementation Plan (V1-2.6), rev 3
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development to implement this plan task-by-task.
|
||||
> Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Status:** DRAFT rev 2, waiting for the owner's answers to D1 to D4. No implementation before them. DEV unchanged,
|
||||
no merge. BLK-015 and RR-13 stay separate tracks. Rev 2 = rev 1 + three fresh challenges of 2026-11-16 (correctness
|
||||
**Status:** VALIDATED by the owner, 2026-11-17 (brief « Je valide le plan R4 avec les décisions suivantes »): D1
|
||||
ALTERNATIVE (a version over the size limits shows the existing caps text, no « Réessayer », told apart from an
|
||||
integrity failure); D2, D3, D4 as recommended; R-2 to R-7 accepted. Owner precisions, binding: (P1) the trial
|
||||
procedure says how to tell the anomalies already on the sandbox from R4's own behaviour; (P2) the spec cleans only
|
||||
the sheets and the right it created, identity checked, no pre-existing row changed. Implementation authorised on the
|
||||
sandbox. DEV unchanged, no merge. BLK-015 and RR-13 stay separate tracks. Rev 3 = rev 2 + the owner's answers. Rev 2 = rev 1 + three fresh challenges of 2026-11-16 (correctness
|
||||
FATAL(4), robustness FATAL(4), simplicity FATAL(3)); what became of each finding is in « Challenge round » at the end.
|
||||
|
||||
**Goal:** a catalogue card whose published version fails the core's integrity check says so inside the card, with
|
||||
@@ -45,26 +49,27 @@ the executor writes the JSX under TDD against board 30.
|
||||
| F11 | The core runtime does not retry a failed first load by itself: `ready()` answers false until `coreRuntime().retry()` is called; the sheet page and `CatalogueCanvas` call it before reloading. Each trap spends one of three recoveries for the whole tab. | `packages/core-wasm/src/runtime.ts:142-184`, `catalogue/useSheetVersion.ts:85-88`, `CatalogueCanvas.tsx:100-104` | The card's retry for `core_unavailable` calls `coreRuntime().retry()` first (R-2). |
|
||||
| F12 | e2e: the app talks to a fake `.invalid` origin served only by the `routeToSandbox` context route; Playwright runs the last route first. Every card loads at mount (156+ on the sandbox). | `e2e/support/sandbox.ts:12, 33-40`, `CatalogRoute.tsx:68` | A route that aborts one version must `route.fallback()` the rest and be removed alone; the spec searches its tag before any check (as `catalogue.spec.ts`). |
|
||||
|
||||
## Owner decisions pending
|
||||
## Owner decisions (answered 2026-11-17: D1 ALTERNATIVE, D2 to D4 recommendation)
|
||||
|
||||
| # | Question | Recommendation | Alternative(s) | Cost if wrong |
|
||||
|---|---|---|---|---|
|
||||
| D1 | `caps` (a version over the size limits) in a card | Integrity line, error tone, A10 text, no « Réessayer »: the core refuses the version itself and a retry cannot change it. | Its own line, existing text `catalogue.failure.caps` (« Cette version dépasse les limites de taille d'une fiche. »), error tone, no retry. | One mapping line. |
|
||||
| D2 | The version passes the check but its main view cannot be drawn (no thumbnail) | Say it: a neutral line (tone `info`, not a live region) with the existing text `catalogue.failure.view`; counts and « Consulter » kept; when the engine itself failed (F5) the core line with its retry instead. Nothing left silent, no new wording. | (a) Silent as today (no code). (b) A new shorter text for the card, to ratify (e.g. « L'aperçu de cette fiche ne peut pas être affiché. »). | One component branch and its test; built only if chosen. |
|
||||
| D3 | Where the owner tries R4 | `pnpm db:sandbox trial` (the automated-test stack served for a manual trial, used on 2026-11-09): its 4 failing entries show the integrity line as they are; the network line by hiding a card with a search, going offline in DevTools, clearing the search, waiting about 7 s, going back online, « Réessayer ». No write by Claude on any stack. The page loads slowly there (156 cards each load their version). | (a) Seed two published test sheets on the trial stack (one sound, one with a wrong stored fingerprint) through a new `db:trial` step: a script change and a write on the owner's trial data, its own go. (b) Both. | (a) adds a script and a write; the recommendation adds none. |
|
||||
| D4 | Cleanup of the browser spec's own data on the persistent sandbox (F9): published test sheets cannot be deleted | The spec archives its own sheets at the end, by SQL as postgres under the seed owner, the same « prior owner action » form as its seed (status `archived`, read back per id), and revokes its own catalogue grant the same way; it touches no other row. Archived sheets leave the catalogue. | (a) No cleanup, as `catalogue.spec.ts` today: every run leaves one broken card listed on the sandbox (and in the D3 trial). (b) Archive through the application RPC with an aal2 publisher account: one more account and grant per run (BLK-015). | (a) grows the shared catalogue with broken cards; the recommendation writes only the run's own rows. |
|
||||
| D1 | `caps` (a version over the size limits) in a card | Integrity line, error tone, A10 text, no « Réessayer »: the core refuses the version itself and a retry cannot change it. | Its own line, existing text `catalogue.failure.caps` (« Cette version dépasse les limites de taille d'une fiche. »), error tone, no retry. | One mapping line. ANSWER: alternative (own caps line, no retry). |
|
||||
| D2 | The version passes the check but its main view cannot be drawn (no thumbnail) | Say it: a neutral line (tone `info`, not a live region) with the existing text `catalogue.failure.view`; counts and « Consulter » kept; when the engine itself failed (F5) the core line with its retry instead. Nothing left silent, no new wording. | (a) Silent as today (no code). (b) A new shorter text for the card, to ratify (e.g. « L'aperçu de cette fiche ne peut pas être affiché. »). | One component branch and its test; built only if chosen. ANSWER: recommendation. |
|
||||
| D3 | Where the owner tries R4 | `pnpm db:sandbox trial` (the automated-test stack served for a manual trial, used on 2026-11-09): its 4 failing entries show the integrity line as they are; the network line by hiding a card with a search, going offline in DevTools, clearing the search, waiting about 7 s, going back online, « Réessayer ». No write by Claude on any stack. The page loads slowly there (156 cards each load their version). | (a) Seed two published test sheets on the trial stack (one sound, one with a wrong stored fingerprint) through a new `db:trial` step: a script change and a write on the owner's trial data, its own go. (b) Both. | (a) adds a script and a write; the recommendation adds none. ANSWER: recommendation; P1 on the procedure. |
|
||||
| D4 | Cleanup of the browser spec's own data on the persistent sandbox (F9): published test sheets cannot be deleted | The spec archives its own sheets at the end, by SQL as postgres under the seed owner, the same « prior owner action » form as its seed (status `archived`, read back per id), and revokes its own catalogue grant the same way; it touches no other row. Archived sheets leave the catalogue. | (a) No cleanup, as `catalogue.spec.ts` today: every run leaves one broken card listed on the sandbox (and in the D3 trial). (b) Archive through the application RPC with an aal2 publisher account: one more account and grant per run (BLK-015). | (a) grows the shared catalogue with broken cards; the recommendation writes only the run's own rows. ANSWER: recommendation (soft deletion and grant removal authorised; ruling in Task 2). |
|
||||
|
||||
## Recorded unless the owner objects
|
||||
|
||||
- R-1 Integrity class (error tone, A10 text in bold, glyph `alert`, no retry): `fingerprint_mismatch`,
|
||||
`drawing_hash_mismatch`, `drawing_missing`, `invalid_document` (board 30 note « Portée »), plus `caps` if D1 as
|
||||
recommended. `drawing_missing` includes Storage answering « not found » for the drawing (400 or 404, folded by
|
||||
`drawing_hash_mismatch`, `drawing_missing`, `invalid_document` (board 30 note « Portée »). D1 (owner): `caps` is NOT
|
||||
integrity: its own line, existing text `catalogue.failure.caps` (« Cette version dépasse les limites de taille
|
||||
d'une fiche. »), error tone, glyph `alert`, no « Réessayer » (a retry cannot change the version). `drawing_missing` includes Storage answering « not found » for the drawing (400 or 404, folded by
|
||||
`classifyDrawingError`): an illustration the server does not give is missing (board 30 « illustration manquante »).
|
||||
The executor checks which Storage answers fold there and pins them in a test.
|
||||
- R-2 Other class (warning tone, existing text, « Réessayer » for that card): every other kind; texts
|
||||
`catalogue.failure.<kind>`, `access_denied.title` for `denied`, the core's text and retry label for
|
||||
`core_unavailable` (its retry calls `coreRuntime().retry()` before reloading, F11). Retry offered unless the kind is
|
||||
integrity or the engine stopped for good, as `CatalogueFailureNotice`. A version that traps the core spends one of
|
||||
integrity or `caps`, or the engine stopped for good (the page's own rule, plus D1). A version that traps the core spends one of
|
||||
the tab's three recoveries per click, as on the sheet page (accepted, same blast radius).
|
||||
- R-3 Announcements and focus: the lines are not live regions (no burst of announcements at load when several
|
||||
cards fail). During a retry the line and « Réessayer » stay in place, the button `aria-disabled` and the card
|
||||
@@ -129,7 +134,7 @@ the executor writes the JSX under TDD against board 30.
|
||||
export function cardFailure(
|
||||
failure: CatalogueFailure,
|
||||
stopped: boolean,
|
||||
): { integrity: boolean; retry: boolean }
|
||||
): { integrity: boolean; refused: boolean; retry: boolean }
|
||||
|
||||
// catalogue/useCardDetails.ts
|
||||
export type CardState =
|
||||
@@ -145,20 +150,23 @@ const INTEGRITY: ReadonlySet<CatalogueFailure> = new Set([
|
||||
'drawing_hash_mismatch',
|
||||
'drawing_missing',
|
||||
'invalid_document',
|
||||
'caps', // D1
|
||||
])
|
||||
|
||||
/** How a catalogue card treats its failure (board 30, A10): never hidden, retried where it can work. */
|
||||
/**
|
||||
* How a catalogue card treats its failure (board 30, A10, owner D1): never hidden; `refused` when the
|
||||
* version itself is refused (integrity, or over the size limits), retried only where a retry can work.
|
||||
*/
|
||||
export function cardFailure(failure: CatalogueFailure, stopped: boolean) {
|
||||
const integrity = INTEGRITY.has(failure)
|
||||
const retry = !integrity && !(failure === 'core_unavailable' && stopped)
|
||||
return { integrity, retry }
|
||||
const refused = integrity || failure === 'caps'
|
||||
const retry = !refused && !(failure === 'core_unavailable' && stopped)
|
||||
return { integrity, refused, retry }
|
||||
}
|
||||
```
|
||||
|
||||
`CardFailure` derives the rest at its one render site: text (`catalogue.card.integrity_failed` for integrity,
|
||||
`CardFailure` derives the rest at its one render site: text (`catalogue.card.integrity_failed` for integrity, `catalogue.failure.caps` for caps,
|
||||
`coreFailureMessage(t, 'sheet.core_unavailable')` for the core, `access_denied.title` for `denied`, else
|
||||
`catalogue.failure.<kind>`), tone (`error` / `warning`), glyph (`wifi-off` for `network`, else `alert`), retry label
|
||||
`catalogue.failure.<kind>`), tone (`error` when `refused`, else `warning`), glyph (`wifi-off` for `network`, else `alert`), retry label
|
||||
(`sheet.core_retry` for the core, else `common.retry`).
|
||||
|
||||
Hook behaviour: today's loading and freeing order kept (preview freed once the canvas is composed, blob URL revoked
|
||||
@@ -185,13 +193,15 @@ into a plain async function and the hook.
|
||||
7. core first load fails (`coreRuntime().ready` stubbed to `false` once): the core line with `sheet.core_retry`;
|
||||
click: `coreRuntime().retry` called, the card loads.
|
||||
8. `session_expired` and `denied`: their texts, with « Réessayer ».
|
||||
8b. caps (D1): a document over a size limit (or `coreFailure('caps')` through a stubbed preview state): the card
|
||||
shows `fr['catalogue.failure.caps']`, error tone, NOT the integrity text, no « Réessayer », « Consulter » kept.
|
||||
9. the existing first test: « Chien, rachis » also shows `fr['access_denied.title']` (F7).
|
||||
10. English: the integrity line reads the EN text.
|
||||
11. `cardFailure` exhaustiveness: every member of `CatalogueFailure` gives the expected pair (the test lists the
|
||||
union's members and fails on a new one).
|
||||
12. `Notice` defaults: `error` keeps `role="alert"` and `alert`, `success` keeps `check`; `live={false}` removes the
|
||||
role; `icon` overrides the glyph.
|
||||
13. D2 only if chosen: the main view's canvas refused shows `catalogue.failure.view` (tone `info`, no role) with the
|
||||
13. D2 (owner, validated): the main view's canvas refused shows `catalogue.failure.view` (tone `info`, no role) with the
|
||||
counts; the canvas answering `core_unavailable` shows the core line with its retry.
|
||||
- [ ] **Step 2: Run, expect FAIL** `pnpm --filter @faunosteo/app exec vitest run tests/unit/routes.catalogue.test.tsx`.
|
||||
- [ ] **Step 3: Implement** `cardFailure`, `Notice`, `Icon`, the hook, `CardFailure`, the card, the two dictionary lines.
|
||||
@@ -209,10 +219,19 @@ into a plain async function and the hook.
|
||||
- Fixtures (`beforeAll`): one tag per run; one `listed` sheet with the core's fingerprint (« R4 <tag> saine »), one
|
||||
with `storedFingerprint: '0'.repeat(64)` (« R4 <tag> altérée »); one catalogue reader account and grant as
|
||||
`catalogue.spec.ts` does. Ids kept in the run's own list.
|
||||
- Cleanup (`afterAll`), per D4 as recommended: each own sheet archived on its own by SQL as postgres under the seed
|
||||
owner (the executor uses the migrations' own archive path, e.g. `private.set_sheet_status`, never a bare update
|
||||
that skips its triggers), read back `archived`; the run's grant revoked the same way and read back; failures
|
||||
listed, then asserted empty. If D4 is (a), no cleanup and the accumulation line goes to TODO.
|
||||
- Cleanup (`afterAll`), D4 (owner, validated): each own sheet id archived on its own by SQL as postgres, through
|
||||
`private.set_sheet_status(<seed owner>, <id>, 'active', 'archived', 'anatomical_sheet.archived')` (the migrations'
|
||||
own path, audit row included), then read back `status = 'archived'` for that id; the run's own catalogue grant
|
||||
revoked by id (`update public.anatomical_catalog_grants set revoked_at = now(), revoked_by = <its account>,
|
||||
revocation_reason = 'e2e cleanup' where id = <the grant id captured at seed> and revoked_at is null returning id`),
|
||||
read back. Every statement names one id the run captured; nothing matches by pattern. Failures listed, then
|
||||
asserted empty. `seedGrant` returns the grant id (additive). The run's account stays (accounts are not cleaned by
|
||||
any suite; tracked with BLK-015).
|
||||
Ruling (controller): archive, not soft delete, although the owner authorised soft deletion: the application
|
||||
never deletes a sheet that had a published version (§6.9, `delete_anatomical_sheet`), so a deleted row with
|
||||
published history is a state no screen can reach; archiving is reachable, takes the sheet out of the catalogue and
|
||||
stays inside the owner's authorisation. Cost if wrong: archived test sheets remain visible in the admin sheet
|
||||
list under « Archivée » (one line per run, tagged « R4 <tag> »).
|
||||
- Integrity, per locale (fr, en) and project (desktop, chromium-375): sign in, open the catalogue, search the tag;
|
||||
the altered card shows the integrity line, its « Consulter » focusable and opening the sheet page, which shows its
|
||||
unchanged `catalogue.failure.fingerprint_mismatch` notice; the sound card shows its counts; axe on the searched
|
||||
@@ -232,7 +251,12 @@ into a plain async function and the hook.
|
||||
- Mandatory: `V1-2-6_U1_CORRECTIONS.md` §R4 as built (classes, R-1 to R-8, D1 to D4 answers) and §5 row C closed;
|
||||
the review's Part II row (R-8); `CHANGELOG.md`; `.claude/tasks/TODO.md` (one line per run, shortcuts harvested).
|
||||
- One line each: `BROWSER_TESTS.md` (the new spec), `docs/design/README.md` (only if a deviation from board 30).
|
||||
- Per D3: `V1-2-6_OWNER_TRIAL.md` §4.16 in French, no em-dash, with the remount and the wait of the offline step.
|
||||
- D3 (owner, validated): `V1-2-6_OWNER_TRIAL.md` §4.16 in French, no em-dash, on `pnpm db:sandbox trial`, with the
|
||||
remount and the wait of the offline step. P1: it names the sandbox's pre-existing failing entries (anomaly A: the
|
||||
current versions stored with the fictitious fingerprint, listed by name from a read-only query at Task 3, and any
|
||||
other entry the catalogue shows failing, classified by kind) and says what is R4's own behaviour (the line inside
|
||||
the card, « Consulter » kept, the unchanged sheet page, « Réessayer » on a load failure) as opposed to the data's
|
||||
fault (why those versions fail, which R4 does not fix).
|
||||
- Gates, in order: task reviews, design review against board 30 (screenshots desktop and 375 px from the spec run),
|
||||
final code review, security review of the diff, fresh verifier on the contract, `pnpm check:all`.
|
||||
- Commit `docs(docs): R4 catalogue card integrity warning as built`.
|
||||
|
||||
Reference in new issue
Block a user