@ai-matrx/data 0.22.33 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.24.0 — doors hardened (independent review)
+
+- **Every write on a versioned table is guarded.** `remove` (and `archive` / `restore`) take the same
+  `{ expectedVersion }` / `{ overwrite: true }` guard as `update`; `expectedVersion` on an UNversioned
+  table is refused (it used to be ignored silently). `remove` returns `{ status }` (or a conflict).
+- **Reads exclude soft-deleted rows** by default (`read`, `listAll`, `page`, `count`); `includeDeleted: true` opts in.
+- **`listAll` / `page` order by the full primary key** (stable paging on composite keys).
+- **Types:** ops infer `TableDescriptor<Row, Insert, Update>` directly, so an insert error names the
+  table's Insert type; `read`/`listAll`/`page` take `columns: [...]` and type the result to them; the
+  `Where` callback receives a typed `Filter<Row>` (column names and value types checked).
+- **Pay-only runtime tables:** `--flags-index` writes `<schema>.flags.ts` per schema plus
+  `flags-index.ts` loaders; `loadTableByName(flagLoaders, "schema.table")` loads only that schema.
+- **The description ships in the package** (`description/*.json.gz`, 0.5 MB): `matrx-data generate`
+  needs no repository or database access (`--from` still takes a fresher one). README documents it.
+- `matrx-data emit` accounts for every callable-door register row: `index.json` →
+  `report.registeredDoorsOutsideDescription` by reason, and the emit fails if any row is unexplained.
+
+Consumer action: `remove(db, t, id)` on a versioned table now needs a guard and returns `{ status }`;
+`read(db, t, id, "cols")` becomes `read(db, t, id, { columns: [...] })`. No consumer used 0.23.0's doors yet.
+
+## 0.23.0 — the doors: one way to talk to the database
+
+- **`matrx-data` CLI** (`bin`): `matrx-data emit [--out db-contract] [--check]` reads the LIVE database
+  (read-only, every statement in `begin transaction read only`) into the ONE language-neutral database
+  description — per exposed schema: tables/views with columns, keys, grants per role, the table-registry
+  flags, lifecycle columns, the organization rule (entity binding · parent via `inherit_org_from_parent`),
+  realtime publications; every function any client role may execute (overloads kept apart, register
+  metadata or `registered: false`); enums; `index.json` with the contract hash. `--check` exits 1 on drift.
+  `matrx-data generate --from <description> --out <dir> [--schemas a,b] [--flags-index] [--check]` writes
+  typed descriptors INSIDE the app (one self-contained file per schema; one top-level `const` per table
+  and function), so a new column never waits on a package release.
+- **`@ai-matrx/data/db` doors** (additive): `createDb({ client, organization })` wraps the app's existing
+  Supabase client (no second auth client or socket) and hands the session to `@ai-matrx/api` as its
+  `user` credential (`db.credentials`); `createServiceDb` (server only, throws in a browser);
+  `read`, `listAll` (complete past 1,000 rows), `page`, `count`, `insert` (entity → named or active
+  organization; child → never the active organization, the parent's comes from the database),
+  `update` (`{ expectedVersion }` guarded or `{ overwrite: true }` on versioned tables), `remove`
+  (soft delete; archive-only tables refuse), `archive` / `restore`, `call` (functions), `tableByName`
+  (runtime-chosen tables over the flags index), `changesOf` (published tables only); the door set by
+  registry type refused before the wire (`DoorRefusedError`).
+
+Consumer action: none required (additive; nothing existing changed). To adopt: add
+`"db:generate": "matrx-data generate --from <aidream>/db-contract --out src/db/generated --schemas <yours>"`,
+then `createDb({ client: <your existing client>, organization: () => activeOrgId })` and call the doors.
+Migration of existing call sites starts at the data layer design's step 5.
+
 ## 0.22.33
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/README.md

@@ -32,6 +32,40 @@ npm install @ai-matrx/data
 | `createActiveOrgCookie` | ONE browser memory of the organization a person is acting in, shared by every Matrx surface on the apex (`matrx-active-org`, `Domain=.aimatrx.com`): identity-keyed (`<userId>:<orgId>`), domain-wide only on a listed apex, host-only elsewhere. Stores the stored-selection rung of the canonical order; never decides. |
 | `uniqueChannelTopic` | Realtime channel hygiene: unique per-mount topics so React 19 double-invoked effects and Fast Refresh can never collide with a still-joined channel. |
 
+## The doors — one way to talk to the database
+
+Every app talks to the database through doors over descriptors it **generates locally** from the
+ONE database description. The description ships inside this package (`description/`, gzipped, the one
+this version was built with), so no repository or database access is needed.
+
+```bash
+# in your app (package.json: "db:generate": "matrx-data generate --out src/db/generated --schemas workbench,chat")
+npx matrx-data generate --out src/db/generated --schemas workbench          # one file per schema
+npx matrx-data generate --out src/db/generated --schemas workbench --check  # CI: fail when stale
+npx matrx-data generate --out src/db/generated --flags-index                # + per-schema flags for tableByName
+# fresher than this package version? With the direct-DB variables (SUPABASE_MATRIX_*):
+npx matrx-data emit --out db-contract && npx matrx-data generate --from db-contract --out src/db/generated
+```
+
+```ts
+import { createDb, listAll, read, insert, update, remove, call } from "@ai-matrx/data/db";
+import { noteFolders, notes, noteFolderGetOrCreate } from "./db/generated/workbench";
+
+const db = createDb({ client: supabase, organization: () => activeOrgId }); // wraps YOUR client
+const pinned = await listAll(db, notes, (q) => q.eq("is_pinned", true));       // complete; typed filter; live rows
+const row = await read(db, notes, id, { columns: ["id", "label"] });           // typed to those columns
+await insert(db, notes, { folder_id, label });         // child: the folder's organization, never the active one
+await update(db, notes, id, { label }, { expectedVersion: row.version });      // or { overwrite: true }
+await remove(db, notes, id, { expectedVersion: v });   // soft delete; archive-only tables refuse
+await call(db, noteFolderGetOrCreate, { p_name: "Clients" });
+// @ai-matrx/api: pass db.credentials as its `credentials` option — one sign-in feeds both lanes
+```
+
+Rules come from the description (the live table registry), never the call site: organization by the
+access ladder; reads never filter by the active organization and exclude soft-deleted rows unless
+`includeDeleted`; `listAll` is complete and ordered by the full primary key; every write on a versioned
+table is guarded; the door set follows the registry type; `createServiceDb` is server-only.
+
 ## `@ai-matrx/data/net`
 
 | Export | What it does |

package/bin/direct-db.mjs

@@ -0,0 +1,80 @@
+/**
+ * direct-db.mjs — @ai-matrx/data's BUILD-TIME read of the live catalogue (the
+ * `matrx-data emit` step). Never part of a runtime entry point.
+ *
+ * Connection: the SAME five variables every Matrx tool resolves —
+ * SUPABASE_MATRIX_USER / PASSWORD / HOST / PORT / DATABASE_NAME — from the
+ * environment, then `.env.local` / `.env` up the tree, then a sibling
+ * `aidream/.env`. No second candidate variable, no fallback database.
+ * The password rides PGPASSWORD in psql's environment; it is never printed.
+ *
+ * READ-ONLY, always: every statement runs inside `begin transaction read only`.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const DB_VARS = [
+  "SUPABASE_MATRIX_USER",
+  "SUPABASE_MATRIX_PASSWORD",
+  "SUPABASE_MATRIX_HOST",
+  "SUPABASE_MATRIX_PORT",
+  "SUPABASE_MATRIX_DATABASE_NAME",
+];
+
+function parseEnvFile(file) {
+  const out = {};
+  for (const line of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/.exec(line);
+    if (m) out[m[1]] = (m[2] ?? "").replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+const complete = (bag) => DB_VARS.every((k) => bag[k]);
+
+export function connection() {
+  if (complete(process.env)) return { bag: process.env, from: "the environment" };
+  const seen = new Set();
+  let dir = process.cwd();
+  for (;;) {
+    for (const file of [join(dir, ".env.local"), join(dir, ".env"), join(dir, "aidream", ".env")]) {
+      if (seen.has(file) || !existsSync(file)) continue;
+      seen.add(file);
+      const bag = parseEnvFile(file);
+      if (complete(bag)) return { bag, from: file };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function psqlBinary() {
+  try {
+    const prefix = execFileSync("brew", ["--prefix", "libpq"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (existsSync(join(prefix, "bin", "psql"))) return join(prefix, "bin", "psql");
+  } catch {
+    /* fall through */
+  }
+  return "psql";
+}
+
+/** Run one read-only SELECT that returns a single json value; returns the parsed value. */
+export function readJson(sql) {
+  const conn = connection();
+  if (!conn) {
+    throw new Error(`matrx-data: none of ${DB_VARS.join(", ")} resolvable (environment, .env up the tree, aidream/.env)`);
+  }
+  const b = conn.bag;
+  const out = execFileSync(
+    psqlBinary(),
+    [
+      "-h", b.SUPABASE_MATRIX_HOST, "-p", b.SUPABASE_MATRIX_PORT, "-U", b.SUPABASE_MATRIX_USER,
+      "-d", b.SUPABASE_MATRIX_DATABASE_NAME, "-X", "-q", "-At", "-v", "ON_ERROR_STOP=1",
+      "-c", "begin transaction read only;", "-c", sql, "-c", "rollback;",
+    ],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1 << 30, env: { ...process.env, PGPASSWORD: b.SUPABASE_MATRIX_PASSWORD } },
+  );
+  return JSON.parse(out.trim() || "null");
+}

