@bygghammar/cms-platform 0.91.1 → 0.92.1

package/migrations/20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql

@@ -0,0 +1,3298 @@
+-- Contract v3: telling apart the five things "it is deployed" used to mean ----
+--
+-- Contract v2 made publication rows the only thing the public reader consults,
+-- and closed the writes that changed public visibility behind their back. It
+-- left a larger question unanswered: when a release moves a site from one
+-- contract version to the next, *what* has to be true before traffic may see
+-- it, and who is allowed to say so.
+--
+-- Until now one sentence — "the deployment succeeded" — stood for five
+-- separate facts that fail independently:
+--
+--   1. the migration ran;
+--   2. the schema therefore offers a capability;
+--   3. somebody scanned the existing publication rows and understood what the
+--      new reader would do differently to them;
+--   4. the decisions from that scan were applied;
+--   5. the routes were activated, the database was declared ready, and only
+--      then was traffic released.
+--
+-- Collapsing them is what turns a green deploy into a site that answers 200
+-- with last month's homepage. This migration gives each of the five its own
+-- record, and makes the later ones refuse to be written unless the earlier
+-- ones already are. Nothing here publishes, unpublishes or edits a page: it
+-- adds the ledger the release process reads and writes, and the two helpers
+-- everything else in contract v3 is built on.
+--
+-- Nothing in this file depends on the hosted PostgREST stack. The roles
+-- `anon`, `authenticated` and `service_role` are granted to only where they
+-- exist, exactly as the two v2 migrations do.
+
+-- 1. Which database is this? -------------------------------------------------
+--
+-- A review run, a route artifact and an activation record are all statements
+-- about one specific database. Carried to another — staging's scan applied to
+-- production, most obviously — they are worse than useless: they describe
+-- pages that may not exist and publications that certainly do not.
+--
+-- So every artifact carries the identity of the database it was made from, and
+-- every function that consumes one refuses a mismatch. The identity is a
+-- random uuid written once, on the installation itself: not a hostname, not a
+-- database name, not anything an operator might reasonably copy along with the
+-- data. Restoring a backup into a new database keeps the old identity, which
+-- is the correct answer — it is the same installation's content, and its
+-- artifacts still describe it.
+CREATE TABLE IF NOT EXISTS public.cms_installation (
+  -- One row, forever. The CHECK is what makes that true rather than hoped for.
+  singleton       boolean     NOT NULL PRIMARY KEY DEFAULT true CHECK (singleton),
+  installation_id uuid        NOT NULL DEFAULT gen_random_uuid(),
+  created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO public.cms_installation (singleton) VALUES (true)
+ON CONFLICT (singleton) DO NOTHING;
+
+CREATE OR REPLACE FUNCTION public.cms_installation_id()
+RETURNS uuid
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT installation_id FROM public.cms_installation WHERE singleton;
+$$;
+
+-- 2. What can this schema do? ------------------------------------------------
+--
+-- "The migration ran" and "the schema offers contract v3" are different
+-- claims, and only the second one is useful to a caller. A migration ledger
+-- records filenames; it cannot answer "may I call the v3 route functions yet"
+-- without the reader knowing which filename introduced them. This table
+-- answers that question directly, and is written by the migration that makes
+-- it true — so it cannot drift from the schema it describes.
+--
+-- It is deliberately not a readiness record. A schema can offer a capability
+-- while the data it operates on has not been reviewed yet; conflating the two
+-- is the third and fourth of the five facts collapsing into one again.
+CREATE TABLE IF NOT EXISTS public.cms_schema_capabilities (
+  capability  text        NOT NULL PRIMARY KEY,
+  version     integer     NOT NULL,
+  migration   text        NOT NULL,
+  recorded_at timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO public.cms_schema_capabilities (capability, version, migration)
+VALUES ('platform-contract', 3, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql')
+ON CONFLICT (capability) DO UPDATE
+   SET version     = EXCLUDED.version,
+       migration   = EXCLUDED.migration,
+       recorded_at = now()
+ WHERE public.cms_schema_capabilities.version < EXCLUDED.version;
+
+CREATE OR REPLACE FUNCTION public.cms_schema_capability(_capability text)
+RETURNS integer
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT version FROM public.cms_schema_capabilities WHERE capability = _capability;
+$$;
+
+-- 3. One canonical form, two implementations, one answer ---------------------
+--
+-- Contract v3 asks two independent programs to agree about identity: the
+-- command-line tool decides whether the plan it holds still describes the
+-- database, and the database decides whether the plan being applied is the one
+-- that was reviewed. If they hash the same content differently, every plan is
+-- either always stale or never stale, and the check is theatre.
+--
+-- `jsonb` cannot be used directly for this. Its text output orders object keys
+-- by length and then by bytes, which no JSON library reproduces, and its
+-- numbers keep whatever scale they were parsed with. So a canonical form is
+-- defined here and mirrored in TypeScript, with a parity test that hashes the
+-- same corpus on both sides and compares:
+--
+--   null, true, false      literally, lowercase
+--   strings                the JSON string literal, minimal escapes
+--   numbers                integers only, no sign on zero, no exponent
+--   arrays                 [a,b,c] — order preserved, no spaces
+--   objects                {"a":1,"b":2} — keys ascending by code point
+--
+-- The two restrictions are the point rather than a shortcut. Fractional
+-- numbers have no single spelling that a numeric and an IEEE double both
+-- produce — 0.1 is not 0.1 in either direction — so a digest containing one
+-- could never be proved equal. And keys are held to ASCII, because PostgreSQL
+-- sorts by byte and JavaScript sorts by UTF-16 code unit, and those two orders
+-- disagree above the basic plane. Every field name contract v3 digests is a
+-- literal in this repository; anything else is a bug, and is refused loudly
+-- here rather than hashed to something the other side cannot reproduce.
+CREATE OR REPLACE FUNCTION public.cms_canonical_json(_value jsonb)
+RETURNS text
+LANGUAGE plpgsql
+IMMUTABLE
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _kind text;
+  _num  numeric;
+  _body text;
+BEGIN
+  IF _value IS NULL THEN
+    RAISE EXCEPTION 'cms_canonical_json: SQL NULL is not a JSON value'
+      USING ERRCODE = '22023';
+  END IF;
+
+  _kind := jsonb_typeof(_value);
+
+  IF _kind = 'null' THEN
+    RETURN 'null';
+  END IF;
+
+  IF _kind = 'boolean' THEN
+    RETURN CASE WHEN _value = 'true'::jsonb THEN 'true' ELSE 'false' END;
+  END IF;
+
+  IF _kind = 'string' THEN
+    -- A scalar `jsonb` string renders as its JSON literal, escaping exactly
+    -- the characters JSON requires: quote, backslash, and the control range as
+    -- \b \f \n \r \t or \uXXXX. `JSON.stringify` makes the same choices, and
+    -- both leave every other code point as literal UTF-8. The one input that
+    -- could differ, U+0000, cannot reach here: `jsonb` refuses to store it.
+    RETURN _value::text;
+  END IF;
+
+  IF _kind = 'number' THEN
+    _num := _value::text::numeric;
+    IF _num <> trunc(_num) THEN
+      RAISE EXCEPTION
+        'cms_canonical_json: % is fractional, and digest inputs may only '
+        'contain whole numbers.', _value::text
+        USING ERRCODE = '22023';
+    END IF;
+    -- Beyond this range a JavaScript number stops being able to name the
+    -- integer it holds, so the two sides could agree on the text and disagree
+    -- about the value.
+    IF _num > 9007199254740991::numeric OR _num < -9007199254740991::numeric THEN
+      RAISE EXCEPTION
+        'cms_canonical_json: % is outside the range both sides can represent '
+        'exactly (±9007199254740991).', _value::text
+        USING ERRCODE = '22023';
+    END IF;
+    RETURN trunc(_num)::bigint::text;
+  END IF;
+
+  IF _kind = 'array' THEN
+    SELECT coalesce(string_agg(public.cms_canonical_json(e.value), ',' ORDER BY e.ordinality), '')
+      INTO _body
+      FROM jsonb_array_elements(_value) WITH ORDINALITY AS e(value, ordinality);
+    RETURN '[' || _body || ']';
+  END IF;
+
+  PERFORM 1 FROM jsonb_object_keys(_value) AS k
+    WHERE k !~ '^[A-Za-z0-9_.:-]+$'
+    LIMIT 1;
+  IF FOUND THEN
+    RAISE EXCEPTION
+      'cms_canonical_json: object keys in a digest input must be ASCII letters, '
+      'digits, underscore, dot, colon or hyphen.'
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- `COLLATE "C"` is byte order, which for the ASCII keys allowed above is
+  -- code-point order — the order the TypeScript side gets from comparing
+  -- strings with `<`.
+  SELECT coalesce(
+           string_agg(
+             to_jsonb(k)::text || ':' || public.cms_canonical_json(_value -> k),
+             ',' ORDER BY k COLLATE "C"),
+           '')
+    INTO _body
+    FROM jsonb_object_keys(_value) AS k;
+  RETURN '{' || _body || '}';
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.cms_digest(_value jsonb)
+RETURNS text
+LANGUAGE sql
+IMMUTABLE
+SET search_path = public, pg_temp
+AS $$
+  SELECT encode(sha256(convert_to(public.cms_canonical_json(_value), 'UTF8')), 'hex');
+$$;
+
+
+-- 4. The publication review model ---------------------------------------------
+--
+-- Fact 3 of the five is "somebody scanned the existing publication rows and
+-- understood what the new reader would do differently to them". The thing that
+-- makes it a *fact* rather than a claim is that the scan, its findings and the
+-- decisions taken on them are three separate records with different lifetimes,
+-- and none of them can be quietly rewritten afterwards.
+--
+-- The disagreement being reviewed is not between v2 and v3. It is between the
+-- reader that shipped in 0.90.0-m7.12 and the reader that shipped in 0.91.1:
+--
+--   the 0.90 reader took the newest active publication row whose window was
+--   open — ORDER BY publish_at DESC LIMIT 1 — and, when there was none,
+--   fell back to COALESCE(..., pages.current_version_id);
+--
+--   the 0.91 reader added a published_at DESC tie-break and dropped the
+--   fallback entirely.
+--
+-- The dropped fallback is the whole risk. A page that 0.90 served from
+-- current_version_id, with no publication row at all, is a page 0.91 serves
+-- nothing for. It goes dark on upgrade, silently, and the site owner finds out
+-- from a visitor. Every page in this database is therefore looked at once,
+-- classified, and — where the two readers disagree — resolved by a person
+-- before 0.92.0 is allowed to serve traffic.
+--
+-- Three tables, three lifetimes:
+--
+--   runs        immutable except for a forward-only state machine
+--   items       write-once; one per live page per run
+--   decisions   append-only; at most one per item, forever
+--
+-- The alternative — mutable resolved_* columns on the items themselves — was
+-- rejected for two reasons. A merge restore could then write over a decision
+-- somebody had already taken, and the current state of an item would depend on
+-- an update ordering that nothing in the database records.
+
+CREATE TABLE IF NOT EXISTS public.cms_publication_review_runs (
+  id                  uuid        NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- The nonce is what ties this row to one approval by one person at one
+  -- moment. It arrives from outside the database and is never reused.
+  approval_nonce      uuid        NOT NULL UNIQUE,
+
+  -- Where the scan happened. All of it is recorded so that a run found in a
+  -- backup can be recognised as belonging to somewhere else, rather than
+  -- mistaken for this installation's own history.
+  site_key            text        NOT NULL,
+  environment         text        NOT NULL,
+
+  -- The database, not the cluster: current_database() and its oid, which is
+  -- the identity the migration checks its approval against.
+  --
+  -- An approval carries two identities and they answer different questions.
+  -- 'database_identity' names the cluster -- one number for every database in
+  -- it -- and is the most the deployment tooling can check from outside,
+  -- before it has a connection to ask anything sharper with.
+  -- 'review_database_identity' names the database, which is the question worth
+  -- asking once you are inside one: two databases in a cluster share a cluster
+  -- identifier and are not the same thing to review, and a staging review must
+  -- not be able to approve a production upgrade.
+  --
+  -- Only the sharper one is kept. The cluster identifier has done its work by
+  -- the time this row is written, and a second copy of a settled answer is
+  -- something to drift rather than something to check against. The column is
+  -- named for the setting it comes from so that a person reading this table in
+  -- a backup, months later, does not have to guess which of the two it holds.
+  review_database_identity text   NOT NULL,
+
+  release_sha         text        NOT NULL,
+  package_version     text        NOT NULL,
+  migration_name      text        NOT NULL,
+  migration_digest    text        NOT NULL,
+
+  -- What the scan looked at, and what it produced. The fingerprint is
+  -- recomputed from the live rows before anything is applied; if the pages
+  -- moved between the scan and the apply, the numbers stop matching and the
+  -- migration refuses rather than applying decisions to data nobody reviewed.
+  input_fingerprint   text        NOT NULL,
+  manifest_digest     text        NOT NULL,
+  evaluated_at        timestamptz NOT NULL,
+
+  -- expected_page_count is settled at scan time; scanned_page_count is written
+  -- when the run finishes. A run may only be relied upon when the two agree —
+  -- see cms_publication_review_is_complete below.
+  expected_page_count integer     NOT NULL,
+  scanned_page_count  integer,
+  counts              jsonb,
+
+  state               text        NOT NULL
+                                  CHECK (state IN ('scanning', 'applying', 'applied', 'aborted')),
+  scan_completed_at   timestamptz,
+
+  -- What caused this scan to happen. 'migration' is the upgrade itself, 'cli'
+  -- is somebody running cms-review, 'reconciliation' is a restore that brought
+  -- in content the review history says nothing about.
+  --
+  -- Worth recording rather than inferring, because the three mean different
+  -- things about the *approval*. A migration run carries a person's approval
+  -- of a specific plan. A reconciliation run carries no approval at all: it is
+  -- the database noticing that content arrived unclassified and classifying it
+  -- with the standing default. Reading "applied run, therefore reviewed" off a
+  -- reconciliation would be reading somebody's consent into a machine's
+  -- housekeeping.
+  source              text        NOT NULL DEFAULT 'migration'
+                                  CHECK (source IN ('migration', 'cli', 'reconciliation')),
+
+  -- Three people, or the same person three times, but always recorded
+  -- separately: who classified, who approved, who applied. The email is kept
+  -- alongside the id so the record still reads correctly after the account is
+  -- gone. Classification and approval both precede the insert, so both are
+  -- mandatory; application happens afterwards, so it is not.
+  classified_by       uuid,
+  classified_by_email text        NOT NULL,
+  classified_at       timestamptz NOT NULL,
+  approved_by         uuid,
+  approved_by_email   text        NOT NULL,
+  approved_at         timestamptz NOT NULL,
+  applied_by          uuid,
+  applied_by_email    text,
+  applied_at          timestamptz,
+
+  created_at          timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT cms_publication_review_runs_counts_object
+    CHECK (counts IS NULL OR jsonb_typeof(counts) = 'object'),
+  CONSTRAINT cms_publication_review_runs_page_counts_sane
+    CHECK (expected_page_count >= 0 AND (scanned_page_count IS NULL OR scanned_page_count >= 0))
+);
+
+-- "Which run governs right now" has exactly one answer: the applied run with
+-- the greatest applied_at. This index is what makes that lookup cheap, and
+-- restricting it to applied runs keeps abandoned scans out of the way.
+CREATE INDEX IF NOT EXISTS cms_publication_review_runs_current_idx
+    ON public.cms_publication_review_runs (applied_at DESC)
+ WHERE state = 'applied';
+
+CREATE TABLE IF NOT EXISTS public.cms_publication_review_items (
+  id                      uuid    NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
+  run_id                  uuid    NOT NULL
+                                  REFERENCES public.cms_publication_review_runs (id) ON DELETE RESTRICT,
+
+  -- ON DELETE RESTRICT, not CASCADE, and deliberately so. A cascade would
+  -- erase the review history for a page the moment somebody hard-deleted it,
+  -- which is precisely when that history is worth having. It also stops a
+  -- forward-ordered restore from appearing to succeed while dropping the
+  -- evidence for what it restored.
+  page_id                 uuid    NOT NULL
+                                  REFERENCES public.pages (id) ON DELETE RESTRICT,
+  page_key                text    NOT NULL,
+
+  classification          text    NOT NULL
+                                  CHECK (classification IN (
+                                    'already_safe', 'preserved', 'hidden_by_expiry',
+                                    'hidden_by_design', 'disagreement', 'needs_review',
+                                    'structurally_invalid')),
+  requires_decision       boolean NOT NULL,
+
+  -- What each reader would serve for this page. The two are compared, not
+  -- interpreted: equal means nothing changes, different means somebody looks.
+  legacy_version_id       uuid,
+  v2_version_id           uuid,
+
+  -- True when the 0.90 answer came from a publication row, false when it came
+  -- from the current_version_id fallback. This single boolean is the
+  -- difference between "this page was published and stays published" and
+  -- "this page was never published and is about to disappear".
+  legacy_from_publication boolean NOT NULL,
+
+  governing_publication_id uuid,
+  scheduled_version_id    uuid,
+  scheduled_publish_at    timestamptz,
+
+  -- Set when the historically served version was not deterministic: two active
+  -- rows sharing the maximum publish_at, or a tie in the (publish_at,
+  -- published_at) pair among the candidates. Such a page is never preserved
+  -- automatically, whatever else is true of it.
+  ambiguous_order         boolean NOT NULL,
+
+  reason                  text,
+
+  -- Everything the classification was computed from, canonicalised. The digest
+  -- is generated rather than supplied, so it cannot disagree with the inputs it
+  -- claims to cover: a decision quoting a stale digest is refused by
+  -- construction rather than by a check somebody remembered to write.
+  inputs                  jsonb   NOT NULL,
+  inputs_digest           text    NOT NULL
+                                  GENERATED ALWAYS AS (public.cms_digest(inputs)) STORED,
+
+  -- One item per page per run. Note what is *not* here: any uniqueness on
+  -- page_id alone. A later scan produces a second item for the same page, and
+  -- that is a new row rather than a conflict, which is what keeps old runs
+  -- readable after a new one lands.
+  CONSTRAINT cms_publication_review_items_run_page_key UNIQUE (run_id, page_id),
+
+  -- Redundant on its own — id is already the primary key — but a foreign key
+  -- has to name a unique constraint, and the decisions table below needs to
+  -- point at all three columns at once. See the note there.
+  CONSTRAINT cms_publication_review_items_identity_key UNIQUE (id, run_id, page_id),
+
+  CONSTRAINT cms_publication_review_items_inputs_object
+    CHECK (jsonb_typeof(inputs) = 'object')
+);
+
+CREATE INDEX IF NOT EXISTS cms_publication_review_items_run_idx
+    ON public.cms_publication_review_items (run_id);
+CREATE INDEX IF NOT EXISTS cms_publication_review_items_page_idx
+    ON public.cms_publication_review_items (page_id);
+
+-- The pending queue is the interesting read: items in a run that need somebody
+-- and have not got them yet.
+CREATE INDEX IF NOT EXISTS cms_publication_review_items_pending_idx
+    ON public.cms_publication_review_items (run_id, page_key)
+ WHERE requires_decision;
+
+CREATE TABLE IF NOT EXISTS public.cms_publication_review_decisions (
+  id                    uuid        NOT NULL PRIMARY KEY DEFAULT gen_random_uuid(),
+
+  -- UNIQUE, so an item is resolved at most once and for good. A second attempt
+  -- reports that it was already resolved rather than overwriting; an operator
+  -- who changes their mind runs a new scan, which produces new items to decide
+  -- on. This is also what makes a backup merge safe: an archived decision
+  -- either inserts, because the item had none, or collides visibly. There is no
+  -- path by which it silently supersedes a local one.
+  item_id               uuid        NOT NULL UNIQUE
+                                    REFERENCES public.cms_publication_review_items (id) ON DELETE RESTRICT,
+
+  run_id                uuid        NOT NULL,
+  page_id               uuid        NOT NULL,
+
+  decision              text        NOT NULL
+                                    CHECK (decision IN (
+                                      'publish-legacy-version', 'leave-hidden', 'no-change')),
+
+  -- The digest the decider was looking at. If the item's inputs have moved
+  -- since, this no longer matches and the resolve refuses — a decision is
+  -- about a specific reading of a specific page, not about a page in general.
+  expected_inputs_digest text       NOT NULL,
+
+  source                text        NOT NULL
+                                    CHECK (source IN ('migration', 'cli', 'reconciliation')),
+
+  -- The pointer is released when the account is deleted; the email stays, so
+  -- the history still says who decided. See the update trigger below, which
+  -- makes room for exactly that one write and no other.
+  resolved_by           uuid        REFERENCES public.app_users (id) ON DELETE SET NULL,
+  resolved_by_email     text        NOT NULL,
+
+  decided_at            timestamptz NOT NULL DEFAULT now(),
+  note                  text,
+
+  -- The decision's own run_id and page_id must be the ones on the item it
+  -- names, so a row cannot be filed against one page while claiming to be
+  -- about another. All three columns are in the key on purpose: a foreign key
+  -- on (run_id, page_id) alone would only prove that *some* item has that
+  -- pair, which is satisfied by a second run's item for the same page and so
+  -- proves nothing about this decision's own item.
+  CONSTRAINT cms_publication_review_decisions_item_fk
+    FOREIGN KEY (item_id, run_id, page_id)
+    REFERENCES public.cms_publication_review_items (id, run_id, page_id) ON DELETE RESTRICT
+);
+
+CREATE INDEX IF NOT EXISTS cms_publication_review_decisions_run_idx
+    ON public.cms_publication_review_decisions (run_id, page_id);
+
+-- 5. Making the lifetimes structural, not conventional -----------------------
+--
+-- Everything above describes what the three tables are *for*. What follows is
+-- what makes those descriptions true even when the caller is a restore script,
+-- a well-meaning operator with psql open, or a future version of this codebase
+-- that has forgotten the rule. Comments do not stop an UPDATE; triggers do.
+
+-- Runs move forward or they abort. Nothing else.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_runs_guard()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  -- The only columns a legitimate transition writes. Everything outside this
+  -- list is identity, provenance or an agreed count, and is frozen at insert.
+  _mutable constant text[] := ARRAY[
+    'state', 'scanned_page_count', 'counts', 'scan_completed_at',
+    'applied_by', 'applied_by_email', 'applied_at'
+  ];
+BEGIN
+  IF (to_jsonb(NEW) - _mutable) IS DISTINCT FROM (to_jsonb(OLD) - _mutable) THEN
+    RAISE EXCEPTION
+      'a review run records what was scanned and approved; that cannot be edited afterwards'
+      USING ERRCODE = '42501',
+            DETAIL  = format('run %s: an update changed a column outside the state machine', OLD.id),
+            HINT    = 'run a new scan instead of amending this one';
+  END IF;
+
+  IF NEW.state = OLD.state THEN
+    RAISE EXCEPTION 'a review run update must move its state forward'
+      USING ERRCODE = '42501',
+            DETAIL  = format('run %s is already %L', OLD.id, OLD.state);
+  END IF;
+
+  IF NEW.state = 'aborted' THEN
+    IF OLD.state = 'aborted' THEN
+      RAISE EXCEPTION 'review run %s is already aborted', OLD.id USING ERRCODE = '42501';
+    END IF;
+    RETURN NEW;
+  END IF;
+
+  IF NOT ((OLD.state, NEW.state) IN (('scanning', 'applying'), ('applying', 'applied'))) THEN
+    RAISE EXCEPTION 'a review run cannot go from % to %', OLD.state, NEW.state
+      USING ERRCODE = '42501',
+            DETAIL  = 'the permitted moves are scanning to applying, applying to applied, and anything to aborted',
+            HINT    = 'a run that went wrong is aborted, not rewound';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION public.cms_publication_review_runs_no_delete()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  RAISE EXCEPTION 'review runs are the record that a scan happened; they are not deleted'
+    USING ERRCODE = '42501',
+          DETAIL  = format('run %s', OLD.id),
+          HINT    = 'a run that should not be relied on is aborted, which leaves the evidence in place';
+END;
+$$;
+
+-- Items are written once, by the scan that found them.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_items_write_once()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  RAISE EXCEPTION 'review items are what the scan saw; they are append-only'
+    USING ERRCODE = '42501',
+          DETAIL  = format('item %s (%s) may not be %s',
+                           OLD.id, OLD.page_key,
+                           CASE TG_OP WHEN 'UPDATE' THEN 'updated' ELSE 'deleted' END),
+          HINT    = 'record a decision against the item, or run a new scan';
+END;
+$$;
+
+-- Decisions are append-only, with one deliberate exception: when an account is
+-- deleted, the foreign key releases the pointer to it. That release is itself
+-- an UPDATE, so an unconditional guard here would turn ON DELETE SET NULL into
+-- a refusal to delete the account at all — with an error message about review
+-- decisions, which is not a sentence anybody deleting a user should have to
+-- read. The guard therefore permits exactly one shape of update: resolved_by
+-- going from something to nothing, with every other column identical. The
+-- email stays, so the record still says who decided.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_decisions_append_only()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  IF TG_OP = 'UPDATE'
+     AND OLD.resolved_by IS NOT NULL
+     AND NEW.resolved_by IS NULL
+     AND (to_jsonb(NEW) - 'resolved_by') = (to_jsonb(OLD) - 'resolved_by')
+  THEN
+    RETURN NEW;
+  END IF;
+
+  RAISE EXCEPTION 'a review decision is a record of what somebody decided; it is append-only'
+    USING ERRCODE = '42501',
+          DETAIL  = format('decision %s may not be %s', OLD.id,
+                           CASE TG_OP WHEN 'UPDATE' THEN 'updated' ELSE 'deleted' END),
+          HINT    = 'to decide differently, run a new scan and resolve the new item';
+END;
+$$;
+
+-- Row triggers never see a TRUNCATE, so append-only would be a rule you could
+-- step around with one statement. These close that door. Note that TRUNCATE on
+-- the items table alone is already refused by the decisions foreign key before
+-- any trigger runs — it is the CASCADE form, and truncating the three tables
+-- together, that these actually catch.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_no_truncate()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  RAISE EXCEPTION 'the publication review record is append-only; % cannot be truncated', TG_TABLE_NAME
+    USING ERRCODE = '42501',
+          HINT    = 'a run that should not be relied on is aborted, which leaves the evidence in place';
+END;
+$$;
+
+DROP TRIGGER IF EXISTS cms_publication_review_runs_guard
+  ON public.cms_publication_review_runs;
+CREATE TRIGGER cms_publication_review_runs_guard
+  BEFORE UPDATE ON public.cms_publication_review_runs
+  FOR EACH ROW EXECUTE FUNCTION public.cms_publication_review_runs_guard();
+
+DROP TRIGGER IF EXISTS cms_publication_review_runs_no_delete
+  ON public.cms_publication_review_runs;
+CREATE TRIGGER cms_publication_review_runs_no_delete
+  BEFORE DELETE ON public.cms_publication_review_runs
+  FOR EACH ROW EXECUTE FUNCTION public.cms_publication_review_runs_no_delete();
+
+DROP TRIGGER IF EXISTS cms_publication_review_items_write_once
+  ON public.cms_publication_review_items;
+CREATE TRIGGER cms_publication_review_items_write_once
+  BEFORE UPDATE OR DELETE ON public.cms_publication_review_items
+  FOR EACH ROW EXECUTE FUNCTION public.cms_publication_review_items_write_once();
+
+DROP TRIGGER IF EXISTS cms_publication_review_decisions_append_only
+  ON public.cms_publication_review_decisions;
+CREATE TRIGGER cms_publication_review_decisions_append_only
+  BEFORE UPDATE OR DELETE ON public.cms_publication_review_decisions
+  FOR EACH ROW EXECUTE FUNCTION public.cms_publication_review_decisions_append_only();
+
+DROP TRIGGER IF EXISTS cms_publication_review_runs_no_truncate
+  ON public.cms_publication_review_runs;
+CREATE TRIGGER cms_publication_review_runs_no_truncate
+  BEFORE TRUNCATE ON public.cms_publication_review_runs
+  FOR EACH STATEMENT EXECUTE FUNCTION public.cms_publication_review_no_truncate();
+
+DROP TRIGGER IF EXISTS cms_publication_review_items_no_truncate
+  ON public.cms_publication_review_items;
+CREATE TRIGGER cms_publication_review_items_no_truncate
+  BEFORE TRUNCATE ON public.cms_publication_review_items
+  FOR EACH STATEMENT EXECUTE FUNCTION public.cms_publication_review_no_truncate();
+
+DROP TRIGGER IF EXISTS cms_publication_review_decisions_no_truncate
+  ON public.cms_publication_review_decisions;
+CREATE TRIGGER cms_publication_review_decisions_no_truncate
+  BEFORE TRUNCATE ON public.cms_publication_review_decisions
+  FOR EACH STATEMENT EXECUTE FUNCTION public.cms_publication_review_no_truncate();
+
+-- 6. Three authorities the rest of contract v3 is built on --------------------
+--
+-- The review model above answers "may this upgrade proceed at all". The tables
+-- here answer three questions the upgraded site asks on ordinary days, and
+-- each of them is an authority rather than a cache. That is the whole reason
+-- they are tables: every one of these three failures is a second opinion,
+-- computed somewhere in application code, disagreeing with the first.
+--
+-- Nothing populates them here. Section 10 writes the first two and section 9
+-- the third, and until something calls those, a database that has the tables
+-- and no rows has claimed no routes and served no duplicate twice — which is
+-- the correct description of one that has never done either.
+
+-- Route authority.
+--
+-- Read-then-write validation cannot be made correct by ordering: two
+-- concurrent saves both read a path as free, both commit, and the site now has
+-- two pages at one URL. The authority has to be a constraint, so it is the
+-- primary key below. cms_route_claim_apply recomputes a page's entire claim
+-- set and swaps it in one transaction, taking an advisory lock per origin so
+-- that writers queue in a predictable order — but the advisory lock is only a
+-- fairness device. A writer that forgets it still cannot double-claim, because
+-- the key is what refuses, not the queue.
+--
+-- The origin keeps its port. Dropping every port was the earlier mistake:
+-- https://example.com and https://example.com:8443 are different sites and
+-- have every right to claim the same path. Only :80 on http and :443 on https
+-- come off, and they come off before the row arrives here.
+--
+-- Reserved paths — the API prefix, the backoffice, sitemap.xml, robots.txt,
+-- the asset roots — are materialised as rows of their own, so a page that
+-- tries to sit on one collides through the same primary key as a page
+-- colliding with another page. One mechanism, one error, and no second list of
+-- forbidden strings to keep in step with the first.
+CREATE TABLE IF NOT EXISTS public.cms_route_claims (
+  -- Scheme and host lowercased, port preserved: the canonical origin, not the
+  -- Host header some particular request happened to arrive with.
+  origin       text NOT NULL,
+
+  -- The normalized served path, always rooted. Case is deliberately not forced
+  -- here. Trailing-slash and case policy live in the registry snapshot below
+  -- because they are host decisions, and a claim is normalized under whichever
+  -- policy was current when it was written — which is what registry_sha
+  -- records.
+  path         text NOT NULL,
+
+  kind         text NOT NULL CHECK (kind IN ('page', 'redirect', 'reserved')),
+
+  -- ON DELETE CASCADE, unlike the review tables above, and for the opposite
+  -- reason. A review item is history and outlives its page; a claim is a
+  -- statement about what the site serves right now, and a deleted page serves
+  -- nothing. Leaving the claim behind would keep a URL reserved against a page
+  -- that no longer exists.
+  page_id      uuid REFERENCES public.pages (id) ON DELETE CASCADE,
+  locale       text,
+
+  -- Which registry snapshot this claim was normalized under, so a claim
+  -- written against yesterday's route map is recognisable as such instead of
+  -- being trusted on sight.
+  registry_sha text,
+
+  PRIMARY KEY (origin, path),
+
+  -- The key is only an authority if both writers spell the same URL the same
+  -- way, so the two normalization steps that are not policy-dependent are
+  -- enforced here rather than assumed of every caller.
+  CONSTRAINT cms_route_claims_origin_canonical
+    CHECK (origin = lower(origin) AND origin NOT LIKE '%/'),
+  CONSTRAINT cms_route_claims_path_rooted
+    CHECK (path LIKE '/%'),
+
+  -- A page claim with no page is unenforceable, and a reserved claim with one
+  -- would mean a page had been handed a path the host reserves. Redirects are
+  -- left open on purpose: a redirect source may or may not belong to a page.
+  CONSTRAINT cms_route_claims_page_id_matches_kind
+    CHECK ((kind = 'page'     AND page_id IS NOT NULL)
+        OR (kind = 'reserved' AND page_id IS NULL)
+        OR  kind = 'redirect')
+);
+
+-- "Every claim this page owns" is the read cms_route_claim_apply does before
+-- each swap, and the read the cascade above does on every page delete. Without
+-- this index both are a sequential scan of every route on the site.
+CREATE INDEX IF NOT EXISTS cms_route_claims_page_idx
+    ON public.cms_route_claims (page_id)
+ WHERE page_id IS NOT NULL;
+
+-- What the host knows and the database cannot infer: which paths are reserved,
+-- which locales exist, which domain serves which locale, whether a trailing
+-- slash is kept, whether case is folded. The package cannot read the host's
+-- route table, so the host writes it down here once per release and everything
+-- that normalizes a URL afterwards reads that one copy.
+--
+-- One row, enforced by the check, because "the current route map" is not a
+-- collection. release_sha is what makes a stale one fail closed:
+-- cms_route_claim_apply refuses when the sha the caller expected is not the
+-- sha stored here, rather than validating tomorrow's claim against yesterday's
+-- map and finding no collision.
+CREATE TABLE IF NOT EXISTS public.cms_route_registry (
+  id          int         NOT NULL PRIMARY KEY CHECK (id = 1),
+  release_sha text        NOT NULL,
+  snapshot    jsonb       NOT NULL,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT cms_route_registry_snapshot_object
+    CHECK (jsonb_typeof(snapshot) = 'object')
+);
+
+-- Duplication is idempotent by key rather than by hope. A committed request
+-- whose response never arrived is an ordinary event on a slow link, and the
+-- editor retries. Without this table the retry makes a second copy; with the
+-- route authority above, that copy then tries to claim the same routes and
+-- collides with the original, so a dropped packet turns into a routing failure
+-- somebody has to untangle by hand. With it, the retry returns the first
+-- result and says so.
+--
+-- No foreign keys, deliberately. The row records that a request was served,
+-- which stays true after either page is deleted, and a cascade would erase the
+-- evidence that a key had been used — letting a late retry duplicate after
+-- all, which is precisely the case the table exists for.
+CREATE TABLE IF NOT EXISTS public.cms_page_duplicate_operations (
+  idempotency_key uuid        NOT NULL PRIMARY KEY,
+  source_page_id  uuid        NOT NULL,
+  created_page_id uuid        NOT NULL,
+  created_at      timestamptz NOT NULL DEFAULT now()
+);
+
+-- The lock helper, in `app` because nothing outside the database may call it.
+--
+-- The rejected alternative was a publicly executable _locks_held flag that
+-- callers could pass to tell an inner function to skip its locking. That is a
+-- caller-controlled bypass of the only thing standing between two concurrent
+-- mutations and a deadlock, and it is not in this design. No flag is needed:
+-- PostgreSQL row locks are reentrant within a transaction, so an inner
+-- function re-locking a row its caller already holds is a no-op. Natural
+-- reentrancy replaces the flag entirely.
+--
+-- The order is the uuid's own byte order — total, deterministic, and identical
+-- in every session. That is the entire deadlock argument: a bulk resolution
+-- over a batch and a single-page mutation take the rows they share in the same
+-- order, so one waits rather than both dying. The tier order around it is
+-- invariant too — pages, then publications, then review — and lives in the
+-- callers, because this function knows only about pages.
+--
+-- A null array, or an array with a null in it, is refused rather than quietly
+-- locking nothing: `id = ANY (ARRAY[NULL])` matches no rows, so a caller that
+-- assembled its target set wrongly would sail past this believing it held a
+-- lock. Ids that do not exist are not refused — the caller revalidates under
+-- the lock, and "that page is gone" is its answer to give, not this
+-- function's.
+CREATE OR REPLACE FUNCTION app.cms_lock_pages(_page_ids uuid[])
+RETURNS void
+LANGUAGE plpgsql
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  IF _page_ids IS NULL OR array_position(_page_ids, NULL) IS NOT NULL THEN
+    RAISE EXCEPTION 'app.cms_lock_pages requires an array of page ids with no nulls'
+      USING ERRCODE = '22004';
+  END IF;
+
+  PERFORM id
+     FROM public.pages
+    WHERE id = ANY (_page_ids)
+    ORDER BY id
+      FOR UPDATE;
+END
+$$;
+
+-- 7. Reading the ledger, and who may read it ---------------------------------
+--
+-- Two questions get an answer in the database rather than in each caller,
+-- because getting either of them subtly wrong is how "the scan is done" starts
+-- meaning something different in two places.
+
+-- A run is only evidence when it finished. This matters more than it looks:
+-- under a run that satisfies this predicate, the *absence* of an item for a
+-- live page positively means the page was scanned and needed no record. Under
+-- any other run, absence means nothing at all, and a caller that cannot tell
+-- the two apart will happily report an interrupted scan as a clean bill of
+-- health.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_is_complete(_run_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = public, pg_temp
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+      FROM public.cms_publication_review_runs
+     WHERE id = _run_id
+       AND state = 'applied'
+       AND scan_completed_at IS NOT NULL
+       AND scanned_page_count = expected_page_count
+  );
+$$;
+
+-- "Which review governs this installation right now" — the applied run with
+-- the greatest applied_at, and no other. Pending work is then that run's items
+-- with requires_decision and no decision row, which needs no adjudication
+-- because an item has at most one decision by constraint.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_current_run()
+RETURNS uuid
+LANGUAGE sql
+STABLE
+SET search_path = public, pg_temp
+AS $$
+  SELECT id
+    FROM public.cms_publication_review_runs
+   WHERE state = 'applied'
+   ORDER BY applied_at DESC, id
+   LIMIT 1;
+$$;
+
+-- The scan, and the fingerprint it is taken against, as callable functions ---
+--
+-- Both were written inline in the DO block below, which was correct for as
+-- long as the only thing that ever scanned this database was the upgrade
+-- itself. That stopped being true the moment a schema-2 backup could be
+-- restored into a v3 database: the archive carries content but no review
+-- history, so the pages that arrive have no classification and nothing is left
+-- to give them one. Reconciliation needs the same scan, and a second copy of a
+-- 130-line classification would be two opinions rather than one answer.
+--
+-- So they are functions, and the DO block calls them. There is exactly one
+-- classification in this schema, and exactly one fingerprint expression.
+
+-- Everything either reader looks at, in one deterministic string.
+--
+-- Soft-deleted pages and inactive publication rows are in it deliberately:
+-- deleting a page and deactivating a publication both change what the site
+-- serves, and both would slip through a fingerprint that only looked at what
+-- is live. scripts/review-fingerprint.sql is this same expression written for
+-- a reviewer standing at a database that has no cms_digest() yet; the two are
+-- held together by ops/migration-smoke.mjs.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_fingerprint()
+RETURNS text
+LANGUAGE sql
+STABLE
+SET search_path = public, pg_temp
+AS $fingerprint$
+  SELECT public.cms_digest(jsonb_build_object(
+           'pageCount', count(*),
+           'pages', coalesce(jsonb_agg(entry ORDER BY page_id), '[]'::jsonb)
+         ))
+    FROM (
+      SELECT pg.id AS page_id,
+             jsonb_build_object(
+               'id', pg.id::text,
+               'key', pg.key,
+               'status', pg.status,
+               'currentVersionId', pg.current_version_id::text,
+               'deletedAt', to_char(pg.deleted_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+               'publications', (
+                 SELECT coalesce(jsonb_agg(jsonb_build_object(
+                          'id', pp.id::text,
+                          'versionId', pp.version_id::text,
+                          'publishAt', to_char(pp.publish_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+                          'unpublishAt', to_char(pp.unpublish_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+                          'publishedAt', to_char(pp.published_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+                          'active', pp.is_active
+                        ) ORDER BY pp.id), '[]'::jsonb)
+                   FROM public.page_publications pp
+                  WHERE pp.page_id = pg.id
+               )
+             ) AS entry
+        FROM public.pages pg
+    ) snapshot;
+$fingerprint$;
+
+-- One row per live page: what each reader would serve for it, and the shape of
+-- their disagreement.
+--
+-- This is the same calculation as src/platform/publication-review.ts, written
+-- a second time because a migration cannot call TypeScript;
+-- tests/fixtures/publication-review-corpus.json is seeded into a database and
+-- run through both, so the two stay one answer rather than two opinions.
+-- `_at` is the moment the scan is taken as at, and it is a parameter rather
+-- than a `now()` inside the body for one reason: a scan compares publication
+-- windows against a clock, and every row in one scan must be compared against
+-- the *same* reading of it. A body calling now() would be stable within a
+-- statement and so would happen to be correct today, but it would also let a
+-- caller with its own idea of "now" -- the migration, which checks whether
+-- windows crossed between the approval and this moment -- silently disagree
+-- with the scan it is checking.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_scan(_at timestamptz DEFAULT now())
+RETURNS TABLE (
+  page_id                  uuid,
+  page_key                 text,
+  classification           text,
+  requires_decision        boolean,
+  legacy_version_id        uuid,
+  v2_version_id            uuid,
+  legacy_from_publication  boolean,
+  governing_publication_id uuid,
+  scheduled_version_id     uuid,
+  scheduled_publish_at     timestamptz,
+  ambiguous_order          boolean,
+  reason                   text,
+  inputs                   jsonb
+)
+LANGUAGE sql
+STABLE
+SET search_path = public, pg_temp
+AS $scan$
+  WITH live AS (
+    SELECT p.id AS page_id, p.key AS page_key, p.status, p.current_version_id
+      FROM public.pages p
+     WHERE p.deleted_at IS NULL
+  ),
+  act AS (
+    SELECT pp.id, pp.page_id, pp.version_id, pp.publish_at, pp.unpublish_at, pp.published_at
+      FROM public.page_publications pp
+      JOIN live l ON l.page_id = pp.page_id
+     WHERE pp.is_active
+  ),
+  started AS (SELECT * FROM act WHERE publish_at <= _at),
+  opened  AS (SELECT * FROM started WHERE unpublish_at IS NULL OR unpublish_at > _at),
+  -- 0.90.0-m7.12: closed rows are gone before the newest is chosen.
+  legacy AS (
+    SELECT DISTINCT ON (page_id) page_id, id, version_id
+      FROM opened ORDER BY page_id, publish_at DESC, id
+  ),
+  -- 0.91.1: the newest started row governs whether or not it is still open,
+  -- and only then is it asked. An expired row shadows an open one here.
+  gov AS (
+    SELECT DISTINCT ON (page_id) page_id, id, version_id, unpublish_at
+      FROM started ORDER BY page_id, publish_at DESC, published_at DESC NULLS LAST, id
+  ),
+  sched AS (
+    SELECT DISTINCT ON (page_id) page_id, version_id, publish_at
+      FROM act WHERE publish_at > _at ORDER BY page_id, publish_at, id
+  ),
+  -- Two independent ways to lose determinism, one per reader. Ties are still
+  -- broken above, by row id, so that this record can be reproduced; these two
+  -- are what says the record is not authoritative.
+  amb_open AS (
+    SELECT page_id FROM (
+      SELECT page_id, publish_at, max(publish_at) OVER (PARTITION BY page_id) AS mx FROM opened
+    ) t WHERE publish_at = mx GROUP BY page_id HAVING count(*) > 1
+  ),
+  amb_started AS (
+    SELECT page_id FROM (
+      SELECT page_id, publish_at, published_at,
+             max(publish_at) OVER (PARTITION BY page_id) AS mx FROM started
+    ) t WHERE publish_at = mx GROUP BY page_id
+     HAVING count(*) > 1
+        AND (count(*) FILTER (WHERE published_at IS NULL) > 0
+             OR count(DISTINCT published_at) < count(*))
+  ),
+  faults AS (
+    SELECT page_id, string_agg(fault, '; ' ORDER BY ord, fault) AS reason FROM (
+      SELECT l.page_id, 0 AS ord,
+             format('page status %L is not one this schema defines', l.status) AS fault
+        FROM live l WHERE l.status NOT IN ('draft', 'published')
+      UNION ALL
+      SELECT l.page_id, 1,
+             CASE WHEN v.id IS NULL
+                  THEN 'current_version_id points at a version that does not exist'
+                  ELSE 'current_version_id points at another page''s version' END
+        FROM live l
+        LEFT JOIN public.page_versions v ON v.id = l.current_version_id
+       WHERE l.current_version_id IS NOT NULL AND (v.id IS NULL OR v.page_id <> l.page_id)
+      UNION ALL
+      SELECT a.page_id, 2,
+             format('publication %s points at %s', a.id,
+                    CASE WHEN v.id IS NULL THEN 'a version that does not exist'
+                         ELSE 'another page''s version' END)
+        FROM act a
+        LEFT JOIN public.page_versions v ON v.id = a.version_id
+       WHERE v.id IS NULL OR v.page_id <> a.page_id
+      UNION ALL
+      SELECT a.page_id, 3, format('publication %s is scheduled to end before it starts', a.id)
+        FROM act a
+       WHERE a.unpublish_at IS NOT NULL AND a.unpublish_at <= a.publish_at
+    ) f GROUP BY page_id
+  ),
+  computed AS (
+    SELECT l.page_id, l.page_key, l.status,
+           (lg.version_id IS NOT NULL)                    AS legacy_from_publication,
+           coalesce(lg.version_id, l.current_version_id)   AS legacy_version_id,
+           CASE WHEN g.unpublish_at IS NULL OR g.unpublish_at > _at
+                THEN g.version_id END                     AS v2_version_id,
+           lg.id                                          AS governing_publication_id,
+           s.version_id                                   AS scheduled_version_id,
+           s.publish_at                                   AS scheduled_publish_at,
+           (ao.page_id IS NOT NULL OR ast.page_id IS NOT NULL) AS ambiguous_order,
+           EXISTS (SELECT 1 FROM started st WHERE st.page_id = l.page_id) AS has_started,
+           f.reason                                       AS fault_reason
+      FROM live l
+      LEFT JOIN legacy      lg  ON lg.page_id  = l.page_id
+      LEFT JOIN gov         g   ON g.page_id   = l.page_id
+      LEFT JOIN sched       s   ON s.page_id   = l.page_id
+      LEFT JOIN amb_open    ao  ON ao.page_id  = l.page_id
+      LEFT JOIN amb_started ast ON ast.page_id = l.page_id
+      LEFT JOIN faults      f   ON f.page_id   = l.page_id
+  ),
+  classified AS (
+    SELECT c.*,
+           CASE
+             WHEN c.fault_reason IS NOT NULL                                   THEN 'structurally_invalid'
+             WHEN c.legacy_version_id IS NOT DISTINCT FROM c.v2_version_id     THEN 'already_safe'
+             WHEN c.legacy_version_id IS NOT NULL AND c.v2_version_id IS NOT NULL THEN 'disagreement'
+             WHEN c.status <> 'published'                                      THEN 'hidden_by_design'
+             WHEN c.ambiguous_order                                            THEN 'needs_review'
+             WHEN c.has_started AND NOT c.legacy_from_publication              THEN 'hidden_by_expiry'
+             WHEN c.legacy_from_publication                                    THEN 'preserved'
+             ELSE 'needs_review'
+           END AS classification
+      FROM computed c
+  ),
+  final AS (
+    SELECT c.*,
+           (c.classification IN ('structurally_invalid', 'disagreement', 'needs_review'))
+             AS requires_decision,
+           CASE c.classification
+             WHEN 'structurally_invalid' THEN c.fault_reason
+             WHEN 'disagreement' THEN 'the two readers serve different versions of this page'
+             WHEN 'hidden_by_design' THEN
+               format('the page is %s, so it was not public either way', c.status)
+             WHEN 'hidden_by_expiry' THEN
+               'every publication window for this page had already closed'
+             WHEN 'preserved' THEN
+               'an expired publication row shadows the open one, so the new reader serves nothing'
+             WHEN 'needs_review' THEN
+               CASE WHEN c.ambiguous_order THEN 'ambiguous_order'
+                    WHEN c.scheduled_version_id IS NOT NULL THEN
+                      'this page''s only publication window has not opened yet, and the data cannot '
+                      || 'say whether it is meant to stay live until then or go dark now'
+                    ELSE 'the page has no publication row at all, so what it used to serve cannot '
+                      || 'be established from the data' END
+           END AS reason
+      FROM classified c
+  )
+  SELECT f.page_id, f.page_key, f.classification, f.requires_decision,
+         f.legacy_version_id, f.v2_version_id, f.legacy_from_publication,
+         f.governing_publication_id, f.scheduled_version_id, f.scheduled_publish_at,
+         f.ambiguous_order, f.reason,
+         -- Field names are the SQL column names on both sides, and the digest
+         -- is taken over the canonical form, so key order here does not matter
+         -- and a rename on either side is a parity failure rather than a
+         -- silent divergence.
+         jsonb_build_object(
+           'ambiguous_order', f.ambiguous_order,
+           'classification', f.classification,
+           'governing_publication_id', f.governing_publication_id::text,
+           'legacy_from_publication', f.legacy_from_publication,
+           'legacy_version_id', f.legacy_version_id::text,
+           'page_id', f.page_id::text,
+           'page_key', f.page_key,
+           'requires_decision', f.requires_decision,
+           'scheduled_publish_at', to_char(f.scheduled_publish_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+           'scheduled_version_id', f.scheduled_version_id::text,
+           'v2_version_id', f.v2_version_id::text
+         )
+    FROM final f;
+$scan$;
+
+-- Reconciliation: a scan that no person asked for --------------------------
+--
+-- A schema-2 archive predates these tables entirely, so restoring one leaves a
+-- database full of pages that no run has ever looked at. Nothing is wrong with
+-- the content; what is missing is the record of what it publishes and why. The
+-- backoffice queue would be empty, cms_publication_review_is_complete would be
+-- false for every candidate run, and the site would be in the one state this
+-- schema exists to make impossible: serving pages whose classification nobody
+-- can state.
+--
+-- So the restore scans, and records the scan honestly:
+--
+--   source='reconciliation'   nobody approved this; the database did it
+--   classified_by_email       the operator who ran the restore
+--   approved_by_email         the same, and it is not a second signature --
+--                             the columns are NOT NULL and the honest answer
+--                             to "who approved this" is "the person who chose
+--                             to restore an archive that carried no history"
+--
+-- What it does NOT do is decide anything. It writes items, never decisions:
+-- every page is classified with the standing default (keep showing what the
+-- site shows today), and any page the scan cannot speak for is left with
+-- requires_decision set, waiting for a person exactly as it would after an
+-- upgrade. A reconciliation that silently resolved its own ambiguities would
+-- be a way to launder an unreviewed publication state through a backup file.
+--
+-- Called only where the restore actually finished. A partial restore must not
+-- produce a run, because a run's expected_page_count is a claim about a
+-- database that has stopped changing, and half a restore is not that.
+--
+-- Definer's rights, and granted to service_role alone.
+--
+-- The two tables it writes grant every client role SELECT and nothing else --
+-- runs and items are written by this schema, never by a session -- so an
+-- invoker-rights version of this function would reach its first INSERT and
+-- stop, whoever called it. The grant is also the whole of the authorization:
+-- there is no signed-in user behind a restore to ask is_staff about, and the
+-- newest applied run is the one that governs the installation, so an editor
+-- session able to call this could displace a person's reviewed run with a
+-- machine's housekeeping and empty the pending-decision queue by doing it.
+-- Same shape, and the same reason, as cms_route_registry_set below.
+CREATE OR REPLACE FUNCTION public.cms_publication_review_reconcile(
+  _operator_email text,
+  _site_key       text DEFAULT NULL,
+  _environment    text DEFAULT NULL
+)
+RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $reconcile$
+DECLARE
+  _at       timestamptz := now();
+  _run_id   uuid        := gen_random_uuid();
+  _live     bigint;
+  _scanned  bigint;
+  _identity text;
+BEGIN
+  IF coalesce(btrim(_operator_email), '') = '' THEN
+    RAISE EXCEPTION 'reconciliation needs the address of whoever ran the restore'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT current_database() || '/' || d.oid::text INTO _identity
+    FROM pg_database d WHERE d.datname = current_database();
+
+  SELECT count(*) INTO _live FROM public.pages WHERE deleted_at IS NULL;
+
+  -- 'applying' first, then 'applied' once the items are in and counted. The
+  -- run's own guard trigger permits exactly that transition, and a failure
+  -- between the two leaves a run that cms_publication_review_is_complete
+  -- refuses -- which is the correct reading of an interrupted scan.
+  INSERT INTO public.cms_publication_review_runs (
+    id, approval_nonce, site_key, environment, review_database_identity,
+    release_sha,
+    package_version, migration_name, migration_digest, input_fingerprint,
+    manifest_digest, evaluated_at, expected_page_count, state, source,
+    classified_by_email, classified_at, approved_by_email, approved_at
+  ) VALUES (
+    _run_id, gen_random_uuid(),
+    coalesce(nullif(btrim(_site_key), ''), 'restore'),
+    coalesce(nullif(btrim(_environment), ''), 'restore'),
+    _identity,
+    'restore', 'restore', 'restore', 'restore',
+    public.cms_publication_review_fingerprint(),
+    'restore',
+    _at, _live, 'applying', 'reconciliation',
+    _operator_email, _at, _operator_email, _at
+  );
+
+  INSERT INTO public.cms_publication_review_items (
+    run_id, page_id, page_key, classification, requires_decision,
+    legacy_version_id, v2_version_id, legacy_from_publication,
+    governing_publication_id, scheduled_version_id, scheduled_publish_at,
+    ambiguous_order, reason, inputs
+  )
+  SELECT _run_id, page_id, page_key, classification, requires_decision,
+         legacy_version_id, v2_version_id, legacy_from_publication,
+         governing_publication_id, scheduled_version_id, scheduled_publish_at,
+         ambiguous_order, reason, inputs
+    FROM public.cms_publication_review_scan(_at);
+
+  GET DIAGNOSTICS _scanned = ROW_COUNT;
+
+  -- expected and scanned are compared, not assumed equal: a page created or
+  -- soft-deleted between the count above and the scan would make them differ,
+  -- and cms_publication_review_is_complete is what notices.
+  UPDATE public.cms_publication_review_runs
+     SET state = 'applied',
+         scanned_page_count = _scanned,
+         scan_completed_at = now(),
+         applied_by_email = _operator_email,
+         applied_at = now(),
+         counts = (
+           SELECT jsonb_object_agg(classification, n)
+             FROM (SELECT classification, count(*) AS n
+                     FROM public.cms_publication_review_items
+                    WHERE run_id = _run_id
+                    GROUP BY classification) c
+         )
+   WHERE id = _run_id;
+
+  RETURN _run_id;
+END;
+$reconcile$;
+
+-- The runtime capability answer. A filename list cannot tell a caller whether
+-- it may call the v3 functions yet; this can, because it is assembled from the
+-- rows the migrations themselves wrote as they made each capability true.
+-- healthResponse calls it, and treats a missing function, an error, or a
+-- contractVersion below what the package expects as a failed health check.
+--
+-- Every row here is written by the file that makes its capability true, in the
+-- same transaction, which is what keeps the answer honest: there is no point
+-- at which the schema claims route-claims and has no cms_route_claims to
+-- claim into. The four named capabilities are the four contract v3 adds; the
+-- two versioned ones are reported as versions instead.
+INSERT INTO public.cms_schema_capabilities (capability, version, migration)
+VALUES
+  ('archive-schema',         3, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql'),
+  ('publication-review',     1, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql'),
+  ('route-claims',           1, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql'),
+  ('duplicate-idempotency',  1, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql'),
+  ('global-lock-order',      1, '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24.sql')
+ON CONFLICT (capability) DO UPDATE
+   SET version     = EXCLUDED.version,
+       migration   = EXCLUDED.migration,
+       recorded_at = now()
+ WHERE public.cms_schema_capabilities.version < EXCLUDED.version;
+
+CREATE OR REPLACE FUNCTION public.cms_platform_capability()
+RETURNS jsonb
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT jsonb_build_object(
+    'contractVersion', public.cms_schema_capability('platform-contract'),
+    'schemaVersion',   public.cms_schema_capability('archive-schema'),
+    'reviewModel',     'runs-items-decisions',
+    -- Named capabilities only: the two version rows above are reported as
+    -- versions, not repeated here as feature names. Sorted, so two
+    -- installations at the same schema give byte-identical answers.
+    'capabilities',    COALESCE((
+      SELECT jsonb_agg(capability ORDER BY capability)
+        FROM public.cms_schema_capabilities
+       WHERE capability NOT IN ('platform-contract', 'archive-schema')
+    ), '[]'::jsonb)
+  );
+$$;
+
+ALTER TABLE public.cms_publication_review_runs      ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.cms_publication_review_items     ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.cms_publication_review_decisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.cms_route_claims                 ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.cms_route_registry               ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.cms_page_duplicate_operations    ENABLE ROW LEVEL SECURITY;
+
+-- The two route tables are the one exception to "anon gets nothing", and the
+-- exception is the public reader itself. Every render resolves the requested
+-- URL against the claims and against the registry's normalization policy, and
+-- it does so as whichever role serves public traffic — anon, on a hosted
+-- stack. Withholding them would also protect nothing: this schema has let
+-- anyone read public.pages since its first migration ("Anyone can read
+-- pages"), so every page a claim can name is already legible. What the claims
+-- add is which URL serves it, which is the one thing a site tells the world on
+-- purpose.
+--
+-- No TO clause on either policy, deliberately. A self-host with no hosted
+-- roles at all still has to be able to read its own routes, and a policy named
+-- for roles that do not exist cannot be created there.
+DROP POLICY IF EXISTS cms_route_claims_public_read ON public.cms_route_claims;
+CREATE POLICY cms_route_claims_public_read
+    ON public.cms_route_claims FOR SELECT USING (true);
+
+DROP POLICY IF EXISTS cms_route_registry_public_read ON public.cms_route_registry;
+CREATE POLICY cms_route_registry_public_read
+    ON public.cms_route_registry FOR SELECT USING (true);
+
+-- Read-only, to the roles that have any business reading each table, and only
+-- where those roles exist — this file has to apply to a plain PostgreSQL
+-- database with no PostgREST stack behind it, exactly as the two v2
+-- migrations do.
+--
+-- Nothing here grants INSERT, UPDATE or DELETE to anybody, on any of the six.
+-- Runs and items are written by the migration and by
+-- cms_publication_review_reconcile; decisions, route claims, the registry
+-- snapshot and the duplicate ledger are written only through SECURITY DEFINER
+-- functions, which is what makes "who decided this", "who claimed this URL"
+-- and "was this duplication already served" questions with one answer each. The duplicate ledger joins the review tables on the private
+-- side: it is editor bookkeeping, and it names pages before anyone has decided
+-- to publish them.
+DO $$
+DECLARE
+  _role  text;
+  _table 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 _table IN ARRAY ARRAY['cms_installation',
+                                  'cms_schema_capabilities',
+                                  'cms_publication_review_runs',
+                                  'cms_publication_review_items',
+                                  'cms_publication_review_decisions',
+                                  'cms_page_duplicate_operations'] LOOP
+      EXECUTE format('REVOKE ALL ON TABLE public.%I FROM %I', _table, _role);
+      IF _role <> 'anon' THEN
+        EXECUTE format('GRANT SELECT ON TABLE public.%I TO %I', _table, _role);
+      END IF;
+    END LOOP;
+
+    FOREACH _table IN ARRAY ARRAY['cms_route_claims',
+                                  'cms_route_registry'] LOOP
+      EXECUTE format('REVOKE ALL ON TABLE public.%I FROM %I', _table, _role);
+      EXECUTE format('GRANT SELECT ON TABLE public.%I TO %I', _table, _role);
+    END LOOP;
+
+    IF _role = 'authenticated' THEN
+      FOREACH _table IN ARRAY ARRAY['cms_publication_review_runs',
+                                    'cms_publication_review_items',
+                                    'cms_publication_review_decisions',
+                                    'cms_page_duplicate_operations'] LOOP
+        EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', _table || '_admin_read', _table);
+        EXECUTE format(
+          'CREATE POLICY %I ON public.%I FOR SELECT TO authenticated
+             USING (public.has_role(auth.uid(), ''admin''::public.app_role))',
+          _table || '_admin_read', _table);
+      END LOOP;
+    ELSIF _role = 'service_role' THEN
+      FOREACH _table IN ARRAY ARRAY['cms_publication_review_runs',
+                                    'cms_publication_review_items',
+                                    'cms_publication_review_decisions',
+                                    'cms_page_duplicate_operations'] LOOP
+        EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', _table || '_service_read', _table);
+        EXECUTE format(
+          'CREATE POLICY %I ON public.%I FOR SELECT TO service_role USING (true)',
+          _table || '_service_read', _table);
+      END LOOP;
+    END IF;
+  END LOOP;
+END
+$$;
+
+-- 8. The approval this migration refuses to run without ----------------------
+--
+-- Everything above is schema. What follows changes what the site serves, and
+-- it does so on the strength of a scan somebody looked at and signed. The
+-- signature arrives as custom GUCs, set by the deployment helper immediately
+-- before this file is piped in:
+--
+--   PGOPTIONS="-c lovable.approval_nonce=... -c lovable.input_fingerprint=..."
+--
+-- which leaves stdin byte-identical to the file that was digested, so the
+-- approval covers exactly the SQL that runs. No psql meta-commands, no
+-- interpolation, nothing that makes this file unreadable by another client.
+--
+-- The helper has already checked the approval record against this deployment
+-- before exporting anything. Some of that is deliberately checked again here,
+-- because the helper and the database can disagree, and the database is the
+-- one that knows what is actually in it.
+--
+-- One exception, and it is not a loophole. The review exists to carry a
+-- person's answers from the moment they looked at the site to the moment the
+-- upgrade happens. Where the scan finds nothing to answer, there is nothing to
+-- carry, and nobody to wait for: every page either looks the same to both
+-- readers, was not public either way, or is covered by the standing default.
+-- So a database the scan can speak for entirely records an unattended run and
+-- says so in the record. This is what lets a site be installed from scratch --
+-- the earlier migrations seed a site's own starter pages, so a fresh database
+-- is never empty by the time this runs -- and it is not a way around the
+-- review, because the scan happens in this transaction, against this database:
+-- "there was nothing to decide" is not a claim an approval can make.
+--
+-- An approval that is present is honoured and checked in full either way.
+DO $$
+DECLARE
+  _migration   constant text := '20260905120000_da2db0b2-6048-4aa8-8e4f-13ee33e9cc24';
+  -- Not a person, and shaped so it can never become one: .invalid is reserved
+  -- precisely so that it never resolves.
+  _unattended  constant text := 'migration@cms-platform.invalid';
+  -- Every setting an approval must arrive with. The setting
+  -- 'database_identity' is not here and that is deliberate: it names the
+  -- cluster, which is the deployment tooling's question, and this file asks a
+  -- narrower one. See the identity check below.
+  _required    constant text[] := ARRAY[
+    'approval_nonce', 'site_key', 'environment', 'review_database_identity',
+    'release_sha', 'package_version', 'migration_name', 'migration_digest',
+    'run_id', 'input_fingerprint', 'manifest_digest', 'approval_expires_at',
+    'evaluated_at', 'decision_count'
+  ];
+  _at          timestamptz := now();
+  _live        bigint;
+  _needs       bigint;
+  _approved    boolean;
+  _identity    text;
+  _run_id      uuid;
+  _evaluated   timestamptz;
+  _expires     timestamptz;
+  _decisions   jsonb := '[]'::jsonb;
+  _live_fp     text;
+  _crossed     bigint;
+  _undecided   text;
+  _mismatched  text;
+  _unrestorable text;
+  _guc         text;
+  _raw         text;
+  _missing     text[] := ARRAY[]::text[];
+BEGIN
+  -- Already done. A migration runner that loses its connection between the
+  -- commit and its own bookkeeping will run this file again, and the second
+  -- attempt must be a quiet no-op rather than a refusal: the review is a
+  -- one-time crossing from the old reader to the new one, and once a run has
+  -- reached 'applied' there is no longer an old reader to preserve anything
+  -- from. Without this the retry reaches the fingerprint check and fails with
+  -- "the pages changed after this review was approved" -- true, because the
+  -- restorations changed them, but a frightening sentence to meet when in fact
+  -- nothing is wrong.
+  IF EXISTS (SELECT 1 FROM public.cms_publication_review_runs
+              WHERE migration_name = _migration AND state = 'applied') THEN
+    RAISE NOTICE 'contract v3: the publication review already ran here, so there is nothing to do';
+    RETURN;
+  END IF;
+
+  SELECT count(*) INTO _live FROM public.pages WHERE deleted_at IS NULL;
+
+  -- The identity an approval can name. cms_installation_id() is created by
+  -- this very file, so on a first upgrade it did not exist when the scan ran
+  -- and cannot be what the scan bound itself to. This is what a read-only role
+  -- could see beforehand, and it changes when content is restored into a
+  -- different database — which is the case worth catching.
+  SELECT current_database() || '/' || d.oid::text INTO _identity
+    FROM pg_database d WHERE d.datname = current_database();
+
+  -- The fingerprint of what is here. Both paths record it, and an approval is
+  -- checked against it. Not "has anything changed" in the abstract, but
+  -- everything either reader looks at, in one deterministic string, so that a
+  -- page edited between the review and the upgrade is refused on arrival
+  -- rather than settled from stale evidence. See the function for what is in
+  -- it and why.
+  _live_fp := public.cms_publication_review_fingerprint();
+
+  -- The scan itself, and it runs before anything has been decided, because
+  -- whether this upgrade needs a person is a question only the scan can
+  -- answer.
+  --
+  -- Into a temporary table rather than straight into the review items, because
+  -- an item belongs to a run and the run cannot be written until the count
+  -- below has chosen a path. ON COMMIT DROP, so a failure anywhere after this
+  -- takes the scan with it and leaves nothing behind to be mistaken for a
+  -- record.
+  CREATE TEMP TABLE cms_v3_scan (
+    page_id                  uuid,
+    page_key                 text,
+    classification           text,
+    requires_decision        boolean,
+    legacy_version_id        uuid,
+    v2_version_id            uuid,
+    legacy_from_publication  boolean,
+    governing_publication_id uuid,
+    scheduled_version_id     uuid,
+    scheduled_publish_at     timestamptz,
+    ambiguous_order          boolean,
+    reason                   text,
+    inputs                   jsonb
+  ) ON COMMIT DROP;
+
+  INSERT INTO cms_v3_scan
+  SELECT * FROM public.cms_publication_review_scan(_at);
+
+  -- Who has to be involved. A page that classified cleanly needs nobody; only
+  -- the pages the data cannot speak for do. Where there are none, this is an
+  -- ordinary schema change and is applied as one.
+  SELECT count(*) FILTER (WHERE requires_decision) INTO _needs FROM cms_v3_scan;
+
+  -- An approval that was supplied is used even when the scan would have been
+  -- content to proceed alone. Somebody who looked at this database and recorded
+  -- an answer gets that answer applied and every check below run against it --
+  -- including the one case the count above cannot see on its own, an operator
+  -- who decided that a page the default would have kept alive should stay dark.
+  _approved := _needs > 0
+            OR nullif(current_setting('lovable.approval_nonce', true), '') IS NOT NULL;
+
+  IF _approved THEN
+    -- Absent and empty are the same thing here. PGOPTIONS will happily carry a
+    -- variable that was set to nothing, and a blank fingerprint must not read as
+    -- a fingerprint that matched.
+    FOREACH _guc IN ARRAY _required LOOP
+      IF nullif(current_setting('lovable.' || _guc, true), '') IS NULL THEN
+        _missing := _missing || _guc;
+      END IF;
+    END LOOP;
+
+    IF cardinality(_missing) > 0 THEN
+      RAISE EXCEPTION
+        'this database has % live pages and no approved publication review; missing %',
+        _live, array_to_string(_missing, ', ')
+        USING ERRCODE = '42501',
+              HINT = 'run cms-review scan, review what it found, then install-lovable-migration-approval';
+    END IF;
+
+    -- Malformed is its own failure, separate from absent, because "the helper
+    -- exported something unusable" and "the helper exported nothing" are
+    -- different faults and get looked for in different places.
+    _raw := current_setting('lovable.run_id', true);
+    BEGIN
+      _run_id := _raw::uuid;
+      _evaluated := current_setting('lovable.evaluated_at', true)::timestamptz;
+      _expires := current_setting('lovable.approval_expires_at', true)::timestamptz;
+      PERFORM current_setting('lovable.approval_nonce', true)::uuid;
+    EXCEPTION WHEN others THEN
+      RAISE EXCEPTION 'this approval is not readable: %', SQLERRM USING ERRCODE = '22023';
+    END;
+
+    IF _expires <= _at THEN
+      RAISE EXCEPTION 'this approval expired at %', _expires
+        USING ERRCODE = '42501',
+              HINT = 'the database may have moved on since the scan; run cms-review scan again';
+    END IF;
+
+    -- A review cannot have happened later than now. Worth refusing on its own
+    -- terms, but the reason it matters here is the window-crossing check below:
+    -- that check asks which windows moved between the review and now, and if the
+    -- review claims to be in the future there is no such interval, so the check
+    -- passes by looking at nothing. A skewed clock or an edited timestamp would
+    -- switch off the one protection a fingerprint cannot provide.
+    IF _evaluated > _at THEN
+      RAISE EXCEPTION 'this approval says it was evaluated at %, which is in the future', _evaluated
+        USING ERRCODE = '22023',
+              HINT = 'check the clock on the machine that ran cms-review scan';
+    END IF;
+
+    -- The name arrives as the file, because the other reader of an approval is
+    -- a deployment script holding a path and comparing basenames. One trailing
+    -- '.sql' is removed here rather than adding a second spelling of the name to
+    -- the approval, since two spellings of one thing is how the two readers came
+    -- to disagree in the first place. A name that never had the suffix still
+    -- matches, so an approval made by an older helper is not orphaned.
+    IF regexp_replace(coalesce(current_setting('lovable.migration_name', true), ''),
+                      '[.]sql$', '') <> _migration THEN
+      RAISE EXCEPTION 'this approval is for migration %, not %',
+        current_setting('lovable.migration_name', true), _migration
+        USING ERRCODE = '42501';
+    END IF;
+
+    -- The database, not the cluster. An approval also carries the cluster's
+    -- identifier, under the setting 'database_identity', and the deployment
+    -- tooling checks that one before it connects, because that is the most it
+    -- can know from outside. From in here the sharper question is answerable
+    -- and is the one worth asking: two databases in one cluster share an
+    -- identifier and are not the same database to review. It is this answer
+    -- the run keeps, in cms_publication_review_runs.review_database_identity.
+    IF current_setting('lovable.review_database_identity', true) <> _identity THEN
+      RAISE EXCEPTION 'this approval was made against database %, but this is %',
+        current_setting('lovable.review_database_identity', true), _identity
+        USING ERRCODE = '42501',
+              HINT = 'a staging review cannot approve a production upgrade';
+    END IF;
+
+    -- Recorded, not verified: nothing in this database states which release or
+    -- package version is being deployed, so there is nothing here to check them
+    -- against. The helper checked them against the deployment before it exported
+    -- anything; this file writes them down so the run says which deployment it
+    -- belonged to.
+
+    IF _live_fp <> current_setting('lovable.input_fingerprint', true) THEN
+      RAISE EXCEPTION 'the pages changed after this review was approved'
+        USING ERRCODE = '42501',
+              DETAIL = format('approved %s, found %s',
+                              current_setting('lovable.input_fingerprint', true), _live_fp),
+              HINT = 'run cms-review scan again against the current database';
+    END IF;
+
+
+    -- A fingerprint says the rows have not moved. It cannot say the clock has
+    -- not: a window that opened or closed between the scan and now changes what
+    -- a page serves without changing a single row, and the classification the
+    -- operator approved would be describing a moment that has passed.
+    SELECT count(*) INTO _crossed
+      FROM public.page_publications pp
+     WHERE pp.is_active
+       AND ((pp.publish_at > _evaluated AND pp.publish_at <= _at)
+         OR (pp.unpublish_at IS NOT NULL AND pp.unpublish_at > _evaluated AND pp.unpublish_at <= _at));
+
+    IF _crossed > 0 THEN
+      RAISE EXCEPTION
+        '% publication window(s) opened or closed between the review at % and now',
+        _crossed, _evaluated
+        USING ERRCODE = '42501',
+              HINT = 'run cms-review scan again; the site is not showing what the review described';
+    END IF;
+
+    INSERT INTO public.cms_publication_review_runs (
+      id, approval_nonce, site_key, environment, review_database_identity,
+      release_sha,
+      package_version, migration_name, migration_digest, input_fingerprint,
+      manifest_digest, evaluated_at, expected_page_count, state, source,
+      classified_by_email, classified_at, approved_by_email, approved_at
+    ) VALUES (
+      _run_id,
+      current_setting('lovable.approval_nonce', true)::uuid,
+      current_setting('lovable.site_key', true),
+      current_setting('lovable.environment', true),
+      _identity,
+      current_setting('lovable.release_sha', true),
+      current_setting('lovable.package_version', true),
+      _migration,
+      current_setting('lovable.migration_digest', true),
+      _live_fp,
+      current_setting('lovable.manifest_digest', true),
+      _evaluated, _live, 'applying', 'migration',
+      coalesce(nullif(current_setting('lovable.classified_by_email', true), ''), _unattended), _evaluated,
+      coalesce(nullif(current_setting('lovable.approved_by_email', true), ''), _unattended), _evaluated
+    );
+  ELSE
+    -- Nothing here was ambiguous, so there is no approval to record and no
+    -- person to name. The run is written anyway, with the real page count and
+    -- the real fingerprint, because "this database was scanned and found
+    -- clear" is exactly as much a fact about the upgrade as a signed review is,
+    -- and the readiness check asks the same question of both.
+    _run_id := gen_random_uuid();
+    INSERT INTO public.cms_publication_review_runs (
+      id, approval_nonce, site_key, environment, review_database_identity,
+      release_sha,
+      package_version, migration_name, migration_digest, input_fingerprint,
+      manifest_digest, evaluated_at, expected_page_count, state, source,
+      classified_by_email, classified_at, approved_by_email, approved_at
+    ) VALUES (
+      _run_id, gen_random_uuid(),
+      coalesce(nullif(current_setting('lovable.site_key', true), ''), 'unattended'),
+      coalesce(nullif(current_setting('lovable.environment', true), ''), 'unattended'),
+      _identity,
+      coalesce(nullif(current_setting('lovable.release_sha', true), ''), 'unattended'),
+      coalesce(nullif(current_setting('lovable.package_version', true), ''), 'unattended'),
+      _migration,
+      coalesce(nullif(current_setting('lovable.migration_digest', true), ''), 'unattended'),
+      _live_fp,
+      coalesce(nullif(current_setting('lovable.manifest_digest', true), ''), 'unattended'),
+      _at, _live, 'applying', 'migration',
+      _unattended, _at, _unattended, _at
+    );
+    RAISE NOTICE
+      'contract v3: % live page(s) scanned, none of which needed a person', _live;
+  END IF;
+
+  INSERT INTO public.cms_publication_review_items (
+    run_id, page_id, page_key, classification, requires_decision,
+    legacy_version_id, v2_version_id, legacy_from_publication,
+    governing_publication_id, scheduled_version_id, scheduled_publish_at,
+    ambiguous_order, reason, inputs
+  )
+  SELECT _run_id, page_id, page_key, classification, requires_decision,
+         legacy_version_id, v2_version_id, legacy_from_publication,
+         governing_publication_id, scheduled_version_id, scheduled_publish_at,
+         ambiguous_order, reason, inputs
+    FROM cms_v3_scan;
+
+  -- The decisions a person made about what they saw. They travel as canonical
+  -- JSON in a GUC alongside their digest, so a payload edited between the
+  -- approval and the upgrade is a refusal rather than a surprise.
+  --
+  -- Only departures from the standing default travel this way. The default is
+  -- "keep showing what the site shows today", which the migration can apply on
+  -- its own; what it cannot know is when somebody decided otherwise.
+  -- Only where an approval was checked. On the unattended path nothing has
+  -- been bound to this database or to this scan, so a decision list arriving
+  -- in a startup option would be an unsigned instruction, and is not read.
+  _raw := CASE WHEN _approved
+               THEN nullif(current_setting('lovable.decisions', true), '') END;
+  IF _raw IS NOT NULL THEN
+    BEGIN
+      _decisions := _raw::jsonb;
+    EXCEPTION WHEN others THEN
+      RAISE EXCEPTION 'the approved decisions are not readable json' USING ERRCODE = '22023';
+    END;
+
+    IF jsonb_typeof(_decisions) <> 'array' THEN
+      RAISE EXCEPTION 'the approved decisions must be a json array, not %',
+        jsonb_typeof(_decisions) USING ERRCODE = '22023';
+    END IF;
+
+    IF public.cms_digest(_decisions)
+       IS DISTINCT FROM nullif(current_setting('lovable.decisions_digest', true), '') THEN
+      RAISE EXCEPTION 'the approved decisions do not match the digest that was signed'
+        USING ERRCODE = '42501',
+              HINT = 'the decision list was edited after the approval was installed';
+    END IF;
+  END IF;
+
+  -- The count exists for the reader that has no json parser: a shell script on
+  -- a server can say how many answers it is about to install, but only if
+  -- somebody counted for it. Checked because a number nobody verifies is a
+  -- number that will eventually be wrong, and it would be wrong in the one
+  -- place an operator was relying on it to be right. Outside the block above on
+  -- purpose: an approval claiming three decisions and carrying no decision
+  -- setting at all is exactly the case worth catching, and _decisions is the
+  -- empty list until something fills it.
+  IF _approved AND current_setting('lovable.decision_count', true)
+                   IS DISTINCT FROM jsonb_array_length(_decisions)::text THEN
+    RAISE EXCEPTION 'this approval says it carries % decision(s) but carries %',
+      current_setting('lovable.decision_count', true), jsonb_array_length(_decisions)
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- A decision is an answer to a specific classification, not to a page. If
+  -- the page classified differently this time, the answer is about a question
+  -- nobody asked, and applying it would be guesswork wearing a signature.
+  SELECT string_agg(d.page_id::text, ', ' ORDER BY d.page_id::text) INTO _mismatched
+    FROM jsonb_to_recordset(_decisions)
+      AS d(page_id uuid, decision text, expected_inputs_digest text,
+           resolved_by_email text, note text)
+    LEFT JOIN public.cms_publication_review_items i
+      ON i.run_id = _run_id AND i.page_id = d.page_id
+   WHERE i.id IS NULL OR i.inputs_digest IS DISTINCT FROM d.expected_inputs_digest;
+
+  IF _mismatched IS NOT NULL THEN
+    RAISE EXCEPTION 'these pages classified differently than when they were reviewed: %',
+      _mismatched
+      USING ERRCODE = '42501',
+            HINT = 'run cms-review scan again and review the pages that changed';
+  END IF;
+
+  INSERT INTO public.cms_publication_review_decisions (
+    item_id, run_id, page_id, decision, expected_inputs_digest, source,
+    resolved_by_email, note
+  )
+  SELECT i.id, i.run_id, i.page_id, d.decision, d.expected_inputs_digest, 'migration',
+         coalesce(nullif(d.resolved_by_email, ''), _unattended), d.note
+    FROM jsonb_to_recordset(_decisions)
+      AS d(page_id uuid, decision text, expected_inputs_digest text,
+           resolved_by_email text, note text)
+    JOIN public.cms_publication_review_items i
+      ON i.run_id = _run_id AND i.page_id = d.page_id;
+
+  -- Fail closed. A page whose classification says "nobody can tell what this
+  -- was showing" does not get an answer invented for it at three in the
+  -- morning; the upgrade stops and waits for a person.
+  SELECT string_agg(i.page_key, ', ' ORDER BY i.page_key) INTO _undecided
+    FROM public.cms_publication_review_items i
+    LEFT JOIN public.cms_publication_review_decisions d ON d.item_id = i.id
+   WHERE i.run_id = _run_id AND i.requires_decision AND d.id IS NULL;
+
+  IF _undecided IS NOT NULL THEN
+    RAISE EXCEPTION 'these pages still need a decision before the upgrade can proceed: %',
+      _undecided
+      USING ERRCODE = '42501',
+            HINT = 'cms-review resolve records what to do with each of them';
+  END IF;
+
+  -- A decision to republish is only honourable if the version it names is
+  -- actually this page's. On a structurally invalid page the legacy version is
+  -- itself the corrupt datum -- it may belong to another page or have been
+  -- deleted -- and writing it into a fresh publication row would carry the
+  -- fault forward under a note claiming the page was preserved. Refuse instead,
+  -- so the reviewer is told their answer cannot be carried out rather than
+  -- being shown a restoration that quietly did the wrong thing.
+  SELECT string_agg(i.page_key, ', ' ORDER BY i.page_key) INTO _unrestorable
+    FROM public.cms_publication_review_items i
+    LEFT JOIN public.cms_publication_review_decisions d ON d.item_id = i.id
+    LEFT JOIN public.page_versions v ON v.id = i.legacy_version_id
+   WHERE i.run_id = _run_id
+     AND i.legacy_version_id IS NOT NULL
+     AND (d.decision = 'publish-legacy-version'
+          OR (d.id IS NULL AND i.classification = 'preserved'))
+     AND (v.id IS NULL OR v.page_id <> i.page_id);
+
+  IF _unrestorable IS NOT NULL THEN
+    RAISE EXCEPTION 'these pages cannot be republished, because the version recorded for them does not belong to them: %',
+      _unrestorable
+      USING ERRCODE = '22023',
+            HINT = 'leave-hidden records the outage honestly; repairing the version pointer is a separate, deliberate change';
+  END IF;
+
+  -- Making it true. A restoration writes a NEW publication row rather than
+  -- reopening the expired one: the old row is the record of a window that
+  -- genuinely closed, and editing it would destroy the only evidence of what
+  -- the site did before the upgrade. The new row is dated now, so it governs
+  -- under the new reader, and it says in its own note which run put it there.
+  INSERT INTO public.page_publications (
+    page_id, version_id, publish_at, unpublish_at, is_active, published_at, note
+  )
+  SELECT i.page_id, i.legacy_version_id, _at, NULL, true, _at,
+         format('contract v3 review %s: kept serving the version this page was showing', _run_id)
+    FROM public.cms_publication_review_items i
+    LEFT JOIN public.cms_publication_review_decisions d ON d.item_id = i.id
+   WHERE i.run_id = _run_id
+     AND i.legacy_version_id IS NOT NULL
+     AND (d.decision = 'publish-legacy-version'
+          OR (d.id IS NULL AND i.classification = 'preserved'));
+END
+$$;
+
+-- 9. Every mutation takes the same locks in the same order -------------------
+--
+-- Two editors, two pages, one deadlock. `cms_save_page_version` locks the page
+-- it is saving and then — still holding that lock — calls
+-- `cms_schedule_page_reveal`, which locks the page the countdown names. An
+-- editor publishing A with a countdown revealing B takes A and then B. An
+-- editor publishing B with a countdown revealing A takes B and then A. Run the
+-- two in the same second and PostgreSQL kills one of them with a deadlock
+-- error, which is not something the person on the other end can act on.
+--
+-- None of this is hypothetical. The two nested reveal call sites are in the
+-- published migration 20260904160000, at lines 268 and 675; and
+-- `cms_cancel_page_publication` compounds the problem at lines 541 and 546 by
+-- locking a publication row before the page that owns it, which is the reverse
+-- of the order every one of its siblings uses.
+--
+-- The fix is one rule, written out the same way in every function that writes:
+--
+--   1. Work out the complete set of pages the call can touch, before taking a
+--      single lock.
+--   2. Lock that whole set through `app.cms_lock_pages`, which orders it by
+--      id — the UUID's own byte order: total, deterministic, and the same
+--      order in every session of every installation.
+--   3. Read the pages again under the lock, and decide everything from what is
+--      there now. A key that named a different page a moment ago aborts the
+--      call with SQLSTATE 40001, the one code client libraries already know to
+--      retry.
+--   4. Only then publication rows, and only in id order.
+--
+-- Two sessions that want the same pages queue at the same first row instead of
+-- meeting head-on, so the second one waits rather than dies.
+--
+-- There is no `_locks_held` flag and no "internal" twin of any function: a flag
+-- the caller can set is a caller-controlled bypass of the ordering, which is
+-- the whole of what is being protected. It is not needed, either. PostgreSQL
+-- row locks are reentrant within a transaction, so when `cms_save_page_version`
+-- has already locked A and B, the `cms_schedule_page_reveal` it calls locks A
+-- and B again and waits for nothing. The nested call still runs the whole
+-- collect-lock-revalidate; under its caller's locks that revalidation cannot
+-- fail, and that is exactly the property which makes nesting safe.
+--
+-- Every signature below is unchanged, so every body is a replacement rather
+-- than a new function. `CREATE OR REPLACE` keeps the EXECUTE grants migrations
+-- 20260904140000 and 20260904160000 wrote, and the rollback rows the review
+-- records can name the published bodies precisely because nothing was dropped.
+
+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;
+  _keys       text[];
+  _targets    jsonb;
+  _relocked   jsonb;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  IF _page_id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  -- Step 1. Every page this call can reach, worked out before anything is
+  -- locked. A reveal is only ever acted on by a publish, so only a publish
+  -- widens the set past the page being saved.
+  _keys := ARRAY(
+    SELECT DISTINCT btrim(r.value->>'key')
+      FROM jsonb_array_elements(
+             CASE WHEN _publish THEN COALESCE(_reveals, '[]'::jsonb)
+                  ELSE '[]'::jsonb END) AS r(value)
+     WHERE btrim(COALESCE(r.value->>'key', '')) <> '');
+
+  SELECT COALESCE(jsonb_object_agg(p.key, p.id), '{}'::jsonb) INTO _targets
+    FROM public.pages p
+   WHERE p.key = ANY (_keys) AND p.deleted_at IS NULL;
+
+  -- Step 2. One ordered lock over the whole set, taken once.
+  PERFORM app.cms_lock_pages(
+    ARRAY[_page_id]
+      || ARRAY(SELECT t.v::uuid FROM jsonb_each_text(_targets) AS t(k, v)));
+
+  -- Step 3. Ask the same question again, now that the answer cannot change.
+  -- A key that has moved means somebody else's rename landed between the two
+  -- statements: there is no honest answer to give, so this says "try again" in
+  -- the one SQLSTATE a client already retries, and writes nothing.
+  SELECT COALESCE(jsonb_object_agg(p.key, p.id), '{}'::jsonb) INTO _relocked
+    FROM public.pages p
+   WHERE p.key = ANY (_keys) AND p.deleted_at IS NULL;
+  IF _relocked IS DISTINCT FROM _targets THEN
+    RAISE EXCEPTION
+      'A page this save reveals was renamed, deleted or created while the save '
+      'was waiting for its locks. Nothing was written; try again.'
+      USING ERRCODE = '40001';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NULL;
+  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
+    -- Step 4. Publication rows, and only now. The page tier above has already
+    -- decided which session gets here first; ordering inside this tier is what
+    -- keeps two sessions holding the same pages from crossing each other over
+    -- the rows beneath them.
+    PERFORM id FROM public.page_publications
+      WHERE page_id = _page_id AND is_active
+      ORDER BY id
+      FOR UPDATE;
+
+    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. Every page it can reach is already locked, so the call below
+     * re-locks rows this transaction holds and waits for nothing.
+     */
+    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;
+$$;
+
+-- One page is still a set, and it goes through the same door. Writing the
+-- single-page case by hand would leave two lock orders in the schema — the one
+-- described above, and whatever this function happened to do — and the second
+-- one is the sort of thing that stays right until somebody adds a second page
+-- to it.
+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;
+  IF _page_id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  PERFORM app.cms_lock_pages(ARRAY[_page_id]);
+
+  SELECT * INTO _page FROM public.pages
+    WHERE id = _page_id AND deleted_at IS NULL;
+  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;
+
+  PERFORM id FROM public.page_publications
+    WHERE page_id = _page_id AND is_active
+    ORDER BY id
+    FOR UPDATE;
+
+  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;
+$$;
+
+-- The reveal is where the cycle used to close: it locked its target and nothing
+-- else, so whichever page its caller was already holding became the second edge
+-- of the graph. Locking source and target together, in id order, is what turns
+-- that edge into a queue. Called on its own the source is NULL and the set is
+-- one page; called from a save or a schedule both are already held, and this
+-- costs a lock lookup and nothing else.
+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;
+  _wanted    text := btrim(COALESCE(_page_key, ''));
+  _target    uuid;
+  _relocked  uuid;
+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 p.id INTO _target FROM public.pages p
+   WHERE p.key = _wanted AND p.deleted_at IS NULL;
+
+  PERFORM app.cms_lock_pages(
+    ARRAY(SELECT x FROM unnest(ARRAY[_source_page_id, _target]) AS u(x)
+           WHERE x IS NOT NULL));
+
+  SELECT p.id INTO _relocked FROM public.pages p
+   WHERE p.key = _wanted AND p.deleted_at IS NULL;
+  IF _relocked IS DISTINCT FROM _target THEN
+    RAISE EXCEPTION
+      'The page "%" was renamed, deleted or created while this reveal was '
+      'waiting for its locks. Nothing was written; try again.', _wanted
+      USING ERRCODE = '40001';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages WHERE id = _target;
+
+  -- 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;
+
+  -- Publication rows, after the pages and in id order.
+  PERFORM id FROM public.page_publications
+    WHERE page_id = _page.id AND is_active
+    ORDER BY id
+    FOR UPDATE;
+
+  -- 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;
+$$;
+
+-- The inversion. This function read its publication row `FOR UPDATE` and only
+-- afterwards locked the page that owns it — publications before pages, the
+-- reverse of everything else in the schema, and enough on its own to deadlock
+-- against any sibling that was doing it the right way round. The publication is
+-- read once without a lock, purely to learn which page to lock; the page goes
+-- first; and only then is the row read again, locked, and judged.
+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;
+  _owner uuid;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  SELECT pp.page_id INTO _owner FROM public.page_publications pp
+   WHERE pp.id = _publication_id;
+  IF _owner IS NULL THEN
+    RAISE EXCEPTION 'Publication not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  PERFORM app.cms_lock_pages(ARRAY[_owner]);
+
+  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;
+  -- Nothing in this schema moves a publication between pages, so this can only
+  -- be something nothing here wrote. Refusing is cheaper than reasoning about
+  -- it, and 40001 says the one useful thing: read it again.
+  IF _pub.page_id IS DISTINCT FROM _owner THEN
+    RAISE EXCEPTION
+      'This publication changed pages while the cancellation was waiting for '
+      'its locks. Nothing was written; try again.'
+      USING ERRCODE = '40001';
+  END IF;
+
+  SELECT * INTO _page FROM public.pages WHERE id = _pub.page_id;
+
+  -- 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;
+$$;
+
+-- The scheduled path reaches the same second page the immediate one does, and
+-- reached it the same way: page first, reveal target second. The version is
+-- read without a lock to learn which page it belongs to, that page and every
+-- reveal target are locked together, and the version is then read again — a
+-- version that changed pages under us is not something this schema does, so it
+-- is refused rather than reasoned about.
+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;
+  _owner          uuid;
+  _keys           text[];
+  _targets        jsonb;
+  _relocked       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 pv.page_id INTO _owner FROM public.page_versions pv
+   WHERE pv.id = _version_id;
+  IF _owner IS NULL THEN
+    RAISE EXCEPTION 'Version not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  _keys := ARRAY(
+    SELECT DISTINCT btrim(r.value->>'key')
+      FROM jsonb_array_elements(COALESCE(_reveals, '[]'::jsonb)) AS r(value)
+     WHERE btrim(COALESCE(r.value->>'key', '')) <> '');
+
+  SELECT COALESCE(jsonb_object_agg(p.key, p.id), '{}'::jsonb) INTO _targets
+    FROM public.pages p
+   WHERE p.key = ANY (_keys) AND p.deleted_at IS NULL;
+
+  PERFORM app.cms_lock_pages(
+    ARRAY[_owner]
+      || ARRAY(SELECT t.v::uuid FROM jsonb_each_text(_targets) AS t(k, v)));
+
+  SELECT COALESCE(jsonb_object_agg(p.key, p.id), '{}'::jsonb) INTO _relocked
+    FROM public.pages p
+   WHERE p.key = ANY (_keys) AND p.deleted_at IS NULL;
+  IF _relocked IS DISTINCT FROM _targets THEN
+    RAISE EXCEPTION
+      'A page this schedule reveals was renamed, deleted or created while the '
+      'schedule was waiting for its locks. Nothing was written; try again.'
+      USING ERRCODE = '40001';
+  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;
+  IF _version.page_id IS DISTINCT FROM _owner THEN
+    RAISE EXCEPTION
+      'This version changed pages while the schedule was waiting for its '
+      'locks. Nothing was written; try again.'
+      USING ERRCODE = '40001';
+  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;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  PERFORM id FROM public.page_publications
+    WHERE page_id = _page.id AND is_active
+    ORDER BY id
+    FOR UPDATE;
+
+  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;
+$$;
+
+-- Duplicating a page was five round trips from the browser: read the source,
+-- read every key in the installation, read the source's blocks, insert a page,
+-- insert a version, update the pointer, write an audit row. Anything that went
+-- wrong after the third of those left a page with no content, or content with
+-- no pointer, or a copy nobody could account for — and nothing rolled any of it
+-- back. Here it is one transaction, and what it asks of the caller is what
+-- makes the copy honest:
+--
+--   * `_expected_version_id` is which version the editor was looking at;
+--   * `_expected_blocks_digest` is what that version *contained* when they
+--     looked. A version id cannot bind content on its own, because content
+--     under a stable version id is not immutable in this schema: the published
+--     migrations 20260730095256 and 20260811130318 both rewrite
+--     `page_versions.blocks` in place. So the digest is recomputed here, from
+--     the row, under the row's own lock, and a mismatch refuses the copy;
+--   * `_idempotency_key` is which duplication this is. A committed request
+--     whose response was lost on a slow link is ordinary, and without a key the
+--     retry silently makes a second copy — which, once §9 route claims exist,
+--     stops being a cosmetic annoyance and starts colliding for the same
+--     addresses as the first.
+--
+-- `_blocks` is what to write into the copy, which is not the same thing as what
+-- the source holds: the caller re-identifies every block so the two pages do
+-- not share block ids. The digest binds what it was derived *from*.
+CREATE OR REPLACE FUNCTION public.cms_duplicate_page(
+  _source_page_id         uuid,
+  _expected_version_id    uuid,
+  _expected_blocks_digest text,
+  _idempotency_key        uuid,
+  _key                    text,
+  _name                   text,
+  _blocks                 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();
+  _email      text;
+  _new_id     uuid := gen_random_uuid();
+  _prior      public.cms_page_duplicate_operations;
+  _copy       public.pages;
+  _source     public.pages;
+  _version    public.page_versions;
+  _version_id uuid;
+  _wanted_key text := btrim(COALESCE(_key, ''));
+  _wanted_nm  text := btrim(COALESCE(_name, ''));
+  _actual     text;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  IF _idempotency_key IS NULL THEN
+    RAISE EXCEPTION
+      'A duplication needs an idempotency key, so that a retry can be told '
+      'apart from a second copy.'
+      USING ERRCODE = '22023';
+  END IF;
+  IF _wanted_key = '' OR _wanted_nm = '' THEN
+    RAISE EXCEPTION 'A copy needs both an address and a name.'
+      USING ERRCODE = '22023';
+  END IF;
+  IF _source_page_id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  -- The source and the page that is about to exist, in id order. Locking an id
+  -- no row carries yet costs nothing and blocks nobody; it is written down so
+  -- that this function's lock set is stated in the same shape as every other
+  -- one, rather than remembered as an exception.
+  PERFORM app.cms_lock_pages(ARRAY[_source_page_id, _new_id]);
+
+  -- A retry is a retry, not a second copy. Two calls carrying the same key
+  -- cannot both be here at once: they are duplicating the same source, so the
+  -- lock above has already put one of them behind the other.
+  SELECT * INTO _prior FROM public.cms_page_duplicate_operations
+    WHERE idempotency_key = _idempotency_key;
+  IF _prior.idempotency_key IS NOT NULL THEN
+    SELECT * INTO _copy FROM public.pages WHERE id = _prior.created_page_id;
+    RETURN jsonb_build_object(
+      'pageId',     _prior.created_page_id,
+      'sourceId',   _prior.source_page_id,
+      'key',        _copy.key,
+      'name',       _copy.name,
+      'status',     _copy.status,
+      'versionId',  _copy.current_version_id,
+      'idempotent', true
+    );
+  END IF;
+
+  SELECT * INTO _source FROM public.pages
+    WHERE id = _source_page_id AND deleted_at IS NULL;
+  IF _source.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  -- Trashed pages keep their address, so a copy that took one would collide the
+  -- moment the original came back out of the trash.
+  IF EXISTS (SELECT 1 FROM public.pages WHERE key = _wanted_key) THEN
+    RAISE EXCEPTION
+      'A page already has the address "%", including in the trash.', _wanted_key
+      USING ERRCODE = '23505';
+  END IF;
+
+  IF _source.current_version_id IS DISTINCT FROM _expected_version_id THEN
+    RAISE EXCEPTION
+      'The page "%" was saved again while this copy was being prepared, so the '
+      'copy would not be of what was on screen. Reopen the page and copy it '
+      'again.', _source.key
+      USING ERRCODE = '22023';
+  END IF;
+
+  IF _source.current_version_id IS NULL THEN
+    -- Nothing saved means nothing to bind, and a digest for content that does
+    -- not exist is a caller that thinks it is copying something else.
+    IF _expected_blocks_digest IS NOT NULL THEN
+      RAISE EXCEPTION
+        'The page "%" has no saved content, so there is no block digest for it '
+        'to match.', _source.key
+        USING ERRCODE = '22023';
+    END IF;
+  ELSE
+    -- Read `FOR UPDATE` and never written: the copy must not be able to change
+    -- what it was copied from, and the lock is what makes the digest below an
+    -- answer about the row rather than about a moment that has passed.
+    SELECT * INTO _version FROM public.page_versions
+      WHERE id = _source.current_version_id
+      FOR UPDATE;
+    IF _version.id IS NULL THEN
+      RAISE EXCEPTION 'Version not found' USING ERRCODE = 'P0002';
+    END IF;
+
+    _actual := public.cms_digest(_version.blocks);
+    IF _expected_blocks_digest IS NULL OR _actual <> _expected_blocks_digest THEN
+      RAISE EXCEPTION
+        'The content of "%" is not what this copy was built from (% rather '
+        'than %). Reopen the page and copy it again.',
+        _source.key, _actual, COALESCE(_expected_blocks_digest, 'nothing')
+        USING ERRCODE = '22023';
+    END IF;
+  END IF;
+
+  _email := public.cms_actor_email(_uid, _actor_email);
+
+  -- The copy starts as a draft whatever the source's status is: it has no
+  -- publication rows, so there is nothing for it to be published *as*.
+  INSERT INTO public.pages (id, key, name, is_system, status, updated_by)
+  VALUES (_new_id, _wanted_key, _wanted_nm, false, 'draft', _uid);
+
+  INSERT INTO public.page_versions
+    (page_id, version_no, blocks, note, created_by, created_by_email)
+  VALUES
+    (_new_id, 1, COALESCE(_blocks, '[]'::jsonb),
+     format('Copied from "%s"', _source.name), _uid, _email)
+  RETURNING id INTO _version_id;
+
+  UPDATE public.pages
+     SET current_version_id = _version_id,
+         updated_at         = now(),
+         updated_by         = _uid
+   WHERE id = _new_id;
+
+  -- The ledger entry is written in the same transaction as the page it accounts
+  -- for, which is the whole of what makes it trustworthy: if anything after
+  -- this rolls back, the key is unspent and the retry does the entire thing
+  -- again, exactly as it should.
+  INSERT INTO public.cms_page_duplicate_operations
+    (idempotency_key, source_page_id, created_page_id)
+  VALUES (_idempotency_key, _source.id, _new_id);
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid, _email, 'page.duplicate', 'pages', _new_id::text,
+    COALESCE(_audit, '{}'::jsonb)
+      || jsonb_build_object(
+           'key', _wanted_key, 'source_key', _source.key,
+           'sourceId', _source.id, 'versionId', _version_id,
+           'idempotencyKey', _idempotency_key,
+           'description', format('Duplicated the page "%s" as the draft "%s" (%s).',
+                                 _source.name, _wanted_nm, _wanted_key))
+  );
+
+  RETURN jsonb_build_object(
+    'pageId',     _new_id,
+    'sourceId',   _source.id,
+    'key',        _wanted_key,
+    'name',       _wanted_nm,
+    'status',     'draft',
+    'versionId',  _version_id,
+    'idempotent', false
+  );
+END;
+$$;
+
+-- 10. The route authority, and the host knowledge it answers against ---------
+--
+-- Section 6 created the two tables and said nothing writes them yet. These are
+-- the two functions that do, and the order between them is not interchangeable.
+-- The registry has to exist before a claim can be checked against it, because
+-- the check is what a claim is validated by; and the reserved rows the registry
+-- materialises have to be present before a page can be refused for sitting on
+-- one, because that refusal is a primary-key violation and not a list lookup.
+
+-- The host writes down what the package cannot infer.
+--
+-- The database has never been able to see the host's route table: which paths
+-- are reserved for the API, the backoffice, the sitemap and the asset roots,
+-- which locales exist, which domain serves which locale, whether a trailing
+-- slash is kept, whether case is folded. Every one of those is a decision the
+-- application makes at build time, and every one of them changes what two URLs
+-- have to agree about before they count as the same URL. So the deploy step
+-- writes them here once per release, and everything that normalizes a URL
+-- afterwards reads that one copy rather than forming its own opinion.
+--
+-- Reserved paths become claims of their own — one row per origin per path,
+-- kind = 'reserved', owned by no page. That is the whole reason they are
+-- materialised rather than checked: a page that tries to sit on /api is
+-- refused by the same primary key that refuses a page sitting on another
+-- page's path, with the same error, through the same code. A second list of
+-- forbidden strings, consulted separately, is a second opinion waiting to
+-- disagree with the first.
+--
+-- This one is not for editors. It is called by a deploy step, which has no
+-- signed-in user, so the grant below is the authority rather than is_staff --
+-- and the check here refuses a signed-in caller who is not staff, so that a
+-- grant widened by mistake still does not hand the route map to a visitor.
+CREATE OR REPLACE FUNCTION public.cms_route_registry_set(
+  _release_sha text,
+  _snapshot    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();
+  _email    text;
+  _sha      text := btrim(COALESCE(_release_sha, ''));
+  _origins  text[];
+  _paths    text[];
+  _origin   text;
+  _path     text;
+  _policy   text;
+  _reserved int := 0;
+  _holder   record;
+BEGIN
+  IF _uid IS NOT NULL AND NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  _email := public.cms_actor_email(_uid, _actor_email);
+
+  IF _sha = '' THEN
+    RAISE EXCEPTION
+      'A route registry needs the release it describes, so that a claim '
+      'normalized under it can be told apart from one normalized under the '
+      'release before.'
+      USING ERRCODE = '22023';
+  END IF;
+  IF _snapshot IS NULL OR jsonb_typeof(_snapshot) <> 'object' THEN
+    RAISE EXCEPTION 'The route registry snapshot has to be an object.'
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- Fail closed on the mapping, and name the entry that failed. A deployment
+  -- whose locale-to-domain map has one bad entry has to stop, because the
+  -- alternative -- quietly serving that locale from the default origin -- is
+  -- a site that claims one set of URLs and serves another, and nobody finds
+  -- out until a canonical tag points somewhere that was never deployed.
+  IF jsonb_typeof(_snapshot->'origins') <> 'array'
+     OR jsonb_array_length(_snapshot->'origins') = 0 THEN
+    RAISE EXCEPTION
+      'The route registry has to name at least one origin. There is no '
+      'single-origin fallback: a mapping that cannot be read is a mapping '
+      'nobody has checked.'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT array_agg(value ORDER BY value) INTO _origins
+    FROM jsonb_array_elements_text(_snapshot->'origins') AS t(value);
+
+  FOREACH _origin IN ARRAY _origins LOOP
+    IF _origin IS NULL OR btrim(_origin) = '' THEN
+      RAISE EXCEPTION 'The route registry names an empty origin.'
+        USING ERRCODE = '22023';
+    END IF;
+    IF _origin <> lower(_origin) OR _origin LIKE '%/' THEN
+      RAISE EXCEPTION
+        'The origin % is not canonical. Scheme and host are lowercased and '
+        'the origin carries no trailing slash; the port stays, because '
+        'https://x and https://x:8443 are different sites.', _origin
+        USING ERRCODE = '22023';
+    END IF;
+    IF _origin NOT LIKE 'http://%' AND _origin NOT LIKE 'https://%' THEN
+      RAISE EXCEPTION
+        'The origin % names no scheme. An origin without one cannot be '
+        'compared with the origin a request arrived on.', _origin
+        USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+
+  IF _snapshot ? 'trailingSlash' THEN
+    _policy := _snapshot->>'trailingSlash';
+    IF _policy IS NULL OR _policy NOT IN ('never', 'always') THEN
+      RAISE EXCEPTION
+        'The trailing-slash policy is % and has to be never or always. A '
+        'policy nobody can read is a policy two writers will read '
+        'differently.', COALESCE(_policy, 'null')
+        USING ERRCODE = '22023';
+    END IF;
+  END IF;
+
+  IF _snapshot ? 'reservedPaths' THEN
+    IF jsonb_typeof(_snapshot->'reservedPaths') <> 'array' THEN
+      RAISE EXCEPTION 'The registry''s reserved paths have to be an array.'
+        USING ERRCODE = '22023';
+    END IF;
+    SELECT array_agg(DISTINCT value ORDER BY value) INTO _paths
+      FROM jsonb_array_elements_text(_snapshot->'reservedPaths') AS t(value);
+  END IF;
+  _paths := COALESCE(_paths, ARRAY[]::text[]);
+
+  FOREACH _path IN ARRAY _paths LOOP
+    IF _path IS NULL OR _path NOT LIKE '/%' THEN
+      RAISE EXCEPTION
+        'The reserved path % is not rooted. A reserved path is compared '
+        'against a served path, and those always begin at the root.',
+        COALESCE(_path, 'null')
+        USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+
+  INSERT INTO public.cms_route_registry (id, release_sha, snapshot, updated_at)
+  VALUES (1, _sha, _snapshot, now())
+  ON CONFLICT (id) DO UPDATE
+     SET release_sha = EXCLUDED.release_sha,
+         snapshot    = EXCLUDED.snapshot,
+         updated_at  = EXCLUDED.updated_at;
+
+  -- Rewritten rather than merged, for the same reason a page's claims are:
+  -- the snapshot is the whole truth about what this release reserves, so a
+  -- path dropped from it stops being reserved in the same statement that stops
+  -- describing it. Merging would leave yesterday's reservations standing with
+  -- nothing left that says why.
+  DELETE FROM public.cms_route_claims WHERE kind = 'reserved';
+
+  BEGIN
+    INSERT INTO public.cms_route_claims (origin, path, kind, page_id, locale, registry_sha)
+    SELECT o.origin, p.path, 'reserved', NULL, NULL, _sha
+      FROM unnest(_origins) AS o(origin)
+     CROSS JOIN unnest(_paths) AS p(path);
+    GET DIAGNOSTICS _reserved = ROW_COUNT;
+  EXCEPTION WHEN unique_violation THEN
+    -- A page is already sitting where this release wants to reserve. The
+    -- deploy step has to stop: the alternative is a release that serves its
+    -- own API from one origin and somebody's page from another.
+    SELECT c.origin, c.path, c.kind, pg.key INTO _holder
+      FROM public.cms_route_claims c
+      LEFT JOIN public.pages pg ON pg.id = c.page_id
+     WHERE c.kind <> 'reserved'
+       AND c.origin = ANY (_origins)
+       AND c.path   = ANY (_paths)
+     ORDER BY c.origin, c.path
+     LIMIT 1;
+    RAISE EXCEPTION
+      'The path % on % is reserved by this release and already claimed by %. '
+      'Move or delete that claim and deploy again; the registry is not '
+      'written.',
+      COALESCE(_holder.path, '?'), COALESCE(_holder.origin, '?'),
+      COALESCE('the ' || _holder.kind || ' "' || _holder.key || '"', 'another claim')
+      USING ERRCODE = '23505';
+  END;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid, _email, 'route.registry', 'cms_route_registry', '1',
+    COALESCE(_audit, '{}'::jsonb)
+      || jsonb_build_object(
+           'releaseSha', _sha,
+           'origins', to_jsonb(_origins),
+           'reserved', _reserved,
+           'description', format(
+             'Wrote the route registry for release %s: %s origin(s), %s reserved claim(s).',
+             _sha, array_length(_origins, 1), _reserved))
+  );
+
+  RETURN jsonb_build_object(
+    'ok',         true,
+    'releaseSha', _sha,
+    'origins',    to_jsonb(_origins),
+    'reserved',   _reserved
+  );
+END;
+$$;
+
+-- One page's routes, swapped in one transaction.
+--
+-- Read-then-write cannot be made correct by ordering. Two editors renaming two
+-- pages to the same slug both read the path as free, both write, and the site
+-- now serves two pages at one URL with nothing in the database that disagrees.
+-- So nothing here reads to decide. The page's whole claim set is deleted and
+-- re-inserted, and the primary key on (origin, path) is what refuses the
+-- second writer -- which means a writer that skips every precaution below
+-- still cannot double-claim.
+--
+-- The advisory lock is a fairness device and nothing more. It makes concurrent
+-- writers queue in a predictable order per origin instead of interleaving into
+-- an avoidable failure, and it is taken after the page lock, because the tier
+-- order in section 9 is pages first and a route claim does not get to invert
+-- it. One lock per distinct origin, in sorted order, so two sessions claiming
+-- across the same two origins in opposite directions queue rather than
+-- deadlock. Two origins that hash alike share a queue; that costs a little
+-- waiting and no correctness, because the queue was never the authority.
+--
+-- A collision comes back as a value rather than an exception. It is an
+-- ordinary editing outcome -- somebody else got there first -- and raising
+-- would take down whatever transaction the caller had already built around
+-- this call. The insert still rolls back, so the page keeps the claims it had.
+CREATE OR REPLACE FUNCTION public.cms_route_claim_apply(
+  _page_id               uuid,
+  _claims                jsonb,
+  _expected_registry_sha 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();
+  _email      text;
+  _page       public.pages;
+  _registry   public.cms_route_registry;
+  _origins    text[];
+  _origin     text;
+  _claim      jsonb;
+  _repeat     record;
+  _released   int := 0;
+  _claimed    int := 0;
+  _collisions jsonb;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  _email := public.cms_actor_email(_uid, _actor_email);
+
+  IF _page_id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+  IF _claims IS NULL OR jsonb_typeof(_claims) <> 'array' THEN
+    RAISE EXCEPTION
+      'A claim set is an array, and an empty one is how a page says it serves '
+      'nothing. Null is not the same statement.'
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO _registry FROM public.cms_route_registry WHERE id = 1;
+  IF _registry.id IS NULL THEN
+    RAISE EXCEPTION
+      'No route registry has been written, so there is nothing to normalize '
+      'this claim against. The deploy step calls cms_route_registry_set once '
+      'the application is up.'
+      USING ERRCODE = '22023';
+  END IF;
+  -- A stale registry fails closed. Validating tomorrow's claim against
+  -- yesterday's route map finds no collision precisely when the map is the
+  -- thing that changed, which is the one case where finding none is wrong.
+  IF _registry.release_sha IS DISTINCT FROM _expected_registry_sha THEN
+    RAISE EXCEPTION
+      'This claim was normalized against release %, and the site is now on '
+      '%. Reload the route registry and normalize again.',
+      COALESCE(_expected_registry_sha, 'nothing'), _registry.release_sha
+      USING ERRCODE = '22023';
+  END IF;
+
+  SELECT array_agg(value ORDER BY value) INTO _origins
+    FROM jsonb_array_elements_text(_registry.snapshot->'origins') AS t(value);
+  _origins := COALESCE(_origins, ARRAY[]::text[]);
+
+  FOR _claim IN SELECT value FROM jsonb_array_elements(_claims) LOOP
+    IF COALESCE(_claim->>'origin', '') = ''
+       OR COALESCE(_claim->>'path', '') = '' THEN
+      RAISE EXCEPTION 'Every claim needs an origin and a path.'
+        USING ERRCODE = '22023';
+    END IF;
+    IF _claim->>'origin' <> lower(_claim->>'origin')
+       OR _claim->>'origin' LIKE '%/' THEN
+      RAISE EXCEPTION
+        'The origin % is not canonical: lowercase it and drop the trailing '
+        'slash, but keep the port.', _claim->>'origin'
+        USING ERRCODE = '22023';
+    END IF;
+    IF _claim->>'path' NOT LIKE '/%' THEN
+      RAISE EXCEPTION 'The path % is not rooted.', _claim->>'path'
+        USING ERRCODE = '22023';
+    END IF;
+    IF COALESCE(_claim->>'kind', '') NOT IN ('page', 'redirect') THEN
+      RAISE EXCEPTION
+        'A page claims paths as a page or as a redirect. Reserved paths '
+        'belong to the release and are written by cms_route_registry_set.'
+        USING ERRCODE = '22023';
+    END IF;
+    -- An origin the registry does not serve has no reserved rows on it, so a
+    -- claim there would find /api free. That is the invalid-mapping case, and
+    -- it fails closed here rather than being served from somewhere else.
+    IF NOT (_claim->>'origin' = ANY (_origins)) THEN
+      RAISE EXCEPTION
+        'This release serves %, and the claim names %. A locale mapped to a '
+        'domain the release does not serve is refused rather than served '
+        'from the default origin.',
+        array_to_string(_origins, ', '), _claim->>'origin'
+        USING ERRCODE = '22023';
+    END IF;
+  END LOOP;
+
+  -- Two claims at one address inside one set would raise the same 23505 as a
+  -- real collision and find no other holder, which would answer "somebody
+  -- else has it" about nobody. It is a caller mistake and says so.
+  SELECT e.value->>'origin' AS origin, e.value->>'path' AS path INTO _repeat
+    FROM jsonb_array_elements(_claims) AS e(value)
+   GROUP BY 1, 2
+  HAVING count(*) > 1
+   LIMIT 1;
+  IF _repeat.path IS NOT NULL THEN
+    RAISE EXCEPTION
+      'This claim set names % on % twice. One page cannot serve one URL two '
+      'ways.', _repeat.path, _repeat.origin
+      USING ERRCODE = '22023';
+  END IF;
+
+  -- Pages first, as everywhere else in this file.
+  PERFORM app.cms_lock_pages(ARRAY[_page_id]);
+
+  SELECT * INTO _page FROM public.pages
+   WHERE id = _page_id AND deleted_at IS NULL;
+  IF _page.id IS NULL THEN
+    RAISE EXCEPTION 'Page not found' USING ERRCODE = 'P0002';
+  END IF;
+
+  SELECT array_agg(DISTINCT e.value->>'origin' ORDER BY e.value->>'origin')
+    INTO _origins
+    FROM jsonb_array_elements(_claims) AS e(value);
+  FOREACH _origin IN ARRAY COALESCE(_origins, ARRAY[]::text[]) LOOP
+    PERFORM pg_advisory_xact_lock(hashtext('cms_route_claims'), hashtext(_origin));
+  END LOOP;
+
+  BEGIN
+    DELETE FROM public.cms_route_claims WHERE page_id = _page_id;
+    GET DIAGNOSTICS _released = ROW_COUNT;
+
+    INSERT INTO public.cms_route_claims (origin, path, kind, page_id, locale, registry_sha)
+    SELECT e.value->>'origin',
+           e.value->>'path',
+           e.value->>'kind',
+           _page_id,
+           NULLIF(e.value->>'locale', ''),
+           _registry.release_sha
+      FROM jsonb_array_elements(_claims) AS e(value);
+    GET DIAGNOSTICS _claimed = ROW_COUNT;
+  EXCEPTION WHEN unique_violation THEN
+    -- The delete above is rolled back with the insert, so the page still holds
+    -- what it held. What follows is a diagnostic, not the decision: the key
+    -- already made that, and this only reads back who won.
+    SELECT jsonb_agg(jsonb_build_object(
+             'origin', held.origin,
+             'path',   held.path,
+             'kind',   held.kind,
+             'locale', held.locale,
+             'heldBy', CASE WHEN held.page_id IS NULL THEN NULL
+                            ELSE jsonb_build_object('pageId', held.page_id,
+                                                    'key',    holder.key,
+                                                    'name',   holder.name)
+                       END)
+             ORDER BY held.origin, held.path)
+      INTO _collisions
+      FROM public.cms_route_claims held
+      LEFT JOIN public.pages holder ON holder.id = held.page_id
+     WHERE held.page_id IS DISTINCT FROM _page_id
+       AND (held.origin, held.path) IN (
+             SELECT e.value->>'origin', e.value->>'path'
+               FROM jsonb_array_elements(_claims) AS e(value));
+
+    RETURN jsonb_build_object(
+      'ok',          false,
+      'pageId',      _page_id,
+      'registrySha', _registry.release_sha,
+      'collisions',  COALESCE(_collisions, '[]'::jsonb)
+    );
+  END;
+
+  INSERT INTO public.audit_logs (actor_id, actor_email, action, entity, entity_id, meta)
+  VALUES (
+    _uid, _email, 'route.claim', 'cms_route_claims', _page_id::text,
+    COALESCE(_audit, '{}'::jsonb)
+      || jsonb_build_object(
+           'key', _page.key,
+           'registrySha', _registry.release_sha,
+           'claimed', _claimed,
+           'released', _released,
+           'claims', _claims,
+           'description', format(
+             'The page "%s" now claims %s route(s); %s released.',
+             _page.name, _claimed, _released))
+  );
+
+  RETURN jsonb_build_object(
+    'ok',          true,
+    'pageId',      _page_id,
+    'registrySha', _registry.release_sha,
+    'claimed',     _claimed,
+    'released',    _released,
+    'collisions',  '[]'::jsonb
+  );
+END;
+$$;
+
+-- 11. Closing the run ---------------------------------------------------------
+--
+-- Separate from the block above on purpose. Until this runs, the run says
+-- 'applying', which is not evidence of anything: cms_publication_review_is_-
+-- complete refuses it, and a caller asking "was this page scanned?" gets no
+-- for every page. The transition to 'applied' is the single moment the answer
+-- changes, and it happens once, at the end, when there is nothing left to do.
+--
+-- If anything above raised, this never runs and the whole transaction is gone
+-- — the tables included. There is no state in which the schema exists and the
+-- review does not.
+DO $$
+DECLARE
+  _run_id  uuid;
+  _scanned bigint;
+  _counts  jsonb;
+BEGIN
+  -- Nothing to close, because the block above short-circuited on a database
+  -- where the review already ran. Checked before the STRICT select, which
+  -- would otherwise turn a harmless second run of this file into an error.
+  IF NOT EXISTS (SELECT 1 FROM public.cms_publication_review_runs
+                  WHERE state = 'applying') THEN
+    RETURN;
+  END IF;
+
+  -- STRICT rather than a plain SELECT: "exactly one run is being applied" is
+  -- an invariant of this file, and if it is ever false the right outcome is a
+  -- refusal, not finalising whichever row came back first.
+  SELECT id INTO STRICT _run_id
+    FROM public.cms_publication_review_runs
+   WHERE state = 'applying';
+
+  SELECT coalesce(jsonb_object_agg(classification, n), '{}'::jsonb), coalesce(sum(n), 0)
+    INTO _counts, _scanned
+    FROM (
+      SELECT classification, count(*) AS n
+        FROM public.cms_publication_review_items
+       WHERE run_id = _run_id
+       GROUP BY classification
+    ) tally;
+
+  UPDATE public.cms_publication_review_runs
+     SET state              = 'applied',
+         scanned_page_count = _scanned,
+         counts             = _counts,
+         scan_completed_at  = now(),
+         applied_by_email   = coalesce(applied_by_email, 'migration@cms-platform.invalid'),
+         applied_at         = now()
+   WHERE id = _run_id;
+
+  -- The predicate the rest of the system trusts, asserted here rather than
+  -- hoped for. A run that does not satisfy it is not evidence, so shipping one
+  -- would mean shipping a schema whose central question has no answer.
+  IF NOT public.cms_publication_review_is_complete(_run_id) THEN
+    RAISE EXCEPTION 'the review run did not finalise cleanly'
+      USING ERRCODE = 'P0002',
+            DETAIL = format('run %s scanned %s of %s pages', _run_id, _scanned,
+                            (SELECT expected_page_count
+                               FROM public.cms_publication_review_runs WHERE id = _run_id));
+  END IF;
+END
+$$;
+
+-- 12. Who may reach any of this ----------------------------------------------
+--
+-- Last, and deliberately so: nothing above can be reached by anybody until the
+-- review has been written and closed, because a half-applied transaction is
+-- never visible to another session at all.
+
+-- The two capability helpers are the one thing here an unauthenticated caller
+-- has to be able to reach: the health endpoint asks what contract version the
+-- schema offers before anybody has signed in, and a health check that cannot
+-- ask fails closed on every request. They are SECURITY DEFINER for exactly
+-- that reason — the answer is public, the table it is assembled from is not,
+-- and opening the function is a much smaller thing to open than the table.
+--
+-- cms_installation_id is SECURITY DEFINER for the same mechanical reason but
+-- is not public: nothing unauthenticated needs to know which installation it
+-- is talking to, and an identifier that is only interesting to an attacker
+-- correlating backups is not worth handing out for free.
+-- PostgreSQL grants EXECUTE on a new function to PUBLIC by default, and
+-- revoking it from a named role does not take that away — so on a SECURITY
+-- DEFINER function, revoking from `anon` alone leaves it callable by `anon`.
+-- The three below are restricted, so they say so to PUBLIC explicitly, in the
+-- same shape the rest of this repository's migrations use. The two capability
+-- helpers keep the default on purpose: an unauthenticated health check has to
+-- reach them, including on a self-host that has no hosted roles at all.
+REVOKE ALL ON FUNCTION public.cms_installation_id() FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_publication_review_is_complete(uuid) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_publication_review_current_run() FROM PUBLIC;
+
+-- The lock helper is not on any of those lists, because it is not for callers
+-- at all. It lives in `app`, which PostgREST does not expose, and this takes
+-- away the EXECUTE that PostgreSQL hands PUBLIC on every new function — after
+-- which the only things that can call it are the SECURITY DEFINER functions in
+-- this schema, which run as the owner. There is no grant to anon,
+-- authenticated or service_role anywhere in this file, and the loop below
+-- revokes from each of them by name as well, so that adding one later has to
+-- be a deliberate act rather than an oversight.
+REVOKE ALL ON FUNCTION app.cms_lock_pages(uuid[]) FROM PUBLIC;
+
+-- The one new function in this migration a person calls. It follows the rule
+-- migration 20260904160000 set for every other write: away from PUBLIC here,
+-- away from `anon` by name below, and to the two roles that already hold the
+-- rest of the page lifecycle. A self-hosted installation grants it to the role
+-- its application connects as, alongside the statements `docs/PAGES.md` lists:
+--
+--   GRANT EXECUTE ON FUNCTION public.cms_duplicate_page(
+--     uuid, uuid, text, uuid, text, text, jsonb, jsonb, text) TO cms_app;
+REVOKE ALL ON FUNCTION public.cms_duplicate_page(
+  uuid, uuid, text, uuid, text, text, jsonb, jsonb, text) FROM PUBLIC;
+
+-- The claim writer follows the same rule as the duplicate above: staff, in the
+-- application's own role. The registry writer does not, and is the one
+-- function in this file granted to service_role alone. It is called by a
+-- deploy step that has no signed-in user, so the grant is what stands in for
+-- is_staff — and the route map is precisely the thing an editor session must
+-- not be able to rewrite, because rewriting it is how every claim already
+-- stored stops meaning what it meant.
+REVOKE ALL ON FUNCTION public.cms_route_claim_apply(
+  uuid, jsonb, text, jsonb, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_route_registry_set(
+  text, jsonb, jsonb, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.cms_publication_review_reconcile(
+  text, text, text) FROM PUBLIC;
+
+DO $$
+DECLARE
+  _role      text;
+  _signature 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 ARRAY[
+      'public.cms_platform_capability()',
+      'public.cms_schema_capability(text)',
+      'public.cms_canonical_json(jsonb)',
+      'public.cms_digest(jsonb)'
+    ] LOOP
+      EXECUTE format('REVOKE ALL ON FUNCTION %s FROM %I', _signature, _role);
+      EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO %I', _signature, _role);
+    END LOOP;
+
+    FOREACH _signature IN ARRAY ARRAY[
+      'public.cms_installation_id()',
+      'public.cms_publication_review_is_complete(uuid)',
+      'public.cms_publication_review_current_run()'
+    ] 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;
+
+    FOREACH _signature IN ARRAY ARRAY[
+      'public.cms_duplicate_page(uuid, uuid, text, uuid, text, text, jsonb, jsonb, text)',
+      'public.cms_route_claim_apply(uuid, jsonb, text, jsonb, text)'
+    ] 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;
+
+    FOREACH _signature IN ARRAY ARRAY[
+      'public.cms_route_registry_set(text, jsonb, jsonb, text)',
+      'public.cms_publication_review_reconcile(text, text, text)'
+    ] LOOP
+      EXECUTE format('REVOKE ALL ON FUNCTION %s FROM %I', _signature, _role);
+      IF _role = 'service_role' THEN
+        EXECUTE format('GRANT EXECUTE ON FUNCTION %s TO %I', _signature, _role);
+      END IF;
+    END LOOP;
+
+    -- Revoked from every client role and granted to none of them.
+    EXECUTE format('REVOKE ALL ON FUNCTION app.cms_lock_pages(uuid[]) FROM %I', _role);
+  END LOOP;
+END
+$$;