@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/fake-mcp-litellm.ts

@@ -0,0 +1,214 @@
+/**
+ * A fake of LiteLLM's `/v1/mcp/server` routes for tests — TEST ONLY, never imported by `index.ts`.
+ * Like `fake-litellm.ts` it is a `fetch` function handed to Effect's real `FetchHttpClient` through
+ * its `Fetch` reference, so a test exercises distilled's REAL path assembly, JSON encoding and
+ * status-to-error matching; only the wire responses a scenario needs are written here.
+ *
+ * ★ A SEPARATE FILE FROM `fake-litellm.ts` ON PURPOSE: that fake carries the pass-through and
+ *   budget routes and is at its size budget; a fake per route family keeps each one small.
+ * ⚠️ SHAPES ARE FROM THE GENERATED 1.103.0 SCHEMA (`mcp_management.ts`), NOT A LIVE READ. What the
+ *   real proxy does on a duplicate create, an edit of a missing id, a delete of a missing id, and
+ *   whether its list redacts `credentials` is UNMEASURED; the answers below (400, 404, 404, redacted
+ *   unless `echoCredentials`) are the fake's own choices, and every test that leans on one says so.
+ * ★ ONE RULE IS MEASURED, NOT CHOSEN: an edit that changes `auth_type` and sends no `credentials` key
+ *   clears the stored credential (litellm 1.103.0, `db.py` lines 1013-1014, read from the live
+ *   container; every static type is its own credential class). The engine tests that rely on it are
+ *   `mcp-server-retype.test.ts`.
+ * ★ THREE MORE RULES ARE MEASURED (2026-09-29, the live 1.103.0 container, read from source and, for
+ *   the alias rule, by running its own normaliser on a body): (1) `GET /v1/mcp/server` is the
+ *   in-memory REGISTRY, not the table, so a row can be committed and not listed (`registryMisses`,
+ *   `hideCreated`); the by-id `GET` reads the table first and REGISTERS the row it finds. (2) The
+ *   list's `description` is `mcp_info.description` when that key exists, else the column. (3) A
+ *   write with a `server_name` and no `alias` defaults the alias to the name and WRITES it; `-` in
+ *   either name is a 400, and a space in an alias becomes `_`.
+ * ⚠️ `servers()` RETURNS WHAT REACHED THE PROXY, credentials included, so a test can assert what
+ *   was SENT. The list route (`GET`) is what a resource can read, and it hides them by default.
+ * ★ `FAKE-*` VALUES ONLY. Nothing here is, or looks like, a real credential.
+ */
+/** One request that reached the fake. Its own type, so this file depends on no other fake. */
+export interface FakeMcpRequest {
+  readonly method: string;
+  readonly path: string;
+}
+
+type Row = Record<string, unknown>;
+
+export interface FakeMcpLitellm {
+  readonly fetch: typeof globalThis.fetch;
+  /** Every stored row exactly as the proxy holds it, `credentials` included. */
+  readonly servers: () => readonly Row[];
+  readonly requests: () => readonly FakeMcpRequest[];
+  /** The JSON bodies of every `POST`/`PUT`, in order. */
+  readonly bodies: () => readonly Row[];
+}
+
+export interface FakeMcpOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** `GET` echoes the stored `credentials` instead of hiding them (a worst-case proxy). */
+  readonly echoCredentials?: boolean;
+  /** `PUT` drops an empty list and a `false`, like a truthiness check would. */
+  readonly editIgnoresFalsy?: boolean;
+  /** `POST` ignores a supplied `server_id` and issues its own. */
+  readonly issuesOwnId?: boolean;
+  /** Every `DELETE` answers 400, whether or not the row exists (no rights). */
+  readonly forbidDelete?: boolean;
+  /** Ids committed to the table that the registry does not hold (a failed reload), so the list omits them. */
+  readonly registryMisses?: readonly string[];
+  /** A `POST` commits the row but its registry refresh fails (LiteLLM only logs it). */
+  readonly hideCreated?: boolean;
+  /**
+   * The by-id `GET` answers 403, whether or not the row exists. ⚠️ Not 500: the SDK retries 5xx with
+   * backoff (`Retry.Retry`), which would take a test tens of seconds to no purpose.
+   */
+  readonly readFails?: boolean;
+}
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+const ISSUED_ID = 'FAKE-issued-id-0001';
+
+/** A minimal 1.103.0-shaped row, as the list route returns it. */
+export const serverRow = (fields: Row): Row => ({
+  allow_all_keys: false,
+  allowed_tools: [],
+  auth_type: null,
+  mcp_access_groups: [],
+  transport: 'http',
+  ...fields,
+});
+
+/** LiteLLM's `normalize_server_name`: spaces become underscores. */
+const normalised = (name: unknown): string => String(name).replaceAll(' ', '_');
+
+/** What the list shows as `description`: `mcp_info.description` when the KEY exists, else the column. */
+const effectiveDescription = (row: Row): unknown => {
+  const info = row['mcp_info'] as Row | null | undefined;
+  if (info !== null && info !== undefined && 'description' in info) return info['description'];
+  return row['description'] === undefined || row['description'] === '' ? null : row['description'];
+};
+
+/**
+ * `validate_and_normalize_mcp_server_payload`: the alias LiteLLM will write, or `undefined` for none,
+ * or the 400 body. A `server_name` with no alias gives the alias the name.
+ */
+const aliasFor = (body: Row): { alias?: string; refusal?: string } => {
+  for (const field of ['server_name', 'alias']) {
+    if (typeof body[field] === 'string' && body[field].includes('-')) {
+      return { refusal: `Server name cannot contain '-'. Found: ${body[field]}` };
+    }
+  }
+  if (typeof body['alias'] === 'string' && body['alias'] !== '') {
+    return { alias: normalised(body['alias']) };
+  }
+  return typeof body['server_name'] === 'string' && body['server_name'] !== ''
+    ? { alias: normalised(body['server_name']) }
+    : {};
+};
+
+export const startFakeMcpLitellm = (options: FakeMcpOptions = {}): FakeMcpLitellm => {
+  const masterKey = options.masterKey ?? 'sk-test-master';
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  const requests: FakeMcpRequest[] = [];
+  const bodies: Row[] = [];
+  const misses = new Set(options.registryMisses ?? []);
+  /** The ids the in-memory registry holds. */
+  const registered = new Set(
+    rows.map((row) => String(row['server_id'])).filter((id) => !misses.has(id)),
+  );
+
+  const stored = (row: Row): Row =>
+    options.echoCredentials === true ? row : { ...row, credentials: null };
+  const listed = (row: Row): Row => ({ ...stored(row), description: effectiveDescription(row) });
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    if (request.headers.get('authorization') !== `Bearer ${masterKey}`) {
+      return json(401, { detail: 'invalid api key' });
+    }
+    if (url.pathname === '/v1/mcp/server' && request.method === 'GET') {
+      return json(200, rows.filter((row) => registered.has(String(row['server_id']))).map(listed));
+    }
+    if (url.pathname === '/v1/mcp/server' && request.method === 'POST') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const id = options.issuesOwnId === true ? ISSUED_ID : String(body['server_id']);
+      if (rows.some((row) => row['server_id'] === id)) {
+        return json(400, { detail: { error: `MCP server ${id} already exists` } });
+      }
+      const { alias, refusal } = aliasFor(body);
+      if (refusal !== undefined) return json(400, { detail: { error: refusal } });
+      const created = serverRow({ ...body, alias, server_id: id });
+      rows = [...rows, created];
+      if (options.hideCreated !== true) registered.add(id);
+      return json(200, stored(created));
+    }
+    if (url.pathname === '/v1/mcp/server' && request.method === 'PUT') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const at = rows.findIndex((row) => row['server_id'] === body['server_id']);
+      if (at === -1) return json(404, { detail: { error: 'MCP server not found' } });
+      const { alias, refusal } = aliasFor(body);
+      if (refusal !== undefined) return json(400, { detail: { error: refusal } });
+      const written: Row = { ...body, ...(alias === undefined ? {} : { alias }) };
+      const patch: Row = Object.fromEntries(
+        Object.entries(written).filter(([, value]) =>
+          options.editIgnoresFalsy === true
+            ? value !== false && !(Array.isArray(value) && value.length === 0)
+            : true,
+        ),
+      );
+      // ★ measured: a changed auth class with no `credentials` key wipes the stored credential
+      if (
+        typeof body['auth_type'] === 'string' &&
+        body['auth_type'] !== rows[at]?.['auth_type'] &&
+        !('credentials' in body)
+      ) {
+        patch['credentials'] = null;
+      }
+      rows = rows.map((row, i) => (i === at ? { ...row, ...patch } : row));
+      registered.add(String(body['server_id']));
+      return json(200, stored(rows[at] ?? {}));
+    }
+    const byId = /^\/v1\/mcp\/server\/([^/]+)$/.exec(url.pathname);
+    if (byId !== null && request.method === 'GET') {
+      if (options.readFails === true) return json(403, { detail: 'not_allowed_access' });
+      const id = decodeURIComponent(byId[1] ?? '');
+      // ★ measured: the table first (and the row is registered), then the registry by id, name or alias
+      const found =
+        rows.find((row) => row['server_id'] === id) ??
+        rows.find(
+          (row) =>
+            registered.has(String(row['server_id'])) &&
+            [row['server_id'], row['server_name'], row['alias']].includes(id),
+        );
+      if (found === undefined) {
+        return json(404, { detail: { error: `MCP Server with id ${id} not found` } });
+      }
+      registered.add(String(found['server_id']));
+      return json(200, stored(found));
+    }
+    if (byId !== null && request.method === 'DELETE') {
+      if (options.forbidDelete === true) return json(400, { detail: 'not_allowed_access' });
+      const id = decodeURIComponent(byId[1] ?? '');
+      if (!rows.some((row) => row['server_id'] === id)) {
+        return json(404, { detail: { error: `MCP server ${id} not found` } });
+      }
+      rows = rows.filter((row) => row['server_id'] !== id);
+      registered.delete(id);
+      return json(200, {});
+    }
+    return json(404, { detail: 'not found' });
+  }) as typeof globalThis.fetch;
+
+  return {
+    bodies: () => [...bodies],
+    fetch,
+    requests: () => [...requests],
+    servers: () => rows.map((row) => ({ ...row })),
+  };
+};

