@homeflare/alchemy 0.42.0 → 0.44.0

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

package/src/postgres/schema-assert.ts

@@ -0,0 +1,139 @@
+/**
+ * Assert a just-read `pg_namespace` row — and the connection that read it — against a
+ * `Postgres.Schema` declaration.
+ *
+ * ⛔ OWNER BEFORE COMMENT. `reconcile` calls `assertOwner` on the create re-read before any
+ *   `COMMENT ON SCHEMA`. Measured before the 2026-10-01 fix: a concurrent creator could win
+ *   `IF NOT EXISTS` (the `CREATE` did nothing). Plain CREATE now refuses that race. The kit role
+ *   is superuser, so commenting first rewrites their schema, and the later drift failure does not roll that write back — the two statements are not one
+ *   transaction.
+ * ⛔ AN OMITTED `owner` IS `current_user`, NOT "DON'T ASSERT". A fresh `CREATE SCHEMA` without
+ *   `AUTHORIZATION` is owned by the role running it. Skipping the comparison when the prop is
+ *   omitted returns that foreign row as reconciled, and a later `RemovalPolicy.destroy()` drops
+ *   the other role's schema.
+ * ⛔ DELETE RE-READS AND PROVES OWNERSHIP (`deleteForeignRefusal`). `DROP SCHEMA` fires by
+ *   name alone; the name is no proof the live schema is the one this resource created — the
+ *   old row can be dropped out of band and the name recreated by another role, and the engine
+ *   hands `delete` no re-read of its own once state exists. The persisted `oid` + `owner`
+ *   (what the last reconcile asserted) are the proof: a live row that does not match them is
+ *   refused, and nothing is dropped.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import {
+  type PostgresSchemaAttributes,
+  type PostgresSchemaProps,
+  normalizedComment,
+} from './schema-attrs.ts';
+import {
+  PostgresSchemaDeleteForeignRefused,
+  PostgresSchemaDrift,
+  PostgresSchemaWrongDatabase,
+} from './schema-errors.ts';
+import { currentDatabase } from './schema-sql.ts';
+
+/** The connected database, proven equal to the declaration or refused — the guard every write
+ * path in this family runs first. */
+export const assertDatabase = (
+  props: PostgresSchemaProps,
+  pg: PgExecutor,
+): Effect.Effect<void, PostgresSchemaWrongDatabase | SqlError> =>
+  Effect.flatMap(currentDatabase(pg), (connected) =>
+    connected === props.database
+      ? Effect.void
+      : Effect.fail(
+          new PostgresSchemaWrongDatabase({
+            schema: props.name,
+            declared: props.database,
+            connected,
+          }),
+        ),
+  );
+
+/** The role a fresh `CREATE SCHEMA` without `AUTHORIZATION` would be owned by. */
+export const declaredOwner = (props: PostgresSchemaProps, executingRole: string): string =>
+  props.owner ?? executingRole;
+
+const ownerDrift = (
+  props: PostgresSchemaProps,
+  live: PostgresSchemaAttributes,
+  executingRole: string,
+): { readonly prop: 'owner'; readonly declared: string; readonly live: string } | undefined => {
+  const declared = declaredOwner(props, executingRole);
+  return declared === live.owner ? undefined : { prop: 'owner', declared, live: live.owner };
+};
+
+/** Owner, then comment. An omitted owner is `executingRole` (`current_user`), so a race
+ * winner owned by someone else is drift on every return path, not only the create path. */
+export const liveDrift = (
+  props: PostgresSchemaProps,
+  live: PostgresSchemaAttributes,
+  executingRole: string,
+): { readonly prop: string; readonly declared: unknown; readonly live: unknown } | undefined => {
+  const owner = ownerDrift(props, live, executingRole);
+  if (owner !== undefined) return owner;
+  const comment = normalizedComment(props.comment);
+  if (comment !== undefined && comment !== (live.comment ?? undefined)) {
+    return { prop: 'comment', declared: comment, live: live.comment };
+  }
+  return undefined;
+};
+
+const refuse = (
+  props: PostgresSchemaProps,
+  drift: { readonly prop: string; readonly declared: unknown; readonly live: unknown },
+): Effect.Effect<never, PostgresSchemaDrift> =>
+  Effect.fail(
+    new PostgresSchemaDrift({
+      schema: props.name,
+      prop: drift.prop,
+      declared: drift.declared,
+      live: drift.live,
+    }),
+  );
+
+/** Owner only — the check that runs before `COMMENT ON`, so a race winner is never commented. */
+export const assertOwner = (
+  props: PostgresSchemaProps,
+  row: PostgresSchemaAttributes,
+  executingRole: string,
+): Effect.Effect<void, PostgresSchemaDrift> => {
+  const drift = ownerDrift(props, row, executingRole);
+  return drift === undefined ? Effect.void : refuse(props, drift);
+};
+
+/** Owner and comment. Every return path of `reconcile` passes through this. */
+export const assertLive = (
+  props: PostgresSchemaProps,
+  row: PostgresSchemaAttributes,
+  executingRole: string,
+): Effect.Effect<PostgresSchemaAttributes, PostgresSchemaDrift> => {
+  const drift = liveDrift(props, row, executingRole);
+  return drift === undefined ? Effect.succeed(row) : refuse(props, drift);
+};
+
+/**
+ * The delete-time ownership proof: `undefined` when the live row is provably the one this
+ * resource created (same `oid` and `owner` as the persisted state handed to `delete`), else
+ * the typed refusal — with `lastOid`/`lastOwner` `undefined` when no state was handed over,
+ * the fail-closed shape (the handler type allows `output === undefined` even though the
+ * engine passes state whenever it calls delete).
+ */
+export const deleteForeignRefusal = (
+  props: PostgresSchemaProps,
+  live: PostgresSchemaAttributes,
+  output: PostgresSchemaAttributes | undefined,
+): PostgresSchemaDeleteForeignRefused | undefined => {
+  if (output !== undefined && output.oid === live.oid && output.owner === live.owner) {
+    return undefined;
+  }
+  return new PostgresSchemaDeleteForeignRefused({
+    schema: props.name,
+    database: props.database,
+    liveOid: live.oid,
+    liveOwner: live.owner,
+    lastOid: output?.oid,
+    lastOwner: output?.owner,
+  });
+};

