@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/model-form.ts

@@ -0,0 +1,223 @@
+/**
+ * Refusals, wire bodies, the read shape and the comparison for `LiteLLM.Model`, testable without
+ * a server. Credential handling is model-credential.ts's; the URL rules are mcp-server-url.ts's.
+ *
+ * ⛔ WHAT IS COMPARED, WITH ENCRYPTION IN MIND. LiteLLM stores `litellm_params` encrypted when the
+ *   proxy runs with a database master key (`prisma_client.py`, `encrypt_value`, tag v1.103.0) and
+ *   answers a row whose `litellm_params` are decrypted, with `api_key` stripped (measured at
+ *   v1.103.0) — `/v2/model/info`'s docstring still says api keys and api_base are left out. So:
+ *   - `model_name`, `model_info.id`, `mode`, `base_model` and `access_groups` are compared from
+ *     the fields the read returns.
+ *   - `model`, `api_base` and `api_key` are compared through a DIGEST of the DECLARED values
+ *     (`declaredDigest`), carried in attributes as `paramsSeal`, never a digest of the live row.
+ *     A plan therefore reports drift when the declaration changes and stays quiet when the proxy
+ *     hides a field it was told before — the false-drift answer the encrypted row leaves no other
+ *     way to. A field the proxy DOES return (`model`) is additionally compared when the read
+ *     carries it; the seal is what decides when the read says nothing.
+ * ⛔ A LIVE `api_key` IS NEVER OVERWRITTEN BY AN ADOPTED ROW'S NOTHING. `apiKey` omitted on an
+ *   adopted row sends no `api_key` and the live reference is kept; `differing` reports no drift
+ *   for it. Declaring `apiKey` is what moves the row onto `os.environ/NAME`.
+ * ⛔ EVERYTHING AN EXISTING ROW NEEDS GOES TO ONE PATCH `/model/{model_id}/update`. At the tag
+ *   the SDK was generated from (OpenAPI 1.103.0), POST `/model/update`'s `update_model` REBUILDS
+ *   `litellm_params` from the parsed request model and REPLACES the column: a key the model does
+ *   not declare (`extra_headers`, `weight`, `order`) is DELETED from the stored row, and a
+ *   non-`None` pydantic default (`false` on the five flags in `LEAVE_ALONE_PARAMS`) overwrites
+ *   it — measured on a throwaway 1.103.0 proxy, and the reason a params POST is never sent. The
+ *   PATCH route's `update_db_model` instead MERGES: sent keys land, the rest of the row is
+ *   preserved, and a JSON `null` keeps the stored value. So one PATCH carries the managed
+ *   `litellm_params` (with `null` for those five flags), the `model_name` when it changed, and
+ *   the `model_info` fields — `access_groups`, `mode`, `base_model`, and the row's own `id`, so
+ *   an adopt-by-id re-affirms the row it pinned. `model_name` is sent only when it changed,
+ *   because a same-name write would collide with another deployment in the group (model.ts).
+ */
+import type * as models from '@distilled.cloud/litellm/model_management';
+import {
+  type ModelAttributes,
+  type ModelProps,
+  hasProviderPrefix,
+  isBlank,
+} from './model-types.ts';
+import { redactUrl, urlProblem } from './mcp-server-url.ts';
+import { declaredValues, sealFromValues } from './model-credential.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Pure: no environment, no server. */
+export const firstProblem = (props: ModelProps): string | undefined => {
+  if (isBlank(props.modelName) || props.modelName !== props.modelName.trim()) {
+    return '`modelName` must be a non-empty string without leading or trailing whitespace';
+  }
+  if (props.id !== undefined && isBlank(props.id)) {
+    return '`id` must be a non-empty string when declared';
+  }
+  if (isBlank(props.model)) return '`model` must be a non-empty string';
+  if (!hasProviderPrefix(props.model)) {
+    return `\`model\` must carry a provider prefix, e.g. "xai/${props.model}": LiteLLM routes by it`;
+  }
+  if (
+    props.model.toLowerCase().startsWith('openai/') &&
+    props.modelName.toLowerCase().startsWith('grok')
+  ) {
+    return '`model` must not use the "openai/" prefix on a grok group: Grok is xAI, declare "xai/…"';
+  }
+  if (props.apiBase !== undefined) {
+    const url = urlProblem(props.apiBase);
+    if (url !== undefined) return url;
+  }
+  if (
+    props.apiKey !== undefined &&
+    (typeof props.apiKey !== 'object' || typeof props.apiKey.fromEnv !== 'string')
+  ) {
+    return "`apiKey` takes `{ fromEnv: 'NAME' }`, never a value: the value would land in Alchemy's unencrypted state";
+  }
+  if (props.apiKey !== undefined && isBlank(props.apiKey.fromEnv)) {
+    return '`apiKey.fromEnv` must name an environment variable';
+  }
+  return undefined;
+};
+
+/** The digest of the DECLARED values, for `paramsSeal`. Pure: no environment, no lookup. */
+export const declaredDigest = (props: ModelProps): string => sealFromValues(declaredValues(props));
+
+const sameSet = (live: readonly string[], declared: readonly string[]): boolean =>
+  new Set(live).size === new Set(declared).size && declared.every((entry) => live.includes(entry));
+
+/**
+ * Wire names of the fields where the live row and the declaration disagree.
+ *
+ * `model` is compared only when the read carries it (an encrypted row omits it); the seal decides
+ * otherwise, and model.ts's diff turns a changed seal into an update. `model_name` mismatch on a
+ * pinned id is identity drift — replace in model.ts, update here only when the name changed and
+ * the id stayed.
+ */
+export const differing = (live: ModelAttributes, props: ModelProps): readonly string[] => {
+  const out: string[] = [];
+  if (live.modelName !== props.modelName) out.push('model_name');
+  if (live.model !== null && live.model !== props.model) {
+    out.push('model');
+  }
+  if (props.mode !== undefined && live.mode !== props.mode) out.push('mode');
+  if (props.baseModel !== undefined && live.baseModel !== props.baseModel) out.push('base_model');
+  if (!sameSet(live.accessGroups, props.accessGroups ?? [])) out.push('access_groups');
+  return out;
+};
+
+/**
+ * One row of `/model/info`, as attributes. ⛔ Copies no `litellm_params` field but `model`, and
+ * only when the read returns an OBJECT: the fields a row hides (`api_key` is stripped at
+ * v1.103.0) are never mistaken for declared values — `api_base` and any `api_key` are never
+ * copied at all. `dbModel` records `model_info.db_model` (false = served from the proxy's config
+ * file), defaulting to true when the read omits it. The digest is the caller's (model.ts fills
+ * `paramsSeal` from state, a row cannot supply one).
+ */
+export const toAttributes = (row: Record<string, unknown>): ModelAttributes => {
+  const info = (row['model_info'] ?? {}) as Record<string, unknown>;
+  const params = row['litellm_params'];
+  const carriedModel =
+    typeof params === 'object' && params !== null
+      ? (params as Record<string, unknown>)['model']
+      : undefined;
+  const id = row['id'] ?? info['id'];
+  return {
+    accessGroups: Array.isArray(info['access_groups'])
+      ? (info['access_groups'] as string[]).map(String)
+      : [],
+    baseModel: typeof info['base_model'] === 'string' ? info['base_model'] : null,
+    dbModel: info['db_model'] === false ? false : true,
+    id: String(id),
+    mode: typeof info['mode'] === 'string' ? info['mode'] : null,
+    model: typeof carriedModel === 'string' ? redactUrl(carriedModel) : null,
+    modelName: String(row['model_name'] ?? ''),
+    paramsSeal: '',
+  };
+};
+
+/**
+ * `litellm_params` fields whose pydantic default is `False`, not `None` (`litellm/types/router.py`
+ * at v1.103.0). A params write parses the request model, which fills every unset field, so an
+ * omitted key is written `false`; JSON `null` is the `None` that keeps the stored value. Create
+ * does not send them: a new row should take the vendor default.
+ */
+const LEAVE_ALONE_PARAMS = [
+  'allow_client_keepalive_override',
+  'merge_reasoning_content_in_choices',
+  'use_in_pass_through',
+  'use_litellm_proxy',
+  'use_xai_oauth',
+] as const;
+
+/** The managed `litellm_params` a create sends — with the credential in reference form. */
+const managedParams = (props: ModelProps) => {
+  const params: Record<string, unknown> = { model: props.model };
+  if (props.apiBase !== undefined) params['api_base'] = props.apiBase;
+  if (props.apiKey !== undefined) params['api_key'] = `os.environ/${props.apiKey.fromEnv}`;
+  return params;
+};
+
+/**
+ * The same set for a PATCH, plus `null` for every non-`None` default this resource does not own.
+ * The PATCH merge keeps the stored value for `None`, so the nulls are what stop a params write
+ * clobbering those five flags.
+ */
+const patchParams = (props: ModelProps): Record<string, unknown> => ({
+  ...managedParams(props),
+  ...Object.fromEntries(LEAVE_ALONE_PARAMS.map((key) => [key, null])),
+});
+
+/**
+ * ⚠️ `Record`, then a widening cast in the callers, ON PURPOSE: the generated 1.103.0 request
+ *   schema declares neither `access_groups` nor `mode` on `model_info`, while the vendor routes
+ *   on both (`model/types.py`'s `access_groups`, the read's own docstring) and the read ANSWERS
+ *   both. `modelInfoOf` returns the plain object and the wire probe's runtime encode carries
+ *   unknown keys through (measured: the fake receives `model_info.id` and `access_groups` the
+ *   typed struct does not declare).
+ */
+const modelInfoOf = (props: ModelProps): Record<string, unknown> => ({
+  ...(props.baseModel === undefined ? {} : { base_model: props.baseModel }),
+  ...(props.mode === undefined ? {} : { mode: props.mode }),
+  // ★ ALWAYS SENT: `accessGroups` is compared with a default empty set (model-types.ts), so an
+  //   omitted list is a declared "no groups" — a partial update must be able to clear them, the
+  //   way a budget's soft-only declaration clears max_budget. `mode`/`base_model` are compared
+  //   only when declared, so their omission really does leave the live value alone.
+  access_groups: [...(props.accessGroups ?? [])],
+  id: null,
+});
+
+/** A create names the group and pins the id it asked for on `model_info` of the POST body. */
+export const createBody = (
+  props: ModelProps,
+  modelId: string,
+): models.AddNewModelModelNewPostRequest => {
+  const body: Record<string, unknown> = {
+    litellm_params: managedParams(props),
+    model_info: { ...modelInfoOf(props), id: modelId },
+    model_name: props.modelName,
+  };
+  return body as unknown as models.AddNewModelModelNewPostRequest;
+};
+
+/**
+ * PATCH `/model/{model_id}/update`: everything an existing row needs, in the ONE write a
+ * converge fires (model.ts). `update_db_model` MERGES (v1.103.0, measured), so:
+ *   - `litellm_params` carries the managed keys (with `null` for the five non-`None` defaults
+ *     this resource does not own); the merge keeps every stored key the declaration does not
+ *     own (`extra_headers`, `weight`, `order`), which is exactly what POST `/model/update`
+ *     would DELETE by rebuilding the column.
+ *   - `model_info` carries `access_groups` (always present: an omitted list is "no groups" and
+ *     must be able to clear), `mode` and `base_model` only when declared, and the row's own
+ *     `id`, so an adopt-by-id re-affirms the row it pinned.
+ *   - `model_name` only when it changed: a same-name write would collide with a sibling
+ *     deployment in the group (model.ts). Not a seal stamp: a matching row records `paramsSeal`
+ *     locally (model.ts).
+ *
+ * ⚠️ `Record`, then a widening cast, for the same reason as {@link modelInfoOf}: the generated
+ *   1.103.0 `LitellmTypesRouterModelInfo` declares neither `access_groups` nor `mode`, while the
+ *   vendor model allows both (`extra="allow"`) and the read answers both.
+ */
+export const patchBody = (props: ModelProps, live: ModelAttributes): Record<string, unknown> => {
+  const renamed = live.modelName !== props.modelName;
+  return {
+    model_id: live.id,
+    litellm_params: patchParams(props),
+    model_info: { ...modelInfoOf(props), id: live.id },
+    ...(renamed ? { model_name: props.modelName } : {}),
+  };
+};

