@homeflare/alchemy 0.27.4 → 0.29.0

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)));

package/src/paperless/document-type.test.ts

@@ -0,0 +1,48 @@
+/**
+ * `DocumentType`'s exported production `spec` against a fake Paperless-ngx — proves this file's
+ * own `@distilled.cloud/paperless-ngx/document_types` wiring (right operations, right field
+ * names) round-trips for real. The shared `matching.ts` engine and the PR 163 identity switch are
+ * proven generically by `tag.test.ts`/`tag-identity.test.ts`/`matching-locate.test.ts`; this file
+ * does not repeat that coverage.
+ */
+import { describe, expect, test } from 'bun:test';
+import { spec } from './document-type.ts';
+import { fakePaperless, run } from './fake-paperless.ts';
+import { matchingOperations } from './matching.ts';
+
+const ops = matchingOperations(spec);
+
+test('create sends owner: null when undeclared, and the constraint-checked body', async () => {
+  const fake = fakePaperless();
+  await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+  const post = fake.seen.find((s) => s.method === 'POST');
+  expect(post).toBeDefined();
+  expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ name: 'Invoices', owner: null });
+});
+
+describe('a full create → read → patch → delete round trip', () => {
+  test('the real distilled wire path carries every field through', async () => {
+    const fake = fakePaperless();
+    const created = await run(
+      ops.reconcile({ isInsensitive: true, match: 'invoice', name: 'Invoices' }, undefined),
+      fake.fetch,
+    );
+    expect(created).toMatchObject({ isInsensitive: true, match: 'invoice', name: 'Invoices' });
+
+    const after = await run(
+      ops.reconcile({ isInsensitive: true, match: 'receipt', name: 'Invoices' }, created),
+      fake.fetch,
+    );
+    const patch = fake.seen.find((s) => s.method === 'PATCH');
+    expect(JSON.parse(patch?.body ?? '{}')).toEqual({ match: 'receipt' });
+    expect(after?.match).toBe('receipt');
+
+    await run(ops.destroy({ name: 'Invoices' }, after), fake.fetch);
+    expect(fake.rows('document_types').length).toBe(0);
+  });
+});
+
+test('a 404 on read folds to absent', async () => {
+  const fake = fakePaperless();
+  expect(await run(ops.read({ name: 'Nothing here' }), fake.fetch)).toBeUndefined();
+});

package/src/paperless/document-type.ts

@@ -1,17 +1,25 @@
 /**
  * `Paperless.DocumentType` — a Paperless-ngx document type, create-or-update and never deleted.
  * Same shape as `tag.ts` minus `color`/`isInboxTag`/`parent` — see that file's header for why
- * `matchingAlgorithm`'s type comes off the generated request type rather than being retyped.
+ * `matchingAlgorithm`'s type comes off the generated request type rather than being retyped, and
+ * for the 2026-09-24 transport migration this file follows exactly.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as documentTypes from '@distilled.cloud/paperless-ngx/document_types';
 import * as Effect from 'effect/Effect';
 import type { PaperlessDocumentTypeRequest } from './generated/types/document-types.ts';
-import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+import {
+  LOCATE_PAGE,
+  type MatchingRequirements,
+  type MatchingSpec,
+  matchingHandlers,
+} from './matching.ts';
 
-export interface DocumentTypeProps extends MatchingProps {
+export interface DocumentTypeProps {
   /** ⚠️ maxLength 128 (generated constraint table). The locate key. */
   name: string;
+  owner?: number;
   /** ⚠️ maxLength 256. */
   match?: string;
   matchingAlgorithm?: PaperlessDocumentTypeRequest['matching_algorithm'];
@@ -39,36 +47,57 @@ export const DocumentType = Resource<DocumentType>('Paperless.DocumentType', {
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = matchingHandlers<DocumentTypeProps, DocumentTypeAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      id,
-      isInsensitive: live['is_insensitive'] === true,
-      match: typeof live['match'] === 'string' ? live['match'] : '',
-      matchingAlgorithm:
-        typeof live['matching_algorithm'] === 'number' ? live['matching_algorithm'] : 0,
-      name: typeof live['name'] === 'string' ? live['name'] : props.name,
-      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
-    };
-  },
-  collection: 'document_types',
+/** ★ Exported for direct testing — see tag.ts's own note on this seam. */
+export const spec: MatchingSpec<
+  DocumentTypeProps,
+  documentTypes.DocumentType,
+  DocumentTypeAttributes,
+  | documentTypes.CreateDocumentTypeError
+  | documentTypes.GetDocumentTypeError
+  | documentTypes.ListDocumentTypesError
+  | documentTypes.UpdateDocumentTypesPartialError
+  | documentTypes.DocumentTypesDestroyError
+> = {
+  attributes: (live, props) => ({
+    id: live.id,
+    isInsensitive: live.is_insensitive === true,
+    match: live.match ?? '',
+    matchingAlgorithm: live.matching_algorithm ?? 0,
+    name: live.name,
+    owner: live.owner ?? undefined,
+  }),
+  create: (body) =>
+    documentTypes.createDocumentType(body as unknown as documentTypes.CreateDocumentTypeRequest),
   describe: (props) => `document_types ${props.name}`,
+  destroy: (id) => documentTypes.documentTypesDestroy({ id }),
   endpoint: {
     create: 'paperless:POST /api/document_types/',
     update: 'paperless:PATCH /api/document_types/{id}/',
   },
   fields: [
-    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    { key: 'match', live: (r) => r.match, prop: (p) => p.match },
     {
       key: 'matching_algorithm',
-      live: (r) => r['matching_algorithm'],
+      live: (r) => r.matching_algorithm,
       prop: (p) => p.matchingAlgorithm,
     },
-    { key: 'is_insensitive', live: (r) => r['is_insensitive'], prop: (p) => p.isInsensitive },
+    { key: 'is_insensitive', live: (r) => r.is_insensitive, prop: (p) => p.isInsensitive },
   ],
-});
+  getById: (id) =>
+    documentTypes
+      .getDocumentType({ id })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  list: (props) =>
+    documentTypes.listDocumentTypes({ name__iexact: props.name, page_size: LOCATE_PAGE }),
+  ownerOf: (live) => live.owner ?? undefined,
+  update: (id, body) =>
+    documentTypes.updateDocumentTypesPartial({
+      ...(body as unknown as Omit<documentTypes.UpdateDocumentTypesPartialRequest, 'id'>),
+      id,
+    }),
+};
+
+export const handlers = matchingHandlers(spec);
 
 export const DocumentTypeProvider = () =>
   Provider.effect(DocumentType, Effect.succeed(DocumentType.Provider.of(handlers)));