@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/key-errors.ts

@@ -0,0 +1,241 @@
+/**
+ * The typed refusals `LiteLLM.Key` raises on top of `@distilled.cloud/litellm`'s own SDK errors.
+ *
+ * ⛔ NOT ONE OF THESE CARRIES A KEY VALUE. They name the alias, the environment VARIABLE and the
+ *   rule broken, never what the variable held: an error is logged, retried and pasted into a PR.
+ *   The SDK's own errors are the other half: `generateKey` (key-operations.ts) turns the one that
+ *   holds the request, and so the value, into `LitellmKeyTransportError` below.
+ */
+import type * as keys from '@distilled.cloud/litellm/key_management';
+import * as Data from 'effect/Data';
+import type { HttpClientErrorReason } from 'effect/unstable/http/HttpClientError';
+import type {
+  LitellmKeyCallbackMetadataDeclaredError,
+  LitellmKeyCallbackMetadataLiveError,
+} from './key-metadata-errors.ts';
+
+/** A create is needed and the declaration names no `key` — LiteLLM would mint a value nobody holds. */
+export class LitellmKeyValueRequiredError extends Data.TaggedError('LitellmKeyValueRequiredError')<{
+  readonly keyAlias: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}' does not exist and declares no \`key\`. Creating it would ` +
+      'mint a value nobody holds. Declare `key: { fromEnv: "NAME" }`, or adopt an existing key.'
+    );
+  }
+}
+
+/**
+ * distilled prints request and response BODIES to stderr while `DISTILLED_DEBUG_HTTP` is set, and
+ * `/key/generate` carries the key in both. Refused before any request, as `fetchMeshNodeToken` does.
+ */
+export class LitellmKeyDebugLoggingError extends Data.TaggedError('LitellmKeyDebugLoggingError')<{
+  readonly keyAlias: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': DISTILLED_DEBUG_HTTP is set, so the SDK would print the ` +
+      "key to stderr in /key/generate's request and response. Unset it and run again. Nothing was written."
+    );
+  }
+}
+
+/**
+ * `/key/generate` failed on the wire (or its answer could not be read), so nobody knows whether the
+ * key exists.
+ *
+ * ⛔ THIS IS WHAT STANDS IN FOR AN `HttpClientError`, WHICH CARRIES ITS REQUEST, AND THE REQUEST BODY
+ *   OF `/key/generate` IS `{"key":"sk-…"}`. Measured 2026-09-29 with a synthetic value: on a dropped
+ *   connection `JSON.stringify(error)`, `Bun.inspect(error, { depth: 10 })` and Effect's JSON logger
+ *   all printed the key, and so did the failure of a deploy over it. A defect from reading a broken
+ *   answer (`protocol-rest.ts` reads it with `Effect.orDie`) carries the same request. So `reason` is
+ *   the `HttpClientError` reason's TAG (a string) and nothing else is kept: no request, no cause, no
+ *   description (a cause is free text from `fetch`).
+ */
+export class LitellmKeyTransportError extends Data.TaggedError('LitellmKeyTransportError')<{
+  readonly keyAlias: string;
+  readonly reason: HttpClientErrorReason['_tag'] | 'Defect';
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the /key/generate request failed (${this.reason}) before an ` +
+      'answer could be read, so the key MAY have been created. This error keeps neither the request ' +
+      "nor its cause: the request body holds the key's value. Look for the alias in LiteLLM. A key " +
+      'that landed is taken over by the next deploy with --adopt; one that did not is created by it.'
+    );
+  }
+}
+
+/** An empty alias: `/key/list` would read `key_alias=` as no filter, and nothing could find the key again. */
+export class LitellmKeyAliasEmptyError extends Data.TaggedError('LitellmKeyAliasEmptyError')<{}> {
+  override get message(): string {
+    return "LiteLLM.Key: keyAlias is empty. The alias is the key's identity. Nothing was written.";
+  }
+}
+
+/** `key: { fromEnv }` names a variable the deploying process does not have (or has empty). */
+export class LitellmKeyValueMissingError extends Data.TaggedError('LitellmKeyValueMissingError')<{
+  readonly keyAlias: string;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the environment variable ${this.variable} is unset or empty ` +
+      'in the deploying process. Nothing was written.'
+    );
+  }
+}
+
+/** The variable's value breaks the rule `/key/generate` states for a user-defined key. */
+export class LitellmKeyValueMalformedError extends Data.TaggedError(
+  'LitellmKeyValueMalformedError',
+)<{
+  readonly keyAlias: string;
+  readonly variable: string;
+  readonly rule: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the value of ${this.variable} is not usable — ${this.rule}. ` +
+      'Nothing was written.'
+    );
+  }
+}
+
+/**
+ * `/key/generate` answered with a different value than the one sent, so the row exists under a
+ * key nobody holds. `removed` says whether the row was deleted again on the way out.
+ */
+export class LitellmKeyValueNotHonouredError extends Data.TaggedError(
+  'LitellmKeyValueNotHonouredError',
+)<{
+  readonly keyAlias: string;
+  readonly removed: boolean;
+}> {
+  override get message(): string {
+    const outcome = this.removed
+      ? 'The row was deleted again.'
+      : 'The row could NOT be deleted again: remove it by hand.';
+    return (
+      `LiteLLM.Key '${this.keyAlias}': /key/generate answered with a different value than the one ` +
+      `sent, so the key would authenticate nobody. ${outcome}`
+    );
+  }
+}
+
+/**
+ * An ADOPTED key was declared with a `key` whose value is not the key the live row holds. The
+ * value is compared only as a sha256 in memory against the row's `token` (`hash_token`, the
+ * vendor's own store) — never in state, never in an error — and a mismatch is refused, because a
+ * seat that reads the same variable would hold a key that authenticates nothing while the plan
+ * reported success. `/key/update` cannot change a key's value (`prepare_key_update_data` pops
+ * `key`), so there is nothing to write: the operator must fix the variable or drop the `key`.
+ */
+export class LitellmKeyValueMismatchError extends Data.TaggedError('LitellmKeyValueMismatchError')<{
+  readonly keyAlias: string;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the value of ${this.variable} is not the key this alias ` +
+      'holds. Nothing was written. /key/update cannot change a key value, so fix the variable or ' +
+      'drop the `key` and manage the existing key without one.'
+    );
+  }
+}
+
+/**
+ * The alias is the identity: `/key/update` and `/key/delete` find a key by it, and this resource
+ * never holds the value that could find it any other way. A different alias is a different key.
+ */
+export class LitellmKeyAliasChangedError extends Data.TaggedError('LitellmKeyAliasChangedError')<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key alias changed from '${this.from}' to '${this.to}'. The alias is the key's ` +
+      'identity and a rename would need the same value under a new row: declare the new alias as ' +
+      'a new resource and remove the old one with RemovalPolicy.destroy(). Nothing was written.'
+    );
+  }
+}
+
+/** More than one live key carries the alias, so nothing can say which one is declared. */
+export class LitellmKeyAmbiguousAliasError extends Data.TaggedError(
+  'LitellmKeyAmbiguousAliasError',
+)<{
+  readonly keyAlias: string;
+  readonly count: number;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': ${this.count} live keys carry this alias, so none can be ` +
+      'called the declared one. Resolve the duplicates in LiteLLM first. Nothing was written.'
+    );
+  }
+}
+
+/** `/key/list` answered something that is not a list of key rows. */
+export class LitellmKeyUnreadableError extends Data.TaggedError('LitellmKeyUnreadableError')<{
+  readonly keyAlias: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': /key/list did not answer full key rows (a hash list means ` +
+      'return_full_object was ignored). Nothing was written.'
+    );
+  }
+}
+
+/** A write returned no error but the alias is not listed afterwards. */
+export class LitellmKeyAbsentAfterWriteError extends Data.TaggedError(
+  'LitellmKeyAbsentAfterWriteError',
+)<{
+  readonly keyAlias: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.Key '${this.keyAlias}': the write returned no error but the alias is not listed.`;
+  }
+}
+
+/**
+ * The write returned no error but the row still differs from the declaration. `/key/update` is a
+ * merge patch (its docstring), so this is a proxy that did not apply a field — refused, never
+ * reported as done.
+ */
+export class LitellmKeyFieldNotAppliedError extends Data.TaggedError(
+  'LitellmKeyFieldNotAppliedError',
+)<{
+  readonly keyAlias: string;
+  readonly fields: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the write returned no error but ${this.fields.join(', ')} ` +
+      'still differ from the declaration.'
+    );
+  }
+}
+
+export type KeyError =
+  | keys.ListKeysKeyListGetError
+  | keys.GenerateKeyFnKeyGeneratePostError
+  | keys.UpdateKeyFnKeyUpdatePostError
+  | keys.DeleteKeyFnKeyDeletePostError
+  | LitellmKeyDebugLoggingError
+  | LitellmKeyTransportError
+  | LitellmKeyAliasEmptyError
+  | LitellmKeyValueRequiredError
+  | LitellmKeyValueMissingError
+  | LitellmKeyValueMalformedError
+  | LitellmKeyValueNotHonouredError
+  | LitellmKeyValueMismatchError
+  | LitellmKeyAliasChangedError
+  | LitellmKeyAmbiguousAliasError
+  | LitellmKeyCallbackMetadataDeclaredError
+  | LitellmKeyCallbackMetadataLiveError
+  | LitellmKeyUnreadableError
+  | LitellmKeyAbsentAfterWriteError
+  | LitellmKeyFieldNotAppliedError;

