@homeflare/alchemy 0.41.0 → 0.43.0

package/src/litellm/budget.test.ts

@@ -0,0 +1,105 @@
+/**
+ * `LiteLLM.Budget` through Alchemy's real Plan and Apply over the fake proxy.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, startFakeLitellm } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { type BudgetProps, LiteLLMBudget } from './budget.ts';
+import { differing, isHardCapUnjustified, toAttributes } from './budget-form.ts';
+
+const KEY = 'sk-test-master';
+const stack = (fake: ReturnType<typeof startFakeLitellm>) =>
+  fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: BudgetProps, name = 'Tier') =>
+  Effect.gen(function* () {
+    yield* LiteLLMBudget(name, props);
+  });
+
+const tier = {
+  budget_id: 'hf-tier-agent',
+  budget_duration: '1d',
+  created_at: 'x',
+  max_budget: 2,
+  rpm_limit: '60',
+  soft_budget: null,
+  tpm_limit: null,
+  updated_at: 'x',
+};
+
+test('creates a soft-only budget and sends no max_budget', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  const planned = await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-x', budgetDuration: '1d', softBudget: 50 }),
+  );
+  expect(planned).toEqual({ Tier: 'create' });
+  expect(fake.budgets()[0]).toMatchObject({ budget_id: 'hf-tier-x', soft_budget: 50 });
+  expect(fake.budgets()[0]).not.toHaveProperty('max_budget');
+});
+
+test('a second deploy of the same declaration writes nothing', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  const props = { budgetId: 'hf-tier-x', softBudget: 50, rpmLimit: 60 };
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Tier: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a hard cap without a reason is refused before any write', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  await expect(
+    stack(fake).deploy(declare({ budgetId: 'hf-tier-x', maxBudget: 60 })),
+  ).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(isHardCapUnjustified({ maxBudget: 1, maxBudgetReason: ' ' })).toBe(true);
+  expect(isHardCapUnjustified({ maxBudget: 1, maxBudgetReason: 'abuse guard' })).toBe(false);
+});
+
+test('a hard cap with a reason is written', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-x', maxBudget: 5, maxBudgetReason: 'public voice endpoint' }),
+  );
+  expect(fake.budgets()[0]).toMatchObject({ max_budget: 5 });
+});
+
+test('a live row is Unowned: refused without --adopt, taken with it', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier] });
+  const props = {
+    budgetId: 'hf-tier-agent',
+    budgetDuration: '1d',
+    maxBudget: 2,
+    maxBudgetReason: 'measured live',
+  };
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(props))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  const planned = await engine.deploy(declare({ ...props, rpmLimit: 60 }), { adopt: true });
+  expect(Object.values(planned)).toEqual(['adopted']);
+});
+
+test('adopting a hard tier and declaring it soft clears max_budget', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier] });
+  await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-agent', budgetDuration: '1d', rpmLimit: 60, softBudget: 2 }),
+    { adopt: true },
+  );
+  expect(fake.budgets()[0]).toMatchObject({ max_budget: null, soft_budget: 2 });
+});
+
+test('a proxy that cannot clear a limit fails the apply instead of claiming success', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier], budgetExcludeNone: true });
+  await expect(
+    stack(fake).deploy(declare({ budgetId: 'hf-tier-agent', budgetDuration: '1d', rpmLimit: 60 }), {
+      adopt: true,
+    }),
+  ).rejects.toThrow();
+});
+
+test('form helpers: string limits become numbers, and differences are named', () => {
+  const live = toAttributes(tier);
+  expect(live.rpmLimit).toBe(60);
+  expect(differing(live, { budgetDuration: '1d', rpmLimit: 60 })).toEqual(['max_budget']);
+});

package/src/litellm/budget.ts

@@ -0,0 +1,127 @@
+/**
+ * `LiteLLM.Budget` — one row of LiteLLM's `LiteLLM_BudgetTable` (`/budget/*`), the "tier" keys and
+ * teams bind to (`hf-tier-*`).
+ *
+ * ★ MONITORING, NOT LIMITS (Tim, 2026-09-28): `softBudget` is the prop; `maxBudget` is a hard cap
+ *   that 429s every caller and is refused without `maxBudgetReason` (budget-form.ts).
+ * ★ ADOPT BY id. `budgetId` names the live row; without it a deterministic physical name is used.
+ *   A foreign row with that id is `Unowned`, so it needs `--adopt`.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a budget row that keys still reference either
+ *   fails or detaches them, and a detached key loses its rate limits. Opt in with
+ *   `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ CLEARING A LIMIT: sent as an explicit `null`. If this LiteLLM merges with `exclude_none` the
+ *   row keeps the old value; reconcile reads back and FAILS (`LitellmBudgetFieldNotClearedError`)
+ *   rather than report a cleared cap. Unmeasured against a live proxy at 1.103.0.
+ * ⛔ NO 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 { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import {
+  LitellmBudgetFieldNotClearedError,
+  LitellmBudgetHardCapUnjustifiedError,
+} from './budget-errors.ts';
+import {
+  type BudgetAttributes,
+  type BudgetProps,
+  createBody,
+  differing,
+  isHardCapUnjustified,
+  updateBody,
+} from './budget-form.ts';
+import { createBudget, deleteBudget, listBudgets, updateBudget } from './budget-operations.ts';
+
+export type { BudgetAttributes, BudgetProps };
+export type { BudgetError } from './budget-errors.ts';
+
+export interface LiteLLMBudget extends Resource<'LiteLLM.Budget', BudgetProps, BudgetAttributes> {}
+
+export const LiteLLMBudget = Resource<LiteLLMBudget>('LiteLLM.Budget', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMBudget = (value: unknown): value is LiteLLMBudget =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Budget';
+
+const refuseUnjustifiedCap = (props: BudgetProps) =>
+  isHardCapUnjustified(props)
+    ? Effect.fail(new LitellmBudgetHardCapUnjustifiedError({ budgetId: props.budgetId }))
+    : Effect.void;
+
+const idOf = (
+  id: string,
+  instanceId: string,
+  props: BudgetProps,
+  output: BudgetAttributes | undefined,
+) =>
+  output?.budgetId !== undefined
+    ? Effect.succeed(output.budgetId)
+    : props.budgetId !== undefined
+      ? Effect.succeed(props.budgetId)
+      : createPhysicalName({ id, instanceId, lowercase: true, maxLength: 64 });
+
+type Args<P> = {
+  id: string;
+  instanceId: string;
+  output: BudgetAttributes | undefined;
+} & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const budgetHandlers = {
+  read: ({ id, instanceId, olds, output }: Args<{ olds: BudgetProps }>) =>
+    Effect.gen(function* () {
+      const budgetId = yield* idOf(id, instanceId, olds, output);
+      const live = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({ news, output }: { news: Input<BudgetProps>; output: BudgetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuseUnjustifiedCap(news);
+      if (output === undefined) return undefined;
+      // The id is identity: a different declared id is a different row.
+      if (news.budgetId !== undefined && news.budgetId !== output.budgetId) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ id, instanceId, news, output }: Args<{ news: BudgetProps }>) =>
+    Effect.gen(function* () {
+      yield* refuseUnjustifiedCap(news);
+      const budgetId = yield* idOf(id, instanceId, news, output);
+      const before = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (before === undefined) yield* createBudget(createBody(news, budgetId));
+      else if (differing(before, news).length > 0) yield* updateBudget(updateBody(news, before));
+
+      const after = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (after === undefined) {
+        return yield* Effect.die(
+          new Error(`LiteLLM.Budget ${budgetId}: write returned no error but the row is absent.`),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmBudgetFieldNotClearedError({ budgetId, fields: left }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: BudgetAttributes }) => deleteBudget(output.budgetId),
+
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMBudgetProvider = () =>
+  Provider.effect(LiteLLMBudget, Effect.succeed(LiteLLMBudget.Provider.of(budgetHandlers)));

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';