@homeflare/alchemy 0.38.0 → 0.39.0

package/src/unifi/get-only-guard.test.ts

@@ -0,0 +1,165 @@
+/**
+ * `GetOnlyHttpClient` (`resource.ts`, B0a/T12) in isolation — against a bare `HttpClient` service,
+ * no `CredentialsFromEnv`, no real SDK operation. Proves the guard's own mechanism: a `GET`
+ * reaches the wrapped transport unchanged, and any other method dies with `UnifiNonGetRequest`
+ * BEFORE the fake server ever sees it (`fake.seen` stays empty for the refused call).
+ *
+ * ⚠️ NOT ROUTED THROUGH `unifiHandlers`/`CredentialsFromEnv` ON PURPOSE — see `fake-unifi.ts`'s
+ *   own warning: `CredentialsFromEnv` resolves `UNIFI_NETWORK_*` through Effect's `Config`, which
+ *   this directory's existing tests all avoid depending on for the same reason. Since the guard
+ *   only touches the `HttpClient` service, testing it directly here is both simpler and a more
+ *   precise proof of the mechanism than routing real credentials through it would be.
+ * ⚠️ CORRECTION (2026-09-26, red team): the line this replaces claimed `network.test.ts`/
+ *   `firewall-zone.test.ts` prove `withCredentials` lets a real GET through. They don't —
+ *   both call `unifiOperations(spec)` directly, which bypasses `unifiHandlers`/`withCredentials`
+ *   (and therefore this guard) entirely. Proof: deleting `Effect.provide(GetOnlyHttpClient)` from
+ *   `withCredentials` (`resource.ts`) left all 56 tests green before this file's own
+ *   `describe('GetOnlyHttpClient installed in unifiHandlers', …)` block below existed. THAT block
+ *   is what closes the gap: it drives `unifiHandlers(...).read`/`.reconcile` — the actual exported
+ *   entry points a real deploy calls — through a `ConfigProvider` override (the same pattern
+ *   `opnsense/write-refusal.test.ts` uses for `CredentialsFromEnv`), so it fails if the guard is
+ *   ever removed from `withCredentials` again.
+ * ★ REUSES `fakeUnifi` (`fake-unifi.ts`), NOT AN AD HOC MOCK. `fakeUnifi`'s wrapper records
+ *   `seen` BEFORE calling `route`, so even a `route` that would throw still proves whether the
+ *   guard let a request through — the assertion is on `seen`, never on catching that throw.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import type * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { FAKE_BASE, FAKE_KEY, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import {
+  GetOnlyHttpClient,
+  UnifiNonGetRequest,
+  type UnifiSpec,
+  unifiHandlers,
+} from './resource.ts';
+
+const FAKE_PATH = '/proxy/network/integration/v1/sites/site-1/networks';
+const FAKE_URL = `https://unifi.example.com${FAKE_PATH}`;
+
+/** One request through `GetOnlyHttpClient`, over a fake transport built by `fakeUnifi`. */
+const sendGuarded = (method: string, fetchFn: typeof globalThis.fetch) =>
+  Effect.runPromiseExit(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      return yield* client.execute(HttpClientRequest.make(method as never)(FAKE_URL));
+    }).pipe(Effect.provide(GetOnlyHttpClient), Effect.provide(fakeUnifiLayer(fetchFn))),
+  );
+
+describe('GetOnlyHttpClient', () => {
+  test('a GET request passes through unchanged and reaches the transport', async () => {
+    const fake = fakeUnifi(() => Response.json({ ok: true }));
+
+    const exit = await sendGuarded('GET', fake.fetch);
+
+    expect(Exit.isSuccess(exit)).toBe(true);
+    expect(fake.seen).toEqual([{ method: 'GET', path: FAKE_PATH }]);
+  });
+
+  test.each(['POST', 'PUT', 'PATCH', 'DELETE'])(
+    '%s dies with UnifiNonGetRequest and never reaches the transport',
+    async (method) => {
+      const fake = fakeUnifi(() => {
+        throw new Error(`get-only-guard.test.ts: unexpected ${method} reached the fake transport`);
+      });
+
+      const exit = await sendGuarded(method, fake.fetch);
+
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (!Exit.isFailure(exit)) return;
+      expect(Cause.hasDies(exit.cause)).toBe(true);
+      expect(Cause.hasFails(exit.cause)).toBe(false);
+      const defect = Cause.squash(exit.cause);
+      expect(defect).toBeInstanceOf(UnifiNonGetRequest);
+      expect((defect as UnifiNonGetRequest).method).toBe(method);
+      // ⛔ THE PROOF: the fake transport never even recorded the call -- the guard refused the
+      //   request in `mapRequestEffect`, before dispatch, not after a failed response.
+      expect(fake.seen).toEqual([]);
+    },
+  );
+});
+
+interface ProbeProps {
+  id: string;
+}
+
+/**
+ * A `fetchLive` that sends exactly one raw request over whatever `method` the test wants to
+ * probe — not a real SDK operation, on purpose: this block proves the GUARD'S INSTALLATION in
+ * `unifiHandlers`, not any one family's own all-GET behavior (`network.test.ts`/
+ * `firewall-zone.test.ts` already prove that, for calls that bypass `unifiHandlers` entirely).
+ */
+const probeSpec = (
+  method: string,
+): UnifiSpec<ProbeProps, ProbeProps, ProbeProps, HttpClientError.HttpClientError> => ({
+  type: 'Test.Probe',
+  describe: (props) => `probe/${props.id}`,
+  fetchLive: (props) =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      yield* client.execute(HttpClientRequest.make(method as never)(`${FAKE_BASE}/probe`));
+      return props;
+    }),
+  attributes: (live) => live,
+  matches: () => true,
+});
+
+/**
+ * Overrides the `ConfigProvider` `CredentialsFromEnv` resolves `UNIFI_NETWORK_*` against — the
+ * SAME pattern `opnsense/write-refusal.test.ts` uses for its own `CredentialsFromEnv` — WITHOUT
+ * touching real `process.env` (a parallel test file could race on that). `unifiHandlers`'s
+ * `withCredentials` bakes in `CredentialsFromEnv` itself, so providing a `Credentials` layer from
+ * OUTSIDE (the way `fake-unifi.ts`'s own `fakeUnifiLayer` does for tests that call `spec.fetchLive`
+ * directly) would be shadowed and do nothing here — this ConfigProvider override is what actually
+ * reaches it.
+ */
+const fakeCredentialsConfigProvider = ConfigProvider.layer(
+  ConfigProvider.fromUnknown({
+    UNIFI_NETWORK_API_BASE_URL: FAKE_BASE,
+    UNIFI_NETWORK_API_KEY: FAKE_KEY,
+  }),
+);
+
+describe('GetOnlyHttpClient is installed in unifiHandlers (IMPORTANT-1, red team 2026-09-26)', () => {
+  test('a GET through the real handler entry point still reaches the transport', async () => {
+    const fake = fakeUnifi(() => Response.json({ id: 'w1' }));
+    const attrs = await Effect.runPromise(
+      unifiHandlers(probeSpec('GET'))
+        .read({ olds: { id: 'w1' }, output: undefined })
+        .pipe(
+          Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), fakeCredentialsConfigProvider)),
+        ),
+    );
+    expect(attrs).toEqual({ id: 'w1' });
+    expect(fake.seen).toEqual([{ method: 'GET', path: '/proxy/network/integration/probe' }]);
+  });
+
+  test('a non-GET through the real handler entry point dies, never reaching the transport', async () => {
+    const fake = fakeUnifi(() => {
+      throw new Error('get-only-guard.test.ts: unexpected POST reached the fake transport');
+    });
+    const exit = await Effect.runPromiseExit(
+      unifiHandlers(probeSpec('POST'))
+        .read({ olds: { id: 'w1' }, output: undefined })
+        .pipe(
+          Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), fakeCredentialsConfigProvider)),
+        ),
+    );
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (!Exit.isFailure(exit)) return;
+    expect(Cause.hasDies(exit.cause)).toBe(true);
+    expect(Cause.squash(exit.cause)).toBeInstanceOf(UnifiNonGetRequest);
+    // ⛔ THIS IS THE PROOF THE FILE HEADER PROMISES. Verified by hand (2026-09-26): deleting
+    //   `Effect.provide(GetOnlyHttpClient)` from `withCredentials` (`resource.ts`) turns this
+    //   exact test into a passing `Response.json` round-trip with a non-empty `fake.seen` --
+    //   i.e. it FAILS the instant the guard installation regresses, which no test in this
+    //   directory could do before this block existed (IMPORTANT-1).
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/index.ts

