dzql 0.6.37 → 0.8.0

package/src/sql/001b-delta-scope.sql

@@ -0,0 +1,619 @@
+-- =========================================================================
+-- Delta-doc: doc lookup, scope resolution, temporal helpers
+-- =========================================================================
+
+-- ---------------------------------------------------------------------------
+-- _delta_find_doc: match a doc name to its definition
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_find_doc(p_doc_name TEXT)
+RETURNS _delta_docs AS $$
+  -- Exact prefix match (NOT LIKE): a prefix containing `_` or `%` would
+  -- otherwise be treated as a LIKE wildcard and over-match. Mirrors the
+  -- TypeScript resolver's startsWith.
+  SELECT * FROM _delta_docs
+   WHERE left(p_doc_name, length(prefix)) = prefix
+   ORDER BY length(prefix) DESC
+   LIMIT 1;
+$$ LANGUAGE sql STABLE;
+
+-- ---------------------------------------------------------------------------
+-- _delta_resolve_scope: turn a doc name + def into WHERE clause + metadata
+--
+-- Scope binding syntax:  { "column": "op:param" }
+--   "=:name"      → column = <value>           (equality)
+--   "<=:name"     → column <= <value>           (range)
+--   ">=:name"     → column >= <value>           (range)
+--   "like:name"   → column ILIKE <value>%       (prefix search)
+--   "at:name"     → reserved: temporal snapshot  (not a WHERE condition)
+--   ":name"       → shorthand for "=:name"
+--
+-- Named params are resolved positionally from the colon-separated doc ID.
+-- Empty resolved values are skipped (no filter applied for that entry).
+--
+-- A value is read as its column takes it, by one grammar on every backend (the
+-- SQLite backend's scopeValue is its twin), and one it cannot take is refused
+-- (22P02, a 400): an integer's is digits, signed, up to 2^53 - 1 (not 1_000 or
+-- 0x10, which Postgres's own cast takes); a real's a finite decimal number (not
+-- Infinity, NaN or 0x10), one a double holds; an id's or a parent key's a whole
+-- number, or text no row here has (below); a timestamptz's a date, YYYY-MM-DD,
+-- the instant midnight UTC begins it (the cast's own 22007 would be a 500). Other
+-- types are left to the column's cast, which reads them as SQLite does.
+--
+-- Returns JSONB:
+--   { "where":  "SQL WHERE clause",
+--     "values": { equality bindings for ADD ops },
+--     "mode":   "list" | "single",
+--     "at":     "2026-06-01" | null }
+--
+-- With p_refuse false a value refused is not raised: the answer is the scope
+-- that holds nothing ("where" FALSE, list mode), with "refused" its message --
+-- how the fan-out reads a name opened before a rule refused it (_delta_doc_holds).
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
+RETURNS JSONB AS $$
+DECLARE
+  v_doc_id    TEXT;
+  v_scope     JSONB;
+  v_parts     TEXT[];
+  v_key       TEXT;
+  v_val       TEXT;
+  v_op        TEXT;
+  v_param     TEXT;
+  v_resolved  TEXT;
+  v_where     TEXT := '';
+  v_values    JSONB := '{}'::jsonb;
+  v_at        TEXT := NULL;
+  v_mode      TEXT;
+  v_param_map JSONB := '{}'::jsonb;
+  v_root_coll RECORD;
+  v_type      TEXT;
+  v_refused   TEXT;
+  v_cond      TEXT;
+  v_date      TEXT[];
+BEGIN
+  v_doc_id := substring(p_doc_name FROM length(p_def.prefix) + 1);
+  v_scope  := p_def.scope;
+
+  -- Fail-fast: every scope key must be a real column of the root collection.
+  -- Catches typos and the "dotted key" footgun (e.g. "kanban_boards.id")
+  -- before they silently produce an always-empty WHERE.
+  IF v_scope IS NOT NULL AND v_scope != '{}'::jsonb THEN
+    DECLARE
+      v_bad_key        TEXT;
+      v_valid_keys_txt TEXT;
+    BEGIN
+      SELECT * INTO v_root_coll FROM _delta_collections
+       WHERE collection_key = p_def.root_collection;
+      IF NOT FOUND THEN
+        RAISE EXCEPTION 'doc "%" references unknown root collection: %',
+          p_def.prefix, p_def.root_collection
+          USING ERRCODE = 'P0001';
+      END IF;
+
+      -- "id" is implicit; parent_fk is implicit if set. `at:`-typed values
+      -- feed the temporal snapshot marker and don't go through the WHERE,
+      -- so their keys (typically `valid_from`) don't need to be real columns.
+      SELECT k INTO v_bad_key
+        FROM jsonb_each_text(v_scope) AS x(k, val)
+       WHERE k != 'id'
+         AND k IS DISTINCT FROM v_root_coll.parent_fk
+         AND NOT (_delta_cols(v_root_coll.collection_key, v_root_coll.columns_def) ? k)
+         AND val !~ '^at:'
+       LIMIT 1;
+
+      IF v_bad_key IS NOT NULL THEN
+        SELECT 'id'
+             || CASE WHEN v_root_coll.parent_fk IS NOT NULL
+                     THEN ', ' || v_root_coll.parent_fk
+                     ELSE '' END
+             || COALESCE(
+                  (SELECT ', ' || string_agg(kk, ', ')
+                     FROM jsonb_object_keys(_delta_cols(v_root_coll.collection_key, v_root_coll.columns_def)) kk),
+                  '')
+          INTO v_valid_keys_txt;
+        RAISE EXCEPTION
+          'scope key "%" is not a column of "%" (valid keys: %)',
+          v_bad_key, v_root_coll.collection_key, v_valid_keys_txt
+          USING ERRCODE = 'P0001';
+      END IF;
+    END;
+  END IF;
+
+  -- Empty scope: default behaviour
+  IF v_scope = '{}'::jsonb OR v_scope IS NULL THEN
+    IF v_doc_id = '' THEN
+      RETURN jsonb_build_object(
+        'where', 'TRUE', 'values', '{}'::jsonb, 'mode', 'list', 'at', NULL
+      );
+    ELSE
+      RETURN jsonb_build_object(
+        'where', format('id = %L', v_doc_id),
+        'values', jsonb_build_object('id', v_doc_id::BIGINT),
+        'mode', 'single',
+        'at', NULL
+      );
+    END IF;
+  END IF;
+
+  -- Build positional param map from colon-separated doc ID parts.
+  -- Params named "id" always get position 1. Remaining params are assigned
+  -- in alphabetical order to subsequent positions.
+  v_parts := string_to_array(v_doc_id, ':');
+
+  SELECT jsonb_object_agg(p, to_jsonb(COALESCE(v_parts[pos], '')))
+  INTO v_param_map
+  FROM (
+    SELECT DISTINCT param AS p,
+           row_number() OVER (ORDER BY (param != 'id'), param) AS pos
+    FROM (
+      SELECT CASE
+        WHEN val ~ '^(at|like):' THEN substring(val FROM '[a-z]+:(.+)$')
+        WHEN val ~ '^[<>=!]+:'   THEN substring(val FROM '[<>=!]+:(.+)$')
+        ELSE ltrim(val, ':')
+      END AS param
+      FROM jsonb_each_text(v_scope) AS x(key, val)
+    ) params
+  ) ordered;
+
+  -- Second pass: process each scope entry using the resolved param map
+  FOR v_key, v_val IN SELECT * FROM jsonb_each_text(v_scope)
+  LOOP
+    -- Parse operator and param name
+    IF v_val ~ '^(at):' THEN
+      v_op    := 'at';
+      v_param := substring(v_val FROM 'at:(.+)$');
+    ELSIF v_val ~ '^(like):' THEN
+      v_op    := 'like';
+      v_param := substring(v_val FROM 'like:(.+)$');
+    ELSIF v_val ~ '^[<>=!]+:' THEN
+      v_op    := substring(v_val FROM '^([<>=!]+):');
+      v_param := substring(v_val FROM '[<>=!]+:(.+)$');
+      -- Defence in depth: the regex above only matches `<`, `>`, `=`, `!`
+      -- characters, and the scope value is app-controlled (from _delta_docs),
+      -- but we still whitelist the final operator so any future exposure of
+      -- the scope DSL to user input can't smuggle arbitrary SQL into
+      -- `format('%I %s %L', ...)`.
+      IF v_op NOT IN ('=', '>=', '<=', '>', '<', '!=') THEN
+        RAISE EXCEPTION
+          'invalid scope operator "%" (valid: =, >=, <=, >, <, !=, like, at)',
+          v_op USING ERRCODE = 'P0001';
+      END IF;
+    ELSE
+      v_op    := '=';
+      v_param := ltrim(v_val, ':');
+    END IF;
+
+    v_resolved := v_param_map ->> v_param;
+
+    -- Skip empty resolved values (no filter)
+    IF v_resolved IS NULL OR v_resolved = '' THEN CONTINUE; END IF;
+
+    -- The value as its column takes it: one its column cannot take is refused.
+    -- A time in the name (at:) is a date, as a time column's condition is.
+    v_cond := NULL;
+    IF v_op <> 'like' THEN
+      v_type := CASE WHEN v_op = 'at' THEN 'timestamptz' ELSE _delta_cols(v_root_coll.collection_key, v_root_coll.columns_def)->v_key->>'type' END;
+      IF v_op <> 'at' AND (v_key = 'id' OR v_key = v_root_coll.parent_fk) THEN
+        -- An id, as SQLite reads one: a whole number, signed, up to 2^53 - 1;
+        -- one not whole is none (1.5, 1e0); other text is an id SQLite keeps as
+        -- text (a session's token). No row here has one -- every id is a number --
+        -- so it compares as SQLite orders it, after every number: = > >= read no
+        -- row, != < <= every row. (Single mode's id is the root's: still a 400.)
+        IF v_resolved ~ '^\s*[+-]?[0-9]+\s*$' THEN
+          IF v_resolved !~ '^\s*[+-]?0*[0-9]{1,16}\s*$' THEN
+            v_refused := format('%s %s is past 2^53 - 1, which no number holds exactly', v_key, v_resolved);
+          ELSIF abs(v_resolved::numeric) > 9007199254740991 THEN
+            v_refused := format('%s %s is past 2^53 - 1, which no number holds exactly', v_key, v_resolved);
+          END IF;
+        ELSIF v_resolved ~* '^\s*[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)(e[+-]?[0-9]+)?\s*$' THEN
+          v_refused := format('%s must be an id -- a whole number, or text -- not "%s"', v_key, v_resolved);
+        ELSE
+          v_cond := CASE WHEN v_op IN ('!=', '<', '<=') THEN format('%I IS NOT NULL', v_key) ELSE 'FALSE' END;
+        END IF;
+      ELSIF v_type = 'integer' THEN
+        -- at most 16 digits past any zeros (2^53 - 1 has 16), so the cast that follows cannot fail
+        IF v_resolved !~ '^\s*[+-]?0*[0-9]{1,16}\s*$' THEN
+          v_refused := format('%s must be an integer, not "%s"', v_key, v_resolved);
+        ELSIF abs(v_resolved::numeric) > 9007199254740991 THEN
+          v_refused := format('%s must be an integer, not "%s"', v_key, v_resolved);
+        END IF;
+      ELSIF v_type = 'real' THEN
+        IF v_resolved !~* '^\s*[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)(e[+-]?[0-9]+)?\s*$' THEN
+          v_refused := format('%s must be a number, not "%s"', v_key, v_resolved);
+        ELSE
+          BEGIN
+            PERFORM v_resolved::float8;
+          EXCEPTION WHEN numeric_value_out_of_range THEN   -- 1e400, 1e-400: past what a double holds
+            v_refused := format('%s must be a number, not "%s"', v_key, v_resolved);
+          END;
+        END IF;
+      ELSIF v_type = 'timestamptz' THEN
+        -- A date, YYYY-MM-DD (a name's ":" separates its values, so it holds no
+        -- time of day), read as the instant midnight UTC begins it, whatever
+        -- the session's TimeZone -- as SQLite reads it; not now, 20260101 or
+        -- Jan 1 2026, which Postgres's own cast takes. (The day a statement of
+        -- its own, so make_date is asked only of a month there is.)
+        v_date := regexp_match(v_resolved, '^\s*([0-9]{4})-([0-9]{2})-([0-9]{2})\s*$');
+        IF v_date IS NULL OR v_date[1]::int < 1 OR v_date[2]::int NOT BETWEEN 1 AND 12 THEN
+          v_refused := format('%s must be a date, YYYY-MM-DD, not "%s"', v_key, v_resolved);
+        ELSIF v_date[3]::int NOT BETWEEN 1 AND extract(day FROM make_date(v_date[1]::int, v_date[2]::int, 1) + interval '1 month - 1 day')::int THEN
+          v_refused := format('%s must be a date, YYYY-MM-DD, not "%s"', v_key, v_resolved);
+        ELSE
+          v_resolved := format('%s-%s-%s 00:00:00+00', v_date[1], v_date[2], v_date[3]);
+        END IF;
+      END IF;
+      IF v_refused IS NOT NULL THEN
+        IF p_refuse THEN RAISE EXCEPTION '%', v_refused USING ERRCODE = '22P02'; END IF;
+        RETURN jsonb_build_object('where', 'FALSE', 'values', '{}'::jsonb, 'mode', 'list', 'at', NULL, 'refused', v_refused);
+      END IF;
+    END IF;
+
+    -- Handle each operator
+    CASE v_op
+      WHEN 'at' THEN
+        v_at := v_resolved;
+
+      WHEN 'like' THEN
+        IF v_where != '' THEN v_where := v_where || ' AND '; END IF;
+        v_where := v_where || format('%I ILIKE %L', v_key, v_resolved || '%');
+
+      WHEN '=' THEN
+        IF v_where != '' THEN v_where := v_where || ' AND '; END IF;
+        v_where := v_where || COALESCE(v_cond, format('%I = %L', v_key, v_resolved));
+        v_values := v_values || jsonb_build_object(v_key, v_resolved);
+
+      ELSE
+        -- Range operators: >=, <=, >, <, !=
+        IF v_where != '' THEN v_where := v_where || ' AND '; END IF;
+        v_where := v_where || COALESCE(v_cond, format('%I %s %L', v_key, v_op, v_resolved));
+    END CASE;
+  END LOOP;
+
+  -- Default to no filter if nothing was added
+  IF v_where = '' THEN v_where := 'TRUE'; END IF;
+
+  -- Mode: single if we have an id equality, list otherwise
+  IF v_values ? 'id' THEN
+    v_mode := 'single';
+  ELSE
+    v_mode := 'list';
+  END IF;
+
+  RETURN jsonb_build_object('where', v_where, 'values', v_values, 'mode', v_mode, 'at', v_at);
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- The resolver as every caller but the fan-out asks it: a value refused is raised.
+CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT)
+RETURNS JSONB LANGUAGE sql STABLE AS $$
+  SELECT _delta_resolve_scope(p_def, p_doc_name, TRUE);
+$$;
+
+-- ---------------------------------------------------------------------------
+-- _delta_scope_row: the scope's equality values (_delta_resolve_scope's
+-- `values`, the name's text), as a list-mode add of a root row is given them:
+-- as the scope's condition reads each (todo #46). The condition casts its text
+-- to the column's type; jsonb_populate_record does the same with a JSON string
+-- for every type but json, where it keeps the string whole -- a name's 5 stored
+-- as "5", which `wishes = '5'` does not match. So a json column's value is the
+-- JSON its text is (5 is 5, "5" the string); every other column's stays text,
+-- for the column to cast. The SQLite backend's scopeValue reads it the same way.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_scope_row(p_columns JSONB, p_values JSONB)
+RETURNS JSONB LANGUAGE sql IMMUTABLE AS $$
+  SELECT COALESCE(jsonb_object_agg(
+           k, CASE WHEN p_columns->k->>'type' = 'json' THEN (v #>> '{}')::jsonb ELSE v END), '{}'::jsonb)
+    FROM jsonb_each(COALESCE(p_values, '{}'::jsonb)) AS x(k, v);
+$$;
+
+-- ---------------------------------------------------------------------------
+-- _delta_row_in_scope: may this doc address this row?
+--
+-- Mirrors the READ filtering in _delta_load_collection / delta_open exactly,
+-- so the rule is simply "you may write what you may read".
+--
+-- Reads were always scoped, but writes addressed rows by bare id: a client
+-- holding `tenant:1` could name a row id belonging to `tenant:2` and remove or
+-- overwrite it. delta_apply now gates every row-addressed write through here.
+-- Returning FALSE for a row that exists but is invisible (including one hidden
+-- by RLS) is deliberate — it keeps "forbidden" and "absent" indistinguishable
+-- so the gate can't be used to probe for ids.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_row_in_scope(
+  p_def            _delta_docs,
+  p_doc_name       TEXT,
+  p_collection_key TEXT,
+  p_id             BIGINT
+) RETURNS BOOLEAN AS $$
+DECLARE
+  v_scope    JSONB;
+  v_is_list  BOOLEAN;
+  v_root_id  BIGINT;
+  v_coll     RECORD;
+  v_cur_coll TEXT;
+  v_cur_id   BIGINT;
+  v_view     TEXT;
+  v_exists   BOOLEAN;
+  v_depth    INT := 0;
+BEGIN
+  IF p_id IS NULL THEN RETURN FALSE; END IF;
+
+  v_scope   := _delta_resolve_scope(p_def, p_doc_name);
+  v_is_list := (v_scope->>'mode') = 'list';
+
+  IF v_is_list THEN
+    -- List mode: `include`d collections are loaded in FULL by
+    -- _delta_load_collection_all (no FK filter), so every row of them is
+    -- readable and therefore writable. Only the root is narrowed, by the
+    -- resolved WHERE.
+    IF p_collection_key IS DISTINCT FROM p_def.root_collection THEN
+      RETURN TRUE;
+    END IF;
+    SELECT * INTO v_coll FROM _delta_collections
+     WHERE collection_key = p_collection_key;
+    IF NOT FOUND THEN RETURN FALSE; END IF;
+    v_view := _delta_source_view(v_coll.table_name, v_coll.temporal);
+    EXECUTE format(
+      'SELECT EXISTS(SELECT 1 FROM %I t WHERE t.id = $1 AND %s)',
+      v_view, COALESCE(v_scope->>'where', 'TRUE')
+    ) INTO v_exists USING p_id;
+    RETURN v_exists;
+  END IF;
+
+  -- Single mode: walk the parent-FK chain up to the root collection, the same
+  -- traversal _delta_load_collection makes on the way down.
+  v_root_id  := (v_scope->'values'->>'id')::BIGINT;
+  v_cur_coll := p_collection_key;
+  v_cur_id   := p_id;
+
+  LOOP
+    v_depth := v_depth + 1;
+    IF v_depth > 32 THEN RETURN FALSE; END IF;   -- malformed / cyclic parent chain
+
+    IF v_cur_coll = p_def.root_collection THEN
+      IF v_cur_id IS DISTINCT FROM v_root_id THEN RETURN FALSE; END IF;
+      -- ... and the root meets the rest of its name's scope -- a column beside
+      -- its id, as fo-guest:<id>:<email> names one -- as delta_open reads it
+      -- (0.10.0 review). A scope of the id alone asks nothing more.
+      IF NOT EXISTS (SELECT 1 FROM jsonb_object_keys(COALESCE(p_def.scope, '{}'::jsonb)) k WHERE k <> 'id') THEN
+        RETURN TRUE;
+      END IF;
+      SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = v_cur_coll;
+      IF NOT FOUND THEN RETURN FALSE; END IF;
+      EXECUTE format('SELECT EXISTS(SELECT 1 FROM %I t WHERE t.id = $1 AND %s)',
+        _delta_source_view(v_coll.table_name, v_coll.temporal), COALESCE(v_scope->>'where', 'TRUE'))
+        INTO v_exists USING v_root_id;
+      RETURN v_exists;
+    END IF;
+
+    SELECT * INTO v_coll FROM _delta_collections
+     WHERE collection_key = v_cur_coll;
+    IF NOT FOUND THEN RETURN FALSE; END IF;
+
+    -- Unparented collection: included, _delta_load_collection loads it whole,
+    -- so it is shared by every doc of this type and every row of it is in
+    -- scope. Met on the way up from a row, or not included (the parent of a
+    -- row being added), it ends a chain that never reaches the root: nothing
+    -- under it is in the document (todo #32).
+    IF v_coll.parent_collection IS NULL THEN
+      RETURN v_depth = 1 AND v_cur_coll = ANY(COALESCE(p_def.include, ARRAY[]::text[]));
+    END IF;
+
+    v_view := _delta_source_view(v_coll.table_name, v_coll.temporal);
+    EXECUTE format('SELECT t.%I FROM %I t WHERE t.id = $1', v_coll.parent_fk, v_view)
+      INTO v_cur_id USING v_cur_id;
+    IF v_cur_id IS NULL THEN RETURN FALSE; END IF;   -- absent, or invisible to us
+
+    v_cur_coll := v_coll.parent_collection;
+  END LOOP;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- ---------------------------------------------------------------------------
+-- Who holds a row: the fan-out (todo #28)
+--
+-- A write is told to every document that holds a row it changed -- the one
+-- written through, and every other opened document over the same rows -- as
+-- the SQLite backend tells its open documents. These answer, from a row's
+-- values (as it was before the write, or as it is after), which documents
+-- hold it; delta_apply tells each what changed for it.
+-- ---------------------------------------------------------------------------
+
+-- _delta_chain_root: the id of the `p_root` row that `p_row` (of `p_coll`)
+-- hangs from, following parent keys up through the tables as they stand;
+-- NULL when the chain does not reach p_root (an unparented collection on the
+-- way, or a row not there).
+CREATE OR REPLACE FUNCTION _delta_chain_root(p_coll TEXT, p_row JSONB, p_root TEXT)
+RETURNS BIGINT AS $$
+DECLARE
+  v_coll  RECORD;
+  v_cur   TEXT;
+  v_id    BIGINT;
+  v_view  TEXT;
+  v_depth INT := 0;
+BEGIN
+  IF p_row IS NULL THEN RETURN NULL; END IF;
+  IF p_coll = p_root THEN RETURN (p_row->>'id')::BIGINT; END IF;
+  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_coll;
+  IF NOT FOUND OR v_coll.parent_collection IS NULL THEN RETURN NULL; END IF;
+  v_id  := (p_row->>v_coll.parent_fk)::BIGINT;
+  v_cur := v_coll.parent_collection;
+  LOOP
+    v_depth := v_depth + 1;
+    IF v_depth > 32 OR v_id IS NULL THEN RETURN NULL; END IF;   -- malformed chain, or a row not there
+    IF v_cur = p_root THEN RETURN v_id; END IF;
+    SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = v_cur;
+    IF NOT FOUND OR v_coll.parent_collection IS NULL THEN RETURN NULL; END IF;
+    v_view := _delta_source_view(v_coll.table_name, v_coll.temporal);
+    EXECUTE format('SELECT t.%I FROM %I t WHERE t.id = $1', v_coll.parent_fk, v_view)
+      INTO v_id USING v_id;
+    v_cur := v_coll.parent_collection;
+  END LOOP;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- _delta_doc_holds: does the document `p_doc_name` (of `p_def`) hold `p_row`
+-- of `p_coll`? Judged on the row's values, so a row as it was before a write
+-- is judged as well as one as it is after -- the same rule delta_open reads by.
+CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+RETURNS BOOLEAN AS $$
+DECLARE
+  v_scope JSONB;
+  v_coll  RECORD;
+  v_ok    BOOLEAN;
+BEGIN
+  IF p_row IS NULL THEN RETURN FALSE; END IF;
+  IF p_coll IS DISTINCT FROM p_def.root_collection
+     AND NOT (p_coll = ANY(COALESCE(p_def.include, ARRAY[]::text[]))) THEN
+    RETURN FALSE;
+  END IF;
+  -- a name its root's columns cannot take (one opened before a rule refused it) holds nothing
+  v_scope := _delta_resolve_scope(p_def, p_doc_name, FALSE);
+  IF v_scope ? 'refused' THEN RETURN FALSE; END IF;
+  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_coll;
+  IF NOT FOUND THEN RETURN FALSE; END IF;
+  -- Named with a time past, it holds a temporal row as it stood then, which no
+  -- write now changes (a table that keeps no history it reads as it is).
+  IF v_coll.temporal AND (v_scope->>'at')::TIMESTAMPTZ <= now() THEN RETURN FALSE; END IF;
+
+  -- The root: the one row a single-mode document is named for, or the rows a
+  -- list-mode document's condition reads -- tested on the row's own values.
+  IF p_coll = p_def.root_collection THEN
+    IF (v_scope->>'mode') = 'single'
+       AND (p_row->>'id')::BIGINT IS DISTINCT FROM (v_scope->'values'->>'id')::BIGINT THEN
+      RETURN FALSE;
+    END IF;
+    EXECUTE format(
+      'SELECT EXISTS (SELECT 1 FROM jsonb_populate_record(null::%I, $1) t WHERE %s)',
+      v_coll.table_name, COALESCE(v_scope->>'where', 'TRUE')
+    ) INTO v_ok USING p_row;
+    RETURN v_ok;
+  END IF;
+
+  -- An included collection: a list-mode document, or an unparented
+  -- collection, holds every row of it (loaded in full); else the row hangs
+  -- from this document's root.
+  IF (v_scope->>'mode') = 'list' OR v_coll.parent_collection IS NULL THEN RETURN TRUE; END IF;
+  RETURN _delta_chain_root(p_coll, p_row, p_def.root_collection)
+         IS NOT DISTINCT FROM (v_scope->'values'->>'id')::BIGINT;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- _delta_holders: the documents that hold `p_row` of `p_coll` -- every one
+-- open now (a name in _delta_held, todo #73), and the writer's own `p_writer`.
+-- A single-mode document of an unscoped definition is found by its name,
+-- prefix || the root the row hangs from; a scoped or list-mode one, or one
+-- holding an unparented collection, by the open names of its prefix. So a
+-- write costs what is open, not what was ever opened.
+--
+-- Before it asks, it takes its prefix's lock, shared, until the write commits:
+-- an open of that prefix holds its name and waits for it (_delta_hold), so a
+-- name held from now is seen here, and a write that asked before is read by
+-- the open. VOLATILE, so the question is asked after the lock -- and so a
+-- write runs at READ COMMITTED: a transaction that reads from one snapshot
+-- (REPEATABLE READ, SERIALIZABLE) would not see a name held after it began,
+-- and is refused (SQLSTATE 0A000).
+--
+-- SECURITY DEFINER (todo #33), with pg_temp last on its path: who holds a row
+-- is worked out as the functions' owner, not the writer, so a parent row the writer's RLS hides (another's
+-- list, under another's board) does not hide the document that holds it. It
+-- answers document names, never a row; each document is told only what it
+-- holds (a caller may ask it of a row it makes up, and learn which open
+-- documents would hold it). It sees past RLS where its owner does: the role
+-- that applied the framework, owning the tables without FORCE ROW LEVEL
+-- SECURITY, or with BYPASSRLS; applied as the app's own role, it sees what
+-- the writer sees, as before.
+CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+RETURNS TEXT[] AS $$
+DECLARE
+  v_def   _delta_docs;
+  v_coll  RECORD;
+  v_names TEXT[] := ARRAY[]::text[];
+  v_rid   BIGINT;
+  v_all   BOOLEAN;
+  v_cand  TEXT;
+BEGIN
+  IF current_setting('transaction_isolation') <> 'read committed' THEN
+    RAISE EXCEPTION 'a delta write runs at READ COMMITTED, not %: a document opened while it ran would not be told of it',
+      upper(current_setting('transaction_isolation')) USING ERRCODE = '0A000';
+  END IF;
+  IF p_row IS NULL THEN RETURN v_names; END IF;
+  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_coll;
+  IF NOT FOUND THEN RETURN v_names; END IF;
+
+  FOR v_def IN
+    SELECT * FROM _delta_docs
+     WHERE root_collection = p_coll OR p_coll = ANY(include)
+  LOOP
+    v_all := v_def.scope <> '{}'::jsonb
+             OR (p_coll IS DISTINCT FROM v_def.root_collection AND v_coll.parent_collection IS NULL);
+    v_rid := CASE WHEN v_all THEN NULL ELSE _delta_chain_root(p_coll, p_row, v_def.root_collection) END;
+    PERFORM pg_advisory_xact_lock_shared(hashtext('_delta_hold'), hashtext(v_def.prefix));
+    FOR v_cand IN
+      SELECT doc_name FROM _delta_held
+       WHERE (v_all AND starts_with(doc_name, v_def.prefix))
+          OR (NOT v_all AND doc_name IN (v_def.prefix, v_def.prefix || v_rid::text))
+      UNION
+      SELECT p_writer WHERE p_writer IS NOT NULL AND starts_with(p_writer, v_def.prefix)
+    LOOP
+      IF NOT (v_cand = ANY(v_names))
+         AND (_delta_find_doc(v_cand)).prefix = v_def.prefix     -- the longest prefix owns the name
+         AND _delta_doc_holds(v_def, v_cand, p_coll, p_row) THEN
+        v_names := v_names || v_cand;
+      END IF;
+    END LOOP;
+  END LOOP;
+  RETURN v_names;
+END;
+$$ LANGUAGE plpgsql VOLATILE SECURITY DEFINER;
+-- the search path it was applied with, and pg_temp last: a caller's temporary
+-- tables never stand in for delta's own (pg_temp is searched first unless named)
+DO $$ BEGIN
+  EXECUTE format('ALTER FUNCTION _delta_holders(TEXT, JSONB, TEXT) SET search_path = %s, pg_temp', COALESCE(NULLIF(current_setting('search_path'), ''), 'public'));
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- _delta_strip_temporal: remove valid_from/valid_to/override from a JSONB row
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_strip_temporal(p_row JSONB)
+RETURNS JSONB AS $$ SELECT p_row - 'valid_from' - 'valid_to' - 'override'; $$ LANGUAGE sql IMMUTABLE;
+
+-- ---------------------------------------------------------------------------
+-- The schema is the contract (reference/migrations.md): a process writes by
+-- the columns its own schema declares. _delta_cols: a collection's columns as
+-- the process writing declares them -- `delta.declared`, set for the call by its
+-- listener (`{ <collection>: <columns_def> }`, createDocListener's `schema`) --
+-- else as the database last declared them (_delta_collections, generateSql).
+-- Two versions on one database each validate, default and replace by their
+-- own, whichever started last. _delta_stored_columns: every column the table
+-- has, by name -- a walk puts a row back as the ledger stored it, a column this
+-- process does not declare too.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_cols(p_collection_key TEXT, p_columns_def JSONB)
+RETURNS JSONB AS $$
+  SELECT COALESCE(NULLIF(current_setting('delta.declared', true), '')::jsonb -> p_collection_key, p_columns_def);
+$$ LANGUAGE sql STABLE;
+
+CREATE OR REPLACE FUNCTION _delta_stored_columns(p_table TEXT)
+RETURNS TEXT[] AS $$
+  SELECT COALESCE(array_agg(attname::text ORDER BY attnum), '{}')
+    FROM pg_attribute
+   WHERE attrelid = to_regclass(quote_ident(p_table)) AND attnum > 0 AND NOT attisdropped;
+$$ LANGUAGE sql STABLE;
+
+-- _delta_insert_sql: the INSERT of a new row that names only the columns the
+-- row gives (its id, parent key, declared columns and validity; a row put back
+-- by a walk, every column it was stored with), so a column it does not give --
+-- one a migration added NOT NULL with a default -- takes its database default,
+-- as SQLite's insertRow gives it. Run with the row as $1; RETURNING may follow.
+CREATE OR REPLACE FUNCTION _delta_insert_sql(p_table TEXT, p_row JSONB)
+RETURNS TEXT AS $$
+  SELECT format('INSERT INTO %1$I AS t (%2$s) SELECT %2$s FROM jsonb_populate_record(null::%1$I, $1)', p_table,
+    (SELECT string_agg(format('%I', k), ', ') FROM jsonb_object_keys(p_row) AS k));
+$$ LANGUAGE sql STABLE;