@homeflare/alchemy 0.42.0 → 0.43.0

package/src/litellm/fake-litellm.ts

@@ -40,6 +40,8 @@ export interface FakeLitellm {
   readonly fetch: typeof globalThis.fetch;
   readonly rows: () => readonly PassThroughGenericEndpoint[];
   readonly requests: () => readonly FakeRequest[];
+  /** `/budget/*` rows, wire-shaped (`tpm_limit`/`rpm_limit` as decimal strings, like the real table). */
+  readonly budgets: () => readonly Record<string, unknown>[];
 }
 
 const RACE_WINDOW_MS = 15;
@@ -53,11 +55,52 @@ export const startFakeLitellm = (options?: {
   readonly seed?: readonly PassThroughGenericEndpoint[];
   /** Every `DELETE` 400s `not_allowed_access`, whether or not the row exists — see the file header. */
   readonly forbidDelete?: boolean;
+  readonly budgetSeed?: readonly Record<string, unknown>[];
+  /** `/budget/update` drops `null`s instead of writing them (an `exclude_none` merge). */
+  readonly budgetExcludeNone?: boolean;
 }): FakeLitellm => {
   const masterKey = options?.masterKey ?? 'sk-test-master';
   const forbidDelete = options?.forbidDelete ?? false;
   let rows: PassThroughGenericEndpoint[] = [...(options?.seed ?? [])];
   const requests: FakeRequest[] = [];
+  let budgets: Record<string, unknown>[] = [...(options?.budgetSeed ?? [])];
+
+  /**
+   * ⚠️ Shapes from the generated 1.100.0 schema (`budget_management.ts`), not a live 1.103.0 read.
+   *   Create of an existing id is 400 (a unique-key failure); update/delete of a missing id is 400
+   *   (unmeasured, the SDK patch for these routes declares `BadRequest`).
+   */
+  const budgetRoute = async (request: Request, url: URL) => {
+    if (request.method === 'GET' && url.pathname === '/budget/list') return json(200, budgets);
+    const body = (await request.json()) as Record<string, unknown>;
+    const id = String(body['budget_id'] ?? body['id']);
+    const at = budgets.findIndex((row) => row['budget_id'] === id);
+    const wire = (fields: Record<string, unknown>) =>
+      Object.fromEntries(
+        Object.entries(fields).map(([k, v]) => [
+          k,
+          k.endsWith('_limit') && v !== null ? String(v) : v,
+        ]),
+      );
+    if (url.pathname === '/budget/new') {
+      if (at !== -1) return json(400, { detail: `budget ${id} exists` });
+      budgets = [...budgets, { created_at: 'now', updated_at: 'now', ...wire(body) }];
+      return json(200, {});
+    }
+    if (at === -1) return json(400, { detail: `budget ${id} not found` });
+    if (url.pathname === '/budget/update') {
+      const patch = options?.budgetExcludeNone
+        ? Object.fromEntries(Object.entries(body).filter(([, v]) => v !== null))
+        : body;
+      budgets = budgets.map((row, i) => (i === at ? { ...row, ...wire(patch) } : row));
+      return json(200, {});
+    }
+    if (url.pathname === '/budget/delete') {
+      budgets = budgets.filter((_, i) => i !== at);
+      return json(200, {});
+    }
+    return json(404, { detail: 'not found' });
+  };
 
   const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
     const request =
@@ -66,6 +109,7 @@ export const startFakeLitellm = (options?: {
     requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
     const auth = request.headers.get('authorization');
     if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
+    if (url.pathname.startsWith('/budget/')) return budgetRoute(request, url);
     if (
       url.pathname !== '/config/pass_through_endpoint' &&
       !url.pathname.startsWith('/config/pass_through_endpoint/')
@@ -117,5 +161,10 @@ export const startFakeLitellm = (options?: {
     return json(405, { detail: `unhandled ${request.method} ${url.pathname}` });
   }) as typeof globalThis.fetch;
 
-  return { fetch, requests: () => [...requests], rows: () => [...rows] };
+  return {
+    budgets: () => [...budgets],
+    fetch,
+    requests: () => [...requests],
+    rows: () => [...rows],
+  };
 };

package/src/litellm/index.ts

@@ -25,4 +25,17 @@ export {
   type PassThroughEndpointError,
   type PassThroughEndpointProps,
 } from './pass-through-endpoint.ts';
+export {
+  LiteLLMBudget,
+  LiteLLMBudgetProvider,
+  isLiteLLMBudget,
+  type BudgetAttributes,
+  type BudgetError,
+  type BudgetProps,
+} from './budget.ts';
+export {
+  LitellmBudgetFieldNotClearedError,
+  LitellmBudgetHardCapUnjustifiedError,
+  LitellmBudgetUnreadableError,
+} from './budget-errors.ts';
 export { litellmProviders } from './providers.ts';

package/src/litellm/operations.ts

@@ -77,7 +77,7 @@ const semaphoreFor = (baseUrl: string): Effect.Effect<Semaphore.Semaphore> =>
  *   `Fetch` service still wins inside that client, which is how the fake proxy stays the test
  *   transport.
  */
-const throughFetch = <A, E, R>(io: Effect.Effect<A, E, R>) =>
+export const throughFetch = <A, E, R>(io: Effect.Effect<A, E, R>) =>
   io.pipe(Effect.provide(FetchHttpClient.layer));
 
 const mutate = <A, E>(

package/src/litellm/providers.ts

@@ -20,7 +20,10 @@
  */
 import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/Credentials';
 import * as Layer from 'effect/Layer';
+import { LiteLLMBudgetProvider } from './budget.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
 export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFromEnv) =>
-  LiteLLMPassThroughEndpointProvider().pipe(Layer.provideMerge(creds));
+  Layer.mergeAll(LiteLLMPassThroughEndpointProvider(), LiteLLMBudgetProvider()).pipe(
+    Layer.provideMerge(creds),
+  );

package/src/openbao/auth-role-form.test.ts

@@ -43,3 +43,40 @@ describe('auth role secret_id TTL', () => {
     expect(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS)).toBe(false);
   });
 });
