@homeflare/alchemy 0.42.0 → 0.44.0

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

@@ -0,0 +1,158 @@
+/**
+ * The write-only password lifecycle (S25) against `fake-sql.ts`'s recording fake: the
+ * declaration is the NAME of an environment variable, the value exists only in memory and on
+ * the wire of the one dedicated `ALTER ROLE … PASSWORD` statement, and what state remembers is
+ * a scrypt seal. Create, adopt, rotate and the never-guessed refusals.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { seal, sealMatches } from '../secrets/write-only.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRoleCreateVanished, PostgresRolePasswordEnvUnsetError } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { 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 withPassword = {
+  ...baseProps,
+  password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' },
+};
+
+describe('password: create', () => {
+  test('travels in a dedicated ALTER, never in the CREATE, and only its seal lands in state', async () => {
+    const fake = makeFakeSql();
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' }),
+    );
+    expect(startingWith(fake, 'CREATE ROLE')[0]?.text.includes('PASSWORD')).toBe(false);
+    // The statement carries the SCRAM-SHA-256 verifier, never the plain value: this is the text
+    // that reaches the span attribute `db.query.text` on the socket transport and the inlined
+    // stdin on the runner transport, so both are covered by one assertion over the shared text.
+    const sent = startingWith(fake, 'ALTER ROLE').map((s) => s.text);
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatch(/^ALTER ROLE "seat-observability" WITH PASSWORD E'SCRAM-SHA-256\$/);
+    expect(JSON.stringify(fake.statements)).not.toContain('s3cret-value');
+    expect(JSON.stringify(attrs)).not.toContain('s3cret-value');
+    // The seal stays a seal of the plain value — only the wire form changed.
+    expect(sealMatches(attrs.passwordSeal, { password: 's3cret-value' })).toBe(true);
+  });
+
+  test('a missing environment value refuses before any statement — never a guess', async () => {
+    const fake = makeFakeSql();
+    const error = await fails(reconcileWithClient(fake, withPassword, {}));
+    expect(error).toBeInstanceOf(PostgresRolePasswordEnvUnsetError);
+    expect((error as PostgresRolePasswordEnvUnsetError).variable).toBe('PG_SEAT_ROLE_PASSWORD');
+    // The reconcile reads first (one SELECT); the refusal lands before any write statement.
+    expect(startingWith(fake, 'CREATE').length).toBe(0);
+    expect(startingWith(fake, 'ALTER').length).toBe(0);
+  });
+});
+
+describe('password: live role', () => {
+  test('a rotated environment value rewrites the password under a fresh seal', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'new' }, oldSeal),
+    );
+    const sent = startingWith(fake, 'ALTER ROLE').map((s) => s.text);
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatch(/^ALTER ROLE "seat-observability" WITH PASSWORD E'SCRAM-SHA-256\$/);
+    expect(JSON.stringify(fake.statements)).not.toContain('new');
+    expect(sealMatches(attrs.passwordSeal, { password: 'new' })).toBe(true);
+    expect(sealMatches(attrs.passwordSeal, { password: 'old' })).toBe(false);
+  });
+
+  test('an unchanged environment value sends no password statement and keeps the seal bit-identical', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'old' }, oldSeal),
+    );
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+    expect(attrs.passwordSeal).toBe(oldSeal);
+  });
+
+  test('an adopted role (empty seal) gets the password written on the first reconcile that holds it', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: 'first' }),
+    );
+    expect(startingWith(fake, 'ALTER ROLE').length).toBe(1);
+    expect(sealMatches(attrs.passwordSeal, { password: 'first' })).toBe(true);
+  });
+
+  test('an environment that went empty on a live role never churns the stored password', async () => {
+    const oldSeal = seal({ password: 'old' }, 'fixed-salt');
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    const attrs = await run(
+      reconcileWithClient(fake, withPassword, { PG_SEAT_ROLE_PASSWORD: '' }, oldSeal),
+    );
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+    expect(attrs.passwordSeal).toBe(oldSeal);
+  });
+
+  test('a declared password whose seal is still empty refuses an unset variable on the update path', async () => {
+    // CREATE ROLE committed, then ALTER ROLE … PASSWORD failed or the process died before state
+    // was saved. The next run sees the role and an empty seal. Reporting success would leave a
+    // LOGIN role this stack has never sealed.
+    const fake = makeFakeSql({ roleRows: [liveRole({ login: true })] });
+    const error = await fails(
+      reconcileWithClient(fake, { ...withPassword, login: true }, { PG_SEAT_ROLE_PASSWORD: '' }),
+    );
+    expect(error).toBeInstanceOf(PostgresRolePasswordEnvUnsetError);
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+  });
+});
+
+describe('password: no new write statements on the no-op path', () => {
+  test('a create with no password declared never mentions PASSWORD at all', async () => {
+    const fake = makeFakeSql();
+    await run(reconcileWithClient(fake, baseProps));
+    expect(fake.statements.some((s) => s.text.includes('PASSWORD'))).toBe(false);
+  });
+
+  test('a vanished create on a password-carrying reconcile fails typed, with the password statement issued first', async () => {
+    // The blank executor answers every read with `[]` (absent), so the reconcile takes the
+    // create path: CREATE, then the dedicated password ALTER, then a re-read that finds nothing.
+    // The typed `PostgresRoleCreateVanished` surfaces that — the value stayed on the wire, and
+    // the failure is never a secret leak.
+    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, withPassword, { PG_SEAT_ROLE_PASSWORD: 'v' }),
+    );
+    expect(error).toBeInstanceOf(PostgresRoleCreateVanished);
+  });
+});

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

@@ -0,0 +1,80 @@
+/**
+ * Adopt and alter of a role that already carries privileges this family never declares.
+ *
+ * The review of PR 336: `--adopt` of a SUPERUSER (or CREATEROLE / CREATEDB / REPLICATION /
+ * BYPASSRLS) role planned green and left the flag set, and a membership already granted
+ * `WITH ADMIN` matched by name so it was never revoked. `GRANT` also omitted `SET`, which
+ * upstream defaults to TRUE — a member can `SET ROLE` to the parent.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresRolePrivilegedRefused } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { 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-widget',
+  login: false,
+  connectionLimit: -1,
+  inherit: true,
+  memberOf: ['hf_agent'],
+};
+
+const liveRole = (over: Partial<PostgresRoleAttributes> = {}): PostgresRoleAttributes => ({
+  name: 'seat-widget',
+  oid: 20000,
+  login: false,
+  connectionLimit: -1,
+  inherit: true,
+  validUntil: null,
+  memberOf: ['hf_agent'],
+  passwordSeal: '',
+  superuser: false,
+  createrole: false,
+  createdb: false,
+  replication: false,
+  bypassrls: false,
+  ...over,
+});
+
+describe('adopted privilege flags', () => {
+  test('a live SUPERUSER is refused before any write', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole({ superuser: true })] });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresRolePrivilegedRefused);
+    expect(
+      fake.statements.some((s) => s.text.startsWith('ALTER') || s.text.startsWith('GRANT')),
+    ).toBe(false);
+  });
+
+  test('a membership granted WITH ADMIN by this session is repaired in place', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()], roles: ['hf_agent'] });
+    fake.memberships.add('seat-widget\0hf_agent\0postgres');
+    fake.membershipOptions.set('seat-widget\0hf_agent\0postgres', { admin: true, set: true });
+    await run(reconcileWithClient(fake, baseProps));
+    const texts = fake.statements.map((s) => s.text);
+    // `AddRoleMems` updates the session grantor's row. One full-options GRANT clears ADMIN
+    // and SET without a REVOKE that would drop the membership the declaration still wants.
+    expect(texts).toContain('GRANT "hf_agent" TO "seat-widget" WITH ADMIN FALSE, SET FALSE');
+    expect(texts.some((text) => text.startsWith('REVOKE'))).toBe(false);
+    expect(fake.memberships.has('seat-widget\0hf_agent\0postgres')).toBe(true);
+    expect(fake.membershipOptions.has('seat-widget\0hf_agent\0postgres')).toBe(false);
+  });
+
+  test("another grantor's ADMIN row is revoked by that grantor and the seat grant remains", async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()], roles: ['hf_agent'] });
+    fake.memberships.add('seat-widget\0hf_agent\0other');
+    fake.membershipOptions.set('seat-widget\0hf_agent\0other', { admin: true, set: true });
+    await run(reconcileWithClient(fake, baseProps));
+    const texts = fake.statements.map((s) => s.text);
+    expect(texts).toContain('GRANT "hf_agent" TO "seat-widget" WITH ADMIN FALSE, SET FALSE');
+    expect(texts).toContain('REVOKE "hf_agent" FROM "seat-widget" GRANTED BY "other"');
+    expect(fake.memberships.has('seat-widget\0hf_agent\0other')).toBe(false);
+    expect(fake.memberships.has('seat-widget\0hf_agent\0postgres')).toBe(true);
+    expect(fake.membershipOptions.has('seat-widget\0hf_agent\0postgres')).toBe(false);
+  });
+});

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

@@ -0,0 +1,200 @@
+/**
+ * Provenance: every `PostgresRoleProps` field traces to a real `CREATE ROLE` synopsis option AND
+ * a real `pg_authid`/`pg_auth_members` column, every synopsis option this family does NOT expose
+ * is named with a reason, and the `ALTER ROLE` synopsis backs every field the family alters (plus
+ * the "memberships move via GRANT and REVOKE" note the membership statements lean on). All four
+ * fixtures are parsed, not eyeballed — deleting a fixture line, or adding a prop with no mapping,
+ * fails this file (S38, the house's provenance rule).
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FIXTURES = join(import.meta.dir, 'fixtures');
+const createRole = readFileSync(join(FIXTURES, 'pg-REL_18_6-create_role.sgml.txt'), 'utf8');
+const alterRole = readFileSync(join(FIXTURES, 'pg-REL_18_6-alter_role.sgml.txt'), 'utf8');
+const authid = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_authid.h.txt'), 'utf8');
+const authMembers = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_auth_members.h.txt'), 'utf8');
+
+const CREATE_ROLE_BLOB = 'cee23b1ea6b4dcf2d9d356d07a582e64808c2912';
+const ALTER_ROLE_BLOB = '7b0a04bc4637c7c08246e597a9acf4466b467fa2';
+const AUTHID_BLOB = 'b2f3e9d01eec972a3392e7037c9679ac644ddc7b';
+const AUTH_MEMBERS_BLOB = '387316e44f07982264482f01f2298f4f85ffbafb';
+
+/** Each alternative of a "where <option> can be:" list, normalised to its leading keyword
+ * sequence, keeping the optional `[ ENCRYPTED ]` prefix and multi-word forms such as
+ * `CONNECTION LIMIT` / `VALID UNTIL` intact. */
+const optionTokens = (region: string): readonly string[] => {
+  const found: string[] = [];
+  for (const line of region.split('\n')) {
+    for (const raw of line.split('|')) {
+      const m = /^(\[ ENCRYPTED \] )?([A-Z]+(?: [A-Z]+)*)/.exec(raw.trim());
+      if (m !== null) found.push(`${m[1] ?? ''}${m[2] as string}`.trim());
+    }
+  }
+  return [...new Set(found)];
+};
+
+/** A `CATALOG` struct's column names, from the tab-indicated `type name;` lines. */
+const structColumns = (fixture: string): readonly string[] => {
+  const re = /^\t[A-Za-z_][A-Za-z0-9_]*\s+(\w+)(?:\[\d+\])?\b/;
+  return fixture
+    .split('\n')
+    .map((line) => re.exec(line)?.[1])
+    .filter((name): name is string => name !== undefined);
+};
+
+/** The create synopsis's option list: from the first `can be:</phrase>` to `</synopsis>`. */
+const createOptionsRegion = (): string => {
+  const start = createRole.indexOf('can be:</phrase>');
+  return createRole.slice(start, createRole.indexOf('</synopsis>', start));
+};
+
+/** The first ALTER variant's option list: from the first `can be:</phrase>` to `RENAME TO`. */
+const alterOptionsRegion = (): string => {
+  const start = alterRole.indexOf('can be:</phrase>');
+  return alterRole.slice(start, alterRole.indexOf('RENAME TO', start));
+};
+
+/** Every asserted prop except `name`, which is the mandatory `CREATE ROLE <name>` token, checked
+ * separately below. A boolean prop claims both its affirmative and its negative option. */
+const PROP_MAPPING: Readonly<
+  Record<string, { readonly option: string; readonly also?: string; readonly column: string }>
+> = {
+  login: { option: 'LOGIN', also: 'NOLOGIN', column: 'rolcanlogin' },
+  inherit: { option: 'INHERIT', also: 'NOINHERIT', column: 'rolinherit' },
+  connectionLimit: { option: 'CONNECTION LIMIT', column: 'rolconnlimit' },
+  validUntil: { option: 'VALID UNTIL', column: 'rolvaliduntil' },
+  // The value is never a prop (S25): the prop names the environment variable, and the value
+  // travels only in the dedicated `ALTER ROLE … WITH PASSWORD` statement.
+  password: { option: '[ ENCRYPTED ] PASSWORD', column: 'rolpassword' },
+};
+
+/** Every synopsis option this family does NOT declare as a prop, and why. */
+const EXCLUDED: Readonly<Record<string, string>> = {
+  SUPERUSER:
+    'left at the server default (NOSUPERUSER) on CREATE; an adopt or alter that finds rolsuper true is PostgresRolePrivilegedRefused — the flag is not inherited, SET ROLE exercises it',
+  NOSUPERUSER:
+    'the server default for CREATE ROLE; never declared, so the default is what a create lands on',
+  CREATEDB:
+    "left at the server default (NOCREATEDB); database creation is Postgres.Database's job, not a role prop",
+  NOCREATEDB: 'the server default for CREATE ROLE; never declared',
+  CREATEROLE:
+    'left at the server default (NOCREATEROLE) on CREATE; an adopt or alter that finds rolcreaterole true is refused — a CREATEROLE role can manage other roles',
+  NOCREATEROLE: 'the server default for CREATE ROLE; never declared',
+  REPLICATION:
+    'left at the server default (NOREPLICATION); replication is a cluster-operator concern, never a seat role',
+  NOREPLICATION: 'the server default for CREATE ROLE; never declared',
+  BYPASSRLS:
+    'left at the server default (NOBYPASSRLS) on CREATE; an adopt or alter that finds rolbypassrls true is refused',
+  NOBYPASSRLS: 'the server default for CREATE ROLE; never declared',
+  'PASSWORD NULL':
+    'clears the password; this family never clears one — a password is either declared by reference or left alone',
+  'IN ROLE':
+    'the create-time membership shorthand; this family writes memberships with one explicit GRANT per parent instead, so the re-read stays authoritative',
+  ROLE: 'grants the listed roles membership in the NEW role — the inverse of memberOf; membership is declared in one direction only',
+  ADMIN:
+    'grants membership with ADMIN OPTION; a live membership that already has admin_option is revoked and re-granted without it, and the seat GRANT says SET FALSE',
+  SYSID:
+    'ignored by the server since PostgreSQL 8.1 (the docs keep it only for compatibility); this family never assigns oids',
+};
+
+describe('postgres role provenance', () => {
+  test('fixture headers name the measured blob shas', () => {
+    expect(createRole).toContain(CREATE_ROLE_BLOB);
+    expect(createRole).toContain('doc/src/sgml/ref/create_role.sgml');
+    expect(alterRole).toContain(ALTER_ROLE_BLOB);
+    expect(alterRole).toContain('doc/src/sgml/ref/alter_role.sgml');
+    expect(authid).toContain(AUTHID_BLOB);
+    expect(authid).toContain('src/include/catalog/pg_authid.h');
+    expect(authMembers).toContain(AUTH_MEMBERS_BLOB);
+    expect(authMembers).toContain('src/include/catalog/pg_auth_members.h');
+  });
+
+  test('the name token is documented and backed by rolname', () => {
+    expect(createRole).toContain('CREATE ROLE <replaceable class="parameter">name</replaceable>');
+    expect(structColumns(authid)).toContain('rolname');
+  });
+
+  test('every declared prop maps to a real synopsis option (affirmative and negative)', () => {
+    const options = optionTokens(createOptionsRegion());
+    for (const [prop, { option, also }] of Object.entries(PROP_MAPPING)) {
+      expect(options, `prop "${prop}" claims synopsis option "${option}"`).toContain(option);
+      if (also !== undefined) {
+        expect(options, `prop "${prop}" claims negative option "${also}"`).toContain(also);
+      }
+    }
+  });
+
+  test('every declared prop maps to a real pg_authid column', () => {
+    const columns = structColumns(authid);
+    for (const [prop, { column }] of Object.entries(PROP_MAPPING)) {
+      expect(columns, `prop "${prop}" claims column "${column}"`).toContain(column);
+    }
+  });
+
+  test('memberOf is backed by the pg_auth_members catalog columns the membership read joins on', () => {
+    const columns = structColumns(authMembers);
+    expect(columns).toContain('roleid');
+    expect(columns).toContain('member');
+  });
+
+  test('every synopsis option is either a declared prop or a documented exclusion', () => {
+    const declared = new Set(
+      Object.values(PROP_MAPPING).flatMap((m) => [
+        m.option,
+        ...(m.also !== undefined ? [m.also] : []),
+      ]),
+    );
+    for (const option of optionTokens(createOptionsRegion())) {
+      const accounted = declared.has(option) || option in EXCLUDED;
+      expect(accounted, `synopsis option "${option}" is neither a prop nor in EXCLUDED`).toBe(true);
+    }
+  });
+
+  test('no excluded option is silently also a declared prop', () => {
+    const declared = new Set(
+      Object.values(PROP_MAPPING).flatMap((m) => [
+        m.option,
+        ...(m.also !== undefined ? [m.also] : []),
+      ]),
+    );
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(declared.has(option), `"${option}" is both excluded and declared`).toBe(false);
+    }
+  });
+
+  test('every excluded option actually exists in the synopsis (no stale entries)', () => {
+    const options = new Set(optionTokens(createOptionsRegion()));
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(
+        options.has(option),
+        `EXCLUDED names "${option}", which the synopsis no longer has`,
+      ).toBe(true);
+    }
+  });
+
+  test('ALTER ROLE backs every field this family alters', () => {
+    const alterOptions = optionTokens(alterOptionsRegion());
+    for (const option of Object.values(PROP_MAPPING).map((m) => m.option)) {
+      expect(alterOptions, `ALTER ROLE cannot set "${option}"`).toContain(option);
+    }
+  });
+
+  test('ALTER ROLE offers no membership or oid options, which is why memberships move via GRANT/REVOKE', () => {
+    const alterOptions = new Set(optionTokens(alterOptionsRegion()));
+    for (const option of ['IN ROLE', 'ROLE', 'ADMIN', 'SYSID']) {
+      expect(alterOptions.has(option), `ALTER ROLE unexpectedly offers "${option}"`).toBe(false);
+    }
+  });
+
+  test('the fixture carries the memberships sentence the one-parent GRANT/REVOKE design leans on', () => {
+    const stripped = alterRole.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ');
+    expect(stripped).toMatch(/no options[^;]*memberships/);
+    expect(stripped).toMatch(/use GRANT.{0,20}REVOKE/);
+  });
+
+  test('RENAME TO exists in the synopsis — the rename refusal is a choice, not an unknowing gap', () => {
+    expect(alterRole).toContain('RENAME TO');
+  });
+});

