@homeflare/alchemy 0.42.0 → 0.44.0

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

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

@@ -0,0 +1,161 @@
+/**
+ * The `Postgres.Schema` socket transport, mocked at the pool: what the review measured was a
+ * cold plan's `read` opening the declared database directly and failing untyped
+ * (`UnknownError`, SQLSTATE `3D000` — the pinned driver classification below). The handler
+ * now probes `pg_database` over the FAMILY pool first and treats a missing declared database
+ * as schema-absence, and the operation's pool opens the declared database through the
+ * `withPg` override — the config each `PgClient.layer` call receives is recorded here.
+ */
+import { beforeEach, describe, expect, test } from 'bun:test';
+import * as PgClientModule from '@effect/sql-pg/PgClient';
+import type { PgClient as PgClientService } from '@effect/sql-pg/PgClient';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { SqlClient } from 'effect/unstable/sql/SqlClient';
+import { isDependentObjectsError } from './schema-sql.ts';
+import { classifyInstalled } from './installed-classifier.ts';
+import { PostgresPool, postgresConnection } from './connection.ts';
+import { postgresSchemaHandlers } from './schema.ts';
+import { PostgresSchemaDeleteForeignRefused } from './schema-errors.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { type RouteAnswers, deleteArgs, readArgs, route } from './schema-test-kit.ts';
+import { Unowned } from 'alchemy/AdoptPolicy';
+
+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;
+
+/** Every `PgClient.layer` config the mocked layer was built with — one per `withPg` call. */
+const pools: Array<{ database?: string | undefined }> = [];
+/** Every SQL text the fake client ran, in order. */
+const queries: string[] = [];
+/** The router answers for the current test (`schema-test-kit.ts` markers, JSON strings). */
+let answers: RouteAnswers = {};
+
+// The fake service: `unsafe` is the only member the schema handlers call (`withPg`'s build
+// callbacks), and `Statement<A>` is an `Effect<ReadonlyArray<A>, SqlError>` — a plain succeed
+// satisfies the same call shape.
+const fakeClient = {
+  unsafe: (text: string) => {
+    queries.push(text);
+    const answer = route(text, answers);
+    return Effect.succeed(
+      (answer === undefined ? [] : (JSON.parse(answer) as ReadonlyArray<object>)) as never,
+    );
+  },
+} as unknown as PgClientService;
+
+// The pool factory is provided to this Effect only; other suites keep the real driver.
+const socket = Layer.merge(
+  postgresConnection({ host: '/tmp', database: 'postgres', username: 'postgres' }),
+  Layer.succeed(PostgresPool, (config) => {
+    pools.push(config);
+    return Layer.merge(
+      Layer.succeed(PgClientModule.PgClient, fakeClient),
+      Layer.succeed(SqlClient, fakeClient),
+    );
+  }),
+);
+const declared: PostgresSchemaProps = { name: 's4', database: 'agents', owner: 'seat_role' };
+const persisted: PostgresSchemaAttributes = {
+  name: 's4',
+  database: 'agents',
+  oid: 16442,
+  owner: 'seat_role',
+  comment: null,
+};
+
+describe('socket transport: a missing declared database is schema absent', () => {
+  beforeEach(() => {
+    pools.length = 0;
+    queries.length = 0;
+    answers = {};
+  });
+
+  test('delete is idempotent success: one probe over the FAMILY pool, no connection to the declared database', async () => {
+    answers = { probe: '[]' };
+    await Effect.runPromise(
+      postgresSchemaHandlers
+        .delete(deleteArgs({ ...declared, cascade: true }, persisted))
+        .pipe(Effect.provide(socket)),
+    );
+    expect(pools.length).toBe(1);
+    expect(pools[0]?.database).toBe('postgres');
+    expect(queries.length).toBe(1);
+    expect(queries[0]).toContain('FROM pg_database');
+    expect(queries.some((q) => q.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('read answers absent: the untyped 3D000 connect never happens', async () => {
+    answers = { probe: '[]' };
+    const result = await Effect.runPromise(
+      schemaRead(readArgs(declared)).pipe(Effect.provide(socket)),
+    );
+    expect(result).toBeUndefined();
+    expect(pools.length).toBe(1);
+    expect(pools[0]?.database).toBe('postgres');
+    expect(queries.length).toBe(1);
+    expect(queries[0]).toContain('FROM pg_database');
+  });
+
+  test('the `database` override reaches the pool: probe over the family pool, statements over the declared one', async () => {
+    answers = {
+      probe: '[{"present":1}]',
+      schema: '[{"name":"s4","oid":16442,"owner":"seat_role","comment":null,"database":"agents"}]',
+      empty: '[{"empty":true}]',
+      proof: '[{"database":"agents"}]',
+    };
+    await Effect.runPromise(
+      postgresSchemaHandlers.delete(deleteArgs(declared, persisted)).pipe(Effect.provide(socket)),
+    );
+    // The probe opened the family database; every statement after it opened `agents`.
+    expect(pools.map((pool) => pool.database)).toEqual(['postgres', 'agents']);
+    expect(queries.some((q) => q.startsWith('DROP SCHEMA'))).toBe(true);
+  });
+
+  test('read over an existing declared database answers the row from the overridden pool', async () => {
+    answers = {
+      probe: '[{"present":1}]',
+      schema: '[{"name":"s4","oid":16442,"owner":"seat_role","comment":null,"database":"agents"}]',
+      proof: '[{"database":"agents"}]',
+    };
+    const result = await Effect.runPromise(
+      schemaRead(readArgs(declared)).pipe(Effect.provide(socket)),
+    );
+    expect(pools.map((pool) => pool.database)).toEqual(['postgres', 'agents']);
+    expect(Unowned.is(result)).toBe(true);
+    expect({ ...(result as object) }).toEqual({ ...persisted });
+  });
+
+  test('delete still proves ownership over the socket: an out-of-band recreation is refused', async () => {
+    // The re-read row is another role's (the review's s4 scenario): the persisted proof cannot
+    // vouch for it, and the socket pool never issues the DROP.
+    answers = {
+      probe: '[{"present":1}]',
+      schema: '[{"name":"s4","oid":16443,"owner":"other_role","comment":null,"database":"agents"}]',
+      proof: '[{"database":"agents"}]',
+    };
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete(deleteArgs({ ...declared, cascade: true }, persisted))
+          .pipe(Effect.provide(socket)),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
+    expect(error).toMatchObject({ liveOid: 16443, liveOwner: 'other_role', lastOid: 16442 });
+    expect(queries.some((q) => q.startsWith('DROP SCHEMA'))).toBe(false);
+  });
+
+  test('the installed classifier keeps 3D000 as UnknownError with the raw code — the untyped failure the probe prevents', async () => {
+    // `classifySqlState` only types class `42` as `SqlSyntaxError`; `3D000` (`invalid_catalog_name`)
+    // is class `3D`, so a socket connect to a missing database surfaces as this shape today —
+    // the reason `read`/`delete` probe `pg_database` first instead of opening it.
+    const error = await classifyInstalled('3D000', 'database "agents" does not exist');
+    expect(error.reason._tag).toBe('UnknownError');
+    expect((error.reason as { cause?: { code?: string } }).cause?.code).toBe('3D000');
+    expect(isDependentObjectsError(error)).toBe(false);
+  });
+});

package/src/postgres/schema-sql.ts

@@ -0,0 +1,130 @@
+/**
+ * The statements `Postgres.Schema` issues and the quoting each needs.
+ *
+ * ⛔ `CREATE SCHEMA` TAKES NO BIND PARAMETERS. Measured at `gram.y@REL_18_6`:
+ *   `CreateSchemaStmt: CREATE SCHEMA [IF NOT EXISTS] opt_schema_name AUTHORIZATION
+ *   RoleSpec | create_schema_name opt_schema_element_list`. Neither the name nor the
+ *   authorization role reaches `PARAM` (`$n`), so every free-form value is escaped by hand
+ *   (`quoteIdent`) and the assembled text runs through `.unsafe()`.
+ * ★ The schema name is a single `ColId` token, so `quoteIdent` (single-token quoting) is
+ *   correct — same rule as `Postgres.Database`'s name.
+ */
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import * as Effect from 'effect/Effect';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { quoteIdent, quoteStringLiteral } from './database-sql.ts';
+import type { PgExecutor } from './database-sql.ts';
+
+/** `CREATE SCHEMA "name" [AUTHORIZATION "owner"]` — the only create this family issues. */
+export const buildCreateSchemaSql = (props: PostgresSchemaProps): string =>
+  `CREATE SCHEMA ${quoteIdent(props.name)}${
+    props.owner === undefined ? '' : ` AUTHORIZATION ${quoteIdent(props.owner)}`
+  }`;
+
+/** `COMMENT ON SCHEMA "name" IS E'…'` — issued only when a comment is declared. */
+export const buildCommentSchemaSql = (name: string, comment: string): string =>
+  `COMMENT ON SCHEMA ${quoteIdent(name)} IS ${quoteStringLiteral(comment)}`;
+
+/** `DROP SCHEMA IF EXISTS "name" [CASCADE]` — idempotent; `CASCADE` only when declared. */
+export const buildDropSchemaSql = (name: string, cascade: boolean): string =>
+  `DROP SCHEMA IF EXISTS ${quoteIdent(name)}${cascade ? ' CASCADE' : ''}`;
+
+const SELECT_SCHEMA_SQL = `SELECT
+    n.oid AS oid,
+    n.nspname AS name,
+    pg_get_userbyid(n.nspowner) AS owner,
+    obj_description(n.oid, 'pg_namespace') AS comment,
+    current_database() AS database
+  FROM pg_namespace n
+  WHERE n.nspname = $1`;
+
+/** The read: one bound `SELECT` on `pg_namespace`. `undefined` when absent. The row carries
+ * `current_database()` as `database`, so every caller can prove where the statement ran. */
+export const selectSchema = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<PostgresSchemaAttributes | undefined, SqlError> =>
+  Effect.map(pg.unsafe<PostgresSchemaAttributes>(SELECT_SCHEMA_SQL, [name]), (rows) => rows[0]);
+
+const CURRENT_DATABASE_SQL = 'SELECT current_database() AS database';
+
+/** Which database this executor actually reaches — checked before any `CREATE` or `DROP SCHEMA`,
+ * so a schema declared for `agents` can never quietly land in the maintenance database the
+ * family connection points at. */
+export const currentDatabase = (pg: PgExecutor): Effect.Effect<string, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly database: string }>(CURRENT_DATABASE_SQL),
+    // current_database() always answers one row; an empty fallback can only compare unequal,
+    // failing closed into PostgresSchemaWrongDatabase.
+    (rows) => rows[0]?.database ?? '',
+  );
+
+/**
+ * The role a `CREATE SCHEMA` without `AUTHORIZATION` is owned by. Measured at
+ * `gram.y@REL_18_6`: absent `AUTHORIZATION`, the schema owner is the current user.
+ * `reconcile` compares an omitted `owner` to this, so a race winner owned by someone else
+ * is drift rather than an adopted row.
+ */
+const CURRENT_USER_SQL = 'SELECT current_user AS role';
+
+export const currentUser = (pg: PgExecutor): Effect.Effect<string, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly role: string }>(CURRENT_USER_SQL),
+    // An empty answer can only compare unequal, failing closed into PostgresSchemaDrift.
+    (rows) => rows[0]?.role ?? '',
+  );
+
+/**
+ * "Empty" means no object of ANY kind the schema owns. Measured object kinds live in four
+ * catalogs: relations (tables, views, indexes, sequences — `pg_class`), functions and
+ * aggregates (`pg_proc`), types, domains and enums (`pg_type`), operators (`pg_operator`). A
+ * kind without a dedicated catalog (an extension's `extnamespace`, a collation) can still pass
+ * this check — and then the plain `DROP SCHEMA` answers `2BP01`, which `dropWithClient`
+ * classifies as the same typed refusal.
+ *
+ * ⚠️ THE FAKE (`fake-schema-sql.ts`) ROUTES THIS STATEMENT BY `AS empty` + `pg_class` — keep both
+ *   markers in any rewrite, and keep this check matched BEFORE the plain `pg_namespace` branch
+ *   (this SQL contains `FROM pg_namespace` too, inside its `WITH`).
+ */
+const SCHEMA_EMPTY_SQL = `WITH ns AS (SELECT oid FROM pg_namespace WHERE nspname = $1)
+  SELECT NOT EXISTS (
+    SELECT 1 FROM pg_class c WHERE c.relnamespace = (SELECT oid FROM ns)
+  ) AND NOT EXISTS (
+    SELECT 1 FROM pg_proc p WHERE p.pronamespace = (SELECT oid FROM ns)
+  ) AND NOT EXISTS (
+    SELECT 1 FROM pg_type t WHERE t.typnamespace = (SELECT oid FROM ns)
+  ) AND NOT EXISTS (
+    SELECT 1 FROM pg_operator o WHERE o.oprnamespace = (SELECT oid FROM ns)
+  ) AS empty`;
+
+/** `true` when the schema holds none of the four object catalogs above (used before a
+ * non-cascade `DROP SCHEMA`). */
+export const schemaIsEmpty = (pg: PgExecutor, name: string): Effect.Effect<boolean, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly empty: boolean }>(SCHEMA_EMPTY_SQL, [name]),
+    (rows) => rows[0]?.empty ?? true,
+  );
+
+/** SQLSTATE `2BP01` (`dependent_objects_still_exist`): the non-cascade `DROP SCHEMA` refused
+ * because an object kind outside the emptiness check's four catalogs still exists.
+ *
+ * Measured at `@effect/sql-pg@4.0.0-rc.115` `src/internal/sqlError.ts#classifySqlState`: only
+ * class `42` becomes `SqlSyntaxError`. `2BP01` is class `2B`, so it falls through to
+ * `UnknownError` (`sqlError.ts:74`). `PgConnection.ts#classifyFields` still puts the raw code
+ * on `reason.cause.code`. The runner transport copies that rule (`psql-executor.ts#failure`):
+ * `SqlSyntaxError` only when `state.startsWith('42')`, otherwise `UnknownError` with the same
+ * `cause.code`. Reading the code, not the tag, is what makes a real server refusal match. */
+export const isDependentObjectsError = (error: SqlError): boolean => {
+  const cause = error.reason.cause;
+  return (
+    typeof cause === 'object' && cause !== null && (cause as { code?: unknown }).code === '2BP01'
+  );
+};
+
+/** REL_18_6 pg_namespace.c raises duplicate_schema; both transports retain cause.code. */
+export const isDuplicateSchemaError = (error: SqlError): boolean => {
+  const cause = error.reason.cause;
+  return (
+    typeof cause === 'object' && cause !== null && (cause as { code?: unknown }).code === '42P06'
+  );
+};

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

