@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/model.ts

@@ -0,0 +1,237 @@
+/**
+ * `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); this resource owns exactly one row.
+ *
+ * ★ ADOPT BY NAME. `modelName` finds the live row whose group name matches; declare `id` to pin one
+ *   instead. A live row with no state is `Unowned`, so it needs `--adopt`. A name matching more
+ *   than one listed row is refused, never guessed at (`LitellmModelAmbiguousNameError`).
+ * ★ `defaultRemovalPolicy: 'retain'` — a deployment's removal takes it out of its routing group for
+ *   every key that reaches it. Opt in with `.pipe(RemovalPolicy.destroy())`.
+ * ⛔ THE CREDENTIAL IS `{ fromEnv: 'NAME' }`, NEVER A VALUE (S25): it is sent in LiteLLM's own
+ *   reference form `os.environ/NAME` and the proxy resolves it in its own environment — nothing
+ *   here reads `process.env` (model-credential.ts), so a value could never be sealed truthfully.
+ *   A row's stored params come back DECRYPTED at v1.103.0 but with `api_key` STRIPPED (measured),
+ *   so a plan compares the visible fields plus a digest of the DECLARED values (`paramsSeal`) —
+ *   never the values themselves, which belong in the proxy's DB only (model-form.ts).
+ * ⚠️ A RENAME IS A NEW GROUP when the id is not pinned: the old row survives under 'retain', the
+ *   new group gets a fresh deterministic id. With a pinned id the SAME row is renamed — the caller
+ *   chose the row (model-types.ts).
+ * ⚠️ UNMEASURED AT 1.103.0, guarded by a read back: whether `/model/new` honours a supplied
+ *   `model_info.id`. The answer is an untyped body, so the id ASKED FOR is the one tracked
+ *   (model-operations.ts); a proxy that issued its own id fails loudly
+ *   (`LitellmModelAbsentAfterWriteError`) instead of recording a row it cannot identify.
+ */
+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 { noteUnfinished } from '../ownership/resume.ts';
+import {
+  LitellmModelAbsentAfterWriteError,
+  LitellmModelConfigFileRowError,
+  LitellmModelInvalidError,
+  LitellmModelNotConvergedError,
+} from './model-errors.ts';
+import { claimStatelessRow } from './model-claim.ts';
+import { createBody, declaredDigest, differing, firstProblem, patchBody } from './model-form.ts';
+import { sealState } from './model-credential.ts';
+import { findLive, wantedId } from './model-locate.ts';
+import {
+  createModel,
+  deleteModel,
+  listModels,
+  patchModel,
+  readModelRow,
+} from './model-operations.ts';
+import type { ModelAttributes, ModelProps } from './model-types.ts';
+
+export type { ModelAttributes, ModelProps };
+export type { ModelError } from './model-errors.ts';
+
+export interface LiteLLMModel extends Resource<'LiteLLM.Model', ModelProps, ModelAttributes> {}
+
+export const LiteLLMModel = Resource<LiteLLMModel>('LiteLLM.Model', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMModel = (value: unknown): value is LiteLLMModel =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Model';
+
+const refuse = (props: ModelProps) => {
+  const problem = firstProblem(props);
+  return problem === undefined
+    ? Effect.void
+    : Effect.fail(new LitellmModelInvalidError({ problem, modelName: String(props.modelName) }));
+};
+
+type Args<P> = {
+  fqn: string;
+  id: string;
+  instanceId: string;
+  output: ModelAttributes | undefined;
+} & P;
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const modelHandlers = {
+  /**
+   * ⛔ WITH NO `output` THIS IS ALCHEMY'S ADOPTION PROBE, AND THE ONLY PLAN-TIME HOOK A NEW MODEL
+   *   GETS — so the refusals run here too, as a defect (mcp-server.ts: the cold-start probe must
+   *   fail the plan, and a recovery read must degrade to "nothing recovered", which only a defect
+   *   does). The v1.103.0 read answers params decrypted with `api_key` stripped, so this refusal
+   *   is the declaration's (`firstProblem`), before Apply commits props into unencrypted state.
+   */
+  read: ({ id, instanceId, olds, output }: Args<{ olds: ModelProps }>) =>
+    Effect.gen(function* () {
+      const problem = output === undefined ? firstProblem(olds) : undefined;
+      if (problem !== undefined) {
+        return yield* Effect.die(
+          new LitellmModelInvalidError({ problem, modelName: String(olds.modelName) }),
+        );
+      }
+      // ★ THE LIST FIRST: one GET answers a name, an id and absence (model-locate.ts).
+      const found = yield* findLive(id, instanceId, olds, output);
+      if (found === undefined) return undefined;
+      // ★ AN INTERRUPTED UNPINNED CREATE. The recovery read reuses the `creating` row's instance
+      //   id, which is the one `POST /model/new` was given, so the live id matches the physical
+      //   name. The probe's instance id is minted fresh (Plan.ts `generateInstanceId`) and cannot
+      //   match a row this declaration created. A declared id can collide, so it stays `Unowned`.
+      if (output === undefined && olds.id === undefined) {
+        const physical = yield* createPhysicalName({
+          id,
+          instanceId,
+          lowercase: true,
+          maxLength: 64,
+        });
+        if (found.id === physical) return found;
+      }
+      // The row cannot supply a digest of what was declared; state can (model-form.ts).
+      return output === undefined ? Unowned(found) : { ...found, paramsSeal: output.paramsSeal };
+    }),
+
+  diff: ({
+    instanceId,
+    news,
+    output,
+  }: {
+    instanceId: string;
+    news: Input<ModelProps>;
+    output: ModelAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuse(news);
+      // ★ No attributes: an unfinished generation of our own. `--adopt` may resume it
+      //   (ownership/resume.ts). A fresh replace's new instance is never diffed this way.
+      if (output === undefined) return yield* noteUnfinished(instanceId);
+      // The id is identity: a different declared id is a different row.
+      if (news.id !== undefined && news.id !== output.id) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      // A rename without a pinned id is a new group (model.ts header): old row retained.
+      if (news.modelName !== output.modelName && news.id === undefined) {
+        return { action: 'replace', deleteFirst: false } as const;
+      }
+      // Visible drift, or a stale seal, is an update: the read strips `api_key`, so the
+      // seal is the only signal a declared credential moved (model-credential.ts).
+      // Reconcile then decides the write: a bare matching adopt records its seal
+      // locally, and a declaration that manages an invisible param PATCHes once to
+      // converge it.
+      return differing(output, news).length === 0 && sealState(news, output.paramsSeal) === 'match'
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ fqn, id, instanceId, news, output }: Args<{ news: ModelProps }>) =>
+    Effect.gen(function* () {
+      yield* refuse(news);
+      const before = yield* findLive(id, instanceId, news, output);
+      let sealed = output?.paramsSeal ?? '';
+      let modelId: string;
+
+      if (before === undefined) {
+        const wanted = yield* wantedId(id, instanceId, news, output);
+        yield* createModel(createBody(news, wanted));
+        // The id ASKED FOR is the one tracked; the read back refuses to claim a row the
+        // proxy filed elsewhere (model.ts header's unmeasured note, model-operations.ts).
+        modelId = wanted;
+        sealed = declaredDigest(news);
+      } else {
+        // ⛔ CONFIG-FILE ROWS ARE ALWAYS REFUSED. The DB API cannot manage a row the proxy
+        //   serves from its config file (`model_info.db_model: false`), regardless of whether
+        //   this stack already holds state for it.
+        if (before.dbModel === false) {
+          return yield* Effect.fail(
+            new LitellmModelConfigFileRowError({ id: before.id, modelName: news.modelName }),
+          );
+        }
+        // ⛔ NOTHING IS WRITTEN OVER A ROW THIS STACK HOLDS NO STATE FOR, unless the gate says
+        //   so (model-claim.ts): a deterministic id is ours, an older generation's id is refused
+        //   with a state-level recovery, and anything else needs `--adopt` on a create or an
+        //   unfinished generation. `output` may be the live attributes the plan stripped from
+        //   `Unowned(found)` (`paramsSeal` is empty until a deploy commits a seal), so the gate
+        //   runs both when output is undefined and when it is only a probe result.
+        const stateless = output === undefined || output.paramsSeal === '';
+        if (stateless) {
+          yield* claimStatelessRow({
+            beforeId: before.id,
+            fqn,
+            instanceId,
+            news,
+            output,
+            wanted: yield* wantedId(id, instanceId, news, output),
+          });
+        }
+        modelId = before.id;
+        const drifted = differing(before, news);
+        const sealStale = sealState(news, sealed) === 'stale';
+        // ⛔ A STAMPING ADOPT, AND ONE MORE REASON TO WRITE. A live row starts `paramsSeal: ''`
+        //   (model-form.ts), and the PATCH merge rewrites the managed `litellm_params`: a bare
+        //   adopt of an already-matching row records the digest locally and writes nothing. A
+        //   declaration that manages an invisible param (`apiKey` / `apiBase` — never on the
+        //   read) must still write once: a matching-looking row can carry a DIFFERENT stored
+        //   reference, and a local seal over it would freeze that divergence forever. A seal
+        //   that EXISTS and no longer matches is a declaration this resource already owns —
+        //   that one writes too, with nulls for the five non-`None` defaults (model-form.ts).
+        const sealNeedsStamp =
+          sealStale && (sealed !== '' || news.apiKey !== undefined || news.apiBase !== undefined);
+        if (drifted.length > 0 || sealNeedsStamp) {
+          yield* patchModel(patchBody(news, before));
+        }
+        if (drifted.length > 0 || sealStale) sealed = declaredDigest(news);
+      }
+
+      // ★ THE LIST FIRST, THEN BY ID: a row the list does not show yet (create commits, list
+      //   refreshes lazily) is still a live row if the by-id read answers it.
+      const after =
+        (yield* listModels()).find((row) => row.id === modelId) ?? (yield* readModelRow(modelId));
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmModelAbsentAfterWriteError({ id: modelId, modelName: news.modelName }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmModelNotConvergedError({
+            fields: left,
+            id: modelId,
+            modelName: news.modelName,
+          }),
+        );
+      }
+      return { ...after, paramsSeal: sealed };
+    }),
+
+  delete: ({ output }: { output: ModelAttributes }) => deleteModel(output.id),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMModelProvider = () =>
+  Provider.effect(LiteLLMModel, Effect.succeed(LiteLLMModel.Provider.of(modelHandlers)));

package/src/litellm/policy-attachment-form.ts

@@ -0,0 +1,103 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.PolicyAttachment`, testable without a server.
+ *
+ * ★ TWO ATTACHMENTS ARE "THE SAME" WHEN EVERY FIELD IS: the policy, the scope, the four selector SETS
+ *   and the priority. That is the only identity an attachment has (policy-attachment-types.ts), and
+ *   it is what adoption and the read back both use.
+ */
+import type * as policies from '@distilled.cloud/litellm/policy_engine';
+import {
+  asRow,
+  canonical,
+  firstBadEntry,
+  firstDuplicate,
+  isBlank,
+  numberOrNull,
+  sameSet,
+  stringOrNull,
+  stringsOf,
+} from './registry-support.ts';
+import type {
+  PolicyAttachmentAttributes,
+  PolicyAttachmentProps,
+} from './policy-attachment-types.ts';
+
+const SELECTORS = ['teams', 'keys', 'models', 'tags'] as const;
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: PolicyAttachmentProps): string | undefined => {
+  if (isBlank(props.policyName) || props.policyName !== props.policyName.trim()) {
+    return '`policyName` must be a non-blank name with no leading or trailing space';
+  }
+  if (props.scope !== undefined && props.scope !== '*') return "`scope` can only be '*'";
+  for (const field of SELECTORS) {
+    const values = props[field] ?? [];
+    const bad = firstBadEntry(values);
+    if (bad !== undefined)
+      return `\`${field}\` has a blank or padded entry (${JSON.stringify(bad)})`;
+    const twice = firstDuplicate(values);
+    if (twice !== undefined) return `\`${field}\` lists ${JSON.stringify(twice)} twice`;
+  }
+  if (props.scope === undefined && SELECTORS.every((field) => (props[field] ?? []).length === 0)) {
+    return "no `scope`, `teams`, `keys`, `models` or `tags`: LiteLLM treats an attachment with no selector as GLOBAL, so declare `scope: '*'` if that is meant";
+  }
+  if (
+    props.priority !== undefined &&
+    !(
+      Number.isInteger(props.priority) &&
+      props.priority >= -2147483648 &&
+      props.priority <= 2147483647
+    )
+  ) {
+    return '`priority` must be a 32-bit integer';
+  }
+  return undefined;
+};
+
+/** One attachment row. `undefined` is "not an attachment", and so is a config-file one. */
+export const toAttributes = (value: unknown): PolicyAttachmentAttributes | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const attachmentId = row['attachment_id'];
+  const policyName = row['policy_name'];
+  if (typeof attachmentId !== 'string' || typeof policyName !== 'string') return undefined;
+  return {
+    attachmentId,
+    keys: canonical(stringsOf(row['keys'])),
+    models: canonical(stringsOf(row['models'])),
+    policyName,
+    priority: numberOrNull(row['priority']),
+    scope: stringOrNull(row['scope']),
+    tags: canonical(stringsOf(row['tags'])),
+    teams: canonical(stringsOf(row['teams'])),
+  };
+};
+
+/** Whether a live row is defined in config.yaml (its synthetic id is `config-<n>`): out of reach of the API. */
+export const isConfigRow = (value: unknown): boolean =>
+  asRow(value)?.['definition_location'] === 'config';
+
+/** Wire names of the fields where live and declared disagree. Empty means "the same attachment". */
+export const differing = (
+  live: PolicyAttachmentAttributes,
+  props: PolicyAttachmentProps,
+): readonly string[] => {
+  const fields: string[] = [];
+  if (live.policyName !== props.policyName) fields.push('policy_name');
+  if ((live.scope ?? null) !== (props.scope ?? null)) fields.push('scope');
+  for (const field of SELECTORS) if (!sameSet(live[field], props[field] ?? [])) fields.push(field);
+  if (live.priority !== (props.priority ?? null)) fields.push('priority');
+  return fields;
+};
+
+export const createBody = (
+  props: PolicyAttachmentProps,
+): policies.CreatePolicyAttachmentPoliciesAttachmentsPostRequest => ({
+  policy_name: props.policyName,
+  ...(props.scope === undefined ? {} : { scope: props.scope }),
+  ...(props.teams === undefined ? {} : { teams: [...props.teams] }),
+  ...(props.keys === undefined ? {} : { keys: [...props.keys] }),
+  ...(props.models === undefined ? {} : { models: [...props.models] }),
+  ...(props.tags === undefined ? {} : { tags: [...props.tags] }),
+  ...(props.priority === undefined ? {} : { priority: props.priority }),
+});

