@homeflare/alchemy 0.27.3 → 0.27.4

package/dist/netbox/resource.d.ts

@@ -1,48 +1,66 @@
 import type { Input } from 'alchemy/Input';
+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 NetboxRow } from './client.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;
+/**
+ * ⚠️ NOT `limit=1`, AND NOT `limit=2` EITHER. One row is all a caller wants, but the page has to
+ *   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. Unchanged from client.ts's original value.
+ */
+export declare const LOCATE_PAGE = 20;
+/**
+ * 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;
+/**
+ * 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 declare 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>;
+/**
+ * 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;
@@ -50,30 +68,37 @@ export interface NetboxSpec<Props extends object, Attributes> {
     };
     /** For the message `soleMatch` raises and for read-back failures. */
     readonly describe: (props: Props) => string;
-}
-export declare const netboxOperations: <Props extends object, Attributes>(spec: NetboxSpec<Props, Attributes>) => {
-    read: (props: Props) => Effect.Effect<Attributes | undefined, never, HttpClient.HttpClient>;
+};
+export declare const netboxOperations: <Props extends object, Live, Attributes, E>(spec: NetboxSpec<Props, Live, Attributes, E>) => {
+    read: (props: Props) => Effect.Effect<Attributes | undefined, E, NetboxOpContext>;
     diff: (news: Input<Props>, output: Attributes | undefined) => Effect.Effect<{
         readonly action: 'update';
     } | {
         readonly action: 'noop';
     } | {
         readonly action: 'replace';
-    } | undefined, never, HttpClient.HttpClient>;
-    reconcile: (news: Props) => Effect.Effect<Attributes & ({} | null), NetboxError, HttpClient.HttpClient>;
-    destroy: (olds: Props) => Effect.Effect<void, NetboxError, HttpClient.HttpClient>;
+    } | undefined, E, NetboxOpContext>;
+    reconcile: (news: Props) => Effect.Effect<Attributes & ({} | null), E, NetboxOpContext>;
+    destroy: (olds: Props) => Effect.Effect<void, E, NetboxOpContext>;
 };
 /**
  * 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 declare const netboxHandlers: <Props extends object, Attributes extends object>(spec: NetboxSpec<Props, Attributes>) => {
+export declare const netboxHandlers: <Props extends object, Live, Attributes extends object, E>(spec: NetboxSpec<Props, Live, Attributes, E>) => {
     list: () => Effect.Effect<never[], never, never>;
     read: ({ olds }: {
         olds: Props;
-    }) => Effect.Effect<Attributes | undefined, never, HttpClient.HttpClient>;
+    }) => Effect.Effect<Attributes | undefined, E, HttpClient.HttpClient>;
     diff: ({ news, output }: {
         news: Input<Props>;
         output: Attributes | undefined;
@@ -83,12 +108,12 @@ export declare const netboxHandlers: <Props extends object, Attributes extends o
         readonly action: 'noop';
     } | {
         readonly action: 'replace';
-    } | undefined, never, HttpClient.HttpClient>;
+    } | undefined, E, HttpClient.HttpClient>;
     reconcile: ({ news }: {
         news: Props;
-    }) => Effect.Effect<Attributes, NetboxError, HttpClient.HttpClient>;
+    }) => Effect.Effect<Attributes, E, HttpClient.HttpClient>;
     delete: ({ olds }: {
         olds: Props;
-    }) => Effect.Effect<void, NetboxError, HttpClient.HttpClient>;
+    }) => Effect.Effect<void, E, HttpClient.HttpClient>;
 };
 //# sourceMappingURL=resource.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/netbox/resource.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAmB,KAAK,SAAS,EAAqB,MAAM,aAAa,CAAC;AAE9F,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,UAAU,CAAC;AAEvD,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,MAAM,EAAE,UAAU;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IAC1E;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACjE,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,GAAG,SAAS,CAAC;IAC/E,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC;IAClD,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,CAAC;IACnF,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C;AA2BD,eAAO,MAAM,gBAAgB,GAAI,KAAK,SAAS,MAAM,EAAE,UAAU,QACzD,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC;kBA0Bd,KAAK;iBAQX,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBACF,MAAM;;yBAEtC,SAAS;;sBAIV,KAAK;oBAkCP,KAAK;CAOxB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,SAAS,MAAM,EAAE,UAAU,SAAS,MAAM,QACtE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC;IAIjC,IAAI;IACJ,IAAI,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IAChC,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBA/DlC,QAAQ;;yBACF,MAAM;;yBAEtC,SAAS;;IA8D5B,SAAS,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACrC,MAAM,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAErC,CAAC"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/netbox/resource.ts"],"names":[],"mappings":"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"}

package/docs/credentials.md

@@ -19,3 +19,13 @@ through the package's own `CredentialsFromEnv` layer, which reads `FORGEJO_URL`
 — the same two variable names the retired hand-rolled client read, still resolved on the calling
 fiber per request, never captured at module scope. `Authorization: token <value>` (Forgejo's
 access-token scheme, not `Bearer`) is built by the package's protocol layer, not by this package.
+
+The NetBox subpath (2026-09-23, moved onto `@distilled.cloud/netbox` — see
+[distilled-interim.md](./distilled-interim.md)) resolves credentials the same way, through the
+SDK's own `CredentialsFromEnv` layer, which reads `NETBOX_URL` / `NETBOX_TOKEN` — the same two
+variable names the retired hand-rolled `client.ts` read, still resolved on the calling fiber per
+request, never captured at module scope. `Authorization: Token <value>` (NetBox's Django REST
+Framework `TokenAuthentication` scheme — NOT `Bearer`, measured against this estate's own
+instance) is built by the package's protocol layer, not by this package. ⛔ The token is never a
+prop: Alchemy persists attributes unencrypted, so nothing stored in a stack file may be a
+credential.

package/docs/peers.md

@@ -53,3 +53,14 @@ whole install, not one per subpath — `peers.test.ts`'s "no peer is marked opti
 enforces it. `@effect/sql-pg` is optional on `alchemy`'s own manifest (its module graph
 does not reach `SQL/Postgres` unless a stack imports it); here it stays a plain peer like
 every other one.
+
+★ **`@distilled.cloud/netbox` (added 2026-09-23, moving `/netbox` off a hand-rolled
+`HttpClient` client the same way `/forgejo` did) is NOT on this install line, and that is
+deliberate — see [distilled-interim.md](./distilled-interim.md).** The real
+`@distilled.cloud/netbox` is not published upstream yet, so this package aliases it onto
+`@homeflare/distilled-netbox@0.2.0`, a copy built the distilled way and shipped from this
+monorepo, as a plain **`dependencies`** entry (not a peer). A `dependencies` entry resolves
+automatically for every consumer that installs `@homeflare/alchemy` — nothing to add to a
+peer install line, and nothing for `peers.test.ts` to check. When the real package ships
+upstream, the alias's target changes (or the entry becomes a normal peer, matching
+`@distilled.cloud/forgejo` above) and this line still does not change for it.

package/docs/upstream-conformance.md

@@ -104,8 +104,23 @@ then tidiness.
    kubeconfig it writes is meant to be consumed through upstream's
    `Kubernetes.KubeConfig({ path })`.
 9. **`netbox/*` conforms mostly.** Its constraints are generated from NetBox 4.7.0's
-   OpenAPI, and it uses Effect `HttpClient`. Adopting first is documented as deliberate.
-   It diverges in its credentials: `NETBOX_TOKEN` is read at call time (S24).
+   OpenAPI. Adopting first is documented as deliberate.
+   - ✅ **S23 fixed 2026-09-23** (branch `claude2/distilled-netbox-family`, mirroring the
+     Forgejo migration above, decision 42). `Netbox.Prefix` now calls
+     `@distilled.cloud/netbox`'s typed `ipam` operations instead of a hand-rolled `Effect
+HttpClient` client. The old status-carrying `NetboxError` and its `cause.status ===
+404` check are gone entirely — `Netbox.Prefix` locates by a server-side list filter,
+     which never 404s (an empty page is a normal 200), so nothing here checks a status
+     code at all, a stronger form of the same rule `catchTag('NotFound', …)` enforces for
+     a family that reads by direct key. `client.ts` is deleted. Not published upstream
+     yet, so aliased onto `@homeflare/distilled-netbox@0.2.0` as a plain `dependencies`
+     entry, not a peer — [distilled-interim.md](./distilled-interim.md). State did not
+     move: props/attributes stay byte-identical, proven by the family's unchanged
+     existing tests plus new tests against a fake NetBox exercising the real distilled
+     protocol.
+   - ⛔ **Still diverges on credentials (S24):** `NETBOX_TOKEN` / `NETBOX_URL` are read at
+     call time, now through the SDK's `CredentialsFromEnv` rather than a hand-rolled
+     `token()` — same divergence, unchanged by the transport swap.
 10. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
     `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
     (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.27.3",
+  "version": "0.27.4",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -94,6 +94,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.2.0"
   },
   "peerDependencies": {

package/src/netbox/fake-netbox.ts

@@ -0,0 +1,56 @@
+/**
+ * A minimal in-memory NetBox REST API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../forgejo/fake-forgejo.ts` (itself mirroring `cloudflare/fake-mesh.ts`). Tests exercise
+ * distilled's REAL path assembly, JSON encode/decode and status→typed-error matching (`404` →
+ * `NotFound`, `403` → `Forbidden`, …) — nothing about that matching is re-implemented here, only
+ * the wire responses a scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `netbox.example.com`, and the token is a placeholder.
+ */
+import { type Credentials, credentials } from '@distilled.cloud/netbox/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://netbox.example.com';
+export const FAKE_TOKEN = 'placeholder-netbox-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** NetBox's `{ detail }` failure envelope (403/404) — matching protocol.ts's `errorEnvelope`. */
+export const fakeFailure = (status: number, detail: string) =>
+  Response.json({ detail }, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ */
+export const fakeNetbox = (route: (method: string, url: URL) => Response) => {
+  const seen: Seen[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    return route(request.method, url);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen };
+};
+
+/**
+ * distilled Credentials + the real FetchHttpClient over the fake — `NetboxOpContext`, what every
+ * resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers` (each resource file's `netboxHandlers(spec)` export). `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves `NETBOX_URL` / `NETBOX_TOKEN` through Effect's
+ *   `Config` — whose default provider snapshots `process.env` once and never re-reads it (measured
+ *   in the forgejo migration, kit PR 180: mutating `process.env` mid-test-run had no effect). So a
+ *   test cannot point `handlers` at a fake server; it calls `spec.fetchLive`/`spec.attributes`
+ *   directly instead, with this explicit layer, exercising exactly the same production code
+ *   without that env seam.
+ */
+export const fakeNetboxLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ baseUrl: FAKE_BASE, token: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/netbox/index.ts

@@ -8,7 +8,6 @@
  * ★ The constraint reader IS exported, because a consumer writing its own family needs the same
  *   guard — and because a table nobody can reach is a table nobody uses.
  */
-export { NetboxError, apiBase } from './client.ts';
 export {
   NETBOX_CONSTRAINTS,
   bodyViolations,
@@ -31,4 +30,11 @@ export {
   type PrefixProps,
   type PrefixStatus,
 } from './prefix.ts';
-export { type NetboxRequirements, type NetboxSpec, netboxHandlers } from './resource.ts';
+export {
+  LOCATE_PAGE,
+  locateOne,
+  type NetboxRequirements,
+  type NetboxSpec,
+  netboxHandlers,
+  soleMatch,
+} from './resource.ts';

package/src/netbox/prefix.test.ts

@@ -0,0 +1,223 @@
+/**
+ * `Netbox.Prefix`'s `spec` against a fake NetBox, proving the real distilled wire path that
+ * replaced `client.ts`'s hand-rolled `HttpClient` calls — path assembly, JSON encode/decode and
+ * status→typed-error matching, exercised through `@distilled.cloud/netbox/ipam`'s real operations,
+ * never re-implemented here. Mirrors `../forgejo/org-label.test.ts` and `repository.test.ts`'s
+ * "call the exported production functions" shape (kit PR 180).
+ *
+ * ⛔ THE POINT OF THIS FILE. `resource.test.ts` proves `locateOne`/`soleMatch` in isolation with a
+ *   fixture list; this file proves prefix.ts's own `spec.fetchLive`, `spec.attributes`,
+ *   `spec.create`, `spec.update.call` and `spec.destroy` — the exact object `netboxHandlers(spec)`
+ *   wraps into `NetboxPrefixProvider` — against a real HTTP round trip.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as ipam from '@distilled.cloud/netbox/ipam';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, fakeFailure, fakeNetbox, fakeNetboxLayer } from './fake-netbox.ts';
+import type { PrefixProps } from './prefix.ts';
+import { spec } from './prefix.ts';
+
+const PREFIXES_PATH = '/api/ipam/prefixes/';
+const PREFIX_ID_PATH = '/api/ipam/prefixes/7/';
+
+/** A decodable `Prefix` — every field the SDK's schema requires present, per ipam.ts's interface. */
+const livePrefix = (overrides: Record<string, unknown> = {}): ipam.Prefix =>
+  ({
+    _depth: 0,
+    children: 0,
+    comments: '',
+    created: '2026-01-01T00:00:00Z',
+    description: '',
+    display: '10.0.0.0/24',
+    display_url: `${FAKE_BASE}${PREFIX_ID_PATH}`,
+    family: { label: 'IPv4', value: 4 },
+    id: 7,
+    is_pool: false,
+    last_updated: '2026-01-01T00:00:00Z',
+    mark_utilized: false,
+    prefix: '10.0.0.0/24',
+    scope: null,
+    status: { label: 'Active', value: 'active' },
+    url: `${FAKE_BASE}${PREFIX_ID_PATH}`,
+    vrf: null,
+    ...overrides,
+  }) as unknown as ipam.Prefix;
+
+/** `BriefVRF`/`BriefRIR`/`BriefVLAN` all require `id`, `url`, `display`, `name` — no `S.optional`. */
+const briefVrf = (id: number, name: string) => ({
+  display: name,
+  id,
+  name,
+  url: `${FAKE_BASE}/api/ipam/vrfs/${String(id)}/`,
+});
+const briefTenant = (id: number, name: string) => ({
+  display: name,
+  id,
+  name,
+  slug: name,
+  url: `${FAKE_BASE}/api/tenancy/tenants/${String(id)}/`,
+});
+const briefVlan = (id: number, name: string, vid: number) => ({
+  display: name,
+  id,
+  name,
+  url: `${FAKE_BASE}/api/ipam/vlans/${String(id)}/`,
+  vid,
+});
+
+const readThrough = (fetchFn: typeof globalThis.fetch, props: PrefixProps) =>
+  Effect.runPromise(
+    spec.fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+      Effect.provide(fakeNetboxLayer(fetchFn)),
+    ),
+  );
+
+describe('Netbox.Prefix spec.fetchLive', () => {
+  test('one server-side match, no VRF declared, decodes into the typed row', async () => {
+    const fake = fakeNetbox((method, url) =>
+      method === 'GET' && url.pathname === PREFIXES_PATH
+        ? Response.json({ count: 1, next: null, previous: null, results: [livePrefix()] })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ prefix: '10.0.0.0/24' }).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe(7);
+    expect(fake.seen[0]?.method).toBe('GET');
+    // ⚠️ Not just the path — the server-side filter this resource relies on to narrow
+    //   candidates before `identifies` runs. A future distilled bump that changed how an
+    //   array param serializes would silently stop narrowing on the wire; asserting only
+    //   `pathname` would never catch that.
+    const sent = new URL(`${FAKE_BASE}${fake.seen[0]?.path ?? ''}`);
+    expect(sent.searchParams.getAll('prefix')).toEqual(['10.0.0.0/24']);
+  });
+
+  /**
+   * 🔴 THE CASE `identifies` EXISTS FOR — the same VRF disambiguation prefix.ts's own docstring
+   *   explains. `prefix` alone matched two rows (the same CIDR in two VRFs); the declared `vrf`
+   *   picks the right one in this process, never by re-filtering server-side.
+   */
+  test('several rows for the same CIDR narrow to the declared VRF', async () => {
+    const rows = [
+      livePrefix({ id: 7, vrf: briefVrf(1, 'blue') }),
+      livePrefix({ id: 8, vrf: briefVrf(2, 'red') }),
+    ];
+    const fake = fakeNetbox((method, url) =>
+      method === 'GET' && url.pathname === PREFIXES_PATH
+        ? Response.json({ count: 2, next: null, previous: null, results: rows })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec
+        .fetchLive({ prefix: '10.0.0.0/24', vrf: 2 })
+        .pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe(8);
+  });
+
+  test('no candidate rows is absent, not an error', async () => {
+    const fake = fakeNetbox(() =>
+      Response.json({ count: 0, next: null, previous: null, results: [] }),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ prefix: '10.20.30.0/24' }).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 400 on the list propagates — never folded to absent', async () => {
+    const fake = fakeNetbox(() => fakeFailure(400, 'prefix: invalid CIDR'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive({ prefix: 'not-a-cidr' }).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('BadRequest');
+  });
+});
+
+describe('Netbox.Prefix spec.attributes — the actual exported production mapping', () => {
+  test('status, foreign keys and free text all decode the way client.ts used to read them', async () => {
+    const fake = fakeNetbox((method, url) =>
+      method === 'GET' && url.pathname === PREFIXES_PATH
+        ? Response.json({
+            count: 1,
+            next: null,
+            previous: null,
+            results: [
+              livePrefix({
+                comments: 'management range',
+                description: 'core VLAN',
+                is_pool: true,
+                mark_utilized: true,
+                status: { label: 'Deprecated', value: 'deprecated' },
+                tenant: briefTenant(3, 'ops'),
+                vlan: briefVlan(5, 'core', 10),
+                vrf: briefVrf(1, 'blue'),
+              }),
+            ],
+          })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    expect(await readThrough(fake.fetch, { prefix: '10.0.0.0/24', vrf: 1 })).toEqual({
+      comments: 'management range',
+      description: 'core VLAN',
+      isPool: true,
+      markUtilized: true,
+      prefix: '10.0.0.0/24',
+      prefixId: 7,
+      status: 'deprecated',
+      tenant: 3,
+      vlan: 5,
+      vrf: 1,
+    });
+  });
+});
+
+describe('Netbox.Prefix spec.create / spec.update.call / spec.destroy — the real wire calls', () => {
+  const props: PrefixProps = { description: 'core VLAN', prefix: '10.0.0.0/24', status: 'active' };
+  const update = spec.update;
+  if (update === undefined) throw new Error('Netbox.Prefix must declare spec.update');
+
+  test('create POSTs the constraint-checked body to /api/ipam/prefixes/', async () => {
+    const fake = fakeNetbox((method, url) =>
+      method === 'POST' && url.pathname === PREFIXES_PATH
+        ? Response.json(livePrefix({ description: 'core VLAN' }), { status: 201 })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const body = spec.createBody(props);
+    const live = await Effect.runPromise(
+      spec.create(props, body).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect((live as ipam.Prefix).id).toBe(7);
+    expect(fake.seen).toEqual([{ method: 'POST', path: PREFIXES_PATH }]);
+  });
+
+  test('update PATCHes /api/ipam/prefixes/{id}/, addressed by the live row numeric id', async () => {
+    const fake = fakeNetbox((method, url) =>
+      method === 'PATCH' && url.pathname === PREFIX_ID_PATH
+        ? Response.json(livePrefix({ status: { label: 'Deprecated', value: 'deprecated' } }))
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const declared = { ...props, status: 'deprecated' as const };
+    const body = update.body(declared);
+    const after = await Effect.runPromise(
+      update.call(declared, livePrefix(), body).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect((after as ipam.Prefix).status?.value).toBe('deprecated');
+    expect(fake.seen).toEqual([{ method: 'PATCH', path: PREFIX_ID_PATH }]);
+  });
+
+  test('destroy DELETEs /api/ipam/prefixes/{id}/', async () => {
+    const fake = fakeNetbox((method, url) =>
+      method === 'DELETE' && url.pathname === PREFIX_ID_PATH
+        ? new Response(null, { status: 204 })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    await Effect.runPromise(
+      spec.destroy(props, livePrefix()).pipe(Effect.provide(fakeNetboxLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([{ method: 'DELETE', path: PREFIX_ID_PATH }]);
+  });
+});