@homeflare/alchemy 0.27.3 → 0.28.0

package/src/github/repository-ruleset-props.ts

@@ -0,0 +1,92 @@
+/**
+ * `GitHub.RepositoryRuleset`'s declared shape — split out of repository-ruleset.ts purely to
+ * keep that file (the provider wiring) under the 250-line cap; nothing here is provider logic.
+ */
+import type { RulesetProps } from 'alchemy/GitHub';
+
+type UpstreamRules = NonNullable<RulesetProps['rules']>;
+
+export interface RepositoryRulesetReviewerRule {
+  readonly filePatterns: readonly string[];
+  readonly minimumApprovals: number;
+  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
+}
+
+export interface RepositoryRulesetPullRequestRule extends NonNullable<
+  UpstreamRules['pullRequest']
+> {
+  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
+  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
+  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
+  /** `require_extra_approval_for_unattributed_changes` — see repository-ruleset.ts's H15. Only
+   * `false` is modeled: sending `true` has no house use, and GitHub already defaults absent to
+   * `true`. */
+  readonly extraApprovalForUnattributedChanges?: false;
+}
+
+export interface RepositoryRulesetStatusChecksRule extends NonNullable<
+  UpstreamRules['requiredStatusChecks']
+> {
+  readonly doNotEnforceOnCreate?: boolean;
+}
+
+export interface RepositoryRulesetRules extends Omit<
+  UpstreamRules,
+  'pullRequest' | 'requiredStatusChecks'
+> {
+  /** `undefined`: no opinion (refused if the live ruleset already has one and this is not an
+   * exact-adopt pass-through — see repository-ruleset-guards.ts's `undeclaredLiveRuleRefusal`).
+   * `false`: declare its ABSENCE — either "this repo never had one" (a create, or an adopt
+   * where live already has none, both no-ops) or a deliberate removal of a live rule, which
+   * `ruleNarrowingRefusal` gates behind `acknowledgeRuleNarrowing` (see below). Added 2026-09-23 for
+   * exact-adopt pass-through: `requiredStatusChecks` already had this `false` escape; `deletion`/
+   * `nonFastForward`/etc already have it implicitly (plain `boolean`, so `false` is already a
+   * value); `pullRequest` was the one modeled rule with NO way to express "not present at all" —
+   * a repo like `taslabs-net/taslabs-net` (measured live 2026-09-23: `rules = [deletion,
+   * non_fast_forward]`, no `pull_request`) could not be adopted through this resource without
+   * either refusing to omit the key (a type error) or silently declaring a brand-new rule. */
+  readonly pullRequest?: RepositoryRulesetPullRequestRule | false;
+  /** `undefined`: no opinion (refused if the live ruleset already has one — see
+   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
+  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
+}
+
+export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
+  readonly rules?: RepositoryRulesetRules;
+  /**
+   * An explicit, reasoned sign-off that THIS declaration deliberately drops a live bypass actor
+   * (`bypassActors` is a strict subset of what is live). Without this, `reconcile` refuses the
+   * write rather than silently loosen a ruleset that already protects something — see
+   * `bypassNarrowingRefusal` in repository-ruleset-narrowing-guards.ts. `reason` is not logged or
+   * sent to GitHub; it exists so the declaration's own diff carries WHY, for the next reader
+   * (S21: a refusal names the fact it checked — this is the human-authored counterpart for the
+   * one case a fact alone cannot settle: "is this narrowing intentional?").
+   *
+   * ⛔ SEPARATE FROM `acknowledgeRuleNarrowing` ON PURPOSE (2026-09-23 review finding: a single
+   *   shared `acknowledgeNarrowing` let one reason worded for a rule drop silently also rubber-
+   *   stamp an unrelated bypass-actor drop in the SAME declaration — a `bypassActors: []` left
+   *   over from an unrelated edit slipped through under a reason that never mentioned bypass at
+   *   all). Each prop authorizes only the narrowing its own guard checks; a declaration that
+   *   narrows both needs both, each with its own reason.
+   *
+   * ⛔ ALSO A STANDING PROP, NOT A ONE-TIME TOKEN — remove it from the declaration once the
+   *   narrowing it describes has landed. Left in place, it keeps disabling the bypass-narrowing
+   *   guard for every future `reconcile` of this resource, not only the change it was written
+   *   for — the same way `rules: { deletion: false }` stays a standing "this rule stays absent"
+   *   fact rather than a one-time action, only here the standing fact is "bypass narrowing needs
+   *   no review", which is a fact you want true for as short a window as possible. A reviewer
+   *   reading a diff that adds a SECOND, unrelated bypass drop under an OLD
+   *   `acknowledgeBypassNarrowing` left over from a prior change is the failure mode this note
+   *   exists to head off.
+   */
+  readonly acknowledgeBypassNarrowing?: { readonly reason: string };
+  /**
+   * The `rules`-side counterpart to `acknowledgeBypassNarrowing` above — an explicit, reasoned
+   * sign-off that THIS declaration deliberately drops a live rule (a modeled rule type declared
+   * `false`/boolean-`false` while the live ruleset still has it). Without this, `reconcile`
+   * refuses the write — see `ruleNarrowingRefusal` in repository-ruleset-narrowing-guards.ts.
+   * Same standing-prop caution as `acknowledgeBypassNarrowing`: remove it once the rule drop it
+   * describes has landed, or it keeps excusing every later rule drop on this resource too.
+   */
+  readonly acknowledgeRuleNarrowing?: { readonly reason: string };
+}

