dzql 0.6.37 → 0.8.0

package/src/postgres/migrate.ts

@@ -0,0 +1,143 @@
+/**
+ * Postgres's migrations (PGlite's too; `../migrate.ts` says the rules):
+ * `migrate` runs a list at start-up, before `applyFramework` and
+ * `applySql(pool, generateSql(…))`; the helpers are the changes people make
+ * most, each SQL that keeps delta's scaffolding in step (a temporal table's
+ * `current_<table>` view and its grants, the `idx_<table>_…` indexes, the
+ * `seq_<table>` serial, `_delta_collections`). Two processes starting at once
+ * take turns on an advisory lock, so each migration runs once.
+ */
+import type { Pool, PoolClient } from "pg";
+import { q } from "@blueshed/delta/backend";
+import { appOf, fenced, runMigrations, statusOf, type MigrateOptions, type MigrateResult, type Migration, type MigrationStatus, type Store } from "@blueshed/delta/backend";
+
+export { fromFolder, type Migration, type MigrateOptions, type MigrateResult, type MigrationStatus } from "@blueshed/delta/backend";
+
+/** What a helper runs its SQL on: the client `up` is given. */
+type Tx = Pick<PoolClient, "query">;
+
+/** The advisory lock's key: one per database, for delta's migrations. */
+const LOCK = "hashtext('delta_migrations')";
+
+const regclass = async (tx: Tx, name: string): Promise<boolean> =>
+  (await tx.query("SELECT to_regclass($1) IS NOT NULL AS there", [q(name)])).rows[0]?.there === true;
+
+function store(client: PoolClient, app: string, collections?: string): Store<PoolClient> {
+  return {
+    async lock() { await client.query(`SELECT pg_advisory_lock(${LOCK})`); },
+    async unlock() { await client.query(`SELECT pg_advisory_unlock(${LOCK})`); },
+    async exists() { return regclass(client, "delta_migrations"); },
+    async tables(names) {
+      const out = new Map<string, { columns: string[]; rows: boolean }>();
+      const { rows: found } = await client.query(
+        `SELECT table_name AS name, array_agg(column_name::text) AS columns FROM information_schema.columns
+          WHERE table_schema = current_schema() AND table_name IN (SELECT jsonb_array_elements_text($1::jsonb)) GROUP BY 1`, [JSON.stringify(names)]);
+      for (const t of found) {
+        const rows = (await client.query(`SELECT EXISTS (SELECT 1 FROM ${q(t.name)}) AS any`)).rows[0]?.any === true;
+        out.set(t.name, { columns: Array.isArray(t.columns) ? t.columns : String(t.columns).replace(/^\{|\}$/g, "").split(","), rows });
+      }
+      return out;
+    },
+    async hasAppTables() {
+      const { rows } = await client.query(
+        "SELECT count(*)::int AS n FROM pg_tables WHERE schemaname = current_schema() AND tablename !~ '^_?delta_'",
+      );
+      return rows[0]!.n > 0;
+    },
+    async create() { await client.query("CREATE TABLE IF NOT EXISTS delta_migrations (app TEXT NOT NULL, id TEXT NOT NULL, ran_at TEXT NOT NULL, PRIMARY KEY (app, id))"); },
+    async recorded() { return (await client.query("SELECT id, ran_at FROM delta_migrations WHERE app = $1 ORDER BY ran_at, id", [app])).rows; },
+    async transaction(fn) {
+      await client.query("BEGIN");
+      try {
+        const out = await fn(client);
+        await client.query("COMMIT");
+        return out;
+      } catch (err) {
+        await client.query("ROLLBACK");
+        throw err;
+      }
+    },
+    async has(tx, id) { return (await tx.query("SELECT 1 FROM delta_migrations WHERE app = $1 AND id = $2", [app, id])).rows.length > 0; },
+    async record(tx, id, at) { await tx.query("INSERT INTO delta_migrations (app, id, ran_at) VALUES ($1, $2, $3)", [app, id, at]); },
+    async fence(tx) {
+      if (!(await regclass(tx, "_delta_ledger"))) return;
+      if (collections === undefined) return void (await tx.query("UPDATE _delta_ledger SET undoable = FALSE WHERE undoable"));
+      // an entry is the app's when an op of it, or of its inverse, names one of the app's collections: /<coll>/...
+      await tx.query(`UPDATE _delta_ledger SET undoable = FALSE WHERE undoable AND EXISTS (
+        SELECT 1 FROM jsonb_array_elements(ops || inverse) AS o
+         WHERE split_part(o->>'path', '/', 2) IN (SELECT jsonb_array_elements_text($1::jsonb)))`, [collections]);
+    },
+  };
+}
+
+/** Runs `fn` on a client of its own, holding nothing after. */
+async function withClient<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try { return await fn(client); }
+  finally { client.release(); }
+}
+
+/**
+ * Runs each migration of the app's list not yet run here, in order, each in
+ * its own transaction on one client (`up(client)`). Call it at start-up, before
+ * `applyFramework` and the schema's `generateSql`; name the app and give its
+ * schema when apps share the database.
+ */
+export function migrate(pool: Pool, migrations: Migration<PoolClient>[], options: MigrateOptions = {}): Promise<MigrateResult> {
+  return withClient(pool, (client) => runMigrations(store(client, appOf(options), fenced(options)), migrations, options));
+}
+
+/** What of the app's has run here, what would run, and whether the app is new here; changes nothing. */
+export function migrationStatus(pool: Pool, migrations: Migration<PoolClient>[], options: MigrateOptions = {}): Promise<MigrationStatus> {
+  return withClient(pool, (client) => statusOf(store(client, appOf(options)), migrations, options));
+}
+
+// ---------------------------------------------------------------------------
+// Helpers: each one change, with delta's scaffolding kept in step. Each takes
+// the client `up` is given.
+// ---------------------------------------------------------------------------
+
+/** Renames a column, every version of every row with it, and in the table's `current_` view; its `idx_<table>_<from>` index goes by the new name. */
+export async function renameColumn(tx: Tx, table: string, from: string, to: string): Promise<void> {
+  await tx.query(`ALTER TABLE ${q(table)} RENAME COLUMN ${q(from)} TO ${q(to)}`);
+  if (await regclass(tx, `current_${table}`)) await tx.query(`ALTER VIEW ${q(`current_${table}`)} RENAME COLUMN ${q(from)} TO ${q(to)}`);
+  await tx.query(`ALTER INDEX IF EXISTS ${q(`idx_${table}_${from}`)} RENAME TO ${q(`idx_${table}_${to}`)}`);
+}
+
+/**
+ * Drops a column and what it held. A temporal table's `current_` view reads
+ * every column, so it is made again without it, with the grants it had. Move
+ * what must be kept first.
+ */
+export async function dropColumn(tx: Tx, table: string, column: string): Promise<void> {
+  const view = `current_${table}`;
+  if (!(await regclass(tx, view))) {
+    await tx.query(`ALTER TABLE ${q(table)} DROP COLUMN ${q(column)}`);
+    return;
+  }
+  const { rows: grants } = await tx.query(
+    `SELECT grantee, privilege_type FROM information_schema.role_table_grants
+      WHERE table_schema = current_schema() AND table_name = $1 AND grantee <> current_user`, [view]);
+  await tx.query(`DROP VIEW ${q(view)}`);
+  await tx.query(`ALTER TABLE ${q(table)} DROP COLUMN ${q(column)}`);
+  await tx.query(`CREATE VIEW ${q(view)} WITH (security_invoker = true) AS SELECT * FROM ${q(table)} WHERE valid_to IS NULL`);
+  for (const g of grants) await tx.query(`GRANT ${g.privilege_type} ON ${q(view)} TO ${g.grantee === "PUBLIC" ? "PUBLIC" : q(g.grantee)}`);
+}
+
+/**
+ * Renames a table, with its `current_<table>` view, its `idx_<table>_…`
+ * indexes and primary key, its `seq_<table>` serial (the next id follows on),
+ * and the name `_delta_collections` keeps for it.
+ */
+export async function renameTable(tx: Tx, from: string, to: string): Promise<void> {
+  await tx.query(`ALTER TABLE ${q(from)} RENAME TO ${q(to)}`);
+  await tx.query(`ALTER VIEW IF EXISTS ${q(`current_${from}`)} RENAME TO ${q(`current_${to}`)}`);
+  await tx.query(`ALTER SEQUENCE IF EXISTS ${q(`seq_${from}`)} RENAME TO ${q(`seq_${to}`)}`);
+  const { rows: indexes } = await tx.query(
+    "SELECT indexname FROM pg_indexes WHERE schemaname = current_schema() AND tablename = $1 AND starts_with(indexname, $2)", [to, `idx_${from}_`]);
+  for (const { indexname } of indexes) await tx.query(`ALTER INDEX ${q(indexname)} RENAME TO ${q(`idx_${to}_${indexname.slice(`idx_${from}_`.length)}`)}`);
+  const { rows: pkey } = await tx.query(
+    "SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass($1) AND conname = $2", [q(to), `${from}_pkey`]);
+  if (pkey.length) await tx.query(`ALTER TABLE ${q(to)} RENAME CONSTRAINT ${q(`${from}_pkey`)} TO ${q(`${to}_pkey`)}`);
+  if (await regclass(tx, "_delta_collections")) await tx.query("UPDATE _delta_collections SET table_name = $2 WHERE table_name = $1", [from, to]);
+}

