@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-repair-plan.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The pure statement planners: `planRepair`'s per-class repair (no-op, drift, the
+ * revoke-only delete twin, the grant-option split, the two PUBLIC clears), the measured
+ * rules the convergence proof depends on (a table revoke clears its declared columns;
+ * owned objects are left alone). Removal revokes live in `grants-plan-revocations.test.ts`.
+ * `resolveProps` and the refusals live in `grants-plan.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+import { resolveProps } from './grants-declare.ts';
+import { planRepair } from './grants-plan.ts';
+import type { LiveGrants } from './grants-read.ts';
+
+const props: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+};
+
+const live = (over: Partial<LiveGrants> = {}): LiveGrants => ({
+  schemaExists: true,
+  schema: { role: [], public: [] },
+  tables: [],
+  columns: [],
+  defaults: [],
+  schemaOwnedByRole: false,
+  ownedTables: [],
+  ...over,
+});
+
+describe('planRepair', () => {
+  test('a class whose live set equals the declaration contributes nothing', () => {
+    expect(
+      planRepair(
+        resolveProps({ ...props, tables: [{ table: 'widgets', privileges: ['select'] }] }),
+        live({
+          schema: { role: ['usage'], public: [] },
+          tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('drift on a table is REVOKE ALL then GRANT the declared words', () => {
+    expect(
+      planRepair(
+        resolveProps({ ...props, tables: [{ table: 'widgets', privileges: ['select'] }] }),
+        live({
+          tables: [{ table: 'widgets', relkind: 'r', role: ['insert', 'update'], public: [] }],
+        }),
+      ),
+    ).toEqual([
+      'REVOKE ALL ON SCHEMA "app" FROM "seat_writer"',
+      'GRANT usage ON SCHEMA "app" TO "seat_writer"',
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+      'GRANT select ON "app"."widgets" TO "seat_writer"',
+    ]);
+  });
+
+  test('a class that declares nothing but holds live grants gets the revoke only', () => {
+    expect(
+      planRepair(
+        resolveProps({ ...props, schemaUsage: false }),
+        live({ schema: { role: ['usage'], public: [] } }),
+      ),
+    ).toEqual(['REVOKE ALL ON SCHEMA "app" FROM "seat_writer"']);
+  });
+
+  test('a mixed grant-option list splits into one plain grant and one option grant', () => {
+    const plan = planRepair(
+      resolveProps({
+        ...props,
+        tables: [{ table: 'widgets', privileges: ['select', 'insert*'] }],
+      }),
+      live({ tables: [{ table: 'widgets', relkind: 'r', role: ['delete'], public: [] }] }),
+    );
+    expect(plan).toContain('GRANT select ON "app"."widgets" TO "seat_writer"');
+    expect(plan).toContain('GRANT insert ON "app"."widgets" TO "seat_writer" WITH GRANT OPTION');
+    expect(plan.some((s) => s === 'GRANT select, insert ON "app"."widgets" TO "seat_writer"')).toBe(
+      false,
+    );
+  });
+
+  test('a table revoke also re-grants the table\u2019s declared columns in the SAME pass — measured on PG 18.6, a table REVOKE ALL clears that grantee\u2019s column entries', () => {
+    const plan = planRepair(
+      resolveProps({
+        ...props,
+        tables: [{ table: 'widgets', privileges: ['select', 'insert'] }],
+        columnGrants: [{ table: 'widgets', column: 'id', privileges: ['select'] }],
+      }),
+      live({
+        schema: { role: ['usage'], public: [] },
+        tables: [{ table: 'widgets', relkind: 'r', role: ['select'], public: [] }],
+        columns: [
+          { table: 'widgets', column: 'id', role: ['select'], public: [], restorable: ['select'] },
+        ],
+      }),
+    );
+    expect(plan).toEqual([
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+      'GRANT insert, select ON "app"."widgets" TO "seat_writer"',
+      'REVOKE ALL ("id") ON "app"."widgets" FROM "seat_writer"',
+      'GRANT select ("id") ON "app"."widgets" TO "seat_writer"',
+    ]);
+  });
+
+  test('drift on a default-privileges entry is the ALTER DEFAULT PRIVILEGES revoke-then-grant pair', () => {
+    expect(
+      planRepair(
+        resolveProps({
+          ...props,
+          defaultPrivileges: [{ forRole: 'owner_role', privileges: ['select'] }],
+        }),
+        live({
+          schema: { role: ['usage'], public: [] },
+          defaults: [{ forRole: 'owner_role', role: ['insert'] }],
+        }),
+      ),
+    ).toEqual([
+      'ALTER DEFAULT PRIVILEGES FOR ROLE "owner_role" IN SCHEMA "app" REVOKE ALL ON TABLES FROM "seat_writer"',
+      'ALTER DEFAULT PRIVILEGES FOR ROLE "owner_role" IN SCHEMA "app" GRANT select ON TABLES TO "seat_writer"',
+    ]);
+  });
+
+  test('objects the declared role OWNS contribute nothing — an owner holds every privilege implicitly and a revoke cannot take it away', () => {
+    expect(
+      planRepair(
+        resolveProps({
+          ...props,
+          tables: [{ table: 'notes', privileges: ['select', 'insert'] }],
+        }),
+        live({
+          schemaOwnedByRole: true,
+          ownedTables: ['notes'],
+          tables: [{ table: 'notes', relkind: 'r', role: [], public: [] }],
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('ownership is per object: a table the role does NOT own is still repaired beside the owned one', () => {
+    const plan = planRepair(
+      resolveProps({
+        ...props,
+        tables: [
+          { table: 'notes', privileges: ['select'] },
+          { table: 'shared', privileges: ['select'] },
+        ],
+      }),
+      live({
+        ownedTables: ['notes'],
+        tables: [
+          { table: 'notes', relkind: 'r', role: [], public: [] },
+          { table: 'shared', relkind: 'r', role: ['delete'], public: [] },
+        ],
+      }),
+    );
+    expect(plan.some((s) => s.includes('"notes"'))).toBe(false);
+    expect(plan).toContain('REVOKE ALL ON "app"."shared" FROM "seat_writer"');
+    expect(plan).toContain('GRANT select ON "app"."shared" TO "seat_writer"');
+  });
+});
+
+describe('the PUBLIC clears', () => {
+  const declared = resolveProps({ ...props, revokeFromPublic: true });
+
+  test('PUBLIC schema words earn the schema revoke; PUBLIC table words earn the tables revoke', () => {
+    expect(planRepair(declared, live({ schema: { role: ['usage'], public: ['usage'] } }))).toEqual([
+      'REVOKE ALL ON SCHEMA "app" FROM PUBLIC',
+    ]);
+    expect(
+      planRepair(
+        declared,
+        live({
+          schema: { role: ['usage'], public: [] },
+          columns: [
+            { table: 'widgets', column: 'id', role: [], public: ['select'], restorable: [] },
+          ],
+        }),
+      ),
+    ).toEqual(['REVOKE ALL ON ALL TABLES IN SCHEMA "app" FROM PUBLIC']);
+  });
+
+  test('a PUBLIC grant on a SEQUENCE is outside the bulk revoke\u2019s reach (relkind S) and never blocks convergence', () => {
+    expect(
+      planRepair(
+        declared,
+        live({
+          schema: { role: ['usage'], public: [] },
+          tables: [{ table: 'app_seq', relkind: 'S', role: [], public: ['usage'] }],
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('without the flag, PUBLIC holds are never drift', () => {
+    expect(
+      planRepair(resolveProps(props), live({ schema: { role: ['usage'], public: ['usage'] } })),
+    ).toEqual([]);
+  });
+});

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

@@ -0,0 +1,128 @@
+/**
+ * The statement builders' exact output: every identifier `quoteIdent`ed, every clause in the
+ * one order the parser (`fake-grants-parse.ts`, in tests) and a real server accept, and the
+ * mixed grant-option refusal that protects the declaration from over-granting (one
+ * `WITH GRANT OPTION` clause would grant the option to EVERY listed privilege).
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  grantColumnSql,
+  grantDefaultSql,
+  grantSchemaSql,
+  grantTableSql,
+  revokeColumnSql,
+  revokeDefaultSql,
+  revokePublicSchemaSql,
+  revokePublicTablesSql,
+  revokeSchemaSql,
+  revokeTableSql,
+} from './grants-sql.ts';
+
+describe('grant builders', () => {
+  test('a table grant lists words comma-separated on the qualified relation', () => {
+    expect(grantTableSql('app', 'widgets', 'seat_writer', ['select', 'insert'])).toBe(
+      'GRANT select, insert ON "app"."widgets" TO "seat_writer"',
+    );
+  });
+
+  test('a grant-option list carries exactly one WITH GRANT OPTION clause at the end', () => {
+    expect(grantTableSql('app', 'widgets', 'seat_writer', ['select*'])).toBe(
+      'GRANT select ON "app"."widgets" TO "seat_writer" WITH GRANT OPTION',
+    );
+  });
+
+  test('a MIXED list throws instead of over-granting the option to the plain words', () => {
+    expect(() => grantTableSql('app', 'widgets', 'seat_writer', ['select', 'insert*'])).toThrow(
+      /mixed grant-option list/,
+    );
+  });
+
+  test('an out-of-vocabulary word is refused before it reaches a GRANT clause', () => {
+    // The builders are exported API, so the vocabulary check lives inside them, not only
+    // in the resource path: an injected fragment can never be concatenated into SQL.
+    expect(() => grantTableSql('app', 'widgets', 'seat_writer', ['select', 'execute'])).toThrow(
+      /not a privilege/,
+    );
+    expect(() => grantTableSql('app', 'widgets', 'seat_writer', ['*'])).toThrow(/not a privilege/);
+  });
+
+  test('a column grant parenthesizes the column after the words', () => {
+    expect(grantColumnSql('app', 'widgets', 'id', 'seat_writer', ['select'])).toBe(
+      'GRANT select ("id") ON "app"."widgets" TO "seat_writer"',
+    );
+  });
+
+  test('a multi-word column grant repeats the synopsis per word', () => {
+    // One trailing column list binds only to the privilege it follows (gram.y@REL_18_6):
+    // `GRANT select, update ("id")` is a table-level SELECT plus a column-level UPDATE.
+    // Every word carries its own list, so all of them land on the column and nothing on
+    // the relation — a grant the declaration did not name is never issued.
+    expect(grantColumnSql('app', 'widgets', 'amount', 'seat_writer', ['select', 'update'])).toBe(
+      'GRANT select ("amount"), update ("amount") ON "app"."widgets" TO "seat_writer"',
+    );
+    expect(grantColumnSql('app', 'widgets', 'amount', 'seat_writer', ['select*', 'update*'])).toBe(
+      'GRANT select ("amount"), update ("amount") ON "app"."widgets" TO "seat_writer" WITH GRANT OPTION',
+    );
+  });
+
+  test('a schema grant names SCHEMA, not a relation', () => {
+    expect(grantSchemaSql('app', 'seat_writer', ['usage'])).toBe(
+      'GRANT usage ON SCHEMA "app" TO "seat_writer"',
+    );
+  });
+
+  test('a default-privileges grant carries FOR ROLE (the creator) IN SCHEMA, grantee last', () => {
+    expect(grantDefaultSql('app', 'ledger_owner', 'seat_writer', ['select'])).toBe(
+      'ALTER DEFAULT PRIVILEGES FOR ROLE "ledger_owner" IN SCHEMA "app" GRANT select ON TABLES TO "seat_writer"',
+    );
+  });
+});
+
+describe('revoke builders', () => {
+  test('a table revoke', () => {
+    expect(revokeTableSql('app', 'widgets', 'seat_writer')).toBe(
+      'REVOKE ALL ON "app"."widgets" FROM "seat_writer"',
+    );
+  });
+
+  test('a column revoke', () => {
+    expect(revokeColumnSql('app', 'widgets', 'id', 'seat_writer')).toBe(
+      'REVOKE ALL ("id") ON "app"."widgets" FROM "seat_writer"',
+    );
+  });
+
+  test('a schema revoke', () => {
+    expect(revokeSchemaSql('app', 'seat_writer')).toBe(
+      'REVOKE ALL ON SCHEMA "app" FROM "seat_writer"',
+    );
+  });
+
+  test('a default-privileges revoke', () => {
+    expect(revokeDefaultSql('app', 'ledger_owner', 'seat_writer')).toBe(
+      'ALTER DEFAULT PRIVILEGES FOR ROLE "ledger_owner" IN SCHEMA "app" REVOKE ALL ON TABLES FROM "seat_writer"',
+    );
+  });
+
+  test('the PUBLIC schema revoke uses the bare keyword, never a quoted role', () => {
+    expect(revokePublicSchemaSql('app')).toBe('REVOKE ALL ON SCHEMA "app" FROM PUBLIC');
+  });
+
+  test('the PUBLIC tables revoke clears every relation in the schema', () => {
+    expect(revokePublicTablesSql('app')).toBe(
+      'REVOKE ALL ON ALL TABLES IN SCHEMA "app" FROM PUBLIC',
+    );
+  });
+});
+
+describe('quoting', () => {
+  test('embedded quotes and hyphens survive in every position', () => {
+    expect(grantTableSql('a"b', 'weird-name', 'x y', ['select'])).toBe(
+      'GRANT select ON "a""b"."weird-name" TO "x y"',
+    );
+    // A single quote needs no doubling inside a double-quoted identifier — only the
+    // identifier quote character ("") is doubled (grant.sgml@REL_18_6, SQL syntax).
+    expect(grantColumnSql('a"b', 'weird-name', "it's", 'x y', ['select'])).toBe(
+      `GRANT select ("it's") ON "a""b"."weird-name" TO "x y"`,
+    );
+  });
+});

package/src/postgres/grants-sql.ts

@@ -0,0 +1,144 @@
+/**
+ * The statements `Postgres.Grants` ever ISSUES: ten builders, one statement each. The READ
+ * half lives in `grants-read.ts` (it goes through `aclexplode`, never `aclitem` text); this
+ * file is writes only. Every free-form value is bound (`$n`) or `quoteIdent`ed, never
+ * hand-concatenated, and every privilege word is checked against the vocabularies before
+ * it is concatenated — the builders are exported API, so the check cannot live only in
+ * the resource path.
+ *
+ * ⛔ NO `CASCADE`, EVER: a revoke whose grantee re-granted onward is refused by the server
+ *   rather than silently removing a third role's grant (the declaration does not name that
+ *   role). The refusal surfaces as the driver's own statement error; the operator adds the
+ *   grant to their declaration or revokes by hand.
+ * ⛔ A GRANT LIST UNDER ONE `WITH GRANT OPTION` OPTION CLAUSE GRANTS THE OPTION TO EVERY
+ *   LISTED PRIVILEGE. The builders therefore throw on a MIXED list (some words marked `*`,
+ *   some not): `planRepair` splits the words with `splitGrantWords` and issues two grants —
+ *   the split is the only shape that cannot over-grant beyond the declaration.
+ */
+import { ALL_GRANT_WORDS } from './grants-attrs.ts';
+import { quoteIdent } from './database-sql.ts';
+
+const splitParts = (
+  words: ReadonlyArray<string>,
+): { readonly parts: ReadonlyArray<string>; readonly anyOption: boolean } => {
+  const parts: string[] = [];
+  let optionCount = 0;
+  for (const word of words) {
+    const base = word.endsWith('*') ? word.slice(0, -1) : word;
+    // The builders are exported API, so the vocabulary check does not only live in the
+    // resource path: a word outside every class vocabulary (a bare `*`, an injected
+    // fragment) is refused here instead of concatenated into a GRANT clause.
+    if (!ALL_GRANT_WORDS.includes(base)) {
+      throw new Error(
+        `grants-sql: "${base}" is not a privilege this family can grant — see the three ` +
+          'vocabularies in grants-attrs.ts (traced to acl.h at REL_18_6)',
+      );
+    }
+    if (word.endsWith('*')) optionCount += 1;
+    parts.push(base);
+  }
+  if (optionCount > 0 && optionCount < words.length) {
+    throw new Error(
+      `grants-sql: a mixed grant-option list cannot be one GRANT statement: ${words.join(', ')}` +
+        ' — split it with splitGrantWords first (one option clause grants the option to every word)',
+    );
+  }
+  return { parts, anyOption: optionCount > 0 };
+};
+
+const optionClause = (anyOption: boolean): string => (anyOption ? ' WITH GRANT OPTION' : '');
+
+/** `GRANT` on one relation. `words` are already validated lowercase declared words; a
+ * trailing `*` (WITH GRANT OPTION) becomes the option clause — the list must share one
+ * flag (see the header). */
+export const grantTableSql = (
+  schema: string,
+  table: string,
+  role: string,
+  words: ReadonlyArray<string>,
+): string => {
+  const { parts, anyOption } = splitParts(words);
+  return `GRANT ${parts.join(', ')} ON ${quoteIdent(schema)}.${quoteIdent(table)} TO ${quoteIdent(role)}${optionClause(anyOption)}`;
+};
+
+/** `GRANT` on one column of one relation.
+ *
+ * Each word is emitted as its own synopsis inside one statement — `GRANT select ("col"),
+ * update ("col") ON …`. A column list binds only to the privilege it follows
+ * (gram.y@REL_18_6), so a word list under ONE trailing column list parses as a table-level
+ * grant of every word but the last (which alone lands on the column) — a silent over-grant
+ * the declaration did not name. Repeating the synopsis is the one shape that puts every
+ * declared word on the column and nothing on the relation. */
+export const grantColumnSql = (
+  schema: string,
+  table: string,
+  column: string,
+  role: string,
+  words: ReadonlyArray<string>,
+): string => {
+  const { parts, anyOption } = splitParts(words);
+  const columnList = `(${quoteIdent(column)})`;
+  return `GRANT ${parts.map((word) => `${word} ${columnList}`).join(', ')} ON ${quoteIdent(schema)}.${quoteIdent(table)} TO ${quoteIdent(role)}${optionClause(anyOption)}`;
+};
+
+/** `GRANT` on the schema itself (`USAGE` / `CREATE`). */
+export const grantSchemaSql = (
+  schema: string,
+  role: string,
+  words: ReadonlyArray<string>,
+): string => {
+  const { parts, anyOption } = splitParts(words);
+  return `GRANT ${parts.join(', ')} ON SCHEMA ${quoteIdent(schema)} TO ${quoteIdent(role)}${optionClause(anyOption)}`;
+};
+
+/** `ALTER DEFAULT PRIVILEGES FOR ROLE <creator> IN SCHEMA <schema> GRANT … ON TABLES TO
+ * <role>` — the creator is `forRole`, the grantee is always the resource's role. */
+export const grantDefaultSql = (
+  schema: string,
+  forRole: string,
+  role: string,
+  words: ReadonlyArray<string>,
+): string => {
+  const { parts, anyOption } = splitParts(words);
+  return `ALTER DEFAULT PRIVILEGES FOR ROLE ${quoteIdent(forRole)} IN SCHEMA ${quoteIdent(schema)} GRANT ${parts.join(', ')} ON TABLES TO ${quoteIdent(role)}${optionClause(anyOption)}`;
+};
+
+/** `REVOKE ALL ON <schema>.<table> FROM <role>` — the repair's first half for a drifted
+ * table. Revoking a privilege the grantee does not hold is a silent no-op on the server, so
+ * the repair's revoke is idempotent; what the server REFUSES is a revoke that would have to
+ * cascade (see the header). */
+export const revokeTableSql = (schema: string, table: string, role: string): string =>
+  `REVOKE ALL ON ${quoteIdent(schema)}.${quoteIdent(table)} FROM ${quoteIdent(role)}`;
+
+/** `REVOKE ALL (<column>) ON <schema>.<table> FROM <role>` — same reasoning as
+ * {@link revokeTableSql}. */
+export const revokeColumnSql = (
+  schema: string,
+  table: string,
+  column: string,
+  role: string,
+): string =>
+  `REVOKE ALL (${quoteIdent(column)}) ON ${quoteIdent(schema)}.${quoteIdent(table)} FROM ${quoteIdent(role)}`;
+
+/** `REVOKE ALL ON SCHEMA <schema> FROM <role>` — the repair's first half for the schema's
+ * own privileges. */
+export const revokeSchemaSql = (schema: string, role: string): string =>
+  `REVOKE ALL ON SCHEMA ${quoteIdent(schema)} FROM ${quoteIdent(role)}`;
+
+/** `ALTER DEFAULT PRIVILEGES FOR ROLE <creator> IN SCHEMA <schema> REVOKE ALL ON TABLES
+ * FROM <role>`. */
+export const revokeDefaultSql = (schema: string, forRole: string, role: string): string =>
+  `ALTER DEFAULT PRIVILEGES FOR ROLE ${quoteIdent(forRole)} IN SCHEMA ${quoteIdent(schema)} REVOKE ALL ON TABLES FROM ${quoteIdent(role)}`;
+
+/** `REVOKE ALL ON SCHEMA <schema> FROM PUBLIC` — the `revokeFromPublic` half for the
+ * schema itself. PUBLIC is the bare keyword (`aclitem`'s empty grantee, acl.h@REL_18_6
+ * `ACL_ID_PUBLIC`). */
+export const revokePublicSchemaSql = (schema: string): string =>
+  `REVOKE ALL ON SCHEMA ${quoteIdent(schema)} FROM PUBLIC`;
+
+/** `REVOKE ALL ON ALL TABLES IN SCHEMA <schema> FROM PUBLIC` — the `revokeFromPublic` half
+ * for every relation in the schema, including PUBLIC's column privileges on those relations
+ * (revoke.sgml@REL_18_6: revoking table privileges also revokes the corresponding column
+ * privileges). */
+export const revokePublicTablesSql = (schema: string): string =>
+  `REVOKE ALL ON ALL TABLES IN SCHEMA ${quoteIdent(schema)} FROM PUBLIC`;

package/src/postgres/grants-words.ts

@@ -0,0 +1,34 @@
+/**
+ * The vocabulary primitives of `Postgres.Grants`: the aclexplode row as it crosses the
+ * wire, the word it encodes, the word set a read answers — and the `relkind` vocabulary
+ * the PUBLIC-tables clear is scoped to. Pure — no client, no `Effect` — so the reads
+ * (`grants-read.ts`), the plans (`grants-plan.ts`, `grants-diff.ts`) and the test fake
+ * (`fake-grants-read.ts`) all share one definition of what a word is.
+ */
+/** One aclexplode row as it crosses the wire: lowercase declared word with `*` appended
+ * when the privilege carries WITH GRANT OPTION (`is_grantable`). */
+export interface AclRow {
+  readonly public: boolean;
+  readonly privilege: string;
+  readonly grantable: boolean;
+}
+
+/** Lowercase word, `*` appended when the privilege carries WITH GRANT OPTION. */
+export const encodeWord = (row: {
+  readonly privilege: string;
+  readonly grantable: boolean;
+}): string => `${row.privilege.toLowerCase()}${row.grantable ? '*' : ''}`;
+
+/** Union of one grantee's distinct words over all its aclexplode rows, sorted — two reads
+ * of the same state must compare equal, which the re-run-is-a-no-op rule needs. */
+export const wordsOf = (rows: ReadonlyArray<AclRow>, wantPublic: boolean): ReadonlyArray<string> =>
+  [...new Set(rows.filter((row) => row.public === wantPublic).map(encodeWord))].sort();
+
+/** The relkinds `GRANT/REVOKE … ON ALL TABLES IN SCHEMA` covers — every pg_class relation
+ * class except sequences (`S`), composite types (`c`) and indexes (`i`), per
+ * `revoke.sgml@REL_18_6` ("ALL TABLES also affects views and foreign tables") and measured
+ * on PG 18.6. */
+export const PUBLIC_REVOCABLE_RELKINDS: ReadonlyArray<string> = ['r', 'v', 'm', 'f', 'p'];
+
+export const relkindIsPublicRevocable = (relkind: string): boolean =>
+  PUBLIC_REVOCABLE_RELKINDS.includes(relkind);

package/src/postgres/grants.ts

@@ -0,0 +1,110 @@
+/**
+ * `Postgres.Grants` — one declarative grant set for one role in one schema of one database:
+ * schema USAGE/CREATE, per-table privileges, per-column privileges, default privileges for
+ * future tables per creator role, and an optional clear of PUBLIC. Computed as a diff
+ * against the catalogs (`grants-read.ts`, through `aclexplode`), so a re-run with nothing
+ * changed emits nothing, and drift on any NAMED object is repaired. The lifecycle cores
+ * against any client live in `grants-ops.ts`; the refusals in `grants-refuse.ts`; the
+ * repair plans in `grants-plan.ts` and the offline diff in `grants-diff.ts`.
+ *
+ * ★ A GRANT SET CARRIES NO OWNERSHIP MARK (H1, same as `Postgres.Database`): `read` answers
+ *   `Unowned` for a match, so already-live grants need `adopt(true)` in the stack that
+ *   declares them. A target that holds NOTHING anywhere reads as ABSENT — that is a first
+ *   create, never an adoption of an empty schema.
+ * ★ OBJECTS THE DECLARED ROLE OWNS ARE LEFT ALONE (H2): the owner holds every privilege
+ *   implicitly and a `REVOKE` cannot take that away, so the repair and the delete skip
+ *   objects the catalogs say the role owns (grants-plan.ts, measured on PG 18.6).
+ * ⛔ SCOPE IS EXACTLY THE DECLARATION. Objects the declaration does not name are never
+ *   touched; removing an entry from the declaration is a DRIFT the reconcile repairs — the
+ *   removed names are revoked before the new declaration's plan runs, so taking an entry
+ *   away takes the privilege away. `delete` revokes what the LAST declaration named. PUBLIC
+ *   is only ever cleared, only when `revokeFromPublic: true`, and never re-granted.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
+import { declaredNames, namesFromAttrs, resolveProps } from './grants-declare.ts';
+import {
+  deleteWithClient,
+  diffPostgresGrants,
+  readWithClient,
+  reconcileWithClient,
+} from './grants-ops.ts';
+import type { PostgresConnection } from './connection.ts';
+import { withPg } from './connection.ts';
+import { databaseExists } from './database-sql.ts';
+import { PostgresGrantsDatabaseMissing } from './grants-errors.ts';
+
+export interface PostgresGrants extends Resource<
+  'Postgres.Grants',
+  PostgresGrantsProps,
+  PostgresGrantsAttributes,
+  never,
+  PostgresConnection
+> {}
+
+export const PostgresGrants = Resource<PostgresGrants>('Postgres.Grants', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Same dual `typeof` guard as `isPostgresDatabase` (see `database.ts` for the measured
+ * regression it exists to prevent). */
+export const isPostgresGrants = (value: unknown): value is PostgresGrants =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Postgres.Grants';
+
+/** The five lifecycle handlers. Exported on its own so a test drives the real implementation
+ * (see `database.ts` for why that matters). */
+export const postgresGrantsHandlers = PostgresGrants.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP — the same reasoning as Postgres.Database's list: a sweep of
+  //   every ACL row would enumerate grants nothing declared, across every role and schema.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ olds, output }) =>
+    Effect.gen(function* () {
+      const names =
+        output !== undefined ? namesFromAttrs(output) : declaredNames(resolveProps(olds));
+      // Probe over the FAMILY connection. Opening a database that does not exist yet
+      // fails untyped (`ConnectionError` over psql, `UnknownError` 3D000 over the socket);
+      // absence is a first create, the same rule `Postgres.Schema` uses.
+      const present = yield* withPg((pg) => databaseExists(pg, names.database));
+      if (!present) return undefined;
+      const live = yield* withPg(
+        (pg) => readWithClient(pg, names, output !== undefined),
+        names.database,
+      );
+      return live === undefined ? undefined : Unowned(live);
+    }),
+
+  diff: ({ news, output }) => diffPostgresGrants(news, output),
+
+  reconcile: ({ news, output }) =>
+    Effect.gen(function* () {
+      // Probe the declared database BEFORE opening it, like `read`/`delete`: a declaration
+      // whose database was dropped would otherwise fail untyped on connect (`ConnectionError`
+      // over psql, `UnknownError` 3D000 over the socket). A reconcile must write into an
+      // existing container, so a missing database is a typed refusal, not absence.
+      const present = yield* withPg((pg) => databaseExists(pg, news.database));
+      if (!present) {
+        return yield* Effect.fail(new PostgresGrantsDatabaseMissing({ database: news.database }));
+      }
+      return yield* withPg((pg) => reconcileWithClient(pg, news, output), news.database);
+    }),
+
+  delete: ({ olds }) =>
+    Effect.gen(function* () {
+      // Same missing-database rule as `read`: the probe stays on the family connection,
+      // so a dropped database never becomes a connect failure. `deleteWithClient` then
+      // proves `current_database()` on the declared database.
+      const present = yield* withPg((pg) => databaseExists(pg, olds.database));
+      if (!present) return;
+      return yield* withPg((pg) => deleteWithClient(pg, olds), olds.database);
+    }),
+});
+
+export const PostgresGrantsProvider = () =>
+  Provider.succeed(PostgresGrants, postgresGrantsHandlers);