@homeflare/alchemy 0.28.0 → 0.29.1

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,

package/src/paperless/matching-locate.test.ts

@@ -0,0 +1,102 @@
+/**
+ * `soleMatch`, `locateOne` and the PR 163 identity switch (`fetchLive`) — identity resolution, in
+ * isolation. Pure/Effect only (no HTTP, `R = never`): every fixture is `Effect.succeed`, mirroring
+ * `../netbox/resource.test.ts`'s own `locateOne` tests. `tag.test.ts`/`tag-identity.test.ts`
+ * exercise the real distilled wire path this feeds from, plus the full PR 163 regression suite
+ * this file does not repeat.
+ *
+ * ⛔ THE FAILURE `soleMatch` GUARDS IS SILENT AND SELF-RENEWING. If an ambiguous match took the
+ *   first row, adopt would bind to it, the next plan would bind to the other, and every plan
+ *   after that would report drift that is not there. Failing loudly is the only outcome an
+ *   operator can act on. Ported verbatim from the pre-migration `client.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { LOCATE_PAGE, fetchLive, locateOne, soleMatch } from './matching-locate.ts';
+
+describe('soleMatch', () => {
+  test('no candidate is absent, not an error — that is what plans a create', () => {
+    expect(soleMatch([], 'tags Invoices')).toBeUndefined();
+  });
+
+  test('exactly one candidate is the object', () => {
+    expect(soleMatch([{ id: 7 }], 'tags Invoices')).toEqual({ id: 7 });
+  });
+
+  /** ⛔ Two rows means the identity rule is wrong, and the message says which object it was. */
+  test('more than one candidate throws and names the object', () => {
+    expect(() => soleMatch([{ id: 7 }, { id: 8 }], 'tags Invoices')).toThrow(
+      /tags Invoices matched 2 Paperless objects/,
+    );
+  });
+});
+
+interface Row {
+  readonly id: number;
+  readonly name: string;
+}
+
+const page = (results: readonly Row[]) => Effect.succeed({ count: results.length, results });
+
+describe('locateOne', () => {
+  test('an empty page is absent', async () => {
+    expect(await Effect.runPromise(locateOne(page([]), 'tags Invoices'))).toBeUndefined();
+  });
+
+  test('one row with no `identifies` narrowing is the object', async () => {
+    const row = await Effect.runPromise(
+      locateOne(page([{ id: 7, name: 'Invoices' }]), 'tags Invoices'),
+    );
+    expect(row).toEqual({ id: 7, name: 'Invoices' });
+  });
+
+  test('`identifies` narrows several server-side matches to the declared one', async () => {
+    const rows = [
+      { id: 7, name: 'Invoices' },
+      { id: 8, name: 'invoices' },
+    ];
+    const row = await Effect.runPromise(
+      locateOne(page(rows), 'tags Invoices', (r) => r.name === 'invoices'),
+    );
+    expect(row).toEqual({ id: 8, name: 'invoices' });
+  });
+
+  test('more rows than the page width is a defect, not a truncation', async () => {
+    const rows = Array.from({ length: LOCATE_PAGE + 1 }, (_, i) => ({ id: i, name: 'x' }));
+    await expect(Effect.runPromise(locateOne(page(rows), 'tags Invoices'))).rejects.toThrow(
+      /matched 21 rows, more than the 20-row page/,
+    );
+  });
+});
+
+describe('fetchLive (the PR 163 identity switch)', () => {
+  const byName = (rows: readonly Row[]) => (props: { name: string }) =>
+    locateOne(page(rows), `tags ${props.name}`, (r) => r.name === props.name);
+  const byId = (rows: readonly Row[]) => (id: number) =>
+    Effect.succeed(rows.find((r) => r.id === id));
+  const describe_ = (props: { name: string }) => `tags ${props.name}`;
+
+  test('no output: locates by name', async () => {
+    const rows = [{ id: 7, name: 'Invoices' }];
+    const live = await Effect.runPromise(
+      fetchLive({ name: 'Invoices' }, undefined, byName(rows), byId(rows), describe_),
+    );
+    expect(live?.id).toBe(7);
+  });
+
+  test('output present: locates by id, ignoring a since-changed name', async () => {
+    const rows = [{ id: 7, name: 'Renamed' }];
+    const live = await Effect.runPromise(
+      fetchLive({ name: 'Invoices' }, { id: 7 }, byName(rows), byId(rows), describe_),
+    );
+    expect(live?.id).toBe(7);
+  });
+
+  test('output.id no longer live: refuses rather than falling through to a create', async () => {
+    await expect(
+      Effect.runPromise(
+        fetchLive({ name: 'Invoices' }, { id: 7 }, byName([]), byId([]), describe_),
+      ),
+    ).rejects.toThrow(/no longer exists live|deleted out of band/);
+  });
+});