package/src/litellm/key-form.ts

@@ -0,0 +1,200 @@
+/**
+ * Props, attributes, wire bodies and comparison for `LiteLLM.Key`, testable without a server.
+ *
+ * ⛔ THERE IS NO SECRET IN THIS FILE'S OUTPUT. `KeyAttributes` has no `key`, no `token` and no hash:
+ *   `/key/list` rows carry `token` (LiteLLM's hash of the key) and `toAttributes` drops it, because
+ *   attributes are persisted unencrypted (key-secret.ts). The value is unwrapped in `createBody`, at
+ *   the last moment before the wire, and compared with a live row only as a sha256 in memory
+ *   (`verifyKeyValue`, key-secret.ts) against the raw row's `token` — the hash itself never reaches
+ *   state. The callback slots of `metadata` are dropped too (key-metadata.ts).
+ * ★ THE ROW IS READ THROUGH `/key/list?key_alias=…&return_full_object=true`. Measured 2026-09-28
+ *   (litellm-key-access): a bare list and `get_key` come back with `models: []` for keys whose real
+ *   allowlist lives in the full object. The generated `UserAPIKeyAuth` row declares every column
+ *   compared here (`budget_id`, `models`, `allowed_routes`, `team_id`, `metadata`, `expires`).
+ * ⛔ A DECLARATION MANAGES ONLY WHAT IT NAMES. An omitted `budgetId`, `models`, `allowedRoutes`,
+ *   `teamId` or `duration` is neither compared nor sent, so a live value stays. Reading omission as
+ *   "clear it" FAILS OPEN on a credential: `[]` is "all models" and "no route restriction" to
+ *   LiteLLM, and no budget drops the tier's limits. On an adopted key (whose plan says `adopted`, never
+ *   what the apply will write, and which `--adopt` given for another resource takes over too) that
+ *   would widen a live key without the plan ever showing an `update`. Clearing is an explicit
+ *   declaration: `models: []`, `allowedRoutes: []`, `budgetId: null`, `teamId: null`, `duration: null`.
+ *   `/key/update` is a merge patch for the COLUMNS (its docstring), so an unsent one is left as it is.
+ * ⛔ `metadata` IS A MERGE, NOT A COLUMN OF THE DECLARER'S: LiteLLM keeps guardrails, per-model limits
+ *   and more inside it, and `/key/update` replaces it wholesale. See key-metadata.ts.
+ * ⚠️ NOT MODELLED, so a declaration of them could never be diffed: `max_budget`, `soft_budget`,
+ *   `object_permission`, `blocked`, `spend`, and the top-level rate limits. Bind a `LiteLLM.Budget`
+ *   for limits. The ones that live in `metadata` (guardrails, tags, `model_rpm_limit`, …) are left
+ *   alone by the merge, and can be declared as `metadata` keys.
+ */
+import type * as keys from '@distilled.cloud/litellm/key_management';
+import * as Redacted from 'effect/Redacted';
+import type { FromEnv } from '../secrets/write-only.ts';
+import { type Metadata, mergedMetadata, metadataDiffers, splitMetadata } from './key-metadata.ts';
+
+export interface KeyProps {
+  /** The alias LiteLLM knows the key by: its identity, unique per proxy. Declare an existing key's alias to adopt it. */
+  readonly keyAlias: string;
+  /**
+   * The key's VALUE, by the NAME of the environment variable holding it (`{ fromEnv: 'SEAT_KEY' }`).
+   * Write-only and create-only: required to create the key, never stored. On an EXISTING key a
+   * declared value is compared with the row in memory only (sha256 against the row's `token`), and a
+   * mismatch is refused — `/key/update` cannot change a key's value. Omit it to manage an existing
+   * key's settings without ever holding its value.
+   */
+  readonly key?: FromEnv;
+  /**
+   * The `LiteLLM.Budget` tier the key binds to (`budget.budgetId`, so the tier is created first).
+   * Omitted = not managed, a live binding stays. `null` = unbind, which drops the tier's limits.
+   */
+  readonly budgetId?: string | null;
+  /**
+   * Model names the key may call. Omitted = not managed, a live scope stays (a NEW key then starts
+   * with LiteLLM's default). `[]` = ALL models, LiteLLM's reading: declared on a scoped key it WIDENS it.
+   */
+  readonly models?: readonly string[];
+  /**
+   * Routes the key may call, exact or wildcard (`/chat/completions`, `/v1/*`). Omitted = not
+   * managed. `[]` = no route restriction: declared on a restricted key it WIDENS it.
+   */
+  readonly allowedRoutes?: readonly string[];
+  /** The team the key belongs to. Omitted = not managed. `null` = detach. */
+  readonly teamId?: string | null;
+  /**
+   * The `metadata` keys this declaration manages, a MERGE (key-metadata.ts): other live keys are
+   * carried, never removed, and a key is cleared by declaring it `null`. Stored in state, so no
+   * secrets. `logging`, `callback_settings` and `secret_manager_settings` are refused.
+   */
+  readonly metadata?: Metadata;
+  /**
+   * Validity from creation: `'30s'`, `'30m'`, `'30h'`, `'30d'`. Omitted = not managed (a live expiry
+   * stays; a new key never expires). `null` = never expires, which clears a live expiry.
+   */
+  readonly duration?: string | null;
+}
+
+export interface KeyAttributes {
+  readonly keyAlias: string;
+  readonly budgetId: string | null;
+  readonly models: readonly string[];
+  readonly allowedRoutes: readonly string[];
+  readonly teamId: string | null;
+  /** The row's `metadata` WITHOUT the callback slots (`withheld`): those carry secret keys and state is unencrypted. */
+  readonly metadata: Metadata;
+  /**
+   * The `duration` this provider last WROTE. The row carries only `expires`, an absolute time, so
+   * the declared duration cannot be read back; state remembers it. `null` for an adopted row.
+   */
+  readonly duration: string | null;
+  /** When the key stops authenticating, as the row says. Observed, never declared. */
+  readonly expires: string | null;
+  /**
+   * The NAMES of the `metadata` callback slots the row has and this resource never reads. A metadata
+   * write is refused while any is present: `/key/update` replaces the column and could not carry them.
+   */
+  readonly withheld: readonly string[];
+}
+
+/** Order-insensitive: LiteLLM does not promise the order a list comes back in. */
+const sameSet = (a: readonly string[], b: readonly string[]): boolean => {
+  const left = [...a].sort();
+  const right = [...b].sort();
+  return left.length === right.length && left.every((value, i) => value === right[i]);
+};
+
+/**
+ * Whether the expiry differs from the DECLARED `duration` (`null` = never expires): the remembered
+ * duration is not the declared one, or the row has (no) expiry where the declaration wants (none) —
+ * someone cleared or set it by hand.
+ * ⚠️ AN ADOPTED ROW REMEMBERS NOTHING, so declaring a `duration` on one re-arms its expiry once,
+ *   from that deploy; after it the duration is remembered and a plan is quiet.
+ */
+const expiryDiffers = (live: KeyAttributes, wanted: string | null): boolean =>
+  live.duration !== wanted || (wanted === null) !== (live.expires === null);
+
+/**
+ * Wire names of the fields the declaration NAMES where the live row disagrees. An omitted prop is
+ * never here (the header's "manages only what it names"), so nothing omitted is ever written.
+ */
+export const differing = (live: KeyAttributes, props: KeyProps): readonly string[] => {
+  const out: string[] = [];
+  if (props.budgetId !== undefined && live.budgetId !== props.budgetId) out.push('budget_id');
+  if (props.models !== undefined && !sameSet(live.models, props.models)) out.push('models');
+  if (props.allowedRoutes !== undefined && !sameSet(live.allowedRoutes, props.allowedRoutes)) {
+    out.push('allowed_routes');
+  }
+  if (props.teamId !== undefined && live.teamId !== props.teamId) out.push('team_id');
+  if (metadataDiffers(live.metadata, props.metadata)) out.push('metadata');
+  if (props.duration !== undefined && expiryDiffers(live, props.duration)) out.push('duration');
+  return out;
+};
+
+/**
+ * Create body: only what is declared, plus the value.
+ * ⛔ `Redacted.value` IS CALLED HERE, TO SEND, AND IN key-secret.ts's `echoes`, TO COMPARE — nowhere else.
+ */
+export const createBody = (
+  props: KeyProps,
+  secret: Redacted.Redacted<string>,
+): keys.GenerateKeyFnKeyGeneratePostRequest => {
+  const body: keys.GenerateKeyFnKeyGeneratePostRequest = {
+    key: Redacted.value(secret),
+    key_alias: props.keyAlias,
+  };
+  // ★ A DECLARED `null` (unbind, detach, never expires) IS NOT SENT: a new key has nothing to clear.
+  if (typeof props.budgetId === 'string') body.budget_id = props.budgetId;
+  if (props.models !== undefined) body.models = [...props.models];
+  if (props.allowedRoutes !== undefined) body.allowed_routes = [...props.allowedRoutes];
+  if (typeof props.teamId === 'string') body.team_id = props.teamId;
+  if (props.metadata !== undefined) body.metadata = { ...props.metadata };
+  if (typeof props.duration === 'string') body.duration = props.duration;
+  return body;
+};
+
+/**
+ * Update body: the alias (which finds the key, `key` omitted) and ONLY the declared fields that
+ * differ, each as the declaration wants it — a declared `null` on `budget_id`/`team_id`/`duration`
+ * as an explicit `null` (a key column, which "an explicit null clears"), a declared `[]` as `[]`.
+ * ★ `metadata` CARRIES EVERY LIVE KEY with the declared ones on top, because `/key/update` replaces
+ *   the column (key-metadata.ts). The caller has refused a key with `withheld` slots by now.
+ * ⛔ NEVER CARRIES `key`: an update must not be able to change which value authenticates.
+ */
+export const updateBody = (
+  props: KeyProps,
+  live: KeyAttributes,
+): keys.UpdateKeyFnKeyUpdatePostRequest => {
+  const body: keys.UpdateKeyFnKeyUpdatePostRequest = { key_alias: live.keyAlias };
+  for (const field of differing(live, props)) {
+    if (field === 'budget_id') body.budget_id = props.budgetId ?? null;
+    if (field === 'models') body.models = [...(props.models ?? [])];
+    if (field === 'allowed_routes') body.allowed_routes = [...(props.allowedRoutes ?? [])];
+    if (field === 'team_id') body.team_id = props.teamId ?? null;
+    if (field === 'metadata') body.metadata = { ...mergedMetadata(live.metadata, props.metadata) };
+    if (field === 'duration') body.duration = props.duration ?? null;
+  }
+  return body;
+};
+
+const strings = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+const stringOrNull = (value: unknown): string | null => (typeof value === 'string' ? value : null);
+
+/**
+ * One row of `/key/list?return_full_object=true`. The row's `token` (LiteLLM's hash of the key), the
+ * `metadata` callback slots (only their names stay, as `withheld`), and every other column not named
+ * in `KeyAttributes`, are dropped here on purpose.
+ */
+export const toAttributes = (row: Record<string, unknown>): KeyAttributes => {
+  const { metadata, withheld } = splitMetadata(row['metadata']);
+  return {
+    allowedRoutes: strings(row['allowed_routes']),
+    budgetId: stringOrNull(row['budget_id']),
+    duration: null,
+    expires: stringOrNull(row['expires']),
+    keyAlias: String(row['key_alias']),
+    metadata,
+    models: strings(row['models']),
+    teamId: stringOrNull(row['team_id']),
+    withheld,
+  };
+};