package/src/litellm/fake-model-litellm-post-update.ts

@@ -0,0 +1,103 @@
+/**
+ * POST /model/update handler for the fake LiteLLM proxy.
+ *
+ * Extracted from `fake-model-litellm.ts` so each file stays under the repository line cap.
+ * See that file for context on what the fake is and what is measured vs. assumed.
+ */
+import type { Row } from './fake-model-litellm.ts';
+
+type PostUpdateOptions = Readonly<{
+  /** `POST /model/update` drops a `false` and an empty list, like a truthiness check would. */
+  readonly editIgnoresFalsy?: boolean;
+  /**
+   * `POST /model/update` parses `litellm_params` the way v1.103.0 `updateLiteLLMParams` does:
+   * every unset field is filled with its pydantic default before the write. `None` keeps the
+   * stored value; a non-`None` default (`false` on the five flags below) overwrites it.
+   */
+  readonly fillsParamDefaults?: boolean;
+}>;
+
+/**
+ * The five `litellm_params` fields whose pydantic default is `False`, not `None`
+ * (`litellm/types/router.py` at v1.103.0). `updateLiteLLMParams` fills every unset field with
+ * that default before `update_model` walks the parsed model, so an omitted key is written
+ * `false` and a stored `true` is clobbered. A JSON `null` is the `None` that keeps the stored
+ * value. A key the parsed model does not declare survives PATCH but is DELETED by POST's
+ * column rebuild (`extra_headers`, `weight`, `order` have no field).
+ */
+const NON_NONE_PARAM_DEFAULTS = [
+  'use_in_pass_through',
+  'use_litellm_proxy',
+  'use_xai_oauth',
+  'allow_client_keepalive_override',
+  'merge_reasoning_content_in_choices',
+] as const;
+
+/**
+ * v1.103.0 `updateLiteLLMParams`: an omitted field takes its pydantic default. The five flags
+ * default to `False`, not `None`. An explicit `null` stays `null` (it was set, not omitted) so a
+ * later `exclude_none` can drop it and keep the stored value.
+ */
+export const withOmittedFalseDefaults = (sent: Row): Row => {
+  const filled: Row = { ...sent };
+  for (const key of NON_NONE_PARAM_DEFAULTS) {
+    if (!(key in filled)) filled[key] = false;
+  }
+  return filled;
+};
+
+export interface PostModelUpdateResult {
+  readonly response: Response;
+  /** Merged row to write back into the table. */
+  readonly merged: Row;
+  /** Index into the original rows array that `merged` should replace. */
+  readonly at: number;
+}
+
+/**
+ * Handle `POST /model/update`.
+ *
+ * ⛔ v1.103.0 `update_model` REBUILDS `litellm_params`: it parses the request model
+ *   (every unset field filled with its pydantic default, `None` keeps the stored value)
+ *   and REPLACES the column, so a stored key the model does not declare is DELETED.
+ *   `editIgnoresFalsy` models a proxy that REFUSES a `false` or an empty list: the edit
+ *   never lands, so the row's current value survives. Drop the incoming falsy value
+ *   BEFORE the rebuild — filtering after erases the field and hides the dropped edit.
+ */
+export const handlePostModelUpdate = (args: {
+  readonly body: Row;
+  readonly rows: readonly Row[];
+  readonly rowId: (row: Row) => string;
+  readonly json: (status: number, body: unknown) => Response;
+  readonly options: PostUpdateOptions;
+}): PostModelUpdateResult => {
+  const { body, rows, rowId, json, options } = args;
+  const id = String(((body['model_info'] ?? {}) as Row)['id']);
+  const at = rows.findIndex((row) => rowId(row) === id);
+  if (at === -1) {
+    return { at: -1, merged: {}, response: json(400, { detail: { error: 'model not found' } }) };
+  }
+  const dropFalsy = <T extends Row>(incoming: T): T =>
+    options.editIgnoresFalsy === true
+      ? (Object.fromEntries(
+          Object.entries(incoming).filter(
+            ([, value]) => value !== false && !(Array.isArray(value) && value.length === 0),
+          ),
+        ) as T)
+      : incoming;
+  const current = rows[at] as Row;
+  const sent = dropFalsy((body['litellm_params'] ?? {}) as Row);
+  const stored = { ...(current['litellm_params'] as Row) };
+  const parsed = options.fillsParamDefaults === true ? withOmittedFalseDefaults(sent) : sent;
+  // `None` keeps the stored value; every other field is the parsed model's — nothing else
+  // of the stored row survives the rebuild (undeclared keys are dropped).
+  const rewritten = Object.fromEntries(
+    Object.entries(parsed).map(([key, value]) => [key, value === null ? stored[key] : value]),
+  );
+  const merged: Row = {
+    ...current,
+    ...(body['model_name'] === undefined ? {} : { model_name: body['model_name'] }),
+    ...(body['litellm_params'] === undefined ? {} : { litellm_params: rewritten }),
+  };
+  return { at, merged, response: json(200, {}) };
+};

