@homeflare/alchemy 0.42.0 → 0.43.0

package/docs/litellm-budget.md

@@ -0,0 +1,55 @@
+# LiteLLM — `LiteLLM.Budget`
+
+One row of LiteLLM's `LiteLLM_BudgetTable` (`/budget/*`): the "tier" that virtual keys and teams
+bind to (`hf-tier-agent`, `hf-tier-interactive`, …). Typed calls come from
+`@distilled.cloud/litellm/budget_management`; credentials and refusals are the family's, see
+[litellm.md](./litellm.md).
+
+## Monitoring, not limits
+
+`max_budget` is a **hard cap**: LiteLLM's own field doc says "Requests will fail if this budget
+(in USD) is exceeded". On 2026-09-28 an undeclared $60/day cap on `hf-tier-interactive` (made
+through the API on 09-06, in no repo) 429'd every call of the claude2 fleet. So:
+
+- `softBudget` is the prop to reach for: it "will NOT fail if this is exceeded" and fires the alert.
+- `maxBudget` is **never defaulted**, and the plan is refused
+  (`LitellmBudgetHardCapUnjustifiedError`) unless `maxBudgetReason` is set. The reason lives in the
+  declaration, so a hard cap is a reviewed line of source, not an API side effect.
+
+```ts
+export class Interactive extends LiteLLMBudget('Interactive', {
+  budgetId: 'hf-tier-interactive', // adopts the live row (needs --adopt)
+  budgetDuration: '1d',
+  softBudget: 60,
+  rpmLimit: 60,
+  tpmLimit: 6_000_000,
+}) {}
+```
+
+Declaring an adopted hard tier **without** `maxBudget` clears the live cap: the update sends an
+explicit `null` for every limit the declaration omits.
+
+## Behaviour
+
+| Concern     | Rule                                                                                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity    | `budgetId` (else a deterministic physical name). A different declared id is a `replace`.                                                                    |
+| Adopt       | A live row with the id and no state is `Unowned`; needs `--adopt`.                                                                                          |
+| Removal     | `defaultRemovalPolicy: 'retain'`. Opt in with `RemovalPolicy.destroy()`. Delete is idempotent: a `BadRequest` is swallowed only if a re-list shows it gone. |
+| Read        | `/budget/list` (whole table). `rpm_limit`/`tpm_limit` come back as decimal strings (`BigInt?`), converted to numbers.                                       |
+| Write check | Reconcile reads back; a limit the row still carries that the declaration dropped fails with `LitellmBudgetFieldNotClearedError`.                            |
+
+## Version: distilled copy is 1.100.0, the proxy is 1.103.0
+
+The SDK is generated at v1.100.0. For the budget routes the request bodies used here
+(`budget_id`, `soft_budget`, `max_budget`, `budget_duration`, `rpm_limit`, `tpm_limit`) are all in
+that schema. **Not measured against 1.103.0** (no live proxy read was made, and the source for it
+is not cloned): whether `/budget/update` accepts an explicit `null` to clear a limit, and what
+happens on create of an existing id. The fake models 400 for both. The read-back check above
+exists so an `exclude_none` merge fails loudly instead of leaving a hard cap in place.
+
+## Not modelled
+
+`max_parallel_requests`, `model_max_budget` and `budget_reset_at`: the row read back
+(`BudgetListItem`) does not carry them, so a declaration could never be diffed. Add them once a
+read that returns them is measured. Keys and teams that reference a tier are separate resources.

package/docs/litellm.md

@@ -16,12 +16,13 @@ against the tag's committed `schema.d.ts`; NOT a live read, because the referenc
 Measured at 1.100.0 (`schema.prisma`, `pass_through_endpoints.py`, and the mini's own
 `settings.yaml` `store_model_in_db: true`):
 
