@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/policy.ts

@@ -0,0 +1,146 @@
+/**
+ * `LiteLLM.Policy` — the PRODUCTION version of one named policy in LiteLLM's policy engine
+ * (`LiteLLM_PolicyTable`, `/policies`): a set of guardrails to add and remove, with an optional model
+ * condition. Props, the versioning and what is left out: policy-types.ts.
+ *
+ * ★ A CHANGE IS A NEW VERSION, PROMOTED. Only a draft is editable and only production is enforced, so
+ *   an update clones production to a draft, edits it, publishes it and promotes it; the old production
+ *   stays as a `published` version. A run that stops midway leaves a draft or a published copy, both
+ *   inert; the next run starts from production again and never touches a version it did not make.
+ * ★ ADOPT BY NAME. A live production version with no state is `Unowned`, so it needs `--adopt`.
+ * ⛔ A POLICY THAT EXISTS ONLY IN config.yaml IS NEVER SHADOWED BY ACCIDENT: a create refuses when the
+ *   name belongs to a config policy, because a production DB policy would override it at runtime.
+ * ⛔ NO PRODUCTION VERSION IS NEVER GUESSED AT: a name whose versions are all `draft` or `published`
+ *   (someone demoted it) is refused with the count, not promoted.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting removes EVERY version (the history) and stops the
+ *   guardrails applying wherever an attachment pointed at it. Opt in with `RemovalPolicy.destroy()`.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `policy_endpoints.py` and `policy_engine/*.py` have no
+ *   `premium_user` check (grep, 1.103.0). The docs page says team/key-based attachment needs Enterprise
+ *   (docs.litellm.ai/docs/proxy/guardrails/guardrail_policies); whether a CE proxy enforces one is
+ *   UNVERIFIED. The `policies` metadata of a team or key IS gated (`_premium_user_check`).
+ * ⛔ 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, toAttributes, updateBody } from './policy-form.ts';
+import {
+  configPolicyNames,
+  createDraft,
+  createPolicy,
+  deleteAllVersions,
+  editDraft,
+  listPolicyVersions,
+  setVersionStatus,
+} from './policy-operations.ts';
+import type { PolicyAttributes, PolicyProps, PolicyVersion } from './policy-types.ts';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryInvalidError,
+  LitellmRegistryNotConvergedError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+
+export type { PolicyAttributes, PolicyProps };
+export type { RegistryError as PolicyError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.Policy';
+
+export interface LiteLLMPolicy extends Resource<'LiteLLM.Policy', PolicyProps, PolicyAttributes> {}
+
+export const LiteLLMPolicy = Resource<LiteLLMPolicy>('LiteLLM.Policy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMPolicy = (value: unknown): value is LiteLLMPolicy =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Policy';
+
+const production = (versions: readonly PolicyVersion[]) =>
+  versions.find((version) => version.versionStatus === 'production');
+
+const invalid = (name: string, problem: string) =>
+  Effect.fail(new LitellmRegistryInvalidError({ name, problem, resource: RESOURCE }));
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const policyHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: PolicyProps; output: PolicyAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.policyName), firstProblem(olds));
+      }
+      const live = production(yield* listPolicyVersions(output?.policyName ?? olds.policyName));
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(toAttributes(live)) : toAttributes(live);
+    }),
+
+  diff: ({ news, output }: { news: Input<PolicyProps>; output: PolicyAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.policyName), firstProblem(news));
+      if (output === undefined) return undefined;
+      // The name is identity: a different name is a different policy.
+      if (news.policyName !== output.policyName) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ news }: { news: PolicyProps }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.policyName), firstProblem(news));
+      const versions = yield* listPolicyVersions(news.policyName);
+      const live = production(versions);
+      if (versions.length === 0) {
+        if ((yield* configPolicyNames()).includes(news.policyName)) {
+          return yield* invalid(
+            news.policyName,
+            'a policy of this name is defined in config.yaml, and a production DB policy would override it at runtime; rename this one or remove the config policy first',
+          );
+        }
+        yield* createPolicy(createBody(news));
+      } else if (live === undefined) {
+        return yield* invalid(
+          news.policyName,
+          `${versions.length} version(s) exist and none is production, so the policy is inactive; promote one in LiteLLM (or delete its versions) instead of letting this guess`,
+        );
+      } else if (differing(live, news).length > 0) {
+        const draft = yield* createDraft(news.policyName);
+        yield* editDraft(draft.policyId, updateBody(news, live));
+        yield* setVersionStatus(draft.policyId, 'published');
+        yield* setVersionStatus(draft.policyId, 'production');
+      }
+
+      const after = production(yield* listPolicyVersions(news.policyName));
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.policyName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.policyName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return toAttributes(after);
+    }),
+
+  delete: ({ output }: { output: PolicyAttributes }) => deleteAllVersions(output.policyName),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMPolicyProvider = () =>
+  Provider.effect(LiteLLMPolicy, Effect.succeed(LiteLLMPolicy.Provider.of(policyHandlers)));

package/src/litellm/providers.ts

@@ -20,10 +20,31 @@
  */
 import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/Credentials';
 import * as Layer from 'effect/Layer';
