@homeflare/alchemy 0.27.3 → 0.27.4

package/src/netbox/prefix.ts

@@ -28,13 +28,22 @@
  *   IP assignments; the record of why it existed survives only in the change log.
  *
  * ⛔ NO CREDENTIAL IS A PROP. `NETBOX_URL` and `NETBOX_TOKEN` are read from the environment at
- *   call time — the house convention, and the only shape that keeps a token out of Alchemy state.
+ *   call time, through `@distilled.cloud/netbox`'s `CredentialsFromEnv` (resource.ts) — the house
+ *   convention, and the only shape that keeps a token out of Alchemy state. Unchanged by this
+ *   migration off `client.ts`'s hand-rolled `HttpClient` calls onto distilled's typed operations.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as ipam from '@distilled.cloud/netbox/ipam';
 import * as Effect from 'effect/Effect';
 import { prefixBody, prefixMatches } from './prefix-form.ts';
-import { type NetboxRequirements, netboxHandlers } from './resource.ts';
+import {
+  LOCATE_PAGE,
+  type NetboxRequirements,
+  type NetboxSpec,
+  locateOne,
+  netboxHandlers,
+} from './resource.ts';
 import { choice, fk, text } from './values.ts';
 
 /**
@@ -92,45 +101,72 @@ export const NetboxPrefix = Resource<NetboxPrefix>('Netbox.Prefix', {
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = netboxHandlers<PrefixProps, PrefixAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      comments: text(live['comments']),
-      description: text(live['description']),
-      isPool: live['is_pool'] === true,
-      markUtilized: live['mark_utilized'] === true,
-      prefix: text(live['prefix']) || props.prefix,
-      prefixId: id,
-      status: choice(live['status']),
-      tenant: fk(live['tenant']),
-      vlan: fk(live['vlan']),
-      vrf: fk(live['vrf']),
-    };
-  },
-  collection: 'ipam/prefixes',
+const attributesOf = (live: ipam.Prefix, props: PrefixProps): PrefixAttributes => ({
+  comments: text(live.comments),
+  description: text(live.description),
+  isPool: live.is_pool === true,
+  markUtilized: live.mark_utilized === true,
+  prefix: live.prefix || props.prefix,
+  prefixId: live.id,
+  status: choice(live.status),
+  tenant: fk(live.tenant),
+  vlan: fk(live.vlan),
+  vrf: fk(live.vrf),
+});
+
+/**
+ * ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see
+ *   `fake-netbox.ts`/`prefix.test.ts`, the same seam `../forgejo/repository.ts` uses.
+ */
+export const spec: NetboxSpec<
+  PrefixProps,
+  ipam.Prefix,
+  PrefixAttributes,
+  | ipam.CreateIpamPrefixError
+  | ipam.ListIpamPrefixesError
+  | ipam.UpdateIpamPrefixesPartialError
+  | ipam.IpamPrefixesDestroyError
+> = {
+  attributes: attributesOf,
+  create: (_props, body) =>
+    ipam.createIpamPrefix({ body: body as unknown as ipam.WritablePrefixRequest }),
   createBody: prefixBody,
+  destroy: (_props, live) => ipam.ipamPrefixesDestroy({ id: live.id }),
   describe: (props) => `ipam/prefixes ${props.prefix}`,
   endpoint: {
     create: 'netbox:POST /api/ipam/prefixes/',
     update: 'netbox:PATCH /api/ipam/prefixes/{id}/',
   },
   /**
-   * 🔴 THE VRF IS **NOT** IN THIS FILTER, AND THE REASON IS A GUESS THAT WAS CAUGHT. This read
-   *   `vrf_id=null` for the global table — NetBox does define `FILTERS_NULL_CHOICE_VALUE = 'null'`
-   *   and does honour it on filters that opt in. ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at
-   *   v4.7.0: `PrefixFilterSet.vrf_id` is a plain `django_filters.ModelMultipleChoiceFilter` with
-   *   no `null_value`, so `'null'` is validated against the VRF queryset, fails, and NetBox
-   *   answers 400 under strict filtering — on EVERY plan for EVERY global prefix.
-   * ★ So the CIDR narrows server-side with a filter the document plainly declares, and `identifies`
-   *   picks the VRF in this process. One extra page of candidates, no vendor semantics guessed.
+   * 🔴 THE VRF IS **NOT** IN THIS SERVER-SIDE FILTER, AND THE REASON IS A GUESS THAT WAS CAUGHT.
+   *   An earlier version filtered `vrf_id=null` for the global table — NetBox does define
+   *   `FILTERS_NULL_CHOICE_VALUE = 'null'` and does honour it on filters that opt in. ⛔ MEASURED
+   *   IN THE VENDOR'S OWN SOURCE at v4.7.0: `PrefixFilterSet.vrf_id` is a plain
+   *   `django_filters.ModelMultipleChoiceFilter` with NO `null_value`, so `'null'` is validated
+   *   against the VRF queryset, fails, and NetBox answers 400 under strict filtering. The
+   *   sentinel is real but it is opt-in per filter, and this one did not opt in.
+   * ★ SO THE DISCRIMINATOR STAYS IN THIS PROCESS, VIA `locateOne`'s `identifies` — one extra page
+   *   of candidates, no vendor semantics guessed. `listIpamPrefixes` never declares `NotFound`
+   *   (a list call 200s with an empty page, it does not 404), so there is no status to fold here.
    */
-  identifies: (live, props) => fk(live['vrf']) === props.vrf,
-  locate: (props) => [['prefix', props.prefix]],
+  fetchLive: (props) =>
+    locateOne(
+      ipam.listIpamPrefixes({ limit: LOCATE_PAGE, prefix: [props.prefix] }),
+      `ipam/prefixes ${props.prefix}`,
+      (row) => fk(row.vrf) === props.vrf,
+    ),
   matches: prefixMatches,
-  updateBody: prefixBody,
-});
+  update: {
+    body: prefixBody,
+    call: (_props, live, body) =>
+      ipam.updateIpamPrefixesPartial({
+        ...(body as unknown as Omit<ipam.UpdateIpamPrefixesPartialRequest, 'id'>),
+        id: live.id,
+      }),
+  },
+};
+
+export const handlers = netboxHandlers(spec);
 
 export const NetboxPrefixProvider = () =>
   Provider.effect(NetboxPrefix, Effect.succeed(NetboxPrefix.Provider.of(handlers)));

