@homeflare/alchemy 0.38.0 → 0.40.0

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

@@ -0,0 +1,151 @@
+/**
+ * `Unifi.FirewallPolicy`'s `driftOf`/`matches` (`firewall-policy-drift.ts`, B6) — split out of
+ * `firewall-policy.test.ts` to keep that file under the house 250-line cap once this coverage grew,
+ * same split `network-drift.test.ts` is from `network.test.ts`, not a different family.
+ *
+ * The last `describe` closes red-team finding I2 (2026-09-26, PR 309 LAND): `firewall-policy-
+ * drift.ts`'s field list is untyped strings (`makeDriftOf`'s own contract) — deleting any 7 of its
+ * 11 entries left every test in `firewall-policy.test.ts` green. `DECLARABLE_FIELDS` below is a
+ * `Record<..., true>` keyed by `Exclude<keyof FirewallPolicyProps, 'siteId' | 'firewallPolicyId'>`
+ * — adding or removing a `FirewallPolicyProps` field without updating that record is a TYPE ERROR,
+ * so the list this test walks is complete BY CONSTRUCTION. Changing exactly one field at a time and
+ * asserting `driftOf` reports exactly that field's name means a field missing from the real
+ * `fieldDrift` array (as the red-team mutant produced) shows up here as "reports []" instead of
+ * "reports [field]" — the same failure the red team's own by-hand deletion produced, now a standing
+ * test instead of a one-off probe.
+ *
+ * I1 (the filter-bearing-policy round trip) lives in `firewall-policy-filter-roundtrip.test.ts` —
+ * a third split, not folded in here, to keep this file under the cap too.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import { attributesOf } from './firewall-policy-form.ts';
+import { driftOf, matches } from './firewall-policy-drift.ts';
+import type { FirewallPolicyProps } from './firewall-policy.ts';
+
+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('driftOf -- B6 field-level drift, straight from one live read', () => {
+  test('a real name change reports its own field, live and declared', () => {
+    const live = liveFirewallPolicy({ name: 'Allow IoT outbound' });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'name', live: 'Allow IoT outbound', declared: 'Allow IoT to Internet' },
+    ]);
+  });
+
+  test('connectionStateFilter in a different order is a noop -- it is a SET, not a sequence', () => {
+    const live = liveFirewallPolicy({ connectionStateFilter: ['RELATED', 'ESTABLISHED'] });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(true);
+    expect(driftOf(live, PROPS)).toEqual([]);
+  });
+
+  test('the DECLARED side of connectionStateFilter is also normalized (MEDIUM-4 mutant)', () => {
+    const live = liveFirewallPolicy({ connectionStateFilter: ['ESTABLISHED', 'RELATED'] });
+    const props: FirewallPolicyProps = {
+      ...PROPS,
+      connectionStateFilter: ['RELATED', 'ESTABLISHED'],
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('a genuine connectionStateFilter difference is caught', () => {
+    const live = liveFirewallPolicy({ connectionStateFilter: ['NEW'] });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'connectionStateFilter', live: ['NEW'], declared: ['ESTABLISHED', 'RELATED'] },
+    ]);
+  });
+
+  test('index is never compared -- it is attributes-only, owned by FirewallPolicyOrdering', () => {
+    const live = liveFirewallPolicy({ index: 41 });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(true);
+    expect(attributesOf(live, PROPS).index).toBe(41);
+  });
+
+  test('source/destination compare wholesale -- a real zone change is still caught', () => {
+    const live = liveFirewallPolicy({ destination: { zoneId: 'zone-guest' } });
+    expect(driftOf(live, PROPS)).toEqual([
+      {
+        field: 'destination',
+        live: { zoneId: 'zone-guest' },
+        declared: { zoneId: 'zone-external' },
+      },
+    ]);
+  });
+});
+
+type DeclarableField = Exclude<keyof FirewallPolicyProps, 'siteId' | 'firewallPolicyId'>;
+
+const DECLARABLE_FIELDS: Record<DeclarableField, true> = {
+  action: true,
+  connectionStateFilter: true,
+  description: true,
+  destination: true,
+  enabled: true,
+  ipProtocolScope: true,
+  ipsecFilter: true,
+  loggingEnabled: true,
+  name: true,
+  schedule: true,
+  source: true,
+};
+
+/** One changed value per field -- distinct enough from PROPS' own that `deepEqual` calls it drift,
+ *  and (for `enabled`/`loggingEnabled`) not merely `undefined` vs a value, which `stripNullish`
+ *  would treat as a noop. */
+const CHANGED_VALUE: { [K in DeclarableField]: FirewallPolicyProps[K] } = {
+  action: { type: 'BLOCK' },
+  connectionStateFilter: ['NEW'],
+  description: 'a different description',
+  destination: { zoneId: 'zone-different' },
+  enabled: false,
+  ipProtocolScope: { ipVersion: 'IPV6' },
+  ipsecFilter: 'MATCH_ENCRYPTED',
+  loggingEnabled: true,
+  name: 'a different name',
+  schedule: { mode: 'EVERY_DAY' },
+  source: { zoneId: 'zone-different-2' },
+};
+
+describe('I2 -- every declarable field is wired into the drift field list', () => {
+  // `liveFirewallPolicy()` (no overrides) matches PROPS field-for-field (proved above), so
+  // changing exactly one PROPS field per case isolates that field's own wire-up.
+  test.each(Object.keys(DECLARABLE_FIELDS) as DeclarableField[])(
+    'changing only %s reports exactly that field',
+    (field) => {
+      const live = liveFirewallPolicy();
+      const changedProps: FirewallPolicyProps = { ...PROPS, [field]: CHANGED_VALUE[field] };
+      expect(driftOf(live, changedProps).map((d) => d.field)).toEqual([field]);
+    },
+  );
+});

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

