@homeflare/alchemy 0.27.4 → 0.29.0

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

package/src/paperless/matching-types.ts

@@ -4,21 +4,31 @@
  * itself (the identity/locate/create/patch logic the PR 163 red-team HIGH finding is about) stays
  * under the house's 250-line-per-file cap. See `matching.ts`'s header for the identity design
  * (`output.id` once a resource has state) this `MatchingSpec` shape supports.
+ *
+ * 🔴 MOVED ONTO `@distilled.cloud/paperless-ngx` (2026-09-24, decision 43) — `Live` is now
+ *   whatever a distilled operation decodes (a `tags.Tag`, a `documentTypes.DocumentType`, …), no
+ *   more untyped `PaperlessRow`. `E` is left to each resource file to declare (the union of the
+ *   distilled operations it actually calls), so a call site's precise per-operation error union
+ *   flows straight through instead of being widened by hand here — the same split
+ *   `../netbox/resource.ts` and `../forgejo/resource.ts` use.
  */
-import type { PaperlessCredentialsError } from './credentials.ts';
-import type { PaperlessError } from './errors.ts';
-import type { PaperlessRequirements, PaperlessRow } from './client.ts';
-import type { EndpointKey } from './constraints.ts';
+import type { PaperlessNgxOpContext } from '@distilled.cloud/paperless-ngx/Protocol';
+import type * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { EndpointKey, PaperlessBody } from './constraints.ts';
 
-/** = `client.ts`'s `PaperlessRequirements` — `HttpClient` and the credentials service both. */
-export type MatchingRequirements = PaperlessRequirements;
-export type MatchingError = PaperlessError | PaperlessCredentialsError;
+/**
+ * What a CONSUMING STACK must provide. `matchingHandlers` (matching.ts) bakes in
+ * `CredentialsFromEnv` itself, the same way `netboxHandlers`/`forgejoHandlers` do, so only the
+ * transport is left — see matching.ts's own note on `withCredentials`.
+ */
+export type MatchingRequirements = HttpClient.HttpClient;
 
 /** A wire field beyond `name`/`owner`: how to read it from props, and how to read it back. */
-export interface FieldSpec<Props> {
+export interface FieldSpec<Props, Live> {
   readonly key: string;
   readonly prop: (props: Props) => unknown;
-  readonly live: (row: PaperlessRow) => unknown;
+  readonly live: (row: Live) => unknown;
 }
 
 export interface MatchingProps {
@@ -27,29 +37,40 @@ export interface MatchingProps {
   readonly owner?: number;
 }
 
+/** The shape every `list*` distilled operation this family calls answers. */
+export interface MatchingPage<Live> {
+  readonly count: number;
+  readonly results: readonly Live[];
+}
+
 export interface MatchingSpec<
   Props extends MatchingProps,
+  Live extends { readonly id: number; readonly name: string },
   Attributes extends { readonly id: number },
+  E,
 > {
-  /** `tags`, `document_types`, `storage_paths`, `custom_fields`. */
-  readonly collection: string;
   /**
    * ⚠️ DEFAULT `true`. `Tag`, `DocumentType` and `StoragePath` extend Paperless-ngx's
    *   `OwnedObjectSerializer`; `CustomField` does not — its wire body has no `owner` key at all
    *   (measured against the v3.1.1 schema: `CustomFieldRequest` is `{name, data_type,
-   *   extra_data}`). `false` stops `createBody` sending a field the vendor would silently ignore.
+   *   extra_data}`). `false` stops `createBody` sending a field the vendor would silently ignore,
+   *   and `ownerOf` need not be declared.
    */
   readonly owned?: boolean;
   /** Compared, PATCHed when they differ, and sent on create. */
-  readonly fields: readonly FieldSpec<Props>[];
+  readonly fields: readonly FieldSpec<Props, Live>[];
   /**
    * Sent on CREATE only — never compared, never PATCHed. `CustomField.dataType` (custom-field.ts)
    * is the one user: it must reach the create body, but `immutable` is what refuses a later
    * change, and `matches`/`patchBody` must never see it as ordinary drift.
    */
-  readonly createOnly?: readonly FieldSpec<Props>[];
-  readonly attributes: (live: PaperlessRow, props: Props) => Attributes | undefined;
+  readonly createOnly?: readonly FieldSpec<Props, Live>[];
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  /** Reads the live row's owner. Required unless `owned === false` (CustomField). */
+  readonly ownerOf?: (live: Live) => number | undefined;
+  /** The generated constraint table to check each body against, by endpoint key. */
   readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
+  /** For `soleMatch`'s message and for read-back failures. */
   readonly describe: (props: Props) => string;
   /**
    * A field this object refuses to change once set — `CustomField.dataType` (custom-field.ts):
@@ -57,5 +78,17 @@ export interface MatchingSpec<
    * replace is acceptable. Return the refusal message, or `undefined` when unchanged. Checked in
    * `diff` (plan time) and again in `reconcile` (an adoption `diff` never saw).
    */
-  readonly immutable?: (live: PaperlessRow, props: Props) => string | undefined;
+  readonly immutable?: (live: Live, props: Props) => string | undefined;
+
+  /** `name__iexact` + `page_size` — wired per resource file (`listTags`, `listDocumentTypes`, …). */
+  readonly list: (props: Props) => Effect.Effect<MatchingPage<Live>, E, PaperlessNgxOpContext>;
+  /** Already folds the SDK's `NotFound` to `undefined` — each resource file's own `.pipe(Effect.catchTag('NotFound', …))`. */
+  readonly getById: (id: number) => Effect.Effect<Live | undefined, E, PaperlessNgxOpContext>;
+  readonly create: (body: PaperlessBody) => Effect.Effect<Live, E, PaperlessNgxOpContext>;
+  /** Absent would mean create-only-and-never-updated; every family here declares one. */
+  readonly update?: (
+    id: number,
+    body: PaperlessBody,
+  ) => Effect.Effect<Live, E, PaperlessNgxOpContext>;
+  readonly destroy: (id: number) => Effect.Effect<unknown, E, PaperlessNgxOpContext>;
 }