@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/mcp-server-url.ts

@@ -0,0 +1,66 @@
+/**
+ * The URL half of `LiteLLM.MCPServer`: what a declared URL may not carry, and what a live one is
+ * scrubbed of before it reaches Alchemy's state.
+ *
+ * ⛔ THE URL IS A PROP, SO IT LANDS IN AN UNENCRYPTED STATE STORE. A secret in it (userinfo, a
+ *   `?token=`) would be persisted, so a declaration is refused for carrying one and a live row's
+ *   URL is redacted on the way in. The credential is `authValue`, never the URL.
+ */
+import { isBlank } from './mcp-server-types.ts';
+
+/** A query parameter whose NAME says it carries a secret. */
+const SECRET_PARAM = /token|secret|passw|api.?key|auth|credential|signature|^key$|^sig$/i;
+
+/** Why a URL may not be declared, or `undefined`. ⛔ Never quotes the URL: it may hold the secret. */
+export const urlProblem = (raw: unknown): string | undefined => {
+  if (isBlank(raw)) return '`url` must be a non-empty string';
+  let url: URL;
+  try {
+    url = new URL(raw as string);
+  } catch {
+    return '`url` must be a full http(s) URL including the scheme';
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return '`url` must be http or https';
+  if (url.username !== '' || url.password !== '') {
+    return '`url` must not carry userinfo; declare the credential as `authValue`';
+  }
+  if (url.hash !== '') return '`url` must not carry a fragment';
+  for (const name of url.searchParams.keys()) {
+    if (SECRET_PARAM.test(name)) {
+      return `\`url\` carries the query parameter "${name}", which looks like a credential; declare it as \`authValue\` instead, because the URL is stored in Alchemy's state`;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * `userinfo` and secret-looking query values replaced with `REDACTED`, so a live URL that carries a
+ * token never reaches Alchemy's unencrypted state.
+ * ★ A URL THAT NEEDS NO REDACTION COMES BACK BYTE-FOR-BYTE, never re-serialised: `URL#toString`
+ *   adds a trailing slash to a bare origin, and a declared `https://host` would then differ from
+ *   its own live row on every plan. A URL that does not parse is returned as it is.
+ */
+export const redactUrl = (raw: string): string => {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return raw;
+  }
+  let changed = false;
+  if (url.username !== '') {
+    url.username = 'REDACTED';
+    changed = true;
+  }
+  if (url.password !== '') {
+    url.password = 'REDACTED';
+    changed = true;
+  }
+  // ⚠️ A Set first: `set` mutates the live iterator's list, and a repeated name would be skipped.
+  for (const name of new Set(url.searchParams.keys())) {
+    if (!SECRET_PARAM.test(name)) continue;
+    url.searchParams.set(name, 'REDACTED');
+    changed = true;
+  }
+  return changed ? url.toString() : raw;
+};

package/src/litellm/mcp-server.test.ts

@@ -0,0 +1,213 @@
+/**
+ * `LiteLLM.MCPServer` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-mcp-litellm.ts`): create, no-op, rotate, adopt by name and drift.
+ *
+ * ★ 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.
+ * ⚠️ WHAT THE FAKE MODELS IS ITS OWN CHOICE, NOT A MEASUREMENT OF LITELLM 1.103.0 (see the fake).
+ *   A test that leans on one of those choices says so.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeMcpLitellm, serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMMCPServer } from './mcp-server.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_MCP_SERVER_TOKEN';
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: McpServerProps, name = 'Docs') =>
+  Effect.gen(function* () {
+    yield* LiteLLMMCPServer(name, props);
+  });
+
+const docs: McpServerProps = {
+  authType: 'bearer_token',
+  authValue: { fromEnv: VARIABLE },
+  serverName: 'FAKE_docs',
+  transport: 'http',
+  url: 'https://mcp.example.com/mcp',
+};
+
+const live = serverRow({
+  server_id: 'FAKE-uuid-1',
+  server_name: 'FAKE_search',
+  transport: 'sse',
+  url: 'https://search.example.com/sse',
+});
+const search: McpServerProps = {
+  authType: 'none',
+  serverName: 'FAKE_search',
+  transport: 'sse',
+  url: 'https://search.example.com/sse',
+};
+
+beforeEach(() => {
+  process.env[VARIABLE] = 'FAKE-token-one';
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+});
+
+test('creates a server, sends the credential once, and defaults the key and group grants to closed', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  expect(await stack(fake).deploy(declare(docs))).toEqual({ Docs: 'create' });
+  const [row] = fake.servers();
+  expect(row).toMatchObject({
+    allow_all_keys: false,
+    auth_type: 'bearer_token',
+    mcp_access_groups: [],
+    server_name: 'FAKE_docs',
+    transport: 'http',
+    url: 'https://mcp.example.com/mcp',
+  });
+  expect(row?.['credentials']).toEqual({ auth_value: 'FAKE-token-one' });
+  // ⛔ an undeclared tool list is not sent: `[]` would mean "no restriction" (mcp-server-tools.test.ts)
+  expect(fake.bodies()[0]).not.toHaveProperty('allowed_tools');
+  // ★ a deterministic physical name, not a proxy-issued uuid
+  expect(String(row?.['server_id'])).toMatch(/^[a-z0-9-]+$/);
+});
+
+test('a second deploy of the same declaration writes nothing', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(docs));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(docs))).toEqual({ Docs: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a rotated credential is an update that carries the new value, then a no-op', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(docs));
+  process.env[VARIABLE] = 'FAKE-token-two';
+  expect(await same.deploy(declare(docs))).toEqual({ Docs: 'update' });
+  expect(fake.servers()[0]?.['credentials']).toEqual({ auth_value: 'FAKE-token-two' });
+  expect(await same.deploy(declare(docs))).toEqual({ Docs: 'noop' });
+});
+
+test('an unset variable is "cannot tell", never drift: an unchanged server stays a no-op', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(docs));
+  delete process.env[VARIABLE];
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(docs))).toEqual({ Docs: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a create whose variable is unset is refused, names the variable, and writes nothing', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  delete process.env[VARIABLE];
+  const failure = await stack(fake)
+    .deploy(declare(docs))
+    .then(
+      () => undefined,
+      (error: unknown) => String(error),
+    );
+  expect(failure).toContain(VARIABLE);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a refused declaration fails the plan before a single request, so nothing invalid is stored', async () => {
+  for (const props of [
+    { ...docs, url: 'https://mcp.example.com/mcp?token=FAKE-in-url' },
+    { ...docs, authValue: undefined },
+    { ...docs, transport: 'stdio' as never },
+  ]) {
+    const fake = startFakeMcpLitellm({ masterKey: KEY });
+    await expect(stack(fake).deploy(declare(props as McpServerProps))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('a live row is Unowned: refused without --adopt, taken by name with it, with no write', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(search, 'Search'))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  const planned = await engine.deploy(declare(search, 'Search'), { adopt: true });
+  expect(Object.values(planned)).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting an open server: allow_all_keys is corrected to closed, the undeclared tool list is left', async () => {
+  const open = serverRow({
+    ...live,
+    allow_all_keys: true,
+    allowed_tools: ['FAKE_tool_a'],
+  });
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [open] });
+  await stack(fake).deploy(declare(search, 'Search'), { adopt: true });
+  expect(fake.servers()[0]).toMatchObject({
+    allow_all_keys: false,
+    allowed_tools: ['FAKE_tool_a'],
+  });
+  // ★ the update sent the whole managed set, and left the id alone
+  expect(fake.bodies()[0]).toMatchObject({ server_id: 'FAKE-uuid-1', allow_all_keys: false });
+  expect(fake.bodies()[0]).not.toHaveProperty('allowed_tools');
+});
+
+test('two live rows with the declared name are refused, never guessed at', async () => {
+  const twin = serverRow({ ...live, server_id: 'FAKE-uuid-2' });
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [live, twin] });
+  await expect(stack(fake).deploy(declare(search, 'Search'), { adopt: true })).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a declared serverId pins one of two same-named rows', async () => {
+  const twin = serverRow({ ...live, server_id: 'FAKE-uuid-2' });
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [live, twin] });
+  const planned = await stack(fake).deploy(
+    declare({ ...search, serverId: 'FAKE-uuid-2' }, 'Search'),
+    { adopt: true },
+  );
+  expect(Object.values(planned)).toEqual(['adopted']);
+});
+
+test('a proxy that drops an edit it cannot apply 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 open = serverRow({ ...live, allow_all_keys: true });
+  const fake = startFakeMcpLitellm({ editIgnoresFalsy: true, masterKey: KEY, seed: [open] });
+  await expect(stack(fake).deploy(declare(search, 'Search'), { adopt: true })).rejects.toThrow();
+});
+
+test('the id the proxy issues is the one recorded: the next deploy is a no-op on it', async () => {
+  const fake = startFakeMcpLitellm({ issuesOwnId: true, masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(search, 'Search'));
+  expect(fake.servers()[0]?.['server_id']).toBe('FAKE-issued-id-0001');
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(search, 'Search'))).toEqual({ Search: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('moving off a static auth type sends credentials: null and forgets the seal', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare(docs));
+  const oauth: McpServerProps = {
+    authType: 'oauth2',
+    serverName: docs.serverName,
+    transport: docs.transport,
+    url: docs.url,
+  };
+  expect(await same.deploy(declare(oauth))).toEqual({ Docs: 'update' });
+  expect(fake.bodies().at(-1)).toMatchObject({ auth_type: 'oauth2', credentials: null });
+  expect(fake.servers()[0]?.['credentials']).toBeNull();
+  expect(await same.deploy(declare(oauth))).toEqual({ Docs: 'noop' });
+});
+
+test('a changed declared serverId is a replace, create-first, and the old row is retained', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const same = stack(fake);
+  await same.deploy(declare({ ...search, serverId: 'FAKE-id-a' }, 'Search'));
+  const planned = await same.deploy(declare({ ...search, serverId: 'FAKE-id-b' }, 'Search'));
+  expect(planned).toEqual({ Search: 'replace' });
+  // ★ `defaultRemovalPolicy: 'retain'`: nothing removes a server unless the stack opts in
+  expect(fake.servers().map((row) => row['server_id'])).toEqual(['FAKE-id-a', 'FAKE-id-b']);
+});

package/src/litellm/mcp-server.ts

@@ -0,0 +1,225 @@
+/**
+ * `LiteLLM.MCPServer` — one row of LiteLLM's `LiteLLM_MCPServerTable` (`/v1/mcp/server`), an
+ * upstream MCP server the proxy's gateway exposes to keys and teams.
+ *
+ * ★ ADOPT BY NAME. `serverName` finds the live row whose `server_name` matches; declare `serverId`
+ *   to pin one instead. A live row with no state is `Unowned`, so it needs `--adopt`. Two rows with
+ *   the same name are refused, never guessed at (`LitellmMcpServerAmbiguousNameError`).
+ * ★ `defaultRemovalPolicy: 'retain'` — a server's removal takes its tools from every key, team and
+ *   seat that reaches it. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ THE CREDENTIAL IS `{ fromEnv: 'NAME' }`, NEVER A VALUE (S25): mcp-server-types.ts says why a
+ *   `Redacted` prop would still be stored in plaintext. Reading a server never reveals auth material
+ *   either — `toAttributes` copies no credential — and a rotated credential is noticed through a
+ *   seal (mcp-server-credential.ts).
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP either: `litellmProviders`' layer supplies `Credentials`.
+ * ⛔ THE LIST IS LITELLM'S IN-MEMORY REGISTRY, NOT THE TABLE (mcp-server-operations.ts): a committed row
+ *   can be missing from it. So a row the list lacks is read by id from the table (`findLive`), the read
+ *   back after a write falls back to the same read, and a delete always sends its DELETE.
+ * ⛔ AN UPDATE NEVER LETS LITELLM DEFAULT THE ALIAS (mcp-server-form.ts): the alias is the tool prefix.
+ * ⚠️ A `description` that the row's `mcp_info` would hide is refused before any write (mcp-server-shadow.ts).
+ * ⚠️ UNMEASURED AT 1.103.0, each guarded by a read back: whether a create honours a supplied
+ *   `server_id`, and whether an empty list or a `false` lands on an edit (that the edit is a partial
+ *   update is read from the source, `mcp-server-form.ts`). Nothing here assumes them; the returned
+ *   row is what is recorded.
+ */
+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 {
+  LitellmMcpServerAbsentAfterWriteError,
+  LitellmMcpServerInvalidError,
+  LitellmMcpServerNotConvergedError,
+} from './mcp-server-errors.ts';
+import {
+  credentialState,
+  requireCredential,
+  resolveCredential,
+  sealCredential,
+} from './mcp-server-credential.ts';
+import {
+  createBody,
+  differing,
+  firstProblem,
+  toAttributes,
+  updateBody,
+} from './mcp-server-form.ts';
+import { findLive, wantedId } from './mcp-server-locate.ts';
+import {
+  createMcpServer,
+  deleteMcpServer,
+  listMcpServers,
+  readMcpServer,
+  updateMcpServer,
+} from './mcp-server-operations.ts';
+import { refuseShadowedDescription } from './mcp-server-shadow.ts';
+import {
+  type McpServerAttributes,
+  type McpServerProps,
+  isStaticAuthType,
+} from './mcp-server-types.ts';
+
+export type { McpServerAttributes, McpServerProps };
+export type { McpServerError } from './mcp-server-errors.ts';
+
+export interface LiteLLMMCPServer extends Resource<
+  'LiteLLM.MCPServer',
+  McpServerProps,
+  McpServerAttributes
+> {}
+
+export const LiteLLMMCPServer = Resource<LiteLLMMCPServer>('LiteLLM.MCPServer', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMMCPServer = (value: unknown): value is LiteLLMMCPServer =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.MCPServer';
+
+const refuse = (props: McpServerProps) => {
+  const problem = firstProblem(props);
+  return problem === undefined
+    ? Effect.void
+    : Effect.fail(
+        new LitellmMcpServerInvalidError({ problem, serverName: String(props.serverName) }),
+      );
+};
+
+type Args<P> = {
+  id: string;
+  instanceId: string;
+  output: McpServerAttributes | undefined;
+} & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const mcpServerHandlers = {
+  /**
+   * ⛔ WITH NO `output` THIS IS ALCHEMY'S ADOPTION PROBE, AND THE ONLY PLAN-TIME HOOK A NEW SERVER
+   *   GETS — so the refusals run here too. Measured on beta.79 (`Plan.ts` lines 1303-1316, the
+   *   `oldState === undefined` branch): a declaration with no state row is `read` with `olds: news`
+   *   and never `diff`ed, and Apply then commits its props as `creating` BEFORE `reconcile` runs. A
+   *   URL that carries a token would already be in the unencrypted store when reconcile refused it.
+   * ★ A DEFECT (`Effect.die`), NOT A TYPED FAILURE, and that is what keeps it from wedging a stage:
+   *   the same call shape is Alchemy's recovery read of an interrupted create (`Plan.ts` lines
+   *   1428-1447), with the STORED props, and only a defect is caught there (`Effect.catchDefect`
+   *   degrades it to "nothing recovered"). A typed failure would block the plan on props that a
+   *   later, stricter release now refuses. The cold-start probe has no such catch, so there the
+   *   defect fails the plan, as intended. `pbs-notification-target-lifecycle.ts` reasons the same.
+   */
+  read: ({ id, instanceId, olds, output }: Args<{ olds: McpServerProps }>) =>
+    Effect.gen(function* () {
+      const problem = output === undefined ? firstProblem(olds) : undefined;
+      if (problem !== undefined) {
+        return yield* Effect.die(
+          new LitellmMcpServerInvalidError({ problem, serverName: String(olds.serverName) }),
+        );
+      }
+      // ★ THE LIST, THEN THE TABLE BY ID: a row the registry lacks is still a live row
+      //   (mcp-server-locate.ts). `instanceId` is what recovery of an interrupted create needs to
+      //   rebuild the deterministic id that create asked for.
+      const found = yield* findLive(id, instanceId, olds, output);
+      if (found === undefined) return undefined;
+      const live = toAttributes(found);
+      return output === undefined
+        ? Unowned(live)
+        : { ...live, credentialSeal: output.credentialSeal };
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<McpServerProps>;
+    output: McpServerAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuse(news);
+      if (output === undefined) return undefined;
+      // The id is identity: a different declared id is a different row.
+      if (news.serverId !== undefined && news.serverId !== output.serverId) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0 &&
+        credentialState(news, output.credentialSeal) !== 'stale'
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ id, instanceId, news, output }: Args<{ news: McpServerProps }>) =>
+    Effect.gen(function* () {
+      yield* refuse(news);
+      const before = yield* findLive(id, instanceId, news, output);
+      const credential = resolveCredential(news);
+      let sealed = output?.credentialSeal ?? '';
+      let serverId: string;
+
+      if (before === undefined) {
+        // A static credential is part of the create: without it the row would exist unusable.
+        yield* requireCredential(news, credential);
+        const wanted = yield* wantedId(id, instanceId, news, output);
+        const created = yield* createMcpServer(createBody(news, wanted, credential.value));
+        // ★ THE ROW LITELLM ANSWERS IS THE TRUTH: a proxy that ignores a supplied `server_id` is
+        //   recorded under the id it actually used, not the one that was asked for.
+        serverId = typeof created?.server_id === 'string' ? created.server_id : wanted;
+        sealed = credential.value === undefined ? '' : sealCredential(credential.value);
+      } else {
+        serverId = before.server_id;
+        const live = toAttributes(before);
+        const state = credentialState(news, sealed, credential);
+        if (differing(live, news).length > 0 || state === 'stale') {
+          // ⛔ A CHANGED AUTH TYPE DEMANDS THE CREDENTIAL, before anything is written: LiteLLM wipes
+          //   the stored one on an auth-class change that sends none (mcp-server-credential.ts).
+          if (live.authType !== news.authType) yield* requireCredential(news, credential);
+          // ⛔ Same rule for a description `mcp_info` would hide: before anything is written.
+          if (differing(live, news).includes('description')) {
+            yield* refuseShadowedDescription(news, serverId);
+          }
+          // ★ Otherwise sent whenever the process has it, demanded only when the seal says stale.
+          const send = isStaticAuthType(news.authType) ? credential.value : undefined;
+          const leavingStatic =
+            !isStaticAuthType(news.authType) && (sealed !== '' || isStaticAuthType(live.authType));
+          yield* updateMcpServer(updateBody(news, serverId, send, leavingStatic, live));
+          if (send !== undefined) sealed = sealCredential(send);
+          else if (leavingStatic) sealed = '';
+        }
+      }
+
+      // ★ THE LIST FIRST, THEN THE TABLE: after a create the registry refresh can fail (LiteLLM only
+      //   logs it), and a committed row that the list does not show yet is "created, not yet visible",
+      //   never absent. The by-id read also registers it, which heals the list.
+      const found =
+        (yield* listMcpServers()).find((row) => row.server_id === serverId) ??
+        (yield* readMcpServer(serverId));
+      if (found === undefined) {
+        return yield* Effect.fail(
+          new LitellmMcpServerAbsentAfterWriteError({ serverId, serverName: news.serverName }),
+        );
+      }
+      const after = toAttributes(found);
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmMcpServerNotConvergedError({
+            fields: left,
+            serverId,
+            serverName: news.serverName,
+          }),
+        );
+      }
+      return { ...after, credentialSeal: sealed };
+    }),
+
+  delete: ({ output }: { output: McpServerAttributes }) => deleteMcpServer(output.serverId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMMCPServerProvider = () =>
+  Provider.effect(
+    LiteLLMMCPServer,
+    Effect.succeed(LiteLLMMCPServer.Provider.of(mcpServerHandlers)),
+  );

package/src/litellm/model-claim.ts

@@ -0,0 +1,69 @@
+/**
+ * Whether a stateless `LiteLLM.Model` reconcile may write the live row it found.
+ *
+ * ⛔ A ROW WITH NO SEAL IS NOT YET THIS GENERATION'S. `output` is undefined on a create and on a
+ *   `replacing` row Apply committed before reconcile (Apply.ts), and a probe result carries
+ *   `paramsSeal: ''`. Either way the live row may belong to someone else.
+ * ★ TWO ROWS THAT LOOK THE SAME AND ARE NOT. A deterministic id this declaration would create is
+ *   ours by construction. An older generation's `attr.id` (ownership/rows.ts) is our own serving
+ *   deployment from before this replacement — recording it here makes destroy() delete it. A
+ *   declared id needs `--adopt` on a create or an unfinished generation; an unpinned row with any
+ *   other id is adopted only on a create (ownership/adopt.ts).
+ */
+import * as Effect from 'effect/Effect';
+import { adoptEnabled, adoptsAtApply } from '../ownership/adopt.ts';
+import { adopting } from '../ownership/adopting.ts';
+import { isCreate, olderGenerationIds } from '../ownership/rows.ts';
+import { unfinished } from '../ownership/resume.ts';
+import { LitellmModelForeignRowError, LitellmModelPriorGenerationError } from './model-errors.ts';
+import type { ModelAttributes, ModelProps } from './model-types.ts';
+
+export const claimStatelessRow = (args: {
+  readonly fqn: string;
+  readonly instanceId: string;
+  readonly output: ModelAttributes | undefined;
+  readonly news: ModelProps;
+  readonly beforeId: string;
+  readonly wanted: string;
+}): Effect.Effect<void, LitellmModelPriorGenerationError | LitellmModelForeignRowError> =>
+  Effect.gen(function* () {
+    const older = yield* olderGenerationIds(args.fqn, args.instanceId);
+    // ⛔ NOT OURS, EVEN WITH --adopt. The id is the previous generation's. Accepting it stores
+    //   that id on this generation; destroy() GC then deletes the old generation by the same id
+    //   (Apply.ts ~2168). The way back is `alchemy state rm`, then a deploy with --adopt.
+    if (older.includes(args.beforeId)) {
+      return yield* Effect.fail(
+        new LitellmModelPriorGenerationError({
+          fqn: args.fqn,
+          id: args.beforeId,
+          modelName: args.news.modelName,
+        }),
+      );
+    }
+    // ⛔ ONLY A DETERMINISTIC ID IS OURS BY CONSTRUCTION. With no declared id, `wanted` is the
+    //   physical name this declaration would create. A row found by name with any other id is not
+    //   the one this generation posted — a resumed unpinned replace must not `--adopt` it.
+    //   A DECLARED id is a name a human chose, so a matching row goes through the adoption gate,
+    //   which `--adopt` may pass for a create or an unfinished generation (the read-back that
+    //   died after `POST /model/new`).
+    const unpinned = args.news.id === undefined;
+    const ours = unpinned && args.beforeId === args.wanted;
+    const owner = { fqn: args.fqn, instanceId: args.instanceId, output: args.output };
+    const isAdoption = yield* adopting(owner, () => Effect.succeed(false));
+    const creating = yield* isCreate(args.fqn, args.instanceId);
+    const mayAdopt = unpinned
+      ? creating && (yield* adoptEnabled(args.fqn))
+      : yield* adoptsAtApply(owner);
+    if (!ours && !isAdoption && !mayAdopt) {
+      // A declared id's unfinished generation is the one `--adopt` resumes. An unpinned row whose
+      // id is not the physical name is a different deployment, replace or not.
+      const replace = unpinned ? !creating : !creating && !(yield* unfinished(args.instanceId));
+      return yield* Effect.fail(
+        new LitellmModelForeignRowError({
+          id: args.beforeId,
+          modelName: args.news.modelName,
+          replace,
+        }),
+      );
+    }
+  });

package/src/litellm/model-credential.ts

@@ -0,0 +1,45 @@
+/**
+ * The seal of a `LiteLLM.Model`'s declared `litellm_params` — the one way a plan notices a changed
+ * `model`, `apiBase` or `apiKey` when the live row hides them.
+ *
+ * ★ REFERENCE-ONLY, AND THEREFORE PURE. The credential this resource declares is LiteLLM's own
+ *   `os.environ/NAME` reference: the PROXY resolves the variable in ITS environment at inference
+ *   time, and neither the row it writes nor the wire body ever carries the value. So this module
+ *   never reads `process.env` — there is no value here to read, and a digest of a value that lives
+ *   on another host would be false drift on every plan whose deploying environment differed.
+ * ⛔ THE SEAL COVERS THE DECLARED VALUES ONLY. At v1.103.0 the read answers the stored params
+ *   DECRYPTED but STRIPS `api_key` (model-types.ts), and a credential that did come back would
+ *   only be a plaintext in state — so the live row never contributes to this comparison:
+ *   attributes carry the digest of what was DECLARED, `paramsSeal`, and a plan that changes any
+ *   of `model`, `apiBase` or the variable behind `apiKey` sees the digest change and updates.
+ *   What was last written is remembered exactly; a value the proxy strips stays quiet because
+ *   the comparison never involves it.
+ * ⛔ ADOPTED OR FOREIGN ROWS START `paramsSeal: ''` (a row cannot supply a digest of values it
+ *   hides), which reads as `stale`. A bare adopt of a visibly matching row records the digest
+ *   locally with no write; a stale seal on a declaration that manages a param the read never
+ *   shows (`api_key`, `api_base`) forces one stamping PATCH, so a different stored reference is
+ *   never sealed over. After that the seal is stable. `seals/write-only.ts` carries the scrypt
+ *   rules; see also mcp-server-credential.ts for the credential that LiteLLM STORES (this one is
+ *   only referenced).
+ */
+import { seal, sealMatches } from '../secrets/write-only.ts';
+import type { ModelProps } from './model-types.ts';
+
+/**
+ * The declared `litellm_params` as the reference form names them — the input to the seal. `model`
+ * and `api_base` are what the proxy routes on; `api_key` is the reference LiteLLM resolves in its
+ * own environment. No value, ever: there is no lookup and no environment here.
+ */
+export const declaredValues = (props: ModelProps): Record<string, string> => {
+  const values: Record<string, string> = { model: props.model };
+  if (props.apiBase !== undefined) values['api_base'] = props.apiBase;
+  if (props.apiKey !== undefined) values['api_key'] = `os.environ/${props.apiKey.fromEnv}`;
+  return values;
+};
+
+/** `scrypt:<salt>:<digest>` of declared values, for `paramsSeal`. ⛔ Never a secret value. */
+export const sealFromValues = (values: Record<string, string>): string => seal(values);
+
+/** Whether the declaration's values are the ones `sealed` was made from. */
+export const sealState = (props: ModelProps, sealed: string): 'match' | 'stale' =>
+  sealMatches(sealed, declaredValues(props)) ? 'match' : 'stale';