@homeflare/alchemy 0.31.1 → 0.32.0

package/src/proxmox/user.ts

@@ -33,12 +33,12 @@
  *       user, so a role wide enough to edit the account can still be refused for one group.
  *     · `Sys.Audit` (or `User.Modify`) for the read, which the `read` role's auditor already has.
  *
- * ⚠️ A MISSING USER IS A 500, NOT A 404 — "no such user ('x@pve')". distilled turns that into an
- *   `UnknownProxmoxError` (protocol.ts), and `readOrUnreadable`'s own `orElseSucceed` folds it
- *   into "absent" same as the old hand-rolled client did. A 403 therefore also reads as absent
- *   UNLESS it is the one refusal `readOrUnreadable` catches (unreadable-read.ts): a REFUSED
- *   `provision` mint, the cries-wolf case. Any other refusal still reads as absent, and the
- *   honest error arrives one step later, from the create.
+ * ⚠️ A MISSING USER IS A 500, NOT A 404 — MEASURED against the live cluster, "no such user
+ *   ('x@pve')". distilled turns that into an `InternalServerError`, with no distinct "not found"
+ *   tag to catch. `user-wire.ts`'s `readUser` (used by `read`/`reconcile`, where the create
+ *   workflow needs "absent" from exactly this failure) still folds it; `readUserOrFail` (used by
+ *   `diff` below) does not — see that function's own header for why folding it there was the
+ *   cries-wolf bug all over again, just for a genuine PVE quirk instead of a permission denial.
  *
  * ⚠️ THE WIRE URL FOR THIS FAMILY CHANGED, THOUGH NOTHING A CALLER SEES DID. MEASURED
  *   (user.test.ts): distilled's `{userid}` label substitution percent-encodes it —
@@ -60,18 +60,15 @@ import * as Effect from 'effect/Effect';
 import { guardWrite } from './distilled-guard.ts';
 import type { PveRequirements, WithTarget } from './resource-spec.ts';
 import { runPve } from './distilled-pve.ts';
-import {
-  UNREADABLE,
-  type Unreadable,
-  readOrUnreadable,
-  unreadableWarning,
-} from './unreadable-read.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 import {
   USER_CREATE,
   USER_UPDATE,
-  attributesOf,
   createForm,
+  dropUnreadable,
   matches,
+  readUser,
+  readUserOrFail,
   updateForm,
 } from './user-wire.ts';
 
@@ -126,17 +123,6 @@ export interface ProxmoxUser extends Resource<
 
 export const ProxmoxUser = Resource<ProxmoxUser>('Proxmox.User');
 
