@homeflare/alchemy 0.46.0 → 0.47.0

package/src/postgres/schema-errors.ts

@@ -4,6 +4,7 @@
  * Refusals use checked catalog facts or raw SQLSTATE (42P06 / 2BP01), never driver message text.
  */
 import * as Data from 'effect/Data';
+import type { PostgresSchemaCascadeSequencesRefused } from './schema-sequence-error.ts';
 
 /** A declared name would be silently truncated (same as `PostgresDatabaseNameRefused`). */
 export class PostgresSchemaNameRefused extends Data.TaggedError('PostgresSchemaNameRefused')<{
@@ -94,6 +95,29 @@ export class PostgresSchemaDropNotEmptyError extends Data.TaggedError(
   }
 }
 
+/**
+ * `cascade: true` refused: `DROP SCHEMA … CASCADE` would also drop objects that live in OTHER
+ * schemas because they depend on something in this one (a view, a foreign key or a trigger
+ * another stack owns). The refusal carries the COUNT only — never an object name, so the error
+ * cannot disclose another owner's catalog. Nothing was dropped: move or drop those dependents
+ * deliberately, or empty this schema by hand and declare `cascade: false`.
+ */
+export class PostgresSchemaCascadeCrossSchemaRefused extends Data.TaggedError(
+  'PostgresSchemaCascadeCrossSchemaRefused',
+)<{
+  readonly schema: string;
+  /** How many dependent objects live outside this schema (at least one when raised). */
+  readonly dependents: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": cascade: true refused — ${String(this.dependents)} ` +
+      'dependent object(s) outside this schema would be dropped with it. No DROP was issued. ' +
+      'Remove or move those dependents first.'
+    );
+  }
+}
+
 /** Every statement this resource issues must run against the DECLARED database. The family
  * connection points at a maintenance database, so the schema handlers open `props.database`
  * themselves (`withPg`'s database override); this failure means the server answered
@@ -204,6 +228,8 @@ export type PostgresSchemaError =
   | PostgresSchemaDrift
   | PostgresSchemaCreateVanished
   | PostgresSchemaDropNotEmptyError
+  | PostgresSchemaCascadeCrossSchemaRefused
+  | PostgresSchemaCascadeSequencesRefused
   | PostgresSchemaDeleteForeignRefused
   | PostgresSchemaWrongDatabase
   | PostgresSchemaDatabaseRefused;

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

@@ -14,6 +14,7 @@ import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-att
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { postgresSchemaHandlers } from './schema.ts';
 import { PostgresSchemaDropNotEmptyError, PostgresSchemaWrongDatabase } from './schema-errors.ts';
+import { buildAtomicDropSql } from './schema-drop-sql.ts';
 import { deleteArgs, ok, readArgs, route, router, runnerWith } from './schema-test-kit.ts';
 
 const sampleOutput: PostgresSchemaAttributes = {
@@ -51,10 +52,12 @@ describe('delete handler (runner transport)', () => {
           ),
         ),
     );
-    expect(stdins.find((s) => s.startsWith('DROP SCHEMA'))).toBe(
-      'DROP SCHEMA IF EXISTS "ledger" CASCADE;',
+    // The drop is ONE `DO` statement carrying the proven oid + owner (`schema-drop-sql.ts`),
+    // not a re-read followed by a separate `DROP`.
+    expect(stdins.find((s) => s.startsWith('DO '))).toBe(
+      `${buildAtomicDropSql({ name: 'ledger', oid: 1, owner: 'tim', cascade: true })};`,
     );
-    // One `psql` argv per STATEMENT: probe, proof, ownership re-read, drop. The probe's argv
+    // One `psql` argv per STATEMENT: probe, proof, ownership re-read, atomic 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);
@@ -80,17 +83,19 @@ describe('delete handler (runner transport)', () => {
           ),
         ),
     );
-    expect(stdins.find((s) => s.startsWith('DROP SCHEMA'))).toBe('DROP SCHEMA IF EXISTS "ledger";');
+    expect(stdins.find((s) => s.startsWith('DO '))).toBe(
+      `${buildAtomicDropSql({ name: 'ledger', oid: 1, owner: 'tim', cascade: false })};`,
+    );
   });
 
-  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,
-      }),
+  test('a non-empty schema is the typed refusal the atomic drop raises (HF002), over one psql', async () => {
+    const answers = router({
+      probe: '[{"present":1}]',
+      schema: '[{"name":"ledger","oid":1,"owner":"tim"}]',
+      proof,
+    });
+    const { run, stdins } = runnerWith(answers, (stdin) =>
+      stdin.startsWith('DO ') ? 'ERROR:  HF002: schema not empty' : undefined,
     );
     const error = await Effect.runPromise(
       Effect.flip(
@@ -104,7 +109,9 @@ describe('delete handler (runner transport)', () => {
       ),
     );
     expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
-    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+    // Proof and drop were ONE statement: exactly one `DO`, and no separate emptiness probe.
+    expect(stdins.filter((s) => s.startsWith('DO ')).length).toBe(1);
+    expect(stdins.some((s) => s.includes('AS empty'))).toBe(false);
   });
 
   test('the real handler refuses a wrong connected database before any DROP', async () => {
@@ -128,7 +135,7 @@ describe('delete handler (runner transport)', () => {
       ),
     );
     expect(error).toBeInstanceOf(PostgresSchemaWrongDatabase);
-    expect(stdins.some((s) => s.startsWith('DROP SCHEMA'))).toBe(false);
+    expect(stdins.some((s) => s.startsWith('DO '))).toBe(false);
   });
 
   test('defaultRemovalPolicy is retain — declared on the Resource for Postgres.Schema itself', () => {

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

@@ -1,18 +1,16 @@
 /**
  * `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.
+ * quoting, and the `current_database()` proof every write path runs first. The drop rules live
+ * in `schema-drop.test.ts`.
  */
 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,
