@ai-matrx/data 0.22.32 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 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
+`git diff npm/data/v0.22.32..npm/data/v0.22.33 -- apps/shared/data`).
+No source changes intended and no consumer action required.
+
 ## 0.22.32
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

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,355 @@
+/**
+ * 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`);
+
+  const doors = readJson(`
+    select coalesce(json_agg(json_build_object(
+      'schema', d.schema_name, 'name', d.function_name, 'identity', 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
+    )), '[]') from platform.client_callable_door d`);
+
+  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: 0 } };
+  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;
+  // Register rows whose function is outside the exposed schemas, not executable by any client role,
+  // or whose identity no longer matches a live signature.
+  index.report.registeredDoorsOutsideDescription = doors.length - matchedDoors;
+  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;
+}

package/bin/generate.mjs

@@ -0,0 +1,196 @@
+/**
+ * generate.mjs — `matrx-data generate`: the database description → typed doors,
+ * written INSIDE the app that uses them (Prisma's model: the package ships the
+ * runtime and this generator, never the generated tables, so a new column never
+ * waits on a package release).
+ *
+ * One file per schema (`<schema>.ts`), each self-contained (no file imports
+ * another), so importing one schema loads no other; every table and function is
+ * its own top-level `const` (flags + names only, no row data), so a bundler keeps
+ * exactly the descriptors used. Types: Row (client-excluded columns removed),
+ * Insert (defaulted / nullable / org-filled columns optional; generated and
+ * client-read-only columns removed), Update (Partial of Insert). Functions: one
+ * descriptor per name; overloads become a union of named-argument shapes.
+ *
+ *   matrx-data generate --from <description dir> --out <dir> [--schemas a,b] [--check]
+ *                       [--flags-index]   also write flags-index.ts for tableByName()
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const RESERVED = new Set(
+  "break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(
+    " ",
+  ),
+);
+
+const camel = (s) => s.replace(/^_+/, "").replace(/_+([a-z0-9])/g, (_, c) => c.toUpperCase());
+const pascal = (s) => {
+  const c = camel(s);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+};
+const ident = (s) => {
+  let c = camel(s) || "_";
+  if (/^[0-9]/.test(c)) c = `_${c}`;
+  return RESERVED.has(c) ? `${c}Table` : c;
+};
+const key = (s) => (/^[A-Za-z_$][\w$]*$/.test(s) ? s : JSON.stringify(s));
+
+const NUMBER = new Set(["smallint", "integer", "bigint", "real", "double precision", "numeric", "oid", "int2", "int4", "int8", "float4", "float8"]);
+const STRING_PREFIX = /^(?:text|uuid|character|char|varchar|citext|name|date|time|timestamp|interval|inet|cidr|macaddr|tsvector|tsquery|bytea|money|xml|bit|ltree|regclass|regproc|regtype|point|line|box|path|polygon|circle|int4range|int8range|tsrange|tstzrange|daterange|numrange|halfvec|vector|sparsevec)/;
+
+function tsType(t, enums) {
+  let base;
+  if (t.enum) base = (enums[t.enum] ?? []).map((v) => JSON.stringify(v)).join(" | ") || "string";
+  else if (NUMBER.has(t.type)) base = "number";
+  else if (t.type === "boolean") base = "boolean";
+  else if (t.type === "json" || t.type === "jsonb") base = "Json";
+  else if (t.type === "void") base = "undefined";
+  else if (STRING_PREFIX.test(t.type)) base = "string";
+  else base = "unknown";
+  return t.array ? (base.includes("|") ? `(${base})[]` : `${base}[]`) : base;
+}
+
+function tableTypes(P, t, enums) {
+  const reg = t.registry ?? null;
+  const excluded = new Set(reg?.clientExcludedColumns ?? []);
+  const readOnly = new Set(reg?.clientReadOnlyColumns ?? []);
+  const rowLines = [];
+  const insLines = [];
+  for (const c of t.columns) {
+    const ty = tsType(c, enums);
+    if (!excluded.has(c.name)) rowLines.push(`  ${key(c.name)}: ${ty}${c.nullable ? " | null" : ""};`);
+    if (t.kind !== "table" || c.generated || readOnly.has(c.name) || excluded.has(c.name)) continue;
+    const orgFilled = c.name === "organization_id" && (t.org.rule === "binding" || t.org.rule === "parent");
+    const optional = c.nullable || c.default || c.identity || orgFilled;
+    insLines.push(`  ${key(c.name)}${optional ? "?" : ""}: ${ty}${c.nullable ? " | null" : ""};`);
+  }
+  let out = `export interface ${P}Row {\n${rowLines.join("\n")}\n}\n`;
+  if (t.kind === "table") {
+    out += `export interface ${P}Insert {\n${insLines.join("\n")}\n}\nexport type ${P}Update = Partial<${P}Insert>;\n`;
+  } else {
+    out += `export type ${P}Insert = never;\nexport type ${P}Update = never;\n`;
+  }
+  return out;
+}
+
+function tableDescriptor(schema, name, t) {
+  const reg = t.registry ?? null;
+  const archive = t.lifecycle.archived_at ? "archived_at" : t.lifecycle.is_archived ? "is_archived" : null;
+  const flags = {
+    schema,
+    name,
+    kind: t.kind,
+    type: reg?.type ?? null,
+    pk: t.primaryKey,
+    org: t.org,
+    versioned: !!(reg ? reg.versioned && t.lifecycle.version : t.lifecycle.version),
+    softDelete: !!(reg ? reg.softDelete && t.lifecycle.deleted_at : t.lifecycle.deleted_at),
+    archive,
+    readOnly: !!reg?.clientReadOnly,
+    deletesRefused: !!reg?.clientDeletesRefused,
+    readOnlyColumns: reg?.clientReadOnlyColumns ?? [],
+    listScope: reg?.listScope ?? null,
+    realtime: (t.realtime ?? []).includes("supabase_realtime"),
+  };
+  return flags;
+}
+
+function fnTypes(P, overloads, enums) {
+  const shapes = [];
+  let result = "unknown";
+  for (const f of overloads) {
+    const inputs = f.args.filter((a) => a.mode === "in" || a.mode === "inout" || a.mode === "variadic");
+    if (inputs.some((a) => !a.name)) {
+      shapes.push("never /* positional arguments: PostgREST calls by name */");
+      continue;
+    }
+    shapes.push(inputs.length ? `{ ${inputs.map((a) => `${key(a.name)}${a.optional ? "?" : ""}: ${tsType(a, enums)}`).join("; ")} }` : "Record<string, never>");
+    const outs = f.args.filter((a) => a.mode === "table" || a.mode === "out" || a.mode === "inout");
+    let r;
+    if (outs.length && (f.returns.type === "record" || f.args.some((a) => a.mode === "table"))) {
+      r = `{ ${outs.map((a) => `${key(a.name || "value")}: ${tsType(a, enums)} | null`).join("; ")} }`;
+    } else r = tsType(f.returns, enums);
+    if (f.returns.set) r = r.startsWith("{") || !r.includes("|") ? `${r}[]` : `(${r})[]`;
+    result = r;
+  }
+  const args = [...new Set(shapes)];
+  return `export type ${P}Args = ${args.join(" | ")};\nexport type ${P}Result = ${result};\n`;
+}
+
+const HEADER = (schema, src, importFrom) => `/**
+ * GENERATED by \`matrx-data generate\` from the database description — never edit by hand.
+ * schema: ${schema} · description ${src.slice(0, 12)}
+ * Regenerate: matrx-data generate (see @ai-matrx/data README).
+ */
+/* eslint-disable */
+import type { FunctionDescriptor, TableDescriptor } from "${importFrom}";
+
+type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[];
+`;
+
+export function renderSchema(desc, schemaSha, importFrom) {
+  const { schema, tables, views, functions, enums } = desc;
+  const used = new Set();
+  const take = (base) => {
+    let n = base;
+    while (used.has(n)) n = `${n}_`;
+    used.add(n);
+    return n;
+  };
+  let out = HEADER(schema, schemaSha, importFrom);
+  const rels = [...Object.entries(tables), ...Object.entries(views)].sort(([a], [b]) => a.localeCompare(b));
+  for (const [name, t] of rels) {
+    const id = take(ident(name));
+    const P = pascal(id);
+    out += `\n${tableTypes(P, t, enums)}export const ${id} = ${JSON.stringify(tableDescriptor(schema, name, t))} as unknown as TableDescriptor<${P}Row, ${P}Insert, ${P}Update>;\n`;
+  }
+  for (const [name, overloads] of Object.entries(functions).sort(([a], [b]) => a.localeCompare(b))) {
+    let id = ident(name);
+    if (used.has(id)) id = `${id}Fn`;
+    id = take(id);
+    const P = pascal(id);
+    const roles = [...new Set(overloads.flatMap((f) => f.roles))].sort();
+    const fd = { schema, name, roles, registered: overloads.some((f) => f.registered) };
+    out += `\n${fnTypes(P, overloads, enums)}export const ${id} = ${JSON.stringify(fd)} as unknown as FunctionDescriptor<${P}Args, ${P}Result>;\n`;
+  }
+  return out;
+}
+
+export function renderFlagsIndex(descs, importFrom) {
+  const index = {};
+  for (const d of descs) for (const [name, t] of Object.entries({ ...d.tables, ...d.views })) index[`${d.schema}.${name}`] = tableDescriptor(d.schema, name, t);
+  return `/** GENERATED by \`matrx-data generate --flags-index\` — the flags of every table, for tableByName(). Never edit by hand. */
+/* eslint-disable */
+import type { FlagsIndex } from "${importFrom}";
+
+export const flagsIndex: FlagsIndex = ${JSON.stringify(index)} as unknown as FlagsIndex;
+`;
+}
+
+export function generate({ from, out, schemas, check, importFrom, flagsIndex = process.argv.includes("--flags-index") }) {
+  const index = JSON.parse(readFileSync(path.join(from, "index.json"), "utf8"));
+  const names = schemas?.length ? schemas : Object.keys(index.schemas).sort();
+  const files = {};
+  const descs = [];
+  for (const s of names) {
+    if (!index.schemas[s]) throw new Error(`schema "${s}" is not in the description (${Object.keys(index.schemas).length} schemas)`);
+    const desc = JSON.parse(readFileSync(path.join(from, `${s}.json`), "utf8"));
+    descs.push(desc);
+    files[`${s}.ts`] = renderSchema(desc, index.schemas[s].sha256, importFrom);
+  }
+  if (flagsIndex) files["flags-index.ts"] = renderFlagsIndex(descs, importFrom);
+  if (check) {
+    const stale = Object.entries(files).filter(([n, t]) => !existsSync(path.join(out, n)) || readFileSync(path.join(out, n), "utf8") !== t).map(([n]) => n);
+    if (stale.length) {
+      console.error(`matrx-data generate --check: stale against the description: ${stale.join(", ")}`);
+      return 1;
+    }
+    console.log(`matrx-data generate --check: ${Object.keys(files).length} file(s) current (contract ${index.contractSha256.slice(0, 12)})`);
+    return 0;
+  }
+  mkdirSync(out, { recursive: true });
+  for (const [n, t] of Object.entries(files)) writeFileSync(path.join(out, n), t);
+  console.log(`matrx-data generate: ${Object.keys(files).join(", ")} → ${out} (contract ${index.contractSha256.slice(0, 12)})`);
+  return 0;
+}