@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/model-errors.ts

@@ -0,0 +1,168 @@
+/**
+ * The typed refusals `LiteLLM.Model` raises on top of `@distilled.cloud/litellm`'s own SDK errors.
+ *
+ * ⛔ NO MESSAGE HERE MAY CARRY A CREDENTIAL: only names, ids, field names and the NAME of an
+ *   environment variable, exactly like mcp-server-errors.ts.
+ */
+import type { BadRequest, NotFound } from '@distilled.cloud/litellm/Errors';
+import type * as models from '@distilled.cloud/litellm/model_management';
+import * as Data from 'effect/Data';
+
+/** A declaration the resource refuses before any request: a combination nobody meant. */
+export class LitellmModelInvalidError extends Data.TaggedError('LitellmModelInvalidError')<{
+  readonly modelName: string;
+  readonly problem: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.Model "${this.modelName}": ${this.problem}.`;
+  }
+}
+
+/**
+ * More than one live deployment carries the declared `model_name`, so adopt-by-name cannot say
+ * which one is meant — LiteLLM runs several deployments under one group name on purpose. Declare
+ * `id` to pick one; nothing is adopted, updated or deleted on a guess.
+ */
+export class LitellmModelAmbiguousNameError extends Data.TaggedError(
+  'LitellmModelAmbiguousNameError',
+)<{
+  readonly modelName: string;
+  readonly ids: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Model "${this.modelName}": ${this.ids.length} live deployments carry that name ` +
+      `(${this.ids.join(', ')}). Declare \`id\` to choose one.`
+    );
+  }
+}
+
+/** `GET /model/info` answered something that is not a list of deployments. */
+export class LitellmModelUnreadableError extends Data.TaggedError('LitellmModelUnreadableError')<{
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.Model: the deployment list is unreadable (${this.reason}).`;
+  }
+}
+
+/**
+ * A create or update returned no error, yet no read answers a deployment with the id it was written
+ * under: not in the list, and not by the id it would carry.
+ */
+export class LitellmModelAbsentAfterWriteError extends Data.TaggedError(
+  'LitellmModelAbsentAfterWriteError',
+)<{
+  readonly modelName: string;
+  readonly id: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Model "${this.modelName}": the write of ${this.id} returned no error but the ` +
+      'deployment is absent from the list and from the by-id read.'
+    );
+  }
+}
+
+/**
+ * The write returned no error but the deployment still differs from the declaration. The PATCH
+ * merge writes the keys it was sent (`update_db_model` at v1.103.0); a field the read-back still
+ * shows different is refused here instead of being reported as converged.
+ */
+export class LitellmModelNotConvergedError extends Data.TaggedError(
+  'LitellmModelNotConvergedError',
+)<{
+  readonly modelName: string;
+  readonly id: string;
+  readonly fields: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Model "${this.modelName}": after the write, ${this.id} still differs from the ` +
+      `declaration in ${this.fields.join(', ')}.`
+    );
+  }
+}
+
+/**
+ * A reconcile with no state found a live row under the declared name whose id is not the one this
+ * declaration would create, and nothing vouchsafes it: writing over it would take over another
+ * owner's deployment. `replace` says whether this generation is a replace's new identity (a changed
+ * declared id), which `--adopt` does not cover — the object must be removed first.
+ */
+export class LitellmModelForeignRowError extends Data.TaggedError('LitellmModelForeignRowError')<{
+  readonly modelName: string;
+  readonly id: string;
+  readonly replace: boolean;
+}> {
+  override get message(): string {
+    const remedy = this.replace
+      ? 'It is the new identity of a replace, which --adopt does not cover: remove it first.'
+      : 'Deploy with --adopt to take it over, or remove it first.';
+    return (
+      `LiteLLM.Model "${this.modelName}": the live row ${this.id} already exists and this stack ` +
+      `holds no state for it. Nothing was written. ${remedy}`
+    );
+  }
+}
+
+/**
+ * The row a reconcile found is served from the proxy's config file (`model_info.db_model: false`),
+ * not from the database, so the DB API cannot manage it. Remove it from the config file first.
+ */
+/**
+ * The live row a stateless reconcile found is an OLDER generation of this FQN's own state chain
+ * (`attr.id` walked through `old`). It is still the serving deployment: the replacement that
+ * followed it never committed. Taking the row over would store that id on the new generation, and
+ * `destroy()` then deletes the old generation by the same id.
+ * ⛔ THE RECOVERY IS STATE, NOT THE ROW. `alchemy state rm` deletes the state record and leaves the
+ *   deployment; deleting the live row takes the serving model out of its group.
+ */
+export class LitellmModelPriorGenerationError extends Data.TaggedError(
+  'LitellmModelPriorGenerationError',
+)<{
+  readonly modelName: string;
+  readonly id: string;
+  readonly fqn: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Model "${this.modelName}": the live row ${this.id} is an older generation still ` +
+      `recorded on ${this.fqn}. Nothing was written. Taking it over would store that id on the ` +
+      'in-flight replacement, and destroy() then deletes the old generation by the same id. ' +
+      "Drop this resource's state row (alchemy state rm, which leaves the deployment) and " +
+      'deploy again with --adopt. Do not delete the live row.'
+    );
+  }
+}
+
+export class LitellmModelConfigFileRowError extends Data.TaggedError(
+  'LitellmModelConfigFileRowError',
+)<{
+  readonly modelName: string;
+  readonly id: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.Model "${this.modelName}": the live row ${this.id} is served from the proxy's ` +
+      'config file (db_model: false), not from the database, so the DB API cannot manage it. ' +
+      'Remove it from the config file first.'
+    );
+  }
+}
+
+export type ModelError =
+  | models.AddNewModelModelNewPostError
+  | models.DeleteModelModelDeletePostError
+  | models.GetModelInfoV1ModelInfoError
+  | models.PatchModelModelModelIdUpdatePatchError
+  | BadRequest
+  | NotFound
+  | LitellmModelInvalidError
+  | LitellmModelAmbiguousNameError
+  | LitellmModelUnreadableError
+  | LitellmModelAbsentAfterWriteError
+  | LitellmModelNotConvergedError
+  | LitellmModelForeignRowError
+  | LitellmModelPriorGenerationError
+  | LitellmModelConfigFileRowError;