package/src/postgres/pglite.ts

@@ -0,0 +1,142 @@
+/**
+ * @blueshed/delta/pglite — Postgres in this process.
+ *
+ * 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
+ * it unchanged:
+ *
+ *   const pool = await openPglite("./data");        // or openPglite() in memory
+ *   await applyFramework(pool);
+ *   await applySql(pool, generateSql(schema, docs));
+ *   await createDocListener(ws, pool, { types: docs.map((def) => docTypeFromDef(def, pool)), ledger: true });
+ *
+ * Outgrow it and move to a server: `exportTables(pool, schema)` here,
+ * `importTables(server, schema, rows)` there -- the ids and sequences carry.
+ * One process owns the directory. Taken from epsilon's `pglite.ts`.
+ *
+ * Optional, like `pg`: `bun add @electric-sql/pglite` to use it.
+ */
+import type { Pool } from "pg";
+
+/** The slice of PGlite this drives (structural: no hard import). */
+interface PGliteish {
+  query(text: string, params?: unknown[]): Promise<{ rows: any[] }>;
+  exec(text: string): Promise<{ rows: any[] }[]>;
+  transaction<T>(fn: (tx: { query(text: string, params?: unknown[]): Promise<{ rows: any[] }>; exec(text: string): Promise<{ rows: any[] }[]> }) => Promise<T>): Promise<T>;
+  listen(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+  close(): Promise<void>;
+}
+
+type Runner = Pick<PGliteish, "query" | "exec">;
+type Result = { rows: any[]; rowCount: number };
+
+/** pg sends a JS object or array as JSON; PGlite binds by type, so give it the JSON text. */
+const bind = (v: unknown): unknown => (v !== null && typeof v === "object" && !(v instanceof Date) ? JSON.stringify(v) : v);
+
+/** One statement with parameters, or several without, as `pg`'s query takes them. */
+async function run(on: Runner, text: string, params?: unknown[]): Promise<Result> {
+  if (params?.length) {
+    const { rows } = await on.query(text, params.map(bind));
+    return { rows, rowCount: rows.length };
+  }
+  const results = await on.exec(text);
+  const rows = results[results.length - 1]?.rows ?? [];
+  return { rows, rowCount: rows.length };
+}
+
+const verb = (text: string) => text.trim().replace(/;$/, "").toUpperCase();
+
+/**
+ * Wrap a PGlite instance in the Pool delta uses. PGlite is one session: a
+ * client's `BEGIN` opens a PGlite transaction and holds it until `COMMIT` or
+ * `ROLLBACK`, and every other query waits for it (PGlite runs queries and
+ * transactions under one lock), so nothing lands inside another's
+ * transaction. `LISTEN` on a client is PGlite's `listen`, its payloads the
+ * client's `notification` events.
+ */
+export function pglitePool(db: PGliteish): Pool {
+  function connect() {
+    const handlers = new Set<(msg: { channel: string; payload: string }) => void>();
+    const unlisten: (() => Promise<void>)[] = [];
+    // The open transaction, if any: its queries, and how to end it.
+    let tx: { on: Runner; end: (commit: boolean) => void; done: Promise<unknown> } | null = null;
+
+    const client = {
+      async query(text: string, params?: unknown[]): Promise<Result> {
+        const v = verb(text);
+        if (v === "BEGIN") {
+          if (tx) throw new Error("a transaction is already open on this client");
+          let opened!: (on: Runner) => void;
+          const ready = new Promise<Runner>((r) => (opened = r));
+          let end!: (commit: boolean) => void;
+          const ended = new Promise<boolean>((r) => (end = r));
+          const done = db.transaction(async (t) => {
+            opened(t);
+            if (!(await ended)) throw new Rollback();
+          }).catch((err) => { if (!(err instanceof Rollback)) throw err; });
+          tx = { on: await ready, end, done };
+          return { rows: [], rowCount: 0 };
+        }
+        if (v === "COMMIT" || v === "ROLLBACK") {
+          const open = tx;
+          tx = null;
+          if (!open) return { rows: [], rowCount: 0 };
+          open.end(v === "COMMIT");
+          await open.done;
+          return { rows: [], rowCount: 0 };
+        }
+        const listen = /^LISTEN\s+"?([\w.]+)"?$/.exec(v);
+        if (listen) {
+          const channel = text.trim().replace(/;$/, "").split(/\s+/)[1]!.replace(/"/g, "");
+          unlisten.push(await db.listen(channel, (payload) => { for (const h of handlers) h({ channel, payload }); }));
+          return { rows: [], rowCount: 0 };
+        }
+        if (v.startsWith("UNLISTEN")) {
+          for (const off of unlisten.splice(0)) await off();
+          return { rows: [], rowCount: 0 };
+        }
+        return run(tx ? tx.on : db, text, params);
+      },
+      on(event: string, handler: (msg: any) => void) {
+        if (event === "notification") handlers.add(handler);
+        return client;
+      },
+      removeListener(event: string, handler: (msg: any) => void) {
+        if (event === "notification") handlers.delete(handler);
+        return client;
+      },
+      release() {
+        // A client let go inside a transaction rolls it back, as pg's would be reset.
+        if (tx) { tx.end(false); tx = null; }
+      },
+    };
+    return client;
+  }
+
+  const pool = {
+    query: (text: string, params?: unknown[]) => run(db, text, params),
+    connect: async () => connect(),
+    end: () => db.close(),
+    on: () => pool,
+  };
+  return pool as unknown as Pool;
+}
+
+class Rollback extends Error {}
+
+/**
+ * Open (or create) an in-process Postgres: in `dir`, or in memory when none
+ * is given, as the Pool delta's Postgres backend takes.
+ */
+export async function openPglite(dir?: string): Promise<Pool> {
+  let PGlite: any;
+  try {
+    ({ PGlite } = await import("@electric-sql/pglite"));
+  } 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();
+  return pglitePool(db);
+}

package/src/postgres/registry.ts

@@ -0,0 +1,253 @@
+/**
+ * Doc-type registry — single source of truth for how doc names are dispatched.
+ *
+ * Each doc type owns a prefix and the four lifecycle operations:
+ *   - parse   — does this name belong to me? return ctx or null.
+ *   - open    — load the doc at its current version.
+ *   - apply   — apply delta ops and return the new version.
+ *   - openAt  — optional snapshot-at-timestamp read.
+ *
+ * Generic docs (delta-doc framework) are made by `docTypeFromDef(def, pool)`.
+ * Custom docs (e.g. venue-occasion) export their own `DocType`. Each is given
+ * to a listener (`createDocListener(ws, pool, { types })`), which asks its own
+ * types for every WS message -- no other place in the codebase interprets
+ * doc-name prefixes.
+ */
+import type { Pool } from "pg";
+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";
+
+/** 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 };
+
+// ---------------------------------------------------------------------------
+// DocType — the unified handler contract
+// ---------------------------------------------------------------------------
+
+/**
+ * A document the listener answers for. `docTypeFromDef` makes one from a
+ * `defineDoc`, which the database knows (`_delta_docs`), so a write through
+ * any document is told to it wherever it holds a row the write changed.
+ * One written by hand is the app's own: the database cannot know what its
+ * `open` reads, so it is told only its own writes -- those its `apply` logs
+ * with `_delta_bump_and_notify(docName, ops)`. To hear other writes, make it
+ * from a `defineDoc` (`docTypeFromDef`), or watch the collections with a
+ * custom document (`defineCustomDoc`).
+ */
+export interface DocType<C = any, I = unknown> {
+  /** Unique prefix this type owns (e.g. "venue:", "venue-at:"). */
+  prefix: string;
+
+  /** Parse the doc name into a context object, or null if it doesn't match. */
+  parse(docName: string): C | null;
+
+  /** Open the doc at its current version. `identity` is the authenticated
+   *  identity produced by the `DeltaAuth` gate (undefined if auth disabled). */
+  open(
+    ctx: C,
+    docName: string,
+    msg?: any,
+    identity?: I,
+  ): Promise<{ result: any; version: number } | null>;
+
+  /** Apply delta ops. Returns new version; ops may be omitted since broadcast
+   *  happens via LISTEN/NOTIFY, but returning them keeps the contract honest.
+   *  Given `by` (the listener keeps a ledger), the write is recorded with its
+   *  inverse in the same transaction -- the framework's docs do; a custom type
+   *  that ignores `by` is simply not on the ledger. */
+  apply(
+    ctx: C,
+    docName: string,
+    ops: DeltaOp[],
+    identity?: I,
+    by?: Writer,
+    /** The columns the listener's schema declares, by collection (JSON), for `callAs`: a write by them (`_delta_cols`). */
+    declared?: string,
+  ): Promise<{ version: number; ops?: any[]; inverse?: any[]; entry?: number | null }>;
+
+  /** Optional: snapshot read at a historical timestamp. Not every doc type
+   *  supports this (e.g. venue-at: already embeds the timestamp in its name). */
+  openAt?(
+    ctx: C,
+    docName: string,
+    at: string,
+    identity?: I,
+  ): Promise<any | null>;
+
+  /**
+   * With an `auth` module: may `identity` open `docName`, write through it and
+   * hear what is written to it? A document's name is its broadcast channel --
+   * whoever has it open hears every write made through it, whatever RLS lets
+   * them read -- so this is the check that keeps one identity's writes off
+   * another's socket. The listener asks it before open, delta, open_at,
+   * history, and an undo or redo of an entry written through the document;
+   * false answers 404. It asks it again before it tells a socket of a change,
+   * once per identity per change, and lets go of a socket it refuses -- so keep
+   * it cheap (a name check, or a membership the app caches). With auth, a type needs it or `shared: true`:
+   * `createDocListener` and its `register` refuse one with neither.
+   */
+  owns?(identity: I, docName: string): boolean | Promise<boolean>;
+
+  /**
+   * With an `auth` module: every identity that passes the gate may open every
+   * document of this prefix and hear every write to it -- the author's word
+   * for a type with no `owns`.
+   */
+  shared?: boolean;
+
+  /**
+   * The definition a framework document was made from (`docTypeFromDef`): its
+   * writer is answered only what it holds -- a write's, a walk's and its
+   * history's ops and inverse (`showAnswer`).
+   */
+  def?: DocDef;
+}
+
+/**
+ * A write's, a walk's or a history entry's ops and inverse as the document
+ * `doc` (of `def`) shows them: ops of the collections it holds alone -- a
+ * removal's cascade into one it does not include is left out -- and, where it
+ * names its columns, those (`_delta_show_ops`, 001c; asked only then, which
+ * framework SQL older than it cannot have). The ledger keeps them whole.
+ */
+export async function showAnswer<R extends { ops?: unknown; inverse?: unknown }>(q: Pick<Pool, "query">, doc: string, r: R, def: DocDef | undefined): Promise<R> {
+  if (!r || !def) return r;
+  const held = (ops: unknown) => Array.isArray(ops) ? ops.filter((op) => { const coll = splitPath(op.path)[0]!; return coll === def.root || def.include.includes(coll); }) : ops;
+  const out = { ...r, ...(r.ops ? { ops: held(r.ops) } : {}), ...(r.inverse ? { inverse: held(r.inverse) } : {}) };
+  if (!def.columns) return out;
+  const { rows } = await q.query("SELECT _delta_show_ops($1, $2::jsonb) AS ops, _delta_show_ops($1, $3::jsonb) AS inverse", [doc, JSON.stringify(out.ops ?? null), JSON.stringify(out.inverse ?? null)]);
+  return { ...out, ...(out.ops ? { ops: rows[0].ops } : {}), ...(out.inverse ? { inverse: rows[0].inverse } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// A listener's types -- the longest prefix answers a name
+// ---------------------------------------------------------------------------
+
+/**
+ * A listener's document types (`createDocListener`'s `types`), each server its
+ * own. With `auth`, each says who owns it (`owns`, or `shared: true`); no two
+ * have one prefix, nor one of `taken` (the listener's custom documents, todo
+ * #76). `register` adds one later, replacing the type of its prefix: a module
+ * run again (`bun --hot`) registers the latest code.
+ */
+export function docTypes(initial: DocType[], taken: string[], auth: boolean) {
+  const types: DocType[] = [];
+  assertOnePrefix([...initial.map((t) => t.prefix), ...taken]);
+  function register(t: DocType): void {
+    if (auth && !t.owns && !t.shared) throw ownerless(t.prefix, "createDocListener types");
+    assertOnePrefix([t.prefix], (p) => taken.includes(p));
+    const earlier = types.findIndex((e) => e.prefix === t.prefix);
+    if (earlier >= 0) types.splice(earlier, 1);
+    types.push(t);
+    types.sort((a, b) => b.prefix.length - a.prefix.length);
+  }
+  initial.forEach(register);
+  return {
+    register,
+    resolve(docName: string): { type: DocType; ctx: any } | null {
+      for (const type of types) {
+        const ctx = type.parse(docName);
+        if (ctx !== null) return { type, ctx };
+      }
+      return null;
+    },
+  };
+}
+
+/**
+ * `SELECT fn(args) AS result` on `db`, as `identity` when the auth module
+ * says how to name it (`asSqlArg`): `fn_as(user, args)`, which sets
+ * `app.user_id` and calls `fn` in one round-trip (001f).
+ */
+export async function callAs<I>(db: { query(sql: string, params: unknown[]): Promise<{ rows: any[] }> }, fn: string, args: unknown[], auth?: DeltaAuth<I>, identity?: I, declared?: string): Promise<any> {
+  const as = auth?.asSqlArg && identity !== undefined ? [String(auth.asSqlArg(identity))] : [];
+  const all = [...as, ...args];
+  const call = `${as.length ? `${fn}_as` : fn}(${all.map((_, i) => `$${i + 1}`).join(", ")})`;
+  if (declared === undefined) return (await db.query(`SELECT ${call} AS result`, all)).rows[0]?.result;
+  // the columns this process declares, for the call's transaction (`_delta_cols`, 001b): set first, then the call
+  const { rows } = await db.query(`WITH d AS MATERIALIZED (SELECT set_config('delta.declared', $${all.length + 1}, true)) SELECT ${call} AS result FROM d`, [...all, declared]);
+  return rows[0]?.result;
+}
+
+// ---------------------------------------------------------------------------
+// docTypeFromDef — lift a generic DocDef into a DocType
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce a DocType for a framework-generic doc. One DocType per DocDef —
+ * this replaces the former "one big generic handler that loops prefixes"
+ * pattern so the registry stays flat and each prefix owns itself.
+ *
+ * When `opts.auth` is provided with `asSqlArg`, the hot path calls the
+ * `delta_*_as(user_id, ...)` stored-function variants (see
+ * `src/sql/001f-delta-as.sql`). Each op is ONE round-trip — the wrapper
+ * runs `set_config('app.user_id', ..., true)` server-side inside the
+ * SELECT's implicit transaction, then calls the base function. Compare
+ * to the four RTTs `withAppAuth` takes (BEGIN / set_config / call / COMMIT).
+ *
+ * When auth is omitted, queries run on the bare pool with the base
+ * `delta_*` functions.
+ *
+ * With `auth`, pass `owns(identity, docName)` -- who may open a document of
+ * this prefix -- or `shared: true`; without either it throws. A document's
+ * name is the channel its writes are broadcast on, so RLS alone does not keep
+ * one identity's writes off another identity's socket.
+ */
+export function docTypeFromDef<I = unknown>(
+  def: DocDef,
+  pool: Pool,
+  opts?: {
+    auth?: DeltaAuth<I>;
+    /** Who may open a document of this prefix (see `DocType.owns`). Required with `auth`, unless `shared`. */
+    owns?: (identity: I, docName: string) => boolean | Promise<boolean>;
+    /** Every identity that passes the gate may open every document of this prefix and hear every write to it. */
+    shared?: boolean;
+  },
+): DocType<{}, I> {
+  const auth = opts?.auth;
+  // Default-deny: RLS filters what `open` reads, not what the document's
+  // channel carries, so a name several identities may open would hand each of
+  // them every row written through it. Say who owns it, or that it is shared.
+  if (auth && !opts?.owns && !opts?.shared) throw ownerless(def.prefix, "docTypeFromDef");
+  // 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");
+
+  return {
+    prefix: def.prefix,
+    ...(opts?.owns ? { owns: opts.owns } : {}),
+    ...(opts?.shared ? { shared: true } : {}),
+    def,
+
+    parse(docName) {
+      return docName.startsWith(def.prefix) ? {} : null;
+    },
+
+    async open(_ctx, docName, _msg, identity) {
+      const doc = await callAs(pool, "delta_open", [docName], auth, identity);
+      if (!doc) return null;
+      const version = doc._version ?? 0;
+      delete doc._version;
+      // Forward the version to the client as `_v` so it can detect a missed
+      // broadcast (gap) and re-open to resync. The client strips `_v` before
+      // it reaches `doc.data`. Number() keeps it consistent with the broadcast
+      // `v` (which pg yields as a string from a BIGINT column).
+      doc._v = Number(version);
+      return { result: doc, version };
+    },
+
+    async apply(_ctx, docName, ops, identity, by, declared) {
+      // on the ledger: delta_apply with its entry, in one transaction (001g)
+      const result = by
+        ? await callAs(pool, "delta_apply_logged", [docName, JSON.stringify(ops), by.who, by.cursor, by.undoable !== false, by.undoes ?? null], auth, identity, declared)
+        : await callAs(pool, "delta_apply", [docName, JSON.stringify(ops)], auth, identity, declared);
+      if (!result) throw new Error(`delta_apply returned no result for ${docName}`);
+      return showAnswer(pool, docName, result, def);   // its writer is answered only what it holds
+    },
+
+    async openAt(_ctx, docName, at, identity) {
+      return (await callAs(pool, "delta_open_at", [docName, at], auth, identity)) ?? null;
+    },
+  };
+}