@homeflare/alchemy 0.28.0 → 0.29.0

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

package/src/paperless/fake-paperless.ts

@@ -1,59 +1,73 @@
 /**
- * A fake Paperless-ngx for the tests beside it — `Bun.serve` on an ephemeral 127.0.0.1 port, the
- * same shape `../openbao/fake-bao.ts` and `../caddy/fake-caddy.ts` use.
+ * A minimal in-memory Paperless-ngx REST API for this family's tests — an in-memory `fetch`
+ * handed to Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../netbox/fake-netbox.ts` and `../forgejo/fake-forgejo.ts`. Tests exercise distilled's REAL
+ * path assembly, JSON encode/decode and status→typed-error matching (`404` → `NotFound`, `403` →
+ * `Forbidden`, `400` → `BadRequest`, …) — nothing about that matching is re-implemented here, only
+ * the wire responses and in-memory rows a scenario needs.
  *
- * ⛔ TEST-ONLY. No provider imports this file. It stores rows in memory for exactly the four
- *   taxonomy collections and answers `name__iexact` the way Django does — case-insensitive,
- *   never collapsing two differently-cased rows into one.
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. Stores rows in memory for the four
+ *   taxonomy collections and answers `name__iexact` the way Django does — case-insensitive, never
+ *   collapsing two differently-cased rows into one. Ported from the pre-migration `Bun.serve`
+ *   fake: production now goes through `@distilled.cloud/paperless-ngx`'s `CredentialsFromEnv`,
+ *   which resolves through Effect `Config` and snapshots `process.env` once (measured in the
+ *   forgejo migration, kit PR 180) — a test can no longer point production code at a fake server
+ *   by mutating env vars, so this hands an explicit `credentials()` layer instead.
  */
+import { type Credentials, credentials } from '@distilled.cloud/paperless-ngx/Credentials';
+import type { PaperlessNgxOpContext } from '@distilled.cloud/paperless-ngx/Protocol';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import type { PaperlessRequirements } from './client.ts';
-import { type PaperlessCredentialsError, environmentLayer } from './credentials.ts';
-import type { PaperlessError } from './errors.ts';
 
-export const FAKE_TOKEN = 'fake-token-not-real';
+export const FAKE_BASE = 'https://paperless.example.com';
+export const FAKE_TOKEN = 'placeholder-paperless-token';
 
 export interface Seen {
   readonly method: string;
   readonly path: string;
-  readonly headers: Headers;
   readonly body: string;
 }
 
 export type Row = Record<string, unknown> & { id: number };
 
 const COLLECTIONS = ['tags', 'document_types', 'storage_paths', 'custom_fields'] as const;
+type Collection = (typeof COLLECTIONS)[number];
 
 export interface FakePaperless {
-  readonly url: string;
+  readonly fetch: typeof globalThis.fetch;
   readonly seen: Seen[];
-  readonly rows: (collection: (typeof COLLECTIONS)[number]) => readonly Row[];
-  /** `undefined` to answer normally; a status to force it once per subsequent call. */
+  readonly rows: (collection: Collection) => readonly Row[];
+  /** `undefined` to answer normally; a status to force it once for the NEXT call only. */
   forceStatus: number | undefined;
-  stop(): void;
 }
 
-const nextId = (store: Row[]): number =>
+const nextId = (store: readonly Row[]): number =>
   store.length === 0 ? 1 : Math.max(...store.map((r) => r.id)) + 1;
 
+const json = (status: number, body: unknown): Response =>
+  new Response(status === 204 ? null : JSON.stringify(body), {
+    headers: { 'content-type': 'application/json' },
+    status,
+  });
+
+/**
+ * A stateful CRUD router across the four collections — this is what makes it possible to test
+ * `matching.ts`'s full create → read-back → PATCH → DELETE lifecycle, not just one canned
+ * response per test the way `fakeNetbox`/`fakeForgejo`'s simpler `route` callback does.
+ */
 export const fakePaperless = (): FakePaperless => {
   const seen: Seen[] = [];
-  const store = new Map<(typeof COLLECTIONS)[number], Row[]>(COLLECTIONS.map((c) => [c, []]));
+  const store = new Map<Collection, Row[]>(COLLECTIONS.map((c) => [c, []]));
   let forced: number | undefined;
 
-  const fetch = async (request: Request): Promise<Response> => {
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
     const url = new URL(request.url);
     const body = await request.text();
-    seen.push({
-      body,
-      headers: request.headers,
-      method: request.method,
-      path: `${url.pathname}${url.search}`,
-    });
-
-    const token = request.headers.get('Authorization');
-    if (token !== `Token ${FAKE_TOKEN}`) return json(401, { detail: 'Invalid token.' });
+    seen.push({ body, method: request.method, path: `${url.pathname}${url.search}` });
+
     if (forced !== undefined) {
       const status = forced;
       forced = undefined;
@@ -62,7 +76,7 @@ export const fakePaperless = (): FakePaperless => {
 
     const segments = url.pathname.split('/').filter((s) => s !== '');
     // ['api', collection, (id)?]
-    const collection = segments[1] as (typeof COLLECTIONS)[number] | undefined;
+    const collection = segments[1] as Collection | undefined;
     if (collection === undefined || !COLLECTIONS.includes(collection))
       return json(404, { detail: 'Not found.' });
     const rows = store.get(collection) as Row[];
@@ -96,10 +110,10 @@ export const fakePaperless = (): FakePaperless => {
       return new Response(null, { status: 204 });
     }
     return json(405, { detail: 'method not allowed' });
-  };
+  }) as typeof globalThis.fetch;
 
-  const server = Bun.serve({ fetch, hostname: '127.0.0.1', port: 0 });
   return {
+    fetch,
     get forceStatus() {
       return forced;
     },
@@ -108,49 +122,26 @@ export const fakePaperless = (): FakePaperless => {
     },
     rows: (collection) => store.get(collection) ?? [],
     seen,
-    stop: () => void server.stop(true),
-    url: server.url.origin,
   };
 };
 
