@homeflare/alchemy 0.31.2 → 0.33.0

package/src/unifi/firewall-zone.test.ts

@@ -0,0 +1,88 @@
+/**
+ * `Unifi.FirewallZone`'s `spec` against a fake UniFi Network API — mirrors `network.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { attributesOf, matches } from './firewall-zone-form.ts';
+import { type FirewallZoneProps, declareFirewallZone, spec } from './firewall-zone.ts';
+import { unifiOperations } from './resource.ts';
+
+const ZONE_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/zones/zone-1';
+
+const liveZone = (overrides: Partial<firewall.FirewallZone> = {}): firewall.FirewallZone => ({
+  id: 'zone-1',
+  metadata: { origin: 'USER' },
+  name: 'Cameras',
+  networkIds: ['net-2', 'net-1'],
+  ...overrides,
+});
+
+const PROPS: FirewallZoneProps = {
+  siteId: 'site-1',
+  firewallZoneId: 'zone-1',
+  name: 'Cameras',
+  networkIds: ['net-1', 'net-2'],
+};
+
+describe('Unifi.FirewallZone spec.fetchLive', () => {
+  test('a real GET response decodes, and networkIds order does not affect matches', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ZONE_PATH
+        ? Response.json(liveZone())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('zone-1');
+    const attrs = attributesOf(live as firewall.FirewallZone, PROPS);
+    expect(matches(attrs, PROPS)).toBe(true);
+  });
+
+  test('a genuine 404 folds to undefined', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+});
+
+describe('declareFirewallZone -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveZone({ networkIds: ['net-9', 'net-3', 'net-3'] });
+    const declared = declareFirewallZone(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('Unifi.FirewallZone write paths never reach the vendor API', () => {
+  test('reconcile on an exact-match adoption (H6) sends only the one read', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ZONE_PATH
+        ? Response.json(liveZone())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      unifiOperations(spec)
+        .reconcile(PROPS)
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Success');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi(() => fakeFailure(400, 'unexpected request'));
+    const exit = await Effect.runPromiseExit(
+      unifiOperations(spec)
+        .destroy(PROPS)
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/firewall-zone.ts

@@ -0,0 +1,66 @@
+/**
+ * `Unifi.FirewallZone` — one firewall zone on a UniFi Network site, READ-ONLY (`policy.ts`).
+ *
+ * ★ WHY FIREWALL ZONE IS IN THE FIRST IMPORT SET AND `Unifi.FirewallPolicy` IS NOT.
+ *   `getFirewallZone`/`getFirewallZones` (`firewall.ts`) is a list+get pair over genuine,
+ *   simply-shaped configuration: `{id, metadata, name, networkIds}`, four fields, no nested
+ *   discriminated filter. `FirewallPolicy` (same file) is also list+get and also configuration,
+ *   but its `source`/`destination`/`ipProtocolScope` fields carry several of `docs/unifi-api-notes.md`'s
+ *   "converter-flattened discriminator variants" each, and `firewall/policies/ordering` replaces
+ *   the whole ordered list — modelling those correctly is a bigger, separate PR (`network.ts`'s
+ *   header note names it explicitly) rather than something to rush alongside this one.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import {
+  type FirewallZoneAttributes,
+  type FirewallZoneProps,
+  attributesOf,
+  matches,
+} from './firewall-zone-form.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { FirewallZoneAttributes, FirewallZoneProps } from './firewall-zone-form.ts';
+export { declareFirewallZone } from './firewall-zone-form.ts';
+
+export interface UnifiFirewallZone extends Resource<
+  'Unifi.FirewallZone',
+  FirewallZoneProps,
+  FirewallZoneAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiFirewallZone = Resource<UnifiFirewallZone>('Unifi.FirewallZone', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `firewallZone('lan', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export const firewallZone = (id: string, props: FirewallZoneProps) =>
+  UnifiFirewallZone(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  FirewallZoneProps,
+  firewall.FirewallZone,
+  FirewallZoneAttributes,
+  firewall.GetFirewallZoneError
+> = {
+  type: 'Unifi.FirewallZone',
+  describe: (props) => `sites/${props.siteId}/firewall/zones/${props.firewallZoneId}`,
+  fetchLive: (props) =>
+    firewall
+      .getFirewallZone({ siteId: props.siteId, firewallZoneId: props.firewallZoneId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiFirewallZoneProvider = () =>
+  Provider.effect(UnifiFirewallZone, Effect.succeed(UnifiFirewallZone.Provider.of(handlers)));

package/src/unifi/index.ts

@@ -0,0 +1,26 @@
+/**
+ * UniFi Network providers for Alchemy — READ-ONLY, by Tim's rule (2026-09-24; `policy.ts`).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, SMALLER THAN THE DIRECTORY. `resource.ts`'s generic engine
+ *   and each `*-form.ts`'s wire helpers are internals a provider needs but a consumer should
+ *   not depend on — mirrors `../netbox/index.ts`.
+ */
+export { UNIFI_READ_ONLY_POLICY, UnifiWriteRefused, type UnifiWriteAction } from './policy.ts';
+export type { UnifiRequirements, UnifiSpec } from './resource.ts';
+export {
+  UnifiNetwork,
+  UnifiNetworkProvider,
+  declareNetwork,
+  network,
+  type NetworkAttributes,
+  type NetworkProps,
+} from './network.ts';
+export {
+  UnifiFirewallZone,
+  UnifiFirewallZoneProvider,
+  declareFirewallZone,
+  firewallZone,
+  type FirewallZoneAttributes,
+  type FirewallZoneProps,
+} from './firewall-zone.ts';
+export { providers } from './providers.ts';

