docs(docs): V1-1.4 animals and relations as built, DEV procedure to M3

Contract §8.3 (differences, relation states, caps, lock order across M2 and
M3, concurrency results, migration states, mutations, residuals), helpers
and derived values; SUPABASE.md §3.3 procedure from DEV's current state to
M3 (not run) and §3.5; TEST_STRATEGY, plan note, backend table, CLAUDE.md.
This commit is contained in:
bchanot committed 2026-10-26 01:06:24 +01:00
1 parent d7845b7339
commit bc6a7ddb6f
6 files changed
+183 -46

No files matched your search

+107 -15
View File
@@ -8,10 +8,12 @@ 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. 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.
authorised V1-1.2. V1-1.2 and V1-1.3 were validated on 2026-10-25 and
2026-10-26 (BDR-076; brief « Validation V1-1.3 et autorisation V1-1.4
Animaux et relations », BDR-077), which authorised V1-1.4. Migrations M1
(§8.1), M2 (§8.2) and M3 (§8.3) are written and tested on the isolated stack
(`pnpm db:sandbox`, SUPABASE.md §5.1); none is applied to Supabase DEV (owner
procedure: SUPABASE.md §3.3). Nothing of V1-1.5 and 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
@@ -519,7 +521,7 @@ term travels in a POST body), audit rows, application logs or error messages
---
## 8. SQL schema (M1 written, M2 and M3 proposed)
## 8. SQL schema (M1, M2 and M3 written)
Three forward-only migrations, one per data step, each with its pgTAP files,
the regenerated `database.types.ts` and the census updates in the same branch
@@ -530,7 +532,7 @@ differences from the sketch below: §8.1.
|---|---|---|
| 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 `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 |
| M3 `20261026100000_animals_relations.sql` (written, V1-1.4) | 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
header verbatim today (foundation migration), the app never sends it, and
@@ -789,6 +791,93 @@ 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).
### 8.3 M3 as built (V1-1.4, 2026-10-26)
`supabase/migrations/20261026100000_animals_relations.sql`, tested by
`supabase/tests/014_animals_relations.sql` (258 checks), the census of
`001_schema.sql` and `013_clients.sql`, the parity test (animal text fields,
year and date floors) and the sandbox suite
`packages/supabase/tests/sandbox/animals.sandbox.ts` (18 tests). Differences
from the sketch and from §9:
| Point | Sketch or contract | As built | Why |
|---|---|---|---|
| Replay with other content | clients only (§8.2) | `create_request_digest` on animals and relations too, never granted to an API role; a divergent replay is `request_conflict` | the same rule for every create |
| Initial relation of `create_animal` | "in the same transaction" | the relation reuses the animal's `create_request_id` (unique per table), so a replay answers the same `relation_id`; it counts as two audited writes in the budget (two audit rows) | idempotence of the two-row create; the budget counts audited writes (§10) |
| Species filter of `search_animals` | parameter `species_id` | `species_filter` | PostgreSQL refuses a parameter named like the `species_id` output column |
| Cursor of `list_client_animals` | `after_sort` | each row returns `sort_key`: `0` (current) or `1` (former) followed by the animal's `name_key`; keyset on `(sort_key, relation_id)` | one text cursor covers both groups |
| Output of `list_client_animals` | "relation and animal columns" | `relation_id`, `relation_role`, `started_on`, `ended_on`, `is_current`, `relation_revision`, `animal_id`, `animal_name`, `species_id`, `species_detail`, `sex`, `breed`, `birth_year`, `animal_archived_at`, `sort_key` | what the client page needs to show and to end or void a relation |
| `client_archive_preview` | `{count, animals}` | `{count, animals: [{id, name}]}`, the first 10 in name order | |
| Replay of a relation create | archived, then revision, then rules | the replay is answered right after the locks, before `archived`: a retry of a committed create returns it even if the animal or the client was archived since | idempotence |
| Dates and years | parsed in each body | `private.parse_record_date`, `private.parse_birth_year`, and the bound `private.utc_tomorrow(timestamptz)`, pure, so pgTAP pins « 1 January accepted on 31 December UTC » without the clock | one rule, testable |
| Opening of the relation writes | per RPC | `private.lock_relation_for_write`: authorise, lock the animal then the relation, refuse `archived`, `conflict`, then a voided row (`invalid_input`) | the same order in the three RPCs |
| `search_clients` | "recreated with the column" | dropped and created again with the same parameters, rules and privileges, plus `current_animal_count` | a return type change needs a drop |
| Access layer `animals.ts`, `relations.ts` | V1-1.4 (TODO) | moved to the UI steps | first consumer, as `clients.ts` at V1-1.2 |
Relation states. `ended_at` tells an ended relation from a current one, so a
relation whose end is recorded without a known date is unambiguous; the
contract needed no change (owner brief §7).
| State | `ended_at` | `ended_on` | `voided_at` | Shown | Current index, cap of 20 | Totals of 200 and 100 000 |
|---|---|---|---|---|---|---|
| current | null | null | null | current | yes | yes |
| ended, date known | set | the date | null | former, with its date | no | yes |
| ended, date unknown | set | null | null | former, no end date | no | yes |
| voided (entered by mistake, current or ended) | as entered | as entered | set | nowhere | no | yes |
Caps: a current relation (`ended_at` and `voided_at` null) counts against
20 per animal; every row, ended and voided included, counts against 200 per
animal and 100 000 per workspace, so a create-and-void loop is bounded. The
200 and 20 are counted under the animal row lock, the 100 000 and the 20 000
animals under the workspace row lock.
Lock order as built, M2 included. Every write RPC takes the budget row last
and the others in the order workspace, animal, relation, client; none takes
two of them the other way round, so no wait cycle can form:
| RPC | Locks, in order |
|---|---|
| `create_client` | workspace (no key update), budget |
| `update_client`, `set_client_archived` | client (update), budget |
| `create_animal` | workspace (no key update), client (share, with a relation), budget (once, twice with a relation) |
| `update_animal`, `set_animal_archived` | animal (update), budget |
| `create_animal_client_relation` | workspace (no key update), animal (update), client (share), budget |
| `end_`, `update_`, `void_animal_client_relation` | animal (update), relation (update), budget |
The relation RPCs first read the animal's (or the relation's) workspace among
the caller's writable ones without a lock, so a caller outside the workspace
takes none: with A's client, animal and relation rows held for 2 s, B's four
refusals answered in 15 ms.
Results on the isolated stack: 8 identical `create_animal` calls with a
relation gave one animal, one relation and two counted writes; 10 identical
relations, one row and nine `duplicate_relation`; end and void racing on one
revision (6 rounds of 3 calls), exactly one applied each time; 6 links at 18
current relations, 2 passed; a relation create racing the archive of its
client or of its animal (10 rounds each), created before or refused
`archived`; at 990 writes, 30 mixed client, animal and relation writes, exactly
10 passed; 5 `create_animal` at 19 998 animals and 5 links at 99 998
relations, 2 each (49 ms for the five links); 96 mixed M2 and M3 writes in one
workspace, no deadlock (109 ms). Reads over 20 000 animals, 20 000 relations
and 1 000 clients (24 POST calls): median 7.9 ms, p95 11.8 ms.
Migration states, each from an empty sandbox: from zero; a pre-M1 base
(seeds, GoTrue accounts) then M1 to M3; the same base, M1 (backfill of five
workspaces), then M2 and M3 (`pnpm db:sandbox up upgrade 20261025100000
20261025110000`); an M1 and M2 base then M3. In each: the 14 pgTAP files
green (919 checks), the generated types identical to the committed file, the
sandbox suites 46/46. Fourteen deliberate faults of M3 were each caught; two
only after the tests were strengthened (a client whose only link was voided
while current; B linking its own animal to a client of A, which made B wait
on A's lock).
Not built: reopening an ended relation (§5.3: void it and create it again).
Residual: a privileged SQL writer (the table owner) can still change a
relation's `animal_id`, `client_id` or `relation_role` inside one workspace,
and move an animal without relations to another workspace (the evolution path
of §4); the RPCs never do, and the composite keys refuse any row across
workspaces whatever writes it.
---
## 9. Policies, helpers and RPCs
@@ -806,8 +895,11 @@ The RPC refusals carry no hint (checked on both engines).
| `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 |
| `private.utc_tomorrow(p_now timestamptz)` | `date` | the latest date a record may carry when written at `p_now`: tomorrow's UTC date (M3, §8.3) | none |
| `private.parse_record_date(p_value text)`, `private.parse_birth_year(p_value text)` | `date`, `smallint` | `YYYY-MM-DD` or four digits, not after `utc_tomorrow(now())` (its year), else `invalid_input` without the value; null stays null (M3) | none |
| `private.lock_relation_for_write(p_relation_id uuid, p_expected_revision integer)` | relation row | authorises and locks animal then relation; `not_found`, `archived`, `conflict`, voided `invalid_input` (M3) | none |
All are `security definer` (except `fold_text` and `is_clean_text`, pure SQL functions),
All are `security definer` (except `fold_text`, `is_clean_text`, `utc_tomorrow` and the two parsers, which read no table),
`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
@@ -921,7 +1013,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` 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 |
| `search_animals` | `workspace_id`, `query`, `species_filter` (§8.3), `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 |
@@ -938,8 +1030,8 @@ Derived values:
| Value | Exact rule |
|---|---|
| `current_animal_count` | `count(distinct animal_id)` over the client's relations with `ended_at is null`, any role, animals not archived |
| `current_owners` | the animal's relations with `relation_role = 'owner'` and `ended_at is null`, archived clients included and flagged, ordered by client `name_key` then `id`, first three as `{client_id, display_name, archived}` |
| `current_animal_count` | `count(distinct animal_id)` over the client's relations with `ended_at is null` and `voided_at is null`, any role, animals not archived |
| `current_owners` | the animal's relations with `relation_role = 'owner'`, `ended_at is null` and `voided_at is null`, archived clients included and flagged, ordered by client `name_key` then `id`, first three as `{client_id, display_name, archived}` |
| `current_owner_count` | the count of those relations |
| « only current owner » (archive preview) | the animal is active, this client has a current `owner` relation, and no other client, archived or not, has one |
@@ -1176,7 +1268,7 @@ validated mockups unchanged).
### 12.1 SQL (pgTAP, on PGlite and on the real stack)
Files: `012_workspaces.sql`, `013_clients.sql`,
`014_animals_relations.sql`; updates to `001_schema.sql` (tables, RLS,
`014_animals_relations.sql` (258 checks); updates to `001_schema.sql` (tables, RLS,
privileges, helper census) and to `packages/supabase/tests/db/schema-types.test.ts`;
the PGlite harness loads `unaccent`.
@@ -1351,10 +1443,10 @@ 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, 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). Built (§11.6), awaiting the owner's checkpoint |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof |
| 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), validated 2026-10-25; 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, sandbox suite. Written and tested on the isolated stack (§8.2), validated 2026-10-25; not applied to DEV |
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13). Built (§11.6), validated 2026-10-26 |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof. Written and tested on the isolated stack (§8.3), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry |
| V1-1.6 | Animals and relations UI, navigation (D11), dashboard tiles (D12), documents, Definition of Done |