@homeflare/alchemy 0.28.0 → 0.29.0

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

package/src/paperless/tag-identity.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Regression suite for the PR 163 red-team HIGH finding, re-proved against
+ * `@distilled.cloud/paperless-ngx`'s real wire path: `diff`/`reconcile` re-derived identity from
+ * `news` alone on every call, so renaming (or re-owning) an already-deployed Tag missed the row
+ * it previously wrote, POSTed a second object under the new name/owner, and left the original
+ * permanently orphaned — while `diff` reported a plain `{action:'update'}`. See `matching.ts`'s
+ * header and `matching-locate.ts`'s `fetchLive` for the fix: once `output` is defined, identity
+ * is `output.id`, not `(name, owner)`.
+ *
+ * "Someone else changed the live row out of band" is simulated with the SDK's own
+ * `tags.updateTagsPartial`/`tags.tagsDestroy` against the fake, not an internal escape hatch —
+ * this package no longer has one after the `client.ts` removal, and calling the real production
+ * functions is the more faithful simulation anyway.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as tags from '@distilled.cloud/paperless-ngx/tags';
+import { fakePaperless, run } from './fake-paperless.ts';
+import { matchingOperations } from './matching.ts';
+import { spec } from './tag.ts';
+
+const ops = matchingOperations(spec);
+const writesOf = (fake: { seen: readonly { method: string }[] }) =>
+  fake.seen.filter((s) => s.method !== 'GET');
+
+describe('renaming or re-owning an already-deployed object (PR 163)', () => {
+  test('a rename PATCHes the same id — no POST, no orphan', async () => {
+    const fake = fakePaperless();
+    const created = await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    const before = writesOf(fake).length;
+
+    const renamed = await run(ops.reconcile({ name: 'Invoices - Renamed' }, created), fake.fetch);
+
+    const writes = writesOf(fake);
+    expect(writes.length).toBe(before + 1);
+    expect(writes.slice(before).every((w) => w.method === 'PATCH')).toBe(true);
+    expect(fake.rows('tags').length).toBe(1);
+    expect(renamed?.id).toBe(created?.id);
+    expect(renamed?.name).toBe('Invoices - Renamed');
+  });
+
+  test('an owner change PATCHes the same id — no POST, no orphan', async () => {
+    const fake = fakePaperless();
+    const created = await run(ops.reconcile({ name: 'Invoices', owner: 7 }, undefined), fake.fetch);
+    const before = writesOf(fake).length;
+
+    const reowned = await run(ops.reconcile({ name: 'Invoices', owner: 9 }, created), fake.fetch);
+
+    expect(writesOf(fake).length).toBe(before + 1);
+    expect(fake.rows('tags').length).toBe(1);
+    expect(reowned?.id).toBe(created?.id);
+    expect(reowned?.owner).toBe(9);
+  });
+});
+
+describe('a deleted-out-of-band object (PR 163)', () => {
+  test('diff refuses at plan rather than creating a replacement', async () => {
+    const fake = fakePaperless();
+    const created = await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    if (created === undefined) throw new Error('unreachable: reconcile always returns attrs');
+    await run(tags.tagsDestroy({ id: created.id }), fake.fetch);
+
+    await expect(run(ops.diff({ name: 'Invoices' }, created), fake.fetch)).rejects.toThrow(
+      /no longer exists live|deleted out of band/,
+    );
+    expect(fake.rows('tags').length).toBe(0);
+  });
+
+  test('reconcile also refuses, not only diff, if called with no prior diff', async () => {
+    const fake = fakePaperless();
+    const created = await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    if (created === undefined) throw new Error('unreachable: reconcile always returns attrs');
+    await run(tags.tagsDestroy({ id: created.id }), fake.fetch);
+
+    await expect(run(ops.reconcile({ name: 'Invoices' }, created), fake.fetch)).rejects.toThrow(
+      /no longer exists live|deleted out of band/,
+    );
+  });
+});
+
+describe('the no-state path is unaffected (PR 163)', () => {
+  test('a first create still locates by name', async () => {
+    const fake = fakePaperless();
+    await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+
+    const get = fake.seen.find((s) => s.method === 'GET');
+    expect(get?.path).toContain('name__iexact=Invoices');
+    expect(fake.seen.find((s) => s.method === 'POST')).toBeDefined();
+  });
+
+  test("adopt (output from the engine's own read) locates the id it read, no duplicate", async () => {
+    const fake = fakePaperless();
+    // A pre-existing object, created out of band — what `provider.read` (always called with
+    // `output: undefined`) discovers during its adoption probe.
+    await run(tags.createTag({ name: 'Invoices', owner: null }), fake.fetch);
+    const readAttrs = await run(ops.read({ name: 'Invoices' }), fake.fetch);
+    if (readAttrs === undefined) throw new Error('unreachable: asserted defined above');
+
+    const after = await run(ops.reconcile({ name: 'Invoices' }, readAttrs), fake.fetch);
+
+    expect(fake.rows('tags').length).toBe(1);
+    expect(after?.id).toBe(readAttrs.id);
+    expect(fake.seen.filter((s) => s.method === 'POST').length).toBe(1);
+  });
+});
+
+describe('delete locates by output.id, not by (possibly stale) olds.name (re-review)', () => {
+  test('a row renamed out of band is still found and deleted, by id', async () => {
+    const fake = fakePaperless();
+    const created = await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    if (created === undefined) throw new Error('unreachable: reconcile always returns attrs');
+
+    await run(tags.updateTagsPartial({ id: created.id, name: 'Renamed Elsewhere' }), fake.fetch);
+    await run(ops.destroy({ name: 'Invoices' }, created), fake.fetch);
+
+    expect(fake.rows('tags').length).toBe(0);
+    const deletes = fake.seen.filter((s) => s.method === 'DELETE');
+    expect(deletes.length).toBe(1);
+    expect(deletes[0]?.path).toBe(`/api/tags/${String(created.id)}/`);
+  });
+
+  test('with no output (no-state path), delete still falls back to locating by name', async () => {
+    const fake = fakePaperless();
+    await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    await run(ops.destroy({ name: 'Invoices' }, undefined), fake.fetch);
+    expect(fake.rows('tags').length).toBe(0);
+  });
+});