package/src/netbox/resource.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `soleMatch` and `locateOne` — identity resolution, and the two ways it must refuse. Pure/Effect
+ * only (no HTTP): `locateOne` takes an already-built list `Effect`, so these run against
+ * `Effect.succeed` fixtures rather than a fake server — `prefix.test.ts` exercises the real
+ * distilled wire path this feeds from.
+ *
+ * ⛔ THE FAILURE THIS 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 — while "fixing" it PATCHed one object with the other's
+ *   declaration. Failing loudly is the only outcome an operator can act on. Ported verbatim from
+ *   the pre-migration `client.test.ts`, which tested the same `soleMatch` before it moved here.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { LOCATE_PAGE, locateOne, soleMatch } from './resource.ts';
+
+describe('soleMatch', () => {
+  test('no candidate is absent, not an error — that is what plans a create', () => {
+    expect(soleMatch([], 'ipam/prefixes 10.0.0.0/24')).toBeUndefined();
+  });
+
+  test('exactly one candidate is the object', () => {
+    expect(soleMatch([{ id: 7 }], 'ipam/prefixes 10.0.0.0/24')).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 }], 'ipam/prefixes 10.0.0.0/24')).toThrow(
+      /ipam\/prefixes 10\.0\.0\.0\/24 matched 2 NetBox objects/,
+    );
+  });
+});
+
+describe('locateOne', () => {
+  const page = (count: number, results: readonly { id: number; vrf?: number }[]) =>
+    Effect.succeed({ count, results });
+
+  test('an empty page is absent', async () => {
+    const result = await Effect.runPromise(locateOne(page(0, []), 'ipam/prefixes 10.0.0.0/24'));
+    expect(result).toBeUndefined();
+  });
+
+  test('one row with no `identifies` narrowing is the object', async () => {
+    const result = await Effect.runPromise(
+      locateOne(page(1, [{ id: 7 }]), 'ipam/prefixes 10.0.0.0/24'),
+    );
+    expect(result).toEqual({ id: 7 });
+  });
+
+  test('`identifies` narrows several server-side matches to the declared one', async () => {
+    const rows = [
+      { id: 7, vrf: 1 },
+      { id: 8, vrf: 2 },
+    ];
+    const result = await Effect.runPromise(
+      locateOne(page(2, rows), 'ipam/prefixes 10.0.0.0/24', (row) => row.vrf === 2),
+    );
+    expect(result).toEqual({ id: 8, vrf: 2 });
+  });
+
+  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 }));
+    await expect(
+      Effect.runPromise(locateOne(page(LOCATE_PAGE + 1, rows), 'ipam/prefixes 10.0.0.0/24')),
+    ).rejects.toThrow(/matched 21 rows, more than the 20-row page/);
+  });
+});