@@ -42,7 +40,9 @@ describe('the current_database() proof', () => {
     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.includes('FROM pg_catalog.pg_namespace'))).toBe(
+      false,
+    );
     expect(fake.statements.some((s) => s.text.startsWith('CREATE SCHEMA'))).toBe(false);
   });
 
@@ -50,7 +50,7 @@ describe('the current_database() proof', () => {
     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.statements.some((s) => s.text.startsWith('DO '))).toBe(false);
     expect(fake.schemas.get('ledger')).not.toBeUndefined();
   });
 
@@ -190,57 +190,3 @@ describe('read', () => {
     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-reconcile.ts

@@ -1,6 +1,6 @@
 /** 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 { SqlError } from 'effect/sql/SqlError';
 import { type PgExecutor, roleExists } from './database-sql.ts';
 import {
   type PostgresSchemaAttributes,

package/src/postgres/schema-sequence-error.ts

@@ -0,0 +1,38 @@
+import * as Data from 'effect/Data';
+
+/**
+ * `cascade: true` on a schema that holds a SEQUENCE is refused (`HF004`, `schema-drop-sql.ts`).
+ *
+ * ⛔ A sequence cannot be locked by `LOCK TABLE`, so the drop's closure proof has a hole there: a
+ *   concurrent, uncommitted `CREATE VIEW other.v AS SELECT last_value FROM ours.seq` is invisible
+ *   to the scan, and when it commits while the drop waits on the sequence, PostgreSQL's deletion
+ *   cascades into `other.v` (Codex read of PR 357, 2026-10-06). Serial and identity columns each
+ *   own a sequence, so such a schema cannot be cascade-dropped by this provider.
+ * The message carries a COUNT only. Nothing was dropped: drop the schema's contents deliberately
+ * (the sequences included), then declare `cascade: false`.
+ */
+export class PostgresSchemaCascadeSequencesRefused extends Data.TaggedError(
+  'PostgresSchemaCascadeSequencesRefused',
+)<{
+  readonly schema: string;
+  /** How many sequences the schema holds (at least one when raised). */
+  readonly sequences: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": cascade: true refused — the schema holds ` +
+      `${String(this.sequences)} sequence(s) (serial/identity columns own one), which cannot be ` +
+      'locked, so a concurrent dependent could escape the cascade proof. No DROP was issued. ' +
+      'Drop the schema contents first, then declare cascade: false.'
+    );
+  }
+}
+
+/** The sequence COUNT out of an `HF004` error; unreadable still refuses (1, never 0). */
+export const sequencesCount = (error: {
+  readonly reason: { readonly cause?: unknown };
+}): number => {
+  const cause = error.reason.cause;
+  const message = typeof cause === 'object' && cause !== null ? (cause as Error).message : '';
+  return Math.max(1, Number(/sequences:\s*(\d+)/.exec(message ?? '')?.[1] ?? 1));
+};

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