package/src/litellm/model-locate.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Which live row a `LiteLLM.Model` declaration means — `model-locate.ts`'s rules, through
+ * Alchemy's real Plan and Apply over the fake proxy (`fake-model-litellm.ts`): a shared group
+ * name is refused rather than guessed at, a pinned `id` selects exactly one row, a rename is a
+ * new group unless the id is pinned, and a changed id is a replace.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`; no environment variable is set anywhere (model.test.ts's header).
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeModelLitellm, modelRow, startFakeModelLitellm } from './fake-model-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMModel } from './model.ts';
+import type { ModelProps } from './model-types.ts';
+
+type Row = Record<string, unknown>;
+
+const KEY = 'sk-test-master';
+const stack = (fake: FakeModelLitellm) =>
+  fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: ModelProps, name = 'Grok') =>
+  Effect.gen(function* () {
+    yield* LiteLLMModel(name, props);
+  });
+
+const grok: ModelProps = {
+  apiKey: { fromEnv: 'FAKE_XAI_KEY' },
+  model: 'xai/grok-4.7',
+  modelName: 'grok',
+};
+
+test('two live rows with the declared name are refused, never guessed at', async () => {
+  const seed = [
+    modelRow({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_info: { access_groups: [], id: 'FAKE-live-id-a' },
+      model_name: 'grok',
+    }),
+    modelRow({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_info: { access_groups: [], id: 'FAKE-live-id-b' },
+      model_name: 'grok',
+    }),
+  ];
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed });
+  await expect(stack(fake).deploy(declare(grok), { adopt: true })).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a declared id pins one of two same-named rows', async () => {
+  const fake = startFakeModelLitellm({
+    masterKey: KEY,
+    seed: [
+      modelRow({
+        litellm_params: { model: 'xai/grok-4.7' },
+        model_info: { access_groups: [], id: 'FAKE-live-id-a' },
+        model_name: 'grok',
+      }),
+      modelRow({
+        litellm_params: { model: 'xai/grok-4.7' },
+        model_info: { access_groups: [], id: 'FAKE-live-id-b' },
+        model_name: 'grok',
+      }),
+    ],
+  });
+  const pinned: ModelProps = { ...grok, id: 'FAKE-live-id-b' };
+  expect(await stack(fake).deploy(declare(pinned), { adopt: true })).toEqual({ Grok: 'adopted' });
+  // The pin's declaration manages a credential the read never shows, so adopt converges it with
+  // one params PATCH (the five nulls keep unmanaged flags — model-form.ts). The sibling with the
+  // same group name is left alone: the adopted row is the one the id named.
+  expect(writesOf(fake.requests())).toContain('PATCH /model/FAKE-live-id-b/update');
+  expect(fake.models().map((row) => (row['model_info'] as Row)['id'])).toEqual([
+    'FAKE-live-id-a',
+    'FAKE-live-id-b',
+  ]);
+});
+
+test('a renamed group without a pinned id is a new group: the old row is retained', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(grok));
+  const planned = await same.deploy(declare({ ...grok, modelName: 'grok-fast' }));
+  expect(planned).toEqual({ Grok: 'replace' });
+  // ★ `defaultRemovalPolicy: 'retain'`: nothing removes the old group unless the stack opts in
+  expect(fake.models().map((row) => row['model_name'])).toEqual(['grok', 'grok-fast']);
+  const ids = fake.models().map((row) => String((row['model_info'] as Row)['id']));
+  expect(ids[0]).not.toBe(ids[1]);
+});
+
+test('a rename with a pinned id renames the same row', async () => {
+  const fake = startFakeModelLitellm({
+    masterKey: KEY,
+    seed: [
+      modelRow({
+        litellm_params: { model: 'xai/grok-4.7' },
+        model_info: { access_groups: [], id: 'FAKE-live-id' },
+        model_name: 'grok',
+      }),
+    ],
+  });
+  const engine = stack(fake);
+  const pinned: ModelProps = { ...grok, id: 'FAKE-live-id' };
+  await engine.deploy(declare(pinned), { adopt: true });
+  expect(
+    await engine.deploy(declare({ ...pinned, modelName: 'grok-fast' }), { adopt: true }),
+  ).toEqual({
+    Grok: 'update',
+  });
+  expect(fake.models()).toHaveLength(1);
+  expect(fake.models()[0]?.['model_name']).toBe('grok-fast');
+  expect(fake.bodies().at(-1)).toMatchObject({
+    model_info: { id: 'FAKE-live-id' },
+    model_name: 'grok-fast',
+  });
+});
+
+test('a changed declared id is a replace, create-first, and the old row is retained', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare({ ...grok, id: 'FAKE-id-a' }));
+  const planned = await same.deploy(declare({ ...grok, id: 'FAKE-id-b' }));
+  expect(planned).toEqual({ Grok: 'replace' });
+  expect(fake.models().map((row) => String((row['model_info'] as Row)['id']))).toEqual([
+    'FAKE-id-a',
+    'FAKE-id-b',
+  ]);
+});

package/src/litellm/model-locate.ts

@@ -0,0 +1,67 @@
+/**
+ * Which live row a `LiteLLM.Model` declaration means, and which id a new row would ask for.
+ *
+ * ★ THE LIST DECIDES FIRST. `GET /model/info` answers every deployment row in one call, so a
+ *   group name, an id and absence are all decided from it (model-operations.ts). The by-id read
+ *   is the same route with the `litellm_model_id` filter, kept only for the write-back on a row
+ *   the list may not show yet — after a create, the read-back falls back to it exactly like
+ *   `mcp-server-locate.ts` does for the registry.
+ * ⚠️ ADOPT-BY-NAME NEEDS THE LIST: a name cannot be read from the table by this route family. A
+ *   row the list lacks is adoptable only by declaring its `id`.
+ * ⛔ A NAME IS NOT UNIQUE (unlike an MCPServer): LiteLLM runs several deployments under one group
+ *   name on purpose, so a name that matches more than one listed row is refused
+ *   (`LitellmModelAmbiguousNameError`), never guessed at.
+ */
+import { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Effect from 'effect/Effect';
+import { LitellmModelAmbiguousNameError } from './model-errors.ts';
+import { listModels, readModelRow } from './model-operations.ts';
+import type { ModelAttributes, ModelProps } from './model-types.ts';
+
+/**
+ * The live row among the LISTED ones, or `undefined`. A pinned id (from state, else declared) wins;
+ * otherwise the name decides, and an ambiguous name is refused.
+ */
+export const locate = (
+  rows: readonly ModelAttributes[],
+  props: ModelProps,
+  output: ModelAttributes | undefined,
+) => {
+  const pinned = output?.id ?? props.id;
+  if (pinned !== undefined) return Effect.succeed(rows.find((row) => row.id === pinned));
+  const named = rows.filter((row) => row.modelName === props.modelName);
+  return named.length > 1
+    ? Effect.fail(
+        new LitellmModelAmbiguousNameError({
+          ids: named.map((row) => row.id),
+          modelName: props.modelName,
+        }),
+      )
+    : Effect.succeed(named[0]);
+};
+
+/** The id a create asks for: the recorded one, else the declared one, else a deterministic name. */
+export const wantedId = (
+  id: string,
+  instanceId: string,
+  props: ModelProps,
+  output: ModelAttributes | undefined,
+) =>
+  output?.id !== undefined
+    ? Effect.succeed(output.id)
+    : props.id !== undefined
+      ? Effect.succeed(props.id)
+      : createPhysicalName({ id, instanceId, lowercase: true, maxLength: 64 });
+
+/** The live row this declaration means, from the list, else from the table by the id it would use. */
+export const findLive = (
+  id: string,
+  instanceId: string,
+  props: ModelProps,
+  output: ModelAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const listed = yield* locate(yield* listModels(), props, output);
+    if (listed !== undefined) return listed;
+    return yield* readModelRow(yield* wantedId(id, instanceId, props, output));
+  });

package/src/litellm/model-operations.test.ts

@@ -0,0 +1,93 @@
+/**
+ * `LiteLLM.Model`'s operations against the fake proxy: what absence really is, and which delete
+ * failures are allowed to be swallowed. The rule under test is S21's — never decide absence from
+ * an error's text, only from a read.
+ *
+ * ⚠️ The fake's 400 on a delete of a missing id is its own choice, not a measurement of LiteLLM
+ *   1.103.0. A PATCH of a missing id is the measured 404 (fake-model-litellm.ts).
+ */
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { modelRow, startFakeModelLitellm } from './fake-model-litellm.ts';
+import { deleteModel, listModels, readModelRow } from './model-operations.ts';
+import { LitellmModelUnreadableError } from './model-errors.ts';
+import type { LitellmOpContext } from './operations.ts';
+
+const KEY = 'sk-test-master';
+
+const run = <A, E>(
+  fetchFn: typeof globalThis.fetch,
+  effect: Effect.Effect<A, E, LitellmOpContext>,
+) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+const live = modelRow({
+  litellm_params: { model: 'xai/grok-4.7' },
+  model_info: { access_groups: [], id: 'FAKE-live-id' },
+  model_name: 'grok',
+});
+
+describe('absence', () => {
+  test('a missing id is a 400, re-listed, and absent only when the list lacks it', async () => {
+    const fake = startFakeModelLitellm({ masterKey: KEY });
+    await expect(run(fake.fetch, readModelRow('FAKE-never-existed'))).resolves.toBeUndefined();
+    expect(fake.requests().map((request) => request.path)).toEqual([
+      '/model/info?litellm_model_id=FAKE-never-existed',
+      '/model/info',
+    ]);
+  });
+
+  test('a 400 on an id the list still holds is not read as absence', async () => {
+    const fake = startFakeModelLitellm({
+      byIdRefused: true,
+      masterKey: KEY,
+      seed: [live],
+    });
+    await expect(run(fake.fetch, readModelRow('FAKE-live-id'))).rejects.toThrow();
+  });
+
+  test('a row the by-id read answers is the one asked for', async () => {
+    const fake = startFakeModelLitellm({ masterKey: KEY, seed: [live] });
+    const row = await run(fake.fetch, readModelRow('FAKE-live-id'));
+    expect(row?.id).toBe('FAKE-live-id');
+  });
+
+  test('a list answer without ids is refused, never adopted', async () => {
+    const fetchFn = (async () =>
+      new Response(JSON.stringify({ data: [{ model_name: 'grok' }] }), {
+        headers: { 'content-type': 'application/json' },
+        status: 200,
+      })) as unknown as typeof globalThis.fetch;
+    const result = run(fetchFn, listModels());
+    await expect(result).rejects.toBeInstanceOf(LitellmModelUnreadableError);
+  });
+});
+
+describe('deleting a deployment', () => {
+  test('a 400 on a row that is genuinely still live is not swallowed', async () => {
+    const fake = startFakeModelLitellm({ forbidDelete: true, masterKey: KEY, seed: [live] });
+    await expect(run(fake.fetch, deleteModel('FAKE-live-id'))).rejects.toThrow();
+    expect(fake.models()).toHaveLength(1);
+  });
+
+  test('a genuinely-gone id still succeeds with no error (idempotent delete preserved)', async () => {
+    const fake = startFakeModelLitellm({ forbidDelete: true, masterKey: KEY });
+    await expect(run(fake.fetch, deleteModel('FAKE-never-existed'))).resolves.toBeUndefined();
+  });
+
+  test('a delete that lands removes the row', async () => {
+    const fake = startFakeModelLitellm({ masterKey: KEY, seed: [live] });
+    await expect(run(fake.fetch, deleteModel('FAKE-live-id'))).resolves.toBeUndefined();
+    expect(fake.models()).toEqual([]);
+  });
+});

package/src/litellm/model-operations.ts

@@ -0,0 +1,146 @@
+/**
+ * The five LiteLLM `/model/*` calls `LiteLLM.Model` uses, through the SDK's typed operations in
+ * `@distilled.cloud/litellm/model_management` (LiteLLM 1.103.0; names verified in the generated
+ * source, never guessed):
+ *
+ *   list    `getModelInfoV1ModelInfo`            GET   /model/info
+ *   read    `getModelInfoV1ModelInfo`            GET   /model/info?litellm_model_id={id}
+ *   create  `addNewModelModelNewPost`            POST  /model/new
+ *   patch   `patchModelModelModelIdUpdatePatch`  PATCH /model/{model_id}/update
+ *   delete  `deleteModelModelDeletePost`         POST  /model/delete
+ *
+ * The SDK is generated from LiteLLM OpenAPI **1.103.0** (`model_management.ts`'s header). At that
+ * tag, and at v1.100.0, `model_info_v1` raises HTTP 400 when the router has no such deployment
+ * (`proxy_server.py`, "Model id = … not found on litellm proxy"), not 404. The same 400 is also
+ * "no rights" or a bad filter. The PATCH route's `update_db_model` MERGES: `litellm_params`,
+ * `model_name` and `model_info` (`access_groups`, `mode`, `base_model`) all land without
+ * rebuilding the column, which is the one write `LiteLLM.Model` converges with (model-form.ts).
+ * POST `/model/update` REBUILDS `litellm_params` and deletes stored keys the request model does
+ * not declare, so this resource never sends it.
+ *
+ * ⛔ LIST-FIRST READS. One GET of the whole list answers a group, an id and absence unambiguously,
+ *   the way `budget-operations.ts` reads. The by-id read is the same route with the
+ *   `litellm_model_id` filter, used only where the list cannot decide (a write-back on a row the
+ *   list may not show yet).
+ * ⛔ NO MESSAGE SNIFFING (S21). The by-id read's 400 is undeclared on the generated operation, so
+ *   it decodes at run time as the shared `BadRequest` (`HTTP_STATUS_MAP`). `catchTag` matches the
+ *   tag — the same match `deleteModel` uses — so a later declared class with that tag is still
+ *   seen. A 400 is absence only when a re-list also lacks the id. A 404 is the same absence.
+ *   Any other failure propagates.
+ * ⛔ THE ROW'S PARAMS ARE NEVER READ INTO STATE: `toAttributes` (model-form.ts) copies `model`
+ *   only when `litellm_params` is an object, and never `api_base` or `api_key` — the v1.103.0
+ *   read answers params DECRYPTED but STRIPS `api_key` (measured). What was declared is
+ *   remembered as a digest instead.
+ * ⚠️ Unlike pass-through endpoints, each deployment is its own DB row: no semaphore.
+ */
+import * as models from '@distilled.cloud/litellm/model_management';
+import type { BadRequest, NotFound } from '@distilled.cloud/litellm/Errors';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { toAttributes } from './model-form.ts';
+import type { ModelAttributes } from './model-types.ts';
+import { LitellmModelUnreadableError } from './model-errors.ts';
+
+const hasRowId = (row: unknown): boolean => {
+  if (typeof row !== 'object' || row === null) return false;
+  const record = row as Record<string, unknown>;
+  const info =
+    typeof record['model_info'] === 'object' && record['model_info'] !== null
+      ? (record['model_info'] as Record<string, unknown>)
+      : {};
+  return typeof record['id'] === 'string' || typeof info['id'] === 'string';
+};
+
+/**
+ * The rows the answer carries. ⚠️ MEASURED with the fake: the SDK types
+ * `GetModelInfoV1ModelInfoResponse` as `{ body: unknown }` but hands the decoded JSON back
+ * directly (a bare array, or the proxy's `{ data: [...] }` wrapper), so accept all three shapes
+ * and refuse anything else — the same rule budget-operations.ts / mcp-server-operations.ts keep.
+ */
+const rowsOf = (
+  response: unknown,
+): Effect.Effect<readonly ModelAttributes[], LitellmModelUnreadableError> => {
+  const rows: unknown = Array.isArray(response)
+    ? response
+    : Array.isArray((response as { data?: unknown } | null)?.data)
+      ? (response as { data: unknown[] }).data
+      : (response as { body?: unknown } | null)?.body;
+  return Array.isArray(rows) && rows.every(hasRowId)
+    ? Effect.succeed((rows as Record<string, unknown>[]).map(toAttributes))
+    : Effect.fail(
+        new LitellmModelUnreadableError({
+          reason: Array.isArray(rows) ? 'a row has no model id' : 'not a list of deployments',
+        }),
+      );
+};
+
+/** Every deployment row, config-file ones included. This is the read that locates and diffs. */
+export const listModels = (): Effect.Effect<
+  readonly ModelAttributes[],
+  models.GetModelInfoV1ModelInfoError | LitellmModelUnreadableError,
+  LitellmOpContext
+> => throughFetch(models.getModelInfoV1ModelInfo({})).pipe(Effect.flatMap(rowsOf));
+
+/**
+ * One row by id, or `undefined` when the proxy has no such deployment.
+ *
+ * ⛔ A 400 IS NOT ABSENCE BY ITSELF. v1.103.0 `model_info_v1` raises 400 for a missing id, and the
+ *   same status is "no rights" or a bad filter. Re-list, and treat the id as absent only when the
+ *   list does not contain it (`deleteModel`'s rule). A 401, a 500 or a dead network says nothing
+ *   about whether the row exists and must never be read as absence. The id is re-checked on a
+ *   successful answer: a proxy that ignored the filter must not hand back some other row.
+ * ⚠️ 400 and 404 are undeclared on this GET, so they are not in its error union, but the status
+ *   map still produces those tags. Widening here is what lets `catchTag` see them.
+ */
+type ModelInfoFailure = models.GetModelInfoV1ModelInfoError | BadRequest | NotFound;
+
+export const readModelRow = (modelId: string) =>
+  throughFetch(models.getModelInfoV1ModelInfo({ litellm_model_id: modelId })).pipe(
+    Effect.mapError((error): ModelInfoFailure => error),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    Effect.catchTag('BadRequest', (error) =>
+      listModels().pipe(
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.id === modelId) ? Effect.fail(error) : Effect.succeed(undefined),
+        ),
+      ),
+    ),
+    Effect.flatMap((response) =>
+      response === undefined
+        ? Effect.succeed(undefined)
+        : rowsOf(response).pipe(Effect.map((rows) => rows.find((row) => row.id === modelId))),
+    ),
+  );
+
+/** POST /model/new. The answer carries no usable row (the fake answers `{}`), so the id asked for is the one tracked. */
+export const createModel = (body: models.AddNewModelModelNewPostRequest) =>
+  throughFetch(models.addNewModelModelNewPost(body)).pipe(Effect.asVoid);
+
+/**
+ * PATCH `/model/{model_id}/update`. The ONE write a converge of an existing row fires: its merge
+ * carries `litellm_params`, `model_name` and `model_info` together (model-form.ts).
+ */
+export const patchModel = (body: Record<string, unknown>) =>
+  throughFetch(
+    models.patchModelModelModelIdUpdatePatch(
+      body as unknown as models.PatchModelModelModelIdUpdatePatchRequest,
+    ),
+  ).pipe(Effect.asVoid);
+
+/**
+ * Idempotent BY THIS FUNCTION, not by the vendor. A `BadRequest` re-lists and is swallowed only
+ * when the id is genuinely absent — the same delete can also be refused for lack of rights or a
+ * disconnected DB, which leaves the row live and must never be reported as done
+ * (budget-operations.ts's rule; never the message text, S21).
+ */
+export const deleteModel = (modelId: string) =>
+  throughFetch(models.deleteModelModelDeletePost({ id: modelId })).pipe(
+    Effect.asVoid,
+    Effect.catchTag('BadRequest', (original) =>
+      listModels().pipe(
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.id === modelId) ? Effect.fail(original) : Effect.void,
+        ),
+      ),
+    ),
+  );