@homeflare/alchemy 0.43.0 → 0.44.0

package/src/litellm/access-group-types.ts

@@ -0,0 +1,49 @@
+/**
+ * What a `LiteLLM.AccessGroup` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ THIS IS THE UNIFIED ACCESS GROUP, `LiteLLM_AccessGroupTable` (`/v1/unified_access_group`), not
+ *   the two other things LiteLLM calls an "access group": a MODEL access group (`access_groups` in a
+ *   model's `model_info`) and an MCP access group (a bare name on an MCP server row, referenced by
+ *   `object_permission.mcp_access_groups`). A unified group bundles models, MCP servers and agents
+ *   under one name and attaches to teams and keys (docs.litellm.ai/docs/proxy/access_groups).
+ * ⚠️ TOOLSETS ARE NOT IN IT. `AccessGroupCreateRequest` (`litellm/types/access_group.py`, 1.103.0)
+ *   has `access_model_names`, `access_mcp_server_ids`, `access_agent_ids`, `assigned_team_ids` and
+ *   `assigned_key_ids` and no toolset field. A toolset is granted through `object_permission.mcp_toolsets`
+ *   on a team or key (`LiteLLM.Team`), not through a group.
+ * ★ MODELS ARE MODEL NAMES, MCP SERVERS ARE SERVER IDS. `access_model_names` holds the `model_name`
+ *   a caller sends (`cf-code`), and `access_mcp_server_ids` holds `server_id`s. Declare a server's id
+ *   with `server.serverId` (a `LiteLLM.MCPServer`) so the dependency edge exists.
+ * ⚠️ NOT MODELLED, on purpose: `assigned_team_ids`, `assigned_key_ids` and `access_agent_ids`. A
+ *   team's group membership is declared on the TEAM (`accessGroupIds`), and LiteLLM mirrors it into
+ *   `assigned_team_ids` in the same transaction; two resources writing one edge would fight. Agents
+ *   are not managed here. None of the three is ever sent, and the update is a partial one, so an
+ *   adopted group keeps whatever it has there.
+ */
+export interface AccessGroupProps {
+  /**
+   * The group's name, and the way an existing row is ADOPTED: `access_group_name` is UNIQUE in the
+   * table (`access_group_endpoints.py` finds it with `find_unique`), so the match is exact. Changing
+   * it is an update of the same row, never a replace: the id does not change.
+   */
+  readonly accessGroupName: string;
+  /** Compared only when declared: adopting a row never clears text a person wrote. Blank is refused. */
+  readonly description?: string;
+  /**
+   * `model_name`s the group grants, compared as a SET and ALWAYS compared (default `[]`): it is an
+   * access grant, so an adopted group that grants more than declared is corrected, never left open.
+   * ⚠️ LiteLLM prunes a name itself when its last deployment is deleted
+   * (`management_helpers/access_group_model_sync.py`), so a plan can show an update for a model that
+   * was removed elsewhere.
+   */
+  readonly modelNames?: readonly string[];
+  /** MCP `server_id`s the group grants, compared as a set and always compared (default `[]`). */
+  readonly mcpServerIds?: readonly string[];
+}
+
+export interface AccessGroupAttributes {
+  readonly accessGroupId: string;
+  readonly accessGroupName: string;
+  readonly description: string | null;
+  readonly modelNames: readonly string[];
+  readonly mcpServerIds: readonly string[];
+}

package/src/litellm/access-group.test.ts

