@homeflare/alchemy 0.43.0 → 0.45.0

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

@@ -0,0 +1,162 @@
+/**
+ * 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(
+  // tmp-allow: unix socket directory the driver joins a socket name onto, not a directory this test creates
+  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,
+});

package/src/postgres/schema.ts

@@ -0,0 +1,130 @@
+/**
+ * `Postgres.Schema` — create-and-assert over one schema in a self-hosted PostgreSQL 18 cluster.
+ *
+ * ★ A SCHEMA CARRIES NO OWNERSHIP MARK, exactly like `Postgres.Database` (H1). `read` answers
+ *   `Unowned` for a match, so every already-live schema needs `adopt(true)` in the stack that
+ *   declares it.
+ * ⛔ NOT ALTER-CAPABLE. `ALTER SCHEMA` only renames or changes owner in Postgres; neither is
+ *   implemented. An owner or comment mismatch against the live row is a typed
+ *   `PostgresSchemaDrift` refusal, never an `ALTER SCHEMA` — same rule `Postgres.Database`
+ *   applies to its own asserted props. An omitted `owner` is compared to `current_user`
+ *   (`schema-assert.ts`): a fresh create without `AUTHORIZATION` would be owned by that role.
+ * ⛔ THE DECLARED `database` IS PROVEN, NEVER ASSUMED. The family connection points at a
+ *   maintenance database (a brand-new database cannot be connected to on a cold plan —
+ *   `docs/postgres.md#measured-path`), so the handlers below open `props.database` themselves
+ *   (`withPg`'s database override) and `reconcile`/`drop` first compare `current_database()`
+ *   against it (`PostgresSchemaWrongDatabase`). Without that proof a seat's schema would be
+ *   created in whatever database the single connection happened to target.
+ * ⛔ `delete` DROPS ONLY WHAT IT CAN PROVE IT CREATED. Before any `DROP`, the handler re-reads
+ *   the live row (`schema-delete.ts`) and matches it against the persisted `oid` + `owner`;
+ *   a mismatch is `PostgresSchemaDeleteForeignRefused`, never a `DROP` (`CASCADE` included) —
+ *   the schema under that name may be another role's, recreated out of band.
+ * ⛔ A MISSING DECLARED DATABASE IS "SCHEMA ABSENT" IN `read` AND `delete`. Both probe
+ *   `pg_database` over the family connection first (`database-sql.ts#databaseExists`), so a
+ *   cold plan against a not-yet-created database plans a create (`read` answers absent)
+ *   instead of failing untyped on connect (`ConnectionError` over psql, `UnknownError` 3D000
+ *   over the socket), and a delete of a dropped database stays idempotent. `reconcile` still
+ *   requires the database to exist — that ordering is the declaration's job (`docs/
+ *   postgres-schema.md`: pass `database: db.name`).
+ * ⛔ `delete` DROPS ONLY WHEN SAFE. `DROP SCHEMA` refuses a non-empty schema unless
+ *   `cascade: true` is declared (`PostgresSchemaDropNotEmptyError`); the `cascade` prop
+ *   defaults to `false` (retain policy by default — see `defaultRemovalPolicy: 'retain'`).
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PostgresSchemaAttributes, type PostgresSchemaProps } from './schema-attrs.ts';
+import { schemaNameByteRefusal } from './schema-attrs.ts';
+import { diffPostgresSchema } from './schema-diff.ts';
+import { selectSchema } from './schema-sql.ts';
+import { databaseExists } from './database-sql.ts';
+import { reconcileWithClient } from './schema-reconcile.ts';
+import { assertSchemaIdentity, assertSchemaTarget } from './schema-identity.ts';
+import { deleteWithClient, dropWithClient } from './schema-delete.ts';
+import type { PgExecutor } from './database-sql.ts';
+import { type PostgresConnection, withPg } from './connection.ts';
+import { PostgresSchemaNameRefused, PostgresSchemaWrongDatabase } from './schema-errors.ts';
+
+export interface PostgresSchema extends Resource<
+  'Postgres.Schema',
+  PostgresSchemaProps,
+  PostgresSchemaAttributes,
+  never,
+  PostgresConnection
+> {}
+
+export const PostgresSchema = Resource<PostgresSchema>('Postgres.Schema', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Same dual `typeof` guard as `isPostgresDatabase` (see `database.ts`): a resource constructor
+ * is a callable `Object.assign`ed function, not a plain object. */
+export const isPostgresSchema = (value: unknown): value is PostgresSchema =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Postgres.Schema';
+
+/** The core of `read`: one bound `SELECT`, no ownership branding. */
+export const readWithClient = (pg: PgExecutor, name: string) => selectSchema(pg, name);
+
+export { diffPostgresSchema } from './schema-diff.ts';
+export { reconcileWithClient } from './schema-reconcile.ts';
+export { deleteWithClient, dropWithClient };
+
+/** The five lifecycle handlers. Exported on its own so a test drives the real implementation. */
+export const postgresSchemaHandlers = PostgresSchema.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP — same reasoning as Postgres.Database's list.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ olds, output }) =>
+    Effect.gen(function* () {
+      const name = output?.name ?? olds.name;
+      const database = output?.database ?? olds.database;
+      // A declared database that does not exist IS a schema absent. The probe runs over the
+      // FAMILY connection (no override), which points at the maintenance database a cold plan
+      // can always reach — opening the declared database instead would fail untyped
+      // (`ConnectionError` over psql, `UnknownError` 3D000 over the socket).
+      const present = yield* withPg((pg) => databaseExists(pg, database));
+      if (!present) return undefined;
+      const live = yield* withPg((pg) => readWithClient(pg, name), database);
+      if (live !== undefined && live.database !== database) {
+        return yield* Effect.fail(
+          new PostgresSchemaWrongDatabase({
+            schema: name,
+            declared: database,
+            connected: live.database,
+          }),
+        );
+      }
+      if (live !== undefined && output !== undefined) yield* assertSchemaIdentity(live, output);
+      return live === undefined ? undefined : Unowned(live);
+    }),
+
+  diff: ({ news, output, olds }) => diffPostgresSchema(news, output, olds),
+
+  reconcile: ({ news, output }) =>
+    Effect.gen(function* () {
+      const nameRefusal = schemaNameByteRefusal(news.name);
+      if (nameRefusal !== undefined) {
+        return yield* Effect.fail(
+          new PostgresSchemaNameRefused({ name: news.name, ...nameRefusal }),
+        );
+      }
+      yield* assertSchemaTarget(news, output);
+      return yield* withPg((pg) => reconcileWithClient(pg, news, output), news.database);
+    }),
+
+  delete: ({ olds, output }) =>
+    Effect.gen(function* () {
+      // Same missing-database rule as `read`: an absent database is an absent schema, and the
+      // delete stays idempotent instead of failing untyped on connect.
+      const present = yield* withPg((pg) => databaseExists(pg, olds.database));
+      if (!present) return undefined;
+      return yield* withPg((pg) => deleteWithClient(pg, olds, output), olds.database);
+    }),
+});
+
+export const PostgresSchemaProvider = () =>
+  Provider.succeed(PostgresSchema, postgresSchemaHandlers);