package/src/litellm/policy-attachment-operations.ts

@@ -0,0 +1,74 @@
+/**
+ * The three LiteLLM `/policies/attachments*` calls `LiteLLM.PolicyAttachment` uses, through the SDK's
+ * typed operations in `@distilled.cloud/litellm/policy_engine` (LiteLLM 1.103.0):
+ *
+ *   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-attachment-types.ts). The by-id
+ *   `GET` is not used either: the list carries every field and answers absence without a 404.
+ * ★ THE LIST MERGES IN CONFIG-FILE ATTACHMENTS (`definition_location: "config"`, ids `config-<n>`),
+ *   which the API cannot delete. `listAttachments` returns database rows only.
+ * ⚠️ MOST FAILURES ARE A PLAIN 500 (`policy_endpoints.py` wraps everything in `except Exception` and
+ *   answers `HTTPException(500, detail=str(e))`), and the SDK retries 5xx with backoff. The two
+ *   answers that are not: a policy with no production version is a 404, and a concrete team, key or model
+ *   selector that resolves to nothing is a 400 (`PolicyValidator.find_invalid_scope_entries`), so a
+ *   `teams` entry must exist BEFORE its attachment: declare it as `team.teamAlias`. Wildcard patterns
+ *   are let through, and may match nothing today.
+ * ★ DELETE IS 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; otherwise the ORIGINAL error is re-raised.
+ */
+import * as policies from '@distilled.cloud/litellm/policy_engine';
+import * as Effect from 'effect/Effect';
+import { throughFetch } from './operations.ts';
+import { isConfigRow, toAttributes } from './policy-attachment-form.ts';
+import type { PolicyAttachmentAttributes } from './policy-attachment-types.ts';
+import { LitellmRegistryUnreadableError } from './registry-errors.ts';
+import { asRow, bodyOf } from './registry-support.ts';
+
+const RESOURCE = 'LiteLLM.PolicyAttachment';
+
+const unreadable = (reason: string) =>
+  new LitellmRegistryUnreadableError({ reason, resource: RESOURCE });
+
+/** Every DATABASE attachment. Config-file ones are dropped here, once. */
+export const listAttachments = () =>
+  throughFetch(policies.listPolicyAttachmentsPoliciesAttachmentsListGet({})).pipe(
+    Effect.flatMap((response) => {
+      const rows = asRow(bodyOf(response))?.['attachments'];
+      if (rows === undefined) return Effect.succeed<readonly PolicyAttachmentAttributes[]>([]);
+      if (!Array.isArray(rows)) return Effect.fail(unreadable('attachments is not an array'));
+      const parsed = rows.filter((row) => !isConfigRow(row)).map(toAttributes);
+      return parsed.every((each) => each !== undefined)
+        ? Effect.succeed(parsed as readonly PolicyAttachmentAttributes[])
+        : Effect.fail(unreadable('an attachment has no id or policy name'));
+    }),
+  );
+
+/** The created row, which carries the id LiteLLM issued. `undefined` when the answer is not one. */
+export const createAttachment = (
+  body: policies.CreatePolicyAttachmentPoliciesAttachmentsPostRequest,
+) =>
+  throughFetch(policies.createPolicyAttachmentPoliciesAttachmentsPost(body)).pipe(
+    Effect.map((response) => toAttributes(bodyOf(response))),
+  );
+
+export const deleteAttachment = (attachmentId: string) =>
+  throughFetch(
+    policies.deletePolicyAttachmentPoliciesAttachmentsAttachmentIdDelete({
+      attachment_id: attachmentId,
+    }),
+  ).pipe(
+    Effect.asVoid,
+    Effect.catch((original) =>
+      listAttachments().pipe(
+        Effect.catch(() => Effect.fail(original)),
+        Effect.flatMap((rows) =>
+          rows.some((row) => row.attachmentId === attachmentId)
+            ? Effect.fail(original)
+            : Effect.void,
+        ),
+      ),
+    ),
+  );

