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`.
+5
View File
@@ -16,6 +16,11 @@ V1-1.1 (2026-10-25): supabase vitest 44 (config test added), 12 pgTAP files
(`012_workspaces.sql`, 85 checks; 531 checks in all), also run on an isolated
real stack because the DEV stack stays untouched until the owner applies M1
(`V1-1_OWNERS_ANIMALS.md` §8.1).
V1-1.2 (2026-10-25): supabase vitest 53 (field-limits parity test added), 13
pgTAP files (`013_clients.sql`, 130 checks; 661 in all); the isolated stack is
a project tool (`pnpm db:sandbox`, SUPABASE.md §5.1) with its own suite under
`packages/supabase/tests/sandbox` (28 real-stack checks: HTTP per role,
concurrency, budget races, 20 000-client search timing).
## 1. Layers
+65 -17
View File
@@ -6,9 +6,12 @@ BDR-073). The architecture of Parts 4 to 9 and the technical choices N1 to N9
were validated by the owner the same day (brief « Validation du contrat V1-1
et autorisation de V1-1.1 Workspaces », BDR-074, §13.2), with the precisions
written into §5.3, §9 and §10. The interface choices of §13.3 stay proposals
until their UI steps. Only step V1-1.1 is authorised: migration M1 is written
and tested on an isolated database (§8.1); it is not applied to Supabase DEV,
and nothing of V1-1.2 to V1-1.6 exists.
until their UI steps. V1-1.1 was validated by the owner on 2026-10-25 (brief
« Validation V1-1.1 et autorisation V1-1.2 Données clients », BDR-075), which
authorised V1-1.2. Migrations M1 (§8.1) and M2 (§8.2) are written and tested
on the isolated stack (`pnpm db:sandbox`, SUPABASE.md §5.1); neither is
applied to Supabase DEV (owner procedure: SUPABASE.md §3.3). Nothing of
V1-1.3 to V1-1.6 exists.
Branch: `feature/v1-1-clients-animals`. Roadmap position:
`IMPLEMENTATION_PLAN.md` §0; this step is a reduced plan Step 12 that also lays
the permission frame of Step 10. The file name keeps "OWNERS" so the documents
@@ -526,7 +529,7 @@ differences from the sketch below: §8.1.
| Migration | Step | Content |
|---|---|---|
| M1 `20261025100000_workspaces.sql` (written, V1-1.1) | V1-1.1 | enums `workspace_kind`, `workspace_member_role`; `workspaces`, `workspace_members`; helpers; trigger; backfill function called once; `private.log_event` redefined (same signature) to keep `x-correlation-id` only when it matches `^[A-Za-z0-9-]{1,64}$`, plus a NOT VALID CHECK on `audit_logs.correlation_id`; grants; RLS |
| M2 `<ts>_clients.sql` | V1-1.2 | extension `unaccent`; `private.fold_text`; enum `client_kind`; `clients`; write budget helper; client RPCs and searches; grants; RLS |
| M2 `20261025110000_clients.sql` (written, V1-1.2) | V1-1.2 | extension `unaccent`; `private.fold_text`; enum `client_kind`; `clients`; write budget helper; client RPCs and searches; grants; RLS |
| M3 `<ts>_animals_relations.sql` | V1-1.4 | species rows; enums `animal_sex`, `animal_relation_role`; `animals`, `animal_client_relations`; animal and relation RPCs; grants; RLS |
Why the correlation header in M1: `private.log_event` copies that request
@@ -755,6 +758,37 @@ workspace along, and the residual admin path of §6.3). The types were
generated from that database: the diff with the committed file is exactly the
M1 additions.
### 8.2 M2 as built (V1-1.2, 2026-10-25)
`supabase/migrations/20261025110000_clients.sql`, tested by
`supabase/tests/013_clients.sql` (130 checks), the census of `001_schema.sql`,
the parity test `packages/supabase/tests/db/field-limits.test.ts` and the
sandbox suite `packages/supabase/tests/sandbox/clients.sandbox.ts`.
Differences from the sketch and the plan:
| Point | Sketch or plan | As built | Why |
|---|---|---|---|
| Replay with other content | not covered | column `create_request_digest` (SHA-256 of the normalised creation content, not granted to any API role); a replay with the same id and another digest is refused `request_conflict` (§9.4), never applied | owner brief §11: a reused request id must not silently accept a divergent operation |
| Text rule in CHECKs | written inline | `private.is_clean_text(value, max)`, immutable, EXECUTE for nobody, used by every text CHECK (M3 reuses it) | one literal for the control ranges |
| Folding | `lower + unaccent` | `lower(unaccent('extensions.unaccent', value) collate "C")`: accents removed, then ASCII lower case only, identical on PGlite and the real image (checked); Cyrillic or Greek capitals keep their case | the database collations differ (C on PGlite, ICU on the image) |
| `search_key` | `concat_ws` | `display_name || ' ' || coalesce(city, '') || ' ' || coalesce(email, '')` | a generated column needs an immutable expression; `concat_ws` is stable |
| Write budget | `require_write_budget(p_actor)`, rolling windows | `private.consume_write_budget(p_workspace_id)` over `private.workspace_write_budgets` (one row per workspace), fixed UTC windows (§10) | owner decision N6 and brief §9: transactional counter per workspace, UTC windows |
| `search_clients` output | with `current_animal_count` | without it | the relations table comes with M3, which recreates the function with the column (return type change) |
| Access layer `clients.ts` | V1-1.2 | moved to V1-1.5, its first consumer, together with the personal workspace read | the brief's V1-1.2 scope lists no access layer; `field-limits.ts` (D-R7) is written now because the parity test needs it |
| Real-stack e2e | `clients-animals.e2e.ts` on the DEV stack | the sandbox suite, on the isolated stack | DEV stays untouched (owner) |
Search measurement (owner requirement, §8): 20 000 clients in one workspace,
21 POST calls through PostgREST mixing name, city, email and phone terms:
median 9.8 ms, p95 21.4 ms, max 21.9 ms (isolated stack, this host). Under
the 100 ms threshold, so no trigram index is added.
Residual disclosure found on the real image: a refused direct table access
(`permission denied for table clients`) carries a hint added by the Supabase
image, « Grant the required privileges to the current role with: GRANT
INSERT ON public.clients TO authenticated; ». It names the table, the role
and the privilege, never a value, and the app never sends such a request.
The RPC refusals carry no hint (checked on both engines).
---
## 9. Policies, helpers and RPCs
@@ -765,14 +799,15 @@ M1 additions.
|---|---|---|---|
| `private.caller_workspace_ids()` | `setof uuid` | the single source of the access rule: workspaces where `auth.uid()` is a member, with an active profile and a confirmed email | `authenticated` (policies evaluate it) |
| `private.writable_workspace_ids()` | `setof uuid` | `caller_workspace_ids()` restricted to a write role (V1-1: `holder`) | none (called inside RPCs) |
| `private.require_write_budget(p_workspace_id uuid)` | `void` | raises P0001 `rate_limited` when the workspace has 1 000 audited writes within the past hour or 5 000 within the past day (N6: per workspace); the count and the write are serialised per workspace, never a bare count followed by an unprotected insert; the counter (rows counted by workspace, or a counter row per workspace and window) and its lock are fixed and documented with M2 | none |
| `private.fold_text(p_value text)` | `text` | lower case without accents (`unaccent` with an explicit dictionary), declared immutable for the generated columns | `authenticated` (the invoker search folds the term) |
| `private.consume_write_budget(p_workspace_id uuid)` | `void` | counts one write of the workspace in its UTC hour and day (upsert of its row in `private.workspace_write_budgets`, row lock), raises P0001 `rate_limited` past 1 000 / 5 000 (§10); called last by every write RPC (M2, §8.2) | none |
| `private.is_clean_text(p_value text, p_max integer)` | `boolean` | the text rule of §5 for CHECK constraints (M2) | none |
| `private.fold_text(p_value text)` | `text` | without accents (`unaccent` with an explicit dictionary), then ASCII lower case (collation "C"), declared immutable for the generated columns (§8.2) | `authenticated` (the invoker search folds the term) |
| `private.ensure_personal_workspace(p_user_id uuid)` | `boolean` | the single write path: workspace and `holder` membership in one statement, `on conflict do nothing` on `personal_user_id`; true when it created (M1, §8.1) | none |
| `private.create_personal_workspace()` | trigger | after insert on `profiles`: calls `ensure_personal_workspace(new.id)` | none |
| `private.backfill_personal_workspaces()` | `integer` | same for every profile without a personal workspace; idempotent | none |
| `private.check_personal_workspace()` | constraint trigger | deferred to commit: a personal workspace has exactly its account as `holder` (M1, §8.1) | none |
All are `security definer` (except `fold_text`, a pure SQL function),
All are `security definer` (except `fold_text` and `is_clean_text`, pure SQL functions),
`set search_path = ''`, `revoke all ... from public, anon, authenticated,
service_role` then the grants of the table, and listed in the census of
`001_schema.sql`. The write RPCs do not call `private.require_actor()`: its
@@ -811,25 +846,37 @@ Write RPCs: `language plpgsql`, `security definer`, volatile,
private.writable_workspace_ids())` with its lock, so a caller outside the
workspace never takes a lock and never waits on one; no row found raises
42501 `not_found`;
2. calls `private.require_write_budget`;
3. checks, in this order, archived (`archived`), then revision (`conflict`),
then the rules of the table below;
2. checks, in this order, archived (`archived`), then revision (`conflict`),
then the rules of the table below; a replayed create or a call that
changes nothing returns here, uncounted;
3. calls `private.consume_write_budget` (as built in M2: last, after the
checks, so its lock is the last one taken);
4. writes, inside a block that turns `check_violation`, `not_null_violation`,
`string_data_right_truncation` and `invalid_text_representation` into
`invalid_input`, `unique_violation` on the current-relation index into
`duplicate_relation` and `foreign_key_violation` into `not_found`;
5. writes one audit row and returns ids and the new revision only.
Locks: create RPCs of clients and animals lock the workspace row (cap and
insert serialised per workspace); every relation RPC locks the animal row
Locks: create RPCs of clients and animals lock the workspace row `for no
key update` (cap, replay check and insert serialised per workspace, foreign
key checks of other writes not blocked); every relation RPC locks the animal row
`for update` then the client row `for share`, in that order; the archive RPCs
lock their row `for update`. So caps, « both active » and « animal active »
cannot be passed by a concurrent call. The write budget and the 100 000
relations per workspace count rows that writes on different animals or
clients can add at the same time: they are counted under a lock that
serialises those writes per workspace (owner, N6: never a bare count followed
by an unprotected insert). M2 fixes that lock and the global lock order
(candidate: workspace row, then animal, then client) and documents it here.
by an unprotected insert). As built in M2: the budget row of the workspace
(`private.workspace_write_budgets`) is locked by the upsert of
`private.consume_write_budget`, which every write RPC calls last, after its
entity locks and checks; no lock is taken after it, so no cycle can form. The
lock order of every write RPC is therefore: workspace row (creates), animal
row, client row, budget row. M3 keeps it: a relation create locks the
workspace row first (its 100 000 cap), then the animal, then the client, then
the budget. The budget lock is per workspace: measured on the isolated stack,
a budget row held for 2 s delayed the create of its workspace by 1.75 s while
nine creates in nine other workspaces finished in 8 ms; 60 mixed writes in one
workspace raised no deadlock.
Parameters: dates, years and enum values arrive as `text` and are parsed inside
the body, so a malformed value (« 2015-02-30 ») is answered `invalid_input`
@@ -873,7 +920,7 @@ with POST, so terms and cursors stay out of URLs and access logs.
| RPC | Parameters | Returns (one row per record) | Rules |
|---|---|---|---|
| `search_clients` | `workspace_id`, `query`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `kind`, `display_name`, `city`, `phone`, `email`, `archived_at`, `name_key`, `current_animal_count` | see below; also serves the client picker of the relation forms |
| `search_clients` | `workspace_id`, `query`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `kind`, `display_name`, `city`, `phone`, `email`, `archived_at`, `name_key`; `current_animal_count` added by M3 (§8.2) | see below; also serves the client picker of the relation forms |
| `search_animals` | `workspace_id`, `query`, `species_id`, `archived`, `page_size`, `after_name_key`, `after_id` | `id`, `name`, `species_id`, `species_detail`, `sex`, `breed`, `birth_year`, `archived_at`, `name_key`, `current_owners`, `current_owner_count` | see below; optional species filter |
| `list_client_animals` | `client_id`, `page_size`, `after_sort`, `after_id` | relation and animal columns | a client's relations with their animals, current first then former, each group by animal `name_key`, then `id`; keyset on that order; 50 by default, 100 at most |
| `client_archive_preview` | `client_id` | `{count, animals}` | active animals for which this client holds the only current `owner` relation: their count and the first 10 by name |
@@ -918,6 +965,7 @@ in FR and EN, like the auth and asset failures:
| P0001 `duplicate_relation` | `duplicate_relation` | same current (animal, client, role), including the loser of a race |
| P0001 `already_ended` | `already_ended` | ending an ended relation |
| P0001 `invalid_input` | `invalid_input` | an RPC rule or a constraint or parse error caught inside the RPC |
| P0001 `request_conflict` | `request_conflict` | a create replayed with a known `create_request_id` but other content (§8.2); the first record is kept unchanged |
| anything else | `unavailable` | network, server |
pgTAP compares the whole error (SQLSTATE, message, detail, hint) of a foreign id
@@ -961,7 +1009,7 @@ migration.
| Search term | 0 to 100 characters after trimming | a name or a phone fits; longer is noise | RPC |
| Records per workspace | 20 000 clients, 20 000 animals, 100 000 relations | a full-time practitioner sees roughly 1 000 to 2 000 visits a year, so 20 000 animals is more than a decade of distinct animals for one person | RPC, under the workspace or animal row lock |
| Relations per animal | 20 current, 200 in total | co-owners, keeper and contacts fit in 20; 200 covers decades of sales; the animal page reads them in one select | RPC |
| Write rate | 1 000 audited writes per workspace per rolling hour and 5 000 per rolling day (owner, N6), counted under a per-workspace lock (§9.3); the counter is fixed with M2 | typing a whole client base by hand stays under 200 an hour; bounds the growth of the append-only audit log and the damage of a stolen session | RPC (`private.require_write_budget`) |
| Write rate | 1 000 audited writes per workspace per UTC hour and 5 000 per UTC day (owner, N6), fixed windows: the hour from hh:00:00 to hh:59:59.999 UTC, the day from 00:00:00 UTC; the first write of a new window restarts its count at 1; the 1 000th write of the hour passes, the 1 001st is refused `rate_limited`. Across an hour boundary up to 2 000 writes can land in 2 minutes; the daily 5 000 still holds. Counted per workspace under the budget row lock (§9.3); a refused write, a replayed create and a call that changes nothing are not counted (the count is rolled back with the refusal) | typing a whole client base by hand stays under 200 an hour; bounds the growth of the append-only audit log and the damage of a stolen session | RPC (`private.consume_write_budget`) |
| Audit row size | `correlation_id` kept only when it matches `^[A-Za-z0-9-]{1,64}$`; metadata limited to the workspace id (N9) | the caller no longer chooses the size of an append-only row | M1 (`private.log_event`, CHECK) |
| Concurrent writes | optimistic `revision` on every update; locks of §9.3 (workspace row for creates, animal then client row for relations, the row itself for archive); idempotent creates through `create_request_id` | no silent overwrite between two tabs or devices, no cap overshoot, no duplicate on retry | SQL and RPC |
| Enumeration | random uuid ids; one 42501 `not_found` for an unknown and a forbidden id in every RPC, with no lock taken outside the caller's workspaces; reads filtered by RLS return empty, never an error that says "exists"; searches limited to one workspace of the caller; closed codes, never values, in errors | | RLS, RPC |
@@ -1257,7 +1305,7 @@ validates after V1-1.1 and after the first UI step; nothing merges into
| Step | Content |
|---|---|
| V1-1.1 | Workspaces: M1 (with the correlation header cap), helpers, trigger, backfill, RLS, pgTAP `012`. Written and tested on an isolated stack (§8.1), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, access layer (with the personal workspace read deferred from V1-1.1), real-stack e2e |
| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, sandbox suite. Written and tested on the isolated stack (§8.2), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13) |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof |
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry |