@homeflare/alchemy 0.43.0 → 0.45.0

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

@@ -0,0 +1,156 @@
+/**
+ * `LiteLLM.Key`'s `metadata`, over the fake: a MERGE that never strips what LiteLLM keeps inside the
+ * column (guardrails, per-model limits, passthrough routes), and callback credentials that never
+ * reach state (key-metadata.ts has the measured reasons). The fake replaces `metadata` on update, as
+ * LiteLLM does, so a body that dropped a folded key would lose it here too.
+ */
+import { describe, expect, test } from 'bun:test';
+import { differing, toAttributes, updateBody } from './key-form.ts';
+import {
+  FAKE_KEY,
+  VAR,
+  dashboardEdit,
+  declare,
+  failureOf,
+  keyStack,
+  liveRow,
+  newFake,
+  withEnv,
+} from './key-harness.ts';
+import { callbackSlotsIn, mergedMetadata, splitMetadata } from './key-metadata.ts';
+
+/** What LiteLLM 1.103 keeps in a key's metadata besides what a person declared. */
+const folded = {
+  allowed_passthrough_routes: ['/x'],
+  guardrails: ['pii-mask'],
+  model_rpm_limit: { m: 5 },
+  tags: ['prod'],
+};
+/** A legacy row's plaintext callback config: 1.103 encrypts new ones, old ones pass through. */
+const SECRET = 'sk-lf-FAKE-callback-secret-000001';
+const logging = [{ callback_name: 'langfuse', callback_vars: { langfuse_secret_key: SECRET } }];
+const seat = (metadata: Record<string, unknown>) =>
+  liveRow({ metadata: { seat: 'a', ...metadata } });
+
+describe('metadata is a merge', () => {
+  test('a declaration that matches what it names writes nothing, however much else the row holds', async () => {
+    const fake = newFake({ keySeed: [seat(folded)] });
+    const planned = await keyStack(fake).deploy(
+      declare({ keyAlias: 'seat-a', metadata: { seat: 'a' } }),
+      {
+        adopt: true,
+      },
+    );
+    expect(Object.values(planned)).toEqual(['adopted']);
+    expect(fake.keys.writes()).toEqual([]);
+    expect(fake.keys.rows()[0]?.['metadata']).toEqual({ seat: 'a', ...folded });
+  });
+
+  test('changing a declared key resends every live key with it', async () => {
+    const fake = newFake({ keySeed: [seat({ ...folded, owner: 'ops' })] });
+    await keyStack(fake).deploy(declare({ keyAlias: 'seat-a', metadata: { seat: 'b' } }), {
+      adopt: true,
+    });
+    const expected = { seat: 'b', ...folded, owner: 'ops' };
+    expect(fake.keys.writes()).toEqual([
+      { body: { key_alias: 'seat-a', metadata: expected }, path: '/key/update' },
+    ]);
+    expect(fake.keys.rows()[0]?.['metadata']).toEqual(expected);
+  });
+
+  test('a setting someone adds to a key the stack owns survives the next update', async () => {
+    const fake = newFake();
+    const stack = keyStack(fake);
+    const props = { key: { fromEnv: VAR }, keyAlias: 'seat-a', metadata: { seat: 'a' } };
+    const deploy = (models: readonly string[]) =>
+      withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare({ ...props, models })));
+    expect(await deploy([])).toEqual({ Seat: 'create' });
+    await dashboardEdit(fake, 'seat-a', { metadata: { seat: 'a', ...folded } });
+    // ★ THE NEXT DEPLOY'S RECONCILE READS THE ROW, SEES THE GUARDRAIL AND MUST NOT SEND `metadata`
+    //   AT ALL: the declared key already matches, and a body without it leaves the column as it is.
+    expect(await deploy(['m'])).toEqual({ Seat: 'update' });
+    expect(fake.keys.writes().at(-1)?.body).toEqual({ key_alias: 'seat-a', models: ['m'] });
+    expect(fake.keys.rows()[0]?.['metadata']).toEqual({ seat: 'a', ...folded });
+  });
+
+  test('a key is cleared by declaring it null, and is quiet after', async () => {
+    const fake = newFake({ keySeed: [seat(folded)] });
+    const stack = keyStack(fake);
+    const props = { keyAlias: 'seat-a', metadata: { seat: null } };
+    await stack.deploy(declare(props), { adopt: true });
+    expect(fake.keys.rows()[0]?.['metadata']).toEqual({ seat: null, ...folded });
+    expect(await stack.deploy(declare(props))).toEqual({ Seat: 'noop' });
+  });
+
+  test('form: only declared keys differ, and the body merges', () => {
+    const live = toAttributes(seat(folded));
+    expect(differing(live, { keyAlias: 'seat-a', metadata: { seat: 'a' } })).toEqual([]);
+    const props = { keyAlias: 'seat-a', metadata: { seat: 'b' } };
+    expect(differing(live, props)).toEqual(['metadata']);
+    expect(updateBody(props, live)).toEqual({
+      key_alias: 'seat-a',
+      metadata: { seat: 'b', ...folded },
+    });
+    expect(mergedMetadata({ a: 1 }, undefined)).toEqual({ a: 1 });
+  });
+});
+
+describe('callback credentials never reach state', () => {
+  const held = seat({ ...folded, logging });
+
+  test('an adopted key with legacy plaintext logging leaves the secret out of state', async () => {
+    const fake = newFake({ keySeed: [held] });
+    const stack = keyStack(fake);
+    const props = { keyAlias: 'seat-a', metadata: { seat: 'a' } };
+    await stack.deploy(declare(props), { adopt: true });
+    expect(fake.keys.writes()).toEqual([]);
+    const state = stack.snapshot();
+    expect(state).not.toContain(SECRET);
+    expect(state).toContain('logging'); // the slot's NAME is what state keeps
+    expect(state).toContain('pii-mask'); // and the rest of the metadata, which it needs to carry it
+  });
+
+  test('a metadata write onto a key that holds callback config is refused, nothing written', async () => {
+    const fake = newFake({ keySeed: [held] });
+    const message = await failureOf(
+      keyStack(fake).deploy(declare({ keyAlias: 'seat-a', metadata: { seat: 'b' } }), {
+        adopt: true,
+      }),
+    );
+    expect(message).toContain('logging');
+    expect(message).not.toContain(SECRET);
+    expect(fake.keys.writes()).toEqual([]);
+    expect(fake.keys.rows()[0]?.['metadata']).toEqual({ seat: 'a', ...folded, logging });
+  });
+
+  test('a write that touches no metadata still goes ahead on such a key', async () => {
+    const fake = newFake({ keySeed: [held] });
+    await keyStack(fake).deploy(declare({ keyAlias: 'seat-a', models: ['m'] }), { adopt: true });
+    expect(fake.keys.writes()).toEqual([
+      { body: { key_alias: 'seat-a', models: ['m'] }, path: '/key/update' },
+    ]);
+    expect(fake.keys.rows()[0]?.['metadata']).toMatchObject({ logging });
+  });
+
+  for (const slot of ['logging', 'callback_settings', 'secret_manager_settings']) {
+    test(`a declaration naming ${slot} is refused before anything is written`, async () => {
+      const fake = newFake();
+      const props = {
+        keyAlias: 'seat-a',
+        metadata: { [slot]: [{ callback_vars: { k: SECRET } }] },
+      };
+      const message = await failureOf(keyStack(fake).deploy(declare(props)));
+      expect(message).toContain(slot);
+      expect(message).not.toContain(SECRET);
+      expect(fake.requests().filter((each) => each.method !== 'GET')).toEqual([]);
+    });
+  }
+
+  test('form: the slots are split off the row, and only their names stay', () => {
+    const split = splitMetadata({ seat: 'a', logging, callback_settings: {} });
+    expect(split).toEqual({ metadata: { seat: 'a' }, withheld: ['callback_settings', 'logging'] });
+    expect(JSON.stringify(toAttributes(held))).not.toContain(SECRET);
+    expect(callbackSlotsIn(undefined)).toEqual([]);
+    expect(callbackSlotsIn({ tags: [] })).toEqual([]);
+  });
+});

