@homeflare/alchemy 0.42.0 → 0.44.0

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

@@ -0,0 +1,250 @@
+/**
+ * Every plan-time refusal and offline comparison, checked without a client: name-byte precision
+ * (the truncation trap `Postgres.Database` refuses), the rename refusal, a full sweep proving
+ * `diff` answers `update` and never `replace`, per-field and membership drift semantics,
+ * quoting, and the write-only password shape (S25). Zone-free and unparseable `validUntil`
+ * live in `role-valid-until.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { POSTGRES_NAME_MAX_BYTES } from './database-attrs.ts';
+import { refuseAtPlan } from './role.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { resolvePassword } from './role-secrets.ts';
+import { seal } from '../secrets/write-only.ts';
+import { PostgresRoleNameRefused, PostgresRoleRenameRefused } from './role-errors.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import {
+  buildAlterRoleSql,
+  buildCreateRoleSql,
+  buildDropRoleSql,
+  buildSetPasswordSql,
+  scalarDrift,
+} from './role-sql.ts';
+import {
+  buildGrantMembershipSql,
+  buildRevokeGrantorMembershipSql,
+  membershipDrift,
+} from './role-membership-sql.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 base: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const output: PostgresRoleAttributes = {
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+};
+
+describe('name byte length', () => {
+  test('a 63-byte ASCII name passes the plan check', async () => {
+    await run(refuseAtPlan({ ...base, name: 'a'.repeat(63) }));
+  });
+
+  test('a 64-byte ASCII name is refused with the typed tag naming the measurement', async () => {
+    const error = await fails(refuseAtPlan({ ...base, name: 'a'.repeat(64) }));
+    expect(error).toBeInstanceOf(PostgresRoleNameRefused);
+    expect((error as PostgresRoleNameRefused).byteLength).toBe(64);
+    expect((error as PostgresRoleNameRefused).limit).toBe(POSTGRES_NAME_MAX_BYTES);
+  });
+
+  test('a 64-byte multibyte name is refused though .length is 32', async () => {
+    // U+00E9 ("é") is 2 UTF-8 bytes; 32 of them is 64 bytes — over the 63-byte limit.
+    const error = await fails(refuseAtPlan({ ...base, name: 'é'.repeat(32) }));
+    expect(error).toBeInstanceOf(PostgresRoleNameRefused);
+  });
+});
+
+describe('diff', () => {
+  test('a rename is refused at plan, before reconcile ever runs', async () => {
+    const error = await fails(diffPostgresRole({ ...base, name: 'seat-logs' }, output));
+    expect(error).toBeInstanceOf(PostgresRoleRenameRefused);
+  });
+
+  test('an unchanged declaration answers noop, and no output answers undefined (nothing to diff)', async () => {
+    expect(await run(diffPostgresRole(base, output))).toEqual({ action: 'noop' });
+    expect(await run(diffPostgresRole(base, undefined))).toBeUndefined();
+  });
+
+  test('a change in any single prop answers update, and NEVER replace \u2014 swept across every prop', async () => {
+    const variants: ReadonlyArray<
+      readonly [Partial<PostgresRoleProps>, Partial<PostgresRoleAttributes>]
+    > = [
+      [{ login: true }, {}],
+      [{ inherit: false }, {}],
+      [{ connectionLimit: 5 }, {}],
+      [{ validUntil: '2027-01-01T00:00:00Z' }, {}],
+      [{ memberOf: ['hf_agent'] }, {}],
+      [{ memberOf: [] }, { memberOf: ['hf_agent'] }],
+      [{ memberOf: ['hf_agent', 'seat-owners'] }, { memberOf: ['hf_agent'] }],
+    ];
+    for (const [variant, live] of variants) {
+      const result = await run(diffPostgresRole({ ...base, ...variant }, { ...output, ...live }));
+      expect(result?.action, `variant ${JSON.stringify(variant)}`).toBe('update');
+      expect(result).not.toEqual({ action: 'replace' });
+    }
+  });
+
+  test('ADMIN or SET on the live read answers update; stored membership rows do not', async () => {
+    const declared = { ...base, memberOf: ['hf_agent'] as const };
+    const stored = { ...output, memberOf: ['hf_agent'] as const };
+    const row = (admin: boolean, set: boolean) => ({
+      found: {
+        ...stored,
+        memberships: [{ parent: 'hf_agent', grantor: 'postgres', admin, set }],
+      },
+    });
+    expect(await run(diffPostgresRole(declared, stored, {}, row(true, true)))).toEqual({
+      action: 'update',
+    });
+    expect(await run(diffPostgresRole(declared, stored, {}, row(false, true)))).toEqual({
+      action: 'update',
+    });
+    expect(await run(diffPostgresRole(declared, stored, {}, row(false, false)))).toEqual({
+      action: 'noop',
+    });
+    const stuffed = {
+      ...stored,
+      memberships: [{ parent: 'hf_agent', grantor: 'postgres', admin: true, set: true }],
+    };
+    expect(await run(diffPostgresRole(declared, stuffed))).toEqual({ action: 'noop' });
+  });
+
+  test('a rotated password answers update even with no other drift; a matching or unreadable one does not', async () => {
+    const declared = { ...base, password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' } as const };
+    const stale = seal({ password: 'old' }, 'fixed-salt');
+    const matched = seal({ password: 'current' }, 'fixed-salt');
+    const held = { PG_SEAT_ROLE_PASSWORD: 'current' };
+    // A value the seal does not match — rotated, or an adopted role's empty seal — answers update.
+    expect(await run(diffPostgresRole(declared, { ...output, passwordSeal: stale }, held))).toEqual(
+      { action: 'update' },
+    );
+    expect(await run(diffPostgresRole(declared, output, held))).toEqual({ action: 'update' });
+    // Still matching: noop. The variable unset here: never stale — a plan that cannot read the
+    // secret never churns it.
+    expect(
+      await run(diffPostgresRole(declared, { ...output, passwordSeal: matched }, held)),
+    ).toEqual({ action: 'noop' });
+    expect(await run(diffPostgresRole(declared, { ...output, passwordSeal: stale }, {}))).toEqual({
+      action: 'noop',
+    });
+  });
+});
+
+describe('scalarDrift', () => {
+  test('lists one change per drifted field, in the family\u2019s compared order', () => {
+    expect(
+      scalarDrift(
+        {
+          ...base,
+          login: true,
+          inherit: false,
+          connectionLimit: 5,
+          validUntil: '2027-01-01T00:00:00Z',
+        },
+        { ...output, login: false, inherit: true, connectionLimit: 10 },
+      ),
+    ).toEqual([
+      { prop: 'login', value: true },
+      { prop: 'inherit', value: false },
+      { prop: 'connectionLimit', value: 5 },
+      { prop: 'validUntil', value: '2027-01-01T00:00:00Z' },
+    ]);
+  });
+
+  test('is empty when the live row matches, including the milliseconds case', () => {
+    expect(scalarDrift(base, output)).toEqual([]);
+    expect(
+      scalarDrift(
+        { ...base, validUntil: '2027-01-01T00:00:00Z' },
+        {
+          ...output,
+          validUntil: '2027-01-01T00:00:00.000Z',
+        },
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('membershipDrift', () => {
+  test('undefined asserts nothing; duplicates collapse; grants and revokes are sorted set differences', () => {
+    expect(membershipDrift(undefined, ['hf_agent'])).toEqual({ grants: [], revokes: [] });
+    expect(membershipDrift(['hf_agent', 'hf_agent', 'seat-b'], [])).toEqual({
+      grants: ['hf_agent', 'seat-b'],
+      revokes: [],
+    });
+    expect(membershipDrift(['hf_agent'], ['hf_agent', 'seat-b', 'seat-a'])).toEqual({
+      grants: [],
+      revokes: ['seat-a', 'seat-b'],
+    });
+  });
+});
+
+describe('quoting', () => {
+  test('a hostile role name is doubled in every statement that quotes it', () => {
+    expect(buildCreateRoleSql({ ...base, name: 'a"b' })).toBe(
+      'CREATE ROLE "a""b" WITH NOLOGIN INHERIT CONNECTION LIMIT 10',
+    );
+    expect(buildAlterRoleSql('a"b', { prop: 'connectionLimit', value: 3 })).toBe(
+      'ALTER ROLE "a""b" WITH CONNECTION LIMIT 3',
+    );
+    expect(buildGrantMembershipSql('m"1', 'p"2')).toBe('GRANT "p""2" TO "m""1" WITH SET FALSE');
+    expect(buildRevokeGrantorMembershipSql('m"1', 'p"2', 'g"3')).toBe(
+      'REVOKE "p""2" FROM "m""1" GRANTED BY "g""3"',
+    );
+    expect(buildDropRoleSql('a"b')).toBe('DROP ROLE IF EXISTS "a""b"');
+  });
+
+  test('the value buildSetPasswordSql carries is single-quote escaped exactly once', () => {
+    // In production that value is a SCRAM verifier (`role-scram.ts`), which the base64 alphabet
+    // keeps free of `'`; the quoting property still holds for any string handed to the builder.
+    expect(buildSetPasswordSql('seat-observability', "O'Brien; DROP")).toBe(
+      "ALTER ROLE \"seat-observability\" WITH PASSWORD E'O''Brien; DROP'",
+    );
+  });
+});
+
+describe('write-only password shape (S25)', () => {
+  const props = { ...base, password: { fromEnv: 'PG_SEAT_ROLE_PASSWORD' } };
+
+  test('resolvePassword holds the value as Redacted, which never prints or serialises it', () => {
+    const { variable, value } = resolvePassword(props, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' });
+    expect(variable).toBe('PG_SEAT_ROLE_PASSWORD');
+    expect(String(value)).toBe('<redacted>');
+    expect(JSON.stringify({ value })).not.toContain('s3cret-value');
+    expect(Redacted.isRedacted(value)).toBe(true);
+    if (Redacted.isRedacted(value)) {
+      expect(Redacted.value(value)).toBe('s3cret-value');
+    }
+  });
+
+  test('resolvePassword answers no value when the variable is unset or empty', () => {
+    expect(resolvePassword(props, {}).value).toBeUndefined();
+    expect(resolvePassword(props, { PG_SEAT_ROLE_PASSWORD: '' }).value).toBeUndefined();
+    expect(resolvePassword(base, { PG_SEAT_ROLE_PASSWORD: 's3cret-value' })).toEqual({
+      variable: undefined,
+      value: undefined,
+    });
+  });
+});
+
+describe('removal policy', () => {
+  test('defaultRemovalPolicy is retain (checked in source, declared alongside PostgresRole)', () => {
+    const source = readFileSync(new URL('./role.ts', import.meta.url), 'utf8');
+    expect(source).toContain("defaultRemovalPolicy: 'retain'");
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * The SCRAM-SHA-256 verifier `role-scram.ts` builds — the only password form this family ever
+ * sends. The golden vector below was computed OUTSIDE node (`hashlib`/`hmac` from the Python 3
+ * standard library, 2026-09-30) so the test is a cross-implementation check, not the function
+ * re-deriving its own math.
+ */
+import { describe, expect, test } from 'bun:test';
+import { scramSha256Verifier } from './role-scram.ts';
+
+// A placeholder, never a credential; the salt is fixed so the vector is deterministic.
+const GOLDEN_SALT = Buffer.from('a1b2c3d4e5f60718293a4b5c6d7e8f90', 'hex');
+const PLACEHOLDER = 'placeholder-password';
+const GOLDEN =
+  'SCRAM-SHA-256$4096:obLD1OX2BxgpOktcbX6PkA==$' +
+  'wP+XMQxcTjqewigDeRTAJB703b2ekDF1fCBumhTm4N8=:' +
+  'Bcc+TZOxqllgMPNn8IX0u/TJpvlRhwqPJaNQ2VLm1F4=';
+
+describe('scramSha256Verifier', () => {
+  test('matches a verifier computed by an independent implementation', () => {
+    expect(scramSha256Verifier(PLACEHOLDER, GOLDEN_SALT)).toBe(GOLDEN);
+  });
+
+  test('fresh salt per call, standard base64 parts at PostgreSQL defaults', () => {
+    const shape =
+      /^SCRAM-SHA-256\$4096:[A-Za-z0-9+/]{22}==\$[A-Za-z0-9+/]{43}=:[A-Za-z0-9+/]{43}=$/;
+    const a = scramSha256Verifier(PLACEHOLDER);
+    const b = scramSha256Verifier(PLACEHOLDER);
+    expect(a).not.toBe(b);
+    expect(a).toMatch(shape);
+    expect(b).toMatch(shape);
+  });
+
+  test('a different password gives a different verifier for the same salt', () => {
+    expect(scramSha256Verifier(PLACEHOLDER, GOLDEN_SALT)).not.toBe(
+      scramSha256Verifier('placeholder-password-two', GOLDEN_SALT),
+    );
+  });
+});