package/src/litellm/model-foreign-row.test.ts

@@ -0,0 +1,173 @@
+/**
+ * A replace (an unpinned rename, or a changed declared id) reaches `reconcile` with `output`
+ * undefined and a live row under the name or id it is moving onto — and that row may belong to
+ * another owner. The old gate let it take the row over (measured live on a throwaway 1.103.0
+ * proxy through Alchemy's real Plan and Apply: the foreign row's model was overwritten, its
+ * access group cleared, its `extra_headers` dropped, and state recorded the foreign id, so a
+ * later destroy deleted another owner's deployment). The gate in model.ts now counts only a row
+ * whose id is the deterministic one this declaration would create (`ours`); anything else is
+ * refused (`LitellmModelForeignRowError`), and a declared id that points at an existing row goes
+ * through the `Unowned`/`--adopt` gate like any adoption.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`, through Alchemy's real Plan and Apply over the fake proxy.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type FakeModelLitellm, modelRow, startFakeModelLitellm } from './fake-model-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMModel } from './model.ts';
+import type { ModelProps } from './model-types.ts';
+
+type Row = Record<string, unknown>;
+
+const KEY = 'sk-test-master';
+const stack = (fake: FakeModelLitellm) =>
+  fakeStack({ apiKey: KEY, baseUrl: 'https://litellm.example.com' }, fake.fetch);
+const declare = (props: ModelProps, name = 'Grok') =>
+  Effect.gen(function* () {
+    yield* LiteLLMModel(name, props);
+  });
+
+const grok: ModelProps = {
+  apiKey: { fromEnv: 'FAKE_XAI_KEY' },
+  model: 'xai/grok-4.7',
+  modelName: 'grok',
+};
+
+/** A one-deployment group a foreign owner runs: a gateway auth header, a weight, a group. */
+const foreign = modelRow({
+  litellm_params: {
+    extra_headers: { 'X-Gateway-Auth': 'FAKE-gateway-credential' },
+    model: 'xai/grok-4.6',
+    weight: 2,
+  },
+  model_info: { access_groups: ['FAKE-team'], id: 'FAKE-foreign-id' },
+  model_name: 'grok',
+});
+
+const rowAt = (fake: FakeModelLitellm, id: string): Row =>
+  (fake.models().find((each) => ((each['model_info'] as Row)['id'] as string) === id) ?? {}) as Row;
+
+test('an unpinned rename onto a foreign row is refused and the row is untouched', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [foreign] });
+  const engine = stack(fake);
+  // The stack first owns a row under another name, so the next declaration is a REPLACE.
+  expect(await engine.deploy(declare({ ...grok, modelName: 'old-name' }))).toEqual({
+    Grok: 'create',
+  });
+  const before = fake.requests().length;
+  await expect(engine.deploy(declare(grok))).rejects.toThrow(/--adopt does not cover/);
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  // 🔴 the measured takeover wrote the model, cleared the group and dropped extra_headers here.
+  expect(rowAt(fake, 'FAKE-foreign-id')).toMatchObject({
+    litellm_params: {
+      extra_headers: { 'X-Gateway-Auth': 'FAKE-gateway-credential' },
+      model: 'xai/grok-4.6',
+      weight: 2,
+    },
+    model_info: { access_groups: ['FAKE-team'] },
+    model_name: 'grok',
+  });
+  // The rename refused, the stack's own row is neither deleted nor renamed either.
+  expect(writesOf(fake.requests())).toEqual(['POST /model/new']);
+});
+
+test('an unpinned rename onto a foreign row is refused even with --adopt', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [foreign] });
+  const engine = stack(fake);
+  await engine.deploy(declare({ ...grok, modelName: 'old-name' }));
+  const before = fake.requests().length;
+  // 🔴 A replace's new identity is never probed and never offered adoption: Apply commits it as
+  //   `replacing`, so `--adopt` cannot speak for it (ownership/adopt.ts). Refused, not adopted.
+  await expect(engine.deploy(declare(grok), { adopt: true })).rejects.toThrow(
+    /--adopt does not cover/,
+  );
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('reverting an unpinned rename that hit a foreign row names a state recovery', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [foreign] });
+  const engine = stack(fake);
+  expect(await engine.deploy(declare({ ...grok, modelName: 'old-name' }))).toEqual({
+    Grok: 'create',
+  });
+  // The refusal is right, and Apply has already committed the `replacing` row.
+  await expect(engine.deploy(declare(grok))).rejects.toThrow(/--adopt does not cover/);
+  const before = fake.requests().length;
+  // The engine resumes that same replacement. Reconcile finds the stack's own serving row by
+  // the old name. Its id is the previous generation's, not this instance's physical name.
+  await expect(engine.deploy(declare({ ...grok, modelName: 'old-name' }))).rejects.toThrow(
+    /older generation/,
+  );
+  await expect(
+    engine.deploy(declare({ ...grok, modelName: 'old-name' }), { adopt: true }),
+  ).rejects.toThrow(/alchemy state rm/);
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  expect(rowAt(fake, 'FAKE-foreign-id')).toMatchObject({
+    litellm_params: { model: 'xai/grok-4.6' },
+    model_name: 'grok',
+  });
+  const serving = fake.models().find((row) => row['model_name'] === 'old-name');
+  if (serving === undefined) throw new Error("the stack's own row is gone");
+  expect((serving['model_info'] as Row)['id']).not.toBe('FAKE-foreign-id');
+});
+
+test('a changed declared id pointing at a foreign row is refused, the row untouched', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [foreign] });
+  const engine = stack(fake);
+  expect(
+    await engine.deploy(declare({ ...grok, id: 'FAKE-ours-id', modelName: 'old-name' })),
+  ).toEqual({ Grok: 'create' });
+  const before = fake.requests().length;
+  // The id is identity: declaring the foreign row's id is a replace onto it — refused, whether
+  // it is `--adopt` or not, because the probe never asked whose row the replacement would move to.
+  await expect(
+    engine.deploy(declare({ ...grok, id: 'FAKE-foreign-id', modelName: 'old-name' }), {
+      adopt: true,
+    }),
+  ).rejects.toThrow(/FAKE-foreign-id/);
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  expect(rowAt(fake, 'FAKE-foreign-id')).toMatchObject({
+    model_info: { access_groups: ['FAKE-team'] },
+  });
+  // The stack's own row survives the failed replace (`retain`), and the foreign row is intact.
+  expect(rowAt(fake, 'FAKE-ours-id')).toMatchObject({ model_name: 'old-name' });
+});
+
+test('a declared id on a foreign row goes through the Unowned gate: refused, then adopted', async () => {
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [foreign] });
+  const engine = stack(fake);
+  // No state at all: the plan's probe answers Unowned, so the deploy refuses without --adopt.
+  await expect(engine.deploy(declare({ ...grok, id: 'FAKE-foreign-id' }))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  // With --adopt it is an explicit adoption: the drift (a different model) PATCHes with the
+  // row's own id in model_info, and the second deploy is a no-op on it.
+  expect(await engine.deploy(declare({ ...grok, id: 'FAKE-foreign-id' }), { adopt: true })).toEqual(
+    { Grok: 'adopted' },
+  );
+  expect(writesOf(fake.requests())).toEqual(['PATCH /model/FAKE-foreign-id/update']);
+  const adopted = rowAt(fake, 'FAKE-foreign-id');
+  expect(adopted['litellm_params']).toMatchObject({ model: 'xai/grok-4.7' });
+  expect(adopted['model_info']).toMatchObject({ access_groups: [] });
+  expect(await engine.deploy(declare({ ...grok, id: 'FAKE-foreign-id' }), { adopt: true })).toEqual(
+    { Grok: 'noop' },
+  );
+});
+
+test('a config-file row is refused at adopt, even with --adopt', async () => {
+  const config = modelRow({
+    litellm_params: { model: 'xai/grok-4.6' },
+    model_info: { access_groups: ['FAKE-team'], db_model: false, id: 'FAKE-config-id' },
+    model_name: 'grok',
+  });
+  const fake = startFakeModelLitellm({ masterKey: KEY, seed: [config] });
+  const engine = stack(fake);
+  // The DB API cannot manage what the proxy serves from its config file, so --adopt must not
+  // take it over either: the gate refuses before a single write.
+  await expect(engine.deploy(declare(grok), { adopt: true })).rejects.toThrow(/config file/);
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(rowAt(fake, 'FAKE-config-id')).toMatchObject({
+    model_info: { access_groups: ['FAKE-team'], db_model: false },
+    model_name: 'grok',
+  });
+});

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