-| Family                                                                                                  | Managed by this resource?                       |
-| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| Pass-through endpoints                                                                                  | Yes — this package                              |
-| Models, virtual keys, teams, credentials, access groups                                                 | DB-backed, API-managed, but no kit resource yet |
-| `router_settings`, `litellm_settings`, `general_settings.master_key`/`database_url`/`store_model_in_db` | config-file only — read-only through the API    |
-| A `config.yaml` pass-through entry (`is_from_config: true`)                                             | Read-only through this resource — see Refusals  |
+| Family                                                                                                  | Managed by this resource?                                        |
+| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Pass-through endpoints                                                                                  | Yes — this package                                               |
+| Budgets (`/budget/*`)                                                                                   | Yes — `LiteLLM.Budget`, [litellm-budget.md](./litellm-budget.md) |
+| Models, virtual keys, teams, credentials, access groups                                                 | DB-backed, API-managed, but no kit resource yet                  |
+| `router_settings`, `litellm_settings`, `general_settings.master_key`/`database_url`/`store_model_in_db` | config-file only — read-only through the API                     |
+| A `config.yaml` pass-through entry (`is_from_config: true`)                                             | Read-only through this resource — see Refusals                   |
 
 ## Credentials
 

package/docs/postgres.md

@@ -123,3 +123,25 @@ mini's 19 already-live databases needs `adopt(true)` in the consuming stack.
 
 Whether `ALTER DATABASE … REFRESH COLLATION VERSION` should ever be offered as an explicit,
 separate operation (not part of `reconcile`) is open — nothing in this family calls it.
+
+## Runner transport (loopback-only clusters)
+
+A cluster reachable only by a command — CT100's rootful podman container `postgres`, loopback
+listener, local socket, user `postgres`, no password — cannot take a wire connection from the
+mini. `postgresRunnerProviders({ run, database, username, template? })` (or
+`postgresRunnerConnection` on its own) runs the same `Postgres.Database` reconcile through a
+caller-supplied `PsqlRunner`, which prepends the transport, e.g. `ssh <host> sudo -n podman
+exec -i postgres <argv>` with `stdin` piped through. The kit holds no host, container or sudo
+rule; the consuming stack's runner does.
+
+- Same props, same create-and-assert, same adopt/retain and drift semantics — only the
+  `PgExecutor` differs (`psql-executor.ts`).
+- `psql` has no bind parameters, so string params are inlined as `quoteStringLiteral`
+  literals; a non-string param is refused. Rows come back through `json_agg`, so `oid` and
+  `datconnlimit` are numbers as on the socket path.
+- `CREATE DATABASE … TEMPLATE "template0"` is the runner default (`template` overrides):
+  CT100's `template1` is ParadeDB's and would copy postgis/pg_ivm/paradedb objects. The socket
+  path adds no `TEMPLATE` clause, unchanged.
+- Not covered: there is no `Postgres.Role` resource in the kit yet, so the owner role must
+  exist (`PostgresDatabaseOwnerMissing` otherwise). NetBox's 11 lost triggers on `pg_restore`
+  are a restore concern, out of this resource's scope.

package/docs/proxmox-sdk-migration.md

@@ -44,6 +44,51 @@ SdnVnet, SdnSubnet, HaResource, HaRule and CephFlag.
 Their previous measured-none records
 are historical inventories, not a current census or permission to skip migration.
 
