@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/policy-attachment.ts

@@ -0,0 +1,178 @@
+/**
+ * `LiteLLM.PolicyAttachment` — one row of LiteLLM's policy attachment table
+ * (`/policies/attachments`): WHERE a policy applies, by team alias, key alias, model and tag. Props,
+ * the global-by-default trap and the config-file exclusion: policy-attachment-types.ts.
+ *
+ * ⛔ IMMUTABLE, SO EVERY CHANGE IS A CREATE-FIRST REPLACE. There is no update route. The engine creates
+ *   the new attachment and then deletes the old, so both apply for a moment; guardrails are additive,
+ *   so that can only add enforcement.
+ * ★ THE REMOVAL POLICY IS THE DEFAULT (`destroy`), DELIBERATELY NOT `retain` (the other registry
+ *   resources retain). Under `retain` a replace would leave the OLD attachment live beside the new one
+ *   for good: a scope the declaration no longer names would keep the policy attached. An attachment
+ *   holds no data, so removing it loses nothing but the scoping the declaration just dropped.
+ * ★ ADOPT BY CONTENT. A live attachment that matches every field, with no state, is `Unowned` and needs
+ *   `--adopt`. Two identical live rows are refused, never guessed at.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: none in `policy_endpoints.py` or `policy_engine/*.py` (1.103.0).
+ *   The guardrail-policies docs page says team/key-based attachment needs Enterprise
+ *   (docs.litellm.ai/docs/proxy/guardrails/guardrail_policies); whether a CE proxy enforces a
+ *   team-scoped attachment is UNVERIFIED.
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { createBody, differing, firstProblem } from './policy-attachment-form.ts';
+import {
+  createAttachment,
+  deleteAttachment,
+  listAttachments,
+} from './policy-attachment-operations.ts';
+import type {
+  PolicyAttachmentAttributes,
+  PolicyAttachmentProps,
+} from './policy-attachment-types.ts';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryAmbiguousError,
+  LitellmRegistryNotConvergedError,
+  LitellmRegistryUnreadableError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+
+export type { PolicyAttachmentAttributes, PolicyAttachmentProps };
+export type { RegistryError as PolicyAttachmentError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.PolicyAttachment';
+
+export interface LiteLLMPolicyAttachment extends Resource<
+  'LiteLLM.PolicyAttachment',
+  PolicyAttachmentProps,
+  PolicyAttachmentAttributes
+> {}
+
+export const LiteLLMPolicyAttachment = Resource<LiteLLMPolicyAttachment>(
+  'LiteLLM.PolicyAttachment',
+);
+
+export const isLiteLLMPolicyAttachment = (value: unknown): value is LiteLLMPolicyAttachment =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.PolicyAttachment';
+
+/**
+ * The live row this declaration means: a RECORDED id is matched by id alone (a row that vanished is
+ * `undefined`); with no state, the rows equal to the declaration decide, and a twin is refused.
+ */
+const locate = (
+  rows: readonly PolicyAttachmentAttributes[],
+  props: PolicyAttachmentProps,
+  output: PolicyAttachmentAttributes | undefined,
+) => {
+  if (output !== undefined) {
+    return Effect.succeed(rows.find((row) => row.attachmentId === output.attachmentId));
+  }
+  const equal = rows.filter((row) => differing(row, props).length === 0);
+  return equal.length > 1
+    ? Effect.fail(
+        new LitellmRegistryAmbiguousError({
+          ids: equal.map((row) => row.attachmentId),
+          name: props.policyName,
+          resource: RESOURCE,
+        }),
+      )
+    : Effect.succeed(equal[0]);
+};
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const policyAttachmentHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({
+    olds,
+    output,
+  }: {
+    olds: PolicyAttachmentProps;
+    output: PolicyAttachmentAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.policyName), firstProblem(olds));
+      }
+      const live = yield* locate(yield* listAttachments(), olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<PolicyAttachmentProps>;
+    output: PolicyAttachmentAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.policyName), firstProblem(news));
+      if (output === undefined) return undefined;
+      // ⛔ no update route: any difference is a new attachment, created before the old one goes
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'replace', deleteFirst: false } as const);
+    }),
+
+  reconcile: ({
+    news,
+    output,
+  }: {
+    news: PolicyAttachmentProps;
+    output: PolicyAttachmentAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.policyName), firstProblem(news));
+      const before = yield* locate(yield* listAttachments(), news, output);
+      // an attachment that already IS the declaration is kept, whether it is ours or being adopted
+      if (before !== undefined && differing(before, news).length === 0) return before;
+
+      const created = yield* createAttachment(createBody(news));
+      if (created === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryUnreadableError({
+            reason: 'the create answered something that is not an attachment',
+            resource: RESOURCE,
+          }),
+        );
+      }
+      const after = (yield* listAttachments()).find(
+        (row) => row.attachmentId === created.attachmentId,
+      );
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.policyName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.policyName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: PolicyAttachmentAttributes }) =>
+    deleteAttachment(output.attachmentId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMPolicyAttachmentProvider = () =>
+  Provider.effect(
+    LiteLLMPolicyAttachment,
+    Effect.succeed(LiteLLMPolicyAttachment.Provider.of(policyAttachmentHandlers)),
+  );

package/src/litellm/policy-form.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire bodies, comparison and refusals for `LiteLLM.Policy`, testable without a server.
+ *
+ * ★ THE EDIT BODY CARRIES ONLY WHAT DIFFERS AND IS NEVER A `null`: `update_policy_in_db` skips every
+ *   field that is `None` (policy-types.ts), so a `null` would be a silent no-op the read back would
+ *   then have to catch.
+ */
+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 { PolicyAttributes, PolicyProps, PolicyVersion } from './policy-types.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Runs before any request. */
+export const firstProblem = (props: PolicyProps): 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';
+  }
+  for (const [field, value] of [
+    ['description', props.description],
+    ['inherit', props.inherit],
+    ['conditionModel', props.conditionModel],
+  ] as const) {
+    if (value !== undefined && isBlank(value)) {
+      return `\`${field}\` is blank; leave it out to keep the live value (a policy field cannot be cleared)`;
+    }
+  }
+  if (props.inherit === props.policyName) return '`inherit` names the policy itself';
+  for (const [field, values] of [
+    ['guardrailsAdd', props.guardrailsAdd ?? []],
+    ['guardrailsRemove', props.guardrailsRemove ?? []],
+  ] as const) {
+    const bad = firstBadEntry(values);
+    if (bad !== undefined)
+      return `\`${field}\` has a blank or padded entry (${JSON.stringify(bad)})`;
+    const twice = firstDuplicate(values);
+    if (twice !== undefined) return `\`${field}\` lists ${JSON.stringify(twice)} twice`;
+  }
+  const both = (props.guardrailsAdd ?? []).find((name) =>
+    (props.guardrailsRemove ?? []).includes(name),
+  );
+  if (both !== undefined) return `guardrail ${JSON.stringify(both)} is both added and removed`;
+  return undefined;
+};
+
+/** One policy version. `undefined` is "not a policy row": the caller refuses the whole answer. */
+export const toVersion = (value: unknown): PolicyVersion | undefined => {
+  const row = asRow(value);
+  if (row === undefined) return undefined;
+  const policyId = row['policy_id'];
+  const policyName = row['policy_name'];
+  if (typeof policyId !== 'string' || typeof policyName !== 'string') return undefined;
+  const condition = asRow(row['condition']);
+  return {
+    conditionModel: stringOrNull(condition?.['model']),
+    description: stringOrNull(row['description']),
+    guardrailsAdd: canonical(stringsOf(row['guardrails_add'])),
+    guardrailsRemove: canonical(stringsOf(row['guardrails_remove'])),
+    inherit: stringOrNull(row['inherit']),
+    policyId,
+    policyName,
+    versionNumber: numberOrNull(row['version_number']) ?? 1,
+    versionStatus: typeof row['version_status'] === 'string' ? row['version_status'] : 'production',
+  };
+};
+
+/** The attributes of a version: without the status, which is never recorded. */
+export const toAttributes = (version: PolicyVersion): PolicyAttributes => {
+  const { versionStatus: _status, ...attributes } = version;
+  return attributes;
+};
+
+/** Wire names of the fields where live and declared disagree. */
+export const differing = (live: PolicyAttributes, props: PolicyProps): readonly string[] => {
+  const fields: string[] = [];
+  if (props.description !== undefined && live.description !== props.description) {
+    fields.push('description');
+  }
+  if (props.inherit !== undefined && live.inherit !== props.inherit) fields.push('inherit');
+  if (!sameSet(live.guardrailsAdd, props.guardrailsAdd ?? [])) fields.push('guardrails_add');
+  if (!sameSet(live.guardrailsRemove, props.guardrailsRemove ?? []))
+    fields.push('guardrails_remove');
+  if (props.conditionModel !== undefined && live.conditionModel !== props.conditionModel) {
+    fields.push('condition');
+  }
+  return fields;
+};
+
+/** Create body (version 1, which LiteLLM makes production): every declared field. */
+export const createBody = (props: PolicyProps): policies.CreatePolicyPoliciesPostRequest => ({
+  guardrails_add: [...(props.guardrailsAdd ?? [])],
+  guardrails_remove: [...(props.guardrailsRemove ?? [])],
+  policy_name: props.policyName,
+  ...(props.description === undefined ? {} : { description: props.description }),
+  ...(props.inherit === undefined ? {} : { inherit: props.inherit }),
+  ...(props.conditionModel === undefined ? {} : { condition: { model: props.conditionModel } }),
+});
+
+/** Draft edit body: only the fields that differ from what the draft was cloned from. */
+export const updateBody = (
+  props: PolicyProps,
+  live: PolicyAttributes,
+): Omit<policies.UpdatePolicyPoliciesPolicyIdPutRequest, 'policy_id'> => {
+  const changed = new Set(differing(live, props));
+  return {
+    ...(changed.has('description') ? { description: props.description ?? null } : {}),
+    ...(changed.has('inherit') ? { inherit: props.inherit ?? null } : {}),
+    ...(changed.has('guardrails_add') ? { guardrails_add: [...(props.guardrailsAdd ?? [])] } : {}),
+    ...(changed.has('guardrails_remove')
+      ? { guardrails_remove: [...(props.guardrailsRemove ?? [])] }
+      : {}),
+    ...(changed.has('condition') ? { condition: { model: props.conditionModel ?? null } } : {}),
+  };
+};