package/src/netbox/resource.ts

@@ -1,134 +1,146 @@
 /**
- * One shape for every NetBox object — the same four operations, different path and JSON body.
+ * One shape for every NetBox object — the same four operations, different distilled call.
  *
  * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Prefixes, VLANs, devices, tenants
- *   and interfaces are all create / read / update / delete over `/api` with JSON bodies and a
- *   numeric primary key. Hand-rolling the fourth copy is where someone drops the read-back or the
+ *   and interfaces are all create / read / update / delete against `@distilled.cloud/netbox`'s
+ *   typed operations. Hand-rolling the fourth copy is where someone drops the read-back or the
  *   constraint guard and the plan lies.
  *
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE — mirroring `../forgejo/resource.ts`'s engine exactly,
+ *   plus the constraint-guard wiring every NetBox write already had (guardBody, unchanged).
+ *
+ * 🔴 WHY THIS REPLACED `client.ts`'s HAND-ROLLED `HttpClient` CALLS. 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/netbox`
+ *   (published as `@homeflare/distilled-netbox@0.2.0`, aliased in — see
+ *   `docs/distilled-interim.md`) covers every operation this family calls.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the
+ *   direct successor to the old, centralized `absentOn404`, and the same split `../forgejo/resource.ts`
+ *   uses. `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. A
+ *   NetBox *list* call (what `locateOne` below wraps) never 404s — narrowing happens by an empty
+ *   `results` page, not a status code — so nothing here folds a status at all.
+ *
  * ★ ADOPT IS THE DEFAULT POSTURE, NOT A FLAG. `reconcile` LOCATES before it writes: an object the
  *   estate already has is bound, not duplicated. NetBox is a record that predates this code by
  *   years; a provider that created a second `10.20.10.0/24` on first deploy would be worse than
  *   no provider.
  *
- * ★ `defaultRemovalPolicy: 'retain'` ON EVERY FAMILY. NetBox holds the estate's record of what
- *   the network was DECIDED to be, and deleting a row deletes history — child prefixes reparent,
- *   IP assignments detach, and the change log is the only trace left. `retain` means the engine
- *   skips `delete` when a resource is orphaned unless the caller opts into
- *   `.pipe(RemovalPolicy.destroy())`. The `delete` handler is FULLY IMPLEMENTED anyway: a stub
- *   that silently does nothing lies to whoever reads the plan.
+ * ★ `defaultRemovalPolicy: 'retain'` ON EVERY FAMILY — declared per resource file (prefix.ts),
+ *   same as before this migration.
  */
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/netbox/Credentials';
+import type { NetboxOpContext } from '@distilled.cloud/netbox/Protocol';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { NetboxError, type NetboxList, type NetboxRow, netbox, soleMatch } from './client.ts';
 import { guardBody } from './constraint-guard.ts';
 import type { EndpointKey, NetboxBody } from './constraints.ts';
 
 /**
- * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME, AND NOTHING MORE. The token comes from
- *   `NETBOX_TOKEN` in the environment, so there is no process to spawn and no `bao` to shell out
- *   to. Declaring a service you never use is not harmless — it makes a stack provide a layer for
- *   nothing, and it hides the one service you DO need.
+ * ★ WHAT EVERY HANDLER NEEDS FROM THE CALLER'S RUNTIME, after Credentials are provided below.
+ *   `Netbox.NetboxOpContext` is `Credentials | HttpClient.HttpClient`; `netboxHandlers` closes
+ *   over `CredentialsFromEnv` itself (`NETBOX_URL` / `NETBOX_TOKEN`, the names client.ts already
+ *   read — see the SDK's own credentials.ts note), so a consuming stack only has to provide
+ *   `HttpClient.HttpClient`, exactly as it did before this migration.
  */
 export type NetboxRequirements = HttpClient.HttpClient;
 