package/src/postgres/role-provider.ts

@@ -0,0 +1,104 @@
+/**
+ * `Postgres.Role`'s five lifecycle handlers, wired to `withPg` for anything that touches a
+ * client, and the one Layer a consuming stack provides. Split from `role.ts` so the file stays
+ * under the house cap: `role.ts` holds reconcile, `role-diff.ts` the plan diff; this file holds
+ * only the engine wiring.
+ */
+import * as Provider from 'alchemy/Provider';
+import { isResolved } from 'alchemy/Diff';
+import * as Effect from 'effect/Effect';
+import { ownedRead } from '../ownership/probe.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { PostgresRole } from './role.ts';
+import { readRole, reconcileWithClient, refuseAtPlan } from './role.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { PostgresRoleIdentityRefused } from './role-errors.ts';
+import { buildDropRoleSql, declarationMatches } from './role-sql.ts';
+import { withPg } from './connection.ts';
+
+export const postgresRoleHandlers = PostgresRole.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP: `pg_roles` lists every role on the cluster, most of which nothing
+  //   declared — the same reasoning `Postgres.Database`'s `list` documents.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ fqn, instanceId, olds, output }) =>
+    Effect.gen(function* () {
+      const name = output?.name ?? olds.name;
+      const live = yield* withPg((pg) => readRole(pg, name));
+      if (live === undefined) return undefined;
+      // A recycled name is not the role state recorded. Failing (rather than `Unowned`) matters
+      // because drift strips `Unowned` and would then reconcile the foreign role.
+      if (output !== undefined && live.oid !== output.oid) {
+        return yield* Effect.fail(
+          new PostgresRoleIdentityRefused({
+            role: name,
+            storedOid: output.oid,
+            liveOid: live.oid,
+          }),
+        );
+      }
+      const passwordSeal = output?.passwordSeal ?? '';
+      const found = { ...live, passwordSeal };
+      return yield* ownedRead(
+        { fqn, instanceId, output },
+        found,
+        Effect.succeed(declarationMatches(olds, live)),
+      );
+    }),
+
+  diff: ({ news, output, instanceId }) =>
+    Effect.gen(function* () {
+      // A `creating` row has no attributes. Mark it unfinished so `--adopt` can resume it
+      // (ownership/resume.ts); the engine treats `undefined` as "defer".
+      if (output === undefined) return yield* noteUnfinished(instanceId);
+      if (!isResolved(news)) return undefined;
+      const found = yield* withPg((pg) => readRole(pg, output.name));
+      return yield* diffPostgresRole(news, output, process.env, { found });
+    }),
+
+  reconcile: ({ fqn, instanceId, news, output }) =>
+    Effect.gen(function* () {
+      yield* refuseAtPlan(news);
+      return yield* withPg((pg) =>
+        Effect.gen(function* () {
+          // Alchemy skips the plan probe while a prop is still an Output, and a role can
+          // appear between plan and apply. A live role with no state is a takeover: refuse
+          // before any ALTER, PASSWORD or REVOKE, unless `--adopt` speaks for this apply.
+          const observed = yield* readRole(pg, news.name);
+          if (observed !== undefined && output === undefined) {
+            yield* refuseTakeover({ fqn, instanceId, output }, 'Postgres.Role');
+          }
+          return yield* reconcileWithClient(
+            pg,
+            news,
+            process.env,
+            output?.passwordSeal,
+            output?.oid,
+          );
+        }),
+      );
+    }),
+
+  delete: ({ output }) =>
+    withPg((pg) =>
+      Effect.gen(function* () {
+        if (output === undefined) return;
+        const live = yield* readRole(pg, output.name);
+        if (live === undefined) return;
+        if (live.oid !== output.oid) {
+          return yield* Effect.fail(
+            new PostgresRoleIdentityRefused({
+              role: output.name,
+              storedOid: output.oid,
+              liveOid: live.oid,
+            }),
+          );
+        }
+        yield* pg.unsafe(buildDropRoleSql(output.name)).pipe(Effect.asVoid);
+      }),
+    ),
+});
+
+export const PostgresRoleProvider = () => Provider.succeed(PostgresRole, postgresRoleHandlers);