@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/role-identity.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Oid identity, live membership options, and the unfinished-create resume. The engine passes
+ * stored attributes to `diff` and calls `read` with `output: undefined` on a `creating` row;
+ * these tests drive `postgresRoleHandlers` the way that engine does, over the runner transport.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { Artifacts, makeScopedArtifacts } from 'alchemy/Artifacts';
+import { InMemoryService } from 'alchemy/State/InMemoryState';
+import { State } from 'alchemy/State/State';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import { unfinished } from '../ownership/resume.ts';
+import { postgresRunnerConnection } from './connection.ts';
+import { parseLiteral } from './fake-sql-quote.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { type PsqlRunner } from './psql-executor.ts';
+import { PostgresRoleIdentityRefused } from './role-errors.ts';
+import { postgresRoleHandlers } from './role-provider.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+
+const baseProps: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const stored = (): PostgresRoleAttributes => ({
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: ['hf_agent'],
+  passwordSeal: '',
+});
+
+/** Same envelope the adopt test uses: `withPg` wraps a SELECT in `json_agg` and inlines `$1`. */
+const runnerFor =
+  (fake: ReturnType<typeof makeFakeSql>): PsqlRunner =>
+  async ({ stdin }) => {
+    const wrapped = /^SELECT coalesce\(json_agg\(t\), '\[\]'::json\)::text FROM \((.*)\) t;$/s.exec(
+      stdin,
+    );
+    const body = (wrapped?.[1] ?? stdin).replace(/;\s*$/, '');
+    const bound = /^([\s\S]*) = (E'[\s\S]*')$/.exec(body);
+    const sql = bound === null ? body : `${bound[1]} = $1`;
+    const params = bound === null ? [] : [parseLiteral(bound[2] as string)];
+    const rows = await Effect.runPromise(fake.unsafe(sql, params));
+    return { code: 0, stdout: JSON.stringify(rows), stderr: '' };
+  };
+
+const layerFor = (fake: ReturnType<typeof makeFakeSql>) =>
+  postgresRunnerConnection({
+    run: runnerFor(fake),
+    database: 'postgres',
+    username: 'postgres',
+  });
+
+const handlers = postgresRoleHandlers;
+if (handlers.read === undefined || handlers.diff === undefined || handlers.delete === undefined) {
+  throw new Error('Postgres.Role read, diff and delete are part of the provider');
+}
+const readRoleHandler = handlers.read;
+const diffRoleHandler = handlers.diff;
+const deleteRoleHandler = handlers.delete;
+
+const ids = {
+  id: 'seat-observability',
+  fqn: 'Postgres.Role/seat-observability',
+  instanceId: 'i',
+};
+
+describe('oid and live membership options', () => {
+  test('a recycled oid is refused on read, diff and delete, and delete issues no DROP', async () => {
+    const fake = makeFakeSql({ roleRows: [{ ...stored(), oid: 7 }] });
+    const output = stored();
+    const provided = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      effect.pipe(Effect.provide(layerFor(fake)));
+    const readError = await Effect.runPromise(
+      Effect.flip(provided(readRoleHandler({ ...ids, olds: baseProps, output }))),
+    );
+    expect(readError).toBeInstanceOf(PostgresRoleIdentityRefused);
+    const diffError = await Effect.runPromise(
+      Effect.flip(
+        provided(
+          diffRoleHandler({
+            ...ids,
+            olds: baseProps,
+            news: { ...baseProps, memberOf: ['hf_agent'] },
+            output,
+            oldBindings: [],
+            newBindings: [],
+          }),
+        ),
+      ),
+    );
+    expect(diffError).toBeInstanceOf(PostgresRoleIdentityRefused);
+    await Effect.runPromise(
+      Effect.flip(
+        provided(
+          deleteRoleHandler({
+            ...ids,
+            olds: baseProps,
+            output,
+            session: {} as never,
+            bindings: [],
+          }),
+        ),
+      ),
+    );
+    expect(fake.statements.some((s) => s.text.startsWith('DROP'))).toBe(false);
+  });
+
+  test('diff reads live ADMIN even though stored output has no membership rows', async () => {
+    const fake = makeFakeSql({ roleRows: [stored()] });
+    fake.memberships.add('seat-observability\0hf_agent\0postgres');
+    fake.membershipOptions.set('seat-observability\0hf_agent\0postgres', {
+      admin: true,
+      set: false,
+    });
+    const plan = await Effect.runPromise(
+      diffRoleHandler({
+        ...ids,
+        olds: baseProps,
+        news: { ...baseProps, memberOf: ['hf_agent'] },
+        output: stored(),
+        oldBindings: [],
+        newBindings: [],
+      }).pipe(Effect.provide(layerFor(fake))),
+    );
+    expect(plan).toEqual({ action: 'update' });
+  });
+
+  test('a creating row with no attributes is noted unfinished', async () => {
+    const bag = makeScopedArtifacts(new Map(), ids.fqn);
+    const plan = await Effect.runPromise(
+      diffRoleHandler({
+        ...ids,
+        instanceId: 'creating-1',
+        olds: baseProps,
+        news: baseProps,
+        output: undefined,
+        oldBindings: [],
+        newBindings: [],
+      }).pipe(Effect.provideService(Artifacts, bag), Effect.provide(layerFor(makeFakeSql()))),
+    );
+    expect(plan).toBeUndefined();
+    expect(
+      await Effect.runPromise(unfinished('creating-1').pipe(Effect.provideService(Artifacts, bag))),
+    ).toBe(true);
+  });
+
+  test('a creating row whose live role matches the declaration is ours', async () => {
+    const fake = makeFakeSql({ roleRows: [{ ...stored(), memberOf: [] }] });
+    const row = {
+      fqn: ids.fqn,
+      instanceId: 'creating-1',
+      status: 'creating',
+      props: baseProps,
+    };
+    const found = await Effect.runPromise(
+      readRoleHandler({
+        ...ids,
+        instanceId: 'creating-1',
+        olds: baseProps,
+        output: undefined,
+      }).pipe(
+        Effect.provide(layerFor(fake)),
+        Effect.provideService(State, InMemoryService({ s: { test: { [ids.fqn]: row as never } } })),
+        Effect.provideService(Stack, {
+          actions: {},
+          bindings: {},
+          name: 's',
+          resources: { [ids.fqn]: { Props: baseProps } },
+          stage: 'test',
+        } as never),
+      ),
+    );
+    expect(Unowned.is(found)).toBe(false);
+    expect(found?.oid).toBe(20000);
+  });
+});

