@homeflare/alchemy 0.38.0 → 0.40.0

package/src/unifi/firewall-policy-ordering.test.ts

@@ -0,0 +1,185 @@
+/**
+ * `Unifi.FirewallPolicyOrdering`'s `spec` against a fake UniFi Network API — mirrors
+ * `acl-rule-ordering.test.ts`. The two things this file exists to prove that no other family test
+ * does: the zone-pair QUERY identity actually reaches the wire (unlike `acl-rule-ordering.ts`'s
+ * one-per-site path with no query at all), and T5's "order IS the value, never `sortedSet`" rule
+ * holds independently for BOTH `beforeSystemDefined` and `afterSystemDefined`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+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, driftOf, matches } from './firewall-policy-ordering-form.ts';
+import {
+  type FirewallPolicyOrderingProps,
+  declareFirewallPolicyOrdering,
+  spec,
+} from './firewall-policy-ordering.ts';
+import { unifiOperations } from './resource.ts';
+
+const ORDERING_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/ordering';
+
+const liveOrdering = (
+  overrides: Partial<firewall.IntegrationFirewallPolicyOrderingDto> = {},
+): firewall.IntegrationFirewallPolicyOrderingDto => ({
+  orderedFirewallPolicyIds: {
+    beforeSystemDefined: ['fp-1', 'fp-2'],
+    afterSystemDefined: ['fp-9'],
+  },
+  ...overrides,
+});
+
+const PROPS: FirewallPolicyOrderingProps = {
+  siteId: 'site-1',
+  sourceFirewallZoneId: 'zone-iot',
+  destinationFirewallZoneId: 'zone-external',
+  beforeSystemDefined: ['fp-1', 'fp-2'],
+  afterSystemDefined: ['fp-9'],
+};
+
+describe('Unifi.FirewallPolicyOrdering spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object, with the zone pair as a query', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.orderedFirewallPolicyIds.beforeSystemDefined).toEqual(['fp-1', 'fp-2']);
+    expect(fake.seen).toHaveLength(1);
+    const sentUrl = new URL(`http://x${fake.seen[0]?.path}`);
+    expect(sentUrl.pathname).toBe(ORDERING_PATH);
+    expect(sentUrl.searchParams.get('sourceFirewallZoneId')).toBe('zone-iot');
+    expect(sentUrl.searchParams.get('destinationFirewallZoneId')).toBe('zone-external');
+  });
+
+  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();
+  });
+
+  test('a 500 fails loudly -- only a genuine not-found may mean absent (T14)', async () => {
+    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('declareFirewallPolicyOrdering -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: { beforeSystemDefined: ['fp-5'], afterSystemDefined: [] },
+    });
+    const declared = declareFirewallPolicyOrdering(live, 'site-1', 'zone-iot', 'zone-external');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('T5 -- order IS the value, never sortedSet, independently on each half', () => {
+  test('an identical pair of lists is a noop', () => {
+    expect(driftOf(liveOrdering(), PROPS)).toEqual([]);
+    expect(matches(attributesOf(liveOrdering(), PROPS), PROPS)).toBe(true);
+  });
+
+  test('the SAME ids in a DIFFERENT order within beforeSystemDefined is real drift', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-2', 'fp-1'],
+        afterSystemDefined: ['fp-9'],
+      },
+    });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'beforeSystemDefined', live: ['fp-2', 'fp-1'], declared: ['fp-1', 'fp-2'] },
+    ]);
+  });
+
+  test('a reorder within afterSystemDefined alone is caught, beforeSystemDefined untouched', () => {
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-1', 'fp-2'],
+        afterSystemDefined: ['fp-9', 'fp-10'],
+      },
+    });
+    const props: FirewallPolicyOrderingProps = { ...PROPS, afterSystemDefined: ['fp-10', 'fp-9'] };
+    expect(driftOf(live, props)).toEqual([
+      { field: 'afterSystemDefined', live: ['fp-9', 'fp-10'], declared: ['fp-10', 'fp-9'] },
+    ]);
+  });
+
+  test('a policy moving from beforeSystemDefined to afterSystemDefined drifts on both fields', () => {
+    // The two halves can never swap through this endpoint by "reordering" alone -- membership moving
+    // across them is a genuine drift on each side independently, not one combined-list reorder.
+    const live = liveOrdering({
+      orderedFirewallPolicyIds: {
+        beforeSystemDefined: ['fp-1'],
+        afterSystemDefined: ['fp-2', 'fp-9'],
+      },
+    });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'beforeSystemDefined', live: ['fp-1'], declared: ['fp-1', 'fp-2'] },
+      { field: 'afterSystemDefined', live: ['fp-2', 'fp-9'], declared: ['fp-9'] },
+    ]);
+  });
+});
+
+describe('Unifi.FirewallPolicyOrdering 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 === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : 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 (a reorder) refuses instead of PUTting the whole pair', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(
+            liveOrdering({
+              orderedFirewallPolicyIds: {
+                beforeSystemDefined: ['fp-2', 'fp-1'],
+                afterSystemDefined: [],
+              },
+            }),
+          )
+        : 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 === ORDERING_PATH
+        ? Response.json(liveOrdering())
+        : 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/firewall-policy-ordering.ts

@@ -0,0 +1,87 @@
+/**
+ * `Unifi.FirewallPolicyOrdering` — the ordered `before`/`afterSystemDefined` policy-id lists for
+ * ONE `(sourceFirewallZoneId, destinationFirewallZoneId)` zone pair (`getFirewallPolicyOrdering`,
+ * `GET /v1/sites/{siteId}/firewall/policies/ordering`), READ-ONLY (`policy.ts`). T5/I4's per-family
+ * variant: `docs/unifi.md`'s own header named this "a future `Unifi.FirewallPolicyOrdering`" as a
+ * separate, bigger PR (see `acl-rule-ordering.ts`'s header for the same forward reference, now
+ * resolved) — this is that resource.
+ *
+ * ⚠️ NOT ONE OBJECT PER SITE, UNLIKE `acl-rule-ordering.ts` — the identity is the TRIPLE
+ *   `(siteId, sourceFirewallZoneId, destinationFirewallZoneId)`, both zone ids passed as QUERY
+ *   parameters on the same path every time (`firewall.ts`'s `GetFirewallPolicyOrderingRequest`).
+ *   There is no "list every zone pair with an ordering" endpoint — a caller (a future Lane C import)
+ *   has to already know which pairs exist, typically by walking `firewall.getFirewallPolicies`
+ *   (T9's own 424-live-policy scale — B0b's `pageAll`, see `firewall-policy.test.ts`'s own decode
+ *   proof) and grouping by each policy's `source.zoneId`/`destination.zoneId`. Nothing here performs
+ *   that discovery — this resource is one already-known pair's ordering, same as
+ *   `firewall-policy.ts`/`acl-rule.ts` are one already-known object's own fields.
+ */
+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 FirewallPolicyOrderingAttributes,
+  type FirewallPolicyOrderingProps,
+  attributesOf,
+  matches,
+} from './firewall-policy-ordering-form.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type {
+  FirewallPolicyOrderingAttributes,
+  FirewallPolicyOrderingProps,
+} from './firewall-policy-ordering-form.ts';
+export { declareFirewallPolicyOrdering, driftOf } from './firewall-policy-ordering-form.ts';
+
+export interface UnifiFirewallPolicyOrdering extends Resource<
+  'Unifi.FirewallPolicyOrdering',
+  FirewallPolicyOrderingProps,
+  FirewallPolicyOrderingAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiFirewallPolicyOrdering = Resource<UnifiFirewallPolicyOrdering>(
+  'Unifi.FirewallPolicyOrdering',
+  { defaultRemovalPolicy: 'retain' },
+);
+
+/** `firewallPolicyOrdering('iot-to-external', props)` — `adopt(true)` piped on by default (H5); see
+ *  `network.ts`. */
+export const firewallPolicyOrdering = (id: string, props: FirewallPolicyOrderingProps) =>
+  UnifiFirewallPolicyOrdering(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  FirewallPolicyOrderingProps,
+  firewall.IntegrationFirewallPolicyOrderingDto,
+  FirewallPolicyOrderingAttributes,
+  firewall.GetFirewallPolicyOrderingError
+> = {
+  type: 'Unifi.FirewallPolicyOrdering',
+  describe: (props) =>
+    `sites/${props.siteId}/firewall/policies/ordering` +
+    `?sourceFirewallZoneId=${props.sourceFirewallZoneId}` +
+    `&destinationFirewallZoneId=${props.destinationFirewallZoneId}`,
+  fetchLive: (props) =>
+    firewall
+      .getFirewallPolicyOrdering({
+        siteId: props.siteId,
+        sourceFirewallZoneId: props.sourceFirewallZoneId,
+        destinationFirewallZoneId: props.destinationFirewallZoneId,
+      })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiFirewallPolicyOrderingProvider = () =>
+  Provider.effect(
+    UnifiFirewallPolicyOrdering,
+    Effect.succeed(UnifiFirewallPolicyOrdering.Provider.of(handlers)),
+  );

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

@@ -0,0 +1,183 @@
+/**
+ * `Unifi.FirewallPolicy`'s `spec` against a fake UniFi Network API — mirrors `acl-rule.test.ts`/
+ * `dns-policy.test.ts`.
+ *
+ * ⚠️ `driftOf`/`matches` coverage lives in `firewall-policy-drift.test.ts` (the field-level table
+ *   plus I2's per-field completeness check) and `firewall-policy-filter-roundtrip.test.ts` (I1's
+ *   filter-bearing round trip) — both split out to keep this file under the house 250-line cap once
+ *   that coverage grew, same split `network-drift.test.ts` is from `network.test.ts`, not a
+ *   different family. Red team, 2026-09-26.
+ *
+ * The last `describe` block is this family's own decode-proof of B0b's `pageAll` (T9) — not used by
+ * `spec.fetchLive` itself (`getFirewallPolicy` reads one policy by id directly, same as
+ * `acl-rule.ts`), but a real console's FirewallPolicy list is the one T9 names by scale (424 live
+ * policies, `alchemy-ledger-network.md:13`) — `paginate.test.ts`'s own "against the real SDK" section
+ * proves the pager's decode path against `networks.getNetworksOverviewPage`; this proves it against
+ * `firewall.getFirewallPolicies`'s own page shape too, so a future Lane C import walking this
+ * family's full list is walking a shape this suite has already exercised end to end.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+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 } from './firewall-policy-form.ts';
+import { driftOf, matches } from './firewall-policy-drift.ts';
+import { type FirewallPolicyProps, declareFirewallPolicy, spec } from './firewall-policy.ts';
+import { pageAll } from './paginate.ts';
+import { unifiOperations } from './resource.ts';
+
+const POLICY_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/fp-1';
+
+const liveFirewallPolicy = (
+  overrides: Partial<firewall.FirewallPolicy> = {},
+): firewall.FirewallPolicy => ({
+  action: { type: 'ALLOW' },
+  connectionStateFilter: ['ESTABLISHED', 'RELATED'],
+  description: 'Allow IoT devices outbound to the internet',
+  destination: { zoneId: 'zone-external' },
+  enabled: true,
+  id: 'fp-1',
+  index: 3,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: false,
+  metadata: { origin: 'USER' },
+  name: 'Allow IoT to Internet',
+  source: { zoneId: 'zone-iot' },
+  ...overrides,
+});
+
+const PROPS: FirewallPolicyProps = {
+  siteId: 'site-1',
+  firewallPolicyId: 'fp-1',
+  action: { type: 'ALLOW' },
+  connectionStateFilter: ['ESTABLISHED', 'RELATED'],
+  description: 'Allow IoT devices outbound to the internet',
+  destination: { zoneId: 'zone-external' },
+  enabled: true,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: false,
+  name: 'Allow IoT to Internet',
+  source: { zoneId: 'zone-iot' },
+};
+
+describe('Unifi.FirewallPolicy spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('fp-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: POLICY_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 (T14)', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 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('declareFirewallPolicy -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveFirewallPolicy({
+      connectionStateFilter: ['RELATED', 'ESTABLISHED'],
+      index: 9,
+    });
+    const declared = declareFirewallPolicy(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+  });
+});
+
+describe('Unifi.FirewallPolicy 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 === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : 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 PATCHing/PUTting a merged body', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveFirewallPolicy({ enabled: false }))
+        : 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 === POLICY_PATH
+        ? Response.json(liveFirewallPolicy())
+        : 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([]);
+  });
+});
+
+describe("T9/B0b -- pageAll walks this family's own page shape (decode proof)", () => {
+  test('every row across several pages of getFirewallPolicies decodes, in order', async () => {
+    const rows = Array.from({ length: 7 }, (_, i) =>
+      liveFirewallPolicy({ id: `fp-${i}`, index: i }),
+    );
+    const fake = fakeUnifi((method, url) => {
+      if (
+        method !== 'GET' ||
+        url.pathname !== '/proxy/network/integration/v1/sites/site-1/firewall/policies'
+      ) {
+        return fakeFailure(400, 'unexpected request');
+      }
+      const offset = Number(url.searchParams.get('offset') ?? '0');
+      const limit = Number(url.searchParams.get('limit') ?? '3');
+      const data = rows.slice(offset, offset + limit);
+      return Response.json({ count: data.length, data, limit, offset, totalCount: rows.length });
+    });
+
+    const result = await Effect.runPromise(
+      pageAll(firewall.getFirewallPolicies, { siteId: 'site-1', limit: 3 }).pipe(
+        Effect.provide(fakeUnifiLayer(fake.fetch)),
+      ),
+    );
+
+    expect(result.map((p) => p.id)).toEqual(rows.map((r) => r.id));
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen).toHaveLength(3);
+  });
+});

package/src/unifi/firewall-policy.ts

@@ -0,0 +1,73 @@
+/**
+ * `Unifi.FirewallPolicy` — one firewall policy on a UniFi Network site, READ-ONLY (`policy.ts`).
+ * `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`) is the sibling resource for policy
+ * ORDER within a zone pair (T5) — one per `(sourceFirewallZoneId, destinationFirewallZoneId)`, never
+ * this file's concern. `docs/unifi.md`'s own header names this pair as "a bigger, separate PR";
+ * this is that PR — see `docs/unifi-firewall-policy.md` for the full breakdown.
+ *
+ * ★ T11 GATE, CHECKED 2026-09-26: the `Firewall` tag's 13 operations (5 already covered for
+ *   `Unifi.FirewallZone` in `docs/unifi.md`, 8 new here for `FirewallPolicy` — `getFirewallPolicies`,
+ *   `createFirewallPolicy`, `getFirewallPolicyOrdering`, `updateFirewallPolicyOrdering`,
+ *   `deleteFirewallPolicy`, `getFirewallPolicy`, `patchFirewallPolicy`, `updateFirewallPolicy`) are
+ *   byte-identical between 10.4.57 and 10.6.97, full raw operation objects; the 106-schema closure
+ *   reachable from all 13 (`$ref` + `discriminator.mapping`) shares zero names with the 14 schemas
+ *   that DID change elsewhere in the document. Corroborated independently by the A3 changeset's own
+ *   broader 25-operation/139-schema re-check (`.changeset/unifi-network-a3-typed-discriminator-filters.md`).
+ *   Full breakdown: `docs/unifi-firewall-policy.md`.
+ */
+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 FirewallPolicyAttributes,
+  type FirewallPolicyProps,
+  attributesOf,
+} from './firewall-policy-form.ts';
+import { matches } from './firewall-policy-drift.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { FirewallPolicyAttributes, FirewallPolicyProps } from './firewall-policy-form.ts';
+export { declareFirewallPolicy } from './firewall-policy-form.ts';
+export { driftOf } from './firewall-policy-drift.ts';
+
+export interface UnifiFirewallPolicy extends Resource<
+  'Unifi.FirewallPolicy',
+  FirewallPolicyProps,
+  FirewallPolicyAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiFirewallPolicy = Resource<UnifiFirewallPolicy>('Unifi.FirewallPolicy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `firewallPolicy('block-iot-wan', props)` — `adopt(true)` piped on by default (H5); see
+ *  `network.ts`. */
+export const firewallPolicy = (id: string, props: FirewallPolicyProps) =>
+  UnifiFirewallPolicy(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  FirewallPolicyProps,
+  firewall.FirewallPolicy,
+  FirewallPolicyAttributes,
+  firewall.GetFirewallPolicyError
+> = {
+  type: 'Unifi.FirewallPolicy',
+  describe: (props) => `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
+  fetchLive: (props) =>
+    firewall
+      .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiFirewallPolicyProvider = () =>
+  Provider.effect(UnifiFirewallPolicy, Effect.succeed(UnifiFirewallPolicy.Provider.of(handlers)));

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

@@ -13,6 +13,7 @@
  *   the same reasoning `proxmox/user-wire.ts`'s `groupSet` gives for PVE's `groups`.
  */
 import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import { makeDriftOf } from './drift.ts';
 
 export interface FirewallZoneProps {
   siteId: string;
@@ -45,9 +46,37 @@ export const attributesOf = (
   metadataOrigin: live.metadata.origin,
 });
 
+/**
+ * B6: `fieldDrift` (`makeDriftOf`, `drift.ts`) is now the ONLY comparison this family has — MEDIUM-4
+ * (red team, 2026-09-26): a hand-written `matches` kept beside `fieldDrift` is two field lists an
+ * edit to one can silently leave out of sync with the other (a mutant deleting a `fieldDrift` entry
+ * left every test green, because `matches` never consulted it). `matches(attrs, props) ===
+ * (driftOf(live, props).length === 0)` is now true BY CONSTRUCTION, not just by a test that happens
+ * to check both. `networkIds`' custom `equal` is the set comparison the family has always used —
+ * see the header — and its reported `live`/`declared` values in a `driftOf` result are the SORTED
+ * arrays, not the joined strings this `equal` compares internally, so a real diff reads as a set
+ * difference, not two opaque strings.
+ */
+const fieldDrift = makeDriftOf<FirewallZoneAttributes, FirewallZoneProps>([
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  {
+    field: 'networkIds',
+    live: (a) => a.networkIds,
+    declared: (p) => sortedSet(p.networkIds),
+    equal: (live, declared) => (live as string[]).join(',') === (declared as string[]).join(','),
+  },
+]);
+
 export const matches = (attributes: FirewallZoneAttributes, props: FirewallZoneProps): boolean =>
-  attributes.name === props.name &&
-  attributes.networkIds.join(',') === sortedSet(props.networkIds).join(',');
+  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: firewall.FirewallZone, props: FirewallZoneProps) =>
+  fieldDrift(attributesOf(live, props), props);
 
 /**
  * The declaration renderer (task spec: "given one live object, return the props a declaration

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

@@ -5,7 +5,7 @@ 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 { attributesOf, driftOf, matches } from './firewall-zone-form.ts';
 import { type FirewallZoneProps, declareFirewallZone, spec } from './firewall-zone.ts';
 import { unifiOperations } from './resource.ts';
 
@@ -59,6 +59,26 @@ describe('declareFirewallZone -- the declaration renderer', () => {
   });
 });
 
+describe('driftOf -- B6 field-level drift, straight from one live read', () => {
+  test('a live object that matches its declaration drifts on nothing, order included', () => {
+    // `networkIds` in a different order is a noop for `matches` (the header's own rule) --
+    // `driftOf` must agree, not report a set that only LOOKS different because of order.
+    expect(driftOf(liveZone(), PROPS)).toEqual([]);
+  });
+
+  test('a real name change reports its own field, live and declared', () => {
+    const live = liveZone({ name: 'Garage' });
+    expect(driftOf(live, PROPS)).toEqual([{ field: 'name', live: 'Garage', declared: 'Cameras' }]);
+  });
+
+  test('a genuine networkIds difference reports SORTED arrays, not joined strings', () => {
+    const live = liveZone({ networkIds: ['net-1'] });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'networkIds', live: ['net-1'], declared: ['net-1', 'net-2'] },
+    ]);
+  });
+});
+
 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) =>

package/src/unifi/firewall-zone.ts

@@ -25,7 +25,7 @@ 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 { declareFirewallZone, driftOf } from './firewall-zone-form.ts';
 
 export interface UnifiFirewallZone extends Resource<
   'Unifi.FirewallZone',