+import { LiteLLMAccessGroupProvider } from './access-group.ts';
 import { LiteLLMBudgetProvider } from './budget.ts';
+import { LiteLLMCredentialProvider } from './credential.ts';
+import { LiteLLMMCPServerProvider } from './mcp-server.ts';
+import { LiteLLMKeyProvider } from './key.ts';
+import { LiteLLMModelProvider } from './model.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
+import { LiteLLMPolicyAttachmentProvider } from './policy-attachment.ts';
+import { LiteLLMPolicyProvider } from './policy.ts';
+import { LiteLLMTeamProvider } from './team.ts';
+import { LiteLLMToolPolicyProvider } from './tool-policy.ts';
+import { LiteLLMToolsetProvider } from './toolset.ts';
 
 export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFromEnv) =>
-  Layer.mergeAll(LiteLLMPassThroughEndpointProvider(), LiteLLMBudgetProvider()).pipe(
-    Layer.provideMerge(creds),
-  );
+  Layer.mergeAll(
+    LiteLLMPassThroughEndpointProvider(),
+    LiteLLMBudgetProvider(),
+    LiteLLMCredentialProvider(),
+    LiteLLMMCPServerProvider(),
+    LiteLLMAccessGroupProvider(),
+    LiteLLMToolsetProvider(),
+    LiteLLMToolPolicyProvider(),
+    LiteLLMPolicyProvider(),
+    LiteLLMPolicyAttachmentProvider(),
+    LiteLLMTeamProvider(),
+    LiteLLMKeyProvider(),
+    LiteLLMModelProvider(),
+  ).pipe(Layer.provideMerge(creds));

package/src/litellm/registry-errors.ts

@@ -0,0 +1,88 @@
+/**
+ * The typed refusals the LiteLLM registry resources (`LiteLLM.Team`, `AccessGroup`, `Toolset`,
+ * `Policy`, `PolicyAttachment`, `ToolPolicy`) raise on top of `@distilled.cloud/litellm`'s own SDK
+ * errors. One small set, tagged with the resource it came from, so a stack's error handling does not
+ * grow six near-identical classes.
+ *
+ * ⛔ NO MESSAGE HERE MAY CARRY A CREDENTIAL. What is named: the resource type, the declared name or
+ *   id, ids the proxy already lists, and field names. Never a description (free text a person wrote)
+ *   and never a request body.
+ */
+import * as Data from 'effect/Data';
+
+/** A declaration the resource refuses before any request: a combination nobody meant. */
+export class LitellmRegistryInvalidError extends Data.TaggedError('LitellmRegistryInvalidError')<{
+  readonly resource: string;
+  readonly name: string;
+  readonly problem: string;
+}> {
+  override get message(): string {
+    return `${this.resource} "${this.name}": ${this.problem}.`;
+  }
+}
+
+/** A list or read answered something that is not the rows this resource expects. */
+export class LitellmRegistryUnreadableError extends Data.TaggedError(
+  'LitellmRegistryUnreadableError',
+)<{
+  readonly resource: string;
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `${this.resource}: the proxy's answer is unreadable (${this.reason}).`;
+  }
+}
+
+/**
+ * More than one live row could be the declared one, so adopting by name cannot say which. Nothing is
+ * adopted, updated or deleted on a guess: declare the id to choose one.
+ */
+export class LitellmRegistryAmbiguousError extends Data.TaggedError(
+  'LitellmRegistryAmbiguousError',
+)<{
+  readonly resource: string;
+  readonly name: string;
+  readonly ids: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `${this.resource} "${this.name}": ${this.ids.length} live rows match (${this.ids.join(', ')}). ` +
+      'Declare the id to choose one.'
+    );
+  }
+}
+
+/** A write returned no error, yet the row is not there on the read back. */
+export class LitellmRegistryAbsentAfterWriteError extends Data.TaggedError(
+  'LitellmRegistryAbsentAfterWriteError',
+)<{
+  readonly resource: string;
+  readonly name: string;
+}> {
+  override get message(): string {
+    return `${this.resource} "${this.name}": the write returned no error but the row is absent on the read back.`;
+  }
+}
+
+/**
+ * A write returned no error, yet the row still differs from the declaration. The route may merge with
+ * `exclude_none` or a truthiness check; the read back says so instead of reporting a converged row.
+ */
+export class LitellmRegistryNotConvergedError extends Data.TaggedError(
+  'LitellmRegistryNotConvergedError',
+)<{
+  readonly resource: string;
+  readonly name: string;
+  readonly fields: readonly string[];
+}> {
+  override get message(): string {
+    return `${this.resource} "${this.name}": after the write, the row still differs in ${this.fields.join(', ')}.`;
+  }
+}
+
+export type RegistryError =
+  | LitellmRegistryInvalidError
+  | LitellmRegistryUnreadableError
+  | LitellmRegistryAmbiguousError
+  | LitellmRegistryAbsentAfterWriteError
+  | LitellmRegistryNotConvergedError;

