Files
faunosteo/docs/development/V1-2-6_R3_SQL_CHECKPOINT.md
T
bchanot bcdacbbb9a docs(app): R3 gate results, fix wave run, deploy order, trial steps
- CHANGELOG: the six shell failures split into the four Target crashed
  of BLK-015 and the two A0 lookup timeouts (counted as BLK-015, not A/B
  proven); pgTAP 014 / 021 not proven by a run without M9; the intro
  names the R3 entry's branch
- owner trial 4.15: steps strictly in order (step 5 shows what two
  sheets prove, the move back to the top is step 9's last action), how
  to open the working copy, the trimmed text, no Claude sentence, the
  re-save sentence removed
- deploy order (database first, then the application) and its
  fail-closed consequence in the SQL checkpoint and SUPABASE.md
- design review, code review and security gate results, the fix wave
  run, the owner decisions left open; verifier, check:all and the owner
  trial still pending
- TODO: fix wave line, three follow-ups
2026-11-16 18:11:12 +01:00

12 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

8. Deploy order and its consequence

Database first (M9), then the application. The typed client requires last_modified_at in the admin sheet summary and in the admin sheet read built on it (packages/supabase/src/sheets.ts). An application at this head against a database without M9 therefore answers « indisponible » on the admin sheet screens (the Administration card, the list, a sheet's page, the draft editor) and on the editor's admin reads around a save: it fails closed, by the client's check, and shows no wrong date. An older application against a migrated database is unaffected: its schema does not know the key and drops it. The order D3 already ran: sandbox, trial stack, then the application.