package/src/litellm/policy-attachment-types.ts

@@ -0,0 +1,48 @@
+/**
+ * What a `LiteLLM.PolicyAttachment` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ AN ATTACHMENT SAYS WHERE A POLICY APPLIES (`LiteLLM_PolicyAttachmentTable`,
+ *   `/policies/attachments`): a request gets the policy when it matches ALL of the attachment's
+ *   selectors (`PolicyMatcher.scope_matches`, `policy_engine/policy_matcher.py`, 1.103.0). Teams, keys
+ *   and models are matched by ALIAS or model name with `*` wildcards (`prefix-*`); a request's team
+ *   alias is `LiteLLM.Team`'s `teamAlias`, not its id.
+ * ⛔ AN ATTACHMENT WITH NO SELECTOR IS GLOBAL. `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. It is
+ *   refused unless `scope: '*'` says so. The other three empty selectors are "any", which is why
+ *   `{ teams: ['x'] }` covers every key and every model of team x.
+ * ⛔ IMMUTABLE: THERE IS NO UPDATE ROUTE (`policy_endpoints.py` has create, get, list and delete only).
+ *   Any change is a REPLACE: the new attachment is created first, then the old one is deleted, so for a
+ *   moment both apply. Guardrails are additive, so overlap can only add enforcement, never drop it.
+ * ★ IDENTITY IS CONTENT. The id is issued by the proxy and there is no name, so a live attachment is
+ *   adopted by matching every field (policy, scope, the four selector sets, priority).
+ * ⚠️ CONFIG-FILE ATTACHMENTS (`config-<n>` ids) are never adopted or deleted: they cannot be removed
+ *   through the API.
+ */
+export interface PolicyAttachmentProps {
+  /** The policy to attach, by name. The proxy refuses a name with no PRODUCTION version (404). */
+  readonly policyName: string;
+  /** `'*'` for a global attachment. Declare this OR a selector; neither is refused (see above). */
+  readonly scope?: '*';
+  /** Team ALIASES or patterns. A set. */
+  readonly teams?: readonly string[];
+  /** Key aliases or patterns. A set. */
+  readonly keys?: readonly string[];
+  /** Model names or patterns. A set. */
+  readonly models?: readonly string[];
+  /** Tag patterns matched against key and team `metadata.tags`. A set. */
+  readonly tags?: readonly string[];
+  /** Explicit execution order, lower first; an attachment with one runs before those without. 32-bit int. */
+  readonly priority?: number;
+}
+
+export interface PolicyAttachmentAttributes {
+  readonly attachmentId: string;
+  readonly policyName: string;
+  readonly scope: string | null;
+  readonly teams: readonly string[];
+  readonly keys: readonly string[];
+  readonly models: readonly string[];
+  readonly tags: readonly string[];
+  readonly priority: number | null;
+}