package/bin/emit.mjs

@@ -0,0 +1,380 @@
+/**
+ * emit.mjs — `matrx-data emit`: the LIVE database → the database description.
+ *
+ * The description is the ONE language-neutral contract every client generates
+ * from (TypeScript today, Swift/Kotlin and matrx-local's SQLite mirror read the
+ * same JSON). It carries what the database itself knows, never a hand-written
+ * list:
+ *
+ *   per schema (every schema PostgREST exposes — `pgrst.db_schemas` on `authenticator`):
+ *     tables + views: columns (type, array, nullable, default, generated, identity, enum),
+ *       primary key, foreign keys, RLS on/off, per-role grants (anon/authenticated/service_role),
+ *       the table-registry row (`platform.entity_types`: token, type, versioned, soft delete,
+ *       component, client_read_only, client_deletes_refused, client_excluded_columns,
+ *       client_read_only_columns, governed_columns, default_list_scope, title_column),
+ *       lifecycle columns (deleted_at / archived_at / is_archived / version / organization_id),
+ *       the organization rule (entity binding · parent via `inherit_org_from_parent` · none),
+ *       the guard triggers, realtime publications
+ *     functions: EVERY function anon / authenticated / service_role may execute (overloads kept
+ *       apart), args with mode/default, result, volatility, definer/invoker, and the
+ *       callable-door register's metadata where a row exists (`registered: false` otherwise)
+ *     enums referenced by the schema
+ *
+ *   index.json: format, contract hash (sha256 over every schema file), per-schema hash and
+ *     counts, the publications, and the report (tables with no registry row, untyped rows).
+ *
+ * Deterministic: no timestamps, everything sorted — `--check` compares bytes.
+ * READ-ONLY: every statement runs inside `begin transaction read only` (direct-db.mjs).
+ *
+ *   matrx-data emit [--out <dir>] [--check]
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { readJson } from "./direct-db.mjs";
+
+export const FORMAT = "matrx-db-description/1";
+const ROLES = ["anon", "authenticated", "service_role"];
+const LIFECYCLE = ["deleted_at", "archived_at", "is_archived", "version", "organization_id"];
+const GUARD_TRIGGERS = ["inherit_org_from_parent", "refuse_org_foreign_to_parent", "_cascade_soft_delete", "_guard_soft_delete_parent"];
+
+const lit = (s) => `'${String(s).replace(/'/g, "''")}'`;
+const arr = (xs) => `array[${xs.map(lit).join(",")}]::text[]`;
+
+/** Stable stringify: object keys sorted, 2-space indent. */
+export function canonical(value) {
+  const sort = (v) =>
+    Array.isArray(v) ? v.map(sort) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sort(v[k])])) : v;
+  return `${JSON.stringify(sort(value), null, 1)}\n`;
+}
+
+export const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+function exposedSchemas() {
+  const cfg = readJson(
+    "select coalesce(json_agg(c), '[]') from pg_roles r, unnest(r.rolconfig) c where r.rolname = 'authenticator' and c like 'pgrst.db_schemas=%'",
+  );
+  const raw = (cfg[0] ?? "").replace(/^pgrst\.db_schemas=/, "");
+  const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const present = readJson(`select coalesce(json_agg(nspname order by nspname), '[]') from pg_namespace where nspname = any(${arr(names)})`);
+  // graphql_public carries no client tables or functions of ours.
+  return present.filter((s) => s !== "graphql_public");
+}
+
+function collect(schemas) {
+  const S = arr(schemas);
+  const TYPE = (oidExpr) => `(
+    select json_build_object(
+      'type', format_type(coalesce(nullif(bt.typbasetype, 0), bt.oid), null),
+      'enum', case when coalesce(dt.typtype, bt.typtype) = 'e' then dn.nspname || '.' || dt.typname end
+    )
+    from pg_type t0
+    join pg_type bt on bt.oid = case when t0.typcategory = 'A' and t0.typelem <> 0 then t0.typelem else t0.oid end
+    left join pg_type dt on dt.oid = case when bt.typtype = 'd' then bt.typbasetype else bt.oid end
+    left join pg_namespace dn on dn.oid = dt.typnamespace
+    where t0.oid = ${oidExpr})`;
+
+  const relations = readJson(`
+    select coalesce(json_agg(r order by r.schema, r.name), '[]') from (
+      select n.nspname as schema, c.relname as name, c.oid::int as oid,
+        case c.relkind when 'v' then 'view' when 'm' then 'materialized_view' else 'table' end as kind,
+        c.relrowsecurity as rls,
+        (select json_agg(json_build_object(
+            'name', a.attname, 'nullable', not a.attnotnull, 'default', a.atthasdef,
+            'generated', a.attgenerated <> '', 'identity', a.attidentity <> '',
+            'array', t.typcategory = 'A', 't', ${TYPE("a.atttypid")}) order by a.attnum)
+          from pg_attribute a join pg_type t on t.oid = a.atttypid
+          where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped) as columns,
+        (select json_agg(a.attname order by k.ord) from pg_index i
+           cross join lateral unnest(i.indkey) with ordinality k(attnum, ord)
+           join pg_attribute a on a.attrelid = c.oid and a.attnum = k.attnum
+          where i.indrelid = c.oid and i.indisprimary) as pk,
+        (select json_agg(json_build_object(
+            'name', co.conname,
+            'columns', (select json_agg(a.attname order by k.ord) from unnest(co.conkey) with ordinality k(n, ord) join pg_attribute a on a.attrelid = co.conrelid and a.attnum = k.n),
+            'references', fn.nspname || '.' || fc.relname,
+            'referencedColumns', (select json_agg(a.attname order by k.ord) from unnest(co.confkey) with ordinality k(n, ord) join pg_attribute a on a.attrelid = co.confrelid and a.attnum = k.n)
+          ) order by co.conname)
+          from pg_constraint co join pg_class fc on fc.oid = co.confrelid join pg_namespace fn on fn.oid = fc.relnamespace
+          where co.conrelid = c.oid and co.contype = 'f') as fks,
+        json_build_object(${ROLES.map(
+          (r) =>
+            `'${r}', json_build_object('select', has_table_privilege('${r}', c.oid, 'SELECT'), 'insert', has_table_privilege('${r}', c.oid, 'INSERT'), 'update', has_table_privilege('${r}', c.oid, 'UPDATE'), 'delete', has_table_privilege('${r}', c.oid, 'DELETE'))`,
+        ).join(", ")}) as grants,
+        (select json_agg(json_build_object('function', p.proname, 'args', string_to_array(rtrim(encode(t.tgargs, 'escape'), E'\\\\000'), E'\\\\000')) order by p.proname, t.tgname)
+          from pg_trigger t join pg_proc p on p.oid = t.tgfoid
+          where t.tgrelid = c.oid and not t.tgisinternal and p.proname = any(${arr(GUARD_TRIGGERS)})) as guards,
+        (select json_agg(pubname order by pubname) from pg_publication_tables pt where pt.schemaname = n.nspname and pt.tablename = c.relname) as publications
+      from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = any(${S}) and c.relkind in ('r','p','v','m') and not c.relispartition
+    ) r`);
+
+  const registry = readJson(`
+    select coalesce(json_agg(json_build_object(
+      'oid', e.table_ref::oid::int, 'schema', e.schema_name, 'table', e.table_name, 'token', e.token, 'type', e.type,
+      'versioned', e.is_versioned, 'softDelete', e.has_soft_delete, 'component', e.is_component, 'active', e.is_active,
+      'clientReadOnly', e.client_read_only, 'clientDeletesRefused', e.client_deletes_refused,
+      'clientExcludedColumns', e.client_excluded_columns, 'clientReadOnlyColumns', e.client_read_only_columns,
+      'governedColumns', e.governed_columns, 'listScope', e.default_list_scope::text, 'titleColumn', e.title_column
+    ) order by e.schema_name, e.table_name), '[]') from platform.entity_types e`);
+
+  const functions = readJson(`
+    select coalesce(json_agg(f order by f.schema, f.name, f.identity), '[]') from (
+      select n.nspname as schema, p.proname as name, pg_get_function_identity_arguments(p.oid) as identity,
+        p.proretset as "returnsSet", p.provolatile as volatility, p.prosecdef as definer,
+        p.pronargdefaults as "argDefaults",
+        (select json_agg(json_build_object(
+            'name', coalesce(p.proargnames[k.ord], ''), 'mode', coalesce(p.proargmodes[k.ord], 'i'),
+            'array', (select typcategory = 'A' from pg_type where oid = k.typ), 't', ${TYPE("k.typ")}) order by k.ord)
+          from unnest(coalesce(p.proallargtypes, p.proargtypes::oid[])) with ordinality k(typ, ord)) as args,
+        (select json_build_object('array', typcategory = 'A', 'pseudo', typtype = 'p', 't', ${TYPE("p.prorettype")}) from pg_type where oid = p.prorettype) as result,
+        json_build_array(${ROLES.map((r) => `case when has_function_privilege('${r}', p.oid, 'EXECUTE') then '${r}' end`).join(", ")}) as roles
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+      where n.nspname = any(${S}) and p.prokind = 'f'
+        and p.prorettype not in ('trigger'::regtype, 'event_trigger'::regtype)
+        and not exists (select 1 from pg_depend d where d.classid = 'pg_proc'::regclass and d.objid = p.oid and d.deptype = 'e')
+        and (${ROLES.map((r) => `has_function_privilege('${r}', p.oid, 'EXECUTE')`).join(" or ")})
+    ) f`);
+
+  // Every register row, matched to its live function (schema-qualified type names normalized, so
+  // "p_row block_states" matches "p_row platform.block_states"), and when it is not in the
+  // description, WHY — so no register row is ever unaccounted for.
+  const doors = readJson(`
+    select coalesce(json_agg(json_build_object(
+      'schema', d.schema_name, 'name', d.function_name, 'identity', coalesce(p.ident, d.identity_args),
+      'gatePredicate', d.gate_predicate, 'anonymousCallers', d.anonymous_callers, 'signedInCallers', d.signed_in_callers,
+      'nonClientLane', d.non_client_lane, 'argumentRules', d.argument_rules, 'refusalOnly', d.refusal_only,
+      'outside', case
+        when p.oid is null and not exists (select 1 from pg_proc p2 join pg_namespace n2 on n2.oid = p2.pronamespace
+                                            where n2.nspname = d.schema_name and p2.proname = d.function_name) then 'function no longer exists'
+        when p.oid is null then 'no live overload has the registered signature'
+        when not (d.schema_name = any(${S})) then 'schema not exposed to PostgREST (server-only)'
+        when not (${ROLES.map((r) => `has_function_privilege('${r}', p.oid, 'EXECUTE')`).join(" or ")}) then 'no client role may execute it'
+        when p.prorettype in ('trigger'::regtype, 'event_trigger'::regtype) then 'trigger function'
+        when exists (select 1 from pg_depend dd where dd.classid = 'pg_proc'::regclass and dd.objid = p.oid and dd.deptype = 'e') then 'extension-owned'
+      end
+    )), '[]')
+    from platform.client_callable_door d
+    left join lateral (
+      select p.oid, p.prorettype, pg_get_function_identity_arguments(p.oid) as ident
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+      where n.nspname = d.schema_name and p.proname = d.function_name
+        and regexp_replace(pg_get_function_identity_arguments(p.oid), '\\m[a-z_][a-z0-9_]*\\.', '', 'g')
+          = regexp_replace(d.identity_args, '\\m[a-z_][a-z0-9_]*\\.', '', 'g')
+      limit 1) p on true`);
+
+  const enums = readJson(`
+    select coalesce(json_object_agg(n.nspname || '.' || t.typname,
+      (select json_agg(e.enumlabel order by e.enumsortorder) from pg_enum e where e.enumtypid = t.oid)), '{}')
+    from pg_type t join pg_namespace n on n.oid = t.typnamespace where t.typtype = 'e'`);
+
+  // Every published table, in every schema (a client subscribes by name; the messages
+  // publication's daily partitions collapse to their parent so the description does not drift each day).
+  const published = readJson(`
+    select coalesce(json_agg(json_build_object('pub', pubname, 'table', schemaname || '.' || tablename)), '[]') from pg_publication_tables`);
+
+  return { relations, registry, functions, doors, enums, published };
+}
+
+const col = (c) => {
+  const out = { name: c.name, type: c.t.type };
+  if (c.t.enum) out.enum = c.t.enum;
+  if (c.array) out.array = true;
+  if (c.nullable) out.nullable = true;
+  if (c.default) out.default = true;
+  if (c.generated) out.generated = true;
+  if (c.identity) out.identity = true;
+  return out;
+};
+
+function describeTable(rel, reg) {
+  const names = new Set((rel.columns ?? []).map((c) => c.name));
+  const guards = rel.guards ?? [];
+  const inherit = guards.find((g) => g.function === "inherit_org_from_parent");
+  let org;
+  if (inherit) {
+    const [ps, pt, fk] = inherit.args;
+    org = { rule: "parent", parent: `${ps}.${pt}`, via: fk };
+  } else if (names.has("organization_id")) {
+    org = { rule: rel.kind === "table" ? "binding" : "column" };
+  } else org = { rule: "none" };
+
+  const lifecycle = Object.fromEntries(LIFECYCLE.filter((c) => names.has(c)).map((c) => [c, true]));
+  const out = {
+    name: rel.name,
+    kind: rel.kind,
+    columns: (rel.columns ?? []).map(col),
+    primaryKey: rel.pk ?? [],
+    foreignKeys: (rel.fks ?? []).map((f) => ({ name: f.name, columns: f.columns, references: f.references, referencedColumns: f.referencedColumns })),
+    rls: rel.rls,
+    grants: rel.grants,
+    lifecycle,
+    org,
+    guards: [...new Set(guards.map((g) => g.function))].sort(),
+    realtime: rel.publications ?? [],
+  };
+  if (reg) {
+    out.registry = {
+      token: reg.token,
+      type: reg.type ?? null,
+      versioned: !!reg.versioned,
+      softDelete: !!reg.softDelete,
+      component: !!reg.component,
+      active: reg.active !== false,
+      clientReadOnly: !!reg.clientReadOnly,
+      clientDeletesRefused: !!reg.clientDeletesRefused,
+      clientExcludedColumns: reg.clientExcludedColumns ?? [],
+      clientReadOnlyColumns: reg.clientReadOnlyColumns ?? [],
+      governedColumns: reg.governedColumns ?? [],
+      listScope: reg.listScope ?? null,
+      titleColumn: reg.titleColumn ?? null,
+    };
+  } else out.registry = null;
+  return out;
+}
+
+function describeFunction(fn, door) {
+  const args = (fn.args ?? []).map((a) => {
+    const o = { name: a.name, mode: { i: "in", o: "out", b: "inout", v: "variadic", t: "table" }[a.mode] ?? a.mode, type: a.t.type };
+    if (a.t.enum) o.enum = a.t.enum;
+    if (a.array) o.array = true;
+    return o;
+  });
+  const inputs = args.filter((a) => a.mode === "in" || a.mode === "inout" || a.mode === "variadic");
+  inputs.slice(inputs.length - fn.argDefaults).forEach((a) => {
+    a.optional = true;
+  });
+  const out = {
+    name: fn.name,
+    identity: fn.identity,
+    args,
+    returns: {
+      type: fn.result.t.type,
+      ...(fn.result.t.enum ? { enum: fn.result.t.enum } : {}),
+      ...(fn.result.array ? { array: true } : {}),
+      ...(fn.returnsSet ? { set: true } : {}),
+    },
+    volatility: { i: "immutable", s: "stable", v: "volatile" }[fn.volatility],
+    security: fn.definer ? "definer" : "invoker",
+    roles: fn.roles.filter(Boolean),
+    registered: !!door,
+  };
+  if (door) {
+    out.door = {
+      gatePredicate: door.gatePredicate ?? null,
+      anonymousCallers: !!door.anonymousCallers,
+      signedInCallers: door.signedInCallers !== false,
+      nonClientLane: door.nonClientLane ?? null,
+      argumentRules: door.argumentRules ?? null,
+      refusalOnly: !!door.refusalOnly,
+    };
+  }
+  return out;
+}
+
+/** Build every file of the description in memory: { "index.json": text, "<schema>.json": text, … } */
+export function buildDescription() {
+  const schemas = exposedSchemas();
+  const { relations, registry, functions, doors, enums, published } = collect(schemas);
+  const regByOid = new Map(registry.filter((r) => r.oid).map((r) => [r.oid, r]));
+  const doorKey = (s, n, i) => `${s}.${n}(${i})`;
+  const doorsByKey = new Map(doors.map((d) => [doorKey(d.schema, d.name, d.identity), d]));
+
+  const files = {};
+  const index = { format: FORMAT, schemas: {}, publications: {}, report: { tablesWithoutRegistryRow: [], untypedRegistryRows: [], registeredDoorsOutsideDescription: {} } };
+  const publications = {};
+  for (const { pub, table } of published) {
+    const name = table.replace(/^realtime\.messages_\d{4}_\d{2}_\d{2}$/, "realtime.messages");
+    const list = (publications[pub] ??= []);
+    if (!list.includes(name)) list.push(name);
+  }
+  let matchedDoors = 0;
+
+  for (const schema of schemas) {
+    const rels = relations.filter((r) => r.schema === schema);
+    const tables = {};
+    const views = {};
+    const used = new Set();
+    for (const rel of rels) {
+      const reg = regByOid.get(rel.oid) ?? null;
+      const d = describeTable(rel, reg);
+      d.columns.forEach((c) => c.enum && used.add(c.enum));
+      if (rel.kind === "table") {
+        tables[rel.name] = d;
+        if (!reg) index.report.tablesWithoutRegistryRow.push(`${schema}.${rel.name}`);
+        else if (!reg.type) index.report.untypedRegistryRows.push(`${schema}.${rel.name}`);
+      } else {
+        delete d.registry;
+        views[rel.name] = d;
+      }
+    }
+    const fns = {};
+    for (const fn of functions.filter((f) => f.schema === schema)) {
+      const door = doorsByKey.get(doorKey(schema, fn.name, fn.identity));
+      if (door) matchedDoors += 1;
+      const d = describeFunction(fn, door);
+      d.args.forEach((a) => a.enum && used.add(a.enum));
+      if (d.returns.enum) used.add(d.returns.enum);
+      (fns[fn.name] ??= []).push(d);
+    }
+    for (const list of Object.values(fns)) list.sort((a, b) => a.identity.localeCompare(b.identity));
+    const schemaEnums = Object.fromEntries([...used].sort().map((e) => [e, enums[e] ?? []]));
+    const text = canonical({ format: FORMAT, schema, tables, views, functions: fns, enums: schemaEnums });
+    files[`${schema}.json`] = text;
+    const overloads = Object.values(fns).filter((l) => l.length > 1).length;
+    index.schemas[schema] = {
+      sha256: sha256(text),
+      tables: Object.keys(tables).length,
+      views: Object.keys(views).length,
+      functions: Object.values(fns).reduce((n, l) => n + l.length, 0),
+      overloadedNames: overloads,
+    };
+  }
+  for (const k of Object.keys(publications)) publications[k].sort();
+  index.publications = publications;
+  // Every register row not in the description, by reason (each named; none unaccounted for).
+  const outside = {};
+  for (const d of doors) if (d.outside) (outside[d.outside] ??= []).push(`${d.schema}.${d.name}(${d.identity})`);
+  for (const k of Object.keys(outside)) outside[k].sort();
+  index.report.registeredDoorsOutsideDescription = outside;
+  index.report.registeredDoors = { total: doors.length, inDescription: matchedDoors, outside: doors.length - matchedDoors };
+  const unexplained = doors.length - matchedDoors - Object.values(outside).reduce((n, l) => n + l.length, 0);
+  if (unexplained !== 0) throw new Error(`${unexplained} register row(s) neither in the description nor explained — the emitter's matching is wrong`);
+  index.report.tablesWithoutRegistryRow.sort();
+  index.report.untypedRegistryRows.sort();
+  index.contractSha256 = sha256(Object.keys(index.schemas).sort().map((s) => `${s}:${index.schemas[s].sha256}`).join("\n"));
+  files["index.json"] = canonical(index);
+  return files;
+}
+
+export function emit({ out, check }) {
+  const files = buildDescription();
+  if (check) {
+    const drift = [];
+    for (const [name, text] of Object.entries(files)) {
+      const p = path.join(out, name);
+      if (!existsSync(p)) drift.push(`${name}: missing on disk`);
+      else if (readFileSync(p, "utf8") !== text) drift.push(`${name}: differs from the live database`);
+    }
+    if (existsSync(out))
+      for (const name of readdirSync(out)) if (name.endsWith(".json") && !(name in files)) drift.push(`${name}: on disk, no longer in the live database`);
+    if (drift.length) {
+      console.error(`matrx-data emit --check: the committed description drifted from the live database (${drift.length}):`);
+      for (const d of drift) console.error(`  ${d}`);
+      console.error("Run `matrx-data emit` and commit the result.");
+      return 1;
+    }
+    const idx = JSON.parse(files["index.json"]);
+    console.log(`matrx-data emit --check: in step with the live database (contract ${idx.contractSha256.slice(0, 12)})`);
+    return 0;
+  }
+  mkdirSync(out, { recursive: true });
+  for (const [name, text] of Object.entries(files)) writeFileSync(path.join(out, name), text);
+  const idx = JSON.parse(files["index.json"]);
+  const sum = (k) => Object.values(idx.schemas).reduce((n, s) => n + s[k], 0);
+  console.log(
+    `matrx-data emit: ${Object.keys(idx.schemas).length} schemas · ${sum("tables")} tables · ${sum("views")} views · ${sum("functions")} functions → ${out} (contract ${idx.contractSha256.slice(0, 12)})`,
+  );
+  return 0;
+}