docs(docs): V1-1.2 clients as built, budget windows and lock order

Contract §8.2 (as built, divergent replay, fold, measured search, residual hint), §9 helpers and lock order, §9.4 request_conflict, §10 UTC budget windows. SUPABASE.md §3.4 and the DEV procedure for M1 and M2 pending together (rehearsed). TEST_STRATEGY counts.
This commit is contained in:
bchanot committed 2026-10-25 21:11:53 +01:00
1 parent 4adbfcb608
commit f8bd1b6861
3 files changed
+102 -27

No files matched your search

+32 -10
View File
@@ -19,7 +19,8 @@ supabase/
│ ├─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks
│ ├─ 20261011100000_profiles_professional.sql practice_name, professional_title, siret
│ ├─ 20261013100000_files_foundation.sql assets table, seven private buckets, avatar policies through assets, purge queue, browser + worker RPCs (STORAGE.md)
│ └─ 20261025100000_workspaces.sql V1-1.1 (M1): workspaces, workspace_members, personal workspace per account, access helpers, audit correlation cap (§3.3)
│ ├─ 20261025100000_workspaces.sql V1-1.1 (M1): workspaces, workspace_members, personal workspace per account, access helpers, audit correlation cap (§3.3)
│ └─ 20261025110000_clients.sql V1-1.2 (M2): clients, unaccent, client RPCs and search, write budget per workspace, N9 audit filter (§3.4)
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine`
│ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input)
@@ -210,10 +211,14 @@ pnpm supabase status # API on the DEV origin, DB on por
test ! -f supabase/.temp/project-ref && echo "no linked project" # nothing remote is linked
docker ps --filter name=supabase_db_faunosteo --format '{{.Names}} {{.Status}}'
# 1. History: M1 must be the only pending migration.
pnpm supabase migration list --local # every row has local = remote, except 20261025100000 (remote empty)
pnpm db:types:check # the diff must be exactly the M1 objects (workspaces, workspace_members,
# workspace_kind, workspace_member_role): anything else = drift, STOP
# 1. History: only the V1-1 migrations may be pending.
pnpm supabase migration list --local # every row has local = remote, except the V1-1 ones (remote empty):
# 20261025100000 (M1) on a checkout of 6bf6978-08abe42,
# 20261025100000 and 20261025110000 (M1, M2) from 4adbfcb on
pnpm db:types:check # the diff must be exactly the objects of those migrations (M1: workspaces,
# workspace_members, workspace_kind, workspace_member_role; M2: clients,
# client_kind, create_client, update_client, set_client_archived,
# search_clients): anything else = drift, STOP
# 2. Existing accounts (the backfill creates one workspace per profile).
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A \
@@ -227,14 +232,15 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump
docker exec -i supabase_db_faunosteo pg_restore --list < ~/faunosteo-backups/dev-before-m1.dump \
| grep -E "TABLE DATA (auth users|public profiles|supabase_migrations schema_migrations)" # three lines expected
# 4. Apply M1 without reset (its backfill runs inside the migration).
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql"
# 4. Apply without reset (M1's backfill runs inside the migration). `migration up` applies every
# pending migration of the checkout, in order: to apply M1 alone, run it from a checkout of 08abe42.
pnpm supabase migration up --local # "Applying migration 20261025100000_workspaces.sql" (then ..._clients.sql)
```
After applying:
```bash
pnpm supabase migration list --local # 20261025100000 now has its remote column
pnpm supabase migration list --local # each applied migration now has its remote column
docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h 127.0.0.1 -U postgres -d postgres -t -A -c "
select (select count(*) from public.profiles) || '"'"' profiles, '"'"'
|| (select count(*) from public.workspaces) || '"'"' workspaces, '"'"'
@@ -242,7 +248,7 @@ docker exec supabase_db_faunosteo sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" psql -h
|| (select count(*) from public.profiles p where (select count(*) from public.workspaces w
where w.personal_user_id = p.id) <> 1) || '"'"' profiles without exactly one workspace'"'"'"'
# expected: N profiles, N workspaces, N members, 0 profiles without exactly one workspace
pnpm db:test # pgTAP 001-012 (grants, policies, reads); every file runs in
pnpm db:test # pgTAP 001-013 (grants, policies, reads); every file runs in
# begin ... rollback: rows unchanged (checked on the sandbox)
pnpm db:types:check # no diff
pnpm e2e:avatar # avatar flow and worker on the DEV stack (fictitious seed accounts)
@@ -251,13 +257,29 @@ pnpm e2e:avatar # avatar flow and worker on the DE
Stop and report instead of continuing when: `migration list` shows another
pending migration or a remote-only one; `db:types:check` before step 4 shows
anything beyond the M1 objects; the dump check misses a line; `migration up`
applies anything else than `20261025100000`; any count after it differs from
applies anything else than the expected V1-1 migrations; any count after it differs from
the expectation. The backup restores into a scratch database (rehearsed:
every row back; `pg_restore --no-owner` prints privilege errors on
Supabase-managed objects, which do not affect the data). Storage file bytes
(avatars) live in the storage container's volume, not in the dump; M1 does not
touch them.
### 3.4 Clients (V1-1.2, migration M2)
Contract: `V1-1_OWNERS_ANIMALS.md` §5.1, §8.2, §9, §10. `public.clients`
holds the clients of a workspace; the browser reads them through RLS (members
of the workspace, active profile, confirmed email) and writes them only
through `create_client`, `update_client` and `set_client_archived` (security
definer); `search_clients` (invoker, POST) searches one workspace. Refusals
are closed codes: 42501 `not_found` (also for a foreign id), P0001
`invalid_input`, `archived`, `conflict`, `request_conflict`, `limit_reached`,
`rate_limited`. Writes are counted per workspace in
`private.workspace_write_budgets` (UTC hour and day). M2 creates the
extension `unaccent` in `extensions` (available on the CLI image and in
PGlite 0.3.16, loaded by the harness). An account whose workspace holds a
client can no longer be deleted (D9a); in DEV, delete its clients first from
a privileged SQL session, or reset.
## 4. Writing a migration
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`.