package/src/litellm/key-metadata.ts

@@ -0,0 +1,74 @@
+/**
+ * `LiteLLM.Key`'s `metadata` column: what is compared, what is sent, and what is never held.
+ * Pure, so it is testable without a server.
+ *
+ * ⛔ `metadata` IS NOT ONLY THE DECLARER'S. LiteLLM 1.103 keeps a key's guardrails, policies, tags,
+ *   prompts, per-model RPM/TPM caps, `enforced_params`, `allowed_passthrough_routes`,
+ *   `end_user_budget_id` and more INSIDE it: they are `LiteLLM_ManagementEndpoint_MetadataFields`
+ *   and `..._Premium` (`proxy/_types.py:4821-4853`), folded in on create by
+ *   `metadata_json_with_limits` (`key_management_endpoints.py:4429`) and on update by
+ *   `prepare_metadata_fields` (:2312). And `/key/update` REPLACES the column with the `metadata` it is
+ *   sent: only `service_account_id`, the one reserved field, survives an omission (:2323-2336). A
+ *   body carrying just the declared keys therefore strips every one of those from a live credential,
+ *   and the deploy reports success. Measured over the fake, which replaces the column the same way
+ *   (key.test.ts, "metadata is a merge").
+ * ★ SO `metadata` IS A MERGE, AT THE TOP-LEVEL KEY. A declaration COMPARES and WRITES only the keys it
+ *   names; a live key it does not name is CARRIED into the update body unchanged, never dropped. The
+ *   alternative, a list of the keys LiteLLM owns to carry and clear the rest, was not taken: the list
+ *   is per-version (a key LiteLLM adds next release would be stripped until it is updated here),
+ *   and this way fails safe. The cost: a key cannot be removed by leaving it out. Declare it `null`.
+ * ⛔ THREE SLOTS ARE NEVER HELD, READ OR WRITTEN: `logging`, `callback_settings` and
+ *   `secret_manager_settings` (`common_utils/callback_utils.py:51`, `_CALLBACK_CONFIG_SLOTS`). They
+ *   carry `callback_vars`, an observability platform's secret keys. LiteLLM encrypts them at rest
+ *   (`encrypt_callback_vars`, :716) but a legacy row's are plaintext ("pass through unchanged",
+ *   :725-731), and Alchemy persists attributes unencrypted. So a row's slots are dropped from
+ *   `KeyAttributes.metadata` and only their NAMES are kept (`withheld`); a declaration that names
+ *   one is refused, since it would be stored encrypted and so never read back equal (a deploy that
+ *   failed on every run); and a metadata write on a key that HAS one is refused, since this resource
+ *   cannot carry what it never read. Configure key logging in LiteLLM itself.
+ * ⚠️ TOP-LEVEL KEYS ONLY, as LiteLLM reads them: `_transform_callback_vars` looks at `metadata["logging"]`
+ *   and no deeper.
+ */
+import { deepEqual } from 'alchemy/Diff';
+
+export type Metadata = Readonly<Record<string, unknown>>;
+
+/** The slots that carry callback credentials: never in attributes, never declared, never written. */
+export const CALLBACK_SLOTS = ['callback_settings', 'logging', 'secret_manager_settings'] as const;
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The callback slots `metadata` names, sorted (`CALLBACK_SLOTS` is). */
+export const callbackSlotsIn = (metadata: Metadata | undefined): readonly string[] =>
+  metadata === undefined ? [] : CALLBACK_SLOTS.filter((slot) => Object.hasOwn(metadata, slot));
+
+/**
+ * A row's `metadata` as attributes hold it: everything but the callback slots, whose NAMES are
+ * returned beside it (`withheld`) so a write knows it could not carry them.
+ */
+export const splitMetadata = (
+  raw: unknown,
+): { readonly metadata: Record<string, unknown>; readonly withheld: readonly string[] } => {
+  if (!isObject(raw)) return { metadata: {}, withheld: [] };
+  const withheld = callbackSlotsIn(raw);
+  return {
+    metadata: Object.fromEntries(Object.entries(raw).filter(([name]) => !withheld.includes(name))),
+    withheld,
+  };
+};
+
+/**
+ * Whether a key the declaration names differs from the live row. An absent live key differs from any
+ * declared value, `null` included (`deepEqual` tells `undefined` from `null`), so `{ seat: null }`
+ * writes a `null` once and is quiet after.
+ */
+export const metadataDiffers = (live: Metadata, declared: Metadata | undefined): boolean =>
+  declared !== undefined &&
+  Object.entries(declared).some(([name, value]) => !deepEqual(live[name], value));
+
+/** The body's `metadata`: every live key carried, the declared ones on top. */
+export const mergedMetadata = (live: Metadata, declared: Metadata | undefined): Metadata => ({
+  ...live,
+  ...declared,
+});

