From 0f8c9833cc27449831936e42585114387263e738 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 25 Oct 2026 20:00:06 +0100 Subject: [PATCH] docs(docs): V1-1 owner decisions N1-N9 and M1 as built MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contract: N4 voiding instead of deletion, N5 date constraints, N6 write budget per workspace under a lock, N7 effective-privilege wording and residual admin paths, N9 audit metadata limited to ids; M1 as-built notes and isolated-stack results (§8.1). SUPABASE.md §3.3 with the owner procedure to apply M1 on DEV without reset; backend architecture, test strategy, plan and CLAUDE.md lines. --- CLAUDE.md | 7 +- docs/development/BACKEND_ARCHITECTURE.md | 15 +- docs/development/IMPLEMENTATION_PLAN.md | 5 +- docs/development/SUPABASE.md | 38 +++- docs/development/TEST_STRATEGY.md | 4 + docs/development/V1-1_OWNERS_ANIMALS.md | 227 ++++++++++++++++++----- 6 files changed, 237 insertions(+), 59 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d737e62b..5753ea05 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,8 +49,9 @@ MVP species: equine only. Open-source MIT. Product roadmap (owner, 2026-10-25): P0 docs, then V1-1 clients and animals, V1-2 sheets from Supabase, V1-3 cloud bilans, V1-4 stored PDF and sharing, V1-5 mobile and accessibility pass (`docs/development/IMPLEMENTATION_PLAN.md` §0; V1-1 contract `docs/development/V1-1_OWNERS_ANIMALS.md`: -business decisions ratified 2026-10-25, BDR-073; SQL/RLS/RPC design awaiting owner validation on -`feature/v1-1-clients-animals`; nothing built). +business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validated, BDR-074; on +`feature/v1-1-clients-animals` only V1-1.1 is built: migration `20261025100000_workspaces.sql`, tested on PGlite and an +isolated stack, not applied to Supabase DEV). --- @@ -274,7 +275,7 @@ faunosteo/ │ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test ├─ supabase/ │ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts -│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2, profiles_professional, files_foundation (assets, buckets, avatar policies, purge queue, RPCs) +│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2, profiles_professional, files_foundation (assets, buckets, avatar policies, purge queue, RPCs), workspaces (V1-1.1: personal workspace per account, access helpers) │ ├─ seed/anatomical-sheets/equine/ │ │ ├─ legacy-sources/ ← the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input, never edited) │ │ ├─ legacy-import/ ← GENERATED baseline: document, id map, IMPORT-REPORT, SVG copies (no SQL) diff --git a/docs/development/BACKEND_ARCHITECTURE.md b/docs/development/BACKEND_ARCHITECTURE.md index 8f581756..c9ae2ad9 100644 --- a/docs/development/BACKEND_ARCHITECTURE.md +++ b/docs/development/BACKEND_ARCHITECTURE.md @@ -83,12 +83,25 @@ private.has_active_entitlement(uid, capability text) Each helper ships with pgTAP tests in the same migration step: positive case, negative case, expired grant, revoked grant, wrong organization. +As built from V1-1 (contract `V1-1_OWNERS_ANIMALS.md` §9, BDR-073/074): the +perimeter is a workspace, not an organization. `private.caller_workspace_ids()` +(member, active profile, confirmed email; no parameter, `auth.uid()` only; +EXECUTE for `authenticated`) and `private.writable_workspace_ids()` (the same, +restricted to a write role; EXECUTE for nobody, called inside definer RPCs) +replace `is_org_*` and `can_view_client/animal` for V1-1 records. They avoid +RLS recursion by running as the table owner (`security definer`, owner +`postgres`, `search_path = ''`) rather than with `row_security = off`. No +helper or policy has a platform-role branch (D16). Every V1-1 table revokes +all privileges from `anon` and `service_role` (N7); `postgres` keeps +`BYPASSRLS` on the Supabase image and the service key stays a GoTrue admin +credential, residual paths named in the contract §6.3. + ### 4.2 Policy rules per domain (summary of §17.3) | Table family | SELECT | INSERT/UPDATE/DELETE | |---|---|---| | `profiles` | own row; admins via view | own row; roles only through RPC | -| `organizations`, `organization_members` | members | managers/owners through RPC (`add_member`, `remove_member`, `set_role`) so that "secretary cannot self-grant practitioner" is one place | +| `workspaces`, `workspace_members` (V1-1; cabinets extend them instead of `organizations`) | members, through `caller_workspace_ids()` | none through the API: personal workspace created by trigger; cabinet membership RPCs come with Step 10 | | `clients`, `client_contacts`, `client_consents` | `can_view_client` | create by the practitioner who starts the relationship; core identity edits restricted (open question Q6) | | `animals` | `can_view_animal` | practitioner with an active relationship or grant | | `reports` | `can_view_report` | `can_edit_report` for drafts; completion and numbering only via RPC | diff --git a/docs/development/IMPLEMENTATION_PLAN.md b/docs/development/IMPLEMENTATION_PLAN.md index 32c24c64..ab07364b 100644 --- a/docs/development/IMPLEMENTATION_PLAN.md +++ b/docs/development/IMPLEMENTATION_PLAN.md @@ -354,8 +354,9 @@ ratified by the owner on 2026-10-25 (BDR-073): records attached to a workspace, one personal workspace per practitioner, cabinets later, no global client record shared between practitioners, no consents, grants, sharing, files or candidate matching. Contract and technical design: -`V1-1_OWNERS_ANIMALS.md` (business decisions approved; the SQL, RLS and RPC -design awaits the owner's validation before the first migration). Where the +`V1-1_OWNERS_ANIMALS.md` (business decisions approved; architecture and N1-N9 +validated 2026-10-25, BDR-074; V1-1.1 workspaces migration written and tested +in isolation, not applied to DEV). Where the text above differs (global clients, consents, grants, photo, files, deceased flow), the contract governs V1-1. diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 1d9bb47e..d14fa979 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -18,7 +18,8 @@ supabase/ │ ├─ 20261009100000_sheet_asset_storage.sql bucket anatomical-sheet-assets + read policy through the sheet │ ├─ 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) +│ ├─ 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) ├─ 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) @@ -181,11 +182,44 @@ Seed accounts (local only, password `LocalDev-only-password-1`): | `alice@faunosteo.local` | plain user | | `bob@faunosteo.local` | plain user | +### 3.3 Workspaces (V1-1.1, migration M1) + +Contract: `docs/development/V1-1_OWNERS_ANIMALS.md` §4, §8.1, §9. Every +account has exactly one personal workspace, created by the trigger +`profiles_create_personal_workspace` in the sign-up transaction (GoTrue → +`handle_new_auth_user` → profile → workspace + `holder` membership), through +the single write path `private.ensure_personal_workspace(uuid)` (one +statement, idempotent, race-safe). A deferred constraint trigger refuses at +commit a personal workspace without its holder or with any other member. +Reads: RLS through `private.caller_workspace_ids()` (member, active profile, +confirmed email, `auth.uid()` only). No API role writes either table; `anon` +and `service_role` hold no privilege on them. From M2 on, record tables use +the same helpers; the app passes its workspace id explicitly. + +M1 is written and tested on PGlite and on an isolated stack, not applied to +the DEV stack. Applying it there is an owner action, without a reset: + +```bash +pnpm supabase db dump --local -f ~/faunosteo-dev-schema-before-m1.sql # optional safety copy: schema +pnpm supabase db dump --local --data-only -f ~/faunosteo-dev-data-before-m1.sql # and data (DEV accounts are fictitious) +pnpm supabase migration list --local # 20261025100000 listed as local only +pnpm supabase migration up --local # applies the pending migration; its backfill creates the missing workspaces +pnpm db:test # the 12 pgTAP files on the DEV database (each rolled back) +pnpm db:types:check # no diff with the committed types +``` + +Afterwards every existing account has its workspace: in Studio's SQL editor, +`select count(*) from public.profiles p where not exists (select 1 from +public.workspaces w where w.personal_user_id = p.id)` returns 0. The migration is forward-only: undoing it means restoring +the dumps or writing a new migration. `pnpm db:reset` also applies it, but +replays the whole database from zero and loses the DEV accounts and data. + ## 4. Writing a migration 1. `pnpm supabase migration new ` creates `supabase/migrations/_.sql`. 2. A migration that adds a table adds, in the same file: RLS enable, explicit - `revoke all ... from public, anon, authenticated` then the exact grants, + `revoke all ... from public, anon, authenticated` (and `service_role` for + V1-1 record tables, contract N7) then the exact grants, separate SELECT / INSERT / UPDATE / DELETE policies, indexes, comments. 3. Add or extend a pgTAP file under `supabase/tests/`: the allowed path and every denied path (other user, anon, direct write bypassing an RPC). Scope diff --git a/docs/development/TEST_STRATEGY.md b/docs/development/TEST_STRATEGY.md index 2097c86e..7bf1897f 100644 --- a/docs/development/TEST_STRATEGY.md +++ b/docs/development/TEST_STRATEGY.md @@ -12,6 +12,10 @@ not created; the real-stack e2e lives in `packages/supabase/tests/e2e`. No real-browser suite exists yet (TODO RR-8; V1-1 contract §12.5 proposes the first one, decision D14). No CI has ever run (BDR-047): "CI" in the tables means the prepared workflow. +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). ## 1. Layers diff --git a/docs/development/V1-1_OWNERS_ANIMALS.md b/docs/development/V1-1_OWNERS_ANIMALS.md index c5a9db44..60fcc75f 100644 --- a/docs/development/V1-1_OWNERS_ANIMALS.md +++ b/docs/development/V1-1_OWNERS_ANIMALS.md @@ -2,10 +2,13 @@ Status: business decisions approved by the owner on 2026-10-25 (brief « V1-1 : ratification des décisions métier et préparation de l'implémentation », -BDR-073). The technical design of Parts 8 to 10 and the choices of §13.2 and -§13.3 are proposals awaiting the owner's validation at the V1-1 preparation -checkpoint. Until that validation nothing is implemented: no migration, table, -RPC, policy, component, route or dependency, and Supabase DEV is untouched. +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. 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 @@ -106,10 +109,25 @@ clients shared between practitioners, no data visible from one practitioner to another, and no sharing between practitioners of a cabinet. Invitations and cabinet permissions are not built. -- Creation: a trigger after insert on `profiles` creates the personal workspace - and its `holder` membership; the migration backfills existing profiles. +- Creation: a controlled server initialisation, never a client call. A + trigger after insert on `profiles` creates the personal workspace and its + `holder` membership in the transaction that creates the account (GoTrue + inserts `auth.users`, `private.handle_new_auth_user` inserts the profile, + the trigger creates the workspace): a failure anywhere rolls back the whole + sign-up, so no account exists without its workspace and no workspace + without its account. The workspace exists before the email is confirmed and + stays unreadable until then (§9.1). The migration backfills existing + profiles through the same write path. - Uniqueness: `personal_user_id` is unique, so an account never has two - personal workspaces. + personal workspaces. The single write path inserts with `on conflict do + nothing` on that key: a retry, a replay or two concurrent calls create one + workspace and one membership, never two (§8.1). +- Consistency: a personal workspace has exactly one member, its account, as + `holder`. A deferred constraint trigger checks it at commit, whatever role + writes, so neither row survives alone and no other account can be added. +- Deletion: no archive state for a workspace. A personal workspace follows its + account: deleting an empty account deletes it; from M2 on, records refuse + the deletion (D9a, §7.2). - Context: every read and write names its workspace (RPC parameter or filter). The app reads its personal workspace once after sign-in and passes its id explicitly to the access layer; nothing reads a global "current workspace" @@ -222,9 +240,10 @@ Table `animal_client_relations`: |---|---| | `animal_id`, `client_id` | same workspace, enforced by composite foreign keys | | `relation_role` | `owner`, `keeper` or `contact` | -| `started_on` | date the relation began, when known; null when unknown | -| `ended_at` | null while the relation is current; set when the end is recorded (§13.2 N5) | +| `started_on` | date the relation began, when known; null when unknown; never filled by default | +| `ended_at` | null while the relation is current; set to the recording time when the end is recorded (§13.2 N5); a technical time, never shown as the end date | | `ended_on` | date the relation ended, when known; only on an ended relation; not before `started_on` | +| `voided_at` | null for a relation that existed; set when a relation entered by mistake is voided (§13.2 N4) | | `revision`, `created_at`, `updated_at` | server-maintained | Rules: @@ -252,15 +271,48 @@ Rules: keeps their other animals and appears as « ancien propriétaire » on the animal's page. Between the two actions the animal has two current owners or none, two valid states, so no atomic transfer operation is needed; -- ending is not deleting: an ended relation stays readable. Removing a - relation entered by mistake is §13.2 N4; a relation ended by mistake is - corrected the same way: removed, then created again as current. +- ending is not deleting: an ended relation stays readable as a former + relation, with its dates; +- voiding is not ending (N4): a relation that never existed (wrong client, + wrong animal, wrong role) is voided, never ended, so it never appears as a + former owner or keeper and no end date is invented for a period that never + was. The row keeps every value as entered, gains `voided_at`, and becomes + frozen (no end, no date change, no un-voiding); the audit log records who + voided it and when (§9.3). Voided relations are left out of every list, of + the current-relation index, of the derived values (§9.3) and of the current + cap; they count in the 200 total per animal, so a create-and-void loop + cannot grow a table without bound. No V1-1 screen shows them; the row stays + for the lifecycle contract (export, erasure) and incident work; +- an end recorded on the wrong relation is voided like any wrong relation, + then the right one is created. An end recorded with a wrong date is + corrected by `update_animal_client_relation`. Re-opening a relation whose + end never happened (clearing `ended_at`) is not offered in V1-1: the + relation is voided and created again as current, with the same start date; + the owner may ask for an explicit reopening at V1-1.4. + +Date rules (N5), all enforced by SQL CHECK except « not in the future », +which needs the clock and is checked by the RPCs (tomorrow's UTC date, §9.3): + +| Constraint | SQL | +|---|---| +| dates optional, no default | `started_on date`, `ended_on date`, both nullable, no `default` | +| plausible lower bound | `started_on >= '1900-01-01'`, `ended_on >= '1900-01-01'` | +| an end date only on an ended relation | `ended_on is null or ended_at is not null` | +| order when both are known | `started_on is null or ended_on is null or started_on <= ended_on` | +| a voided relation keeps its state | `voided_at` set only by the void RPC; every other write RPC refuses a voided row (`invalid_input`) | +| one current relation per triple | unique index on `(animal_id, client_id, relation_role) where ended_at is null and voided_at is null` | ### 5.4 Species (D5, approved) Reference data written by migration: the nine species of the contract (the existing `equine` row plus eight) and « Autre ». No other species is added. -Slugs, names and order are proposal §13.2 N1: +Slugs, names and order approved by the owner (§13.2 N1). Compatibility, +checked on 2026-10-25: species are rows of `public.species` (text `id`, +CHECK `^[a-z0-9][a-z0-9_-]{0,63}$`, which every slug below satisfies), never a +SQL enum, so M3 adds rows and freezes no new enumeration; the Rust core +carries `species_id` / `speciesId` as a free string (report identity, sheet +document, snapshot, sheet index) with no species list, and the only existing +id, `equine`, is kept unchanged: | `id` | `name_fr` | `name_en` | `sort_order` | |---|---|---|---| @@ -291,7 +343,7 @@ adds the refusal if it opens sheet creation. | Actor | Read | Create | Edit | Archive / restore | Delete | |---|---|---|---|---|---| -| Member with role `holder` of the workspace (V1-1: the account of its personal workspace), active profile, confirmed email | yes | yes | yes, active records only | yes | no, except a relation entered by mistake if §13.2 N4 is approved | +| Member with role `holder` of the workspace (V1-1: the account of its personal workspace), active profile, confirmed email | yes | yes | yes, active records only | yes | no; a relation entered by mistake is voided, never deleted (§13.2 N4) | | Future cabinet roles | defined by the cabinet step | | | | | | The same account with an unconfirmed email | no | no | no | no | no | | Another signed-in account | no | no | no | no | no | @@ -334,16 +386,26 @@ Residual technical paths, named so nobody believes them closed: credentials, bounded only by their custody; the exceptional-access contract covers them, with two follow-ups in §14 (a narrower worker credential, monitoring of GoTrue admin actions in `auth.audit_log_entries`); -- the table owner (`postgres`, not a superuser on Supabase) and any database +- the table owner (`postgres`, not a superuser on Supabase, but holding + `BYPASSRLS` on the Supabase image, checked on 17.11.0.004) and any database superuser read past RLS: maintenance, backup restore and incident response are exceptional privileged operations that the separate contract frames, justifies and audits before any publication. +Both paths were exercised on the isolated stack of V1-1.1 (§8.1): the service +key reads nothing through PostgREST (`permission denied`), yet it obtains a +session for any account through GoTrue's admin link generation and then reads +that account's workspace like its practitioner. Removing table privileges +narrows the direct path only; the residual risk stays on the security track +before production (RR-4), as the owner required (N7). + The existing audit policy lets platform owners and admins read audit rows. The -V1-1 rows carry the actor, resource ids, the action and the workspace id. Read -with the staff policy on profiles, that reveals per-practitioner volumes, -working hours and events such as « relation ended »: activity metadata, never -names or contacts. §13.2 N9 decides whether that stays visible. +V1-1 rows carry the actor, the resource id, the action, the time and the +workspace id. Read with the staff policy on profiles, that would reveal +per-practitioner volumes, working hours and events such as « relation ended »: +activity metadata, never names or contacts. N9 (§13.2): platform staff get no +general view of the private records, so M2 removes the `client.*`, `animal.*` +and `animal_client_relation.*` actions from `audit_logs_select_admin`. ### 6.4 Edits and finished bilans (C5, approved) @@ -454,23 +516,24 @@ term travels in a POST body), audit rows, application logs or error messages --- -## 8. SQL schema (proposed, not a migration) +## 8. SQL schema (M1 written, M2 and M3 proposed) 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 -(plan principle 2). Timestamps are set when written. +(plan principle 2). Timestamps are set when written. M1 as built, with its +differences from the sketch below: §8.1. | Migration | Step | Content | |---|---|---| -| M1 `_workspaces.sql` | 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 | +| 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 `_clients.sql` | V1-1.2 | extension `unaccent`; `private.fold_text`; enum `client_kind`; `clients`; write budget helper; client RPCs and searches; grants; RLS | | M3 `_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 header verbatim today (foundation migration), the app never sends it, and PostgREST exposes every header, so a caller chooses the size of each -append-only audit row. V1-1 raises the audited write rate from 10 to 1 000 an -hour per account, which turns that into a storage risk. The change keeps the +append-only audit row. V1-1 raises the audited write rate to 1 000 an hour +per workspace (§10), which turns that into a storage risk. The change keeps the function's signature and callers. Sketch of the tables. `(c)` abbreviates the text rule of §5: @@ -580,6 +643,7 @@ create table public.animal_client_relations ( started_on date, -- >= 1900-01-01 (CHECK); not in the future (RPC) ended_on date, -- idem ended_at timestamptz, + voided_at timestamptz, -- set once by the void RPC (N4) create_request_id uuid not null, revision integer not null default 1, created_at timestamptz not null default now(), @@ -592,12 +656,14 @@ create table public.animal_client_relations ( check (ended_on is null or ended_at is not null), constraint animal_client_relations_dates_order check (started_on is null or ended_on is null or started_on <= ended_on), + constraint animal_client_relations_started_on_range check (started_on >= '1900-01-01'), + constraint animal_client_relations_ended_on_range check (ended_on >= '1900-01-01'), constraint animal_client_relations_create_request_unique unique (workspace_id, create_request_id) ); create unique index animal_client_relations_current_unique on public.animal_client_relations (animal_id, client_id, relation_role) - where ended_at is null; + where ended_at is null and voided_at is null; create index animal_client_relations_animal_idx on public.animal_client_relations (workspace_id, animal_id); create index animal_client_relations_client_idx @@ -644,6 +710,51 @@ follows French alphabetical order closely enough for a list. If the dictionary of `unaccent` ever changed, stored keys would differ from new ones until their rows are rewritten: recorded, low risk. +### 8.1 M1 as built (V1-1.1, 2026-10-25) + +`supabase/migrations/20261025100000_workspaces.sql`, tested by +`supabase/tests/012_workspaces.sql` (85 checks) and the census of +`001_schema.sql`. Differences from the sketch and from the plan, each +deliberate: + +| Point | Sketch or plan | As built | Why | +|---|---|---|---| +| Uniqueness of the personal workspace | inline `unique` | named constraint `workspaces_personal_user_unique` | the single write path targets it with `on conflict`, tests name it | +| Write path | trigger and backfill | both call `private.ensure_personal_workspace(uuid)`: workspace and holder membership inserted by one statement, `on conflict (personal_user_id) do nothing`, returns whether it created | one place for atomicity and idempotence; a concurrent call waits for the first commit, then writes nothing | +| Consistency workspace ↔ holder | not in the sketch | deferred constraint triggers `workspaces_personal_holder` and `workspace_members_personal_holder` on `private.check_personal_workspace()`: at commit, a personal workspace has exactly its account as `holder` | the owner asked for a coherence constraint between the workspace's account and its member; it holds for any writer, the table owner included; cabinets are not constrained | +| Trigger name | not named | `profiles_create_personal_workspace` | | +| `private.writable_workspace_ids()` | M1 | created in M1, unused until M2's write RPCs | the helper set of §9.1 ships and is tested once | +| Access layer `packages/supabase/src/workspaces.ts` | planned in V1-1.1 | deferred to V1-1.2 | no consumer before the clients access layer; the brief authorised M1 and its tests | +| `pnpm db:reset && pnpm db:test` | planned gate | not run: the owner kept the DEV stack untouched | replaced by an isolated real stack (below) | + +Not changed by M1: the privileges of existing tables. `service_role` keeps the +Supabase default privileges it holds today on `profiles`, `profile_roles` and +`assets` (only the new tables and `private.object_purge_queue` revoke it); +narrowing them is outside V1-1.1 and needs the owner's decision (N7). + +Isolated real-stack verification. A throwaway stack built from the DEV stack's +images (PostgreSQL 17.11.0.004, GoTrue v2.197.0, Storage v1.79.36, PostgREST +v16.4, Mailpit v1.31.3) on its own Docker network, ports on the loopback +only, no Docker volume, DEV containers untouched. Two runs: from zero (all +migrations then the seeds, as `supabase db reset`), and the DEV path (the +migrations before M1, the seeds and two accounts created through GoTrue, then +M1, whose backfill created the five missing workspaces). In both: the twelve +pgTAP files green (531 checks); real concurrent sessions (two creations of one +account's workspace: the second waited for the first commit and wrote +nothing; two racing backfills created 40 workspaces between them, no +duplicate; commits of a workspace without its holder or with a foreign member +refused at COMMIT; a rolled-back creation left nothing and the retry created +one); ten parallel GoTrue sign-ups each with one workspace; 33 HTTP checks +through GoTrue and PostgREST (sign-up without session, confirmation by the +mailed link, reads limited to the own workspace, `count=exact` of one, +refusals with `permission denied` for writes, for the anon key and for the +service key, `private` functions unreachable, deactivation effective on the +next request with the same token, the correlation header capped through a +real request, an empty account deleted by the GoTrue admin API taking its +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. + --- ## 9. Policies, helpers and RPCs @@ -654,10 +765,12 @@ rows are rewritten: recorded, low risk. |---|---|---|---| | `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_actor uuid)` | `void` | raises P0001 `rate_limited` when the actor has 1 000 audit rows within the past hour or 5 000 within the past day (every audit row of the actor counts, on the existing `audit_logs_actor_idx`) | none | +| `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.create_personal_workspace()` | trigger | after insert on `profiles`: workspace + `holder` membership | none | +| `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), `set search_path = ''`, `revoke all ... from public, anon, authenticated, @@ -711,7 +824,12 @@ Locks: create RPCs of clients and animals lock the workspace row (cap and insert serialised per workspace); 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. +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. 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` @@ -729,9 +847,9 @@ update that changes nothing writes nothing and returns the current revision. | `update_animal` | `animal_id`, `expected_revision`, the seven fields | `{revision}` | species active or unchanged; birth not in the future | `animal.updated` | | `set_animal_archived` | `animal_id`, `archived` | `{revision}` | same state: no write | `animal.archived` / `animal.restored` | | `create_animal_client_relation` | `animal_id`, `client_id`, `create_request_id`, `relation_role`, optional `started_on` | `{id, revision}` | both in one writable workspace (else 42501); both active; no current duplicate; at most 20 current and 200 total relations per animal and 100 000 per workspace (`limit_reached`); `started_on` not in the future | `animal_client_relation.created` | -| `end_animal_client_relation` | `relation_id`, `expected_revision`, optional `ended_on` | `{revision}` | animal active; current only (`already_ended`); sets `ended_at = now()`; `ended_on` not in the future and not before `started_on` | `animal_client_relation.ended` | -| `update_animal_client_relation` | `relation_id`, `expected_revision`, `started_on`, `ended_on` | `{revision}` | animal active; `ended_on` only on an ended relation; same date rules | `animal_client_relation.updated` | -| `delete_animal_client_relation` | `relation_id`, `expected_revision` | `void` | only if §13.2 N4 is approved; animal active; explicit confirmation in the UI | `animal_client_relation.deleted` | +| `end_animal_client_relation` | `relation_id`, `expected_revision`, optional `ended_on` | `{revision}` | animal active; not voided; current only (`already_ended`); sets `ended_at = now()`; `ended_on` not in the future and not before `started_on` | `animal_client_relation.ended` | +| `update_animal_client_relation` | `relation_id`, `expected_revision`, `started_on`, `ended_on` | `{revision}` | animal active; not voided; `ended_on` only on an ended relation; same date rules | `animal_client_relation.updated` | +| `void_animal_client_relation` | `relation_id`, `expected_revision` | `{revision}` | N4: a relation entered by mistake, current or ended; animal active; not already voided; sets `voided_at = now()`, changes no other column; explicit confirmation in the UI; no deletion | `animal_client_relation.voided` | The combined journeys use the atomic `create_animal` with its optional relation. « New client with a first animal » is two calls (`create_client`, @@ -741,9 +859,12 @@ after a failure resumes at the missing call and never creates a second client. "Not in the future" allows up to the UTC date of tomorrow (and its year for `birth_year`), so a date that is today in any time zone is accepted; the form -checks against the device's local date. Audit metadata is `{workspace_id}`, -plus `{relation_role}` on relation actions: no changed-field list, no name, -contact, date or search term. +checks against the device's local date. Audit rows (N9) hold the technical +ids (actor, resource, workspace in `metadata` as `{workspace_id}`), the +action and its time: no relation role, no changed-field list, no name, +contact, date or search term. A row exists only for a committed write, so its +presence is the result; refusals write nothing, which keeps a caller from +growing the log by failing on purpose. Read RPCs: `language plpgsql`, `security invoker` (RLS applies), stable, `set search_path = ''`, `#variable_conflict use_column`, parameters referenced @@ -840,8 +961,8 @@ 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 actor per rolling hour and 5 000 per rolling day, every audit row of the actor counted on the existing `audit_logs_actor_idx` | 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`) | -| Audit row size | `correlation_id` kept only when it matches `^[A-Za-z0-9-]{1,64}$`; metadata limited to ids and the relation role | the caller no longer chooses the size of an append-only row | M1 (`private.log_event`, CHECK) | +| 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`) | +| 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 | | Login, sign-up, email sending | existing GoTrue limits (`[auth.rate_limit]` in `config.toml`); per-IP limits on `/rest/v1` at the production reverse proxy | | GoTrue; infrastructure (deploy notes) | @@ -879,7 +1000,7 @@ only, never a name or a search term. | `/app/clients/:clientId/edit` | client form | | `/app/animals` | list (name, species, breed, sex, current owners or « Propriétaire non renseigné »), search, species filter, « archivés » filter, « Nouvel animal » | | `/app/animals/new` | animal form with optional client selection or inline client creation; prefilled when opened from a client | -| `/app/animals/:animalId` | identity, owners, keepers and contacts, current then former, with dates; add, end, correct (and remove per N4) a relation; edit, archive or restore | +| `/app/animals/:animalId` | identity, owners, keepers and contacts, current then former, with dates; add, end, correct the dates of, or void (N4) a relation; edit, archive or restore | | `/app/animals/:animalId/edit` | animal form | An unknown id and a forbidden id show the same « introuvable » screen. @@ -1083,19 +1204,22 @@ without the owner's go. | D15 | Principle of technical caps protecting the service, distinct from commercial quotas; thresholds proposed in §10 for validation before the RPCs | | Naming | Explicit nomenclature (§3); no generic `owner_id` | -### 13.2 Technical choices to validate before the first migration +### 13.2 Technical choices, decided by the owner on 2026-10-25 (BDR-074) -| Id | Question | Recommendation | Alternative | +The owner validated N1 to N9 with the precisions of the last column; they +prevail over the recommendation where they differ (N4, N6, N9). + +| Id | Question | Recommendation (preparation) | Owner decision, 2026-10-25 | |---|---|---|---| -| N1 | Species slugs, names and order (§5.4) | Latin adjectives like the existing `equine` (`asinine`, `canine`, `feline`, `bovine`, `caprine`, `ovine`, `porcine`, `leporine`) plus `other`; names Âne, Chien, Chat, Bovin, Chèvre, Mouton, Porc, Lapin, Autre | English nouns (`donkey`, `dog`…), which mixes two schemes since `equine` cannot be renamed (sheets and reports cite it) | -| N2 | First and last names for persons (D4a) | not in V1-1: no V1-1 screen reads them, search and sort use the display name, and adding two nullable columns later touches no row | add `given_name` and `family_name` now with the priority rule of §5.1 | -| N3 | Client notes (not in the ratified list; animal notes deferred) | defer, like animal notes: minimisation, and free text is where sensitive data slips in | keep `notes` (at most 2 000 characters, with a hint to record only what the care needs) | -| N4 | Removing a relation entered by mistake | allow an explicit, confirmed, audited deletion (`delete_animal_client_relation`): ending a wrong relation would record a false « ancien propriétaire », against the accuracy principle; this is an exception to plan principle 4 (no deletion of user data), limited to relations | a `voided_at` flag hidden from every read (keeps the wrong row, adds a filter everywhere), or no correction (end it) | -| N5 | Relation dates | `started_on` and `ended_on` as optional business dates, plus `ended_at` as the owner named it: null while current, the time the end was recorded, so an end with an unknown date never invents one | `ended_at` alone, which stores the recording time as the end date | -| N6 | Thresholds of §10 | as proposed | other values | -| N7 | Service key on the V1-1 tables | no table or RPC privilege for `service_role` (the precedent of the files migration): no direct read path. It does not close the GoTrue admin path (§6.3): the key stays a full-access credential, bounded by its custody | default Supabase privileges for `service_role` (bypasses RLS: one request reads every record) | -| N8 | Sex in the form | three explicit choices, none preselected: one tap more, but « inconnu » then means unknown, not skipped | « Inconnu » preselected | -| N9 | Audit rows read by platform owners and admins | exclude `client.*`, `animal.*` and `animal_client_relation.*` actions from `audit_logs_select_admin` now (a new policy condition in M2): what they reveal (§6.3) is activity of private records, which D16 keeps from staff; incident work reads them through the exceptional-access path | keep the existing policy until the exceptional-access contract | +| N1 | Species slugs, names and order (§5.4) | Latin adjectives like the existing `equine` (`asinine`, `canine`, `feline`, `bovine`, `caprine`, `ovine`, `porcine`, `leporine`) plus `other`; names Âne, Chien, Chat, Bovin, Chèvre, Mouton, Porc, Lapin, Autre | approved: exactly the nine species of the contract plus `other` with a required detail, no invented species, no historical anatomical id renamed; compatibility with the Rust model and Supabase checked before freezing anything (§5.4: rows, not an enum) | +| N2 | First and last names for persons (D4a) | not in V1-1 | approved: no separate names in V1-1; `display_name` is the required reference and the single source of truth | +| N3 | Client notes | defer, like animal notes (minimisation) | approved: deferred; no free-text field without an identified business need | +| N4 | Correcting a relation entered by mistake | an explicit, audited deletion | changed: a traceable logical voiding (`voided_at`, `void_animal_client_relation`), distinct from the normal end of a relation; a voided relation stops appearing as current or former without its history being falsified; `ended_on` never represents a period that never existed; minimised audit row (§5.3, §9.3); nothing built before V1-1.4 | +| N5 | Relation dates | optional `started_on` and `ended_on`, plus `ended_at` recording time | approved: both dates optional, never invented, ordered when both are known; an end date is not a deletion; SQL constraints written in §5.3 before V1-1.4 | +| N6 | Thresholds of §10 | as proposed, write budget per actor | approved as technical caps (not commercial quotas), with the write budget per workspace: 1 000 an hour, 5 000 a day; caps enforced consistently under concurrency, never a bare count then an unprotected insert; counters and locks documented when the RPCs are written; no quota system in V1-1.1 | +| N7 | Service key on the V1-1 tables | no table or RPC privilege for `service_role` | approved as minimisation, without claiming it removes every administrative path: effective grants examined, direct privileges removed, EXECUTE limited, definer owners checked, access tested for anon, authenticated and service_role; global Supabase privileges and existing tables unchanged without a specific decision; the GoTrue admin residual risk stays on the pre-production security track (§6.3) | +| N8 | Sex in the form | three explicit choices, none preselected | approved: nothing preselected, « Inconnu » chosen explicitly, a missing answer never turned into a value | +| N9 | Audit rows read by platform owners and admins | exclude the V1-1 actions from `audit_logs_select_admin` (M2) | approved: no general staff view of private client and animal data; audit rows limited to technical id, operation, time, result and bounded validated correlation ids; no name, contact, observation or business data; append-only kept; caller-controlled growth bounded (correlation cap in M1, §8.1) | ### 13.3 Interface decisions still open @@ -1132,8 +1256,8 @@ 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` | -| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards, N9 audit policy, field limits and parity test, access layer, real-stack e2e | +| 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.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 | @@ -1158,7 +1282,8 @@ Risks and dependencies: - DEV holds fictitious data only until the legal framing (§7.3); - `docs/design/README.md` places the mobile tab bar « with the first list screens », which D11 contradicts until the owner decides; -- the RPC surface grows by fourteen functions (RR-4 review); +- the RPC surface grows by fourteen functions (RR-4 review); N4 replaces the + delete RPC by `void_animal_client_relation`, so the count is unchanged; - the D-R7 chore for the existing forms reuses the V1-1 constants module; - no CI runs on the forge: every gate is local; - two old R5.6 rehearsal worktrees in an earlier session's scratchpad hold