@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/schema-lifecycle.test.ts

@@ -0,0 +1,246 @@
+/**
+ * `reconcile`, `read`, and `drop` for `Postgres.Schema` against `fake-sql.ts`'s recording fake.
+ * Tests the greenfield create, comment creation, already-present/drift, owner-missing guard,
+ * quoting, the safe-drop rules, and the `current_database()` proof every write path runs first.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { SqlError, UnknownError } from 'effect/unstable/sql/SqlError';
+import { makeFakeSql } from './fake-sql.ts';
+import { type PostgresSchemaAttributes, type PostgresSchemaProps } from './schema-attrs.ts';
+import type { PgExecutor } from './database-sql.ts';
+import {
+  PostgresSchemaCreateVanished,
+  PostgresSchemaDrift,
+  PostgresSchemaDropNotEmptyError,
+  PostgresSchemaExistsRefused,
+  PostgresSchemaOwnerMissing,
+  PostgresSchemaWrongDatabase,
+} from './schema-errors.ts';
+import { dropWithClient, readWithClient, reconcileWithClient } from './schema.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const baseProps: PostgresSchemaProps = { name: 'ledger', database: 'postgres', owner: 'tim' };
+
+const liveRow = (over: Partial<PostgresSchemaAttributes> = {}): PostgresSchemaAttributes => ({
+  name: 'ledger',
+  database: 'postgres',
+  oid: 30000,
+  owner: 'tim',
+  comment: null,
+  ...over,
+});
+
+describe('the current_database() proof', () => {
+  test('reconcile refuses a declared database the connection does not answer, before any write', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    const error = await fails(reconcileWithClient(fake, { ...baseProps, database: 'agents' }));
+    expect(error).toBeInstanceOf(PostgresSchemaWrongDatabase);
+    const refusal = error as PostgresSchemaWrongDatabase;
+    expect(refusal.declared).toBe('agents');
+    expect(refusal.connected).toBe('postgres');
+    // The refusal fires before the first pg_namespace read, so nothing but the proof ran.
+    expect(fake.statements.some((s) => s.text.includes('FROM pg_namespace'))).toBe(false);
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE SCHEMA'))).toBe(false);
+  });
+
+  test('drop refuses the same mismatch before any DROP or emptiness check', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    const error = await fails(dropWithClient(fake, { ...baseProps, database: 'agents' }));
+    expect(error).toBeInstanceOf(PostgresSchemaWrongDatabase);
+    expect(fake.statements.some((s) => s.text.startsWith('DROP SCHEMA'))).toBe(false);
+    expect(fake.schemas.get('ledger')).not.toBeUndefined();
+  });
+
+  test('every read row carries the connected database', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    const row = await run(readWithClient(fake, 'ledger'));
+    expect(row?.database).toBe('postgres');
+  });
+});
+
+describe('reconcile: greenfield', () => {
+  test('issues exactly one CREATE SCHEMA with an AUTHORIZATION clause', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    const attrs = await run(reconcileWithClient(fake, baseProps));
+    expect(attrs.name).toBe('ledger');
+    expect(attrs.owner).toBe('tim');
+    const creates = fake.statements.filter((s) => s.text.startsWith('CREATE SCHEMA'));
+    expect(creates.length).toBe(1);
+    expect(creates[0]?.text).toBe('CREATE SCHEMA "ledger" AUTHORIZATION "tim"');
+  });
+
+  test('no owner clause falls back to the executing role', async () => {
+    const fake = makeFakeSql({ roles: ['postgres'] });
+    const attrs = await run(reconcileWithClient(fake, { name: 'plain', database: 'postgres' }));
+    expect(attrs.owner).toBe('postgres');
+    const create = fake.statements.find((s) => s.text.startsWith('CREATE SCHEMA'));
+    expect(create?.text).toBe('CREATE SCHEMA "plain"');
+  });
+
+  test('declared comment is issued with a single COMMENT ON SCHEMA statement', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    const attrs = await run(reconcileWithClient(fake, { ...baseProps, comment: 'seat ledger' }));
+    expect(attrs.comment).toBe('seat ledger');
+    const comments = fake.statements.filter((s) => s.text.startsWith('COMMENT ON SCHEMA'));
+    expect(comments.length).toBe(1);
+    expect(comments[0]?.text).toBe('COMMENT ON SCHEMA "ledger" IS E\'seat ledger\'');
+  });
+
+  test('a declared empty comment IS "no comment": no statement issued, no drift later', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    const attrs = await run(reconcileWithClient(fake, { ...baseProps, comment: '' }));
+    expect(attrs.comment).toBeNull();
+    expect(fake.statements.some((s) => s.text.startsWith('COMMENT ON SCHEMA'))).toBe(false);
+    // Postgres stores IS E'' as NULL, so a second plan must stay a noop — the permanent drift
+    // loop an unnormalized '' used to cause. Reads (the current_database() and schema-row
+    // SELECT proofs) always run, so compare write statements only.
+    const writeCount = () =>
+      fake.statements.filter((s) => !/^\s*(SELECT|WITH)\b/i.test(s.text)).length;
+    const writesBefore = writeCount();
+    await run(reconcileWithClient(fake, { ...baseProps, comment: '' }, attrs));
+    expect(writeCount()).toBe(writesBefore);
+  });
+
+  test('refuses before any CREATE when the owner role does not exist', async () => {
+    const fake = makeFakeSql({ roles: [] });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresSchemaOwnerMissing);
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE SCHEMA'))).toBe(false);
+  });
+
+  test("fails with the vanish tag when the create's re-read finds nothing (S10)", async () => {
+    const fake = makeFakeSql({ roles: ['tim'], swallowNextCreateSchema: true });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresSchemaCreateVanished);
+  });
+
+  test('a concurrent creator that won the IF NOT EXISTS race is refused, not adopted', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], raceNextCreateSchema: 'someone-else' });
+    const error = await fails(reconcileWithClient(fake, baseProps));
+    expect(error._tag).toBe('PostgresSchemaExistsRefused');
+  });
+
+  test('hostile names are quoted exactly: embedded quote and a hyphen', async () => {
+    const fake = makeFakeSql({ roles: ['tim'] });
+    await run(reconcileWithClient(fake, { name: 'a"b-c', database: 'postgres', owner: 'tim' }));
+    const create = fake.statements.find((s) => s.text.startsWith('CREATE SCHEMA'));
+    expect(create?.text).toBe('CREATE SCHEMA "a""b-c" AUTHORIZATION "tim"');
+  });
+});
+
+describe('reconcile: already present', () => {
+  test('adopted output with no drift records zero write statements', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], schemas: [liveRow()] });
+    const attrs = await run(reconcileWithClient(fake, baseProps, liveRow()));
+    expect(attrs).toEqual(liveRow());
+    expect(
+      fake.statements.every(
+        (s) => !s.text.startsWith('CREATE SCHEMA') && !s.text.startsWith('COMMENT ON SCHEMA'),
+      ),
+    ).toBe(true);
+  });
+
+  test('an owner mismatch fails with the typed drift tag and issues no ALTER', async () => {
+    const fake = makeFakeSql({
+      roles: ['tim', 'someone-else'],
+      schemas: [liveRow({ owner: 'someone-else' })],
+    });
+    const error = await fails(reconcileWithClient(fake, baseProps, liveRow()));
+    expect(error).toBeInstanceOf(PostgresSchemaDrift);
+    expect((error as PostgresSchemaDrift).prop).toBe('owner');
+    expect(fake.statements.some((s) => s.text.startsWith('ALTER'))).toBe(false);
+  });
+
+  test('a comment mismatch fails with the typed drift tag naming "comment"', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], schemas: [liveRow({ comment: 'old comment' })] });
+    const error = await fails(
+      reconcileWithClient(fake, { ...baseProps, comment: 'new comment' }, liveRow()),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDrift);
+    expect((error as PostgresSchemaDrift).prop).toBe('comment');
+  });
+
+  test('a missing comment declaration does not drift against an existing comment', async () => {
+    const fake = makeFakeSql({ roles: ['tim'], schemas: [liveRow({ comment: 'legacy' })] });
+    const attrs = await run(reconcileWithClient(fake, baseProps, liveRow()));
+    expect(attrs.comment).toBe('legacy');
+    expect(fake.statements.some((s) => s.text.startsWith('COMMENT'))).toBe(false);
+  });
+});
+
+test('pre-existing same-owner schema without output is refused', async () => {
+  const fake = makeFakeSql({ schemas: [liveRow()], schemasWithRelations: ['ledger'] });
+  const error = await fails(reconcileWithClient(fake, baseProps));
+  expect(error).toBeInstanceOf(PostgresSchemaExistsRefused);
+  expect(fake.schemas.get('ledger')).toEqual(liveRow());
+  expect(fake.relationsIn.has('ledger')).toBe(true);
+});
+
+describe('read', () => {
+  test('answers undefined when the schema is absent', async () => {
+    const fake = makeFakeSql();
+    expect(await run(readWithClient(fake, 'ledger'))).toBeUndefined();
+  });
+
+  test("answers the live row when present (ownership branding is the caller's job)", async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    expect(await run(readWithClient(fake, 'ledger'))).toEqual(liveRow());
+  });
+});
+
+describe('drop', () => {
+  test('drops an empty schema with cascade false', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    await run(dropWithClient(fake, baseProps));
+    const drops = fake.statements.filter((s) => s.text.startsWith('DROP SCHEMA'));
+    expect(drops.length).toBe(1);
+    expect(drops[0]?.text).toBe('DROP SCHEMA IF EXISTS "ledger"');
+    expect(fake.schemas.get('ledger')).toBeUndefined();
+  });
+
+  test('refuses to drop a non-empty schema with cascade false', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()], schemasWithRelations: ['ledger'] });
+    const error = await fails(dropWithClient(fake, baseProps));
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+    expect(fake.schemas.get('ledger')).not.toBeUndefined();
+  });
+
+  test('drops a non-empty schema with cascade true', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()], schemasWithRelations: ['ledger'] });
+    await run(dropWithClient(fake, { ...baseProps, cascade: true }));
+    const drop = fake.statements.find((s) => s.text.startsWith('DROP SCHEMA'));
+    expect(drop?.text).toBe('DROP SCHEMA IF EXISTS "ledger" CASCADE');
+    expect(fake.schemas.get('ledger')).toBeUndefined();
+  });
+
+  test('classifies the server 2BP01 refusal as the typed not-empty tag', async () => {
+    // The emptiness check said empty, but the server refuses with SQLSTATE 2BP01 — an object
+    // kind the check's four catalogs do not cover. Class `2B` is not `42`, so both drivers
+    // wrap it as UnknownError with the raw code on the cause; this executor replays that shape.
+    const refusing: PgExecutor = {
+      unsafe: <A extends object>(text: string) =>
+        text.startsWith('SELECT current_database()')
+          ? Effect.succeed([{ database: 'postgres' }] as unknown as ReadonlyArray<A>)
+          : text.includes('AS empty')
+            ? Effect.succeed([{ empty: true }] as unknown as ReadonlyArray<A>)
+            : Effect.fail(
+                new SqlError({
+                  reason: new UnknownError({
+                    cause: Object.assign(
+                      new Error('ERROR:  2BP01: dependent objects still exist'),
+                      { code: '2BP01' },
+                    ),
+                    message: 'dependent_objects_still_exist',
+                    operation: 'DROP SCHEMA',
+                  }),
+                }),
+              ),
+      transaction: () => Effect.void,
+    };
+    const error = await fails(dropWithClient(refusing, baseProps));
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+  });
+});

package/src/postgres/schema-race.test.ts

@@ -0,0 +1,70 @@
+/**
+ * The `IF NOT EXISTS` race the lifecycle test does not pin: a concurrent creator wins
+ * between the not-found SELECT and CREATE SCHEMA. Plain CREATE now refuses it with 42P06.
+ *
+ * Two shapes the existing race test skips. A declared comment must not `COMMENT ON` that
+ * row before the refusal — the kit role is superuser, so the comment would land and
+ * a failed effect would not roll it back. An omitted `owner` must not adopt the foreign
+ * row: a fresh CREATE without AUTHORIZATION is owned by current_user. Even a matching owner
+ * now fails with PostgresSchemaExistsRefused, never a row a later destroy could drop.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { PostgresSchemaExistsRefused } from './schema-errors.ts';
+import { reconcileWithClient } from './schema.ts';
+
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+describe('IF NOT EXISTS race, the shapes the owner-only test skips', () => {
+  test('a race plus a declared comment issues zero COMMENT ON', async () => {
+    const fake = makeFakeSql({ roles: ['seat_role'], raceNextCreateSchema: 'other_role' });
+    const error = await fails(
+      reconcileWithClient(fake, {
+        name: 'ledger',
+        database: 'postgres',
+        owner: 'seat_role',
+        comment: 'seat ledger',
+      }),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaExistsRefused);
+    expect(fake.statements.some((s) => s.text.startsWith('COMMENT ON SCHEMA'))).toBe(false);
+    // The foreign row is untouched: comment still absent, owner still the racer's.
+    expect(fake.schemas.get('ledger')?.comment).toBeNull();
+    expect(fake.schemas.get('ledger')?.owner).toBe('other_role');
+  });
+
+  test('a race plus an omitted owner refuses takeover and does not return the foreign row', async () => {
+    // `current_user` is `seat_role`, not the fake's historical `'postgres'` default, so a
+    // hardcoded owner cannot satisfy `declared`.
+    const fake = makeFakeSql({
+      roles: ['seat_role'],
+      raceNextCreateSchema: 'other_role',
+      currentUser: 'seat_role',
+    });
+    const error = await fails(reconcileWithClient(fake, { name: 'ledger', database: 'postgres' }));
+    expect(error).toBeInstanceOf(PostgresSchemaExistsRefused);
+    expect(fake.schemas.get('ledger')?.owner).toBe('other_role');
+  });
+
+  test('a later plan sees the foreign row as already present and still refuses it', async () => {
+    // The failed race leaves the racer's schema in place. The next reconcile takes the
+    // already-present path, which must refuse too — otherwise that plan adopts the row.
+    const fake = makeFakeSql({
+      currentUser: 'seat_role',
+      schemas: [
+        {
+          name: 'ledger',
+          database: 'postgres',
+          oid: 30000,
+          owner: 'other_role',
+          comment: null,
+        },
+      ],
+    });
+    const error = await fails(reconcileWithClient(fake, { name: 'ledger', database: 'postgres' }));
+    expect(error).toBeInstanceOf(PostgresSchemaExistsRefused);
+    expect(fake.statements.some((s) => s.text.startsWith('CREATE SCHEMA'))).toBe(false);
+    expect(fake.statements.some((s) => s.text.startsWith('COMMENT ON SCHEMA'))).toBe(false);
+  });
+});

package/src/postgres/schema-reconcile.ts

@@ -0,0 +1,100 @@
+/** Schema reconcile: prove the stored target and identity before asserting a live row. */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import { type PgExecutor, roleExists } from './database-sql.ts';
+import {
+  type PostgresSchemaAttributes,
+  type PostgresSchemaProps,
+  normalizedComment,
+} from './schema-attrs.ts';
+import { assertDatabase, assertLive, assertOwner } from './schema-assert.ts';
+import { assertSchemaIdentity, assertSchemaTarget } from './schema-identity.ts';
+import {
+  buildCommentSchemaSql,
+  buildCreateSchemaSql,
+  currentUser,
+  isDuplicateSchemaError,
+  selectSchema,
+} from './schema-sql.ts';
+import {
+  PostgresSchemaCreateVanished,
+  type PostgresSchemaDatabaseRefused,
+  type PostgresSchemaDrift,
+  PostgresSchemaExistsRefused,
+  type PostgresSchemaIdentityRefused,
+  PostgresSchemaOwnerMissing,
+  type PostgresSchemaRenameRefused,
+  type PostgresSchemaWrongDatabase,
+} from './schema-errors.ts';
+
+/**
+ * The core of `reconcile`, against any {@link PgExecutor} — the real pooled client through
+ * `withPg`, or `fake-sql.ts`'s recording fake in tests.
+ */
+export const reconcileWithClient = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+  output?: PostgresSchemaAttributes,
+): Effect.Effect<
+  PostgresSchemaAttributes,
+  | PostgresSchemaWrongDatabase
+  | PostgresSchemaOwnerMissing
+  | PostgresSchemaDrift
+  | PostgresSchemaCreateVanished
+  | PostgresSchemaExistsRefused
+  | PostgresSchemaIdentityRefused
+  | PostgresSchemaRenameRefused
+  | PostgresSchemaDatabaseRefused
+  | SqlError
+> =>
+  Effect.gen(function* () {
+    yield* assertSchemaTarget(props, output);
+    yield* assertDatabase(props, pg);
+    // Only an omitted owner needs the session role: a declared owner is the comparison itself.
+    const executingRole = props.owner !== undefined ? props.owner : yield* currentUser(pg);
+    const observed = yield* selectSchema(pg, props.name);
+    if (observed === undefined) {
+      if (props.owner !== undefined) {
+        const ownerPresent = yield* roleExists(pg, props.owner);
+        if (!ownerPresent) {
+          return yield* Effect.fail(
+            new PostgresSchemaOwnerMissing({ schema: props.name, owner: props.owner }),
+          );
+        }
+      }
+      // REL_18_6 pg_namespace.c: duplicate_schema is 42P06. Never turn a race into adoption.
+      const createRefusal = (error: SqlError): PostgresSchemaExistsRefused | SqlError =>
+        isDuplicateSchemaError(error)
+          ? new PostgresSchemaExistsRefused({ schema: props.name, database: props.database })
+          : error;
+      yield* pg.unsafe(buildCreateSchemaSql(props)).pipe(
+        Effect.asVoid,
+        Effect.catchTag('SqlError', (error) => Effect.fail(createRefusal(error))),
+      );
+      // Never trust the write's own report (S10): re-read what the server actually stored.
+      const created = yield* selectSchema(pg, props.name);
+      if (created === undefined) {
+        return yield* Effect.fail(new PostgresSchemaCreateVanished({ schema: props.name }));
+      }
+      // Owner before COMMENT ON (schema-assert.ts): preserve the post-write assertion too;
+      // duplicate CREATE already refused the race before this re-read.
+      yield* assertOwner(props, created, executingRole);
+      const comment = normalizedComment(props.comment);
+      if (comment !== undefined && comment !== (created.comment ?? undefined)) {
+        yield* pg.unsafe(buildCommentSchemaSql(props.name, comment)).pipe(Effect.asVoid);
+        const commented = yield* selectSchema(pg, props.name);
+        if (commented === undefined) {
+          return yield* Effect.fail(new PostgresSchemaCreateVanished({ schema: props.name }));
+        }
+        return yield* assertLive(props, commented, executingRole);
+      }
+      return yield* assertLive(props, created, executingRole);
+    }
+    if (output === undefined) {
+      return yield* Effect.fail(
+        new PostgresSchemaExistsRefused({ schema: props.name, database: props.database }),
+      );
+    }
+    yield* assertSchemaIdentity(observed, output);
+    return yield* assertLive(props, observed, executingRole);
+  });

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