@@ -0,0 +1,197 @@
+/**
+ * `LiteLLM.AccessGroup` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-access-group-litellm.ts`): create, no-op, adopt, update, rename, drift and delete.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ * ⚠️ WHAT THE FAKE MODELS IS READ FROM THE 1.103.0 SOURCE, NOT MEASURED ON A LIVE PROXY (its header).
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { LiteLLMAccessGroup } from './access-group.ts';
+import { deleteAccessGroup } from './access-group-operations.ts';
+import type { AccessGroupProps } from './access-group-types.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakeAccessGroupLitellm,
+  groupRow,
+  startFakeAccessGroupLitellm,
+} from './fake-access-group-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+
+const stack = (fake: FakeAccessGroupLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: AccessGroupProps, name = 'Estate') =>
+  Effect.gen(function* () {
+    yield* LiteLLMAccessGroup(name, props);
+  });
+
+const estate: AccessGroupProps = {
+  accessGroupName: 'FAKE-estate',
+  description: 'FAKE estate group',
+  mcpServerIds: ['FAKE-server-a'],
+  modelNames: ['fake-code', 'fake-flash'],
+};
+
+test('creates a group with both grant lists, then a second deploy writes nothing', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'create' });
+  expect(fake.groups()[0]).toMatchObject({
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE estate group',
+  });
+  // ★ the id is the proxy's, and it is what the state remembers
+  expect(String(fake.groups()[0]?.['access_group_id'])).toStartWith('FAKE-group-');
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('an undeclared grant list means "grants nothing": it is sent as an empty list on create', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  await stack(fake).deploy(declare({ accessGroupName: 'FAKE-empty' }));
+  expect(fake.bodies()[0]).toMatchObject({ access_mcp_server_ids: [], access_model_names: [] });
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('a changed model set is an update that sends ONLY the field that changed', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const planned = await same.deploy(declare({ ...estate, modelNames: ['fake-code'] }));
+  expect(planned).toEqual({ Estate: 'update' });
+  expect(fake.bodies().at(-1)).toEqual({ access_model_names: ['fake-code'] });
+  expect(fake.groups()[0]?.['access_mcp_server_ids']).toEqual(['FAKE-server-a']);
+});
+
+test('a rename is an update of the SAME row: the id does not change', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  const id = fake.groups()[0]?.['access_group_id'];
+  expect(await same.deploy(declare({ ...estate, accessGroupName: 'FAKE-renamed' }))).toEqual({
+    Estate: 'update',
+  });
+  expect(fake.groups()).toHaveLength(1);
+  expect(fake.groups()[0]).toMatchObject({
+    access_group_id: id,
+    access_group_name: 'FAKE-renamed',
+  });
+});
+
+test('a live row is Unowned: refused without --adopt, taken by name with it, and a matching row writes nothing', async () => {
+  const live = groupRow({
+    access_group_id: 'FAKE-live-1',
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE estate group',
+  });
+  const fake = startFakeAccessGroupLitellm({ seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(estate))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(estate), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting a group that grants MORE than declared corrects it, and leaves undeclared text and teams alone', async () => {
+  const wide = groupRow({
+    access_group_id: 'FAKE-live-2',
+    access_group_name: 'FAKE-estate',
+    access_mcp_server_ids: ['FAKE-server-a', 'FAKE-server-extra'],
+    access_model_names: ['fake-code', 'fake-flash', 'fake-extra'],
+    assigned_team_ids: ['FAKE-team-1'],
+    description: 'written by a person',
+  });
+  const fake = startFakeAccessGroupLitellm({ seed: [wide] });
+  const { description: _kept, ...withoutDescription } = estate;
+  await stack(fake).deploy(declare(withoutDescription), { adopt: true });
+  expect(fake.groups()[0]).toMatchObject({
+    access_mcp_server_ids: ['FAKE-server-a'],
+    access_model_names: ['fake-code', 'fake-flash'],
+    assigned_team_ids: ['FAKE-team-1'],
+    description: 'written by a person',
+  });
+  // ★ a partial update: the team edge is not in the body at all
+  expect(fake.bodies()[0]).not.toHaveProperty('assigned_team_ids');
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('reconcile compares the LIVE row: after LiteLLM prunes a model name itself, the next update puts it back', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  fake.dropModel('fake-flash'); // ⚠️ access_group_model_sync.py: a deleted last deployment
+  // ★ Alchemy plans from state, so an unchanged declaration is a no-op even now (beta.79 reads live
+  //   state only to adopt); a declaration that changes anything reaches reconcile, which reads live
+  expect(await same.deploy(declare(estate))).toEqual({ Estate: 'noop' });
+  expect(await same.deploy(declare({ ...estate, description: 'FAKE changed' }))).toEqual({
+    Estate: 'update',
+  });
+  expect(fake.bodies().at(-1)).toEqual({
+    access_model_names: ['fake-code', 'fake-flash'],
+    description: 'FAKE changed',
+  });
+});
+
+test('a proxy that drops an empty-list edit fails the deploy instead of claiming success', async () => {
+  // ⚠️ the fake's own model of a truthiness check on the edit route — unmeasured at 1.103.0
+  const fake = startFakeAccessGroupLitellm({ editIgnoresEmpty: true });
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  await expect(same.deploy(declare({ ...estate, mcpServerIds: [] }))).rejects.toThrow();
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...estate, accessGroupName: ' ' },
+    { ...estate, accessGroupName: ' padded' },
+    { ...estate, description: '  ' },
+    { ...estate, modelNames: ['fake-code', 'fake-code'] },
+    { ...estate, mcpServerIds: ['FAKE-server-a', ''] },
+  ]) {
+    const fake = startFakeAccessGroupLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the row: nothing deletes a group unless the stack opts in', async () => {
+  const fake = startFakeAccessGroupLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(estate));
+  await same.deploy(Effect.void);
+  expect(fake.groups()).toHaveLength(1);
+});
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('delete answers 204 with no body, and a missing id is swallowed only because a real read says so', async () => {
+  const live = groupRow({ access_group_id: 'FAKE-live-3', access_group_name: 'FAKE-estate' });
+  const fake = startFakeAccessGroupLitellm({ seed: [live] });
+  await run(fake.fetch, deleteAccessGroup('FAKE-live-3'));
+  expect(fake.groups()).toEqual([]);
+  // already gone: the DELETE 404s, the re-list confirms absence, so it is success
+  await run(fake.fetch, deleteAccessGroup('FAKE-live-3'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the row stays', async () => {
+  const live = groupRow({ access_group_id: 'FAKE-live-4', access_group_name: 'FAKE-estate' });
+  const fake = startFakeAccessGroupLitellm({ forbidWrites: true, seed: [live] });
+  await expect(run(fake.fetch, deleteAccessGroup('FAKE-live-4'))).rejects.toThrow();
+  expect(fake.groups()).toHaveLength(1);
+});

package/src/litellm/access-group.ts

@@ -0,0 +1,151 @@
+/**
+ * `LiteLLM.AccessGroup` — one row of LiteLLM's unified access group table
+ * (`LiteLLM_AccessGroupTable`, `/v1/unified_access_group`): a named bundle of models and MCP servers
+ * that teams and keys are attached to. Types and what is left out: access-group-types.ts.
+ *
+ * ★ ADOPT BY NAME. `access_group_name` is unique in the table, so `accessGroupName` finds the one
+ *   live row that carries it. A live row with no state is `Unowned`, so it needs `--adopt`.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a group detaches it from every team and key that
+ *   holds it (`delete_access_group` rewrites their `access_group_ids`), and those callers lose the
+ *   models and servers it granted. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ★ THE GRANTS ARE THE DECLARATION. `modelNames` and `mcpServerIds` are always compared (an
+ *   undeclared list means "grants nothing"), so an adopted group that grants more is corrected.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `access_group_endpoints.py` has no `premium_user` check
+ *   (grep, 1.103.0), and docs.litellm.ai/docs/proxy/access_groups makes no Enterprise statement.
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { createBody, differing, firstProblem, updateBody } from './access-group-form.ts';
+import {
+  createAccessGroup,
+  deleteAccessGroup,
+  listAccessGroups,
+  updateAccessGroup,
+} from './access-group-operations.ts';
+import type { AccessGroupAttributes, AccessGroupProps } from './access-group-types.ts';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryNotConvergedError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+
+export type { AccessGroupAttributes, AccessGroupProps };
+export type { RegistryError as AccessGroupError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.AccessGroup';
+
+export interface LiteLLMAccessGroup extends Resource<
+  'LiteLLM.AccessGroup',
+  AccessGroupProps,
+  AccessGroupAttributes
+> {}
+
+export const LiteLLMAccessGroup = Resource<LiteLLMAccessGroup>('LiteLLM.AccessGroup', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMAccessGroup = (value: unknown): value is LiteLLMAccessGroup =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.AccessGroup';
+
+/**
+ * The live row this declaration means. A RECORDED id wins and is matched by id alone: a row that
+ * vanished and was recreated by hand under the same name is not silently taken over (the create
+ * would then fail on the unique name, loudly). With no state, the name decides.
+ */
+const locate = (
+  rows: readonly AccessGroupAttributes[],
+  props: AccessGroupProps,
+  output: AccessGroupAttributes | undefined,
+) =>
+  output !== undefined
+    ? rows.find((row) => row.accessGroupId === output.accessGroupId)
+    : rows.find((row) => row.accessGroupName === props.accessGroupName);
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const accessGroupHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: AccessGroupProps; output: AccessGroupAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.accessGroupName), firstProblem(olds));
+      }
+      const live = locate(yield* listAccessGroups(), olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<AccessGroupProps>;
+    output: AccessGroupAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.accessGroupName), firstProblem(news));
+      if (output === undefined) return undefined;
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: AccessGroupProps;
+    output: AccessGroupAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.accessGroupName), firstProblem(news));
+      const before = locate(yield* listAccessGroups(), news, output);
+      if (before === undefined) yield* createAccessGroup(createBody(news));
+      else if (differing(before, news).length > 0) {
+        yield* updateAccessGroup(before.accessGroupId, updateBody(news, before));
+      }
+
+      const rows = yield* listAccessGroups();
+      const after =
+        before === undefined
+          ? rows.find((row) => row.accessGroupName === news.accessGroupName)
+          : rows.find((row) => row.accessGroupId === before.accessGroupId);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({
+            name: news.accessGroupName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.accessGroupName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: AccessGroupAttributes }) =>
+    deleteAccessGroup(output.accessGroupId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMAccessGroupProvider = () =>
+  Provider.effect(
+    LiteLLMAccessGroup,
+    Effect.succeed(LiteLLMAccessGroup.Provider.of(accessGroupHandlers)),
+  );

package/src/litellm/credential-errors.ts

@@ -0,0 +1,183 @@
+/**
+ * The typed refusals `LiteLLM.Credential` raises on top of `@distilled.cloud/litellm`'s own SDK
+ * errors.
+ *
+ * ⛔ NO MESSAGE HERE MAY CARRY A CREDENTIAL VALUE: only the credential's NAME, field names, the
+ *   NAMES of environment variables, and SDK error text — exactly like mcp-server-errors.ts.
+ * ⚠️ THE SDK'S TYPED UNION IS NARROW ON PURPOSE, and the runtime is wider: the credential routes
+ *   declare only `UnprocessableEntity` (422) in `credential_management.ts`, so a create on an
+ *   existing name — which the live 1.103.0 container answers `409` (`endpoints.py`'s
+ *   `_credential_exists_detail`) — decodes at run time as the core `Conflict` class (`Errors.ts`
+ *   re-exports it, but it is not in the operation's TS union) and PROPAGATES as such, never
+ *   silently swallowed (S21). The read's and delete's `404` is TYPED as the SDK's
+ *   `CredentialNotFound` (a distilled patch matched on the vendor's "Credential not found"
+ *   message, `endpoints.py`), so credential-operations.ts `catchTag`s it instead of `instanceof`
+ *   `NotFound`: a 404 from a front proxy, Access, or a wrong base path stays a `NotFound` and is
+ *   never read as absence. `CredentialError` carries the typed members of the four operations the
+ *   resource calls (create, by-name read, PATCH, delete), plus the refusals below.
+ */
+import type * as credentials from '@distilled.cloud/litellm/credential_management';
+import * as Data from 'effect/Data';
+import type { HttpClientErrorReason } from 'effect/unstable/http/HttpClientError';
+
+/** A declaration the resource refuses before any request: a combination nobody meant. */
+export class LitellmCredentialInvalidError extends Data.TaggedError(
+  'LitellmCredentialInvalidError',
+)<{
+  readonly credentialName: string;
+  readonly problem: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.Credential "${this.credentialName}": ${this.problem}.`;
+  }
+}
+
+/**
+ * A create's `POST /credentials` or an update's `PATCH /credentials/{name}` failed on the wire (or
+ * its answer could not be read), so nobody knows whether the credential is what was asked for.
+ *
+ * ⛔ THIS IS WHAT STANDS IN FOR AN `HttpClientError`, WHICH CARRIES ITS REQUEST, AND THE REQUEST
+ *   BODY OF A CREATE OR UPDATE IS `{"credential_name": …, "credential_values": {"api_key": "…"}}`.
+ *   Measured 2026-09-30: on a dropped connection `JSON.stringify(error)`, `Bun.inspect(error)` and
+ *   Effect's JSON logger all printed the value, as did a failed deploy over it — the same leak
+ *   key-operations.ts's `LitellmKeyTransportError` closes. A defect reading a broken answer
+ *   (`protocol-rest.ts` reads it `Effect.orDie`) carries the same request. So `reason` keeps the
+ *   `HttpClientError` reason's TAG (a string) and nothing else: no request, no cause, no
+ *   description. The credential NAME stays — it is not secret.
+ */
+export class LitellmCredentialTransportError extends Data.TaggedError(
+  'LitellmCredentialTransportError',
+)<{
+  readonly credentialName: string;
+  readonly reason: HttpClientErrorReason['_tag'] | 'Defect';
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": a /credentials write failed ` +
+      `(${this.reason}) before an answer could be read, so the credential MAY have been written. ` +
+      'This error keeps neither the request nor its cause: the request body holds the credential ' +
+      'values. Look the name up in LiteLLM. A row that landed is taken over by the next deploy ' +
+      'with --adopt; one that did not is created by it.'
+    );
+  }
+}
+
+/**
+ * The SDK prints request and response bodies to stderr while `DISTILLED_DEBUG_HTTP` is set, and a
+ * `POST /credentials` carries the values in its body — refused before any request, exactly like
+ * `key-secret.ts`'s `refuseDebugLogging` for `/key/generate`.
+ */
+export class LitellmCredentialDebugLoggingError extends Data.TaggedError(
+  'LitellmCredentialDebugLoggingError',
+)<{
+  readonly credentialName: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": DISTILLED_DEBUG_HTTP is set, so the SDK ` +
+      "would print the credential values to stderr in /credentials' request and response. Unset " +
+      'it and run again. Nothing was written.'
+    );
+  }
+}
+
+/**
+ * A write had to send the credential values and the deploying process does not hold one or more
+ * of the declared variables. The names are listed, never a value.
+ */
+export class LitellmCredentialEnvUnsetError extends Data.TaggedError(
+  'LitellmCredentialEnvUnsetError',
+)<{
+  readonly credentialName: string;
+  readonly variables: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": ` +
+      `the deploying process does not set ${this.variables.join(', ')}.`
+    );
+  }
+}
+
+/**
+ * A credentials read answered something that is not a row of the credential table (or named a
+ * different row), so adopt-by-name cannot trust it. The by-name read is this resource's only
+ * read, so a row it cannot recognise is refused rather than guessed at.
+ */
+export class LitellmCredentialUnreadableError extends Data.TaggedError(
+  'LitellmCredentialUnreadableError',
+)<{
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.Credential: a credentials read is unreadable (${this.reason}).`;
+  }
+}
+
+/**
+ * A create or update returned no error, yet the by-name read does not answer the credential — the
+ * proxy failed to record it in memory or in the DB. Refused instead of reported as done.
+ */
+export class LitellmCredentialAbsentAfterWriteError extends Data.TaggedError(
+  'LitellmCredentialAbsentAfterWriteError',
+)<{
+  readonly credentialName: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": the write returned no error but the ` +
+      'credential is absent from the by-name read.'
+    );
+  }
+}
+
+/**
+ * The write returned no error but the credential still differs from the declaration. The update
+ * path this resource uses is a PATCH merge (credential.ts, credential-operations.ts) — or a
+ * whole-row rewrite to drop a key — so a residual difference is refused here instead of being
+ * reported as converged.
+ */
+export class LitellmCredentialNotConvergedError extends Data.TaggedError(
+  'LitellmCredentialNotConvergedError',
+)<{
+  readonly credentialName: string;
+  readonly fields: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": after the write it still differs from the ` +
+      `declaration in ${this.fields.join(', ')}.`
+    );
+  }
+}
+
+/** A rewrite deleted the old row before its POST failed. Keep only the failure tag. */
+export class LitellmCredentialRewriteError extends Data.TaggedError(
+  'LitellmCredentialRewriteError',
+)<{
+  readonly credentialName: string;
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Credential "${this.credentialName}": DELETE already ran, but the replacement ` +
+      `POST failed (${this.reason}). The next deploy recreates the row if absent; keep all ` +
+      'declared credential variables set. If the POST landed despite the failure, the next ' +
+      'deploy reads and reconciles that row.'
+    );
+  }
+}
+
+export type CredentialError =
+  | credentials.CreateCredentialCredentialsPostError
+  | credentials.GetCredentialByNameCredentialsByNameCredentialNameGetError
+  | credentials.UpdateCredentialCredentialsCredentialNamePatchError
+  | credentials.DeleteCredentialCredentialsCredentialNameDeleteError
+  | LitellmCredentialInvalidError
+  | LitellmCredentialTransportError
+  | LitellmCredentialRewriteError
+  | LitellmCredentialDebugLoggingError
+  | LitellmCredentialEnvUnsetError
+  | LitellmCredentialUnreadableError
+  | LitellmCredentialAbsentAfterWriteError
+  | LitellmCredentialNotConvergedError;