+
+describe('auth role token_period', () => {
+  const LIVE = {
+    bind_secret_id: true,
+    secret_id_num_uses: 0,
+    secret_id_ttl: 7776000,
+    token_max_ttl: 3600,
+    token_period: 0,
+    token_policies: ['default', 'host-cert'],
+    token_ttl: 900,
+  };
+
+  it('omits token_period from the SDK write when the prop is unset', async () => {
+    expect((await Effect.runPromise(authRoleRequest(PROPS))).token_period).toBeUndefined();
+  });
+
+  it('writes 24h as the equivalent SDK seconds, never legacy period', async () => {
+    const props = { ...PROPS, tokenPeriod: '24h' };
+    const request = await Effect.runPromise(authRoleRequest(props));
+    expect(request.token_period).toBe(86400);
+    expect(request).not.toHaveProperty('period');
+  });
+
+  it('reads a live token_period back and matches an equivalent declaration', () => {
+    const props = { ...PROPS, tokenPeriod: '24h' };
+    const attributes = attributesOf(props, { ...LIVE, token_period: 86400 });
+    expect(attributes.tokenPeriod).toBe('1d');
+    expect(matches(attributes, props)).toBe(true);
+    expect(matches(attributesOf(props, { ...LIVE, token_period: 3600 }), props)).toBe(false);
+  });
+
+  it('leaves an unmanaged live token_period out of drift when the prop is unset', () => {
+    const attributes = attributesOf(PROPS, { ...LIVE, token_period: 86400 });
+    expect(attributes.tokenPeriod).toBe('1d');
+    expect(matches(attributes, PROPS)).toBe(true);
+  });
+});

package/src/openbao/auth-role-form.ts

@@ -16,6 +16,14 @@ export interface BaoAuthRoleProps {
   bindSecretId?: boolean;
   /** `0` means unlimited uses — the shape reconcile.sh writes for headless roles. */
   secretIdNumUses?: number;
+  /**
+   * Token period, e.g. `24h` — set only for a periodic (forever-renewable) role, where
+   * `tokenTtl`/`tokenMaxTtl` are conventionally `'0'`. Omitted means this declaration does not
+   * manage the field: a live role's `token_period` (however it got set) is left untouched, the
+   * same way an omitted `bindSecretId` is. See house `openbao/approles.ts` for the role this
+   * unblocks — a periodic agent token that was inexpressible with these props.
+   */
+  tokenPeriod?: string;
 }
 
 export interface BaoAuthRoleAttributes {
@@ -26,6 +34,7 @@ export interface BaoAuthRoleAttributes {
   secretIdTtl: string;
   bindSecretId: boolean;
   secretIdNumUses: number;
+  tokenPeriod: string;
   /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
   digest: string;
 }
@@ -64,6 +73,7 @@ export const attributesOf = (
     secretIdTtl: ttlText(ttlSeconds(live['secret_id_ttl']), '0'),
     bindSecretId: bool(live['bind_secret_id'], true),
     secretIdNumUses: int(live['secret_id_num_uses'], 0),
+    tokenPeriod: ttlText(ttlSeconds(live['token_period']), '0'),
   };
   return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
 };
