@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/credential-form.test.ts

@@ -0,0 +1,151 @@
+/**
+ * `credential-form.ts`'s refusals, read shape and comparison — pure: no server, no environment
+ * (the values' own behaviour is credential-values.ts's, tested through the resource test).
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ */
+import { expect, test } from 'bun:test';
+import * as Redacted from 'effect/Redacted';
+import {
+  createBody,
+  differing,
+  firstProblem,
+  isCredentialRow,
+  literalValues,
+  patchBody,
+  removedInfoKeys,
+  toAttributes,
+} from './credential-form.ts';
+import type { CredentialAttributes, CredentialProps } from './credential-types.ts';
+import type { ResolvedValues } from './credential-values.ts';
+
+const VARIABLE = 'FAKE_CREDENTIAL_KEY';
+const base: CredentialProps = {
+  credentialInfo: { note: 'docs search' },
+  credentialName: 'FAKE_api',
+  credentialValues: { api_key: { fromEnv: VARIABLE } },
+};
+
+/** Live attributes as the resource would hold them, over a metadata map. */
+const attributes = (info: Record<string, unknown>, seal = ''): CredentialAttributes => ({
+  credentialInfo: info,
+  credentialName: 'FAKE_api',
+  valuesSeal: seal,
+});
+
+test('firstProblem refuses the combinations nobody meant', () => {
+  const cases: readonly [label: string, props: CredentialProps, fragment: string][] = [
+    ['a blank name', { ...base, credentialName: '  ' }, 'credentialName'],
+    ['a padded name', { ...base, credentialName: ' FAKE_api' }, 'credentialName'],
+    ['a non-object metadata map', { ...base, credentialInfo: null as never }, 'credentialInfo'],
+    [
+      'a sensitive metadata key',
+      { ...base, credentialInfo: { authToken: 'FAKE-meta' } },
+      'authToken',
+    ],
+    ['an empty values map', { ...base, credentialValues: {} }, 'credentialValues'],
+    [
+      'a padded values key',
+      { ...base, credentialValues: { ' key': { fromEnv: VARIABLE } } },
+      'credentialValues',
+    ],
+    [
+      'a literal value',
+      { ...base, credentialValues: { api_key: 'FAKE-literal' as never } },
+      'credentialValues',
+    ],
+    [
+      'a blank variable name',
+      { ...base, credentialValues: { api_key: { fromEnv: ' ' } } },
+      'credentialValues',
+    ],
+  ];
+  for (const [label, props, fragment] of cases) {
+    expect(firstProblem(props), label).toContain(fragment);
+  }
+  expect(firstProblem(base)).toBeUndefined();
+});
+
+test('toAttributes mirrors only the metadata the vendor answers unmasked, and no values at all', () => {
+  const live = toAttributes({
+    credential_info: { note: 'docs search', aws_secret: 'FAKE-clear-in-info' },
+    credential_name: 'FAKE_api',
+    credential_values: { api_key: 'FA****ey', region: 'us-east' },
+  });
+  expect(live).toEqual({
+    credentialInfo: { note: 'docs search' },
+    credentialName: 'FAKE_api',
+    valueKeys: ['api_key', 'region'],
+    infoKeys: ['aws_secret', 'note'],
+    valuesSeal: '',
+  });
+});
+
+test('differing compares per declared key only, deeply, ignoring object key order', () => {
+  // This helper checks declared values; removedInfoKeys separately detects undeclared live keys.
+  expect(differing(attributes({ note: 'docs search', extra: 'live' }), base)).toEqual([]);
+  expect(differing(attributes({ note: 'docs search v2', extra: 'live' }), base)).toEqual([
+    'credential_info.note',
+  ]);
+  expect(differing(attributes({}), base)).toEqual(['credential_info.note']);
+  const nested = { ...base, credentialInfo: { scopes: ['read', 'write'], vendor: { a: 1, b: 2 } } };
+  // object key order never matters; array order does — an array is an ordered list in JSON
+  expect(
+    differing(attributes({ scopes: ['read', 'write'], vendor: { b: 2, a: 1 } }), nested),
+  ).toEqual([]);
+  expect(
+    differing(attributes({ scopes: ['write', 'read'], vendor: { a: 1, b: 2 } }), nested),
+  ).toEqual(['credential_info.scopes']);
+  expect(differing(attributes({ scopes: ['read'], vendor: { a: 1, b: 2 } }), nested)).toEqual([
+    'credential_info.scopes',
+  ]);
+});
+
+test('isCredentialRow accepts only a row with a string name', () => {
+  expect(isCredentialRow({ credential_name: 'FAKE_api' })).toBe(true);
+  expect(isCredentialRow({ credential_values: {} })).toBe(false);
+  expect(isCredentialRow('not a row')).toBe(false);
+  expect(isCredentialRow(null)).toBe(false);
+});
+
+test('createBody carries the name in the body and the values as literals, unwrapped once', () => {
+  const resolved: ResolvedValues = {
+    missing: [],
+    values: { api_key: Redacted.make('FAKE-key-one') },
+  };
+  expect(literalValues(resolved)).toEqual({ api_key: 'FAKE-key-one' });
+  const body = createBody(base, resolved);
+  expect(body).toEqual({
+    credential_info: { note: 'docs search' },
+    credential_name: 'FAKE_api',
+    credential_values: { api_key: 'FAKE-key-one' },
+  });
+  // the body carries the VALUE the proxy stores, never the variable NAME the declaration holds
+  expect(JSON.stringify(body)).not.toContain(VARIABLE);
+});
+
+test('patchBody carries the name twice (path label and body field) and the info, values optional', () => {
+  expect(patchBody(base, undefined)).toEqual({
+    credential_info: { note: 'docs search' },
+    credential_name: 'FAKE_api',
+    credential_name_body: 'FAKE_api',
+  });
+  expect(patchBody(base, { api_key: 'FAKE-key-one' })).toEqual({
+    credential_info: { note: 'docs search' },
+    credential_name: 'FAKE_api',
+    credential_name_body: 'FAKE_api',
+    credential_values: { api_key: 'FAKE-key-one' },
+  });
+  // the body carries the VALUE, never the variable NAME the declaration holds
+  expect(JSON.stringify(patchBody(base, { api_key: 'FAKE-key-one' }))).not.toContain(VARIABLE);
+});
+
+test('removedInfoKeys finds live keys absent from the full intended info map', () => {
+  const prior = attributes({ note: 'docs search', team: 'a' });
+  expect(removedInfoKeys(prior, base)).toEqual(['team']);
+  expect(
+    removedInfoKeys(prior, { ...base, credentialInfo: { note: 'docs search', team: 'a' } }),
+  ).toEqual([]);
+  // No live row means there is nothing to remove.
+  expect(removedInfoKeys(undefined, base)).toEqual([]);
+});

