@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-plan.ts

@@ -0,0 +1,245 @@
+/**
+ * The repair plan: the statement list a reconcile executes, as one pure function of the
+ * declared grant set and the live catalogs — no client, no `Effect` — so `reconcile`, the
+ * engine's `diff` and the tests share one implementation (the family's S10 rule holds at
+ * the callers: `reconcile` re-reads live after the statements run, and re-plans: an EMPTY
+ * plan is the no-op proof). The read-back projection and the plan-time comparison live in
+ * `grants-diff.ts`.
+ *
+ * ★ REPAIR SHAPE PER CLASS: on drift, `REVOKE ALL` (clears extras and grant options) then
+ *   `GRANT` the declared words (only when any are declared), split by the grant-option
+ *   flag. A class that declares nothing and holds nothing live is a no-op; a class that
+ *   declares nothing but holds live grants gets only the revoke — that is how `delete`
+ *   (a cleared declaration, `grants-declare.ts`) revokes exactly what the old declaration
+ *   named. The one thing it restores is the collateral a table `REVOKE ALL` clears on
+ *   columns the declaration never named (see `restoredColumnGrants` below): a delete takes
+ *   away what it managed and leaves a DBA's or another resource's column grant untouched.
+ * ★ OBJECTS THE DECLARED ROLE OWNS ARE LEFT ALONE (H2): an owner holds every privilege
+ *   implicitly and a `REVOKE` cannot take that away, so both plans skip owned objects —
+ *   repairing them would only add ACL rows the state can never converge on, and revoking
+ *   them would strip rights that existed before the resource (measured on PG 18.6: the
+ *   docs' own seat example had its owner rights churned). The projection
+ *   (`grants-diff.ts`) records the ownership facts so the plan-time diff skips the same
+ *   objects.
+ * ★ A TABLE'S `REVOKE ALL` ALSO CLEARS THAT GRANTEE'S COLUMN ENTRIES ON IT (measured on
+ *   PG 18.6, and cited by the resource's own convergence check): every declared column of
+ *   a table whose revoke this plan emits is therefore planned against an empty column
+ *   set, so the declared words are re-granted after the table revoke in the SAME pass —
+ *   without this, the re-read would answer drift and the repair would refuse.
+ */
+import type { DeclaredGrants } from './grants-declare.ts';
+import { splitGrantWords } from './grants-declare.ts';
+import type { LiveGrants } from './grants-read.ts';
+import { removalRevokes } from './grants-plan-restore.ts';
+import { relkindIsPublicRevocable } from './grants-words.ts';
+import {
+  grantColumnSql,
+  grantDefaultSql,
+  grantSchemaSql,
+  grantTableSql,
+  revokeColumnSql,
+  revokeDefaultSql,
+  revokePublicSchemaSql,
+  revokePublicTablesSql,
+  revokeSchemaSql,
+  revokeTableSql,
+} from './grants-sql.ts';
+
+/** Both sides are sorted by construction (declared by `cleanWords`, live by the reads), so
+ * set equality is positional — grant-option marks included: `select` and `select*` are
+ * DIFFERENT states and the repair must converge on the declared one. */
+export const wordsDiffer = (
+  declared: ReadonlyArray<string>,
+  live: ReadonlyArray<string>,
+): boolean =>
+  declared.length !== live.length || declared.some((word, index) => word !== live[index]);
+
+const grantStatements = (
+  words: ReadonlyArray<string>,
+  grant: (words: ReadonlyArray<string>) => string,
+): ReadonlyArray<string> => {
+  const { plain, grantable } = splitGrantWords(words);
+  return [
+    ...(plain.length > 0 ? [grant(plain)] : []),
+    ...(grantable.length > 0 ? [grant(grantable)] : []),
+  ];
+};
+
+export const liveTableWords = (live: LiveGrants, table: string): ReadonlyArray<string> =>
+  live.tables.find((entry) => entry.table === table)?.role ?? [];
+
+export const liveColumnWords = (
+  live: LiveGrants,
+  table: string,
+  column: string,
+): ReadonlyArray<string> =>
+  live.columns.find((entry) => entry.table === table && entry.column === column)?.role ?? [];
+
+export const liveDefaultWords = (live: LiveGrants, forRole: string): ReadonlyArray<string> =>
+  live.defaults.find((entry) => entry.forRole === forRole)?.role ?? [];
+
+const columnKey = (table: string, column: string): string => `${table}\u0000${column}`;
+
+/** Re-grant the column entries a table `REVOKE ALL` cleared that the declaration does
+ * not name. Only `restorable` words: revoke.sgml@REL_18_6, a role revokes grants it made,
+ * and a superuser's REVOKE is performed as the owner — a third grantor's entry survives,
+ * and granting it again would add an owner grant on top of that one. */
+const restoredColumnGrants = (
+  declared: DeclaredGrants,
+  live: LiveGrants,
+  table: string,
+  skip: ReadonlySet<string>,
+): ReadonlyArray<string> => {
+  const statements: string[] = [];
+  for (const column of live.columns) {
+    if (column.table !== table || skip.has(columnKey(column.table, column.column))) continue;
+    if (column.restorable.length === 0) continue;
+    statements.push(
+      ...grantStatements(column.restorable, (words) =>
+        grantColumnSql(declared.schema, column.table, column.column, declared.role, words),
+      ),
+    );
+  }
+  return statements;
+};
+
+/** Every statement the repair runs, in order. Classes whose live set already equals the
+ * declared one contribute NOTHING — an already-correct declaration emits zero statements,
+ * which is the re-run-is-a-no-op rule; the same function re-planned against the post-repair
+ * read-back is the convergence proof (`PostgresGrantsRepairRefused` when it is not empty). */
+export const planRepair = (
+  declared: DeclaredGrants,
+  live: LiveGrants,
+  prior: {
+    /** Tables whose `REVOKE ALL` this same plan already emits (an update removed them). */
+    readonly revokedTables?: ReadonlyArray<string>;
+    /** Columns that removal is revoking on purpose — do not restore them. */
+    readonly revokedColumns?: ReadonlyArray<{ readonly table: string; readonly column: string }>;
+  } = {},
+): ReadonlyArray<string> => {
+  const statements: string[] = [];
+  const ownedTables = new Set(live.ownedTables);
+  if (!live.schemaOwnedByRole && wordsDiffer(declared.schemaPrivileges, live.schema.role)) {
+    statements.push(revokeSchemaSql(declared.schema, declared.role));
+    statements.push(
+      ...grantStatements(declared.schemaPrivileges, (words) =>
+        grantSchemaSql(declared.schema, declared.role, words),
+      ),
+    );
+  }
+  // A table whose REVOKE is emitted ALSO loses the grantee's column privileges on it
+  // (the header's measured rule) — the ones the revoking role or the owner made
+  // (`restoredColumnGrants`). Declared columns of such a table are planned against an
+  // empty column set. Undeclared entries the revoke clears are re-granted in the same
+  // plan, including tables an update removed (`prior.revokedTables`): those revokes are
+  // planned offline with this repair so they can share one transaction.
+  const revokedTables = new Set(prior.revokedTables ?? []);
+  const skipColumns = new Set([
+    ...declared.columns.map((column) => columnKey(column.table, column.column)),
+    ...(prior.revokedColumns ?? []).map((column) => columnKey(column.table, column.column)),
+  ]);
+  const declaredTableNames = new Set(declared.tables.map((table) => table.table));
+  for (const table of declared.tables) {
+    if (ownedTables.has(table.table)) continue;
+    if (wordsDiffer(table.privileges, liveTableWords(live, table.table))) {
+      revokedTables.add(table.table);
+      statements.push(revokeTableSql(declared.schema, table.table, declared.role));
+      statements.push(
+        ...grantStatements(table.privileges, (words) =>
+          grantTableSql(declared.schema, table.table, declared.role, words),
+        ),
+      );
+      statements.push(...restoredColumnGrants(declared, live, table.table, skipColumns));
+    }
+  }
+  for (const table of prior.revokedTables ?? []) {
+    if (declaredTableNames.has(table) || ownedTables.has(table)) continue;
+    statements.push(...restoredColumnGrants(declared, live, table, skipColumns));
+  }
+  for (const column of declared.columns) {
+    if (ownedTables.has(column.table)) continue;
+    const liveWords = revokedTables.has(column.table)
+      ? []
+      : liveColumnWords(live, column.table, column.column);
+    if (wordsDiffer(column.privileges, liveWords)) {
+      statements.push(revokeColumnSql(declared.schema, column.table, column.column, declared.role));
+      statements.push(
+        ...grantStatements(column.privileges, (words) =>
+          grantColumnSql(declared.schema, column.table, column.column, declared.role, words),
+        ),
+      );
+    }
+  }
+  for (const entry of declared.defaults) {
+    if (wordsDiffer(entry.privileges, liveDefaultWords(live, entry.forRole))) {
+      statements.push(revokeDefaultSql(declared.schema, entry.forRole, declared.role));
+      statements.push(
+        ...grantStatements(entry.privileges, (words) =>
+          grantDefaultSql(declared.schema, entry.forRole, declared.role, words),
+        ),
+      );
+    }
+  }
+  if (declared.publicSchemaRevoked && live.schema.public.length > 0) {
+    statements.push(revokePublicSchemaSql(declared.schema));
+  }
+  // The PUBLIC-tables check is scoped to the relkinds the bulk revoke actually reaches:
+  // a PUBLIC grant on a SEQUENCE in the schema survives `REVOKE ALL ON ALL TABLES IN
+  // SCHEMA` (measured on PG 18.6), so counting it would refuse to converge forever.
+  if (
+    declared.publicTablesRevoked &&
+    (live.tables.some(
+      (table) => relkindIsPublicRevocable(table.relkind) && table.public.length > 0,
+    ) ||
+      live.columns.some((column) => column.public.length > 0))
+  ) {
+    statements.push(revokePublicTablesSql(declared.schema));
+  }
+  return statements;
+};
+
+/** Revoke-only statements for the entries an update REMOVED from the declaration: one
+ * `REVOKE ALL` per removed object where the catalogs still show the role's words, so
+ * taking an entry away takes the privilege away (a removal is a drift this resource
+ * repairs, never a silent retention). Never the schema class (a role/database/schema
+ * retarget is refused, so the schema can never gain or lose an entry), never PUBLIC,
+ * never a grant, never an object the role OWNS (an owner's implicit rights are not this
+ * resource's to revoke), and nothing for an object that no longer exists — it shows no
+ * words. */
+export const planRevocations = (
+  removed: Pick<DeclaredGrants, 'schema' | 'role' | 'tables' | 'columns' | 'defaults'>,
+  live: LiveGrants,
+): ReadonlyArray<string> => {
+  const statements: string[] = [];
+  const revoked = removalRevokes(removed, live);
+  for (const table of revoked.tables) {
+    statements.push(revokeTableSql(removed.schema, table, removed.role));
+  }
+  for (const column of revoked.columns) {
+    statements.push(revokeColumnSql(removed.schema, column.table, column.column, removed.role));
+  }
+  for (const entry of removed.defaults) {
+    if (liveDefaultWords(live, entry.forRole).length > 0) {
+      statements.push(revokeDefaultSql(removed.schema, entry.forRole, removed.role));
+    }
+  }
+  return statements;
+};
+
+/** Removal revokes and the new declaration's repair, planned against one read. Removed
+ * tables count as revoked inside `planRepair`, so the column re-grants that follow a
+ * table `REVOKE ALL` are in this list — the caller runs it as one transaction. */
+export const planReconcile = (
+  declared: DeclaredGrants,
+  live: LiveGrants,
+  removed: Pick<DeclaredGrants, 'schema' | 'role' | 'tables' | 'columns' | 'defaults'> | undefined,
+): ReadonlyArray<string> => {
+  const revoked = removed === undefined ? undefined : removalRevokes(removed, live);
+  return [
+    ...(removed !== undefined ? planRevocations(removed, live) : []),
+    ...planRepair(declared, live, {
+      revokedTables: revoked?.tables ?? [],
+      revokedColumns: removed?.columns ?? [],
+    }),
+  ];
+};