@@ -0,0 +1,55 @@
+/**
+ * `Unifi.FirewallPolicy`'s `matches` AND `driftOf` (B6) — both built on the ONE field list below,
+ * the same `fieldDrift`-is-the-only-comparison shape `network-drift.ts`'s header explains (MEDIUM-4,
+ * red team, 2026-09-26): `matches(attrs, props) === (driftOf(live, props).length === 0)` is true
+ * BY CONSTRUCTION, never two hand-kept-in-sync comparisons.
+ *
+ * ⚠️ `stripNullish: true` ON EVERY FIELD BY DEFAULT (`drift.ts`'s `defaultEqual`) — same "UniFi's
+ *   JSON answers `null`, a declaration omits" tolerance every other family here relies on.
+ * ⛔ `connectionStateFilter` RUNS THROUGH `firewall-policy-form.ts`'s normalizer on BOTH sides
+ *   before comparing — never applied to only `live` or only `declared` (the specific gap MEDIUM-4's
+ *   own mutant found in `network-drift.ts`; see its header, and `acl-rule-drift.ts`'s own repeat of
+ *   this same rule for `protocolFilter`/`enforcingDeviceFilter`).
+ * ★ `action`/`destination`/`ipProtocolScope`/`schedule`/`source` compare with the plain default
+ *   `equal` (whole-value `deepEqual`) — see `firewall-policy-form.ts`'s header for the accepted
+ *   known gap this leaves in their own nested set-like arrays.
+ */
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import { makeDriftOf } from './drift.ts';
+import {
+  type FirewallPolicyAttributes,
+  type FirewallPolicyProps,
+  attributesOf,
+  normalizeConnectionStateFilter,
+} from './firewall-policy-form.ts';
+
+const fieldDrift = makeDriftOf<FirewallPolicyAttributes, FirewallPolicyProps>([
+  { field: 'action', live: (a) => a.action, declared: (p) => p.action },
+  {
+    field: 'connectionStateFilter',
+    live: (a) => normalizeConnectionStateFilter(a.connectionStateFilter),
+    declared: (p) => normalizeConnectionStateFilter(p.connectionStateFilter),
+  },
+  { field: 'description', live: (a) => a.description, declared: (p) => p.description },
+  { field: 'destination', live: (a) => a.destination, declared: (p) => p.destination },
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  { field: 'ipProtocolScope', live: (a) => a.ipProtocolScope, declared: (p) => p.ipProtocolScope },
+  { field: 'ipsecFilter', live: (a) => a.ipsecFilter, declared: (p) => p.ipsecFilter },
+  { field: 'loggingEnabled', live: (a) => a.loggingEnabled, declared: (p) => p.loggingEnabled },
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'schedule', live: (a) => a.schedule, declared: (p) => p.schedule },
+  { field: 'source', live: (a) => a.source, declared: (p) => p.source },
+]);
+
+export const matches = (
+  attributes: FirewallPolicyAttributes,
+  props: FirewallPolicyProps,
+): 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: firewall.FirewallPolicy, props: FirewallPolicyProps) =>
+  fieldDrift(attributesOf(live, props), props);

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