@@ -88,6 +98,7 @@ export const matches = (attributes: BaoAuthRoleAttributes, props: BaoAuthRolePro
     sameTtl(props.tokenMaxTtl, attributes.tokenMaxTtl) &&
     sameTtl(props.secretIdTtl, attributes.secretIdTtl) &&
     (props.bindSecretId === undefined || attributes.bindSecretId === props.bindSecretId) &&
-    (props.secretIdNumUses === undefined || attributes.secretIdNumUses === props.secretIdNumUses)
+    (props.secretIdNumUses === undefined || attributes.secretIdNumUses === props.secretIdNumUses) &&
+    (props.tokenPeriod === undefined || sameTtl(props.tokenPeriod, attributes.tokenPeriod))
   );
 };

package/src/openbao/auth-role-wire.test.ts

@@ -16,6 +16,7 @@ const DATA = {
   secret_id_num_uses: 0,
   secret_id_ttl: 7776000,
   token_max_ttl: 3600,
+  token_period: 0,
   token_policies: ['host-cert'],
   token_ttl: 900,
 };

package/src/openbao/auth-role-wire.ts

@@ -35,6 +35,7 @@ const completeRole = (live: AppRoleReadRoleResponse): boolean =>
   seconds(live.secret_id_ttl) &&
   seconds(live.token_ttl) &&
   seconds(live.token_max_ttl) &&
+  seconds(live.token_period) &&
   Array.isArray(live.token_policies) &&
   live.token_policies.every((policy) => typeof policy === 'string');
 
@@ -56,7 +57,14 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
     const tokenTtl = parseDuration(props.tokenTtl);
     const tokenMaxTtl = parseDuration(props.tokenMaxTtl);
     const secretIdTtl = parseDuration(props.secretIdTtl);
-    if (!seconds(tokenTtl) || !seconds(tokenMaxTtl) || !seconds(secretIdTtl)) {
+    const tokenPeriod =
+      props.tokenPeriod === undefined ? undefined : parseDuration(props.tokenPeriod);
+    if (
+      !seconds(tokenTtl) ||
+      !seconds(tokenMaxTtl) ||
+      !seconds(secretIdTtl) ||
+      (props.tokenPeriod !== undefined && !seconds(tokenPeriod))
+    ) {
       return yield* Effect.fail(
         new BaoError(0, 'POST', readPath(props.name), ['invalid role TTL duration']),
       );
@@ -64,6 +72,9 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
     // ★ The former CLI-style body used strings for every k=v. The SDK schema uses seconds,
     // booleans and arrays; omitted knobs stay omitted on update.
     // pathRoleCreateUpdate preserves absent bind_secret_id/secret_id_num_uses on existing roles.
+    // ⛔ token_period, not period — the vendor doc on both fields says period is legacy and loses
+    // to token_period when both are set (approle.ts AppRoleWriteRoleRequest); this Resource only
+    // ever emits the modern field.
     const request: AppRoleWriteRoleRequest = {
       ...identity(props.name),
       token_policies: [...props.tokenPolicies],
@@ -72,6 +83,7 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
       secret_id_ttl: secretIdTtl,
       ...(props.bindSecretId === undefined ? {} : { bind_secret_id: props.bindSecretId }),
       ...(props.secretIdNumUses === undefined ? {} : { secret_id_num_uses: props.secretIdNumUses }),
+      ...(tokenPeriod === undefined ? {} : { token_period: tokenPeriod }),
     };
     return request;
   });

package/src/openbao/distilled-retry.test.ts

@@ -25,6 +25,7 @@ const ROLE = {
   secret_id_num_uses: 0,
   secret_id_ttl: 0,
   token_max_ttl: 3600,
+  token_period: 0,
   token_policies: ['default'],
   token_ttl: 900,
 };

package/src/openbao/fake-engines-roles.ts