package/src/litellm/key-operations.ts

@@ -0,0 +1,184 @@
+/**
+ * The four LiteLLM `/key/*` calls `LiteLLM.Key` uses, through the SDK's typed operations.
+ *
+ * ★ EVERY OPERATION HERE EXISTS IN `@distilled.cloud/litellm/key_management` (generated at LiteLLM
+ *   1.103.0) AND IS CALLED WITH ITS OWN REQUEST TYPE — none is guessed, none is hand-rolled:
+ *     `listKeysKeyListGet`        GET  /key/list      read, by `key_alias`, `return_full_object`
+ *     `generateKeyFnKeyGeneratePost` POST /key/generate  create, with the user-defined `key`
+ *     `updateKeyFnKeyUpdatePost`  POST /key/update    merge patch, found by `key_alias`
+ *     `deleteKeyFnKeyDeletePost`  POST /key/delete    by `key_aliases`
+ *   `/key/info` and `/v2/key/info` are NOT used: they take the key or its hash, and this resource
+ *   holds neither for an adopted key. Listing by alias needs no value.
+ * ⚠️ NO SEMAPHORE, unlike pass-through endpoints: every key is its own DB row (budget-operations.ts).
+ * ⚠️ THE SDK'S DEFAULT RETRY APPLIES TO `/key/generate` TOO. A create whose response was lost and is
+ *   then retried surfaces the proxy's duplicate-alias 400 rather than a second key; the next deploy
+ *   reads the row. UNVERIFIED against a live proxy — the retry policy is core's, not this file's.
+ * ⚠️ DELETE IS IDEMPOTENT BY THIS FUNCTION, not by the vendor. MEASURED in the litellm 1.103.0 wheel
+ *   (`key_management_endpoints.py`): `/key/delete` for an alias it does not hold answers 404 "No keys
+ *   found" (`delete_verification_tokens`, :4915-4918), and 403 for a caller that may not delete the
+ *   key (:4933-4936). The SDK types both as resource-specific tags, `KeyNotFound` and
+ *   `KeyDeleteForbidden` (a distilled patch, `patches/key_management/delete_key_fn_key_delete_post.json`,
+ *   each matched on the status AND a phrase of the vendor's message), so `catchTag` sees them: the
+ *   MESSAGE MATCH LIVES IN THE SDK, never here (S21). An absent alias is settled by the LIST, which
+ *   answers absence unambiguously, and a `KeyNotFound` (another caller won the race, or a retry of a
+ *   delete whose answer was lost) re-lists and is swallowed only if the key has gone since. Every
+ *   other failure, `KeyDeleteForbidden` included, propagates typed: a 404 that is not the vendor's
+ *   is core's `NotFound`, not absence. operations.ts's `deletePassThroughEndpoint` and
+ *   budget-operations.ts decide the same way, on their own tag.
+ */
+import * as keys from '@distilled.cloud/litellm/key_management';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { isHttpClientError } from 'effect/unstable/http/HttpClientError';
+import {
+  LitellmKeyAliasEmptyError,
+  LitellmKeyAmbiguousAliasError,
+  LitellmKeyTransportError,
+  LitellmKeyUnreadableError,
+} from './key-errors.ts';
+import { type KeyAttributes, toAttributes } from './key-form.ts';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+
+/**
+ * The one live key with this alias, or `undefined`. Two rows are an error, never a pick: the
+ * server filters by an EXACT alias by default, and this filters again so a proxy that matched a
+ * substring cannot hand back someone else's key.
+ */
+export const findKey = (
+  keyAlias: string,
+): Effect.Effect<
+  KeyAttributes | undefined,
+  | keys.ListKeysKeyListGetError
+  | LitellmKeyUnreadableError
+  | LitellmKeyAmbiguousAliasError
+  | LitellmKeyAliasEmptyError,
+  LitellmOpContext
+> =>
+  keyAlias.trim() === '' ? Effect.fail(new LitellmKeyAliasEmptyError()) : findKeyByAlias(keyAlias);
+
+const findKeyByAlias = (keyAlias: string) =>
+  findKeyRowByAlias(keyAlias).pipe(
+    Effect.map((row) => (row === undefined ? undefined : toAttributes(row))),
+  );
+
+/**
+ * The one live key with this alias, as the raw `/key/list` row — the shape `toAttributes` reads
+ * and drops the `token` from. `findKey` maps it to `KeyAttributes`; `readKeyToken` reads the raw
+ * row because the row's `token` (the vendor's sha256 of the key) is what key-secret.ts's
+ * `verifyKeyValue` compares a declared value against, and it must not pass through `toAttributes`
+ * (which would put the hash in state).
+ */
+const findKeyRowByAlias = (keyAlias: string) =>
+  throughFetch(keys.listKeysKeyListGet({ key_alias: keyAlias, return_full_object: true })).pipe(
+    Effect.flatMap((response) =>
+      Effect.gen(function* () {
+        const rows: readonly unknown[] = response.keys ?? [];
+        // ⚠️ A STRING ROW IS A HASH: the proxy ignored `return_full_object`, and a hash carries none
+        //   of the columns compared. Refused rather than read as "no key".
+        if (rows.some((row) => typeof row !== 'object' || row === null)) {
+          return yield* new LitellmKeyUnreadableError({ keyAlias });
+        }
+        const mine = (rows as readonly Record<string, unknown>[]).filter(
+          (row) => row['key_alias'] === keyAlias,
+        );
+        if (mine.length > 1) {
+          return yield* new LitellmKeyAmbiguousAliasError({ count: mine.length, keyAlias });
+        }
+        return mine[0];
+      }),
+    ),
+  );
+
+/**
+ * The row's `token` (the vendor's sha256 of the key), `null` when the row carries none, or
+ * `undefined` when the alias is absent. Absence must plan recreation, not a value mismatch.
+ * Read only for the in-memory mismatch check (`verifyKeyValue`); the hash is never persisted.
+ */
+export const readKeyToken = (
+  keyAlias: string,
+): Effect.Effect<
+  string | null | undefined,
+  | keys.ListKeysKeyListGetError
+  | LitellmKeyUnreadableError
+  | LitellmKeyAmbiguousAliasError
+  | LitellmKeyAliasEmptyError,
+  LitellmOpContext
+> =>
+  keyAlias.trim() === ''
+    ? Effect.fail(new LitellmKeyAliasEmptyError())
+    : findKeyRowByAlias(keyAlias).pipe(
+        Effect.map((row) =>
+          row === undefined ? undefined : typeof row['token'] === 'string' ? row['token'] : null,
+        ),
+      );
+
+/**
+ * Whether `value` holds the request it answers. An `HttpClientError` does, through `reason.request`
+ * (its `request` getter reads it), and its body is the JSON the call sent.
+ */
+const carriesRequest = (value: unknown): boolean =>
+  isHttpClientError(value) || Predicate.hasProperty(value, 'request');
+
+/**
+ * `/key/generate`. The response's `key` is `Redacted` (the SDK's `SensitiveValue`); never log the response.
+ * ⛔ THE REQUEST BODY IS `{"key":"sk-…"}`, AND A FAILED CALL CAN CARRY ITS REQUEST. Two ways, both
+ *   measured 2026-09-29 with a synthetic key (key-transport.test.ts): a transport failure is an
+ *   `HttpClientError` in the error channel, and a body that fails mid-read is the SAME error as a
+ *   DEFECT (`Effect.orDie` in `@distilled.cloud/core`'s `protocol-rest.ts`). Either would put the
+ *   plaintext in front of anything that serialises, inspects or logs the failure — while the SDK's
+ *   own `HttpClientError` is not something this resource can leave typed as it is. Both become
+ *   `LitellmKeyTransportError`, which keeps the alias and the reason's tag and nothing else.
+ *   The SDK's status errors (`BadRequest`, `Forbidden`, …) carry only the proxy's message text and
+ *   stay as they are, so a caller can still `catchTag` them.
+ */
+export const generateKey = (body: keys.GenerateKeyFnKeyGeneratePostRequest) => {
+  const keyAlias = body.key_alias ?? '';
+  return throughFetch(keys.generateKeyFnKeyGeneratePost(body)).pipe(
+    Effect.catchTag('HttpClientError', (error) =>
+      Effect.fail(new LitellmKeyTransportError({ keyAlias, reason: error.reason._tag })),
+    ),
+    Effect.catchDefect((defect) =>
+      carriesRequest(defect)
+        ? Effect.fail(
+            new LitellmKeyTransportError({
+              keyAlias,
+              reason: isHttpClientError(defect) ? defect.reason._tag : 'Defect',
+            }),
+          )
+        : Effect.die(defect),
+    ),
+  );
+};
+
+/** `/key/update`, found by the body's `key_alias`. */
+export const updateKey = (body: keys.UpdateKeyFnKeyUpdatePostRequest) =>
+  throughFetch(keys.updateKeyFnKeyUpdatePost(body)).pipe(Effect.asVoid);
+
+/** `/key/delete` by alias, when the list shows the key; a no-op when it does not. */
+export const deleteKey = (
+  keyAlias: string,
+): Effect.Effect<
+  void,
+  | keys.DeleteKeyFnKeyDeletePostError
+  | keys.ListKeysKeyListGetError
+  | LitellmKeyUnreadableError
+  | LitellmKeyAmbiguousAliasError
+  | LitellmKeyAliasEmptyError,
+  LitellmOpContext
+> =>
+  findKey(keyAlias).pipe(
+    Effect.flatMap((live) =>
+      live === undefined
+        ? Effect.void
+        : throughFetch(keys.deleteKeyFnKeyDeletePost({ key_aliases: [keyAlias] })).pipe(
+            Effect.asVoid,
+            Effect.catchTag('KeyNotFound', (original) =>
+              findKey(keyAlias).pipe(
+                Effect.flatMap((still) =>
+                  still === undefined ? Effect.void : Effect.fail(original),
+                ),
+              ),
+            ),
+          ),
+    ),
+  );