package/src/paperless/matching-locate.ts

@@ -4,101 +4,95 @@
  * live Paperless row IS this declaration — by name while there is no state, by the stored
  * `output.id` once there is one. See `matching.ts`'s header for the PR 163 red-team HIGH finding
  * this identity switch fixes.
+ *
+ * ★ EVERY EXPORT HERE IS GENERIC OVER `R`, NOT TIED TO `PaperlessNgxOpContext` — mirroring
+ *   `../netbox/resource.ts`'s standalone `locateOne`. `matching.ts` wires these against a real
+ *   spec's `PaperlessNgxOpContext`-typed operations; `matching-locate.test.ts` wires them against
+ *   plain `Effect.succeed` fixtures (`R = never`) — the same function, no fake HTTP needed to
+ *   prove the pure rule.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `spec.getById`, NOT HERE —
+ *   the direct successor to the old, centralized `absentOn404`, and the same split
+ *   `../netbox/resource.ts` and `../forgejo/resource.ts` use. `Effect.catchTag`'s tag-literal
+ *   inference needs a concrete error union to resolve `"NotFound"` against; a spec's `E` is only
+ *   concrete at each resource file's own call site (`GetTagError`, `GetDocumentTypeError`, …). A
+ *   LIST call is never folded here either — an empty `results` page is a normal 200, not a 404
+ *   (measured live, kit PR 194).
  */
 import * as Effect from 'effect/Effect';
-import { PaperlessNotFound } from './errors.ts';
-import { type PaperlessList, type PaperlessRow, paperless } from './client.ts';
-import type { MatchingError, MatchingProps, MatchingRequirements } from './matching-types.ts';
 
 /**
- * ⚠️ Only 404 folds to "absent" — a 401/403 is never read as absent (acceptance criteria).
- * Exported — `matching.ts`'s `destroy` uses it directly around its own DELETE call.
+ * ★ Wide enough to see every case-variant candidate `name__iexact` returns; a natural key past it
+ *   is not one. Unchanged from the pre-migration `client.ts`'s own value.
  */
-export const absentOn404 = <A>(io: Effect.Effect<A, MatchingError, MatchingRequirements>) =>
-  io.pipe(
-    Effect.catchIf(
-      (cause): cause is PaperlessNotFound => cause instanceof PaperlessNotFound,
-      () => Effect.succeed(undefined as A),
-    ),
-  );
-
-/** ★ Wide enough to see every case-variant candidate `name__iexact` returns; a natural key past it is not one. */
-const LOCATE_PAGE = 20;
-
-/** ⚠️ Exported — `matching.ts`'s `patchBody`/`matches` compare the live `owner` too (PR 163). */
-export const ownerOf = (row: PaperlessRow): number | undefined =>
-  typeof row['owner'] === 'number' ? row['owner'] : undefined;
+export const LOCATE_PAGE = 20;
 
 /**
- * The name/id lookups every `matching.ts` operation shares, built once per family spec.
- * `collection` and `describe` are all this slice needs out of a full `MatchingSpec`.
+ * The single row a filtered list returns, or `undefined`.
+ *
+ * ⛔ MORE THAN ONE MATCH IS A DEFECT, NOT A REASON TO TAKE THE FIRST. If an ambiguous match took
+ *   the first row, adopt would bind to it, the next plan would bind to the other, and every plan
+ *   after that would report drift that is not there — while "fixing" it PATCHed one object with
+ *   the other's declaration. Failing loudly is the only outcome an operator can act on.
  */