package/src/github/repository-ruleset-reconcile.ts

@@ -20,6 +20,12 @@ import {
   requiredChecksOmissionRefusal,
   undeclaredLiveRuleRefusal,
 } from './repository-ruleset-guards.ts';
+import {
+  bypassNarrowingRefusal,
+  isBypassNarrowingAcknowledged,
+  isRuleNarrowingAcknowledged,
+  ruleNarrowingRefusal,
+} from './repository-ruleset-narrowing-guards.ts';
 import {
   type RulesetOctokit,
   type RulesetRecord,
@@ -104,6 +110,12 @@ export const reconcileRuleset = <R = never>(input: {
       observed = yield* probeByName(octokit, { owner, repo, name: news.name, target });
     }
 
+    // Deliberately TWO separate reads, not one shared flag — each guard below is authorized
+    // only by the acknowledgement scoped to what it checks (see the file header on
+    // repository-ruleset-narrowing-guards.ts for the 2026-09-23 finding this fixes).
+    const bypassAcknowledged = isBypassNarrowingAcknowledged(news);
+    const ruleAcknowledged = isRuleNarrowingAcknowledged(news);
+
     const bypassRefusal =
       news.bypassActors === undefined
         ? undefined
@@ -116,6 +128,19 @@ export const reconcileRuleset = <R = never>(input: {
           });
     if (bypassRefusal !== undefined) return yield* Effect.fail(bypassRefusal);
 
+    const bypassNarrowRefusal =
+      news.bypassActors === undefined
+        ? undefined
+        : bypassNarrowingRefusal({
+            owner,
+            repository: repo,
+            name: news.name,
+            declared: news.bypassActors,
+            live: observed,
+            acknowledged: bypassAcknowledged,
+          });
+    if (bypassNarrowRefusal !== undefined) return yield* Effect.fail(bypassNarrowRefusal);
+
     const ruleRefusal = undeclaredLiveRuleRefusal({
       owner,
       repository: repo,
@@ -125,6 +150,16 @@ export const reconcileRuleset = <R = never>(input: {
     });
     if (ruleRefusal !== undefined) return yield* Effect.fail(ruleRefusal);
 
+    const ruleNarrowRefusal = ruleNarrowingRefusal({
+      owner,
+      repository: repo,
+      name: news.name,
+      declared: news.rules,
+      live: observed,
+      acknowledged: ruleAcknowledged,
+    });
+    if (ruleNarrowRefusal !== undefined) return yield* Effect.fail(ruleNarrowRefusal);
+
     const checksRefusal = requiredChecksOmissionRefusal({
       owner,
       repository: repo,

package/src/github/repository-ruleset-write-refusals.test.ts

@@ -1,8 +1,12 @@
 /**
  * (ii) The write-recording fake, refusals: duplicate names, bypass widening, an undeclared live
  * rule, required checks omitted, and a never-reported context each make ZERO writes; and a
- * readback mismatch fails even though the write itself "succeeded" (S10). The happy paths
- * (create, noop, update) are repository-ruleset-write.test.ts.
+ * readback mismatch fails even though the write itself "succeeded" (S10). Bypass/rule narrowing
+ * without the matching `acknowledge{Bypass,Rule}Narrowing` are their own file,
+ * repository-ruleset-narrowing.test.ts (split out purely for the 250-line cap). The happy paths
+ * (create, noop, update) are repository-ruleset-write.test.ts; exact-adopt pass-through's own
+ * dedicated fixtures (all 5 live non-empty-bypass shapes) are
+ * repository-ruleset-exact-adopt.test.ts.
  */
 import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
@@ -94,30 +98,6 @@ describe('refusals make zero writes', () => {
     expect(tagOf(error)).toBe('UndeclaredLiveRule');
   });
 
-  test('the SAME live ruleset with deletion explicitly declared false is a deliberate removal, not refused', async () => {
-    const live = {
-      id: 1,
-      name: 'main',
-      enforcement: 'active',
-      bypass_actors: [],
-      conditions: {},
-      rules: [
-        { type: 'deletion' },
-        { type: 'pull_request', parameters: { required_approving_review_count: 0 } },
-      ],
-    };
-    const fake = makeRecordingFake({ widgets: live });
-    fake.reportedContexts.add('ci');
-    const declaration = props({
-      rules: { deletion: false, pullRequest: BASE_PULL_REQUEST },
-    });
-    await reconcileAgainst(fake, declaration, { rulesetId: 1 }).pipe(Effect.runPromise);
-    expect(fake.writes).toHaveLength(1);
-    expect(fake.writes[0]?.op).toBe('update');
-    const sentTypes = fake.writes[0]?.body?.rules?.map((r) => r.type);
-    expect(sentTypes).not.toContain('deletion');
-  });
-
   test('required checks omitted while the live ruleset has them', async () => {
     const live = {
       id: 1,

package/src/github/repository-ruleset.ts

@@ -42,7 +42,7 @@
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
-import type { GitHubCredentials, RulesetProps } from 'alchemy/GitHub';
+import type { GitHubCredentials } from 'alchemy/GitHub';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
@@ -52,46 +52,16 @@ import {
 import { RulesetConstraintRefused } from './repository-ruleset-errors.ts';
 import { makeRulesetOctokit } from './repository-ruleset-octokit.ts';
 import { type RulesetRecord, probeByName } from './repository-ruleset-probe.ts';
+import type { RepositoryRulesetProps } from './repository-ruleset-props.ts';
 import { reconcileRuleset } from './repository-ruleset-reconcile.ts';
 
-type UpstreamRules = NonNullable<RulesetProps['rules']>;
-
-export interface RepositoryRulesetReviewerRule {
-  readonly filePatterns: readonly string[];
-  readonly minimumApprovals: number;
-  readonly reviewer: { readonly actorId: number; readonly actorType: 'Team' };
-}
-
-export interface RepositoryRulesetPullRequestRule extends NonNullable<
-  UpstreamRules['pullRequest']
-> {
-  /** @default every method GitHub allows — the house baseline always pins `['squash']`. */
-  readonly allowedMergeMethods?: readonly ('merge' | 'squash' | 'rebase')[];
-  readonly requiredReviewers?: readonly RepositoryRulesetReviewerRule[];
-  /** `require_extra_approval_for_unattributed_changes` — see H15 above. Only `false` is
-   * modeled: sending `true` has no house use, and GitHub already defaults absent to `true`. */
-  readonly extraApprovalForUnattributedChanges?: false;
-}
-
-export interface RepositoryRulesetStatusChecksRule extends NonNullable<
-  UpstreamRules['requiredStatusChecks']
-> {
-  readonly doNotEnforceOnCreate?: boolean;
-}
-
-export interface RepositoryRulesetRules extends Omit<
-  UpstreamRules,
-  'pullRequest' | 'requiredStatusChecks'
-> {
-  readonly pullRequest?: RepositoryRulesetPullRequestRule;
-  /** `undefined`: no opinion (refused if the live ruleset already has one — see
-   * repository-ruleset-guards.ts). `false`: declare its ABSENCE — removes a live one. */
-  readonly requiredStatusChecks?: RepositoryRulesetStatusChecksRule | false;
-}
-
-export interface RepositoryRulesetProps extends Omit<RulesetProps, 'rules'> {
-  readonly rules?: RepositoryRulesetRules;
-}
+export type {
+  RepositoryRulesetProps,
+  RepositoryRulesetPullRequestRule,
+  RepositoryRulesetReviewerRule,
+  RepositoryRulesetRules,
+  RepositoryRulesetStatusChecksRule,
+} from './repository-ruleset-props.ts';
 
 export interface RepositoryRulesetAttributes {
   readonly rulesetId: number;
@@ -124,7 +94,11 @@ export const attrsOf = (r: RulesetRecord): RepositoryRulesetAttributes => ({
 /** Plan-time-only refusals — no live data needed, so these run before any read (schema-codegen's
  * rule: check the form before the "no previous state" branch, never after it). */
 function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefused | undefined {
-  const approvals = props.rules?.pullRequest?.requiredApprovingReviewCount;
+  // `=== false` narrows `pullRequest` out of the `| false` half added for exact-adopt
+  // pass-through (see `RepositoryRulesetRules` above) — a declared absence has no fields to
+  // constrain.
+  const pr = props.rules?.pullRequest === false ? undefined : props.rules?.pullRequest;
+  const approvals = pr?.requiredApprovingReviewCount;
   if (approvals !== undefined) {
     const reason = approvalCountRefusal(approvals);
     if (reason !== undefined) {
@@ -134,7 +108,7 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
-  const methods = props.rules?.pullRequest?.allowedMergeMethods;
+  const methods = pr?.allowedMergeMethods;
   if (methods !== undefined) {
     const reason = allowedMergeMethodsRefusal(methods);
     if (reason !== undefined) {
@@ -144,6 +118,18 @@ function constraintRefusal(props: RepositoryRulesetProps): RulesetConstraintRefu
       });
     }
   }
+  // ⚠️ NO SEPARATE PLAN-TIME CHECK FOR A BLANK `acknowledge{Bypass,Rule}Narrowing.reason` HERE.
+  //   A blank reason is already indistinguishable from "not acknowledged at all" —
+  //   `isBypassNarrowingAcknowledged`/`isRuleNarrowingAcknowledged`
+  //   (repository-ruleset-narrowing-guards.ts) each require a non-empty, trimmed `reason` on
+  //   their OWN prop, and the matching narrowing guard reads that, not presence alone. Adding a
+  //   SECOND check here would refuse with `RulesetConstraintRefused` instead of the more
+  //   specific `BypassActorNarrowed`/`RuleNarrowed` the caller actually needs to act on — and,
+  //   unlike those two (exercised directly through `reconcileRuleset`, injected-octokit fakes
+  //   included), this function is wired only through the real `RepositoryRuleset.Provider`
+  //   (`makeRulesetOctokit` needs live `GitHubCredentials`), which this family's own test
+  //   helpers do not exercise (see `repository-ruleset-test-helpers.ts`'s stub
+  //   `constraintRefusal`) — a check that lives only here would ship untested.
   return undefined;
 }
 

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 }]);
+  });
+});