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

+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 |