package/src/postgres/role-scram.ts

@@ -0,0 +1,38 @@
+/**
+ * SCRAM-SHA-256 password verifier, built client-side the way `psql \password` and `createuser -w`
+ * do (`createuser.c@REL_18_6` → `pg_format scram verifier`). Postgres stores the verifier as-is in
+ * `pg_authid.rolpassword` and never recovers the password from it.
+ *
+ * ⛔ THE PLAIN PASSWORD NEVER ENTERS A STATEMENT. Before this file, `ALTER ROLE … PASSWORD` carried
+ *   the plain value as a literal, so it landed in the Effect SQL span attribute `db.query.text`,
+ *   in `pg_stat_statements` (`track_utility=on` records utility statements), and in the server log
+ *   of any failed `ALTER`. The verifier is the one form Postgres accepts that is not the secret:
+ *   `PASSWORD 'SCRAM-SHA-256$4096:<salt>$<StoredKey>:<ServerKey>'` (`create_role.sgml`: a string
+ *   already in SCRAM verifier format is stored as given).
+ * ★ WIRE FORMAT AND MATH (`scram_protocols` / RFC 5802 / `auth-scram.c`): salt 16 bytes,
+ *   iterations 4096 (both Postgres defaults), standard base64. SaltedPassword = PBKDF2-HMAC-SHA-256
+ *   (password, salt, 4096, 32 bytes); ClientKey = HMAC(SaltedPassword, "Client Key"); StoredKey =
+ *   SHA-256(ClientKey); ServerKey = HMAC(SaltedPassword, "Server Key").
+ */
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from 'node:crypto';
+
+const ITERATIONS = 4096;
+const SALT_BYTES = 16;
+const KEY_BYTES = 32;
+
+const hmac = (key: Buffer, label: string): Buffer =>
+  createHmac('sha256', key).update(label, 'utf8').digest();
+
+const b64 = (value: Buffer): string => value.toString('base64');
+
+/**
+ * `SCRAM-SHA-256$4096:<salt>$<StoredKey>:<ServerKey>` for one password. The salt is fresh per
+ * call (same as `psql \password`); tests pass one to make the output deterministic.
+ */
+export const scramSha256Verifier = (password: string, salt?: Buffer): string => {
+  const bytes = salt ?? randomBytes(SALT_BYTES);
+  const saltedPassword = pbkdf2Sync(password, bytes, ITERATIONS, KEY_BYTES, 'sha256');
+  const storedKey = createHash('sha256').update(hmac(saltedPassword, 'Client Key')).digest();
+  const serverKey = hmac(saltedPassword, 'Server Key');
+  return `SCRAM-SHA-256$${ITERATIONS}:${b64(bytes)}$${b64(storedKey)}:${b64(serverKey)}`;
+};