-const json = (status: number, body: unknown): Response =>
-  new Response(status === 204 ? null : JSON.stringify(body), {
-    headers: { 'content-type': 'application/json' },
-    status,
-  });
-
-/** Run `body` against a fresh fake, `PAPERLESS_URL`/`PAPERLESS_TOKEN` set only for its duration. */
-export const withFake = async (body: (fake: FakePaperless) => Promise<void>): Promise<void> => {
-  const fake = fakePaperless();
-  const savedUrl = process.env['PAPERLESS_URL'];
-  const savedToken = process.env['PAPERLESS_TOKEN'];
-  process.env['PAPERLESS_URL'] = fake.url;
-  process.env['PAPERLESS_TOKEN'] = FAKE_TOKEN;
-  try {
-    await body(fake);
-  } finally {
-    fake.stop();
-    if (savedUrl === undefined) delete process.env['PAPERLESS_URL'];
-    else process.env['PAPERLESS_URL'] = savedUrl;
-    if (savedToken === undefined) delete process.env['PAPERLESS_TOKEN'];
-    else process.env['PAPERLESS_TOKEN'] = savedToken;
-  }
-};
-
-/** Run an effect through the real `FetchHttpClient` and the real environment credentials layer. */
-export const run = <A>(
-  effect: Effect.Effect<A, PaperlessError | PaperlessCredentialsError, PaperlessRequirements>,
-) =>
-  Effect.runPromise(
-    effect.pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(environmentLayer)),
-  );
-
-export const runFailure = <A>(
-  effect: Effect.Effect<A, PaperlessError | PaperlessCredentialsError, PaperlessRequirements>,
-) =>
-  Effect.runPromise(
-    Effect.flip(effect).pipe(
-      Effect.provide(FetchHttpClient.layer),
-      Effect.provide(environmentLayer),
-    ),
-  );
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `PaperlessNgxOpContext`, what
+ * `matchingOperations(spec)` (matching.ts, unwrapped — not `matchingHandlers`, which bakes in
+ * `CredentialsFromEnv` and so cannot be pointed at a fake server, per this file's own header)
+ * needs to run against a fake.
+ */
+export const fakePaperlessLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ baseUrl: FAKE_BASE, token: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));
+
+export const run = <A, E>(
+  effect: Effect.Effect<A, E, PaperlessNgxOpContext>,
+  fetchFn: typeof globalThis.fetch,
+) => Effect.runPromise(effect.pipe(Effect.provide(fakePaperlessLayer(fetchFn))));
+
+export const runFailure = <A, E>(
+  effect: Effect.Effect<A, E, PaperlessNgxOpContext>,
+  fetchFn: typeof globalThis.fetch,
+) => Effect.runPromise(Effect.flip(effect).pipe(Effect.provide(fakePaperlessLayer(fetchFn))));

package/src/paperless/index.ts

@@ -5,20 +5,14 @@
  *   header. `matching.ts`'s internals and the raw generated modules are not re-exported; a
  *   consumer wanting the same guard a Resource uses gets it through `constraintsFor`/
  *   `bodyViolations`, not by importing `generated/` directly.
+ *
+ * 🔴 `PaperlessCredentials`/`PaperlessError` AND FRIENDS ARE GONE (2026-09-24, the
+ *   `@distilled.cloud/paperless-ngx` migration — matching.ts's header), the same way
+ *   `../netbox/index.ts` dropped `NetboxError`/`apiBase` in its own migration. A caller that
+ *   needs the typed errors now imports them from `@distilled.cloud/paperless-ngx` directly (e.g.
+ *   `@distilled.cloud/paperless-ngx/tags`'s `NotFound`); nothing in this estate imported the old
+ *   names (measured 2026-09-24).
  */
-export {
-  PaperlessCredentials,
-  type PaperlessCredentialValue,
-  PaperlessCredentialsError,
-  environmentLayer as paperlessEnvironmentLayer,
-} from './credentials.ts';
-export {
-  PaperlessNotFound,
-  PaperlessUnauthorized,
-  PaperlessValidation,
-  PaperlessUnavailable,
-  type PaperlessError,
-} from './errors.ts';
 export {
   PAPERLESS_CONSTRAINTS,
   bodyViolations,