@@ -0,0 +1,144 @@
+/**
+ * Every plan-time refusal for `Postgres.Schema`, checked without a client: name-byte
+ * precision, identifier and literal quoting, the rename and database-move refusals, and the
+ * sweep proving `diff` never answers `replace` — including the `cascade` flip compared against
+ * `olds` so the change reaches the persisted props. The real handlers over the runner transport
+ * live in `schema-handlers.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { POSTGRES_NAME_MAX_BYTES, utf8ByteLength } from './database-attrs.ts';
+import { quoteIdent, quoteStringLiteral } from './database-sql.ts';
+import { buildCommentSchemaSql, buildCreateSchemaSql } from './schema-sql.ts';
+import { schemaNameByteRefusal } from './schema-attrs.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { diffPostgresSchema } from './schema-diff.ts';
+import {
+  PostgresSchemaDatabaseRefused,
+  PostgresSchemaNameRefused,
+  PostgresSchemaRenameRefused,
+} from './schema-errors.ts';
+
+describe('name byte length', () => {
+  test('a 63-byte ASCII name is accepted', () => {
+    const name = 'a'.repeat(63);
+    expect(utf8ByteLength(name)).toBe(63);
+    expect(schemaNameByteRefusal(name)).toBeUndefined();
+  });
+
+  test('a 64-byte ASCII name is refused', () => {
+    const name = 'a'.repeat(64);
+    const refusal = schemaNameByteRefusal(name);
+    expect(refusal).toEqual({ byteLength: 64, limit: POSTGRES_NAME_MAX_BYTES });
+  });
+
+  test('a 63-byte multibyte name (21 three-byte characters) is accepted, though .length is 21', () => {
+    // U+4E2D ("中") is 3 UTF-8 bytes. 21 * 3 = 63 bytes exactly — the last size that survives.
+    const name = '中'.repeat(21);
+    expect(name.length).toBe(21);
+    expect(utf8ByteLength(name)).toBe(63);
+    expect(schemaNameByteRefusal(name)).toBeUndefined();
+  });
+
+  test('one more multibyte character (64 bytes) is refused', () => {
+    const name = `${'中'.repeat(21)}a`;
+    expect(utf8ByteLength(name)).toBe(64);
+    expect(schemaNameByteRefusal(name)).toEqual({ byteLength: 64, limit: POSTGRES_NAME_MAX_BYTES });
+  });
+
+  test('the typed refusal names the truncation danger in its message', () => {
+    expect(
+      new PostgresSchemaNameRefused({ name: 'x', byteLength: 64, limit: 63 }).message,
+    ).toContain('silently truncate');
+  });
+});
+
+describe('quoting', () => {
+  test('quoteIdent doubles an embedded double quote and leaves a hyphen alone', () => {
+    expect(quoteIdent('a"b-c')).toBe('"a""b-c"');
+  });
+
+  test('quoteStringLiteral doubles an embedded single quote', () => {
+    expect(quoteStringLiteral("seat ledger'; DROP")).toBe("E'seat ledger''; DROP'");
+  });
+
+  test('buildCreateSchemaSql never string-concatenates an unescaped value', () => {
+    const sql = buildCreateSchemaSql({ name: 'sc"1', database: 'postgres', owner: 'ro"le' });
+    expect(sql).toBe('CREATE SCHEMA "sc""1" AUTHORIZATION "ro""le"');
+  });
+
+  test('buildCommentSchemaSql never string-concatenates an unescaped comment', () => {
+    const sql = buildCommentSchemaSql('sc"1', "it'; DROP");
+    expect(sql).toBe(`COMMENT ON SCHEMA "sc""1" IS E'it''; DROP'`);
+  });
+});
+
+const sampleOutput: PostgresSchemaAttributes = {
+  name: 'ledger',
+  database: 'postgres',
+  oid: 1,
+  owner: 'tim',
+  comment: null,
+};
+const base: PostgresSchemaProps = { name: 'ledger', database: 'postgres', owner: 'tim' };
+
+describe('diff', () => {
+  test('a rename is refused at plan, before reconcile ever runs', async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(diffPostgresSchema({ ...base, name: 'gadgets' }, sampleOutput, base)),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaRenameRefused);
+  });
+
+  test('a database move is refused at plan, the same way a rename is', async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(diffPostgresSchema({ ...base, database: 'agents' }, sampleOutput, base)),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDatabaseRefused);
+  });
+
+  test('an unchanged declaration answers noop', async () => {
+    const result = await Effect.runPromise(diffPostgresSchema(base, sampleOutput, base));
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('an unchanged cascade answers noop even when the previous declaration carried it', async () => {
+    const result = await Effect.runPromise(
+      diffPostgresSchema({ ...base, cascade: true }, sampleOutput, { ...base, cascade: true }),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('a change in any single prop answers update, and NEVER replace — swept across every prop', async () => {
+    const variants: ReadonlyArray<Partial<PostgresSchemaProps>> = [
+      { owner: 'someone-else' },
+      { comment: 'changed' },
+      { cascade: true },
+    ];
+    for (const variant of variants) {
+      const result = await Effect.runPromise(
+        diffPostgresSchema({ ...base, ...variant }, sampleOutput, base),
+      );
+      expect(result?.action, `variant ${JSON.stringify(variant)}`).toBe('update');
+      expect(result).not.toEqual({ action: 'replace' });
+    }
+  });
+
+  test('a cascade flip answers update in BOTH directions — compared against olds, so the flip reaches the persisted props', async () => {
+    // The engine's noop branch commits the old props (Apply.ts), so a cascade flip that
+    // answered noop would leave the persisted props carrying the OLD value forever: a schema
+    // first declared cascade: true would keep dropping with CASCADE even after the
+    // declaration said false.
+    const down = await Effect.runPromise(
+      diffPostgresSchema(base, sampleOutput, { ...base, cascade: true }),
+    );
+    expect(down?.action).toBe('update');
+  });
+
+  test('a declared empty comment diffs as "no comment", never as a change against a NULL', async () => {
+    const result = await Effect.runPromise(
+      diffPostgresSchema({ ...base, comment: '' }, sampleOutput, base),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+});