@@ -6,7 +6,16 @@
  *   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 {
+  // Barrel-exported (not just internal to `unifiHandlers`) so `homeflare-network`'s own
+  // import-layer guard (plan item C0) can reuse this instead of re-implementing the same
+  // `HttpClient` wrap against a second copy of the SDK's `HttpClient.HttpClient` service.
+  GetOnlyHttpClient,
+  UnifiNonGetRequest,
+  type UnifiRequirements,
+  type UnifiSpec,
+} from './resource.ts';
+export type { FieldDrift } from './drift.ts';
 export {
   UnifiNetwork,
   UnifiNetworkProvider,
@@ -14,6 +23,10 @@ export {
   network,
   type NetworkAttributes,
   type NetworkProps,
+  // B6: renamed here, not in `network.ts` — `network-form.ts`'s `matches`/`attributesOf` name the
+  // same function identically per family (never barrel-exported); `driftOf` IS barrel-exported, so
+  // it needs a name unique across both families the moment it leaves `network.ts`.
+  driftOf as networkDriftOf,
 } from './network.ts';
 export {
   UnifiFirewallZone,
@@ -22,5 +35,6 @@ export {
   firewallZone,
   type FirewallZoneAttributes,
   type FirewallZoneProps,
+  driftOf as firewallZoneDriftOf,
 } from './firewall-zone.ts';
 export { providers } from './providers.ts';

package/src/unifi/network-drift.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `Unifi.Network`'s `driftOf`/`matches` (`network-drift.ts`, B6) — split out of `network.test.ts`
+ * to keep that file under the house 250-line cap once this coverage grew, not because this is a
+ * different family (same split `network-drift.ts` itself is from `network-form.ts`).
+ *
+ * Since MEDIUM-4 (red team, 2026-09-26), `matches` IS `fieldDrift(...).length === 0` — there is no
+ * second, hand-written comparison — so every test below exercises both functions together on
+ * purpose, proving they cannot disagree rather than merely asserting each looks right alone.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as networks from '@distilled.cloud/unifi-network/networks';
+import { attributesOf } from './network-form.ts';
+import { driftOf, matches } from './network-drift.ts';
+import { type NetworkProps, declareNetwork } from './network.ts';
+
+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('driftOf -- B6 field-level drift, straight from one live read', () => {
+  test('a live object that matches its declaration drifts on nothing', () => {
+    const live = liveNetwork();
+    expect(driftOf(live, PROPS)).toEqual([]);
+  });
+
+  test('a drifted field reports its own live and declared values, by name', () => {
+    const live = liveNetwork({ vlanId: 999 });
+    expect(driftOf(live, PROPS)).toEqual([{ field: 'vlanId', live: 999, declared: 40 }]);
+  });
+
+  test('agrees with matches() on every case matches() already covers', () => {
+    const live = liveNetwork({ name: 'Guest', vlanId: 7 });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+    expect(driftOf(live, PROPS).length > 0).toBe(true);
+  });
+
+  // MEDIUM-4 (red team, 2026-09-26) Mutant B: deleting the `zoneId`/`deviceId` entries from
+  // `fieldDrift` entirely left 56/56 green, because nothing exercised a live/declared difference
+  // on either field. `matches` now IS `fieldDrift(...).length === 0` (no second comparison to fall
+  // back on), so this closes the gap for both functions at once, not just `driftOf`. Verified by
+  // hand: reverting `fieldDrift` to drop these two entries fails both tests below.
+  test('a zoneId difference is caught, not silently dropped from either comparison', () => {
+    const live = liveNetwork({ zoneId: 'zone-9' });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+    expect(driftOf(live, PROPS)).toEqual([{ field: 'zoneId', live: 'zone-9', declared: 'zone-1' }]);
+  });
+
+  test('a deviceId difference is caught, not silently dropped from either comparison', () => {
+    const props: NetworkProps = { ...PROPS, deviceId: 'device-1' };
+    const live = liveNetwork({ deviceId: 'device-2' });
+    expect(matches(attributesOf(live, props), props)).toBe(false);
+    expect(driftOf(live, props)).toEqual([
+      { field: 'deviceId', live: 'device-2', declared: 'device-1' },
+    ]);
+  });
+});
+
+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);
+    // MEDIUM-4: `driftOf` shares `matches`' own field list now, so a normalizer this test relies
+    // on being applied to the DECLARED side (T15) getting dropped would show up here too.
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('the DECLARED side is also normalized, not just live (MEDIUM-4 mutant)', () => {
+    // The previous test's PROPS happens to already be sorted, so it can't tell a real normalizer
+    // from one silently applied to only the live side -- a red-team mutant that dropped
+    // `normalizeDhcpGuarding` from `network-drift.ts`'s DECLARED closure left every test (this
+    // file included, before this one) green. Reversing PROPS here, with live already sorted,
+    // exercises the declared-side call directly. Verified by hand: this test fails against that
+    // exact mutant; every other test in this file still passes against it.
+    const live = liveNetwork({
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.2'] },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.2', '10.0.0.1'] },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  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);
+    expect(driftOf(live, props).some((d) => d.field === 'dhcpGuarding')).toBe(true);
+  });
+
+  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);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('the DECLARED side of IPv6 subnets/DNS overrides is also normalized (MEDIUM-4 mutant)', () => {
+    // Same blind spot as the DHCP test above, for both ipv6Configuration override lists: live is
+    // already sorted here, so only reversing PROPS exercises the DECLARED side's normalizer.
+    const live = liveNetwork({
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8:1::/64', '2001:db8::/64'],
+        dnsServerIpAddressesOverride: ['2001:4860:4860::8844', '2001:4860:4860::8888'],
+      },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:1::/64'],
+        dnsServerIpAddressesOverride: ['2001:4860:4860::8888', '2001:4860:4860::8844'],
+      },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  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);
+    expect(driftOf(live, props).some((d) => d.field === 'ipv6Configuration')).toBe(true);
+  });
+
+  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);
+  });
+});