+**Measured 2026-09-28, by parser** (Bun's `Transpiler.scanImports` — a real import-graph
+read, not a text match — walked one hop through local imports so a family that only
+reaches the hand client via the shared `resource.ts` factory is still attributed
+correctly; run against `packages/alchemy/src/proxmox` and `src/openbao`):
+
+| Package                           | distilled-only | hand-client-only                                                                                                                                                                                | mixed                                                                                                    | no transport import (pure logic/form/test) |
+| --------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `alchemy/src/proxmox` (165 files) | 71             | 9 — `resource.ts` (the shared `pveHandlers` factory itself), `sdn-zone.ts`, `sdn-vnet.ts`, `sdn-subnet.ts`, `sdn-apply.ts`, `sdn-apply-read.ts`, `ha-resource.ts`, `ha-rule.ts`, `ceph-flag.ts` | 1 — `index.ts` (barrel, re-exports both)                                                                 | 84                                         |
+| `alchemy/src/openbao` (80 files)  | 2              | 36 (every `Bao*` family but Policy)                                                                                                                                                             | 5 — `distilled.ts`, `policy-wire.ts`, `policy-identity.ts`, `auth-role-wire.ts`, `auth-role-identity.ts` | 37                                         |
+
+The proxmox count confirms the doc text above with one addition: nine, not eight,
+files are hand-client-only. Eight back the seven named families (SdnApply's family
+spans two files, `sdn-apply.ts` and `sdn-apply-read.ts`); the ninth is `resource.ts`
+— the shared `pveHandlers`/`pveOperations` factory itself, which imports
+`./client.ts` and no `@distilled.cloud/*` module, so
+the one-hop rule that correctly attributes the seven named families' hand-client use
+attributes this file's own import the same way. It does not mean every distilled-only
+family still calls through it: 17 of the 71 import `resource.ts`, and all 17 are
+type-only (`PveRequirements`/`WithTarget`, or `WithPbsTarget` for three PBS files —
+types are erased at build time, invisible to `scanImports`, so the parser correctly
+leaves them out of this table). `ceph-osd.ts` is one of those 17, not an exception;
+it is the only one of the 71 that even mentions `pveHandlers` at all, in a comment
+explaining why it deliberately does not use the factory — read in full, it calls
+neither factory function. No other PVE/PBS family has regressed to hand-client
+since the 28-family migration
+landed.
+
+**OpenBao is far less migrated than this repo's own comments could suggest** — only
+`BaoPolicy`'s wire/identity pair and the `distilled.ts` wrapper use distilled transport
+at all today; every other family (`BaoMount`, `BaoAuthMethod`, `BaoAuthRole`'s form
+paths, `BaoPkiRole`, `BaoSshRole`, `BaoCloudflareRole`, `BaoProxmoxRole`, `BaoJwtRole`,
+`BaoJwtAuthConfig`, `BaoMfaTotpMethod`, `BaoMfaLoginEnforcement`, `BaoPlugin`,
+rename/remount/role-reconcile helpers) is still on the hand `bao-http.ts` client.
+`mount-wire.ts` specifically is blocked on more than volume: the distilled SDK's
+`mounts.ts` operations all declare `errors: []` (no typed absence error), unlike the
+sibling `policies.ts`'s `PolicyNotFound` — a clean migration needs that SDK gap patched
+first, in the distilled clone, per [the interim route](./distilled-interim.md)'s
+build-SDK-first step. Two `codex/`-prefixed worktrees already exist in the distilled
+clone (`openbao-mount-map`, `openbao-policy-runtime`) with unmerged work toward exactly
+this: `openbao-mount-map`'s six commits generate the OpenBao SDK from a disposable local
+2.6.2 server and add a typed mount-inventory response shape (`protocol-mount-tables.ts`,
+provenance in `patches/mount-tables.md`), but its `mounts.ts` operations still declare
+`errors: []` — the inventory-shape fix and the typed-absence-error fix are two separate
+gaps, and only the first is done there.
+
 - NetworkApply reads `listNodeNetwork`. A string `changes` sibling is preserved by
   the protocol and decoded by that operation's union. The diff is counted and does
   not enter state or logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -128,12 +128,12 @@
   "dependencies": {
     "@distilled.cloud/caddy": "npm:@homeflare/distilled-caddy@0.2.2",
     "@distilled.cloud/grafana": "npm:@homeflare/distilled-grafana@0.2.0",
-    "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
+    "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.3.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/openbao": "npm:@homeflare/distilled-openbao@0.2.2",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.3.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.3",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.4",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",
     "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.4.0"
   },

package/src/litellm/budget-errors.ts