@@ -0,0 +1,228 @@
+/**
+ * `LiteLLM.Model`'s pure form, with no server and no environment: the plan-time refusals, the wire
+ * bodies, the read shape under encryption, and the comparison. The credential is a reference, so
+ * nothing here reads (or could read) a value.
+ */
+import { describe, expect, test } from 'bun:test';
+import { declaredValues, sealFromValues, sealState } from './model-credential.ts';
+import {
+  createBody,
+  declaredDigest,
+  differing,
+  firstProblem,
+  patchBody,
+  toAttributes,
+} from './model-form.ts';
+import type { ModelProps } from './model-types.ts';
+
+type Row = Record<string, unknown>;
+
+const props: ModelProps = {
+  apiKey: { fromEnv: 'FAKE_XAI_KEY' },
+  model: 'xai/grok-4.7',
+  modelName: 'grok',
+};
+
+describe('firstProblem refuses', () => {
+  test('a blank or padded model name', () => {
+    expect(firstProblem({ ...props, modelName: '' })).toContain('modelName');
+    expect(firstProblem({ ...props, modelName: ' grok' })).toContain('modelName');
+  });
+
+  test('a blank id', () => {
+    expect(firstProblem({ ...props, id: '  ' })).toContain('id');
+  });
+
+  test('a model without a provider prefix', () => {
+    expect(firstProblem({ ...props, model: 'grok-4.7' })).toContain('provider prefix');
+  });
+
+  test('the openai/ prefix on a grok-named group: Grok is xAI', () => {
+    expect(firstProblem({ ...props, model: 'openai/grok-4.7' })).toContain('xAI');
+  });
+
+  test('an api_base that carries a secret, a userinfo or a fragment', () => {
+    expect(firstProblem({ ...props, apiBase: 'https://api.xai.example.com?token=FAKE' })).toContain(
+      'credential',
+    );
+    expect(firstProblem({ ...props, apiBase: 'https://user:FAKE@api.xai.example.com' })).toContain(
+      'userinfo',
+    );
+    expect(firstProblem({ ...props, apiBase: 'https://api.xai.example.com#frag' })).toContain(
+      'fragment',
+    );
+  });
+
+  test('an apiKey value instead of a reference', () => {
+    expect(firstProblem({ ...props, apiKey: 'FAKE-literal-value' as never })).toContain(
+      'never a value',
+    );
+    expect(firstProblem({ ...props, apiKey: { fromEnv: '' } })).toContain('environment variable');
+  });
+
+  test('nothing else: a well-formed declaration passes', () => {
+    expect(firstProblem(props)).toBeUndefined();
+    expect(
+      firstProblem({
+        apiBase: 'https://api.xai.example.com',
+        baseModel: 'grok-4',
+        id: 'FAKE-id',
+        mode: 'chat',
+        model: 'cloudflare/@cf/meta/llama-3.1-8b-instruct',
+        modelName: 'llama',
+      }),
+    ).toBeUndefined();
+  });
+});
+
+describe('the wire bodies', () => {
+  test('a create sends the group, the id it asks for, and the reference credential', () => {
+    // `as Row`: the SDK's 1.103.0 request type does not declare `access_groups` (model-form.ts)
+    expect(createBody(props, 'FAKE-wanted') as unknown as Row).toEqual({
+      litellm_params: { api_key: 'os.environ/FAKE_XAI_KEY', model: 'xai/grok-4.7' },
+      model_info: { access_groups: [], id: 'FAKE-wanted' },
+      model_name: 'grok',
+    });
+  });
+
+  test('a declared api_base, mode, base model and groups are sent', () => {
+    const declared: ModelProps = {
+      accessGroups: ['FAKE-team'],
+      apiBase: 'https://api.xai.example.com',
+      baseModel: 'grok-4',
+      mode: 'chat',
+      model: 'xai/grok-4.7',
+      modelName: 'grok',
+    };
+    expect(createBody(declared, 'FAKE-wanted')).toMatchObject({
+      litellm_params: { api_base: 'https://api.xai.example.com' },
+      model_info: {
+        access_groups: ['FAKE-team'],
+        base_model: 'grok-4',
+        mode: 'chat',
+      },
+    });
+  });
+
+  test('a patch re-sends the managed set, the row id, and the group name only when it changed', () => {
+    const live = toAttributes({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_info: { id: 'FAKE-live-id' },
+      model_name: 'grok',
+    });
+    const sameName = patchBody(props, live) as Row;
+    expect(sameName['litellm_params']).toEqual({
+      allow_client_keepalive_override: null,
+      api_key: 'os.environ/FAKE_XAI_KEY',
+      merge_reasoning_content_in_choices: null,
+      model: 'xai/grok-4.7',
+      use_in_pass_through: null,
+      use_litellm_proxy: null,
+      use_xai_oauth: null,
+    });
+    expect('model_name' in sameName).toBe(false);
+    // ★ The row's own id rides the body: an adopt-by-id re-affirms the row it pinned.
+    expect(sameName['model_info']).toEqual({ access_groups: [], id: 'FAKE-live-id' });
+    expect(sameName['model_id']).toBe('FAKE-live-id');
+
+    const renamed = patchBody({ ...props, modelName: 'grok-fast' }, live) as Row;
+    expect(renamed['model_name']).toBe('grok-fast');
+  });
+
+  test('an undeclared mode, base model and credential are never sent, so the row keeps its own', () => {
+    const live = toAttributes({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_info: { id: 'FAKE-live-id' },
+      model_name: 'grok',
+    });
+    const bare: ModelProps = { model: 'xai/grok-4.7', modelName: 'grok' };
+    const body = patchBody(bare, live) as Row;
+    expect(body['litellm_params']).toMatchObject({
+      model: 'xai/grok-4.7',
+      use_in_pass_through: null,
+      use_xai_oauth: null,
+    });
+    expect(body['model_info']).toEqual({ access_groups: [], id: 'FAKE-live-id' });
+    expect((patchBody({ ...bare, mode: 'chat' }, live) as Row)['model_info']).toEqual({
+      access_groups: [],
+      id: 'FAKE-live-id',
+      mode: 'chat',
+    });
+  });
+});
+
+describe('the declared seal', () => {
+  test('matches what a write stamps, and round-trips', () => {
+    const sealed = sealFromValues(declaredValues(props));
+    expect(sealed).not.toBe('');
+    expect(sealState(props, sealed)).toBe('match');
+  });
+
+  test('an adopted row without a seal is stale, so the next reconcile records it locally', () => {
+    expect(sealState(props, '')).toBe('stale');
+  });
+
+  test('a change of model, api_base or reference NAME moves the seal (the value never does)', () => {
+    const sealed = declaredDigest(props);
+    expect(sealState({ ...props, model: 'xai/grok-4.6' }, sealed)).toBe('stale');
+    expect(sealState({ ...props, apiBase: 'https://api.xai.example.com' }, sealed)).toBe('stale');
+    expect(sealState({ ...props, apiKey: { fromEnv: 'FAKE_XAI_KEY_TWO' } }, sealed)).toBe('stale');
+    expect(sealState(props, 'garbage')).toBe('stale');
+  });
+});
+
+describe('toAttributes and differing', () => {
+  test('reads the id from wherever the proxy carried it', () => {
+    expect(toAttributes({ model_info: { id: 'i' }, model_name: 'grok' }).id).toBe('i');
+    expect(toAttributes({ id: 'top', model_name: 'grok' }).id).toBe('top');
+  });
+
+  test('a ciphertext params field hides the model; an object one carries it as it is', () => {
+    const encrypted = toAttributes({
+      litellm_params: '<encrypted>',
+      model_name: 'grok',
+    });
+    expect(encrypted.model).toBeNull();
+    expect(differing(encrypted, props)).toEqual([]);
+    const visible = toAttributes({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_name: 'grok',
+    });
+    expect(visible.model).toBe('xai/grok-4.7');
+  });
+
+  test('never copies api_base or api_key, and no row supplies a digest', () => {
+    const live = toAttributes({
+      litellm_params: {
+        api_base: 'https://api.xai.example.com',
+        api_key: 'os.environ/FAKE_XAI_KEY',
+        model: 'xai/grok-4.7',
+      },
+      model_info: { id: 'i' },
+      model_name: 'grok',
+    });
+    expect(JSON.stringify(live)).not.toContain('FAKE_XAI_KEY');
+    expect(live.paramsSeal).toBe('');
+  });
+
+  test('names exactly the fields where the row and the declaration disagree', () => {
+    const live = toAttributes({
+      litellm_params: { model: 'xai/grok-4.7' },
+      model_info: { access_groups: ['FAKE-team'], id: 'i', mode: 'chat' },
+      model_name: 'grok',
+    });
+    expect(differing(live, props)).toEqual(['access_groups']);
+    expect(differing(live, { ...props, mode: 'chat' })).toEqual(['access_groups']);
+    expect(differing(live, { ...props, accessGroups: ['FAKE-team'], mode: 'chat' })).toEqual([]);
+    expect(differing(live, { ...props, modelName: 'grok-fast' })).toEqual([
+      'model_name',
+      'access_groups',
+    ]);
+    // ★ access groups compare as a set, order-free
+    const shuffled = toAttributes({
+      model_info: { access_groups: ['b', 'a'], id: 'i' },
+      model_name: 'grok',
+    });
+    expect(differing(shuffled, { ...props, accessGroups: ['a', 'b'] })).toEqual([]);
+  });
+});