@homeflare/alchemy 0.43.0 → 0.45.0

package/dist/valkey/transport.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The RESP wire the `Valkey` family speaks, hand-rolled the same way `postgres/database-sql.ts`
+ * hand-rolls its four statements: there is no `@distilled.cloud/valkey` SDK (registry 404, checked
+ * 2026-09-29), and `effect@4.0.0-rc.115` ships no Valkey/Redis client, so the family declares a
+ * `ValkeyExecutor` seam — the real socket client below, or `fake-valkey.ts` in tests — and every
+ * lifecycle function depends only on that small interface, never on `node:net`.
+ * ★ Alchemy beta.79 DOES ship Redis.connect. Its internal parser/queue cannot enforce our
+ *   reply caps before allocating, and it exposes no deadline settings. The audited exception
+ *   and executable measurements are in `docs/valkey-transport.md`.
+ *
+ * ⛔ RESP, NOT A TAG TO VALKEY'S C VERSION. The protocol is line-and-prefix oriented and stable
+ *   across Valkey's releases; the commands this family issues (`INFO`, `CONFIG GET`, `ACL LIST`,
+ *   `ACL SETUSER`, `PING`) are all long-settled. Nothing here parses a version-specific field.
+ * ★ RUNTIME-NEUTRAL. The executor is a function of `node:net` sockets, no Bun API; a Bun-only
+ *   consumer would be a regression the postgres family's own `PgClient` avoided.
+ * ⛔ AN `error` EVENT WITH NO LISTENER EXITS THE PROCESS. `openSocket` listens only until
+ *   `connect`. This executor installs the listener that stays for the life of the socket, and
+ *   fails the in-flight read with `ValkeySocketError` (measured 2026-09-30: a peer RST after
+ *   the connect listener was dropped was `uncaughtException` `read ECONNRESET`, exit 1).
+ */
+import * as Effect from 'effect/Effect';
+import type { Socket } from 'node:net';
+import { type ValkeyReply, type ValkeyTransportError } from './transport-error.ts';
+export type { ValkeyReply, ValkeyTransportError } from './transport-error.ts';
+export { ValkeyServerError, ValkeySocketError } from './transport-error.ts';
+/** One command with its arguments, as the byte strings that go on the wire. */
+export interface ValkeyCommand {
+    readonly args: ReadonlyArray<string>;
+}
+/** The smallest thing a lifecycle function needs from a client: send one command, read the reply
+ * as one of the three RESP top-level shapes the family interprets — a bulk string, a flat array of
+ * bulk strings, or an error. `null` is the RESP "nil" reply (a missing key). Failures are the two
+ * transport tags: a server error reply, or a socket failure. */
+export interface ValkeyExecutor {
+    readonly send: (args: ReadonlyArray<string>) => Effect.Effect<ValkeyReply, ValkeyTransportError>;
+}
+/** The per-read abort, and the idle/`connect` deadline `withValkey` sets on the socket. */
+export declare const DEFAULT_SOCKET_TIMEOUT_MS = 10000;
+/**
+ * The real executor over a `node:net` socket. `socket` is supplied by the caller (which owns
+ * connect/close), so `withValkey` can open one socket per operation and close it after.
+ * `timeoutMs` bounds each read; the default matches the socket deadline in `connection.ts`.
+ */
+export declare const makeSocketExecutor: (socket: Socket, timeoutMs?: number) => ValkeyExecutor;
+/**
+ * Decode a flat array reply into `Map<string, string | null>` for the `key value key value`
+ * shape `CONFIG GET` answers. Null values are preserved; a missing key is `null`, never `''`.
+ */
+export declare const arrayPairs: (values: ReadonlyArray<string | null>) => ReadonlyMap<string, string | null>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/valkey/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/valkey/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE5E,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACtC;AAED;;;gEAGgE;AAChE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;CAClG;AAED,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WACrB,MAAM,cACH,MAAM,KAChB,cAiCF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,WACb,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,KACnC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAMnC,CAAC"}

package/docs/litellm-access-group.md

