@homeflare/alchemy 0.42.0 → 0.44.0

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

@@ -0,0 +1,193 @@
+/**
+ * The real `Postgres.Schema` lifecycle handlers, driven directly over the loopback runner
+ * transport — no live database, the same wiring `psql-executor.test.ts` uses: the delete path
+ * (drop, non-empty refusal, wrong-database proof, the retain default) and `read`'s `Unowned`
+ * adopt branding. Plan-time refusals live in `schema-refusals.test.ts`; the fake-driven
+ * create/adopt/drop lifecycle in `schema-lifecycle.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import { postgresRunnerConnection } from './connection.ts';
+import type { PsqlRunner } from './psql-executor.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { postgresSchemaHandlers } from './schema.ts';
+import { PostgresSchemaDropNotEmptyError, PostgresSchemaWrongDatabase } from './schema-errors.ts';
+import { deleteArgs, ok, readArgs, route, router, runnerWith } from './schema-test-kit.ts';
+
+const sampleOutput: PostgresSchemaAttributes = {
+  name: 'ledger',
+  database: 'postgres',
+  oid: 1,
+  owner: 'tim',
+  comment: null,
+};
+const base: PostgresSchemaProps = { name: 'ledger', database: 'postgres', owner: 'tim' };
+
+// `read` is optional on the service type; these tests drive the real one.
+if (postgresSchemaHandlers.read === undefined) {
+  throw new Error('Postgres.Schema is missing its read handler');
+}
+const schemaRead = postgresSchemaHandlers.read;
+const proof = '[{"database":"postgres"}]';
+
+describe('delete handler (runner transport)', () => {
+  test('the real handler drops an empty schema over the runner transport, with CASCADE', async () => {
+    const { run, stdins, argvs } = runnerWith(
+      router({
+        probe: '[{"present":1}]',
+        schema: '[{"name":"ledger","oid":1,"owner":"tim"}]',
+        empty: '[{"empty":true}]',
+        proof,
+      }),
+    );
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs({ ...base, cascade: true }, sampleOutput))
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+    );
+    expect(stdins.find((s) => s.startsWith('DROP SCHEMA'))).toBe(
+      'DROP SCHEMA IF EXISTS "ledger" CASCADE;',
+    );
+    // One `psql` argv per STATEMENT: probe, proof, ownership re-read, drop. The probe's argv
+    // targets the family database; the delete's argvs target the declared one — the `-d` value
+    // is the argv's last element.
+    expect(argvs.length).toBe(4);
+    expect(argvs[0]?.at(-1)).toBe('postgres');
+    expect(argvs.slice(1).every((argv) => argv.at(-1) === 'postgres')).toBe(true);
+  });
+
+  test('the real handler drops an empty schema without CASCADE — a plain DROP', async () => {
+    const { run, stdins } = runnerWith(
+      router({
+        probe: '[{"present":1}]',
+        schema: '[{"name":"ledger","oid":1,"owner":"tim"}]',
+        empty: '[{"empty":true}]',
+        proof,
+      }),
+    );
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs(base, sampleOutput))
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+    );
+    expect(stdins.find((s) => s.startsWith('DROP SCHEMA'))).toBe('DROP SCHEMA IF EXISTS "ledger";');
+  });
+
+  test('the real handler refuses a non-empty schema over the runner transport, no DROP issued', async () => {
+    const { run, stdins } = runnerWith(
+      router({
+        probe: '[{"present":1}]',
+        schema: '[{"name":"ledger","oid":1,"owner":"tim"}]',
+        empty: '[{"empty":false}]',
+        proof,
+      }),
+    );
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete(deleteArgs(base, sampleOutput))
+          .pipe(
+            Effect.provide(
+              postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+            ),
+          ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('the real handler refuses a wrong connected database before any DROP', async () => {
+    // The connection targets `postgres` while the declaration says `agents` — the proof must
+    // fail the delete before anything is dropped. The database probe answers PRESENT, so the
+    // absent-database short-circuit does not swallow the wrong-database refusal.
+    const { run, stdins } = runnerWith(
+      router({ probe: '[{"present":1}]', proof: '[{"database":"postgres"}]' }),
+    );
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete(
+            deleteArgs({ ...base, database: 'agents' }, { ...sampleOutput, database: 'agents' }),
+          )
+          .pipe(
+            Effect.provide(
+              postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+            ),
+          ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaWrongDatabase);
+    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('defaultRemovalPolicy is retain — declared on the Resource for Postgres.Schema itself', () => {
+    // The engine keeps the default in a closure, not on the constructor, so the source IS the
+    // assertable fact — anchored to this resource's own declaration, not any string in the file.
+    const source = readFileSync(new URL('./schema.ts', import.meta.url), 'utf8');
+    expect(source).toMatch(
+      /Resource<PostgresSchema>\('Postgres\.Schema', \{\s*\n\s*defaultRemovalPolicy: 'retain',/,
+    );
+  });
+});
+
+describe('read handler (runner transport)', () => {
+  test('answers Unowned for a live row — the adopt-path branding a stack needs', async () => {
+    const run: PsqlRunner = ({ stdin }) => {
+      const r = route(stdin, {
+        probe: '[{"present":1}]',
+        schema:
+          '[{"name":"ledger","oid":"16384","owner":"tim","comment":null,"database":"postgres"}]',
+        proof,
+      });
+      if (r !== undefined) return ok(r);
+      return ok('');
+    };
+    const result = await Effect.runPromise(
+      schemaRead(readArgs(base)).pipe(
+        Effect.provide(
+          postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+        ),
+      ),
+    );
+    expect(Unowned.is(result)).toBe(true);
+    // The brand is a non-enumerable symbol that bun's toEqual compares; spread it off.
+    expect({ ...result }).toEqual({ ...sampleOutput, oid: 16384 });
+  });
+
+  test('refuses with the typed wrong-database tag when the row was read from another database', async () => {
+    const run: PsqlRunner = ({ stdin }) =>
+      Promise.resolve({
+        code: 0,
+        stdout:
+          route(stdin, {
+            probe: '[{"present":1}]',
+            schema:
+              '[{"name":"ledger","oid":"16384","owner":"tim","comment":null,"database":"agents"}]',
+            proof: '[{"database":"agents"}]',
+          }) ?? '',
+        stderr: '',
+      });
+    const error = await Effect.runPromise(
+      Effect.flip(
+        schemaRead(readArgs(base)).pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+        ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaWrongDatabase);
+    expect((error as PostgresSchemaWrongDatabase).connected).toBe('agents');
+  });
+});

package/src/postgres/schema-identity.ts

@@ -0,0 +1,39 @@
+/** Apply repeats plan guards: unresolved Outputs can skip both diff and the adoption probe. */
+import * as Effect from 'effect/Effect';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import {
+  PostgresSchemaDatabaseRefused,
+  PostgresSchemaIdentityRefused,
+  PostgresSchemaRenameRefused,
+} from './schema-errors.ts';
+
+export const assertSchemaTarget = (
+  props: PostgresSchemaProps,
+  output: PostgresSchemaAttributes | undefined,
+): Effect.Effect<void, PostgresSchemaRenameRefused | PostgresSchemaDatabaseRefused> =>
+  Effect.gen(function* () {
+    if (output === undefined) return;
+    if (props.name !== output.name)
+      return yield* Effect.fail(
+        new PostgresSchemaRenameRefused({ from: output.name, to: props.name }),
+      );
+    if (props.database !== output.database)
+      return yield* Effect.fail(
+        new PostgresSchemaDatabaseRefused({ from: output.database, to: props.database }),
+      );
+  });
+
+/** Like Role, refuse recycled names on read as well: drift must not refresh away the proof. */
+export const assertSchemaIdentity = (
+  live: PostgresSchemaAttributes,
+  output: PostgresSchemaAttributes,
+): Effect.Effect<void, PostgresSchemaIdentityRefused> =>
+  live.oid === output.oid
+    ? Effect.void
+    : Effect.fail(
+        new PostgresSchemaIdentityRefused({
+          schema: live.name,
+          storedOid: output.oid,
+          liveOid: live.oid,
+        }),
+      );

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