dzql 0.9.0 → 0.10.0

package/src/sql/001d-delta-write.sql

@@ -75,7 +75,7 @@ END $$;
 -- ---------------------------------------------------------------------------
 
 DROP FUNCTION IF EXISTS _delta_cascade_remove(TEXT, BIGINT, TEXT[]);
-CREATE OR REPLACE FUNCTION _delta_cascade_remove(
+CREATE OR REPLACE FUNCTION _delta_cascade_remove_framework(
   p_collection_key TEXT,
   p_id             BIGINT
 ) RETURNS JSONB AS $$
@@ -155,6 +155,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql;
 
+-- the framework's, until dzql's compiler (`compileCascades`) writes one per
+-- collection; the framework's own recursion goes through this name, so a
+-- collection either way cascades into the other
+CREATE OR REPLACE FUNCTION _delta_cascade_remove(p_collection_key TEXT, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_cascade_remove_framework(p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- _delta_cascade_rows: the rows _delta_cascade_remove would take, read before
 -- it takes them, in the order it emits their removes -- so who holds each can
@@ -162,7 +168,7 @@ $$ LANGUAGE plpgsql;
 -- ---------------------------------------------------------------------------
 
 DROP FUNCTION IF EXISTS _delta_cascade_rows(TEXT, BIGINT, TEXT[]);
-CREATE OR REPLACE FUNCTION _delta_cascade_rows(
+CREATE OR REPLACE FUNCTION _delta_cascade_rows_framework(
   p_collection_key TEXT,
   p_id             BIGINT
 ) RETURNS JSONB AS $$
@@ -209,6 +215,9 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+CREATE OR REPLACE FUNCTION _delta_cascade_rows(p_collection_key TEXT, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_cascade_rows_framework(p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- _delta_hanging_rows: the rows that hang from a row -- its children, theirs,
 -- and on down, whichever documents include them -- parent first, each
@@ -216,7 +225,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- hanging in sqlite.ts).
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_hanging_rows(p_collection_key TEXT, p_id BIGINT)
+CREATE OR REPLACE FUNCTION _delta_hanging_rows_framework(p_collection_key TEXT, p_id BIGINT)
 RETURNS JSONB AS $$
 DECLARE
   v_child RECORD;
@@ -238,6 +247,9 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+CREATE OR REPLACE FUNCTION _delta_hanging_rows(p_collection_key TEXT, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_hanging_rows_framework(p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- _delta_tell: tell every document that holds a row a write changed what
 -- changed for it (todo #28), and answer the writer's new version.
@@ -268,6 +280,53 @@ $$ LANGUAGE plpgsql STABLE;
 -- two-argument form logs none.
 -- ---------------------------------------------------------------------------
 
+-- _delta_told: what one document is told of a write -- `p_rows`, the write's
+-- touches with their holders, as _delta_tell gathers them -- by its name
+-- `p_target`: an add, a replace of each field that changed, a remove; its
+-- root's arrival or leaving as a replace. The framework's answer is
+-- `_delta_told_framework`; dzql's compiler (`compileTold`) replaces
+-- `_delta_told` with one sending each document it compiled to its own.
+
+CREATE OR REPLACE FUNCTION _delta_told_framework(p_def _delta_docs, p_target TEXT, p_rows JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  v_t      JSONB;
+  v_single BOOLEAN;
+  v_told   JSONB := '[]'::jsonb;
+  v_was    BOOLEAN;
+  v_is     BOOLEAN;
+  v_root   BOOLEAN;
+  v_path   TEXT;
+BEGIN
+  v_single := (_delta_resolve_scope(p_def, p_target)->>'mode') = 'single';
+  FOR v_t IN SELECT jsonb_array_elements(p_rows) LOOP
+    v_was := (v_t->'before') ? p_target;
+    v_is  := (v_t->'holders') ? p_target;
+    CONTINUE WHEN NOT v_was AND NOT v_is;
+    CONTINUE WHEN v_was AND v_is AND (v_t ? 'carried');   -- carried along, and held either way: unchanged for it
+    v_root := v_single AND (v_t->>'coll') = p_def.root_collection;
+    v_path := CASE WHEN v_root THEN _delta_build_path(v_t->>'coll') ELSE _delta_build_path(v_t->>'coll', v_t->>'id') END;
+    -- each row as this document shows it: the columns it holds (_delta_show, todo #70)
+    IF v_was AND v_is THEN   -- stayed: what changed
+      v_told := v_told || COALESCE((SELECT jsonb_agg(jsonb_build_object('op', 'replace', 'path', v_path || _delta_build_path(f), 'value', v) ORDER BY f COLLATE "C")
+                                      FROM jsonb_each(_delta_show(p_def, v_t->>'coll', v_t->'after')) AS e(f, v) WHERE v IS DISTINCT FROM v_t->'was'->f), '[]'::jsonb);
+    ELSIF v_is THEN
+      v_told := v_told || jsonb_build_array(jsonb_build_object(
+        'op', CASE WHEN v_root THEN 'replace' ELSE 'add' END, 'path', v_path, 'value', _delta_show(p_def, v_t->>'coll', v_t->'after')));
+    ELSIF v_root THEN   -- gone: null, or the empty root an implied document then opens with
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'replace', 'path', v_path, 'value',
+        CASE WHEN COALESCE(p_def.implied, FALSE) THEN _delta_show(p_def, v_t->>'coll', _delta_implied_root(p_def, (v_t->>'id')::BIGINT)) ELSE 'null'::jsonb END));
+    ELSE
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'remove', 'path', v_path));
+    END IF;
+  END LOOP;
+  RETURN v_told;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+CREATE OR REPLACE FUNCTION _delta_told(p_def _delta_docs, p_target TEXT, p_rows JSONB)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_told_framework(p_def, p_target, p_rows); $$;
+
 CREATE OR REPLACE FUNCTION _delta_tell(p_writer TEXT, p_touched JSONB, p_applied JSONB)
 RETURNS BIGINT AS $$
 DECLARE
@@ -277,12 +336,7 @@ DECLARE
   v_targets TEXT[] := ARRAY[]::text[];
   v_target  TEXT;
   v_def     _delta_docs;
-  v_single  BOOLEAN;
   v_told    JSONB;
-  v_was     BOOLEAN;
-  v_is      BOOLEAN;
-  v_root    BOOLEAN;
-  v_path    TEXT;
   v_version BIGINT;
   v_next    JSONB := '{}'::jsonb;   -- a row's holders, as its next touch found them
   v_key     TEXT;
@@ -309,29 +363,7 @@ BEGIN
   LOOP
     v_def := _delta_find_doc(v_target);
     CONTINUE WHEN v_def.prefix IS NULL;
-    v_single := (_delta_resolve_scope(v_def, v_target)->>'mode') = 'single';
-    v_told := '[]'::jsonb;
-    FOR v_t IN SELECT jsonb_array_elements(v_rows) LOOP
-      v_was := (v_t->'before') ? v_target;
-      v_is  := (v_t->'holders') ? v_target;
-      CONTINUE WHEN NOT v_was AND NOT v_is;
-      CONTINUE WHEN v_was AND v_is AND (v_t ? 'carried');   -- carried along, and held either way: unchanged for it
-      v_root := v_single AND (v_t->>'coll') = v_def.root_collection;
-      v_path := CASE WHEN v_root THEN _delta_build_path(v_t->>'coll') ELSE _delta_build_path(v_t->>'coll', v_t->>'id') END;
-      -- each row as this document shows it: the columns it holds (_delta_show, todo #70)
-      IF v_was AND v_is THEN   -- stayed: what changed
-        v_told := v_told || COALESCE((SELECT jsonb_agg(jsonb_build_object('op', 'replace', 'path', v_path || _delta_build_path(f), 'value', v) ORDER BY f COLLATE "C")
-                                        FROM jsonb_each(_delta_show(v_def, v_t->>'coll', v_t->'after')) AS e(f, v) WHERE v IS DISTINCT FROM v_t->'was'->f), '[]'::jsonb);
-      ELSIF v_is THEN
-        v_told := v_told || jsonb_build_array(jsonb_build_object(
-          'op', CASE WHEN v_root THEN 'replace' ELSE 'add' END, 'path', v_path, 'value', _delta_show(v_def, v_t->>'coll', v_t->'after')));
-      ELSIF v_root THEN   -- gone: null, or the empty root an implied document then opens with
-        v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'replace', 'path', v_path, 'value',
-          CASE WHEN COALESCE(v_def.implied, FALSE) THEN _delta_show(v_def, v_t->>'coll', _delta_implied_root(v_def, (v_t->>'id')::BIGINT)) ELSE 'null'::jsonb END));
-      ELSE
-        v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'remove', 'path', v_path));
-      END IF;
-    END LOOP;
+    v_told := _delta_told(v_def, v_target, v_rows);
     IF v_target = p_writer THEN
       v_version := _delta_bump_and_notify(p_writer, v_told, CASE WHEN p_applied IS DISTINCT FROM v_told THEN p_applied END);
     ELSIF jsonb_array_length(v_told) > 0 THEN
@@ -353,7 +385,7 @@ RETURNS BIGINT LANGUAGE sql AS $$ SELECT _delta_tell(p_writer, p_touched, NULL);
 -- not yet written opens empty). `there` in sqlite.ts.
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_row_there(p_collection_key TEXT, p_id BIGINT)
+CREATE OR REPLACE FUNCTION _delta_row_there_framework(p_collection_key TEXT, p_id BIGINT)
 RETURNS BOOLEAN AS $$
 DECLARE
   v_coll   RECORD;
@@ -367,6 +399,10 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- the framework's, until dzql's compiler (`compileRows`) writes one per collection
+CREATE OR REPLACE FUNCTION _delta_row_there(p_collection_key TEXT, p_id BIGINT)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_row_there_framework(p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- _delta_assert_parent_held: a parent key written (in `p_value`, over the row
 -- as it is, `p_row`) moves the row, and only under a parent the document holds,
@@ -414,6 +450,136 @@ RETURNS JSONB AS $$
     ELSE COALESCE((SELECT jsonb_object_agg(k, v) FROM jsonb_each(p_columns) AS e(k, v) WHERE (p_def.held->p_coll) ? k), '{}'::jsonb) END;
 $$ LANGUAGE sql STABLE;
 
+-- _delta_root_there: is a single document's root row `p_id` there now, and
+-- does it meet the whole of its name's scope (a column beside its id), as
+-- delta_open reads it? Asked before each op of a write (delta_apply). The
+-- framework's runs the scope's conditions as text (`p_scope`, the resolver's
+-- answer) over the root's current rows (`p_view`); dzql's compiler
+-- (`compileRootThere`) replaces `_delta_root_there` with one sending each
+-- document it compiled to its own.
+CREATE OR REPLACE FUNCTION _delta_root_there_framework(p_def _delta_docs, p_doc_name TEXT, p_scope JSONB, p_view TEXT, p_id BIGINT)
+RETURNS BOOLEAN AS $$
+DECLARE
+  v_exists BOOLEAN;
+BEGIN
+  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I t WHERE t.id = $1 AND %s)', p_view, p_scope->>'where') INTO v_exists USING p_id;
+  RETURN v_exists;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+CREATE OR REPLACE FUNCTION _delta_root_there(p_def _delta_docs, p_doc_name TEXT, p_scope JSONB, p_view TEXT, p_id BIGINT)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_root_there_framework(p_def, p_doc_name, p_scope, p_view, p_id); $$;
+
+-- _delta_write_columns: the columns of `p_coll` a document writes -- as the
+-- process writing declares them (_delta_cols), those the document holds
+-- (_delta_held_columns). The framework's, until dzql's compiler
+-- (`compileColumns`) replaces it with one sending each document it compiled to
+-- its own.
+CREATE OR REPLACE FUNCTION _delta_write_columns_framework(p_def _delta_docs, p_coll TEXT, p_columns_def JSONB)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_held_columns(p_def, p_coll, _delta_cols(p_coll, p_columns_def)); $$;
+
+CREATE OR REPLACE FUNCTION _delta_write_columns(p_def _delta_docs, p_coll TEXT, p_columns_def JSONB)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_write_columns_framework(p_def, p_coll, p_columns_def); $$;
+
+-- ---------------------------------------------------------------------------
+-- A row's SQL, as delta_apply runs it: the framework's, built from the table's
+-- name at run time; dzql's compiler (`compileRows`) replaces each with one
+-- written for each collection it compiled, any other sent here.
+--   _delta_row_lock: a row as it stands, locked for the write (NULL: not there)
+--   _delta_row_put: a replace's row stored -- a temporal one a new version (one
+--     this write made gives way to it; the standing one closes at `p_ts`), else
+--     the row again -- answered as stored
+--   _delta_next_id: an add's id, minted
+--   _delta_row_clear_moment: a temporal version this write made and took back
+--     (it never was outside the write), so an add of its id takes its place
+-- (_delta_row_there, above, is an add's "is the id there now".)
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION _delta_row_lock_framework(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+  IF p_temporal THEN
+    EXECUTE format('SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 AND valid_to IS NULL FOR UPDATE', p_table) INTO v_row USING p_id;
+  ELSE
+    EXECUTE format('SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 FOR UPDATE', p_table) INTO v_row USING p_id;
+  END IF;
+  RETURN v_row;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION _delta_row_put_framework(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT, p_row JSONB, p_ts TIMESTAMPTZ)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+  IF p_temporal THEN
+    EXECUTE format('DELETE FROM %I WHERE id = $1 AND valid_to IS NULL AND valid_from = $2', p_table) USING p_id, p_ts;
+    EXECUTE format('UPDATE %I SET valid_to = $2 WHERE id = $1 AND valid_to IS NULL', p_table) USING p_id, p_ts;
+    EXECUTE format('INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)', p_table, p_table)
+      INTO v_row USING p_row || jsonb_build_object('valid_from', p_ts, 'valid_to', NULL);
+  ELSE
+    EXECUTE format('DELETE FROM %I WHERE id = $1', p_table) USING p_id;
+    EXECUTE format('INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)', p_table, p_table)
+      INTO v_row USING p_row;
+  END IF;
+  RETURN v_row;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION _delta_next_id_framework(p_coll TEXT, p_table TEXT)
+RETURNS BIGINT AS $$
+DECLARE
+  v_id BIGINT;
+BEGIN
+  EXECUTE format('SELECT nextval(%L)', 'seq_' || p_table) INTO v_id;
+  RETURN v_id;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION _delta_row_clear_moment_framework(p_coll TEXT, p_table TEXT, p_id BIGINT, p_ts TIMESTAMPTZ)
+RETURNS void AS $$
+BEGIN
+  EXECUTE format('DELETE FROM %I WHERE id = $1 AND valid_from = $2 AND valid_to = $2', p_table) USING p_id, p_ts;
+END;
+$$ LANGUAGE plpgsql;
+
+-- _delta_row_add: an add's row stored, naming the columns the row gives (_delta_insert_sql), answered as stored
+CREATE OR REPLACE FUNCTION _delta_row_add_framework(p_coll TEXT, p_table TEXT, p_row JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+  EXECUTE _delta_insert_sql(p_table, p_row) || ' RETURNING to_jsonb(t.*)' INTO v_row USING p_row;
+  RETURN v_row;
+END;
+$$ LANGUAGE plpgsql;
+
+-- _delta_row_read: a row as it stands, without its validity (NULL: not there)
+CREATE OR REPLACE FUNCTION _delta_row_read_framework(p_coll TEXT, p_view TEXT, p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_row JSONB;
+BEGIN
+  EXECUTE format('SELECT _delta_strip_temporal(to_jsonb(t.*)) FROM %I t WHERE t.id = $1', p_view) INTO v_row USING p_id;
+  RETURN v_row;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+CREATE OR REPLACE FUNCTION _delta_row_add(p_coll TEXT, p_table TEXT, p_row JSONB)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_row_add_framework(p_coll, p_table, p_row); $$;
+CREATE OR REPLACE FUNCTION _delta_row_read(p_coll TEXT, p_view TEXT, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_row_read_framework(p_coll, p_view, p_id); $$;
+CREATE OR REPLACE FUNCTION _delta_row_lock(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_row_lock_framework(p_coll, p_table, p_temporal, p_id); $$;
+CREATE OR REPLACE FUNCTION _delta_row_put(p_coll TEXT, p_table TEXT, p_temporal BOOLEAN, p_id BIGINT, p_row JSONB, p_ts TIMESTAMPTZ)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_row_put_framework(p_coll, p_table, p_temporal, p_id, p_row, p_ts); $$;
+CREATE OR REPLACE FUNCTION _delta_next_id(p_coll TEXT, p_table TEXT)
+RETURNS BIGINT LANGUAGE sql AS $$ SELECT _delta_next_id_framework(p_coll, p_table); $$;
+CREATE OR REPLACE FUNCTION _delta_row_clear_moment(p_coll TEXT, p_table TEXT, p_id BIGINT, p_ts TIMESTAMPTZ)
+RETURNS void LANGUAGE sql AS $$ SELECT _delta_row_clear_moment_framework(p_coll, p_table, p_id, p_ts); $$;
+
 CREATE OR REPLACE FUNCTION _delta_whole(p_columns JSONB, p_value JSONB)
 RETURNS JSONB AS $$
 DECLARE
@@ -524,11 +690,11 @@ BEGIN
   -- documents, which showed it already (ensureImpliedRoot in sqlite.ts); an
   -- empty write makes nothing
   IF NOT v_is_list AND COALESCE(v_def.implied, FALSE) AND jsonb_array_length(p_ops) > 0 THEN
-    EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', v_root_view) INTO v_exists USING v_doc_id;
+    v_exists := _delta_row_there(v_def.root_collection, v_doc_id);
     PERFORM _delta_make_implied(v_def, v_doc_id, p_ops, v_ts);
     IF NOT v_exists THEN
       v_passed := jsonb_build_object(v_root_coll.table_name, v_doc_id);
-      EXECUTE format('SELECT _delta_strip_temporal(to_jsonb(t.*)) FROM %I t WHERE t.id = $1', v_root_view) INTO v_row USING v_doc_id;
+      v_row := _delta_row_read(v_def.root_collection, v_root_view, v_doc_id);
       IF v_row IS NOT NULL THEN
         v_touched := jsonb_build_array(jsonb_build_object('coll', v_def.root_collection, 'id', v_doc_id, 'after', v_row, 'carried', TRUE,
           'before', COALESCE((SELECT jsonb_agg(n) FROM unnest(_delta_holders(v_def.root_collection, v_row, p_doc_name)) AS n
@@ -541,7 +707,7 @@ BEGIN
   -- An empty write is asked what each op is (below): a single document whose
   -- root is not there is not found, as on SQLite -- unless implied, or a walk.
   IF jsonb_array_length(p_ops) = 0 AND NOT v_is_list AND NOT COALESCE(p_walk, FALSE) AND NOT COALESCE(v_def.implied, FALSE) THEN
-    EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I t WHERE t.id = $1 AND %s)', v_root_view, v_scope->>'where') INTO v_exists USING v_doc_id;
+    v_exists := _delta_root_there(v_def, p_doc_name, v_scope, v_root_view, v_doc_id);
     IF NOT v_exists THEN
       RAISE EXCEPTION 'document not found: % (its root, %, is not there)',
         p_doc_name, _delta_build_path(v_def.root_collection, v_doc_id::text)
@@ -565,7 +731,7 @@ BEGIN
     -- (_delta_walk_plan), as SQLite's and ./json's are.
     IF NOT v_is_list AND NOT COALESCE(p_walk, FALSE) THEN   -- a walk not said (null) is none
       -- there, and meeting the whole of its name's scope (a column beside its id), as delta_open reads it
-      EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I t WHERE t.id = $1 AND %s)', v_root_view, v_scope->>'where') INTO v_exists USING v_doc_id;
+      v_exists := _delta_root_there(v_def, p_doc_name, v_scope, v_root_view, v_doc_id);
       v_opened := COALESCE(v_opened, v_exists OR COALESCE(v_def.implied, FALSE));
       v_back := FALSE;
       IF NOT v_exists AND v_opened AND v_op->>'op' = 'add' THEN
@@ -594,7 +760,7 @@ BEGIN
       THEN COALESCE((SELECT jsonb_object_agg(c, '{"nullable": true}'::jsonb) FROM unnest(_delta_stored_columns(v_coll.table_name)) AS c
                       WHERE c NOT IN ('id', 'valid_from', 'valid_to') AND c IS DISTINCT FROM v_coll.parent_fk), '{}'::jsonb)
            || _delta_cols(v_coll_key, v_coll.columns_def)
-      ELSE _delta_held_columns(v_def, v_coll_key, _delta_cols(v_coll_key, v_coll.columns_def)) END;
+      ELSE _delta_write_columns(v_def, v_coll_key, v_coll.columns_def) END;
 
     -- Scope guard: an op may only target the doc's root or an included
     -- collection. Defence-in-depth — a client that opened doc A must not write
@@ -637,17 +803,7 @@ BEGIN
       v_blank := CASE WHEN array_length(v_parts, 1) = 1 THEN _delta_whole(v_cols, v_op->'value') ELSE '{}'::jsonb END;
 
       -- Read + lock
-      IF v_coll.temporal THEN
-        EXECUTE format(
-          'SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 AND valid_to IS NULL FOR UPDATE',
-          v_coll.table_name
-        ) INTO v_row USING v_doc_id;
-      ELSE
-        EXECUTE format(
-          'SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 FOR UPDATE',
-          v_coll.table_name
-        ) INTO v_row USING v_doc_id;
-      END IF;
+      v_row := _delta_row_lock(v_coll_key, v_coll.table_name, v_coll.temporal, v_doc_id);   -- read, and lock
 
       IF v_row IS NULL THEN
         RAISE EXCEPTION 'root row not found: %', v_def.root_collection USING ERRCODE = 'P0002';
@@ -660,34 +816,8 @@ BEGIN
       -- is the path's (it renumbered the row).
       v_new_row := v_row || v_blank || (v_op->'value') || jsonb_build_object('id', v_doc_id);
 
-      IF v_coll.temporal THEN
-        -- One version per write: a version this write made (its valid_from is the
-        -- write's NOW()) gives way to the next, rather than closing at the same
-        -- instant and colliding with it on (id, valid_from).
-        EXECUTE format(
-          'DELETE FROM %I WHERE id = $1 AND valid_to IS NULL AND valid_from = $2',
-          v_coll.table_name
-        ) USING v_doc_id, v_ts;
-        EXECUTE format(
-          'UPDATE %I SET valid_to = $2 WHERE id = $1 AND valid_to IS NULL',
-          v_coll.table_name
-        ) USING v_doc_id, v_ts;
-
-        v_new_row := v_new_row || jsonb_build_object('valid_from', v_ts, 'valid_to', NULL);
-
-        EXECUTE format(
-          'INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)',
-          v_coll.table_name, v_coll.table_name
-        ) INTO v_new_row USING v_new_row;
-
-        v_new_row := _delta_strip_temporal(v_new_row);
-      ELSE
-        EXECUTE format('DELETE FROM %I WHERE id = $1', v_coll.table_name) USING v_doc_id;
-        EXECUTE format(
-          'INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)',
-          v_coll.table_name, v_coll.table_name
-        ) INTO v_new_row USING v_new_row;
-      END IF;
+      v_new_row := _delta_row_put(v_coll_key, v_coll.table_name, v_coll.temporal, v_doc_id, v_new_row, v_ts);   -- the new version, or the row again
+      IF v_coll.temporal THEN v_new_row := _delta_strip_temporal(v_new_row); END IF;
 
       -- The root written through its document stays in its scope, as a list's
       -- rows do (below): one written out of the rest of its name's scope -- a
@@ -737,7 +867,7 @@ BEGIN
       v_id_text := v_parts[2];
       -- Auto-generate ID from sequence if path ends with '-'
       IF v_id_text = '-' THEN
-        EXECUTE format('SELECT nextval(%L)', 'seq_' || v_coll.table_name) INTO v_id;
+        v_id := _delta_next_id(v_coll_key, v_coll.table_name);
       ELSE
         v_id := _delta_row_id(v_coll_key, v_id_text);
       END IF;
@@ -767,7 +897,7 @@ BEGIN
         v_exists := NOT _delta_serial_new(v_coll.table_name, v_id);
       END IF;
       IF NOT v_exists AND (v_id_text <> '-' OR v_coll.temporal) THEN
-        EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', v_view) INTO v_exists USING v_id;
+        v_exists := _delta_row_there(v_coll_key, v_id);
       END IF;
       IF v_exists THEN
         RAISE EXCEPTION 'id already taken: % -- add to % for a new id',
@@ -847,10 +977,7 @@ BEGIN
         -- valid_from and valid_to both the write's NOW()) never was outside it,
         -- so an add of the same id takes its place rather than colliding with it
         -- on (id, valid_from). SQLite's insertCollectionRow keeps the same rule.
-        EXECUTE format(
-          'DELETE FROM %I WHERE id = $1 AND valid_from = $2 AND valid_to = $2',
-          v_coll.table_name
-        ) USING v_id, v_ts;
+        PERFORM _delta_row_clear_moment(v_coll_key, v_coll.table_name, v_id, v_ts);
         v_new_row := v_new_row || jsonb_build_object('valid_from', v_ts, 'valid_to', NULL);
       END IF;
 
@@ -858,7 +985,7 @@ BEGIN
       -- value its column casts (a scope's '1' into an integer, a date into a
       -- timestamptz) is told as a later open reads it, so the broadcast, the
       -- ledger's entry and undo's guard agree with the table.
-      EXECUTE _delta_insert_sql(v_coll.table_name, v_new_row) || ' RETURNING to_jsonb(t.*)' INTO v_new_row USING v_new_row;
+      v_new_row := _delta_row_add(v_coll_key, v_coll.table_name, v_new_row);
 
       -- An id the add named moves the serial past it, so a later /- does not meet it.
       IF v_id_text <> '-' AND v_id > COALESCE((v_passed->>v_coll.table_name)::BIGINT, 0) THEN
@@ -955,17 +1082,7 @@ BEGIN
           USING ERRCODE = 'P0002';
       END IF;
 
-      IF v_coll.temporal THEN
-        EXECUTE format(
-          'SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 AND valid_to IS NULL FOR UPDATE',
-          v_coll.table_name
-        ) INTO v_row USING v_id;
-      ELSE
-        EXECUTE format(
-          'SELECT to_jsonb(t.*) FROM %I t WHERE t.id = $1 FOR UPDATE',
-          v_coll.table_name
-        ) INTO v_row USING v_id;
-      END IF;
+      v_row := _delta_row_lock(v_coll_key, v_coll.table_name, v_coll.temporal, v_id);   -- read, and lock
 
       IF v_row IS NULL THEN
         RAISE EXCEPTION 'row not found: %/%', v_coll_key, v_id USING ERRCODE = 'P0002';
@@ -1000,35 +1117,7 @@ BEGIN
       -- an add's is (it renumbered the row).
       v_new_row := v_row || v_blank || (v_op->'value') || jsonb_build_object('id', v_id);
 
-      IF v_coll.temporal THEN
-        -- One version per write: a version this write made (its valid_from is the
-        -- write's NOW()) gives way to the next, rather than closing at the same
-        -- instant and colliding with it on (id, valid_from).
-        EXECUTE format(
-          'DELETE FROM %I WHERE id = $1 AND valid_to IS NULL AND valid_from = $2',
-          v_coll.table_name
-        ) USING v_id, v_ts;
-        EXECUTE format(
-          'UPDATE %I SET valid_to = $2 WHERE id = $1 AND valid_to IS NULL',
-          v_coll.table_name
-        ) USING v_id, v_ts;
-
-        v_new_row := v_new_row || jsonb_build_object('valid_from', v_ts, 'valid_to', NULL);
-
-        EXECUTE format(
-          'INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)',
-          v_coll.table_name, v_coll.table_name
-        ) INTO v_new_row USING v_new_row;
-      ELSE
-        -- Non-temporal: UPDATE with merged row
-        EXECUTE format(
-          'DELETE FROM %I WHERE id = $1', v_coll.table_name
-        ) USING v_id;
-        EXECUTE format(
-          'INSERT INTO %I AS t SELECT * FROM jsonb_populate_record(null::%I, $1) RETURNING to_jsonb(t.*)',
-          v_coll.table_name, v_coll.table_name
-        ) INTO v_new_row USING v_new_row;
-      END IF;
+      v_new_row := _delta_row_put(v_coll_key, v_coll.table_name, v_coll.temporal, v_id, v_new_row, v_ts);   -- the new version, or the row again
 
       -- A list's root row written through the list stays in its scope, as an
       -- add through it is given its bindings: a field, a row or a merge that

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

@@ -29,6 +29,8 @@ CREATE TABLE IF NOT EXISTS _delta_ledger (
 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);
+-- a cursor's entries newest first: where an undo or a redo looks for its tip (_delta_ledger_tip)
+CREATE INDEX IF NOT EXISTS idx_delta_ledger_cursor_id ON _delta_ledger (cursor, id);
 
 -- ---------------------------------------------------------------------------
 -- _delta_row_at: the row a document holds at a row's path, split -- the twin
@@ -204,25 +206,44 @@ $$ LANGUAGE plpgsql;
 -- what could be redone; an entry not undoable (a fact) starts no chain.
 -- ---------------------------------------------------------------------------
 
+-- _delta_ledger_tip: the entry an undo (p_back) or a redo of a cursor takes --
+-- the newest tip of the cursor's chains that goes the way asked: back, a tip at
+-- an even depth (a write, or a redo); forward, one at an odd depth (an undo that
+-- changed something) newer than the cursor's last write. Found newest first,
+-- among the cursor's own entries, so it costs what was written since the
+-- answer, not the cursor's whole history (todo #28): every entry of a chain
+-- carries its write's cursor, as delta_walk records it (an entry recorded by
+-- hand as walking another cursor's chain is not one of this cursor's tips).
 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;
+DECLARE
+  v_entry _delta_ledger;
+  v_up    _delta_ledger;
+  v_depth INT;
+BEGIN
+  -- a step at a time, each the next older entry (LIMIT 1 on the cursor's index): it reads as far as it goes
+  SELECT * INTO v_entry FROM _delta_ledger WHERE cursor = p_cursor ORDER BY id DESC LIMIT 1;
+  WHILE v_entry.id IS NOT NULL LOOP
+    -- the cursor's last write, met newest first: a redo is of nothing older (a fresh write ends what could be redone)
+    IF NOT p_back AND v_entry.undoes IS NULL AND v_entry.undoable THEN RETURN NULL; END IF;
+    IF NOT EXISTS (SELECT 1 FROM _delta_ledger w WHERE w.undoes = v_entry.id) THEN   -- a tip: nothing has walked it
+      -- its depth along its chain, up to the write that began it
+      v_depth := 0;
+      v_up := v_entry;
+      WHILE v_up.undoes IS NOT NULL LOOP
+        SELECT * INTO v_up FROM _delta_ledger WHERE id = v_up.undoes;
+        v_depth := v_depth + 1;
+      END LOOP;
+      IF v_up.cursor IS NOT DISTINCT FROM p_cursor AND v_up.undoable THEN   -- a chain this cursor's undoable write began
+        IF p_back AND v_depth % 2 = 0 THEN RETURN v_entry; END IF;
+        IF NOT p_back AND v_depth % 2 = 1 AND v_entry.undoable THEN RETURN v_entry; END IF;   -- a walk recorded as changing nothing is never redone
+      END IF;
+    END IF;
+    SELECT * INTO v_entry FROM _delta_ledger WHERE cursor = p_cursor AND id < v_entry.id ORDER BY id DESC LIMIT 1;
+  END LOOP;
+  RETURN NULL;
+END;
+$$ LANGUAGE plpgsql STABLE;
 
 -- JSON values the same, with JSON null and a missing value the same.
 CREATE OR REPLACE FUNCTION _delta_same(a JSONB, b JSONB)
@@ -233,7 +254,7 @@ $$;
 -- 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)
+CREATE OR REPLACE FUNCTION _delta_same_framework(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'
@@ -243,6 +264,31 @@ RETURNS BOOLEAN LANGUAGE sql STABLE AS $$
   END;
 $$;
 
+-- the framework's, until dzql's compiler (`compileLedger`) writes each
+-- collection's time fields in
+CREATE OR REPLACE FUNCTION _delta_same(p_coll TEXT, p_field TEXT, a JSONB, b JSONB)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_same_framework(p_coll, p_field, a, b); $$;
+
+-- _delta_row_standing: row `p_id` of a collection as it stands, without its
+-- validity, as {row} (row null: not there); NULL for a collection there is not.
+-- What a walk guards a row beyond its document by.
+CREATE OR REPLACE FUNCTION _delta_row_standing_framework(p_coll TEXT, p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_coll RECORD;
+  v_row  JSONB;
+BEGIN
+  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_coll;
+  IF NOT FOUND THEN RETURN NULL; END IF;
+  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 p_id;
+  RETURN jsonb_build_object('row', v_row);
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+CREATE OR REPLACE FUNCTION _delta_row_standing(p_coll TEXT, p_id BIGINT)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_row_standing_framework(p_coll, p_id); $$;
+
 -- _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
@@ -306,11 +352,9 @@ BEGIN
   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));
+    v_row := _delta_row_standing(v_parts[1], v_parts[2]::bigint);
+    CONTINUE WHEN v_row IS NULL;   -- a collection there is not
+    v_beyond := v_beyond || jsonb_build_array(jsonb_build_object('coll', v_parts[1], 'id', v_parts[2]::bigint, 'row', v_row->'row'));
   END LOOP;
   v_doc := _delta_beside(v_doc, v_def, v_beyond);
 

package/src/sql/auth-jwt.sql

@@ -2,7 +2,7 @@
 -- auth-jwt — reference users schema + login / register stored functions.
 -- =========================================================================
 --
--- Apply this alongside the @blueshed/delta/auth-jwt module. Consumers who
+-- Apply this alongside the dzql/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 })`.