@@ -0,0 +1,105 @@
+# LiteLLM — `LiteLLM.AccessGroup`
+
+One row of LiteLLM's **unified access group** table (`LiteLLM_AccessGroupTable`,
+`/v1/unified_access_group`): a named bundle of models and MCP servers that teams and keys are attached to.
+Typed calls come from `@distilled.cloud/litellm/access_groups`, generated from LiteLLM **v1.103.0**;
+credentials and the family's other refusals are in [litellm.md](./litellm.md).
+
+Everything below marked "read" was read from the **live 1.103.0 container's source** on 2026-09-30 (no
+request was sent to a proxy). What the docs page says is cited by URL.
+
+## Which "access group" this is
+
+LiteLLM uses the words for three different things. This resource is the first.
+
+| Thing                    | Where it lives                                         | Holds                       |
+| ------------------------ | ------------------------------------------------------ | --------------------------- |
+| **Unified access group** | `LiteLLM_AccessGroupTable`, `/v1/unified_access_group` | models, MCP servers, agents |
+| Model access group       | `access_groups` in a model's `model_info`              | models only                 |
+| MCP access group         | a bare name on an MCP server row (`mcp_access_groups`) | MCP servers by name         |
+
+⚠️ **Toolsets are not in a unified group.** `AccessGroupCreateRequest` (`litellm/types/access_group.py`)
+has `access_model_names`, `access_mcp_server_ids`, `access_agent_ids`, `assigned_team_ids` and
+`assigned_key_ids`, and nothing else. A toolset is granted through `object_permission.mcp_toolsets` on a
+team or key ([litellm-team.md](./litellm-team.md)).
+The docs agree: docs.litellm.ai/docs/proxy/access_groups lists models, MCP servers and agents.
+
+## The distilled operations it uses
+
+Nothing is hand-rolled: every call is one of these, through `access-group-operations.ts`.
+
+| step   | operation (`@distilled.cloud/litellm/access_groups`)       | route                                 |
+| ------ | ---------------------------------------------------------- | ------------------------------------- |
+| list   | `listAccessGroupsV1UnifiedAccessGroupGet`                  | `GET /v1/unified_access_group`        |
+| create | `createAccessGroupV1UnifiedAccessGroupPost`                | `POST /v1/unified_access_group` (201) |
+| update | `updateAccessGroupV1UnifiedAccessGroupAccessGroupIdPut`    | `PUT /v1/unified_access_group/{id}`   |
+| delete | `deleteAccessGroupV1UnifiedAccessGroupAccessGroupIdDelete` | `DELETE …/{id}` (204, no body)        |
+
+Not used: the by-id `GET` (a missing id is a 404 this tag does not declare; the list decides absence
+without it), and the `/v1/access_group` routes (registered as aliases of these on the same handlers,
+`access_group_endpoints.py`, "Alias routes").
+
+## Example
+
+```ts
+import { LiteLLMAccessGroup, litellmProviders } from '@homeflare/alchemy/litellm';
+
+// An existing group, adopted by its name (needs --adopt), made to grant exactly this.
+export class Estate extends LiteLLMAccessGroup('Estate', {
+  accessGroupName: 'estate',
+  description: 'Models and tools every estate seat may use',
+  modelNames: ['cf-code', 'cf-flash'],
+  mcpServerIds: [docs.serverId], // a LiteLLM.MCPServer: the dependency edge is the Output
+}) {}
+```
+
+Then provide `litellmProviders()` alongside the stack's other providers.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                        |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `access_group_name` is **unique** (`find_unique`, a duplicate is a 409), so the name finds the one row. The id is the proxy's (a uuid) and is what state remembers.         |
+| Adopt       | A live row with no state is `Unowned`; it needs `--adopt`. A matching row writes nothing.                                                                                   |
+| Rename      | An update of the same row (the id does not change), never a replace.                                                                                                        |
+| Grants      | `modelNames` and `mcpServerIds` are **always compared**, as sets; an undeclared list means "grants nothing". An adopted group that grants more than declared is corrected.  |
+| Description | Compared only when declared: adopting never clears text a person wrote. Blank is refused.                                                                                   |
+| Update      | Partial (`exclude_unset`, a `null` list becomes `[]`), so only the fields that differ are sent. Team and key edges, agents and `access_agent_ids` are never in the body.    |
+| Removal     | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`. Deleting a group **detaches it from every team and key** that holds it (`delete_access_group`).    |
+| Delete      | Idempotent by a real read: a failed DELETE is swallowed only when the list no longer has the id. A 403 (PROXY_ADMIN only) re-raises the original error.                     |
+| Write check | Reconcile lists again and fails (`LitellmRegistryNotConvergedError`) if a declared field did not land, or (`LitellmRegistryAbsentAfterWriteError`) if the row is not there. |
+
+## Team and key membership is declared on the other side
+
+`assigned_team_ids` and `assigned_key_ids` are **not modelled**. A team's group membership is
+`LiteLLM.Team`'s `accessGroupIds`, and LiteLLM mirrors it into the group's `assigned_team_ids` in the same
+transaction (`_sync_add_access_group_to_teams`). Two resources writing one edge would fight, so the group
+never sends either field, and an adopted group keeps whatever it has there.
+
+⚠️ **LiteLLM edits `access_model_names` itself.** Unified groups store model **names**, and
+`management_helpers/access_group_model_sync.py` removes a name from every group when its last deployment is
+deleted (and renames it when a deployment is renamed). A model removed elsewhere therefore shows up as a
+plan difference on the next change. Alchemy plans from state and reads live rows only to adopt (beta.79), so
+the correction lands on the next deploy that changes the group at all, not on its own.
+
+## Refused before any request
+
+A blank or padded `accessGroupName`; a blank `description`; a blank, padded or repeated entry in
+`modelNames` or `mcpServerIds`.
+
+## Licence gating (measured)
+
+None. `access_group_endpoints.py` has no `premium_user` check (`grep -ci premium`: 0), and the docs page makes
+no Enterprise statement. Writes need PROXY_ADMIN (`_require_proxy_admin`, 403), reads admin or admin-view.
+
+## Not modelled
+
+`assigned_team_ids`, `assigned_key_ids`, `access_agent_ids`; nothing validates that a model name or a server
+id exists (LiteLLM stores them raw), so a dangling id is accepted and silently grants nothing.
+
+## Unmeasured at 1.103.0
+
+No live proxy was contacted. The fake (`fake-access-group-litellm.ts`) is built from the source and the
+generated schema; each choice it makes is in its header. Whether the list is paged, and what the by-id
+`GET` answers for a missing id, were not exercised. The typed fix for the undeclared 404 and 409 of this tag
+is a distilled patch, which belongs in the distilled clone and is not part of this change.

package/docs/litellm-credential.md

@@ -0,0 +1,60 @@
+# LiteLLM — `LiteLLM.Credential`
+
+One row of LiteLLM's reusable credential table (`/credentials/*`): a named bag of values the
+proxy stores **encrypted** and can bind to a deployment by `model_id`. Typed calls come from
+`@distilled.cloud/litellm/credential_management` (generated from v1.103.0, the same schema this
+resource's rules were read from); credentials and refusals are the family's, see
+[litellm.md](./litellm.md).
+
+## The values never live in a declaration
+
+`credentialValues` is `Record<string, { fromEnv: 'NAME' }>`. Alchemy's state is unencrypted and
+LiteLLM stores these literals encrypted in its own database (`credential_endpoints/endpoints.py`,
+read from a 1.103.0 container), so the declaration holds only the variable's NAME; the
+deploying process resolves the value at call time and the wire body carries the literal once.
+A literal value in the props is refused at plan time, and so is a sensitive-keyed
+`credentialInfo` entry — `credential_info` is stored and returned in the clear.
+
+The reads hand the values back masked (`litellm_logging.py::_get_masked_values`: a
+sensitive-keyed string answers `v[:2] + "****" + v[-2:]`, `*****` for a short one), so no value
+is ever compared against or copied from the masked row (only value key names are retained): what was last written is remembered as
+a salted scrypt seal (`valuesSeal`), and a rotated value is noticed by re-resolving and
+re-sealing. A variable that is unset makes the state "cannot tell" — it never drifts a
+plan-only environment. An info-only PATCH needs no value; a create, values PATCH or rewrite
+demands every declared variable. A required rewrite refuses before DELETE if any is missing.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `credentialName` (the table's unique column). A different declared name is a `replace`, `deleteFirst: false` — the old row survives.                                                                                                              |
+| Adopt       | A live row with the name and no state is `Unowned`; needs `--adopt`. The full intended info and value-key maps are authoritative, including undeclared live keys. Resolvable values are stamped and sealed; removal requires all declared values. |
+| Removal     | `defaultRemovalPolicy: 'retain'` — a deployment's `model_id` may reference the row. Opt in with `RemovalPolicy.destroy()`. Delete is idempotent (`NotFound` is already-absent).                                                                   |
+| Read        | `GET /credentials/by_name/{name}` — the proxy's in-memory list, not the table. A row committed to the database but not loaded in memory reads as absent; a create for it answers `409`, which fails the deploy loudly.                            |
+| Update      | PATCH changes values/info; DELETE + POST removes value or info keys. The regenerated SDK sends the required `credential_name` in both path and body.                                                                                              |
+| Write check | Reconcile reads back; unapplied info or remaining removed key names fail with `LitellmCredentialNotConvergedError`. Values and masked fragments never enter state.                                                                                |
+
+## PATCH and removal
+
+Measured in LiteLLM 1.103.0 `proxy/credential_endpoints/endpoints.py:312,384`: PATCH merges
+`credential_values` by key in both database and memory. It cannot remove a value key. The
+by-name read exposes key names even when values are masked, so removed names trigger a rewrite.
+
+`credential_info` differs: nonempty PATCH info normally **replaces** the database map
+(`:314–319`, except when the old map contains a literal `credential_info` key); empty info
+leaves it unchanged. In-memory info only merges (`:385–387`), retaining old keys until restart.
+Every PATCH sends the full intended info map. **The declaration owns the complete map**, with
+omission meaning `{}`: undeclared live info keys, including on adoption, are removed by rewrite
+so both stores agree. Sensitive info values are withheld; only their names are retained.
+
+Reconcile refuses invalid declarations and `DISTILLED_DEBUG_HTTP` at entry, rechecks ownership,
+and demands all values needed for a write before any DELETE. Debug logging could print request
+or response values; plan-time reads refuse debug logging too. Transport failures from value-bearing POST/PATCH become a typed
+`LitellmCredentialTransportError` containing the name and reason tag, no request or cause.
+A failed PATCH leaves the row in place. A rewrite is still non-atomic: a failed POST after a
+successful DELETE can leave no row. No live proxy was contacted for these regression tests.
+
+## Not modelled
+
+`model_id` (copying a deployment's values into a credential) — nothing in the estate declares
+one yet; add it with a measured read of the copy semantics.

package/docs/litellm-key-metadata.md

@@ -0,0 +1,56 @@
+# LiteLLM — `LiteLLM.Key` metadata
+
+How [`LiteLLM.Key`](./litellm-key.md) compares and writes a key's `metadata`, and what it never holds.
+Read 2026-09-29 in the LiteLLM **1.103.0** PyPI wheel's source (`litellm/proxy/…`), not against a live
+proxy. The code is `src/litellm/key-metadata.ts`; its header carries the same reasoning.
+
+## Why `metadata` is not the declarer's alone
+
+LiteLLM stores many per-key settings **inside** the `metadata` JSON column:
+
+- `LiteLLM_ManagementEndpoint_MetadataFields` and `..._Premium` (`_types.py:4821-4853`): `model_rpm_limit`,
+  `model_tpm_limit`, `enforced_params`, `end_user_budget_id`, `guardrails`, `policies`, `tags`, `prompts`,
+  `logging`, `secret_manager_settings`, `allowed_passthrough_routes`, and others.
+- `/key/generate` folds them in through `metadata_json_with_limits` (`key_management_endpoints.py:4429-4457`).
+- `/key/update` **replaces** the column with the `metadata` it is sent (`prepare_metadata_fields`, :2312-2359).
+  When `metadata` is not sent it keeps the existing one (:2318-2319). Only `service_account_id` is
+  preserved across a replacement (`LiteLLM_Reserved_Metadata_Fields`, `_types.py:4857`; :2323-2336).
+
+A body that carried only the declared keys therefore strips the key's guardrails, per-model caps and
+passthrough allowlist, and the deploy reports success. Measured over the test fake, which replaces the
+column the same way: an adopted key with `{ seat: 'a', guardrails: [...], model_rpm_limit: {...} }` and a
+declaration of `metadata: { seat: 'b' }` lost both before this merge (`key-metadata.test.ts`).
+
+## The merge
+
+| Declaration                | Compared                                        | Sent (only when a declared key differs)        |
+| -------------------------- | ----------------------------------------------- | ---------------------------------------------- |
+| `metadata` omitted         | nothing                                         | nothing                                        |
+| `metadata: { seat: 'a' }`  | the live `seat` against `'a'`                   | every live key, with `seat` set as declared    |
+| `metadata: { seat: null }` | the live `seat` against `null` (absent differs) | every live key, with `seat: null`; quiet after |
+
+A key you stop declaring is **carried, never removed**: leaving it out does not clear it, declare it
+`null`. The alternative, a list of the keys LiteLLM owns to carry while clearing the rest, was not
+taken: the list is per-version, a key LiteLLM adds next release would be stripped until it is updated,
+and this way fails safe on a live credential. The scope is top-level keys, as LiteLLM reads them.
+
+## Callback credentials are never held
+
+`logging`, `callback_settings` and `secret_manager_settings` (`common_utils/callback_utils.py:51`,
+`_CALLBACK_CONFIG_SLOTS`) carry `callback_vars`: an observability platform's secret keys. LiteLLM
+encrypts them at rest (`encrypt_callback_vars`, :716), but a legacy row's are plaintext ("Legacy
+plaintext rows pass through unchanged", `decrypt_callback_vars`, :725-731), and Alchemy persists
+attributes unencrypted. So:
+
+| What                                        | What this resource does                                                                                                                                                  |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A row with one of the slots (read, adopt)   | Drops the slot from `attributes.metadata`; keeps only its **name** in `attributes.withheld`.                                                                             |
+| A declaration whose `metadata` names a slot | Refused (`LitellmKeyCallbackMetadataDeclaredError`): stored encrypted, it would never read back equal and every deploy would fail with `LitellmKeyFieldNotAppliedError`. |
+| A metadata write onto a key that has a slot | Refused (`LitellmKeyCallbackMetadataLiveError`): the resource never read the slot, so the update could not carry it, and LiteLLM would drop it.                          |
+| A write that touches no `metadata`          | Goes ahead: the update body has no `metadata`, and the column is left as it is.                                                                                          |
+
+Configure key logging in LiteLLM itself. ⚠️ The raw slot still crosses the wire in `/key/list`'s answer
+(as every read of that row does), so `DISTILLED_DEBUG_HTTP`, which prints response bodies, would show a
+legacy plaintext one on a read; it is refused only for a create, where the request carries the key.
+UNVERIFIED: whether `/key/list` returns the stored (encrypted) or the decrypted form of `callback_vars`;
+either is dropped before it reaches an attribute.

package/docs/litellm-key.md

@@ -0,0 +1,194 @@
+# LiteLLM — `LiteLLM.Key`
+
+One virtual key of LiteLLM's `LiteLLM_VerificationToken` (`/key/*`), bound to a
+[`LiteLLM.Budget`](./litellm-budget.md) tier, with its value **kept out of Alchemy state**. Typed
+calls come from `@distilled.cloud/litellm/key_management`; credentials and the family's refusals are
+in [litellm.md](./litellm.md). Read 2026-09-29 against `@homeflare/distilled-litellm@0.3.0`
+(generated at LiteLLM **1.103.0**) and the 1.103.0 PyPI wheel's own source.
+
+## The key value is write-only
+
+Alchemy persists props **and** attributes unencrypted: a `Redacted` is tagged, not encrypted
+(`State/StateEncoding.ts` writes the inner value beside the tag). So the key's value can be neither a
+prop nor an attribute, and `LiteLLM.Key` uses the mechanism every other kit secret uses
+(`src/secrets/write-only.ts`, the same one as the PBS webhook secret): the prop holds the **name** of
+an environment variable.
+
+```ts
+import * as Effect from 'effect/Effect';
+import { LiteLLMBudget, LiteLLMKey } from '@homeflare/alchemy/litellm';
+
+export default Effect.gen(function* () {
+  const tier = yield* LiteLLMBudget('Tier', { budgetId: 'hf-tier-seat', softBudget: 25 });
+  yield* LiteLLMKey('Seat', {
+    keyAlias: 'hf-seat-a',
+    key: { fromEnv: 'HF_SEAT_A_KEY' }, // a random `sk-…` minted outside, e.g. in the vault
+    budgetId: tier.budgetId, // an Output: Alchemy creates the tier first
+    models: ['glm-5.3', 'gpt-oss-120b'],
+    metadata: { seat: 'a' },
+  });
+});
+```
+
+Then provide `litellmProviders()` alongside the stack's other providers, as
+[litellm.md](./litellm.md#example) shows.
+
+| where the value is         | it is                                                                                                                                                            |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| the declaration / state    | never: the state row holds `{ fromEnv: 'HF_SEAT_A_KEY' }`, the NAME                                                                                              |
+| `diff`, a plan             | a set variable is checked against the live token in memory; unset/empty skips verification                                                                       |
+| `/key/generate`'s body     | once, on create, unwrapped in `createBody` and nowhere else                                                                                                      |
+| `/key/generate`'s response | `Redacted` (the SDK's `T.SensitiveValue`); compared with what was sent                                                                                           |
+| an attribute, error or log | never: errors name the alias, the variable and the rule, not the value; a failed create is `LitellmKeyTransportError`, never the SDK's `HttpClientError` (below) |
+
+★ **Why the value is minted outside and not by LiteLLM.** `/key/generate` does return the new key,
+and the SDK hands it back `Redacted`. A resource has two places to put it: an attribute, which is
+state in the clear, or nowhere, and LiteLLM never shows the plaintext again (only its hash). A key
+minted and dropped is a row nobody can use. `/key/generate`'s own docstring supports a caller-chosen
+value: "Must start with 'sk-' and be at least 16 characters long."
+
+- **The value is sent only on create.** For an existing key, plan and reconcile compare a set
+  variable's sha256 with the live row's `token`, only in memory. A mismatch is a typed
+  `LitellmKeyValueMismatchError`, even when every prop is unchanged. `/key/update` drops `key`
+  and cannot rotate it; `/key/regenerate` is an Enterprise feature. **Rotate with a new alias.**
+- **Unset or empty variables skip verification on existing keys**, including ordinary settings
+  updates. A deployer need not hold the seat key. Creation still requires the declared value.
+- **Adopting needs no value.** Omit `key` to manage an existing key's settings. A create with no `key`
+  is refused (`LitellmKeyValueRequiredError`): it would mint a value nobody holds.
+- **A malformed value is refused before any write**: not `sk-…`, under 16 characters (both LiteLLM's
+  rules) or containing whitespace (the house's: a renderer's trailing newline would be sent as part of
+  the value). The error names the variable and the rule, never the value.
+- ⛔ **`DISTILLED_DEBUG_HTTP` refuses a create.** While it is set the SDK prints the first 400
+  characters of every request and response body to stderr (`@distilled.cloud/core`, read 2026-09-29),
+  and `/key/generate` carries the key in both. An update carries no value, so it is not refused.
+- ⛔ **A create that fails on the wire does not carry the request.** `/key/generate`'s request body is
+  `{"key":"sk-…"}`, and the SDK's `HttpClientError` holds its request, so `JSON.stringify`,
+  `Bun.inspect` at depth or Effect's JSON logger printed the value from a dropped connection, from the
+  deploy that failed over it, and from a defect (`protocol-rest.ts` reads a body with `Effect.orDie`).
+  Measured 2026-09-29 with a synthetic key (`key-transport.test.ts`, each reading searched for the
+  value). `generateKey` turns both into `LitellmKeyTransportError`: the alias and the reason's tag, no
+  request, no cause. The key **may** exist afterwards (the answer can be lost after the write); the next
+  deploy sees a live key with no state and takes it with `--adopt`, and one that did not land is created.
+  The SDK's status errors (`BadRequest`, `Forbidden`, …) hold only the proxy's message and stay typed.
+- ⚠️ **A proxy with the dashboard's `disable_custom_api_keys` setting on** answers 403 to any
+  user-defined key (`_check_custom_key_allowed`). It surfaces as the SDK's `Forbidden`.
+  UNVERIFIED whether the estate's proxy has it on.
+- **A proxy that ignores the value** and mints its own would leave a key nobody can use, reported as
+  a success. `/key/generate` echoes the key; a different one is deleted again and refused
+  (`LitellmKeyValueNotHonouredError`). UNVERIFIED that any proxy does this.
+
+Measured against the installed `alchemy@2.0.0-beta.79`: `src/Provider.ts:274–289` declares
+`diff` as `Effect<Diff | void, any, DiffReq>`. `src/Plan.ts:1503–1527` invokes it before falling
+back to props equality, so unchanged props do not bypass verification; `:750–765` also calls it
+for stable-reference evaluation. The check reads the live token each time and persists neither
+value nor hash. Unresolved props defer to reconcile. `key-rotation.test.ts` exercises real
+Plan/Apply with only the environment changed, no adoption and no other drift.
+
+## Props
+
+| prop            | type                      | notes                                                                                   |
+| --------------- | ------------------------- | --------------------------------------------------------------------------------------- |
+| `keyAlias`      | `string`                  | **Identity.** Non-empty, unique per proxy. Declare an existing key's alias to adopt it. |
+| `key`           | `{ fromEnv: string }`     | Write-only, create-only. Optional when the key already exists.                          |
+| `budgetId`      | `string \| null`          | The tier. Pass `budget.budgetId` and Alchemy creates the tier first. `null` unbinds.    |
+| `models`        | `string[]`                | `[]` = **all models** (LiteLLM's reading). Compared order-insensitively.                |
+| `allowedRoutes` | `string[]`                | Exact or wildcard routes. `[]` = no route restriction.                                  |
+| `teamId`        | `string \| null`          | `null` detaches the team.                                                               |
+| `metadata`      | `Record<string, unknown>` | The keys you manage: a **merge**, see [below](#metadata). Stored in state: no secrets.  |
+| `duration`      | `string \| null`          | `'30d'`, `'12h'`, … from creation. `null` = never expires. See below.                   |
+
+⛔ **A declaration manages only what it names.** An omitted prop is neither compared nor sent, so a
+live scope, budget, team or expiry stays as it is; a **new** key with no `models` starts with
+LiteLLM's default, all models. Clearing is explicit: `models: []`, `allowedRoutes: []`,
+`budgetId: null`, `teamId: null`, `duration: null`. Omission never clears, because clearing fails open
+on a credential: `[]` is "all models" and "no route restriction", and an adopted key's plan says
+`adopted`, never the `update` the apply would send (the plan cannot probe it; `--adopt` given for
+another resource takes over every declared key whose alias is live).
+
+Attributes: `keyAlias`, `budgetId`, `models`, `allowedRoutes`, `teamId`, `metadata`, `expires` (what
+the row says, observed), `duration` (see below) and `withheld` (the names of the `metadata` callback
+slots the row has, [below](#metadata)). ⛔ There is no `key`, `token` or hash attribute.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Identity    | `keyAlias`. A different alias is **refused** (`LitellmKeyAliasChangedError`), not replaced: the new key would need the same value, and a retained old row still holds it.                        |
+| Adopt       | A live key with the alias and no state is `Unowned`; needs `--adopt`. The apply re-checks it (`refuseTakeover`) for a create the planner could not probe.                                        |
+| Removal     | `defaultRemovalPolicy: 'retain'`: deleting a key breaks whatever holds it. Opt in with `RemovalPolicy.destroy()`.                                                                                |
+| Read        | `/key/list?key_alias=…&return_full_object=true`. Two rows under one alias are refused (`LitellmKeyAmbiguousAliasError`); the column is not unique in LiteLLM's schema.                           |
+| Update      | `/key/update` by alias with **only the declared fields that differ**. A declared `null` on `budget_id`/`team_id`/`duration` is sent as `null`, a declared `[]` as `[]`; `metadata` is merged.    |
+| Write check | Reconcile reads back; a field the row still differs on fails with `LitellmKeyFieldNotAppliedError`.                                                                                              |
+| Delete      | Idempotent by the list: an absent alias writes nothing. The SDK's `KeyNotFound` (a lost race, a retried delete) re-lists and is swallowed only if the key is gone. Any other failure propagates. |
+| Read errors | A 5xx on `/key/list` propagates typed. It is never read as "no such key" (which would go on to create one).                                                                                      |
+
+### `duration`
+
+The row carries `expires`, an absolute time, so a declared `'30d'` cannot be read back. State
+remembers the duration this provider last wrote. Changing it, or declaring `null`, plans an `update`
+that sends `duration` (`null` = never expires; the 1.103.0 source sets `expires` from it). Omitting it
+leaves a live expiry alone. A key whose expiry was set or cleared by hand while the declaration names
+a `duration` plans an update too.
+⚠️ **An adopted key remembers nothing**, so declaring a `duration` on one re-arms its expiry once,
+from that deploy; afterwards a plan is quiet.
+
+## Operations used, none guessed
+
+Every call is `@distilled.cloud/litellm/key_management`'s own operation with its own request type,
+through `throughFetch` (`operations.ts`); nothing is hand-rolled.
+
+| operation                      | route                | used for                                                 |
+| ------------------------------ | -------------------- | -------------------------------------------------------- |
+| `listKeysKeyListGet`           | `GET /key/list`      | read by `key_alias`, `return_full_object: true`          |
+| `generateKeyFnKeyGeneratePost` | `POST /key/generate` | create, with the user-defined `key`                      |
+| `updateKeyFnKeyUpdatePost`     | `POST /key/update`   | merge patch, found by `key_alias` (no `key` in the body) |
+| `deleteKeyFnKeyDeletePost`     | `POST /key/delete`   | delete by `key_aliases`                                  |
+
+Not used: `/key/info` and `/v2/key/info` take the key or its hash, which an adopted key never has.
+
+## Measured, and not
+
+Measured 2026-09-29 in the 1.103.0 wheel's source (`litellm/proxy/management_endpoints/
+key_management_endpoints.py`), not against a live proxy: `hash_token` is `sha256` hex; a duplicate
+alias is 400 (`_enforce_unique_key_alias`, :7639); a user-defined key must start `sk-` and be 16+
+characters (:1477-1490); `/key/update` applies `model_dump(exclude_unset=True)`, so an explicit `null`
+clears a column and `key` is dropped (:2468-2469); `/key/delete` of an absent alias is **404** "No
+keys found" (:4914) and of a forbidden one 403 (:4933); `/key/list` filters `key_alias` exactly, page
+size at most 100 (:6376); `models` and `allowed_routes` are non-null `String[]` columns, hence `[]`
+not `null` to clear.
+
+★ **`/key/delete`'s 404 and 403 are typed by the SDK, as resource-specific tags.** The operation
+declared 400 and 422 only, so both surfaced at runtime as core's status-mapped `NotFound`/`Forbidden`,
+outside its error type. A distilled patch (`patches/key_management/delete_key_fn_key_delete_post.json`
+in the distilled clone, byte-copied here) now types them as `KeyNotFound` (404, the message
+`No keys found`) and `KeyDeleteForbidden` (403, `You are not authorized to delete this key`), each
+matched on the status AND that phrase. `delete_key_fn` re-raises through `handle_exception_on_proxy`, so
+the wire message is Python's `str(detail)`, `{'error': 'No keys found'}`, which the `includes` matcher
+fits, as it fits a bare `detail`. `deleteKey` does `catchTag('KeyNotFound')`, then re-lists: the absence
+proof is still the list, never the tag. A 404 without the phrase (a proxy in front) stays core's
+`NotFound` and fails. UNVERIFIED against a live proxy: the wire shape is read from the wheel's source.
+The tags ship with the next `@homeflare/distilled-litellm` release (its own changeset); the workspace copy has them now.
+
+UNVERIFIED: that `/key/list?return_full_object=true` returns `budget_id` on a live 1.103.0 proxy (the
+generated row type and the Prisma model both carry it; a miss fails the apply loudly as
+`LitellmKeyFieldNotAppliedError`, never silently); the status of a `budget_id` naming no budget; a
+retried `/key/generate` after a lost response (the SDK's default retry applies; the next deploy reads
+the row). No live LiteLLM was contacted.
+
+## `metadata`
+
+LiteLLM keeps a key's guardrails, tags, per-model RPM/TPM limits, `allowed_passthrough_routes` and
+more **inside** `metadata`, and `/key/update` replaces the column with what it is sent. So `metadata`
+is a **merge** at the top-level key: the keys you declare are compared and written, every other live
+key is carried into the update body unchanged, and one is cleared by declaring it `null`. Declaring
+`{ seat: 'a' }` on a key that also has `guardrails` leaves them. Details and the measured source:
+[litellm-key-metadata.md](./litellm-key-metadata.md). ⛔ `logging`, `callback_settings` and
+`secret_manager_settings` carry callback secret keys: they are never held in state, a declaration
+naming one is refused, and a metadata write onto a key that has one is refused (`withheld`).
+
+## Not modelled
+
+`max_budget`/`soft_budget`, `object_permission`, `blocked`, `spend` and the top-level rate limits.
+The row read back has some of them, some it does not, and a field a declaration cannot diff is a field
+it cannot own. Bind a `LiteLLM.Budget` for limits. `/key/update` is a merge patch for the columns, so
+a field this resource never sends is left as it is; the ones inside `metadata` are left by the merge.