-/** ★ Default `read` role for this family — only the write side needs `provision`. */
-const readUser = (props: UserProps) =>
-  readOrUnreadable(runPve(props.target, 'read', false, access.getAccessUser(props))).pipe(
-    Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))),
-    Effect.orElseSucceed(() => undefined),
-  );
-
-/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
-const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>
-  live === UNREADABLE ? undefined : live;
-
 export const ProxmoxUserProvider = () =>
   Provider.effect(
     ProxmoxUser,
@@ -148,15 +134,31 @@ export const ProxmoxUserProvider = () =>
          *   identity someone made years ago. Adoption is an explicit act.
          */
         list: () => Effect.succeed([]),
-        read: Effect.fn(function* ({ olds }) {
-          return dropUnreadable(yield* readUser(olds));
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined` — MEASURED 2026-09-24, an adversarial review
+        //   of this very fix caught the gap. The engine calls this ONE hook from FOUR places
+        //   (alchemy/src/{Plan,Apply,Drift}.ts), and only `output` tells them apart: Plan.ts's
+        //   cold-start adoption probe and interrupted-create recovery, and Apply.ts's
+        //   delete-recovery, all pass `output: undefined` — nothing is confirmed to exist yet, so
+        //   `readUser`'s fold is still needed there or a brand-new account could never be adopted
+        //   or created. `Drift.ts` (`alchemy drift`/`sync`/`deploy --detect-drift`) is different:
+        //   it calls this on an ALREADY-CONFIRMED row (`output: old.attr`, defined), exactly
+        //   `diff`'s own situation below — a transient failure folded to `undefined` there is
+        //   reported as `{action: 'missing'}` with NO error at all, the cries-wolf bug again, one
+        //   command over. `readUserOrFail` on that branch propagates it instead.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readUser(olds) : readUserOrFail(olds),
+          );
         }),
         diff: Effect.fn(function* ({ news, output }) {
           if (!isResolved(news)) return undefined;
           yield* guardWrite(USER_CREATE, createForm(news), output === undefined);
           yield* guardWrite(USER_UPDATE, updateForm(news), false);
           if (output === undefined) return undefined;
-          const live = yield* readUser(news);
+          // ⚠️ `readUserOrFail`, NOT `readUser` — see that function's own header (user-wire.ts).
+          //   A genuine failure here propagates and fails the whole plan loudly instead of
+          //   folding to "absent" and forcing a false update, the cries-wolf class of bug.
+          const live = yield* readUserOrFail(news);
           // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
           //   `update` on an account that was plainly there — see unreadable-read.ts.
           if (live === UNREADABLE) {

package/src/unifi/fake-unifi.ts

@@ -0,0 +1,60 @@
+/**
+ * A minimal in-memory UniFi Network API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring `../netbox/fake-netbox.ts`
+ * (itself mirroring `../forgejo/fake-forgejo.ts`). Tests exercise distilled's REAL path assembly,
+ * JSON encode/decode and status→typed-error matching — 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
+ *   `unifi.example.com` and the key is a placeholder — never a real console address: a cloud
+ *   connector's base URL embeds the account's Console ID, which must never appear in this repo
+ *   (`docs/unifi.md`).
+ */
+import { type Credentials, credentials } from '@distilled.cloud/unifi-network/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://unifi.example.com/proxy/network/integration';
+export const FAKE_KEY = 'placeholder-unifi-key';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** No documented failure envelope (see `protocol.ts`) — plain text is all a failure needs. */
+export const fakeFailure = (status: number, detail: string) => new Response(detail, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature.
+ *
+ * ★ THE WRITE-REFUSAL PROOF USES `seen` DIRECTLY, NOT A THROWING ROUTE. `resource.test.ts`'s
+ *   "no SDK write operation is reachable" test asserts `seen.every(s => s.method === 'GET')`
+ *   after driving every handler — a request this family's engine was never supposed to send
+ *   shows up in `seen` as a fact, rather than depending on an exception surviving Effect's own
+ *   error handling on its way back out of a fake `fetch`.
+ */
+export const fakeUnifi = (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 — `UnifiNetworkOpContext`, what
+ * every resource file's exported `spec.fetchLive` needs.
+ *
+ * ⚠️ NOT PAIRED WITH `handlers`. `handlers` (each resource file's `unifiHandlers(spec)` export)
+ *   bakes in `CredentialsFromEnv`, which resolves `UNIFI_NETWORK_API_KEY`/`_API_BASE_URL` through
+ *   Effect's `Config` — whose default provider snapshots `process.env` once and never re-reads it
+ *   (the same seam `netbox/fake-netbox.ts` documents). Tests call `spec.fetchLive`/`spec.attributes`
+ *   directly instead, with this explicit layer.
+ */
+export const fakeUnifiLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = credentials({ apiBaseUrl: FAKE_BASE, apiKey: FAKE_KEY }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

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

@@ -0,0 +1,65 @@
+/**
+ * `Unifi.FirewallZone`'s wire shape — the declarable subset of `FirewallZone`, and how a live
+ * read becomes both plan attributes and a rendered declaration.
+ *
+ * ⚠️ ONLY `name` AND `networkIds` ARE DECLARABLE. `CreateFirewallZoneRequest`
+ *   (`firewall.ts`) accepts exactly those two beyond `siteId`; `metadata` (origin/source) and
+ *   `id` are server-derived, so — same split as `network-form.ts`'s `default`/`metadata` —
+ *   they are attributes-only, reported but never compared or declared.
+ *
+ * ⛔ `networkIds` ORDER IS NOT PART OF IDENTITY. The vendor document gives no indication the
+ *   list is ordered (it is a set of attached networks, not a sequence like the ordering
+ *   endpoints' rule lists), so `matches` compares it as a set — sorted before comparing —
+ *   the same reasoning `proxmox/user-wire.ts`'s `groupSet` gives for PVE's `groups`.
+ */
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+
+export interface FirewallZoneProps {
+  siteId: string;
+  firewallZoneId: string;
+  /** Name of a firewall zone. */
+  name: string;
+  /** Network IDs attached to this zone — compared as a set, see the header. */
+  networkIds: string[];
+}
+
+export interface FirewallZoneAttributes {
+  siteId: string;
+  firewallZoneId: string;
+  name: string;
+  networkIds: string[];
+  /** `origin`/`source` (e.g. `SDWAN`) — server-derived, never declared. */
+  metadataOrigin: string;
+}
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+export const attributesOf = (
+  live: firewall.FirewallZone,
+  props: FirewallZoneProps,
+): FirewallZoneAttributes => ({
+  siteId: props.siteId,
+  firewallZoneId: live.id,
+  name: live.name,
+  networkIds: sortedSet(live.networkIds),
+  metadataOrigin: live.metadata.origin,
+});
+
+export const matches = (attributes: FirewallZoneAttributes, props: FirewallZoneProps): boolean =>
+  attributes.name === props.name &&
+  attributes.networkIds.join(',') === sortedSet(props.networkIds).join(',');
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). `matches(attributesOf(live, props), declareFirewallZone(live,
+ * siteId))` is `true` by construction (`firewall-zone.test.ts` proves it).
+ */
+export const declareFirewallZone = (
+  live: firewall.FirewallZone,
+  siteId: string,
+): FirewallZoneProps => ({
+  siteId,
+  firewallZoneId: live.id,
+  name: live.name,
+  networkIds: sortedSet(live.networkIds),
+});

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