-- V1-2.5 M7 `sheet_admin_reads`: the read RPCs of the administration space. -- docs/development/V1-2_ANATOMICAL_SHEETS.md §11.1 (`/app/admin/sheets`, its -- overview), §12.3 (M7), §16.6; owner decision 2026-11-02 (BDR-097). -- -- The admin list shows the historical and working-copy badges, the version -- and round states and the rounds awaiting review. The reader column grants -- of M4 leave out `working_copy_source_version_id`, `last_version_number`, -- `updated_at` and the version authors on purpose (§5.3), so the admin space -- reads them here, never through a wider grant: -- * list_official_sheets_admin: every official sheet that is not deleted, -- one summary each; -- * get_official_sheet_admin: one sheet's summary, its versions and its -- rounds, with the names of the people who acted. -- Capability holders at aal2 only (`caller_is_catalog_staff`, the predicate -- of the draft reads); an unknown or forbidden sheet gets one answer. No -- table or policy change here. Rule change limited to the species sort -- order: `create_species` / `update_inactive_species` refuse an order -- outside 0..9 999 (owner 2026-11-02), their privileges restated. Also: -- `get_sheet_version` returns the fingerprint of a deprecated version (§10, -- BDR-098). -- =========================================================================== -- 1. Helpers -- =========================================================================== -- An account as the admin space names it: id and display name. create or replace function private.sheet_admin_person(p_user_id uuid) returns jsonb language sql stable security definer set search_path = '' as $$ select case when p_user_id is null then null else jsonb_build_object( 'user_id', p_user_id, 'display_name', (select p.display_name from public.profiles p where p.id = p_user_id) ) end; $$; -- One official sheet as the admin list shows it. create or replace function private.official_sheet_admin_summary(p_sheet_id uuid) returns jsonb language sql stable security definer set search_path = '' as $$ select jsonb_build_object( 'sheet_id', s.id, 'species_id', s.species_id, 'slug', s.slug, 'status', s.status, 'archived_at', s.archived_at, 'created_at', s.created_at, 'updated_at', s.updated_at, 'name', coalesce(latest.content -> 'name', jsonb_build_object('fr', s.name, 'en', s.name)), 'historical', s.id = private.historical_sheet_id(), 'working_copy', private.is_historical_working_copy(s.id), -- The single slot of §14.3, read where the action is offered. 'working_copy_active', case when s.id = private.historical_sheet_id() then private.historical_working_copy_active(null) end, 'latest_version', case when latest.id is not null then jsonb_build_object( 'version_id', latest.id, 'version_number', latest.version_number, 'status', latest.status, 'revision', latest.revision) end, 'current_version', case when cur.id is not null then jsonb_build_object( 'version_id', cur.id, 'version_number', cur.version_number, 'published_at', cur.published_at) end, 'draft_version', ( select jsonb_build_object('version_id', d.id, 'version_number', d.version_number, 'revision', d.revision) from public.anatomical_sheet_versions d where d.sheet_id = s.id and d.status = 'draft' order by d.version_number desc limit 1), 'version_statuses', coalesce(( select jsonb_agg(distinct v.status) from public.anatomical_sheet_versions v where v.sheet_id = s.id), '[]'::jsonb), 'open_rounds', ( select count(*) from public.anatomical_sheet_reviews r join public.anatomical_sheet_versions v on v.id = r.version_id where v.sheet_id = s.id and r.status = 'open'), 'latest_round', ( select jsonb_build_object('review_id', r.id, 'version_number', v.version_number, 'round', r.round, 'status', r.status, 'submitted_at', r.submitted_at) from public.anatomical_sheet_reviews r join public.anatomical_sheet_versions v on v.id = r.version_id where v.sheet_id = s.id order by r.submitted_at desc nulls last, v.version_number desc, r.round desc limit 1) ) from public.anatomical_sheets s left join public.anatomical_sheet_versions cur on cur.id = s.current_version_id left join lateral ( select v.* from public.anatomical_sheet_versions v where v.sheet_id = s.id order by v.version_number desc limit 1 ) latest on true where s.id = p_sheet_id; $$; -- =========================================================================== -- 2. Read RPCs -- =========================================================================== create or replace function public.list_official_sheets_admin() returns jsonb language plpgsql stable security definer set search_path = '' as $$ begin perform private.require_catalog_actor(); if not private.caller_is_catalog_staff() then raise exception 'rights.capability' using errcode = '42501'; end if; return coalesce(( select jsonb_agg(private.official_sheet_admin_summary(s.id) order by s.species_id, s.slug) from public.anatomical_sheets s where s.is_official and s.status <> 'deleted' ), '[]'::jsonb); end; $$; create or replace function public.get_official_sheet_admin(sheet_id uuid) returns jsonb language plpgsql stable security definer set search_path = '' as $$ #variable_conflict use_column begin perform private.require_catalog_actor(); -- Unknown, deleted, personal and forbidden sheets: one answer (§10). if get_official_sheet_admin.sheet_id is null or not private.caller_can_see_official_sheet(get_official_sheet_admin.sheet_id) then raise exception 'not_found' using errcode = '42501'; end if; return private.official_sheet_admin_summary(get_official_sheet_admin.sheet_id) || jsonb_build_object( 'working_copy_source', ( select jsonb_build_object('version_id', src.id, 'version_number', src.version_number) from public.anatomical_sheets s join public.anatomical_sheet_versions src on src.id = s.working_copy_source_version_id where s.id = get_official_sheet_admin.sheet_id), 'versions', coalesce(( select jsonb_agg(jsonb_build_object( 'version_id', v.id, 'version_number', v.version_number, 'status', v.status, 'revision', v.revision, 'change_note', v.change_note, 'created_at', v.created_at, 'published_at', v.published_at, 'deprecated_at', v.deprecated_at, 'source_version_number', (select src.version_number from public.anatomical_sheet_versions src where src.id = v.source_version_id), 'authors', coalesce((select jsonb_agg(private.sheet_admin_person(a.id) order by a.ord) from unnest(v.authors) with ordinality a(id, ord)), '[]'::jsonb) ) order by v.version_number desc) from public.anatomical_sheet_versions v where v.sheet_id = get_official_sheet_admin.sheet_id), '[]'::jsonb), 'rounds', coalesce(( select jsonb_agg(jsonb_build_object( 'review_id', r.id, 'version_id', v.id, 'version_number', v.version_number, 'round', r.round, 'revision', r.revision, 'status', r.status, 'submitted_by', private.sheet_admin_person(r.submitted_by), 'submitted_at', r.submitted_at, 'verified_at', r.verified_at, 'failure_outcome', r.failure_outcome, 'failure_code', r.failure_code, 'decided_by', private.sheet_admin_person(r.decided_by), 'decided_at', r.decided_at, 'withdrawn_at', r.withdrawn_at ) order by r.submitted_at desc nulls last, v.version_number desc, r.round desc) from public.anatomical_sheet_reviews r join public.anatomical_sheet_versions v on v.id = r.version_id where v.sheet_id = get_official_sheet_admin.sheet_id), '[]'::jsonb) ); end; $$; -- =========================================================================== -- 3. get_sheet_version: the fingerprint of a deprecated version too -- =========================================================================== -- M5 returned the fingerprint for published versions only, while the core's -- PreviewSheet checks it for published and deprecated versions alike (§10: a -- deprecated version previews like a published one), so no withdrawn version -- could open in the catalogue. A deprecated version keeps the fingerprint it -- was published with, already public then; a draft still gets none. Owner -- decision 2026-11-02 (BDR-098). Body otherwise identical to M5. create or replace function public.get_sheet_version(version_id uuid) returns jsonb language plpgsql stable security definer set search_path = '' as $$ #variable_conflict use_column declare v_uid uuid := auth.uid(); v_version public.anatomical_sheet_versions%rowtype; v_sheet public.anatomical_sheets%rowtype; v_allowed boolean; begin if v_uid is null then raise exception 'not_found' using errcode = '42501'; end if; select v.* into v_version from public.anatomical_sheet_versions v where v.id = get_sheet_version.version_id; if v_version.id is null then raise exception 'not_found' using errcode = '42501'; end if; select s.* into v_sheet from public.anatomical_sheets s where s.id = v_version.sheet_id; v_allowed := private.caller_can_see_official_sheet(v_sheet.id) or (v_version.status in ('published', 'deprecated') and private.can_read_catalog_sheet(v_uid, v_sheet.id)); if not v_allowed then raise exception 'not_found' using errcode = '42501'; end if; return jsonb_build_object( 'sheet_id', v_sheet.id, 'version_id', v_version.id, 'version_number', v_version.version_number, 'status', v_version.status, 'species_id', v_sheet.species_id, 'document', v_version.content, 'revision', v_version.revision, 'fingerprint', case when v_version.status in ('published', 'deprecated') then v_version.document_fingerprint end, 'drawings', coalesce(( select jsonb_agg(jsonb_build_object('asset_id', a.id, 'sha256', a.sha256, 'byte_size', a.byte_size) order by a.id) from public.anatomical_sheet_assets a where a.sheet_id = v_sheet.id and a.uploaded_at is not null and a.id::text = any (private.sheet_document_asset_ids(v_version.content)) ), '[]'::jsonb) ); end; $$; comment on function public.list_official_sheets_admin() is 'Capability holders, live aal2 session: every official sheet that is not deleted, with its historical and working-copy badges, version and round states (V1-2 contract §11.1, M7).'; comment on function public.get_official_sheet_admin(uuid) is 'Capability holders, live aal2 session: one official sheet''s summary, versions (authors named) and rounds (actors named); unknown and forbidden ids answer not_found (V1-2 contract §11.1, M7).'; -- =========================================================================== -- 4. Privileges -- =========================================================================== revoke all on function private.sheet_admin_person(uuid) from public, anon, authenticated, service_role; revoke all on function private.official_sheet_admin_summary(uuid) from public, anon, authenticated, service_role; revoke all on function public.list_official_sheets_admin() from public, anon, service_role; revoke all on function public.get_official_sheet_admin(uuid) from public, anon, service_role; grant execute on function public.list_official_sheets_admin() to authenticated; grant execute on function public.get_official_sheet_admin(uuid) to authenticated; -- Kept by `create or replace`, stated again so this file stands alone. revoke all on function public.get_sheet_version(uuid) from public, anon, service_role; grant execute on function public.get_sheet_version(uuid) to authenticated; -- =========================================================================== -- 5. Species order range (owner 2026-11-02) -- =========================================================================== -- The M5 bodies, with the sort order bounded 0..9 999 (null keeps today's -- meaning: the default 100 on creation, the stored value on update). create or replace function public.create_species(id text, name_fr text, name_en text, sort_order integer default 100) returns text language plpgsql volatile security definer set search_path = '' as $$ #variable_conflict use_column declare v_actor uuid := private.require_capability('sheet_editor'); begin if create_species.id is null or create_species.id !~ '^[a-z0-9][a-z0-9_-]{0,63}$' or create_species.id = 'other' or char_length(name_fr) not between 1 and 80 or char_length(name_en) not between 1 and 80 or (create_species.sort_order is not null and create_species.sort_order not between 0 and 9999) then raise exception 'invalid_input' using errcode = 'P0001'; end if; if exists (select 1 from public.species s where s.id = create_species.id) then raise exception 'species.exists' using errcode = 'P0001'; end if; perform private.consume_catalog_write_budget(v_actor); insert into public.species (id, name_fr, name_en, sort_order, active) values (create_species.id, name_fr, name_en, coalesce(sort_order, 100), false); perform private.log_event(v_actor, 'species.created', 'species', null, null, null, jsonb_build_object('id', create_species.id)); return create_species.id; end; $$; create or replace function public.update_inactive_species(id text, name_fr text, name_en text, sort_order integer) returns text language plpgsql volatile security definer set search_path = '' as $$ #variable_conflict use_column declare v_actor uuid := private.require_capability('sheet_editor'); begin if char_length(name_fr) not between 1 and 80 or char_length(name_en) not between 1 and 80 or (update_inactive_species.sort_order is not null and update_inactive_species.sort_order not between 0 and 9999) then raise exception 'invalid_input' using errcode = 'P0001'; end if; perform 1 from public.species s where s.id = update_inactive_species.id and not s.active for update; if not found then raise exception 'species.not_inactive' using errcode = 'P0001'; end if; perform private.consume_catalog_write_budget(v_actor); update public.species s set name_fr = update_inactive_species.name_fr, name_en = update_inactive_species.name_en, sort_order = coalesce(update_inactive_species.sort_order, s.sort_order) where s.id = update_inactive_species.id; perform private.log_event(v_actor, 'species.updated', 'species', null, null, null, jsonb_build_object('id', update_inactive_species.id)); return update_inactive_species.id; end; $$; revoke all on function public.create_species(text, text, text, integer) from public, anon, service_role; revoke all on function public.update_inactive_species(text, text, text, integer) from public, anon, service_role; grant execute on function public.create_species(text, text, text, integer) to authenticated; grant execute on function public.update_inactive_species(text, text, text, integer) to authenticated;