@@ -0,0 +1,149 @@
+/** Regressions for unresolved-Output apply paths, driven through the actual runner handlers. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { postgresSchemaHandlers, reconcileWithClient } from './schema.ts';
+import { postgresRunnerConnection } from './connection.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { readArgs, router, runnerWith } from './schema-test-kit.ts';
+import type { PostgresSchemaAttributes } from './schema-attrs.ts';
+
+const props = { name: 'ledger', database: 'postgres', owner: 'postgres', cascade: true };
+const stored: PostgresSchemaAttributes = { ...props, oid: 25533, comment: null };
+const replacement = { ...stored, oid: 25534 };
+const args = (output?: PostgresSchemaAttributes) => ({
+  ...readArgs(props),
+  news: props,
+  output,
+  session: undefined as never,
+});
+
+for (const name of ['ledger', 'public']) {
+  test(`apply refuses existing ${name} without output even when owner matches`, async () => {
+    const { run, stdins } = runnerWith(
+      router({ proof: '[{"database":"postgres"}]', schema: JSON.stringify([{ ...stored, name }]) }),
+    );
+    const error = await Effect.runPromise(
+      postgresSchemaHandlers
+        .reconcile({ ...args(), news: { ...props, name } })
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+          Effect.flip,
+        ),
+    );
+    expect(error).toMatchObject({ _tag: 'PostgresSchemaExistsRefused' });
+    expect(stdins.every((s) => s.startsWith('SELECT'))).toBe(true);
+  });
+}
+
+test('update refuses a recycled oid before it can replace the delete proof', async () => {
+  const fake = makeFakeSql({ schemas: [replacement], schemasWithRelations: ['ledger'] });
+  const error = await Effect.runPromise(Effect.flip(reconcileWithClient(fake, props, stored)));
+  expect(error).toMatchObject({
+    _tag: 'PostgresSchemaIdentityRefused',
+    storedOid: 25533,
+    liveOid: 25534,
+  });
+  expect(fake.schemas.get('ledger')).toEqual(replacement);
+  expect(fake.relationsIn.has('ledger')).toBe(true);
+});
+
+test('read refuses a recycled oid instead of refreshing persisted proof', async () => {
+  const { run } = runnerWith(
+    router({ probe: '[{"present":1}]', schema: JSON.stringify([replacement]) }),
+  );
+  const read = postgresSchemaHandlers.read;
+  if (read === undefined) throw new Error('missing read');
+  const error = await Effect.runPromise(
+    read({ ...readArgs(props), output: stored }).pipe(
+      Effect.provide(postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' })),
+      Effect.flip,
+    ),
+  );
+  expect(error).toMatchObject({ _tag: 'PostgresSchemaIdentityRefused' });
+});
+
+for (const [change, tag] of [
+  [{ name: 'new_ledger' }, 'PostgresSchemaRenameRefused'],
+  [{ database: 'new_database' }, 'PostgresSchemaDatabaseRefused'],
+] as const) {
+  test(`apply repeats ${tag} after unresolved diff`, async () => {
+    const { run, stdins } = runnerWith(
+      router({
+        proof: JSON.stringify([{ database: change.database ?? 'postgres' }]),
+        schema: JSON.stringify([{ ...stored, ...change }]),
+      }),
+    );
+    const error = await Effect.runPromise(
+      postgresSchemaHandlers
+        .reconcile({ ...args(stored), news: { ...props, ...change } })
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+          Effect.flip,
+        ),
+    );
+    expect(error).toMatchObject({ _tag: tag });
+    expect(stdins).toEqual([]);
+  });
+}
+
+test('same-owner create race is a typed exists refusal, never a comment or adoption', async () => {
+  const fake = makeFakeSql({ roles: ['postgres'], raceNextCreateSchema: 'postgres' });
+  const error = await Effect.runPromise(
+    Effect.flip(reconcileWithClient(fake, { ...props, comment: 'ours' })),
+  );
+  expect(error).toMatchObject({ _tag: 'PostgresSchemaExistsRefused' });
+  expect(fake.schemas.get('ledger')?.comment).toBeNull();
+});
+
+test('runner 42P06 becomes an adoption refusal; other SQLSTATEs remain SqlError', async () => {
+  for (const code of ['42P06', '42501']) {
+    const run = ({ stdin }: { stdin: string }) =>
+      Promise.resolve(
+        stdin.startsWith('CREATE')
+          ? { code: 3, stdout: '', stderr: `ERROR:  ${code}: refused` }
+          : {
+              code: 0,
+              stdout:
+                stdin.includes('current_database()') && !stdin.includes('pg_namespace')
+                  ? '[{"database":"postgres"}]'
+                  : stdin.includes('pg_roles')
+                    ? '[{"present":1}]'
+                    : '[]',
+              stderr: '',
+            },
+      );
+    const error = await Effect.runPromise(
+      postgresSchemaHandlers
+        .reconcile(args())
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+          ),
+          Effect.flip,
+        ),
+    );
+    expect(error._tag).toBe(code === '42P06' ? 'PostgresSchemaExistsRefused' : 'SqlError');
+  }
+});
+
+// Apply.ts passes the adopted live attributes as output. The stricter gate must permit that.
+test('explicit adoption output permits a matching schema with zero writes', async () => {
+  const { run, stdins } = runnerWith(
+    router({ proof: '[{"database":"postgres"}]', schema: JSON.stringify([stored]) }),
+  );
+  const result = await Effect.runPromise(
+    postgresSchemaHandlers
+      .reconcile(args(stored))
+      .pipe(
+        Effect.provide(
+          postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+        ),
+      ),
+  );
+  expect(result).toEqual(stored);
+  expect(stdins.every((s) => s.startsWith('SELECT'))).toBe(true);
+});

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

@@ -0,0 +1,85 @@
+/**
+ * Shared wiring for the runner-transport `Postgres.Schema` handler tests: the recording
+ * `PsqlRunner` (every stdin and its `psql` argv), the handler-argument builders, and the
+ * one SQL router they all answer through.
+ *
+ * ⚠️ THE ROUTER ORDER IS LOAD-BEARING (`schema-sql.ts`): the emptiness check's `WITH`
+ *   contains `FROM pg_namespace`, and the schema row SELECT contains
+ *   `current_database() AS database` — so `AS empty` must be matched before
+ *   `FROM pg_namespace`, and `FROM pg_namespace` before `current_database()`. The database
+ *   probe (`SELECT 1 AS present FROM pg_database`, `database-sql.ts`) carries no other
+ *   branch's marker and matches its own.
+ */
+import type { PsqlRunner } from './psql-executor.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+
+export const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
+
+/** One answer per statement shape a handler issues; `undefined` falls through the router. */
+export interface RouteAnswers {
+  /** `schemaIsEmpty` — the pre-DROP emptiness check (`cascade` unset). */
+  readonly empty?: string;
+  /** `selectSchema` — the schema row re-read, or `[]` for an absent schema. */
+  readonly schema?: string;
+  /** `databaseExists` — `[{\"present\":1}]` when the declared database exists, `[]` when not. */
+  readonly probe?: string;
+  /** `current_database()` — the proof that the override reached the declared database. */
+  readonly proof?: string;
+}
+
+/** Route one stdin to its answer by the markers above, `undefined` when no branch matches. */
+export const route = (stdin: string, answers: RouteAnswers): string | undefined => {
+  if (stdin.includes('AS empty')) return answers.empty;
+  if (stdin.includes('FROM pg_namespace')) return answers.schema;
+  if (stdin.includes('FROM pg_database')) return answers.probe;
+  if (stdin.includes('current_database()')) return answers.proof;
+  return undefined;
+};
+
+/** A `router` that answers every stdin (unrouted statements answer the empty string). */
+export const router = (answers: RouteAnswers) => (stdin: string) => route(stdin, answers) ?? '';
+
+/**
+ * A recording `PsqlRunner`: every stdin and the `psql` argv are kept, each stdin answered by
+ * `answers`. The argv recording pins the `-d` database each statement ran against — the last
+ * element of the argv is the `psql -d` value (`psql-executor.ts`).
+ */
+export const runnerWith = (
+  answers: (stdin: string) => string,
+): { run: PsqlRunner; stdins: string[]; argvs: Array<readonly string[]> } => {
+  const stdins: string[] = [];
+  const argvs: Array<readonly string[]> = [];
+  return {
+    run: ({ stdin, argv }) => {
+      stdins.push(stdin);
+      argvs.push(argv);
+      return Promise.resolve({ code: 0, stdout: answers(stdin), stderr: '' });
+    },
+    stdins,
+    argvs,
+  };
+};
+
+/** The handler inputs the engine passes on `delete`. `output` is the persisted state — the
+ * `oid` + `owner` the last reconcile asserted, which delete must prove the live row still
+ * matches before it drops (`schema-delete.ts`). */
+export const deleteArgs = (olds: PostgresSchemaProps, output: PostgresSchemaAttributes) => ({
+  id: 'x',
+  fqn: 'x',
+  instanceId: 'x',
+  olds,
+  output,
+  session: undefined as never,
+  bindings: [] as never,
+});
+
+/** The handler inputs the engine passes on `read` (undefined output is the adopt path). */
+export const readArgs = (olds: PostgresSchemaProps) => ({
+  id: 'x',
+  fqn: 'x',
+  instanceId: 'x',
+  olds,
+  output: undefined,
+  session: undefined as never,
+  bindings: [] as never,
+});