@@ -11,7 +11,8 @@ 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 { SqlClient, TransactionConnection } from 'effect/sql/SqlClient';
+import { PIN_SEARCH_PATH_SQL } from './search-path.ts';
 import { isDependentObjectsError } from './schema-sql.ts';
 import { classifyInstalled } from './installed-classifier.ts';
 import { PostgresPool, postgresConnection } from './connection.ts';
@@ -31,6 +32,8 @@ const schemaRead = postgresSchemaHandlers.read;
 const pools: Array<{ database?: string | undefined }> = [];
 /** Every SQL text the fake client ran, in order. */
 const queries: string[] = [];
+/** The pool count at each `SET search_path`: one pin per pool, before that pool's statements. */
+const pins: number[] = [];
 /** The router answers for the current test (`schema-test-kit.ts` markers, JSON strings). */
 let answers: RouteAnswers = {};
 
@@ -38,7 +41,15 @@ let answers: RouteAnswers = {};
 // callbacks), and `Statement<A>` is an `Effect<ReadonlyArray<A>, SqlError>` — a plain succeed
 // satisfies the same call shape.
 const fakeClient = {
+  // `pinnedSocketExecutor` reserves one connection and routes every statement through the
+  // client's own `transactionService` — the fake only has to answer both.
+  reserve: Effect.succeed({}),
+  transactionService: TransactionConnection(0),
   unsafe: (text: string) => {
+    if (text === PIN_SEARCH_PATH_SQL) {
+      pins.push(pools.length);
+      return Effect.succeed([] as never);
+    }
     queries.push(text);
     const answer = route(text, answers);
     return Effect.succeed(
@@ -72,6 +83,7 @@ describe('socket transport: a missing declared database is schema absent', () =>
   beforeEach(() => {
     pools.length = 0;
     queries.length = 0;
+    pins.length = 0;
     answers = {};
   });
 
@@ -85,8 +97,8 @@ describe('socket transport: a missing declared database is schema absent', () =>
     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);
+    expect(queries[0]).toContain('FROM pg_catalog.pg_database');
+    expect(queries.some((q) => q.startsWith('DO '))).toBe(false);
   });
 
   test('read answers absent: the untyped 3D000 connect never happens', async () => {
@@ -98,7 +110,7 @@ describe('socket transport: a missing declared database is schema absent', () =>
     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[0]).toContain('FROM pg_catalog.pg_database');
   });
 
   test('the `database` override reaches the pool: probe over the family pool, statements over the declared one', async () => {
@@ -113,7 +125,9 @@ describe('socket transport: a missing declared database is schema absent', () =>
     );
     // 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);
+    // Each pool's reserved connection is pinned before its first statement: pool 1, then pool 2.
+    expect(pins).toEqual([1, 2]);
+    expect(queries.some((q) => q.startsWith('DO '))).toBe(true);
   });
 
   test('read over an existing declared database answers the row from the overridden pool', async () => {
@@ -147,7 +161,7 @@ describe('socket transport: a missing declared database is schema absent', () =>
     );
     expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
     expect(error).toMatchObject({ liveOid: 16443, liveOwner: 'other_role', lastOid: 16442 });
-    expect(queries.some((q) => q.startsWith('DROP SCHEMA'))).toBe(false);
+    expect(queries.some((q) => q.startsWith('DO '))).toBe(false);
   });
 
   test('the installed classifier keeps 3D000 as UnknownError with the raw code — the untyped failure the probe prevents', async () => {

package/src/postgres/schema-sql.ts

@@ -9,7 +9,7 @@
  * ★ 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 type { SqlError } from 'effect/sql/SqlError';
 import * as Effect from 'effect/Effect';
 import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
 import { quoteIdent, quoteStringLiteral } from './database-sql.ts';
@@ -32,10 +32,10 @@ export const buildDropSchemaSql = (name: string, cascade: boolean): string =>
 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,
+    pg_catalog.pg_get_userbyid(n.nspowner) AS owner,
+    pg_catalog.obj_description(n.oid, 'pg_namespace') AS comment,
     current_database() AS database
-  FROM pg_namespace n
+  FROM pg_catalog.pg_namespace n
   WHERE n.nspname = $1`;
 
 /** The read: one bound `SELECT` on `pg_namespace`. `undefined` when absent. The row carries
@@ -84,18 +84,23 @@ export const currentUser = (pg: PgExecutor): Effect.Effect<string, SqlError> =>
  *
  * ⚠️ 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`).
+ *   (this SQL contains `FROM pg_catalog.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)
+/** The four-catalog emptiness predicate over a namespace oid expression — shared by this read
+ * and by the atomic drop's in-transaction check (`schema-drop-sql.ts`), so the two cannot
+ * disagree about what "empty" means. */
+export const emptyPredicate = (ns: string): string => `NOT EXISTS (
+    SELECT 1 FROM pg_catalog.pg_class c WHERE c.relnamespace = ${ns}
   ) AND NOT EXISTS (
-    SELECT 1 FROM pg_proc p WHERE p.pronamespace = (SELECT oid FROM ns)
+    SELECT 1 FROM pg_catalog.pg_proc p WHERE p.pronamespace = ${ns}
   ) AND NOT EXISTS (
-    SELECT 1 FROM pg_type t WHERE t.typnamespace = (SELECT oid FROM ns)
+    SELECT 1 FROM pg_catalog.pg_type t WHERE t.typnamespace = ${ns}
   ) AND NOT EXISTS (
-    SELECT 1 FROM pg_operator o WHERE o.oprnamespace = (SELECT oid FROM ns)
-  ) AS empty`;
+    SELECT 1 FROM pg_catalog.pg_operator o WHERE o.oprnamespace = ${ns}
+  )`;
+
+const SCHEMA_EMPTY_SQL = `WITH ns AS (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
+  SELECT ${emptyPredicate('(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`). */

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

@@ -5,6 +5,7 @@ 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 { stripPin } from './search-path.ts';
 import type { PostgresSchemaAttributes } from './schema-attrs.ts';
 
 const props = { name: 'ledger', database: 'postgres', owner: 'postgres', cascade: true };
@@ -101,21 +102,23 @@ test('same-owner create race is a typed exists refusal, never a comment or adopt
 
 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(
+    const run = ({ stdin: raw }: { stdin: string }) => {
+      const stdin = stripPin(raw);
+      return Promise.resolve(
         stdin.startsWith('CREATE')
           ? { code: 3, stdout: '', stderr: `ERROR:  ${code}: refused` }
           : {
               code: 0,
               stdout:
-                stdin.includes('current_database()') && !stdin.includes('pg_namespace')
+                stdin.includes('current_database()') && !stdin.includes('pg_catalog.pg_namespace')
                   ? '[{"database":"postgres"}]'
-                  : stdin.includes('pg_roles')
+                  : stdin.includes('pg_catalog.pg_roles')
                     ? '[{"present":1}]'
                     : '[]',
               stderr: '',
             },
       );
+    };
     const error = await Effect.runPromise(
       postgresSchemaHandlers
         .reconcile(args())

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

@@ -11,6 +11,7 @@
  *   branch's marker and matches its own.
  */
 import type { PsqlRunner } from './psql-executor.ts';
+import { stripPin } from './search-path.ts';
 import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
 
 export const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
@@ -29,9 +30,12 @@ export interface RouteAnswers {
 
 /** Route one stdin to its answer by the markers above, `undefined` when no branch matches. */
 export const route = (stdin: string, answers: RouteAnswers): string | undefined => {
+  // The atomic drop (`schema-drop-sql.ts`) quotes every marker below inside its body: it answers
+  // nothing, and a refusal is injected by `runnerWith`'s `failOn`, never routed.
+  if (stdin.startsWith('DO ')) return 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('FROM pg_catalog.pg_namespace')) return answers.schema;
+  if (stdin.includes('FROM pg_catalog.pg_database')) return answers.probe;
   if (stdin.includes('current_database()')) return answers.proof;
   return undefined;
 };
@@ -46,14 +50,24 @@ export const router = (answers: RouteAnswers) => (stdin: string) => route(stdin,
  */
 export const runnerWith = (
   answers: (stdin: string) => string,
+  /** The `psql` stderr a statement fails with (exit 3), or `undefined` to answer normally. */
+  failOn: (stdin: string) => string | undefined = () => undefined,
 ): { run: PsqlRunner; stdins: string[]; argvs: Array<readonly string[]> } => {
   const stdins: string[] = [];
   const argvs: Array<readonly string[]> = [];
   return {
-    run: ({ stdin, argv }) => {
+    // The pin prefix (`search-path.ts`) is stripped: these tests assert the STATEMENT. The pin
+    // itself is asserted once, on the raw stdin, in `search-path.test.ts`.
+    run: ({ stdin: raw, argv }) => {
+      const stdin = stripPin(raw);
       stdins.push(stdin);
       argvs.push(argv);
-      return Promise.resolve({ code: 0, stdout: answers(stdin), stderr: '' });
+      const stderr = failOn(stdin);
+      return Promise.resolve(
+        stderr === undefined
+          ? { code: 0, stdout: answers(stdin), stderr: '' }
+          : { code: 3, stdout: '', stderr },
+      );
     },
     stdins,
     argvs,

package/src/postgres/search-path.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The `search_path` pin (`search-path.ts`): every session this family opens starts with
+ * `SET search_path = pg_catalog, pg_temp`, on both transports, and the SQL builders only name
+ * catalogs as `pg_catalog.*`. The Opus read of PR 334 (2026-10-02) found that a role allowed to
+ * create objects in a schema on the path could forge `pg_namespace` and fake the delete proof.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { currentDatabase } from './schema-sql.ts';
+import { makePsqlExecutor } from './psql-executor.ts';
+import { PIN_SCRIPT_PREFIX, PIN_SEARCH_PATH_SQL } from './search-path.ts';
+
+describe('runner transport', () => {
+  const target = { database: 'postgres', username: 'postgres' };
+  const record = () => {
+    const stdins: string[] = [];
+    const run = ({ stdin }: { stdin: string }) => {
+      stdins.push(stdin);
+      return Promise.resolve({ code: 0, stdout: '[]', stderr: '' });
+    };
+    return { stdins, run };
+  };
+
+  test('a read starts with the pin, in the same psql session as the statement', async () => {
+    const { stdins, run } = record();
+    await Effect.runPromise(currentDatabase(makePsqlExecutor(run, target)));
+    expect(stdins).toHaveLength(1);
+    expect(stdins[0]?.startsWith('SET search_path = pg_catalog, pg_temp;\n')).toBe(true);
+    expect(stdins[0]?.startsWith(PIN_SCRIPT_PREFIX)).toBe(true);
+  });
+
+  test('a write and a transaction start with the pin too', async () => {
+    const { stdins, run } = record();
+    const pg = makePsqlExecutor(run, target);
+    await Effect.runPromise(pg.unsafe('COMMENT ON SCHEMA "a" IS E\'b\''));
+    await Effect.runPromise(pg.transaction(['CREATE ROLE "r"']));
+    expect(stdins).toHaveLength(2);
+    for (const stdin of stdins) expect(stdin.startsWith(PIN_SCRIPT_PREFIX)).toBe(true);
+    // The pin comes BEFORE `BEGIN`: it is a session setting, not part of the transaction.
+    expect(stdins[1]).toBe(`${PIN_SCRIPT_PREFIX}BEGIN;\nCREATE ROLE "r";\nCOMMIT;`);
+  });
+
+  test('the pin is the one statement text both transports share', () => {
+    expect(PIN_SEARCH_PATH_SQL).toBe('SET search_path = pg_catalog, pg_temp');
+  });
+});
+
+/** Every hand-written SQL builder in this family. The `*errors.ts` files are excluded: they name
+ * catalogs in error-message PROSE, which no server ever parses. The fakes match on the qualified
+ * text the builders emit, so their own tests pin them. */
+const sources = readdirSync(import.meta.dir).filter(
+  (f) =>
+    f.endsWith('.ts') &&
+    !f.endsWith('.test.ts') &&
+    !f.startsWith('fake-') &&
+    !/errors?\.ts$/.test(f),
+);
+const CATALOGS =
+  /(?<![\w.])(pg_(?:namespace|class|proc|type|operator|roles|authid|auth_members|database|tablespace|attribute|default_acl|depend|constraint|trigger|rewrite|attrdef|policy))\b/g;
+
+describe('catalog references', () => {
+  test('no SQL builder names a catalog without the pg_catalog. qualifier', () => {
+    const offenders: string[] = [];
+    for (const file of sources) {
+      const text = readFileSync(`${import.meta.dir}/${file}`, 'utf8');
+      // Only template/quoted SQL is judged: skip comment lines and `'pg_namespace'` literals
+      // (an `obj_description` class argument is a string, not a relation reference).
+      for (const [index, line] of text.split('\n').entries()) {
+        const trimmed = line.trim();
+        if (/^(\/\/|\*|\/\*)/.test(trimmed)) continue;
+        for (const match of line.matchAll(CATALOGS)) {
+          const before = line[(match.index ?? 0) - 1];
+          if (before === "'" || before === '`') continue;
+          offenders.push(`${file}:${String(index + 1)} ${match[1] ?? ''}`);
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  test('the scan sees the catalogs it is meant to police', () => {
+    const joined = sources.map((f) => readFileSync(`${import.meta.dir}/${f}`, 'utf8')).join('\n');
+    for (const needle of [
+      'pg_catalog.pg_namespace',
+      'pg_catalog.pg_class',
+      'pg_catalog.pg_depend',
+      'pg_catalog.pg_roles',
+      'pg_catalog.pg_database',
+    ]) {
+      expect(joined).toContain(needle);
+    }
+  });
+
+  test('the scan itself fails on an unqualified reference', () => {
+    const bad = '  FROM pg_namespace n\n  JOIN pg_catalog.pg_class c ON true';
+    const hits = [...bad.matchAll(CATALOGS)].map((m) => m[1]);
+    expect(hits).toEqual(['pg_namespace']);
+  });
+});

package/src/postgres/search-path.ts

@@ -0,0 +1,62 @@
+/**
+ * The session setup every `Postgres.*` connection runs first: `search_path = pg_catalog, pg_temp`.
+ *
+ * ⛔ AN UNPINNED SESSION READS ITS OWN CATALOGS THROUGH `search_path`. Postgres searches
+ *   `pg_catalog` first only while the path does not NAME it (ddl.sgml 5.10.3); a role- or
+ *   database-level `ALTER … SET search_path = public, pg_catalog` (or a path naming any schema
+ *   another role may create in) puts a writable schema ahead of it, and a `public.pg_namespace`
+ *   TABLE then answers the delete proof's `oid`/`owner` re-read. Found by the Opus read of PR 334
+ *   (2026-10-02). The pin makes the order ours whatever the role, database or server says; the SQL
+ *   builders ALSO write `pg_catalog.<name>` (`catalog-qualified.test.ts` greps for it), so no
+ *   single layer is the whole defence.
+ * ★ `pg_temp` goes LAST on purpose: unnamed, it is searched FIRST for relations.
+ * ★ TWO TRANSPORTS, TWO MECHANISMS. The runner path prefixes the stdin script: `psql` argv is
+ *   the consumer's to join into a remote command, and a value with a space would split. The
+ *   socket path pins the ONE connection an operation reserves, because the driver's startup
+ *   message carries user, database and application_name only (`PgConnection.ts`, 4.0.0-rc.115)
+ *   and a pool hands each statement a different, unpinned connection.
+ */
+import type { PgClient } from '@effect/sql-pg/PgClient';
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+import type { SqlError } from 'effect/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+
+export const PIN_SEARCH_PATH_SQL = 'SET search_path = pg_catalog, pg_temp';
+
+/** The runner path's script prefix. */
+export const PIN_SCRIPT_PREFIX = `${PIN_SEARCH_PATH_SQL};\n`;
+
+/** A runner stdin without its pin — for tests that assert the statement that follows it. */
+export const stripPin = (stdin: string): string =>
+  stdin.startsWith(PIN_SCRIPT_PREFIX) ? stdin.slice(PIN_SCRIPT_PREFIX.length) : stdin;
+
+/**
+ * A `PgExecutor` over ONE reserved, pinned connection, for the life of the surrounding scope.
+ * `unsafe` runs on it (the client routes any statement under `transactionService` to that
+ * connection, so spans and error classification stay the driver's); `transaction` is a plain
+ * `BEGIN` … `COMMIT` on it — `withTransaction` would open a SAVEPOINT, because the service is
+ * already provided. A failure rolls back, and the pin is re-asserted by the next operation's own
+ * reservation, never assumed to survive one.
+ */
+export const pinnedSocketExecutor = (
+  pg: PgClient,
+): Effect.Effect<PgExecutor, SqlError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const connection = yield* pg.reserve;
+    const run = <A extends object>(sql: string, params?: ReadonlyArray<unknown>) =>
+      Effect.provideService(pg.unsafe<A>(sql, params), pg.transactionService, [connection, 0]);
+    yield* run(PIN_SEARCH_PATH_SQL);
+    return {
+      unsafe: run,
+      transaction: (statements) =>
+        Effect.gen(function* () {
+          yield* run('BEGIN');
+          for (const sql of statements) yield* run(sql);
+          yield* run('COMMIT');
+        }).pipe(
+          Effect.onError(() => run('ROLLBACK').pipe(Effect.ignore)),
+          Effect.asVoid,
+        ),
+    };
+  });