@homeflare/alchemy 0.38.0 → 0.40.0

package/src/unifi/acl-rule-ordering.test.ts

@@ -0,0 +1,141 @@
+/**
+ * `Unifi.AclRuleOrdering`'s `spec` against a fake UniFi Network API — mirrors `acl-rule.test.ts`.
+ * The one thing this file exists to prove that no other family test does: T5's "order IS the
+ * value, never `sortedSet`" rule actually holds for `orderedAclRuleIds`.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+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 './acl-rule-ordering-form.ts';
+import { type AclRuleOrderingProps, declareAclRuleOrdering, spec } from './acl-rule-ordering.ts';
+import { unifiOperations } from './resource.ts';
+
+const ORDERING_PATH = '/proxy/network/integration/v1/sites/site-1/acl-rules/ordering';
+
+const liveOrdering = (
+  overrides: Partial<aclRules.ACLRuleOrdering> = {},
+): aclRules.ACLRuleOrdering => ({
+  orderedAclRuleIds: ['rule-1', 'rule-2', 'rule-3'],
+  ...overrides,
+});
+
+const PROPS: AclRuleOrderingProps = {
+  siteId: 'site-1',
+  orderedAclRuleIds: ['rule-1', 'rule-2', 'rule-3'],
+};
+
+describe('Unifi.AclRuleOrdering spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', 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?.orderedAclRuleIds).toEqual(['rule-1', 'rule-2', 'rule-3']);
+    expect(fake.seen).toEqual([{ method: 'GET', path: ORDERING_PATH }]);
+  });
+
+  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 () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 indefinitely with backoff -- this test
+    //   asserts the FAILURE, not the retry schedule. Regression for red-team Important finding 2:
+    //   a blanket `Effect.orElseSucceed(() => undefined)` fold would pass every test above too.
+    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('declareAclRuleOrdering -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveOrdering({ orderedAclRuleIds: ['rule-9', 'rule-2'] });
+    const declared = declareAclRuleOrdering(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('T5 -- order IS the value, never sortedSet', () => {
+  test('an identical list is a noop', () => {
+    expect(driftOf(liveOrdering(), PROPS)).toEqual([]);
+    expect(matches(attributesOf(liveOrdering(), PROPS), PROPS)).toBe(true);
+  });
+
+  test('the SAME rule ids in a DIFFERENT order is real drift, not a noop', () => {
+    // The one behavior `firewall-zone-form.ts`'s `networkIds` and this file must NOT share:
+    // there, a reorder is a noop (a set); here, it is the whole point of the resource.
+    const live = liveOrdering({ orderedAclRuleIds: ['rule-2', 'rule-1', 'rule-3'] });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+    expect(driftOf(live, PROPS)).toEqual([
+      {
+        field: 'orderedAclRuleIds',
+        live: ['rule-2', 'rule-1', 'rule-3'],
+        declared: ['rule-1', 'rule-2', 'rule-3'],
+      },
+    ]);
+  });
+
+  test('a genuinely different rule set (not just reordered) is also drift', () => {
+    const live = liveOrdering({ orderedAclRuleIds: ['rule-1', 'rule-4'] });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(false);
+  });
+});
+
+describe('Unifi.AclRuleOrdering 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 list', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ORDERING_PATH
+        ? Response.json(liveOrdering({ orderedAclRuleIds: ['rule-3', 'rule-2', 'rule-1'] }))
+        : 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/acl-rule-ordering.ts

@@ -0,0 +1,70 @@
+/**
+ * `Unifi.AclRuleOrdering` — the ONE ordered list of user-defined ACL rule IDs for a site
+ * (`getAclRuleOrdering`/`updateAclRuleOrdering`, `GET`/`PUT /v1/sites/{siteId}/acl-rules/ordering`),
+ * READ-ONLY (`policy.ts`). T5's per-family variant of the ordering trap `docs/unifi-api-notes.md`
+ * warns about for `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`, keyed per zone
+ * pair rather than site-wide — see its own header for why): the endpoint replaces the WHOLE list
+ * on a write, so a partial or resorted body would drop or reorder every OTHER rule too.
+ * This family never writes at all, but its `matches`/`driftOf` (`acl-rule-ordering-form.ts`) are
+ * still order-preserving, never `sortedSet`, so a future write path inherits a correct comparison
+ * rather than one that has to be fixed alongside the first `update`.
+ *
+ * ★ ONE OBJECT PER SITE, NOT PER RULE — unlike `acl-rule.ts`, there is no per-object id in the
+ *   wire response at all (`ACLRuleOrdering` is just `{ orderedAclRuleIds }`); the resource's own
+ *   `id` (the stack-chosen string passed to `aclRuleOrdering(id, props)`) is a label the DECLARER
+ *   picks, same as `firewallZone`/`network`, not something read back from the vendor.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import * as Effect from 'effect/Effect';
+import {
+  type AclRuleOrderingAttributes,
+  type AclRuleOrderingProps,
+  attributesOf,
+  matches,
+} from './acl-rule-ordering-form.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { AclRuleOrderingAttributes, AclRuleOrderingProps } from './acl-rule-ordering-form.ts';
+export { declareAclRuleOrdering, driftOf } from './acl-rule-ordering-form.ts';
+
+export interface UnifiAclRuleOrdering extends Resource<
+  'Unifi.AclRuleOrdering',
+  AclRuleOrderingProps,
+  AclRuleOrderingAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiAclRuleOrdering = Resource<UnifiAclRuleOrdering>('Unifi.AclRuleOrdering', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `aclRuleOrdering('site-1', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export const aclRuleOrdering = (id: string, props: AclRuleOrderingProps) =>
+  UnifiAclRuleOrdering(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  AclRuleOrderingProps,
+  aclRules.ACLRuleOrdering,
+  AclRuleOrderingAttributes,
+  aclRules.GetAclRuleOrderingError
+> = {
+  type: 'Unifi.AclRuleOrdering',
+  describe: (props) => `sites/${props.siteId}/acl-rules/ordering`,
+  fetchLive: (props) =>
+    aclRules
+      .getAclRuleOrdering({ siteId: props.siteId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiAclRuleOrderingProvider = () =>
+  Provider.effect(UnifiAclRuleOrdering, Effect.succeed(UnifiAclRuleOrdering.Provider.of(handlers)));

package/src/unifi/acl-rule.test.ts

@@ -0,0 +1,183 @@
+/**
+ * `Unifi.AclRule`'s `spec` against a fake UniFi Network API — mirrors `network.test.ts`/
+ * `firewall-zone.test.ts`. `driftOf`/`matches` coverage lives here too, same as
+ * `dns-policy.test.ts`, not split into its own file (see that file's own header).
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+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 './acl-rule-form.ts';
+import { driftOf, matches } from './acl-rule-drift.ts';
+import { type AclRuleProps, declareAclRule, spec } from './acl-rule.ts';
+import { unifiOperations } from './resource.ts';
+
+const RULE_PATH = '/proxy/network/integration/v1/sites/site-1/acl-rules/rule-1';
+
+const liveAclRule = (overrides: Partial<aclRules.ACLRule> = {}): aclRules.ACLRule => ({
+  action: 'BLOCK',
+  enabled: true,
+  id: 'rule-1',
+  index: 3,
+  metadata: { origin: 'USER' },
+  name: 'Block IoT to WAN',
+  // ★ `IPV4` is the real `ACL rule` discriminator value (`type`: `IPV4`|`MAC`, `docs/unifi-acl-
+  //   rule.md`) -- a prior fixture used the invented `NETWORK_TO_INTERNET`, corrected 2026-09-26.
+  type: 'IPV4',
+  protocolFilter: ['TCP', 'UDP'],
+  // ★ `DEVICES` is the real `ACL rule device filter` discriminator value; the vendor has no
+  //   "ALL_SWITCHES" variant -- omitting the field entirely means "all switches" per its own
+  //   description ("When null, the rule will be provisioned to all switches on the site").
+  enforcingDeviceFilter: { type: 'DEVICES', deviceIds: ['sw-1'] },
+  ...overrides,
+});
+
+const PROPS: AclRuleProps = {
+  siteId: 'site-1',
+  aclRuleId: 'rule-1',
+  action: 'BLOCK',
+  enabled: true,
+  name: 'Block IoT to WAN',
+  type: 'IPV4',
+  protocolFilter: ['TCP', 'UDP'],
+  enforcingDeviceFilter: { type: 'DEVICES', deviceIds: ['sw-1'] },
+};
+
+describe('Unifi.AclRule spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === RULE_PATH
+        ? Response.json(liveAclRule())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('rule-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: RULE_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. Regression for red-team Important finding 2:
+    //   a blanket `Effect.orElseSucceed(() => undefined)` fold would pass every test above too.
+    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('declareAclRule -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveAclRule({ protocolFilter: ['UDP', 'TCP'], index: 9 });
+    const declared = declareAclRule(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+  });
+});
+
+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 = liveAclRule({ name: 'Block cameras from WAN' });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'name', live: 'Block cameras from WAN', declared: 'Block IoT to WAN' },
+    ]);
+  });
+
+  test('protocolFilter in a different order is a noop -- it is a SET, not a sequence', () => {
+    const live = liveAclRule({ protocolFilter: ['UDP', 'TCP'] });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(true);
+    expect(driftOf(live, PROPS)).toEqual([]);
+  });
+
+  test('the DECLARED side of protocolFilter is also normalized, not just live (MEDIUM-4 mutant)', () => {
+    const live = liveAclRule({ protocolFilter: ['TCP', 'UDP'] });
+    const props: AclRuleProps = { ...PROPS, protocolFilter: ['UDP', 'TCP'] };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('a genuine protocolFilter difference is caught', () => {
+    const live = liveAclRule({ protocolFilter: ['TCP'] });
+    expect(driftOf(live, PROPS)).toEqual([
+      { field: 'protocolFilter', live: ['TCP'], declared: ['TCP', 'UDP'] },
+    ]);
+  });
+
+  test('enforcingDeviceFilter.deviceIds in a different order is a noop -- also a SET', () => {
+    const live = liveAclRule({
+      enforcingDeviceFilter: { type: 'DEVICES', deviceIds: ['sw-2', 'sw-1'] },
+    });
+    const props: AclRuleProps = {
+      ...PROPS,
+      enforcingDeviceFilter: { type: 'DEVICES', deviceIds: ['sw-1', 'sw-2'] },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+    expect(driftOf(live, props)).toEqual([]);
+  });
+
+  test('index is never compared -- it is attributes-only (deprecated for writes, owned by ordering)', () => {
+    const live = liveAclRule({ index: 41 });
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(true);
+    expect(attributesOf(live, PROPS).index).toBe(41);
+  });
+
+  test('sourceFilter/destinationFilter stay opaque -- a real difference is still caught', () => {
+    // `NETWORKS` + `networkIds` (plural, an array) is the real `IntegrationIpAclRuleNetworkEndpoint
+    // FilterDto` shape -- a prior fixture used the invented singular `NETWORK`/`networkId`,
+    // corrected 2026-09-26. `sourceFilter` is `unknown` either way, so this is a fixture-realism fix
+    // only, not a behavior change.
+    const live = liveAclRule({ sourceFilter: { type: 'NETWORKS', networkIds: ['net-1'] } });
+    expect(driftOf(live, PROPS)).toEqual([
+      {
+        field: 'sourceFilter',
+        live: { type: 'NETWORKS', networkIds: ['net-1'] },
+        declared: undefined,
+      },
+    ]);
+  });
+});
+
+describe('Unifi.AclRule 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 === RULE_PATH
+        ? Response.json(liveAclRule())
+        : 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('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === RULE_PATH
+        ? Response.json(liveAclRule())
+        : 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/acl-rule.ts

@@ -0,0 +1,61 @@
+/**
+ * `Unifi.AclRule` — one user-defined ACL rule on a UniFi Network site, READ-ONLY (`policy.ts`).
+ * `Unifi.AclRuleOrdering` (`acl-rule-ordering.ts`) is the sibling resource for rule ORDER (T5) —
+ * one per site, never this file's concern.
+ *
+ * ★ T11 GATE — see `dns-policy.ts`'s own header for the full closure-diff record: `Access Control
+ *   (ACL Rules)` (7 ops, including `getAclRuleOrdering`/`updateAclRuleOrdering`) is
+ *   byte-identical between 10.4.57 and 10.6.97, and unreachable from any of the 14 schemas that DID
+ *   change. Full breakdown: `docs/unifi-acl-rule.md`.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import * as Effect from 'effect/Effect';
+import { type AclRuleAttributes, type AclRuleProps, attributesOf } from './acl-rule-form.ts';
+import { matches } from './acl-rule-drift.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { AclRuleAttributes, AclRuleProps } from './acl-rule-form.ts';
+export { declareAclRule } from './acl-rule-form.ts';
+export { driftOf } from './acl-rule-drift.ts';
+
+export interface UnifiAclRule extends Resource<
+  'Unifi.AclRule',
+  AclRuleProps,
+  AclRuleAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiAclRule = Resource<UnifiAclRule>('Unifi.AclRule', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `aclRule('block-iot-wan', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export const aclRule = (id: string, props: AclRuleProps) =>
+  UnifiAclRule(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  AclRuleProps,
+  aclRules.ACLRule,
+  AclRuleAttributes,
+  aclRules.GetAclRuleError
+> = {
+  type: 'Unifi.AclRule',
+  describe: (props) => `sites/${props.siteId}/acl-rules/${props.aclRuleId}`,
+  fetchLive: (props) =>
+    aclRules
+      .getAclRule({ siteId: props.siteId, aclRuleId: props.aclRuleId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiAclRuleProvider = () =>
+  Provider.effect(UnifiAclRule, Effect.succeed(UnifiAclRule.Provider.of(handlers)));

package/src/unifi/discriminated-filter-decode.test.ts

@@ -0,0 +1,134 @@
+/**
+ * A3/T26 regression: the SDK's per-discriminator-typed filters (FirewallPolicy's
+ * `protocolFilter`/`macAddressFilter`, an ACL rule's `sourceFilter`/`destinationFilter`) must
+ * decode a wire value UNCHANGED — including a key this pinned spec doesn't yet declare.
+ *
+ * ⛔ WITHOUT THIS TEST, A REGEN THAT SWITCHES `scripts/generate.ts` BACK TO
+ *   `unionStyle: "opaque-cases"` STAYS GREEN. That style emits `S.Unknown.pipe(T.UnionCases(...))`,
+ *   whose decode (`@distilled.cloud/core` `protocol-http.ts`'s `mapKeys`) picks the best-matching
+ *   case by key set and keeps ONLY that case's keys — silently dropping a future vendor field, and
+ *   in a same-key-set tie (an all-null MAC endpoint vs. the IP endpoint below) picking the WRONG
+ *   case's keys outright. `scripts/generate.ts` now uses Argo CD's `union:` callback instead — a
+ *   bare `S.Unknown` with no case annotation — which this repo's own `fake-unifi.ts` proves against
+ *   the real wire path (path assembly + JSON decode), the same way `errors-and-secrets.test.ts`
+ *   proves A1/A2. This family has no `Unifi.FirewallPolicy`/`Unifi.AclRule` provider yet (Lane B),
+ *   so the SDK's own `getAclRule`/`getFirewallPolicy` operations are called directly.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import { fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+
+const ACL_PATH = '/proxy/network/integration/v1/sites/site-1/acl-rules/acl-1';
+const FW_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies/fp-1';
+
+// Fabricated fixture (RFC 5737 address block, RFC 2606-safe ids) — kit is PUBLIC (fake-unifi.ts).
+const aclBody = () => ({
+  type: 'IPV4',
+  id: 'acl-1',
+  name: 'example-rule',
+  enabled: true,
+  action: 'BLOCK',
+  index: 0,
+  metadata: { origin: 'USER' },
+  // A future console version's field this pinned spec has never declared.
+  sourceFilter: {
+    type: 'IP_ADDRESSES_OR_SUBNETS',
+    ipAddressesOrSubnets: ['192.0.2.0/24'],
+    futureVendorField: 'unmodeled-by-this-spec-version',
+  },
+  // Every member null (a same-key-set tie with the IP case under key-set matching).
+  destinationFilter: { type: 'MAC_ADDRESSES', macAddresses: null, prefixLength: null },
+});
+
+describe('A3/T26 — ACL rule filters decode unchanged, including an unmodeled field', () => {
+  test('sourceFilter keeps a key this spec version does not declare', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === ACL_PATH
+        ? Response.json(aclBody())
+        : new Response('unexpected request', { status: 400 }),
+    );
+    const live = await Effect.runPromise(
+      aclRules
+        .getAclRule({ siteId: 'site-1', aclRuleId: 'acl-1' })
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    const source = live.sourceFilter as unknown as Record<string, unknown>;
+    expect(source.futureVendorField).toBe('unmodeled-by-this-spec-version');
+    expect(source.ipAddressesOrSubnets).toEqual(['192.0.2.0/24']);
+  });
+
+  test('destinationFilter is not silently reassigned to the tied IP case', async () => {
+    const fake = fakeUnifi(() => Response.json(aclBody()));
+    const live = await Effect.runPromise(
+      aclRules
+        .getAclRule({ siteId: 'site-1', aclRuleId: 'acl-1' })
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    const dest = live.destinationFilter as unknown as Record<string, unknown>;
+    expect(dest.type).toBe('MAC_ADDRESSES');
+    expect('macAddresses' in dest).toBe(true);
+    // The IP case's own keys (`ipAddressesOrSubnets`, `portFilter`, `networkIds`) never appear —
+    // the case-narrowing mapKeys path this SDK no longer uses would rewrite them in on a key-set tie.
+    expect('ipAddressesOrSubnets' in dest).toBe(false);
+  });
+});
+
+const fwBody = () => ({
+  id: 'fp-1',
+  name: 'example-policy',
+  enabled: true,
+  index: 1,
+  action: { type: 'ALLOW' },
+  source: {
+    zoneId: 'zone-src',
+    trafficFilter: {
+      type: 'MAC_ADDRESS',
+      macAddressFilter: {
+        macAddresses: ['02:00:00:00:00:01'],
+        futureVendorField: 'unmodeled-by-this-spec-version',
+      },
+    },
+  },
+  destination: { zoneId: 'zone-dst' },
+  ipProtocolScope: {
+    ipVersion: 'IPV6',
+    protocolFilter: {
+      type: 'NAMED_PROTOCOL',
+      protocol: { name: 'icmpv6', typenameFilter: 'ECHO_REQUEST' },
+      matchOpposite: false,
+      futureVendorField: 'unmodeled-by-this-spec-version',
+    },
+  },
+  metadata: { origin: 'USER' },
+  loggingEnabled: false,
+});
+
+describe('A3/T26 — FirewallPolicy filters decode unchanged, including an unmodeled field', () => {
+  test('macAddressFilter and protocolFilter both keep a key this spec version does not declare', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === FW_PATH
+        ? Response.json(fwBody())
+        : new Response('unexpected request', { status: 400 }),
+    );
+    const live = await Effect.runPromise(
+      firewall
+        .getFirewallPolicy({ siteId: 'site-1', firewallPolicyId: 'fp-1' })
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    const macFilter = live.source.trafficFilter?.macAddressFilter as unknown as Record<
+      string,
+      unknown
+    >;
+    expect(macFilter.futureVendorField).toBe('unmodeled-by-this-spec-version');
+    expect(macFilter.macAddresses).toEqual(['02:00:00:00:00:01']);
+
+    const protocolFilter = live.ipProtocolScope.protocolFilter as unknown as Record<
+      string,
+      unknown
+    >;
+    expect(protocolFilter.futureVendorField).toBe('unmodeled-by-this-spec-version');
+    expect((protocolFilter.protocol as Record<string, unknown>).name).toBe('icmpv6');
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * `Unifi.DnsPolicy`'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 own 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.
+ *
+ * ★ NO CUSTOM `equal` ANYWHERE. Every field is a scalar and `drift.ts`'s `defaultEqual`
+ *   (`deepEqual` with `stripNullish: true`) already gives UniFi's `null`-for-unset-optional
+ *   reality the same tolerance `network-drift.ts`/`firewall-zone-form.ts` rely on — see
+ *   `dns-policy-form.ts`'s own header for why no field here needs a set/order normalizer.
+ */
+import type * as dnsPolicies from '@distilled.cloud/unifi-network/dns_policies';
+import { makeDriftOf } from './drift.ts';
+import { type DnsPolicyAttributes, type DnsPolicyProps, attributesOf } from './dns-policy-form.ts';
+
+const fieldDrift = makeDriftOf<DnsPolicyAttributes, DnsPolicyProps>([
+  { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
+  { field: 'type', live: (a) => a.type, declared: (p) => p.type },
+  { field: 'domain', live: (a) => a.domain, declared: (p) => p.domain },
+  { field: 'ipv6Address', live: (a) => a.ipv6Address, declared: (p) => p.ipv6Address },
+  { field: 'ttlSeconds', live: (a) => a.ttlSeconds, declared: (p) => p.ttlSeconds },
+  { field: 'ipv4Address', live: (a) => a.ipv4Address, declared: (p) => p.ipv4Address },
+  { field: 'targetDomain', live: (a) => a.targetDomain, declared: (p) => p.targetDomain },
+  { field: 'ipAddress', live: (a) => a.ipAddress, declared: (p) => p.ipAddress },
+  {
+    field: 'mailServerDomain',
+    live: (a) => a.mailServerDomain,
+    declared: (p) => p.mailServerDomain,
+  },
+  { field: 'priority', live: (a) => a.priority, declared: (p) => p.priority },
+  { field: 'port', live: (a) => a.port, declared: (p) => p.port },
+  { field: 'protocol', live: (a) => a.protocol, declared: (p) => p.protocol },
+  { field: 'serverDomain', live: (a) => a.serverDomain, declared: (p) => p.serverDomain },
+  { field: 'service', live: (a) => a.service, declared: (p) => p.service },
+  { field: 'weight', live: (a) => a.weight, declared: (p) => p.weight },
+  { field: 'text', live: (a) => a.text, declared: (p) => p.text },
+]);
+
+export const matches = (attributes: DnsPolicyAttributes, props: DnsPolicyProps): 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: dnsPolicies.DNSPolicy, props: DnsPolicyProps) =>
+  fieldDrift(attributesOf(live, props), props);