package/src/postgres/schema-attrs.ts

@@ -0,0 +1,71 @@
+/**
+ * Props and live attributes for `Postgres.Schema`.
+ *
+ * Backed by `pg_namespace` (`nspname`, `nspowner`, `oid`) and `pg_description`
+ * (`obj_description(n.oid, 'pg_namespace')`).
+ *
+ * `CREATE SCHEMA` options are limited: only `IF NOT EXISTS`, the schema name and an optional
+ * `AUTHORIZATION` role. No altering option exists for a schema (`ALTER SCHEMA` only renames or
+ * changes owner in Postgres, neither of which this family implements — see `docs/postgres.md`
+ * for why `Postgres.Database` refuses all `ALTER DATABASE`).
+ */
+import { POSTGRES_NAME_MAX_BYTES, utf8ByteLength } from './database-attrs.ts';
+
+export interface PostgresSchemaProps {
+  /** Schema name. At most 63 UTF-8 bytes (`NAMEDATALEN`), refused at plan. */
+  readonly name: string;
+  /**
+   * The database the schema lives in. The family connection points at a maintenance database
+   * (`docs/postgres.md#measured-path` — a brand-new database cannot be connected to on a cold
+   * plan), so the schema handlers open THIS database instead and prove it with
+   * `current_database()` (`PostgresSchemaWrongDatabase`) before any write. A change is refused
+   * at plan (`PostgresSchemaDatabaseRefused`) the same way a rename is.
+   */
+  readonly database: string;
+  /** Owning role; becomes `AUTHORIZATION` in `CREATE SCHEMA`. The role must already exist. */
+  readonly owner?: string;
+  /**
+   * Optional `COMMENT ON SCHEMA`. Stored in `pg_description`. A declared `''` IS "no comment":
+   * Postgres stores an empty comment as NULL, so it is normalized to `undefined`
+   * (`normalizedComment`) rather than compared against a live NULL forever.
+   */
+  readonly comment?: string;
+  /**
+   * Whether `DELETE` with `RemovalPolicy.destroy()` may cascade into objects in the schema.
+   * Default `false`: `DROP SCHEMA` refuses when the schema is not empty.
+   */
+  readonly cascade?: boolean;
+}
+
+export interface PostgresSchemaAttributes {
+  /** Schema name (`pg_namespace.nspname`). */
+  readonly name: string;
+  /** The database the row was read from (`current_database()`), equal to the declared prop on
+   * every honest read — the row itself carries the proof of where the statement ran. */
+  readonly database: string;
+  /** Owner role name (`pg_get_userbyid(nspowner)`). */
+  readonly owner: string;
+  /** Comment from `obj_description`, `null` when none. */
+  readonly comment: string | null;
+  /** `pg_namespace` OID, read as a native `oid` number. */
+  readonly oid: number;
+}
+
+/**
+ * A declared `''` comment means "no comment": `COMMENT ON SCHEMA … IS ''` deletes the comment in
+ * Postgres (the stored value becomes NULL), so treating `''` as a value would drift against the
+ * live NULL on every later plan — a permanent update loop. Normalizing it to `undefined` keeps
+ * `''` and an absent comment identical everywhere they are compared.
+ */
+export const normalizedComment = (comment: string | undefined): string | undefined =>
+  comment === '' ? undefined : comment;
+
+/** Refuse names PostgreSQL would silently truncate (see `database-attrs.ts`). */
+export const schemaNameByteRefusal = (
+  name: string,
+): { readonly byteLength: number; readonly limit: number } | undefined => {
+  const byteLength = utf8ByteLength(name);
+  return byteLength > POSTGRES_NAME_MAX_BYTES
+    ? { byteLength, limit: POSTGRES_NAME_MAX_BYTES }
+    : undefined;
+};

