docs(app): R3 sheet list documents as built, M9 applied

V1-2-6_U1_CORRECTIONS §R3 as built (A7 split superseded by D2, exact
results, deviations), the SQL checkpoint applied with corrections F2 to
F4, the owner's answers and the date limits F7, M9 in §12.3, db:sandbox
migrate, the sheet list spec and its named failures, class C rows, the
design deviations, CLAUDE.md and CHANGELOG. Gates pending.
This commit is contained in:
bchanot committed 2026-11-16 17:47:49 +01:00
1 parent 73ed37546f
commit a86020d6e3
9 files changed
+235 -12

No files matched your search

+83 -4
View File
@@ -1,9 +1,12 @@
# R3 SQL checkpoint: a true last-modification date for the sheet list
Status: DESIGN ACCEPTED by the owner, 2026-11-09 (verdict « R0 — Verdict de revue graphique propriétaire », BDR-109),
after the brief « R0 — Décisions propriétaire et dernière validation graphique » (A7). No migration is created or
applied for now; writing and applying it needs the owner's later go. R3 keeps its split before and after this
checkpoint (section 5). Companion of `V1-2-6_U1_CORRECTIONS.md` (lot R3).
Status: APPLIED 2026-11-16 as M9 `supabase/migrations/20261116100000_sheet_admin_last_modified.sql`, on the
sandbox and on the trial stack (`pnpm db:trial`); DEV unchanged. History: design accepted by the owner, 2026-11-09
(verdict « R0 — Verdict de revue graphique propriétaire », BDR-109), after the brief « R0 — Décisions propriétaire et
dernière validation graphique » (A7); writing and applying it authorised by the owner on 2026-11-16 (section 6). The
split before and after this checkpoint (section 5) is superseded by the owner's decision D2: R3 shipped in one lot.
Sections 1 to 5 are the checkpoint as accepted on 2026-11-09, with the corrections of 2026-11-16 marked in place.
Companion of `V1-2-6_U1_CORRECTIONS.md` (lot R3).
## 1. The problem
@@ -42,6 +45,11 @@ A new migration replaces `private.official_sheet_admin_summary` with the same bo
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.
Correction 2026-11-16 (F3): `pnpm db:test` runs `supabase test db` on the DEV stack, and V1-2 is sandbox only. The
real-PostgreSQL run is `pnpm db:sandbox test-db`, after the sandbox is migrated; DEV stays untouched.
- Correction 2026-11-16 (F4): a pgTAP file runs in one transaction, where `now()` is frozen and `set_updated_at`
stamps `now()`. « A draft save moves `last_modified_at` and not `updated_at` » cannot be seen on rows dated
`now()`, so the new fixture rows are dated in the past at insert (the trigger stamps updates only).
- `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`.
@@ -60,9 +68,80 @@ without the owner:
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.
Correction 2026-11-16 (F2, F3): path a alone was not enough. The shell suite runs on the sandbox, and once the
client requires the key every admin and editor spec fails at load on a stack without M9, and nothing would prove the
date on a real PostgreSQL. Both paths were taken: b first (`pnpm db:sandbox migrate`, forward only, additions
only to the script), then a, then the application code (owner decision D3). The last sentence above is
wrong for `pnpm db:test`, which runs on DEV (section 3).
## 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.
Superseded 2026-11-16 (owner decision D2): the « before » state was never built. R3 shipped once, in the « after »
state.
## 6. Owner's answers and application (2026-11-16)
Owner messages of 2026-11-16, verbatim in `.claude/tasks/contracts/2026-11-16-r3-sheet-list-1720.md`:
- Plan validation (rev 2): D1 yes (write M9 and its pgTAP), D2 yes (one delivery in the final state), D3 yes (the
sandbox through the new `pnpm db:sandbox migrate` without a reset, then `db:trial` after an operational checkpoint,
then the application), D4 yes (RR-13 widened to the paging of the admin lists, rights and official sheets, not
implemented in R3), D5 no (the list state kept on return stays out of R3, tracked as a later navigation
improvement), D6 yes, D7 yes. Precisions: (P1) the tests cover the real computation on PostgreSQL, drafts and
working copies included; (P2) the migration reviewed and frozen before its first application; (P3) the application
never shows an old or wrong date as a reliable last modification; (P4) exact test results kept, the known BLK-015
failures included.
- Go for the trial stack: the controller runs the operations (state check, the app on port 5194 identified then
stopped, cold backup, `pnpm db:trial migrate`, the six containers checked, integrity checks, the app restarted); on
a backup or migration failure, stop and report, no destructive restore without a new go; the pgTAP failures of 014
and 021 kept in the tracking, the suite never presented as green.
As applied:
- M9 is the M7 summary body plus the key of section 2, the revoke restated; no table, policy, index or privilege
change. Task review and security review before the first application (security PASS, one LOW finding that
predates M9: file 022 checks the helper's revoke for `authenticated` only, not for `service_role`). Frozen since:
blob `a33b1770`.
- pgTAP `022_sheet_admin_reads.sql`, plan 74 (60 before): a draft newer than its sheet row, a sheet without a version,
a draft save that moves `last_modified_at` and leaves the sheet row's `updated_at`, a sheet change that moves
both, a dated working copy and its draft save, a sheet row newer than its versions, the key on every listed sheet.
- Sandbox (`pnpm db:sandbox migrate`): `20261103100000` → `20261116100000`, a second run applies nothing. Data guard
before and after (6 981 sheets, 7 130 versions, full rows per id): identical. Function digest
`3a61a802…` → `1a4a1157…`. `pnpm db:sandbox types --check`: no drift. Recomputation of every official sheet not
deleted against `greatest(s.updated_at, max(v.updated_at))`: 6 981 checked, 0 mismatch, 0 null, 11 working copies
(0 mismatch), 1 historical sheet; 6 579 sheets whose date now differs from `updated_at`, 0 older than it. pgTAP on
the real image: Files=21, Tests=1958, Result FAIL, with `022` and `023` ok, `014_animals_relations` 2 of 258 failed,
`021_sheet_verification_jobs` 23 failed with « Bad plan. You planned 90 tests but ran 42 ». Read as dependent on the
accumulated sandbox state, M9 touching neither file's functions; NOT proven by a run without M9 or on a fresh
stack.
- Trial stack (`pnpm db:trial migrate`, 21 s, 14:41:52Z to 14:42:13Z): backup `20261116T144154Z-pre-migrate` (63M),
checked by the script before the migration, then by hand (`SHA256SUMS` 5 entries all match, `db.tar` 1 371 entries,
`storage.tar` 6 entries); 18 migrations applied, six containers running. Digest of 58 tables, 155 functions
(definition and privileges), 23 policies and 20 table grants before and after: exactly 3 lines differ (the
migration registry 17 → 18 rows and its new row, the summary function's definition = the sandbox's digest
`1a4a1157…`, its privileges unchanged). Accounts, roles, TOTP factors, the 2 sheets, 2 versions and 2 drawing rows
identical. Recomputation: 2 checked, 0 mismatch, 0 null, 1 working copy, 1 historical. Reads as the trial's
practitioner account (admin and `sheet_editor`, its own `aal2` session, read-only transaction rolled back): the
admin list 2 rows, each with `last_modified_at`; one sheet's overview; each version with its document and
drawings. The app restarted, its pages and the auth health check answering 200 through its proxy. NOT checked: a
browser sign-in with TOTP and the admin and editor screens in a browser (the owner's accounts, the owner's
trial); the restore of the backup was not exercised (destructive).
## 7. Known limits of the date (F7)
`last_modified_at` moves, or fails to move, in these cases the checkpoint did not list. Only (iii) is reachable from
the application today.
| # | Case | Effect |
|---|---|---|
| i | `delete_sheet_version` removes a draft row (`20261028110000_sheet_review_workflow.sql:1304-1332`) | the date can go back to an older one. No screen calls it today; fixed in that write the day a « supprimer le brouillon » screen exists |
| ii | deleting an account that created a draft sets the version's `created_by` to null (`20261008110000_anatomical_sheets.sql:111`) | that update stamps the version: the sheet reads as modified at the account's deletion |
| iii | review rounds and audit rows | never move the date, by design (section 2) |
| iv | a future data migration that rewrites drafts | re-dates every such sheet to the deploy time |
| v | the autumn clock change in Paris | two saves an hour apart can read the same « 02:30 » and still sort in their true order, which looks inconsistent |