@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/toolset.test.ts

@@ -0,0 +1,198 @@
+/**
+ * `LiteLLM.Toolset` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-toolset-litellm.ts`): create, no-op, adopt by name, update, rename and delete.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ * ⚠️ WHAT THE FAKE MODELS IS READ FROM THE 1.103.0 SOURCE, NOT MEASURED ON A LIVE PROXY (its header).
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import {
+  type FakeToolsetLitellm,
+  startFakeToolsetLitellm,
+  toolsetRow,
+} from './fake-toolset-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMToolset } from './toolset.ts';
+import { deleteToolset } from './toolset-operations.ts';
+import type { ToolsetProps } from './toolset-types.ts';
+
+const stack = (fake: FakeToolsetLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: ToolsetProps, name = 'Web') =>
+  Effect.gen(function* () {
+    yield* LiteLLMToolset(name, props);
+  });
+
+const web: ToolsetProps = {
+  description: 'FAKE web tools',
+  tools: [
+    { serverId: 'FAKE-server-a', toolName: 'search' },
+    { serverId: 'FAKE-server-b', toolName: 'fetch' },
+  ],
+  toolsetName: 'FAKE-web',
+};
+
+test('creates a toolset with the pairs, remembers the id the proxy issued, then writes nothing', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(web))).toEqual({ Web: 'create' });
+  expect(fake.toolsets()[0]).toMatchObject({
+    description: 'FAKE web tools',
+    tools: web.tools.map((tool) => ({ server_id: tool.serverId, tool_name: tool.toolName })),
+    toolset_name: 'FAKE-web',
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(web))).toEqual({ Web: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('the list is used ONLY to adopt: with state, every read is by id and the list is never asked', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  const before = fake.requests().length;
+  await same.deploy(declare({ ...web, description: 'FAKE changed' }));
+  const paths = fake
+    .requests()
+    .slice(before)
+    .map((each) => `${each.method} ${each.path}`);
+  expect(paths).not.toContain('GET /v1/mcp/toolset');
+  expect(paths.some((path) => path.startsWith('GET /v1/mcp/toolset/FAKE-toolset-'))).toBe(true);
+});
+
+test('a changed selection is an update that sends the id and ONLY the changed field', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  const planned = await same.deploy(
+    declare({ ...web, tools: [{ serverId: 'FAKE-server-a', toolName: 'search' }] }),
+  );
+  expect(planned).toEqual({ Web: 'update' });
+  expect(fake.bodies().at(-1)).toEqual({
+    tools: [{ server_id: 'FAKE-server-a', tool_name: 'search' }],
+    toolset_id: 'FAKE-toolset-0001',
+  });
+});
+
+test('an empty selection is sent as an explicit empty list, because a null would be a no-op', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  await same.deploy(declare({ ...web, tools: [] }));
+  expect(fake.bodies().at(-1)).toMatchObject({ tools: [] });
+  expect(fake.toolsets()[0]?.['tools']).toEqual([]);
+});
+
+test('a rename is an update of the SAME row', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  expect(await same.deploy(declare({ ...web, toolsetName: 'FAKE-renamed' }))).toEqual({
+    Web: 'update',
+  });
+  expect(fake.toolsets()).toHaveLength(1);
+  expect(fake.toolsets()[0]).toMatchObject({
+    toolset_id: 'FAKE-toolset-0001',
+    toolset_name: 'FAKE-renamed',
+  });
+});
+
+test('a live row is Unowned: refused without --adopt, adopted by name with it, and a matching row writes nothing', async () => {
+  const live = toolsetRow({
+    description: 'FAKE web tools',
+    tools: [
+      { server_id: 'FAKE-server-b', tool_name: 'fetch' },
+      { server_id: 'FAKE-server-a', tool_name: 'search' },
+    ],
+    toolset_id: 'FAKE-live-1',
+    toolset_name: 'FAKE-web',
+  });
+  const fake = startFakeToolsetLitellm({ seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(web))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(web), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting a toolset with MORE tools than declared corrects it, and keeps undeclared text', async () => {
+  const wide = toolsetRow({
+    description: 'written by a person',
+    tools: [
+      { server_id: 'FAKE-server-a', tool_name: 'search' },
+      { server_id: 'FAKE-server-b', tool_name: 'fetch' },
+      { server_id: 'FAKE-server-b', tool_name: 'FAKE-extra' },
+    ],
+    toolset_id: 'FAKE-live-2',
+    toolset_name: 'FAKE-web',
+  });
+  const fake = startFakeToolsetLitellm({ seed: [wide] });
+  const { description: _kept, ...withoutDescription } = web;
+  await stack(fake).deploy(declare(withoutDescription), { adopt: true });
+  expect(fake.toolsets()[0]?.['tools']).toHaveLength(2);
+  expect(fake.toolsets()[0]?.['description']).toBe('written by a person');
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('a list that swallowed a database error cannot hide an existing name: the create fails on the 409', async () => {
+  // ⛔ measured in the source: list_mcp_toolsets answers [] on any exception
+  const live = toolsetRow({ toolset_id: 'FAKE-live-3', toolset_name: 'FAKE-web' });
+  const fake = startFakeToolsetLitellm({ listSwallowsErrors: true, seed: [live] });
+  await expect(stack(fake).deploy(declare(web))).rejects.toThrow();
+  expect(fake.toolsets()).toHaveLength(1);
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...web, toolsetName: ' ' },
+    { ...web, toolsetName: 'a/b' },
+    { ...web, description: ' ' },
+    { ...web, tools: [{ serverId: '', toolName: 'search' }] },
+    { ...web, tools: [web.tools[0], web.tools[0]] as never },
+  ]) {
+    const fake = startFakeToolsetLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the toolset', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  await same.deploy(Effect.void);
+  expect(fake.toolsets()).toHaveLength(1);
+});
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('delete answers 202 with no body, and a missing id is swallowed only because a by-id read says so', async () => {
+  const fake = startFakeToolsetLitellm({
+    seed: [toolsetRow({ toolset_id: 'FAKE-live-4', toolset_name: 'FAKE-web' })],
+  });
+  await run(fake.fetch, deleteToolset('FAKE-live-4'));
+  expect(fake.toolsets()).toEqual([]);
+  await run(fake.fetch, deleteToolset('FAKE-live-4'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the row stays', async () => {
+  const fake = startFakeToolsetLitellm({
+    forbidWrites: true,
+    seed: [toolsetRow({ toolset_id: 'FAKE-live-5', toolset_name: 'FAKE-web' })],
+  });
+  await expect(run(fake.fetch, deleteToolset('FAKE-live-5'))).rejects.toThrow();
+  expect(fake.toolsets()).toHaveLength(1);
+});

package/src/litellm/toolset.ts

@@ -0,0 +1,151 @@
+/**
+ * `LiteLLM.Toolset` — one row of LiteLLM's MCP toolset table (`/v1/mcp/toolset`): a named selection of
+ * `{ server_id, tool_name }` pairs a key or team can be granted instead of whole servers. Props and
+ * what is left out: toolset-types.ts.
+ *
+ * ★ ADOPT BY NAME. `toolset_name` is unique, so `toolsetName` finds the one live row (from the LIST,
+ *   which is the only by-name lookup the API has, and which cannot prove absence: toolset-operations.ts).
+ *   A live row with no state is `Unowned`, so it needs `--adopt`.
+ * ★ THE ID IS THE PROXY'S and is what state remembers; every later read is BY ID, from the table.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a toolset does not detach it: teams and keys that hold
+ *   its id keep a dangling grant, and every caller reaching MCP through it loses the tools.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `mcp_management_endpoints.py`'s toolset block has no
+ *   `premium_user` check (1.103.0), and docs.litellm.ai/docs/mcp_toolsets makes no Enterprise statement.
+ *   Writes need PROXY_ADMIN (403 otherwise).
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryAmbiguousError,
+  LitellmRegistryNotConvergedError,
+  LitellmRegistryUnreadableError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+import { createBody, differing, firstProblem, updateBody } from './toolset-form.ts';
+import {
+  createToolset,
+  deleteToolset,
+  listToolsets,
+  readToolset,
+  updateToolset,
+} from './toolset-operations.ts';
+import type { ToolsetAttributes, ToolsetProps } from './toolset-types.ts';
+
+export type { ToolsetAttributes, ToolsetProps };
+export type { RegistryError as ToolsetError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.Toolset';
+
+export interface LiteLLMToolset extends Resource<
+  'LiteLLM.Toolset',
+  ToolsetProps,
+  ToolsetAttributes
+> {}
+
+export const LiteLLMToolset = Resource<LiteLLMToolset>('LiteLLM.Toolset', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMToolset = (value: unknown): value is LiteLLMToolset =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Toolset';
+
+/**
+ * The live row this declaration means: BY ID from the table when state has one (a vanished row is
+ * `undefined`, never taken over by name), else by name from the list. Two rows sharing a name would
+ * mean the unique index is gone; refused, never guessed.
+ */
+const locate = (props: ToolsetProps, output: ToolsetAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output !== undefined) return yield* readToolset(output.toolsetId);
+    const named = (yield* listToolsets()).filter((row) => row.toolsetName === props.toolsetName);
+    if (named.length > 1) {
+      return yield* Effect.fail(
+        new LitellmRegistryAmbiguousError({
+          ids: named.map((row) => row.toolsetId),
+          name: props.toolsetName,
+          resource: RESOURCE,
+        }),
+      );
+    }
+    return named[0];
+  });
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const toolsetHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: ToolsetProps; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.toolsetName), firstProblem(olds));
+      }
+      const live = yield* locate(olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({ news, output }: { news: Input<ToolsetProps>; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.toolsetName), firstProblem(news));
+      if (output === undefined) return undefined;
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ news, output }: { news: ToolsetProps; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.toolsetName), firstProblem(news));
+      const before = yield* locate(news, output);
+      let toolsetId: string;
+      if (before === undefined) {
+        const created = yield* createToolset(createBody(news));
+        if (created === undefined) {
+          return yield* Effect.fail(
+            new LitellmRegistryUnreadableError({
+              reason: 'the create answered something that is not a toolset',
+              resource: RESOURCE,
+            }),
+          );
+        }
+        toolsetId = created.toolsetId;
+      } else {
+        toolsetId = before.toolsetId;
+        if (differing(before, news).length > 0) yield* updateToolset(updateBody(news, before));
+      }
+
+      // ★ BY ID FROM THE TABLE, never the list: the list is the caller-narrowed, error-swallowing view.
+      const after = yield* readToolset(toolsetId);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.toolsetName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.toolsetName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: ToolsetAttributes }) => deleteToolset(output.toolsetId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMToolsetProvider = () =>
+  Provider.effect(LiteLLMToolset, Effect.succeed(LiteLLMToolset.Provider.of(toolsetHandlers)));

package/src/ownership/ownership.test.ts

@@ -12,7 +12,7 @@ import * as Effect from 'effect/Effect';
 import { refuseTakeover } from './adopt.ts';
 import { ownedRead } from './probe.ts';
 import { noteResume, noteUnfinished, resumes } from './resume.ts';
-import { forgetRefusedCreate, isCreate, recordedInstance } from './rows.ts';
+import { forgetRefusedCreate, isCreate, olderGenerationIds, recordedInstance } from './rows.ts';
 import { row, withStore } from './store-fixture.ts';
 
 describe('recordedInstance', () => {
@@ -50,6 +50,38 @@ describe('isCreate', () => {
   });
 });
 
+describe('olderGenerationIds', () => {
+  test('collects attr.id from every generation older than the instance, through the old chain', async () => {
+    const rows = {
+      A: {
+        ...row('A', 'new', { ...row('A', 'older'), attr: { id: 'older-id' } }),
+        attr: { id: 'new-id' },
+      },
+    };
+    expect(await withStore(rows, olderGenerationIds('A', 'new'))).toEqual(['older-id']);
+  });
+
+  test('walks a former FQN the instance moved away from (renamedFrom)', async () => {
+    // Z is declared renamedFrom('X'). beta.79 moves the row (preserving instanceId) and deletes
+    // the former FQN; while a pre-move row still sits at X, the FormerFqns walk finds it and
+    // collects the older generation it holds.
+    const rows = {
+      Z: row('Z', 'new'),
+      X: {
+        ...row('X', 'new', { ...row('X', 'older'), attr: { id: 'older-id' } }),
+        attr: { id: 'new-id' },
+      },
+    };
+    expect(await withStore(rows, olderGenerationIds('Z', 'new'))).toEqual(['older-id']);
+  });
+
+  test('the current generation itself is skipped, and an empty store answers nothing', async () => {
+    const rows = { A: { ...row('A', 'new'), attr: { id: 'new-id' } } };
+    expect(await withStore(rows, olderGenerationIds('A', 'new'))).toEqual([]);
+    expect(await Effect.runPromise(olderGenerationIds('A', 'new'))).toEqual([]);
+  });
+});
+
 describe('forgetRefusedCreate', () => {
   test('drops only the creating row of this instance, with no attributes', async () => {
     const rows: Record<string, ResourceState> = {

package/src/ownership/rows.ts

@@ -99,6 +99,59 @@ export const isCreate = (fqn: string, instanceId: string): Effect.Effect<boolean
     (generation) => generation?.status === 'creating',
   );
 
+const idOf = (attr: unknown): string | undefined => {
+  if (typeof attr !== 'object' || attr === null) return undefined;
+  const id = (attr as { readonly id?: unknown }).id;
+  return typeof id === 'string' && id !== '' ? id : undefined;
+};
+
+/**
+ * `attr.id` on every generation OLDER than `instanceId` in this FQN's state chain (and a former
+ * FQN `renamedFrom` names). Walks `old` the way {@link generationOf} does, and skips the current
+ * generation itself.
+ * ⛔ THOSE IDS ARE NOT THIS GENERATION'S. A `replacing` row's reconcile runs with no attributes, so
+ *   a live row found by name can be the previous generation's own deployment. Recording that id on
+ *   the new generation makes both the same id, and `destroy()` then deletes the old generation by
+ *   it (Apply.ts, the retain check near 2168 and the provider delete that follows when the policy
+ *   is not `retain`). A same-instance `old` snapshot (an `updating` row) is not one of these.
+ */
+export const olderGenerationIds = (
+  fqn: string,
+  instanceId: string,
+): Effect.Effect<readonly string[]> =>
+  Effect.gen(function* () {
+    const found = yield* storeOf;
+    if (found === undefined) return [];
+    const ids: string[] = [];
+    for (const at of [fqn, ...(found.resources[fqn]?.FormerFqns ?? [])]) {
+      collectOlder(yield* rowAt(found.store, found.where, at), instanceId, ids);
+    }
+    return ids;
+  });
+
+/**
+ * Once `instanceId` has been seen, collect `attr.id` from generations with a DIFFERENT instance
+ * id. An `updating` row's `old` is the same instance's pre-update snapshot (Apply.ts), not a
+ * replacement generation — that snapshot's id is the row this apply is already writing.
+ */
+const collectOlder = (row: unknown, instanceId: string, ids: string[]): void => {
+  let at = row;
+  let seen = false;
+  while (typeof at === 'object' && at !== null && !isActionState(at as never)) {
+    const generation = at as Generation;
+    if (!seen) {
+      seen = generation.instanceId === instanceId;
+      at = generation.old;
+      continue;
+    }
+    if (generation.instanceId !== instanceId) {
+      const id = idOf(generation.attr);
+      if (id !== undefined) ids.push(id);
+    }
+    at = generation.old;
+  }
+};
+
 /**
  * ⛔ A REFUSED CREATE MUST NOT LEAVE A ROW THAT CLAIMS THE OBJECT IT REFUSED. Apply commits a
  *   `creating` row for this instance before it calls reconcile, and a failed reconcile leaves it

package/src/postgres/connection.ts

@@ -44,9 +44,12 @@ export interface PostgresRunnerConfig {
   readonly template?: string;
 }
 
-/** What `withPg`'s callback learns about the transport beyond the client. */
+/** What `withPg`'s callback learns about the transport beyond the client. `database` is the
+ * database the statements run IN: the family connection's, or the override `Postgres.Schema`
+ * and `Postgres.Grants` pass so they open their declared database and then prove it. */
 export interface PgContext {
   readonly template?: string;
+  readonly database: string;
 }
 
 /** The lazy connection service. Its value is an `Effect` of the config, per S24 — see the file
@@ -67,6 +70,11 @@ export const postgresRunnerConnection = (
   config: PostgresRunnerConfig,
 ): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
 
+/** Effect-scoped pool factory, like BaoGate: tests override it without process-wide module mocks. */
+export const PostgresPool = Context.Reference<typeof PgClient.layer>('homeflare/postgres/Pool', {
+  defaultValue: () => PgClient.layer,
+});
+
 const isRunner = (c: PostgresConnectionConfig | PostgresRunnerConfig): c is PostgresRunnerConfig =>
   'run' in c;
 
@@ -77,20 +85,47 @@ const isRunner = (c: PostgresConnectionConfig | PostgresRunnerConfig): c is Post
  * operation — never once per statement — so a reconcile that runs a `SELECT`, then a `CREATE`,
  * then a re-read shares one pool and closes it once, while a plan-only `read` still opens and
  * closes its own.
+ *
+ * `database` overrides which database of the SAME cluster the pool opens — the declared
+ * database of `Postgres.Schema` and `Postgres.Grants`. The family connection is pointed at a
+ * maintenance database (a brand-new database cannot be connected to on a cold plan), so those
+ * resources pass their declared database here: the runner transport swaps the `psql -d` target,
+ * the socket path swaps the pool's `database`. The swap is proven, not trusted: schema rows
+ * carry `current_database()` (`schema-sql.ts`) and grants calls the same function before writing.
  */
 export const withPg = <A, E>(
-  build: (pg: PgClient.PgClient | PgExecutor, context: PgContext) => Effect.Effect<A, E>,
+  build: (pg: PgExecutor, context: PgContext) => Effect.Effect<A, E>,
+  database?: string,
 ): Effect.Effect<A, E | SqlError, PostgresConnection> =>
   Effect.gen(function* () {
     const resolveConfig = yield* PostgresConnection;
     const config = yield* resolveConfig;
-    if (isRunner(config)) {
-      return yield* build(makePsqlExecutor(config.run, config), {
-        template: config.template ?? 'template0',
+    const target: PostgresConnectionConfig | PostgresRunnerConfig =
+      database === undefined ? config : { ...config, database };
+    if (isRunner(target)) {
+      return yield* build(makePsqlExecutor(target.run, target), {
+        template: target.template ?? 'template0',
+        database: target.database,
       });
     }
+    const pool = yield* PostgresPool;
     return yield* Effect.provide(
-      Effect.flatMap(PgClient.PgClient, (pg) => build(pg, {})),
-      PgClient.layer(config),
+      Effect.flatMap(PgClient.PgClient, (pg) =>
+        build(
+          {
+            unsafe: (sql, params) => pg.unsafe(sql, params),
+            // One reserved connection (`SqlClient.withTransaction`). A pool checkout per
+            // statement would autocommit CREATE before GRANT.
+            transaction: (statements) =>
+              pg.withTransaction(
+                Effect.gen(function* () {
+                  for (const sql of statements) yield* pg.unsafe(sql).pipe(Effect.asVoid);
+                }),
+              ),
+          },
+          { database: target.database },
+        ),
+      ),
+      pool(target),
     );
   });

package/src/postgres/database-bigint-serialization.test.ts

@@ -90,6 +90,7 @@ const wireAccuratePg = (seed?: {
         }
         throw new Error(`wireAccuratePg: unrecognised statement: ${text}`);
       }) as Effect.Effect<ReadonlyArray<A>, SqlError>,
+    transaction: () => Effect.void,
   };
 };
 

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

@@ -50,12 +50,12 @@ describe('quoting', () => {
   });
 
   test('quoteStringLiteral doubles an embedded single quote', () => {
-    expect(quoteStringLiteral("en_US.UTF-8'; DROP")).toBe("'en_US.UTF-8''; DROP'");
+    expect(quoteStringLiteral("en_US.UTF-8'; DROP")).toBe("E'en_US.UTF-8''; DROP'");
   });
 
   test('buildCreateDatabaseSql never string-concatenates an unescaped value', () => {
     const sql = buildCreateDatabaseSql({ name: 'db"1', owner: 'ro"le', encoding: "UT'F8" });
-    expect(sql).toBe('CREATE DATABASE "db""1" WITH OWNER "ro""le" ENCODING \'UT\'\'F8\'');
+    expect(sql).toBe('CREATE DATABASE "db""1" WITH OWNER "ro""le" ENCODING E\'UT\'\'F8\'');
   });
 });
 

package/src/postgres/database-sql.ts

@@ -19,23 +19,33 @@
  *   `createdb_opt_item`'s string branch is `opt_boolean_or_string → NonReservedWord_or_Sconst →
  *   NonReservedWord | Sconst`. A locale like `en_US.UTF-8` would hit the same dot-splitting
  *   `quoteIdent` avoids if it were identifier-quoted; a plain `Sconst` (`quoteStringLiteral`) has
- *   no such rule. This rests on `standard_conforming_strings = on` (the PG18 default, and
- *   measured live 2026-09-23 — `docs/postgres.md#measured`); the escaper only ever doubles `'`
- *   and never emits a backslash, so it never depends on which way that setting points.
+ *   no such rule. Use E'…' with doubled backslashes and quotes: PostgreSQL 18 lexical
+ *   section 4.1.2.2 makes escape strings independent of standard_conforming_strings.
+ *   Measured 2026-10-01: the former quote-only escaper allowed comment SQL injection when
+ *   that setting was off; an input backslash escaped the first quote of a doubled pair.
  */
 import type { SqlError } from 'effect/unstable/sql/SqlError';
 import * as Effect from 'effect/Effect';
 import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 
 /** What every function in this file needs from a client — real (`PgClient.PgClient`) or fake
- * (`fake-sql.ts`). Deliberately smaller than `SqlClient`: nothing here ever needs the tagged
- * template, transactions or streaming, because every statement is either bound params through
- * `.unsafe(text, params)` or a hand-escaped literal through `.unsafe(text)`. */
+ * (`fake-sql.ts`). Deliberately smaller than `SqlClient`: nothing here needs the tagged template
+ * or streaming. `transaction` is the exception `Postgres.Role`'s create and `Postgres.Grants`'
+ * repair share: role DDL commits per statement unless the statements share a transaction, and
+ * a grants repair's `REVOKE` must not autocommit apart from the `GRANT`s that restore it. */
 export interface PgExecutor {
   readonly unsafe: <A extends object>(
     sql: string,
     params?: ReadonlyArray<unknown>,
   ) => Effect.Effect<ReadonlyArray<A>, SqlError>;
+  /**
+   * Run `statements` in one transaction. `CREATE ROLE`, `ALTER ROLE` and `GRANT`/`REVOKE` of
+   * membership are transactional (`utility.c@REL_18_6`: those cases do not call
+   * `PreventInTransactionBlock`; `CREATE DATABASE` does). The socket client reserves one
+   * connection (`SqlClient.withTransaction`); the runner sends one `psql` script, because each
+   * `unsafe` call is its own session and would autocommit.
+   */
+  readonly transaction: (statements: readonly string[]) => Effect.Effect<void, SqlError>;
 }
 
 /** Single-token identifier quoting: wrap in `"`, double any embedded `"`. No dot-splitting —
@@ -43,9 +53,10 @@ export interface PgExecutor {
  * `NonReservedWord` too, for `OWNER` and `TABLESPACE`. */
 export const quoteIdent = (value: string): string => `"${value.replace(/"/g, '""')}"`;
 
-/** SQL string-literal quoting: wrap in `'`, double any embedded `'`. Used for every `WITH`
- * value that is locale or encoding text, never for an identifier (see the file header). */
-export const quoteStringLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+/** Escape-string quoting is safe with standard_conforming_strings either on or off.
+ * Double backslashes BEFORE quotes, so caller text cannot escape a closing delimiter. */
+export const quoteStringLiteral = (value: string): string =>
+  `E'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
 
 const withOptions = (props: PostgresDatabaseProps, template?: string): string => {
   const parts: string[] = [`OWNER ${quoteIdent(props.owner)}`];
@@ -103,6 +114,22 @@ export const roleExists = (pg: PgExecutor, role: string): Effect.Effect<boolean,
     (rows) => rows.length > 0,
   );
 
+const DATABASE_EXISTS_SQL = 'SELECT 1 AS present FROM pg_database WHERE datname = $1';
+
+/**
+ * Does one database of the cluster exist? `Postgres.Schema` runs this over the FAMILY
+ * connection (no `withPg` database override) before `read` and `delete`, so a declared
+ * database that does not exist yet answers "schema absent" instead of the transports' untyped
+ * connect failures (`ConnectionError` over psql, `UnknownError` 3D000 over the socket). The
+ * probe targets the maintenance database the family connection already points at, which a
+ * cold plan can always reach.
+ */
+export const databaseExists = (pg: PgExecutor, name: string): Effect.Effect<boolean, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly present: number }>(DATABASE_EXISTS_SQL, [name]),
+    (rows) => rows.length > 0,
+  );
+
 /** `datlocprovider` is Postgres's internal 1-byte `"char"` type, which this client decodes as
  * raw bytes rather than text (measured 2026-09-23 against the live socket — `docs/postgres.md`);
  * the `CASE` maps it to the same three words `pg_collation.h@REL_18_6#collprovider_name` returns