package/src/litellm/fake-model-litellm.ts

@@ -0,0 +1,233 @@
+/**
+ * A fake of LiteLLM's `/model/*` routes for tests — TEST ONLY, never imported by `index.ts`.
+ * Like `fake-mcp-litellm.ts` it is a `fetch` function handed to Effect's real `FetchHttpClient`
+ * through its `Fetch` reference, so a test exercises distilled's REAL path assembly, JSON encoding
+ * and status-to-error matching; only the wire responses a scenario needs are written here.
+ *
+ * ★ A SEPARATE FILE FROM `fake-litellm.ts` ON PURPOSE: that fake carries the pass-through and
+ *   budget routes and is at its size budget; a fake per route family keeps each one small.
+ * ⚠️ SHAPES ARE FROM THE GENERATED 1.103.0 SCHEMA (`model_management.ts`), NOT A LIVE READ. A
+ *   missing id on the by-id read is HTTP 400, measured in `model_info_v1` at v1.100.0 and
+ *   v1.103.0. POST `/model/update` REBUILDS `litellm_params` from the parsed request model and
+ *   REPLACES the column (deleting stored keys the model does not declare); PATCH merges
+ *   (`update_db_model`) after `updateLiteLLMParams` and `exclude_none`. A PATCH of a missing id
+ *   is HTTP 404 (`patch_model` at v1.103.0). A duplicate create and a delete of a missing id
+ *   stay the fake's own 400s, and every test that leans on one says so.
+ * ★ THE LIST IS THE TABLE, the way `GET /model/info` reads: a row is listed as soon as it is
+ *   committed — no in-memory registry like the MCP server list. `listOmits` models the opposite,
+ *   rows the list does not answer but the by-id read does, UNMEASURED, to exercise the read-back
+ *   fallback (model-operations.ts).
+ * ★ THE READ ANSWERS THE MEASURED 1.103.0 SHAPE: `litellm_params` DECRYPTED but with `api_key`
+ *   STRIPPED (measured on a live proxy; see the comment on `readable`), while the stored row
+ *   keeps every key it was sent, so `models()` still asserts what a resource SENT.
+ * ★ `FAKE-*` VALUES ONLY. Nothing here is, or looks like, a real credential.
+ */
+import {
+  handlePostModelUpdate,
+  withOmittedFalseDefaults,
+} from './fake-model-litellm-post-update.ts';
+
+/** One request that reached the fake. Its own type, so this file depends on no other fake. */
+export interface FakeModelRequest {
+  readonly method: string;
+  readonly path: string;
+}
+
+export type Row = Record<string, unknown>;
+
+export interface FakeModelLitellm {
+  readonly fetch: typeof globalThis.fetch;
+  /** Every stored row exactly as the proxy holds it, `litellm_params` included. */
+  readonly models: () => readonly Row[];
+  readonly requests: () => readonly FakeModelRequest[];
+  /** The JSON bodies of every `POST`, in order. */
+  readonly bodies: () => readonly Row[];
+  /**
+   * The next `count` successful `POST /model/new` calls each make the following `GET /model/info`
+   * answer 500 once — a read-back that fails after the row is committed.
+   */
+  readonly failNextReadBacks: (count: number) => void;
+}
+
+export interface FakeModelOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** `POST /model/new` ignores the supplied `model_info.id` and issues its own. */
+  readonly issuesOwnId?: boolean;
+  /** Every `POST /model/delete` answers 400, whether or not the row exists (no rights). */
+  readonly forbidDelete?: boolean;
+  /**
+   * Every by-id `GET /model/info` answers 400 even when the row is listed. Models "no rights" /
+   * a bad filter: a 400 is absence only when a re-list also lacks the id (model-operations.ts).
+   */
+  readonly byIdRefused?: boolean;
+  /** `POST /model/update` drops a `false` and an empty list, like a truthiness check would. */
+  readonly editIgnoresFalsy?: boolean;
+  /**
+   * `POST /model/update` and `PATCH /model/{id}/update` parse `litellm_params` the way v1.103.0
+   * `updateLiteLLMParams` does: every unset field is filled with its pydantic default before the
+   * write. `None` keeps the stored value; a non-`None` default (`false` on the five flags) overwrites
+   * it. POST then REPLACES the column. PATCH merges after `exclude_none`, so an explicit JSON `null`
+   * is dropped and the stored value survives, while an omitted flag is written `false`.
+   */
+  readonly fillsParamDefaults?: boolean;
+  /** Ids committed to the table that the list omits; the by-id read still answers them. */
+  readonly listOmits?: readonly string[];
+}
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+const ISSUED_ID = 'FAKE-issued-id-0001';
+
+/** A minimal 1.103.0-shaped row, as the table holds it: the id lives in `model_info`. */
+export const modelRow = (fields: Row): Row => ({
+  litellm_params: {},
+  model_info: {},
+  model_name: '',
+  ...fields,
+});
+
+/** The id of a stored row, wherever the proxy carried it. */
+const rowId = (row: Row): string => {
+  const info = (row['model_info'] ?? {}) as Row;
+  return String(row['id'] ?? info['id']);
+};
+
+export const startFakeModelLitellm = (options: FakeModelOptions = {}): FakeModelLitellm => {
+  const masterKey = options.masterKey ?? 'sk-test-master';
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  const requests: FakeModelRequest[] = [];
+  const bodies: Row[] = [];
+  const omitted = new Set(options.listOmits ?? []);
+  let readBacksLeft = 0;
+  let failNextGet = false;
+
+  /**
+   * The measured 1.103.0 read: `litellm_params` decrypted but with `api_key` stripped — never a
+   * ciphertext object, never the credential reference. The stored row keeps everything
+   * (`models()`), so what was SENT stays assertable.
+   */
+  const readable = (row: Row): Row => {
+    const { api_key: _stripped, ...params } = row['litellm_params'] as Row;
+    return { ...row, litellm_params: params };
+  };
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    if (request.headers.get('authorization') !== `Bearer ${masterKey}`) {
+      return json(401, { detail: 'invalid api key' });
+    }
+    if (url.pathname === '/model/info' && request.method === 'GET') {
+      if (failNextGet) {
+        failNextGet = false;
+        return json(500, { detail: { error: 'injected read-back failure' } });
+      }
+      const wanted = url.searchParams.get('litellm_model_id');
+      const listed = rows.filter((row) => !omitted.has(rowId(row)));
+      if (wanted === null) return json(200, { data: listed.map(readable) });
+      const found =
+        listed.find((row) => rowId(row) === wanted) ?? rows.find((row) => rowId(row) === wanted);
+      // ★ v1.100.0 and v1.103.0 `model_info_v1` raise HTTP 400 when the router has no such
+      //   deployment (`proxy_server.py`, "Model id = … not found on litellm proxy"), not 404.
+      //   The SDK still decodes that undeclared 400 as BadRequest. A 400 is also "no rights".
+      if (options.byIdRefused === true || found === undefined) {
+        return json(400, {
+          detail: { error: `Model id = ${wanted} not found on litellm proxy` },
+        });
+      }
+      return json(200, { data: [readable(found)] });
+    }
+    if (url.pathname === '/model/new' && request.method === 'POST') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const info = { ...((body['model_info'] ?? {}) as Row) };
+      if (options.issuesOwnId === true) info['id'] = ISSUED_ID;
+      const id = String(info['id']);
+      if (rows.some((row) => rowId(row) === id)) {
+        return json(400, { detail: { error: `Model with id ${id} already exists` } });
+      }
+      rows = [...rows, modelRow({ ...body, model_info: info })];
+      if (readBacksLeft > 0) {
+        readBacksLeft -= 1;
+        failNextGet = true;
+      }
+      return json(200, {});
+    }
+    if (url.pathname === '/model/update' && request.method === 'POST') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const update = handlePostModelUpdate({ body, json, options, rowId, rows });
+      if (update.at !== -1) {
+        rows = rows.map((row, i) => (i === update.at ? update.merged : row));
+      }
+      return update.response;
+    }
+    const patch = /^\/model\/([^/]+)\/update$/.exec(url.pathname);
+    if (patch !== null && request.method === 'PATCH') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const id = decodeURIComponent(patch[1] ?? '');
+      const at = rows.findIndex((row) => rowId(row) === id);
+      // ★ v1.103.0 `patch_model` answers 404 when the table has no such id
+      //   (`model_management_endpoints.py`, `HTTP_404_NOT_FOUND`), not 400.
+      if (at === -1) return json(404, { detail: { error: `Model ${id} not found on proxy.` } });
+      // ★ v1.103.0 `update_db_model` MERGES onto the stored row (the opposite of POST's rebuild).
+      //   An empty access_groups clears the groups. editIgnoresFalsy drops that clear. The
+      //   params parse below is `updateLiteLLMParams` plus `exclude_none` when the flag is on.
+      const dropFalsy = <T extends Row>(incoming: T): T =>
+        options.editIgnoresFalsy === true
+          ? (Object.fromEntries(
+              Object.entries(incoming).filter(
+                ([, value]) => value !== false && !(Array.isArray(value) && value.length === 0),
+              ),
+            ) as T)
+          : incoming;
+      const current = rows[at] as Row;
+      const info = dropFalsy((body['model_info'] ?? {}) as Row);
+      const sent = dropFalsy((body['litellm_params'] ?? {}) as Row);
+      const stored = { ...(current['litellm_params'] as Row) };
+      // ★ v1.103.0 parses `litellm_params` as `updateLiteLLMParams` (omitted flags become
+      //   `false`) and then `model_dump(exclude_none=True)`. An explicit JSON `null` is `None`
+      //   and is dropped, so the stored value survives; an omitted flag is written `false`.
+      const parsed = options.fillsParamDefaults === true ? withOmittedFalseDefaults(sent) : sent;
+      const applied = Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== null));
+      const params: Row = { ...stored, ...applied };
+      const merged: Row = {
+        ...current,
+        ...(body['model_name'] === undefined ? {} : { model_name: body['model_name'] }),
+        ...(body['litellm_params'] === undefined ? {} : { litellm_params: params }),
+        ...(body['model_info'] === undefined
+          ? {}
+          : { model_info: { ...(current['model_info'] as Row), ...info } }),
+      };
+      rows = rows.map((row, i) => (i === at ? merged : row));
+      return json(200, {});
+    }
+    if (url.pathname === '/model/delete' && request.method === 'POST') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      if (options.forbidDelete === true) return json(400, { detail: 'not_allowed_access' });
+      const id = String(body['id']);
+      if (!rows.some((row) => rowId(row) === id)) {
+        return json(400, { detail: { error: `model with id ${id} not found` } });
+      }
+      rows = rows.filter((row) => rowId(row) !== id);
+      return json(200, {});
+    }
+    return json(404, { detail: 'not found' });
+  }) as typeof globalThis.fetch;
+
+  return {
+    bodies: () => [...bodies],
+    failNextReadBacks: (count) => {
+      readBacksLeft = count;
+    },
+    fetch,
+    models: () => rows.map((row) => ({ ...row })),
+    requests: () => [...requests],
+  };
+};

