@homeflare/alchemy 0.38.0 → 0.39.0

package/src/unifi/network.test.ts

@@ -2,13 +2,19 @@
  * `Unifi.Network`'s `spec` against a fake UniFi Network API, proving the real distilled wire
  * path (path assembly, JSON decode, `NotFound` folding), the declaration renderer, and — the
  * task's own requirement — that no handler this family exposes ever sends a non-`GET` request.
+ *
+ * ⚠️ `driftOf`/`matches` coverage (the DHCP/IPv6 unordered-array normalizers, the MEDIUM-4
+ *   mutant-closing tests) lives in `network-drift.test.ts`, split out to keep this file under the
+ *   house 250-line cap once that coverage grew — same split `network-drift.ts` itself is from
+ *   `network-form.ts`, not a different family.
  */
 import { describe, expect, test } from 'bun:test';
 import type * as networks from '@distilled.cloud/unifi-network/networks';
 import * as Retry from '@distilled.cloud/unifi-network/Retry';
 import * as Effect from 'effect/Effect';
 import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
-import { attributesOf, matches } from './network-form.ts';
+import { attributesOf } from './network-form.ts';
+import { matches } from './network-drift.ts';
 import { type NetworkProps, declareNetwork, spec } from './network.ts';
 import { unifiOperations } from './resource.ts';
 
@@ -84,87 +90,6 @@ describe('declareNetwork -- the declaration renderer', () => {
   });
 });
 