package/src/unifi/network-form.ts

@@ -0,0 +1,207 @@
+/**
+ * `Unifi.Network`'s wire shape: the declarable subset of `NetworkDetails`, and how a live read
+ * becomes both plan attributes and a rendered declaration.
+ *
+ * ⚠️ PROPS MIRROR `UpdateNetworkRequest`, NOT `NetworkDetails`. `default` and `metadata` are
+ *   server-derived — no writable endpoint in `networks.ts` accepts either — so they are
+ *   attributes-only, reported but never compared or declared. Everything else in `NetworkProps`
+ *   is exactly what `updateNetwork`/`createNetwork` would accept, even though this family never
+ *   calls either: the shape is what a future write path would need, and what today's read-only
+ *   `matches` compares against.
+ *
+ * ⛔ `ipv4Configuration` STAYS `unknown`, ON THE SDK'S OWN AUTHORITY. `networks.ts`'s own comment
+ *   ("Shape varies by variant — widened by scripts/convert.ts; see README") says the OpenAPI
+ *   discriminator this field varies over was flattened at generation time, not decoded per
+ *   variant. Comparing it as an opaque JSON value (below) is honest about that; guessing a
+ *   narrower shape here would silently stop matching the day a new variant's key order differs.
+ *   ⚠️ It may ALSO hide an unordered array the way `dhcpGuarding` and `ipv6Configuration` do
+ *   below — this family just can't know, because the shape is never decoded. If a future variant
+ *   plans spurious `update`s, suspect this field first and widen it into a typed, order-normalized
+ *   shape rather than adding another opaque comparison.
+ *
+ * ⛔ THREE FIELDS ARE SETS, NOT SEQUENCES: `dhcpGuarding.trustedDhcpServerIpAddresses`,
+ *   `ipv6Configuration.additionalHostIpSubnets`, and `ipv6Configuration.dnsServerIpAddressesOverride`.
+ *   The vendor document gives no indication any of the three is ordered — same reasoning
+ *   `firewall-zone-form.ts` gives for `networkIds`, and `proxmox/user-wire.ts`'s `groupSet` gives
+ *   for PVE's `groups` — but `matches` compares via alchemy's `deepEqual`, which sorts object KEYS
+ *   but NOT ARRAY ELEMENTS (`node_modules/alchemy/lib/Diff.js`). Left alone, a console that
+ *   returns the same set in a different order between calls plans a spurious `update`, and the
+ *   read-only reconcile then refuses every deploy. `sortedSet` (dedupe + sort) neutralizes that
+ *   before any of the three is attributed, declared, or compared. Every OTHER array field in this
+ *   family (there are none today besides these three) would stay declaration-order as written.
+ */
+import { deepEqual } from 'alchemy/Diff';
+import type * as networks from '@distilled.cloud/unifi-network/networks';
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+// ⚠️ `value == null` (NOT `=== undefined`) ON PURPOSE, IN BOTH NORMALIZERS BELOW. The SDK types
+//   `dhcpGuarding`/`ipv6Configuration` `T | undefined`, but `matches`'s own header says UniFi's
+//   JSON answers `null` for an unset optional field — a reality `deepEqual`'s `stripNullish`
+//   already treats as equivalent to `undefined` (`value == null` in alchemy's `Diff.js`), which
+//   this family's props/attributes types don't model at the TS level. Destructuring a `null` with
+//   `=== undefined`'s false branch (`{ ...value, field: value.field }`) would throw
+//   `TypeError: Cannot read properties of null` the first time a console omits either field —
+//   `== null` catches both and returns the value through untouched, matching what the rest of
+//   this file already does for every other optional field.
+const normalizeDhcpGuarding = (
+  value: networks.NetworkDHCPGuarding | undefined,
+): networks.NetworkDHCPGuarding | undefined =>
+  value == null
+    ? value
+    : { ...value, trustedDhcpServerIpAddresses: sortedSet(value.trustedDhcpServerIpAddresses) };
+
+// ⚠️ `exactOptionalPropertyTypes` (see the props header) means these two subfields must be
+//   OMITTED, not set to an explicit `undefined`, when the live/declared value has no override —
+//   `NetworkIPv6Configuration` types them `field?: T`, not `field?: T | undefined`. Conditional
+//   spread (rather than `field: value.field === undefined ? undefined : sortedSet(...)`) is what
+//   keeps an absent key absent.
+const normalizeIpv6Configuration = (
+  value: networks.NetworkIPv6Configuration | undefined,
+): networks.NetworkIPv6Configuration | undefined =>
+  value == null
+    ? value
+    : {
+        ...value,
+        ...(value.additionalHostIpSubnets !== undefined
+          ? { additionalHostIpSubnets: sortedSet(value.additionalHostIpSubnets) }
+          : {}),
+        ...(value.dnsServerIpAddressesOverride !== undefined
+          ? { dnsServerIpAddressesOverride: sortedSet(value.dnsServerIpAddressesOverride) }
+          : {}),
+      };
+
+/**
+ * ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` ON PURPOSE. `tsconfig.json` sets
+ *   `exactOptionalPropertyTypes`, which treats `field?: T` (absent-or-T) and
+ *   `field?: T | undefined` (absent-or-explicitly-undefined) as different types. `declareNetwork`
+ *   below assigns `live.dhcpGuarding` (typed `T | undefined`) straight through — the whole point
+ *   of a renderer that echoes a live optional field structurally rather than defaulting it — so
+ *   the target has to admit an explicit `undefined`, not just omission.
+ */
+export interface NetworkProps {
+  siteId: string;
+  networkId: string;
+  name: string;
+  enabled: boolean;
+  management: string;
+  /** VLAN ID. Must be 1 for the default network and >= 2 for additional networks. */
+  vlanId: number;
+  dhcpGuarding?: networks.NetworkDHCPGuarding | undefined;
+  cellularBackupEnabled?: boolean | undefined;
+  internetAccessEnabled?: boolean | undefined;
+  /** Opaque — see the header. */
+  ipv4Configuration?: unknown;
+  ipv6Configuration?: networks.NetworkIPv6Configuration | undefined;
+  isolationEnabled?: boolean | undefined;
+  mdnsForwardingEnabled?: boolean | undefined;
+  zoneId?: string | undefined;
+  deviceId?: string | undefined;
+}
+
+export interface NetworkAttributes {
+  siteId: string;
+  networkId: string;
+  /** Whether this is the site's undeletable default network — server-derived, never declared. */
+  default: boolean;
+  name: string;
+  enabled: boolean;
+  management: string;
+  vlanId: number;
+  dhcpGuarding: networks.NetworkDHCPGuarding | undefined;
+  cellularBackupEnabled: boolean | undefined;
+  internetAccessEnabled: boolean | undefined;
+  ipv4Configuration: unknown;
+  ipv6Configuration: networks.NetworkIPv6Configuration | undefined;
+  isolationEnabled: boolean | undefined;
+  mdnsForwardingEnabled: boolean | undefined;
+  zoneId: string | undefined;
+  deviceId: string | undefined;
+}
+
+export const attributesOf = (
+  live: networks.NetworkDetails,
+  props: NetworkProps,
+): NetworkAttributes => ({
+  siteId: props.siteId,
+  networkId: live.id,
+  default: live.default,
+  name: live.name,
+  enabled: live.enabled,
+  management: live.management,
+  vlanId: live.vlanId,
+  dhcpGuarding: normalizeDhcpGuarding(live.dhcpGuarding),
+  cellularBackupEnabled: live.cellularBackupEnabled,
+  internetAccessEnabled: live.internetAccessEnabled,
+  ipv4Configuration: live.ipv4Configuration,
+  ipv6Configuration: normalizeIpv6Configuration(live.ipv6Configuration),
+  isolationEnabled: live.isolationEnabled,
+  mdnsForwardingEnabled: live.mdnsForwardingEnabled,
+  zoneId: live.zoneId,
+  deviceId: live.deviceId,
+});
+
+/**
+ * ⚠️ `stripNullish: true` ON EVERY COMPARISON. UniFi's JSON answers `null` for an unset optional
+ *   field; a declaration that omits the same prop carries `undefined`. Without this option every
+ *   plan against an object with one unset optional field would report `update` forever — the
+ *   exact "read and write are different shapes" trap `netbox/values.ts` and `proxmox/user-wire.ts`
+ *   both work around, here solved once with the engine's own `deepEqual` instead of a per-field
+ *   coercion, because nothing here needs PVE's or NetBox's extra wire-format translation.
+ */
+export const matches = (attributes: NetworkAttributes, props: NetworkProps): boolean =>
+  attributes.name === props.name &&
+  attributes.enabled === props.enabled &&
+  attributes.management === props.management &&
+  attributes.vlanId === props.vlanId &&
+  deepEqual(
+    normalizeDhcpGuarding(attributes.dhcpGuarding),
+    normalizeDhcpGuarding(props.dhcpGuarding),
+    {
+      stripNullish: true,
+    },
+  ) &&
+  deepEqual(attributes.cellularBackupEnabled, props.cellularBackupEnabled, {
+    stripNullish: true,
+  }) &&
+  deepEqual(attributes.internetAccessEnabled, props.internetAccessEnabled, {
+    stripNullish: true,
+  }) &&
+  deepEqual(attributes.ipv4Configuration, props.ipv4Configuration, { stripNullish: true }) &&
+  deepEqual(
+    normalizeIpv6Configuration(attributes.ipv6Configuration),
+    normalizeIpv6Configuration(props.ipv6Configuration),
+    { stripNullish: true },
+  ) &&
+  deepEqual(attributes.isolationEnabled, props.isolationEnabled, { stripNullish: true }) &&
+  deepEqual(attributes.mdnsForwardingEnabled, props.mdnsForwardingEnabled, {
+    stripNullish: true,
+  }) &&
+  deepEqual(attributes.zoneId, props.zoneId, { stripNullish: true }) &&
+  deepEqual(attributes.deviceId, props.deviceId, { stripNullish: true });
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). A later import script feeds `getNetworkDetails`'s own response
+ * straight in and writes the result into `alchemy.run.ts` as `network('<id>', declareNetwork(live,
+ * siteId))` — no field is invented or defaulted here beyond what `attributesOf` already reports,
+ * so `matches(attributesOf(live, props), declareNetwork(live, siteId))` is `true` by construction
+ * (`network.test.ts` proves it) for any live object this SDK can decode.
+ */
+export const declareNetwork = (live: networks.NetworkDetails, siteId: string): NetworkProps => ({
+  siteId,
+  networkId: live.id,
+  name: live.name,
+  enabled: live.enabled,
+  management: live.management,
+  vlanId: live.vlanId,
+  dhcpGuarding: normalizeDhcpGuarding(live.dhcpGuarding),
+  cellularBackupEnabled: live.cellularBackupEnabled,
+  internetAccessEnabled: live.internetAccessEnabled,
+  ipv4Configuration: live.ipv4Configuration,
+  ipv6Configuration: normalizeIpv6Configuration(live.ipv6Configuration),
+  isolationEnabled: live.isolationEnabled,
+  mdnsForwardingEnabled: live.mdnsForwardingEnabled,
+  zoneId: live.zoneId,
+  deviceId: live.deviceId,
+});