package/src/postgres/schema-delete-proofs.test.ts

@@ -0,0 +1,192 @@
+/**
+ * The red-team-proven delete and read contracts of `Postgres.Schema` (PR #334, 2026-09-30),
+ * over the runner transport — the exact scenarios the Opus review measured live.
+ *
+ * 1. DELETE DROPS ONLY WHAT IT CAN PROVE IT CREATED. The engine does not re-read before a
+ *    delete that has state (alchemy `Apply.ts`), so a schema dropped and recreated out of
+ *    band under the same name — another role's, with its own objects — was dropped by NAME,
+ *    `CASCADE` included. The handler now re-reads first: absent is idempotent success, and a
+ *    live row whose `oid` or `owner` no longer matches the persisted proof is a typed
+ *    `PostgresSchemaDeleteForeignRefused`, never a `DROP`.
+ * 2. A MISSING DECLARED DATABASE IS "SCHEMA ABSENT". A cold plan's `read` used to open the
+ *    declared database directly and fail untyped (`ConnectionError` over psql, `UnknownError`
+ *    3D000 over the socket); now both `read` and `delete` probe `pg_database` over the FAMILY
+ *    connection first and treat absence as schema-absence — the delete stays idempotent.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makePsqlExecutor } from './psql-executor.ts';
+import { postgresRunnerConnection } from './connection.ts';
+import { deleteWithClient, postgresSchemaHandlers } from './schema.ts';
+import { PostgresSchemaDeleteForeignRefused } from './schema-errors.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { deleteArgs, readArgs, route, router, runnerWith } from './schema-test-kit.ts';
+
+if (postgresSchemaHandlers.read === undefined) {
+  throw new Error('Postgres.Schema is missing its read handler');
+}
+/** Narrowed once at module scope — the narrowing does not survive into `test` callbacks. */
+const schemaRead = postgresSchemaHandlers.read;
+
+/** The out-of-band recreation scenario the review measured: created by `seat_role` (oid 16442),
+ * dropped and recreated by `other_role` with a table and a row (oid 16443). */
+const declared: PostgresSchemaProps = {
+  name: 's4',
+  database: 'agents',
+  owner: 'seat_role',
+};
+const persisted: PostgresSchemaAttributes = {
+  name: 's4',
+  database: 'agents',
+  oid: 16442,
+  owner: 'seat_role',
+  comment: null,
+};
+/** `oid` crosses the runner as a JSON string; the executor normalizes it to a number. */
+const schemaRow = (oid: number, owner: string) =>
+  JSON.stringify([{ name: 's4', oid: String(oid), owner, comment: null, database: 'agents' }]);
+/** The full router for a delete whose declared database exists. */
+const answers = (schema: string) => ({
+  probe: '[{"present":1}]',
+  schema,
+  empty: '[{"empty":true}]',
+  proof: '[{"database":"agents"}]',
+});
+
+describe('delete drops only what it can prove it created (Important 1)', () => {
+  test('an absent schema is idempotent success — no DROP issued', async () => {
+    const { run, stdins } = runnerWith(router(answers('[]')));
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs({ ...declared, cascade: true }, persisted))
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+    );
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('refuses on oid mismatch, CASCADE included — no DROP issued', async () => {
+    // The recreated row kept the declared owner but a different oid: the persisted proof
+    // cannot vouch for it, so the handler refuses before the emptiness check or any DROP.
+    const { run, stdins } = runnerWith(router(answers(schemaRow(16443, 'seat_role'))));
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete(deleteArgs({ ...declared, cascade: true }, persisted))
+          .pipe(
+            Effect.provide(
+              postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+            ),
+          ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
+    expect(error).toMatchObject({
+      schema: 's4',
+      liveOid: 16443,
+      liveOwner: 'seat_role',
+      lastOid: 16442,
+      lastOwner: 'seat_role',
+    });
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+    // Refused before the guarded drop, so the emptiness check never ran either.
+    expect(stdins.some((s) => s.includes('AS empty'))).toBe(false);
+  });
+
+  test('refuses on owner mismatch — no DROP issued', async () => {
+    // Same oid, another role: the schema under this name is no longer the one this resource
+    // created, and its objects must survive the delete.
+    const { run, stdins } = runnerWith(router(answers(schemaRow(16442, 'other_role'))));
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete(deleteArgs(declared, persisted))
+          .pipe(
+            Effect.provide(
+              postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+            ),
+          ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
+    expect(error).toMatchObject({
+      liveOid: 16442,
+      liveOwner: 'other_role',
+      lastOid: 16442,
+      lastOwner: 'seat_role',
+    });
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('a live row with no persisted proof fails closed — the delete client core refuses', async () => {
+    // The engine passes state whenever it deletes, but the handler contract allows an
+    // `undefined` output: no proof means no vouching, so a live row is refused, not dropped.
+    const { run, stdins } = runnerWith(router(answers(schemaRow(16443, 'other_role'))));
+    const pg = makePsqlExecutor(run, { database: 'agents', username: 'postgres' });
+    const error = await Effect.runPromise(Effect.flip(deleteWithClient(pg, declared, undefined)));
+    expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
+    expect(error).toMatchObject({
+      liveOid: 16443,
+      liveOwner: 'other_role',
+      lastOid: undefined,
+      lastOwner: undefined,
+    });
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+});
+
+describe('a missing declared database is schema absent (Important 2)', () => {
+  test('delete of a schema whose declared database is gone is idempotent success', async () => {
+    // The probe answers ABSENT: only that one statement ran — over the FAMILY connection
+    // (its argv targets the maintenance database), never a connection to `agents`.
+    const { run, stdins, argvs } = runnerWith(router({ probe: '[]' }));
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs({ ...declared, cascade: true }, persisted))
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+    );
+    expect(stdins.length).toBe(1);
+    expect(stdins[0]).toContain('FROM pg_database');
+    expect(argvs.length).toBe(1);
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+  });
+
+  test('read of a schema whose declared database is gone answers absent, untyped connect never happens', async () => {
+    const { run, stdins } = runnerWith((stdin) => route(stdin, { probe: '[]' }) ?? '');
+    const result = await Effect.runPromise(
+      schemaRead(readArgs(declared)).pipe(
+        Effect.provide(
+          postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+        ),
+      ),
+    );
+    expect(result).toBeUndefined();
+    expect(stdins.length).toBe(1);
+    expect(stdins[0]).toContain('FROM pg_database');
+  });
+
+  test('the `database` override reaches `psql -d`: the probe targets the family database, the rest the declared one', async () => {
+    // A live delete over a declared `agents`: the probe's argv runs `-d postgres` (the family
+    // connection), while every statement after it runs `-d agents` (the override).
+    const { run, stdins, argvs } = runnerWith(router(answers(schemaRow(16442, 'seat_role'))));
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs(declared, persisted))
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+    );
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(true);
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+    expect(argvs.slice(1).every((argv) => argv.at(-1) === 'agents')).toBe(true);
+  });
+});