package/src/litellm/credential-form.ts

@@ -0,0 +1,211 @@
+/**
+ * Refusals, wire bodies, the read shape and the comparison for `LiteLLM.Credential`, testable
+ * without a server. Value handling is credential-values.ts's.
+ *
+ * ⛔ WHAT IS COMPARED, WITH THE VENDOR'S MASKING IN MIND. Both reads answer `credential_values`
+ *   with SENSITIVE-keyed values masked (2 + `****` + 2, `*****` for a short string —
+ *   `litellm_logging.py::_get_masked_values`, measured in the live 1.103.0 container) and
+ *   `credential_info` in full:
+ *   - `credential_info` is the complete intended map, including on adoption. Nonempty PATCH
+ *     normally replaces DB info (`credential_endpoints/endpoints.py:314-319`, 1.103.0), while
+ *     memory merges (:385-387). Empty info leaves DB unchanged. Dropping a live info key therefore
+ *     requires a rewrite to converge both stores (`removedInfoKeys`). Every PATCH sends full info.
+ *   - the values are compared only through the seal of the values this process RESOLVED
+ *     (`valuesSeal`, credential-values.ts) — never against the masked fragments, which are
+ *     partial secrets and are never copied into state.
+ * ★ A CHANGED ROW IS PATCHED, NOT REWRITTEN. The vendor's PATCH merges VALUES by key
+ *   (`update_db_credential`:312), so updating a value or an `info` entry is a PATCH carrying the
+ *   declared `credential_info` and (only when the values are stale) the resolved
+ *   `credential_values`. A PATCH that fails on the wire leaves the row it was merging into — the
+ *   fix for the review's finding 3, where a DELETE + POST rewrite left NO row when the POST failed
+ *   after the DELETE. PATCH cannot REMOVE a value key or an in-memory info key, so dropping either
+ *   is still a whole-row rewrite (credential.ts decides). Names from the read prove removal. The
+ *   PATCH body carries `credential_name` IN THE BODY as a second member (`credential_name_body`,
+ *   wire-named `credential_name`) because the vendor's `UpdateCredentialItem` requires it and a
+ *   Smithy member has one binding — the path label can't also be the body field; the distilled
+ *   patch for it is `patches/credential_management/update_credential_credentials__credential_name__patch.json`.
+ */
+import type * as credentials from '@distilled.cloud/litellm/credential_management';
+import * as Redacted from 'effect/Redacted';
+import {
+  type CredentialAttributes,
+  type CredentialProps,
+  isBlank,
+  isSensitiveKey,
+} from './credential-types.ts';
+import type { ResolvedValues } from './credential-values.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Pure: no environment, no server. */
+export const firstProblem = (props: CredentialProps): string | undefined => {
+  if (isBlank(props.credentialName) || props.credentialName !== props.credentialName.trim()) {
+    return '`credentialName` must be a non-empty string without leading or trailing whitespace';
+  }
+  if (
+    props.credentialInfo !== undefined &&
+    (typeof props.credentialInfo !== 'object' || props.credentialInfo === null)
+  ) {
+    return '`credentialInfo` must be an object of metadata';
+  }
+  if (props.credentialInfo !== undefined) {
+    for (const key of Object.keys(props.credentialInfo)) {
+      if (isSensitiveKey(key)) {
+        return (
+          `\`credentialInfo\` must not declare "${key}": LiteLLM returns \`credential_info\` ` +
+          'unmasked, so declare it in `credentialValues`, which LiteLLM stores encrypted'
+        );
+      }
+    }
+  }
+  if (Object.keys(props.credentialValues).length === 0) {
+    return (
+      '`credentialValues` needs at least one entry: LiteLLM refuses a credential with neither ' +
+      '`credential_values` nor a model_id, and `model_id` is not modelled here'
+    );
+  }
+  for (const key of Object.keys(props.credentialValues)) {
+    if (isBlank(key) || key !== key.trim()) {
+      return '`credentialValues` keys must be non-empty strings without padding';
+    }
+    const entry = props.credentialValues[key];
+    if (typeof entry !== 'object' || entry === null || isBlank(entry.fromEnv)) {
+      return `\`credentialValues["${key}"]\` takes \`{ fromEnv: 'NAME' }\`, never a value: the value would land in Alchemy's unencrypted state`;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Wire names of the fields where the live row and the declaration disagree, for a
+ * `NotConvergedError` and for the drift decision. The NAME is identity — a changed name plans a
+ * REPLACE in credential.ts and is never compared here. Values are never compared against the
+ * live row at all: the seal decides (credential-values.ts).
+ */
+export const differing = (
+  live: CredentialAttributes,
+  props: CredentialProps,
+): readonly string[] => {
+  const out: string[] = [];
+  if (props.credentialInfo !== undefined) {
+    for (const [key, declared] of Object.entries(props.credentialInfo)) {
+      if (!isSensitiveKey(key) && !jsonEquals(live.credentialInfo[key], declared)) {
+        out.push(`credential_info.${key}`);
+      }
+    }
+  }
+  return out;
+};
+
+/** Canonical-JSON deep equality, order-insensitive for objects. */
+const jsonEquals = (left: unknown, right: unknown): boolean =>
+  JSON.stringify(canonicalise(left)) === JSON.stringify(canonicalise(right));
+
+const canonicalise = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(canonicalise);
+  if (typeof value === 'object' && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = canonicalise((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+};
+
+/**
+ * One row of a credentials read, as attributes. ⛔ COPIES NO `credential_values` ENTRY: a masked
+ * fragment (`sk****45`) is a partial secret, and a sensitive key the read masks would land half a
+ * secret in Alchemy's state. The `credential_info` mirror drops SENSITIVE-KEYED entries (they are
+ * returned unmasked and would mirror a clear secret into state). The digest is the caller's
+ * (credential.ts fills `valuesSeal` from state; a row cannot supply one).
+ */
+export const toAttributes = (row: Record<string, unknown>): CredentialAttributes => {
+  const info = (row['credential_info'] ?? {}) as Record<string, unknown>;
+  const mirrored: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(info)) {
+    if (!isSensitiveKey(key)) mirrored[key] = value;
+  }
+  return {
+    credentialInfo: mirrored,
+    credentialName: String(row['credential_name'] ?? ''),
+    valueKeys: Object.keys((row['credential_values'] ?? {}) as Record<string, unknown>).sort(),
+    infoKeys: Object.keys(info).sort(),
+    valuesSeal: '',
+  };
+};
+
+/** The rows a credentials read carries, `CredentialItem`-shaped. */
+export const isCredentialRow = (row: unknown): row is Record<string, unknown> =>
+  typeof row === 'object' &&
+  row !== null &&
+  typeof (row as Record<string, unknown>)['credential_name'] === 'string';
+
+/**
+ * The literal values a create or a values-stale PATCH sends, unwrapped from their `Redacted`
+ * exactly once. ⛔ EVERY DECLARED ENTRY IS SENT: the whole-row create and the values-stale PATCH
+ * both demand every declared value (`requireValues`), so there is no partial send that could
+ * leave a stale value behind under a declared key.
+ */
+export const literalValues = (resolved: ResolvedValues): Readonly<Record<string, unknown>> =>
+  Object.fromEntries(
+    Object.entries(resolved.values).map(([key, value]) => [key, Redacted.value(value)]),
+  );
+
+/** The body `POST /credentials` carries — the name IN THE BODY (measured with a stub fetch). */
+export const createBody = (
+  props: CredentialProps,
+  resolved: ResolvedValues,
+): credentials.CreateCredentialCredentialsPostRequest => {
+  const body: Record<string, unknown> = {
+    credential_info: { ...props.credentialInfo },
+    credential_name: props.credentialName,
+    credential_values: { ...literalValues(resolved) },
+  };
+  return body as unknown as credentials.CreateCredentialCredentialsPostRequest;
+};
+
+/**
+ * The body `PATCH /credentials/{name}` carries — the declared `credential_info` always (the
+ * vendor's `UpdateCredentialItem` REQUIRES it, and the DB normally replaces the info map), the
+ * resolved `credential_values` only when the caller passes them (a values-stale write; an
+ * info-only drift sends none, so it never demands a value the environment does not hold).
+ *
+ * ⛔ `credential_name` APPEARS TWICE, ON PURPOSE: `credential_name` is the path label (its URI
+ *   placeholder is the row's address), and `credential_name_body` is the SAME value as a body
+ *   field wire-named `credential_name` — the vendor's `UpdateCredentialItem` requires the name in
+ *   the body, a Smithy member can carry only ONE binding, and the kit never renames in place (a
+ *   changed name is a REPLACE, credential.ts), so the two are always equal here.
+ */
+export const patchBody = (
+  props: CredentialProps,
+  values: Readonly<Record<string, unknown>> | undefined,
+): credentials.UpdateCredentialCredentialsCredentialNamePatchRequest => {
+  const body: Record<string, unknown> = {
+    credential_info: { ...props.credentialInfo },
+    credential_name: props.credentialName,
+    credential_name_body: props.credentialName,
+  };
+  if (values !== undefined) body.credential_values = { ...values };
+  return body as unknown as credentials.UpdateCredentialCredentialsCredentialNamePatchRequest;
+};
+
+/**
+ * All live info keys absent from the intended map, including on adoption. DB replacement alone
+ * cannot clear memory, so these require a rewrite. Only names of sensitive info are remembered.
+ */
+export const removedInfoKeys = (
+  prior: CredentialAttributes | undefined,
+  props: CredentialProps,
+): readonly string[] => {
+  if (prior === undefined) return [];
+  const declared = props.credentialInfo ?? {};
+  return (prior.infoKeys ?? Object.keys(prior.credentialInfo)).filter(
+    (key) => !Object.hasOwn(declared, key),
+  );
+};
+
+/** Values merge in BOTH stores, so dropped names from the masked read require a rewrite. */
+export const removedValueKeys = (
+  live: CredentialAttributes | undefined,
+  props: CredentialProps,
+): readonly string[] =>
+  (live?.valueKeys ?? []).filter((key) => !Object.hasOwn(props.credentialValues, key));

package/src/litellm/credential-guards.test.ts

@@ -0,0 +1,241 @@
+/**
+ * The guards `LiteLLM.Credential` adds on top of the typed SDK calls, tested at the handler level
+ * (a value is in the request body of `POST /credentials`, so a create that dies on the wire, or one
+ * made while the SDK's debug printing is on, would put it where nobody should see it) and through
+ * Alchemy's real Plan and Apply (a rename onto a row another owner holds must be refused, not
+ * overwritten).
+ *
+ * ★ EVERY VALUE IS `FAKE-*`, and a test that asserts a value is absent needs a value it can search
+ *   for: `FAKE-key-one` is the credential value the declaration resolves from `process.env`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import { Retry } from '@distilled.cloud/litellm/Retry';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { credentialHandlers } from './credential.ts';
+import type { CredentialProps } from './credential-types.ts';
+import { resolveValues, sealValues } from './credential-values.ts';
+import { credentialRow, startFakeCredentialLitellm } from './fake-credential-litellm.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMCredential } from './credential.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_CREDENTIAL_GUARD_KEY';
+const VALUE = 'FAKE-key-one';
+
+const props: CredentialProps = {
+  credentialInfo: { note: 'docs search' },
+  credentialName: 'FAKE_api',
+  credentialValues: { api_key: { fromEnv: VARIABLE } },
+};
+
+beforeEach(() => {
+  process.env[VARIABLE] = VALUE;
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+  delete process.env.DISTILLED_DEBUG_HTTP;
+});
+
+type Fake = ReturnType<typeof startFakeCredentialLitellm>;
+
+/** One reconcile effect at the handler level, against the fake, with the SDK's retry OFF. */
+const reconcileEffect = (
+  fake: Fake,
+  news: CredentialProps,
+  output: Parameters<typeof credentialHandlers.reconcile>[0]['output'] = undefined,
+) =>
+  credentialHandlers
+    .reconcile({ fqn: 'Cred', instanceId: 'i-1', news, output })
+    .pipe(
+      Effect.provideService(Retry, { while: () => false }),
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+      Effect.provide(credentials({ apiKey: KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<unknown, unknown, never>;
+
+/** Runs the reconcile to a value, or the failure it raised. */
+const runReconcile = (fake: Fake, news: CredentialProps): Promise<unknown> =>
+  Effect.runPromise(Effect.flip(reconcileEffect(fake, news)));
+
+/** A fake whose `POST /credentials` drops the connection before any answer. */
+const droppedCreate = (fake: Fake): Fake => ({
+  ...fake,
+  fetch: (async (input: string | URL | Request, init?: RequestInit) => {
+    const request = input instanceof Request ? input : new Request(String(input), init);
+    if (new URL(request.url).pathname === '/credentials' && request.method === 'POST') {
+      throw new TypeError('fetch failed');
+    }
+    return fake.fetch(input, init);
+  }) as typeof globalThis.fetch,
+});
+
+/** A fake whose `PATCH /credentials/{name}` drops the connection before any answer. */
+const droppedPatch = (fake: Fake): Fake => ({
+  ...fake,
+  fetch: (async (input: string | URL | Request, init?: RequestInit) => {
+    const request = input instanceof Request ? input : new Request(String(input), init);
+    if (request.method === 'PATCH' && new URL(request.url).pathname.startsWith('/credentials/')) {
+      const body = (await request.json()) as Record<string, unknown>;
+      expect(Object.keys((body.credential_values ?? {}) as object)).toEqual(['api_key']);
+      throw new TypeError('fetch failed');
+    }
+    return fake.fetch(input, init);
+  }) as typeof globalThis.fetch,
+});
+
+/** What Effect's JSON logger prints for the value. */
+const jsonLogged = async (value: unknown): Promise<string> => {
+  const lines: string[] = [];
+  const capture = Logger.make((options) => void lines.push(Logger.formatJson.log(options)));
+  await Effect.runPromise(
+    Effect.logError('create failed', value).pipe(Effect.provide(Logger.layer([capture]))),
+  );
+  return lines.join('\n');
+};
+
+/** Every reading of `value` a caller could take: serialise, inspect, print, log. */
+const everyReadingOf = async (value: unknown): Promise<string> => {
+  const readings = [Bun.inspect(value, { depth: 12 }), String(value), await jsonLogged(value)];
+  try {
+    readings.push(JSON.stringify(value));
+  } catch {
+    /* a value JSON cannot serialise leaks nothing that way */
+  }
+  if (typeof value === 'object' && value !== null && 'message' in value) {
+    readings.push(String(value.message), 'stack' in value ? String(value.stack) : '');
+  }
+  return readings.join('\n');
+};
+
+describe('a rename onto a row another owner holds', () => {
+  test('is refused at apply, the foreign row untouched, nothing written', async () => {
+    const fake = startFakeCredentialLitellm({
+      masterKey: KEY,
+      seed: [
+        credentialRow({
+          credential_info: { note: 'another owner' },
+          credential_name: 'FAKE_api2',
+          credential_values: { api_key: 'FAKE-elsewhere' },
+        }),
+      ],
+    });
+    const engine = fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+    const declare = (p: CredentialProps) =>
+      Effect.gen(function* () {
+        yield* LiteLLMCredential('Cred', p);
+      });
+    // Own `FAKE_api` first, then rename onto the seeded `FAKE_api2`.
+    await engine.deploy(declare(props));
+    const before = fake.requests().length;
+    await expect(engine.deploy(declare({ ...props, credentialName: 'FAKE_api2' }))).rejects.toThrow(
+      /already exists/,
+    );
+    expect(writesOf(fake.requests().slice(before))).toEqual([]);
+    expect(fake.rows().find((row) => row['credential_name'] === 'FAKE_api2')).toMatchObject({
+      credential_info: { note: 'another owner' },
+      credential_values: { api_key: 'FAKE-elsewhere' },
+    });
+  });
+
+  test('is refused even under --adopt (a replace is never probed for adoption)', async () => {
+    const fake = startFakeCredentialLitellm({
+      masterKey: KEY,
+      seed: [credentialRow({ credential_name: 'FAKE_api2', credential_values: { api_key: 'x' } })],
+    });
+    const engine = fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+    const declare = (p: CredentialProps) =>
+      Effect.gen(function* () {
+        yield* LiteLLMCredential('Cred', p);
+      });
+    await engine.deploy(declare(props));
+    const before = fake.requests().length;
+    await expect(
+      engine.deploy(declare({ ...props, credentialName: 'FAKE_api2' }), { adopt: true }),
+    ).rejects.toThrow(/--adopt does not cover/);
+    expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  });
+});
+
+describe('a create that dies on the wire', () => {
+  test('fails typed, names the credential, and holds no request and no value', async () => {
+    const fake = droppedCreate(startFakeCredentialLitellm({ masterKey: KEY }));
+    const error = await runReconcile(fake, props);
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialTransportError',
+      credentialName: 'FAKE_api',
+      reason: 'TransportError',
+    });
+    expect(Object.keys(error as object)).not.toContain('request');
+    expect(Object.keys(error as object)).not.toContain('cause');
+    expect(await everyReadingOf(error)).not.toContain(VALUE);
+  });
+});
+
+describe('an update that dies on the wire', () => {
+  test('leaves the row in place, fails typed, holds no value', async () => {
+    // The owned row has a stale seal: this failing PATCH MUST carry credential values.
+    const fake = droppedPatch(
+      startFakeCredentialLitellm({
+        masterKey: KEY,
+        seed: [
+          credentialRow({
+            credential_info: { note: 'docs search' },
+            credential_name: 'FAKE_api',
+            credential_values: { api_key: VALUE },
+          }),
+        ],
+      }),
+    );
+    const sealed = sealValues(resolveValues(props).values);
+    process.env[VARIABLE] = 'FAKE-key-rotated';
+    const error = await Effect.runPromise(
+      Effect.flip(
+        reconcileEffect(fake, props, {
+          credentialInfo: { note: 'docs search' },
+          credentialName: 'FAKE_api',
+          valuesSeal: sealed,
+        }),
+      ),
+    );
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialTransportError',
+      credentialName: 'FAKE_api',
+      reason: 'TransportError',
+    });
+    expect(Object.keys(error as object)).not.toContain('request');
+    expect(await everyReadingOf(error)).not.toContain('FAKE-key-rotated');
+    // ★ finding 3: a PATCH that dies leaves the row it was merging into — the old DELETE + POST
+    //   rewrite left NO row when the POST failed after the DELETE.
+    expect(fake.rows()).toHaveLength(1);
+    expect(fake.rows()[0]?.['credential_info']).toEqual({ note: 'docs search' });
+    expect(fake.rows()[0]?.['credential_values']).toEqual({ api_key: VALUE });
+  });
+});
+
+describe('a create while the SDK prints bodies', () => {
+  test('is refused before any request, naming the credential', async () => {
+    process.env.DISTILLED_DEBUG_HTTP = '1';
+    const fake = startFakeCredentialLitellm({ masterKey: KEY });
+    const error = await runReconcile(fake, props);
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialDebugLoggingError',
+      credentialName: 'FAKE_api',
+    });
+    // Refuse at the top of reconcile: even a read can expose unmasked non-sensitive values.
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+});
+
+describe('an absent credential is caught as absence, never a failure', () => {
+  test('reconcile of a create with no live row converges (the read 404 is CredentialNotFound)', async () => {
+    const fake = startFakeCredentialLitellm({ masterKey: KEY });
+    const result = await Effect.runPromise(reconcileEffect(fake, props));
+    expect(result).toMatchObject({ credentialName: 'FAKE_api' });
+    expect(writesOf(fake.requests())).toEqual(['POST /credentials']);
+  });
+});