package/src/litellm/key-rotation.test.ts

@@ -0,0 +1,110 @@
+/** Real beta.79 Plan/Apply: only the environment changes; no adoption or incidental drift. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { keyHandlers } from './key.ts';
+import {
+  FAKE_KEY,
+  MASTER_KEY,
+  OTHER_FAKE_KEY,
+  VAR,
+  declare,
+  failureOf,
+  keyStack,
+  newFake,
+  runAgainst,
+  tokenFor,
+  withEnv,
+} from './key-harness.ts';
+
+const seat = { key: { fromEnv: VAR }, keyAlias: 'seat-a', models: ['old'] };
+
+for (const models of [['new'], seat.models]) {
+  test(`an owned key deleted in the dashboard is recreated with models ${models.join(',')}`, async () => {
+    const fake = newFake();
+    const engine = keyStack(fake);
+    await withEnv({ [VAR]: FAKE_KEY }, async () => {
+      await engine.deploy(declare(seat));
+      const removed = await fake.fetch(`${FAKE_BASE}/key/delete`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${MASTER_KEY}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ key_aliases: [seat.keyAlias] }),
+      });
+      expect(removed.status).toBe(200);
+      expect(fake.keys.rows()).toHaveLength(0);
+      const news = { ...seat, models };
+      expect(Object.values(await engine.deploy(declare(news)))).toEqual(['update']);
+      expect(fake.keys.rows()).toHaveLength(1);
+      expect(fake.keys.rows()[0]?.models).toEqual(models);
+      expect(fake.keys.received().every((value) => value === FAKE_KEY)).toBe(true);
+      expect(Object.values(await engine.deploy(declare(news)))).toEqual(['noop']);
+    });
+    expect(fake.keys.writes().map((write) => write.path)).toEqual([
+      '/key/generate',
+      '/key/delete',
+      '/key/generate',
+    ]);
+    expect(engine.snapshot().includes(FAKE_KEY)).toBe(false);
+    expect(engine.snapshot().includes(tokenFor(FAKE_KEY))).toBe(false);
+  });
+}
+
+test('an owned key with identical props refuses a rotated variable during plan', async () => {
+  const fake = newFake();
+  const engine = keyStack(fake);
+  await withEnv({ [VAR]: FAKE_KEY }, () => engine.deploy(declare(seat)));
+  const writes = fake.keys.writes().length;
+  const state = engine.snapshot();
+  const unchanged = await withEnv({ [VAR]: FAKE_KEY }, () => engine.deploy(declare(seat)));
+  expect(Object.values(unchanged)).toEqual(['noop']);
+  for (const news of [seat, { ...seat, models: ['new'] }]) {
+    const message = await failureOf(
+      withEnv({ [VAR]: OTHER_FAKE_KEY }, () => engine.deploy(declare(news))),
+    );
+    expect(message).toContain('is not the key');
+    expect(message).toContain(VAR);
+    expect(message.includes(OTHER_FAKE_KEY)).toBe(false);
+    expect(fake.keys.writes()).toHaveLength(writes);
+    expect(engine.snapshot()).toBe(state);
+  }
+  for (const material of [FAKE_KEY, OTHER_FAKE_KEY, tokenFor(FAKE_KEY), tokenFor(OTHER_FAKE_KEY)]) {
+    expect(engine.snapshot().includes(material)).toBe(false);
+  }
+});
+
+test('the diff refusal is typed and catchTag handles it without storing any key material', async () => {
+  const fake = newFake();
+  const attributes = await withEnv({ [VAR]: FAKE_KEY }, () =>
+    runAgainst(
+      fake,
+      keyHandlers.reconcile({ fqn: 'Seat', instanceId: 'i-1', news: seat, output: undefined }),
+    ),
+  );
+  const tag = await withEnv({ [VAR]: OTHER_FAKE_KEY }, () =>
+    runAgainst(
+      fake,
+      keyHandlers
+        .diff({ news: { ...seat, models: ['new'] }, output: attributes })
+        .pipe(
+          Effect.catchTag('LitellmKeyValueMismatchError', (error) => Effect.succeed(error._tag)),
+        ),
+    ),
+  );
+  expect(tag).toBe('LitellmKeyValueMismatchError');
+  expect(fake.keys.writes().map((write) => write.path)).toEqual(['/key/generate']);
+});
+
+test('an owned key can update and then noop with the declared variable unset or empty', async () => {
+  for (const missing of [undefined, '']) {
+    const fake = newFake();
+    const engine = keyStack(fake);
+    await withEnv({ [VAR]: FAKE_KEY }, () => engine.deploy(declare(seat)));
+    const news = { ...seat, models: ['new'] };
+    await withEnv({ [VAR]: missing }, async () => {
+      expect(Object.values(await engine.deploy(declare(news)))).toEqual(['update']);
+      expect(Object.values(await engine.deploy(declare(news)))).toEqual(['noop']);
+    });
+    expect(fake.keys.writes().map((write) => write.path)).toEqual(['/key/generate', '/key/update']);
+    expect(JSON.stringify(fake.keys.writes().slice(1)).includes(FAKE_KEY)).toBe(false);
+  }
+});

package/src/litellm/key-scope.test.ts

@@ -0,0 +1,135 @@
+/**
+ * `LiteLLM.Key` manages only what a declaration names. An omitted `budgetId`, `models`,
+ * `allowedRoutes`, `teamId` or `duration` must not mean "clear it", because clearing FAILS OPEN on a
+ * credential: `[]` is "all models" and "no route restriction" to LiteLLM, and an adopted key's plan
+ * says `adopted`, never what the apply would write (key-form.ts's header).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { LiteLLMBudget } from './budget.ts';
+import { LiteLLMKey } from './key.ts';
+import { createBody, differing, toAttributes } from './key-form.ts';
+import { FAKE_KEY, VAR, declare, keyStack, liveRow, newFake, withEnv } from './key-harness.ts';
+
+const tier = (id: string) => ({ budget_id: id, created_at: 'x', updated_at: 'x' });
+/** A key scoped as narrowly as a seat's: one model, one route, a tier, a team, an expiry. */
+const scoped = () =>
+  liveRow({
+    allowed_routes: ['/v1/embeddings'],
+    budget_id: 'old-tier',
+    expires: '2099-01-01T00:00:00.000Z',
+    models: ['embed-only'],
+    team_id: 'team-a',
+  });
+const stillScoped = {
+  allowed_routes: ['/v1/embeddings'],
+  budget_id: 'old-tier',
+  expires: '2099-01-01T00:00:00.000Z',
+  models: ['embed-only'],
+  team_id: 'team-a',
+};
+
+describe('an omitted prop is left alone', () => {
+  test('adopting with only the alias writes nothing: the scoped key is not widened', async () => {
+    const fake = newFake({ budgetSeed: [tier('old-tier')], keySeed: [scoped()] });
+    const planned = await keyStack(fake).deploy(declare({ keyAlias: 'seat-a' }), { adopt: true });
+    expect(Object.values(planned)).toEqual(['adopted']);
+    expect(fake.keys.writes()).toEqual([]);
+    expect(fake.keys.rows()[0]).toMatchObject(stillScoped);
+  });
+
+  test('a budget bound by Output writes only the budget: models and routes stay', async () => {
+    // The documented declaration. Its plan says `create` (an Output cannot be probed), and reading
+    // the omissions as "clear" would send `models: []` and `allowed_routes: []` with the budget.
+    const fake = newFake({ keySeed: [scoped()] });
+    const body = Effect.gen(function* () {
+      const tierRow = yield* LiteLLMBudget('Tier', { budgetId: 'hf-tier-new', softBudget: 5 });
+      yield* LiteLLMKey('Seat', { budgetId: tierRow.budgetId, keyAlias: 'seat-a' });
+    });
+    await keyStack(fake).deploy(body, { adopt: true });
+    expect(fake.keys.writes().filter((write) => write.path === '/key/update')).toEqual([
+      { body: { budget_id: 'hf-tier-new', key_alias: 'seat-a' }, path: '/key/update' },
+    ]);
+    expect(fake.keys.rows()[0]).toMatchObject({
+      ...stillScoped,
+      budget_id: 'hf-tier-new',
+    });
+  });
+
+  test('a key the stack owns keeps what a later declaration stops naming', async () => {
+    const fake = newFake({ budgetSeed: [tier('tier-a')] });
+    const stack = keyStack(fake);
+    const seat = { key: { fromEnv: VAR }, keyAlias: 'seat-a' } as const;
+    const full = {
+      ...seat,
+      allowedRoutes: ['/v1/*'],
+      budgetId: 'tier-a',
+      models: ['m'],
+      teamId: 't',
+    };
+    await withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare(full)));
+    const writes = fake.keys.writes().length;
+    expect(await stack.deploy(declare(seat))).toEqual({ Seat: 'noop' });
+    expect(fake.keys.writes()).toHaveLength(writes);
+    expect(fake.keys.rows()[0]).toMatchObject({
+      allowed_routes: ['/v1/*'],
+      budget_id: 'tier-a',
+      models: ['m'],
+      team_id: 't',
+    });
+  });
+});
+
+describe('clearing is an explicit declaration', () => {
+  test('[] and null clear a live scope, and the update body says so', async () => {
+    const fake = newFake({ budgetSeed: [tier('old-tier')], keySeed: [scoped()] });
+    await keyStack(fake).deploy(
+      declare({
+        allowedRoutes: [],
+        budgetId: null,
+        duration: null,
+        keyAlias: 'seat-a',
+        models: [],
+        teamId: null,
+      }),
+      { adopt: true },
+    );
+    expect(fake.keys.writes()).toEqual([
+      {
+        body: {
+          allowed_routes: [],
+          budget_id: null,
+          duration: null,
+          key_alias: 'seat-a',
+          models: [],
+          team_id: null,
+        },
+        path: '/key/update',
+      },
+    ]);
+  });
+
+  test('a declared null on a key that already has nothing is quiet', () => {
+    const live = toAttributes(liveRow());
+    expect(
+      differing(live, { budgetId: null, duration: null, keyAlias: 'seat-a', teamId: null }),
+    ).toEqual([]);
+  });
+});
+
+describe('form helpers', () => {
+  const live = toAttributes(scoped());
+
+  test('differing names nothing the declaration does not', () => {
+    expect(differing(live, { keyAlias: 'seat-a' })).toEqual([]);
+    expect(differing(live, { keyAlias: 'seat-a', models: ['other'] })).toEqual(['models']);
+  });
+
+  test('a new key is sent only what is declared, and a declared null is not sent', () => {
+    const secret = Redacted.make(FAKE_KEY);
+    expect(
+      Object.keys(createBody({ budgetId: null, keyAlias: 'seat-a', teamId: null }, secret)),
+    ).toEqual(['key', 'key_alias']);
+  });
+});