@@ -57,7 +57,13 @@ export const wireRoles = (): Store =>
   store<Stored>(
     (path, body, before) =>
       path.startsWith('auth/approle/role/')
-        ? { bind_secret_id: true, secret_id_num_uses: 0, ...before, ...typed(body) }
+        ? {
+            bind_secret_id: true,
+            secret_id_num_uses: 0,
+            token_period: 0,
+            ...before,
+            ...typed(body),
+          }
         : typed(body),
     (path) => keyOf(path),
   );

package/src/postgres/connection.ts

@@ -18,6 +18,8 @@ import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
 
 /** What a stack passes to reach one cluster. `host` may be a socket directory (one beginning
  * with `/` expands to `${host}/.s.PGSQL.${port}` — measured in
@@ -31,11 +33,27 @@ export interface PostgresConnectionConfig {
   readonly ssl?: boolean;
 }
 
+/** The runner transport (`psql-executor.ts`): SQL goes through `run` instead of a socket, for a
+ * host whose Postgres is reachable only by a command (CT100: ssh + `podman exec`). `template`
+ * is the `CREATE DATABASE` template — `template0` by default, because CT100's `template1` is
+ * ParadeDB's and would copy postgis/pg_ivm/paradedb objects into every new database. */
+export interface PostgresRunnerConfig {
+  readonly run: PsqlRunner;
+  readonly database: string;
+  readonly username: string;
+  readonly template?: string;
+}
+
+/** What `withPg`'s callback learns about the transport beyond the client. */
+export interface PgContext {
+  readonly template?: string;
+}
+
 /** The lazy connection service. Its value is an `Effect` of the config, per S24 — see the file
  * header for why. */
 export class PostgresConnection extends Context.Service<
   PostgresConnection,
-  Effect.Effect<PostgresConnectionConfig>
+  Effect.Effect<PostgresConnectionConfig | PostgresRunnerConfig>
 >()('Postgres.Connection') {}
 
 /** A stack's one-line way to provide a cluster: `Layer.provide(postgresConnection({ … }))` on
@@ -44,6 +62,14 @@ export const postgresConnection = (
   config: PostgresConnectionConfig,
 ): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
 
+/** A stack's one-line way to provide a cluster reached through a command runner. */
+export const postgresRunnerConnection = (
+  config: PostgresRunnerConfig,
+): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
+
+const isRunner = (c: PostgresConnectionConfig | PostgresRunnerConfig): c is PostgresRunnerConfig =>
+  'run' in c;
+
 /**
  * Run one operation against a freshly built, freshly closed connection pool.
  *
@@ -53,10 +79,18 @@ export const postgresConnection = (
  * closes its own.
  */
 export const withPg = <A, E>(
-  build: (pg: PgClient.PgClient) => Effect.Effect<A, E>,
+  build: (pg: PgClient.PgClient | PgExecutor, context: PgContext) => Effect.Effect<A, E>,
 ): Effect.Effect<A, E | SqlError, PostgresConnection> =>
   Effect.gen(function* () {
     const resolveConfig = yield* PostgresConnection;
     const config = yield* resolveConfig;
-    return yield* Effect.provide(Effect.flatMap(PgClient.PgClient, build), PgClient.layer(config));
+    if (isRunner(config)) {
+      return yield* build(makePsqlExecutor(config.run, config), {
+        template: config.template ?? 'template0',
+      });
+    }
+    return yield* Effect.provide(
+      Effect.flatMap(PgClient.PgClient, (pg) => build(pg, {})),
+      PgClient.layer(config),
+    );
   });

package/src/postgres/database-sql.ts