package/src/unifi/network.test.ts

@@ -0,0 +1,209 @@
+/**
+ * `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.
+ */
+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 { type NetworkProps, declareNetwork, spec } from './network.ts';
+import { unifiOperations } from './resource.ts';
+
+const NETWORK_PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
+
+const liveNetwork = (
+  overrides: Partial<networks.NetworkDetails> = {},
+): networks.NetworkDetails => ({
+  default: false,
+  enabled: true,
+  id: 'net-1',
+  management: 'ADVANCED',
+  metadata: { origin: 'USER' },
+  name: 'Cameras',
+  vlanId: 40,
+  isolationEnabled: true,
+  zoneId: 'zone-1',
+  ...overrides,
+});
+
+const PROPS: NetworkProps = {
+  siteId: 'site-1',
+  networkId: 'net-1',
+  name: 'Cameras',
+  enabled: true,
+  management: 'ADVANCED',
+  vlanId: 40,
+  isolationEnabled: true,
+  zoneId: 'zone-1',
+};
+
+describe('Unifi.Network spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('net-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: NETWORK_PATH }]);
+  });
+
+  test('a genuine 404 folds to undefined -- never a false "unreadable" on anything else', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 500 fails loudly -- only a genuine not-found may mean absent', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 (one of core's DEFAULT_ERROR_STATUSES)
+    //   indefinitely with backoff -- this test asserts the FAILURE, not the retry schedule.
+    const fake = fakeUnifi(() => fakeFailure(500, 'boom'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive(PROPS).pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('InternalServerError');
+  });
+});
+
+describe('declareNetwork -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveNetwork({ name: 'Guest', vlanId: 99, isolationEnabled: false });
+    const declared = declareNetwork(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+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);
+
+  test('reconcile on an exact-match adoption (H6) makes no request but the one read', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Success');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile on drift refuses instead of PUTting a merged body', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork({ vlanId: 999 }))
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.destroy(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/network.ts

@@ -0,0 +1,83 @@
+/**
+ * `Unifi.Network` — one network on a UniFi Network site, READ-ONLY (`policy.ts`).
+ *
+ * ★ WHY NETWORK IS IN THE FIRST IMPORT SET. `getNetworkDetails`/`getNetworksOverviewPage`
+ *   (`../../distilled-unifi-network/src/services/networks.ts`) is a list+get pair over
+ *   genuine configuration — VLAN, DHCP guarding, IPv4/IPv6 addressing, isolation — not runtime
+ *   state like a connected client, a device statistic or a hotspot voucher. It is also the SDK
+ *   package's own README recommendation for a first read/adopt-only resource, alongside `Site`
+ *   (skipped here — no `getSite`, only the list operation, so it fails this task's own "both a
+ *   list and a get" bar) and `FirewallZone`/`FirewallPolicy` (`firewall-zone.ts` ships
+ *   `FirewallZone`; `FirewallPolicy`'s several discriminated filter variants and its
+ *   list-replacing ordering endpoint are a bigger, separate PR).
+ *
+ * ⛔ THE WHOLE-OBJECT-PUT TRAP (`docs/unifi-api-notes.md`) NEVER FIRES HERE, BY CONSTRUCTION.
+ *   `updateNetwork` is a `PUT` that disables `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration`
+ *   outright when the caller omits them — the exact failure mode a read-only family cannot cause,
+ *   because `resource.ts`'s `reconcile` never calls `updateNetwork` at all. Recorded here for
+ *   whoever adds the write path this docs note anticipates: read-merge-write the WHOLE object,
+ *   never a props-only body.
+ */
+import { Resource } from 'alchemy';
+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 { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { NetworkAttributes, NetworkProps } from './network-form.ts';
+export { declareNetwork } from './network-form.ts';
+
+export interface UnifiNetwork extends Resource<
+  'Unifi.Network',
+  NetworkProps,
+  NetworkAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiNetwork = Resource<UnifiNetwork>('Unifi.Network', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * `network('lan', props)` — `adopt(true)` piped on by default (H5). This family never writes, so
+ * the only thing a first deploy against an existing network could ever do is bind to it or refuse
+ * `OwnedBySomeoneElse`; piping `adopt(true)` here picks the former without a stack having to
+ * remember `--adopt`, mirroring `discord/application-command.ts`'s `applicationCommand`.
+ */
+export const network = (id: string, props: NetworkProps) =>
+  UnifiNetwork(id, props).pipe(adopt(true));
+
+/**
+ * ★ EXPORTED for direct testing against a fake `Credentials` layer (`fake-unifi.ts`), the same
+ *   seam `netbox/prefix.ts`'s `spec` and `discord/application-command.ts`'s `spec` use — `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves environment variables a test cannot repoint.
+ */
+export const spec: UnifiSpec<
+  NetworkProps,
+  networks.NetworkDetails,
+  NetworkAttributes,
+  networks.GetNetworkDetailsError
+> = {
+  type: 'Unifi.Network',
+  describe: (props) => `sites/${props.siteId}/networks/${props.networkId}`,
+  fetchLive: (props) =>
+    networks
+      .getNetworkDetails({ siteId: props.siteId, networkId: props.networkId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiNetworkProvider = () =>
+  Provider.effect(UnifiNetwork, Effect.succeed(UnifiNetwork.Provider.of(handlers)));