-describe('matches -- unordered arrays (dhcpGuarding, ipv6Configuration)', () => {
-  // ⛔ `deepEqual` (alchemy/Diff) sorts object keys but not array elements: without normalizing
-  //   these three fields (see network-form.ts's header), a console returning the same set in a
-  //   different order would plan a spurious update.
-  test('the same trusted DHCP servers in a different order is a noop', () => {
-    const live = liveNetwork({
-      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.2', '10.0.0.1'] },
-    });
-    const props: NetworkProps = {
-      ...PROPS,
-      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.2'] },
-    };
-    expect(matches(attributesOf(live, props), props)).toBe(true);
-  });
-
-  test('a different set of trusted DHCP servers is an update', () => {
-    const live = liveNetwork({
-      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.2'] },
-    });
-    const props: NetworkProps = {
-      ...PROPS,
-      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.3'] },
-    };
-    expect(matches(attributesOf(live, props), props)).toBe(false);
-  });
-
-  test('the same IPv6 host subnets and DNS overrides in a different order is a noop', () => {
-    const live = liveNetwork({
-      ipv6Configuration: {
-        clientAddressAssignment: { slaacEnabled: true },
-        interfaceType: 'ETHERNET',
-        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:1::/64'],
-        dnsServerIpAddressesOverride: ['2001:4860:4860::8888', '2001:4860:4860::8844'],
-      },
-    });
-    const props: NetworkProps = {
-      ...PROPS,
-      ipv6Configuration: {
-        clientAddressAssignment: { slaacEnabled: true },
-        interfaceType: 'ETHERNET',
-        additionalHostIpSubnets: ['2001:db8:1::/64', '2001:db8::/64'],
-        dnsServerIpAddressesOverride: ['2001:4860:4860::8844', '2001:4860:4860::8888'],
-      },
-    };
-    expect(matches(attributesOf(live, props), props)).toBe(true);
-  });
-
-  test('a different set of IPv6 host subnets is an update', () => {
-    const live = liveNetwork({
-      ipv6Configuration: {
-        clientAddressAssignment: { slaacEnabled: true },
-        interfaceType: 'ETHERNET',
-        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:1::/64'],
-      },
-    });
-    const props: NetworkProps = {
-      ...PROPS,
-      ipv6Configuration: {
-        clientAddressAssignment: { slaacEnabled: true },
-        interfaceType: 'ETHERNET',
-        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:2::/64'],
-      },
-    };
-    expect(matches(attributesOf(live, props), props)).toBe(false);
-  });
-
-  test('a live `null` (not `undefined`) for either field does not throw', () => {
-    // UniFi's JSON answers `null` for an unset optional field (see network-form.ts's header) —
-    // a reality the SDK's `T | undefined` types don't model. The double cast lands `null` at
-    // runtime the same way a real JSON decode would, past what the type system alone allows.
-    const live = {
-      ...liveNetwork(),
-      dhcpGuarding: null,
-      ipv6Configuration: null,
-    } as unknown as networks.NetworkDetails;
-    const declared = declareNetwork(live, 'site-1');
-    expect(() => attributesOf(live, declared)).not.toThrow();
-    expect(matches(attributesOf(live, declared), declared)).toBe(true);
-  });
-});
-
 describe('Unifi.Network write paths never reach the vendor API', () => {
   const ops = unifiOperations(spec);
 

package/src/unifi/network.ts

@@ -23,17 +23,17 @@ import { adopt } from 'alchemy/AdoptPolicy';
 import * as Provider from 'alchemy/Provider';
 import * as networks from '@distilled.cloud/unifi-network/networks';
 import * as Effect from 'effect/Effect';
-import {
-  type NetworkAttributes,
-  type NetworkProps,
-  attributesOf,
-  matches,
-} from './network-form.ts';
+import { type NetworkAttributes, type NetworkProps, attributesOf } from './network-form.ts';
+import { matches } from './network-drift.ts';
 import type { UnifiRequirements, UnifiSpec } from './resource.ts';
 import { unifiHandlers } from './resource.ts';
 
 export type { NetworkAttributes, NetworkProps } from './network-form.ts';
 export { declareNetwork } from './network-form.ts';
+// MEDIUM-4: `matches` moved here from `network-form.ts` — see network-drift.ts's own header. Not
+// re-exported from this barrel file either, same as before the move: `spec.matches` below is the
+// only consumer a provider needs.
+export { driftOf } from './network-drift.ts';
 
 export interface UnifiNetwork extends Resource<
   'Unifi.Network',

package/src/unifi/paginate.test.ts

@@ -0,0 +1,228 @@
+/**
+ * `pageAll` (B0b/T9) — pure walk-logic tests against a synthetic fetcher, the three IMPORTANT-3
+ * consistency checks (red team, 2026-09-26) against fetchers that lie the exact ways a real vendor
+ * response could, and one integration test proving it type-checks and decodes against a REAL SDK
+ * list operation (`getNetworksOverviewPage`) through the fake UniFi server. `M2`: this file does
+ * not repeat the 404/500 decode tests `network.test.ts` already covers — those are about ONE
+ * page's failure, not the walk this file exists to prove.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as networks from '@distilled.cloud/unifi-network/networks';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type OffsetPage, UnifiPaginationInconsistent, pageAll } from './paginate.ts';
+
+interface Row {
+  readonly id: number;
+}
+
+/** A fake dataset served `pageSize` rows at a time, the same envelope every real list op uses —
+ *  including `offset` echoed back exactly as requested, the honest case every OTHER test in this
+ *  file deviates from on purpose. */
+const fakePages = (rows: readonly Row[], pageSize: number) => {
+  const calls: { offset: number; limit: number | undefined }[] = [];
+  const fetchPage = (request: { offset?: number; limit?: number }) => {
+    const offset = request.offset ?? 0;
+    calls.push({ offset, limit: request.limit });
+    return Effect.succeed<OffsetPage<Row>>({
+      data: rows.slice(offset, offset + pageSize),
+      offset,
+      totalCount: rows.length,
+    });
+  };
+  return { calls, fetchPage };
+};
+
+const flip = <A>(effect: Effect.Effect<A, UnifiPaginationInconsistent>) =>
+  Effect.runPromise(Effect.flip(effect));
+
+describe('pageAll -- walk logic', () => {
+  test('walks every page in order and returns every row exactly once', async () => {
+    const rows = Array.from({ length: 7 }, (_, id) => ({ id }));
+    const { calls, fetchPage } = fakePages(rows, 3);
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { limit: 3 }));
+
+    expect(result).toEqual(rows);
+    expect(calls).toEqual([
+      { offset: 0, limit: 3 },
+      { offset: 3, limit: 3 },
+      { offset: 6, limit: 3 },
+    ]);
+  });
+
+  test('a single page under the limit stops after one call', async () => {
+    const rows = [{ id: 1 }, { id: 2 }];
+    const { calls, fetchPage } = fakePages(rows, 10);
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { limit: 10 }));
+
+    expect(result).toEqual(rows);
+    expect(calls).toHaveLength(1);
+  });
+
+  test('zero rows total makes exactly one call and returns empty', async () => {
+    const { calls, fetchPage } = fakePages([], 5);
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { limit: 5 }));
+
+    expect(result).toEqual([]);
+    expect(calls).toHaveLength(1);
+  });
+
+  test('T9: keeps paging on totalCount even when every page is short of the limit', async () => {
+    // A page shorter than `limit` is NOT by itself "last page" -- only `totalCount` is. This
+    // fetcher returns exactly one row per call (as if capped server-side, independent of `limit`)
+    // while `totalCount` says three exist; a pager that stopped on `data.length < limit` would
+    // truncate after the FIRST call and silently drop rows 2 and 3 -- the exact T9 failure mode.
+    const offsetsSeen: number[] = [];
+    const fetchPage = (request: { offset?: number; limit?: number }) => {
+      const offset = request.offset ?? 0;
+      offsetsSeen.push(offset);
+      return Effect.succeed<OffsetPage<Row>>({ data: [{ id: offset }], offset, totalCount: 3 });
+    };
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { limit: 10 }));
+
+    expect(result).toEqual([{ id: 0 }, { id: 1 }, { id: 2 }]);
+    expect(offsetsSeen).toEqual([0, 1, 2]);
+  });
+
+  test('resumes from a caller-given offset instead of always starting at 0', async () => {
+    const rows = Array.from({ length: 5 }, (_, id) => ({ id }));
+    const { calls, fetchPage } = fakePages(rows, 2);
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { offset: 2, limit: 2 }));
+
+    expect(result).toEqual(rows.slice(2));
+    expect(calls[0]).toEqual({ offset: 2, limit: 2 });
+  });
+
+  test('a failure from one page propagates instead of being swallowed', async () => {
+    const boom = new Error('boom');
+    const fetchPage = () => Effect.fail(boom);
+
+    const result = await Effect.runPromise(Effect.flip(pageAll(fetchPage, { limit: 5 })));
+
+    expect(result).toBe(boom);
+  });
+});
+
+describe('pageAll -- IMPORTANT-3: typed failures on a self-contradicting response', () => {
+  test('the server ignoring offset (always echoing 0) fails as offset-mismatch, not an infinite loop', async () => {
+    let calls = 0;
+    const fetchPage = () => {
+      calls += 1;
+      // Always answers page 1, regardless of the requested offset -- the "offset ignored" trap.
+      return Effect.succeed<OffsetPage<Row>>({
+        data: [{ id: 1 }, { id: 2 }],
+        offset: 0,
+        totalCount: 5,
+      });
+    };
+
+    const failure = await flip(pageAll(fetchPage, { limit: 2 }));
+
+    expect(failure).toBeInstanceOf(UnifiPaginationInconsistent);
+    expect(failure.reason).toBe('offset-mismatch');
+    // The FIRST page (offset 0 requested, 0 echoed) is fine; the SECOND (offset 2 requested, 0
+    // echoed) is what trips it -- proving this stops the walk instead of cycling forever.
+    expect(calls).toBe(2);
+  });
+
+  test('totalCount drifting between calls fails as total-count-changed', async () => {
+    let call = 0;
+    const fetchPage = (request: { offset?: number; limit?: number }) => {
+      call += 1;
+      const offset = request.offset ?? 0;
+      // A row is removed after the first page is read -- totalCount drops from 3 to 2.
+      return Effect.succeed<OffsetPage<Row>>({
+        data: [{ id: offset }],
+        offset,
+        totalCount: call === 1 ? 3 : 2,
+      });
+    };
+
+    const failure = await flip(pageAll(fetchPage, { limit: 1 }));
+
+    expect(failure.reason).toBe('total-count-changed');
+  });
+
+  test('an undercounted totalCount fails loudly instead of silently truncating (T9)', async () => {
+    // The exact scenario named in review: totalCount says 0 but the vendor still returns real
+    // rows on the one page fetched before the loop (correctly) stops on totalCount -- the OLD
+    // behavior returned those 2 rows as if they were the complete, correct answer.
+    const fetchPage = () =>
+      Effect.succeed<OffsetPage<Row>>({ data: [{ id: 1 }, { id: 2 }], offset: 0, totalCount: 0 });
+
+    const failure = await flip(pageAll(fetchPage, { limit: 10 }));
+
+    expect(failure.reason).toBe('row-count-mismatch');
+  });
+
+  test('a walk that never reaches totalCount fails at the page ceiling instead of looping forever', async () => {
+    // Offset IS honored (so this never trips offset-mismatch first) but totalCount is inflated far
+    // past what MAX_PAGES worth of single-row pages could ever reach -- the walk is internally
+    // consistent page-to-page, just never converges, which only the ceiling can catch.
+    const fetchPage = (request: { offset?: number; limit?: number }) =>
+      Effect.succeed<OffsetPage<Row>>({
+        data: [{ id: request.offset ?? 0 }],
+        offset: request.offset ?? 0,
+        totalCount: 1_000_000,
+      });
+
+    const failure = await flip(pageAll(fetchPage, { limit: 1 }));
+
+    expect(failure.reason).toBe('page-ceiling');
+  });
+
+  test('an honest, well-behaved server never trips any of the three checks', async () => {
+    const rows = Array.from({ length: 9 }, (_, id) => ({ id }));
+    const { fetchPage } = fakePages(rows, 4);
+
+    const result = await Effect.runPromise(pageAll(fetchPage, { limit: 4 }));
+
+    expect(result).toEqual(rows);
+  });
+});
+
+describe('pageAll -- against the real SDK (decode proof)', () => {
+  test('walks two real pages of getNetworksOverviewPage through the fake server', async () => {
+    const allNetworks = Array.from({ length: 3 }, (_, i) => ({
+      default: i === 0,
+      enabled: true,
+      id: `net-${i}`,
+      management: 'ADVANCED',
+      metadata: { origin: 'USER' as const },
+      name: `Network ${i}`,
+      vlanId: i + 1,
+    }));
+    const fake = fakeUnifi((method, url) => {
+      if (
+        method !== 'GET' ||
+        url.pathname !== '/proxy/network/integration/v1/sites/site-1/networks'
+      ) {
+        return fakeFailure(400, 'unexpected request');
+      }
+      const offset = Number(url.searchParams.get('offset') ?? '0');
+      const limit = Number(url.searchParams.get('limit') ?? '2');
+      return Response.json({
+        count: allNetworks.slice(offset, offset + limit).length,
+        data: allNetworks.slice(offset, offset + limit),
+        limit,
+        offset,
+        totalCount: allNetworks.length,
+      });
+    });
+
+    const result = await Effect.runPromise(
+      pageAll(networks.getNetworksOverviewPage, { siteId: 'site-1', limit: 2 }).pipe(
+        Effect.provide(fakeUnifiLayer(fake.fetch)),
+      ),
+    );
+
+    expect(result.map((n) => n.id)).toEqual(['net-0', 'net-1', 'net-2']);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen).toHaveLength(2);
+  });
+});