package/src/postgres/role-secrets.ts

@@ -0,0 +1,46 @@
+/**
+ * The `Postgres.Role` password: resolution from the environment and the seal arithmetic that
+ * lets state answer "did this value already go out?" without storing it (S25).
+ *
+ * ⛔ THE PASSWORD IS A REFERENCE, NEVER A VALUE. It is declared as
+ *   `{ fromEnv: 'PG_SEAT_WIDGET_PASSWORD' }`; the NAME lands in state, the value is resolved
+ *   from the deploying process's environment at reconcile/diff time, held as `Redacted`, and
+ *   quoted into the one `ALTER ROLE … PASSWORD` statement that needs it.
+ * ★ What state remembers is a `scrypt:<salt>:<digest>` seal ({@link sealPassword}), so a
+ *   reconcile sends the password only when the environment value differs from the one last
+ *   written — a plan never re-sends a secret that already matches, and never stores one.
+ */
+import * as Redacted from 'effect/Redacted';
+import { type Environment, resolveAll, seal, sealMatches } from '../secrets/write-only.ts';
+import type { PostgresRoleProps } from './role-attrs.ts';
+
+/** What the environment holds for the declared password. `value` is `undefined` when no
+ * password is declared, or when the variable is unset or empty (a renderer that failed writes
+ * `NAME=`; `resolveAll` treats empty as missing). ⛔ Reads the environment at CALL time. */
+export interface ResolvedPassword {
+  readonly variable: string | undefined;
+  readonly value: Redacted.Redacted<string> | undefined;
+}
+
+export const resolvePassword = (
+  props: PostgresRoleProps,
+  env: Environment = process.env,
+): ResolvedPassword => {
+  if (props.password === undefined) return { variable: undefined, value: undefined };
+  const { values } = resolveAll({ password: props.password }, env);
+  const raw = values['password'];
+  return {
+    variable: props.password.fromEnv,
+    value: raw === undefined ? undefined : Redacted.make(raw),
+  };
+};
+
+/** `seal({ password })` of the resolved value — the one thing state remembers about it. */
+export const sealPassword = (value: Redacted.Redacted<string>): string =>
+  seal({ password: Redacted.value(value) });
+
+/** Whether the seal was made from the resolved value. Malformed/empty seals answer false, so an
+ * adopted role (seal `''`) or one written outside this stack gets the password written on the
+ * first reconcile that holds the variable — the declaration is authoritative. */
+export const passwordMatchesSeal = (value: Redacted.Redacted<string>, sealed: string): boolean =>
+  sealMatches(sealed, { password: Redacted.value(value) });