package/src/litellm/policy-operations.ts

@@ -0,0 +1,112 @@
+/**
+ * The seven LiteLLM `/policies*` calls `LiteLLM.Policy` uses, through the SDK's typed operations in
+ * `@distilled.cloud/litellm/policy_engine` (LiteLLM 1.103.0):
+ *
+ *   versions  `listPolicyVersionsPoliciesNamePolicyNameVersionsGet`      GET    /policies/name/{policy_name}/versions
+ *   config    `listPoliciesPoliciesListGet`                              GET    /policies/list?version_status=production
+ *   create    `createPolicyPoliciesPost`                                 POST   /policies
+ *   draft     `createPolicyVersionPoliciesNamePolicyNameVersionsPost`    POST   /policies/name/{policy_name}/versions
+ *   edit      `updatePolicyPoliciesPolicyIdPut`                          PUT    /policies/{policy_id}
+ *   status    `updatePolicyVersionStatusPoliciesPolicyIdStatusPut`       PUT    /policies/{policy_id}/status
+ *   delete    `deleteAllPolicyVersionsPoliciesNamePolicyNameAllVersionsDelete` DELETE /policies/name/{policy_name}/all-versions
+ *
+ * ⛔ THE VERSION LIST IS THE TABLE AND ANSWERS ABSENCE WITH AN EMPTY LIST. `get_versions_by_policy_name`
+ *   is a `find_many` by name (`policy_registry.py`, 1.103.0), so a name with no rows is `versions: []`
+ *   with a 200, never a 404. Nothing here needs the SDK's undeclared `NotFound`.
+ * ⛔ A CONFIG-FILE POLICY IS NOT IN THE TABLE. `/policies/list` merges DB rows with config.yaml
+ *   policies (`definition_location: "config"`), and a production DB policy of the same name OVERRIDES the
+ *   config one at runtime. `configPolicyNames` is how a create refuses to do that by accident.
+ * ⚠️ MOST FAILURES HERE ARE A PLAIN 500. The handlers wrap everything in `except Exception` and answer
+ *   `HTTPException(500, detail=str(e))`, except a duplicate name (400) and a few 404/400 cases matched
+ *   by message text. The SDK retries 5xx with backoff, so a genuine failure is slow to surface; nothing
+ *   here reads the text either way (S21).
+ * ⛔ DELETE REMOVES EVERY VERSION (`delete_many` by name), not just production, and answers 200 whether
+ *   or not any row existed, so it is idempotent as it stands. It is why the resource defaults to `retain`.
+ */
+import * as policies from '@distilled.cloud/litellm/policy_engine';
+import * as Effect from 'effect/Effect';
+import { throughFetch } from './operations.ts';
+import { toVersion } from './policy-form.ts';
+import type { PolicyVersion } from './policy-types.ts';
+import { LitellmRegistryUnreadableError } from './registry-errors.ts';
+import { asRow, bodyOf } from './registry-support.ts';
+
+const RESOURCE = 'LiteLLM.Policy';
+
+const unreadable = (reason: string) =>
+  new LitellmRegistryUnreadableError({ reason, resource: RESOURCE });
+
+/** Every version of one policy name, newest first as LiteLLM orders them. `[]` when there is none. */
+export const listPolicyVersions = (policyName: string) =>
+  throughFetch(
+    policies.listPolicyVersionsPoliciesNamePolicyNameVersionsGet({ policy_name: policyName }),
+  ).pipe(
+    Effect.flatMap((response) => {
+      const versions = asRow(bodyOf(response))?.['versions'];
+      if (versions === undefined) return Effect.succeed<readonly PolicyVersion[]>([]);
+      if (!Array.isArray(versions)) return Effect.fail(unreadable('versions is not an array'));
+      const parsed = versions.map(toVersion);
+      return parsed.every((each) => each !== undefined)
+        ? Effect.succeed(parsed as readonly PolicyVersion[])
+        : Effect.fail(unreadable('a version has no id or name'));
+    }),
+  );
+
+/** The names of the policies defined in config.yaml (their `definition_location` is `config`). */
+export const configPolicyNames = () =>
+  throughFetch(policies.listPoliciesPoliciesListGet({ version_status: 'production' })).pipe(
+    Effect.flatMap((response) => {
+      const rows = asRow(bodyOf(response))?.['policies'];
+      if (!Array.isArray(rows)) return Effect.fail(unreadable('policies is not an array'));
+      return Effect.succeed(
+        rows.flatMap((row) => {
+          const each = asRow(row);
+          return each?.['definition_location'] === 'config' &&
+            typeof each['policy_name'] === 'string'
+            ? [each['policy_name']]
+            : [];
+        }),
+      );
+    }),
+  );
+
+/** Creates version 1 AS PRODUCTION. */
+export const createPolicy = (body: policies.CreatePolicyPoliciesPostRequest) =>
+  throughFetch(policies.createPolicyPoliciesPost(body)).pipe(Effect.asVoid);
+
+/** A new DRAFT cloned from production. Answers the draft, whose id every later call needs. */
+export const createDraft = (policyName: string) =>
+  throughFetch(
+    policies.createPolicyVersionPoliciesNamePolicyNameVersionsPost({ policy_name: policyName }),
+  ).pipe(
+    Effect.flatMap((response) => {
+      const draft = toVersion(bodyOf(response));
+      return draft === undefined
+        ? Effect.fail(unreadable('the new draft is not a policy'))
+        : Effect.succeed(draft);
+    }),
+  );
+
+export const editDraft = (
+  policyId: string,
+  body: Omit<policies.UpdatePolicyPoliciesPolicyIdPutRequest, 'policy_id'>,
+) =>
+  throughFetch(policies.updatePolicyPoliciesPolicyIdPut({ ...body, policy_id: policyId })).pipe(
+    Effect.asVoid,
+  );
+
+/** `draft → published` or `published → production` (which demotes the old production to published). */
+export const setVersionStatus = (policyId: string, status: 'published' | 'production') =>
+  throughFetch(
+    policies.updatePolicyVersionStatusPoliciesPolicyIdStatusPut({
+      policy_id: policyId,
+      version_status: status,
+    }),
+  ).pipe(Effect.asVoid);
+
+export const deleteAllVersions = (policyName: string) =>
+  throughFetch(
+    policies.deleteAllPolicyVersionsPoliciesNamePolicyNameAllVersionsDelete({
+      policy_name: policyName,
+    }),
+  ).pipe(Effect.asVoid);

