dzql 0.6.37 → 0.8.0

package/src/sql/001g-delta-ledger.sql

@@ -0,0 +1,564 @@
+-- =========================================================================
+-- Delta-doc: the ledger
+-- =========================================================================
+-- Every write, with its inverse, written in the write's own transaction, by the
+-- database every process shares: so undo works across processes. The same
+-- entry as the SQLite backend's (src/server/ledger.ts):
+--
+--   who     the identity that made the change, for the audit
+--   cursor  the key undo walks, opaque here (eta passes its session)
+--   undoes  the entry this one walked back (undo) or forward again (redo)
+--
+-- `_delta_ops_log` is a catch-up buffer, pruned within the hour; this is the
+-- history, kept.
+-- =========================================================================
+
+CREATE TABLE IF NOT EXISTS _delta_ledger (
+  id        BIGSERIAL PRIMARY KEY,
+  doc_name  TEXT NOT NULL,
+  version   BIGINT NOT NULL,
+  ops       JSONB NOT NULL,
+  inverse   JSONB NOT NULL,
+  who       TEXT,
+  cursor    TEXT,
+  at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  undoes    BIGINT REFERENCES _delta_ledger (id),
+  undoable  BOOLEAN NOT NULL DEFAULT TRUE
+);
+
+CREATE INDEX IF NOT EXISTS idx_delta_ledger_doc ON _delta_ledger (doc_name, version);
+CREATE INDEX IF NOT EXISTS idx_delta_ledger_cursor ON _delta_ledger (cursor);
+CREATE INDEX IF NOT EXISTS idx_delta_ledger_undoes ON _delta_ledger (undoes);
+
+-- ---------------------------------------------------------------------------
+-- _delta_row_at: the row a document holds at a row's path, split -- the twin
+-- of rowAt in src/server/ledger.ts: /<coll>/<id> in a map, /<coll> its root,
+-- and, in a single document, /<root>/<id>, the root named by its id, as a
+-- write that adds or removes the root tells it. NULL when it holds none.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_row_at(p_doc JSONB, p_parts TEXT[])
+RETURNS JSONB LANGUAGE sql IMMUTABLE AS $$
+  SELECT CASE
+    WHEN array_length(p_parts, 1) = 1 THEN p_doc->p_parts[1]
+    WHEN COALESCE(p_doc->p_parts[1]->p_parts[2], 'null'::jsonb) <> 'null'::jsonb THEN p_doc->p_parts[1]->p_parts[2]
+    WHEN jsonb_typeof(p_doc->p_parts[1]->'id') IN ('number', 'string')
+         AND p_doc->p_parts[1]->>'id' = p_parts[2] THEN p_doc->p_parts[1]
+  END;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- _delta_inverse: what applied ops walked back, read from the document as it
+-- was. Applied ops are whole rows (/coll/id) or the root (/coll; added or
+-- removed, /coll/id, read where the document holds it: _delta_row_at): an add is
+-- removed, a remove added back, a replace replaced by its old self. Reverse
+-- order, except that a remove and the rows its removal cascaded to (a run) come
+-- back in their own order, parent first -- the rule of inverseOf in
+-- src/server/sqlite.ts. p_asked, the ops as the caller sent them, says where
+-- each run starts: at a remove the caller asked for. An undo's removes come
+-- children first, each asked for, so each is its own run, and the runs come back
+-- in reverse: parent first again. Without it (the two-argument form), removes
+-- one after another are taken for one run, right only for a single remove and
+-- its cascade. A single document's root written and then removed by the write
+-- is one row at two paths (/root, /root/id): the add that takes back its
+-- removal puts it back as it was before the write, so its replaces before the
+-- removal have no inverse of their own -- a walk would find /root gone. A row
+-- the write makes and takes out again never was outside it: its make, and what
+-- it had since, walk back nothing, and its removal adds nothing back --
+-- [add, remove] inverts to [], [add, remove, add] to [remove] (todo #67).
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_inverse(p_before JSONB, p_ops JSONB, p_asked JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  v_inverse JSONB := '[]'::jsonb;
+  v_run     JSONB := '[]'::jsonb;
+  v_heads   TEXT[] := '{}';   -- the removes asked for, at the path the write tells each (/t/007 at /t/7)
+  v_op      JSONB;
+  v_i       BIGINT;
+  v_removed JSONB;    -- each path the write removes, at its last remove: one pass, however long the write
+  v_parts   TEXT[];
+  v_prior   JSONB;
+  v_made    JSONB := '{}'::jsonb;   -- each row the write made, by path: the op that made it (each inverse op carries its own, _i)
+BEGIN
+  FOR v_op IN SELECT * FROM jsonb_array_elements(COALESCE(p_asked, '[]'::jsonb)) LOOP
+    CONTINUE WHEN v_op->>'op' IS DISTINCT FROM 'remove';
+    v_parts := _delta_split_path(v_op->>'path');
+    v_heads := v_heads || CASE WHEN array_length(v_parts, 1) = 2
+      THEN _delta_build_path(v_parts[1], _delta_row_id(v_parts[1], v_parts[2])::text)
+      ELSE v_op->>'path' END;
+  END LOOP;
+
+  SELECT COALESCE(jsonb_object_agg(path, last), '{}'::jsonb) INTO v_removed FROM (
+    SELECT o->>'path' AS path, max(i) AS last
+      FROM jsonb_array_elements(COALESCE(p_ops, '[]'::jsonb)) WITH ORDINALITY AS r(o, i)
+     WHERE o->>'op' = 'remove' GROUP BY 1) removes;
+
+  FOR v_op, v_i IN SELECT o, i FROM jsonb_array_elements(COALESCE(p_ops, '[]'::jsonb)) WITH ORDINALITY AS t(o, i) LOOP
+    v_parts := _delta_split_path(v_op->>'path');
+    CONTINUE WHEN v_op->>'op' = 'replace' AND array_length(v_parts, 1) = 1 AND p_before->v_parts[1]->>'id' IS NOT NULL
+      AND (v_removed->>_delta_build_path(v_parts[1], p_before->v_parts[1]->>'id'))::bigint > v_i;
+    IF v_op->>'op' = 'remove' AND v_made ? (v_op->>'path') THEN
+      SELECT COALESCE(jsonb_agg(e ORDER BY n), '[]'::jsonb) INTO v_inverse
+        FROM jsonb_array_elements(v_inverse) WITH ORDINALITY AS x(e, n)
+       WHERE NOT COALESCE(e->>'path' = v_op->>'path' AND (e->>'_i')::bigint >= (v_made->>(v_op->>'path'))::bigint, false);
+      v_made := v_made - (v_op->>'path');
+      CONTINUE;
+    END IF;
+    v_prior := _delta_row_at(p_before, v_parts);
+    IF v_prior IS NOT NULL AND jsonb_typeof(v_prior) = 'object' THEN
+      v_prior := _delta_strip_temporal(v_prior);
+    END IF;
+
+    IF v_op->>'op' = 'remove' THEN
+      IF (v_op->>'path') = ANY(v_heads) THEN   -- a remove asked for starts its own run; one it cascaded to joins it
+        v_inverse := v_run || v_inverse;
+        v_run := '[]'::jsonb;
+      END IF;
+      v_run := v_run || jsonb_build_array(jsonb_build_object('op', 'add', 'path', v_op->>'path', 'value', v_prior));
+    ELSE
+      v_inverse := v_run || v_inverse;
+      v_run := '[]'::jsonb;
+      IF v_op->>'op' = 'add' THEN
+        v_inverse := jsonb_build_array(jsonb_build_object('op', 'remove', 'path', v_op->>'path', '_i', v_i)) || v_inverse;
+        v_made := v_made || jsonb_build_object(v_op->>'path', v_i);
+      ELSE
+        v_inverse := jsonb_build_array(jsonb_build_object('op', 'replace', 'path', v_op->>'path', 'value', v_prior, '_i', v_i)) || v_inverse;
+      END IF;
+    END IF;
+  END LOOP;
+  SELECT COALESCE(jsonb_agg(e - '_i' ORDER BY n), '[]'::jsonb) INTO v_inverse
+    FROM jsonb_array_elements(v_run || v_inverse) WITH ORDINALITY AS x(e, n);
+  RETURN v_inverse;
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;
+
+CREATE OR REPLACE FUNCTION _delta_inverse(p_before JSONB, p_ops JSONB)
+RETURNS JSONB LANGUAGE sql IMMUTABLE AS $$ SELECT _delta_inverse(p_before, p_ops, NULL); $$;
+
+-- ---------------------------------------------------------------------------
+-- _delta_beside: a document with rows outside it beside it -- rows, each
+-- {coll, id, row}, of collections it neither roots nor includes -- for the
+-- ledger: what a removal's cascade takes beyond the document (the schema's
+-- cascade, not the include's), which its inverse puts back and a walk of it is
+-- guarded by. `besides` in sqlite.ts.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_beside(p_doc JSONB, p_def _delta_docs, p_rows JSONB)
+RETURNS JSONB LANGUAGE sql STABLE AS $$
+  SELECT p_doc || COALESCE(jsonb_object_agg(coll, COALESCE(p_doc->coll, '{}'::jsonb) || rows), '{}'::jsonb)
+    FROM (SELECT r->>'coll' AS coll, jsonb_object_agg(r->>'id', r->'row') AS rows
+            FROM jsonb_array_elements(COALESCE(p_rows, '[]'::jsonb)) AS r
+           WHERE r->>'coll' IS DISTINCT FROM p_def.root_collection
+             AND NOT (r->>'coll' = ANY(COALESCE(p_def.include, ARRAY[]::text[])))
+             AND jsonb_typeof(r->'row') = 'object'
+           GROUP BY 1) AS beyond;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- delta_apply_logged: delta_apply, with its ledger entry, in one transaction.
+-- A lock per document keeps another writer of it from landing between the read
+-- the inverse is taken from and the write. Returns delta_apply's {version, ops}
+-- with the inverse and the entry's id.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION delta_apply_logged(
+  p_doc_name TEXT,
+  p_ops      JSONB,
+  p_who      TEXT,
+  p_cursor   TEXT,
+  p_undoable BOOLEAN DEFAULT TRUE,
+  p_undoes   BIGINT DEFAULT NULL
+) RETURNS JSONB AS $$
+DECLARE
+  v_before  JSONB;
+  v_result  JSONB;
+  v_inverse JSONB;
+  v_entry   BIGINT;
+BEGIN
+  PERFORM pg_advisory_xact_lock(hashtext('delta:' || p_doc_name));
+  v_before  := COALESCE(_delta_open(p_doc_name, TRUE), '{}'::jsonb);   -- whole: the inverse puts back every column
+  -- the rows each removal's cascade will take beyond the document, as they are: its inverse puts them back
+  v_before  := _delta_beside(v_before, _delta_find_doc(p_doc_name), (
+    SELECT jsonb_agg(r) FROM jsonb_array_elements(p_ops) AS o,
+           LATERAL _delta_split_path(o->>'path') AS p,
+           LATERAL jsonb_array_elements(_delta_cascade_rows(p[1], p[2]::bigint)) AS r
+     WHERE o->>'op' = 'remove' AND array_length(p, 1) = 2
+       AND p[2] ~ '^[0-9]+$' AND p[2]::numeric <= 9007199254740991));
+  v_result  := delta_apply(p_doc_name, p_ops, p_undoes IS NOT NULL);   -- an entry that walks another is a walk
+  v_inverse := _delta_inverse(v_before, v_result->'ops', p_ops);
+  IF jsonb_array_length(v_result->'ops') > 0 THEN
+    INSERT INTO _delta_ledger (doc_name, version, ops, inverse, who, cursor, undoes, undoable)
+      VALUES (p_doc_name, (v_result->>'version')::BIGINT, v_result->'ops', v_inverse, p_who, p_cursor, p_undoes, p_undoable)
+      RETURNING id INTO v_entry;
+  END IF;
+  RETURN v_result || jsonb_build_object('inverse', v_inverse, 'entry', v_entry);
+END;
+$$ LANGUAGE plpgsql;
+
+-- ---------------------------------------------------------------------------
+-- The cursor: undo and redo walk one cursor's entries. An entry's `undoes`
+-- links it to the entry it walked, so entries form chains; depth along a chain
+-- says which way an entry went (even: forward, odd: back), and the tip -- the
+-- entry nothing has walked yet -- is the one that counts. A fresh write ends
+-- what could be redone; an entry not undoable (a fact) starts no chain.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_ledger_tip(p_cursor TEXT, p_back BOOLEAN)
+RETURNS _delta_ledger AS $$
+  WITH RECURSIVE chain(id, depth) AS (
+    SELECT id, 0 FROM _delta_ledger WHERE cursor = p_cursor AND undoes IS NULL AND undoable
+    UNION ALL
+    SELECT l.id, c.depth + 1 FROM _delta_ledger l JOIN chain c ON l.undoes = c.id
+  ),
+  tips AS (
+    SELECT c.id, c.depth FROM chain c
+    WHERE NOT EXISTS (SELECT 1 FROM _delta_ledger w WHERE w.undoes = c.id)
+  )
+  SELECT l.* FROM _delta_ledger l JOIN tips t ON t.id = l.id
+  WHERE CASE WHEN p_back THEN t.depth % 2 = 0
+        ELSE t.depth % 2 = 1 AND l.undoable   -- a walk recorded as changing nothing is never redone
+          AND l.id > COALESCE((SELECT MAX(id) FROM _delta_ledger WHERE cursor = p_cursor AND undoes IS NULL AND undoable), 0)
+        END
+  ORDER BY l.id DESC
+  LIMIT 1;
+$$ LANGUAGE sql STABLE;
+
+-- JSON values the same, with JSON null and a missing value the same.
+CREATE OR REPLACE FUNCTION _delta_same(a JSONB, b JSONB)
+RETURNS BOOLEAN LANGUAGE sql IMMUTABLE AS $$
+  SELECT COALESCE(a, 'null'::jsonb) = COALESCE(b, 'null'::jsonb);
+$$;
+
+-- A field of a collection's row the same in two values: a timestamptz by the
+-- instant it names, whatever zone its text was written in (a ledger's entry
+-- keeps the session's TimeZone of its write), anything else as _delta_same.
+CREATE OR REPLACE FUNCTION _delta_same(p_coll TEXT, p_field TEXT, a JSONB, b JSONB)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$
+  SELECT CASE
+    WHEN jsonb_typeof(a) = 'string' AND jsonb_typeof(b) = 'string'
+         AND (SELECT _delta_cols(collection_key, columns_def)->p_field->>'type' FROM _delta_collections WHERE collection_key = p_coll) = 'timestamptz'
+      THEN (a #>> '{}')::timestamptz = (b #>> '{}')::timestamptz
+    ELSE _delta_same(a, b)
+  END;
+$$;
+
+-- _delta_walk_key: a row's key in a walk -- the keyOf of planWalk in
+-- src/server/ledger.ts. A single document's root is one row at two paths,
+-- /root (a replace of it) and /root/id (its add, its remove): both are keyed
+-- by the second, the id read from the row, or else from the document, so the
+-- root is walked once whichever way the entry spelled it. Every other path is
+-- its own key.
+CREATE OR REPLACE FUNCTION _delta_walk_key(p_path TEXT, p_value JSONB, p_doc JSONB)
+RETURNS TEXT LANGUAGE plpgsql IMMUTABLE AS $$
+DECLARE
+  v_parts TEXT[] := _delta_split_path(p_path);
+  v_own   JSONB;
+BEGIN
+  IF array_length(v_parts, 1) <> 1 THEN RETURN p_path; END IF;
+  v_own := CASE WHEN jsonb_typeof(p_value) = 'object' THEN p_value->'id' END;
+  IF jsonb_typeof(v_own) IS DISTINCT FROM 'number' AND jsonb_typeof(v_own) IS DISTINCT FROM 'string' THEN
+    v_own := p_doc->v_parts[1]->'id';
+  END IF;
+  IF jsonb_typeof(v_own) IN ('number', 'string') THEN RETURN _delta_build_path(v_parts[1], v_own #>> '{}'); END IF;
+  RETURN p_path;
+END;
+$$;
+
+-- _delta_walk_plan: what walking an entry does to the document as it is now
+-- -- the rule of planWalk in src/server/ledger.ts. Only the fields the entry
+-- changed are set back, each guarded by what the entry left there: a row it
+-- changed gets back those fields if each still holds what it wrote; a row it
+-- made is removed if it is as it was left, and every row its removal would take
+-- with it (_delta_cascade_rows, in the document's include) the entry made too;
+-- a row it removed comes back if nobody has put one there. Each row is walked once, from what it was before
+-- the entry (every inverse op of a path carries it: an add or replace its
+-- value, a remove none) to what the entry left, so a row the entry touched
+-- twice is walked by its net change. A guard that fails is a conflict, by
+-- path, and then nothing is walked. A row a removal planned before it takes
+-- with it is left to that removal. Returns { ops } or { ops: [], conflict: [paths] }.
+CREATE OR REPLACE FUNCTION _delta_walk_plan(p_entry _delta_ledger)
+RETURNS JSONB AS $$
+DECLARE
+  v_doc      JSONB := _delta_open_held(p_entry.doc_name);   -- an implied document's absent root: null
+  v_left     JSONB := '{}'::jsonb;   -- row key -> what the entry left there (JSON null: it removed it)
+  v_before   JSONB := '{}'::jsonb;   -- row key -> what it held before the entry (JSON null: nothing)
+  v_shown    JSONB := '{}'::jsonb;   -- row key -> its path as the inverse first says it: where a conflict is reported
+  v_paths    TEXT[] := '{}';         -- the row keys, in the order the inverse first names them
+  v_op       JSONB;
+  v_path     TEXT;
+  v_key      TEXT;
+  v_at       TEXT;
+  v_parts    TEXT[];
+  v_here     JSONB;
+  v_wrote    JSONB;
+  v_was      JSONB;
+  v_fields   TEXT[];
+  v_ops      JSONB := '[]'::jsonb;
+  v_conflict JSONB := '[]'::jsonb;
+  v_def      _delta_docs := _delta_find_doc(p_entry.doc_name);
+  v_others   BOOLEAN;
+  v_coll     RECORD;
+  v_row      JSONB;
+  v_beyond   JSONB := '[]'::jsonb;
+BEGIN
+  -- a row outside the document that the entry's cascade took is guarded by the tables, as they hold it now
+  FOR v_parts IN SELECT DISTINCT _delta_split_path(o->>'path') FROM jsonb_array_elements(p_entry.ops || p_entry.inverse) AS o LOOP
+    CONTINUE WHEN array_length(v_parts, 1) <> 2 OR v_parts[2] !~ '^[0-9]+$' OR v_parts[2]::numeric > 9007199254740991
+      OR v_parts[1] = v_def.root_collection OR v_parts[1] = ANY(COALESCE(v_def.include, ARRAY[]::text[]));
+    SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = v_parts[1];
+    CONTINUE WHEN NOT FOUND;
+    EXECUTE format('SELECT _delta_strip_temporal(to_jsonb(t.*)) FROM %I t WHERE t.id = $1', _delta_source_view(v_coll.table_name, v_coll.temporal))
+      INTO v_row USING v_parts[2]::bigint;
+    v_beyond := v_beyond || jsonb_build_array(jsonb_build_object('coll', v_parts[1], 'id', v_parts[2]::bigint, 'row', v_row));
+  END LOOP;
+  v_doc := _delta_beside(v_doc, v_def, v_beyond);
+
+  FOR v_op IN SELECT * FROM jsonb_array_elements(p_entry.ops) LOOP
+    v_left := v_left || jsonb_build_object(_delta_walk_key(v_op->>'path', v_op->'value', v_doc),
+      CASE WHEN v_op->>'op' = 'remove' THEN 'null'::jsonb ELSE v_op->'value' END);
+  END LOOP;
+  FOR v_op IN SELECT * FROM jsonb_array_elements(p_entry.inverse) LOOP
+    v_key := _delta_walk_key(v_op->>'path', CASE WHEN v_op->>'op' <> 'remove' THEN v_op->'value' END, v_doc);
+    IF NOT v_before ? v_key THEN
+      v_paths := v_paths || v_key;
+      v_before := v_before || jsonb_build_object(v_key, 'null'::jsonb);
+      v_shown := v_shown || jsonb_build_object(v_key, v_op->>'path');
+    END IF;
+    IF v_op->>'op' <> 'remove' AND COALESCE(v_op->'value', 'null'::jsonb) <> 'null'::jsonb THEN
+      v_before := v_before || jsonb_build_object(v_key, v_op->'value');
+    END IF;
+  END LOOP;
+  FOREACH v_path IN ARRAY v_paths LOOP
+    v_at := v_shown->>v_path;
+    v_parts := _delta_split_path(v_path);
+    v_here := _delta_row_at(v_doc, v_parts);
+    IF v_here = 'null'::jsonb THEN v_here := NULL; END IF;
+    v_wrote := NULLIF(v_left->v_path, 'null'::jsonb);
+    v_was := NULLIF(v_before->v_path, 'null'::jsonb);
+    CONTINUE WHEN v_was IS NULL AND v_wrote IS NULL;   -- made and removed by the entry
+    IF v_was IS NULL THEN                               -- it made the row
+      -- a row under it that the entry did not make: what its removal would take with it
+      v_others := array_length(v_parts, 1) = 2 AND EXISTS (
+        SELECT 1 FROM jsonb_array_elements(_delta_cascade_rows(v_parts[1], _delta_row_id(v_parts[1], v_parts[2]))) WITH ORDINALITY AS c(r, i)
+         WHERE i > 1 AND NOT (
+           COALESCE(v_before->_delta_build_path(r->>'coll', r->>'id'), 'null'::jsonb) = 'null'::jsonb
+           AND COALESCE(v_left->_delta_build_path(r->>'coll', r->>'id'), 'null'::jsonb) <> 'null'::jsonb));
+      IF v_here IS NULL OR v_others OR EXISTS (
+        SELECT 1 FROM jsonb_each(v_wrote) w
+         WHERE w.key NOT IN ('valid_from', 'valid_to') AND NOT _delta_same(v_parts[1], w.key, v_here->w.key, w.value)
+      ) THEN v_conflict := v_conflict || to_jsonb(v_at);
+      ELSE v_ops := v_ops || jsonb_build_array(jsonb_build_object('op', 'remove', 'path', v_path)); END IF;
+    ELSIF v_wrote IS NULL THEN                          -- it removed the row
+      IF v_here IS NOT NULL THEN v_conflict := v_conflict || to_jsonb(v_at);
+      ELSE v_ops := v_ops || jsonb_build_array(jsonb_build_object('op', 'add', 'path', v_path, 'value', v_was)); END IF;
+    ELSE                                                -- it changed the row's fields
+      SELECT array_agg(k ORDER BY k) INTO v_fields FROM (
+        SELECT jsonb_object_keys(v_was) AS k
+        UNION SELECT jsonb_object_keys(v_wrote)
+      ) keys
+      WHERE k NOT IN ('valid_from', 'valid_to') AND NOT _delta_same(v_was->k, v_wrote->k);
+      CONTINUE WHEN v_fields IS NULL;
+      IF v_here IS NULL OR EXISTS (SELECT 1 FROM unnest(v_fields) f WHERE NOT _delta_same(v_parts[1], f, v_here->f, v_wrote->f)) THEN
+        v_conflict := v_conflict || to_jsonb(v_at);
+      ELSE
+        -- each field set back, one replace each (a replace of the row is the row whole, todo #3);
+        -- the document's root at /root/<field>, however the entry spelled it
+        v_ops := v_ops || (SELECT jsonb_agg(jsonb_build_object('op', 'replace',
+          'path', CASE WHEN v_here = v_doc->v_parts[1] THEN _delta_build_path(v_parts[1]) ELSE v_path END || _delta_build_path(f),
+          'value', COALESCE(v_was->f, 'null'::jsonb)) ORDER BY f COLLATE "C") FROM unnest(v_fields) f);
+      END IF;
+    END IF;
+  END LOOP;
+  IF jsonb_array_length(v_conflict) > 0 THEN
+    RETURN jsonb_build_object('ops', '[]'::jsonb, 'conflict', v_conflict);
+  END IF;
+  -- a row the removal of one before it takes with it is taken by that removal: removed again after it, it would not be there
+  SELECT COALESCE(jsonb_agg(o ORDER BY n), '[]'::jsonb) INTO v_ops
+    FROM jsonb_array_elements(v_ops) WITH ORDINALITY AS x(o, n)
+   WHERE NOT (o->>'op' = 'remove' AND EXISTS (
+     SELECT 1 FROM jsonb_array_elements(v_ops) WITH ORDINALITY AS t(e, m),
+            LATERAL _delta_split_path(e->>'path') AS p,
+            LATERAL jsonb_array_elements(_delta_cascade_rows(p[1], _delta_row_id(p[1], p[2]))) WITH ORDINALITY AS c(r, i)
+      WHERE m < n AND e->>'op' = 'remove' AND array_length(p, 1) = 2 AND i > 1
+        AND _delta_build_path(r->>'coll', r->>'id') = o->>'path'));
+  RETURN jsonb_build_object('ops', v_ops);
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- _delta_change_tip: the entry a walk of one change takes -- the rule of
+-- changeTip in src/server/ledger.ts. The change is the chain that holds entry
+-- p_change, named by any entry of it (its write, an undo, a redo); its write
+-- must be the cursor's own and undoable, else SQLSTATE P0002 (404). Its tip, if
+-- it goes the way asked: back when the change stands (an even depth), forward
+-- when it was undone by a walk that changed something (odd); else a NULL row.
+CREATE OR REPLACE FUNCTION _delta_change_tip(p_cursor TEXT, p_change BIGINT, p_back BOOLEAN)
+RETURNS _delta_ledger AS $$
+DECLARE
+  v_tip   _delta_ledger;
+  v_next  _delta_ledger;
+  v_depth INT := 0;
+BEGIN
+  SELECT * INTO v_tip FROM _delta_ledger WHERE id = p_change;
+  WHILE v_tip.undoes IS NOT NULL LOOP   -- up to the change's write
+    SELECT * INTO v_tip FROM _delta_ledger WHERE id = v_tip.undoes;
+  END LOOP;
+  IF v_tip.id IS NULL OR v_tip.cursor IS DISTINCT FROM p_cursor OR NOT v_tip.undoable THEN
+    RAISE EXCEPTION 'Entry % is no change of this cursor''s', p_change USING ERRCODE = 'P0002';
+  END IF;
+  LOOP                                  -- down to the entry nothing has walked
+    SELECT * INTO v_next FROM _delta_ledger WHERE undoes = v_tip.id;
+    EXIT WHEN NOT FOUND;
+    v_tip := v_next;
+    v_depth := v_depth + 1;
+  END LOOP;
+  IF (p_back AND v_depth % 2 = 0) OR (NOT p_back AND v_depth % 2 = 1 AND v_tip.undoable) THEN
+    RETURN v_tip;
+  END IF;
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- delta_walk: the cursor's next entry (p_back: the next to undo, else to
+-- redo), or the next of one change (p_change: any entry of it, the cursor's
+-- own), walked through delta_apply_logged -- by its plan, above -- and
+-- recorded as walking it. NULL when there is none.
+--   p_dry    answer the plan ({ doc, entry, ops, conflict? }) and walk nothing
+--   p_entry  walk only if this is the entry the walk would take (SQLSTATE 40001 → 409)
+-- A conflict, a walk the document refuses, or one that changes nothing is
+-- recorded all the same (no ops, not undoable: never redone), so the cursor
+-- moves on to the entry before it instead of meeting it again for ever. A
+-- named walk has no cursor to move on: it walks nothing and records nothing,
+-- and the change stays to be walked once it can be.
+CREATE OR REPLACE FUNCTION delta_walk(
+  p_cursor TEXT, p_who TEXT, p_back BOOLEAN, p_dry BOOLEAN, p_entry BIGINT, p_change BIGINT
+) RETURNS JSONB AS $$
+DECLARE
+  v_entry   _delta_ledger;
+  v_plan    JSONB;
+  v_version BIGINT;
+  v_skip    BIGINT;
+BEGIN
+  IF p_cursor IS NULL THEN
+    IF p_change IS NOT NULL THEN
+      RAISE EXCEPTION 'Entry % is no change of this cursor''s', p_change USING ERRCODE = 'P0002';
+    END IF;
+    RETURN NULL;
+  END IF;
+  -- one walker per cursor at a time: two undos pressed at once take two entries, not one twice
+  PERFORM pg_advisory_xact_lock(hashtext('delta-cursor:' || p_cursor));
+  IF p_change IS NULL THEN
+    v_entry := _delta_ledger_tip(p_cursor, p_back);
+  ELSE
+    v_entry := _delta_change_tip(p_cursor, p_change, p_back);
+  END IF;
+  IF v_entry.id IS NULL THEN RETURN NULL; END IF;
+  IF p_entry IS NOT NULL AND p_entry <> v_entry.id THEN
+    RAISE EXCEPTION 'The %''s next entry to % is %, not %', CASE WHEN p_change IS NULL THEN 'cursor' ELSE 'change' END,
+      CASE WHEN p_back THEN 'undo' ELSE 'redo' END, v_entry.id, p_entry USING ERRCODE = '40001';
+  END IF;
+  -- the document's lock (delta_apply_logged takes it again): no writer lands between plan and walk
+  PERFORM pg_advisory_xact_lock(hashtext('delta:' || v_entry.doc_name));
+  v_plan := _delta_walk_plan(v_entry);
+  IF p_dry THEN RETURN v_plan || jsonb_build_object('doc', v_entry.doc_name, 'entry', v_entry.id); END IF;
+  IF NOT v_plan ? 'conflict' AND jsonb_array_length(v_plan->'ops') > 0 THEN
+    BEGIN
+      RETURN delta_apply_logged(v_entry.doc_name, v_plan->'ops', p_who, p_cursor, TRUE, v_entry.id)
+        || jsonb_build_object('doc', v_entry.doc_name);
+    EXCEPTION WHEN SQLSTATE '22023' OR SQLSTATE '22P02' OR SQLSTATE '23502' OR SQLSTATE '23505' OR SQLSTATE 'P0002' THEN
+      v_plan := jsonb_build_object('ops', '[]'::jsonb,
+        'conflict', (SELECT jsonb_agg(o->>'path') FROM jsonb_array_elements(v_plan->'ops') o));
+    END;
+  END IF;
+  SELECT COALESCE((SELECT version FROM _delta_versions WHERE doc_name = v_entry.doc_name), 0) INTO v_version;
+  IF p_change IS NULL THEN
+    INSERT INTO _delta_ledger (doc_name, version, ops, inverse, who, cursor, undoes, undoable)
+      VALUES (v_entry.doc_name, v_version, '[]'::jsonb, '[]'::jsonb, p_who, p_cursor, v_entry.id, FALSE)
+      RETURNING id INTO v_skip;
+  END IF;
+  RETURN jsonb_strip_nulls(jsonb_build_object('doc', v_entry.doc_name, 'ops', '[]'::jsonb, 'inverse', '[]'::jsonb, 'version', v_version, 'entry', v_skip))
+    || CASE WHEN v_plan ? 'conflict' THEN jsonb_build_object('conflict', v_plan->'conflict') ELSE '{}'::jsonb END;
+END;
+$$ LANGUAGE plpgsql;
+
+-- The cursor's next entry, as delta_walk was first called: no change named.
+CREATE OR REPLACE FUNCTION delta_walk(
+  p_cursor TEXT, p_who TEXT, p_back BOOLEAN, p_dry BOOLEAN DEFAULT FALSE, p_entry BIGINT DEFAULT NULL
+) RETURNS JSONB AS $$
+BEGIN
+  RETURN delta_walk(p_cursor, p_who, p_back, p_dry, p_entry, NULL::BIGINT);
+END;
+$$ LANGUAGE plpgsql;
+
+-- delta_undo / delta_redo: delta_walk for the cursor's next entry back or forward.
+CREATE OR REPLACE FUNCTION _delta_walk(p_cursor TEXT, p_who TEXT, p_back BOOLEAN)
+RETURNS JSONB AS $$ SELECT delta_walk(p_cursor, p_who, p_back); $$ LANGUAGE sql;
+
+CREATE OR REPLACE FUNCTION delta_undo(p_cursor TEXT, p_who TEXT DEFAULT NULL)
+RETURNS JSONB AS $$ SELECT _delta_walk(p_cursor, p_who, TRUE); $$ LANGUAGE sql;
+
+CREATE OR REPLACE FUNCTION delta_redo(p_cursor TEXT, p_who TEXT DEFAULT NULL)
+RETURNS JSONB AS $$ SELECT _delta_walk(p_cursor, p_who, FALSE); $$ LANGUAGE sql;
+
+-- delta_history: a document's newest entries, each saying whether p_cursor
+-- wrote it -- never who did, never a cursor. Newest first: by version, then
+-- by id (an undo that walked nothing shares the version of the write before
+-- it), as SQLite lists them.
+CREATE OR REPLACE FUNCTION delta_history(p_doc_name TEXT, p_cursor TEXT, p_limit INT DEFAULT 50)
+RETURNS JSONB AS $$
+  SELECT COALESCE(jsonb_agg(e ORDER BY (e->>'version')::BIGINT DESC, (e->>'id')::BIGINT DESC), '[]'::jsonb) FROM (
+    SELECT jsonb_build_object(
+      'id', id, 'doc', doc_name, 'version', version, 'ops', ops, 'inverse', inverse,
+      'at', (EXTRACT(EPOCH FROM at) * 1000)::BIGINT, 'undoable', undoable,
+      'mine', p_cursor IS NOT NULL AND cursor = p_cursor
+    ) AS e
+    FROM _delta_ledger WHERE doc_name = p_doc_name
+    ORDER BY version DESC, id DESC LIMIT p_limit
+  ) entries;
+$$ LANGUAGE sql STABLE;
+
+-- The same, with row-level security: app.user_id set for the transaction, as
+-- delta_apply_as does (001f).
+CREATE OR REPLACE FUNCTION delta_apply_logged_as(
+  p_user_id TEXT, p_doc_name TEXT, p_ops JSONB, p_who TEXT, p_cursor TEXT,
+  p_undoable BOOLEAN DEFAULT TRUE, p_undoes BIGINT DEFAULT NULL
+) RETURNS JSONB LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN delta_apply_logged(p_doc_name, p_ops, p_who, p_cursor, p_undoable, p_undoes);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION delta_undo_as(p_user_id TEXT, p_cursor TEXT, p_who TEXT DEFAULT NULL)
+RETURNS JSONB LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN _delta_walk(p_cursor, p_who, TRUE);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION delta_redo_as(p_user_id TEXT, p_cursor TEXT, p_who TEXT DEFAULT NULL)
+RETURNS JSONB LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN _delta_walk(p_cursor, p_who, FALSE);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION delta_walk_as(
+  p_user_id TEXT, p_cursor TEXT, p_who TEXT, p_back BOOLEAN, p_dry BOOLEAN DEFAULT FALSE, p_entry BIGINT DEFAULT NULL
+) RETURNS JSONB LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN delta_walk(p_cursor, p_who, p_back, p_dry, p_entry);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION delta_walk_as(
+  p_user_id TEXT, p_cursor TEXT, p_who TEXT, p_back BOOLEAN, p_dry BOOLEAN, p_entry BIGINT, p_change BIGINT
+) RETURNS JSONB LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM set_config('app.user_id', p_user_id, true);
+  RETURN delta_walk(p_cursor, p_who, p_back, p_dry, p_entry, p_change);
+END;
+$$;

package/src/sql/auth-jwt.sql

@@ -0,0 +1,62 @@
+-- =========================================================================
+-- auth-jwt — reference users schema + login / register stored functions.
+-- =========================================================================
+--
+-- Apply this alongside the @blueshed/delta/auth-jwt module. Consumers who
+-- want a different identity schema (sessions, OAuth, custom tables) can
+-- substitute their own `login` / `register` functions and pass the SQL
+-- strings via `jwtAuth({ loginSql, registerSql })`.
+--
+-- Uses pgcrypto for bcrypt. Passwords are stored as bcrypt hashes at an
+-- explicit work factor (cost 12 — tune via gen_salt('bf', N)). `login` always
+-- runs one crypt() — even for an unknown email it compares against a fixed
+-- dummy hash — so its timing does not reveal whether an email is registered.
+-- =========================================================================
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS users (
+  id         BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name       TEXT        NOT NULL,
+  email      TEXT        NOT NULL UNIQUE,
+  password   TEXT        NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- register(name, email, password) → { id, name, email }
+--   Raises unique_violation (23505) when email already exists.
+CREATE OR REPLACE FUNCTION register(p_name TEXT, p_email TEXT, p_password TEXT)
+RETURNS JSONB LANGUAGE plpgsql AS $$
+DECLARE
+  rec users;
+BEGIN
+  INSERT INTO users (name, email, password)
+  VALUES (p_name, p_email, crypt(p_password, gen_salt('bf', 12)))
+  RETURNING * INTO rec;
+  RETURN jsonb_build_object('id', rec.id, 'name', rec.name, 'email', rec.email);
+END;
+$$;
+
+-- login(email, password) → { id, name, email } or NULL on bad credentials.
+-- Always runs exactly one bcrypt crypt(): when the email is unknown it
+-- compares against a fixed dummy hash, so an attacker can't tell a missing
+-- account from a wrong password by timing (user-enumeration oracle).
+CREATE OR REPLACE FUNCTION login(p_email TEXT, p_password TEXT)
+RETURNS JSONB LANGUAGE plpgsql AS $$
+DECLARE
+  rec    users;
+  v_hash TEXT;
+  v_ok   BOOLEAN;
+  -- A valid throwaway bcrypt hash (cost 12) to spend crypt() time on when the
+  -- email doesn't exist. Its plaintext is irrelevant — it just equalises cost.
+  c_dummy CONSTANT TEXT := '$2a$12$R9h/cIPz0gi.URNNX3kh2OPST9/PgBkqquzi.Ss7KIUgO2t0jWMUW';
+BEGIN
+  SELECT * INTO rec FROM users WHERE email = p_email;
+  v_hash := COALESCE(rec.password, c_dummy);
+  v_ok   := (crypt(p_password, v_hash) = v_hash);
+  IF rec.id IS NULL OR NOT v_ok THEN
+    RETURN NULL;
+  END IF;
+  RETURN jsonb_build_object('id', rec.id, 'name', rec.name, 'email', rec.email);
+END;
+$$;