package/src/postgres/grants-provenance.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Provenance for `Postgres.Grants`: every vocabulary traces to a real constant in the
+ * committed `acl.h@REL_18_6` excerpt, the column vocabulary to the GRANT synopsis' own
+ * column form, the default-privileges shape to the ALTER DEFAULT PRIVILEGES synopsis, the
+ * read path to `aclexplode`'s documented row — and every object class the family does NOT
+ * express is named with a reason. Both directions fail on a fixture edit (S38).
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  COLUMN_PRIVILEGES,
+  SCHEMA_PRIVILEGES,
+  TABLE_PRIVILEGES,
+  letterForPrivilege,
+} from './grants-attrs.ts';
+
+const FIXTURES = join(import.meta.dir, 'fixtures');
+const aclHeader = readFileSync(join(FIXTURES, 'pg-REL_18_6-acl.h.txt'), 'utf8');
+const grantSynopsis = readFileSync(join(FIXTURES, 'pg-REL_18_6-grant-synopsis.txt'), 'utf8');
+const defaultSynopsis = readFileSync(
+  join(FIXTURES, 'pg-REL_18_6-alter-default-privileges-synopsis.txt'),
+  'utf8',
+);
+const explodeFunc = readFileSync(join(FIXTURES, 'pg-REL_18_6-aclexplode-func.txt'), 'utf8');
+const defaultAclHeader = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_default_acl.h.txt'), 'utf8');
+
+const ACL_BLOB = '13bb8128747139d9cae66777e4782359ead0a760';
+
+/** Pull each `#define ACL_<PRIVILEGE>_CHR '<letter>'` constant out of the committed acl.h. */
+const aclLetter = (name: string): string => {
+  const m = new RegExp(`#define ACL_${name}_CHR\\s+'(.)'`).exec(aclHeader);
+  if (m === null) throw new Error(`no ACL_${name}_CHR in the committed acl.h excerpt`);
+  return m[1] as string;
+};
+
+const WORD_LETTER: Readonly<Record<string, string>> = {
+  insert: 'INSERT',
+  select: 'SELECT',
+  update: 'UPDATE',
+  delete: 'DELETE',
+  truncate: 'TRUNCATE',
+  references: 'REFERENCES',
+  trigger: 'TRIGGER',
+  maintain: 'MAINTAIN',
+  usage: 'USAGE',
+  create: 'CREATE',
+};
+
+describe('grants provenance', () => {
+  test('the acl.h excerpt is the pinned REL_18_6 blob', () => {
+    expect(aclHeader).toContain(ACL_BLOB);
+    expect(aclHeader).toContain('src/include/utils/acl.h');
+    expect(explodeFunc).toContain('aclexplode');
+    expect(explodeFunc).toContain('is_grantable');
+  });
+
+  test('every table word maps to the acl.h letter the server really stores', () => {
+    for (const privilege of TABLE_PRIVILEGES) {
+      expect(letterForPrivilege(privilege)).toBe(aclLetter(WORD_LETTER[privilege] as string));
+    }
+  });
+
+  test('schema and column words too, CREATE above the lowercase CONNECT trap', () => {
+    for (const privilege of SCHEMA_PRIVILEGES) {
+      expect(letterForPrivilege(privilege)).toBe(aclLetter(WORD_LETTER[privilege] as string));
+    }
+    for (const privilege of COLUMN_PRIVILEGES) {
+      expect(letterForPrivilege(privilege)).toBe(aclLetter(WORD_LETTER[privilege] as string));
+    }
+    expect(aclLetter('CREATE')).toBe('C');
+  });
+
+  test('the column vocabulary is exactly the GRANT synopsis column form (table-wide only excluded)', () => {
+    expect(grantSynopsis).toContain(
+      'GRANT { { SELECT | INSERT | UPDATE | REFERENCES } ( <replaceable class="parameter">column_name</replaceable>',
+    );
+    expect([...COLUMN_PRIVILEGES]).toEqual(['select', 'insert', 'update', 'references']);
+    for (const tableWideOnly of ['truncate', 'trigger', 'maintain']) {
+      expect(COLUMN_PRIVILEGES.includes(tableWideOnly as never)).toBe(false);
+    }
+  });
+
+  test('the table vocabulary is the relation grant form of the synopsis', () => {
+    expect(grantSynopsis).toContain(
+      'GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }',
+    );
+    expect([...TABLE_PRIVILEGES]).toEqual([
+      'select',
+      'insert',
+      'update',
+      'delete',
+      'truncate',
+      'references',
+      'trigger',
+      'maintain',
+    ]);
+  });
+
+  test('default privileges are FOR ROLE per creator, ON TABLES, defaclobjtype r', () => {
+    // The synopsis wraps the FOR ROLE clause onto its own line, so assert on that line.
+    expect(defaultSynopsis).toContain(
+      '[ FOR { ROLE | USER } <replaceable>target_role</replaceable>',
+    );
+    expect(defaultSynopsis).toContain('ON TABLES');
+    expect(defaultAclHeader).toContain('DEFACLOBJ_RELATION');
+    expect(defaultAclHeader).toMatch(/#define\s+DEFACLOBJ_RELATION\s+'r'/);
+  });
+
+  test('aclexplode is the read path: one row per privilege, PUBLIC at grantee zero', () => {
+    expect(explodeFunc).toContain('<parameter>privilege_type</parameter> <type>text</type>');
+    expect(explodeFunc).toContain('pseudo-role PUBLIC');
+  });
+});
+
+/** Every GRANT synopsis line this family does NOT express, and why. */
+describe('out of scope', () => {
+  const notModelled: Readonly<Record<string, string>> = {
+    SEQUENCE:
+      'sequences are relations the same ON statement reaches, but no sequence word set is declared',
+    FUNCTION:
+      'routine privileges (EXECUTE) are a different vocabulary (ACL_ALL_RIGHTS_FUNCTION); no declaration shape',
+    DATABASE:
+      'ALTER DATABASE privileges are cluster-level, not one schema\u2019s grant set; the docs name the boundary',
+    LARGE: 'large objects (b/r in acl.h) have no declaration shape and no schema container',
+    TYPE: 'types are granted through USAGE on the type, deferred until a consumer needs it',
+  };
+  test('named with a reason, so a future vocabulary must answer one', () => {
+    for (const [name, reason] of Object.entries(notModelled)) {
+      expect(reason.length).toBeGreaterThan(10);
+      expect(grantSynopsis).toContain(name);
+    }
+  });
+});

package/src/postgres/grants-psql-lifecycle.test.ts

@@ -0,0 +1,105 @@
+/**
+ * The grants lifecycle over `makePsqlExecutor`, whose parameter rule the in-memory fake
+ * does not share: only strings are inlined (`psql-executor.ts`). An existence check that
+ * binds a JS array fails here with "param $2 must be a string" on every reconcile that
+ * names a table or column — the transport CT100 actually uses.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PsqlRunner } from './psql-executor.ts';
+import { makePsqlExecutor } from './psql-executor.ts';
+import { reconcileWithClient } from './grants-ops.ts';
+import { requireDeclaredObjectsExist } from './grants-existence.ts';
+import { resolveProps } from './grants-declare.ts';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+
+const props: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  tables: [{ table: 'a.b', privileges: ['select'] }],
+  columnGrants: [{ table: 'a.b', column: 'c', privileges: ['select'] }],
+};
+
+/** Answers by SQL text. `granted` flips when the repair's `BEGIN` script is seen, so the
+ * convergence re-read reports the privileges that script would have written. */
+const runner = (): { run: PsqlRunner; stdins: string[] } => {
+  const stdins: string[] = [];
+  let granted = false;
+  const run: PsqlRunner = ({ stdin }) => {
+    stdins.push(stdin);
+    if (stdin.startsWith('BEGIN')) granted = true;
+    return Promise.resolve({ code: 0, stdout: answer(stdin, granted), stderr: '' });
+  };
+  return { run, stdins };
+};
+
+const answer = (stdin: string, granted: boolean): string => {
+  if (stdin.includes('current_database()')) return '[{"database":"agents"}]';
+  if (stdin.includes('json_array_elements_text')) return '[{"table":"a"},{"table":"a.b"}]';
+  if (stdin.includes('json_array_elements')) {
+    return '[{"table":"a","column":"b.c"},{"table":"a.b","column":"c"}]';
+  }
+  if (stdin.includes('SELECT 1 AS present FROM pg_roles')) return '[{"present":1}]';
+  if (stdin.includes('SELECT 1 AS present FROM pg_namespace')) return '[{"present":1}]';
+  if (stdin.includes('aclexplode(n.nspacl)')) {
+    return granted ? '[{"public":false,"privilege":"usage","grantable":false}]' : '[]';
+  }
+  if (stdin.includes('aclexplode(c.relacl)')) {
+    return granted
+      ? '[{"table":"a.b","relkind":"r","public":false,"privilege":"select","grantable":false}]'
+      : '[]';
+  }
+  if (stdin.includes('aclexplode(v.attacl)')) {
+    return granted
+      ? '[{"table":"a.b","column":"c","public":false,"privilege":"select","grantable":false,"grantor":"postgres","owner":"postgres","revoker":"postgres"}]'
+      : '[]';
+  }
+  if (stdin.includes('aclexplode(d.defaclacl)')) return '[]';
+  if (stdin.includes('nspowner')) return '[{"role_owns":false}]';
+  if (stdin.includes('relowner')) return '[]';
+  return '';
+};
+
+describe('grants lifecycle over the psql executor', () => {
+  test('existence parameters are one JSON string, and the repair is one BEGIN script', async () => {
+    const { run, stdins } = runner();
+    const pg = makePsqlExecutor(run, { database: 'agents', username: 'postgres' });
+    const attrs = await Effect.runPromise(reconcileWithClient(pg, props, undefined));
+    expect(attrs.tables).toEqual([{ table: 'a.b', privileges: ['select'] }]);
+    expect(attrs.columns).toEqual([{ table: 'a.b', column: 'c', privileges: ['select'] }]);
+    const existence = stdins.filter((stdin) => stdin.includes('json_array_elements'));
+    expect(existence.length).toBeGreaterThan(0);
+    // Pairs, not a concatenated `a.b.c`: table `a.b` + column `c` stays two JSON elements.
+    expect(existence.some((stdin) => stdin.includes('["a.b","c"]'))).toBe(true);
+    expect(existence.some((stdin) => stdin.includes('||'))).toBe(false);
+    const script = stdins.find((stdin) => stdin.startsWith('BEGIN'));
+    expect(script).toContain('COMMIT');
+    expect(script).toContain('REVOKE ALL ON "app"."a.b" FROM "seat_writer"');
+    expect(script).toContain('GRANT select ("c") ON "app"."a.b" TO "seat_writer"');
+  });
+
+  test('a dotted table and a dotted column are separate JSON pairs', async () => {
+    const { run, stdins } = runner();
+    const pg = makePsqlExecutor(run, { database: 'agents', username: 'postgres' });
+    await Effect.runPromise(
+      requireDeclaredObjectsExist(
+        pg,
+        resolveProps({
+          ...props,
+          tables: [
+            { table: 'a.b', privileges: ['select'] },
+            { table: 'a', privileges: ['select'] },
+          ],
+          columnGrants: [
+            { table: 'a.b', column: 'c', privileges: ['select'] },
+            { table: 'a', column: 'b.c', privileges: ['select'] },
+          ],
+        }),
+      ),
+    );
+    const columns = stdins.find((stdin) => stdin.includes('x->>1'));
+    expect(columns).toContain('["a.b","c"]');
+    expect(columns).toContain('["a","b.c"]');
+  });
+});

package/src/postgres/grants-read-absent.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The two faces of `read`'s ABSENT answer, replayed against the fake server model: a
+ * target that holds nothing and has NO stored output reads as absent (that is a first
+ * create, never the adoption of an empty schema — H1), while the same all-empty catalog on
+ * the update path — the resource already has applied state — is a real projection (the
+ * grantee may own everything outright, so `aclexplode` has no rows), so `read` must not
+ * flip the next apply back into a first create. Extracted from
+ * `grants-lifecycle-guards.test.ts` to keep both files under the code-size cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeGrants } from './fake-grants-sql.ts';
+import { readWithClient } from './grants-ops.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+
+/** The seat model: `notes` (with its column) and its catalog are the seat's OWN objects;
+ * `shared` is someone else's. The schema is still owned by the executor. */
+const ownedCatalog = {
+  schemas: ['app'],
+  roles: ['postgres', 'seat_writer'],
+  tables: [
+    { schema: 'app', table: 'notes', owner: 'seat_writer', columns: ['id'] },
+    { schema: 'app', table: 'shared' },
+  ],
+};
+
+describe('read: an empty target is absent', () => {
+  test('answers undefined when the role holds nothing anywhere', async () => {
+    const fake = makeFakeGrants(ownedCatalog);
+    const live = await run(
+      readWithClient(
+        fake,
+        {
+          role: 'seat_writer',
+          database: 'agents',
+          schema: 'app',
+          tables: ['notes', 'shared'],
+          columns: [{ table: 'notes', column: 'id' }],
+          defaults: [],
+        },
+        false,
+      ),
+    );
+    // A first create, never an adoption of an empty schema: only grants mark the target
+    // as live, so the stack declares this grant set with adopt(true) when it is already
+    // applied and without it on a first deploy.
+    expect(live).toBeUndefined();
+  });
+
+  test('answers the projection when stored output exists and the role holds nothing', async () => {
+    const fake = makeFakeGrants(ownedCatalog);
+    const live = await run(
+      readWithClient(
+        fake,
+        {
+          role: 'seat_writer',
+          database: 'agents',
+          schema: 'app',
+          tables: ['notes', 'shared'],
+          columns: [{ table: 'notes', column: 'id' }],
+          defaults: [],
+        },
+        true,
+      ),
+    );
+    // The update path: the resource already has applied state, so an all-empty read is a
+    // real answer — the grantee owns everything outright and `aclexplode` has no rows —
+    // not an absent target. Answering undefined here would flip the next apply into a
+    // first create. The projection still names the declared objects with empty word
+    // lists, the way the reconcile's output does for owned tables.
+    expect(live).toEqual({
+      role: 'seat_writer',
+      database: 'agents',
+      schema: 'app',
+      schemaOwnedByRole: false,
+      schemaPrivileges: [],
+      tables: [
+        { table: 'notes', privileges: [] },
+        { table: 'shared', privileges: [] },
+      ],
+      columns: [{ table: 'notes', column: 'id', privileges: [] }],
+      defaults: [],
+      // PUBLIC holds no rows at all in this all-empty ACL, so both revoked flags answer
+      // true: the projection reports the absence the same way reconcile's output does.
+      publicSchemaRevoked: true,
+      publicTablesRevoked: true,
+      ownedTables: ['notes'],
+    });
+  });
+});

