dzql 0.8.0 → 0.10.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. Compiled SQL is replacing
+the framework SQL a piece at a time: `generateSql` writes functions for each of your documents
+(opening it, reading its name, who holds a row, a write's scope, what each document is told, the
+fan-out), each held equal to the framework's; documents it did not compile go to the framework. Apply `generateSql`
+after the framework, every time (`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/docs/README.md

@@ -1,5 +1,11 @@
 # DZQL: Realtime Apps Without the Boilerplate
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 DZQL compiles your data model into a complete realtime backend. Define entities and permissions in TypeScript, get a PostgreSQL database with CRUD operations, WebSocket sync, and type-safe client SDK - all generated.
 
 ## Why DZQL?

package/docs/for_ai.md

@@ -1,5 +1,11 @@
 # DZQL Domain Modeling Guide
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 This guide defines patterns for generating valid DZQL domain definitions.
 
 ## Quick Reference

package/docs/project-setup.md

@@ -1,5 +1,11 @@
 # DZQL Project Setup Guide
 
+> **The whole-stack dzql.** This describes dzql as it stood at 0.7: `domain.ts`, its runtime, the
+> typed client and the Pinia stores. They keep working until step 5 of Workshop's
+> `docs/postgres-split-plan.md` retires them. dzql is now delta's compiled Postgres step: a new app
+> starts on [@blueshed/delta](https://github.com/blueshed/delta) and comes to dzql through
+> `dzql/postgres` (`philo.md`, at the repo's root).
+
 Complete guide for setting up a Vue/Pinia client project with DZQL.
 
 ## Quick Start

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dzql",
-  "version": "0.8.0",
-  "description": "Database-first real-time framework with TypeScript support",
+  "version": "0.10.0",
+  "description": "delta's compiled Postgres step: an app's delta definitions compiled to SQL",
   "repository": {
     "type": "git",
     "url": "https://github.com/blueshed/dzql"
@@ -17,7 +17,8 @@
     "./namespace": "./src/runtime/namespace.ts",
     "./postgres": "./src/postgres/index.ts",
     "./pglite": "./src/postgres/pglite.ts",
-    "./auth-jwt": "./src/postgres/auth-jwt.ts"
+    "./auth-jwt": "./src/postgres/auth-jwt.ts",
+    "./compile": "./src/compile/opens.ts"
   },
   "files": [
     "src",
@@ -29,7 +30,8 @@
   "scripts": {
     "test": "bun run test:setup && bun test; status=$?; bun run test:teardown; exit $status",
     "test:setup": "docker compose down -v && docker compose up -d --wait",
-    "test:teardown": "docker compose down -v"
+    "test:teardown": "docker compose down -v",
+    "bench": "bun run bench/run.ts"
   },
   "keywords": [
     "postgresql",
@@ -48,7 +50,6 @@
   "author": "Peter Bunyan",
   "license": "MIT",
   "dependencies": {
-    "@blueshed/delta": "^0.16.0",
     "@electric-sql/pglite": "^0.5.4",
     "dotenv": "^16.4.5",
     "jose": "^6.2.4",
@@ -56,14 +57,17 @@
     "postgres": "^3.4.3"
   },
   "devDependencies": {
+    "@blueshed/railroad": "^0.16.0",
     "@types/bun": "latest",
     "@types/pg": "^8.20.0",
     "pinia": "^3.0.4",
     "typescript": "^5.0.0",
-    "vue": "^3.5.26"
+    "vue": "^3.5.26",
+    "@blueshed/delta": "^1.0.0"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@blueshed/delta": "^1.0.0"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/cli/index.ts

@@ -14,6 +14,13 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
 
 const args = process.argv.slice(2);
+
+// delta's Postgres commands (dzql is delta's Postgres step): sql, init, migrate
+if (["sql", "init", "migrate"].includes(args[0] ?? "")) {
+  const { main } = await import("../postgres/cli.ts");
+  await main(args);
+  process.exit(0);
+}
 let command = args[0];
 let input = args[1];
 let outputDir = "dist"; // Default output directory

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 and any other to the framework's
+ * (`_framework`). The order is the framework's: 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 to the framework's. */
+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 ${name}_framework(p_collection_key, p_id);
+  END CASE;`
+    : `  RETURN ${name}_framework(p_collection_key, p_id);`;
+  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 the dispatch to the framework's for any other. */
+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,144 @@
+/**
+ * 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 compiled
+ *   document to its own, any other to the framework
+ *   (`_delta_write_columns_framework`).
+ * - `_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 framework's (`_delta_assert_fields_framework`).
+ */
+import type { ColumnDef, DocDef, ResolvedTable, Schema } from "@blueshed/delta/backend";
+import { lit, named, need } 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 RETURN _delta_write_columns_framework(p_def, p_coll, p_columns_def);
+  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): the framework's
+  PERFORM _delta_assert_fields_framework(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,72 @@
+/**
+ * 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>`). Any other document (registered by hand, or by another
+ * `generateSql`) is asked by the framework's (`_delta_holders_framework`), told
+ * which prefixes were asked already. SECURITY DEFINER, with the search path it
+ * was applied with and pg_temp last, as the framework's.
+ */
+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, any other by the framework's. */
+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")}`] : [];
+  });
+  const asked = `ARRAY[${docs.map((d) => lit(d.prefix)).join(", ")}]::text[]`;
+  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` : ""}  -- the documents not compiled here, as the framework asks them
+  IF EXISTS (SELECT 1 FROM _delta_docs WHERE (root_collection = p_coll OR p_coll = ANY(include)) AND NOT (prefix = ANY(${asked}))) THEN
+    v_names := v_names || _delta_holders_framework(p_coll, p_row, p_writer, ${asked});
+  END IF;
+  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,91 @@
+/**
+ * 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 compiled document to its function and any other
+ * (registered by hand, or by another `generateSql`) to the framework's
+ * (`_delta_doc_holds_framework`).
+ */
+import { q, type DocDef, type ResolvedTable, type Schema } from "@blueshed/delta/backend";
+import { lit, named, need, 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 RETURN _delta_doc_holds_framework(p_def, p_doc_name, p_coll, p_row);
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => holdsOf(schema, d)), dispatch, ""].join("\n\n");
+}