package/src/litellm/registry-exports.test.ts

@@ -0,0 +1,66 @@
+/**
+ * The public barrel re-exports the six registry resources, their providers and guards, and the shared
+ * typed refusals. A missing name here is a runtime import failure for a consumer, and nothing else in
+ * the tests goes through `index.ts`.
+ */
+import { expect, test } from 'bun:test';
+import * as barrel from './index.ts';
+
+const RESOURCES = [
+  ['LiteLLMTeam', 'isLiteLLMTeam', 'LiteLLM.Team', 'LiteLLMTeamProvider'],
+  [
+    'LiteLLMAccessGroup',
+    'isLiteLLMAccessGroup',
+    'LiteLLM.AccessGroup',
+    'LiteLLMAccessGroupProvider',
+  ],
+  ['LiteLLMToolset', 'isLiteLLMToolset', 'LiteLLM.Toolset', 'LiteLLMToolsetProvider'],
+  ['LiteLLMPolicy', 'isLiteLLMPolicy', 'LiteLLM.Policy', 'LiteLLMPolicyProvider'],
+  [
+    'LiteLLMPolicyAttachment',
+    'isLiteLLMPolicyAttachment',
+    'LiteLLM.PolicyAttachment',
+    'LiteLLMPolicyAttachmentProvider',
+  ],
+  ['LiteLLMToolPolicy', 'isLiteLLMToolPolicy', 'LiteLLM.ToolPolicy', 'LiteLLMToolPolicyProvider'],
+] as const;
+
+test('every registry resource, guard and provider is on the barrel, and the guard tells its own type', () => {
+  const exported = barrel as unknown as Record<string, unknown>;
+  for (const [resource, guard, type, provider] of RESOURCES) {
+    expect(exported[resource]).toBeDefined();
+    expect(typeof exported[provider]).toBe('function');
+    const isType = exported[guard] as (value: unknown) => boolean;
+    expect(isType({ Type: type })).toBe(true);
+    expect(isType({ Type: 'LiteLLM.Budget' })).toBe(false);
+    expect(isType(undefined)).toBe(false);
+  }
+});
+
+test('the shared typed refusals are on the barrel and name their resource and subject', () => {
+  const invalid = new barrel.LitellmRegistryInvalidError({
+    name: 'FAKE-name',
+    problem: 'a problem',
+    resource: 'LiteLLM.Team',
+  });
+  expect(invalid._tag).toBe('LitellmRegistryInvalidError');
+  expect(invalid.message).toBe('LiteLLM.Team "FAKE-name": a problem.');
+  expect(
+    new barrel.LitellmRegistryNotConvergedError({
+      fields: ['models'],
+      name: 'FAKE-name',
+      resource: 'LiteLLM.Team',
+    }).message,
+  ).toContain('models');
+  for (const each of [
+    barrel.LitellmRegistryAbsentAfterWriteError,
+    barrel.LitellmRegistryAmbiguousError,
+    barrel.LitellmRegistryUnreadableError,
+  ]) {
+    expect(typeof each).toBe('function');
+  }
+});
+
+test('litellmProviders() builds a layer with every provider merged in', () => {
+  expect(barrel.litellmProviders()).toBeDefined();
+});

