@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/credential-values.ts

@@ -0,0 +1,94 @@
+/**
+ * The values of a `LiteLLM.Credential` — resolved from the deploying process's environment at
+ * call time, held as `Redacted`, and compared by seal.
+ *
+ * ★ THIS IS THE CREDENTIAL LITELLM STORES, so the deploying process holds the value: the wire
+ *   body carries the LITERAL (the proxy encrypts it into its database, measured in the live
+ *   1.103.0 container — `credential_endpoints/endpoints.py`'s `encrypt_credential_values`), which
+ *   is exactly why the prop is only a NAME (`credential-types.ts`). Inside this process the value
+ *   is a `Redacted<string>`, so a stray log or error dump prints `<redacted>`; it is unwrapped in
+ *   exactly one place, the wire body (credential-form.ts). Never a prop or an attribute.
+ * ⚠️ LITELLM DOES NOT HAND THE VALUES BACK TO COMPARE WITH: both reads answer them MASKED
+ *   (2 + `****` + 2, `*****` for a short string — `litellm_logging.py::_get_masked_values`), and a
+ *   masked fragment is a partial secret that must never be compared or stored. So what was last
+ *   written is remembered as a SEAL, and a plan asks "are the values in my environment the ones I
+ *   wrote". Four answers, mcp-server-credential.ts's own list:
+ *   - `none`    — no values are declared, nothing to compare.
+ *   - `unknown` — one or more declared variables is unset here, so a plan cannot tell. Never
+ *                 drift: a plan-only environment must not report every credentialed row as
+ *                 changed. A WRITE still demands them (`requireValues`).
+ *   - `stale`   — every variable is set and there is no seal (an adopted row, or one written
+ *                 outside this stack) or the seal disagrees. The declaration is authoritative,
+ *                 so it is written.
+ *   - `match`   — the seal was made from exactly these resolved values.
+ * ⚠️ ALL-OR-NOTHING RESOLUTION: a write sends `credential_values` only when EVERY declared
+ *   variable resolves — the values-stale PATCH and the whole-row create both demand every value
+ *   (`requireValues`, credential.ts), because sending the resolved half would store a row whose
+ *   unset half was silently blanked. When any variable is missing the state is `unknown`: an
+ *   info-only PATCH can proceed, but a required rewrite refuses before DELETE.
+ * ⚠️ A SEAL OF A GUESSABLE SECRET IS STILL GUESSABLE (secrets/write-only.ts). Use a random token.
+ */
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { type Environment, resolveAll, seal, sealMatches } from '../secrets/write-only.ts';
+import { LitellmCredentialEnvUnsetError } from './credential-errors.ts';
+import type { CredentialProps } from './credential-types.ts';
+
+/** What the environment holds for the declared values. `missing` names the unset variables. */
+export interface ResolvedValues {
+  readonly values: Readonly<Record<string, Redacted.Redacted<string>>>;
+  readonly missing: readonly string[];
+}
+
+export type CredentialValuesState = 'none' | 'unknown' | 'stale' | 'match';
+
+/** ⛔ Reads the environment at CALL time, never at module load (docs/credentials.md). */
+export const resolveValues = (
+  props: CredentialProps,
+  env: Environment = process.env,
+): ResolvedValues => {
+  const { values, missing } = resolveAll(props.credentialValues, env);
+  return {
+    missing,
+    values: Object.fromEntries(
+      Object.entries(values).map(([key, value]) => [key, Redacted.make(value)]),
+    ),
+  };
+};
+
+const sealable = (values: Readonly<Record<string, Redacted.Redacted<string>>>) =>
+  Object.fromEntries(Object.entries(values).map(([key, value]) => [key, Redacted.value(value)]));
+
+/** `scrypt:<salt>:<digest>` of the resolved values, for `valuesSeal`. ⛔ Never a value. */
+export const sealValues = (values: Readonly<Record<string, Redacted.Redacted<string>>>): string =>
+  seal(sealable(values));
+
+export const valuesState = (
+  props: CredentialProps,
+  sealed: string,
+  resolved: ResolvedValues = resolveValues(props),
+): CredentialValuesState => {
+  const declared = Object.keys(props.credentialValues);
+  if (declared.length === 0) return 'none';
+  if (resolved.missing.length > 0) return 'unknown';
+  if (sealed === '') return 'stale';
+  return sealMatches(sealed, sealable(resolved.values)) ? 'match' : 'stale';
+};
+
+/**
+ * Fails naming the missing variables when this write has to send the values and the deploying
+ * process does not hold them all. Creates, rewrites and value-stale PATCHes need every value;
+ * an info-only PATCH leaves values alone and does not need this guard (credential.ts).
+ */
+export const requireValues = (
+  props: CredentialProps,
+  resolved: ResolvedValues,
+): Effect.Effect<void, LitellmCredentialEnvUnsetError> =>
+  resolved.missing.length === 0
+    ? Effect.void
+    : Effect.fail(
+        new LitellmCredentialEnvUnsetError({
+          credentialName: props.credentialName,
+          variables: resolved.missing,
+        }),
+      );