@@ -0,0 +1,38 @@
+/**
+ * The typed refusals `LiteLLM.Budget` raises on top of `@distilled.cloud/litellm`'s own SDK errors.
+ */
+import type * as budgets from '@distilled.cloud/litellm/budget_management';
+import * as Data from 'effect/Data';
+
+/** A `maxBudget` (a HARD cap: LiteLLM answers 429 once it is spent) declared with no reason. */
+export class LitellmBudgetHardCapUnjustifiedError extends Data.TaggedError(
+  'LitellmBudgetHardCapUnjustifiedError',
+)<{
+  readonly budgetId: string | undefined;
+}> {}
+
+/**
+ * The write returned no error but the row still carries a limit the declaration does not.
+ * `/budget/update` may merge with `exclude_none` (the way `/config/pass_through_endpoint` does),
+ * in which case a limit can never be cleared by an update. Refused, never claimed as done.
+ */
+export class LitellmBudgetFieldNotClearedError extends Data.TaggedError(
+  'LitellmBudgetFieldNotClearedError',
+)<{
+  readonly budgetId: string;
+  readonly fields: readonly string[];
+}> {}
+
+/** `/budget/info` answered something that is not a list of budget rows. */
+export class LitellmBudgetUnreadableError extends Data.TaggedError('LitellmBudgetUnreadableError')<{
+  readonly budgetId: string;
+}> {}
+
+export type BudgetError =
+  | budgets.PostInfoBudgetBudgetInfoError
+  | budgets.PostNewBudgetBudgetNewError
+  | budgets.UpdateBudgetBudgetUpdatePostError
+  | budgets.DeleteBudgetBudgetDeletePostError
+  | LitellmBudgetHardCapUnjustifiedError
+  | LitellmBudgetFieldNotClearedError
+  | LitellmBudgetUnreadableError;

package/src/litellm/budget-form.ts

@@ -0,0 +1,94 @@
+/**
+ * Props, wire bodies and comparison for `LiteLLM.Budget`, testable without a server.
+ *
+ * ⛔ NO SILENT `max_budget`. LiteLLM's own field doc: "Requests will fail if this budget (in USD)
+ *   is exceeded" — a hard cap. On 2026-09-28 an undeclared $60/day `max_budget` on
+ *   `hf-tier-interactive` 429'd the whole claude2 fleet. So `maxBudget` is never defaulted and is
+ *   refused unless `maxBudgetReason` says why; `softBudget` is the monitoring field (it "will NOT
+ *   fail if this is exceeded", it fires the alert).
+ * ⚠️ NOT MODELLED: `max_parallel_requests`, `model_max_budget`, `budget_reset_at`. The row read
+ *   back (`BudgetListItem`, generated at LiteLLM 1.100.0) has none of them, so a declaration of
+ *   them could never be diffed. Add them when a read that returns them is measured.
+ */
+import type * as budgets from '@distilled.cloud/litellm/budget_management';
+
+export interface BudgetProps {
+  /** Live budget id. Set it to adopt an existing row (`hf-tier-agent`); default is a deterministic physical name. */
+  readonly budgetId?: string;
+  /** Alert threshold in USD. Requests keep flowing when exceeded. The monitoring field. */
+  readonly softBudget?: number;
+  /** HARD cap in USD: requests fail (429) once spent. Refused unless `maxBudgetReason` is set. */
+  readonly maxBudget?: number;
+  /** Why a hard cap is wanted. Required with `maxBudget`; recorded in the declaration only. */
+  readonly maxBudgetReason?: string;
+  /** Reset period, e.g. `'1d'`, `'28d'`. */
+  readonly budgetDuration?: string;
+  /** Requests per minute. */
+  readonly rpmLimit?: number;
+  /** Tokens per minute. */
+  readonly tpmLimit?: number;
+}
+
+export interface BudgetAttributes {
+  readonly budgetId: string;
+  readonly softBudget: number | null;
+  readonly maxBudget: number | null;
+  readonly budgetDuration: string | null;
+  readonly rpmLimit: number | null;
+  readonly tpmLimit: number | null;
+}
+
+/** Declared field → wire field. The single list every comparison and body walks. */
+const FIELDS = [
+  ['softBudget', 'soft_budget'],
+  ['maxBudget', 'max_budget'],
+  ['budgetDuration', 'budget_duration'],
+  ['rpmLimit', 'rpm_limit'],
+  ['tpmLimit', 'tpm_limit'],
+] as const;
+
+export const isHardCapUnjustified = (props: BudgetProps): boolean =>
+  props.maxBudget !== undefined && (props.maxBudgetReason ?? '').trim() === '';
+
+/** Create body: only what is declared. */
+export const createBody = (
+  props: BudgetProps,
+  budgetId: string,
+): budgets.PostNewBudgetBudgetNewRequest => {
+  const body: Record<string, unknown> = { budget_id: budgetId };
+  for (const [prop, wire] of FIELDS) if (props[prop] !== undefined) body[wire] = props[prop];
+  return body as budgets.PostNewBudgetBudgetNewRequest;
+};
+
+/** Update body: declared fields, plus an explicit `null` for a live limit the declaration dropped. */
+export const updateBody = (
+  props: BudgetProps,
+  live: BudgetAttributes,
+): budgets.UpdateBudgetBudgetUpdatePostRequest => {
+  const body: Record<string, unknown> = { budget_id: live.budgetId };
+  for (const [prop, wire] of FIELDS) {
+    if (props[prop] !== undefined) body[wire] = props[prop];
+    else if (live[prop] !== null) body[wire] = null;
+  }
+  return body as budgets.UpdateBudgetBudgetUpdatePostRequest;
+};
+
+/** Wire names of the fields where live and declared disagree. */
+export const differing = (live: BudgetAttributes, props: BudgetProps): readonly string[] =>
+  FIELDS.filter(([prop]) => live[prop] !== (props[prop] ?? null)).map(([, wire]) => wire);
+
+const numberOrNull = (value: unknown): number | null =>
+  value === null || value === undefined || value === '' ? null : Number(value);
+
+/**
+ * One row of `/budget/info`. `tpm_limit`/`rpm_limit` are `BigInt?` in LiteLLM's schema and come
+ * back as decimal strings (the generated `BudgetListItem` says so), hence `Number()`.
+ */
+export const toAttributes = (row: Record<string, unknown>): BudgetAttributes => ({
+  budgetDuration: typeof row['budget_duration'] === 'string' ? row['budget_duration'] : null,
+  budgetId: String(row['budget_id']),
+  maxBudget: numberOrNull(row['max_budget']),
+  rpmLimit: numberOrNull(row['rpm_limit']),
+  softBudget: numberOrNull(row['soft_budget']),
+  tpmLimit: numberOrNull(row['tpm_limit']),
+});