@@ -0,0 +1,143 @@
+/**
+ * I1 (red team, 2026-09-26, PR 309 LAND): every fixture in `firewall-policy.test.ts` and
+ * `firewall-policy-drift.test.ts` uses filter-LESS `source`/`destination`/`ipProtocolScope`
+ * (`{zoneId}`/`{ipVersion}` only). A mutant that made `attributesOf`/`declareFirewallPolicy` write
+ * only those two keys -- silently dropping every `trafficFilter`/`protocolFilter`/`schedule` --
+ * passed all of `firewall-policy.test.ts` AND `discriminated-filter-decode.test.ts` (17/17). The
+ * latter proves the SDK's OWN decode keeps every key; it never reads them back through THIS
+ * resource's `attributesOf`/`declareFirewallPolicy`, which is the actual path a Lane C import walks.
+ *
+ * This file is that missing link: a filter-bearing wire body, read through `spec.fetchLive`, then
+ * `declareFirewallPolicy` -- proving the filters (plus a key this pinned spec has never declared)
+ * survive THIS round trip, not just the SDK's own decode.
+ *
+ * Split from `firewall-policy-drift.test.ts` to keep that file under the house 250-line cap.
+ */
+import { describe, expect, test } from 'bun:test';
+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';
+
+const FILTER_POLICY_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/fp-2';
+
+// Fabricated fixture (RFC 5737/2606-safe) -- kit is PUBLIC. Every compound field here actually
+// carries a filter, plus one key ("futureVendorField") this pinned spec doesn't declare.
+const filterBearingWireBody = () => ({
+  id: 'fp-2',
+  name: 'Allow specific IPs to the internet',
+  enabled: true,
+  index: 5,
+  action: { type: 'ALLOW' },
+  connectionStateFilter: null,
+  description: null,
+  ipsecFilter: null,
+  loggingEnabled: false,
+  metadata: { origin: 'USER' },
+  source: {
+    zoneId: 'zone-src',
+    trafficFilter: {
+      type: 'NETWORK',
+      networkFilter: { matchOpposite: false, networkIds: ['net-1', 'net-2'] },
+      portFilter: {
+        matchOpposite: false,
+        type: 'PORT',
+        items: [{ type: 'PORT_SINGLE', value: 443 }],
+      },
+    },
+  },
+  destination: {
+    zoneId: 'zone-dst',
+    trafficFilter: {
+      type: 'IP_ADDRESS',
+      ipAddressFilter: {
+        matchOpposite: false,
+        type: 'IP_ADDRESS',
+        items: [{ type: 'IP_SINGLE_ADDRESS', value: '203.0.113.5' }],
+      },
+    },
+  },
+  ipProtocolScope: {
+    ipVersion: 'IPV4_AND_IPV6',
+    protocolFilter: {
+      type: 'PRESET',
+      preset: 'ALL',
+      matchOpposite: false,
+      futureVendorField: 'unmodeled-by-this-spec-version',
+    },
+  },
+  schedule: {
+    mode: 'EVERY_WEEK',
+    repeatOnDays: ['MONDAY', 'FRIDAY'],
+    timeFilter: { startTime: '08:00', stopTime: '18:00' },
+  },
+});
+
+const BASE_PROPS: FirewallPolicyProps = {
+  siteId: 'site-1',
+  firewallPolicyId: 'fp-2',
+  action: { type: 'ALLOW' },
+  destination: { zoneId: 'zone-dst' },
+  enabled: true,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: false,
+  name: 'placeholder',
+  source: { zoneId: 'zone-src' },
+};
+
+describe('I1 -- a filter-bearing policy round-trips through declareFirewallPolicy', () => {
+  test('source.trafficFilter, destination.trafficFilter, ipProtocolScope.protocolFilter and schedule survive, unknown key included', async () => {
+    const wire = filterBearingWireBody();
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === FILTER_POLICY_PATH
+        ? Response.json(wire)
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(BASE_PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    if (live == null) throw new Error('expected a live FirewallPolicy');
+    const declared = declareFirewallPolicy(live, 'site-1');
+
+    // Cast both sides to `Record<string, unknown>` -- the declared side's real type is a narrow
+    // per-discriminator union (A3), and `wire`'s own object-literal type widens each string
+    // property; comparing them as unions vs literals is not the point of this assertion, VALUE
+    // equality (including the unmodeled key below) is.
+    const asRecord = (value: unknown) => value as Record<string, unknown>;
+    expect(asRecord(declared.source.trafficFilter)).toEqual(asRecord(wire.source.trafficFilter));
+    expect(asRecord(declared.destination.trafficFilter)).toEqual(
+      asRecord(wire.destination.trafficFilter),
+    );
+    expect(asRecord(declared.ipProtocolScope.protocolFilter)).toEqual(
+      asRecord(wire.ipProtocolScope.protocolFilter),
+    );
+    expect(asRecord(declared.schedule)).toEqual(asRecord(wire.schedule));
+    // The key this pinned spec has never declared -- proves the mutant this test targets (silently
+    // narrowing to `{zoneId}`/`{ipVersion}`) can't hide behind a fixture with nothing to drop.
+    expect(asRecord(declared.ipProtocolScope.protocolFilter).futureVendorField).toBe(
+      'unmodeled-by-this-spec-version',
+    );
+
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+
+    // A nested change inside ONE compound field reports that field, and only that field.
+    const changedDestination: FirewallPolicyProps = {
+      ...declared,
+      destination: {
+        zoneId: 'zone-dst',
+        trafficFilter: {
+          type: 'IP_ADDRESS',
+          ipAddressFilter: {
+            matchOpposite: false,
+            type: 'IP_ADDRESS',
+            items: [{ type: 'IP_SINGLE_ADDRESS', value: '203.0.113.99' }],
+          },
+        },
+      },
+    };
+    expect(driftOf(live, changedDestination).map((d) => d.field)).toEqual(['destination']);
+  });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * `Unifi.FirewallPolicy`'s wire shape — the declarable subset of `FirewallPolicy` (`getFirewallPolicy`'s
+ * own decode target), and how a live read becomes both plan attributes and a rendered declaration.
+ * Rule ORDER is a separate resource (`firewall-policy-ordering.ts`, T5) — this file is one policy's
+ * own fields only.
+ *
+ * ★ `source`/`destination`/`ipProtocolScope`/`action`/`schedule` STAY COMPOUND, COMPARED WHOLESALE —
+ *   post-A3 (`8ee11f1`, "type FirewallPolicy/ACL/TrafficMatchingList filters per discriminator"),
+ *   these decode as real per-discriminator TS unions instead of `unknown`
+ *   (`discriminated-filter-decode.test.ts` proves the wire path keeps every key, including one this
+ *   pinned spec doesn't yet declare), so this file is honest about their real shape rather than
+ *   casting to `unknown` the way `acl-rule-form.ts` still does for its own opaque filters. It does
+ *   NOT follow that up with a leaf-by-leaf declarable schema for all 12 filter variants, though:
+ *   that is new modelling work this PR does not attempt, so each field is compared with plain
+ *   `deepEqual` (`stripNullish`) as ONE value, same proportion `acl-rule-form.ts`'s
+ *   `enforcingDeviceFilter` gets (one level of structure, not exploded into scalars).
+ *
+ * ⚠️ KNOWN GAP (T15, same shape as `acl-rule-form.ts`'s own — accepted, not fixed, here either):
+ *   several of the vendor's filter variants nested inside `source`/`destination`/`ipProtocolScope`
+ *   are themselves SET-LIKE arrays with no documented order —
+ *   `FirewallPolicyMACAddressFilter.macAddresses`, `FirewallPolicyNetworkFilter.networkIds`,
+ *   `FirewallPolicyApplicationFilter.applicationIds`, `FirewallPolicyIPAddressFilter.items`,
+ *   `FirewallPolicyRegionFilter.regions`, `FirewallPolicyVPNServerFilter.vpnServerIds`,
+ *   `FirewallSchedule.repeatOnDays` — `deepEqual` compares every one of them order-sensitively, so a
+ *   console-side reorder with no membership change would report a spurious drift this read-only
+ *   family's `reconcile` then refuses forever. Not fixed here for the same reason ACL's own gap
+ *   isn't: normalizing 12 filter variants' own nested arrays is a bigger, separate change, not a
+ *   proportional extension of typing per-discriminator (A3) into set-aware comparison too.
+ *
+ * ⛔ `connectionStateFilter` IS THE ONE TOP-LEVEL PROPS ARRAY, AND IS A SET — "Match on firewall
+ *   connection state. If null, matches all connection states" describes membership, not a sequence
+ *   (unlike `firewall-policy-ordering-form.ts`'s own `beforeSystemDefined`/`afterSystemDefined`,
+ *   where position IS the value). Normalized with the same `sortedSet` every other family in this
+ *   directory uses for a set-shaped array (`firewall-zone-form.ts`'s `networkIds`,
+ *   `acl-rule-form.ts`'s `protocolFilter`).
+ *
+ * ⛔ `index` IS ATTRIBUTES-ONLY, NEVER DECLARED. `CreateFirewallPolicyRequest` has no `index`
+ *   field at all — the live object's current position among ALL policies on the site is reported,
+ *   but a policy's PRIORITY relative to its own zone pair is `firewall-policy-ordering.ts`'s concern
+ *   (`OrderedFirewallPolicyIDs`), same split `acl-rule-form.ts`'s own `index` documents.
+ *
+ * ⛔ `metadata.origin` IS ATTRIBUTES-ONLY, same split every other family here uses
+ *   (`firewall-zone-form.ts`'s `metadataOrigin`) — `UserOrSystemDefinedOrDerivedEntityMetadata` is
+ *   server-derived, no writable field accepts it.
+ */
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+/** ★ EXPORTED so `firewall-policy-drift.ts` normalizes both live and declared sides identically —
+ *  see `acl-rule-form.ts`'s own header for why a normalizer applied to only one side is a bug
+ *  class (MEDIUM-4). */
+export const normalizeConnectionStateFilter = (
+  value: readonly string[] | undefined,
+): string[] | undefined => (value == null ? undefined : sortedSet(value));
+
+/** ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` — `exactOptionalPropertyTypes`; see
+ *  `network-form.ts`'s own header. */
+export interface FirewallPolicyProps {
+  siteId: string;
+  firewallPolicyId: string;
+  action: firewall.FirewallPolicyAction;
+  /** Connection states this policy matches — compared as a SET, see the header. */
+  connectionStateFilter?: string[] | undefined;
+  description?: string | undefined;
+  /** Traffic destination — compound, compared wholesale; see the header's known gap. */
+  destination: firewall.FirewallPolicyDestination;
+  enabled: boolean;
+  /** IP version + protocol scope — compound, compared wholesale; see the header's known gap. */
+  ipProtocolScope: firewall.FirewallPolicyIPProtocolScope;
+  ipsecFilter?: string | undefined;
+  loggingEnabled: boolean;
+  name: string;
+  /** Schedule this policy is active on — compound, compared wholesale; see the header's known gap. */
+  schedule?: firewall.FirewallSchedule | undefined;
+  /** Traffic source — compound, compared wholesale; see the header's known gap. */
+  source: firewall.FirewallPolicySource;
+}
+
+export interface FirewallPolicyAttributes {
+  siteId: string;
+  firewallPolicyId: string;
+  action: firewall.FirewallPolicyAction;
+  connectionStateFilter: string[] | undefined;
+  description: string | undefined;
+  destination: firewall.FirewallPolicyDestination;
+  enabled: boolean;
+  /** Current position among ALL policies on the site — server-derived, never declared; see header. */
+  index: number;
+  ipProtocolScope: firewall.FirewallPolicyIPProtocolScope;
+  ipsecFilter: string | undefined;
+  loggingEnabled: boolean;
+  name: string;
+  schedule: firewall.FirewallSchedule | undefined;
+  source: firewall.FirewallPolicySource;
+  /** `metadata.origin` — server-derived, never declared; see `firewall-zone-form.ts`'s own. */
+  metadataOrigin: string;
+}
+
+export const attributesOf = (
+  live: firewall.FirewallPolicy,
+  props: FirewallPolicyProps,
+): FirewallPolicyAttributes => ({
+  siteId: props.siteId,
+  firewallPolicyId: live.id,
+  action: live.action,
+  connectionStateFilter: normalizeConnectionStateFilter(live.connectionStateFilter),
+  description: live.description,
+  destination: live.destination,
+  enabled: live.enabled,
+  index: live.index,
+  ipProtocolScope: live.ipProtocolScope,
+  ipsecFilter: live.ipsecFilter,
+  loggingEnabled: live.loggingEnabled,
+  name: live.name,
+  schedule: live.schedule,
+  source: live.source,
+  metadataOrigin: live.metadata.origin,
+});
+
+/**
+ * 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 `getFirewallPolicy`'s own response
+ * straight in and writes the result as `firewallPolicy('<id>', declareFirewallPolicy(live, siteId))`
+ * — no field is invented or defaulted beyond what `attributesOf` already reports, so
+ * `matches(attributesOf(live, props), declareFirewallPolicy(live, siteId))` is `true` by
+ * construction (`firewall-policy.test.ts` proves it).
+ */
+export const declareFirewallPolicy = (
+  live: firewall.FirewallPolicy,
+  siteId: string,
+): FirewallPolicyProps => ({
+  siteId,
+  firewallPolicyId: live.id,
+  action: live.action,
+  connectionStateFilter: normalizeConnectionStateFilter(live.connectionStateFilter),
+  description: live.description,
+  destination: live.destination,
+  enabled: live.enabled,
+  ipProtocolScope: live.ipProtocolScope,
+  ipsecFilter: live.ipsecFilter,
+  loggingEnabled: live.loggingEnabled,
+  name: live.name,
+  schedule: live.schedule,
+  source: live.source,
+});

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

@@ -0,0 +1,111 @@
+/**
+ * `Unifi.FirewallPolicyOrdering`'s wire shape — ONE resource per `(sourceFirewallZoneId,
+ * destinationFirewallZoneId)` ZONE PAIR (`getFirewallPolicyOrdering`'s own scope, `GET
+ * /v1/sites/{siteId}/firewall/policies/ordering?sourceFirewallZoneId=…&destinationFirewallZoneId=…`),
+ * not per policy and not site-wide. Compare with `acl-rule-ordering-form.ts`'s own header: ACL rule
+ * order is ONE list for the whole site because ACL rules have no zone concept; firewall policies are
+ * scoped to a zone pair (`firewall-zone.ts`'s own `Unifi.FirewallZone`), so the vendor keys ordering
+ * the same way — a console can have as many `Unifi.FirewallPolicyOrdering` resources as it has
+ * zone pairs with at least one user-defined policy between them.
+ *
+ * ⛔ T5 — `beforeSystemDefined`/`afterSystemDefined` ARE EACH A SEQUENCE, NEVER RUN THROUGH
+ *   `sortedSet`. `OrderedFirewallPolicyIDs`' own shape splits a zone pair's user-defined policies
+ *   into the ones ordered BEFORE the system-defined policies and the ones ordered AFTER them —
+ *   within each half, position is priority, the same "lower index/earlier position wins" reasoning
+ *   `acl-rule-ordering-form.ts` gives for `orderedAclRuleIds`. `drift.ts`'s `defaultEqual`
+ *   (`deepEqual`) already compares arrays element-by-element without sorting them, so leaving both
+ *   fields un-normalized is what makes the comparison order-sensitive, not an oversight.
+ *
+ * ★ TWO SEQUENCES, NOT ONE — the one real difference from `acl-rule-ordering-form.ts`'s single
+ *   `orderedAclRuleIds`. A policy ordered "before system-defined" and one ordered "after" can never
+ *   swap sides through this endpoint (there is no single combined list position that would let one
+ *   policy move from one half to the other) — `matches`/`driftOf` below compare each half
+ *   independently, so a policy moving from `beforeSystemDefined` to `afterSystemDefined` reports as
+ *   drift on BOTH fields, not a single reordering of one array.
+ *
+ * ★ `makeDriftOf`, NO CUSTOM `equal` — same framework every other family's `matches`/`driftOf`
+ *   share (MEDIUM-4). Its default `deepEqual` is already order-sensitive for arrays, so the absence
+ *   of a custom `equal` here is itself the "never sortedSet" rule in force, exactly as
+ *   `acl-rule-ordering-form.ts`'s own header explains for its one field.
+ */
+import type * as firewall from '@distilled.cloud/unifi-network/firewall';
+import { makeDriftOf } from './drift.ts';
+
+export interface FirewallPolicyOrderingProps {
+  siteId: string;
+  sourceFirewallZoneId: string;
+  destinationFirewallZoneId: string;
+  /** Policy IDs ordered before the zone pair's system-defined policies, highest priority first —
+   *  never compared as a set (see header). */
+  beforeSystemDefined: string[];
+  /** Policy IDs ordered after the zone pair's system-defined policies, highest priority first —
+   *  never compared as a set (see header). */
+  afterSystemDefined: string[];
+}
+
+export interface FirewallPolicyOrderingAttributes {
+  siteId: string;
+  sourceFirewallZoneId: string;
+  destinationFirewallZoneId: string;
+  beforeSystemDefined: string[];
+  afterSystemDefined: string[];
+}
+
+export const attributesOf = (
+  live: firewall.IntegrationFirewallPolicyOrderingDto,
+  props: FirewallPolicyOrderingProps,
+): FirewallPolicyOrderingAttributes => ({
+  siteId: props.siteId,
+  sourceFirewallZoneId: props.sourceFirewallZoneId,
+  destinationFirewallZoneId: props.destinationFirewallZoneId,
+  beforeSystemDefined: live.orderedFirewallPolicyIds.beforeSystemDefined,
+  afterSystemDefined: live.orderedFirewallPolicyIds.afterSystemDefined,
+});
+
+/**
+ * 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 `getFirewallPolicyOrdering`'s own
+ * response straight in and writes the result as `firewallPolicyOrdering('<id>',
+ * declareFirewallPolicyOrdering(live, siteId, sourceZoneId, destZoneId))` —
+ * `matches(attributesOf(live, props), declareFirewallPolicyOrdering(live, …))` is `true` by
+ * construction (`firewall-policy-ordering.test.ts` proves it).
+ */
+export const declareFirewallPolicyOrdering = (
+  live: firewall.IntegrationFirewallPolicyOrderingDto,
+  siteId: string,
+  sourceFirewallZoneId: string,
+  destinationFirewallZoneId: string,
+): FirewallPolicyOrderingProps => ({
+  siteId,
+  sourceFirewallZoneId,
+  destinationFirewallZoneId,
+  beforeSystemDefined: live.orderedFirewallPolicyIds.beforeSystemDefined,
+  afterSystemDefined: live.orderedFirewallPolicyIds.afterSystemDefined,
+});
+
+const fieldDrift = makeDriftOf<FirewallPolicyOrderingAttributes, FirewallPolicyOrderingProps>([
+  {
+    field: 'beforeSystemDefined',
+    live: (a) => a.beforeSystemDefined,
+    declared: (p) => p.beforeSystemDefined,
+  },
+  {
+    field: 'afterSystemDefined',
+    live: (a) => a.afterSystemDefined,
+    declared: (p) => p.afterSystemDefined,
+  },
+]);
+
+export const matches = (
+  attributes: FirewallPolicyOrderingAttributes,
+  props: FirewallPolicyOrderingProps,
+): 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)`).
+ */
+export const driftOf = (
+  live: firewall.IntegrationFirewallPolicyOrderingDto,
+  props: FirewallPolicyOrderingProps,
+) => fieldDrift(attributesOf(live, props), props);