@homeflare/alchemy 0.43.0 → 0.45.0

package/docs/litellm-mcp.md

@@ -0,0 +1,187 @@
+# LiteLLM — `LiteLLM.MCPServer`
+
+One row of LiteLLM's `LiteLLM_MCPServerTable` (`/v1/mcp/server`): an upstream MCP server that the
+proxy's gateway exposes to virtual keys and teams. Typed calls come from
+`@distilled.cloud/litellm/mcp_management`, generated from LiteLLM **v1.103.0**; credentials and the
+family's other refusals are in [litellm.md](./litellm.md).
+
+## The distilled operations it uses
+
+Nothing is hand-rolled: every call is one of these, through `mcp-server-operations.ts`.
+
+| step   | operation (`@distilled.cloud/litellm/mcp_management`) | route                               |
+| ------ | ----------------------------------------------------- | ----------------------------------- |
+| list   | `fetchAllMcpServersV1McpServerGet`                    | `GET /v1/mcp/server`                |
+| read   | `fetchMcpServerV1McpServerServerIdGet`                | `GET /v1/mcp/server/{server_id}`    |
+| create | `addMcpServerV1McpServerPost`                         | `POST /v1/mcp/server`               |
+| update | `editMcpServerV1McpServerPut`                         | `PUT /v1/mcp/server`                |
+| delete | `removeMcpServerV1McpServerServerIdDelete`            | `DELETE /v1/mcp/server/{server_id}` |
+
+Not used: the submission and approval flow, import, toolsets and the health check.
+
+⛔ **The list is not the table.** Measured on the live 1.103.0 container (2026-09-29, source only):
+`GET /v1/mcp/server` answers the proxy's **in-memory registry**. A reload fills it only from rows whose
+approval status is null, active or approved, skips a row whose build throws, and the caller's key can
+narrow it; `add_mcp_server` only logs a failed registry refresh after the row is committed. So a row
+absent from the list can be live. The by-id read asks the **table** first (a 404 only when the table,
+the registry and a lookup by name all miss), so it is what decides where the list cannot. It has side
+effects (it registers the row and health-checks the upstream), so it runs only when the list misses.
+
+## Example
+
+```ts
+import { LiteLLMMCPServer, litellmProviders } from '@homeflare/alchemy/litellm';
+
+// An existing row, adopted by its name (needs --adopt), closed to every key except one group.
+export class Docs extends LiteLLMMCPServer('Docs', {
+  serverName: 'example_docs',
+  url: 'https://mcp.example.com/mcp',
+  transport: 'http',
+  authType: 'none',
+  mcpAccessGroups: ['example-knowledge'],
+}) {}
+
+// A static credential is the NAME of an environment variable in the deploying process. The tool
+// whitelist is pinned by declaring `allowedTools`; leave it out to keep whatever the proxy holds.
+export class Keyed extends LiteLLMMCPServer('Keyed', {
+  serverName: 'example_keyed',
+  url: 'https://keyed.example.com/sse',
+  transport: 'sse',
+  authType: 'bearer_token',
+  authValue: { fromEnv: 'EXAMPLE_MCP_TOKEN' },
+  allowedTools: ['search', 'fetch'],
+}) {}
+```
+
+Then provide `litellmProviders()` alongside the stack's other providers.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                                                                                                |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | The live row whose `server_name` is `serverName`. `serverId` pins one row instead. Two rows with the same name are refused (`LitellmMcpServerAmbiguousNameError`).                                                                                                  |
+| Adopt       | A live row with no state is `Unowned`; it needs `--adopt`. Adopting a row that already matches writes nothing. The plan says `adopted` even when reconcile then writes. A row the list lacks is adopted only by declaring its `serverId`.                           |
+| Id          | A create asks for `serverId`, else a deterministic physical name. The id LiteLLM answers is the one recorded, so a proxy that issues its own id is still tracked.                                                                                                   |
+| Replace     | Only a changed declared `serverId`, create-first. A changed `serverName` is an update that re-sends the live alias, so the tool prefix stays. Declare `alias` to change the prefix.                                                                                 |
+| Removal     | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`. A replace under `retain` leaves the old row live.                                                                                                                                          |
+| Delete      | Always sends the DELETE (it acts on the table). If it fails, the failure is swallowed only when a by-id read of the table says the row is gone; a row still there, or a read that fails, re-raises the original error.                                              |
+| Read        | The list first, then the table by id when the list lacks the row (the id it would use: recorded, declared, or the deterministic one). Copies no credential, header or environment value; a URL is redacted on the way in.                                           |
+| Write check | Reconcile reads back (list, then table) and fails (`LitellmMcpServerNotConvergedError`) if a declared field did not land, or (`LitellmMcpServerAbsentAfterWriteError`) if the row is in neither. A created row the list does not show yet is recorded, not retried. |
+
+## Access grants
+
+`allowAllKeys` (default `false`) and `mcpAccessGroups` (default empty) are **always compared**, because
+they decide which keys can reach a server: a live row that has them wider than declared is corrected.
+Lists compare as sets.
+
+⛔ **`allowedTools` is compared and sent only when declared, like `alias` and `description`.** An empty
+list is the **open** state, not a closed one. Measured on the live 1.103.0 container (read-only, source
+only): `server_applies_tool_allowlist` (`mcp_server/utils.py`) is "the `mcp_info` enforce flag, or a
+non-empty `allowed_tools`", and `filter_tools_by_allowed_tools` (`server.py` lines 1692-1698) returns
+every tool when that is false. `mcp_info` is not modelled here, so:
+
+- Leave `allowedTools` out and the live whitelist is left exactly as it is: adopting a whitelisted row
+  never widens it.
+- Declare a list and it is authoritative: the live list becomes exactly that set.
+- Declare `[]` only to say "no restriction". It is sent as it is.
+
+⚠️ **The plan does not show an adopted row's write.** Alchemy's adoption branch plans `adopted` for a
+live row with no state, whether or not reconcile then writes (`mcp-server-tools.test.ts` pins this), so
+a corrected `allowAllKeys` or `mcpAccessGroups` on an adopted row appears in the plan only as `adopted`.
+Later deploys of a row this stack owns plan `update`. `alias` and `description` are compared **only when
+declared**, so adopting a row never clears text a person wrote.
+
+⛔ **An update never lets LiteLLM default the alias.** Measured on the live container by running its own
+`validate_and_normalize_mcp_server_payload` and `_prepare_mcp_server_data` on an edit body (no database):
+a body with a `server_name` and no `alias` comes out with `alias = server_name`, and the alias **is
+written**; a body with neither sends none. The alias is the tool prefix, so that would rename every tool
+of a row aliased `search` (`search-*` to `estate_web-*`) for every key and seat. So an update sends
+`server_name` only when it changes, and re-sends the live alias on a rename. A renamed row with no alias
+gets the new name as its alias, LiteLLM's own default.
+
+⚠️ **`description` cannot be written to a row whose `mcp_info` has a `description` key.** The list answers
+`mcp_info.description` when the key exists (even as null), else the column, and this resource writes only
+the column. Live, `linear` and `Memos_CF` have the key. A declared description that differs is refused
+before any write (`LitellmMcpServerDescriptionShadowedError`); the same text, or none declared, is fine.
+
+Team access is not here: the create and edit requests have no team field (`teams` exists only on the
+row a read returns). Grant a team access from the team side (its `object_permission`).
+
+## The credential: a name in, a seal out
+
+⛔ **`authValue` is `{ fromEnv: 'NAME' }`, not a `Redacted` value.** Alchemy persists props and
+attributes unencrypted, and `StateEncoding.ts` writes a `Redacted` value's inner string beside its tag
+(measured on `alchemy@2.0.0-beta.79`), so a `Redacted` prop would sit in the state store as plaintext.
+The variable is read from the deploying process at call time, held there as `Redacted` so a log line
+prints `<redacted>`, and unwrapped in one place: the wire body. See
+[provider-standard.md](./provider-standard.md) (S25) and `src/secrets/write-only.ts`.
+
+Static types (`api_key`, `bearer_token`, `basic`, `authorization`, `token`) require `authValue`;
+`none` and `oauth2` refuse it. LiteLLM is not assumed to return a credential, so a plan compares the
+variable's current value with a **seal** (a salted scrypt digest) kept in the attributes:
+
+| state     | when                                                      | plan                                       |
+| --------- | --------------------------------------------------------- | ------------------------------------------ |
+| `match`   | the variable is set and the seal was made from it         | no change                                  |
+| `stale`   | the variable is set and there is no seal, or it disagrees | update: the declared credential is written |
+| `unknown` | the variable is unset in this process                     | no change: a plan-only run is not drift    |
+| `none`    | no credential is declared                                 | no change                                  |
+
+A **create** needs the variable and fails naming it (`LitellmMcpServerCredentialEnvUnsetError`) if it
+is unset or empty, and so does **any write that changes `authType` to a static type** (from `none`,
+`oauth2` or another static type): before anything is sent. ⛔ Measured on the live 1.103.0 container
+(`mcp_server/db.py` lines 1013-1014): an edit whose auth class differs from the stored one and that
+sends no credential wipes the stored credential, and each static type is its own class. Sent without
+the value, the row would end with none while the seal still matched the old value, so a later deploy
+would be a no-op and the server would stay unauthenticated. Any other update sends the credential
+whenever the process has it. Moving a server off a static type sends `credentials: null` and forgets
+the seal. ⚠️ A seal of a guessable secret is still guessable: use a random token.
+
+## Refused before any request
+
+- A `serverName` or `alias` outside `^[A-Za-z0-9._]{1,128}$`. LiteLLM 1.103 runs the MCP SDK's
+  `validate_tool_name` on both, so a space, `/`, `:`, `@`, `-` or more than 128 characters is a 400
+  only at apply. A blank `alias` is the same refusal.
+- A blank `description` (`''` or whitespace). LiteLLM copies the column into `mcp_info` only when
+  the value is truthy, so a declared blank one is written and read back as absent and never converges.
+- A blank or padded `serverName`, `stdio` (it runs a command on the proxy host), and any auth type
+  outside `none`, `oauth2` and the five static ones (the rest need credential fields not modelled).
+- A URL with userinfo, a fragment, or a query parameter whose name looks like a credential (`token`,
+  `api_key`, `secret`, `auth`, …). The URL is a prop and lands in state; put the secret in `authValue`.
+- A blank entry in `allowedTools` or `mcpAccessGroups`.
+
+## Not modelled
+
+`stdio` and its `command`/`args`/`env`; `static_headers`, `extra_headers` and `env_vars` (a header or
+variable can carry a secret); OAuth client registration and endpoints; `mcp_info`, tool renames, BYOK;
+`timeout`, `max_concurrent_requests`, `available_on_public_internet`; `teams`. A row that uses them can
+be adopted, and what is not declared is not sent. The edit route is a partial update at 1.103.0
+(`mcp_server/db.py`, `exclude_unset=True`, read from the live container, not exercised), so an unsent
+field keeps its stored value; measure it once on a scratch proxy before the first live update of an
+adopted OAuth row (below).
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-mcp-litellm.ts`) is built from the generated schema and
+makes its own choices for each of these, except the clear-on-auth-change rule above, which it models
+from the source; every one is guarded by the read back, so a wrong guess fails loudly rather than
+reporting a converged row.
+
+- Whether an empty list, a `false` or a `null` lands on an edit. (That `PUT /v1/mcp/server` is a
+  partial update is read from the source, not called.)
+- Whether a create honours a supplied `server_id`, and what a duplicate id or name answers.
+- Whether the list redacts `credentials` (the resource copies none either way), whether it is paged or
+  filtered for the master key, and whether it includes config-file servers, which cannot be edited.
+- What a delete or an edit of a missing id answers on the wire. Read from the source: a delete of a
+  missing row and a by-id read that misses everywhere are 404. `mcp_management` declares only
+  `UnprocessableEntity`, and the distilled `patches/` that type 404 cover other tags, so the by-id read
+  tests the SDK's `NotFound` class (`instanceof`), never a message. A distilled patch for this tag would
+  type it; it belongs in the distilled clone.
+- Whether LiteLLM normalises a URL. If it does, declare the URL the way the row returns it, or the
+  read back names `url`.
+
+## Before the first live adoption
+
+Adopting a row that already matches is a no-op. Before an update reaches a live OAuth row, exercise the
+edit route once against a scratch LiteLLM (a row with `static_headers` and OAuth endpoints, then an edit
+of `allowAllKeys` alone) and record whether the other fields survive; the source says they do.

