@acornly/adapter-supabase 0.1.0 → 0.2.1

package/supabase/install.sql

@@ -0,0 +1,2295 @@
+-- @acornly/adapter-supabase installer, through migration 20261011170000.
+--
+-- Generated by scripts/build-install.mjs from supabase/migrations; do not edit it by hand.
+--
+-- Run the whole file in the project's database, as the owner: paste it into the dashboard's SQL
+-- editor, or `psql -v ON_ERROR_STOP=1 "$DATABASE_URL" -f install.sql`. It runs in one transaction and applies only
+-- the migrations it has not applied before, so run it again, as it is, after each upgrade of the
+-- package. acornly_meta.migrations records what it applied, and when.
+--
+-- A database that already has the migrations from `supabase db push` is recognised from the
+-- Supabase CLI's history. One where they were pasted in by hand is refused until you record which
+-- ones it has (the error says how).
+
+begin;
+
+-- One installer at a time.
+select pg_advisory_xact_lock(hashtext('acornly_install'));
+
+create schema if not exists acornly_meta;
+revoke all on schema acornly_meta from public;
+create table if not exists acornly_meta.migrations (
+  version text primary key,
+  name text not null,
+  applied_at timestamptz not null default now()
+);
+revoke all on table acornly_meta.migrations from public;
+
+do $acornly_install$
+begin
+  if exists (select 1 from acornly_meta.migrations) then
+    return;
+  end if;
+  -- Applied by `supabase db push` from copies of these files: the same version, and the same
+  -- name where the CLI records one, so a site's own migration with the same version is not taken
+  -- for Acornly's.
+  if to_regclass('supabase_migrations.schema_migrations') is not null then
+    if exists (select 1 from information_schema.columns c
+                where c.table_schema = 'supabase_migrations' and c.table_name = 'schema_migrations'
+                  and c.column_name = 'name') then
+      insert into acornly_meta.migrations (version, name)
+        select v.version, v.name
+          from (values
+      ('20261005090000', 'contexthive_annotations'),
+    ('20261005130000', 'contexthive_threads'),
+    ('20261010070000', 'acornly_names'),
+    ('20261011080000', 'acornly_delete_node_grants'),
+    ('20261011150000', 'acornly_parent_ids'),
+    ('20261011170000', 'acornly_pdf_document_keys')) v (version, name)
+         where exists (select 1 from supabase_migrations.schema_migrations h
+                        where h.version = v.version and h.name = v.name);
+    else
+      insert into acornly_meta.migrations (version, name)
+        select v.version, v.name
+          from (values
+      ('20261005090000', 'contexthive_annotations'),
+    ('20261005130000', 'contexthive_threads'),
+    ('20261010070000', 'acornly_names'),
+    ('20261011080000', 'acornly_delete_node_grants'),
+    ('20261011150000', 'acornly_parent_ids'),
+    ('20261011170000', 'acornly_pdf_document_keys')) v (version, name)
+         where v.version in (select h.version from supabase_migrations.schema_migrations h);
+    end if;
+  end if;
+  if not exists (select 1 from acornly_meta.migrations)
+     and (to_regclass('public.acornly_annotations') is not null
+          or to_regclass('public.contexthive_annotations') is not null) then
+    raise exception 'Acornly''s tables are here, but not which of its migrations made them'
+      using hint = 'Record each migration file already applied, then run the installer again: '
+        || 'create schema if not exists acornly_meta; '
+        || 'create table if not exists acornly_meta.migrations (version text primary key, name text not null, '
+        || 'applied_at timestamptz not null default now()); '
+        || 'insert into acornly_meta.migrations (version, name) values (''<version>'', ''<name>''); '
+        || 'the version and name are the file''s name, as in 20261005090000_contexthive_annotations.sql.';
+  end if;
+end
+$acornly_install$;
+
+-- 20261005090000_contexthive_annotations.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261005090000') then
+    raise notice 'acornly: applying %', '20261005090000_contexthive_annotations.sql';
+    execute $acornly_migration$
+-- ContextHive notes in a site's own Supabase project (contexthive-adapter-supabase).
+--
+-- This is not the ContextHive Cloud schema in /supabase: a site that runs notes
+-- on its own project applies this file (and later files in this folder) to that
+-- project. Everything it creates is prefixed with `contexthive`, so it can sit
+-- next to the site's own tables.
+--
+-- Rules this migration encodes:
+--
+-- * The stored W3C annotation (`annotation`) is the source of truth. The
+--   columns the policies and indexes use (`id`, `scope`, `document`,
+--   `audience`, `thread_root_id`, `modified`) are copied from it by a trigger
+--   on every write, so a client can never make them disagree.
+-- * The database owns `rev`: a new note starts at 1 and every update adds one.
+--   The adapter updates `where rev = <expected>`, so one of two concurrent
+--   edits wins and the other sees a conflict.
+-- * Clients may write only the `annotation` column. `creator_id` is the
+--   signed-in user, set by the trigger, and is the author a site should trust
+--   (the annotation's own `creator` field is whatever the client sent).
+-- * A signed-in user may write only to scopes the site lists in
+--   `contexthive_scopes`, plus their own `user:<id>` scope.
+-- * Audiences: `private` (only the creator reads it) and `public` (everyone
+--   signed in reads it; anonymous visitors too where the scope allows it).
+--   Other audience kinds need ContextHive Cloud and are refused.
+-- * Replies (`ext.threadRoot` set) live in their root's scope and document,
+--   can narrow the root's audience but never widen it, and are hidden from
+--   others whenever they cannot read the root.
+
+-- ---------------------------------------------------------------------------
+-- Internal schema: helpers for the policies and the trigger. It is not in the
+-- API's exposed schemas, and only the helpers below are executable by clients.
+-- ---------------------------------------------------------------------------
+
+create schema if not exists contexthive_private;
+revoke all on schema contexthive_private from public;
+grant usage on schema contexthive_private to anon, authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- Tables
+-- ---------------------------------------------------------------------------
+
+-- The app and web scopes this site accepts notes in, managed by the site with
+-- SQL or the dashboard (clients have no access). For example:
+--   insert into public.contexthive_scopes (scope) values ('app:my-site');
+--   insert into public.contexthive_scopes (scope, anonymous_read)
+--     values ('web:example.com', true);
+create table public.contexthive_scopes (
+  scope text primary key check (scope ~ '^(app|web):.+$'),
+  -- Whether visitors who are not signed in can read the public notes in this scope.
+  anonymous_read boolean not null default false
+);
+
+alter table public.contexthive_scopes enable row level security;
+revoke all on table public.contexthive_scopes from anon, authenticated;
+
+create table public.contexthive_annotations (
+  id text primary key check (char_length(id) between 1 and 255),
+  -- `app:<appId>`, `web:<registrable domain>` or `user:<user id>`.
+  scope text not null check (scope ~ '^(app|web|user):.+$'),
+  -- The `<appId>` of an app scope, for the site's own queries.
+  app_id text generated always as (
+    case when scope like 'app:%' then substr(scope, 5) end
+  ) stored,
+  -- The canonical document URL, `target.source`.
+  document text not null check (document <> ''),
+  creator_id uuid not null references auth.users (id) on delete cascade,
+  audience text not null check (audience in ('private', 'public')),
+  thread_root_id text references public.contexthive_annotations (id) on delete cascade,
+  modified timestamptz not null,
+  rev integer not null check (rev >= 1),
+  annotation jsonb not null check (
+    jsonb_typeof(annotation) = 'object' and octet_length(annotation::text) <= 65536
+  ),
+
+  constraint contexthive_annotations_user_scope_is_creator check (
+    scope !~ '^user:' or scope = 'user:' || creator_id::text
+  ),
+  constraint contexthive_annotations_not_own_root check (thread_root_id is distinct from id)
+);
+
+-- `list`: one document's notes in one scope, optionally modified after a time.
+create index contexthive_annotations_page_idx
+  on public.contexthive_annotations (scope, document, modified);
+-- Delta sync across documents.
+create index contexthive_annotations_modified_idx on public.contexthive_annotations (modified);
+create index contexthive_annotations_thread_idx
+  on public.contexthive_annotations (thread_root_id) where thread_root_id is not null;
+-- Deleting a user cascades to their notes.
+create index contexthive_annotations_creator_idx on public.contexthive_annotations (creator_id);
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+-- Whether the caller is a signed-in user. Supabase's anonymous sign-ins get a
+-- user id too, but count as visitors here: they read like anyone not signed in
+-- and write nothing.
+create function contexthive_private.signed_in()
+returns boolean
+language sql
+stable
+set search_path = ''
+as $$
+  select auth.uid() is not null
+    and not coalesce((auth.jwt() ->> 'is_anonymous')::boolean, false)
+$$;
+
+-- Whether the request comes from the site's own server code: the service_role
+-- key, or the owner in SQL. Every other role is a client. Decided from the
+-- request's role, which a security-definer function does not change, so a
+-- site function owned by postgres still counts its client caller as a client.
+create function contexthive_private.trusted_caller()
+returns boolean
+language sql
+stable
+set search_path = ''
+as $$
+  select coalesce(nullif(current_setting('role', true), 'none'), session_user::text)
+    in ('service_role', 'postgres', 'supabase_admin')
+$$;
+
+-- Whether the caller may read public notes in `note_scope`: anyone signed in,
+-- and anonymous visitors where the site turned on `anonymous_read`.
+create function contexthive_private.public_readable(note_scope text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select contexthive_private.signed_in()
+    or exists (
+      select 1 from public.contexthive_scopes s
+       where s.scope = note_scope and s.anonymous_read
+    )
+$$;
+
+-- Whether the caller may read the thread root `root_id`. Roots have no root of
+-- their own, so this never recurses.
+create function contexthive_private.root_readable(root_id text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.contexthive_annotations r
+     where r.id = root_id
+       and (
+         r.creator_id = auth.uid()
+         or (r.audience = 'public' and contexthive_private.public_readable(r.scope))
+       )
+  )
+$$;
+
+-- Whether the signed-in caller may write notes in `note_scope`.
+create function contexthive_private.scope_writable(note_scope text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select contexthive_private.signed_in()
+    and (
+      note_scope = 'user:' || auth.uid()::text
+      or exists (select 1 from public.contexthive_scopes s where s.scope = note_scope)
+    )
+$$;
+
+-- Raises unless a reply in `reply_scope` and `reply_document` with audience
+-- `reply_audience` may hang off `root_id`. Reads the root as the owner, but
+-- reports a root the caller cannot read, or a reply, exactly like a missing
+-- one. A trusted caller may reply under any root.
+create function contexthive_private.check_thread_root(
+  root_id text,
+  reply_scope text,
+  reply_document text,
+  reply_audience text
+)
+returns void
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  root public.contexthive_annotations;
+begin
+  select * into root from public.contexthive_annotations r where r.id = root_id;
+  if not found
+    or root.thread_root_id is not null
+    or (
+      not contexthive_private.trusted_caller()
+      and not (
+        root.creator_id = auth.uid()
+        or (root.audience = 'public' and contexthive_private.public_readable(root.scope))
+      )
+    )
+  then
+    raise exception 'thread root % not found', root_id using errcode = '23503';
+  end if;
+  if root.scope <> reply_scope or root.document <> reply_document then
+    raise exception 'a reply must be in its thread root''s scope and document'
+      using errcode = '23514';
+  end if;
+  if root.audience = 'private' and reply_audience <> 'private' then
+    raise exception 'a reply cannot widen its thread root''s audience' using errcode = '23514';
+  end if;
+end
+$$;
+
+revoke all on all functions in schema contexthive_private from public;
+grant execute on function
+  contexthive_private.signed_in(),
+  contexthive_private.trusted_caller(),
+  contexthive_private.public_readable(text),
+  contexthive_private.root_readable(text),
+  contexthive_private.scope_writable(text),
+  contexthive_private.check_thread_root(text, text, text, text)
+  to anon, authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- Write trigger: copies the indexed columns out of the annotation, owns
+-- `creator_id` and `rev`, and checks threads. Runs as the caller, so the
+-- policies below still apply to the row it produces.
+-- ---------------------------------------------------------------------------
+
+create function contexthive_private.prepare_annotation()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  audience_kind text := a #>> '{ext,audience,kind}';
+  -- The site's own server code writing on a user's behalf.
+  trusted boolean := contexthive_private.trusted_caller();
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,scope}') is distinct from 'string'
+    or jsonb_typeof(a #> '{target,source}') is distinct from 'string'
+    or jsonb_typeof(a -> 'modified') is distinct from 'string'
+    -- ISO 8601 only, so no `infinity`, `now` or other special values.
+    or (a ->> 'modified') !~ '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}(:?\d{2})?)$'
+    or coalesce(jsonb_typeof(a #> '{ext,threadRoot}'), 'null') not in ('string', 'null')
+  then
+    raise exception 'id, ext.scope and target.source must be strings, modified an ISO 8601 time, and ext.threadRoot a string or null'
+      using errcode = '23514';
+  end if;
+
+  if tg_op = 'INSERT' then
+    if not trusted then
+      -- Clients cannot write this column; the author is always the caller.
+      new.creator_id := auth.uid();
+      if new.creator_id is null then
+        raise exception 'sign in to write notes' using errcode = '42501';
+      end if;
+    elsif new.creator_id is null then
+      raise exception 'creator_id is required' using errcode = '23502';
+    end if;
+    new.rev := 1;
+  else
+    new.creator_id := old.creator_id;
+    new.rev := old.rev + 1;
+  end if;
+
+  if audience_kind is null or audience_kind not in ('private', 'public') then
+    raise exception 'audience "%" is not supported here; use private or public', audience_kind
+      using errcode = '23514';
+  end if;
+
+  new.id := a ->> 'id';
+  new.scope := a #>> '{ext,scope}';
+  new.document := a #>> '{target,source}';
+  new.audience := audience_kind;
+  new.thread_root_id := a #>> '{ext,threadRoot}';
+  new.modified := (a ->> 'modified')::timestamptz;
+  new.annotation := jsonb_set(a, '{ext,rev}', to_jsonb(new.rev));
+
+  if tg_op = 'UPDATE' then
+    if new.id is distinct from old.id
+      or new.scope is distinct from old.scope
+      or new.document is distinct from old.document
+      or new.thread_root_id is distinct from old.thread_root_id
+    then
+      raise exception 'id, scope, target.source and threadRoot cannot change'
+        using errcode = '23514';
+    end if;
+  end if;
+
+  if new.thread_root_id is not null then
+    perform contexthive_private.check_thread_root(
+      new.thread_root_id, new.scope, new.document, new.audience
+    );
+  end if;
+  return new;
+end
+$$;
+
+revoke all on function contexthive_private.prepare_annotation() from public;
+
+create trigger contexthive_annotations_prepare
+  before insert or update on public.contexthive_annotations
+  for each row execute function contexthive_private.prepare_annotation();
+
+-- ---------------------------------------------------------------------------
+-- Access
+-- ---------------------------------------------------------------------------
+
+alter table public.contexthive_annotations enable row level security;
+
+revoke all on table public.contexthive_annotations from anon, authenticated;
+grant select on table public.contexthive_annotations to anon, authenticated;
+grant insert (annotation), update (annotation), delete
+  on table public.contexthive_annotations to authenticated;
+
+create policy contexthive_annotations_read on public.contexthive_annotations
+  for select to anon, authenticated
+  using (
+    creator_id = (select auth.uid())
+    or (
+      audience = 'public'
+      and contexthive_private.public_readable(scope)
+      and (thread_root_id is null or contexthive_private.root_readable(thread_root_id))
+    )
+  );
+
+create policy contexthive_annotations_create on public.contexthive_annotations
+  for insert to authenticated
+  with check (
+    creator_id = (select auth.uid()) and contexthive_private.scope_writable(scope)
+  );
+
+create policy contexthive_annotations_update on public.contexthive_annotations
+  for update to authenticated
+  using (creator_id = (select auth.uid()))
+  with check (
+    creator_id = (select auth.uid()) and contexthive_private.scope_writable(scope)
+  );
+
+create policy contexthive_annotations_delete on public.contexthive_annotations
+  for delete to authenticated
+  using (creator_id = (select auth.uid()));
+
+-- ---------------------------------------------------------------------------
+-- Realtime: `subscribe` listens to changes on this table. Realtime applies the
+-- read policy above to inserts and updates before sending them.
+-- ---------------------------------------------------------------------------
+
+do $$
+begin
+  if exists (
+    select 1 from pg_publication where pubname = 'supabase_realtime' and not puballtables
+  ) and not exists (
+    select 1 from pg_publication_tables
+     where pubname = 'supabase_realtime'
+       and schemaname = 'public' and tablename = 'contexthive_annotations'
+  ) then
+    alter publication supabase_realtime add table public.contexthive_annotations;
+  end if;
+end
+$$;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261005090000', 'contexthive_annotations');
+  end if;
+end
+$acornly_install$;
+
+-- 20261005130000_contexthive_threads.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261005130000') then
+    raise notice 'acornly: applying %', '20261005130000_contexthive_threads.sql';
+    execute $acornly_migration$
+-- Reply threads and edit history for contexthive-adapter-supabase (#87).
+--
+-- Context on context (replies, tags, reactions, highlights on a note) follows the
+-- tree rules in contexthive-core's thread.ts:
+--
+-- * A child's `target.source` is its parent's id as an IRI
+--   (`urn:contexthive:annotation:<encodeURIComponent(id)>`, the scheme matched
+--   case-insensitively). The trigger decodes it into `parent_id`. Children
+--   nest to any depth and carry `ext.threadRoot` (the note on the page) and
+--   `ext.depth`.
+-- * A new child is checked against its stored parent in the same statement,
+--   with the parent row locked: the parent exists and the replier can read it,
+--   is not a deleted placeholder, and the child has its scope, thread root,
+--   the next depth, an audience no wider (private under anything, public only
+--   under public) and `ext.parentRev` exactly when it quotes the parent.
+-- * Others read a child only if they can read every note above it, so
+--   narrowing any note hides the replies below it (not only narrowing a root).
+-- * Plain writes keep the tree: an update never moves a note in its thread,
+--   never changes `ext.deleted`, never touches a placeholder, never changes the
+--   author of a note with children, and never widens a child past its parent.
+--   A plain delete refuses children and notes with children.
+-- * Deleting goes through `contexthive_delete_node`, which runs as the owner:
+--   a note with any child (even one the caller cannot see) becomes a
+--   placeholder, and one without is removed along with each placeholder above
+--   it left with no children, whoever wrote them.
+-- * `contexthive_versions` keeps earlier versions of edited notes, readable
+--   only by the note's author. Removing a note or turning it into a
+--   placeholder drops its versions.
+--
+-- Errors the adapter maps: CH001 (a tree rule, ThreadError), CH002 (an
+-- audience wider than the parent's, AudienceError), CH003 (a stale rev,
+-- ConflictError, with the stored rev as the detail) and P0002 (missing).
+
+-- ---------------------------------------------------------------------------
+-- Columns
+-- ---------------------------------------------------------------------------
+
+alter table public.contexthive_annotations add column parent_id text;
+
+create index contexthive_annotations_parent_idx
+  on public.contexthive_annotations (parent_id) where parent_id is not null;
+
+-- ---------------------------------------------------------------------------
+-- Helpers
+-- ---------------------------------------------------------------------------
+
+-- The parent id a target names, or null for a note on a page. Mirrors core's
+-- `parentIdOf`: percent-escapes are decoded as UTF-8, and a badly escaped or
+-- empty id is refused.
+create function contexthive_private.parent_id_of(source text)
+returns text
+language plpgsql
+stable
+set search_path = ''
+as $$
+declare
+  prefix constant text := 'urn:contexthive:annotation:';
+  encoded text;
+  decoded text;
+begin
+  if lower(left(source, length(prefix))) <> prefix then
+    return null;
+  end if;
+  encoded := substr(source, length(prefix) + 1);
+  if encoded !~ '^([^%]|%[0-9A-Fa-f]{2})*$' then
+    raise exception 'target % is badly escaped', source using errcode = 'CH001';
+  end if;
+  begin
+    select convert_from(
+             coalesce(
+               string_agg(
+                 case when m[1] is not null
+                   then decode(substr(m[1], 2), 'hex')
+                   else convert_to(m[2], 'UTF8')
+                 end,
+                 ''::bytea order by n
+               ),
+               ''::bytea
+             ),
+             'UTF8'
+           )
+      into decoded
+      from regexp_matches(encoded, '(%[0-9A-Fa-f]{2})|([^%]+)', 'g') with ordinality as t (m, n);
+  exception when character_not_in_repertoire or untranslatable_character then
+    raise exception 'target % is badly escaped', source using errcode = 'CH001';
+  end;
+  if decoded = '' then
+    raise exception 'target % names an empty id', source using errcode = 'CH001';
+  end if;
+  return decoded;
+end
+$$;
+
+-- Whether the caller may read every note from `first` up to its thread root:
+-- each is the caller's own, or public in a scope they may read. False when one
+-- is missing (its author was deleted), so orphans are hidden too. Reads as the
+-- owner, so it never recurses into the read policy.
+create function contexthive_private.ancestors_readable(first text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with recursive chain (id, parent_id, readable, depth, last_parent) as (
+    select a.id,
+           a.parent_id,
+           coalesce(
+             a.creator_id = auth.uid()
+               or (a.audience = 'public' and contexthive_private.public_readable(a.scope)),
+             false
+           ),
+           1,
+           a.parent_id
+      from public.contexthive_annotations a
+     where a.id = first
+    union all
+    select a.id,
+           a.parent_id,
+           coalesce(
+             a.creator_id = auth.uid()
+               or (a.audience = 'public' and contexthive_private.public_readable(a.scope)),
+             false
+           ),
+           c.depth + 1,
+           a.parent_id
+      from public.contexthive_annotations a
+      join chain c on a.id = c.parent_id
+     -- Stop at the first unreadable note. A cycle cannot be written (children
+     -- need an existing parent), but stay bounded anyway.
+     where c.readable and c.depth < 10000
+  )
+  select coalesce(bool_and(readable), false)
+    -- The top of the chain must be a note on a page, not a dangling parent.
+    and bool_or(parent_id is null)
+    from chain
+$$;
+
+-- The read policy, shared by the policy itself and the checked functions that
+-- run as the owner. A child is hidden from others unless every note above it is
+-- readable to them, so narrowing a note hides the replies below it.
+create function contexthive_private.can_read(r public.contexthive_annotations)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select r.creator_id = auth.uid()
+    or (
+      r.audience = 'public'
+      and contexthive_private.public_readable(r.scope)
+      and (r.thread_root_id is null or contexthive_private.root_readable(r.thread_root_id))
+      and (r.parent_id is null or contexthive_private.ancestors_readable(r.parent_id))
+    )
+$$;
+
+-- Whether any stored note targets `note_id`, seen by the owner: children the
+-- caller cannot read count too. A thread root also keeps its place for any
+-- note in its thread, including replies from before threads nested (they name
+-- only their root) and replies whose parent went with its deleted author, since
+-- removing the root would take them with it.
+create function contexthive_private.has_children(note_id text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.contexthive_annotations c
+     where c.parent_id = note_id or c.thread_root_id = note_id
+  )
+$$;
+
+-- Whether a note is a deleted placeholder.
+create function contexthive_private.is_deleted(a jsonb)
+returns boolean
+language sql
+immutable
+set search_path = ''
+as $$
+  select coalesce(a #> '{ext,deleted}' = 'true'::jsonb, false)
+$$;
+
+-- Whether `child` reaches no one who cannot read `parent`. Only private and
+-- public exist here: private fits under anything, public only under public.
+create function contexthive_private.audience_within(child text, parent text)
+returns boolean
+language sql
+immutable
+set search_path = ''
+as $$
+  select child = 'private' or parent = 'public'
+$$;
+
+-- Raises unless the new child `a` (in scope `child_scope`, audience
+-- `child_audience`, under thread root `child_root`) fits under its stored
+-- parent `parent`, which it locks until the transaction ends so a delete
+-- cannot miss the child. Reads the parent as the owner but reports one the
+-- caller cannot read exactly like a missing one; a trusted caller may add
+-- children under any note.
+create function contexthive_private.check_child(
+  parent text,
+  a jsonb,
+  child_scope text,
+  child_root text,
+  child_audience text
+)
+returns void
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+declare
+  p public.contexthive_annotations;
+  parent_rev jsonb := a #> '{ext,parentRev}';
+  selectors jsonb := a #> '{target,selector}';
+  quoted boolean;
+begin
+  select * into p from public.contexthive_annotations r where r.id = parent for share;
+  if not found
+    or not (contexthive_private.trusted_caller() or contexthive_private.can_read(p))
+  then
+    raise exception 'annotation % not found', parent using errcode = 'P0002';
+  end if;
+  if contexthive_private.is_deleted(p.annotation) then
+    raise exception 'annotation % is deleted', parent using errcode = 'CH001';
+  end if;
+  -- A reply from before threads nested shows only on its page.
+  if p.parent_id is null and p.thread_root_id is not null then
+    raise exception 'annotation % is a reply from before threads nested; reply to its root',
+      parent using errcode = 'CH001';
+  end if;
+  if p.scope <> child_scope then
+    raise exception 'annotation % is not in its parent''s scope', a ->> 'id' using errcode = 'CH001';
+  end if;
+  if child_root is distinct from coalesce(p.thread_root_id, p.id) then
+    raise exception 'annotation % is not in its parent''s thread', a ->> 'id'
+      using errcode = 'CH001';
+  end if;
+  if (a #>> '{ext,depth}')::numeric
+    is distinct from coalesce((p.annotation #>> '{ext,depth}')::numeric, 0) + 1
+  then
+    raise exception 'annotation % has the wrong depth', a ->> 'id' using errcode = 'CH001';
+  end if;
+  if not contexthive_private.audience_within(child_audience, p.audience) then
+    raise exception 'annotation % has a wider audience than its parent', a ->> 'id'
+      using errcode = 'CH002';
+  end if;
+  quoted := jsonb_typeof(selectors) = 'array' and exists (
+    select 1 from jsonb_array_elements(selectors) s where s ->> 'type' = 'TextQuoteSelector'
+  );
+  if quoted is distinct from (parent_rev is not null)
+    or (parent_rev is not null and ((parent_rev #>> '{}')::numeric < 1
+      or (parent_rev #>> '{}')::numeric > p.rev))
+  then
+    raise exception 'annotation % must record the parent''s rev exactly when it quotes the parent',
+      a ->> 'id' using errcode = 'CH001';
+  end if;
+end
+$$;
+
+-- The audience of `note_id`, read as the owner and locked until the
+-- transaction ends, or 'public' when it is gone (nothing left to protect).
+create function contexthive_private.locked_audience(note_id text)
+returns text
+language sql
+volatile
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select a.audience from public.contexthive_annotations a where a.id = note_id for share),
+    'public'
+  )
+$$;
+
+-- Whether the current statement runs inside `contexthive_delete_node`, which
+-- writes placeholders and removes children. The flag alone is not enough, as
+-- any SQL session can set a custom setting: the statement must also run as the
+-- table's owner, which only that security-definer function does for a client.
+create function contexthive_private.in_delete_node()
+returns boolean
+language sql
+stable
+set search_path = ''
+as $$
+  select coalesce(current_setting('contexthive.delete_node', true), '') = 'on'
+    and current_user = (
+      select pg_catalog.pg_get_userbyid(c.relowner)
+        from pg_catalog.pg_class c
+       where c.oid = 'public.contexthive_annotations'::regclass
+    )
+$$;
+
+-- The checks on the root replaced by `check_child`.
+drop function contexthive_private.check_thread_root(text, text, text, text);
+
+revoke all on all functions in schema contexthive_private from public;
+grant execute on function
+  contexthive_private.signed_in(),
+  contexthive_private.trusted_caller(),
+  contexthive_private.public_readable(text),
+  contexthive_private.root_readable(text),
+  contexthive_private.scope_writable(text),
+  contexthive_private.parent_id_of(text),
+  contexthive_private.ancestors_readable(text),
+  contexthive_private.can_read(public.contexthive_annotations),
+  contexthive_private.has_children(text),
+  contexthive_private.is_deleted(jsonb),
+  contexthive_private.audience_within(text, text),
+  contexthive_private.check_child(text, jsonb, text, text, text),
+  contexthive_private.locked_audience(text),
+  contexthive_private.in_delete_node()
+  to anon, authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- Write triggers
+-- ---------------------------------------------------------------------------
+
+create or replace function contexthive_private.prepare_annotation()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  audience_kind text := a #>> '{ext,audience,kind}';
+  -- The site's own server code writing on a user's behalf.
+  trusted boolean := contexthive_private.trusted_caller();
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,scope}') is distinct from 'string'
+    or jsonb_typeof(a #> '{target,source}') is distinct from 'string'
+    or jsonb_typeof(a -> 'modified') is distinct from 'string'
+    -- ISO 8601 only, so no `infinity`, `now` or other special values.
+    or (a ->> 'modified') !~ '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}(:?\d{2})?)$'
+    or coalesce(jsonb_typeof(a #> '{ext,threadRoot}'), 'null') not in ('string', 'null')
+  then
+    raise exception 'id, ext.scope and target.source must be strings, modified an ISO 8601 time, and ext.threadRoot a string or null'
+      using errcode = '23514';
+  end if;
+  if coalesce(jsonb_typeof(a #> '{ext,depth}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,parentRev}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,deleted}'), 'null') not in ('boolean', 'null')
+  then
+    raise exception 'ext.depth and ext.parentRev must be numbers and ext.deleted a boolean'
+      using errcode = '23514';
+  end if;
+
+  if tg_op = 'INSERT' then
+    if not trusted then
+      -- Clients cannot write this column; the author is always the caller.
+      new.creator_id := auth.uid();
+      if new.creator_id is null then
+        raise exception 'sign in to write notes' using errcode = '42501';
+      end if;
+    elsif new.creator_id is null then
+      raise exception 'creator_id is required' using errcode = '23502';
+    end if;
+    new.rev := 1;
+  else
+    new.creator_id := old.creator_id;
+    new.rev := old.rev + 1;
+  end if;
+
+  if audience_kind is null or audience_kind not in ('private', 'public') then
+    raise exception 'audience "%" is not supported here; use private or public', audience_kind
+      using errcode = '23514';
+  end if;
+
+  new.id := a ->> 'id';
+  new.scope := a #>> '{ext,scope}';
+  new.document := a #>> '{target,source}';
+  new.audience := audience_kind;
+  new.thread_root_id := a #>> '{ext,threadRoot}';
+  -- The document never changes, so neither does the parent; notes stored
+  -- before this migration keep theirs (none) when edited.
+  new.parent_id := case
+    when tg_op = 'UPDATE' then old.parent_id
+    else contexthive_private.parent_id_of(new.document)
+  end;
+  new.modified := (a ->> 'modified')::timestamptz;
+  new.annotation := jsonb_set(a, '{ext,rev}', to_jsonb(new.rev));
+
+  if tg_op = 'INSERT' then
+    if contexthive_private.is_deleted(a) then
+      raise exception 'a new annotation cannot be deleted' using errcode = 'CH001';
+    end if;
+    if new.parent_id is null then
+      if new.thread_root_id is not null
+        or a #> '{ext,depth}' is not null
+        or a #> '{ext,parentRev}' is not null
+      then
+        raise exception 'annotation % has thread fields but targets a page', new.id
+          using errcode = 'CH001';
+      end if;
+    else
+      perform contexthive_private.check_child(
+        new.parent_id, a, new.scope, new.thread_root_id, new.audience
+      );
+    end if;
+    return new;
+  end if;
+
+  if new.id is distinct from old.id then
+    raise exception 'id cannot change' using errcode = '23514';
+  end if;
+  -- `contexthive_delete_node` writing a placeholder.
+  if contexthive_private.in_delete_node() then
+    return new;
+  end if;
+  if contexthive_private.is_deleted(a) is distinct from contexthive_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted or restored only by deleteNode', new.id
+      using errcode = 'CH001';
+  end if;
+  if contexthive_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted', new.id using errcode = 'CH001';
+  end if;
+  if new.scope is distinct from old.scope
+    or new.document is distinct from old.document
+    or new.thread_root_id is distinct from old.thread_root_id
+    or a #> '{ext,depth}' is distinct from old.annotation #> '{ext,depth}'
+    or a #> '{ext,parentRev}' is distinct from old.annotation #> '{ext,parentRev}'
+    or (old.parent_id is not null and a -> 'target' is distinct from old.annotation -> 'target')
+  then
+    raise exception 'annotation % cannot move: id, scope, target.source and threadRoot cannot change',
+      new.id using errcode = 'CH001';
+  end if;
+  if a #> '{creator,id}' is distinct from old.annotation #> '{creator,id}'
+    and contexthive_private.has_children(new.id)
+  then
+    raise exception 'annotation % has replies; its author stays', new.id using errcode = 'CH001';
+  end if;
+  -- An unchanged or narrower audience is fine even if the parent was narrowed
+  -- meanwhile. A wider one is checked against the parent, locked so a
+  -- concurrent narrowing cannot slip past; a reply from before threads nested
+  -- is checked against its root.
+  if new.thread_root_id is not null
+    and not contexthive_private.audience_within(new.audience, old.audience)
+    and not contexthive_private.audience_within(
+      new.audience,
+      contexthive_private.locked_audience(coalesce(old.parent_id, old.thread_root_id))
+    )
+  then
+    raise exception 'annotation % cannot widen its parent''s audience', new.id
+      using errcode = 'CH002';
+  end if;
+  return new;
+end
+$$;
+
+revoke all on function contexthive_private.prepare_annotation() from public;
+
+-- Plain deletes keep the tree; `contexthive_delete_node` and cascades (a
+-- deleted user's notes) are let through.
+create function contexthive_private.check_delete()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+  if contexthive_private.in_delete_node() or pg_trigger_depth() > 1 then
+    return old;
+  end if;
+  if old.parent_id is not null then
+    raise exception 'annotation % is context on context; use threads.deleteNode', old.id
+      using errcode = 'CH001';
+  end if;
+  if contexthive_private.has_children(old.id) then
+    raise exception 'annotation % has children; use threads.deleteNode', old.id
+      using errcode = 'CH001';
+  end if;
+  return old;
+end
+$$;
+
+revoke all on function contexthive_private.check_delete() from public;
+
+create trigger contexthive_annotations_check_delete
+  before delete on public.contexthive_annotations
+  for each row execute function contexthive_private.check_delete();
+
+-- ---------------------------------------------------------------------------
+-- Reading: replies are hidden below any note the reader cannot read
+-- ---------------------------------------------------------------------------
+
+drop policy contexthive_annotations_read on public.contexthive_annotations;
+
+create policy contexthive_annotations_read on public.contexthive_annotations
+  for select to anon, authenticated
+  using (
+    creator_id = (select auth.uid())
+    or (
+      audience = 'public'
+      and contexthive_private.public_readable(scope)
+      and (thread_root_id is null or contexthive_private.root_readable(thread_root_id))
+      and (parent_id is null or contexthive_private.ancestors_readable(parent_id))
+    )
+  );
+
+-- No `parent_id` backfill: before this migration a reply had to share its
+-- root's page, so no stored row is context on context.
+
+-- ---------------------------------------------------------------------------
+-- Edit history
+-- ---------------------------------------------------------------------------
+
+create table public.contexthive_versions (
+  note_id text not null references public.contexthive_annotations (id) on delete cascade,
+  rev integer not null check (rev >= 1),
+  -- The note's author, set by the trigger.
+  creator_id uuid not null references auth.users (id) on delete cascade,
+  annotation jsonb not null check (
+    jsonb_typeof(annotation) = 'object' and octet_length(annotation::text) <= 65536
+  ),
+  primary key (note_id, rev)
+);
+
+create index contexthive_versions_creator_idx on public.contexthive_versions (creator_id);
+
+create function contexthive_private.prepare_version()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  author uuid;
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,rev}') is distinct from 'number'
+    or (a #>> '{ext,rev}') !~ '^[1-9][0-9]{0,8}$'
+  then
+    raise exception 'a version needs a string id and a positive integer ext.rev'
+      using errcode = '23514';
+  end if;
+  new.note_id := a ->> 'id';
+  new.rev := (a #>> '{ext,rev}')::integer;
+  if tg_op = 'UPDATE' and (new.note_id <> old.note_id or new.rev <> old.rev) then
+    raise exception 'a saved version keeps its id and rev' using errcode = '23514';
+  end if;
+  -- Read as the caller: a client finds only notes it can read.
+  select n.creator_id into author from public.contexthive_annotations n where n.id = new.note_id;
+  if not found then
+    raise exception 'annotation % not found', new.note_id using errcode = 'P0002';
+  end if;
+  if not contexthive_private.trusted_caller() and author is distinct from auth.uid() then
+    raise exception 'only the author keeps versions of annotation %', new.note_id
+      using errcode = '42501';
+  end if;
+  new.creator_id := author;
+  return new;
+end
+$$;
+
+revoke all on function contexthive_private.prepare_version() from public;
+
+create trigger contexthive_versions_prepare
+  before insert or update on public.contexthive_versions
+  for each row execute function contexthive_private.prepare_version();
+
+alter table public.contexthive_versions enable row level security;
+
+revoke all on table public.contexthive_versions from anon, authenticated;
+grant select, delete on table public.contexthive_versions to authenticated;
+-- Visitors read none (no policy admits them), but get an empty list, not an error.
+grant select on table public.contexthive_versions to anon;
+grant insert (annotation), update (annotation) on table public.contexthive_versions to authenticated;
+
+create policy contexthive_versions_read on public.contexthive_versions
+  for select to authenticated
+  using (creator_id = (select auth.uid()));
+
+create policy contexthive_versions_create on public.contexthive_versions
+  for insert to authenticated
+  with check (creator_id = (select auth.uid()));
+
+create policy contexthive_versions_update on public.contexthive_versions
+  for update to authenticated
+  using (creator_id = (select auth.uid()))
+  with check (creator_id = (select auth.uid()));
+
+create policy contexthive_versions_delete on public.contexthive_versions
+  for delete to authenticated
+  using (creator_id = (select auth.uid()));
+
+-- ---------------------------------------------------------------------------
+-- Thread functions the adapter calls
+-- ---------------------------------------------------------------------------
+
+-- The ids in a thread the caller may read: the read policy's rules worked out
+-- top-down in one pass, seeded with the root and its replies from before
+-- threads nested and then walking children through the parent index, so the
+-- cost is linear in the thread's size whatever its shape. The caller's own
+-- notes are always in, and everything for the site's server. Empty unless
+-- `root_id` is a note on a page in `thread_scope`.
+create function contexthive_private.thread_visible(root_id text, thread_scope text)
+returns setof text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with recursive
+  me (uid, trusted, scope_readable) as materialized (
+    select auth.uid(),
+           contexthive_private.trusted_caller(),
+           contexthive_private.public_readable(thread_scope)
+  ),
+  tree (id, path_readable, depth) as (
+    select a.id,
+           coalesce(a.creator_id = me.uid or (a.audience = 'public' and me.scope_readable), false),
+           0
+      from public.contexthive_annotations a, me
+     where a.id = root_id
+       and a.scope = thread_scope
+       and a.parent_id is null
+       and a.thread_root_id is null
+    union all
+    -- Replies from before threads nested target the page and name the root.
+    select c.id,
+           r.path_readable
+             and coalesce(c.creator_id = me.uid or (c.audience = 'public' and me.scope_readable), false),
+           1
+      from public.contexthive_annotations a
+      join public.contexthive_annotations c
+        on c.thread_root_id = a.id and c.parent_id is null and c.scope = thread_scope
+      cross join me
+      cross join lateral (
+        select coalesce(a.creator_id = me.uid or (a.audience = 'public' and me.scope_readable), false)
+      ) r (path_readable)
+     where a.id = root_id and a.scope = thread_scope and a.thread_root_id is null
+    union all
+    select c.id,
+           t.path_readable
+             and coalesce(c.creator_id = me.uid or (c.audience = 'public' and me.scope_readable), false),
+           t.depth + 1
+      from tree t
+      join public.contexthive_annotations c on c.parent_id = t.id
+      cross join me
+     where c.scope = thread_scope and t.depth < 10000
+  )
+  select t.id from tree t, me where t.path_readable or me.trusted
+  union
+  -- The caller's own notes, and everything for the site's server, even below a
+  -- parent that is gone.
+  select a.id
+    from public.contexthive_annotations a, me
+   where a.scope = thread_scope
+     and a.thread_root_id = root_id
+     and (a.creator_id = me.uid or me.trusted)
+     -- Only a real root starts a thread.
+     and exists (select 1 from tree t where t.depth = 0)
+$$;
+
+-- Only the functions below call it, as the owner.
+revoke all on function contexthive_private.thread_visible(text, text) from public;
+
+-- A thread's root and every node below it in one scope, as the caller may read
+-- them, as one JSON array of annotations ordered by `modified` and id. One call
+-- returns everything, as paging would redo the walk for each page.
+create function public.contexthive_list_thread(root_id text, thread_scope text)
+returns jsonb
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(jsonb_agg(a.annotation order by a.modified, a.id), '[]'::jsonb)
+    from contexthive_private.thread_visible(root_id, thread_scope) v (id)
+    join public.contexthive_annotations a on a.id = v.id
+$$;
+
+-- The number of direct children of each id that the caller may read. Replies
+-- from before threads nested are left out, as `assembleThread` does not place
+-- them. Ids with none are left out.
+-- Visibility comes from one top-down walk per thread involved.
+create function public.contexthive_count_children(ids text[])
+returns table (id text, children bigint)
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with children (parent, child, thread_root_id, scope) as materialized (
+    select c.parent_id, c.id, c.thread_root_id, c.scope
+      from public.contexthive_annotations c
+     where c.parent_id = any (ids)
+  ),
+  visible (id) as materialized (
+    select v.id
+      from (select distinct thread_root_id, scope from children) t
+      cross join lateral contexthive_private.thread_visible(t.thread_root_id, t.scope) v (id)
+  )
+  select c.parent, count(*)
+    from children c
+    join visible v on v.id = c.child
+   group by c.parent
+$$;
+
+-- Deletes `note_id` at `expected_rev` for its author (or the site's server).
+-- A note with any child becomes a placeholder at the next rev, modified at
+-- `deleted_at`: no body, author name or edited mark, `ext.deleted` true, and
+-- its versions dropped. One without children is removed, and so is each
+-- placeholder above it left with no children. Returns
+-- `{"placeholder": <annotation>}` or `{"removed": [{id, scope, document}, ...]}`,
+-- the note first.
+create function public.contexthive_delete_node(
+  note_id text,
+  expected_rev integer,
+  deleted_at text
+)
+returns jsonb
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+declare
+  target public.contexthive_annotations;
+  node public.contexthive_annotations;
+  above public.contexthive_annotations;
+  placeholder jsonb;
+  removed jsonb := '[]'::jsonb;
+  trusted boolean := contexthive_private.trusted_caller();
+begin
+  select * into target from public.contexthive_annotations a where a.id = note_id for update;
+  if not found or not (trusted or contexthive_private.can_read(target)) then
+    raise exception 'annotation % not found', note_id using errcode = 'P0002';
+  end if;
+  if not trusted and target.creator_id is distinct from auth.uid() then
+    raise exception 'Not allowed to change annotation %', note_id using errcode = '42501';
+  end if;
+  if target.rev <> expected_rev then
+    raise exception 'annotation % is at rev %, expected %', note_id, target.rev, expected_rev
+      using errcode = 'CH003', detail = target.rev::text;
+  end if;
+
+  perform set_config('contexthive.delete_node', 'on', true);
+
+  if contexthive_private.has_children(note_id) then
+    placeholder := (target.annotation - 'body') || jsonb_build_object('modified', deleted_at);
+    placeholder := jsonb_set(
+      placeholder,
+      '{ext}',
+      ((target.annotation -> 'ext') - 'edited') || '{"deleted": true}'::jsonb
+    );
+    if jsonb_typeof(target.annotation -> 'creator') = 'object' then
+      placeholder := jsonb_set(
+        placeholder,
+        '{creator}',
+        jsonb_strip_nulls(jsonb_build_object('id', target.annotation #> '{creator,id}'))
+      );
+    end if;
+    update public.contexthive_annotations a
+       set annotation = placeholder
+     where a.id = note_id
+    returning a.annotation into placeholder;
+    delete from public.contexthive_versions v where v.note_id = target.id;
+    perform set_config('contexthive.delete_node', '', true);
+    return jsonb_build_object('placeholder', placeholder);
+  end if;
+
+  -- Remove it, then each placeholder above it left with no children. Each
+  -- parent is locked before its children are counted, so a child landing
+  -- meanwhile either waits for this delete or is seen.
+  node := target;
+  loop
+    delete from public.contexthive_annotations a where a.id = node.id;
+    removed := removed || jsonb_build_object(
+      'id', node.id, 'scope', node.scope, 'document', node.document
+    );
+    exit when coalesce(node.parent_id, node.thread_root_id) is null;
+    select * into above from public.contexthive_annotations a
+     where a.id = coalesce(node.parent_id, node.thread_root_id)
+       for update;
+    -- An orphan's parent went with its author: its root may still be waiting.
+    if not found and node.parent_id is not null and node.thread_root_id is not null then
+      select * into above from public.contexthive_annotations a
+       where a.id = node.thread_root_id
+         for update;
+    end if;
+    exit when not found
+      or not contexthive_private.is_deleted(above.annotation)
+      or contexthive_private.has_children(above.id);
+    node := above;
+  end loop;
+  perform set_config('contexthive.delete_node', '', true);
+  return jsonb_build_object('removed', removed);
+end
+$$;
+
+revoke all on function
+  public.contexthive_list_thread(text, text),
+  public.contexthive_count_children(text[]),
+  public.contexthive_delete_node(text, integer, text)
+  from public;
+grant execute on function
+  public.contexthive_list_thread(text, text),
+  public.contexthive_count_children(text[])
+  to anon, authenticated, service_role;
+grant execute on function public.contexthive_delete_node(text, integer, text)
+  to authenticated, service_role;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261005130000', 'contexthive_threads');
+  end if;
+end
+$acornly_install$;
+
+-- 20261010070000_acornly_names.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261010070000') then
+    raise notice 'acornly: applying %', '20261010070000_acornly_names.sql';
+    execute $acornly_migration$
+-- Renames everything the earlier migrations in this folder created from
+-- `contexthive` to `acornly`, as the product is now Acornly.
+--
+-- Renaming keeps each object's data, grants, row level security, policies,
+-- triggers and Realtime publication, since those follow the object. Function
+-- bodies are stored as text, though, so every function that names a renamed
+-- object is recreated below with the new names. The delete-node flag becomes
+-- `acornly.delete_node`; its reader and its writer change together here.
+--
+-- Left as they are: the `urn:contexthive:annotation:` target prefix (part of
+-- the stored notes, not of the schema) and the CH001 to CH003 error codes the
+-- adapter maps.
+
+-- ---------------------------------------------------------------------------
+-- Schema and tables
+-- ---------------------------------------------------------------------------
+
+alter schema contexthive_private rename to acornly_private;
+
+alter table public.contexthive_scopes rename to acornly_scopes;
+alter table public.contexthive_annotations rename to acornly_annotations;
+alter table public.contexthive_versions rename to acornly_versions;
+
+-- Constraints (primary keys rename their index too), then the other indexes,
+-- including the names Postgres chose itself such as `..._scope_check`.
+do $$
+declare
+  c record;
+begin
+  for c in
+    select con.conrelid::regclass as tbl, con.conname
+      from pg_catalog.pg_constraint con
+     where con.conrelid in (
+             'public.acornly_scopes'::regclass,
+             'public.acornly_annotations'::regclass,
+             'public.acornly_versions'::regclass
+           )
+       and con.conname like 'contexthive\_%'
+  loop
+    execute format(
+      'alter table %s rename constraint %I to %I',
+      c.tbl, c.conname, 'acornly_' || substr(c.conname, length('contexthive_') + 1)
+    );
+  end loop;
+
+  for c in
+    select i.relname
+      from pg_catalog.pg_index x
+      join pg_catalog.pg_class i on i.oid = x.indexrelid
+     where x.indrelid in (
+             'public.acornly_scopes'::regclass,
+             'public.acornly_annotations'::regclass,
+             'public.acornly_versions'::regclass
+           )
+       and i.relname like 'contexthive\_%'
+  loop
+    execute format(
+      'alter index public.%I rename to %I',
+      c.relname, 'acornly_' || substr(c.relname, length('contexthive_') + 1)
+    );
+  end loop;
+end
+$$;
+
+-- ---------------------------------------------------------------------------
+-- Triggers and policies
+-- ---------------------------------------------------------------------------
+
+alter trigger contexthive_annotations_prepare on public.acornly_annotations
+  rename to acornly_annotations_prepare;
+alter trigger contexthive_annotations_check_delete on public.acornly_annotations
+  rename to acornly_annotations_check_delete;
+alter trigger contexthive_versions_prepare on public.acornly_versions
+  rename to acornly_versions_prepare;
+
+alter policy contexthive_annotations_read on public.acornly_annotations
+  rename to acornly_annotations_read;
+alter policy contexthive_annotations_create on public.acornly_annotations
+  rename to acornly_annotations_create;
+alter policy contexthive_annotations_update on public.acornly_annotations
+  rename to acornly_annotations_update;
+alter policy contexthive_annotations_delete on public.acornly_annotations
+  rename to acornly_annotations_delete;
+
+alter policy contexthive_versions_read on public.acornly_versions
+  rename to acornly_versions_read;
+alter policy contexthive_versions_create on public.acornly_versions
+  rename to acornly_versions_create;
+alter policy contexthive_versions_update on public.acornly_versions
+  rename to acornly_versions_update;
+alter policy contexthive_versions_delete on public.acornly_versions
+  rename to acornly_versions_delete;
+
+-- ---------------------------------------------------------------------------
+-- Functions: the adapter's entry points get the new prefix, and every function
+-- naming a renamed object is recreated. `create or replace` keeps each one's
+-- owner and grants. The helpers below name no renamed object and are left:
+-- signed_in, trusted_caller, is_deleted, audience_within and parent_id_of.
+-- ---------------------------------------------------------------------------
+
+alter function public.contexthive_list_thread(text, text) rename to acornly_list_thread;
+alter function public.contexthive_count_children(text[]) rename to acornly_count_children;
+alter function public.contexthive_delete_node(text, integer, text) rename to acornly_delete_node;
+
+-- Whether the caller may read public notes in `note_scope`: anyone signed in,
+-- and anonymous visitors where the site turned on `anonymous_read`.
+create or replace function acornly_private.public_readable(note_scope text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select acornly_private.signed_in()
+    or exists (
+      select 1 from public.acornly_scopes s
+       where s.scope = note_scope and s.anonymous_read
+    )
+$$;
+
+-- Whether the caller may read the thread root `root_id`. Roots have no root of
+-- their own, so this never recurses.
+create or replace function acornly_private.root_readable(root_id text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.acornly_annotations r
+     where r.id = root_id
+       and (
+         r.creator_id = auth.uid()
+         or (r.audience = 'public' and acornly_private.public_readable(r.scope))
+       )
+  )
+$$;
+
+-- Whether the signed-in caller may write notes in `note_scope`.
+create or replace function acornly_private.scope_writable(note_scope text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select acornly_private.signed_in()
+    and (
+      note_scope = 'user:' || auth.uid()::text
+      or exists (select 1 from public.acornly_scopes s where s.scope = note_scope)
+    )
+$$;
+
+-- Whether the caller may read every note from `first` up to its thread root:
+-- each is the caller's own, or public in a scope they may read. False when one
+-- is missing (its author was deleted), so orphans are hidden too. Reads as the
+-- owner, so it never recurses into the read policy.
+create or replace function acornly_private.ancestors_readable(first text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with recursive chain (id, parent_id, readable, depth, last_parent) as (
+    select a.id,
+           a.parent_id,
+           coalesce(
+             a.creator_id = auth.uid()
+               or (a.audience = 'public' and acornly_private.public_readable(a.scope)),
+             false
+           ),
+           1,
+           a.parent_id
+      from public.acornly_annotations a
+     where a.id = first
+    union all
+    select a.id,
+           a.parent_id,
+           coalesce(
+             a.creator_id = auth.uid()
+               or (a.audience = 'public' and acornly_private.public_readable(a.scope)),
+             false
+           ),
+           c.depth + 1,
+           a.parent_id
+      from public.acornly_annotations a
+      join chain c on a.id = c.parent_id
+     -- Stop at the first unreadable note. A cycle cannot be written (children
+     -- need an existing parent), but stay bounded anyway.
+     where c.readable and c.depth < 10000
+  )
+  select coalesce(bool_and(readable), false)
+    -- The top of the chain must be a note on a page, not a dangling parent.
+    and bool_or(parent_id is null)
+    from chain
+$$;
+
+-- The read policy, shared by the policy itself and the checked functions that
+-- run as the owner. A child is hidden from others unless every note above it is
+-- readable to them, so narrowing a note hides the replies below it.
+create or replace function acornly_private.can_read(r public.acornly_annotations)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select r.creator_id = auth.uid()
+    or (
+      r.audience = 'public'
+      and acornly_private.public_readable(r.scope)
+      and (r.thread_root_id is null or acornly_private.root_readable(r.thread_root_id))
+      and (r.parent_id is null or acornly_private.ancestors_readable(r.parent_id))
+    )
+$$;
+
+-- Whether any stored note targets `note_id`, seen by the owner: children the
+-- caller cannot read count too. A thread root also keeps its place for any
+-- note in its thread, including replies from before threads nested (they name
+-- only their root) and replies whose parent went with its deleted author, since
+-- removing the root would take them with it.
+create or replace function acornly_private.has_children(note_id text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.acornly_annotations c
+     where c.parent_id = note_id or c.thread_root_id = note_id
+  )
+$$;
+
+-- Raises unless the new child `a` (in scope `child_scope`, audience
+-- `child_audience`, under thread root `child_root`) fits under its stored
+-- parent `parent`, which it locks until the transaction ends so a delete
+-- cannot miss the child. Reads the parent as the owner but reports one the
+-- caller cannot read exactly like a missing one; a trusted caller may add
+-- children under any note.
+create or replace function acornly_private.check_child(
+  parent text,
+  a jsonb,
+  child_scope text,
+  child_root text,
+  child_audience text
+)
+returns void
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+declare
+  p public.acornly_annotations;
+  parent_rev jsonb := a #> '{ext,parentRev}';
+  selectors jsonb := a #> '{target,selector}';
+  quoted boolean;
+begin
+  select * into p from public.acornly_annotations r where r.id = parent for share;
+  if not found
+    or not (acornly_private.trusted_caller() or acornly_private.can_read(p))
+  then
+    raise exception 'annotation % not found', parent using errcode = 'P0002';
+  end if;
+  if acornly_private.is_deleted(p.annotation) then
+    raise exception 'annotation % is deleted', parent using errcode = 'CH001';
+  end if;
+  -- A reply from before threads nested shows only on its page.
+  if p.parent_id is null and p.thread_root_id is not null then
+    raise exception 'annotation % is a reply from before threads nested; reply to its root',
+      parent using errcode = 'CH001';
+  end if;
+  if p.scope <> child_scope then
+    raise exception 'annotation % is not in its parent''s scope', a ->> 'id' using errcode = 'CH001';
+  end if;
+  if child_root is distinct from coalesce(p.thread_root_id, p.id) then
+    raise exception 'annotation % is not in its parent''s thread', a ->> 'id'
+      using errcode = 'CH001';
+  end if;
+  if (a #>> '{ext,depth}')::numeric
+    is distinct from coalesce((p.annotation #>> '{ext,depth}')::numeric, 0) + 1
+  then
+    raise exception 'annotation % has the wrong depth', a ->> 'id' using errcode = 'CH001';
+  end if;
+  if not acornly_private.audience_within(child_audience, p.audience) then
+    raise exception 'annotation % has a wider audience than its parent', a ->> 'id'
+      using errcode = 'CH002';
+  end if;
+  quoted := jsonb_typeof(selectors) = 'array' and exists (
+    select 1 from jsonb_array_elements(selectors) s where s ->> 'type' = 'TextQuoteSelector'
+  );
+  if quoted is distinct from (parent_rev is not null)
+    or (parent_rev is not null and ((parent_rev #>> '{}')::numeric < 1
+      or (parent_rev #>> '{}')::numeric > p.rev))
+  then
+    raise exception 'annotation % must record the parent''s rev exactly when it quotes the parent',
+      a ->> 'id' using errcode = 'CH001';
+  end if;
+end
+$$;
+
+-- The audience of `note_id`, read as the owner and locked until the
+-- transaction ends, or 'public' when it is gone (nothing left to protect).
+create or replace function acornly_private.locked_audience(note_id text)
+returns text
+language sql
+volatile
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select a.audience from public.acornly_annotations a where a.id = note_id for share),
+    'public'
+  )
+$$;
+
+-- Whether the current statement runs inside `acornly_delete_node`, which
+-- writes placeholders and removes children. The flag alone is not enough, as
+-- any SQL session can set a custom setting: the statement must also run as the
+-- table's owner, which only that security-definer function does for a client.
+create or replace function acornly_private.in_delete_node()
+returns boolean
+language sql
+stable
+set search_path = ''
+as $$
+  select coalesce(current_setting('acornly.delete_node', true), '') = 'on'
+    and current_user = (
+      select pg_catalog.pg_get_userbyid(c.relowner)
+        from pg_catalog.pg_class c
+       where c.oid = 'public.acornly_annotations'::regclass
+    )
+$$;
+
+-- The write trigger on notes.
+create or replace function acornly_private.prepare_annotation()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  audience_kind text := a #>> '{ext,audience,kind}';
+  -- The site's own server code writing on a user's behalf.
+  trusted boolean := acornly_private.trusted_caller();
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,scope}') is distinct from 'string'
+    or jsonb_typeof(a #> '{target,source}') is distinct from 'string'
+    or jsonb_typeof(a -> 'modified') is distinct from 'string'
+    -- ISO 8601 only, so no `infinity`, `now` or other special values.
+    or (a ->> 'modified') !~ '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}(:?\d{2})?)$'
+    or coalesce(jsonb_typeof(a #> '{ext,threadRoot}'), 'null') not in ('string', 'null')
+  then
+    raise exception 'id, ext.scope and target.source must be strings, modified an ISO 8601 time, and ext.threadRoot a string or null'
+      using errcode = '23514';
+  end if;
+  if coalesce(jsonb_typeof(a #> '{ext,depth}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,parentRev}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,deleted}'), 'null') not in ('boolean', 'null')
+  then
+    raise exception 'ext.depth and ext.parentRev must be numbers and ext.deleted a boolean'
+      using errcode = '23514';
+  end if;
+
+  if tg_op = 'INSERT' then
+    if not trusted then
+      -- Clients cannot write this column; the author is always the caller.
+      new.creator_id := auth.uid();
+      if new.creator_id is null then
+        raise exception 'sign in to write notes' using errcode = '42501';
+      end if;
+    elsif new.creator_id is null then
+      raise exception 'creator_id is required' using errcode = '23502';
+    end if;
+    new.rev := 1;
+  else
+    new.creator_id := old.creator_id;
+    new.rev := old.rev + 1;
+  end if;
+
+  if audience_kind is null or audience_kind not in ('private', 'public') then
+    raise exception 'audience "%" is not supported here; use private or public', audience_kind
+      using errcode = '23514';
+  end if;
+
+  new.id := a ->> 'id';
+  new.scope := a #>> '{ext,scope}';
+  new.document := a #>> '{target,source}';
+  new.audience := audience_kind;
+  new.thread_root_id := a #>> '{ext,threadRoot}';
+  -- The document never changes, so neither does the parent; notes stored
+  -- before this migration keep theirs (none) when edited.
+  new.parent_id := case
+    when tg_op = 'UPDATE' then old.parent_id
+    else acornly_private.parent_id_of(new.document)
+  end;
+  new.modified := (a ->> 'modified')::timestamptz;
+  new.annotation := jsonb_set(a, '{ext,rev}', to_jsonb(new.rev));
+
+  if tg_op = 'INSERT' then
+    if acornly_private.is_deleted(a) then
+      raise exception 'a new annotation cannot be deleted' using errcode = 'CH001';
+    end if;
+    if new.parent_id is null then
+      if new.thread_root_id is not null
+        or a #> '{ext,depth}' is not null
+        or a #> '{ext,parentRev}' is not null
+      then
+        raise exception 'annotation % has thread fields but targets a page', new.id
+          using errcode = 'CH001';
+      end if;
+    else
+      perform acornly_private.check_child(
+        new.parent_id, a, new.scope, new.thread_root_id, new.audience
+      );
+    end if;
+    return new;
+  end if;
+
+  if new.id is distinct from old.id then
+    raise exception 'id cannot change' using errcode = '23514';
+  end if;
+  -- `acornly_delete_node` writing a placeholder.
+  if acornly_private.in_delete_node() then
+    return new;
+  end if;
+  if acornly_private.is_deleted(a) is distinct from acornly_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted or restored only by deleteNode', new.id
+      using errcode = 'CH001';
+  end if;
+  if acornly_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted', new.id using errcode = 'CH001';
+  end if;
+  if new.scope is distinct from old.scope
+    or new.document is distinct from old.document
+    or new.thread_root_id is distinct from old.thread_root_id
+    or a #> '{ext,depth}' is distinct from old.annotation #> '{ext,depth}'
+    or a #> '{ext,parentRev}' is distinct from old.annotation #> '{ext,parentRev}'
+    or (old.parent_id is not null and a -> 'target' is distinct from old.annotation -> 'target')
+  then
+    raise exception 'annotation % cannot move: id, scope, target.source and threadRoot cannot change',
+      new.id using errcode = 'CH001';
+  end if;
+  if a #> '{creator,id}' is distinct from old.annotation #> '{creator,id}'
+    and acornly_private.has_children(new.id)
+  then
+    raise exception 'annotation % has replies; its author stays', new.id using errcode = 'CH001';
+  end if;
+  -- An unchanged or narrower audience is fine even if the parent was narrowed
+  -- meanwhile. A wider one is checked against the parent, locked so a
+  -- concurrent narrowing cannot slip past; a reply from before threads nested
+  -- is checked against its root.
+  if new.thread_root_id is not null
+    and not acornly_private.audience_within(new.audience, old.audience)
+    and not acornly_private.audience_within(
+      new.audience,
+      acornly_private.locked_audience(coalesce(old.parent_id, old.thread_root_id))
+    )
+  then
+    raise exception 'annotation % cannot widen its parent''s audience', new.id
+      using errcode = 'CH002';
+  end if;
+  return new;
+end
+$$;
+
+-- Plain deletes keep the tree; `acornly_delete_node` and cascades (a
+-- deleted user's notes) are let through.
+create or replace function acornly_private.check_delete()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+  if acornly_private.in_delete_node() or pg_trigger_depth() > 1 then
+    return old;
+  end if;
+  if old.parent_id is not null then
+    raise exception 'annotation % is context on context; use threads.deleteNode', old.id
+      using errcode = 'CH001';
+  end if;
+  if acornly_private.has_children(old.id) then
+    raise exception 'annotation % has children; use threads.deleteNode', old.id
+      using errcode = 'CH001';
+  end if;
+  return old;
+end
+$$;
+
+-- The write trigger on versions.
+create or replace function acornly_private.prepare_version()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  author uuid;
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,rev}') is distinct from 'number'
+    or (a #>> '{ext,rev}') !~ '^[1-9][0-9]{0,8}$'
+  then
+    raise exception 'a version needs a string id and a positive integer ext.rev'
+      using errcode = '23514';
+  end if;
+  new.note_id := a ->> 'id';
+  new.rev := (a #>> '{ext,rev}')::integer;
+  if tg_op = 'UPDATE' and (new.note_id <> old.note_id or new.rev <> old.rev) then
+    raise exception 'a saved version keeps its id and rev' using errcode = '23514';
+  end if;
+  -- Read as the caller: a client finds only notes it can read.
+  select n.creator_id into author from public.acornly_annotations n where n.id = new.note_id;
+  if not found then
+    raise exception 'annotation % not found', new.note_id using errcode = 'P0002';
+  end if;
+  if not acornly_private.trusted_caller() and author is distinct from auth.uid() then
+    raise exception 'only the author keeps versions of annotation %', new.note_id
+      using errcode = '42501';
+  end if;
+  new.creator_id := author;
+  return new;
+end
+$$;
+
+-- The ids in a thread the caller may read: the read policy's rules worked out
+-- top-down in one pass, seeded with the root and its replies from before
+-- threads nested and then walking children through the parent index, so the
+-- cost is linear in the thread's size whatever its shape. The caller's own
+-- notes are always in, and everything for the site's server. Empty unless
+-- `root_id` is a note on a page in `thread_scope`.
+create or replace function acornly_private.thread_visible(root_id text, thread_scope text)
+returns setof text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with recursive
+  me (uid, trusted, scope_readable) as materialized (
+    select auth.uid(),
+           acornly_private.trusted_caller(),
+           acornly_private.public_readable(thread_scope)
+  ),
+  tree (id, path_readable, depth) as (
+    select a.id,
+           coalesce(a.creator_id = me.uid or (a.audience = 'public' and me.scope_readable), false),
+           0
+      from public.acornly_annotations a, me
+     where a.id = root_id
+       and a.scope = thread_scope
+       and a.parent_id is null
+       and a.thread_root_id is null
+    union all
+    -- Replies from before threads nested target the page and name the root.
+    select c.id,
+           r.path_readable
+             and coalesce(c.creator_id = me.uid or (c.audience = 'public' and me.scope_readable), false),
+           1
+      from public.acornly_annotations a
+      join public.acornly_annotations c
+        on c.thread_root_id = a.id and c.parent_id is null and c.scope = thread_scope
+      cross join me
+      cross join lateral (
+        select coalesce(a.creator_id = me.uid or (a.audience = 'public' and me.scope_readable), false)
+      ) r (path_readable)
+     where a.id = root_id and a.scope = thread_scope and a.thread_root_id is null
+    union all
+    select c.id,
+           t.path_readable
+             and coalesce(c.creator_id = me.uid or (c.audience = 'public' and me.scope_readable), false),
+           t.depth + 1
+      from tree t
+      join public.acornly_annotations c on c.parent_id = t.id
+      cross join me
+     where c.scope = thread_scope and t.depth < 10000
+  )
+  select t.id from tree t, me where t.path_readable or me.trusted
+  union
+  -- The caller's own notes, and everything for the site's server, even below a
+  -- parent that is gone.
+  select a.id
+    from public.acornly_annotations a, me
+   where a.scope = thread_scope
+     and a.thread_root_id = root_id
+     and (a.creator_id = me.uid or me.trusted)
+     -- Only a real root starts a thread.
+     and exists (select 1 from tree t where t.depth = 0)
+$$;
+
+-- A thread's root and every node below it in one scope, as the caller may read
+-- them, as one JSON array of annotations ordered by `modified` and id. One call
+-- returns everything, as paging would redo the walk for each page.
+create or replace function public.acornly_list_thread(root_id text, thread_scope text)
+returns jsonb
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(jsonb_agg(a.annotation order by a.modified, a.id), '[]'::jsonb)
+    from acornly_private.thread_visible(root_id, thread_scope) v (id)
+    join public.acornly_annotations a on a.id = v.id
+$$;
+
+-- The number of direct children of each id that the caller may read. Replies
+-- from before threads nested are left out, as `assembleThread` does not place
+-- them. Ids with none are left out.
+-- Visibility comes from one top-down walk per thread involved.
+create or replace function public.acornly_count_children(ids text[])
+returns table (id text, children bigint)
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with children (parent, child, thread_root_id, scope) as materialized (
+    select c.parent_id, c.id, c.thread_root_id, c.scope
+      from public.acornly_annotations c
+     where c.parent_id = any (ids)
+  ),
+  visible (id) as materialized (
+    select v.id
+      from (select distinct thread_root_id, scope from children) t
+      cross join lateral acornly_private.thread_visible(t.thread_root_id, t.scope) v (id)
+  )
+  select c.parent, count(*)
+    from children c
+    join visible v on v.id = c.child
+   group by c.parent
+$$;
+
+-- Deletes `note_id` at `expected_rev` for its author (or the site's server).
+-- A note with any child becomes a placeholder at the next rev, modified at
+-- `deleted_at`: no body, author name or edited mark, `ext.deleted` true, and
+-- its versions dropped. One without children is removed, and so is each
+-- placeholder above it left with no children. Returns
+-- `{"placeholder": <annotation>}` or `{"removed": [{id, scope, document}, ...]}`,
+-- the note first.
+create or replace function public.acornly_delete_node(
+  note_id text,
+  expected_rev integer,
+  deleted_at text
+)
+returns jsonb
+language plpgsql
+volatile
+security definer
+set search_path = ''
+as $$
+declare
+  target public.acornly_annotations;
+  node public.acornly_annotations;
+  above public.acornly_annotations;
+  placeholder jsonb;
+  removed jsonb := '[]'::jsonb;
+  trusted boolean := acornly_private.trusted_caller();
+begin
+  select * into target from public.acornly_annotations a where a.id = note_id for update;
+  if not found or not (trusted or acornly_private.can_read(target)) then
+    raise exception 'annotation % not found', note_id using errcode = 'P0002';
+  end if;
+  if not trusted and target.creator_id is distinct from auth.uid() then
+    raise exception 'Not allowed to change annotation %', note_id using errcode = '42501';
+  end if;
+  if target.rev <> expected_rev then
+    raise exception 'annotation % is at rev %, expected %', note_id, target.rev, expected_rev
+      using errcode = 'CH003', detail = target.rev::text;
+  end if;
+
+  perform set_config('acornly.delete_node', 'on', true);
+
+  if acornly_private.has_children(note_id) then
+    placeholder := (target.annotation - 'body') || jsonb_build_object('modified', deleted_at);
+    placeholder := jsonb_set(
+      placeholder,
+      '{ext}',
+      ((target.annotation -> 'ext') - 'edited') || '{"deleted": true}'::jsonb
+    );
+    if jsonb_typeof(target.annotation -> 'creator') = 'object' then
+      placeholder := jsonb_set(
+        placeholder,
+        '{creator}',
+        jsonb_strip_nulls(jsonb_build_object('id', target.annotation #> '{creator,id}'))
+      );
+    end if;
+    update public.acornly_annotations a
+       set annotation = placeholder
+     where a.id = note_id
+    returning a.annotation into placeholder;
+    delete from public.acornly_versions v where v.note_id = target.id;
+    perform set_config('acornly.delete_node', '', true);
+    return jsonb_build_object('placeholder', placeholder);
+  end if;
+
+  -- Remove it, then each placeholder above it left with no children. Each
+  -- parent is locked before its children are counted, so a child landing
+  -- meanwhile either waits for this delete or is seen.
+  node := target;
+  loop
+    delete from public.acornly_annotations a where a.id = node.id;
+    removed := removed || jsonb_build_object(
+      'id', node.id, 'scope', node.scope, 'document', node.document
+    );
+    exit when coalesce(node.parent_id, node.thread_root_id) is null;
+    select * into above from public.acornly_annotations a
+     where a.id = coalesce(node.parent_id, node.thread_root_id)
+       for update;
+    -- An orphan's parent went with its author: its root may still be waiting.
+    if not found and node.parent_id is not null and node.thread_root_id is not null then
+      select * into above from public.acornly_annotations a
+       where a.id = node.thread_root_id
+         for update;
+    end if;
+    exit when not found
+      or not acornly_private.is_deleted(above.annotation)
+      or acornly_private.has_children(above.id);
+    node := above;
+  end loop;
+  perform set_config('acornly.delete_node', '', true);
+  return jsonb_build_object('removed', removed);
+end
+$$;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261010070000', 'acornly_names');
+  end if;
+end
+$acornly_install$;
+
+-- 20261011080000_acornly_delete_node_grants.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261011080000') then
+    raise notice 'acornly: applying %', '20261011080000_acornly_delete_node_grants.sql';
+    execute $acornly_migration$
+-- Only signed-in callers (and the service role) may run `acornly_delete_node`,
+-- as the threads migration meant.
+--
+-- That migration revoked it from `public` and granted it to `authenticated`
+-- and `service_role`, but Supabase's default privileges give `anon` its own
+-- grant on every function created in `public`, and revoking from `public`
+-- leaves that grant in place. A visitor could not delete anything with it,
+-- since only a note's creator may and every note has one, but the function
+-- should refuse them before it looks a note up.
+revoke execute on function public.acornly_delete_node(text, integer, text) from anon;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261011080000', 'acornly_delete_node_grants');
+  end if;
+end
+$acornly_install$;
+
+-- 20261011150000_acornly_parent_ids.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261011150000') then
+    raise notice 'acornly: applying %', '20261011150000_acornly_parent_ids.sql';
+    execute $acornly_migration$
+-- A reply's target may name its parent under `urn:acornly:annotation:` as well as
+-- `urn:contexthive:annotation:` (docs/design/acornly-rename.md, phase 3). Without this, a reply
+-- written by a version of core that uses the new prefix is refused (CH001: thread fields on a note
+-- that targets a page).
+--
+-- create or replace keeps the function's owner and grants.
+create or replace function acornly_private.parent_id_of(source text)
+returns text
+language plpgsql
+stable
+set search_path = ''
+as $$
+declare
+  prefix text;
+  encoded text;
+  decoded text;
+begin
+  prefix := case
+    when lower(left(source, 23)) = 'urn:acornly:annotation:' then 'urn:acornly:annotation:'
+    when lower(left(source, 27)) = 'urn:contexthive:annotation:' then 'urn:contexthive:annotation:'
+  end;
+  if prefix is null then
+    return null;
+  end if;
+  encoded := substr(source, length(prefix) + 1);
+  if encoded !~ '^([^%]|%[0-9A-Fa-f]{2})*$' then
+    raise exception 'target % is badly escaped', source using errcode = 'CH001';
+  end if;
+  begin
+    select convert_from(
+             coalesce(
+               string_agg(
+                 case when m[1] is not null
+                   then decode(substr(m[1], 2), 'hex')
+                   else convert_to(m[2], 'UTF8')
+                 end,
+                 ''::bytea order by n
+               ),
+               ''::bytea
+             ),
+             'UTF8'
+           )
+      into decoded
+      from regexp_matches(encoded, '(%[0-9A-Fa-f]{2})|([^%]+)', 'g') with ordinality as t (m, n);
+  exception when character_not_in_repertoire or untranslatable_character then
+    raise exception 'target % is badly escaped', source using errcode = 'CH001';
+  end;
+  if decoded = '' then
+    raise exception 'target % names an empty id', source using errcode = 'CH001';
+  end if;
+  return decoded;
+end
+$$;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261011150000', 'acornly_parent_ids');
+  end if;
+end
+$acornly_install$;
+
+-- 20261011170000_acornly_pdf_document_keys.sql
+do $acornly_install$
+begin
+  if not exists (select 1 from acornly_meta.migrations where version = '20261011170000') then
+    raise notice 'acornly: applying %', '20261011170000_acornly_pdf_document_keys.sql';
+    execute $acornly_migration$
+-- Notes on PDFs are listed by the file's key (#403).
+--
+-- A note on a PDF carries `ext.documentKey`, `urn:x-pdf:<fingerprint>` (see
+-- `pdfDocumentKey` in @acornly/core), and `target.source` keeps the URL it was
+-- made on, so the same file opened from another URL shows its notes. The
+-- `document` column now holds that key, as `documentKeyOf` reads it: the key
+-- when it is a valid PDF key, else `target.source`. Notes stored before keep
+-- their source as their document.
+--
+-- The key is set when a note is made and never changes: an update that leaves
+-- it out, or names another, gets the stored one back, and a note's
+-- `target.source` stays as before. A reply's document is still its target
+-- (whatever key it carries), and its parent is still read from it. Notes stored
+-- before with a key already in their annotation move to it below.
+
+-- `documentKeyOf` for a stored annotation. The trigger runs as its caller, so
+-- every role that writes notes may call it, as the other helpers it uses.
+create or replace function acornly_private.document_of(a jsonb)
+returns text
+language sql
+immutable
+set search_path = ''
+as $$
+  select case
+    when jsonb_typeof(a #> '{ext,documentKey}') = 'string'
+      and (a #>> '{ext,documentKey}') ~ '^urn:x-pdf:[0-9a-f]{2,128}$'
+      and (a #>> '{target,source}') !~* '^urn:(acornly|contexthive):annotation:'
+      then a #>> '{ext,documentKey}'
+    else a #>> '{target,source}'
+  end
+$$;
+
+revoke all on function acornly_private.document_of(jsonb) from public;
+grant execute on function acornly_private.document_of(jsonb)
+  to anon, authenticated, service_role;
+
+-- The write trigger on notes, from 20261010070000_acornly_names.sql with the
+-- document key.
+create or replace function acornly_private.prepare_annotation()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+declare
+  a jsonb := new.annotation;
+  audience_kind text := a #>> '{ext,audience,kind}';
+  -- The site's own server code writing on a user's behalf.
+  trusted boolean := acornly_private.trusted_caller();
+begin
+  if jsonb_typeof(a -> 'id') is distinct from 'string'
+    or jsonb_typeof(a #> '{ext,scope}') is distinct from 'string'
+    or jsonb_typeof(a #> '{target,source}') is distinct from 'string'
+    or jsonb_typeof(a -> 'modified') is distinct from 'string'
+    -- ISO 8601 only, so no `infinity`, `now` or other special values.
+    or (a ->> 'modified') !~ '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}(:?\d{2})?)$'
+    or coalesce(jsonb_typeof(a #> '{ext,threadRoot}'), 'null') not in ('string', 'null')
+  then
+    raise exception 'id, ext.scope and target.source must be strings, modified an ISO 8601 time, and ext.threadRoot a string or null'
+      using errcode = '23514';
+  end if;
+  if coalesce(jsonb_typeof(a #> '{ext,depth}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,parentRev}'), 'null') not in ('number', 'null')
+    or coalesce(jsonb_typeof(a #> '{ext,deleted}'), 'null') not in ('boolean', 'null')
+  then
+    raise exception 'ext.depth and ext.parentRev must be numbers and ext.deleted a boolean'
+      using errcode = '23514';
+  end if;
+
+  if tg_op = 'INSERT' then
+    if not trusted then
+      -- Clients cannot write this column; the author is always the caller.
+      new.creator_id := auth.uid();
+      if new.creator_id is null then
+        raise exception 'sign in to write notes' using errcode = '42501';
+      end if;
+    elsif new.creator_id is null then
+      raise exception 'creator_id is required' using errcode = '23502';
+    end if;
+    new.rev := 1;
+  else
+    new.creator_id := old.creator_id;
+    new.rev := old.rev + 1;
+    -- A note's document key never changes: the stored one, or none, stays.
+    a := case
+      when old.annotation #> '{ext,documentKey}' is null then a #- '{ext,documentKey}'
+      else jsonb_set(a, '{ext,documentKey}', old.annotation #> '{ext,documentKey}')
+    end;
+  end if;
+
+  if audience_kind is null or audience_kind not in ('private', 'public') then
+    raise exception 'audience "%" is not supported here; use private or public', audience_kind
+      using errcode = '23514';
+  end if;
+
+  new.id := a ->> 'id';
+  new.scope := a #>> '{ext,scope}';
+  new.document := acornly_private.document_of(a);
+  new.audience := audience_kind;
+  new.thread_root_id := a #>> '{ext,threadRoot}';
+  -- The document never changes, so neither does the parent; notes stored
+  -- before this migration keep theirs (none) when edited.
+  new.parent_id := case
+    when tg_op = 'UPDATE' then old.parent_id
+    else acornly_private.parent_id_of(a #>> '{target,source}')
+  end;
+  new.modified := (a ->> 'modified')::timestamptz;
+  new.annotation := jsonb_set(a, '{ext,rev}', to_jsonb(new.rev));
+
+  if tg_op = 'INSERT' then
+    if acornly_private.is_deleted(a) then
+      raise exception 'a new annotation cannot be deleted' using errcode = 'CH001';
+    end if;
+    if new.parent_id is null then
+      if new.thread_root_id is not null
+        or a #> '{ext,depth}' is not null
+        or a #> '{ext,parentRev}' is not null
+      then
+        raise exception 'annotation % has thread fields but targets a page', new.id
+          using errcode = 'CH001';
+      end if;
+    else
+      perform acornly_private.check_child(
+        new.parent_id, a, new.scope, new.thread_root_id, new.audience
+      );
+    end if;
+    return new;
+  end if;
+
+  if new.id is distinct from old.id then
+    raise exception 'id cannot change' using errcode = '23514';
+  end if;
+  -- `acornly_delete_node` writing a placeholder.
+  if acornly_private.in_delete_node() then
+    return new;
+  end if;
+  if acornly_private.is_deleted(a) is distinct from acornly_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted or restored only by deleteNode', new.id
+      using errcode = 'CH001';
+  end if;
+  if acornly_private.is_deleted(old.annotation) then
+    raise exception 'annotation % is deleted', new.id using errcode = 'CH001';
+  end if;
+  if new.scope is distinct from old.scope
+    or new.document is distinct from old.document
+    or new.thread_root_id is distinct from old.thread_root_id
+    or a #> '{ext,depth}' is distinct from old.annotation #> '{ext,depth}'
+    or a #> '{ext,parentRev}' is distinct from old.annotation #> '{ext,parentRev}'
+    or (old.parent_id is not null and a -> 'target' is distinct from old.annotation -> 'target')
+    -- The document no longer says whether the source moved: a note on a PDF keeps its URL too.
+    or a #> '{target,source}' is distinct from old.annotation #> '{target,source}'
+  then
+    raise exception 'annotation % cannot move: id, scope, target.source and threadRoot cannot change',
+      new.id using errcode = 'CH001';
+  end if;
+  if a #> '{creator,id}' is distinct from old.annotation #> '{creator,id}'
+    and acornly_private.has_children(new.id)
+  then
+    raise exception 'annotation % has replies; its author stays', new.id using errcode = 'CH001';
+  end if;
+  -- An unchanged or narrower audience is fine even if the parent was narrowed
+  -- meanwhile. A wider one is checked against the parent, locked so a
+  -- concurrent narrowing cannot slip past; a reply from before threads nested
+  -- is checked against its root.
+  if new.thread_root_id is not null
+    and not acornly_private.audience_within(new.audience, old.audience)
+    and not acornly_private.audience_within(
+      new.audience,
+      acornly_private.locked_audience(coalesce(old.parent_id, old.thread_root_id))
+    )
+  then
+    raise exception 'annotation % cannot widen its parent''s audience', new.id
+      using errcode = 'CH002';
+  end if;
+  return new;
+end
+$$;
+
+-- Notes stored before this migration with a PDF key in their annotation (written
+-- after core gave notes keys) move to it. The write trigger would refuse the
+-- move, so it is off for this one statement.
+alter table public.acornly_annotations disable trigger acornly_annotations_prepare;
+update public.acornly_annotations
+   set document = acornly_private.document_of(annotation)
+ where document is distinct from acornly_private.document_of(annotation);
+alter table public.acornly_annotations enable trigger acornly_annotations_prepare;
+$acornly_migration$;
+    insert into acornly_meta.migrations (version, name) values ('20261011170000', 'acornly_pdf_document_keys');
+  end if;
+end
+$acornly_install$;
+
+commit;