package/src/postgres/role-sql.ts

@@ -0,0 +1,211 @@
+/**
+ * The statements `Postgres.Role` ever issues, and the one read that backs them.
+ *
+ * ⛔ `CREATE ROLE` / `ALTER ROLE` TAKE NO BIND PARAMETERS FOR ANY OF THEIR VALUES. Measured at
+ *   `gram.y@REL_18_6`: every option value in `CreateOptRoleStmt` is a `RoleSpec`, a signed
+ *   `Iconst` or an `Sconst`, and none of those productions reaches `PARAM` (`$n`). Only the
+ *   catalog reads below bind a role name (`$1`).
+ * ⛔ THE PASSWORD NEVER CROSSES THE WIRE AS A PLAIN LITERAL. Postgres has no bind form for it in
+ *   `CREATE`/`ALTER ROLE`, so the statement carries the SCRAM-SHA-256 verifier `role-scram.ts`
+ *   computes client-side (what `psql \password` sends; stored as-is, never reversible): the
+ *   statement text that reaches the span attribute `db.query.text`, `pg_stat_statements` and a
+ *   failed `ALTER`'s server log holds no secret. It is quoted with `quoteStringLiteral` like every
+ *   other string value and NEVER written to state — only its seal is (`role-attrs.ts`,
+ *   `passwordSeal`).
+ * ★ MEMBERSHIP IS TWO ONE-PARENT STATEMENTS (`GRANT` / `REVOKE`), never a multi-role list, so a
+ *   partially-failed membership write is observable in the state that remains. Those statements
+ *   and the `pg_auth_members` read live in `role-membership-sql.ts` — this file stays the role
+ *   row (`pg_roles`), its scalar statements and the compare between them.
+ */
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import * as Effect from 'effect/Effect';
+import type { PgExecutor } from './database-sql.ts';
+import { quoteIdent, quoteStringLiteral } from './database-sql.ts';
+import { buildGrantMembershipSql, selectRoleMemberships } from './role-membership-sql.ts';
+import {
+  type PostgresRoleAttributes,
+  type PostgresRoleProps,
+  sameValidUntil,
+} from './role-attrs.ts';
+
+/** The one read: the row from the `pg_roles` view, plus this role's memberships from
+ * `pg_auth_members`. `rolvaliduntil` is a `timestamptz`; it is serialised on the server side
+ * (`to_char(rolvaliduntil AT TIME ZONE 'UTC', …)`) so the value that reaches state is a plain
+ * ISO-8601 string, never a driver-specific Date that `encodeState` would persist differently
+ * across transports (the socket client decodes it as a JS Date; the runner transport would hand
+ * back a string). */
+const SELECT_ROLE_SQL = `SELECT
+    r.oid AS oid,
+    r.rolname AS name,
+    r.rolcanlogin AS login,
+    r.rolconnlimit AS "connectionLimit",
+    r.rolinherit AS inherit,
+    r.rolsuper AS superuser,
+    r.rolcreaterole AS createrole,
+    r.rolcreatedb AS createdb,
+    r.rolreplication AS replication,
+    r.rolbypassrls AS bypassrls,
+    to_char(r.rolvaliduntil AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS "validUntil"
+  FROM pg_roles r
+  WHERE r.rolname = $1`;
+
+export const selectRole = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<Omit<PostgresRoleAttributes, 'memberOf' | 'passwordSeal'> | undefined, SqlError> =>
+  Effect.map(
+    pg.unsafe<Omit<PostgresRoleAttributes, 'memberOf' | 'passwordSeal'>>(SELECT_ROLE_SQL, [name]),
+    (rows) => rows[0],
+  );
+
+/** One combined read used by reconcile, so a no-op reconcile issues exactly one round trip.
+ * `passwordSeal` is state-only — `pg_roles` answers no password (S25) — so the caller merges it. */
+export const readRoleWithClient = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<Omit<PostgresRoleAttributes, 'passwordSeal'> | undefined, SqlError> =>
+  Effect.gen(function* () {
+    const row = yield* selectRole(pg, name);
+    if (row === undefined) return undefined;
+    const memberships = yield* selectRoleMemberships(pg, name);
+    // Two grantors of one parent are two catalog rows. `memberOf` is the set of names.
+    return {
+      ...row,
+      memberOf: [...new Set(memberships.map((membership) => membership.parent))].sort(),
+      memberships,
+    };
+  });
+
+/** The `WITH` options a create carries, in one place so `diff` and the fake agree on the text.
+ * A create carries no PASSWORD clause — the password travels through
+ * {@link buildSetPasswordSql} as its SCRAM verifier, so the one quoting path is exercised exactly
+ * once and a `CREATE ROLE` never carries a credential in its log line. */
+const withOptions = (props: PostgresRoleProps): string => {
+  const parts: string[] = [];
+  parts.push(props.login ? 'LOGIN' : 'NOLOGIN');
+  parts.push(props.inherit ? 'INHERIT' : 'NOINHERIT');
+  parts.push(`CONNECTION LIMIT ${String(Math.trunc(props.connectionLimit))}`);
+  if (props.validUntil !== undefined) {
+    parts.push(`VALID UNTIL ${quoteStringLiteral(props.validUntil)}`);
+  }
+  return parts.join(' ');
+};
+
+export const buildCreateRoleSql = (props: PostgresRoleProps): string =>
+  `CREATE ROLE ${quoteIdent(props.name)} WITH ${withOptions(props)}`;
+
+/** One `ALTER ROLE` per drifted scalar. Membership and password are separate statements. */
+export const buildAlterRoleSql = (
+  name: string,
+  change:
+    | { prop: 'login'; value: boolean }
+    | { prop: 'inherit'; value: boolean }
+    | {
+        prop: 'connectionLimit';
+        value: number;
+      }
+    | { prop: 'validUntil'; value: string },
+): string => {
+  const who = quoteIdent(name);
+  switch (change.prop) {
+    case 'login':
+      return `ALTER ROLE ${who} WITH ${change.value ? 'LOGIN' : 'NOLOGIN'}`;
+    case 'inherit':
+      return `ALTER ROLE ${who} WITH ${change.value ? 'INHERIT' : 'NOINHERIT'}`;
+    case 'connectionLimit':
+      return `ALTER ROLE ${who} WITH CONNECTION LIMIT ${String(Math.trunc(change.value))}`;
+    case 'validUntil':
+      return `ALTER ROLE ${who} WITH VALID UNTIL ${quoteStringLiteral(change.value)}`;
+  }
+};
+
+/** One dedicated `ALTER ROLE … PASSWORD`. It carries the SCRAM-SHA-256 verifier
+ * `role-scram.ts` computes, never the plain password: Postgres takes no bind parameter for a role
+ * password, but a string already in SCRAM verifier format is stored as-is (`create_role.sgml`),
+ * so the statement text that reaches the span, `pg_stat_statements` and a failed `ALTER`'s server
+ * log holds no secret. */
+export const buildSetPasswordSql = (name: string, verifier: string): string =>
+  `ALTER ROLE ${quoteIdent(name)} WITH PASSWORD ${quoteStringLiteral(verifier)}`;
+
+export const buildDropRoleSql = (name: string): string => `DROP ROLE IF EXISTS ${quoteIdent(name)}`;
+
+/** `CREATE`, the optional password `ALTER`, and one seat `GRANT` per declared parent, in the
+ * order a single transaction runs them. Grants are sorted so the script is stable. */
+export const buildCreateStatements = (
+  props: PostgresRoleProps,
+  verifier: string | undefined,
+): readonly string[] => [
+  buildCreateRoleSql(props),
+  ...(verifier === undefined ? [] : [buildSetPasswordSql(props.name, verifier)]),
+  ...[...new Set(props.memberOf ?? [])]
+    .sort()
+    .map((parent) => buildGrantMembershipSql(props.name, parent)),
+];
+
+/** Compare every declared scalar prop against the live row; answer the list of statements
+ * reconcile needs to run, empty when nothing drifted. `name` is compared by the caller. */
+export const scalarDrift = (
+  props: PostgresRoleProps,
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+): ReadonlyArray<Parameters<typeof buildAlterRoleSql>[1]> => {
+  const changes: Parameters<typeof buildAlterRoleSql>[1][] = [];
+  if (props.login !== live.login) changes.push({ prop: 'login', value: props.login });
+  if (props.inherit !== live.inherit) changes.push({ prop: 'inherit', value: props.inherit });
+  if (props.connectionLimit !== live.connectionLimit) {
+    changes.push({ prop: 'connectionLimit', value: props.connectionLimit });
+  }
+  // Instant comparison, never string equality: the server serialises `rolvaliduntil` with
+  // milliseconds, so `'2027-01-01T00:00:00Z'` (declared) and `'2027-01-01T00:00:00.000Z'`
+  // (read back) are the same value and must not churn an `ALTER` on every plan.
+  if (props.validUntil !== undefined && !sameValidUntil(props.validUntil, live.validUntil)) {
+    changes.push({ prop: 'validUntil', value: props.validUntil });
+  }
+  return changes;
+};
+
+/** Whether a live role is the one an interrupted create would have left: every declared scalar,
+ * the declared parent set, and no privilege flag or unsafe membership option. The password is
+ * not in `pg_roles`, so it is not part of the proof. */
+export const declarationMatches = (
+  props: PostgresRoleProps,
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+): boolean => {
+  const wanted =
+    props.memberOf === undefined ? undefined : [...new Set(props.memberOf)].sort().join('\0');
+  const found = [...(live.memberOf ?? [])].sort().join('\0');
+  return (
+    props.name === live.name &&
+    props.login === live.login &&
+    props.inherit === live.inherit &&
+    props.connectionLimit === live.connectionLimit &&
+    (props.validUntil === undefined || sameValidUntil(props.validUntil, live.validUntil)) &&
+    (wanted === undefined || wanted === found) &&
+    privilegedFlags(live).length === 0 &&
+    (live.memberships ?? []).every((row) => !row.admin && !row.set)
+  );
+};
+
+/** Drop the observe-only membership options before attributes reach state. Alchemy's plan diff
+ * receives the stored attributes (`Plan.ts` passes `oldState.attr`), so an `admin`/`set` row
+ * kept here would still not be what `diff` sees — the provider reads `pg_auth_members` live.
+ * What state stores is the parent-name set. */
+export const storedAttributes = (
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+): Omit<PostgresRoleAttributes, 'passwordSeal'> => {
+  const { memberships: _observeOnly, ...stored } = live;
+  return stored;
+};
+
+/** 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 privilegedFlags = (
+  live: Omit<PostgresRoleAttributes, 'passwordSeal'>,
+): readonly string[] => {
+  const flags: string[] = [];
+  if (live.superuser === true) flags.push('SUPERUSER');
+  if (live.createrole === true) flags.push('CREATEROLE');
+  if (live.createdb === true) flags.push('CREATEDB');
+  if (live.replication === true) flags.push('REPLICATION');
+  if (live.bypassrls === true) flags.push('BYPASSRLS');
+  return flags;
+};

package/src/postgres/role-valid-until.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Plan-time `validUntil` refusals and the instant compare, extracted from
+ * `role-refusals.test.ts` so that file stays under the house 250-line cap.
+ *
+ * A zone suffix is not a timestamp. `2027-13-01T00:00:00Z` and `not-a-dateZ` match the offset
+ * regex and `Date.parse` to NaN; a plan that accepts them sends a `VALID UNTIL` PostgreSQL
+ * rejects, or one that never compares equal on read-back, so every later reconcile re-issues
+ * the same `ALTER`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { sameValidUntil, validUntilRefusal } from './role-attrs.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { PostgresRoleValidUntilRefused } from './role-errors.ts';
+import { diffPostgresRole } from './role-diff.ts';
+import { refuseAtPlan } from './role.ts';
+
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const base: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const output: PostgresRoleAttributes = {
+  name: 'seat-observability',
+  oid: 20000,
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+  validUntil: null,
+  memberOf: [],
+  passwordSeal: '',
+};
+
+describe('validUntil', () => {
+  test('a zone-carrying value passes; a zone-free or unparseable one is refused with its reason', () => {
+    expect(validUntilRefusal('2027-01-01T00:00:00Z')).toBeUndefined();
+    expect(validUntilRefusal('2027-01-01T02:00:00+02:00')).toBeUndefined();
+    expect(validUntilRefusal('2027-01-01T00:00:00')).toEqual({ reason: 'zone-free' });
+    expect(validUntilRefusal('2027-01-01')).toEqual({ reason: 'zone-free' });
+    expect(validUntilRefusal('not a timestamp')).toEqual({ reason: 'unparseable' });
+    // A zone suffix is not enough: Date.parse of these is NaN, and a plan that accepts them
+    // sends a VALID UNTIL PostgreSQL rejects or that never compares equal on read-back.
+    expect(validUntilRefusal('2027-13-01T00:00:00Z')).toEqual({ reason: 'unparseable' });
+    expect(validUntilRefusal('not-a-dateZ')).toEqual({ reason: 'unparseable' });
+  });
+
+  test('refuseAtPlan raises the typed tag for a zone-free value', async () => {
+    const error = await fails(refuseAtPlan({ ...base, validUntil: '2027-01-01' }));
+    expect(error).toBeInstanceOf(PostgresRoleValidUntilRefused);
+    expect((error as PostgresRoleValidUntilRefused).reason).toBe('zone-free');
+  });
+
+  test('diff refuses the same values, so reconcile and diff can never disagree', async () => {
+    const error = await fails(diffPostgresRole({ ...base, validUntil: '2027-01-01' }, output));
+    expect(error).toBeInstanceOf(PostgresRoleValidUntilRefused);
+  });
+
+  test('sameValidUntil compares instants, so the server’s milliseconds never churn a plan', () => {
+    expect(sameValidUntil('2027-01-01T00:00:00Z', '2027-01-01T00:00:00.000Z')).toBe(true);
+    expect(sameValidUntil('2027-01-01T02:00:00+02:00', '2027-01-01T00:00:00.000Z')).toBe(true);
+    expect(sameValidUntil('2027-01-01T00:00:00Z', null)).toBe(false);
+    expect(sameValidUntil('2027-01-01T00:00:00Z', '2028-01-01T00:00:00.000Z')).toBe(false);
+  });
+});