@@ -47,8 +47,9 @@ export const quoteIdent = (value: string): string => `"${value.replace(/"/g, '""
  * value that is locale or encoding text, never for an identifier (see the file header). */
 export const quoteStringLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
 
-const withOptions = (props: PostgresDatabaseProps): string => {
+const withOptions = (props: PostgresDatabaseProps, template?: string): string => {
   const parts: string[] = [`OWNER ${quoteIdent(props.owner)}`];
+  if (template !== undefined) parts.push(`TEMPLATE ${quoteIdent(template)}`);
   if (props.encoding !== undefined) parts.push(`ENCODING ${quoteStringLiteral(props.encoding)}`);
   if (props.localeProvider !== undefined) {
     parts.push(`LOCALE_PROVIDER ${quoteStringLiteral(props.localeProvider)}`);
@@ -74,8 +75,8 @@ const withOptions = (props: PostgresDatabaseProps): string => {
  * `Math.trunc`ed and stringified, and a boolean is one of exactly two literal words this file
  * writes, so no declared value reaches the statement through string interpolation unescaped.
  */
-export const buildCreateDatabaseSql = (props: PostgresDatabaseProps): string =>
-  `CREATE DATABASE ${quoteIdent(props.name)} WITH ${withOptions(props)}`;
+export const buildCreateDatabaseSql = (props: PostgresDatabaseProps, template?: string): string =>
+  `CREATE DATABASE ${quoteIdent(props.name)} WITH ${withOptions(props, template)}`;
 
 /** `42P04` (`duplicate_database`) is a race: something else created the name between our read
  * and our create. Measured at `internal/sqlError.ts@effect/sql-pg 4.0.0-rc.115`: every SQLSTATE

package/src/postgres/database.ts

@@ -80,6 +80,7 @@ const liveDrift = (props: PostgresDatabaseProps, live: PostgresDatabaseAttribute
 export const reconcileWithClient = (
   pg: PgExecutor,
   props: PostgresDatabaseProps,
+  template?: string,
 ): Effect.Effect<
   PostgresDatabaseAttributes,
   PostgresDatabaseOwnerMissing | PostgresDatabaseDrift | PostgresDatabaseCreateVanished | SqlError
@@ -93,7 +94,7 @@ export const reconcileWithClient = (
           new PostgresDatabaseOwnerMissing({ database: props.name, owner: props.owner }),
         );
       }
-      yield* pg.unsafe(buildCreateDatabaseSql(props)).pipe(
+      yield* pg.unsafe(buildCreateDatabaseSql(props, template)).pipe(
         Effect.asVoid,
         Effect.catchTag('SqlError', (error) =>
           isDuplicateDatabaseRace(error) ? Effect.succeed(undefined) : Effect.fail(error),
@@ -183,7 +184,7 @@ export const postgresDatabaseHandlers = PostgresDatabase.Provider.of({
           new PostgresDatabaseNameRefused({ name: news.name, ...nameRefusal }),
         );
       }
-      return yield* withPg((pg) => reconcileWithClient(pg, news));
+      return yield* withPg((pg, ctx) => reconcileWithClient(pg, news, ctx.template));
     }),
 
   delete: ({ olds }) => Effect.fail(new PostgresDatabaseDropRefused({ database: olds.name })),

package/src/postgres/index.ts

@@ -5,8 +5,15 @@
  * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` is a
  *   test double, not something a consuming stack should import.
  */
-export type { PostgresConnectionConfig } from './connection.ts';
-export { PostgresConnection, postgresConnection, withPg } from './connection.ts';
+export type { PostgresConnectionConfig, PostgresRunnerConfig } from './connection.ts';
+export {
+  PostgresConnection,
+  postgresConnection,
+  postgresRunnerConnection,
+  withPg,
+} from './connection.ts';
+export type { PsqlResult, PsqlRunner } from './psql-executor.ts';
+export { inlineParams, makePsqlExecutor } from './psql-executor.ts';
 export type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 export { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
 export {
@@ -27,4 +34,4 @@ export {
   PostgresDatabaseRenameRefused,
   type PostgresDatabaseError,
 } from './errors.ts';
-export { postgresProviders } from './providers.ts';
+export { postgresProviders, postgresRunnerProviders } from './providers.ts';

package/src/postgres/providers.ts

@@ -9,8 +9,21 @@
  *   the results under whatever logical grouping it wants.
  */
 import * as Layer from 'effect/Layer';
-import { type PostgresConnectionConfig, postgresConnection } from './connection.ts';
+import {
+  type PostgresConnectionConfig,
+  type PostgresRunnerConfig,
+  postgresConnection,
+  postgresRunnerConnection,
+} from './connection.ts';
 import { PostgresDatabaseProvider } from './database.ts';
 
+// ⚠️ `Layer.provideMerge`, NEVER plain `Layer.provide`: the handlers' `withPg` reads
+//   `PostgresConnection` when the ENGINE later calls `read`/`reconcile`, and plain `provide`
+//   seals it away ("Service not found: Postgres.Connection" — measured for `caddyProviders`,
+//   see `caddy/providers.ts`).
 export const postgresProviders = (config: PostgresConnectionConfig) =>
-  PostgresDatabaseProvider().pipe(Layer.provide(postgresConnection(config)));
+  PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresConnection(config)));
+
+/** The same provider over a command runner (`psql-executor.ts`) — for a loopback-only cluster. */
+export const postgresRunnerProviders = (config: PostgresRunnerConfig) =>
+  PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config)));

