@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/migrations/20260904160000_0d565000-2839-4738-aacc-537d7090398f.sql

@@ -0,0 +1,751 @@
+-- Every public transition in one transaction, including the two that hide -----
+--
+-- The previous migration made publication rows the only thing the public
+-- reader consults. That closed the scheduling leaks and left three holes,
+-- because three writes still changed public visibility without going through
+-- a publication:
+--
+--   * Moving a page to the trash set `deleted_at` and left its open
+--     publication behind. Restoring it cleared `deleted_at` and the page came
+--     straight back onto the internet — while `pages.status` said draft.
+--     Restore had quietly become a publishing action nobody confirmed.
+--   * Publishing a page whose countdown reveals another page committed the
+--     publication first and scheduled the reveals afterwards, in separate
+--     transactions. The second reveal failing left the first one committed and
+--     the source page live, and reported the whole save as failed.
+--   * `cms_save_page_version` published without writing an audit entry, so the
+--     one route most editors publish through left no trace.
+--
+-- All three are fixed here, and the reveal logic is not copied: publishing
+-- calls the same `cms_schedule_page_reveal` the countdown path always used,
+-- from inside its own transaction, so either the page and every reveal commit
+-- or none of them does.
+
+-- 1. Pages already in the trash with a publication still open ----------------
+--
+-- They cannot be reached today — the reader joins `pages` and skips deleted
+-- ones — but the row is a loaded gun pointed at the restore button. Retire it
+-- now so restoring an old page is the ordinary "back as a draft" it reads as.
+UPDATE public.page_publications pp
+   SET is_active = false
+  FROM public.pages p
+ WHERE pp.page_id = p.id
+   AND pp.is_active
+   AND p.deleted_at IS NOT NULL;
+
+-- Deleted pages are draft pages. One of them saying "published" in a list is a
+-- claim about the public website that has not been true since it was deleted.
+UPDATE public.pages
+   SET status = 'draft'
+ WHERE deleted_at IS NOT NULL
+   AND status <> 'draft';
+
+-- 2. Trash and restore -------------------------------------------------------
+
+-- Move a page to the trash: it disappears from the public website, and the
+-- rows that made it public are retired rather than left waiting.
+CREATE OR REPLACE FUNCTION public.cms_soft_delete_page(
+  _page_id     uuid,
+  _audit       jsonb DEFAULT '{}'::jsonb,
+  _actor_email text  DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid  uuid := app.current_user_id();
+  _page public.pages;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NULL
+    FOR UPDATE;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+  IF _page.is_system THEN
+    RAISE EXCEPTION 'System pages cannot be deleted' USING ERRCODE = '42501';
+  END IF;
+
+  UPDATE public.page_publications
+     SET is_active = false
+   WHERE page_id = _page_id AND is_active;
+
+  UPDATE public.pages
+     SET deleted_at       = now(),
+         deleted_by       = _uid,
+         deleted_by_email = public.cms_actor_email(_uid, _actor_email),
+         status           = 'draft',
+         updated_at       = now(),
+         updated_by       = _uid
+   WHERE id = _page_id;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid,
+    public.cms_actor_email(_uid, _actor_email),
+    'page.soft_delete',
+    'pages',
+    _page_id::text,
+    COALESCE(_audit, '{}'::jsonb) || jsonb_build_object('key', _page.key, 'name', _page.name)
+  );
+
+  RETURN jsonb_build_object('deleted', true, 'key', _page.key, 'name', _page.name);
+END;
+$$;
+
+-- Take a page out of the trash. It comes back as a hidden draft and nothing
+-- else: republishing it is a separate, deliberate act.
+--
+-- The publication rows are retired again rather than trusted to be retired
+-- already. This function is the last thing standing between a row written by
+-- some older code path and a page the world can suddenly read.
+--
+-- Which is exactly why it may only touch a page that is *in* the trash. Called
+-- with the id of a live page it would do everything above to a page nobody
+-- deleted: retire the publication carrying it and set its status back to
+-- draft. That is an unpublish wearing a restore's name, and it is reachable
+-- from any caller that can guess a page id. A page that is not deleted is
+-- therefore not found here at all — the row is neither read nor locked — and
+-- the caller is told what is wrong instead.
+CREATE OR REPLACE FUNCTION public.cms_restore_page(
+  _page_id     uuid,
+  _audit       jsonb DEFAULT '{}'::jsonb,
+  _actor_email text  DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid  uuid := app.current_user_id();
+  _page public.pages;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NOT NULL
+    FOR UPDATE;
+  IF _page.id IS NULL THEN
+    -- Two different mistakes, and an editor can only fix the one they made.
+    IF EXISTS (SELECT 1 FROM public.pages WHERE id = _page_id) THEN
+      RAISE EXCEPTION 'Page is not in the trash, so there is nothing to restore.'
+        USING ERRCODE = '22023';
+    END IF;
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  UPDATE public.page_publications
+     SET is_active = false
+   WHERE page_id = _page_id AND is_active;
+
+  UPDATE public.pages
+     SET deleted_at       = NULL,
+         deleted_by       = NULL,
+         deleted_by_email = NULL,
+         status           = 'draft',
+         updated_at       = now(),
+         updated_by       = _uid
+   WHERE id = _page_id;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid,
+    public.cms_actor_email(_uid, _actor_email),
+    'page.restore',
+    'pages',
+    _page_id::text,
+    COALESCE(_audit, '{}'::jsonb) || jsonb_build_object('key', _page.key, 'name', _page.name)
+  );
+
+  RETURN jsonb_build_object('restored', true, 'key', _page.key, 'name', _page.name);
+END;
+$$;
+
+-- 3. Saving, publishing and revealing as one transaction ---------------------
+--
+-- The parameter list grows by two, so the old signature is dropped rather than
+-- replaced: `CREATE OR REPLACE` with extra defaulted parameters leaves both
+-- versions installed, and a call by name then matches neither uniquely.
+DROP FUNCTION IF EXISTS public.cms_save_page_version(uuid, jsonb, text, boolean, text);
+
+CREATE OR REPLACE FUNCTION public.cms_save_page_version(
+  _page_id     uuid,
+  _blocks      jsonb,
+  _note        text    DEFAULT NULL,
+  _publish     boolean DEFAULT false,
+  _actor_email text    DEFAULT NULL,
+  -- `[{ "key": "...", "publishAt": "...", "description": "..." }]` — the pages
+  -- a countdown on this page reveals when its timer reaches zero.
+  _reveals     jsonb   DEFAULT '[]'::jsonb,
+  _audit       jsonb   DEFAULT '{}'::jsonb
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid        uuid := app.current_user_id();
+  _email      text;
+  _page       public.pages;
+  _next_no    integer;
+  _version_id uuid;
+  _reveal     jsonb;
+  _scheduled  jsonb := '[]'::jsonb;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NULL
+    FOR UPDATE;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  _email := public.cms_actor_email(_uid, _actor_email);
+
+  SELECT COALESCE(MAX(version_no), 0) + 1 INTO _next_no
+    FROM public.page_versions WHERE page_id = _page_id;
+
+  INSERT INTO public.page_versions
+    (page_id, version_no, blocks, note, created_by, created_by_email)
+  VALUES
+    (_page_id, _next_no, COALESCE(_blocks, '[]'::jsonb), _note, _uid, _email)
+  RETURNING id INTO _version_id;
+
+  UPDATE public.pages
+     SET current_version_id = _version_id,
+         updated_at         = now(),
+         updated_by         = _uid
+   WHERE id = _page_id;
+
+  IF _publish THEN
+    UPDATE public.page_publications
+       SET is_active = false
+     WHERE page_id = _page_id AND is_active;
+
+    INSERT INTO public.page_publications (page_id, version_id, is_active, published_by)
+    VALUES (_page_id, _version_id, true, _uid);
+
+    UPDATE public.pages SET status = 'published' WHERE id = _page_id;
+
+    -- The audit row belongs to the same transaction as the publication it
+    -- describes. Publishing from the builder is the route most editors take,
+    -- and until now it was the one that left no trace.
+    INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+    VALUES (
+      _uid, _email, 'page.publish', 'pages', _page_id::text,
+      COALESCE(_audit, '{}'::jsonb)
+        || jsonb_build_object('key', _page.key, 'status', 'published',
+                              'versionNo', _next_no, 'versionId', _version_id)
+    );
+
+    /*
+     * Reveals are part of the publish, not a follow-up to it. Scheduling them
+     * here — through the very function the countdown path already used, so
+     * there is one implementation of a reveal and not two — means a target
+     * that cannot be scheduled takes the whole publish down with it instead of
+     * leaving a page live and reporting failure. A countdown naming a page
+     * that was renamed or never written to is an editing mistake rather than a
+     * failure: that function reports it scheduled nothing, and the save
+     * carries on.
+     */
+    FOR _reveal IN SELECT value FROM jsonb_array_elements(COALESCE(_reveals, '[]'::jsonb))
+    LOOP
+      _scheduled := _scheduled || jsonb_build_array(
+        jsonb_build_object('key', _reveal->>'key')
+          || public.cms_schedule_page_reveal(
+               _reveal->>'key',
+               (_reveal->>'publishAt')::timestamptz,
+               COALESCE(_audit, '{}'::jsonb)
+                 || jsonb_build_object('description', _reveal->>'description'),
+               _actor_email,
+               -- Named, so a countdown pointing at the page being published is
+               -- refused instead of hiding it until its own deadline.
+               _page_id,
+               -- Publishing now means the countdown starts now, so a deadline
+               -- already past is refused here for the same reason it is on the
+               -- scheduled path: it would reveal the target before anyone
+               -- could see the countdown that was supposed to reveal it.
+               now()
+             )
+      );
+    END LOOP;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'versionId', _version_id,
+    'versionNo', _next_no,
+    'published', _publish,
+    'reveals',   _scheduled
+  );
+END;
+$$;
+
+-- 4. One rule, in one place --------------------------------------------------
+--
+-- `cms_page_publication_json` was a second implementation of "what is public
+-- right now", and not the same one: it discarded expired rows before choosing
+-- a governing row, so an older publication could come back into force behind a
+-- window that had closed — exactly the behaviour the single rule exists to
+-- rule out. No caller ever read it. A second implementation that agrees today
+-- is still a second implementation, so it goes.
+CREATE OR REPLACE FUNCTION public.cms_set_page_status(
+  _page_id     uuid,
+  _status      text,
+  _audit       jsonb DEFAULT '{}'::jsonb,
+  _actor_email text  DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid  uuid := app.current_user_id();
+  _page public.pages;
+  _next text := lower(btrim(COALESCE(_status, '')));
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  IF _next NOT IN ('draft', 'published') THEN
+    RAISE EXCEPTION 'Unknown page status %', _status USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NULL
+    FOR UPDATE;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+  IF _next = 'published' AND _page.current_version_id IS NULL THEN
+    RAISE EXCEPTION 'This page has no saved content yet, so there is nothing to publish.'
+      USING ERRCODE = '22023';
+  END IF;
+
+  UPDATE public.page_publications
+     SET is_active = false
+   WHERE page_id = _page_id AND is_active;
+
+  IF _next = 'published' THEN
+    INSERT INTO public.page_publications (page_id, version_id, is_active, published_by)
+    VALUES (_page_id, _page.current_version_id, true, _uid);
+  END IF;
+
+  UPDATE public.pages SET status = _next, updated_at = now(), updated_by = _uid
+   WHERE id = _page_id;
+
+  -- The audit row belongs to the same transaction: a publish nobody can account
+  -- for afterwards is its own kind of half-applied write.
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid,
+    public.cms_actor_email(_uid, _actor_email),
+    CASE WHEN _next = 'published' THEN 'page.publish' ELSE 'page.unpublish' END,
+    'pages',
+    _page_id::text,
+    COALESCE(_audit, '{}'::jsonb) || jsonb_build_object('key', _page.key, 'status', _next)
+  );
+
+  RETURN jsonb_build_object('status', _next, 'key', _page.key);
+END;
+$$;
+
+DROP FUNCTION IF EXISTS public.cms_page_publication_json(uuid);
+
+-- 5. A reveal reveals; it never hides ----------------------------------------
+--
+-- `cms_schedule_page_reveal` retired every active publication on its target
+-- before writing the future one. On a page that is not public yet — the only
+-- kind a countdown is meant to point at — there is nothing to retire and the
+-- statement is a no-op. On any other page it is a silent unpublish:
+--
+--   * a countdown naming its own page retired the publication the very same
+--     transaction had just written, so publishing the page hid it until the
+--     deadline it was counting down to;
+--   * a countdown naming a page that is live now took that page off the public
+--     website, with no confirmation and nothing in the UI to suggest it might.
+--
+-- Both are editing mistakes rather than intentions, and both are refused here
+-- rather than carried out. Refusing inside the transaction is what makes the
+-- refusal safe to act on: the publish that carried the bad reveal rolls back
+-- with it, so the editor is told what is wrong while the site still shows what
+-- it showed a moment ago.
+--
+-- The signature grows by two, so the old one is dropped rather than replaced —
+-- `CREATE OR REPLACE` with extra defaulted parameters leaves both installed and
+-- a call by name then matches neither uniquely.
+DROP FUNCTION IF EXISTS public.cms_schedule_page_reveal(text, timestamptz, jsonb, text);
+
+CREATE OR REPLACE FUNCTION public.cms_schedule_page_reveal(
+  _page_key          text,
+  _publish_at        timestamptz,
+  _audit             jsonb       DEFAULT '{}'::jsonb,
+  _actor_email       text        DEFAULT NULL,
+  -- The page whose countdown asks for this, so a countdown pointed at its own
+  -- page can be recognised before anything is written.
+  _source_page_id    uuid        DEFAULT NULL,
+  -- When that page itself becomes public, for a reveal being scheduled
+  -- alongside a future publication. NULL when the source is going live now.
+  _source_publish_at timestamptz DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid       uuid := app.current_user_id();
+  _page      public.pages;
+  _governing public.page_publications;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  IF _publish_at IS NULL THEN
+    RAISE EXCEPTION 'A reveal needs an instant to happen at' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE key = btrim(_page_key) AND deleted_at IS NULL
+    FOR UPDATE;
+
+  -- A countdown may name a page that was renamed, deleted or never written to.
+  -- That is an editing mistake, not a database error: say nothing happened.
+  IF _page.id IS NULL OR _page.current_version_id IS NULL THEN
+    RETURN jsonb_build_object('scheduled', false, 'reason', 'no-such-page');
+  END IF;
+
+  -- Checked before any write, because the write this one would do is the one
+  -- that hides the page the editor is publishing.
+  IF _source_page_id IS NOT NULL AND _page.id = _source_page_id THEN
+    RAISE EXCEPTION
+      'The countdown on "%" is set to reveal the page it is on. A page cannot '
+      'reveal itself: point the countdown at another page, or change what it '
+      'does when the timer reaches zero.', _page.key
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- A reveal that fires before the page carrying its countdown appears would
+  -- publish the target while the countdown is still invisible.
+  IF _source_publish_at IS NOT NULL AND _publish_at <= _source_publish_at THEN
+    RAISE EXCEPTION
+      'The countdown revealing "%" reaches zero at %, at or before the page '
+      'carrying it goes live at %. Move the countdown deadline after the '
+      'publication time.', _page.key, _publish_at, _source_publish_at
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- The same rule the public reader uses: the newest active row whose start
+  -- has arrived governs, and the page is public while that row is open.
+  SELECT * INTO _governing FROM public.page_publications
+    WHERE page_id = _page.id AND is_active AND publish_at <= now()
+    ORDER BY publish_at DESC, published_at DESC
+    LIMIT 1;
+  IF _governing.id IS NOT NULL
+     AND (_governing.unpublish_at IS NULL OR _governing.unpublish_at > now()) THEN
+    RAISE EXCEPTION
+      'The page "%" is already on the public website, so a countdown cannot '
+      'reveal it. Unpublish it first, or point the countdown at a page that is '
+      'still hidden.', _page.key
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- Saving the same page twice must not pile up identical reveals.
+  IF EXISTS (
+    SELECT 1 FROM public.page_publications pp
+     WHERE pp.page_id    = _page.id
+       AND pp.version_id = _page.current_version_id
+       AND pp.publish_at = _publish_at
+       AND pp.is_active
+  ) THEN
+    RETURN jsonb_build_object('scheduled', false, 'reason', 'already-scheduled',
+                              'pageId', _page.id);
+  END IF;
+
+  -- Whatever is retired here is either waiting or finished: a governing row
+  -- that is still open was refused above, so this cannot take a page offline.
+  UPDATE public.page_publications
+     SET is_active = false
+   WHERE page_id = _page.id AND is_active;
+
+  INSERT INTO public.page_publications
+    (page_id, version_id, publish_at, is_active, published_by)
+  VALUES
+    (_page.id, _page.current_version_id, _publish_at, true, _uid);
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid, public.cms_actor_email(_uid, _actor_email), 'page.schedule', 'pages', _page.id::text,
+    COALESCE(_audit, '{}'::jsonb) || jsonb_build_object('publish_at', _publish_at)
+  );
+
+  RETURN jsonb_build_object('scheduled', true, 'pageId', _page.id);
+END;
+$$;
+
+-- 6. Cancelling a schedule is not unpublishing a page ------------------------
+--
+-- The builder's Cancel button wrote `is_active = false` straight onto the row
+-- through PostgREST, with no check of what that row was doing. Offered — as it
+-- was — beside every active publication, including the one carrying the page
+-- right now, it meant:
+--
+--   * cancelling the only governing row took the page off the public website
+--     under a confirmation that said "Cancel this scheduled publication?";
+--   * cancelling a governing row that had replaced an earlier one brought that
+--     earlier version back, because the newest started row governs and the
+--     newest had just been retired.
+--
+-- Cancelling may therefore only touch a publication that has not started. The
+-- boundary is read from the database clock inside the transaction that does the
+-- write, so a row that starts between the screen rendering and the button being
+-- clicked is refused rather than raced: `now()` here is the transaction's own
+-- start time, and the row is locked before it is judged.
+--
+-- Taking a live page offline is a different act with a different confirmation,
+-- and it already has a function: `cms_set_page_status(_page_id, 'draft')`.
+CREATE OR REPLACE FUNCTION public.cms_cancel_page_publication(
+  _publication_id uuid,
+  _audit          jsonb DEFAULT '{}'::jsonb,
+  _actor_email    text  DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid  uuid := app.current_user_id();
+  _pub  public.page_publications;
+  _page public.pages;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT * INTO _pub FROM public.page_publications
+    WHERE id = _publication_id
+    FOR UPDATE;
+  IF _pub.id IS NULL THEN
+    RAISE EXCEPTION 'Publication not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages WHERE id = _pub.page_id FOR UPDATE;
+
+  -- Cancelling twice is the same wish twice, not an error worth failing a
+  -- screen over. Nothing is written and nothing is logged.
+  IF NOT _pub.is_active THEN
+    RETURN jsonb_build_object('cancelled', false, 'reason', 'already-cancelled',
+                              'pageId', _pub.page_id);
+  END IF;
+
+  IF _pub.publish_at <= now() THEN
+    RAISE EXCEPTION
+      'This publication has already started, so cancelling it would take "%" '
+      'off the public website — possibly putting an older version back. Use '
+      'Unpublish for that instead.', _page.key
+      USING ERRCODE = '22023';
+  END IF;
+
+  UPDATE public.page_publications
+     SET is_active = false
+   WHERE id = _publication_id;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid,
+    public.cms_actor_email(_uid, _actor_email),
+    'page.schedule.cancel',
+    'pages',
+    _pub.page_id::text,
+    COALESCE(_audit, '{}'::jsonb)
+      || jsonb_build_object('key', _page.key, 'publicationId', _publication_id,
+                            'publish_at', _pub.publish_at,
+                            'unpublish_at', _pub.unpublish_at)
+  );
+
+  RETURN jsonb_build_object('cancelled', true, 'pageId', _pub.page_id, 'key', _page.key);
+END;
+$$;
+
+-- 7. A scheduled version carries its reveals too -----------------------------
+--
+-- Scheduling was a save with `publish = false` followed by a bare insert into
+-- `page_publications`. Reveals were only ever read off a version being
+-- published *now*, so a countdown on a version scheduled for next week
+-- scheduled nothing: the source appeared on time and the page it promised to
+-- reveal stayed hidden for good.
+--
+-- The publication, its reveals and the audit trail are written here in one
+-- transaction, through the same reveal function every other path uses. A reveal
+-- that cannot be honoured takes the schedule down with it, and the editor is
+-- told before anything is committed.
+CREATE OR REPLACE FUNCTION public.cms_schedule_page_version(
+  _version_id   uuid,
+  _publish_at   timestamptz,
+  _unpublish_at timestamptz DEFAULT NULL,
+  _note         text        DEFAULT NULL,
+  -- `[{ "key": "...", "publishAt": "...", "description": "..." }]`, read off
+  -- the blocks of the version being scheduled.
+  _reveals      jsonb       DEFAULT '[]'::jsonb,
+  _audit        jsonb       DEFAULT '{}'::jsonb,
+  _actor_email  text        DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid            uuid := app.current_user_id();
+  _version        public.page_versions;
+  _page           public.pages;
+  _publication_id uuid;
+  _reveal         jsonb;
+  _scheduled      jsonb := '[]'::jsonb;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  -- The browser control offers a wall clock and a calendar; nothing stops a
+  -- caller sending something else, and a window that ends before it begins is
+  -- a page that is never public and a schedule nobody can read.
+  IF _publish_at IS NULL THEN
+    RAISE EXCEPTION 'A scheduled publication needs a time to start at.'
+      USING ERRCODE = '22023';
+  END IF;
+  IF _unpublish_at IS NOT NULL AND _unpublish_at <= _publish_at THEN
+    RAISE EXCEPTION
+      'A publication window has to end after it starts: % is not after %.',
+      _unpublish_at, _publish_at
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO _version FROM public.page_versions WHERE id = _version_id;
+  IF _version.id IS NULL THEN
+    RAISE EXCEPTION 'Version not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  -- The page is derived from the version and locked, so a schedule can only
+  -- ever be written against the page the version belongs to.
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _version.page_id AND deleted_at IS NULL
+    FOR UPDATE;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  INSERT INTO public.page_publications
+    (page_id, version_id, publish_at, unpublish_at, is_active, published_by, note)
+  VALUES
+    (_page.id, _version.id, _publish_at, _unpublish_at, true, _uid, _note)
+  RETURNING id INTO _publication_id;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid,
+    public.cms_actor_email(_uid, _actor_email),
+    'page.schedule',
+    'pages',
+    _page.id::text,
+    COALESCE(_audit, '{}'::jsonb)
+      || jsonb_build_object('key', _page.key, 'versionId', _version.id,
+                            'publicationId', _publication_id,
+                            'publish_at', _publish_at, 'unpublish_at', _unpublish_at)
+  );
+
+  FOR _reveal IN SELECT value FROM jsonb_array_elements(COALESCE(_reveals, '[]'::jsonb))
+  LOOP
+    _scheduled := _scheduled || jsonb_build_array(
+      jsonb_build_object('key', _reveal->>'key')
+        || public.cms_schedule_page_reveal(
+             _reveal->>'key',
+             (_reveal->>'publishAt')::timestamptz,
+             COALESCE(_audit, '{}'::jsonb)
+               || jsonb_build_object('description', _reveal->>'description'),
+             _actor_email,
+             _page.id,
+             _publish_at
+           )
+    );
+  END LOOP;
+
+  RETURN jsonb_build_object(
+    'publicationId', _publication_id,
+    'pageId',        _page.id,
+    'versionId',     _version.id,
+    'reveals',       _scheduled
+  );
+END;
+$$;
+
+-- 8. Who may call these ------------------------------------------------------
+--
+-- Same rule as the previous migration: taking the grant away from PUBLIC is
+-- plain SQL and runs anywhere, while `anon`, `authenticated` and
+-- `service_role` are PostgREST deployment conventions that a plain PostgreSQL
+-- server does not have. Naming a role that does not exist is an error, not a
+-- warning, so each of those statements runs only if the role is there.
+--
+-- A self-hosted installation grants EXECUTE to the role its application
+-- connects as, in a migration of its own:
+--
+--   GRANT EXECUTE ON FUNCTION
+--     public.cms_save_page_version(uuid, jsonb, text, boolean, text, jsonb, jsonb)
+--     TO cms_app;
+--
+-- `docs/PAGES.md` lists every statement.
+REVOKE ALL ON FUNCTION
+  public.cms_save_page_version(uuid, jsonb, text, boolean, text, jsonb, jsonb) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_soft_delete_page(uuid, jsonb, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_restore_page(uuid, jsonb, text) FROM PUBLIC;
+-- Re-stated for the widened signature: the previous migration's REVOKE named
+-- the four-argument function, which no longer exists.
+REVOKE ALL ON FUNCTION
+  public.cms_schedule_page_reveal(text, timestamptz, jsonb, text, uuid, timestamptz)
+  FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_cancel_page_publication(uuid, jsonb, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION
+  public.cms_schedule_page_version(uuid, timestamptz, timestamptz, text, jsonb, jsonb, text)
+  FROM PUBLIC;
+
+DO $$
+DECLARE
+  _signature text;
+  _role      text;
+  _writers   text[] := ARRAY[
+    'public.cms_save_page_version(uuid, jsonb, text, boolean, text, jsonb, jsonb)',
+    'public.cms_soft_delete_page(uuid, jsonb, text)',
+    'public.cms_restore_page(uuid, jsonb, text)',
+    'public.cms_schedule_page_reveal(text, timestamptz, jsonb, text, uuid, timestamptz)',
+    'public.cms_cancel_page_publication(uuid, jsonb, text)',
+    'public.cms_schedule_page_version(uuid, timestamptz, timestamptz, text, jsonb, jsonb, text)'
+  ];
+BEGIN
+  FOREACH _role IN ARRAY ARRAY['anon', 'authenticated', 'service_role'] LOOP
+    IF NOT EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = _role) THEN
+      CONTINUE;
+    END IF;
+    FOREACH _signature IN ARRAY _writers LOOP
+      EXECUTE format('REVOKE ALL ON FUNCTION %s FROM %I', _signature, _role);
+      IF _role <> 'anon' THEN
+        EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO %I', _signature, _role);
+      END IF;
+    END LOOP;
+  END LOOP;
+END
+$$;