package/src/litellm/key-harness.ts

@@ -0,0 +1,121 @@
+/**
+ * What every `LiteLLM.Key` test needs, in one place — TEST ONLY, never imported by `index.ts` (the
+ * `mesh-node-harness.ts` convention).
+ *
+ * ⛔ EVERY KEY VALUE IN THE TESTS IS SYNTHETIC: `sk-FAKE-…`, never a value that ever authenticated
+ *   anything. A test that asserts a value is absent from a place needs a value it can search for.
+ */
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import { Retry } from '@distilled.cloud/litellm/Retry';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE, startFakeLitellm } from './fake-litellm.ts';
+import { type FakeStack, fakeStack } from './fake-stack.ts';
+import { LiteLLMKey } from './key.ts';
+import type { KeyProps } from './key-form.ts';
+import type { LitellmOpContext } from './operations.ts';
+
+export const MASTER_KEY = 'sk-test-master';
+/** A valid user-defined key (`sk-` and 16+ characters) that is obviously not a real one. */
+export const FAKE_KEY = 'sk-FAKE-seat-key-000000000001';
+export const OTHER_FAKE_KEY = 'sk-FAKE-seat-key-000000000002';
+export const VAR = 'FAKE_LITELLM_SEAT_KEY';
+
+/** The row's `token` for a value, the same sha256 the fake and the vendor store (`hash_token`). */
+export const tokenFor = (value: string): string =>
+  new Bun.CryptoHasher('sha256').update(value).digest('hex');
+
+export type Fake = ReturnType<typeof startFakeLitellm>;
+
+export const newFake = (options?: Parameters<typeof startFakeLitellm>[0]): Fake =>
+  startFakeLitellm({ masterKey: MASTER_KEY, ...options });
+
+export const keyStack = (fake: Fake, settings?: { readonly noRetry?: boolean }): FakeStack =>
+  fakeStack({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE }, fake.fetch, 'KeyStack', settings);
+
+/** One declaration as a stack body. `name` is the resource's logical id. */
+export const declare = (props: KeyProps, name = 'Seat') =>
+  Effect.gen(function* () {
+    yield* LiteLLMKey(name, props);
+  });
+
+/**
+ * Runs `body` with `values` in `process.env`, then puts the environment back exactly as it was.
+ * ⚠️ THE PROVIDER READS `process.env` AT CALL TIME (write-only.ts `resolveAll`), so the variable
+ *   has to be there for the whole deploy and gone after it.
+ */
+export const withEnv = async <A>(
+  values: Readonly<Record<string, string | undefined>>,
+  body: () => Promise<A>,
+): Promise<A> => {
+  const saved = Object.fromEntries(Object.keys(values).map((name) => [name, process.env[name]]));
+  for (const [name, value] of Object.entries(values)) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+  try {
+    return await body();
+  } finally {
+    for (const [name, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  }
+};
+
+/** The message a rejected deploy carries, or `''` when it did not reject. */
+export const failureOf = async (attempt: Promise<unknown>): Promise<string> =>
+  attempt.then(
+    () => '',
+    (error: unknown) => (error instanceof Error ? error.message : String(error)),
+  );
+
+/**
+ * Runs one handler effect against the fake outside any stack (a handler-level test), with the SDK's
+ * retry OFF: a test of a failing call wants the failure, not the backoff before it.
+ */
+export const runAgainst = <A, E>(
+  fake: Fake,
+  effect: Effect.Effect<A, E, LitellmOpContext>,
+): Promise<A> =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provideService(Retry, { while: () => false }),
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+      Effect.provide(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+/** A seeded live row shaped like `UserAPIKeyAuth`, with a hash `token` a resource must never surface. */
+export const liveRow = (fields: Record<string, unknown> = {}): Record<string, unknown> => ({
+  allowed_routes: [],
+  blocked: null,
+  budget_id: null,
+  expires: null,
+  key_alias: 'seat-a',
+  metadata: {},
+  models: [],
+  spend: 0,
+  team_id: null,
+  token: 'FAKE-TOKEN-HASH-do-not-surface',
+  ...fields,
+});
+
+/**
+ * Someone changing a live key outside the stack — the dashboard's `/key/update` — through the fake's
+ * own route, so it replaces `metadata` the way LiteLLM does. It shows in `fake.keys.writes()`.
+ */
+export const dashboardEdit = async (
+  fake: Fake,
+  keyAlias: string,
+  patch: Record<string, unknown>,
+): Promise<void> => {
+  const response = await fake.fetch(`${FAKE_BASE}/key/update`, {
+    body: JSON.stringify({ key_alias: keyAlias, ...patch }),
+    headers: { authorization: `Bearer ${MASTER_KEY}`, 'content-type': 'application/json' },
+    method: 'POST',
+  });
+  if (!response.ok) throw new Error(`dashboard edit failed: ${response.status}`);
+};

package/src/litellm/key-metadata-errors.ts

@@ -0,0 +1,49 @@
+/**
+ * The typed refusals for `LiteLLM.Key`'s `metadata` slots that carry callback credentials
+ * (`logging`, `callback_settings`, `secret_manager_settings`; key-metadata.ts has the reasons).
+ * Split from key-errors.ts, which is at its size cap.
+ *
+ * ⛔ NEITHER CARRIES A VALUE. They name the alias and the slot, never what the slot held.
+ */
+import * as Data from 'effect/Data';
+
+/**
+ * The declaration names a callback slot. LiteLLM stores its `callback_vars` ENCRYPTED, so the row
+ * would never read back equal (every deploy would fail with `LitellmKeyFieldNotAppliedError`), and
+ * Alchemy state is unencrypted.
+ */
+export class LitellmKeyCallbackMetadataDeclaredError extends Data.TaggedError(
+  'LitellmKeyCallbackMetadataDeclaredError',
+)<{
+  readonly keyAlias: string;
+  readonly slots: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': metadata declares ${this.slots.join(', ')}, which carry ` +
+      'callback credentials. LiteLLM stores them encrypted, so they would never read back equal, ' +
+      "and Alchemy state is unencrypted. Configure the key's logging in LiteLLM itself. Nothing was written."
+    );
+  }
+}
+
+/**
+ * The live key holds callback credentials in its `metadata` and the declaration wants a metadata
+ * key changed. `/key/update` REPLACES the column, and this resource never read those slots, so it
+ * could not send them back: writing would strip the key's logging. Refused before the write.
+ */
+export class LitellmKeyCallbackMetadataLiveError extends Data.TaggedError(
+  'LitellmKeyCallbackMetadataLiveError',
+)<{
+  readonly keyAlias: string;
+  readonly slots: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Key '${this.keyAlias}': the live key holds ${this.slots.join(', ')} in its metadata ` +
+      '(callback credentials this resource never reads), and /key/update replaces the whole ' +
+      'metadata, so writing the declared metadata would strip them. Change that metadata in LiteLLM, ' +
+      'or stop declaring metadata for this key. Nothing was written.'
+    );
+  }
+}