package/src/unifi/paginate.ts

@@ -0,0 +1,129 @@
+/**
+ * B0b / T9: a CONSUMER-SIDE sequential offset-pager for the SDK's list operations. None of them
+ * paginate on their own — `getNetworksOverviewPage`, `getFirewallZones`, `getAclRules`, … all take
+ * `{ ..., offset?, limit? }` and answer `{ count, data, limit, offset, totalCount }` (the shape
+ * `protocol.ts`'s own header names); there is no `smithy.api#paginated` trait in the pinned spec
+ * to generate a helper from.
+ *
+ * ⛔ NO SDK OR `@distilled.cloud/core` CHANGE (M1 — upstream's own convention: pagination stays
+ *   out of the 59 packages walked down for `distilled-doctrine`). This is a plain function over
+ *   whatever `Effect.Effect<OffsetPage<T>, E, R>` a resource file's own `fetchPage` already is.
+ * ⛔ STOPS ON `totalCount`, NEVER ON `data.length < limit` (T9's own wording). A page can come back
+ *   short of the requested `limit` for reasons unrelated to "this was the last page" (a vendor-side
+ *   per-call cap, a narrow filter) — `totalCount` is the one number the response commits to, so it
+ *   is the only thing this loop trusts to stop early. An empty page (`data.length === 0`) is the
+ *   other legitimate stop, and the only one checked before `totalCount` is read.
+ * ⚠️ NOT SEQUENCED AGAINST A LIVE CONSOLE THAT MUTATES BETWEEN CALLS. `totalCount` is whatever the
+ *   MOST RECENT page reported; a page walk racing a live edit could see a row twice, miss one, or
+ *   just see a moving target. `homeflare-network`'s own import already treats one family's fetch
+ *   as one sequenced run for this reason (T27's neighboring trap) — nothing here can fix a
+ *   concurrent mutation, only DETECT the common ways one shows up (below) instead of returning a
+ *   silently wrong row set.
+ *
+ * ⚠️ RED TEAM (2026-09-26, IMPORTANT-3): the first version of this file trusted the vendor's
+ *   paged response completely — a lying or drifting `totalCount`, an ignored `offset`, or a row
+ *   added/removed mid-walk all produced a WRONG row set with no signal at all (silent truncation,
+ *   an infinite loop, or a subtly incomplete list an importer would commit as if it were correct).
+ *   Every list op's response already carries `offset` alongside `totalCount` (`networks.ts`'s
+ *   `NetworkOverviewPage`, and `protocol.ts`'s header for every OTHER list op too); the three
+ *   checks below are consistency proofs built entirely from fields the vendor already sends, plus
+ *   a hard ceiling as a backstop against a walk that can never converge. These are typed failures,
+ *   not `Effect.die`: an inconsistent paged response is a VENDOR-DATA condition a caller may
+ *   legitimately want to retry or report on (distilled-doctrine: a defect is for "structurally
+ *   impossible" code paths, not for data the wire actually sent).
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+/** The one response shape every UniFi Network list operation already has (`protocol.ts`). */
+export interface OffsetPage<T> {
+  readonly data: readonly T[];
+  readonly offset: number;
+  readonly totalCount: number;
+}
+
+/** The one request shape every UniFi Network list operation already accepts, plus its own fields. */
+export type OffsetPageRequest = { readonly offset?: number; readonly limit?: number };
+
+/** Well past any family's real row count, even at a one-row page size (`docs/unifi.md`: a real
+ *  console's largest family is in the hundreds, not thousands) — a walk that reaches this many
+ *  pages is not looking at a real UniFi site, it is looking at a response that never lets `offset`
+ *  converge on `totalCount`. */
+const MAX_PAGES = 1000;
+
+export class UnifiPaginationInconsistent extends Data.TaggedError('UnifiPaginationInconsistent')<{
+  readonly reason:
+    | 'offset-mismatch'
+    | 'total-count-changed'
+    | 'row-count-mismatch'
+    | 'page-ceiling';
+  readonly detail: string;
+}> {
+  override get message(): string {
+    return (
+      `UniFi pager: ${this.reason} -- ${this.detail}. The paged response contradicted itself (or ` +
+      'the walk ran implausibly long); the rows collected so far cannot be trusted and are not returned.'
+    );
+  }
+}
+
+/**
+ * Walks every page of `fetchPage`, starting at `request.offset ?? 0`, and returns every row in
+ * order. `request.limit`, if given, is kept as the page size for every call; the vendor's own
+ * default applies otherwise — this loop never invents one (T18: "pass ops only their own fields").
+ *
+ * Three self-consistency checks run against fields the vendor already sends with every page —
+ * detection, not a fix, for the "live console mutates mid-walk" case the header above accepts as
+ * unfixable from the client alone: a row added AND removed in the same window can still net out to
+ * a `totalCount` and final row count that agree by coincidence. What this closes is the SILENT
+ * version of every case actually observed in review: an ignored `offset`, a `totalCount` that
+ * drifts between calls, and an undercounted `totalCount` that truncates the walk early.
+ */
+export const pageAll = <Req extends OffsetPageRequest, T, E, R>(
+  fetchPage: (request: Req) => Effect.Effect<OffsetPage<T>, E, R>,
+  request: Req,
+): Effect.Effect<T[], E | UnifiPaginationInconsistent, R> =>
+  Effect.gen(function* () {
+    const rows: T[] = [];
+    const startOffset = request.offset ?? 0;
+    let offset = startOffset;
+    let totalCount: number | undefined;
+    for (let pageCount = 1; ; pageCount++) {
+      if (pageCount > MAX_PAGES) {
+        return yield* new UnifiPaginationInconsistent({
+          reason: 'page-ceiling',
+          detail: `stopped after ${MAX_PAGES} pages at offset ${offset} without reaching totalCount`,
+        });
+      }
+      // ⚠️ THE CAST IS SOUND, NOT A SHORTCUT: `Req` is a generic parameter, so TS cannot see that
+      //   spreading a value already typed `Req` and overriding one of `OffsetPageRequest`'s own
+      //   fields reconstructs a `Req` — but every field except `offset` is untouched from the
+      //   caller's own `request`, so it does.
+      const page = yield* fetchPage({ ...request, offset } as Req);
+      if (page.offset !== offset) {
+        return yield* new UnifiPaginationInconsistent({
+          reason: 'offset-mismatch',
+          detail: `requested offset ${offset}, page echoed ${page.offset} -- rows may be duplicated or skipped`,
+        });
+      }
+      if (totalCount !== undefined && page.totalCount !== totalCount) {
+        return yield* new UnifiPaginationInconsistent({
+          reason: 'total-count-changed',
+          detail: `totalCount changed from ${totalCount} to ${page.totalCount} between page calls`,
+        });
+      }
+      totalCount = page.totalCount;
+      rows.push(...page.data);
+      if (page.data.length === 0) break;
+      offset += page.data.length;
+      if (offset >= totalCount) break;
+    }
+    const expected = totalCount - startOffset;
+    if (rows.length !== expected) {
+      return yield* new UnifiPaginationInconsistent({
+        reason: 'row-count-mismatch',
+        detail: `collected ${rows.length} rows but totalCount(${totalCount}) - startOffset(${startOffset}) = ${expected}`,
+      });
+    }
+    return rows;
+  });