package/docs/litellm-model.md

@@ -0,0 +1,111 @@
+# LiteLLM — `LiteLLM.Model`
+
+One deployment row of LiteLLM's model registry (`/model/info`): an upstream model the proxy's
+router serves under a group name. A group name can carry several deployments — that is LiteLLM's
+load balancing — and this resource owns exactly one row of it. Typed calls come from
+`@distilled.cloud/litellm/model_management`, generated from LiteLLM **v1.103.0**; the family's
+credentials and other refusals in [litellm.md](./litellm.md).
+
+## distilled operations it uses
+
+Nothing hand-rolled: every call is one of these, through `model-operations.ts`.
+
+| step   | operation (`@distilled.cloud/litellm/model_management`) | route                      |
+| ------ | ------------------------------------------------------- | -------------------------- |
+| list   | `getModelInfoV1ModelInfo`                               | `GET /model/info`          |
+| read   | `getModelInfoV1ModelInfo` (`litellm_model_id` filter)   | `GET /model/info?id=…`     |
+| create | `addNewModelModelNewPost`                               | `POST /model/new`          |
+| update | `patchModelModelModelIdUpdatePatch`                     | `PATCH /model/{id}/update` |
+| delete | `deleteModelModelDeletePost`                            | `POST /model/delete`       |
+
+A missing id on the by-id read is HTTP 400 at v1.100.0 and v1.103.0 (`model_info_v1`), and the same
+400 is also "no rights". Absence is a re-list that lacks the id, never the error text.
+
+The list is the table and one GET answers a name, an id and absence. The by-id read is kept only
+for the read-back of a row the list may not show yet (a create commits before the list refreshes)
+— the same order `LiteLLM.MCPServer` keeps for its registry.
+
+## Example
+
+```ts
+import { LiteLLMModel, litellmProviders } from '@homeflare/alchemy/litellm';
+
+// An existing row, adopted by group name (needs --adopt). The id of the live row is adopted;
+// omitting accessGroups declares "no groups", which clears them on adoption.
+export class Grok extends LiteLLMModel('Grok', {
+  modelName: 'grok',
+  model: 'xai/grok-4.7',
+  accessGroups: ['ct100-agents'],
+}) {}
+
+// A credential is the NAME of the environment variable the PROXY resolves in its own
+// environment — never a value. A custom gateway goes through apiBase.
+export class Canary extends LiteLLMModel('Canary', {
+  modelName: 'canary',
+  model: 'cloudflare/@cf/meta/llama-3.1-8b-instruct',
+  apiBase: 'https://gateway.example.com/v1',
+  apiKey: { fromEnv: 'CANARY_UPSTREAM_KEY' },
+  mode: 'chat',
+  baseModel: 'meta/llama-3.1-8b-instruct',
+}) {}
+
+// A pinned id adopts that exact row even when the name is shared by several deployments.
+export class Pinned extends LiteLLMModel('Pinned', {
+  id: 'model-abc123',
+  modelName: 'grok',
+  model: 'xai/grok-4.7',
+}) {}
+```
+
+Then provide `litellmProviders()` alongside the stack's other providers.
+
+## Behaviour
+
+| Concern          | Rule                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| adopt            | By `modelName` (the live row whose group name matches), or by `id` to pin one. A name matching more than one listed row is refused, never guessed at. A live row with no state needs `--adopt` — a same-named foreign row is never taken over silently (`LitellmModelForeignRowError`), and a config-file row (`db_model: false`) is refused even with `--adopt`.                     |
+| default removal  | `retain` — removal takes the deployment out of its routing group for every key that reaches it; opt in with `.pipe(RemovalPolicy.destroy())`.                                                                                                                                                                                                                                         |
+| rename           | A changed `modelName` without a pinned `id` is a new group: the old row survives under `retain`, the new group gets a fresh id. With a pinned `id` the same row is renamed in place.                                                                                                                                                                                                  |
+| changed `id`     | The id is identity: a different declared id is a `replace`, create-first, old row retained.                                                                                                                                                                                                                                                                                           |
+| credential       | `apiKey: { fromEnv: 'NAME' }` only — sent as LiteLLM's own `os.environ/NAME` reference, so the proxy resolves it in its own environment. Never a value (a value would land in Alchemy's unencrypted state).                                                                                                                                                                           |
+| omitted `apiKey` | An adopted row is never blanked: omitting `apiKey` sends no `api_key`, and the live credential stays. Declaring one is what moves the row onto `os.environ/NAME`.                                                                                                                                                                                                                     |
+| encrypted params | The v1.103.0 read answers `litellm_params` DECRYPTED but STRIPS `api_key` (measured), so the comparison is the visible fields the read returns plus `paramsSeal`, a digest of the DECLARED values — never a digest of the live row.                                                                                                                                                   |
+| update scope     | Everything an existing row needs goes to ONE `PATCH /model/{id}/update` (`update_db_model` MERGES: sent keys land, the rest of the row survives). `POST /model/update` is never sent: v1.103.0 `update_model` REBUILDS `litellm_params` from the parsed request model and REPLACES the column, deleting a stored key the model does not declare (`extra_headers`, `weight`, `order`). |
+| read-back        | Every write is read back: a field the proxy did not apply fails the deploy (`LitellmModelNotConvergedError`) instead of claiming success. A row that cannot be found after a write fails it too.                                                                                                                                                                                      |
+| delete           | Idempotent by this resource, not by the vendor: a `BadRequest` re-lists, and only a genuinely-absent id counts as already deleted — a refused delete on a live row re-fails.                                                                                                                                                                                                          |
+| list             | Empty: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by.                                                                                                                                                                                                                                                                                            |
+
+A refused unpinned rename leaves a `replacing` row. Reverting the name finds this stack's own
+still-serving deployment and refuses with `LitellmModelPriorGenerationError`: drop the state row
+(`alchemy state rm`, which leaves the deployment) and deploy with `--adopt`. Do not delete the live
+row — under `destroy()`, garbage collection deletes the old generation by that same id. A declared-id
+replace whose read-back fails after `POST /model/new` resumes on the next deploy with `--adopt`.
+
+## Refusals
+
+A plan is refused, before any write, when the declaration:
+
+- names `modelName` blank or carrying leading/trailing whitespace;
+- declares `model` without a provider prefix (`xai/…`, `cloudflare/@cf/…`) — LiteLLM routes by it;
+- declares `model` with the `openai/` prefix on a group whose name starts with `grok` — Grok is
+  xAI's, declare `xai/…`;
+- declares `apiBase` carrying userinfo, a fragment or a secret-looking query parameter;
+- declares `apiKey` as anything but `{ fromEnv: 'NAME' }`, or names a blank variable.
+
+## Not measured at v1.103.0, guarded instead
+
+- Whether `/model/new` honours a supplied `model_info.id`: the answer is an untyped body, so the id
+  asked for is the one tracked, and a read-back that cannot find it fails the deploy
+  (`LitellmModelAbsentAfterWriteError`) rather than recording a row it cannot identify.
+- What the real proxy answers for a duplicate create and a delete of a missing id: the fake's 400s
+  there are its own choices. A PATCH of a missing id is HTTP 404 (`patch_model` at v1.103.0).
+- The rest of `litellm_params` (rpm/tpm, timeouts, fallbacks, wildcard routing, …), cost fields on
+  `model_info` beyond what the read returns, `teams`, and config-file rows (`db_model: false`) are
+  not modelled on purpose. v1.103.0 fills every unset `litellm_params` field with its pydantic
+  default before a params write (`updateLiteLLMParams`): a `None` default keeps the stored value,
+  a non-`None` default overwrites it — so the PATCH sends `null` for `use_in_pass_through`,
+  `use_litellm_proxy`, `use_xai_oauth`, `allow_client_keepalive_override` and
+  `merge_reasoning_content_in_choices`, the five whose default is `false`. A bare matching adopt
+  records `paramsSeal` locally and writes nothing; an adopt whose declaration also manages
+  `api_key` or `api_base` PATCHes once, because those params never appear on a read and only a
+  write can converge them.