package/src/postgres/psql-executor.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { postgresRunnerProviders } from './providers.ts';
+import { postgresRunnerConnection, withPg } from './connection.ts';
+import { reconcileWithClient } from './database.ts';
+import { buildCreateDatabaseSql, isDuplicateDatabaseRace } from './database-sql.ts';
+import { type PsqlRunner, inlineParams, makePsqlExecutor } from './psql-executor.ts';
+
+const target = { database: 'postgres', username: 'postgres' };
+const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
+
+describe('psql executor', () => {
+  test('inlines string params as literals and refuses non-strings', () => {
+    expect(inlineParams('SELECT $1, $2', ["it's", 'b'])).toBe("SELECT 'it''s', 'b'");
+    expect(() => inlineParams('SELECT $1', [5])).toThrow('must be a string');
+  });
+
+  test('a SELECT is wrapped in json_agg and parsed to rows', async () => {
+    const calls: { argv: readonly string[]; stdin: string }[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call);
+      return ok('[{"oid":"16400","name":"x"}]\n');
+    };
+    const rows = await Effect.runPromise(
+      makePsqlExecutor(run, target).unsafe('SELECT 1 FROM pg_database WHERE datname = $1', ['x']),
+    );
+    expect(rows).toEqual([{ oid: 16400, name: 'x' }]);
+    expect(calls[0]?.argv.slice(0, 1)).toEqual(['psql']);
+    expect(calls[0]?.stdin).toContain('json_agg');
+    expect(calls[0]?.stdin).toContain("datname = 'x'");
+  });
+
+  test('a duplicate-database failure stays recognisable as the 42P04 race', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({
+        code: 3,
+        stdout: '',
+        stderr: 'ERROR:  42P04: database "x" already exists\n',
+      });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('CREATE DATABASE "x"')),
+    );
+    expect(isDuplicateDatabaseRace(error)).toBe(true);
+  });
+
+  test('a runner that never reached psql is a ConnectionError', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({ code: 255, stdout: '', stderr: 'ssh: refused' });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('SELECT 1')),
+    );
+    expect(error.reason._tag).toBe('ConnectionError');
+  });
+});
+
+describe('runner transport through withPg', () => {
+  test('create uses template0 by default and the same adopt path on an existing row', async () => {
+    const stdins: string[] = [];
+    const row = {
+      oid: 1,
+      name: 'lite',
+      owner: 'litellm',
+      encoding: 'UTF8',
+      localeProvider: 'libc',
+      collate: 'C',
+      ctype: 'C',
+      allowConnections: true,
+      connectionLimit: -1,
+      isTemplate: false,
+      tablespace: 'pg_default',
+    };
+    let created = false;
+    const run: PsqlRunner = ({ stdin }) => {
+      stdins.push(stdin);
+      if (stdin.includes('pg_roles')) return ok('[{"present":1}]');
+      if (stdin.includes('FROM pg_database')) return ok(created ? JSON.stringify([row]) : '[]');
+      if (stdin.startsWith('CREATE DATABASE')) created = true;
+      return ok('');
+    };
+    const layer = postgresRunnerConnection({ run, ...target });
+    const props = { name: 'lite', owner: 'litellm' };
+    const attrs = await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(attrs.name).toBe('lite');
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toBe(
+      `${buildCreateDatabaseSql(props, 'template0')};`,
+    );
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toContain('TEMPLATE "template0"');
+    const before = stdins.length;
+    await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(stdins.slice(before).some((s) => s.startsWith('CREATE DATABASE'))).toBe(false);
+  });
+
+  test("postgresRunnerProviders keeps the connection live for the engine's later handler calls", async () => {
+    const run: PsqlRunner = () => ok('[]');
+    const rows = await Effect.runPromise(
+      withPg((pg) => pg.unsafe('SELECT 1')).pipe(
+        Effect.provide(postgresRunnerProviders({ run, ...target })),
+      ),
+    );
+    expect(rows).toEqual([]);
+  });
+});