@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-attrs.ts

@@ -0,0 +1,185 @@
+/**
+ * `Postgres.Grants`' declared shapes: the three privilege vocabularies (schema, table,
+ * column), the ACL letters `aclitem` text stores them as, and the props/attributes surfaces.
+ *
+ * ⛔ NO SUPERUSER-ISH OPTION EXISTS HERE BY CONSTRUCTION. This resource's only vocabularies
+ *   are `CREATE`/`USAGE` (schemas) and the table/column sets below — none of the server's
+ *   other object classes, and no role membership, ownership, `SUPERUSER`, `CREATEROLE`,
+ *   `BYPASSRLS` or parameter right is expressible. `docs/postgres-grants.md#scope` documents
+ *   what that means operationally: an object's OWNER (or a superuser) holds everything
+ *   regardless of ACL rows, and this resource cannot make anyone an owner.
+ * ★ EVERY VOCABULARY IS BACKED BY THE GRANT SYNTAX AT REL_18_6. The table set is
+ *   `ACL_ALL_RIGHTS_RELATION` and the schema set is `ACL_ALL_RIGHTS_SCHEMA` (both
+ *   `acl.h@REL_18_6`, asserted in `grants-provenance.test.ts`); the column set is
+ *   `ACL_ALL_RIGHTS_COLUMN` and the column synopsis (`grant.sgml@REL_18_6`):
+ *   `GRANT { { SELECT | INSERT | UPDATE | REFERENCES } ( column_name … )` — `TRUNCATE`,
+ *   `TRIGGER` and `MAINTAIN` are table-wide only, so they are refused for a column.
+ * ⛔ WORDS ARE STORED LOWERCASE, LETTERS ARE THE SERVER'S. Attributes carry privilege
+ *   WORDS (`"select"`, `"select*"` — trailing `*` marks WITH GRANT OPTION, exactly the mark
+ *   the server records as `is_grantable`), never ACL letters: a persisted state file must
+ *   read as what was declared, and the letter↔word map lives only in code against `acl.h`'s
+ *   `ACL_*_CHR` defines (pinned by `grants-acl.test.ts`).
+ */
+import { POSTGRES_NAME_MAX_BYTES, utf8ByteLength } from './database-attrs.ts';
+
+/** Every schema privilege `GRANT … ON SCHEMA` accepts at REL_18_6 (`ACL_ALL_RIGHTS_SCHEMA`).
+ * `CREATE` lets the role create objects IN the schema; `USAGE` lets it use objects already
+ * there. `schemaUsage` defaults true (a role declared into a schema it cannot even resolve
+ * is almost always a mistake), `schemaCreate` defaults false (create is a real power). */
+export const SCHEMA_PRIVILEGES = ['usage', 'create'] as const;
+export type SchemaPrivilege = (typeof SCHEMA_PRIVILEGES)[number];
+
+/** Every table privilege `GRANT … ON TABLE` accepts at REL_18_6
+ * (`ACL_ALL_RIGHTS_RELATION`). Views are relations with these same letters. */
+export const TABLE_PRIVILEGES = [
+  'select',
+  'insert',
+  'update',
+  'delete',
+  'truncate',
+  'references',
+  'trigger',
+  'maintain',
+] as const;
+export type TablePrivilege = (typeof TABLE_PRIVILEGES)[number];
+
+/** Every column privilege the column synopsis accepts at REL_18_6
+ * (`ACL_ALL_RIGHTS_COLUMN`) — the intersection of the table set with what a single column
+ * can carry, measured from `grant.sgml`'s own column form, asserted in
+ * `grants-provenance.test.ts`. */
+export const COLUMN_PRIVILEGES = ['select', 'insert', 'update', 'references'] as const;
+export type ColumnPrivilege = (typeof COLUMN_PRIVILEGES)[number];
+
+/** Every word across the three vocabularies — the superset the statement builders
+ * (`grants-sql.ts`) validate each privilege against before it ever reaches a `GRANT`
+ * clause, so a word that no class declares can never be concatenated into SQL. */
+export const ALL_GRANT_WORDS: ReadonlyArray<string> = [...SCHEMA_PRIVILEGES, ...TABLE_PRIVILEGES];
+
+/** The `ACL_*_CHR` letters (`acl.h@REL_18_6`, lines 103-115 of the committed excerpt),
+ * `_CHR` define name split into the word this family declares and the letter the server
+ * stores. ⚠️ CASE IS MEANINGFUL: `C` is CREATE (schemas, the uppercase one) while `c` is
+ * CONNECT (databases) — two different rights, and this map is the one place that knows. */
+const LETTER_FOR_PRIVILEGE: Readonly<Record<string, string>> = {
+  insert: 'a',
+  select: 'r',
+  update: 'w',
+  delete: 'd',
+  truncate: 'D',
+  references: 'x',
+  trigger: 't',
+  maintain: 'm',
+  usage: 'U',
+  create: 'C',
+};
+
+export const letterForPrivilege = (word: string): string => {
+  const letter = LETTER_FOR_PRIVILEGE[word];
+  if (letter === undefined) throw new Error(`grants-attrs: no ACL letter for "${word}"`);
+  return letter;
+};
+
+/** One declared table grant. `privileges` holds words; a trailing `*` on a word means
+ * WITH GRANT OPTION for that privilege. Default privileges (for future tables) are a
+ * separate prop — this one never touches `pg_default_acl`. */
+export interface PostgresGrantsTable {
+  readonly table: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+/** One declared column grant, from the synopsis' own column form:
+ * `GRANT … ON TABLE t ( c )` (`grant.sgml@REL_18_6`). */
+export interface PostgresGrantsColumn {
+  readonly table: string;
+  readonly column: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+/** One declared default-privileges entry. PostgreSQL records one
+ * `pg_default_acl` row per (defaclrole, defaclnamespace, defaclobjtype); `forRole` is the
+ * role whose FUTURE objects get the privilege (`FOR ROLE <target_role>` in
+ * `ALTER DEFAULT PRIVILEGES`) and is REQUIRED — the resource never infers the connecting
+ * role, so every entry reads back as exactly the role it names. The privileges apply to
+ * future TABLES (DEFACLOBJ_RELATION `'r'`, the only objtype this family writes). */
+export interface PostgresGrantsDefault {
+  readonly forRole: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+/** The declared grant set: one role, in one schema of one database.
+ *
+ * `role` is a group role a human owns the membership of — roles come from elsewhere (the
+ * operator, or a role resource in this family once one lands); this resource only writes
+ * ACL rows. `database` names the cluster-side database the statements run IN — never
+ * `ALTER DATABASE` privileges, which this family does not issue — and `reconcile` refuses
+ * a declaration whose `database` differs from the one the connection actually opened. `revokeFromPublic` strips PUBLIC's default USAGE on schema `public`
+ * and any default SELECT that might exist (PG15 stopped granting PUBLIC CREATE on `public`,
+ * `ddl.sgml@REL_15_1`; PostgreSQL never grants PUBLIC SELECT on tables by default).
+ */
+export interface PostgresGrantsProps {
+  readonly role: string;
+  readonly database: string;
+  readonly schema: string;
+  /** `GRANT USAGE ON SCHEMA` (`pg_namespace.nspacl`). @default true */
+  readonly schemaUsage?: boolean;
+  /** `GRANT CREATE ON SCHEMA` (`pg_namespace.nspacl`). @default false */
+  readonly schemaCreate?: boolean;
+  readonly tables?: ReadonlyArray<PostgresGrantsTable>;
+  readonly columnGrants?: ReadonlyArray<PostgresGrantsColumn>;
+  readonly defaultPrivileges?: ReadonlyArray<PostgresGrantsDefault>;
+  /** `REVOKE ALL ON SCHEMA/ALL TABLES IN SCHEMA FROM PUBLIC` (ddl.sgml: an empty grantee
+   * stands for PUBLIC). @default false */
+  readonly revokeFromPublic?: boolean;
+}
+
+/** Live attributes, read back from the catalogs after reconcile. Arrays are sorted
+ * (schema tables, then columns) so a persisted state file compares stably, and every word
+ * set is restricted to the objects THIS declaration names (see `attributesOf` in
+ * `grants-plan.ts`). `publicSchemaRevoked`/`publicTablesRevoked` record the one-directional
+ * PUBLIC fact the catalogs answer: PUBLIC holds nothing on the schema itself / on any
+ * relation or column in it. `schemaOwnedByRole`/`ownedTables` record the ownership facts
+ * the catalogs answer: the declared role OWNS the schema / those relations, so it holds
+ * every privilege on them implicitly — the projection records an empty word list for an
+ * owned object (the ACL rows say nothing) and the repair leaves owned objects' ACL rows
+ * alone, because a `REVOKE` cannot take an owner's implicit rights away. */
+export interface PostgresGrantsAttributes {
+  readonly role: string;
+  readonly database: string;
+  readonly schema: string;
+  readonly schemaPrivileges: ReadonlyArray<string>;
+  readonly tables: ReadonlyArray<PostgresGrantsAttributesTable>;
+  readonly columns: ReadonlyArray<PostgresGrantsAttributesColumn>;
+  readonly defaults: ReadonlyArray<PostgresGrantsAttributesDefault>;
+  readonly publicSchemaRevoked: boolean;
+  readonly publicTablesRevoked: boolean;
+  readonly schemaOwnedByRole: boolean;
+  readonly ownedTables: ReadonlyArray<string>;
+}
+
+export interface PostgresGrantsAttributesTable {
+  readonly table: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+export interface PostgresGrantsAttributesColumn {
+  readonly table: string;
+  readonly column: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+export interface PostgresGrantsAttributesDefault {
+  readonly forRole: string;
+  readonly privileges: ReadonlyArray<string>;
+}
+
+/** Refuse a name the server would truncate (`NAMEDATALEN`, the same limit
+ * `Postgres.Database` enforces — roles, schemas, tables and columns are all `NameData`).
+ * Named `grantsNameByteRefusal` so the barrel can export it beside database-attrs' own
+ * `nameByteRefusal` without a collision. */
+export const grantsNameByteRefusal = (
+  name: string,
+): { readonly byteLength: number; readonly limit: number } | undefined => {
+  const byteLength = utf8ByteLength(name);
+  return byteLength > POSTGRES_NAME_MAX_BYTES
+    ? { byteLength, limit: POSTGRES_NAME_MAX_BYTES }
+    : undefined;
+};

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

@@ -0,0 +1,158 @@
+/**
+ * `Postgres.Grants` opens its declared database the way `Postgres.Schema` does. The family
+ * connection points at a maintenance database; a cold plan must not connect to a database
+ * that does not exist yet, and a delete of a dropped database must not fail on connect.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PsqlRunner } from './psql-executor.ts';
+import { postgresRunnerConnection } from './connection.ts';
+import { postgresGrantsHandlers } from './grants.ts';
+import { PostgresGrantsDatabaseMismatch, PostgresGrantsDatabaseMissing } from './grants-errors.ts';
+import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
+
+const declared: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+};
+
+/** The engine passes persisted attributes into `delete`. These tests return before that
+ * state is read — absence is decided by `pg_database`, and the present-database path
+ * stops at a missing role — so the words are empty. */
+const persisted: PostgresGrantsAttributes = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  schemaPrivileges: [],
+  tables: [],
+  columns: [],
+  defaults: [],
+  publicSchemaRevoked: false,
+  publicTablesRevoked: false,
+  schemaOwnedByRole: false,
+  ownedTables: [],
+};
+
+const handlerArgs = {
+  id: 'x',
+  fqn: 'x',
+  instanceId: 'x',
+  session: undefined as never,
+  bindings: [] as never,
+};
+
+const recording = (probe: string, proof: string) => {
+  const stdins: string[] = [];
+  const argvs: Array<readonly string[]> = [];
+  const run: PsqlRunner = ({ stdin, argv }) => {
+    stdins.push(stdin);
+    argvs.push(argv);
+    const stdout = stdin.includes('FROM pg_database')
+      ? probe
+      : stdin.includes('current_database()')
+        ? proof
+        : '[]';
+    return Promise.resolve({ code: 0, stdout, stderr: '' });
+  };
+  return { run, stdins, argvs };
+};
+
+const provide = (run: PsqlRunner) =>
+  postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' });
+
+if (postgresGrantsHandlers.read === undefined || postgresGrantsHandlers.reconcile === undefined) {
+  throw new Error('Postgres.Grants is missing its read or reconcile handler');
+}
+const grantsRead = postgresGrantsHandlers.read;
+const grantsReconcile = postgresGrantsHandlers.reconcile;
+
+describe('a missing declared database is absent', () => {
+  test('delete is a no-op and never connects to the dropped database', async () => {
+    const { run, stdins, argvs } = recording('[]', '[{"database":"agents"}]');
+    const result = await Effect.runPromise(
+      postgresGrantsHandlers
+        .delete({ ...handlerArgs, olds: declared, output: persisted })
+        .pipe(Effect.provide(provide(run))),
+    );
+    // The no-op resolves cleanly: only the family-connection probe ran, so no
+    // current_database()/GRANT/REVOKE ever targeted the (absent) declared database.
+    expect(result).toBeUndefined();
+    expect(stdins.length).toBe(1);
+    expect(stdins[0]).toContain('FROM pg_database');
+    expect(stdins[0]).not.toContain('current_database()');
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+  });
+
+  test('read answers absent without connecting to the declared database', async () => {
+    const { run, stdins, argvs } = recording('[]', '[{"database":"agents"}]');
+    const result = await Effect.runPromise(
+      grantsRead({ ...handlerArgs, olds: declared, output: undefined }).pipe(
+        Effect.provide(provide(run)),
+      ),
+    );
+    expect(result).toBeUndefined();
+    expect(stdins.length).toBe(1);
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+  });
+});
+
+describe('a present database is opened and proved', () => {
+  test('delete probes the family connection, then proves current_database() on the declared one', async () => {
+    const { run, stdins, argvs } = recording('[{"present":1}]', '[{"database":"agents"}]');
+    await Effect.runPromise(
+      postgresGrantsHandlers
+        .delete({ ...handlerArgs, olds: declared, output: persisted })
+        .pipe(Effect.provide(provide(run))),
+    );
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+    expect(stdins[0]).toContain('FROM pg_database');
+    expect(argvs.slice(1).every((argv) => argv.at(-1) === 'agents')).toBe(true);
+    expect(stdins[1]).toContain('current_database()');
+  });
+
+  test('reconcile opens the declared database and refuses when current_database() disagrees', async () => {
+    const { run, stdins, argvs } = recording('[{"present":1}]', '[{"database":"postgres"}]');
+    const error = await Effect.runPromise(
+      Effect.flip(
+        grantsReconcile({
+          ...handlerArgs,
+          news: declared,
+          olds: declared,
+          output: undefined,
+        }).pipe(Effect.provide(provide(run))),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsDatabaseMismatch);
+    expect(error).toMatchObject({ declared: 'agents', connected: 'postgres' });
+    // The reconcile probes the family connection first (pg_database), then opens the
+    // declared database and proves current_database() there.
+    expect(argvs.length).toBe(2);
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+    expect(stdins[0]).toContain('FROM pg_database');
+    expect(argvs[1]?.at(-1)).toBe('agents');
+    expect(stdins[1]).toContain('current_database()');
+  });
+});
+
+describe('a missing declared database on reconcile is a typed refusal', () => {
+  test('reconcile fails PostgresGrantsDatabaseMissing and never opens the declared database', async () => {
+    const { run, stdins, argvs } = recording('[]', '[{"database":"agents"}]');
+    const error = await Effect.runPromise(
+      Effect.flip(
+        grantsReconcile({
+          ...handlerArgs,
+          news: declared,
+          olds: declared,
+          output: undefined,
+        }).pipe(Effect.provide(provide(run))),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsDatabaseMissing);
+    expect(error).toMatchObject({ database: 'agents' });
+    // Only the family-connection probe ran; reconcile never opened the declared database.
+    expect(stdins.length).toBe(1);
+    expect(stdins[0]).toContain('FROM pg_database');
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+  });
+});

package/src/postgres/grants-declare.ts

@@ -0,0 +1,172 @@
+/**
+ * `Postgres.Grants`' declared shape, normalized: every default applied, every list sorted,
+ * the names recovered from the persisted attributes, the cleared twin `delete` replays and
+ * the entries an update removed. Pure — no client, no `Effect` — so `reconcile`, the
+ * engine's `diff` and the tests share one implementation. Word validation and the refusals
+ * live in `grants-refuse.ts`; the comparison against live catalogs and the read-back
+ * projection in `grants-plan.ts` and `grants-diff.ts`.
+ *
+ * ★ WHAT THE RESOURCE OWNS, PRECISELY. For every object the declaration NAMES — the schema,
+ *   each table, each column, each (`forRole`) default — the role's full privilege set is
+ *   declared; an object the declaration does not name is NEVER touched. PUBLIC's privileges
+ *   are touched only when `revokeFromPublic` says so, and only by clearing: this family
+ *   never issues a `GRANT … TO PUBLIC`.
+ */
+import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
+
+/** The resolved declaration: every default applied, every word validated, every list
+ * sorted. Both the live bundle (`grants-read.ts`) and the persisted attributes are already
+ * in these shapes. */
+export interface DeclaredGrants {
+  readonly role: string;
+  readonly database: string;
+  readonly schema: string;
+  readonly schemaPrivileges: ReadonlyArray<string>;
+  readonly tables: ReadonlyArray<{
+    readonly table: string;
+    readonly privileges: ReadonlyArray<string>;
+  }>;
+  readonly columns: ReadonlyArray<{
+    readonly table: string;
+    readonly column: string;
+    readonly privileges: ReadonlyArray<string>;
+  }>;
+  readonly defaults: ReadonlyArray<{
+    readonly forRole: string;
+    readonly privileges: ReadonlyArray<string>;
+  }>;
+  readonly publicSchemaRevoked: boolean;
+  readonly publicTablesRevoked: boolean;
+}
+
+const cleanWords = (words: ReadonlyArray<string>): ReadonlyArray<string> =>
+  [...new Set(words)].sort();
+
+export const baseWord = (word: string): string => (word.endsWith('*') ? word.slice(0, -1) : word);
+
+/** The one place defaults resolve to values: `schemaUsage` true, `schemaCreate` false, the
+ * PUBLIC revokes false. Every caller — plan, reconcile, diff — normalizes through here so
+ * the three never disagree on what an omitted prop means. */
+export const resolveProps = (props: PostgresGrantsProps): DeclaredGrants => ({
+  role: props.role,
+  database: props.database,
+  schema: props.schema,
+  schemaPrivileges: cleanWords([
+    ...(props.schemaUsage === false ? [] : ['usage']),
+    ...(props.schemaCreate === true ? ['create'] : []),
+  ]),
+  tables: [...(props.tables ?? [])]
+    .map((table) => ({ table: table.table, privileges: cleanWords(table.privileges) }))
+    .sort((a, b) => a.table.localeCompare(b.table)),
+  columns: [...(props.columnGrants ?? [])]
+    .map((column) => ({
+      table: column.table,
+      column: column.column,
+      privileges: cleanWords(column.privileges),
+    }))
+    .sort((a, b) => a.table.localeCompare(b.table) || a.column.localeCompare(b.column)),
+  defaults: [...(props.defaultPrivileges ?? [])]
+    .map((entry) => ({ forRole: entry.forRole, privileges: cleanWords(entry.privileges) }))
+    .sort((a, b) => a.forRole.localeCompare(b.forRole)),
+  publicSchemaRevoked: props.revokeFromPublic === true,
+  publicTablesRevoked: props.revokeFromPublic === true,
+});
+
+/** Split one validated word list by its grant-option mark: a mixed list cannot be a single
+ * `GRANT` (one `WITH GRANT OPTION` clause would grant the option to every listed
+ * privilege, `grants-sql.ts`'s header), so the repair issues one statement per group. */
+export const splitGrantWords = (
+  words: ReadonlyArray<string>,
+): { readonly plain: ReadonlyArray<string>; readonly grantable: ReadonlyArray<string> } => ({
+  plain: words.filter((word) => !word.endsWith('*')),
+  grantable: words.filter((word) => word.endsWith('*')),
+});
+
+/** The names the live read is PROJECTED onto — attributes record what the catalogs say,
+ * restricted to the objects one declaration names (an object the declaration never named
+ * must not appear in them: the engine's diff would read it as drift the repair is forbidden
+ * to touch). */
+export interface DeclaredNames {
+  readonly role: string;
+  readonly database: string;
+  readonly schema: string;
+  readonly tables: ReadonlyArray<string>;
+  readonly columns: ReadonlyArray<{ readonly table: string; readonly column: string }>;
+  readonly defaults: ReadonlyArray<string>;
+}
+
+export const declaredNames = (declared: DeclaredGrants): DeclaredNames => ({
+  role: declared.role,
+  database: declared.database,
+  schema: declared.schema,
+  tables: declared.tables.map((table) => table.table),
+  columns: declared.columns.map(({ table, column }) => ({ table, column })),
+  defaults: declared.defaults.map((entry) => entry.forRole),
+});
+
+/** Recover the last declaration's names from the persisted attributes, for `read`'s
+ * projection when a state file exists (`attributesOf` uses only the names; the recorded
+ * words are the catalogs' to decide). */
+export const namesFromAttrs = (attrs: PostgresGrantsAttributes): DeclaredNames => ({
+  role: attrs.role,
+  database: attrs.database,
+  schema: attrs.schema,
+  tables: attrs.tables.map((table) => table.table),
+  columns: attrs.columns.map(({ table, column }) => ({ table, column })),
+  defaults: attrs.defaults.map((entry) => entry.forRole),
+});
+
+/** The `delete` twin of a declaration: the same names, every privilege list emptied, the
+ * PUBLIC flags off. `planRepair` turns it into exactly the revoke set delete may issue —
+ * one revoke per named object where live still shows the role words, nothing for PUBLIC.
+ * A table revoke still restores the column collateral it clears (`grants-plan.ts`), so a
+ * delete takes away what the declaration managed and leaves a DBA's or another resource's
+ * undeclared column grant untouched. */
+export const clearedDeclaration = (declared: DeclaredGrants): DeclaredGrants => ({
+  ...declared,
+  schemaPrivileges: [],
+  tables: declared.tables.map((table) => ({ table: table.table, privileges: [] })),
+  columns: declared.columns.map((column) => ({
+    table: column.table,
+    column: column.column,
+    privileges: [],
+  })),
+  defaults: declared.defaults.map((entry) => ({ forRole: entry.forRole, privileges: [] })),
+  publicSchemaRevoked: false,
+  publicTablesRevoked: false,
+});
+
+/** The entries an update REMOVED from the last applied declaration: the names in
+ * `output` (the persisted attributes) that the new declaration no longer names, every
+ * word list emptied — the input `grants-plan.ts#planRevocations` turns into the revoke set
+ * the reconcile runs before the new declaration's repair, so removing an entry takes the
+ * privilege away instead of silently retaining it. `undefined` when `output` is undefined
+ * (first apply) or nothing was removed. The `database`-mismatch and retarget guards run
+ * first, so the removed set can only ever hold tables, columns and defaults — the schema
+ * class never gains or loses an entry. */
+export const removedNames = (
+  output: PostgresGrantsAttributes | undefined,
+  declared: DeclaredGrants,
+): Pick<DeclaredGrants, 'schema' | 'role' | 'tables' | 'columns' | 'defaults'> | undefined => {
+  if (output === undefined) return undefined;
+  const keepTables = new Set(declared.tables.map((table) => table.table));
+  const keepColumns = new Set(
+    declared.columns.map((column) => `${column.table}\u0000${column.column}`),
+  );
+  const keepDefaults = new Set(declared.defaults.map((entry) => entry.forRole));
+  const tables = output.tables
+    .filter((table) => !keepTables.has(table.table))
+    .map((table) => ({ table: table.table, privileges: [] as ReadonlyArray<string> }));
+  const columns = output.columns
+    .filter((column) => !keepColumns.has(`${column.table}\u0000${column.column}`))
+    .map((column) => ({
+      table: column.table,
+      column: column.column,
+      privileges: [] as ReadonlyArray<string>,
+    }));
+  const defaults = output.defaults
+    .filter((entry) => !keepDefaults.has(entry.forRole))
+    .map((entry) => ({ forRole: entry.forRole, privileges: [] as ReadonlyArray<string> }));
+  if (tables.length === 0 && columns.length === 0 && defaults.length === 0) return undefined;
+  return { schema: declared.schema, role: declared.role, tables, columns, defaults };
+};

package/src/postgres/grants-delete-proof.test.ts

@@ -0,0 +1,154 @@
+/**
+ * The delete-path convergence proof (S10): `delete` runs its revokes, then re-reads and
+ * re-plans the way `reconcile` does. A clean revoke converges silently; a third grantor's
+ * grant the executor's REVOKE cannot clear survives the pass and fails loud with the
+ * still-planned statements (`PostgresGrantsRepairRefused`) instead of reporting a delete
+ * that left the grantee holding privileges. The fake's server rule — `REVOKE ALL` removes
+ * only the executing role's own grants — is the survival the proof must catch.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeGrants } from './fake-grants-sql.ts';
+import { deleteWithClient, reconcileWithClient } from './grants-ops.ts';
+import { PostgresGrantsRepairRefused } from './grants-errors.ts';
+import { readGrants } from './grants-read.ts';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const isWrite = (text: string): boolean => /^(GRANT|REVOKE|ALTER)/.test(text);
+
+const baseProps: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  schemaUsage: true,
+};
+
+/** The catalog a delete needs: the schema and grantee role exist, and one table with a
+ * column so table and column grants have a target. */
+const catalog = {
+  schemas: ['app'],
+  roles: ['postgres', 'seat_writer'],
+  tables: [{ schema: 'app', table: 'widgets', columns: ['id'] }],
+};
+
+describe('delete: the re-read proof', () => {
+  test('a clean delete runs the revokes and converges silently', async () => {
+    const fake = makeFakeGrants(catalog);
+    await run(
+      reconcileWithClient(
+        fake,
+        {
+          ...baseProps,
+          tables: [{ table: 'widgets', privileges: ['select'] }],
+        },
+        undefined,
+      ),
+    );
+    const before = fake.statements.length;
+    await run(
+      deleteWithClient(fake, {
+        ...baseProps,
+        tables: [{ table: 'widgets', privileges: ['select'] }],
+      }),
+    );
+    // Only the revokes, no re-grant, no second-pass writes: the re-read found nothing.
+    expect(
+      fake.statements
+        .slice(before)
+        .map((s) => s.text)
+        .filter(isWrite),
+    ).toEqual([
+      'REVOKE ALL ON SCHEMA "app" FROM "seat_writer"',
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+    ]);
+  });
+
+  test('a delete re-grants the undeclared column entries its table revoke collaterally clears', async () => {
+    // The seat's own column grant on `qty` was never declared, but a table-level
+    // `REVOKE ALL` clears it too. `delete` takes away what the declaration managed and leaves
+    // everything else exactly as it was, so the column grant IS re-granted in the same pass
+    // (the same collateral the reconcile path restores, grants-plan.ts `restoredColumnGrants`).
+    const fake = makeFakeGrants({
+      schemas: ['app'],
+      roles: ['postgres', 'seat_writer'],
+      tables: [{ schema: 'app', table: 'widgets', columns: ['qty'] }],
+      acl: [
+        {
+          object: { schema: 'app', table: 'widgets' },
+          grantee: 'seat_writer',
+          grantor: 'postgres',
+          words: ['select'],
+        },
+        {
+          object: { schema: 'app', table: 'widgets', column: 'qty' },
+          grantee: 'seat_writer',
+          grantor: 'postgres',
+          words: ['update'],
+        },
+      ],
+    });
+    const before = fake.statements.length;
+    await run(
+      deleteWithClient(fake, {
+        ...baseProps,
+        tables: [{ table: 'widgets', privileges: ['select'] }],
+      }),
+    );
+    const writes = fake.statements
+      .slice(before)
+      .map((s) => s.text)
+      .filter(isWrite);
+    // The table revoke, then the collateral column re-grant — no schema grant was seeded, and
+    // the undeclared `qty` entry survives the delete.
+    expect(writes).toEqual([
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+      'GRANT update ("qty") ON "app"."widgets" TO "seat_writer"',
+    ]);
+    const after = await run(readGrants(fake, 'app', 'seat_writer'));
+    expect(after.columns).toEqual([
+      { table: 'widgets', column: 'qty', role: ['update'], public: [], restorable: ['update'] },
+    ]);
+  });
+
+  test('a third grantor\u2019s surviving grant fails the delete as PostgresGrantsRepairRefused', async () => {
+    const fake = makeFakeGrants(catalog);
+    await run(
+      reconcileWithClient(
+        fake,
+        { ...baseProps, tables: [{ table: 'widgets', privileges: ['select'] }] },
+        undefined,
+      ),
+    );
+    // The competing grant lands after the converge (a third grantor grants while the seat
+    // already holds the executor's grant): the delete's REVOKE clears only the executor's
+    // own grants, so this one survives the pass and the delete's re-read must catch it.
+    fake.acl.push({
+      object: { schema: 'app', table: 'widgets' },
+      grantee: 'seat_writer',
+      grantor: 'someone_else',
+      words: ['delete'],
+    });
+    const before = fake.statements.length;
+    const error = await fails(
+      deleteWithClient(fake, {
+        ...baseProps,
+        tables: [{ table: 'widgets', privileges: ['select'] }],
+      }),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsRepairRefused);
+    // The third grantor's 'delete' survived the revoke, so the re-read still plans the
+    // table's REVOKE — that surviving statement is the refusal.
+    expect((error as PostgresGrantsRepairRefused).remaining).toContain(
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+    );
+    expect(
+      fake.statements
+        .slice(before)
+        .map((s) => s.text)
+        .filter(isWrite),
+    ).toContain('REVOKE ALL ON "app"."widgets" FROM "seat_writer"');
+  });
+});