package/docs/litellm-policy-attachment.md

@@ -0,0 +1,86 @@
+# LiteLLM — `LiteLLM.PolicyAttachment`
+
+One row of LiteLLM's policy attachment table (`LiteLLM_PolicyAttachmentTable`, `/policies/attachments`): **where**
+a [policy](./litellm-policy.md) applies, by team alias, key alias, model and tag. Typed calls come from
+`@distilled.cloud/litellm/policy_engine`, generated from LiteLLM **v1.103.0**; credentials and the family's
+other refusals are in [litellm.md](./litellm.md).
+
+Everything marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no request was
+sent to a proxy). The docs page is docs.litellm.ai/docs/proxy/guardrails/guardrail_policies.
+
+## The distilled operations it uses
+
+| step   | operation (`@distilled.cloud/litellm/policy_engine`)          | route                               |
+| ------ | ------------------------------------------------------------- | ----------------------------------- |
+| list   | `listPolicyAttachmentsPoliciesAttachmentsListGet`             | `GET /policies/attachments/list`    |
+| create | `createPolicyAttachmentPoliciesAttachmentsPost`               | `POST /policies/attachments`        |
+| delete | `deletePolicyAttachmentPoliciesAttachmentsAttachmentIdDelete` | `DELETE /policies/attachments/{id}` |
+
+There is **no update operation**, because the API has none (`policy_endpoints.py` has create, get, list and
+delete). The by-id `GET` is not used: the list carries every field and answers absence without a 404.
+
+## ⛔ An attachment with no selector is GLOBAL
+
+A request gets the policy when it matches **all** of the attachment's selectors (`PolicyMatcher.scope_matches`,
+`policy_matcher.py`). `PolicyScope.get_teams()`, `get_keys()` and `get_models()` each default to `["*"]` when
+empty, and empty `tags` are simply not checked (`policy_types.py`). So an attachment that names only a policy
+applies to **every request**, and `{ teams: ['x'] }` covers every key and every model of team x.
+
+An attachment with no `scope`, `teams`, `keys`, `models` or `tags` is therefore **refused** unless `scope: '*'`
+says a global attachment is meant.
+
+## Example
+
+```ts
+import { LiteLLMPolicyAttachment, litellmProviders } from '@homeflare/alchemy/litellm';
+
+export class CodeOnly extends LiteLLMPolicyAttachment('CodeOnly', {
+  policyName: baseline.policyName, // a LiteLLM.Policy: the dependency edge is the Output
+  teams: [estate.teamAlias], // team ALIASES, from a LiteLLM.Team: it must exist before the attachment
+  models: ['cf-*'],
+  priority: 10,
+}) {}
+```
+
+Teams, keys and models are matched by alias or model name with `*` wildcards (`prefix-*`). `tags` match
+key and team `metadata.tags`. A `teams` entry is `LiteLLM.Team`'s `teamAlias`, **not its id**, and an alias is
+not unique in LiteLLM, so two teams sharing one are both matched.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | **Content.** The id is the proxy's and there is no name, so two attachments are "the same" when the policy, scope, the four selector sets and the priority all are.                                  |
+| Adopt       | A live attachment that equals the declaration, with no state, is `Unowned` and needs `--adopt`. Two identical live rows are refused (`LitellmRegistryAmbiguousError`), never guessed at.             |
+| Change      | Always a **`replace`, create-first**: the new attachment is created, then the old one is deleted. For a moment both apply. Guardrails are additive, so that can only add enforcement, never drop it. |
+| Removal     | The **default** removal policy (`destroy`), deliberately not `retain`. Under `retain` a replace would leave the old attachment live beside the new one for good. An attachment holds no data.        |
+| Delete      | Idempotent by a real read: a failed DELETE (a missing id is a 404) is swallowed only when the list no longer has the id. A 403 re-raises the original error.                                         |
+| Config file | Attachments defined in config.yaml (`definition_location: "config"`, ids `config-<n>`) can never be deleted through the API, so they are never listed, adopted or removed here.                      |
+| Write check | Reconcile lists again and fails (`LitellmRegistryNotConvergedError` / `…AbsentAfterWriteError`) if the created attachment differs from the declaration or is not there.                              |
+
+## What the proxy refuses, and this resource does not repeat
+
+`create_policy_attachment` answers **404** for a policy with no production version, and **400** for a concrete
+team, key or model selector that resolves to nothing (`PolicyValidator.find_invalid_scope_entries`); wildcard
+patterns are let through and may match nothing today. Declaring `teams` from `team.teamAlias` gives the
+dependency edge that makes the team exist first. Most other failures are a plain **500** (the handlers wrap
+everything in `except Exception`), which the SDK retries with backoff.
+
+## Refused before any request
+
+A blank or padded `policyName`; a `scope` other than `'*'`; a blank, padded or repeated selector entry; no
+selector at all (above); a `priority` that is not a 32-bit integer.
+
+## Licence gating (measured)
+
+None in the routes: `policy_endpoints.py`, `attachment_registry.py`, `policy_matcher.py` and
+`policy_validator.py` have no `premium_user` reference (`grep -ci premium`: 0 in each). The docs page states
+that "team/key-based policy attachment requires a LiteLLM Enterprise license". Whether that describes these
+routes, or the gated `policies` metadata of a team or key, or request-time matching on a community proxy, is
+**UNVERIFIED**: nothing was run, and the source shows no gate in the attachment path.
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-policy-attachment-litellm.ts`) is built from the source; each
+choice is in its header. The typed fix for this tag's undeclared 400, 404 and 500 answers is a distilled patch,
+which belongs in the distilled clone and is not part of this change.

package/docs/litellm-policy.md

@@ -0,0 +1,103 @@
+# LiteLLM — `LiteLLM.Policy`
+
+The **production version** of one named policy in LiteLLM's policy engine (`LiteLLM_PolicyTable`,
+`/policies`): guardrails to add, guardrails to remove from an inherited parent, and an optional model
+condition. Where it applies is a [`LiteLLM.PolicyAttachment`](./litellm-policy-attachment.md). Typed calls
+come from `@distilled.cloud/litellm/policy_engine`, generated from LiteLLM **v1.103.0**; credentials and
+the family's other refusals are in [litellm.md](./litellm.md).
+
+Everything marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no request was
+sent to a proxy). The docs page is docs.litellm.ai/docs/proxy/guardrails/guardrail_policies.
+
+## ⛔ A policy is versioned; this resource manages the production version
+
+LiteLLM keeps every version (`draft` → `published` → `production`) and only **production** is enforced.
+`POST /policies` creates version 1 **as production**, and `PUT /policies/{id}` edits a **draft only** (400
+otherwise; `policy_endpoints.py`, `policy_registry.py`). So a change is four calls:
+
+1. `POST /policies/name/{name}/versions` — a new draft cloned from production;
+2. `PUT /policies/{draft}` — edit the fields that differ;
+3. `PUT /policies/{draft}/status` `published`;
+4. `PUT /policies/{draft}/status` `production` — which demotes the old production to `published`.
+
+The old version stays as history. `policyId` in the attributes is the **production** version's id and changes
+with every promotion. A run that stops midway leaves a draft or a published copy, both inert (drafts are not
+loaded into memory); the next run starts again from production and **never touches a version it did not
+make**, because promoting a person's draft would put their unmanaged fields into production.
+(The docs page describes no version lifecycle at all; the source is authoritative.)
+
+## The distilled operations it uses
+
+| step     | operation (`@distilled.cloud/litellm/policy_engine`)             | route                                          |
+| -------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| versions | `listPolicyVersionsPoliciesNamePolicyNameVersionsGet`            | `GET /policies/name/{name}/versions`           |
+| config   | `listPoliciesPoliciesListGet`                                    | `GET /policies/list?version_status=production` |
+| create   | `createPolicyPoliciesPost`                                       | `POST /policies`                               |
+| draft    | `createPolicyVersionPoliciesNamePolicyNameVersionsPost`          | `POST /policies/name/{name}/versions`          |
+| edit     | `updatePolicyPoliciesPolicyIdPut`                                | `PUT /policies/{id}`                           |
+| status   | `updatePolicyVersionStatusPoliciesPolicyIdStatusPut`             | `PUT /policies/{id}/status`                    |
+| delete   | `deleteAllPolicyVersionsPoliciesNamePolicyNameAllVersionsDelete` | `DELETE /policies/name/{name}/all-versions`    |
+
+## Example
+
+```ts
+import { LiteLLMPolicy, litellmProviders } from '@homeflare/alchemy/litellm';
+
+export class Baseline extends LiteLLMPolicy('Baseline', {
+  policyName: 'estate-baseline',
+  description: 'Guardrails every estate request gets',
+  guardrailsAdd: ['pii-mask', 'prompt-injection'],
+  conditionModel: 'cf-*',
+}) {}
+```
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `policyName`. A different name is a different policy: a `replace`, create-first, the old one retained.                                                                          |
+| Adopt       | A live **production** version with no state is `Unowned` and needs `--adopt`; found by name. A matching one writes nothing.                                                     |
+| Guardrails  | `guardrailsAdd` and `guardrailsRemove` are always compared, as sets (default `[]`).                                                                                             |
+| Other       | `description`, `inherit` and `conditionModel` are compared **only when declared**.                                                                                              |
+| Removal     | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`. `delete` removes **every version** (`delete_many` by name) and answers 200 whether or not any existed. |
+| Write check | Reconcile lists the versions again and fails (`LitellmRegistryNotConvergedError` / `…AbsentAfterWriteError`) if production does not match.                                      |
+
+⚠️ **A field cannot be cleared through the API.** `update_policy_in_db` writes only fields that are not `None`,
+so removing `description`, `inherit` or `conditionModel` from the declaration leaves the live value (they are
+"compared only when declared" for that reason). The two guardrail lists can be written as `[]`.
+
+## Two guards on a create
+
+- **A config.yaml policy is never shadowed by accident.** `/policies/list` merges DB rows with config policies
+  (`definition_location: "config"`), and a production DB policy of the same name **overrides** the config one at
+  runtime. A create for a name that belongs to a config policy is refused.
+- **No production version is never guessed at.** A name whose versions are all `draft` or `published` (someone
+  demoted it, so it is inactive) is refused with the count, not promoted.
+
+## Refused before any request
+
+A blank or padded `policyName`; a blank `description`, `inherit` or `conditionModel`; `inherit` naming the policy
+itself; a blank, padded or repeated guardrail; a guardrail both added and removed.
+
+## Licence gating (measured)
+
+None in the policy routes: `policy_endpoints.py`, `policy_registry.py`, `attachment_registry.py`,
+`policy_matcher.py` and `policy_validator.py` have no `premium_user` reference (`grep -ci premium`: 0 in each).
+The docs page says team/key-based policy attachment needs Enterprise; whether a community proxy enforces a
+team-scoped attachment is **UNVERIFIED**. The `policies` and `guardrails` **metadata of a team or key IS
+gated** (`_premium_user_check`, `litellm_pre_call_utils.py` lines 2949-3023 and `common_utils.py` line 464),
+which is why `LiteLLM.Team` never sends them.
+
+## Not modelled
+
+`pipeline` (an ordered guardrail pipeline): a new version is cloned from production, so an adopted policy's
+pipeline survives every update, and none is ever sent. Whether the named guardrails exist is not checked
+(LiteLLM does not check it on write).
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-policy-litellm.ts`) is built from the source; each choice is in its
+header. Most failures of these routes are a plain **500** (the handlers wrap everything in `except Exception`),
+and the SDK retries 5xx with backoff, so a genuine failure is slow to surface; nothing here reads the text of
+one. The typed fix for this tag's undeclared 400 and 404 is a distilled patch, which belongs in the distilled
+clone and is not part of this change.

package/docs/litellm-team.md

@@ -0,0 +1,117 @@
+# LiteLLM — `LiteLLM.Team`
+
+One row of LiteLLM's team table (`LiteLLM_TeamTable`, `/team/*`): the **models, MCP grants and member roster**
+that bound every key of a team. Typed calls come from `@distilled.cloud/litellm/team_management`, generated
+from LiteLLM **v1.103.0**; credentials and the family's other refusals are in [litellm.md](./litellm.md).
+
+Everything marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no request was
+sent to a proxy). Docs: docs.litellm.ai/docs/mcp_grant_access, /docs/proxy/users.
+
+## The distilled operations it uses
+
+Nothing is hand-rolled: every call is one of these, through `team-operations.ts`.
+
+| step   | operation (`@distilled.cloud/litellm/team_management`) | route                                       |
+| ------ | ------------------------------------------------------ | ------------------------------------------- |
+| read   | `getTeamInfoTeamInfo`                                  | `GET /team/info?team_id=`                   |
+| create | `postNewTeamTeamNew`                                   | `POST /team/new`                            |
+| update | `updateTeamTeamUpdatePost`                             | `POST /team/update`                         |
+| add    | `teamMemberAddTeamMemberAddPost`                       | `POST /team/member_add`                     |
+| role   | `teamMemberUpdateTeamMemberUpdatePost`                 | `POST /team/member_update`                  |
+| delete | `deleteTeamTeamDeletePost`                             | `POST /team/delete`                         |
+| list   | `listTeamTeamListGet`                                  | `GET /team/list` (only to confirm a delete) |
+
+## Example
+
+```ts
+import { LiteLLMTeam, litellmProviders } from '@homeflare/alchemy/litellm';
+
+export class Estate extends LiteLLMTeam('Estate', {
+  teamId: 'example-estate', // adopts the live team (needs --adopt)
+  teamAlias: 'example-estate',
+  models: ['cf-code', 'cf-flash'],
+  accessGroupIds: [group.accessGroupId],
+  objectPermission: {
+    mcpServers: [], // ⛔ see "the MCP ceiling": leave the team list empty
+    mcpToolsets: [web.toolsetId], // toolset IDS
+    blockedTools: ['estate_shell-run'],
+  },
+  members: [{ userId: 'tim' }],
+}) {}
+```
+
+## ⛔ The team's `mcpServers` is a ceiling that intersects every key's grants
+
+Where both a team and a key list servers, **the key reaches only the intersection** (`user_api_key_auth_mcp.py`
+lines 1482-1503; docs.litellm.ai/docs/mcp_grant_access). "An empty set means this level does not restrict."
+A NON-EMPTY team `mcpServers` therefore silently removes access from any key granted a server the team does
+not list. The fix for a team that carries one is to declare `mcpServers: []` and grant servers on keys, on
+toolsets (`mcpToolsets`) or through unified access groups. This resource does not decide that: it makes it a
+reviewed line of source. `mcpToolPermissions`, `mcpToolsets` and `mcpAccessGroups` are separate fields with
+their own rules (`mcp_grant_access`), and a toolset grant restricts even when it resolves to no servers.
+
+## Behaviour
+
+| Concern           | Rule                                                                                                                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity          | `teamId` (else a deterministic physical name for a create). `team_alias` is **not unique**, so it cannot find a team. A different declared id is a `replace`, create-first, the old team retained. |
+| Adopt             | A live team with that id and no state is `Unowned` and needs `--adopt`. A matching one writes nothing.                                                                                             |
+| Declared = truth  | `models`, `blocked`, `accessGroupIds`, each object-permission field and the roster are compared and sent **only when declared**. `teamAlias` is always compared.                                   |
+| Update            | Partial (`data.json(exclude_unset=True)`, `team_endpoints.py` line 2418): only the team id and what differs. Nothing else about the team is sent.                                                  |
+| Object permission | A **merge by top-level field** (`object_permission_utils.py` lines 114-118): a field left out keeps its value, `[]` replaces it. So five fields are managed and the other seven are left alone.    |
+| Removal           | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`, which **deletes every key of the team** (below).                                                                          |
+| Write check       | Reconcile reads back and fails (`LitellmRegistryNotConvergedError` / `…AbsentAfterWriteError`) if a declared field did not land or the team is not there.                                          |
+
+## The roster is additive only
+
+⛔ `/team/member_delete` does not only take a user off the roster: it **deletes every virtual key that user
+created for the team** (`team_endpoints.py` lines 3701-3748). A seat's key would vanish with a roster edit. So a
+live member the declaration does not list is **never removed and never an error**, and a declared member with
+another role is updated through `member_update`.
+
+- Members are added by `userId` only, in **one** `member_add` call. Adding an id that has no user yet creates its
+  user row (`add_new_member`), and only PROXY_ADMIN may do that (`_validate_member_user_id_provisioning`).
+- ⚠️ `/team/new` adds **the caller as an `admin` member** unless the proxy sets
+  `disable_auto_add_proxy_admin_to_teams` (`_should_auto_add_team_creator`, line 1352). That extra member is not
+  drift: undeclared members are ignored.
+- `role: 'admin'` is **Enterprise** on both routes (`team_endpoints.py` lines 2713-2723 and 3806-3810): a proxy
+  without a licence answers 400, the deploy fails with it, and the roster stays as it was.
+
+## Delete deletes the keys
+
+⛔ `/team/delete` is "delete team and associated team keys" (`team_endpoints.py` line 4258, and
+`delete_data(team_id_list=…, table_name="key")` at line 4374). It is the most destructive call in this family,
+and the reason for `retain`. It is idempotent only after a read that cannot lie: the route's own 404 also covers a
+database error (its lookup sits in `except Exception: raise HTTPException(404)`), so success is reported only
+when `GET /team/list` no longer has the id. A team still listed re-raises the **original** error.
+
+## Refused before any request
+
+A blank or padded `teamAlias` or `teamId`; a blank, padded or repeated entry in `models`, `accessGroupIds` or any
+object-permission list; the sentinel `all-proxy-mcpservers` in `mcpServers` (it grants **every** MCP server, and
+only a proxy admin may, `object_permission_utils.py` line 480); a blank tool-permission key; a repeated or blank
+`userId`; a role other than `user` or `admin`.
+
+## Licence gating (measured)
+
+`team_endpoints.py` has 19 `premium` references (`grep -ci premium`). The fields this resource **manages** are not
+gated except `members[].role: 'admin'`. The gated ones are never sent: the premium metadata fields
+(`disable_global_guardrails`, `guardrails`, `policies`, `tags`, `team_member_key_duration`, `prompts`, `logging`,
+`secret_manager_settings`, `allowed_passthrough_routes`: a 403 when truthy, `_types.py` lines 4843-4853 and
+`common_utils.py` lines 443-468) and `model_max_budget` (a 403, `common_utils.py` lines 73-86).
+
+## Not modelled
+
+Budgets and rate limits (a team's `max_budget` is a HARD cap that 429s every key: the 2026-09-28 incident, see
+[litellm-budget.md](./litellm-budget.md)); `metadata`; `router_settings`; `model_aliases`; the organisation; the
+Enterprise fields above; and the other `object_permission` fields (vector stores, agents, agent access groups,
+`models`, search tools, `mcp_tool_search_enabled`, skills). None is ever sent, so an adopted team keeps them.
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-team-litellm.ts`) is built from the source; each choice is in its
+header. Not exercised: what `/team/info` returns for a team whose `object_permission_id` points at a missing row,
+and how the SDK's `{ body: unknown }` typing meets the real answer (the tests pass through the real SDK decode).
+`/team/info` declares no 404 in the SDK (create, update and delete do, by distilled patch), so its 404 is read by
+class (`registry-support.ts`); the typed fix is a distilled patch, which belongs in the distilled clone and is not
+part of this change.