package/src/litellm/credential.test.ts

@@ -0,0 +1,218 @@
+/**
+ * `LiteLLM.Credential` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-credential-litellm.ts`): create, no-op, the PATCH merge, the whole-row rewrite to drop a
+ * key, adoption, the masked store's asymmetry, removal.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`, and the credential reaches the resource only through an environment
+ *   variable the test sets and removes, exactly as a deploying process would (S25).
+ * ★ WHAT THE FAKE MODELS IS MEASURED FROM THE LIVE 1.103.0 CONTAINER (its header); the one
+ *   unmeasured choice is `rows()` answering values in CLEAR, so a test can assert what a write SENT.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { type CredentialProps, LiteLLMCredential } from './credential.ts';
+import { credentialRow, startFakeCredentialLitellm } from './fake-credential-litellm.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_CREDENTIAL_KEY';
+
+const stack = (fake: ReturnType<typeof startFakeCredentialLitellm>) =>
+  fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: CredentialProps, name = 'Cred') =>
+  Effect.gen(function* () {
+    yield* LiteLLMCredential(name, props);
+  });
+
+const props: CredentialProps = {
+  credentialInfo: { note: 'docs search' },
+  credentialName: 'FAKE_api',
+  credentialValues: { api_key: { fromEnv: VARIABLE } },
+};
+
+beforeEach(() => {
+  process.env[VARIABLE] = 'FAKE-key-one';
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+});
+
+test('creates one row: the whole body in a single POST, the name in the body, values as literals', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  expect(await stack(fake).deploy(declare(props))).toEqual({ Cred: 'create' });
+  expect(fake.bodies()[0]).toEqual({
+    credential_info: { note: 'docs search' },
+    credential_name: 'FAKE_api',
+    credential_values: { api_key: 'FAKE-key-one' },
+  });
+  expect(writesOf(fake.requests())).toEqual(['POST /credentials']);
+});
+
+test('a second deploy of the same declaration writes nothing', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Cred: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a rotated value is a PATCH merge — one row, then a no-op', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  process.env[VARIABLE] = 'FAKE-key-two';
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Cred: 'update' });
+  expect(writesOf(fake.requests().slice(before))).toEqual(['PATCH /credentials/FAKE_api']);
+  expect(fake.rows()).toHaveLength(1);
+  expect(fake.rows()[0]?.['credential_values']).toEqual({ api_key: 'FAKE-key-two' });
+  expect(await same.deploy(declare(props))).toEqual({ Cred: 'noop' });
+});
+
+test('a changed metadata value is a PATCH too', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  expect(
+    await same.deploy(declare({ ...props, credentialInfo: { note: 'docs search v2' } })),
+  ).toEqual({ Cred: 'update' });
+  expect(writesOf(fake.requests())).toEqual(['POST /credentials', 'PATCH /credentials/FAKE_api']);
+  expect(fake.rows()[0]?.['credential_info']).toEqual({ note: 'docs search v2' });
+});
+
+test('dropping a previously-declared info key is a whole-row rewrite (PATCH cannot remove)', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare({ ...props, credentialInfo: { note: 'docs search', team: 'a' } }));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Cred: 'update' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([
+    'DELETE /credentials/FAKE_api',
+    'POST /credentials',
+  ]);
+  expect(fake.rows()[0]?.['credential_info']).toEqual({ note: 'docs search' });
+});
+
+test('a live row is Unowned: refused without --adopt, taken with it (and sealed)', async () => {
+  const seed = [
+    credentialRow({
+      credential_info: { note: 'docs search' },
+      credential_name: 'FAKE_api',
+      credential_values: { api_key: 'FAKE-key-rotated-elsewhere' },
+    }),
+  ];
+  const fake = startFakeCredentialLitellm({ masterKey: KEY, seed });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(props))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  await engine.deploy(declare(props), { adopt: true });
+  // the declared values are stamped over the row a writer elsewhere rotated, so the seal matches
+  expect(writesOf(fake.requests())).toEqual(['PATCH /credentials/FAKE_api']);
+  expect(fake.rows()[0]?.['credential_values']).toEqual({ api_key: 'FAKE-key-one' });
+  const before = fake.requests().length;
+  expect(await engine.deploy(declare(props))).toEqual({ Cred: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('adopting with the variable unset writes nothing and demands nothing; a later deploy writes', async () => {
+  const seed = [
+    credentialRow({
+      credential_info: { note: 'docs search' },
+      credential_name: 'FAKE_api',
+      credential_values: { api_key: 'FAKE-key-elsewhere' },
+    }),
+  ];
+  const fake = startFakeCredentialLitellm({ masterKey: KEY, seed });
+  const engine = stack(fake);
+  delete process.env[VARIABLE];
+  await engine.deploy(declare(props), { adopt: true });
+  expect(writesOf(fake.requests())).toEqual([]);
+  process.env[VARIABLE] = 'FAKE-key-two';
+  expect(await engine.deploy(declare(props))).toEqual({ Cred: 'update' });
+  expect(fake.rows()[0]?.['credential_values']).toEqual({ api_key: 'FAKE-key-two' });
+});
+
+test('a row the proxy holds only in its database (not loaded in memory) fails the deploy loudly', async () => {
+  const fake = startFakeCredentialLitellm({
+    masterKey: KEY,
+    memoryOmits: ['FAKE_api'],
+    seed: [
+      credentialRow({
+        credential_info: { note: 'docs search' },
+        credential_name: 'FAKE_api',
+        credential_values: { api_key: 'FAKE-key-elsewhere' },
+      }),
+    ],
+  });
+  // the read answers 404, the create for the same name answers 409 — never a silent success
+  await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+  expect(fake.rows()).toHaveLength(1);
+});
+
+test('a literal value in the declaration is refused before a single request', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const literal = {
+    ...props,
+    credentialValues: { api_key: { value: 'FAKE-literal' } as never },
+  };
+  await expect(stack(fake).deploy(declare(literal))).rejects.toThrow();
+  expect(fake.requests()).toEqual([]);
+});
+
+test('a sensitive-keyed metadata entry is refused before a single request', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const sensitive = { ...props, credentialInfo: { authToken: 'FAKE-meta' } };
+  await expect(stack(fake).deploy(declare(sensitive))).rejects.toThrow();
+  expect(fake.requests()).toEqual([]);
+});
+
+test('a renamed credential is a replace, and the old row is retained', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  expect(await same.deploy(declare({ ...props, credentialName: 'FAKE_api2' }))).toEqual({
+    Cred: 'replace',
+  });
+  expect(fake.rows().map((row) => row['credential_name'])).toEqual(['FAKE_api', 'FAKE_api2']);
+});
+
+test('under RemovalPolicy.destroy() a removed declaration deletes the row; the default retains it', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const engine = stack(fake);
+  const gone = Effect.gen(function* () {
+    yield* LiteLLMCredential('Gone', props).pipe(RemovalPolicy.destroy());
+  });
+  await engine.deploy(gone);
+  expect(await engine.deploy(Effect.void)).toEqual({ Gone: 'delete' });
+  expect(fake.rows()).toEqual([]);
+
+  await engine.deploy(declare(props, 'Kept'));
+  await engine.deploy(Effect.void);
+  expect(fake.rows()).toHaveLength(1);
+});
+
+test('a create whose variable is unset is refused at the write, names the variable, writes nothing', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  delete process.env[VARIABLE];
+  const failure = await stack(fake)
+    .deploy(declare(props))
+    .then(
+      () => undefined,
+      (error: unknown) => String(error),
+    );
+  expect(failure).toContain(VARIABLE);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('an unset variable on an unchanged row is "cannot tell", never drift', async () => {
+  const fake = startFakeCredentialLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  delete process.env[VARIABLE];
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Cred: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});

package/src/litellm/credential.ts

@@ -0,0 +1,227 @@
+/**
+ * `LiteLLM.Credential` — one row of LiteLLM's reusable credential table (`/credentials/*`), a
+ * named bag of values the proxy stores encrypted and can bind to a deployment by `model_id`.
+ *
+ * ★ ADOPT BY NAME. `credentialName` finds the live row whose `credential_name` equals it; a live
+ *   row with no state is `Unowned`, so it needs `--adopt`. The name is the vendor's only address
+ *   (the table's unique column, `schema.prisma`), so a row is located by the by-name read and
+ *   never guessed at.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a credential a deployment references would break
+ *   that deployment's next call. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ THE VALUES ARE `{ fromEnv: 'NAME' }`, NEVER A VALUE (S25): LiteLLM STORES these literals
+ *   (encrypted at rest), so the deploying process must hold them — credential-types.ts carries the
+ *   full reasoning, and a `model` deployment's `os.environ/NAME` reference is the opposite case.
+ *   A plan compares the live row's `credential_info` per declared key and the values through a
+ *   digest of what was resolved (`valuesSeal`); it never compares the masked read, and a value
+ *   whose variable is unset never drifts a plan-only environment (credential-values.ts).
+ * ⚠️ A RENAME IS A REPLACE: the name is the row's identity and its only address, so a changed
+ *   `credentialName` creates the new row and the old one survives under 'retain' — never renamed
+ *   in place.
+ * ⚠️ A CHANGED ROW IS PATCHED, NOT REWRITTEN — PATCH merges values and normally replaces DB
+ *   info, but only merges in-memory info (1.103.0 credential_endpoints/endpoints.py:312-319,384-387).
+ *   A failed PATCH leaves the row behind (review finding 3: DELETE + POST left NO row when POST
+ *   failed). Dropping a value key OR an info key still requires DELETE + POST; both stores must
+ *   converge. All refusals run before the first write. Every write reads back to prove removal.
+ */
+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 { refuseTakeover } from '../ownership/adopt.ts';
+import {
+  LitellmCredentialAbsentAfterWriteError,
+  LitellmCredentialInvalidError,
+  LitellmCredentialNotConvergedError,
+} from './credential-errors.ts';
+import {
+  createBody,
+  differing,
+  firstProblem,
+  literalValues,
+  patchBody,
+  removedInfoKeys,
+  removedValueKeys,
+} from './credential-form.ts';
+import {
+  createCredential,
+  deleteCredential,
+  readCredential,
+  refuseDebugLogging,
+  updateCredential,
+} from './credential-operations.ts';
+import type { CredentialAttributes, CredentialProps } from './credential-types.ts';
+import { rewriteCredential } from './credential-rewrite.ts';
+import { requireValues, resolveValues, sealValues, valuesState } from './credential-values.ts';
+
+export type { CredentialAttributes, CredentialProps };
+export type { CredentialError } from './credential-errors.ts';
+
+export interface LiteLLMCredential extends Resource<
+  'LiteLLM.Credential',
+  CredentialProps,
+  CredentialAttributes
+> {}
+
+export const LiteLLMCredential = Resource<LiteLLMCredential>('LiteLLM.Credential', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMCredential = (value: unknown): value is LiteLLMCredential =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Credential';
+
+const refuse = (props: CredentialProps) => {
+  const problem = firstProblem(props);
+  return problem === undefined
+    ? Effect.void
+    : Effect.fail(
+        new LitellmCredentialInvalidError({
+          problem,
+          credentialName: String(props.credentialName),
+        }),
+      );
+};
+
+type Args<P> = {
+  fqn: string;
+  instanceId: string;
+  output: CredentialAttributes | undefined;
+} & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const credentialHandlers = {
+  /**
+   * ⛔ WITH NO `output` THIS IS ALCHEMY'S ADOPTION PROBE, AND THE ONLY PLAN-TIME HOOK A NEW
+   *   CREDENTIAL GETS — so the refusals run here too, as a defect (mcp-server.ts's own rule: the
+   *   cold-start probe must fail the plan, and a recovery read must degrade to "nothing
+   *   recovered", which only a defect does).
+   */
+  read: ({ olds, output }: Args<{ olds: CredentialProps }>) =>
+    Effect.gen(function* () {
+      // SDK debug logging prints responses too; non-sensitive value keys can be unmasked.
+      yield* refuseDebugLogging(olds.credentialName);
+      const problem = output === undefined ? firstProblem(olds) : undefined;
+      if (problem !== undefined) {
+        return yield* Effect.die(
+          new LitellmCredentialInvalidError({
+            problem,
+            credentialName: String(olds.credentialName),
+          }),
+        );
+      }
+      const found = yield* readCredential(olds.credentialName);
+      if (found === undefined) return undefined;
+      // A row cannot supply a digest of values it hides; state can.
+      return output === undefined ? Unowned(found) : { ...found, valuesSeal: output.valuesSeal };
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<CredentialProps>;
+    output: CredentialAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuse(news);
+      if (output === undefined) return undefined;
+      // The name is identity: a different declared name is a different row.
+      if (news.credentialName !== output.credentialName) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      // ⚠️ An unresolved value never drifts a plan (credential-values.ts's `unknown`): the gate
+      //   is "not stale", the same shape mcp-server.ts uses, and the write below still demands
+      //   the value when a write is actually being made.
+      const state = valuesState(news, output.valuesSeal);
+      // PATCH cannot remove value keys or in-memory info keys. Names alone prove drift.
+      const removed = [...removedInfoKeys(output, news), ...removedValueKeys(output, news)];
+      return differing(output, news).length === 0 && removed.length === 0 && state !== 'stale'
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ fqn, instanceId, news, output }: Args<{ news: CredentialProps }>) =>
+    Effect.gen(function* () {
+      yield* refuse(news);
+      yield* refuseDebugLogging(news.credentialName);
+      const resolved = resolveValues(news);
+      const before = yield* readCredential(news.credentialName);
+      let sealed = output?.valuesSeal ?? '';
+
+      if (before === undefined) {
+        // ⛔ A CREATE IS A WHOLE-ROW WRITE, so it must hold every declared value.
+        yield* requireValues(news, resolved);
+        yield* createCredential(createBody(news, resolved));
+        sealed = sealValues(resolved.values);
+      } else {
+        // ⛔ A LIVE ROW IS ONLY WRITTEN WHEN THIS STACK MAY OWN IT. A rename onto a name the proxy
+        //   already holds runs here with `output: undefined` (a fresh replace's new generation) and
+        //   `before` set to the FOREIGN row — the planner never probed the new identity, so this is
+        //   the apply-time check key.ts's own reconcile makes, and without it a deploy-wide
+        //   `--adopt` meant for something else would overwrite a row another owner relies on.
+        yield* refuseTakeover(
+          { fqn, instanceId, output },
+          `LiteLLM.Credential ${news.credentialName}`,
+        );
+        // ⛔ PATCH FOR VALUE/INFO CHANGES, REWRITE TO DROP KEYS IN BOTH STORES. Unlike the
+        // old unconditional rewrite (finding 3), failed PATCH leaves the row behind. A rewrite
+        // still needs every declared value BEFORE DELETE so a partial environment cannot erase it.
+        const removed = [...removedInfoKeys(before, news), ...removedValueKeys(before, news)];
+        const infoDrift = differing(before, news).length > 0;
+        const valuesStale = valuesState(news, sealed) === 'stale';
+        if (removed.length > 0) {
+          yield* requireValues(news, resolved);
+          yield* rewriteCredential(createBody(news, resolved));
+          sealed = sealValues(resolved.values);
+        } else if (infoDrift || valuesStale) {
+          if (valuesStale) yield* requireValues(news, resolved);
+          yield* updateCredential(
+            patchBody(news, valuesStale ? literalValues(resolved) : undefined),
+          );
+          if (valuesStale) sealed = sealValues(resolved.values);
+        }
+      }
+
+      // ⛔ THE READ-BACK IS A SINGLE READ, ON PURPOSE, AND THE VENDOR CLOSES THE RACE. The by-name
+      //   read walks the proxy's IN-MEMORY list, which a write that just returned has already
+      //   reloaded: `create_credential` awaits `upsert_credentials` and the PATCH awaits its
+      //   in-memory sync before answering (endpoints.py, 1.103.0), so a row written by THIS proxy
+      //   is in memory by the time its write answers. A retry loop would only paper over a
+      //   multi-proxy read that hit a peer which had not reloaded — and then the honest answer is
+      //   the failure below, not a slow pretend. This is the same single-read stance key.ts takes.
+      const after = yield* readCredential(news.credentialName);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmCredentialAbsentAfterWriteError({ credentialName: news.credentialName }),
+        );
+      }
+      const left = [
+        ...differing(after, news),
+        ...removedInfoKeys(after, news).map((key) => `credential_info.${key}`),
+        ...removedValueKeys(after, news).map((key) => `credential_values.${key}`),
+      ];
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmCredentialNotConvergedError({
+            fields: left,
+            credentialName: news.credentialName,
+          }),
+        );
+      }
+      return { ...after, valuesSeal: sealed };
+    }),
+
+  delete: ({ output }: { output: CredentialAttributes }) => deleteCredential(output.credentialName),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMCredentialProvider = () =>
+  Provider.effect(
+    LiteLLMCredential,
+    Effect.succeed(LiteLLMCredential.Provider.of(credentialHandlers)),
+  );

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

