@homeflare/alchemy 0.28.0 → 0.29.1

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

package/src/paperless/matching.ts

@@ -2,7 +2,15 @@
  * One shape for every Paperless taxonomy object (Tag, DocumentType, StoragePath, CustomField):
  * locate by `name__iexact` only while there is no prior state, identify the exact (name, owner),
  * create-or-update, never delete by default. Modelled on `../netbox/resource.ts`'s
- * `netboxOperations`, with the differences this unit's spec calls for.
+ * `netboxOperations` and `../forgejo/resource.ts`'s `forgejoOperations`.
+ *
+ * 🔴 WHY THIS REPLACED `client.ts`'s HAND-ROLLED `HttpClient` CALLS (2026-09-24, decision 43).
+ *   Measured against Tim's distilled research page 2026-09-23: upstream Alchemy only accepts
+ *   providers that call `@distilled.cloud/<vendor>` operations and `catchTag` their typed errors
+ *   — not a raw `fetch`/`HttpClient` client over a hand-maintained path table.
+ *   `@distilled.cloud/paperless-ngx` (aliased onto `@homeflare/distilled-paperless-ngx@0.3.0` —
+ *   docs/distilled-interim.md) covers every operation this family calls; its 404/400 shapes were
+ *   already live-measured (kit PR 194) before this migration touched a resource file.
  *
  * ⛔ THE CREATE BODY ALWAYS CARRIES `owner`, NULL WHEN UNDECLARED. `OwnedObjectSerializer.create`
  *   sets the owner to the TOKEN USER when the field is absent from the body (Paperless-ngx
@@ -10,60 +18,38 @@
  *   omits an undeclared foreign key would silently create an object owned by whichever credential
  *   ran the deploy, invisible to every other user and a second row beside the estate's `owner:
  *   null` one on the next apply. Sending `owner: null` explicitly is what keeps a create
- *   idempotent under this vendor's default.
+ *   idempotent under this vendor's default. Unchanged by the transport swap.
  *
  * ★ READ ANSWERS `Unowned(attrs)` ON EVERY MATCH (H1, alchemy-provider-standard). Paperless has no
  *   ownership marker this package could check — `owner` here is the estate's OWN prop, not proof
  *   of who created the row — so, per the house's 2026-09-21 decision, identical is not ours: a
- *   live match never adopts silently. `--adopt` (or `adopt(true)`) resolves it, same as any other
- *   marker-less API (upstream's `Snippet.ts#read`).
+ *   live match never adopts silently.
  *
  * ⛔ IDENTITY IS THE STORED `id`, NOT `name`/`owner`, ONCE A RESOURCE HAS STATE (PR 163, red-team
- *   HIGH finding). `diff` and `reconcile` used to re-derive identity from `news` alone on EVERY
- *   call — `fetchLive` located a live row by `(name, owner)` even when `output` (the engine's
- *   record of what this declaration last wrote, `Provider.ts#reconcile`'s `output` parameter) was
- *   right there holding the object's real id. Editing `name` (or `owner`, for the three owned
- *   families) on an already-deployed resource is the single most ordinary edit anyone would make
- *   — and it made `fetchLive(news)` miss the row it previously wrote, fall into the create branch,
- *   POST a SECOND object under the new name/owner, and leave the original permanently orphaned
- *   (`list()` always answers `[]` by design, so `nuke` can never find it either). `diff` reported
- *   a plain `{action:'update'}` — nothing told the operator this was about to duplicate and
- *   abandon an object.
- *
- *   The fix: once `output` is defined, `fetchLive` locates by `output.id` (a direct
- *   `GET {collection}/{id}/`), never by name — a changed `name`/`owner` becomes an ordinary PATCH
- *   of that same id (Paperless allows PATCHing both on all four types; documents keep their
- *   tag/type/path because the id never changes). `patchBody`/`matches` now compare `name` and
- *   (when `spec.owned !== false`) `owner` against the live row too, so the rename/re-own actually
- *   reaches the PATCH body — locating the right row was necessary but not sufficient. The
- *   name/owner-based `fetchByName` locate survives ONLY for the no-state path: a genuine first
- *   create, or the engine's own adoption probe (`provider.read`, called with `output: undefined`
- *   per `Plan.ts`'s adopt block) — `read` is unchanged and still locates by name for exactly that
- *   reason. If `output.id` no longer exists live (deleted out of band — by hand, or by another
- *   tool), `fetchLive` refuses loudly (`Effect.die`) rather than silently falling through to a
- *   create: a plan that would otherwise read as "ordinary update" instead names the id and tells
- *   the operator to adopt or clean up state, the same posture `immutable` already uses below for
- *   `CustomField.dataType`.
+ *   HIGH finding — see `matching-locate.ts`'s `fetchLive` for the fix and the full history). This
+ *   migration keeps that fix byte-for-byte: only the wire call under `fetchByName`/`fetchById`
+ *   changed, not the switch itself.
  */
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/paperless-ngx/Credentials';
+import type { PaperlessNgxOpContext } from '@distilled.cloud/paperless-ngx/Protocol';
 import * as Effect from 'effect/Effect';
-import type { PaperlessRow } from './client.ts';
-import { paperless } from './client.ts';
 import { guardBody } from './constraint-guard.ts';
 import type { PaperlessBody } from './constraints.ts';
-import { absentOn404, matchingLocate, ownerOf } from './matching-locate.ts';
+import { fetchLive as identitySwitch, locateOne } from './matching-locate.ts';
 import type { MatchingProps, MatchingSpec } from './matching-types.ts';
 
 /** Re-exported so `tag.ts`/`document-type.ts`/`storage-path.ts`/`custom-field.ts` keep importing the contract from `./matching.ts` — only the shape itself lives in `matching-types.ts`, split out to hold the file-size cap. */
 export type {
   FieldSpec,
-  MatchingError,
+  MatchingPage,
   MatchingProps,
   MatchingRequirements,
   MatchingSpec,
 } from './matching-types.ts';
+export { LOCATE_PAGE, soleMatch } from './matching-locate.ts';
 
 /** Object equality good enough for this family's scalars, nullable ints and `extra_data` JSON. */
 const sameValue = (a: unknown, b: unknown): boolean =>
@@ -71,15 +57,35 @@ const sameValue = (a: unknown, b: unknown): boolean =>
 
 export const matchingOperations = <
   Props extends MatchingProps,
+  Live extends { readonly id: number; readonly name: string },
   Attributes extends { readonly id: number },
+  E,
 >(
-  spec: MatchingSpec<Props, Attributes>,
+  spec: MatchingSpec<Props, Live, Attributes, E>,
 ) => {
-  // ★ IDENTITY RESOLUTION LIVES IN `matching-locate.ts` (file-size cap) — `fetchByName` for the
-  //   no-state path, `fetchLive` for the `output.id`-first switch this file's header describes.
-  const { fetchByName, fetchById, fetchLive, objectPath } = matchingLocate<Props>(spec);
+  const ownerOf = (live: Live): number | undefined =>
+    spec.owned === false || spec.ownerOf === undefined ? undefined : spec.ownerOf(live);
+
+  const ownerMatches = (live: Live, props: Props): boolean =>
+    spec.owned === false || spec.ownerOf === undefined
+      ? true
+      : spec.ownerOf(live) === (props.owner ?? undefined);
+
+  /** ★ THE NO-STATE LOCATE — see matching-locate.ts's `locateOne` and this file's own header. */
+  const fetchByName = (props: Props) =>
+    locateOne(
+      spec.list(props),
+      spec.describe(props),
+      (row) => row.name === props.name && ownerMatches(row, props),
+    );
 
-  /** ⚠️ ALWAYS NAME-BASED — this is `read`'s own contract (S7): find the object from props alone, with no `output` to consult. Unaffected by the identity switch above. */
+  /** Already folds a 404 — each resource file's own `.pipe(Effect.catchTag('NotFound', …))`. */
+  const fetchById = spec.getById;
+
+  const fetchLive = (props: Props, output: Attributes | undefined) =>
+    identitySwitch(props, output, fetchByName, fetchById, spec.describe);
+
+  /** ⚠️ ALWAYS NAME-BASED — this is `read`'s own contract (S7): find the object from props alone, with no `output` to consult. */
   const read = (props: Props) =>
     fetchByName(props).pipe(
       Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
@@ -102,17 +108,10 @@ export const matchingOperations = <
     return out;
   };
 
-  /**
-   * ⚠️ Only fields that DIFFER from the live row — a PATCH that repeats an unchanged value is
-   *   still a write the audit log carries for nothing.
-   * ⛔ `name` AND (WHEN OWNED) `owner` ARE COMPARED TOO, NOT JUST `spec.fields`. Locating the
-   *   right row by `id` fixed WHERE the write lands; without this, a rename/re-own would still
-   *   locate correctly and then send an empty-for-those-keys PATCH, so the live object's name or
-   *   owner would silently never change (PR 163).
-   */
-  const patchBody = (props: Props, live: PaperlessRow): PaperlessBody => {
+  /** ⚠️ Only fields that DIFFER from the live row. `name`/`owner` are compared too (PR 163). */
+  const patchBody = (props: Props, live: Live): PaperlessBody => {
     const out: PaperlessBody = {};
-    if (props.name !== live['name']) out['name'] = props.name;
+    if (props.name !== live.name) out['name'] = props.name;
     if (spec.owned !== false && ownerOf(live) !== (props.owner ?? undefined)) {
       out['owner'] = props.owner ?? null;
     }
@@ -123,8 +122,8 @@ export const matchingOperations = <
     return out;
   };
 
-  const matches = (props: Props, live: PaperlessRow): boolean => {
-    if (props.name !== live['name']) return false;
+  const matches = (props: Props, live: Live): boolean => {
+    if (props.name !== live.name) return false;
     if (spec.owned !== false && ownerOf(live) !== (props.owner ?? undefined)) return false;
     return spec.fields.every((field) => {
       const value = field.prop(props);
@@ -143,7 +142,7 @@ export const matchingOperations = <
         const refusal = spec.immutable?.(live, news);
         if (refusal !== undefined) return yield* Effect.die(new Error(refusal));
         if (matches(news, live)) return { action: 'noop' } as const;
-        return spec.endpoint.update === undefined
+        return spec.update === undefined
           ? ({ action: 'replace' } as const)
           : ({ action: 'update' } as const);
       }),
@@ -155,25 +154,19 @@ export const matchingOperations = <
         if (before === undefined) {
           const body = createBody(news);
           yield* guardBody(spec.endpoint.create, body, true);
-          yield* paperless('POST', `${spec.collection}/`, body);
+          yield* spec.create(body);
         } else {
-          id = typeof before['id'] === 'number' ? before['id'] : undefined;
-          // ⚠️ RE-CHECKED HERE, NOT ONLY IN `diff` — an adoption's first reconcile can run with
-          //   no prior `diff` at all, and `immutable` guards a write that would destroy data.
+          id = before.id;
           const refusal = spec.immutable?.(before, news);
           if (refusal !== undefined) return yield* Effect.die(new Error(refusal));
-          if (spec.endpoint.update !== undefined) {
+          if (spec.update !== undefined) {
             const body = patchBody(news, before);
             if (Object.keys(body).length > 0) {
               yield* guardBody(spec.endpoint.update, body, false);
-              yield* paperless('PATCH', `${objectPath(before)}/`, body);
+              yield* spec.update(id, body);
             }
           }
         }
-        // ★ READ BACK BY id WHEN WE HAVE ONE — a just-PATCHed row is read back by the id we
-        //   wrote to, not by (possibly just-changed) name, so a rename's own read-back cannot
-        //   fail the way the write it follows no longer can either. A fresh create has no id yet
-        //   to read back by, so that branch still reads back by the name it just created.
         const after = yield* id === undefined ? read(news) : readById(news, id);
         if (after === undefined) {
           return yield* Effect.die(
@@ -185,55 +178,49 @@ export const matchingOperations = <
         return after;
       }),
 
-    /**
-     * ⛔ `output.id` FIRST, SAME SWITCH AS `fetchLive` (PR 163 re-review). The engine always
-     *   passes `output` here too (`Apply.ts`'s delete call sites all carry `output: attr`) —
-     *   `olds` is only the PROPS as last persisted, which drifts from the live object exactly
-     *   the way `news` did pre-fix: rename it out of band (by hand, or by another tool) after
-     *   the last successful reconcile, and a name-only locate silently finds nothing, `destroy`
-     *   returns as if there were nothing to delete, and the engine drops the state row anyway —
-     *   reporting "deleted" while the live object survives, permanently orphaned (the same
-     *   consequence `matching.ts`'s header describes for the original bug, on the delete path
-     *   the original fix didn't touch). A 404 on the `output.id` itself is NOT an error here,
-     *   unlike `fetchLive`'s die — it means the object is already gone, which is exactly the
-     *   idempotent success `delete` is supposed to report (S11, alchemy-provider-standard).
-     */
+    /** ⛔ `output.id` FIRST, SAME SWITCH AS `fetchLive` (PR 163 re-review). A 404 on `output.id` is idempotent success, not an error, unlike `fetchLive`'s die. */
     destroy: (olds: Props, output: Attributes | undefined) =>
       Effect.gen(function* () {
         const live = output === undefined ? yield* fetchByName(olds) : yield* fetchById(output.id);
         if (live === undefined) return;
-        yield* absentOn404(paperless('DELETE', `${objectPath(live)}/`));
+        yield* spec.destroy(live.id);
       }),
   };
 };
 
-/** The five provider handlers for a spec'd Paperless taxonomy object, wired once. */
+/**
+ * The five provider handlers for a spec'd Paperless taxonomy object, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE, NOT BY EVERY CALLER — the same shape
+ *   `netboxHandlers`/`forgejoHandlers` use. `CredentialsFromEnv` resolves `PAPERLESS_URL` /
+ *   `PAPERLESS_TOKEN` on the calling fiber per request, so this closure keeps that laziness —
+ *   nothing is captured at module load. ⛔ THE TOKEN IS NEVER A PROP.
+ */
 export const matchingHandlers = <
   Props extends MatchingProps,
+  Live extends { readonly id: number; readonly name: string },
   Attributes extends { readonly id: number },
+  E,
 >(
-  spec: MatchingSpec<Props, Attributes>,
+  spec: MatchingSpec<Props, Live, Attributes, E>,
 ) => {
   const ops = matchingOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, PaperlessNgxOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
   return {
     /** ⚠️ `[]` — Paperless index endpoints return the whole estate; adoption stays explicit. */
     list: () => Effect.succeed([]),
     read: ({ olds }: { olds: Props }) =>
-      ops
-        .read(olds)
-        .pipe(Effect.map((attrs) => (attrs === undefined ? undefined : Unowned(attrs)))),
+      withCredentials(
+        ops
+          .read(olds)
+          .pipe(Effect.map((attrs) => (attrs === undefined ? undefined : Unowned(attrs)))),
+      ),
     diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
-      ops.diff(news, output),
-    // ⛔ `output` IS WHAT MAKES THE IDENTITY FIX WORK (PR 163) — the engine always passes it
-    //   (`Provider.ts#reconcile`), so it is optional here only so a test can still call
-    //   `reconcile({ news })` for a from-nothing create without spelling out `output: undefined`.
-    //   ⚠️ `| undefined` on the optional type itself, not just `?` — `exactOptionalPropertyTypes`
-    //   otherwise refuses the engine's own `output: Attributes | undefined` at the call site.
+      withCredentials(ops.diff(news, output)),
     reconcile: ({ news, output }: { news: Props; output?: Attributes | undefined }) =>
-      ops.reconcile(news, output),
-    // ⚠️ `output` PASSED THROUGH, NOT DROPPED — see `destroy`'s own header above (PR 163
-    //   re-review). Same `| undefined` reasoning as `reconcile` just above.
+      withCredentials(ops.reconcile(news, output)),
     delete: ({ olds, output }: { olds: Props; output?: Attributes | undefined }) =>
-      ops.destroy(olds, output),
+      withCredentials(ops.destroy(olds, output)),
   };
 };

package/src/paperless/providers.ts

@@ -1,27 +1,31 @@
 /**
- * All four Paperless taxonomy providers, one credentials layer shared between them.
+ * All four Paperless taxonomy providers.
  *
  *     Layer.mergeAll(paperlessProviders(), …the stack's other providers)
  *
  * ⚠️ `HttpClient.HttpClient` IS NOT BUNDLED HERE, and that follows `../netbox/index.ts` and
- *   `../forgejo/client.ts`'s own precedent (its header: "the idiom Alchemy's own providers
- *   follow — `Hetzner/Providers.ts` builds on `FetchHttpClient.layer`") rather than diverging
- *   from it: the transport is the consuming STACK's choice (`FetchHttpClient.layer` in
- *   production, a fake `HttpClient` in a test), not a house default a provider file should pin.
+ *   `../forgejo/client.ts`'s own precedent: the transport is the consuming STACK's choice
+ *   (`FetchHttpClient.layer` in production, a fake `HttpClient` in a test), not a house default a
+ *   provider file should pin.
+ *
+ * 🔴 NO `credentials` PARAMETER ANY MORE (2026-09-24, the `@distilled.cloud/paperless-ngx`
+ *   migration — see `matching.ts`'s header). Each of the four `xxxProvider()`s now bakes in
+ *   `CredentialsFromEnv` itself, the same way `netboxHandlers`/`forgejoHandlers` do — there is no
+ *   longer a layer for this file to merge in or accept an override for. Nothing in this estate
+ *   called `paperlessProviders(customLayer)` (measured 2026-09-24: no tray repo declares a
+ *   Paperless resource at all — grep across `homeflare-landscape`'s tray repos' `origin/main`),
+ *   so this is an uneventful simplification, not a behaviour change for anything live.
  */
 import * as Layer from 'effect/Layer';
 import { CustomFieldProvider } from './custom-field.ts';
 import { DocumentTypeProvider } from './document-type.ts';
-import { type PaperlessCredentials, environmentLayer } from './credentials.ts';
 import { StoragePathProvider } from './storage-path.ts';
 import { TagProvider } from './tag.ts';
 
-export const paperlessProviders = (
-  credentials: Layer.Layer<PaperlessCredentials> = environmentLayer,
-) =>
+export const paperlessProviders = () =>
   Layer.mergeAll(
     TagProvider(),
     DocumentTypeProvider(),
     StoragePathProvider(),
     CustomFieldProvider(),
-  ).pipe(Layer.provide(credentials));
+  );

package/src/paperless/storage-path.test.ts

@@ -0,0 +1,56 @@
+/**
+ * `StoragePath`'s exported production `spec` against a fake Paperless-ngx — proves this file's
+ * own `@distilled.cloud/paperless-ngx/storage_paths` wiring (right operations, right field names,
+ * including the vendor-required `path` template) round-trips for real. See document-type.test.ts
+ * and tag.ts's own header for why the shared engine and PR 163 are not re-proven here.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakePaperless, run } from './fake-paperless.ts';
+import { matchingOperations } from './matching.ts';
+import { spec } from './storage-path.ts';
+
+const ops = matchingOperations(spec);
+
+test('create sends the required path field alongside owner: null', async () => {
+  const fake = fakePaperless();
+  await run(
+    ops.reconcile({ name: 'By correspondent', path: '{correspondent}/{title}' }, undefined),
+    fake.fetch,
+  );
+  const post = fake.seen.find((s) => s.method === 'POST');
+  expect(JSON.parse(post?.body ?? '{}')).toMatchObject({
+    name: 'By correspondent',
+    owner: null,
+    path: '{correspondent}/{title}',
+  });
+});
+
+describe('a full create → read → patch → delete round trip', () => {
+  test('the real distilled wire path carries the path template through a rename', async () => {
+    const fake = fakePaperless();
+    const created = await run(
+      ops.reconcile({ name: 'By correspondent', path: '{correspondent}/{title}' }, undefined),
+      fake.fetch,
+    );
+    expect(created).toMatchObject({ name: 'By correspondent', path: '{correspondent}/{title}' });
+
+    const after = await run(
+      ops.reconcile({ name: 'By correspondent', path: '{correspondent}/{created}' }, created),
+      fake.fetch,
+    );
+    const patch = fake.seen.find((s) => s.method === 'PATCH');
+    expect(JSON.parse(patch?.body ?? '{}')).toEqual({ path: '{correspondent}/{created}' });
+    expect(after?.path).toBe('{correspondent}/{created}');
+
+    await run(
+      ops.destroy({ name: 'By correspondent', path: '{correspondent}/{created}' }, after),
+      fake.fetch,
+    );
+    expect(fake.rows('storage_paths').length).toBe(0);
+  });
+});
+
+test('a 404 on read folds to absent', async () => {
+  const fake = fakePaperless();
+  expect(await run(ops.read({ name: 'Nothing here', path: 'x' }), fake.fetch)).toBeUndefined();
+});

package/src/paperless/storage-path.ts

@@ -1,16 +1,24 @@
 /**
  * `Paperless.StoragePath` — a Paperless-ngx storage path template, create-or-update and never
- * deleted. Same shape as `document-type.ts` plus the vendor-required `path` template string.
+ * deleted. Same shape as `document-type.ts` plus the vendor-required `path` template string; see
+ * `tag.ts`'s header for the 2026-09-24 transport migration this file follows exactly.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as storagePaths from '@distilled.cloud/paperless-ngx/storage_paths';
 import * as Effect from 'effect/Effect';
 import type { PaperlessStoragePathRequest } from './generated/types/storage-paths.ts';
-import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+import {
+  LOCATE_PAGE,
+  type MatchingRequirements,
+  type MatchingSpec,
+  matchingHandlers,
+} from './matching.ts';
 
-export interface StoragePathProps extends MatchingProps {
+export interface StoragePathProps {
   /** ⚠️ maxLength 128 (generated constraint table). The locate key. */
   name: string;
+  owner?: number;
   /** ⚠️ minLength 1 (generated table). Paperless's storage-path template syntax, e.g. `{correspondent}/{title}`. */
   path: string;
   /** ⚠️ maxLength 256. */
@@ -41,38 +49,59 @@ export const StoragePath = Resource<StoragePath>('Paperless.StoragePath', {
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = matchingHandlers<StoragePathProps, StoragePathAttributes>({
-  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,
-      path: typeof live['path'] === 'string' ? live['path'] : props.path,
-    };
-  },
-  collection: 'storage_paths',
+/** ★ Exported for direct testing — see tag.ts's own note on this seam. */
+export const spec: MatchingSpec<
+  StoragePathProps,
+  storagePaths.StoragePath,
+  StoragePathAttributes,
+  | storagePaths.CreateStoragePathError
+  | storagePaths.GetStoragePathError
+  | storagePaths.ListStoragePathsError
+  | storagePaths.UpdateStoragePathsPartialError
+  | storagePaths.StoragePathsDestroyError
+> = {
+  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,
+    path: live.path,
+  }),
+  create: (body) =>
+    storagePaths.createStoragePath(body as unknown as storagePaths.CreateStoragePathRequest),
   describe: (props) => `storage_paths ${props.name}`,
+  destroy: (id) => storagePaths.storagePathsDestroy({ id }),
   endpoint: {
     create: 'paperless:POST /api/storage_paths/',
     update: 'paperless:PATCH /api/storage_paths/{id}/',
   },
   fields: [
-    { key: 'path', live: (r) => r['path'], prop: (p) => p.path },
-    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    { key: 'path', live: (r) => r.path, prop: (p) => p.path },
+    { 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) =>
+    storagePaths
+      .getStoragePath({ id })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  list: (props) =>
+    storagePaths.listStoragePaths({ name__iexact: props.name, page_size: LOCATE_PAGE }),
+  ownerOf: (live) => live.owner ?? undefined,
+  update: (id, body) =>
+    storagePaths.updateStoragePathsPartial({
+      ...(body as unknown as Omit<storagePaths.UpdateStoragePathsPartialRequest, 'id'>),
+      id,
+    }),
+};
+
+export const handlers = matchingHandlers(spec);
 
 export const StoragePathProvider = () =>
   Provider.effect(StoragePath, Effect.succeed(StoragePath.Provider.of(handlers)));