Files
faunosteo/docs/development/V1-2-6_R3_SQL_CHECKPOINT.md
T
bchanot a86020d6e3 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.
2026-11-16 17:47:49 +01:00

11 KiB

R3 SQL checkpoint: a true last-modification date for the sheet list

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

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:

'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. 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.

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.

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