-export interface NetboxSpec<Props extends object, Attributes> {
-  /** `ipam/prefixes` — where a new one is POSTed and where `locate` filters. */
-  readonly collection: string;
-  /**
-   * The query that narrows the candidates, as `URLSearchParams` pairs.
-   *
-   * ⛔ ONLY FILTERS THE VENDOR DOCUMENT DECLARES, AND ONLY IN THE FORM IT DECLARES THEM. A
-   *   filter NetBox rejects answers 400, which `absentOn404` correctly does NOT fold to "absent" —
-   *   so a guessed filter shape is a hard failure on every plan, not a soft one.
-   * ★ IT DOES NOT HAVE TO BE UNIQUE. `identifies` finishes the job in this process, where the
-   *   rule is readable and testable offline.
-   */
-  readonly locate: (props: Props) => readonly (readonly [string, string])[];
-  /**
-   * Which of the returned rows IS this object.
-   *
-   * 🔴 THIS EXISTS BECAUSE THE OBVIOUS ALTERNATIVE WAS A GUESS. `Netbox.Prefix` first narrowed
-   *   server-side with `vrf_id=null`, the sentinel NetBox uses elsewhere for "no foreign key".
-   *   ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at v4.7.0: `PrefixFilterSet.vrf_id` is a plain
-   *   `django_filters.ModelMultipleChoiceFilter` with NO `null_value`, so `'null'` is validated
-   *   against the VRF queryset, fails, and NetBox answers 400 under strict filtering. The
-   *   sentinel is real (`FILTERS_NULL_CHOICE_VALUE = 'null'`) but it is opt-in per filter, and
-   *   this one did not opt in.
-   * ★ SO THE DISCRIMINATOR MOVED INTO THIS PROCESS. It costs one page of candidates and buys a
-   *   rule that can be read, tested without a server, and cannot be wrong about a vendor's
-   *   filter semantics. Omit it when `locate` really is unique on its own.
-   */
-  readonly identifies?: (live: NetboxRow, props: Props) => boolean;
-  readonly attributes: (live: NetboxRow, props: Props) => Attributes | undefined;
-  readonly createBody: (props: Props) => NetboxBody;
-  /** ⚠️ PARTIAL BY DESIGN: NetBox updates are PATCH, so presence is not checked on this body. */
-  readonly updateBody?: (props: Props) => NetboxBody;
-  readonly matches: (attributes: Attributes, props: Props) => boolean;
-  /** The generated constraint table to check each body against, by endpoint key. */
-  readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
-  /** For the message `soleMatch` raises and for read-back failures. */
-  readonly describe: (props: Props) => string;
-}
-
-/** ⚠️ Only 404 folds to "absent". A 403 or a 502 is a real failure — folding it would plan a create over an existing object. */
-const absentOn404 = <A>(io: Effect.Effect<A, NetboxError, NetboxRequirements>) =>
-  io.pipe(
-    Effect.catchIf(
-      (cause): cause is NetboxError => cause instanceof NetboxError && cause.status === 404,
-      () => Effect.succeed(undefined as A),
-    ),
-  );
-
 /**
  * ⚠️ NOT `limit=1`, AND NOT `limit=2` EITHER. One row is all a caller wants, but the page has to
- *   be wide enough for `identifies` to see every candidate `locate` matched — a prefix that
- *   exists in several VRFs comes back several times, and a page of two would hide the third.
+ *   be wide enough for an `identifies` narrowing to see every candidate a server-side filter
+ *   matched — a prefix that exists in several VRFs comes back several times, and a page of two
+ *   would hide the third.
  * ★ TWENTY, AND THE NUMBER IS AN ASSERTION: a natural key matching more than twenty rows is not
  *   a natural key. `count` is checked against it, so the failure is "your filter is too broad"
- *   rather than a silent truncation.
+ *   rather than a silent truncation. Unchanged from client.ts's original value.
  */