@@ -0,0 +1,127 @@
+/**
+ * A fake of LiteLLM's `/v1/unified_access_group` 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, `access_group_endpoints.py`, read,
+ *   not called): the name is UNIQUE (a create or a rename onto a taken name is a 409); a create
+ *   answers 201 with the row; the update is partial (`exclude_unset`) and turns a `null` list into
+ *   `[]`; a delete answers 204 with NO BODY and a missing id is a 404; writes need PROXY_ADMIN
+ *   (`forbidWrites` models the 403). The list is the table.
+ * ⚠️ NOT MODELLED: `assigned_team_ids` / `assigned_key_ids` mirroring into teams and keys (the fake
+ *   keeps the arrays and does nothing with them), and the display-name expansion of the response.
+ *   `dropModel` models `access_group_model_sync.py`: LiteLLM itself removes a model name from a group
+ *   when its last deployment goes, which is the drift source the docs warn about.
+ */
+import { FAKE_KEY, type FakeRecord, empty, json, recordingFetch } from './fake-registry-base.ts';
+import type { Row } from './registry-support.ts';
+
+export interface FakeAccessGroupLitellm extends FakeRecord {
+  /** Every stored group, exactly as the proxy holds it. */
+  readonly groups: () => readonly Row[];
+  /** LiteLLM's own model-name pruning (`access_group_model_sync.py`). */
+  readonly dropModel: (name: string) => void;
+}
+
+export interface FakeAccessGroupOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** `POST`/`PUT`/`DELETE` answer 403, as for a key that is not PROXY_ADMIN. */
+  readonly forbidWrites?: boolean;
+  /** A `PUT` drops empty lists instead of writing them (a truthiness check). */
+  readonly editIgnoresEmpty?: boolean;
+}
+
+/** A row as `AccessGroupResponse` carries it: every required field present. */
+export const groupRow = (fields: Row): Row => ({
+  access_agent_ids: [],
+  access_agents: [],
+  access_mcp_server_ids: [],
+  access_mcp_servers: [],
+  access_model_names: [],
+  assigned_key_ids: [],
+  assigned_keys: [],
+  assigned_team_ids: [],
+  assigned_teams: [],
+  created_at: '2026-09-30T00:00:00Z',
+  description: null,
+  updated_at: '2026-09-30T00:00:00Z',
+  ...fields,
+});
+
+export const startFakeAccessGroupLitellm = (
+  options: FakeAccessGroupOptions = {},
+): FakeAccessGroupLitellm => {
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  let issued = 0;
+
+  const record = recordingFetch(options.masterKey ?? FAKE_KEY, ({ body, request, url }) => {
+    const byId = /^\/v1\/unified_access_group\/([^/]+)$/.exec(url.pathname);
+    if (url.pathname === '/v1/unified_access_group' && request.method === 'GET') {
+      return json(200, rows);
+    }
+    if (request.method !== 'GET' && options.forbidWrites === true) {
+      return json(403, { detail: { error: 'not_allowed_access' } });
+    }
+    if (url.pathname === '/v1/unified_access_group' && request.method === 'POST') {
+      if (rows.some((row) => row['access_group_name'] === body['access_group_name'])) {
+        return json(409, {
+          detail: `Access group '${String(body['access_group_name'])}' already exists`,
+        });
+      }
+      issued += 1;
+      const created = groupRow({
+        access_group_id: `FAKE-group-${String(issued).padStart(4, '0')}`,
+        access_group_name: body['access_group_name'],
+        access_mcp_server_ids: body['access_mcp_server_ids'] ?? [],
+        access_model_names: body['access_model_names'] ?? [],
+        description: body['description'] ?? null,
+      });
+      rows = [...rows, created];
+      return json(201, created);
+    }
+    if (byId !== null && request.method === 'PUT') {
+      const id = decodeURIComponent(byId[1] ?? '');
+      const at = rows.findIndex((row) => row['access_group_id'] === id);
+      if (at === -1) return json(404, { detail: `Access group '${id}' not found` });
+      const taken = rows.some(
+        (row, i) =>
+          i !== at &&
+          body['access_group_name'] !== undefined &&
+          row['access_group_name'] === body['access_group_name'],
+      );
+      if (taken) return json(409, { detail: 'Access group name already exists' });
+      const patch = Object.fromEntries(
+        Object.entries(body)
+          .filter(
+            ([, value]) =>
+              !(options.editIgnoresEmpty === true && Array.isArray(value) && value.length === 0),
+          )
+          .map(([key, value]) => [key, value === null && key.startsWith('access_') ? [] : value]),
+      );
+      rows = rows.map((row, i) => (i === at ? { ...row, ...patch } : row));
+      return json(200, rows[at]);
+    }
+    if (byId !== null && request.method === 'DELETE') {
+      const id = decodeURIComponent(byId[1] ?? '');
+      if (!rows.some((row) => row['access_group_id'] === id)) {
+        return json(404, { detail: `Access group '${id}' not found` });
+      }
+      rows = rows.filter((row) => row['access_group_id'] !== id);
+      return empty(204);
+    }
+    return json(404, { detail: 'not found' });
+  });
+
+  return {
+    ...record,
+    dropModel: (name) => {
+      rows = rows.map((row) => ({
+        ...row,
+        access_model_names: ((row['access_model_names'] as string[] | undefined) ?? []).filter(
+          (each) => each !== name,
+        ),
+      }));
+    },
+    groups: () => rows.map((row) => ({ ...row })),
+  };
+};