package/src/litellm/policy-types.ts

@@ -0,0 +1,58 @@
+/**
+ * What a `LiteLLM.Policy` declares (props) and what is remembered about it (attributes).
+ *
+ * ★ A POLICY IS A NAMED SET OF GUARDRAILS (`LiteLLM_PolicyTable`, `/policies`;
+ *   docs.litellm.ai/docs/proxy/guardrails/guardrail_policies): guardrails to add, guardrails to remove
+ *   from an inherited parent, and an optional model condition. WHERE it applies is a
+ *   `LiteLLM.PolicyAttachment`, not a property of the policy.
+ * ⛔ A POLICY IS VERSIONED, AND THIS RESOURCE MANAGES THE PRODUCTION VERSION. LiteLLM keeps every
+ *   version (`draft` → `published` → `production`) and only the production one is enforced. `POST /policies`
+ *   creates version 1 AS PRODUCTION, and `PUT /policies/{id}` edits a DRAFT only (400 otherwise;
+ *   `policy_endpoints.py` and `policy_registry.py`, 1.103.0). So a change is four calls: new draft from
+ *   production, edit the draft, publish it, promote it (which demotes the old production to `published`).
+ *   The old version is kept as history. `policyId` in the attributes is the PRODUCTION version's id and
+ *   changes with every promotion.
+ * ⚠️ NOT MODELLED: `pipeline` (an ordered guardrail pipeline). A new version is cloned from production,
+ *   so an adopted policy's pipeline survives every update, and none is ever sent.
+ * ⚠️ A FIELD CANNOT BE CLEARED THROUGH THE API. `update_policy_in_db` writes only fields that are not
+ *   `None`, so `description`, `inherit` and `conditionModel` are compared only when declared and
+ *   removing one from the declaration leaves the live value. The two guardrail lists can be written as
+ *   `[]`, so they are always compared.
+ */
+export interface PolicyProps {
+  /**
+   * The policy's name, and the way an existing policy is ADOPTED: its production version, found by
+   * name. Identity: a different name is a different policy, so it is a replace (create-first).
+   */
+  readonly policyName: string;
+  /** Compared only when declared. Blank is refused. */
+  readonly description?: string;
+  /** The parent policy's name. Compared only when declared. Refused if it is this policy's own name. */
+  readonly inherit?: string;
+  /** Guardrail names this policy adds, compared as a SET and always compared (default `[]`). */
+  readonly guardrailsAdd?: readonly string[];
+  /** Guardrail names removed from the inherited set, compared as a set, always compared (default `[]`). */
+  readonly guardrailsRemove?: readonly string[];
+  /**
+   * `condition.model`: the model name (exact or regex) the policy applies to. Compared only when
+   * declared. Written as the whole condition (`PolicyConditionRequest` has no other key).
+   */
+  readonly conditionModel?: string;
+}
+
+export interface PolicyAttributes {
+  readonly policyName: string;
+  /** The PRODUCTION version's id. */
+  readonly policyId: string;
+  readonly versionNumber: number;
+  readonly description: string | null;
+  readonly inherit: string | null;
+  readonly guardrailsAdd: readonly string[];
+  readonly guardrailsRemove: readonly string[];
+  readonly conditionModel: string | null;
+}
+
+/** One version of a policy, as the version list returns it. */
+export interface PolicyVersion extends PolicyAttributes {
+  readonly versionStatus: string;
+}