package/src/litellm/budget-operations.ts

@@ -0,0 +1,51 @@
+/**
+ * The four LiteLLM `/budget/*` calls `LiteLLM.Budget` uses, through the SDK's typed operations.
+ *
+ * ★ READS GO THROUGH `/budget/list` (the whole table, a bare array), not `/budget/info`. Both
+ *   answer `body: unknown` in the generated schema, and what `/budget/info` does for an id that is
+ *   not there is unmeasured; a list answers absence unambiguously.
+ * ⚠️ Unlike pass-through endpoints, each budget is its own DB row, so no semaphore.
+ * ⚠️ DELETE is idempotent BY THIS FUNCTION: a `BadRequest` re-lists and is swallowed only when the
+ *   id is genuinely absent, never on message text (pass-through `operations.ts`' rule).
+ */
+import * as budgets from '@distilled.cloud/litellm/budget_management';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { type BudgetAttributes, toAttributes } from './budget-form.ts';
+import { LitellmBudgetUnreadableError } from './budget-errors.ts';
+
+export const listBudgets = (): Effect.Effect<
+  readonly BudgetAttributes[],
+  budgets.ListBudgetBudgetListGetError | LitellmBudgetUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(budgets.listBudgetBudgetListGet({})).pipe(
+    // ⚠️ MEASURED with the fake: the SDK types this `{ body: unknown }` but hands a bare JSON array
+    //   back as the array itself, so accept both shapes and refuse anything else.
+    Effect.flatMap((response) => {
+      const rows: unknown = Array.isArray(response)
+        ? response
+        : (response as { body?: unknown }).body;
+      return Array.isArray(rows)
+        ? Effect.succeed(rows.map((row) => toAttributes(row as Record<string, unknown>)))
+        : Effect.fail(new LitellmBudgetUnreadableError({ budgetId: '*' }));
+    }),
+  );
+
+export const createBudget = (body: budgets.PostNewBudgetBudgetNewRequest) =>
+  throughFetch(budgets.postNewBudgetBudgetNew(body)).pipe(Effect.asVoid);
+
+export const updateBudget = (body: budgets.UpdateBudgetBudgetUpdatePostRequest) =>
+  throughFetch(budgets.updateBudgetBudgetUpdatePost(body)).pipe(Effect.asVoid);
+
+export const deleteBudget = (id: string) =>
+  throughFetch(budgets.deleteBudgetBudgetDeletePost({ id })).pipe(
+    Effect.asVoid,
+    Effect.catchTag('BadRequest', (original) =>
+      listBudgets().pipe(
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.budgetId === id) ? Effect.fail(original) : Effect.void,
+        ),
+      ),
+    ),
+  );

