Files
faunosteo/.claude/tasks/contracts/2026-10-26-v1-1-4-animals-relations.md

6.8 KiB

CONTRACT: V1-1.4 Animals and relations (M3) + V1-1.3 follow-ups, owner brief 2026-10-26 « Validation V1-1.3 et autorisation V1-1.4 Animaux et relations »

  • branch feature/v1-1-clients-animals, base 0826ecf (V1-1.3 validated); commits 2dc04bc (sandbox upgrade <then>), b54c8e5 (M3 code), 533a1c4 (tests strengthened after mutations), ba3a51e (axe exceptions scoped), d7845b7 (check:all statuses), bc6a7dd (docs)
  • diff under review: git diff 0826ecf..bc6a7dd -- supabase packages scripts apps/app/e2e docs CLAUDE.md
  • functional contract docs/development/V1-1_OWNERS_ANIMALS.md §3, §5, §5.2-§5.4, §6, §7.1, §8, §8.3, §9, §10, §12, §13.2 (N1, N4, N5, N6, N7, N8, N9)
  • isolated stack: pnpm db:sandbox (scripts/db-sandbox.sh, SUPABASE.md §5.1) is UP (upgrade mode: M1 + M2 base, then M3). Allowed: pnpm db:sandbox test-db, pnpm db:sandbox types --check, pnpm db:sandbox test, echo "<read-only SQL>" | pnpm db:sandbox sql, pnpm --filter @faunosteo/supabase test:run (PGlite). Not allowed: pnpm check:all, builds, pnpm wasm:build (a check:all run is in progress), db:sandbox up/down. The DEV stack (supabase_*_faunosteo) must not be touched except pnpm supabase migration list --local (read-only).

Clauses

C1. Scope. One new migration, supabase/migrations/20261026100000_animals_relations.sql; no other migration added or edited. No React screen, route, form or navigation change; no access layer for animals or relations (moved to the UI steps, as clients.ts at V1-1.2); no change under crates/; no sheet published or linked to a species. V1-1.3 follow-ups limited to test code (apps/app/e2e/support/browser.ts), scripts/check-all.sh and docs.

C2. Species. Exactly the nine species of contract §5.4 plus other, with the ids, names and order listed there; equine unchanged; rows of public.species, not an enum; the Rust domain untouched; the table comment says a row does not mean a sheet exists.

C3. Animal model. Every animal in one workspace (on delete restrict); required name (1-80, text rule), species (active row), sex (male|female|unknown, no default); optional breed (≤ 80), birth_year (1900-2100 CHECK, not after tomorrow's UTC year in the RPC), birth_date (≥ 1900-01-01, not after tomorrow UTC, requires birth_year equal to its year); no date invented from a year; species_detail required with other, refused otherwise; no column beyond contract §5.2 (no photo, weight, coat, identification, neutering, death, notes).

C4. Relations. Many-to-many with relation_role owner|keeper|contact; animal without relation allowed; several owners allowed; composite foreign keys (workspace_id, animal_id) and (workspace_id, client_id), not deferrable, so no row joins two workspaces whatever writes it (RPC, privileged SQL, later reference update, concurrency); at most one current row per (animal, client, role) by a partial unique index on rows with ended_at and voided_at null; current / ended (date known or unknown, told apart by ended_at) / voided as in contract §8.3; ended_on only with ended_at, ordered after started_on, no default dates; voiding keeps every value, sets voided_at, freezes the row, removes it from lists, derived values, the current index and the current cap; no deletion path through the API.

C5. RPCs and privileges. The ten functions of contract §9.3 for animals and relations plus search_clients recreated with current_animal_count (deviation: search_animals filter named species_filter, §8.3). Write RPCs: security definer, search_path = '', owner postgres, identity from auth.uid() through private.writable_workspace_ids() (active profile, confirmed email, holder); the same whole 42501 not_found for a foreign and an unknown id; no lock taken in another workspace; order archived → revision → rules; parse and constraint errors → invalid_input without the value; idempotent creates, divergent replay request_conflict; audit rows {workspace_id} only, hidden from platform staff (N9). Reads: security invoker (RLS). EXECUTE: authenticated only on the public functions, nobody on the new private helpers; anon and service_role hold no table or function privilege on M3 objects (N7); RLS on both tables, one SELECT policy each through caller_workspace_ids(), no platform-role branch.

C6. Budget, caps, locks. The M2 counter private.consume_write_budget shared by clients, animals and relations (no table-specific budget), 1 000 / hour, 5 000 / day, UTC windows; refused, replayed and no-op calls not counted; create_animal with its relation counts two writes. Caps 20 000 animals and 100 000 relations per workspace, 20 current and 200 total relations per animal, counted under locks; voided and ended rows count in the totals, not in the current cap. Lock order consistent across M2 and M3 as in contract §8.3 (workspace, animal, relation, client, budget last); concurrency and absence of deadlock tested.

C7. Reads. Pages 25 by default and 100 at most (list_client_animals 50 / 100), terms ≤ 100 characters, deterministic keyset order, LIKE wildcards escaped, POST only; no row, count or page of another workspace; current_animal_count = distinct active animals of current non-voided relations; current_owners / current_owner_count per contract §9.3 (voided and ended left out, archived owners flagged); client_archive_preview per §9.3; M2 behaviour of search_clients otherwise unchanged.

C8. D-R7 parity. packages/supabase/src/field-limits.ts holds the animal bounds and the year and date floors; tests/db/field-limits.test.ts proves by behaviour (valid, at the bound, past it, control characters, Unicode code points) that TypeScript never accepts what SQL refuses.

C9. Tests. pgTAP 014_animals_relations.sql plus 001-013 green on PGlite and on the isolated real image; sandbox suites (workspaces, clients, animals) green with real GoTrue and PostgREST sessions; the four migration states of contract §8.3 claimed green; types in database.types.ts equal to the generator's output against the sandbox (pnpm db:sandbox types --check), no hand edit; the mutation claims of §8.3 plausible from the test code.

C10. V1-1.3 follow-ups. Each axe exception matches rule, selector, opening markup and route, so a new screen or element is not masked; check:all states PASSED / SKIPPED (environment missing) / NOT RUN per browser suite, a running suite that fails stops it with FAILED and a non-zero exit; pnpm e2e:ui and pnpm e2e:shell remain independent commands.

C11. Docs and limits. Contract §8.3 as built; SUPABASE.md §3.3 procedure from DEV's current state to M3 (backup, history check, no reset, not run) and §3.5; TEST_STRATEGY; CLAUDE.md. Commits pushed; no merge; main and release/0.2.0 untouched; DEV untouched; fixtures fictitious.