@homeflare/alchemy 0.28.0 → 0.29.1

package/src/litellm/pass-through-endpoint-delete-swallow.test.ts

@@ -13,15 +13,16 @@
  *   "already gone" only if the row is actually absent.
  */
 import { describe, 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, startFakeLitellm } from './fake-litellm.ts';
 import {
   type LitellmRequirements,
   deletePassThroughEndpoint,
   listPassThroughEndpoints,
-} from './client.ts';
-import { litellmCredentialsLayerFor } from './credentials.ts';
-import { startFakeLitellm } from './fake-litellm.ts';
+} from './operations.ts';
 
 const MASTER_KEY = 'sk-test-master';
 const PROPS = {
@@ -32,35 +33,31 @@ const PROPS = {
   target: 'https://api.bria.ai',
 };
 
-const run = <A, E>(baseUrl: string, effect: Effect.Effect<A, E, LitellmRequirements>): Promise<A> =>
+const run = <A, E>(
+  fetchFn: typeof globalThis.fetch,
+  effect: Effect.Effect<A, E, LitellmRequirements>,
+): Promise<A> =>
   Effect.runPromise(
     effect.pipe(
       Effect.provide(FetchHttpClient.layer),
-      Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl })),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
     ) as Effect.Effect<A, E, never>,
   );
 
 describe('a delete forbidden for a reason other than "already gone"', () => {
   test('is not swallowed: it fails, and the row is still live', async () => {
     const fake = startFakeLitellm({ forbidDelete: true, masterKey: MASTER_KEY, seed: [PROPS] });
-    try {
-      const result = run(fake.url, deletePassThroughEndpoint('live-1'));
-      await expect(result).rejects.toThrow();
-      const rows = await run(fake.url, listPassThroughEndpoints());
-      expect(rows.some((r) => r.id === 'live-1')).toBe(true);
-    } finally {
-      fake.stop();
-    }
+    const result = run(fake.fetch, deletePassThroughEndpoint('live-1'));
+    await expect(result).rejects.toThrow();
+    const rows = await run(fake.fetch, listPassThroughEndpoints());
+    expect(rows.some((r) => r.id === 'live-1')).toBe(true);
   });
 
   test('a genuinely-gone id still succeeds with no error (idempotent delete preserved)', async () => {
     const fake = startFakeLitellm({ forbidDelete: true, masterKey: MASTER_KEY });
-    try {
-      await expect(
-        run(fake.url, deletePassThroughEndpoint('never-existed')),
-      ).resolves.toBeUndefined();
-    } finally {
-      fake.stop();
-    }
+    await expect(
+      run(fake.fetch, deletePassThroughEndpoint('never-existed')),
+    ).resolves.toBeUndefined();
   });
 });

package/src/litellm/pass-through-endpoint-replace.test.ts

@@ -15,11 +15,11 @@
  *   caught this: it calls `h.reconcile` directly with the SAME instanceId and the OLD output, a
  *   call shape the real engine never produces for a `replace`.
  */
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { beforeEach, describe, expect, test } from 'bun:test';
 import * as RemovalPolicy from 'alchemy/RemovalPolicy';
 import * as Effect from 'effect/Effect';
