docs(docs): R0 owner decisions, A1-A15 table, R3 SQL checkpoint proposal

This commit is contained in:
bchanot committed 2026-11-09 16:27:46 +01:00
1 parent 95009069ca
commit 84aba41b7d
5 files changed
+196 -32

No files matched your search

+23 -11
View File
@@ -1,6 +1,9 @@
# Dedicated manual trial stack: technical plan
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5). Plan
Status: PROPOSAL, 2026-11-09 (owner brief « V1-2.6 UX — Arbitrages du premier essai propriétaire », §5), with the
decisions of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108): name
`pnpm db:trial`, two trial accounts, `db:sandbox trial*` kept for now, isolation from the suites, volumes preserved,
resources capped, secrets renewable. Plan
only: no stack is created, started, reset or removed, no script changes, existing data untouched. Implementation
needs its own owner authorisation. Companion of `V1-2-6_U1_CORRECTIONS.md`.
@@ -61,7 +64,10 @@ gateway does (:422-423).
never argv. Generated once at creation; `start` never regenerates them (the database keeps the role passwords set at
its first initialisation). Keys valid one year instead of 30 days, with a `rotate-keys` command that re-signs both
keys with the same secret and restarts the services: a persistent stack with the sandbox's 30-day keys would lock
itself out after a month. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
itself out after a month. Full renewal (owner 2026-11-09) is `rotate-secrets`: a new JWT secret and new keys, new role
passwords set in the database (`alter role … password`, values through psql variables, never argv), env files
rewritten (600), services restarted in order, the previous secrets file kept as `secrets.prev.sh` (600) until the
stack answers; account passwords are untouched. Both commands print no secret. Since every secret differs from the sandbox's, a suite that reached a trial port by mistake
would be refused by GoTrue, PostgREST and Postgres instead of writing.
### 3.4 Persistence and lifecycle
@@ -83,10 +89,16 @@ would be refused by GoTrue, PostgREST and Postgres instead of writing.
- Migrations of the branch, then `equine_draft.sql` only. Not `seed.sql`: its three accounts carry the public DEV
password (`seed.sql:5`).
- Trial accounts: `account <email>` creates a confirmed account through GoTrue's admin API, password at a hidden
prompt (12 characters minimum), as `cmd_trial_account` does (`db-sandbox.sh:457-472`); `grant <email> <right>` as
`cmd_trial_grant` (:476-496), plus the platform role `owner` if the owner wants the rights screen (arbitration A13).
Administration then asks for a TOTP factor, enrolled in Mon compte.
- Trial accounts (owner 2026-11-09: two distinct accounts): `account <email>` creates a confirmed account through
GoTrue's admin API, password at a hidden prompt (12 characters minimum), as `cmd_trial_account` does
(`db-sandbox.sh:457-472`); `grant <email> <right>` as `cmd_trial_grant` (:476-496).
1. Owner/admin account, for the administration trials: platform roles `owner` and `admin`, catalogue rights
`sheet_editor`, `sheet_reviewer`, `sheet_publisher`.
2. Practitioner account, for the normal journey: `sheet_editor` only, no `owner`, no reviewer or publisher right.
Fact to weigh: today a `sheet_editor` right is active only for a platform admin (rule O1,
`supabase/migrations/20261028100000_sheet_access_hardening.sql:199`), so this account also needs the `admin`
role; without it, it can read the catalogue (`catalog_reader`) but not edit. Changing O1 is out of scope.
Editing and Administration require a TOTP factor (aal2, same file :321-341), enrolled in Mon compte by each account.
- The equine sheet: the seed gives the historical sheet its fixed id and `private.historical_sheet_id()` flags it
(`20261102100000_sheet_admin_reads.sql:56`); it is the only official sheet at creation.
- Its drawings: the existing tool `pnpm assets:upload supabase/seed/anatomical-sheets/equine/draft` (R5.5), through
@@ -113,7 +125,7 @@ sandbox up, about 2 GiB of 14.7 GiB. DEV shares no name, port, network, volume o
## 4. Commands (proposal, arbitration A11)
`pnpm db:trial create | start | stop | status | migrate | backup | rotate-keys | app | account <email> |
`pnpm db:trial create | start | stop | status | migrate | backup | rotate-keys | rotate-secrets | app | account <email> |
grant <email> <right> | assets | destroy`, in a new `scripts/db-trial.sh` built on the sandbox script's functions
(shared helpers extracted to one sourced file rather than copied).
@@ -131,8 +143,8 @@ they created; `shellcheck` on both scripts.
| # | Question | Recommendation |
|---|---|---|
| A11 | Command name, prefix, ports | `pnpm db:trial`, `faunosteo_trial_`, 58xxx and 5194 as in 3.2. |
| A12 | Fate of `pnpm db:sandbox trial`, `trial-account`, `trial-grant` | Removed once the trial stack is validated: one trial path. |
| A13 | Platform roles of the owner's trial account | `admin` with the catalogue rights, plus `owner` only if the rights screen is part of the trial. |
| A14 | Key lifetime | One year, with `rotate-keys`. |
| A11 | Command name, prefix, ports | `pnpm db:trial` (RATIFIED), `faunosteo_trial_`, 58xxx and 5194 as in 3.2 (open). |
| A12 | Fate of `pnpm db:sandbox trial`, `trial-account`, `trial-grant` | DECIDED: kept for now, neither removed nor silently redirected. |
| A13 | Trial accounts | DECIDED: two accounts (3.5). Open: confirm the practitioner account takes `admin` because of O1. |
| A14 | Key lifetime and renewal | Renewal DECIDED (`rotate-keys`, `rotate-secrets`); one-year lifetime open. |
| A15 | Backup before every `migrate` | Automatic, kept in the state folder, never pruned without the owner. |
@@ -0,0 +1,67 @@
# R3 SQL checkpoint: a true last-modification date for the sheet list
Status: PROPOSAL for the owner's dedicated SQL checkpoint, 2026-11-09 (brief « R0 — Décisions propriétaire et
dernière validation graphique », A7). Nothing here is written as a migration; no SQL, application, script or sandbox
change before the owner authorises this checkpoint. Companion of `V1-2-6_U1_CORRECTIONS.md` (lot R3).
## 1. The problem
The admin list and the sheet page read `private.official_sheet_admin_summary` (`supabase/migrations/
20261102100000_sheet_admin_reads.sql:40-92`), which returns `anatomical_sheets.updated_at` (:54). A draft save writes
`anatomical_sheet_versions` only (`public.save_sheet_draft`, `20261028110000_sheet_review_workflow.sql:569-630`), so
the sheet row's date does not move when a draft is edited. Read on the sandbox (2026-11-09, select only): 28 of 219
official sheets have a version newer than the sheet row, up to 15 s apart; the fixed historical draft and the owner's
`cheval11` happen to agree. The owner's rule until this lands: no creation date shown as a modification date, no
misleading sort.
## 2. Proposed change (one read change, no table, policy or privilege change)
A new migration replaces `private.official_sheet_admin_summary` with the same body plus one key:
```sql
'last_modified_at', greatest(s.updated_at, (
select max(v.updated_at) from public.anatomical_sheet_versions v where v.sheet_id = s.id))
```
- `greatest` ignores a null, so a sheet without a version keeps its own date.
- Both columns are kept by the existing `set_updated_at` triggers (`20261008110000_anatomical_sheets.sql:90-92`,
:143-145): a draft save, a status change, a publication, an archive, a metadata edit and the working copy's own
writes all move one of them. Review rounds and audit rows are not modifications of the sheet and do not count.
- The per-sheet `max` uses the existing unique index on `(sheet_id, version_number)` (:118) for the lookup by
`sheet_id`; the list is already one summary call per sheet, so the cost is one more indexed aggregate per row. RR-13
(server paging) will sort on the same expression.
- `get_official_sheet_admin` and `list_official_sheets_admin` both call the summary and return the key unchanged;
their signatures, `security definer`, `search_path` and grants are untouched (the revokes at
`20261102100000_sheet_admin_reads.sql:244` stay in force).
- `updated_at` stays in the payload with its current meaning; nothing that reads it changes.
## 3. Verification the checkpoint asks for
- pgTAP in `supabase/tests/022_sheet_admin_reads.sql`: a draft save moves `last_modified_at` and not `updated_at`; a
sheet metadata change moves both; a sheet without a version answers its own date; the key is present for every
listed sheet; the call rights unchanged (existing tests :186-190 re-run).
- `pnpm --filter @faunosteo/supabase test:run` (PGlite) and `pnpm db:test` on a real stack.
- `pnpm db:types`: the functions return `jsonb`, so the generated types do not change; the hand-written summary type
in `packages/supabase/src/sheets.ts` gains `last_modified_at`.
## 4. Applying it to a stack: an owner decision
`scripts/db-sandbox.sh` has no command that applies a new migration to a running sandbox: `up upgrade` builds a new
one, which removes the current sandbox (owner rule: inventory, then a go for that operation). Three paths, none taken
without the owner:
| Path | Effect |
|---|---|
| a. Apply to the trial stack once it exists (`pnpm db:trial migrate`, `TRIAL_STACK.md` §3.4) | No sandbox change; the owner sees the date in the trial |
| b. A `migrate` command added to `db-sandbox.sh` (forward only, no reset) | A script change, its own go; keeps the sandbox's data |
| c. `pnpm db:sandbox up upgrade 2026…` on a new sandbox | Removes the current sandbox: inventory and owner go first |
Recommendation: a (with b only if the shell suite must see the date before the trial stack exists). PGlite and
`pnpm db:test` need no existing stack.
## 5. What R3 does before and after
- Before: search and clear, sort by name only, no date on the rows, the Administration card without a date or a
« most recent » claim (the first five by name, with « Voir les N fiches »).
- After: « Modifiée le … » from `last_modified_at`, « Dernière modification » as the default sort, the card listing the
five most recently modified sheets. Boards 28 and 29 draw this final state.
+30 -19
View File
@@ -69,7 +69,8 @@ reference of R1 to R4.
first (it has no explicit handler today).
- Unit tests: deselect leaves the document text and the history length unchanged; undo after a deselect undoes the
previous edit; the Escape matrix (dialog, menu, panel, tracing, nothing open) with one consumer each time; focus
after « Désélectionner » on the annotation's list row (arbitration A6); accessible names of both history buttons in FR and EN; read-only modes
after « Désélectionner »: the annotation's list row if it still exists, else the drawing, with no new selection
and a polite announcement (A6 as ratified); accessible names of both history buttons in FR and EN; read-only modes
show « Désélectionner » and no « Supprimer ».
- E2E: the journeys that name « Annuler » / « Rétablir » rewritten one for one; a new desktop spec for the button and
Escape; axe on Annotations with a selection.
@@ -98,7 +99,8 @@ reference of R1 to R4.
- Unit tests (about 15 files today assert the four-tab structure or the panel): five tabs and the « Plus » tier at
500 px; each sort, stable, document untouched (text compared before and after); reorder commands present only in
document order without search; clear button; tile disclosure and focus; « Aller à » from Vérification opens the
tab, the tile open and focused; « Aller à » from a tile reaches the finding; the panel from a finding: filtered,
tab, the tile open and focused; « Aller à » from a tile reaches the finding; the panel from a finding: filtered, « Retirer de ce constat » removes only that citation (the reference
stays in the document) and one undo restores it,
« Tout afficher » opens the tab with search and sort reset and focus on its heading, close returns focus to the
finding's button; unsaved edits in a tile form survive a tab change (kept-mounted places); no edit control in any
read-only mode or without the editor right; the reduced-motion class.
@@ -120,7 +122,9 @@ reference of R1 to R4.
the sandbox, 28 of 219 official sheets have a version newer than the sheet row. A true « dernière modification »
needs one read change in SQL (a `last_modified_at` field, greatest of the sheet's and its versions' `updated_at`,
in `private.official_sheet_admin_summary`; no table, policy or privilege change), hence an SQL checkpoint, pgTAP,
regenerated types, and its application to the sandbox, which needs the owner's go for that operation.
regenerated types, and its application to a stack, which needs the owner's go for that operation. Ratified (A7):
the dedicated checkpoint is `V1-2-6_R3_SQL_CHECKPOINT.md`; R3 ships in two steps, search and name sort with no date
first, the date, the date sort and the « most recent » card only once the SQL change is authorised and applied.
- Search and sort run in the browser on the full list: `shortcut:` until RR-13 pages the list on the server, where
search and sort move with it.
- Tests: unit for search (accents, both languages, empty, clear), sort (date ties by name, collation), date format
@@ -141,7 +145,7 @@ reference of R1 to R4.
## 4. Order and dependencies
R0 first (validation). R1 is independent of R2 and can ship first. R2 depends on the validated boards 23 to 27. R3
depends on arbitration A7; with the SQL option, its migration goes through its own checkpoint before the UI part.
ships search and name sort first; its date part waits for the SQL checkpoint (A7 ratified).
R4 is independent and may run any time after its board (30) is validated. Anomaly B (section 5) should land before
the gates of R2 and R3 are read, since its taken slot fails four admin specs on every run.
@@ -153,19 +157,26 @@ the gates of R2 and R3 are read, since its taken slot fails four admin specs on
| B. Working copy never archived | `packages/supabase/tests/sandbox/sheets-admin.sandbox.ts:181-195` creates the historical sheet's working copy (`8c315a12-…`, 2026-11-08 21:00:30) and never archives it; the single slot then disables « Créer une copie de travail » (`WorkingCopyAction.tsx:88`) and fails `admin.spec.ts:717` four times. | Make the suite independent (its own cleanup, or a precondition it creates and removes); the existing copy is not touched before the owner authorises it. |
| C. Silent card failure | Section 3, R4. | Show the failure, never hide or route around it. |
## 6. Arbitrations for the owner
## 6. Arbitrations
| # | Question | Recommendation |
|---|---|---|
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. |
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. |
| A3 | Actions in the contextual panel | Modifier, « Aller à »; no add, no reorder. Every reference in the panel is cited by the finding, so « Supprimer » would always be refused by the core (no dangling reference): offer « Retirer de ce constat » (removes the id from the finding's citations, an ordinary undoable edit) instead, or nothing. « Tout afficher » opens the tab with search and sort reset, focus on its heading. |
| A4 | Closed tile content | Citation on two lines at most, type, « Citée par N constats » or « Non citée ». |
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. |
| A5b | « Toutes les annotations » (top of the properties panel) already clears the selection | Keep both: « Désélectionner » sits where the eye is after acting on an annotation, as decided (D6); the top entry keeps its role of returning to the list. Alternative: rename the top entry. |
| A6 | Focus after « Désélectionner » (the button leaves with the selection) | The annotation's row in the list, as « Toutes les annotations » already does (`PropertiesPanel.tsx:92-102`, `focusRow`). |
| A7 | Source of the last-modification date | SQL read change `last_modified_at` with its own checkpoint (recommended). Without it, label the row « Fiche modifiée le » and accept that draft saves do not move it. |
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). |
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». |
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line for a load that failed for another reason. |
| A11 to A15 | Trial stack: names, ports, old trial commands, account roles, key lifetime, backups | `TRIAL_STACK.md` section 6. |
Status as of the brief « R0 — Décisions propriétaire et dernière validation graphique » (2026-11-09, BDR-108).
The owner-facing table with consequences, in French: `docs/design/v1-2-6-r0/ARBITRAGES.md`.
| # | Question | Recommendation | Status |
|---|---|---|---|
| A1 | Reorder commands with a search active in document order | Hidden, as checkpoint choice 10 already rules (moving among a hidden subset is ambiguous); one hint line. | open |
| A2 | Tiles open at once; how long open state, search and sort last | Several open at once; kept while the editor stays open (kept-mounted tab), reset when it reopens. | open |
| A3 | Actions in the contextual panel | « Modifier », « Retirer de ce constat », « Aller à »; no add, no reorder, no « Supprimer » (always refused by the core there). « Tout afficher » opens the tab with search and sort reset, focus on its heading. | RATIFIED: « Retirer de ce constat » removes only the finding's citation of the reference, never the reference; undoable through the editor history |
| A4 | Closed tile content | Citation on two lines at most, type, « Citée N fois » or « Non citée » (the count includes families). | open |
| A5 | Escape priority | Dialog, then open menu, then contextual panel, then tracing in progress, then selection. | open |
| A5b | « Toutes les annotations » already clears the selection | Keep both (D6). | open |
| A6 | Focus after « Désélectionner » | The annotation's row in the list. | RATIFIED with precision: the row if it still exists, else the drawing; focus never selects again; an accessible announcement |
| A7 | Source of the last-modification date | SQL read change `last_modified_at`, own checkpoint. | RATIFIED: dedicated SQL checkpoint `V1-2-6_R3_SQL_CHECKPOINT.md`; until then no creation date shown as a modification date and no misleading sort |
| A8 | Date format | Absolute, « 9 nov. 2026, 12:06 » (EN « 9 Nov 2026, 12:06 »). | open |
| A9 | Administration home card | The five most recently modified sheets with species, status and date, then « Voir les N fiches ». | open (needs A7 first) |
| A10 | Catalogue warning wording | FR « Contrôle d'intégrité échoué : cette version ne peut pas être affichée. », a distinct line with « Réessayer » for a load that failed for another reason. | R4 ACCEPTED as an independent display fix, the fingerprint check unchanged; wording open |
| A11 | Trial stack command | `pnpm db:trial`, prefix `faunosteo_trial_`, ports 58xxx and 5194. | RATIFIED: `pnpm db:trial`; prefix and ports open |
| A12 | Old `db:sandbox trial*` commands | Remove once the trial stack is validated. | DECIDED otherwise: kept for now, neither removed nor silently redirected |
| A13 | Trial accounts | `admin` with catalogue rights, `owner` if needed. | DECIDED: two accounts, an owner/admin account and a practitioner account with the editing rights (see `TRIAL_STACK.md` §3.5 on rule O1) |
| A14 | Key lifetime and secret renewal | One year, `rotate-keys`. | Renewal RATIFIED (`TRIAL_STACK.md` §3.3); lifetime open |
| A15 | Backup before every `migrate` | Automatic, kept, never pruned without the owner. | open (volumes preserved: ratified) |