package/src/postgres/grants-read-defaults.ts

@@ -0,0 +1,51 @@
+/**
+ * The default-privilege half of the grants read: what `pg_default_acl` says the declared
+ * role receives on relations (`defaclobjtype = 'r'`, the only object type this family
+ * declares — `pg_default_acl.h@REL_18_6#DEFACLOBJ_RELATION`) created in the schema,
+ * whatever role created the entry. Extracted from `grants-read.ts` so that file stays
+ * under the 250-line cap; the read still goes through `aclexplode` (see that file's
+ * header for the doctrine), never the `aclitem` text.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { type AclRow, encodeWord } from './grants-words.ts';
+
+/** One row per default-privilege entry on relations in the schema, with the declared
+ * role's words, whatever role created the entry. Sorted by forRole so two reads of the
+ * same state compare equal. */
+const DEFAULTS_SQL = `SELECT
+    pg_get_userbyid(d.defaclrole) AS for_role,
+    a.privilege_type AS privilege,
+    a.is_grantable AS grantable
+  FROM pg_default_acl d
+  CROSS JOIN LATERAL aclexplode(d.defaclacl) AS a
+  WHERE d.defaclnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    AND d.defaclobjtype = 'r'
+    AND a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2)
+  ORDER BY for_role`;
+
+export interface LiveDefault {
+  readonly forRole: string;
+  readonly role: ReadonlyArray<string>;
+}
+
+export const readDefaultAcls = (
+  pg: PgExecutor,
+  schema: string,
+  role: string,
+): Effect.Effect<ReadonlyArray<LiveDefault>, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly for_role: string } & AclRow>(DEFAULTS_SQL, [schema, role]),
+    (rows) => {
+      const byRole = new Map<string, string[]>();
+      for (const row of rows) {
+        const words = byRole.get(row.for_role) ?? [];
+        words.push(encodeWord(row));
+        byRole.set(row.for_role, words);
+      }
+      return [...byRole.entries()]
+        .map(([forRole, words]) => ({ forRole, role: [...new Set(words)].sort() }))
+        .sort((a, b) => a.forRole.localeCompare(b.forRole));
+    },
+  );