package/src/unifi/network-drift.ts

@@ -0,0 +1,80 @@
+/**
+ * `Unifi.Network`'s `matches` AND `driftOf` (B6) — both built on the ONE field list below, not two
+ * hand-kept-in-sync comparisons. `matches` used to be a separate boolean expression in
+ * `network-form.ts`; MEDIUM-4 (red team, 2026-09-26) found that a `fieldDrift` entry could be
+ * deleted entirely and every test still passed, because `matches` never consulted `fieldDrift` at
+ * all. `matches(attrs, props) === (driftOf(live, props).length === 0)` is now true BY
+ * CONSTRUCTION — there is exactly one comparison — and every `fieldDrift` entry names ONE field
+ * plus its own live/declared value instead of collapsing straight to a boolean.
+ *
+ * ⚠️ `stripNullish: true` ON EVERY FIELD BY DEFAULT (`drift.ts`'s `defaultEqual`). UniFi's JSON
+ *   answers `null` for an unset optional field; a declaration that omits the same prop carries
+ *   `undefined`. Without this, 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 by
+ *   `makeDriftOf`'s own default instead of a per-field coercion.
+ */
+import type * as networks from '@distilled.cloud/unifi-network/networks';
+import { makeDriftOf } from './drift.ts';
+import {
+  type NetworkAttributes,
+  type NetworkProps,
+  attributesOf,
+  normalizeDhcpGuarding,
+  normalizeIpv6Configuration,
+} from './network-form.ts';
+
+const fieldDrift = makeDriftOf<NetworkAttributes, NetworkProps>([
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  { field: 'management', live: (a) => a.management, declared: (p) => p.management },
+  { field: 'vlanId', live: (a) => a.vlanId, declared: (p) => p.vlanId },
+  {
+    field: 'dhcpGuarding',
+    live: (a) => normalizeDhcpGuarding(a.dhcpGuarding),
+    declared: (p) => normalizeDhcpGuarding(p.dhcpGuarding),
+  },
+  {
+    field: 'cellularBackupEnabled',
+    live: (a) => a.cellularBackupEnabled,
+    declared: (p) => p.cellularBackupEnabled,
+  },
+  {
+    field: 'internetAccessEnabled',
+    live: (a) => a.internetAccessEnabled,
+    declared: (p) => p.internetAccessEnabled,
+  },
+  {
+    field: 'ipv4Configuration',
+    live: (a) => a.ipv4Configuration,
+    declared: (p) => p.ipv4Configuration,
+  },
+  {
+    field: 'ipv6Configuration',
+    live: (a) => normalizeIpv6Configuration(a.ipv6Configuration),
+    declared: (p) => normalizeIpv6Configuration(p.ipv6Configuration),
+  },
+  {
+    field: 'isolationEnabled',
+    live: (a) => a.isolationEnabled,
+    declared: (p) => p.isolationEnabled,
+  },
+  {
+    field: 'mdnsForwardingEnabled',
+    live: (a) => a.mdnsForwardingEnabled,
+    declared: (p) => p.mdnsForwardingEnabled,
+  },
+  { field: 'zoneId', live: (a) => a.zoneId, declared: (p) => p.zoneId },
+  { field: 'deviceId', live: (a) => a.deviceId, declared: (p) => p.deviceId },
+]);
+
+export const matches = (attributes: NetworkAttributes, props: NetworkProps): boolean =>
+  fieldDrift(attributes, props).length === 0;
+
+/**
+ * Per-field live-vs-declared drift straight from one live read — the task's own API
+ * (`driftOf(live, props)`), so `homeflare-network`'s pre-import drift check never has to derive
+ * `attributesOf` itself just to call this.
+ */
+export const driftOf = (live: networks.NetworkDetails, props: NetworkProps) =>
+  fieldDrift(attributesOf(live, props), props);

