@homeflare/alchemy 0.43.0 → 0.44.0

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

package/src/postgres/schema-delete.ts

@@ -0,0 +1,96 @@
+/**
+ * `Postgres.Schema`'s drop path: prove the connection, prove the schema is still ours, then
+ * the guarded `DROP SCHEMA`.
+ *
+ * ⛔ THE ENGINE DOES NOT RE-READ BEFORE A DELETE THAT HAS STATE (alchemy `Apply.ts`). When
+ *   persisted attributes exist, `delete` receives the LAST asserted `oid` + `owner` and no
+ *   fresh row — a schema dropped out of band and recreated under the same name by another role
+ *   would be dropped by name, `CASCADE` included, destroying their objects.
+ *   `deleteWithClient` re-reads `pg_namespace` first: absent is idempotent success, and a live
+ *   row that no longer matches the persisted proof fails with
+ *   `PostgresSchemaDeleteForeignRefused` (`schema-assert.ts#deleteForeignRefusal`) before any
+ *   `DROP` is issued.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { assertDatabase, deleteForeignRefusal } from './schema-assert.ts';
+import {
+  type PostgresSchemaDeleteForeignRefused,
+  PostgresSchemaDropNotEmptyError,
+  type PostgresSchemaWrongDatabase,
+} from './schema-errors.ts';
+import {
+  buildDropSchemaSql,
+  isDependentObjectsError,
+  schemaIsEmpty,
+  selectSchema,
+} from './schema-sql.ts';
+
+/**
+ * The guarded `DROP SCHEMA`, against any {@link PgExecutor}: refuses a non-empty schema
+ * without `cascade`, and classifies the server's own `2BP01` refusal as the same typed tag —
+ * for an object kind the emptiness check's four catalogs do not cover. Callers have already
+ * proven the connected database (`assertDatabase`) and, on the delete path, the schema's
+ * ownership.
+ */
+const dropGuarded = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+): Effect.Effect<void, PostgresSchemaDropNotEmptyError | SqlError> =>
+  Effect.gen(function* () {
+    if (props.cascade !== true) {
+      const empty = yield* schemaIsEmpty(pg, props.name);
+      if (!empty) {
+        return yield* Effect.fail(new PostgresSchemaDropNotEmptyError({ schema: props.name }));
+      }
+    }
+    // The server's own `2BP01` refusal (an object kind the four catalogs miss) is classified
+    // into the same typed tag the emptiness check raises — one fail branch, classified before
+    // the fail, exactly as `database-sql.ts` classifies the `42P04` race.
+    const dropRefusal = (error: SqlError): PostgresSchemaDropNotEmptyError | SqlError =>
+      props.cascade !== true && isDependentObjectsError(error)
+        ? new PostgresSchemaDropNotEmptyError({ schema: props.name })
+        : error;
+    yield* pg.unsafe(buildDropSchemaSql(props.name, props.cascade === true)).pipe(
+      Effect.asVoid,
+      Effect.catchTag('SqlError', (error) => Effect.fail(dropRefusal(error))),
+    );
+  });
+
+/** Prove the connected database, then the guarded drop — the drop core on its own, for the
+ * tests that drive it directly. */
+export const dropWithClient = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+): Effect.Effect<void, PostgresSchemaWrongDatabase | PostgresSchemaDropNotEmptyError | SqlError> =>
+  Effect.gen(function* () {
+    yield* assertDatabase(props, pg);
+    yield* dropGuarded(pg, props);
+  });
+
+/**
+ * The core of `delete`: re-read first (see the file header), refuse a schema the persisted
+ * proof cannot vouch for, then the guarded drop. `output` is the persisted state the engine
+ * hands over — `undefined` is no proof and refuses too.
+ */
+export const deleteWithClient = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+  output: PostgresSchemaAttributes | undefined,
+): Effect.Effect<
+  void,
+  | PostgresSchemaWrongDatabase
+  | PostgresSchemaDeleteForeignRefused
+  | PostgresSchemaDropNotEmptyError
+  | SqlError
+> =>
+  Effect.gen(function* () {
+    yield* assertDatabase(props, pg);
+    const live = yield* selectSchema(pg, props.name);
+    if (live === undefined) return;
+    const refusal = deleteForeignRefusal(props, live, output);
+    if (refusal !== undefined) return yield* Effect.fail(refusal);
+    yield* dropGuarded(pg, props);
+  });

package/src/postgres/schema-diff.ts

@@ -0,0 +1,44 @@
+/**
+ * `Postgres.Schema`'s plan-time diff — entirely offline: `news` (declared) against `output`
+ * (last-applied attributes) and `olds` (last-applied props), never a live query (that
+ * authoritative check is `reconcileWithClient`'s, per S10). Extracted from `schema.ts` to keep
+ * each file under the house's 250-line cap.
+ *
+ * ⛔ `cascade` COMPARES AGAINST `olds`, NOT `output`. Attributes are the live row (name,
+ *   database, owner, comment, oid) — `cascade` is a prop-only concern no catalog column
+ *   carries. The engine's noop branch (`Apply.ts`) commits the OLD props unchanged, so a
+ *   `cascade` flip must answer `update` to reach the persisted state at all: a schema first
+ *   declared `cascade: true` and later set to `false` would otherwise keep dropping with
+ *   `CASCADE` on every delete, because `delete`'s `olds` are read from those persisted props.
+ */
+import { assertSchemaTarget } from './schema-identity.ts';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { normalizedComment, schemaNameByteRefusal } from './schema-attrs.ts';
+import { PostgresSchemaNameRefused } from './schema-errors.ts';
+
+/** Plan-time only: rename refused, over-long name refused, a database move refused; a `cascade`
+ * flip answers `update` so the new prop reaches state, and every other change answers `update`
+ * too (which `reconcileWithClient` then applies as create, or refuses as drift on a live
+ * schema). */
+export const diffPostgresSchema = (
+  news: Input<PostgresSchemaProps>,
+  output: PostgresSchemaAttributes | undefined,
+  olds?: PostgresSchemaProps,
+) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    yield* assertSchemaTarget(news, output);
+    const nameRefusal = schemaNameByteRefusal(news.name);
+    if (nameRefusal !== undefined) {
+      return yield* Effect.fail(new PostgresSchemaNameRefused({ name: news.name, ...nameRefusal }));
+    }
+    const comment = normalizedComment(news.comment);
+    const changed =
+      (news.owner !== undefined && news.owner !== output.owner) ||
+      (comment !== undefined && comment !== (output.comment ?? undefined)) ||
+      (news.cascade ?? false) !== (olds?.cascade ?? false);
+    return changed ? ({ action: 'update' } as const) : ({ action: 'noop' } as const);
+  });