package/src/postgres/role-lifecycle.test.ts

@@ -0,0 +1,228 @@
+/**
+ * `reconcile`, `read` and the drop statement against `fake-sql.ts`'s recording fake — greenfield
+ * create with exact statement text, membership `GRANT`/`REVOKE`, per-field scalar drift, a create
+ * whose re-read finds nothing, and zero statements when nothing drifted. The password lifecycle
+ * is `role-password.test.ts`; the plan-time refusals are `role-refusals.test.ts`. Every case
+ * reverts cleanly by reverting `role.ts`/`role-sql.ts`/`role-membership-sql.ts`/`fake-sql.ts`
+ * locally: these fail on `origin/main`, which has none of them.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRoleCreateVanished } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { readRole, reconcileWithClient } from './role.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 baseProps: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const liveRole = (over: Partial<PostgresRoleAttributes> = {}): PostgresRoleAttributes => ({
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+  ...over,
+});
+
+const startingWith = (fake: ReturnType<typeof makeFakeSql>, prefix: string) =>
+  fake.statements.filter((s) => s.text.startsWith(prefix));
+
+const writeStatements = (fake: ReturnType<typeof makeFakeSql>) =>
+  fake.statements.filter(
+    (s) =>
+      s.text.startsWith('CREATE') ||
+      s.text.startsWith('ALTER') ||
+      s.text.startsWith('GRANT') ||
+      s.text.startsWith('REVOKE') ||
+      s.text.startsWith('DROP'),
+  );
+
+describe('reconcile: greenfield', () => {
+  test('issues exactly one CREATE with the seat shape, and nothing else', async () => {
+    const fake = makeFakeSql();
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs.name).toBe('seat-observability');
+    expect(startingWith(fake, 'CREATE ROLE')).toEqual([
+      {
+        text: 'CREATE ROLE "seat-observability" WITH NOLOGIN INHERIT CONNECTION LIMIT 10',
+        params: [],
+      },
+    ]);
+    expect(writeStatements(fake).length).toBe(1);
+  });
+
+  test('a LOGIN role with an expiry carries VALID UNTIL last, quoted', async () => {
+    const fake = makeFakeSql();
+    const props = {
+      name: 'seat-alice',
+      login: true,
+      connectionLimit: 10,
+      inherit: true,
+      validUntil: '2027-01-01T00:00:00Z',
+    };
+    const attrs = await run(reconcileWithClient(fake, props));
+    expect(attrs.validUntil).toBe('2027-01-01T00:00:00Z');
+    expect(startingWith(fake, 'CREATE ROLE')[0]?.text).toBe(
+      'CREATE ROLE "seat-alice" WITH LOGIN INHERIT CONNECTION LIMIT 10 VALID UNTIL E\'2027-01-01T00:00:00Z\'',
+    );
+  });
+
+  test('declared memberships become one-parent GRANTs after the CREATE, and the answer comes from the re-read, sorted', async () => {
+    const fake = makeFakeSql({ roles: ['hf_agent', 'seat-b'] });
+    const attrs = await run(
+      reconcileWithClient(fake, { ...baseProps, memberOf: ['seat-b', 'hf_agent'] }),
+    );
+    expect(startingWith(fake, 'GRANT')).toEqual([
+      { text: 'GRANT "hf_agent" TO "seat-observability" WITH SET FALSE', params: [] },
+      { text: 'GRANT "seat-b" TO "seat-observability" WITH SET FALSE', params: [] },
+    ]);
+    expect(attrs.memberOf).toEqual(['hf_agent', 'seat-b']);
+  });
+
+  test('a hostile role name survives the round trip through the fake\u2019s own catalog', async () => {
+    const fake = makeFakeSql();
+    const attrs = await run(reconcileWithClient(fake, { ...baseProps, name: 'a"b-c' }));
+    expect(attrs.name).toBe('a"b-c');
+    expect(startingWith(fake, 'CREATE ROLE')[0]?.text).toBe(
+      'CREATE ROLE "a""b-c" WITH NOLOGIN INHERIT CONNECTION LIMIT 10',
+    );
+  });
+
+  test('a create whose re-read finds nothing fails with the typed tag, not a guess (S10/S20)', async () => {
+    const unsafe = <A extends object>(_sql?: string) => Effect.succeed([] as ReadonlyArray<A>);
+    const blankPg: PgExecutor = {
+      unsafe,
+      transaction: (statements) =>
+        Effect.gen(function* () {
+          for (const sql of statements) yield* unsafe(sql).pipe(Effect.asVoid);
+        }),
+    };
+    const error = await fails(reconcileWithClient(blankPg, baseProps));
+    expect(error).toBeInstanceOf(PostgresRoleCreateVanished);
+  });
+});
+
+describe('reconcile: already present', () => {
+  test('no drift issues zero write statements and returns the live row', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs).toEqual(liveRole());
+    expect(writeStatements(fake).length).toBe(0);
+  });
+
+  test('scalar drift issues exactly one ALTER per drifted field, in the compared order', async () => {
+    const fake = makeFakeSql({
+      roleRows: [
+        liveRole({
+          login: true,
+          inherit: false,
+          connectionLimit: 1,
+          validUntil: '2026-01-01T00:00:00.000Z',
+        }),
+      ],
+    });
+    const props = {
+      ...baseProps,
+      login: false,
+      inherit: true,
+      connectionLimit: 10,
+      validUntil: '2027-01-01T00:00:00Z',
+    };
+    const attrs = await run(reconcileWithClient(fake, props));
+    expect(startingWith(fake, 'ALTER ROLE').map((s) => s.text)).toEqual([
+      'ALTER ROLE "seat-observability" WITH NOLOGIN',
+      'ALTER ROLE "seat-observability" WITH INHERIT',
+      'ALTER ROLE "seat-observability" WITH CONNECTION LIMIT 10',
+      'ALTER ROLE "seat-observability" WITH VALID UNTIL E\'2027-01-01T00:00:00Z\'',
+    ]);
+    expect(attrs.connectionLimit).toBe(10);
+  });
+
+  test('a validUntil the server serialised with milliseconds is the same instant, so no ALTER', async () => {
+    const fake = makeFakeSql({
+      roleRows: [liveRole({ validUntil: '2027-01-01T00:00:00.000Z' })],
+    });
+    await run(reconcileWithClient(fake, { ...baseProps, validUntil: '2027-01-01T00:00:00Z' }));
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+  });
+
+  test('a membership the declaration adds is granted; a live one it drops is revoked by its grantor', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()], roles: ['seat-owners'] });
+    fake.memberships.add('seat-observability\0hf_agent\0postgres');
+    const attrs = await run(reconcileWithClient(fake, { ...baseProps, memberOf: ['seat-owners'] }));
+    expect(startingWith(fake, 'GRANT').map((s) => s.text)).toEqual([
+      'GRANT "seat-owners" TO "seat-observability" WITH SET FALSE',
+    ]);
+    expect(startingWith(fake, 'REVOKE').map((s) => s.text)).toEqual([
+      'REVOKE "hf_agent" FROM "seat-observability" GRANTED BY "postgres"',
+    ]);
+    expect(attrs.memberOf).toEqual(['seat-owners']);
+  });
+
+  test('memberOf [] revokes everything; memberOf undefined touches nothing', async () => {
+    const revoking = makeFakeSql({ roleRows: [liveRole()] });
+    revoking.memberships.add('seat-observability\0hf_agent\0postgres');
+    const afterRevoke = await run(reconcileWithClient(revoking, { ...baseProps, memberOf: [] }));
+    expect(afterRevoke.memberOf).toEqual([]);
+
+    const untouched = makeFakeSql({ roleRows: [liveRole()] });
+    untouched.memberships.add('seat-observability\0hf_agent\0postgres');
+    const afterNoop = await run(reconcileWithClient(untouched, baseProps));
+    expect(afterNoop.memberOf).toEqual(['hf_agent']);
+    expect(
+      untouched.statements.some((s) => s.text.startsWith('GRANT') || s.text.startsWith('REVOKE')),
+    ).toBe(false);
+  });
+});
+
+describe('read', () => {
+  test('answers undefined when the role is absent', async () => {
+    const fake = makeFakeSql();
+    expect(await run(readRole(fake, 'seat-observability'))).toBeUndefined();
+  });
+
+  test('answers the live row with memberships merged in, sorted \u2014 no seal; branding and the seal merge are the caller\u2019s job', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    fake.memberships.add('seat-observability\0seat-b\0postgres');
+    fake.memberships.add('seat-observability\0hf_agent\0postgres');
+    expect(await run(readRole(fake, 'seat-observability'))).toEqual({
+      name: 'seat-observability',
+      oid: 20000,
+      login: false,
+      connectionLimit: 10,
+      inherit: true,
+      validUntil: null,
+      memberOf: ['hf_agent', 'seat-b'],
+      memberships: [
+        { parent: 'hf_agent', grantor: 'postgres', admin: false, set: false },
+        { parent: 'seat-b', grantor: 'postgres', admin: false, set: false },
+      ],
+    });
+  });
+});
+
+describe('delete statement', () => {
+  test('is the idempotent quoted DROP, and the fake applies it to the row and touching memberships', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    fake.memberships.add('seat-observability\0hf_agent\0postgres');
+    fake.memberships.add('other-role\0seat-observability\0postgres');
+    await run(fake.unsafe('DROP ROLE IF EXISTS "seat-observability"').pipe(Effect.asVoid));
+    expect(fake.roleRows.has('seat-observability')).toBe(false);
+    expect(fake.memberships.has('seat-observability\0hf_agent\0postgres')).toBe(false);
+    expect(fake.memberships.has('other-role\0seat-observability\0postgres')).toBe(false);
+    // Idempotent: the same statement against the now-absent role is not an error.
+    await run(fake.unsafe('DROP ROLE IF EXISTS "seat-observability"').pipe(Effect.asVoid));
+  });
+});

package/src/postgres/role-membership-sql.ts

@@ -0,0 +1,198 @@
+/**
+ * Membership statements and the catalog read behind them, split out of `role-sql.ts`
+ * (file cap). One file so `diff`, reconcile and the fake agree on the exact texts.
+ *
+ * ★ ONE PARENT PER STATEMENT. `pg_auth_members` keys a membership on three columns —
+ *   (parent, member, grantor) — so more than one row can exist for one parent name:
+ *   another grantor's `ADMIN`-option grant rides beside the safe one. A multi-role
+ *   `GRANT`/`REVOKE` list would make a partially-failed write harder to attribute.
+ * ★ SEAT GRANTS SAY `SET FALSE`. Upstream `GRANT` defaults `SET` to TRUE (`grant.sgml` at
+ *   REL_18_6), and `SET ROLE` to the parent is how `SUPERUSER` / `CREATEROLE` / `CREATEDB`
+ *   are exercised (`user-manag.sgml`). A safe seat membership is `ADMIN FALSE, SET FALSE`.
+ * ⛔ REVOKE BY GRANTOR. A plain `REVOKE parent FROM member` only touches rows the session's
+ *   own grantor made; Postgres 18 warns and leaves another grantor's rows standing
+ *   (`revoke.sgml`). Every revoke here names `GRANTED BY`, so the statement either removes
+ *   the row it targets or fails loudly — never a silent no-op.
+ */
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { quoteIdent, roleExists } from './database-sql.ts';
+import { PostgresRoleMembershipUnrepaired, PostgresRoleParentMissing } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+
+/** One `pg_auth_members` row as this family reads it: the parent name, the grantor who made
+ * the grant, and the two options a name-only compare would hide. `admin` true is `WITH ADMIN`;
+ * `set` true (the `GRANT` default) lets the member `SET ROLE` to the parent. `grantor` is null
+ * when the granting role was later dropped — such a row can never be named in a `REVOKE …
+ * GRANTED BY`, so it can only be repaired by hand as a bootstrap superuser. */
+export interface MembershipRow {
+  readonly parent: string;
+  readonly grantor: string | null;
+  readonly admin: boolean;
+  readonly set: boolean;
+}
+
+const MEMBERSHIP_SQL = `SELECT parent.rolname AS parent,
+    grantor.rolname AS grantor,
+    m.admin_option AS admin,
+    m.set_option AS set
+  FROM pg_auth_members m
+  JOIN pg_roles member ON member.oid = m.member
+  JOIN pg_roles parent ON parent.oid = m.roleid
+  LEFT JOIN pg_roles grantor ON grantor.oid = m.grantor
+  WHERE member.rolname = $1
+  ORDER BY parent.rolname, grantor.rolname NULLS FIRST`;
+
+export const selectRoleMemberships = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<readonly MembershipRow[], SqlError> =>
+  Effect.map(pg.unsafe<MembershipRow>(MEMBERSHIP_SQL, [name]), (rows) => rows);
+
+/** Seat grants say `SET FALSE`. Upstream `GRANT` defaults `SET` to TRUE, and `SET ROLE` to the
+ * parent is how `SUPERUSER` / `CREATEROLE` / `CREATEDB` are exercised (`user-manag.sgml`). */
+export const buildGrantMembershipSql = (member: string, parent: string): string =>
+  `GRANT ${quoteIdent(parent)} TO ${quoteIdent(member)} WITH SET FALSE`;
+
+/** Repair an existing membership in place: one atomic full-options `GRANT` per parent.
+ * Upstream keeps any `WITH` option the new `GRANT` omits (`grant.sgml`), so a repair must
+ * spell both bits — `ADMIN FALSE, SET FALSE` — rather than rely on `SET FALSE` alone. */
+export const buildRepairMembershipSql = (member: string, parent: string): string =>
+  `GRANT ${quoteIdent(parent)} TO ${quoteIdent(member)} WITH ADMIN FALSE, SET FALSE`;
+
+/** Remove one grantor's row for one parent. Naming the grantor is what makes the revoke
+ * bind: a plain `REVOKE` skips rows other grantors made (`revoke.sgml`). */
+export const buildRevokeGrantorMembershipSql = (
+  member: string,
+  parent: string,
+  grantor: string,
+): string =>
+  `REVOKE ${quoteIdent(parent)} FROM ${quoteIdent(member)} GRANTED BY ${quoteIdent(grantor)}`;
+
+/** Catalog flags this family never declares. A create lands on the server default (all false);
+ * an absent field on a seeded test row is that default. */
+export const unsafeMemberships = (
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+): ReadonlySet<string> =>
+  new Set((live.memberships ?? []).filter((row) => row.admin || row.set).map((row) => row.parent));
+
+/** Membership drift: sorted set difference between declared and live. Duplicates in the
+ * declaration collapse to one; `undefined` means "not asserted" — nothing to grant or revoke.
+ * A parent already granted `WITH ADMIN`, or with `SET` still at the upstream default TRUE, is
+ * a grant again: the name matches, but the options do not, so reconcile repairs in place. */
+export const membershipDrift = (
+  declared: readonly string[] | undefined,
+  live: readonly string[],
+  unsafe: ReadonlySet<string> = new Set(),
+): { readonly grants: readonly string[]; readonly revokes: readonly string[] } => {
+  if (declared === undefined) return { grants: [], revokes: [] };
+  const wanted = [...new Set(declared)].sort();
+  const current = [...new Set(live)].sort();
+  return {
+    grants: wanted.filter((parent) => !current.includes(parent) || unsafe.has(parent)),
+    revokes: [
+      ...current.filter((parent) => !wanted.includes(parent)),
+      ...wanted.filter((parent) => current.includes(parent) && unsafe.has(parent)),
+    ],
+  };
+};
+
+/** Refuse before any membership write when a declared parent is not in `pg_roles`. `GRANT` of a
+ * missing role is `42704` (`user.c@REL_18_6`), and on a create that error arrives only after
+ * `CREATE ROLE` has committed. */
+export const assertParentsExist = (
+  pg: PgExecutor,
+  role: string,
+  parents: readonly string[] | undefined,
+): Effect.Effect<void, PostgresRoleParentMissing | SqlError> =>
+  Effect.gen(function* () {
+    if (parents === undefined) return;
+    for (const parent of [...new Set(parents)].sort()) {
+      if (!(yield* roleExists(pg, parent))) {
+        return yield* Effect.fail(new PostgresRoleParentMissing({ role, parent }));
+      }
+    }
+  });
+
+/** Make live memberships equal the declaration, never dropping a membership the declaration
+ * keeps. A wanted parent that is already granted is repaired with one
+ * `GRANT … WITH ADMIN FALSE, SET FALSE` — `AddRoleMems` updates that grantor's row in place
+ * (`user.c@REL_18_6` `SearchSysCache3` on role, member, grantor) — and any other grantor's
+ * unsafe row is then revoked by name.
+ *
+ * 1. Rows the declaration does not want are revoked **by their own grantor** (dead-grantor
+ *    rows are skipped and left for the backstop to report).
+ * 2. Unsafe-but-wanted rows get one full-options repair `GRANT` per parent — atomic, in place,
+ *    so the membership never drops even when another grantor's row also exists.
+ * 3. A repair leaves other grantors' unsafe rows beside the safe one, so a mid re-read
+ *    revokes every remaining unsafe row with a live grantor.
+ * 4. Absent-but-wanted parents get a fresh seat grant.
+ * 5. Backstop re-read: any row that is not wanted, or still unsafe, fails typed — including a
+ *    dead-grantor row, which no statement this family may issue can repair. */
+export const syncMemberships = (
+  pg: PgExecutor,
+  props: PostgresRoleProps,
+  rows: readonly MembershipRow[],
+): Effect.Effect<
+  readonly string[],
+  SqlError | PostgresRoleMembershipUnrepaired | PostgresRoleParentMissing
+> =>
+  Effect.gen(function* () {
+    if (props.memberOf === undefined) {
+      return [...new Set(rows.map((row) => row.parent))].sort();
+    }
+    yield* assertParentsExist(pg, props.name, props.memberOf);
+    const wanted = [...new Set(props.memberOf)].sort();
+    // 1. Not-wanted rows: revoke each by its own grantor (dead-grantor rows skipped; the
+    //    backstop catches them).
+    for (const row of rows) {
+      if (wanted.includes(row.parent) || row.grantor === null) continue;
+      yield* pg
+        .unsafe(buildRevokeGrantorMembershipSql(props.name, row.parent, row.grantor))
+        .pipe(Effect.asVoid);
+    }
+    // 2. Unsafe-but-wanted rows: one full-options repair `GRANT` per parent.
+    const repaired = [
+      ...new Set(
+        rows
+          .filter(
+            (row) => wanted.includes(row.parent) && (row.admin || row.set) && row.grantor !== null,
+          )
+          .map((row) => row.parent),
+      ),
+    ];
+    for (const parent of repaired) {
+      yield* pg.unsafe(buildRepairMembershipSql(props.name, parent)).pipe(Effect.asVoid);
+    }
+    // 3. If any repair ran, other grantors' unsafe rows may still stand: re-read and revoke
+    //    them by grantor (the repair's own safe row remains).
+    if (repaired.length > 0) {
+      const midRead = yield* selectRoleMemberships(pg, props.name);
+      for (const row of midRead) {
+        if (wanted.includes(row.parent) && (row.admin || row.set) && row.grantor !== null) {
+          yield* pg
+            .unsafe(buildRevokeGrantorMembershipSql(props.name, row.parent, row.grantor))
+            .pipe(Effect.asVoid);
+        }
+      }
+    }
+    // 4. Absent-but-wanted parents: fresh seat grant.
+    for (const parent of wanted.filter((p) => !rows.some((row) => row.parent === p))) {
+      yield* pg.unsafe(buildGrantMembershipSql(props.name, parent)).pipe(Effect.asVoid);
+    }
+    // 5. Backstop: anything not wanted or still unsafe fails typed.
+    for (const row of yield* selectRoleMemberships(pg, props.name)) {
+      if (!wanted.includes(row.parent) || row.admin || row.set) {
+        return yield* Effect.fail(
+          new PostgresRoleMembershipUnrepaired({
+            role: props.name,
+            parent: row.parent,
+            grantor: row.grantor,
+            declared: wanted.includes(row.parent),
+          }),
+        );
+      }
+    }
+    return wanted;
+  });