package/src/litellm/fake-policy-attachment-litellm.ts

@@ -0,0 +1,97 @@
+/**
+ * A fake of LiteLLM's `/policies/attachments` routes for tests — TEST ONLY. Skeleton and the rules
+ * every fake follows: fake-registry-base.ts.
+ *
+ * ★ MEASURED FROM THE LIVE 1.103.0 CONTAINER'S SOURCE (2026-09-30, `policy_endpoints.py` and
+ *   `attachment_registry.py`, read, not called): a create needs the policy to have a PRODUCTION version
+ *   (404 otherwise), refuses a CONCRETE team, key or model selector that resolves to nothing (400;
+ *   wildcards are let through), and answers the row with a proxy-issued id; the list merges in config.yaml
+ *   attachments (`definition_location: "config"`, ids `config-<n>`); a delete of a missing id is a 404.
+ *   There is NO update route, and the fake answers 405 to one so a resource that tried would fail.
+ * ⚠️ NOT MODELLED: the in-memory registry and how a request is matched (`policy_matcher.py`).
+ */
+import { FAKE_KEY, type FakeRecord, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakePolicyAttachmentLitellm extends FakeRecord {
+  /** Every stored database attachment, exactly as the proxy holds it. */
+  readonly attachments: () => readonly Row[];
+}
+
+export interface FakePolicyAttachmentOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** Policies that have a production version. A create for any other name is a 404. */
+  readonly policies?: readonly string[];
+  /** Team aliases that exist. A concrete (non-wildcard) `teams` entry outside this set is a 400. */
+  readonly knownTeams?: readonly string[];
+  /** Attachments defined in config.yaml: they appear in the list and can never be deleted. */
+  readonly configAttachments?: readonly Row[];
+  /** `DELETE` answers 403, as for a key that is not allowed. */
+  readonly forbidDelete?: boolean;
+}
+
+export const attachmentRow = (fields: Row): Row => ({
+  keys: [],
+  models: [],
+  priority: null,
+  scope: null,
+  tags: [],
+  teams: [],
+  ...fields,
+});
+
+export const startFakePolicyAttachmentLitellm = (
+  options: FakePolicyAttachmentOptions = {},
+): FakePolicyAttachmentLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  let issued = 0;
+
+  const record = recordingFetch(options.masterKey ?? FAKE_KEY, ({ body, request, url }) => {
+    const byId = /^\/policies\/attachments\/([^/]+)$/.exec(url.pathname);
+    if (url.pathname === '/policies/attachments/list' && request.method === 'GET') {
+      const config = (options.configAttachments ?? []).map((row, index) =>
+        attachmentRow({ attachment_id: `config-${index}`, definition_location: 'config', ...row }),
+      );
+      const all = [...rows, ...config];
+      return json(200, { attachments: all, total_count: all.length });
+    }
+    if (url.pathname === '/policies/attachments' && request.method === 'POST') {
+      if (!(options.policies ?? []).includes(String(body['policy_name']))) {
+        return json(404, {
+          detail: `Policy '${String(body['policy_name'])}' not found. Create the policy first.`,
+        });
+      }
+      const teams = (body['teams'] as string[] | undefined) ?? [];
+      const missing = teams.filter(
+        (team) => !team.includes('*') && !(options.knownTeams ?? []).includes(team),
+      );
+      if (missing.length > 0) return json(400, { detail: `Unknown team: ${missing.join(', ')}` });
+      issued += 1;
+      const created = attachmentRow({
+        attachment_id: `FAKE-attachment-${String(issued).padStart(4, '0')}`,
+        keys: body['keys'] ?? [],
+        models: body['models'] ?? [],
+        policy_name: body['policy_name'],
+        priority: body['priority'] ?? null,
+        scope: body['scope'] ?? null,
+        tags: body['tags'] ?? [],
+        teams,
+      });
+      rows = [...rows, created];
+      return json(200, created);
+    }
+    if (byId !== null && request.method === 'DELETE') {
+      const id = decodeURIComponent(byId[1] ?? '');
+      if (options.forbidDelete === true) return json(403, { detail: 'not_allowed_access' });
+      if (!rows.some((row) => row['attachment_id'] === id)) {
+        return json(404, { detail: `Attachment with ID ${id} not found` });
+      }
+      rows = rows.filter((row) => row['attachment_id'] !== id);
+      return json(200, { message: `Attachment ${id} deleted successfully` });
+    }
+    return json(405, { detail: `unhandled ${request.method} ${url.pathname}` });
+  });
+
+  return { ...record, attachments: () => rows.map((row) => ({ ...row })) };
+};