@homeflare/alchemy 0.43.0 → 0.44.0

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;
+  });

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);
+  });
+});