package/src/litellm/registry-support.ts

@@ -0,0 +1,109 @@
+/**
+ * Small pure helpers the LiteLLM registry resources share (`LiteLLM.Team`, `AccessGroup`,
+ * `Toolset`, `Policy`, `PolicyAttachment`, `ToolPolicy`). Nothing here talks to a proxy.
+ *
+ * ★ WHY ONE FILE AND NOT ONE COPY PER RESOURCE: every one of these answers the same three
+ *   questions about a `body: unknown` reply — "what is the payload", "is this list a set of rows",
+ *   "is this failure a missing row" — and they must answer them the same way, or two resources
+ *   disagree about what absence looks like.
+ * ⛔ NO MESSAGE OR STATUS SNIFFING (S21). `isNotFound` is a CLASS test against the SDK's own
+ *   `NotFound`, never a `.status` or message match. These routes do not DECLARE 404 (only the
+ *   `team_management` create/update/delete routes do, by distilled patch), but core's shared status
+ *   map still decodes a 404 to that class at run time, invisible to the type checker
+ *   (`mcp-server-operations.ts` says the same about its own by-id read). The typed fix is a distilled
+ *   patch for each tag, which belongs in the distilled clone — never a catch by text here.
+ * ⚠️ WHICH CLASS A 404 DECODES TO DEPENDS ON THE TAG. Where the SDK DECLARES the status (a distilled
+ *   patch: the `team_management` create, update and delete routes), the runtime error is that service
+ *   module's OWN `NotFound`, a different class from the core one exported by `Errors`, and only
+ *   `Effect.catchTag('NotFound')` sees it (`deleteTeam`). Where it is undeclared (`/team/info`,
+ *   toolset and tool reads) it is core's, and this `instanceof` sees it. A later patch that declares
+ *   404 for one of those tags would move it to the other class and fail the tests here, which run every
+ *   call through the real SDK decode, rather than silently reading "not found" as a failure.
+ */
+import { NotFound } from '@distilled.cloud/litellm/Errors';
+import * as Effect from 'effect/Effect';
+import { LitellmRegistryInvalidError } from './registry-errors.ts';
+
+/** Whether a failure is the SDK's `NotFound` class. A 401, a 500 or a dead network is never absence. */
+export const isNotFound = (error: unknown): boolean => error instanceof NotFound;
+
+/**
+ * ⚠️ The SDK types most of these answers `{ body: unknown }`, but hands a JSON array or object back as
+ *   it came (measured through the fakes, as for `/budget/list`). Accept both shapes.
+ */
+export const bodyOf = (response: unknown): unknown =>
+  typeof response === 'object' &&
+  response !== null &&
+  !Array.isArray(response) &&
+  'body' in response
+    ? (response as { readonly body: unknown }).body
+    : response;
+
+export type Row = Readonly<Record<string, unknown>>;
+
+/** The value as a plain object, else `undefined`. An array is not a row. */
+export const asRow = (value: unknown): Row | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Row) : undefined;
+
+/** The strings of a live list, in order. Anything else (`null`, a number) is skipped, never trusted. */
+export const stringsOf = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((each): each is string => typeof each === 'string') : [];
+
+/** `null` for anything that is not a string: a live column can hold `null`, and so can a proxy's JSON. */
+export const stringOrNull = (value: unknown): string | null =>
+  typeof value === 'string' ? value : null;
+
+/** `null` for anything that is not a finite number. Numeric strings (Prisma BigInt) are converted. */
+export const numberOrNull = (value: unknown): number | null => {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/** Sorted, de-duplicated. Every list a resource compares is a SET, so this is its canonical form. */
+export const canonical = (values: readonly string[]): readonly string[] =>
+  [...new Set(values)].sort();
+
+export const sameSet = (left: readonly string[], right: readonly string[]): boolean => {
+  const a = canonical(left);
+  const b = canonical(right);
+  return a.length === b.length && a.every((each, index) => each === b[index]);
+};
+
+/** Whether a value is not a string with something in it. Takes `unknown`: a declaration can say anything. */
+export const isBlank = (value: unknown): boolean =>
+  typeof value !== 'string' || value.trim() === '';
+
+/** The first blank or padded entry of a declared list, or `undefined`. Padding is refused too: it is a typo. */
+export const firstBadEntry = (values: readonly unknown[]): string | undefined => {
+  for (const each of values) {
+    if (isBlank(each) || (each as string) !== (each as string).trim()) return String(each);
+  }
+  return undefined;
+};
+
+/** A list that names one entry twice. Refused rather than silently collapsed: the twin is a typo. */
+export const firstDuplicate = (values: readonly string[]): string | undefined =>
+  values.find((each, index) => values.indexOf(each) !== index);
+
+/**
+ * A refusal as a TYPED FAILURE. Used in `diff` and `reconcile`, where a failure blocks that one
+ * resource with a message.
+ */
+export const failIfInvalid = (resource: string, name: string, problem: string | undefined) =>
+  problem === undefined
+    ? Effect.void
+    : Effect.fail(new LitellmRegistryInvalidError({ name, problem, resource }));
+
+/**
+ * The same refusal as a DEFECT, for `read` with no `output` — Alchemy's adoption probe and the ONLY
+ * plan-time hook a brand-new declaration gets (`mcp-server.ts` measured this on beta.79, `Plan.ts`
+ * lines 1303-1316). ★ A defect and not a typed failure because the same call shape is Alchemy's
+ * recovery read of an interrupted create with the STORED props, where only a defect is caught
+ * (`Effect.catchDefect`); a typed failure would wedge a stage on props a later, stricter release now
+ * refuses. The cold-start probe has no such catch, so there the defect fails the plan, as intended.
+ */
+export const dieIfInvalid = (resource: string, name: string, problem: string | undefined) =>
+  problem === undefined
+    ? Effect.void
+    : Effect.die(new LitellmRegistryInvalidError({ name, problem, resource }));

package/src/litellm/team-form.ts

@@ -0,0 +1,140 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.Team`, testable without a server. The object
+ * permission is team-permission.ts, the roster team-members.ts.
+ *
+ * ★ THE UPDATE IS A PARTIAL ONE (`/team/update` builds its write from `data.json(exclude_unset=True)`,
+ *   `team_endpoints.py` line 2418, 1.103.0), so it sends the team id and ONLY what differs. Nothing
+ *   here sends `metadata`, a budget, a limit or any Enterprise field.
+ * ★ THE READ IS `/team/info`, and it returns the team's OWN columns: access-group grants are resolved
+ *   into separate `access_group_*` fields (`_resolve_team_access_group_resources`), never merged into
+ *   `models` or `object_permission`, so a group cannot make a team look as if it declared a model.
+ */
+import type * as team from '@distilled.cloud/litellm/team_management';
+import {
+  asRow,
+  canonical,
+  firstBadEntry,
+  firstDuplicate,
+  isBlank,
+  sameSet,
+  stringsOf,
+} from './registry-support.ts';
+import { rosterPending, toMemberAttributes } from './team-members.ts';
+import {
+  permissionBody,
+  permissionDiffers,
+  permissionProblem,
+  toPermissionAttributes,
+} from './team-permission.ts';
+import type { TeamAttributes, TeamProps } from './team-types.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: TeamProps): string | undefined => {
+  if (isBlank(props.teamAlias) || props.teamAlias !== props.teamAlias.trim()) {
+    return '`teamAlias` must be a non-blank name with no leading or trailing space';
+  }
+  if (
+    props.teamId !== undefined &&
+    (isBlank(props.teamId) || props.teamId !== props.teamId.trim())
+  ) {
+    return '`teamId` must be a non-blank id with no leading or trailing space';
+  }
+  for (const [field, values] of [
+    ['models', props.models ?? []],
+    ['accessGroupIds', props.accessGroupIds ?? []],
+  ] as const) {
+    const bad = firstBadEntry(values);
+    if (bad !== undefined)
+      return `\`${field}\` has a blank or padded entry (${JSON.stringify(bad)})`;
+    const twice = firstDuplicate(values);
+    if (twice !== undefined) return `\`${field}\` lists ${JSON.stringify(twice)} twice`;
+  }
+  const ids = (props.members ?? []).map((member) => member.userId);
+  const badId = firstBadEntry(ids);
+  if (badId !== undefined)
+    return `\`members\` has a blank or padded userId (${JSON.stringify(badId)})`;
+  const twiceId = firstDuplicate(ids);
+  if (twiceId !== undefined) return `\`members\` lists ${JSON.stringify(twiceId)} twice`;
+  for (const member of props.members ?? []) {
+    if (member.role !== undefined && member.role !== 'user' && member.role !== 'admin') {
+      return `member ${member.userId} has a role other than user or admin`;
+    }
+  }
+  return permissionProblem(props.objectPermission);
+};
+
+/** One `team_info` row. `undefined` is "not a team": the caller refuses the whole answer. */
+export const toAttributes = (value: unknown): TeamAttributes | undefined => {
+  const row = asRow(asRow(value)?.['team_info']);
+  if (row === undefined) return undefined;
+  const teamId = row['team_id'];
+  if (typeof teamId !== 'string') return undefined;
+  return {
+    accessGroupIds: canonical(stringsOf(row['access_group_ids'])),
+    blocked: row['blocked'] === true,
+    members: toMemberAttributes(row['members_with_roles']),
+    models: canonical(stringsOf(row['models'])),
+    objectPermission: toPermissionAttributes(row['object_permission']),
+    teamAlias: typeof row['team_alias'] === 'string' ? row['team_alias'] : '',
+    teamId,
+  };
+};
+
+/** The team's own fields (never the roster) where live and declared disagree, by wire name. */
+export const teamFieldsDiffering = (live: TeamAttributes, props: TeamProps): readonly string[] => {
+  const fields: string[] = [];
+  if (live.teamAlias !== props.teamAlias) fields.push('team_alias');
+  if (props.models !== undefined && !sameSet(live.models, props.models)) fields.push('models');
+  if (props.blocked !== undefined && live.blocked !== props.blocked) fields.push('blocked');
+  if (props.accessGroupIds !== undefined && !sameSet(live.accessGroupIds, props.accessGroupIds)) {
+    fields.push('access_group_ids');
+  }
+  for (const wire of permissionDiffers(live.objectPermission, props.objectPermission)) {
+    fields.push(`object_permission.${wire}`);
+  }
+  return fields;
+};
+
+/** Everything that differs, the roster included. Empty means converged. */
+export const differing = (live: TeamAttributes, props: TeamProps): readonly string[] => [
+  ...teamFieldsDiffering(live, props),
+  ...(rosterPending(live.members, props.members) ? ['members'] : []),
+];
+
+/** Create body: every declared team field. The roster is added afterwards, through `member_add`. */
+export const createBody = (props: TeamProps, teamId: string): team.PostNewTeamTeamNewRequest => ({
+  team_alias: props.teamAlias,
+  team_id: teamId,
+  ...(props.models === undefined ? {} : { models: [...props.models] }),
+  ...(props.blocked === undefined ? {} : { blocked: props.blocked }),
+  ...(props.accessGroupIds === undefined ? {} : { access_group_ids: [...props.accessGroupIds] }),
+  ...(props.objectPermission === undefined
+    ? {}
+    : { object_permission: permissionBody(props.objectPermission) }),
+});
+
+/** Update body: the team id and only the fields that differ. `undefined` when nothing but the roster does. */
+export const updateBody = (
+  props: TeamProps,
+  live: TeamAttributes,
+): team.UpdateTeamTeamUpdatePostRequest | undefined => {
+  const changed = new Set(teamFieldsDiffering(live, props));
+  if (changed.size === 0) return undefined;
+  const permission = new Set(
+    [...changed]
+      .filter((field) => field.startsWith('object_permission.'))
+      .map((field) => field.slice(18)),
+  );
+  return {
+    team_id: live.teamId,
+    ...(changed.has('team_alias') ? { team_alias: props.teamAlias } : {}),
+    ...(changed.has('models') ? { models: [...(props.models ?? [])] } : {}),
+    ...(changed.has('blocked') ? { blocked: props.blocked ?? false } : {}),
+    ...(changed.has('access_group_ids')
+      ? { access_group_ids: [...(props.accessGroupIds ?? [])] }
+      : {}),
+    ...(props.objectPermission !== undefined && permission.size > 0
+      ? { object_permission: permissionBody(props.objectPermission, permission) }
+      : {}),
+  };
+};