package/src/unifi/resource.ts

@@ -37,8 +37,8 @@ import type { Input } from 'alchemy/Input';
 import { CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
 import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
 import * as Effect from 'effect/Effect';
-import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { refuseWrite } from './policy.ts';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import { UNIFI_READ_ONLY_POLICY, refuseWrite } from './policy.ts';
 
 /** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
 export type UnifiRequirements = HttpClient.HttpClient;
@@ -107,6 +107,76 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
   };
 };
 
+/**
+ * B0a / T12 DEFENSE IN DEPTH. `policy.ts`'s `UnifiWriteRefused` stops write INTENT at
+ * `reconcile`/`destroy` — every path this engine exposes already returns that refusal instead of
+ * calling an SDK write op. This guard stops the same thing one layer lower, AT THE WIRE: it wraps
+ * whatever `HttpClient` the caller already provides (the stack's `FetchHttpClient.layer` in
+ * production, `fakeUnifiLayer` in tests — `openbao/bao-http.ts`'s header names this same
+ * "wrap, don't replace" seam) so a future resource file that, by mistake, called an SDK write
+ * operation directly — bypassing `unifiOperations` entirely — would still never reach the vendor
+ * API. `write-op-reference.test.ts` proves no such call exists today; this is what stops one from
+ * ever taking effect if one is ever added.
+ *
+ * ⚠️ `Effect.die`, NOT A TYPED FAILURE — classified per distilled-doctrine's "classify every
+ *   die/orDie". Every generated SDK operation (`networks.getNetworkDetails`, …) declares its OWN
+ *   closed error union from the pinned OpenAPI spec, and generated files are never hand-edited to
+ *   add a member to it. A typed `Effect.fail` here would be a failure mode absent from every op's
+ *   declared type the moment it occurred — a type-system lie. A defect is the sound way to add a
+ *   NEW "this must be structurally impossible" failure underneath types this package does not
+ *   own, exactly like `openbao`'s `refuse()` helpers' `Effect.die(new Error(...))` for a
+ *   configuration move that should never be reachable.
+ */
+export class UnifiNonGetRequest extends Error {
+  constructor(
+    readonly method: string,
+    /** PATH ONLY, never the full URL — see `requestPath` below. */
+    readonly path: string,
+  ) {
+    super(
+      `UniFi HttpClient guard: refused ${method} ${path} -- ${UNIFI_READ_ONLY_POLICY}. This is a ` +
+        'defect, not a recoverable condition: something under src/unifi tried to send a non-GET ' +
+        "request, which policy.ts's per-operation refusal should already have made impossible. " +
+        'Fix the kit code that produced this request.',
+    );
+    this.name = 'UnifiNonGetRequest';
+  }
+}
+
+/**
+ * ⛔ PATH ONLY, NEVER THE HOST. A cloud connector's base URL embeds the account's Console ID
+ *   (`docs/unifi.md`'s Credentials section, T3) — a defect message is still a message that can
+ *   reach a log, a CI failure body or a pasted error report, so it gets the same treatment as
+ *   `redactUrls` gives the import layer's own error text. Falls back to a fixed placeholder rather
+ *   than the raw string on a parse failure, so a malformed URL can never leak through unredacted.
+ */
+const requestPath = (url: string): string => {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return '<unparseable request url>';
+  }
+};
+
+const guardGetOnly = (client: HttpClient.HttpClient): HttpClient.HttpClient =>
+  client.pipe(
+    HttpClient.mapRequestEffect((request) =>
+      request.method === 'GET'
+        ? Effect.succeed(request)
+        : Effect.die(new UnifiNonGetRequest(request.method, requestPath(request.url))),
+    ),
+  );
+
+/**
+ * A `Layer` that reads whatever `HttpClient` is already in the calling context and replaces it,
+ * for everything downstream, with `guardGetOnly`'s wrapped version (`HttpClient.layerMergedContext`
+ * — see the guard above). Exported so `get-only-guard.test.ts` can prove the mechanism directly,
+ * against a bare `HttpClient` service, without needing `CredentialsFromEnv` or any env var at all.
+ */
+export const GetOnlyHttpClient = HttpClient.layerMergedContext(
+  Effect.map(HttpClient.HttpClient, guardGetOnly),
+);
+
 /**
  * The four provider handlers for a spec'd read-only UniFi object, wired once.
  *
@@ -118,7 +188,7 @@ export const unifiHandlers = <Props extends object, Live, Attributes extends obj
 ) => {
   const ops = unifiOperations(spec);
   const withCredentials = <A, Err>(effect: Effect.Effect<A, Err, UnifiNetworkOpContext>) =>
-    Effect.provide(effect, CredentialsFromEnv);
+    effect.pipe(Effect.provide(GetOnlyHttpClient), Effect.provide(CredentialsFromEnv));
   return {
     list: () => Effect.succeed([]),
     read: (args: { olds: Props; output: Attributes | undefined }) =>