dzql 0.9.0 → 0.11.0

package/src/compile/scope.ts

@@ -0,0 +1,88 @@
+/**
+ * Compiled write scope: may a document write a row? "You may write what you
+ * may read": every row-addressed op in a write is asked first (`delta_apply`,
+ * `_delta_row_in_scope`), and a row it may not read is answered as one that is
+ * not there.
+ *
+ * `compileInScope(schema, docs)` writes `dzql_in_scope__<slug>(name,
+ * collection, id)` for each document, answering what the framework's
+ * `_delta_row_in_scope` answers, from its definition: a list document holds
+ * its included collections whole and its root rows by the name's conditions;
+ * a single document holds a row whose parent chain, walked up through the
+ * tables as they stand, reaches its root, which meets the rest of its name's
+ * scope. And `_delta_row_in_scope` itself, which sends each document to its
+ * own and refuses a name of none (`no doc def for`: the framework that read the rest
+ * retired, todo #26).
+ */
+import { q, type DocDef, type Schema } from "@blueshed/delta/backend";
+import { lit, named, need, noDoc, scopeOf, currentOnly } from "./opens";
+
+/** A document's write-scope function: `dzql_in_scope__<slug>`. */
+export const inScopeFunction = (prefix: string): string => named("in_scope", prefix);
+
+
+/** One document's write-scope function. */
+function inScopeOf(schema: Schema, doc: DocDef): string {
+  const root = need(schema, doc, doc.root);
+  const scope = scopeOf(schema, doc);   // a value its columns cannot take: refused, as the framework's resolver refuses it
+  const conds = scope.conds ? ` AND ${scope.conds}` : "";
+  // the root row of a single document: its id, and (where the name scopes more than the id) the rest of its scope
+  const others = Object.keys(doc.scope ?? {}).some((k) => k !== "id");
+  const rootMeets = (id: string) => others
+    ? `COALESCE(${id} = v_id, FALSE) AND EXISTS (SELECT 1 FROM ${q(root.name)} t WHERE t.id = v_id${currentOnly(root, "t")}${conds})`
+    : `COALESCE(${id} = v_id, FALSE)`;
+  const included = new Set(doc.include);
+
+  const singles = Object.entries(schema.tables).map(([coll, table]) => {
+    if (coll === doc.root) return `      WHEN ${lit(coll)} THEN RETURN ${rootMeets("p_id")};`;
+    // unparented: held whole where included; else it ends a chain short of the root
+    if (!table.parent) return `      WHEN ${lit(coll)} THEN RETURN ${included.has(coll) ? "TRUE" : "FALSE"};`;
+    let id = "p_id";
+    let t = table;
+    for (let depth = 0; depth < 32; depth++) {
+      id = `(SELECT x.${q(t.parent!.fkColumn)} FROM ${q(t.name)} x WHERE x.id = ${id}${currentOnly(t, "x")})`;
+      const parentKey = t.parent!.collection;
+      if (parentKey === doc.root) return `      WHEN ${lit(coll)} THEN RETURN ${rootMeets(id)};`;
+      const parent = schema.tables[parentKey];
+      if (!parent?.parent) return `      WHEN ${lit(coll)} THEN RETURN FALSE;`;   // the chain ends short of the root
+      t = parent;
+    }
+    return `      WHEN ${lit(coll)} THEN RETURN FALSE;`;
+  });
+
+  return `CREATE OR REPLACE FUNCTION ${inScopeFunction(doc.prefix)}(p_name TEXT, p_coll TEXT, p_id BIGINT)
+RETURNS BOOLEAN AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  IF p_id IS NULL THEN RETURN FALSE; END IF;
+  ${scope.body}
+  IF NOT v_single THEN
+    -- a list holds its included collections whole; its root rows by the name's conditions
+    IF p_coll IS DISTINCT FROM ${lit(doc.root)} THEN RETURN TRUE; END IF;
+    RETURN EXISTS (SELECT 1 FROM ${q(root.name)} t WHERE t.id = p_id${currentOnly(root, "t")}${conds});
+  END IF;
+  CASE p_coll
+${singles.join("\n")}
+    ELSE RETURN FALSE;
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+}
+
+/** The SQL that answers a write's scope for each of `docs`: a function per document, and `_delta_row_in_scope` sending each to its own. */
+export function compileInScope(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `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 AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${inScopeFunction(d.prefix)}(p_doc_name, p_collection_key, p_id);`).join("\n")}
+    ELSE ${noDoc("p_doc_name")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => inScopeOf(schema, d)), dispatch, ""].join("\n\n");
+}

package/src/compile/told.ts

@@ -0,0 +1,95 @@
+/**
+ * Compiled telling: what a document is told of a write. Asked by `_delta_tell`
+ * of the writer and of every document that held a row the write touched, or
+ * holds it now, with the write's touches and their holders.
+ *
+ * `compileTold(schema, docs)` writes `dzql_told__<slug>(name, rows)` for each
+ * document, answering what the framework's `_delta_told` answers, from its
+ * definition: whether the name makes it one row (`scopeOf`), its root, the
+ * columns it shows of each collection it names them for (`columns`, the row's
+ * id and parent key with them), and the empty root an implied one opens with
+ * when its root leaves. And `_delta_told` itself, which sends each document to
+ * its own and refuses a name of none (`no doc def for`: the framework that read the rest
+ * retired, todo #26).
+ */
+import type { DocDef, Schema } from "@blueshed/delta/backend";
+import { lit, named, need, noDoc, scopeOf } from "./opens";
+
+/** A document's telling function: `dzql_told__<slug>`. */
+export const toldFunction = (prefix: string): string => named("told", prefix);
+
+/**
+ * A row (SQL `row`) of collection (SQL `coll`) as the document shows it, as
+ * `_delta_show` does: where it names the collection's columns, those, the id
+ * and the parent key; else whole.
+ */
+function shown(schema: Schema, doc: DocDef, coll: string, row: string): string {
+  const named = Object.entries(doc.columns ?? {});
+  if (named.length === 0) return row;
+  const branches = named.map(([c, cols]) => {
+    const fk = schema.tables[c]?.parent?.fkColumn;
+    const keep = [...new Set(["id", ...(fk ? [fk] : []), ...cols])].map(lit).join(", ");
+    return `WHEN ${lit(c)} THEN COALESCE((SELECT jsonb_object_agg(f, v) FROM jsonb_each(${row}) AS e(f, v) WHERE f IN (${keep})), '{}'::jsonb)`;
+  });
+  return `(CASE WHEN jsonb_typeof(${row}) IS DISTINCT FROM 'object' THEN ${row} ELSE CASE ${coll} ${branches.join(" ")} ELSE ${row} END END)`;
+}
+
+/** One document's telling function. */
+function toldOf(schema: Schema, doc: DocDef): string {
+  need(schema, doc, doc.root);
+  const scope = scopeOf(schema, doc);   // a name its columns cannot take: refused, as the framework's resolver refuses it
+  const after = shown(schema, doc, "v_t->>'coll'", "v_t->'after'");
+  const gone = doc.implied
+    ? shown(schema, doc, "v_t->>'coll'", `_delta_implied_root((SELECT d FROM _delta_docs d WHERE d.prefix = ${lit(doc.prefix)}), (v_t->>'id')::BIGINT)`)
+    : "'null'::jsonb";
+  return `CREATE OR REPLACE FUNCTION ${toldFunction(doc.prefix)}(p_name TEXT, p_rows JSONB)
+RETURNS JSONB AS $$
+DECLARE
+  p_at     TIMESTAMPTZ;
+  v_single BOOLEAN;
+  v_id     BIGINT;
+  v_t      JSONB;
+  v_told   JSONB := '[]'::jsonb;
+  v_was    BOOLEAN;
+  v_is     BOOLEAN;
+  v_root   BOOLEAN;
+  v_path   TEXT;
+  ${scope.declare.join("\n  ")}
+BEGIN
+  ${scope.body}
+  FOR v_t IN SELECT jsonb_array_elements(p_rows) LOOP
+    v_was := (v_t->'before') ? p_name;
+    v_is  := (v_t->'holders') ? p_name;
+    CONTINUE WHEN NOT v_was AND NOT v_is;
+    CONTINUE WHEN v_was AND v_is AND (v_t ? 'carried');   -- carried along, and its either way: unchanged for it
+    v_root := v_single AND (v_t->>'coll') = ${lit(doc.root)};
+    v_path := CASE WHEN v_root THEN _delta_build_path(v_t->>'coll') ELSE _delta_build_path(v_t->>'coll', v_t->>'id') END;
+    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(${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', ${after}));
+    ELSIF v_root THEN   -- gone: ${doc.implied ? "the empty root it then opens with" : "null"}
+      v_told := v_told || jsonb_build_array(jsonb_build_object('op', 'replace', 'path', v_path, 'value', ${gone}));
+    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;`;
+}
+
+/** The SQL that answers what each of `docs` is told of a write: a function per document, and `_delta_told` sending each to its own. */
+export function compileTold(schema: Schema, docs: DocDef[]): string {
+  const dispatch = `CREATE OR REPLACE FUNCTION _delta_told(p_def _delta_docs, p_target TEXT, p_rows JSONB)
+RETURNS JSONB AS $$
+BEGIN
+  CASE p_def.prefix
+${docs.map((d) => `    WHEN ${lit(d.prefix)} THEN RETURN ${toldFunction(d.prefix)}(p_target, p_rows);`).join("\n")}
+    ELSE ${noDoc("p_target")}
+  END CASE;
+END;
+$$ LANGUAGE plpgsql STABLE;`;
+  return [...docs.map((d) => toldOf(schema, d)), dispatch, ""].join("\n\n");
+}

package/src/postgres/auth-jwt-sql.ts

@@ -3,7 +3,7 @@
  *
  * These are split out of `auth-jwt.ts` so the `delta init` CLI (which only
  * needs the file path) can run in projects that haven't installed jose.
- * Consumers of the `@blueshed/delta/auth-jwt` subpath still get these via
+ * Consumers of the `dzql/auth-jwt` subpath still get these via
  * re-export from `auth-jwt.ts`.
  */
 import type { Pool } from "pg";

package/src/postgres/auth-jwt.ts

@@ -2,7 +2,7 @@
  * Auth-JWT — reference `DeltaAuth` implementation using JWTs (jose) and
  * Postgres stored functions for credential verification.
  *
- * Ship this as an opt-in subpath: `@blueshed/delta/auth-jwt`. Users who want
+ * Ship this as an opt-in subpath: `dzql/auth-jwt`. Users who want
  * a different auth scheme (sessions, OAuth, magic links, none) implement
  * their own `DeltaAuth` instead.
  *
@@ -13,7 +13,7 @@
  *
  * Both are overridable via the `loginSql` / `registerSql` options.
  *
- *   import { jwtAuth } from "@blueshed/delta/auth-jwt";
+ *   import { jwtAuth } from "dzql/auth-jwt";
  *
  *   const auth = jwtAuth({
  *     pool,

package/src/postgres/bootstrap.ts

@@ -4,7 +4,7 @@
  * consumer's `init_db/` directory.
  *
  *   import { Pool } from "pg";
- *   import { applyFramework } from "@blueshed/delta/postgres";
+ *   import { applyFramework } from "dzql/postgres";
  *
  *   const pool = new Pool({ connectionString: process.env.PG_URL });
  *   await applyFramework(pool);
@@ -23,7 +23,7 @@ const FRAMEWORK_SQL_DIR = join(import.meta.dir, "..", "sql");
 
 /** Absolute paths to the framework SQL files, in apply-order.
  *  Filters to `001*-*.sql` — siblings like `auth-jwt.sql` are applied
- *  separately (see `@blueshed/delta/auth-jwt` → `applyAuthJwtSchema`). */
+ *  separately (see `dzql/auth-jwt` → `applyAuthJwtSchema`). */
 export function frameworkSqlFiles(): string[] {
   return readdirSync(FRAMEWORK_SQL_DIR)
     .filter((f) => /^001[a-z]?-.+\.sql$/.test(f))

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));
  *
@@ -27,6 +27,17 @@ 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 { compileLookups } from "../compile/lookups";
+import { compileTold } from "../compile/told";
 
 export interface GenerateSqlOptions {
   /** Header comment included at the top of the file. */
@@ -170,6 +181,6 @@ export function generateSql(
   lines.push("");
 
   // each document opened by SQL compiled for it (dzql), which docTypeFromDef calls
-  lines.push("", compileOpens(schema, docs));
+  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), "", compileLookups(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/listener.ts

@@ -89,12 +89,15 @@ function errMsg(err: unknown): string {
  * entry that is not the cursor's next (409). And 40P01, a write that met another
  * at once and gave way to it (two adds of temporal ids in opposite orders wait
  * on each other's row locks, todo #16): nothing was written, and the same write
- * sent again goes through, or meets the rows the other made (409). Anything
- * else is the server's (500).
+ * sent again goes through, or meets the rows the other made (409). A document
+ * type that refuses with a wire code of its own (a number, 400 to 499: a
+ * read-only document's 403) is answered with it. Anything else is the
+ * server's (500).
  */
 const CODE_OF_SQLSTATE: Record<string, number> = { "22023": 400, "22P02": 400, "22007": 400, "22008": 400, "23502": 400, "25006": 403, P0002: 404, "23505": 409, "40001": 409, "40P01": 409 };
 function wireCode(err: unknown): number {
   const state = (err as { code?: unknown } | null)?.code;
+  if (typeof state === "number" && state >= 400 && state < 500) return state;
   return (typeof state === "string" && CODE_OF_SQLSTATE[state]) || 500;
 }
 
@@ -122,6 +125,15 @@ interface DocState {
 /** _delta_fetch_log (delta_fetch_ops' rows) caps each call at this many; a full page means there may be more. */
 const FETCH_PAGE = 1000;
 
+/**
+ * What a custom document hears of a log entry: each write once, as it was applied. The writer's
+ * entry carries it (`applied`) where the writer was told otherwise, and null where it was told the
+ * write as applied; each other told document's entry of the write carries none ([]). Told, a row
+ * that left a document is a remove, which is not a delete, and a row told to two documents would be
+ * heard twice (todo #44). An entry logged some other way carries null too: heard as told.
+ */
+const appliedOf = (row: any): DeltaOp[] => (row.applied ?? row.ops) as DeltaOp[];
+
 /**
  * How the listener reads a document's log. `_delta_fetch_log` (001e) gives each
  * entry with the write as applied, for custom documents (todo #44). Framework
@@ -250,7 +262,7 @@ export async function createDocListener<I = unknown>(
   // are recycled by the pool, and a stale listener would fire against this
   // closure's state (and spuriously trigger reconnect) on a future checkout.
   function detachListener(client: any) {
-    try { client.removeListener?.("notification", onNotification); } catch {}
+    try { client.removeListener?.("notification", heard); } catch {}
     if (errorHandler) {
       try { client.removeListener?.("error", errorHandler); } catch {}
     }
@@ -259,7 +271,7 @@ export async function createDocListener<I = unknown>(
   /** LISTEN on `client`, and keep this holder's lock on it. */
   async function setupListener(client: any): Promise<void> {
     await client.query("LISTEN delta_changes");
-    client.on("notification", onNotification);
+    client.on("notification", heard);
     errorHandler = (err: Error) => {
       log.error(`listener error: ${err.message}`);
       if (!destroyed) reconnect();
@@ -306,7 +318,7 @@ export async function createDocListener<I = unknown>(
       state.until = Number.MAX_SAFE_INTEGER;   // the notifications while away are gone: read to the end
       if (state.notifying) { state.pending = true; continue; }
       state.notifying = true;
-      try { await drainDoc(docName, state); }
+      try { await drainDoc(docName, state, true); }
       catch (err) { log.error(`resync ${docName}: ${errMsg(err)}`); }
       finally { state.notifying = false; }
     }
@@ -320,28 +332,38 @@ export async function createDocListener<I = unknown>(
     throw err;
   }
 
-  // Notification handler — fans out LISTEN/NOTIFY to WS subscribers, plus
-  // custom-doc cross-pollination when any predicate-based doc is registered.
+  // A document's own subscribers need only its own order, so each document drains on its own
+  // (onNotification), and none waits on another's. A custom document hears writes made through
+  // every document, so it is told them one after another, as Postgres delivers the notifications
+  // (in commit order): told from each document's drain, a slow read of one told it a later write,
+  // made through another, first.
+  let inCommitOrder: Promise<void> = Promise.resolve();
+  function heard(msg: any) {
+    void onNotification(msg);
+    if (custom.size > 0) inCommitOrder = inCommitOrder.then(() => hearCustom(msg));
+  }
+
+  /** The custom documents told the one write a notification announces: its document's entry at that version. */
+  async function hearCustom(msg: any) {
+    if (destroyed || msg.channel !== "delta_changes" || !msg.payload) return;
+    try {
+      const { doc: docName, v } = JSON.parse(msg.payload);
+      const rows = (await pool.query(fetchSql, [docName, v - 1])).rows.filter((row: any) => Number(row.version) === v);
+      if (auth && rows.length > 0) await custom.letGoWatching(rows.flatMap(appliedOf));
+      for (const row of rows) custom.tell(appliedOf(row));
+    } catch (err) {
+      log.error(`notify error (custom): ${errMsg(err)}`);
+    }
+  }
+
+  // Notification handler — fans out LISTEN/NOTIFY to the document's WS subscribers.
   async function onNotification(msg: any) {
     if (destroyed) return;
     if (msg.channel !== "delta_changes" || !msg.payload) return;
     try {
       const { doc: docName, v } = JSON.parse(msg.payload);
-      let state = tracked.get(docName);
-
-      // Even without direct subscribers, we still process notifications if any
-      // custom doc is registered — a watched collection's rows may need fan-out.
-      if (!state && custom.size === 0) return;
-      if (!state) {
-        // Initialize at v-1 so we fetch only the current notification's row.
-        // Custom docs loaded their initial state via `def.query` on open, so
-        // pre-existing ops are already reflected — replaying history would
-        // duplicate them. Same logic protects close-then-reopen.
-        state = { version: Math.max(0, v - 1), until: v, subscribers: new Set(), notifying: false, pending: false };
-        tracked.set(docName, state);
-      }
-
-      if (v <= state.version) return;
+      const state = tracked.get(docName);
+      if (!state || v <= state.version) return;
       state.until = Math.max(state.until, v);
       if (state.notifying) {
         // A fetch is already running for this doc. Coalesce instead of dropping:
@@ -364,8 +386,9 @@ export async function createDocListener<I = unknown>(
   // Drain a doc's ops to its subscribers. Loops while a full page comes back
   // (a backlog larger than the fetch's LIMIT) and re-runs if another
   // notification arrived mid-drain (the coalesced `pending` flag). Caller owns
-  // the `notifying` guard.
-  async function drainDoc(docName: string, state: DocState) {
+  // the `notifying` guard. After a reconnect (`resync`) the custom documents
+  // are told what it reads too: the notifications while away are gone.
+  async function drainDoc(docName: string, state: DocState, resync = false) {
     do {
       state.pending = false;
       let more = true;
@@ -374,11 +397,10 @@ export async function createDocListener<I = unknown>(
         // only what a notification has announced (`until`): the rest is heard with its own
         const rows = page.filter((row: any) => Number(row.version) <= state.until);
         more = page.length >= FETCH_PAGE && rows.length === page.length;
-        // Told to those who may still hear it (todo #17): the document's own
-        // subscribers, and the custom documents' that watch what it changed.
+        // Told to those who may still hear it (todo #17): the document's own subscribers
         if (auth && rows.length > 0) {
           await custom.letGo(docName, state.subscribers, ownsOf(docName));
-          await custom.letGoWatching(rows.flatMap((row: any) => (row.applied ?? row.ops) as DeltaOp[]));
+          if (resync) await custom.letGoWatching(rows.flatMap(appliedOf));
         }
         for (const row of rows) {
           if (state.subscribers.size > 0) {
@@ -390,14 +412,7 @@ export async function createDocListener<I = unknown>(
             ws.publish(docName, { doc: docName, ops: shownOps(resolveDoc(docName)?.type.def, row.ops), v: Number(row.version) });
           }
           state.version = Number(row.version);
-          // A custom document hears each write once, as it was applied: the
-          // writer's entry carries it (`applied`) where the writer was told
-          // otherwise, and null where it was told the write as applied; each
-          // other told document's entry of the write carries none ([]). Told,
-          // a row that left a document is a remove, which is not a delete, and
-          // a row told to two documents would be heard twice (todo #44). An
-          // entry logged some other way carries null too: heard as told.
-          custom.tell((row.applied ?? row.ops) as DeltaOp[]);
+          if (resync) custom.tell(appliedOf(row));
         }
       }
     } while (state.pending);

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
@@ -137,6 +137,9 @@ export async function openPglite(dir?: string): Promise<Pool> {
   } catch {
     throw new Error("[delta/pglite] @electric-sql/pglite is not installed -- bun add @electric-sql/pglite");
   }
-  const db: PGliteish = dir ? await PGlite.create(dir) : await PGlite.create();
+  // pgcrypto, which dzql/auth-jwt hashes passwords with: PGlite has an extension only when it is
+  // given one at start (loaded when a database creates it)
+  const { pgcrypto } = await import("@electric-sql/pglite/contrib/pgcrypto");
+  const db: PGliteish = await PGlite.create(dir, { extensions: { pgcrypto } });
   return pglitePool(db);
 }

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

@@ -30,6 +30,49 @@ ALTER TABLE _delta_docs ADD COLUMN IF NOT EXISTS implied BOOLEAN NOT NULL DEFAUL
 -- collection not named, whole. It is opened, told and written by those alone.
 ALTER TABLE _delta_docs ADD COLUMN IF NOT EXISTS held JSONB NOT NULL DEFAULT '{}';
 
+-- The framework that read the definitions at run time retired (todo #26): each
+-- document and collection is compiled by generateSql (dzql/compile). Dropped
+-- where an earlier version made them.
+DROP FUNCTION IF EXISTS _delta_collection_framework(text);
+DROP FUNCTION IF EXISTS _delta_assert_fields_framework(text, jsonb, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_temporal_where(timestamptz, text);
+DROP FUNCTION IF EXISTS _delta_find_doc_framework(text);
+DROP FUNCTION IF EXISTS _delta_resolve_scope_framework(_delta_docs, text, boolean);
+DROP FUNCTION IF EXISTS _delta_row_in_scope_framework(_delta_docs, text, text, bigint);
+DROP FUNCTION IF EXISTS _delta_chain_root(text, jsonb, text);
+DROP FUNCTION IF EXISTS _delta_doc_holds_framework(_delta_docs, text, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_holders_framework(text, jsonb, text, text[]);
+DROP FUNCTION IF EXISTS _delta_load_collection(text, text, bigint, timestamptz);
+DROP FUNCTION IF EXISTS _delta_load_collection_all(text, timestamptz);
+DROP FUNCTION IF EXISTS _delta_read_list(_delta_docs, text, timestamptz);
+DROP FUNCTION IF EXISTS _delta_show_doc(_delta_docs, jsonb, boolean);
+DROP FUNCTION IF EXISTS _delta_open_framework(text, boolean);
+DROP FUNCTION IF EXISTS _delta_serial_past_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_serial_new_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_cascade_remove_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_cascade_rows_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_hanging_rows_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_told_framework(_delta_docs, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_row_there_framework(text, bigint);
+DROP FUNCTION IF EXISTS _delta_held_columns(_delta_docs, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_root_there_framework(_delta_docs, text, jsonb, text, bigint);
+DROP FUNCTION IF EXISTS _delta_write_columns_framework(_delta_docs, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_row_lock_framework(text, text, boolean, bigint);
+DROP FUNCTION IF EXISTS _delta_row_put_framework(text, text, boolean, bigint, jsonb, timestamptz);
+DROP FUNCTION IF EXISTS _delta_next_id_framework(text, text);
+DROP FUNCTION IF EXISTS _delta_row_clear_moment_framework(text, text, bigint, timestamptz);
+DROP FUNCTION IF EXISTS _delta_row_add_framework(text, text, jsonb);
+DROP FUNCTION IF EXISTS _delta_row_read_framework(text, text, bigint);
+DROP FUNCTION IF EXISTS _delta_open_at_framework(text, timestamptz);
+DROP FUNCTION IF EXISTS _delta_same_framework(text, text, jsonb, jsonb);
+DROP FUNCTION IF EXISTS _delta_row_standing_framework(text, bigint);
+
+-- _delta_collection: a collection's definition (NULL fields: there is none).
+-- generateSql writes each collection in (compileLookups); before it is applied,
+-- there is none.
+CREATE OR REPLACE FUNCTION _delta_collection(p_key TEXT)
+RETURNS _delta_collections LANGUAGE sql STABLE AS $$ SELECT NULL::_delta_collections; $$;
+
 CREATE TABLE IF NOT EXISTS _delta_versions (
   doc_name TEXT PRIMARY KEY,
   version  BIGINT NOT NULL DEFAULT 0
@@ -135,8 +178,10 @@ $$;
 -- not have, or gives a column a value not of its type (SQLSTATE 22023 → 400).
 -- 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(
+-- the temporal columns are the row's own. By the columns given (`p_columns`): a
+-- set the compiler did not write in (another version's, `delta.declared`; a
+-- walk's, as its entry was stored) is checked here.
+CREATE OR REPLACE FUNCTION _delta_assert_fields_declared(
   p_collection TEXT, p_columns JSONB, p_parent_fk TEXT, p_value JSONB
 ) RETURNS void LANGUAGE plpgsql IMMUTABLE AS $$
 DECLARE
@@ -178,9 +223,16 @@ BEGIN
 END;
 $$;
 
+-- The checks every write asks: generateSql (`compileColumns`) replaces this
+-- with one that checks each column set it compiled by its own statements, and
+-- any other by the columns given.
+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_declared(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)
+--   temporal + timestamp    → base <table> (the caller filters by its time)
 --   non-temporal            → base <table>
 CREATE OR REPLACE FUNCTION _delta_source_view(
   p_table_name TEXT, p_temporal BOOLEAN, p_at TIMESTAMPTZ DEFAULT NULL
@@ -190,15 +242,3 @@ CREATE OR REPLACE FUNCTION _delta_source_view(
     ELSE p_table_name
   END;
 $$;
-
--- Temporal WHERE fragment for embedding into format()-built dynamic SQL.
--- Inlines the timestamp as a %L literal so callers don't need extra param binding.
--- Aliases the row with `p_alias` (default `t`).
-CREATE OR REPLACE FUNCTION _delta_temporal_where(
-  p_at TIMESTAMPTZ, p_alias TEXT DEFAULT 't'
-) RETURNS text LANGUAGE sql IMMUTABLE AS $$
-  SELECT format(
-    '%s.valid_from <= %L AND (%s.valid_to IS NULL OR %s.valid_to > %L)',
-    p_alias, p_at, p_alias, p_alias, p_at
-  );
-$$;