package/src/litellm/budget.test.ts

@@ -0,0 +1,105 @@
+/**
+ * `LiteLLM.Budget` through Alchemy's real Plan and Apply over the fake proxy.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, startFakeLitellm } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { type BudgetProps, LiteLLMBudget } from './budget.ts';
+import { differing, isHardCapUnjustified, toAttributes } from './budget-form.ts';
+
+const KEY = 'sk-test-master';
+const stack = (fake: ReturnType<typeof startFakeLitellm>) =>
+  fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: BudgetProps, name = 'Tier') =>
+  Effect.gen(function* () {
+    yield* LiteLLMBudget(name, props);
+  });
+
+const tier = {
+  budget_id: 'hf-tier-agent',
+  budget_duration: '1d',
+  created_at: 'x',
+  max_budget: 2,
+  rpm_limit: '60',
+  soft_budget: null,
+  tpm_limit: null,
+  updated_at: 'x',
+};
+
+test('creates a soft-only budget and sends no max_budget', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  const planned = await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-x', budgetDuration: '1d', softBudget: 50 }),
+  );
+  expect(planned).toEqual({ Tier: 'create' });
+  expect(fake.budgets()[0]).toMatchObject({ budget_id: 'hf-tier-x', soft_budget: 50 });
+  expect(fake.budgets()[0]).not.toHaveProperty('max_budget');
+});
+
+test('a second deploy of the same declaration writes nothing', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  const props = { budgetId: 'hf-tier-x', softBudget: 50, rpmLimit: 60 };
+  const same = stack(fake);
+  await same.deploy(declare(props));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(props))).toEqual({ Tier: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a hard cap without a reason is refused before any write', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  await expect(
+    stack(fake).deploy(declare({ budgetId: 'hf-tier-x', maxBudget: 60 })),
+  ).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(isHardCapUnjustified({ maxBudget: 1, maxBudgetReason: ' ' })).toBe(true);
+  expect(isHardCapUnjustified({ maxBudget: 1, maxBudgetReason: 'abuse guard' })).toBe(false);
+});
+
+test('a hard cap with a reason is written', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY });
+  await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-x', maxBudget: 5, maxBudgetReason: 'public voice endpoint' }),
+  );
+  expect(fake.budgets()[0]).toMatchObject({ max_budget: 5 });
+});
+
+test('a live row is Unowned: refused without --adopt, taken with it', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier] });
+  const props = {
+    budgetId: 'hf-tier-agent',
+    budgetDuration: '1d',
+    maxBudget: 2,
+    maxBudgetReason: 'measured live',
+  };
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(props))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  const planned = await engine.deploy(declare({ ...props, rpmLimit: 60 }), { adopt: true });
+  expect(Object.values(planned)).toEqual(['adopted']);
+});
+
+test('adopting a hard tier and declaring it soft clears max_budget', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier] });
+  await stack(fake).deploy(
+    declare({ budgetId: 'hf-tier-agent', budgetDuration: '1d', rpmLimit: 60, softBudget: 2 }),
+    { adopt: true },
+  );
+  expect(fake.budgets()[0]).toMatchObject({ max_budget: null, soft_budget: 2 });
+});
+
+test('a proxy that cannot clear a limit fails the apply instead of claiming success', async () => {
+  const fake = startFakeLitellm({ masterKey: KEY, budgetSeed: [tier], budgetExcludeNone: true });
+  await expect(
+    stack(fake).deploy(declare({ budgetId: 'hf-tier-agent', budgetDuration: '1d', rpmLimit: 60 }), {
+      adopt: true,
+    }),
+  ).rejects.toThrow();
+});
+
+test('form helpers: string limits become numbers, and differences are named', () => {
+  const live = toAttributes(tier);
+  expect(live.rpmLimit).toBe(60);
+  expect(differing(live, { budgetDuration: '1d', rpmLimit: 60 })).toEqual(['max_budget']);
+});

package/src/litellm/budget.ts

@@ -0,0 +1,127 @@
+/**
+ * `LiteLLM.Budget` — one row of LiteLLM's `LiteLLM_BudgetTable` (`/budget/*`), the "tier" keys and
+ * teams bind to (`hf-tier-*`).
+ *
+ * ★ MONITORING, NOT LIMITS (Tim, 2026-09-28): `softBudget` is the prop; `maxBudget` is a hard cap
+ *   that 429s every caller and is refused without `maxBudgetReason` (budget-form.ts).
+ * ★ ADOPT BY id. `budgetId` names the live row; without it a deterministic physical name is used.
+ *   A foreign row with that id is `Unowned`, so it needs `--adopt`.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a budget row that keys still reference either
+ *   fails or detaches them, and a detached key loses its rate limits. Opt in with
+ *   `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ CLEARING A LIMIT: sent as an explicit `null`. If this LiteLLM merges with `exclude_none` the
+ *   row keeps the old value; reconcile reads back and FAILS (`LitellmBudgetFieldNotClearedError`)
+ *   rather than report a cleared cap. Unmeasured against a live proxy at 1.103.0.
+ * ⛔ NO 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 { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import {
+  LitellmBudgetFieldNotClearedError,
+  LitellmBudgetHardCapUnjustifiedError,
+} from './budget-errors.ts';
+import {
+  type BudgetAttributes,
+  type BudgetProps,
+  createBody,
+  differing,
+  isHardCapUnjustified,
+  updateBody,
+} from './budget-form.ts';
+import { createBudget, deleteBudget, listBudgets, updateBudget } from './budget-operations.ts';
+
+export type { BudgetAttributes, BudgetProps };
+export type { BudgetError } from './budget-errors.ts';
+
+export interface LiteLLMBudget extends Resource<'LiteLLM.Budget', BudgetProps, BudgetAttributes> {}
+
+export const LiteLLMBudget = Resource<LiteLLMBudget>('LiteLLM.Budget', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMBudget = (value: unknown): value is LiteLLMBudget =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Budget';
+
+const refuseUnjustifiedCap = (props: BudgetProps) =>
+  isHardCapUnjustified(props)
+    ? Effect.fail(new LitellmBudgetHardCapUnjustifiedError({ budgetId: props.budgetId }))
+    : Effect.void;
+
+const idOf = (
+  id: string,
+  instanceId: string,
+  props: BudgetProps,
+  output: BudgetAttributes | undefined,
+) =>
+  output?.budgetId !== undefined
+    ? Effect.succeed(output.budgetId)
+    : props.budgetId !== undefined
+      ? Effect.succeed(props.budgetId)
+      : createPhysicalName({ id, instanceId, lowercase: true, maxLength: 64 });
+
+type Args<P> = {
+  id: string;
+  instanceId: string;
+  output: BudgetAttributes | undefined;
+} & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const budgetHandlers = {
+  read: ({ id, instanceId, olds, output }: Args<{ olds: BudgetProps }>) =>
+    Effect.gen(function* () {
+      const budgetId = yield* idOf(id, instanceId, olds, output);
+      const live = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({ news, output }: { news: Input<BudgetProps>; output: BudgetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuseUnjustifiedCap(news);
+      if (output === undefined) return undefined;
+      // The id is identity: a different declared id is a different row.
+      if (news.budgetId !== undefined && news.budgetId !== output.budgetId) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ id, instanceId, news, output }: Args<{ news: BudgetProps }>) =>
+    Effect.gen(function* () {
+      yield* refuseUnjustifiedCap(news);
+      const budgetId = yield* idOf(id, instanceId, news, output);
+      const before = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (before === undefined) yield* createBudget(createBody(news, budgetId));
+      else if (differing(before, news).length > 0) yield* updateBudget(updateBody(news, before));
+
+      const after = (yield* listBudgets()).find((row) => row.budgetId === budgetId);
+      if (after === undefined) {
+        return yield* Effect.die(
+          new Error(`LiteLLM.Budget ${budgetId}: write returned no error but the row is absent.`),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmBudgetFieldNotClearedError({ budgetId, fields: left }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: BudgetAttributes }) => deleteBudget(output.budgetId),
+
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMBudgetProvider = () =>
+  Provider.effect(LiteLLMBudget, Effect.succeed(LiteLLMBudget.Provider.of(budgetHandlers)));