-export const matchingLocate = <Props extends MatchingProps>(spec: {
-  readonly collection: string;
-  readonly describe: (props: Props) => string;
-}) => {
-  /**
-   * ★ THE NO-STATE LOCATE. Used only when there is no `output` yet: a genuine first create, or
-   *   the engine's own adoption probe (`provider.read`, always called with `output: undefined`).
-   */
-  const fetchByName = (props: Props) =>
-    absentOn404(
-      paperless<PaperlessList<PaperlessRow>>(
-        'GET',
-        `${spec.collection}/?name__iexact=${encodeURIComponent(props.name)}&page_size=${String(LOCATE_PAGE)}`,
-      ),
-    ).pipe(
-      Effect.map((list) => {
-        if (list !== undefined && list.count > LOCATE_PAGE) {
-          throw new Error(
-            `${spec.describe(props)}: name__iexact matched ${String(list.count)} rows, more than ` +
-              `the ${String(LOCATE_PAGE)}-row page this reads. Narrow the name rather than paging.`,
-          );
-        }
-        const rows = (list?.results ?? []).filter(
-          (row) => row['name'] === props.name && ownerOf(row) === (props.owner ?? undefined),
-        );
-        if (rows.length > 1) {
-          throw new Error(
-            `${spec.describe(props)}: matched ${String(rows.length)} Paperless objects with the same (name, owner).`,
-          );
-        }
-        return rows[0];
-      }),
+export const soleMatch = <T>(rows: readonly T[], describe: string): T | undefined => {
+  if (rows.length > 1) {
+    throw new Error(
+      `${describe} matched ${String(rows.length)} Paperless objects with the same (name, owner).`,
     );
+  }
+  return rows[0];
+};
 
-  /** The stored id itself, once this declaration has one. A 404 here means the row is gone. */
-  const fetchById = (id: number) =>
-    absentOn404(paperless<PaperlessRow>('GET', `${spec.collection}/${String(id)}/`));
-
-  /**
-   * ⛔ THE IDENTITY SWITCH (PR 163, red-team HIGH finding — see `matching.ts`'s header). `output`
-   *   defined means this declaration has already written something: identity is `output.id`, full
-   *   stop, and a changed `name`/`owner` in `props` is drift to PATCH, never a reason to relocate.
-   *   `output` undefined means there is nothing to be wrong about yet — locate by name.
-   */
-  const fetchLive = <Attributes extends { readonly id: number }>(
-    props: Props,
-    output: Attributes | undefined,
-  ) =>
-    output === undefined
-      ? fetchByName(props)
-      : fetchById(output.id).pipe(
-          Effect.flatMap((live) =>
-            live === undefined
-              ? Effect.die(
-                  new Error(
-                    `${spec.describe(props)}: id ${String(output.id)} is recorded in state but no ` +
-                      'longer exists live (deleted out of band). Refusing to create a replacement ' +
-                      '— adopt the live object back under this declaration, or remove it from ' +
-                      'state, before deploying again.',
-                  ),
-                )
-              : Effect.succeed(live),
-          ),
+/**
+ * List, then narrow to at most one candidate. Any Paperless resource whose locate is "filter
+ * server-side, then disambiguate in this process" reaches this once rather than reimplementing
+ * the page-width assertion and the ambiguity defect per resource.
+ */
+export const locateOne = <Live, E, R>(
+  list: Effect.Effect<{ readonly count: number; readonly results: readonly Live[] }, E, R>,
+  describe: string,
+  identifies?: (row: Live) => boolean,
+): Effect.Effect<Live | undefined, E, R> =>
+  list.pipe(
+    Effect.map((page) => {
+      if (page.count > LOCATE_PAGE) {
+        throw new Error(
+          `${describe}: name__iexact matched ${String(page.count)} rows, more than the ` +
+            `${String(LOCATE_PAGE)}-row page this reads. Narrow the name rather than paging.`,
         );
+      }
+      const rows = identifies === undefined ? page.results : page.results.filter(identifies);
+      return soleMatch(rows, describe);
+    }),
+  );
 
-  const objectPath = (live: PaperlessRow): string => `${spec.collection}/${String(live['id'])}`;
-
-  return { fetchByName, fetchById, fetchLive, objectPath };
-};
+/**
+ * ⛔ THE IDENTITY SWITCH (PR 163, red-team HIGH finding — see `matching.ts`'s header). `output`
+ *   defined means this declaration has already written something: identity is `output.id`, full
+ *   stop, and a changed `name`/`owner` in the caller's props is drift to PATCH, never a reason to
+ *   relocate. `output` undefined means there is nothing to be wrong about yet — locate by name.
+ */
+export const fetchLive = <Props, Live, Attributes extends { readonly id: number }, E, R>(
+  props: Props,
+  output: Attributes | undefined,
+  fetchByName: (props: Props) => Effect.Effect<Live | undefined, E, R>,
+  fetchById: (id: number) => Effect.Effect<Live | undefined, E, R>,
+  describe: (props: Props) => string,
+): Effect.Effect<Live | undefined, E, R> =>
+  output === undefined
+    ? fetchByName(props)
+    : fetchById(output.id).pipe(
+        Effect.flatMap((live) =>
+          live === undefined
+            ? Effect.die(
+                new Error(
+                  `${describe(props)}: id ${String(output.id)} is recorded in state but no ` +
+                    'longer exists live (deleted out of band). Refusing to create a replacement ' +
+                    '— adopt the live object back under this declaration, or remove it from ' +
+                    'state, before deploying again.',
+                ),
+              )
+            : Effect.succeed(live),
+        ),
+      );