@homeflare/alchemy 0.43.0 → 0.44.0

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

package/src/postgres/role.ts

@@ -0,0 +1,218 @@
+/**
+ * `Postgres.Role` — create / adopt / alter / drop of a LOGIN or NOLOGIN role on the same
+ * self-hosted PostgreSQL 18 cluster `Postgres.Database` talks to, over the same transports
+ * (runner `psql` or socket). The seat-wiring lane B12a's shape: one group role per seat
+ * (NOLOGIN, member of `hf_agent`), plus the LOGIN seat users.
+ *
+ * ★ ALTER-CAPABLE, UNLIKE `Postgres.Database`. Every scalar this resource asserts has a safe
+ *   atomic `ALTER ROLE` form (`LOGIN`/`NOLOGIN`, `INHERIT`/`NOINHERIT`, `CONNECTION LIMIT`,
+ *   `VALID UNTIL` — `alter_role.sgml`'s first synopsis variant), so a drifted live row is
+ *   brought back to the declaration, never refused. Memberships move through one-parent
+ *   `GRANT`/`REVOKE` statements (`alter_role.sgml`: "there are no options for adding or
+ *   removing memberships; use GRANT and REVOKE").
+ * ⛔ THE PASSWORD IS A REFERENCE, NEVER A VALUE (S25). 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 time, held as `Redacted`, and sent only
+ *   as the SCRAM-SHA-256 verifier inside the one `ALTER ROLE … PASSWORD` statement that needs it
+ *   (`role-scram.ts` — the statement text reaching spans, `pg_stat_statements` and a failed
+ *   `ALTER`'s server log never holds the plain value). What state remembers is a
+ *   `scrypt:<salt>:<digest>` seal, 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.
+ * ★ MEMBERSHIP IS `pg_auth_members`, compared as a sorted set. `memberOf` omitted leaves live
+ *   memberships alone; `[]` ensures none.
+ * ★ `defaultRemovalPolicy: 'retain'` — a seat group role may own objects and be granted across
+ *   databases; a destroy is still implemented in full (`DROP ROLE IF EXISTS`), opt in with
+ *   `.pipe(RemovalPolicy.destroy())`. A role that still owns objects fails the drop with the
+ *   server's own `2BP01` (`dependent_objects_still_exist`), surfaced as the client's `SqlError`.
+ */
+import { Resource } from 'alchemy';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import { type Environment } from '../secrets/write-only.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+import { nameByteRefusal, validUntilRefusal } from './role-attrs.ts';
+import { passwordMatchesSeal, resolvePassword, sealPassword } from './role-secrets.ts';
+import { scramSha256Verifier } from './role-scram.ts';
+import {
+  buildAlterRoleSql,
+  buildCreateStatements,
+  buildSetPasswordSql,
+  privilegedFlags,
+  readRoleWithClient,
+  scalarDrift,
+  storedAttributes,
+} from './role-sql.ts';
+import { assertParentsExist, syncMemberships } from './role-membership-sql.ts';
+import {
+  PostgresRoleCreateVanished,
+  PostgresRoleIdentityRefused,
+  type PostgresRoleMembershipUnrepaired,
+  PostgresRoleNameRefused,
+  type PostgresRoleParentMissing,
+  PostgresRolePasswordEnvUnsetError,
+  PostgresRolePrivilegedRefused,
+  PostgresRoleValidUntilRefused,
+} from './role-errors.ts';
+import { type PostgresConnection } from './connection.ts';
+import type { PgExecutor } from './database-sql.ts';
+
+export interface PostgresRole extends Resource<
+  'Postgres.Role',
+  PostgresRoleProps,
+  PostgresRoleAttributes,
+  never,
+  PostgresConnection
+> {}
+
+export const PostgresRole = Resource<PostgresRole>('Postgres.Role', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Mirrors `isPostgresDatabase`: a resource constructor is a callable `Object.assign`ed
+ * function, not a plain object, so `typeof` must accept both. */
+export const isPostgresRole = (value: unknown): value is PostgresRole =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Postgres.Role';
+
+/**
+ * The core of `reconcile`, against any {@link PgExecutor} — the real client through `withPg`,
+ * or `fake-sql.ts`'s recording fake in tests. `env` defaults to `process.env`; tests pass a
+ * recording one. `previousSeal` is the seal in the engine's state — `''` when the role is
+ * being written for the first time — because `pg_roles` answers no password (S25), so the live
+ * row cannot say whether the environment value still matches the one last written.
+ */
+export const reconcileWithClient = (
+  pg: PgExecutor,
+  props: PostgresRoleProps,
+  env: Environment = process.env,
+  previousSeal = '',
+  storedOid?: number,
+): Effect.Effect<
+  PostgresRoleAttributes,
+  | PostgresRolePasswordEnvUnsetError
+  | PostgresRolePrivilegedRefused
+  | PostgresRoleCreateVanished
+  | PostgresRoleMembershipUnrepaired
+  | PostgresRoleParentMissing
+  | PostgresRoleIdentityRefused
+  | SqlError
+> =>
+  Effect.gen(function* () {
+    const resolved = resolvePassword(props, env);
+    const observed = yield* readRoleWithClient(pg, props.name);
+    if (observed === undefined) {
+      // A create that declares a password must hold it: a LOGIN role with no password set, or
+      // one created against a guess, is exactly the unauthenticated path to refuse.
+      if (resolved.variable !== undefined && resolved.value === undefined) {
+        return yield* Effect.fail(
+          new PostgresRolePasswordEnvUnsetError({ role: props.name, variable: resolved.variable }),
+        );
+      }
+      // The create carries no PASSWORD clause. The verifier ALTER and the seat GRANTs share
+      // one transaction with the CREATE, so a failure rolls all of them back. A missing parent
+      // is refused first — `GRANT` would otherwise be `42704` after the CREATE committed.
+      yield* assertParentsExist(pg, props.name, props.memberOf);
+      const verifier =
+        resolved.value === undefined
+          ? undefined
+          : scramSha256Verifier(Redacted.value(resolved.value));
+      yield* pg.transaction(buildCreateStatements(props, verifier));
+      // Never trust the write's own report (S10): re-read what the server actually stored.
+      const created = yield* readRoleWithClient(pg, props.name);
+      if (created === undefined) {
+        return yield* Effect.fail(new PostgresRoleCreateVanished({ role: props.name }));
+      }
+      return {
+        ...storedAttributes(created),
+        passwordSeal: resolved.value === undefined ? '' : sealPassword(resolved.value),
+      };
+    }
+    // A recycled name (dropped and recreated out of band) is a different oid. Refuse before
+    // any ALTER, PASSWORD or DROP-by-name the caller might follow with.
+    if (storedOid !== undefined && observed.oid !== storedOid) {
+      return yield* Effect.fail(
+        new PostgresRoleIdentityRefused({
+          role: props.name,
+          storedOid,
+          liveOid: observed.oid,
+        }),
+      );
+    }
+    // A live role this stack did not create can carry flags CREATE ROLE's default leaves off.
+    // They are not inherited: SET ROLE to this role exercises them. Refuse before any write.
+    const flags = privilegedFlags(observed);
+    if (flags.length > 0) {
+      return yield* Effect.fail(new PostgresRolePrivilegedRefused({ role: props.name, flags }));
+    }
+    // A declared password this stack has never sealed is not "do not churn". CREATE ROLE and
+    // ALTER ROLE … PASSWORD are two statements; a retry after the second failed, or after the
+    // process died before state was saved, sees the role and an empty seal. An unset variable
+    // there must refuse — reporting success would leave a LOGIN role with a null password.
+    if (resolved.variable !== undefined && resolved.value === undefined && previousSeal === '') {
+      return yield* Effect.fail(
+        new PostgresRolePasswordEnvUnsetError({ role: props.name, variable: resolved.variable }),
+      );
+    }
+    // Parents before any ALTER, so a missing one does not leave a half-applied scalar update.
+    yield* assertParentsExist(pg, props.name, props.memberOf);
+    // Adopted or drifted: every scalar comes back to the declaration, one ALTER per field.
+    for (const change of scalarDrift(props, observed)) {
+      yield* pg.unsafe(buildAlterRoleSql(props.name, change)).pipe(Effect.asVoid);
+    }
+    // The password goes out only when it changed: the seal matches the last written value, or
+    // the variable is unset here (a plan-only run must not churn a secret it cannot read). The
+    // same match decides the seal that lands in state, so an unchanged password keeps the seal
+    // it already had instead of being re-salted into a new one on every plan.
+    const passwordMatched =
+      resolved.value !== undefined && passwordMatchesSeal(resolved.value, previousSeal);
+    if (resolved.value !== undefined && !passwordMatched) {
+      yield* pg
+        .unsafe(
+          buildSetPasswordSql(props.name, scramSha256Verifier(Redacted.value(resolved.value))),
+        )
+        .pipe(Effect.asVoid);
+    }
+    yield* syncMemberships(pg, props, observed.memberships ?? []);
+    const after = yield* readRoleWithClient(pg, props.name);
+    if (after === undefined) {
+      return yield* Effect.fail(new PostgresRoleCreateVanished({ role: props.name }));
+    }
+    return {
+      ...storedAttributes(after),
+      passwordSeal:
+        resolved.value === undefined || passwordMatched
+          ? previousSeal
+          : sealPassword(resolved.value),
+    };
+  });
+
+/** The core of `read`. Answers `undefined` when absent; ownership branding and the state-only
+ * `passwordSeal` merge are the caller's. */
+export const readRole = (pg: PgExecutor, name: string) => readRoleWithClient(pg, name);
+
+/** Every plan-time refusal this family makes, in one place so `diff` and `reconcile` check the
+ * same facts. Nothing here touches a client. */
+export const refuseAtPlan = (
+  props: PostgresRoleProps,
+): Effect.Effect<void, PostgresRoleNameRefused | PostgresRoleValidUntilRefused> =>
+  Effect.gen(function* () {
+    const nameRefusal = nameByteRefusal(props.name);
+    if (nameRefusal !== undefined) {
+      return yield* Effect.fail(new PostgresRoleNameRefused({ name: props.name, ...nameRefusal }));
+    }
+    if (props.validUntil !== undefined) {
+      const untilRefusal = validUntilRefusal(props.validUntil);
+      if (untilRefusal !== undefined) {
+        return yield* Effect.fail(
+          new PostgresRoleValidUntilRefused({
+            role: props.name,
+            value: props.validUntil,
+            reason: untilRefusal.reason,
+          }),
+        );
+      }
+    }
+  });