dzql 0.9.0 → 0.11.0

package/README.md

@@ -1,20 +1,15 @@
 # DZQL
 
-Database-first real-time framework with TypeScript support.
+**delta's compiled Postgres step.**
 
-## Quick Start
-
-```bash
-bun create dzql my-app
-cd my-app
-bun install
-bun run db:rebuild
-bun run dev
-```
+An app built on [@blueshed/delta](https://github.com/blueshed/delta) keeps its definitions
+(`defineSchema`, `defineDoc`), its client and its wire. On Postgres, dzql keeps its documents and
+compiles those definitions to SQL, each piece held equal to delta's own cases. Why, and where it
+is going: [philo.md](https://github.com/blueshed/dzql/blob/main/philo.md).
 
 ## delta's Postgres step
 
-dzql is becoming the Postgres step for apps built on [@blueshed/delta](https://github.com/blueshed/delta):
+dzql is the Postgres step for apps built on [@blueshed/delta](https://github.com/blueshed/delta):
 a delta app grows from a JSON file to SQLite to Postgres, and on Postgres its documents are kept by
 dzql. Since 0.8.0 dzql carries delta's Postgres backend, with the same names, so moving is an
 import change:
@@ -25,8 +20,29 @@ import { openPglite } from "dzql/pglite";   // Postgres in this process
 import { jwtAuth } from "dzql/auth-jwt";
 ```
 
-Its tests run delta's own cases (`@blueshed/delta/testing`) against it. Compiled SQL replaces the
-framework SQL in later releases; the plan is in Workshop's `docs/postgres-split-plan.md`.
+Its tests run delta's own cases (`@blueshed/delta/testing`) against it. `generateSql` writes the
+SQL for each of your documents and collections, compiled from their definitions (opening a
+document, reading its name, who holds a row, a write's scope and rows, what each document is told,
+the fan-out, the ledger's reads): nothing interprets a definition at run time. Apply it after the
+framework, every time, one app per database (`docs/delta/postgres.md`, "Compiled SQL"). The plan
+is in Workshop's `docs/postgres-split-plan.md`.
+
+## The whole-stack dzql (retiring)
+
+Before delta, dzql was a framework of its own: a `domain.ts` compiled to SQL, a typed client and
+Pinia stores, started with `bun create dzql`. It is kept working until step 5 of the plan retires
+it (the runtime, the client, the stores and `create-dzql`); nothing new is added to it. A new app
+starts from delta and moves to dzql when it moves to Postgres.
+
+### Quick start
+
+```bash
+bun create dzql my-app
+cd my-app
+bun install
+bun run db:rebuild
+bun run dev
+```
 
 ## Documentation
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dzql",
-  "version": "0.9.0",
-  "description": "Database-first real-time framework with TypeScript support",
+  "version": "0.11.0",
+  "description": "delta's compiled Postgres step: an app's delta definitions compiled to SQL",
   "repository": {
     "type": "git",
     "url": "https://github.com/blueshed/dzql"

package/src/compile/cascades.ts

@@ -0,0 +1,151 @@
+/**
+ * Compiled cascades: what a remove takes with it, and what a moved row
+ * carries. The framework walks `_delta_collections` at run time for a
+ * collection's children and the collections that cascade on it, and builds
+ * each query from their names; here the schema says them, and each is written.
+ *
+ * `compileCascades(schema)` writes, for every collection of the schema:
+ * - `dzql_cascade_remove__<slug>(id)`: the row closed (temporal) or deleted, and
+ *   only if it was there, each child collection's rows under it, then each
+ *   collection that cascades on it -- the removes, in that order;
+ * - `dzql_cascade_rows__<slug>(id)`: the rows that remove would take, read
+ *   before, in the order it takes them;
+ * - `dzql_hanging_rows__<slug>(id)`: the rows that hang from it, and on down,
+ *   parent first.
+ * And `_delta_cascade_remove`, `_delta_cascade_rows` and `_delta_hanging_rows`,
+ * sending each collection to its own; a collection there is not has nothing
+ * to take. The order is the one the framework's had: child collections by key, then
+ * the collections that cascade on it by key and key column, each in the
+ * database's byte order (`COLLATE "C"`), and each one's rows by id.
+ */
+import { q, type Schema } from "@blueshed/delta/backend";
+import { lit, named, standingRows } from "./opens";
+
+/** A collection's function: `dzql_<what>__<slug>`. */
+const fn = (what: string, coll: string): string => named(what, coll);
+
+/** As `COLLATE "C"` orders text: by its bytes. */
+const bytes = (a: string, b: string): number => Buffer.compare(Buffer.from(a), Buffer.from(b));
+
+/** A collection's children, and the collections that cascade on it, in the framework's order: [collection, key column]. */
+function reached(schema: Schema, coll: string): { children: [string, string][]; refs: [string, string][] } {
+  const table = schema.tables[coll]!;
+  const children = [...table.children].sort(bytes).map((c): [string, string] => [c, schema.tables[c]!.parent!.fkColumn]);
+  const refs = table.referencedBy
+    .filter((r) => r.collection !== coll)   // as generateSql's cascade_on: never a collection's own
+    .map((r): [string, string] => [r.collection, r.fkColumn])
+    .sort((a, b) => bytes(a[0], b[0]) || bytes(a[1], b[1]));
+  return { children, refs };
+}
+
+/** Every collection of `schema` its own slug: two that would share a function name are refused. */
+function assertSlugs(schema: Schema): void {
+  const seen = new Map<string, string>();
+  for (const coll of Object.keys(schema.tables)) {
+    const slug = fn("", coll);
+    const other = seen.get(slug);
+    if (other) throw new Error(`[dzql compile] collections "${other}" and "${coll}" would share the function name ${slug}: rename one`);
+    seen.set(slug, coll);
+  }
+}
+
+function removeOf(schema: Schema, coll: string): string {
+  const t = schema.tables[coll]!;
+  const { children, refs } = reached(schema, coll);
+  const walk = [...children, ...refs].map(([c, fk]) =>
+    `  FOR v_id IN SELECT id FROM ${standingRows(schema.tables[c]!)} WHERE ${q(fk)} = p_id ORDER BY id LOOP
+    v_ops := v_ops || ${fn("cascade_remove", c)}(v_id);
+  END LOOP;`);
+  return `CREATE OR REPLACE FUNCTION ${fn("cascade_remove", coll)}(p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_affected BIGINT;
+  v_id       BIGINT;
+  v_ops      JSONB;
+BEGIN
+  ${t.temporal ? `UPDATE ${q(t.name)} SET valid_to = NOW() WHERE id = p_id AND valid_to IS NULL;` : `DELETE FROM ${q(t.name)} WHERE id = p_id;`}
+  GET DIAGNOSTICS v_affected = ROW_COUNT;
+  IF v_affected = 0 THEN RETURN '[]'::jsonb; END IF;   -- only a removal that happened (closed already, or RLS filtered it)
+  v_ops := jsonb_build_array(jsonb_build_object('op', 'remove', 'path', _delta_build_path(${lit(coll)}, p_id::text)));
+${walk.join("\n")}
+  RETURN v_ops;
+END;
+$$ LANGUAGE plpgsql;`;
+}
+
+function rowsOf(schema: Schema, coll: string): string {
+  const t = schema.tables[coll]!;
+  const { children, refs } = reached(schema, coll);
+  const walk = [...children, ...refs].map(([c, fk]) =>
+    `  FOR v_id IN SELECT id FROM ${standingRows(schema.tables[c]!)} WHERE ${q(fk)} = p_id ORDER BY id LOOP
+    v_rows := v_rows || ${fn("cascade_rows", c)}(v_id);
+  END LOOP;`);
+  return `CREATE OR REPLACE FUNCTION ${fn("cascade_rows", coll)}(p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_row  JSONB;
+  v_id   BIGINT;
+  v_rows JSONB;
+BEGIN
+  SELECT to_jsonb(t.*) INTO v_row FROM ${standingRows(t)} t WHERE t.id = p_id;
+  IF v_row IS NULL THEN RETURN '[]'::jsonb; END IF;
+  v_rows := jsonb_build_array(jsonb_build_object('coll', ${lit(coll)}, 'id', p_id, 'row', _delta_strip_temporal(v_row)));
+${walk.join("\n")}
+  RETURN v_rows;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+function hangingOf(schema: Schema, coll: string): string {
+  const { children } = reached(schema, coll);
+  const parts = children.map(([c, fk]) => {
+    const below = schema.tables[c]!.children.length ? `${fn("hanging_rows", c)}(t.id)` : "'[]'::jsonb";
+    return `  SELECT COALESCE(jsonb_agg(e ORDER BY t.id, n), '[]'::jsonb) INTO v_part FROM ${standingRows(schema.tables[c]!)} t,
+         jsonb_array_elements(jsonb_build_array(jsonb_build_object('coll', ${lit(c)}, 'id', t.id, 'row', _delta_strip_temporal(to_jsonb(t.*)))) || ${below})
+           WITH ORDINALITY AS x(e, n)
+   WHERE t.${q(fk)} = p_id;
+  v_rows := v_rows || v_part;`;
+  });
+  return `CREATE OR REPLACE FUNCTION ${fn("hanging_rows", coll)}(p_id BIGINT)
+RETURNS JSONB AS $$
+DECLARE
+  v_part JSONB;
+  v_rows JSONB := '[]'::jsonb;
+BEGIN
+${parts.join("\n")}
+  RETURN v_rows;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** A dispatcher: each collection of `schema` to its own; any other has nothing to take. */
+function dispatch(schema: Schema, name: string, what: string, volatility: string): string {
+  const colls = Object.keys(schema.tables);
+  const body = colls.length
+    ? `  CASE p_collection_key
+${colls.map((c) => `    WHEN ${lit(c)} THEN RETURN ${fn(what, c)}(p_id);`).join("\n")}
+    ELSE RETURN '[]'::jsonb;   -- a collection there is not: nothing to take, nothing hangs from it
+  END CASE;`
+    : `  RETURN '[]'::jsonb;`;
+  return `CREATE OR REPLACE FUNCTION ${name}(p_collection_key TEXT, p_id BIGINT)
+RETURNS JSONB AS $$
+BEGIN
+${body}
+END;
+$$ LANGUAGE plpgsql${volatility};`;
+}
+
+/** The cascades and hanging rows of every collection of `schema`, and their dispatch. */
+export function compileCascades(schema: Schema): string {
+  assertSlugs(schema);
+  const colls = Object.keys(schema.tables);
+  return [
+    ...colls.map((c) => removeOf(schema, c)),
+    ...colls.map((c) => rowsOf(schema, c)),
+    ...colls.map((c) => hangingOf(schema, c)),
+    dispatch(schema, "_delta_cascade_remove", "cascade_remove", ""),
+    dispatch(schema, "_delta_cascade_rows", "cascade_rows", " STABLE"),
+    dispatch(schema, "_delta_hanging_rows", "hanging_rows", " STABLE"),
+    "",
+  ].join("\n\n");
+}

package/src/compile/columns.ts

@@ -0,0 +1,143 @@
+/**
+ * Compiled columns and their checks: what a write may name, and what each
+ * value must be. Asked of every op of a write (`delta_apply`).
+ *
+ * The columns are the writing process's: `delta.declared`, set for the call by
+ * its listener, else as the database last declared them (the schema is the
+ * contract: two versions on one database each write by their own). So they
+ * stay read at run time, as the framework reads them, and what is compiled is
+ * what follows from the definitions:
+ *
+ * - `dzql_columns__<slug>(collection, columns_def)` for each document: the
+ *   columns it writes, the ones it names (`columns`) where it names some,
+ *   from the list written in. `_delta_write_columns` sends each document to
+ *   its own, and refuses a name of none.
+ * - `_delta_assert_fields` itself: for each collection, each set of columns
+ *   the definitions give it (all of them, and each document's own), checked
+ *   by written statements -- the fields there are, the parent key, each
+ *   column's type -- with the framework's messages, put together in the
+ *   framework's order (`ORDER BY` in SQL, so the database's collation orders
+ *   both alike). Columns of another set (a walk's, another version's) are
+ *   checked by the columns given (`_delta_assert_fields_declared`).
+ */
+import type { ColumnDef, DocDef, ResolvedTable, Schema } from "@blueshed/delta/backend";
+import { lit, named, need, noDoc } from "./opens";
+
+/** A document's columns function: `dzql_columns__<slug>`. */
+export const columnsFunction = (prefix: string): string => named("columns", prefix);
+
+/** A set of columns as the database keeps it (`_delta_collections.columns_def`, generateSql's). */
+const asStored = (columns: Record<string, ColumnDef>): string => `${lit(JSON.stringify(columns))}::jsonb`;
+
+/** One document's columns function. */
+function columnsOf(schema: Schema, doc: DocDef): string {
+  const declared = "COALESCE(NULLIF(current_setting('delta.declared', true), '')::jsonb -> p_coll, p_columns_def)";
+  const named = Object.entries(doc.columns ?? {});
+  for (const [coll] of named) need(schema, doc, coll);
+  const body = named.length === 0
+    ? `  RETURN ${declared};`
+    : `  v_cols := ${declared};
+  CASE p_coll
+${named.map(([coll, cols]) => `    WHEN ${lit(coll)} THEN RETURN ${cols.length
+      ? `COALESCE((SELECT jsonb_object_agg(k, v) FROM jsonb_each(v_cols) AS e(k, v) WHERE k IN (${cols.map(lit).join(", ")})), '{}'::jsonb)`
+      : "'{}'::jsonb"};`).join("\n")}
+    ELSE RETURN v_cols;
+  END CASE;`;
+  return `CREATE OR REPLACE FUNCTION ${columnsFunction(doc.prefix)}(p_coll TEXT, p_columns_def JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  v_cols JSONB;
+BEGIN
+${body}
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** What a column's value must be, as the framework says it; none for a type it does not check. */
+const MUST: Record<string, [string, (v: string) => string]> = {
+  text: ["a string", (v) => `jsonb_typeof(${v}) = 'string'`],
+  integer: ["an integer", (v) => `jsonb_typeof(${v}) = 'number' AND ${v}::text::numeric = trunc(${v}::text::numeric)`],
+  real: ["a number", (v) => `jsonb_typeof(${v}) = 'number'`],
+  boolean: ["a boolean", (v) => `jsonb_typeof(${v}) = 'boolean'`],
+  timestamptz: ["an ISO-8601 time", (v) =>
+    `jsonb_typeof(${v}) = 'string' AND (${v} #>> '{}') ~ '^\\d{4}-\\d{2}-\\d{2}([T ]([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d(\\.\\d{1,6})?)?(Z|[+-]([01]\\d|2[0-3])(:?[0-5]\\d)?)?)?$'`],
+};
+
+/** The checks of one set of a collection's columns, as written statements. */
+function checksOf(table: ResolvedTable, columns: Record<string, ColumnDef>): string {
+  const fk = table.parent?.fkColumn;
+  const known = ["id", "valid_from", "valid_to", ...(fk ? [fk] : []), ...Object.keys(columns)];
+  const typed = Object.entries(columns).filter(([, d]) => MUST[d.type]);
+  const lines = [
+    `IF p_value IS NULL OR jsonb_typeof(p_value) <> 'object' THEN
+          RAISE EXCEPTION 'a row value for % must be an object', p_collection USING ERRCODE = '22023';
+        END IF;`,
+    `SELECT string_agg(k, ', ' ORDER BY k) INTO v_bad FROM jsonb_object_keys(p_value) AS k WHERE k NOT IN (${[...new Set(known)].map(lit).join(", ")});
+        IF v_bad IS NOT NULL THEN
+          RAISE EXCEPTION 'Unknown field: % (not a column of %)', v_bad, p_collection USING ERRCODE = '22023';
+        END IF;`,
+  ];
+  if (fk) {
+    const v = `p_value->${lit(fk)}`;
+    lines.push(`IF p_value ? ${lit(fk)} AND jsonb_typeof(${v}) <> 'null'
+           AND NOT (jsonb_typeof(${v}) = 'string' OR (jsonb_typeof(${v}) = 'number' AND (p_value->>${lit(fk)})::numeric = trunc((p_value->>${lit(fk)})::numeric))) THEN
+          RAISE EXCEPTION '% must be an id: an integer', ${lit(fk)} USING ERRCODE = '22023';
+        END IF;`);
+  }
+  if (typed.length) {
+    const rows = typed.map(([col, d]) => {
+      const v = `(p_value->${lit(col)})`;   // in parentheses: `::` binds tighter than `->`
+      const [must, ok] = MUST[d.type]!;
+      return `(${lit(col)}, CASE WHEN jsonb_typeof(${v}) <> 'null' AND NOT (${ok(v)}) THEN ${lit(`${col} must be ${must}`)} END)`;
+    });
+    lines.push(`SELECT string_agg(m, '; ' ORDER BY k) INTO v_bad FROM (VALUES
+          ${rows.join(",\n          ")}) AS x(k, m) WHERE m IS NOT NULL;
+        IF v_bad IS NOT NULL THEN RAISE EXCEPTION '%', v_bad USING ERRCODE = '22023'; END IF;`);
+  }
+  return [...lines, "RETURN;"].join("\n        ");
+}
+
+/** The SQL that gives and checks each of `docs`' columns: a function per document, `_delta_write_columns`, and `_delta_assert_fields`. */
+export function compileColumns(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `CREATE OR REPLACE FUNCTION _delta_write_columns(p_def _delta_docs, p_coll TEXT, p_columns_def JSONB)
+RETURNS JSONB AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${columnsFunction(d.prefix)}(p_coll, p_columns_def);`).join("\n")}
+    ELSE ${noDoc("p_def.prefix")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+
+  // each collection's sets of columns: all of them, and each document's own
+  const branches = Object.entries(schema.tables).map(([coll, table]) => {
+    const sets = new Map<string, Record<string, ColumnDef>>([[JSON.stringify(table.columns), table.columns]]);
+    for (const doc of docs) {
+      const named = doc.columns?.[coll];
+      if (!named) continue;
+      const own = Object.fromEntries(Object.entries(table.columns).filter(([c]) => named.includes(c)));
+      sets.set(JSON.stringify(own), own);
+    }
+    const fk = table.parent?.fkColumn;
+    return `    WHEN ${lit(coll)} THEN
+      IF p_parent_fk IS NOT DISTINCT FROM ${fk ? lit(fk) : "NULL"} THEN
+${[...sets.values()].map((cols) => `        IF p_columns = ${asStored(cols)} THEN
+        ${checksOf(table, cols)}
+        END IF;`).join("\n")}
+      END IF;`;
+  });
+  const checks = `CREATE OR REPLACE FUNCTION _delta_assert_fields(p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB)
+RETURNS void AS $$
+DECLARE
+  v_bad TEXT;
+BEGIN
+  CASE p_collection
+${branches.join("\n")}
+    ELSE NULL;
+  END CASE;
+  -- another set of columns (a walk's, another version's): by the columns given
+  PERFORM _delta_assert_fields_declared(p_collection, p_columns, p_parent_fk, p_value);
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;`;
+  return [...docs.map((d) => columnsOf(schema, d)), dispatch, checks, ""].join("\n\n");
+}

package/src/compile/holders.ts

@@ -0,0 +1,66 @@
+/**
+ * Compiled fan-out: which open documents hold a row. Asked by every write of
+ * every row it touches, as the row was before and as it is after
+ * (`_delta_holders`), and what each is told follows from it.
+ *
+ * `compileHolders(schema, docs)` writes `_delta_holders` itself, answering
+ * what the framework's answers, from the definitions: for the row's
+ * collection, each document that holds it, in turn -- its prefix's lock,
+ * shared; its open names, found as the framework finds them (by the root the
+ * row hangs from, its chain written as lookups, where the document is one row
+ * of an unscoped definition; else every open name of its prefix), and the
+ * writer's; each name its own prefix owns and whose document holds the row
+ * (`dzql_holds__<slug>`). There is no other document: the framework that asked
+ * the rest retired (todo #26). SECURITY DEFINER, with the search path it was
+ * applied with and pg_temp last, as the framework's was.
+ */
+import type { DocDef, Schema } from "@blueshed/delta/backend";
+import { chainRoot, holdsFunction } from "./holds";
+import { lit, need } from "./opens";
+
+/** One document's names that hold the row, for a collection it holds. */
+function askOf(schema: Schema, doc: DocDef, coll: string): string {
+  const table = need(schema, doc, coll);
+  const all = Object.keys(doc.scope ?? {}).length > 0 || (coll !== doc.root && !table.parent);
+  const prefix = lit(doc.prefix);
+  return `      -- ${doc.prefix}
+${all ? "" : `      v_rid := ${coll === doc.root ? "(p_row->>'id')::BIGINT" : chainRoot(schema, doc, coll)};\n`}      PERFORM pg_advisory_xact_lock_shared(hashtext('_delta_hold'), hashtext(${prefix}));
+      FOR v_cand IN
+        SELECT doc_name FROM _delta_held WHERE ${all ? `starts_with(doc_name, ${prefix})` : `doc_name IN (${prefix}, ${prefix} || v_rid::text)`}
+        UNION
+        SELECT p_writer WHERE p_writer IS NOT NULL AND starts_with(p_writer, ${prefix})
+      LOOP
+        IF NOT (v_cand = ANY(v_names))
+           AND NOT EXISTS (SELECT 1 FROM _delta_docs d WHERE length(d.prefix) > ${doc.prefix.length} AND starts_with(v_cand, d.prefix))   -- the longest prefix owns the name
+           AND ${holdsFunction(doc.prefix)}(v_cand, ${lit(coll)}, p_row) THEN
+          v_names := v_names || v_cand;
+        END IF;
+      END LOOP;`;
+}
+
+/** The SQL that answers who holds a row: `_delta_holders`, each of `docs` asked by its own lookups. */
+export function compileHolders(schema: Schema, docs: DocDef[]): string {
+  const branches = Object.keys(schema.tables).flatMap((coll) => {
+    const holding = docs.filter((d) => d.root === coll || d.include.includes(coll));
+    return holding.length ? [`    WHEN ${lit(coll)} THEN\n${holding.map((d) => askOf(schema, d, coll)).join("\n")}`] : [];
+  });
+  return `CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+RETURNS TEXT[] AS $$
+DECLARE
+  v_names TEXT[] := ARRAY[]::text[];
+  v_rid   BIGINT;
+  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;
+${branches.length ? `  CASE p_coll\n${branches.join("\n")}\n    ELSE NULL;\n  END CASE;\n` : ""}  RETURN v_names;
+END;
+$$ LANGUAGE plpgsql VOLATILE SECURITY DEFINER;
+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 $$;
+`;
+}

package/src/compile/holds.ts

@@ -0,0 +1,90 @@
+/**
+ * Compiled holds: does a document hold a row? Asked of every open document by
+ * every write (`_delta_holders`, the fan-out), on the row as it was before the
+ * write and as it is after.
+ *
+ * `compileHolds(schema, docs)` writes one function per document --
+ * `dzql_holds__<slug>(name, collection, row)` -- answering what the
+ * framework's `_delta_doc_holds` answers for it, from its definition: which
+ * collections it holds, its name's conditions tested on the row's own values
+ * (`scopeOf`, a name its columns cannot take holding nothing), a temporal row
+ * not told to a document named with a time past, and an included row's chain
+ * of parents up to the root, as written lookups. And `_delta_doc_holds`
+ * itself, which sends each document to its function and refuses a name of none (`no doc def for`: the framework that read the rest
+ * retired, todo #26).
+ */
+import { q, type DocDef, type ResolvedTable, type Schema } from "@blueshed/delta/backend";
+import { lit, named, need, noDoc, scopeOf, currentOnly } from "./opens";
+
+/** A document's holds function: `dzql_holds__<slug>`. */
+export const holdsFunction = (prefix: string): string => named("holds", prefix);
+
+
+/**
+ * The id of the root row an included row hangs from, as `_delta_chain_root`
+ * finds it: its parent key, then each parent's, through the tables as they
+ * stand; NULL where the chain ends short of the root.
+ */
+export function chainRoot(schema: Schema, doc: DocDef, coll: string): string {
+  let table = need(schema, doc, coll);
+  let id = `(p_row->>${lit(table.parent!.fkColumn)})::BIGINT`;
+  for (let depth = 0; depth < 32; depth++) {
+    const parentKey = table.parent!.collection;
+    if (parentKey === doc.root) return id;
+    const parent = need(schema, doc, parentKey);
+    if (!parent.parent) return "NULL::BIGINT";
+    id = `(SELECT p.${q(parent.parent.fkColumn)} FROM ${q(parent.name)} p WHERE p.id = ${id}${currentOnly(parent, "p")})`;
+    table = parent;
+  }
+  return "NULL::BIGINT";
+}
+
+/** One document's holds function. */
+function holdsOf(schema: Schema, doc: DocDef): string {
+  const root = need(schema, doc, doc.root);
+  // a name its columns cannot take (one opened before a rule refused it) holds nothing
+  const scope = scopeOf(schema, doc, () => "RETURN FALSE;");
+  const colls = [doc.root, ...doc.include.filter((c) => c !== doc.root)];
+  const pastTime = (table: ResolvedTable) => (table.temporal ? `\n      IF p_at <= now() THEN RETURN FALSE; END IF;` : "");
+  const branches = colls.map((coll) => {
+    const table = need(schema, doc, coll);
+    if (coll === doc.root) {
+      return `    WHEN ${lit(coll)} THEN${pastTime(table)}
+      IF v_single AND (p_row->>'id')::BIGINT IS DISTINCT FROM v_id THEN RETURN FALSE; END IF;
+      RETURN EXISTS (SELECT 1 FROM jsonb_populate_record(null::${q(root.name)}, p_row) t WHERE ${scope.conds || "TRUE"});`;
+    }
+    if (!table.parent) return `    WHEN ${lit(coll)} THEN${pastTime(table)}\n      RETURN TRUE;`;
+    return `    WHEN ${lit(coll)} THEN${pastTime(table)}
+      IF NOT v_single THEN RETURN TRUE; END IF;
+      RETURN ${chainRoot(schema, doc, coll)} IS NOT DISTINCT FROM v_id;`;
+  });
+  return `CREATE OR REPLACE FUNCTION ${holdsFunction(doc.prefix)}(p_name TEXT, p_coll TEXT, p_row JSONB)
+RETURNS BOOLEAN AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  IF p_row IS NULL OR p_coll NOT IN (${colls.map(lit).join(", ")}) THEN RETURN FALSE; END IF;
+  ${scope.body}
+  CASE p_coll
+${branches.join("\n")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** The SQL that answers who holds a row for each of `docs`: a function per document, and `_delta_doc_holds` sending each to its own. */
+export function compileHolds(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+RETURNS BOOLEAN AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${holdsFunction(d.prefix)}(p_doc_name, p_coll, p_row);`).join("\n")}
+    ELSE ${noDoc("p_doc_name")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => holdsOf(schema, d)), dispatch, ""].join("\n\n");
+}

package/src/compile/ledger.ts

@@ -0,0 +1,72 @@
+/**
+ * Compiled ledger reads: what the ledger reads to write an entry's inverse and
+ * to guard a walk of it (undo, redo). The framework read the document whole
+ * (`_delta_open(name, TRUE)`), a field's type and the rows beyond the document
+ * from the definitions at run time; here each is written from them.
+ *
+ * `compileLedger(schema, docs)` writes:
+ * - `dzql_open_whole__<slug>(name)` for each document: its open with every
+ *   column of every row, whatever columns it names (`readOf`, whole), and
+ *   `_delta_open` itself, sending each compiled document to its own open, shown
+ *   (`dzql_open__<slug>`) or whole, and refusing a name of none;
+ * - `_delta_same(collection, field, a, b)`: two values of a field the same, a
+ *   time by the instant it names. The field's type is the writing process's
+ *   (`delta.declared`), else the schema's, written in for each collection;
+ *   a collection there is not, the same as JSON;
+ * - `_delta_row_standing(collection, id)`: a row as it stands, as `{row}`, for
+ *   every collection of the schema; NULL for one there is not.
+ */
+import type { DocDef, Schema } from "@blueshed/delta/backend";
+import { lit, noDoc, openFunction, openWholeFunction, readOf, standingRows } from "./opens";
+
+/** The SQL the ledger reads by, for `schema` and each of `docs`. */
+export function compileLedger(schema: Schema, docs: DocDef[]): string {
+  const whole = docs.map((d) => readOf(schema, d, false, true));
+
+  const open = `CREATE OR REPLACE FUNCTION _delta_open(p_doc_name TEXT, p_whole BOOLEAN)
+RETURNS JSONB AS $$
+DECLARE
+  v_def _delta_docs := _delta_find_doc(p_doc_name);
+BEGIN
+  CASE v_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN CASE WHEN p_whole THEN ${openWholeFunction(d.prefix)}(p_doc_name) ELSE ${openFunction(d.prefix)}(p_doc_name) END;`).join("\n")}
+    ELSE ${noDoc("p_doc_name")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql;`;
+
+  const colls = Object.entries(schema.tables);
+  const same = `CREATE OR REPLACE FUNCTION _delta_same(p_coll TEXT, p_field TEXT, a JSONB, b JSONB)
+RETURNS BOOLEAN AS $$
+DECLARE
+  v_declared JSONB;
+  v_type     TEXT;
+BEGIN
+  IF jsonb_typeof(a) = 'string' AND jsonb_typeof(b) = 'string' THEN
+    CASE p_coll
+${colls.map(([coll, t]) => {
+    const times = Object.entries(t.columns).filter(([, d]) => d.type === "timestamptz").map(([c]) => c);
+    return `      WHEN ${lit(coll)} THEN
+        v_declared := NULLIF(current_setting('delta.declared', true), '')::jsonb -> ${lit(coll)};
+        v_type := CASE WHEN v_declared IS NOT NULL THEN v_declared -> p_field ->> 'type'${times.length ? ` WHEN p_field IN (${times.map(lit).join(", ")}) THEN 'timestamptz'` : ""} END;`;
+  }).join("\n")}
+      ELSE NULL;   -- a collection there is not: its values the same as JSON
+    END CASE;
+    IF v_type = 'timestamptz' THEN RETURN (a #>> '{}')::timestamptz = (b #>> '{}')::timestamptz; END IF;
+  END IF;
+  RETURN COALESCE(a, 'null'::jsonb) = COALESCE(b, 'null'::jsonb);
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+
+  const standing = `CREATE OR REPLACE FUNCTION _delta_row_standing(p_coll TEXT, p_id BIGINT)
+RETURNS JSONB AS $$
+BEGIN
+  CASE p_coll
+${colls.map(([coll, t]) => `    WHEN ${lit(coll)} THEN RETURN jsonb_build_object('row', (SELECT _delta_strip_temporal(to_jsonb(t.*)) FROM ${standingRows(t)} t WHERE t.id = p_id));`).join("\n")}
+    ELSE RETURN NULL;   -- a collection there is not
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+
+  return [...whole, open, same, standing, ""].join("\n\n");
+}