From 5d32bed829060057d92e54a8770d74e49eb91b47 Mon Sep 17 00:00:00 2001 From: bchanot Date: Fri, 9 Oct 2026 00:05:39 +0200 Subject: [PATCH] docs(docs): sheet model spec matches the hardened code (counter, SQL-only codes, census, migration list) --- docs/development/ANATOMICAL_SHEET_MODEL.md | 37 ++++++++++++---------- docs/development/SUPABASE.md | 31 +++++++++--------- 2 files changed, 36 insertions(+), 32 deletions(-) diff --git a/docs/development/ANATOMICAL_SHEET_MODEL.md b/docs/development/ANATOMICAL_SHEET_MODEL.md index 53cdcfd7..35a8bd4a 100644 --- a/docs/development/ANATOMICAL_SHEET_MODEL.md +++ b/docs/development/ANATOMICAL_SHEET_MODEL.md @@ -127,10 +127,13 @@ Integrity rules (error unless stated): | `finding_zone.unreferenced` (warning) | zone no annotation points to | A draft may be saved with errors. Publishing a document with errors is -refused in TypeScript (`assertPublishable`) and in SQL -(`private.sheet_document_issues`), which re-checks every error-level rule -except the two recursive ones (parent cycle, sibling uniqueness) and adds -"every `svg_asset_id` is an asset of this sheet". +refused in TypeScript (`assertPublishable`) and in SQL: +`private.sheet_document_issues` re-checks every error-level rule except the +two recursive ones (parent cycle, sibling uniqueness) and reports +`document.shape` when an id-bearing collection is not an array; +`private.sheet_document_unknown_assets` adds `view.asset.unknown` when a +view points at an asset not registered for the sheet. Both run inside +`publish_sheet_version`. ## 3. Relational model @@ -165,16 +168,16 @@ any authenticated user; no write path through the API (platform step later). ### `anatomical_sheet_versions` -| Column | Notes | -| ----------------------------------------------------------- | ------------------------------------------------------------------------ | -| `id uuid`, `sheet_id` | | -| `version_number int` | unique per sheet, assigned by the server (`max + 1`) | -| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` | -| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today | -| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB | -| `change_note text` | what changed in this version | -| `created_by`, `published_by`, `deprecated_by` | profile ids, `on delete set null` | -| `published_at`, `deprecated_at`, `created_at`, `updated_at` | | +| Column | Notes | +| ----------------------------------------------------------- | --------------------------------------------------------------------------- | +| `id uuid`, `sheet_id` | | +| `version_number int` | unique per sheet, assigned by the server from the sheet's monotonic counter | +| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` | +| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today | +| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB | +| `change_note text` | what changed in this version | +| `created_by`, `published_by`, `deprecated_by` | profile ids, `on delete set null` | +| `published_at`, `deprecated_at`, `created_at`, `updated_at` | | Rules enforced by triggers (every role, including the table owner): @@ -211,7 +214,7 @@ authorise through the sheet, never through a sha256 alone. | RPC | Actor | Effect | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `create_anatomical_sheet(species_id, name, slug, document, description, visibility, official)` | any active account; `official = true` needs platform admin | sheet + draft v1 | -| `create_sheet_draft(sheet_id, from_version_id, change_note)` | editor | new draft `max + 1`, content copied from `from_version_id` (default: current version); refused if a draft exists | +| `create_sheet_draft(sheet_id, from_version_id, change_note)` | editor | new draft (next counter value), content copied from `from_version_id` (default: current version); refused if a draft exists | | `publish_sheet_version(version_id)` | editor | draft → published; relational checks; sheet `current_version_id` ← version. Previous published versions stay `published` (historical reports keep rendering) | | `deprecate_sheet_version(version_id, reason)` | editor | published → deprecated (not offered for new reports; still readable) | | `delete_sheet_version(version_id)` | editor | physical delete, trigger preconditions | @@ -248,8 +251,8 @@ Policies: | `anatomical_sheet_assets` | same visibility as the sheet | none (RPC) | `anon` gets nothing. Every `private` function has EXECUTE revoked from -PUBLIC; only the two predicates above are granted to `authenticated` -(pgTAP 001 keeps a census). Public discovery views for the public site come +PUBLIC; `authenticated` executes only the policy predicates (the two above +plus the five platform-role predicates of Step 3); pgTAP 001 keeps a census. Public discovery views for the public site come with the community step (§17.4). ## 4. What the model guarantees (acceptance criteria) diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index 29ab6bdb..b137c74f 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -13,7 +13,8 @@ supabase/ │ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log │ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS │ ├─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs -│ └─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs +│ ├─ 20261008110000_anatomical_sheets.sql species, sheets, immutable versions, assets, lifecycle RPCs +│ └─ 20261008110100_private_execute_hardening.sql EXECUTE revoked from PUBLIC on the Step 3 helpers ├─ seed.sql LOCAL dev accounts + first owner (never run in prod) └─ tests/ pgTAP, one file per concern, allowed AND denied paths packages/supabase/ @@ -51,23 +52,23 @@ pnpm db:reset # drop + replay every migration + seed from zero Local endpoints (`config.toml`): -| Service | URL | -|---|---| -| API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` | -| PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` | -| Studio | `http://127.0.0.1:54323` | -| Mail catcher (confirmation / OTP mails) | `http://127.0.0.1:54324` | +| Service | URL | +| --------------------------------------- | --------------------------------------------------------- | +| API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` | +| PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` | +| Studio | `http://127.0.0.1:54323` | +| Mail catcher (confirmation / OTP mails) | `http://127.0.0.1:54324` | `pnpm db:start` prints the `anon` and `service_role` keys. Only the anon key ever reaches the browser. Seed accounts (local only, password `LocalDev-only-password-1`): -| Email | Role | -|---|---| +| Email | Role | +| ----------------------- | ------------------------------------------- | | `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) | -| `alice@faunosteo.local` | plain user | -| `bob@faunosteo.local` | plain user | +| `alice@faunosteo.local` | plain user | +| `bob@faunosteo.local` | plain user | ## 4. Writing a migration @@ -92,10 +93,10 @@ RLS enabled, no `using (true)` / `with check (true)` policy for `anon` or Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP): -| Command | Engine | Needs Docker | What runs | -|---|---|---|---| -| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema + all migrations + every pgTAP file; schema ↔ types check; client factory; publish gate | -| `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image | +| Command | Engine | Needs Docker | What runs | +| -------------------------------------------- | ------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `pnpm --filter @faunosteo/supabase test:run` | PGlite (PostgreSQL 17 in WASM) | no | shim of the Supabase base schema + all migrations + every pgTAP file; schema ↔ types check; client factory; publish gate | +| `pnpm db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image | `pnpm test:run` at the root runs the PGlite suite together with the app suite. The shim (`packages/supabase/tests/db/supabase-shim.sql`) recreates