package/src/litellm/policy-attachment.test.ts

@@ -0,0 +1,198 @@
+/**
+ * `LiteLLM.PolicyAttachment` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-policy-attachment-litellm.ts`): create, no-op, adopt by content, the create-first replace,
+ * removal, and the refusals.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ * ⚠️ WHAT THE FAKE MODELS IS READ FROM THE 1.103.0 SOURCE, NOT MEASURED ON A LIVE PROXY (its header).
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakePolicyAttachmentLitellm,
+  attachmentRow,
+  startFakePolicyAttachmentLitellm,
+} from './fake-policy-attachment-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMPolicyAttachment } from './policy-attachment.ts';
+import { deleteAttachment } from './policy-attachment-operations.ts';
+import type { PolicyAttachmentProps } from './policy-attachment-types.ts';
+
+const stack = (fake: FakePolicyAttachmentLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: PolicyAttachmentProps, name = 'Attach') =>
+  Effect.gen(function* () {
+    yield* LiteLLMPolicyAttachment(name, props);
+  });
+
+const options = { knownTeams: ['fake-team'], policies: ['FAKE-baseline'] };
+const global: PolicyAttachmentProps = { policyName: 'FAKE-baseline', scope: '*' };
+const scoped: PolicyAttachmentProps = {
+  models: ['fake-code', 'fake-flash'],
+  policyName: 'FAKE-baseline',
+  priority: 10,
+  teams: ['fake-team'],
+};
+
+test('creates a global attachment, then a second deploy writes nothing', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  const same = stack(fake);
+  expect(await same.deploy(declare(global))).toEqual({ Attach: 'create' });
+  expect(fake.attachments()[0]).toMatchObject({
+    policy_name: 'FAKE-baseline',
+    scope: '*',
+    teams: [],
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(global))).toEqual({ Attach: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('sends every declared selector and the priority, and only those', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  await stack(fake).deploy(declare(scoped));
+  expect(fake.bodies()[0]).toEqual({
+    models: ['fake-code', 'fake-flash'],
+    policy_name: 'FAKE-baseline',
+    priority: 10,
+    teams: ['fake-team'],
+  });
+});
+
+test('a change is a create-first REPLACE and the old attachment is deleted afterwards', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  const same = stack(fake);
+  await same.deploy(declare(scoped));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare({ ...scoped, models: ['fake-code'] }))).toEqual({
+    Attach: 'replace',
+  });
+  // ★ create first, delete second: for a moment both applied, and none of that window was unattached
+  expect(writesOf(fake.requests().slice(before))).toEqual([
+    'POST /policies/attachments',
+    'DELETE /policies/attachments/FAKE-attachment-0001',
+  ]);
+  expect(fake.attachments()).toHaveLength(1);
+  expect(fake.attachments()[0]).toMatchObject({
+    attachment_id: 'FAKE-attachment-0002',
+    models: ['fake-code'],
+  });
+});
+
+test('removing the declaration DELETES the attachment: it holds no data, and a retained one would keep the scope attached', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  const same = stack(fake);
+  await same.deploy(declare(scoped));
+  await same.deploy(Effect.void);
+  expect(fake.attachments()).toEqual([]);
+});
+
+test('a live attachment is adopted by CONTENT: Unowned without --adopt, adopted with it, and a match writes nothing', async () => {
+  const live = attachmentRow({
+    attachment_id: 'FAKE-live-1',
+    models: ['fake-flash', 'fake-code'],
+    policy_name: 'FAKE-baseline',
+    priority: 10,
+    teams: ['fake-team'],
+  });
+  const fake = startFakePolicyAttachmentLitellm({ ...options, seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(scoped))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(scoped), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('two identical live attachments are refused, never guessed at', async () => {
+  const twin = (id: string) =>
+    attachmentRow({ attachment_id: id, policy_name: 'FAKE-baseline', scope: '*' });
+  const fake = startFakePolicyAttachmentLitellm({
+    ...options,
+    seed: [twin('FAKE-live-a'), twin('FAKE-live-b')],
+  });
+  await expect(stack(fake).deploy(declare(global), { adopt: true })).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a config-file attachment is never adopted: an equal one is ignored and a database one is created', async () => {
+  const fake = startFakePolicyAttachmentLitellm({
+    ...options,
+    configAttachments: [{ policy_name: 'FAKE-baseline', scope: '*' }],
+  });
+  expect(await stack(fake).deploy(declare(global))).toEqual({ Attach: 'create' });
+  expect(fake.attachments()).toHaveLength(1);
+});
+
+test('an attachment with no selector is refused before any request: LiteLLM would make it GLOBAL', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  await expect(stack(fake).deploy(declare({ policyName: 'FAKE-baseline' }))).rejects.toThrow();
+  expect(fake.requests()).toEqual([]);
+});
+
+test('other refused declarations fail the plan before a single request', async () => {
+  for (const props of [
+    { ...scoped, policyName: ' ' },
+    { ...scoped, scope: 'FAKE' as never },
+    { ...scoped, teams: ['fake-team', 'fake-team'] },
+    { ...scoped, models: [''] },
+    { ...scoped, priority: 1.5 },
+    { ...scoped, priority: 2147483648 },
+  ]) {
+    const fake = startFakePolicyAttachmentLitellm(options);
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('a team that does not exist yet fails the create (declare the alias from the Team), a wildcard is let through', async () => {
+  const fake = startFakePolicyAttachmentLitellm(options);
+  await expect(
+    stack(fake).deploy(declare({ ...scoped, teams: ['fake-missing'] })),
+  ).rejects.toThrow();
+  expect(fake.attachments()).toEqual([]);
+  await stack(fake).deploy(declare({ ...scoped, teams: ['fake-*'] }, 'Wild'));
+  expect(fake.attachments()).toHaveLength(1);
+});
+
+test('a policy with no production version fails the create and leaves nothing behind', async () => {
+  const fake = startFakePolicyAttachmentLitellm({ knownTeams: [], policies: [] });
+  await expect(stack(fake).deploy(declare(global))).rejects.toThrow();
+  expect(fake.attachments()).toEqual([]);
+});
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('delete of a missing id is swallowed only because the list says it is gone', async () => {
+  const live = attachmentRow({
+    attachment_id: 'FAKE-live-2',
+    policy_name: 'FAKE-baseline',
+    scope: '*',
+  });
+  const fake = startFakePolicyAttachmentLitellm({ ...options, seed: [live] });
+  await run(fake.fetch, deleteAttachment('FAKE-live-2'));
+  expect(fake.attachments()).toEqual([]);
+  await run(fake.fetch, deleteAttachment('FAKE-live-2'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the row stays', async () => {
+  const live = attachmentRow({
+    attachment_id: 'FAKE-live-3',
+    policy_name: 'FAKE-baseline',
+    scope: '*',
+  });
+  const fake = startFakePolicyAttachmentLitellm({ ...options, forbidDelete: true, seed: [live] });
+  await expect(run(fake.fetch, deleteAttachment('FAKE-live-3'))).rejects.toThrow();
+  expect(fake.attachments()).toHaveLength(1);
+});