docs(docs): sheet model spec matches the hardened code (counter, SQL-only codes, census, migration list)

This commit is contained in:
bchanot committed 2026-10-09 00:05:39 +02:00
1 parent d3fa65af29
commit 5d32bed829
2 files changed
+17 -13

No files matched your search

+12 -9
View File
@@ -127,10 +127,13 @@ Integrity rules (error unless stated):
| `finding_zone.unreferenced` (warning) | zone no annotation points to | | `finding_zone.unreferenced` (warning) | zone no annotation points to |
A draft may be saved with errors. Publishing a document with errors is A draft may be saved with errors. Publishing a document with errors is
refused in TypeScript (`assertPublishable`) and in SQL refused in TypeScript (`assertPublishable`) and in SQL:
(`private.sheet_document_issues`), which re-checks every error-level rule `private.sheet_document_issues` re-checks every error-level rule except the
except the two recursive ones (parent cycle, sibling uniqueness) and adds two recursive ones (parent cycle, sibling uniqueness) and reports
"every `svg_asset_id` is an asset of this sheet". `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 ## 3. Relational model
@@ -166,9 +169,9 @@ any authenticated user; no write path through the API (platform step later).
### `anatomical_sheet_versions` ### `anatomical_sheet_versions`
| Column | Notes | | Column | Notes |
| ----------------------------------------------------------- | ------------------------------------------------------------------------ | | ----------------------------------------------------------- | --------------------------------------------------------------------------- |
| `id uuid`, `sheet_id` | | | `id uuid`, `sheet_id` | |
| `version_number int` | unique per sheet, assigned by the server (`max + 1`) | | `version_number int` | unique per sheet, assigned by the server from the sheet's monotonic counter |
| `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` | | `status` | enum `sheet_version_status`: `draft` \| `published` \| `deprecated` |
| `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today | | `document_schema_version int` | CHECK = `content->>'schema_version'`; only `1` today |
| `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB | | `content jsonb` | the canonical document; CHECK `jsonb_typeof = 'object'` and size ≤ 2 MiB |
@@ -211,7 +214,7 @@ authorise through the sheet, never through a sha256 alone.
| RPC | Actor | Effect | | 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_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) | | `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) | | `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 | | `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) | | `anatomical_sheet_assets` | same visibility as the sheet | none (RPC) |
`anon` gets nothing. Every `private` function has EXECUTE revoked from `anon` gets nothing. Every `private` function has EXECUTE revoked from
PUBLIC; only the two predicates above are granted to `authenticated` PUBLIC; `authenticated` executes only the policy predicates (the two above
(pgTAP 001 keeps a census). Public discovery views for the public site come 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). with the community step (§17.4).
## 4. What the model guarantees (acceptance criteria) ## 4. What the model guarantees (acceptance criteria)
+5 -4
View File
@@ -13,7 +13,8 @@ supabase/
│ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log │ ├─ 20261008100000_foundation.sql schemas private/audit, updated_at, audit log
│ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS │ ├─ 20261008100100_profiles.sql profiles + auth.users trigger + RLS
│ ├─ 20261008100200_platform_roles.sql platform_role, profile_roles, helpers, RPCs │ ├─ 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) ├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
└─ tests/ pgTAP, one file per concern, allowed AND denied paths └─ tests/ pgTAP, one file per concern, allowed AND denied paths
packages/supabase/ packages/supabase/
@@ -52,7 +53,7 @@ pnpm db:reset # drop + replay every migration + seed from zero
Local endpoints (`config.toml`): Local endpoints (`config.toml`):
| Service | URL | | Service | URL |
|---|---| | --------------------------------------- | --------------------------------------------------------- |
| API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` | | API (PostgREST, Auth, Storage) | `http://127.0.0.1:54321` |
| PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` | | PostgreSQL | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` |
| Studio | `http://127.0.0.1:54323` | | Studio | `http://127.0.0.1:54323` |
@@ -64,7 +65,7 @@ ever reaches the browser.
Seed accounts (local only, password `LocalDev-only-password-1`): Seed accounts (local only, password `LocalDev-only-password-1`):
| Email | Role | | Email | Role |
|---|---| | ----------------------- | ------------------------------------------- |
| `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) | | `owner@faunosteo.local` | platform owner (bootstrapped by `seed.sql`) |
| `alice@faunosteo.local` | plain user | | `alice@faunosteo.local` | plain user |
| `bob@faunosteo.local` | plain user | | `bob@faunosteo.local` | plain user |
@@ -93,7 +94,7 @@ RLS enabled, no `using (true)` / `with check (true)` policy for `anon` or
Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP): Two runners, one SQL source of truth (`supabase/tests/*.sql`, pgTAP):
| Command | Engine | Needs Docker | What runs | | 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 --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 db:test` | `supabase test db` (pg_prove in the local stack) | yes | the same pgTAP files against the real Supabase image |