+import { FAKE_BASE, type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
 import { type FakeStack, fakeStack, writesOf } from './fake-stack.ts';
-import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
 import { LiteLLMPassThroughEndpoint } from './pass-through-endpoint.ts';
 import type { PassThroughEndpointProps } from './pass-through-form.ts';
 
@@ -29,9 +29,8 @@ let fake: FakeLitellm;
 let stack: FakeStack;
 beforeEach(() => {
   fake = startFakeLitellm({ masterKey: MASTER_KEY });
-  stack = fakeStack({ apiKey: MASTER_KEY, baseUrl: fake.url });
+  stack = fakeStack({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE }, fake.fetch);
 });
-afterEach(() => fake.stop());
 
 /** ★ `RemovalPolicy.destroy()`, deliberately: under the (non-default) `retain`, `deleteFirst`'s own
  *   old-generation delete is skipped by the engine (Apply.ts's `deleteOldGenerations`), so a path

package/src/litellm/pass-through-endpoint.test.ts

@@ -2,15 +2,16 @@
  * `LiteLLM.PassThroughEndpoint`'s lifecycle handlers, called directly against `fake-litellm.ts` —
  * the loopback-fake pattern this kit uses in place of `alchemy/Test/*` (H12, no live writes).
  */
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { Stack } from 'alchemy/Stack';
 import { Stage } from 'alchemy/Stage';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import { litellmCredentialsLayerFor } from './credentials.ts';
-import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
-import { createPassThroughEndpoint } from './client.ts';
+import { FAKE_BASE, type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
+import { createPassThroughEndpoint } from './operations.ts';
 import {
   LitellmConfigPathConflictError,
   LitellmLiteralSecretHeaderError,
@@ -22,11 +23,11 @@ const MASTER_KEY = 'sk-test-master';
 const INSTANCE_ID = 'a'.repeat(32);
 const FAKE_STACK = { actions: {}, bindings: {}, name: 's', resources: {}, stage: 'test' } as never;
 
+/** No `.stop()` any more — `fake.fetch` is a plain function, no real socket to close. */
 let fake: FakeLitellm;
 beforeEach(() => {
   fake = startFakeLitellm({ masterKey: MASTER_KEY });
 });
-afterEach(() => fake.stop());
 
 const run = <A, E>(effect: Effect.Effect<A, E, never>): Promise<A> =>
   Effect.runPromise(effect as Effect.Effect<A, E, never>);
@@ -34,7 +35,8 @@ const run = <A, E>(effect: Effect.Effect<A, E, never>): Promise<A> =>
 const withServices = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   effect.pipe(
     Effect.provide(FetchHttpClient.layer),
-    Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl: fake.url })),
+    Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+    Effect.provide(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
     Effect.provideService(Stage, 'test'),
     Effect.provideService(Stack, FAKE_STACK),
   ) as Effect.Effect<A, E, never>;
@@ -150,7 +152,6 @@ describe('two endpoints created in one deploy', () => {
 
 describe('a path held by an is_from_config row', () => {
   test('is refused at read, before any write', async () => {
-    fake.stop();
     fake = startFakeLitellm({
       masterKey: MASTER_KEY,
       seed: [{ ...PROPS, id: 'cfg-1', is_from_config: true }],
@@ -167,7 +168,6 @@ describe('a path held by an is_from_config row', () => {
 
 describe('a foreign DB row on the same path', () => {
   test('is Unowned, and read works with output undefined', async () => {
-    fake.stop();
     fake = startFakeLitellm({
       masterKey: MASTER_KEY,
       seed: [{ ...PROPS, id: 'foreign-1', is_from_config: false }],

package/src/litellm/pass-through-endpoint.ts

@@ -18,7 +18,8 @@
  *   ADDRESSED by the id-keyed update/delete calls this provider uses, so it is refused rather than
  *   silently adopted into an id-based lifecycle it cannot actually manage — see docs/litellm.md.
  * ⛔ NO CREDENTIAL IS A PROP (S25). `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` are read at call
- *   time by credentials.ts.
+ *   time by `@distilled.cloud/litellm`'s own `CredentialsFromEnv` (providers.ts) — the same two
+ *   variable names the retired hand-rolled `credentials.ts` read.
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
@@ -28,18 +29,21 @@ import { createPhysicalName } from 'alchemy/PhysicalName';
 import * as Provider from 'alchemy/Provider';
 import type { Stack } from 'alchemy/Stack';
 import type { Stage } from 'alchemy/Stage';
-import * as Data from 'effect/Data';
+import type * as misc from '@distilled.cloud/litellm/misc';
 import * as Effect from 'effect/Effect';
 import * as Predicate from 'effect/Predicate';
 import {
-  type LitellmError,
   type LitellmRequirements,
   createPassThroughEndpoint,
   deletePassThroughEndpoint,
   listPassThroughEndpoints,
   updatePassThroughEndpoint,
-} from './client.ts';
-import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+} from './operations.ts';
+import {
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  LitellmUnaddressableRowError,
+} from './pass-through-errors.ts';
 import {
   type PassThroughEndpointAttributes,
   type PassThroughEndpointProps,
@@ -51,26 +55,12 @@ import {
 } from './pass-through-form.ts';
 
 export type { PassThroughEndpointAttributes, PassThroughEndpointProps };
-
-export class LitellmConfigPathConflictError extends Data.TaggedError(
-  'LitellmConfigPathConflictError',
-)<{
-  readonly path: string;
-}> {}
-export class LitellmUnaddressableRowError extends Data.TaggedError('LitellmUnaddressableRowError')<{
-  readonly path: string;
-}> {}
-export class LitellmLiteralSecretHeaderError extends Data.TaggedError(
-  'LitellmLiteralSecretHeaderError',
-)<{
-  readonly headers: readonly string[];
-}> {}
-
-export type PassThroughEndpointError =
-  | LitellmError
-  | LitellmConfigPathConflictError
-  | LitellmUnaddressableRowError
-  | LitellmLiteralSecretHeaderError;
+export {
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  LitellmUnaddressableRowError,
+  type PassThroughEndpointError,
+} from './pass-through-errors.ts';
 
 export interface LiteLLMPassThroughEndpoint extends Resource<
   'LiteLLM.PassThroughEndpoint',
@@ -88,7 +78,7 @@ export const isLiteLLMPassThroughEndpoint = (value: unknown): value is LiteLLMPa
   Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.PassThroughEndpoint';
 
 const toAttributes = (
-  row: PassThroughGenericEndpoint,
+  row: misc.PassThroughGenericEndpoint,
   fallbackId: string,
 ): PassThroughEndpointAttributes => ({
   ...row,
@@ -104,12 +94,12 @@ const physicalIdOf = (logicalId: string, instanceId: string) =>
  * file header — or a genuine foreign DB row to hand back `Unowned`).
  */
 const locate = (
-  rows: readonly PassThroughGenericEndpoint[],
+  rows: readonly misc.PassThroughGenericEndpoint[],
   objectId: string,
   path: string,
 ): {
-  readonly mine: PassThroughGenericEndpoint | undefined;
-  readonly conflict: PassThroughGenericEndpoint | undefined;
+  readonly mine: misc.PassThroughGenericEndpoint | undefined;
+  readonly conflict: misc.PassThroughGenericEndpoint | undefined;
 } => {
   const mine = rows.find((row) => row.id === objectId);
   const conflict = mine === undefined ? rows.find((row) => row.path === path) : undefined;
@@ -117,13 +107,13 @@ const locate = (
 };
 
 /** The typed refusal for a `path` conflict that cannot ever be adopted (config row, or no id). */
-const conflictRefusal = (conflict: PassThroughGenericEndpoint, path: string) =>
+const conflictRefusal = (conflict: misc.PassThroughGenericEndpoint, path: string) =>
   conflict.is_from_config === true
     ? new LitellmConfigPathConflictError({ path })
     : new LitellmUnaddressableRowError({ path });
 
 /** `read`'s answer for a path conflict: `Unowned` when it is a real, addressable DB row — a typed refusal otherwise. */
-const readConflict = (conflict: PassThroughGenericEndpoint, path: string) =>
+const readConflict = (conflict: misc.PassThroughGenericEndpoint, path: string) =>
   conflict.is_from_config !== true && conflict.id !== undefined && conflict.id !== null
     ? Effect.succeed(Unowned(toAttributes(conflict, conflict.id)))
     : Effect.fail(conflictRefusal(conflict, path));

package/src/litellm/pass-through-errors.ts

@@ -0,0 +1,37 @@
+/**
+ * The typed refusals `LiteLLM.PassThroughEndpoint` raises on top of `@distilled.cloud/litellm`'s
+ * own SDK errors — split out of pass-through-endpoint.ts to keep that file under the house's
+ * 250-line cap once this migration added the four named SDK error-union re-exports.
+ */
+import type * as misc from '@distilled.cloud/litellm/misc';
+import * as Data from 'effect/Data';
+
+export class LitellmConfigPathConflictError extends Data.TaggedError(
+  'LitellmConfigPathConflictError',
+)<{
+  readonly path: string;
+}> {}
+export class LitellmUnaddressableRowError extends Data.TaggedError('LitellmUnaddressableRowError')<{
+  readonly path: string;
+}> {}
+export class LitellmLiteralSecretHeaderError extends Data.TaggedError(
+  'LitellmLiteralSecretHeaderError',
+)<{
+  readonly headers: readonly string[];
+}> {}
+
+/**
+ * ⛔ THE FOUR SDK ERROR UNIONS, NAMED, NOT `LitellmOpError` ALONE. `catchTag`'s tag-literal
+ *   inference needs a concrete union to resolve `"BadRequest"`/`"NotFound"` against (the same
+ *   reason `netbox/resource.ts` leaves `NotFound` folding to each resource file, not its shared
+ *   engine) — `operations.ts` already returns each call's own precise per-operation error type, so
+ *   this is just their union, not a re-widening.
+ */
+export type PassThroughEndpointError =
+  | misc.GetPassThroughEndpointsConfigPassThroughEndpointGetError
+  | misc.CreatePassThroughEndpointsConfigPassThroughEndpointPostError
+  | misc.UpdatePassThroughEndpointsConfigPassThroughEndpointEndpointIdPostError
+  | misc.DeletePassThroughEndpointsConfigPassThroughEndpointDeleteError
+  | LitellmConfigPathConflictError
+  | LitellmUnaddressableRowError
+  | LitellmLiteralSecretHeaderError;

package/src/litellm/pass-through-form.ts

@@ -5,14 +5,17 @@
  * ★ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER — the same reason netbox keeps `prefix-form.ts`
  *   beside `prefix.ts` (S32/testing-and-docs.md).
  *
- * ⛔ PROPS ARE THE GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE OWNS ITSELF: `id` (a
- *   deterministic physical name — pass-through-endpoint.ts) and `is_from_config` (response-only;
- *   the vendor sets it, a declaration never does). Deriving `Props` with `Omit<>` rather than
- *   hand-typing it means a vendor schema change that adds, removes or narrows a field is felt here
- *   as a compiler error, not silently ignored.
+ * ⛔ PROPS ARE `@distilled.cloud/litellm`'s OWN GENERATED TYPE, MINUS THE TWO FIELDS THIS RESOURCE
+ *   OWNS ITSELF: `id` (a deterministic physical name — pass-through-endpoint.ts) and
+ *   `is_from_config` (response-only; the vendor sets it, a declaration never does). Deriving
+ *   `Props` with `Omit<>` rather than hand-typing it means a vendor schema change the SDK's own
+ *   next regeneration picks up is felt here as a compiler error, not silently ignored — the same
+ *   reason this used to derive from the kit's own hand-generated `./generated/pass-through.ts`
+ *   (retired by this migration: the SDK's type is the same shape, generated from the same LiteLLM
+ *   1.100.0 OpenAPI document, and keeping a second copy would only drift).
  */
 import { deepEqual } from 'alchemy/Diff';
-import type * as Generated from './generated/pass-through.ts';
+import type * as Generated from '@distilled.cloud/litellm/misc';
 
 export type PassThroughEndpointProps = Omit<
   Generated.PassThroughGenericEndpoint,
@@ -71,10 +74,17 @@ export const createBody = (
  * `undefined` OR an explicit `null` here would be dropped by the server anyway; sending neither is
  * the same outcome with no request made when nothing changed (`Object.keys(body).length === 0`
  * checked by the caller in pass-through-endpoint.ts).
+ *
+ * ⛔ `path`/`target` ARE NOT `Partial` HERE, UNLIKE EVERY OTHER FIELD. The SDK's own update
+ *   request type requires both non-optionally (the vendor's PATCH route still wants the full
+ *   route/target pair on every call, unlike the other fields' `exclude_none` merge) — typing them
+ *   as always-present here is what lets `operations.ts`'s `updatePassThroughEndpoint` pass this
+ *   straight to the SDK without an unsafe cast.
  */
-export const updateBody = (
-  props: PassThroughEndpointProps,
-): Partial<Generated.PassThroughGenericEndpoint> =>
+export type UpdateBody = Partial<Omit<Generated.PassThroughGenericEndpoint, 'path' | 'target'>> &
+  Pick<Generated.PassThroughGenericEndpoint, 'path' | 'target'>;
+
+export const updateBody = (props: PassThroughEndpointProps): UpdateBody =>
   prune({
     ...settled(props),
     guardrails: isUnset(props.guardrails) ? undefined : props.guardrails,
@@ -82,7 +92,7 @@ export const updateBody = (
     path: props.path,
     target: props.target,
     timeout: isUnset(props.timeout) ? undefined : props.timeout,
-  }) as Partial<Generated.PassThroughGenericEndpoint>;
+  }) as UpdateBody;
 
 /**
  * Whether ANY of the three nullable fields went from set (in `live`) to unset (in `props`) — the

package/src/litellm/providers.ts

@@ -3,17 +3,18 @@
  *
  *     Layer.mergeAll(litellmProviders(), …the stack's other providers)
  *
- * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME (credentials.ts),
- *   never at layer build — pass another `Layer.Layer<LitellmCredentials>` (see
- *   `litellmCredentialsLayerFor` in a test) to source them another way.
+ * ★ THE DEFAULT READS `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` AT CALL TIME, through
+ *   `@distilled.cloud/litellm`'s own `CredentialsFromEnv` — the same two variable names the
+ *   retired hand-rolled `credentials.ts` read — never at layer build. Pass another
+ *   `Layer.Layer<Credentials>` (see the SDK's own `credentials({ apiKey, baseUrl })` in a test) to
+ *   source them another way.
  * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime the same way it is
  *   for `netboxProviders`-style families in this kit; a stack that already deploys anything over
  *   HTTP already has one.
  */
+import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/Credentials';
 import * as Layer from 'effect/Layer';
-import { type LitellmCredentials, litellmCredentialsLayer } from './credentials.ts';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
-export const litellmProviders = (
-  creds: Layer.Layer<LitellmCredentials> = litellmCredentialsLayer,
-) => LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));
+export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFromEnv) =>
+  LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));

package/src/paperless/custom-field.test.ts

@@ -1,24 +1,27 @@
 /**
  * `Paperless.CustomField.dataType` is create-only: a change is refused at plan time, never
  * silently PATCHed and never routed to a replace. See custom-field.ts's header for why — a
- * replace would delete the field's value on every document.
- *
- * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. `custom-field.ts` did not exist before this change.
+ * replace would delete the field's value on every document. The live-lifecycle tests below drive
+ * the real `@distilled.cloud/paperless-ngx` wire path (tag.test.ts's own note on why
+ * `matchingOperations(spec)`, not `customFieldHandlers`, is what a test can point at a fake).
  */
 import { describe, expect, test } from 'bun:test';
-import { customFieldHandlers, dataTypeImmutable } from './custom-field.ts';
-import { run, withFake } from './fake-paperless.ts';
+import { dataTypeImmutable, spec } from './custom-field.ts';
+import { fakePaperless, run } from './fake-paperless.ts';
+import { matchingOperations } from './matching.ts';
+
+const ops = matchingOperations(spec);
 
 describe('dataTypeImmutable, the pure rule', () => {
   test('no refusal when the live value is unchanged', () => {
     expect(
-      dataTypeImmutable({ data_type: 'string', id: 1 }, { dataType: 'string', name: 'x' }),
+      dataTypeImmutable({ data_type: 'string' }, { dataType: 'string', name: 'x' }),
     ).toBeUndefined();
   });
 
   test('a refusal when the live value differs, naming both values', () => {
     const message = dataTypeImmutable(
-      { data_type: 'select', id: 1 },
+      { data_type: 'select' },
       { dataType: 'string', name: 'Status' },
     );
     expect(message).toMatch(/data_type is create-only/);
@@ -29,46 +32,52 @@ describe('dataTypeImmutable, the pure rule', () => {
 
 describe('the live lifecycle refuses a data_type change', () => {
   test('reconcile dies rather than PATCHing a changed data_type', async () => {
-    await withFake(async (fake) => {
-      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
-      const before = fake.seen.filter((s) => s.method !== 'GET').length;
+    const fake = fakePaperless();
+    const created = await run(
+      ops.reconcile({ dataType: 'select', name: 'Status' }, undefined),
+      fake.fetch,
+    );
+    const before = fake.seen.filter((s) => s.method !== 'GET').length;
 
-      await expect(
-        run(customFieldHandlers.reconcile({ news: { dataType: 'string', name: 'Status' } })),
-      ).rejects.toThrow(/data_type is create-only/);
+    await expect(
+      run(ops.reconcile({ dataType: 'string', name: 'Status' }, created), fake.fetch),
+    ).rejects.toThrow(/data_type is create-only/);
 
-      // ⛔ NOTHING WAS WRITTEN — the refusal fires before the PATCH, not after a failed one.
-      expect(fake.seen.filter((s) => s.method !== 'GET').length).toBe(before);
-    });
+    // ⛔ NOTHING WAS WRITTEN — the refusal fires before the PATCH, not after a failed one.
+    expect(fake.seen.filter((s) => s.method !== 'GET').length).toBe(before);
   });
 
   test('a create followed by a declaration of the SAME data_type is a normal no-drift reconcile', async () => {
-    await withFake(async () => {
-      await run(customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }));
-      const after = await run(
-        customFieldHandlers.reconcile({ news: { dataType: 'select', name: 'Status' } }),
-      );
-      expect(after).toMatchObject({ dataType: 'select', name: 'Status' });
-    });
+    const fake = fakePaperless();
+    const created = await run(
+      ops.reconcile({ dataType: 'select', name: 'Status' }, undefined),
+      fake.fetch,
+    );
+    const after = await run(
+      ops.reconcile({ dataType: 'select', name: 'Status' }, created),
+      fake.fetch,
+    );
+    expect(after).toMatchObject({ dataType: 'select', name: 'Status' });
   });
 
   test('extraData still updates through a normal PATCH', async () => {
-    await withFake(async (fake) => {
-      await run(
-        customFieldHandlers.reconcile({
-          news: { dataType: 'select', extraData: { select_options: ['a'] }, name: 'Status' },
-        }),
-      );
-      await run(
-        customFieldHandlers.reconcile({
-          news: { dataType: 'select', extraData: { select_options: ['a', 'b'] }, name: 'Status' },
-        }),
-      );
-      const patch = fake.seen.find((s) => s.method === 'PATCH');
-      expect(patch).toBeDefined();
-      expect(JSON.parse(patch?.body ?? '{}')).toEqual({
-        extra_data: { select_options: ['a', 'b'] },
-      });
-    });
+    const fake = fakePaperless();
+    const created = await run(
+      ops.reconcile(
+        { dataType: 'select', extraData: { select_options: ['a'] }, name: 'Status' },
+        undefined,
+      ),
+      fake.fetch,
+    );
+    await run(
+      ops.reconcile(
+        { dataType: 'select', extraData: { select_options: ['a', 'b'] }, name: 'Status' },
+        created,
+      ),
+      fake.fetch,
+    );
+    const patch = fake.seen.find((s) => s.method === 'PATCH');
+    expect(patch).toBeDefined();
+    expect(JSON.parse(patch?.body ?? '{}')).toEqual({ extra_data: { select_options: ['a', 'b'] } });
   });
 });

package/src/paperless/custom-field.ts

@@ -7,28 +7,32 @@
  *   this refusal generically; `dataType` is simply never listed in `fields`, so nothing in
  *   `matching.ts` ever builds a PATCH body that includes it.
  *
- * ⛔ NO `owner` FIELD. Unlike `Tag`/`DocumentType`/`StoragePath`, `CustomField` does not extend
- *   Paperless-ngx's `OwnedObjectSerializer` — its wire body is exactly `{name, data_type,
- *   extra_data}` (measured against the v3.1.1 schema). `owned: false` stops `matching.ts`
- *   sending a field the vendor's serializer does not declare.
+ * ⛔ NO `owner` FIELD, AND NO `ownerOf` SPEC ENTRY. Unlike `Tag`/`DocumentType`/`StoragePath`,
+ *   `CustomField` does not extend Paperless-ngx's `OwnedObjectSerializer` — its wire body is
+ *   exactly `{name, data_type, extra_data}` (measured against the v3.1.1 schema, and confirmed
+ *   again in `@distilled.cloud/paperless-ngx`'s generated `custom_fields.ts`, which has no
+ *   `owner` field either). `owned: false` stops `matching.ts` sending or comparing one.
  *
  * ⚠️ `CustomField.select_options` (the vendor's own rule for a `select` field's option list) is
- *   not in the served schema at all, so it is recorded here and NOT enforced (groundTruth).
+ *   not in the served schema at all, so it is recorded here and NOT enforced (groundTruth). See
+ *   `tag.ts`'s header for the 2026-09-24 transport migration this file follows.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as customFields from '@distilled.cloud/paperless-ngx/custom_fields';
 import * as Effect from 'effect/Effect';
 import type { PaperlessCustomFieldRequest } from './generated/types/custom-fields.ts';
-import type { PaperlessRow } from './client.ts';
-import { type MatchingRequirements, matchingHandlers } from './matching.ts';
+import {
+  LOCATE_PAGE,
+  type MatchingRequirements,
+  type MatchingSpec,
+  matchingHandlers,
+} from './matching.ts';
 
 export interface CustomFieldProps {
-  /** ⚠️ maxLength 128 (generated constraint table). The locate key — CustomField's name is globally unique (models.py:1169), with no owner to further scope it. */
+  /** ⚠️ maxLength 128 (generated constraint table). CustomField's name is globally unique (models.py:1169), with no owner to further scope it. */
   name: string;
-  /**
-   * ⛔ CREATE-ONLY — see this file's header. `select`'s own option list
-   *   (`select_options`) is not in the vendor schema and is unenforced here.
-   */
+  /** ⛔ CREATE-ONLY — see this file's header. `select`'s own option list (`select_options`) is not in the vendor schema and is unenforced here. */
   dataType: PaperlessCustomFieldRequest['data_type'];
   /** Arbitrary JSON the vendor attaches no schema to (e.g. a `select` field's option list). */
   extraData?: unknown;
@@ -54,42 +58,62 @@ export const CustomField = Resource<CustomField>('Paperless.CustomField', {
 });
 
 /**
- * ⛔ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER (custom-field.test.ts) — the same reason
- *   `../netbox/prefix-form.ts` pulls its body/matches functions out of `prefix.ts`.
+ * ⛔ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER (custom-field.test.ts). `Pick<…, 'data_type'>`
+ *   rather than the full `CustomField`, so a test fixture need not spell out `name`/`document_count`.
  */
 export const dataTypeImmutable = (
-  live: PaperlessRow,
+  live: Pick<customFields.CustomField, 'data_type'>,
   props: CustomFieldProps,
 ): string | undefined =>
-  typeof live['data_type'] === 'string' && live['data_type'] !== props.dataType
-    ? `Paperless.CustomField "${props.name}": data_type is create-only (live: ${live['data_type']}, ` +
+  live.data_type !== props.dataType
+    ? `Paperless.CustomField "${props.name}": data_type is create-only (live: ${live.data_type}, ` +
       `declared: ${props.dataType}). Changing it would delete this field's value on every ` +
       'document. Create a new custom field instead, and retire this one by hand.'
     : undefined;
 
-/** ⚠️ Exported (not through index.ts) so custom-field.test.ts can drive the real lifecycle. */
-export const customFieldHandlers = matchingHandlers<CustomFieldProps, CustomFieldAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      dataType: typeof live['data_type'] === 'string' ? live['data_type'] : props.dataType,
-      extraData: live['extra_data'],
-      id,
-      name: typeof live['name'] === 'string' ? live['name'] : props.name,
-    };
-  },
-  collection: 'custom_fields',
+/** ★ Exported for direct testing — see tag.ts's own note on this seam. */
+export const spec: MatchingSpec<
+  CustomFieldProps,
+  customFields.CustomField,
+  CustomFieldAttributes,
+  | customFields.CreateCustomFieldError
+  | customFields.GetCustomFieldError
+  | customFields.ListCustomFieldsError
+  | customFields.UpdateCustomFieldsPartialError
+  | customFields.CustomFieldsDestroyError
+> = {
+  attributes: (live, props) => ({
+    dataType: live.data_type ?? props.dataType,
+    extraData: live.extra_data,
+    id: live.id,
+    name: live.name,
+  }),
+  create: (body) =>
+    customFields.createCustomField(body as unknown as customFields.CreateCustomFieldRequest),
+  createOnly: [{ key: 'data_type', live: (r) => r.data_type, prop: (p) => p.dataType }],
   describe: (props) => `custom_fields ${props.name}`,
+  destroy: (id) => customFields.customFieldsDestroy({ id }),
   endpoint: {
     create: 'paperless:POST /api/custom_fields/',
     update: 'paperless:PATCH /api/custom_fields/{id}/',
   },
-  createOnly: [{ key: 'data_type', live: (r) => r['data_type'], prop: (p) => p.dataType }],
-  fields: [{ key: 'extra_data', live: (r) => r['extra_data'], prop: (p) => p.extraData }],
+  fields: [{ key: 'extra_data', live: (r) => r.extra_data, prop: (p) => p.extraData }],
+  getById: (id) =>
+    customFields
+      .getCustomField({ id })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   immutable: dataTypeImmutable,
+  list: (props) =>
+    customFields.listCustomFields({ name__iexact: props.name, page_size: LOCATE_PAGE }),
   owned: false,
-});
+  update: (id, body) =>
+    customFields.updateCustomFieldsPartial({
+      ...(body as unknown as Omit<customFields.UpdateCustomFieldsPartialRequest, 'id'>),
+      id,
+    }),
+};
+
+export const customFieldHandlers = matchingHandlers(spec);
 
 export const CustomFieldProvider = () =>
   Provider.effect(CustomField, Effect.succeed(CustomField.Provider.of(customFieldHandlers)));