package/src/litellm/policy.test.ts

@@ -0,0 +1,214 @@
+/**
+ * `LiteLLM.Policy` through Alchemy's real Plan and Apply over the fake proxy (`fake-policy-litellm.ts`):
+ * create, no-op, the draft → published → production promotion, adopt, config-file collision, replace.
+ *
+ * ★ 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 { FAKE_KEY } from './fake-registry-base.ts';
+import {
+  type FakePolicyLitellm,
+  policyRow,
+  startFakePolicyLitellm,
+} from './fake-policy-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMPolicy, policyHandlers } from './policy.ts';
+import type { PolicyProps } from './policy-types.ts';
+
+const stack = (fake: FakePolicyLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: PolicyProps, name = 'Baseline') =>
+  Effect.gen(function* () {
+    yield* LiteLLMPolicy(name, props);
+  });
+
+const baseline: PolicyProps = {
+  description: 'FAKE baseline',
+  guardrailsAdd: ['fake-pii', 'fake-injection'],
+  policyName: 'FAKE-baseline',
+};
+
+const statuses = (fake: FakePolicyLitellm) =>
+  fake.versions().map((row) => `${String(row['version_number'])}:${String(row['version_status'])}`);
+
+test('creates version 1 as production after a config-collision check, then a second deploy writes nothing', async () => {
+  const fake = startFakePolicyLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(baseline))).toEqual({ Baseline: 'create' });
+  expect(fake.requests().map((each) => each.path)).toContain(
+    '/policies/list?version_status=production',
+  );
+  expect(fake.versions()).toHaveLength(1);
+  expect(fake.versions()[0]).toMatchObject({
+    description: 'FAKE baseline',
+    guardrails_add: ['fake-pii', 'fake-injection'],
+    guardrails_remove: [],
+    policy_name: 'FAKE-baseline',
+    version_number: 1,
+    version_status: 'production',
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(baseline))).toEqual({ Baseline: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('a change is a NEW version: draft cloned from production, edited, published, promoted; the old one is kept', async () => {
+  const fake = startFakePolicyLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(baseline));
+  const before = fake.requests().length;
+  expect(await same.deploy(declare({ ...baseline, guardrailsAdd: ['fake-pii'] }))).toEqual({
+    Baseline: 'update',
+  });
+  expect(writesOf(fake.requests().slice(before))).toEqual([
+    'POST /policies/name/FAKE-baseline/versions',
+    'PUT /policies/FAKE-policy-0002',
+    'PUT /policies/FAKE-policy-0002/status',
+    'PUT /policies/FAKE-policy-0002/status',
+  ]);
+  expect(fake.bodies().slice(-3)).toEqual([
+    { guardrails_add: ['fake-pii'] },
+    { version_status: 'published' },
+    { version_status: 'production' },
+  ]);
+  // ★ history: version 1 was demoted to published, version 2 is the enforced one
+  expect(statuses(fake)).toEqual(['1:published', '2:production']);
+  expect(await same.deploy(declare({ ...baseline, guardrailsAdd: ['fake-pii'] }))).toEqual({
+    Baseline: 'noop',
+  });
+});
+
+test('an undeclared field is carried by the clone, never sent: the description survives a guardrail change', async () => {
+  const seed = policyRow({
+    description: 'written by a person',
+    guardrails_add: ['fake-pii'],
+    inherit: 'FAKE-parent',
+    policy_id: 'FAKE-live-1',
+    policy_name: 'FAKE-baseline',
+  });
+  const fake = startFakePolicyLitellm({ seed: [seed] });
+  await stack(fake).deploy(
+    declare({ guardrailsAdd: ['fake-pii', 'fake-toxic'], policyName: 'FAKE-baseline' }),
+    {
+      adopt: true,
+    },
+  );
+  const production = fake.versions().find((row) => row['version_status'] === 'production');
+  expect(production).toMatchObject({
+    description: 'written by a person',
+    guardrails_add: ['fake-pii', 'fake-toxic'],
+    inherit: 'FAKE-parent',
+  });
+  // ★ the edit body (third from last, before publish and promote) names only the field that differs
+  expect(fake.bodies().at(-3)).toEqual({ guardrails_add: ['fake-pii', 'fake-toxic'] });
+});
+
+test('a live production policy is Unowned: refused without --adopt, adopted by name with it, and a match writes nothing', async () => {
+  const seed = policyRow({
+    description: 'FAKE baseline',
+    guardrails_add: ['fake-injection', 'fake-pii'],
+    policy_id: 'FAKE-live-2',
+    policy_name: 'FAKE-baseline',
+  });
+  const fake = startFakePolicyLitellm({ seed: [seed] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(baseline))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(baseline), { adopt: true }))).toEqual([
+    'adopted',
+  ]);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a name that belongs to a config.yaml policy is refused, so a DB policy never shadows it by accident', async () => {
+  const fake = startFakePolicyLitellm({ configPolicies: ['FAKE-baseline'] });
+  await expect(stack(fake).deploy(declare(baseline))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('versions with no production one are refused, not guessed at', async () => {
+  const demoted = policyRow({
+    policy_id: 'FAKE-live-3',
+    policy_name: 'FAKE-baseline',
+    version_status: 'published',
+  });
+  const fake = startFakePolicyLitellm({ seed: [demoted] });
+  await expect(stack(fake).deploy(declare(baseline))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('a different policy name is a replace, create-first, and the old policy is retained', async () => {
+  const fake = startFakePolicyLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(baseline));
+  expect(await same.deploy(declare({ ...baseline, policyName: 'FAKE-other' }))).toEqual({
+    Baseline: 'replace',
+  });
+  expect(fake.versions().map((row) => row['policy_name'])).toEqual(['FAKE-baseline', 'FAKE-other']);
+});
+
+test('a proxy that drops an empty-list edit fails the deploy instead of claiming success', async () => {
+  // ⚠️ the fake's own model of a truthiness check on the edit route — unmeasured at 1.103.0
+  const fake = startFakePolicyLitellm({ editIgnoresEmpty: true });
+  const same = stack(fake);
+  await same.deploy(declare(baseline));
+  await expect(same.deploy(declare({ ...baseline, guardrailsAdd: [] }))).rejects.toThrow();
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...baseline, policyName: ' ' },
+    { ...baseline, description: ' ' },
+    { ...baseline, inherit: 'FAKE-baseline' },
+    { ...baseline, guardrailsAdd: ['a', 'a'] },
+    { ...baseline, guardrailsAdd: ['a'], guardrailsRemove: ['a'] },
+    { ...baseline, conditionModel: '' },
+  ]) {
+    const fake = startFakePolicyLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS every version', async () => {
+  const fake = startFakePolicyLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(baseline));
+  await same.deploy(Effect.void);
+  expect(fake.versions()).toHaveLength(1);
+});
+
+test('delete removes EVERY version by name and is idempotent (LiteLLM answers 200 either way)', async () => {
+  const fake = startFakePolicyLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(baseline));
+  await same.deploy(declare({ ...baseline, guardrailsAdd: ['fake-pii'] }));
+  expect(fake.versions()).toHaveLength(2);
+  const run = <A, E>(effect: Effect.Effect<A, E, unknown>) =>
+    Effect.runPromise(
+      effect.pipe(
+        Effect.provide(FetchHttpClient.layer),
+        Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+        Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+      ) as Effect.Effect<A, E, never>,
+    );
+  const output = {
+    conditionModel: null,
+    description: null,
+    guardrailsAdd: [],
+    guardrailsRemove: [],
+    inherit: null,
+    policyId: 'x',
+    policyName: 'FAKE-baseline',
+    versionNumber: 2,
+  };
+  await run(policyHandlers.delete({ output }));
+  expect(fake.versions()).toEqual([]);
+  await run(policyHandlers.delete({ output }));
+});