dzql 0.8.0 → 0.10.0

package/src/postgres/cli.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env bun
+/**
+ * dzql's Postgres commands, as delta's CLI had them: `dzql sql`, `dzql init`
+ * and `dzql migrate` (a postgres:// URL or a PGlite directory). Run through
+ * `dzql <command>` (src/cli/index.ts hands these three here).
+ */
+import { parseArgs } from "node:util";
+import { resolve, basename, join, dirname } from "node:path";
+import { mkdirSync, copyFileSync, existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { generateSql } from "./codegen";
+import { frameworkSqlFiles } from "./bootstrap";
+import { authJwtSqlFile } from "./auth-jwt-sql";
+import type { Schema, DocDef } from "./index";
+
+const PKG_VERSION = (() => {
+  try {
+    return String(JSON.parse(readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf8")).version ?? "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const USAGE =
+    `Usage:\n` +
+    `  dzql sql <module> [--out <file>] [--force] [--schema-export <name>] [--docs-export <name>]\n` +
+    `  dzql init <dir> [--with-auth] [--upgrade]\n` +
+    `  dzql migrate <database> [--app <name>] [--dir <migrations>] [--status] [--json]\n` +
+    `        <database>: a PGlite directory or a postgres:// URL; --dir defaults to ./migrations\n` +
+    `\n` +
+    `Exit codes: 0 done, 1 an error, 2 a bad argument.\n`;
+
+let json = process.argv.includes("--json");
+
+const print = (result: unknown) => process.stdout.write(JSON.stringify(result ?? null, null, json ? undefined : 2) + "\n");
+
+function fail(err: unknown, exit = 1): never {
+  const error = { code: 0, message: err instanceof Error ? err.message : String(err) };
+  process.stderr.write((json ? JSON.stringify({ error }) : `dzql: ${error.message}`) + "\n");
+  process.exit(exit);
+}
+
+function usageError(why: string, show = false): never {
+  if (show && !json) process.stderr.write(USAGE + "\n");
+  fail(why, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Header handling — identifies files written by dzql init (stamped with this
+// package's version) so upgrades can read them back and avoid clobbering
+// user-owned SQL, and a `diff -u` against a later `init --upgrade` shows what changed.
+// ---------------------------------------------------------------------------
+
+// a file `delta init` vendored (stamped @blueshed/delta) is older than any of dzql's: always upgraded
+const HEADER_RE = /^-- @blueshed\/(delta|dzql) ([a-z0-9-]+) v(\d+\.\d+\.\d+)/;
+
+function readHeader(path: string): { pkg: string; kind: string; version: string } | null {
+  if (!existsSync(path)) return null;
+  const first = readFileSync(path, "utf8").split("\n", 1)[0] ?? "";
+  const m = first.match(HEADER_RE);
+  return m ? { pkg: m[1]!, kind: m[2]!, version: m[3]! } : null;
+}
+
+function writeWithHeader(src: string, dest: string, kind: "framework" | "auth-jwt"): void {
+  const header =
+    `-- @blueshed/dzql ${kind} v${PKG_VERSION}\n` +
+    `-- Vendored by 'dzql init'. Safe to read; prefer 'dzql init --upgrade' over hand edits.\n\n`;
+  writeFileSync(dest, header + readFileSync(src, "utf8"));
+}
+
+/**
+ * Back up `dest` to `dest + ".bak"` without destroying a pre-existing backup.
+ * If `dest.bak` already exists, fall back to `.bak.1`, `.bak.2`, … so an
+ * earlier backup the user may still need is preserved. Returns the path the
+ * backup was written to.
+ */
+function backupFile(dest: string): string {
+  let bak = dest + ".bak";
+  if (existsSync(bak)) {
+    let n = 1;
+    while (existsSync(`${dest}.bak.${n}`)) n++;
+    bak = `${dest}.bak.${n}`;
+    process.stderr.write(
+      `Note: ${basename(dest)}.bak already exists; backing up to ${basename(bak)} instead.\n`,
+    );
+  }
+  copyFileSync(dest, bak);
+  return bak;
+}
+
+// ---------------------------------------------------------------------------
+// dzql sql
+// ---------------------------------------------------------------------------
+
+// Stable substring of the codegen header (see codegen.ts:
+// "GENERATED FROM types.ts — DO NOT EDIT"). Matching on the leading words
+// avoids depending on the em-dash byte sequence.
+const GENERATED_MARKER = "GENERATED FROM";
+
+async function cmdSql(modulePath: string | undefined, values: Record<string, unknown>) {
+  if (!modulePath) usageError("sql takes a <module>", true);
+
+  const abs = resolve(process.cwd(), modulePath);
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(abs);
+  } catch (err) {
+    // Bun surfaces a `ResolveMessage` whose `.message` is a single useful line
+    // (e.g. "Cannot find module '…'") but is fronted by the class-name prefix;
+    // strip it to a clean one-liner instead of dumping the raw object/stack.
+    const raw =
+      err instanceof Error ? err.message.split("\n", 1)[0] : String(err);
+    const reason = raw.replace(/^(ResolveMessage|BuildMessage|Error):\s*/, "");
+    process.stderr.write(`Cannot load module "${modulePath}": ${reason}\n`);
+    process.exit(2);
+  }
+
+  const schemaExport = values["schema-export"] as string;
+  const docsExport = values["docs-export"] as string;
+  const schema = mod[schemaExport] as Schema | undefined;
+  const docs = mod[docsExport] as DocDef[] | undefined;
+
+  if (!schema || typeof schema !== "object" || !("tables" in schema)) {
+    process.stderr.write(
+      `Module at ${modulePath} does not export a Schema as \`${schemaExport}\`.\n` +
+      `Export one with: export const ${schemaExport} = defineSchema({ ... });\n`,
+    );
+    process.exit(2);
+  }
+  if (!Array.isArray(docs)) {
+    process.stderr.write(
+      `Module at ${modulePath} does not export a DocDef[] as \`${docsExport}\`.\n` +
+      `Export one with: export const ${docsExport} = [defineDoc(...), ...];\n`,
+    );
+    process.exit(2);
+  }
+
+  const sql = generateSql(schema, docs);
+  const out = values.out as string | undefined;
+  const force = !!values.force;
+
+  if (out) {
+    const absOut = resolve(out);
+    // Guard: never silently clobber a file we didn't generate. A previously
+    // generated file carries the codegen header marker and is safe to replace;
+    // anything else needs --force.
+    if (existsSync(absOut) && !force) {
+      const existing = readFileSync(absOut, "utf8");
+      if (!existing.includes(GENERATED_MARKER)) {
+        process.stderr.write(
+          `Refusing to overwrite ${out}: it has no generated-file header ` +
+          `(not produced by 'dzql sql').\n` +
+          `Pass --force to overwrite it anyway.\n`,
+        );
+        process.exit(3);
+      }
+      // It's a previously generated file — back it up before replacing.
+      backupFile(absOut);
+    }
+    mkdirSync(dirname(absOut), { recursive: true });
+    await Bun.write(out, sql);
+    process.stderr.write(`Wrote ${out} (${sql.length} bytes)\n`);
+  } else {
+    process.stdout.write(sql);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// dzql init
+// ---------------------------------------------------------------------------
+
+function cmdInit(dir: string | undefined, values: Record<string, unknown>) {
+  if (!dir) usageError("init takes a <dir>", true);
+
+  const absDir = resolve(process.cwd(), dir);
+  mkdirSync(absDir, { recursive: true });
+
+  const upgrade = !!values.upgrade;
+  const plan: { src: string; dest: string; kind: "framework" | "auth-jwt" }[] =
+    frameworkSqlFiles().map((src) => ({ src, dest: join(absDir, basename(src)), kind: "framework" }));
+  if (values["with-auth"]) plan.push({ src: authJwtSqlFile(), dest: join(absDir, "002-users.sql"), kind: "auth-jwt" });
+
+  // On upgrade we refuse to clobber files that don't have our header or that
+  // point to a newer version than we ship. The user either wrote that file
+  // themselves or has downgraded the package.
+  if (upgrade) {
+    const conflicts: string[] = [];
+    for (const { dest } of plan) {
+      if (!existsSync(dest)) continue;
+      const hdr = readHeader(dest);
+      if (!hdr) conflicts.push(`${basename(dest)}: not stamped by dzql init (or delta init)`);
+      else if (hdr.pkg === "dzql" && compareVersion(hdr.version, PKG_VERSION) > 0) {
+        conflicts.push(`${basename(dest)}: has v${hdr.version}, package is v${PKG_VERSION}`);
+      }
+    }
+    if (conflicts.length) {
+      process.stderr.write(
+        `Refusing to upgrade:\n  ${conflicts.join("\n  ")}\n\n` +
+        `Resolve these manually (move or rename the offending files) and rerun.\n`,
+      );
+      process.exit(3);
+    }
+  }
+
+  const created: string[] = [];
+  const upgraded: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const { src, dest, kind } of plan) {
+    if (existsSync(dest)) {
+      const hdr = readHeader(dest);
+      if (!upgrade || (hdr?.pkg === "dzql" && hdr.version === PKG_VERSION)) {
+        unchanged.push(basename(dest));
+        continue;
+      }
+      const bak = backupFile(dest);
+      writeWithHeader(src, dest, kind);
+      upgraded.push(`${basename(dest)} (backup at ${basename(bak)})`);
+    } else {
+      writeWithHeader(src, dest, kind);
+      created.push(basename(dest));
+    }
+  }
+
+  const lines: string[] = [];
+  if (created.length) lines.push("Created:\n  " + created.join("\n  "));
+  if (upgraded.length) lines.push("Upgraded:\n  " + upgraded.join("\n  "));
+  if (unchanged.length) lines.push("Unchanged:\n  " + unchanged.join("\n  "));
+  process.stderr.write((lines.join("\n\n") || "Nothing to do.") + "\n");
+
+  if (created.length || upgraded.length) {
+    process.stderr.write(
+      `\nNext: regenerate your table SQL from types.ts:\n` +
+      `  bunx dzql sql ./types.ts --out ${dir}/003-tables.sql\n`,
+    );
+  }
+}
+
+function compareVersion(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// dzql migrate
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an app's migrations (`--dir`, default ./migrations, each `NNN-name.ts`
+ * exporting `up`; `--app` names the app when apps share the database) against
+ * its database, or with --status say which ran and which are pending. With no
+ * schema to ask, an app with nothing recorded is new only to a database with
+ * no table but delta's: the app's own start-up, given its schema, knows better.
+ * The database: a postgres:// URL or a PGlite directory that is there (a name
+ * mistyped makes no new database). A SQLite file is delta's own command.
+ */
+async function cmdMigrate(target: string | undefined, values: Record<string, unknown>) {
+  if (!target) usageError("migrate takes a <database>: a PGlite directory or a postgres:// URL", true);
+  const { setLogLevel } = await import("@blueshed/delta/logger");
+  setLogLevel(json ? "silent" : "warn");
+  const dir = resolve(process.cwd(), (values.dir as string | undefined) ?? "migrations");
+  const status = !!values.status;
+  const options = { app: (values.app as string | undefined) ?? "" };
+  const isUrl = /^postgres(ql)?:\/\//.test(target);
+  const path = resolve(process.cwd(), target);
+  if (!isUrl && (!existsSync(path) || !statSync(path).isDirectory())) usageError(`no PGlite database at ${target} (a SQLite file is delta's: bunx @blueshed/delta migrate)`);
+  if (!existsSync(dir)) usageError(`no migrations folder at ${dir} (--dir)`);
+
+  let answer: unknown;
+  const pg = await import("./migrate");
+  let pool: any;
+  if (isUrl) {
+    const { Pool } = await import("pg");
+    pool = new Pool({ connectionString: target });
+  } else {
+    const { openPglite } = await import("./pglite");
+    pool = await openPglite(path);
+  }
+  try {
+    const list = await pg.fromFolder(dir);
+    answer = status ? await pg.migrationStatus(pool, list, options) : await pg.migrate(pool, list, options);
+  } finally { await pool.end(); }
+  if (json) return print(answer);
+  if (status) {
+    const s = answer as import("@blueshed/delta/backend").MigrationStatus;
+    if (s.fresh) process.stdout.write("new database: migrate records every migration as run, and runs none\n");
+    for (const r of s.ran) process.stdout.write(`ran      ${r.id}  ${r.ran_at}\n`);
+    for (const id of s.pending) process.stdout.write(`pending  ${id}\n`);
+    for (const id of s.unknown) process.stdout.write(`unknown  ${id}  (ran here, not in ${dir})\n`);
+    return;
+  }
+  const r = answer as import("@blueshed/delta/backend").MigrateResult;
+  if (r.fresh) process.stdout.write("new database: every migration recorded as run, none run\n");
+  for (const id of r.ran) process.stdout.write(`ran      ${id}\n`);
+  if (!r.fresh && r.ran.length === 0) process.stdout.write("nothing to run\n");
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+export async function main(argv: string[]) {
+  let parsed;
+  try { parsed = parseArgs({
+    args: argv,
+    options: {
+      out: { type: "string", short: "o" },
+      force: { type: "boolean", default: false },
+      "schema-export": { type: "string", default: "schema" },
+      "docs-export": { type: "string", default: "docs" },
+      "with-auth": { type: "boolean", default: false },
+      upgrade: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      dir: { type: "string" },
+      app: { type: "string" },
+      status: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+    allowPositionals: true,
+    strict: true,
+  }); }
+  catch (err) { usageError((err as Error).message, true); }
+  const { values, positionals } = parsed;
+  json = !!values.json;
+  if (values.help) { process.stdout.write(USAGE); return; }
+  const [cmd, arg] = positionals;
+  switch (cmd) {
+    case "sql":     return cmdSql(arg, values);
+    case "init":    return cmdInit(arg, values);
+    case "migrate": return cmdMigrate(arg, values);
+    default:        usageError(cmd ? `no command ${cmd}` : "a command, please", true);
+  }
+}
+
+if (import.meta.main) main(process.argv.slice(2)).catch((err) => fail(err));

package/src/postgres/codegen.ts

@@ -14,7 +14,7 @@
  *
  * Drive it from your project's `types.ts`:
  *
- *   import { generateSql } from "@blueshed/delta/postgres";
+ *   import { generateSql } from "dzql/postgres";
  *   import { schema, docs } from "./types";
  *   await Bun.write("init_db/003-tables.sql", generateSql(schema, docs));
  *
@@ -26,6 +26,17 @@ import type { Schema, DocDef } from "./schema";
 import { lit, columnSqlType, sqlDefault, findCascadeOn } from "./sql";
 import { defaultForType, q } from "@blueshed/delta/backend";
 import { assertScopeKeys } from "@blueshed/delta/backend";
+import { compileOpens } from "../compile/opens";
+import { compileHolds } from "../compile/holds";
+import { compileInScope } from "../compile/scope";
+import { compileHolders } from "../compile/holders";
+import { compileResolve } from "../compile/resolve";
+import { compileRootThere } from "../compile/root";
+import { compileColumns } from "../compile/columns";
+import { compileRows } from "../compile/rows";
+import { compileCascades } from "../compile/cascades";
+import { compileLedger } from "../compile/ledger";
+import { compileTold } from "../compile/told";
 
 export interface GenerateSqlOptions {
   /** Header comment included at the top of the file. */
@@ -168,5 +179,7 @@ export function generateSql(
   }
   lines.push("");
 
+  // each document opened by SQL compiled for it (dzql), which docTypeFromDef calls
+  lines.push("", compileOpens(schema, docs), "", compileHolds(schema, docs), "", compileInScope(schema, docs), "", compileTold(schema, docs), "", compileHolders(schema, docs), "", compileResolve(schema, docs), "", compileRootThere(schema, docs), "", compileColumns(schema, docs), "", compileRows(schema), "", compileCascades(schema), "", compileLedger(schema, docs));
   return lines.join("\n");
 }

package/src/postgres/index.ts

@@ -1,5 +1,5 @@
 /**
- * @blueshed/delta/postgres — Postgres backend for delta-doc.
+ * dzql/postgres — delta's Postgres backend, compiled from its definitions.
  *
  * Schema + stored functions + LISTEN dispatch. Tables are generated from
  * a TypeScript schema definition; all mutations go through stored functions
@@ -9,7 +9,7 @@
  *   import {
  *     defineSchema, defineDoc,
  *     createDocListener, docTypeFromDef,
- *   } from "@blueshed/delta/postgres";
+ *   } from "dzql/postgres";
  *
  * The stored functions are `src/sql/001*.sql`: `applyFramework(pool)` applies
  * them, or `bunx @blueshed/delta init <dir>` copies them for a migration tool

package/src/postgres/pglite.ts

@@ -4,7 +4,7 @@
  * The same stored functions, the same listener, the same documents as a
  * Postgres server, on PGlite (Postgres compiled to WASM): no database to run,
  * the data in a directory (or in memory). `openPglite()` answers the slice of
- * `pg`'s Pool delta uses, so everything in `@blueshed/delta/postgres` runs on
+ * `pg`'s Pool delta uses, so everything in `dzql/postgres` runs on
  * it unchanged:
  *
  *   const pool = await openPglite("./data");        // or openPglite() in memory

package/src/postgres/registry.ts

@@ -18,6 +18,7 @@ import type { DocDef } from "./schema";
 import { splitPath, type DeltaOp } from "@blueshed/delta/core";
 import { authless, ownerless, type DeltaAuth } from "@blueshed/delta/auth";
 import { assertOnePrefix } from "@blueshed/delta/backend";
+import { openAtFunction, openFunction } from "../compile/opens";
 
 /** Who is writing, for the ledger: the identity as the ledger has it, and the cursor undo walks. */
 export type Writer = { who: string | null; cursor: string | null; undoable?: boolean; undoes?: number | null };
@@ -214,6 +215,14 @@ export function docTypeFromDef<I = unknown>(
   // owns or shared with no auth module would guard nothing: the listener asks them only with one
   if (!auth && (opts?.owns || opts?.shared)) throw authless(def.prefix, "docTypeFromDef");
 
+  // its reads compiled for it (generateSql), or the framework's for a document registered by hand:
+  // asked until found, then remembered
+  let compiled = false;
+  const reads = async (): Promise<{ open: string; openAt: string }> => {
+    if (!compiled) compiled = (await pool.query("SELECT to_regprocedure($1) IS NOT NULL AS there", [`${openFunction(def.prefix)}(text)`])).rows[0].there;
+    return compiled ? { open: openFunction(def.prefix), openAt: openAtFunction(def.prefix) } : { open: "delta_open", openAt: "delta_open_at" };
+  };
+
   return {
     prefix: def.prefix,
     ...(opts?.owns ? { owns: opts.owns } : {}),
@@ -225,7 +234,7 @@ export function docTypeFromDef<I = unknown>(
     },
 
     async open(_ctx, docName, _msg, identity) {
-      const doc = await callAs(pool, "delta_open", [docName], auth, identity);
+      const doc = await callAs(pool, (await reads()).open, [docName], auth, identity);
       if (!doc) return null;
       const version = doc._version ?? 0;
       delete doc._version;
@@ -247,7 +256,7 @@ export function docTypeFromDef<I = unknown>(
     },
 
     async openAt(_ctx, docName, at, identity) {
-      return (await callAs(pool, "delta_open_at", [docName, at], auth, identity)) ?? null;
+      return (await callAs(pool, (await reads()).openAt, [docName, at], auth, identity)) ?? null;
     },
   };
 }

package/src/sql/001a-delta-meta.sql

@@ -136,7 +136,7 @@ $$;
 -- It used to be merged into the broadcast row, acked, and dropped (or cast) by
 -- jsonb_populate_record: stored otherwise than told. id, the parent key and
 -- the temporal columns are the row's own.
-CREATE OR REPLACE FUNCTION _delta_assert_fields(
+CREATE OR REPLACE FUNCTION _delta_assert_fields_framework(
   p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB
 ) RETURNS void LANGUAGE plpgsql IMMUTABLE AS $$
 DECLARE
@@ -178,6 +178,13 @@ BEGIN
 END;
 $$;
 
+-- The checks every write asks: the framework's, until dzql's compiler
+-- (`compileColumns`) replaces this with one that checks each column set it
+-- compiled by its own statements, and any other by the framework's.
+CREATE OR REPLACE FUNCTION _delta_assert_fields(
+  p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB
+) RETURNS void LANGUAGE sql IMMUTABLE AS $$ SELECT _delta_assert_fields_framework(p_collection, p_columns, p_parent_fk, p_value); $$;
+
 -- Pick the source relation for a collection.
 --   temporal + no timestamp → current_<table> view
 --   temporal + timestamp    → base <table> (caller filters with _delta_temporal_where)

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

@@ -51,7 +51,7 @@ $$ LANGUAGE sql STABLE;
 -- how the fan-out reads a name opened before a rule refused it (_delta_doc_holds).
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
+CREATE OR REPLACE FUNCTION _delta_resolve_scope_framework(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
 RETURNS JSONB AS $$
 DECLARE
   v_doc_id    TEXT;
@@ -285,6 +285,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- The resolver every caller asks: the framework's, until dzql's compiler
+-- (`compileResolve`) replaces it with one sending each document it compiled
+-- to its own.
+CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT, p_refuse BOOLEAN)
+RETURNS JSONB LANGUAGE sql STABLE AS $$ SELECT _delta_resolve_scope_framework(p_def, p_doc_name, p_refuse); $$;
+
 -- The resolver as every caller but the fan-out asks it: a value refused is raised.
 CREATE OR REPLACE FUNCTION _delta_resolve_scope(p_def _delta_docs, p_doc_name TEXT)
 RETURNS JSONB LANGUAGE sql STABLE AS $$
@@ -323,7 +329,7 @@ $$;
 -- so the gate can't be used to probe for ids.
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_row_in_scope(
+CREATE OR REPLACE FUNCTION _delta_row_in_scope_framework(
   p_def            _delta_docs,
   p_doc_name       TEXT,
   p_collection_key TEXT,
@@ -413,6 +419,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- _delta_row_in_scope: as the framework reads a definition (above), until dzql's generateSql
+-- compiles the app's documents: it then sends each to its own dzql_in_scope__<prefix>, and any
+-- other (registered by hand, or by another generateSql) here.
+CREATE OR REPLACE FUNCTION _delta_row_in_scope(p_def _delta_docs, p_doc_name TEXT, p_collection_key TEXT, p_id BIGINT)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_row_in_scope_framework(p_def, p_doc_name, p_collection_key, p_id); $$;
+
 -- ---------------------------------------------------------------------------
 -- Who holds a row: the fan-out (todo #28)
 --
@@ -459,7 +471,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- _delta_doc_holds: does the document `p_doc_name` (of `p_def`) hold `p_row`
 -- of `p_coll`? Judged on the row's values, so a row as it was before a write
 -- is judged as well as one as it is after -- the same rule delta_open reads by.
-CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+CREATE OR REPLACE FUNCTION _delta_doc_holds_framework(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
 RETURNS BOOLEAN AS $$
 DECLARE
   v_scope JSONB;
@@ -503,6 +515,12 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql STABLE;
 
+-- _delta_doc_holds: as the framework reads a definition (above), until dzql's generateSql
+-- compiles the app's documents: it then sends each to its own dzql_holds__<prefix>, and any
+-- other (registered by hand, or by another generateSql) here.
+CREATE OR REPLACE FUNCTION _delta_doc_holds(p_def _delta_docs, p_doc_name TEXT, p_coll TEXT, p_row JSONB)
+RETURNS BOOLEAN LANGUAGE sql STABLE AS $$ SELECT _delta_doc_holds_framework(p_def, p_doc_name, p_coll, p_row); $$;
+
 -- _delta_holders: the documents that hold `p_row` of `p_coll` -- every one
 -- open now (a name in _delta_held, todo #73), and the writer's own `p_writer`.
 -- A single-mode document of an unscoped definition is found by its name,
@@ -527,7 +545,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- that applied the framework, owning the tables without FORCE ROW LEVEL
 -- SECURITY, or with BYPASSRLS; applied as the app's own role, it sees what
 -- the writer sees, as before.
-CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+CREATE OR REPLACE FUNCTION _delta_holders_framework(p_coll TEXT, p_row JSONB, p_writer TEXT, p_skip TEXT[])
 RETURNS TEXT[] AS $$
 DECLARE
   v_def   _delta_docs;
@@ -547,7 +565,7 @@ BEGIN
 
   FOR v_def IN
     SELECT * FROM _delta_docs
-     WHERE root_collection = p_coll OR p_coll = ANY(include)
+     WHERE (root_collection = p_coll OR p_coll = ANY(include)) AND NOT (prefix = ANY(p_skip))
   LOOP
     v_all := v_def.scope <> '{}'::jsonb
              OR (p_coll IS DISTINCT FROM v_def.root_collection AND v_coll.parent_collection IS NULL);
@@ -572,6 +590,15 @@ END;
 $$ LANGUAGE plpgsql VOLATILE SECURITY DEFINER;
 -- the search path it was applied with, and pg_temp last: a caller's temporary
 -- tables never stand in for delta's own (pg_temp is searched first unless named)
+DO $$ BEGIN
+  EXECUTE format('ALTER FUNCTION _delta_holders_framework(TEXT, JSONB, TEXT, TEXT[]) SET search_path = %s, pg_temp', COALESCE(NULLIF(current_setting('search_path'), ''), 'public'));
+END $$;
+
+-- `p_skip`: the prefixes asked already, by the compiled `_delta_holders`
+-- (dzql's `compileHolders`), which replaces this one: each document it
+-- compiled asked by its own lookups, the rest by the framework's.
+CREATE OR REPLACE FUNCTION _delta_holders(p_coll TEXT, p_row JSONB, p_writer TEXT)
+RETURNS TEXT[] LANGUAGE sql VOLATILE SECURITY DEFINER AS $$ SELECT _delta_holders_framework(p_coll, p_row, p_writer, ARRAY[]::text[]); $$;
 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/sql/001c-delta-read.sql

@@ -212,8 +212,7 @@ BEGIN
   END IF;
   SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = p_def.root_collection;
   IF NOT FOUND THEN RETURN; END IF;
-  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', _delta_source_view(v_coll.table_name, v_coll.temporal))
-    INTO v_exists USING p_id;
+  v_exists := _delta_row_there(p_def.root_collection, p_id);
   IF v_exists THEN RETURN; END IF;
   -- Not there, as the writer reads it: made under the add rule (todo #71) -- an
   -- id the serial has handed out is taken, whether a row RLS hides holds it or
@@ -225,7 +224,7 @@ BEGIN
   END IF;
   v_row := _delta_implied_root(p_def, p_id);
   IF v_coll.temporal THEN v_row := v_row || jsonb_build_object('valid_from', p_ts, 'valid_to', NULL); END IF;
-  EXECUTE _delta_insert_sql(v_coll.table_name, v_row) USING v_row;
+  PERFORM _delta_row_add(p_def.root_collection, v_coll.table_name, v_row);
 END;
 $$ LANGUAGE plpgsql;
 
@@ -235,17 +234,12 @@ DECLARE
   v_doc    JSONB := COALESCE(_delta_open(p_doc_name, TRUE), '{}'::jsonb);
   v_def    _delta_docs := _delta_find_doc(p_doc_name);
   v_scope  JSONB;
-  v_coll   RECORD;
-  v_exists BOOLEAN;
 BEGIN
   IF NOT COALESCE(v_def.implied, FALSE) THEN RETURN v_doc; END IF;
   v_scope := _delta_resolve_scope(v_def, p_doc_name);
   IF (v_scope->>'mode') <> 'single' THEN RETURN v_doc; END IF;
-  SELECT * INTO v_coll FROM _delta_collections WHERE collection_key = v_def.root_collection;
-  IF NOT FOUND THEN RETURN v_doc; END IF;
-  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %I WHERE id = $1)', _delta_source_view(v_coll.table_name, v_coll.temporal))
-    INTO v_exists USING (v_scope->'values'->>'id')::BIGINT;
-  IF v_exists THEN RETURN v_doc; END IF;
+  -- (its root collection is there: _delta_open raised otherwise)
+  IF _delta_row_there(v_def.root_collection, (v_scope->'values'->>'id')::BIGINT) THEN RETURN v_doc; END IF;
   RETURN v_doc || jsonb_build_object(v_def.root_collection, 'null'::jsonb);
 END;
 $$ LANGUAGE plpgsql;
@@ -351,7 +345,7 @@ $$ LANGUAGE plpgsql STABLE;
 -- whole: what the ledger's inverse and a walk's guard read.
 -- ---------------------------------------------------------------------------
 
-CREATE OR REPLACE FUNCTION _delta_open(p_doc_name TEXT, p_whole BOOLEAN)
+CREATE OR REPLACE FUNCTION _delta_open_framework(p_doc_name TEXT, p_whole BOOLEAN)
 RETURNS JSONB AS $$
 DECLARE
   v_def       _delta_docs;
@@ -445,6 +439,11 @@ BEGIN
 END;
 $$ LANGUAGE plpgsql;
 
+-- the framework's, until dzql's compiler (`compileLedger`) sends each document
+-- it compiled to its own open, shown or whole
+CREATE OR REPLACE FUNCTION _delta_open(p_doc_name TEXT, p_whole BOOLEAN)
+RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_open_framework(p_doc_name, p_whole); $$;
+
 CREATE OR REPLACE FUNCTION delta_open(p_doc_name TEXT)
 RETURNS JSONB LANGUAGE sql AS $$ SELECT _delta_open(p_doc_name, FALSE); $$;