@homeflare/alchemy 0.28.0 → 0.29.0

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