-const LOCATE_PAGE = 20;
+export const LOCATE_PAGE = 20;
 
-const query = (pairs: readonly (readonly [string, string])[]): string =>
-  new URLSearchParams([
-    ...pairs.map(([k, v]) => [k, v] as [string, string]),
-    ['limit', String(LOCATE_PAGE)],
-  ]).toString();
+/**
+ * The single row a filtered list returns, or `undefined`.
+ *
+ * ⛔ MORE THAN ONE MATCH IS A DEFECT, NOT A REASON TO TAKE THE FIRST. A `locate` filter that is
+ *   not unique would let adopt bind to whichever row NetBox happened to order first, and the next
+ *   plan would bind to the other one and report drift that is not there.
+ */
+export const soleMatch = <T>(rows: readonly T[], describe: string): T | undefined => {
+  if (rows.length > 1) {
+    throw new Error(
+      `${describe} matched ${String(rows.length)} NetBox objects. An object's identity must be ` +
+        'unique; narrow it (the VRF, the site, the tenant) rather than taking the first row.',
+    );
+  }
+  return rows[0];
+};
 
-export const netboxOperations = <Props extends object, Attributes>(
-  spec: NetboxSpec<Props, Attributes>,
-) => {
-  const fetchLive = (props: Props) =>
-    absentOn404(
-      netbox<NetboxList<NetboxRow>>('GET', `${spec.collection}/?${query(spec.locate(props))}`),
-    ).pipe(
-      Effect.map((list) => {
-        if (list !== undefined && list.count > LOCATE_PAGE) {
-          throw new Error(
-            `${spec.describe(props)}: the locate filter matched ${String(list.count)} rows, more ` +
-              `than the ${String(LOCATE_PAGE)}-row page this reads. That is not a natural key — ` +
-              'narrow the filter rather than paging through candidates.',
-          );
-        }
-        const rows = list?.results ?? [];
-        const narrow = spec.identifies;
-        return soleMatch(
-          narrow === undefined ? rows : rows.filter((row) => narrow(row, props)),
-          spec.describe(props),
+/**
+ * List, then narrow to at most one candidate — the same "which of these rows IS this object"
+ * problem a server-side filter cannot always answer (see prefix.ts's own note on `vrf_id`). Any
+ * NetBox 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 — the direct successor to client.ts's `fetchLive` helper, generalized over the SDK's
+ * own paginated-list shape instead of a hand-decoded `NetboxList<NetboxRow>`.
+ */
+export const locateOne = <Row, E, R>(
+  list: Effect.Effect<{ readonly count: number; readonly results: readonly Row[] }, E, R>,
+  describe: string,
+  identifies?: (row: Row) => boolean,
+): Effect.Effect<Row | undefined, E, R> =>
+  list.pipe(
+    Effect.map((page) => {
+      if (page.count > LOCATE_PAGE) {
+        throw new Error(
+          `${describe}: the locate filter matched ${String(page.count)} rows, more than the ` +
+            `${String(LOCATE_PAGE)}-row page this reads. That is not a natural key — narrow the ` +
+            'filter rather than paging through candidates.',
         );
-      }),
-    );
+      }
+      const rows = identifies === undefined ? page.results : page.results.filter(identifies);
+      return soleMatch(rows, describe);
+    }),
+  );
 
-  /** ⛔ The numeric `id` is the wire path. NetBox has no update-by-natural-key. */
-  const objectPath = (live: NetboxRow): string => `${spec.collection}/${String(live['id'])}`;
+/**
+ * One NetBox object's distilled calls. `Live` is whatever the SDK decodes (a `Prefix`, a `VLAN`,
+ * …) — no more untyped `NetboxRow`. `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.
+ */
+export type NetboxSpec<Props extends object, Live, Attributes, E> = {
+  /** Already folds any real "absent" outcome (an empty list, or a `catchTag('NotFound', ...)`). */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, NetboxOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly createBody: (props: Props) => NetboxBody;
+  readonly create: (props: Props, body: NetboxBody) => Effect.Effect<unknown, E, NetboxOpContext>;
+  /** Absent for a create-only family — reconcile then never attempts a write against an adopted row. */
+  readonly update?: {
+    /** ⚠️ PARTIAL BY DESIGN: NetBox updates are PATCH, so presence is not checked on this body. */
+    readonly body: (props: Props) => NetboxBody;
+    readonly call: (
+      props: Props,
+      live: Live,
+      body: NetboxBody,
+    ) => Effect.Effect<unknown, E, NetboxOpContext>;
+  };
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, NetboxOpContext>;
+  /** The generated constraint table to check each body against, by endpoint key. */
+  readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
+  /** For the message `soleMatch` raises and for read-back failures. */
+  readonly describe: (props: Props) => string;
+};
 
+export const netboxOperations = <Props extends object, Live, Attributes, E>(
+  spec: NetboxSpec<Props, Live, Attributes, E>,
+) => {
   const read = (props: Props) =>
-    fetchLive(props).pipe(
-      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
-    );
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
 
   return {
     read,
@@ -139,29 +151,29 @@ export const netboxOperations = <Props extends object, Attributes>(
         const live = yield* read(news);
         if (live === undefined) return { action: 'update' } as const;
         if (spec.matches(live, news)) return { action: 'noop' } as const;
-        return spec.updateBody === undefined
+        return spec.update === undefined
           ? ({ action: 'replace' } as const)
           : ({ action: 'update' } as const);
       }),
 
     reconcile: (news: Props) =>
       Effect.gen(function* () {
-        const before = yield* fetchLive(news);
+        const before = yield* spec.fetchLive(news);
         if (before === undefined) {
           const body = spec.createBody(news);
           // ⛔ GUARD BEFORE THE REQUEST, WITH PRESENCE ON. This is the only place a missing
           //   required property can still be caught locally.
           yield* guardBody(spec.endpoint.create, body, true);
-          yield* netbox('POST', `${spec.collection}/`, body);
-        } else if (spec.updateBody !== undefined) {
+          yield* spec.create(news, body);
+        } else if (spec.update !== undefined) {
           const mapped = spec.attributes(before, news);
           // ⚠️ ADOPTION IS THE `mapped === undefined` CASE TOO: a row this spec cannot map is not
           //   a row to PATCH blindly.
           if (mapped !== undefined && !spec.matches(mapped, news)) {
-            const body = spec.updateBody(news);
+            const body = spec.update.body(news);
             yield* guardBody(spec.endpoint.update, body, false);
             if (Object.keys(body).length > 0) {
-              yield* netbox('PATCH', `${objectPath(before)}/`, body);
+              yield* spec.update.call(news, before, body);
             }
           }
         }
@@ -180,9 +192,9 @@ export const netboxOperations = <Props extends object, Attributes>(
 
     destroy: (olds: Props) =>
       Effect.gen(function* () {
-        const live = yield* fetchLive(olds);
+        const live = yield* spec.fetchLive(olds);
         if (live === undefined) return;
-        yield* netbox('DELETE', `${objectPath(live)}/`);
+        yield* spec.destroy(olds, live);
       }),
   };
 };
@@ -190,19 +202,28 @@ export const netboxOperations = <Props extends object, Attributes>(
 /**
  * The five provider handlers for a spec'd NetBox object, wired once.
  *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE, NOT BY EVERY CALLER. `CredentialsFromEnv` resolves
+ *   `NETBOX_URL` / `NETBOX_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: Alchemy persists
+ *   attributes unencrypted, so nothing stored in a stack file may be a credential.
+ *
+ * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as `forgejoHandlers`.
+ *
  * ⚠️ `list` answers empty. NetBox index endpoints return the whole estate — tens of thousands of
  *   rows on a real instance — so adoption stays explicit rather than sweeping.
  */
-export const netboxHandlers = <Props extends object, Attributes extends object>(
-  spec: NetboxSpec<Props, Attributes>,
+export const netboxHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: NetboxSpec<Props, Live, Attributes, E>,
 ) => {
   const ops = netboxOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, NetboxOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
   return {
     list: () => Effect.succeed([]),
-    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    read: ({ olds }: { olds: Props }) => withCredentials(ops.read(olds)),
     diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
-      ops.diff(news, output),
-    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
-    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
   };
 };

package/dist/netbox/client.d.ts

@@ -1,52 +0,0 @@
-/**
- * One authenticated call to the NetBox REST API at `/api`.
- *
- * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. NetBox is Django REST Framework using DRF's own
- *   `TokenAuthentication`. MEASURED on this estate's own instance while it was up: `Bearer`
- *   returns 401 and `Token` returns 200. ⛔ A wrong scheme and a wrong credential are
- *   indistinguishable in the response, which is why this is written down rather than inferred.
- *
- * ⚠️ NETBOX DOES NOT WRAP A DETAIL RESPONSE THE WAY PVE DOES — a GET of one object returns the
- *   object. A LIST, however, IS wrapped: `{count, next, previous, results: [...]}`. A caller that
- *   treats a list like a detail sees `undefined` and calls a healthy object absent, which plans a
- *   create over something that already exists.
- *
- * ⛔ THE TOKEN IS NEVER A PROP. It is read from `NETBOX_TOKEN` at call time only. Alchemy persists
- *   attributes unencrypted; nothing stored here may be a credential.
- */
-import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/unstable/http/HttpClient';
-/**
- * The instance, from `NETBOX_URL`. Trailing slash stripped.
- *
- * ⛔ NO DEFAULT HOSTNAME AND NO DEFAULT PORT. A published package that fell back to a loopback
- *   address would let a consumer who forgot the variable watch every call fail against a machine
- *   that is not theirs, instead of being told which variable is missing.
- * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to whatever
- *   the first isolate saw.
- */
-export declare const apiBase: () => string;
-export declare class NetboxError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    constructor(status: number, method: string, path: string, detail: string);
-}
-/** A NetBox list response. ⚠️ Paginated: `next` is a URL, not a cursor to guess at. */
-export interface NetboxList<T> {
-    readonly count: number;
-    readonly next: string | null;
-    readonly results: readonly T[];
-}
-export type NetboxRow = Record<string, unknown>;
-/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
-export declare const netbox: <T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Effect.Effect<T, NetboxError, HttpClient.HttpClient>;
-/**
- * The single row a filtered list returns, or `undefined`.
- *
- * ⛔ MORE THAN ONE MATCH IS A DEFECT, NOT A REASON TO TAKE THE FIRST. A `locate` filter that is
- *   not unique would let adopt bind to whichever row NetBox happened to order first, and the next
- *   plan would bind to the other one and report drift that is not there.
- */
-export declare const soleMatch: <T>(rows: readonly T[], describe: string) => T | undefined;
-//# sourceMappingURL=client.d.ts.map

package/dist/netbox/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/netbox/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAK9D;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,QAAO,MAQ1B,CAAC;AAEF,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHvB,YACW,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EAIf;CACF;AAkBD,uFAAuF;AACvF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,kGAAkG;AAClG,eAAO,MAAM,MAAM,GAAI,CAAC,UACd,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,QAC7C,MAAM,SACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,yDA8C5B,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,QAAQ,SAAS,CAAC,EAAE,YAAY,MAAM,KAAG,CAAC,GAAG,SAQvE,CAAC"}