package/src/unifi/network-form.ts

@@ -30,7 +30,6 @@
  *   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();
@@ -44,7 +43,10 @@ const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].
 //   `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 = (
+// ★ EXPORTED (not just used below): `network-drift.ts`'s `driftOf` reuses these exact two
+//   normalizers so it can never quietly disagree with `matches` about what counts as a change —
+//   see that file's own header.
+export const normalizeDhcpGuarding = (
   value: networks.NetworkDHCPGuarding | undefined,
 ): networks.NetworkDHCPGuarding | undefined =>
   value == null
@@ -56,7 +58,7 @@ const normalizeDhcpGuarding = (
 //   `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 = (
+export const normalizeIpv6Configuration = (
   value: networks.NetworkIPv6Configuration | undefined,
 ): networks.NetworkIPv6Configuration | undefined =>
   value == null
@@ -142,43 +144,13 @@ export const attributesOf = (
 });
 
 /**
- * ⚠️ `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.
+ * MEDIUM-4 (red team, 2026-09-26): `matches` used to be a hand-written boolean expression here,
+ * kept in sync BY HAND with `network-drift.ts`'s separately-maintained field list — two comparisons
+ * that could (and, per a red-team mutant, silently did) drift apart. `matches` now lives in
+ * `network-drift.ts`, defined as `fieldDrift(...).length === 0` — the SAME comparison `driftOf`
+ * runs, not a second one. See that file's own header for the `stripNullish`/normalizer reasoning
+ * this expression used to carry.
  */
-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