@homeflare/alchemy 0.39.0 → 0.41.0

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

@@ -0,0 +1,135 @@
+/**
+ * `Unifi.AclRule`'s wire shape — the declarable subset of `ACLRule` (`getAclRule`'s own decode
+ *   target — `ACLRuleObject` is the structurally-identical page-list item type, unused here), and
+ *   how a live read
+ * becomes both plan attributes and a rendered declaration. Rule ORDER is a separate resource
+ * (`acl-rule-ordering.ts`, T5) — this file is one rule's own fields only.
+ *
+ * ⚠️ `sourceFilter`/`destinationFilter` STAY `unknown`, ON THE SDK'S OWN AUTHORITY.
+ *   `access_control_acl_rules.ts`'s own comment on both ("Shape varies by variant — widened by
+ *   scripts/convert.ts; see README") says the OpenAPI discriminator these vary over was flattened
+ *   at generation time (T10), same as `network-form.ts`'s `ipv4Configuration`. A3 (typing these
+ *   per-discriminator) is scoped OUT of this PR — see the plan's family inventory — so both stay
+ *   opaque JSON, compared with plain `deepEqual`, honest about not being decoded.
+ *
+ * ⚠️ KNOWN GAP UNTIL A3 (T15, red team, Minor finding 4): the vendor's own variant DTOs for these
+ *   filters carry SET-LIKE arrays too (`networkIds`, `ipAddressesOrSubnets`, `portFilter`,
+ *   `macAddresses` — `docs/unifi-acl-rule.md`'s own field notes). Because the filter stays opaque,
+ *   `deepEqual` compares those nested arrays order-sensitively, the same false-`update` risk this
+ *   file already removes for `deviceIds`/`protocolFilter` by normalizing them — but here there is
+ *   no decoded field to normalize. Accepted as a known gap, not fixed, until A3 types the filter
+ *   per-discriminator and can apply `sortedSet` to its own array fields.
+ *
+ * ⛔ `index` IS ATTRIBUTES-ONLY, NEVER DECLARED. `CreateAclRuleRequest`'s own field comment:
+ *   "ACL rule index. This property is deprecated and has no effect. Use the dedicated ACL rule
+ *   reordering endpoint." The live object's current position is `acl-rule-ordering.ts`'s concern
+ *   (`ACLRuleOrdering.orderedAclRuleIds`), not this resource's declared identity — reporting it
+ *   here without comparing it avoids a field that can never converge under this family's own
+ *   `matches` (nothing here could ever change it) from silently pretending to be declarable.
+ *
+ * ⛔ `enforcingDeviceFilter.deviceIds` AND `protocolFilter` ARE SETS, NOT SEQUENCES — same
+ *   reasoning `firewall-zone-form.ts` gives for `networkIds`: "IDs of the Switch-capable devices
+ *   used to enforce the ACL rule" and "Protocols this ACL rule will be applied to" both describe
+ *   membership, with no indication either list is ordered like `acl-rule-ordering.ts`'s rule-id
+ *   sequence. Left alone, a console that returns either in a different order between calls would
+ *   plan a spurious `update` that this read-only family's `reconcile` then refuses forever.
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+
+const sortedSet = (values: readonly string[]): string[] => [...new Set(values)].sort();
+
+/** ★ EXPORTED so `acl-rule-drift.ts` normalizes both live and declared sides identically — see
+ *  `network-form.ts`'s own header for why a normalizer applied to only one side is a bug class. */
+export const normalizeDeviceFilter = (
+  value: aclRules.ACLRuleDeviceFilter | undefined,
+): aclRules.ACLRuleDeviceFilter | undefined =>
+  value == null
+    ? value
+    : {
+        ...value,
+        ...(value.deviceIds !== undefined ? { deviceIds: sortedSet(value.deviceIds) } : {}),
+      };
+
+export const normalizeProtocolFilter = (
+  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 AclRuleProps {
+  siteId: string;
+  aclRuleId: string;
+  /** `ALLOW` or `BLOCK` (also accepts a future vendor value the spec did not enumerate). */
+  action: string;
+  description?: string | undefined;
+  /** Traffic destination filter — opaque, see the header. */
+  destinationFilter?: unknown;
+  enabled: boolean;
+  /** Devices enforcing this rule — compared as a SET, see the header. */
+  enforcingDeviceFilter?: aclRules.ACLRuleDeviceFilter | undefined;
+  name: string;
+  /** Traffic source filter — opaque, see the header. */
+  sourceFilter?: unknown;
+  type: string;
+  /** Protocols this rule applies to — compared as a SET, see the header. */
+  protocolFilter?: string[] | undefined;
+  networkIdFilter?: string | undefined;
+}
+
+export interface AclRuleAttributes {
+  siteId: string;
+  aclRuleId: string;
+  action: string;
+  description: string | undefined;
+  destinationFilter: unknown;
+  enabled: boolean;
+  enforcingDeviceFilter: aclRules.ACLRuleDeviceFilter | undefined;
+  /** ACL rule index (current priority position) — server-derived, never declared; see header. */
+  index: number;
+  name: string;
+  sourceFilter: unknown;
+  type: string;
+  protocolFilter: string[] | undefined;
+  networkIdFilter: string | undefined;
+  /** `metadata.origin` — server-derived, never declared; see `firewall-zone-form.ts`'s own. */
+  metadataOrigin: string;
+}
+
+export const attributesOf = (live: aclRules.ACLRule, props: AclRuleProps): AclRuleAttributes => ({
+  siteId: props.siteId,
+  aclRuleId: live.id,
+  action: live.action,
+  description: live.description,
+  destinationFilter: live.destinationFilter,
+  enabled: live.enabled,
+  enforcingDeviceFilter: normalizeDeviceFilter(live.enforcingDeviceFilter),
+  index: live.index,
+  name: live.name,
+  sourceFilter: live.sourceFilter,
+  type: live.type,
+  protocolFilter: normalizeProtocolFilter(live.protocolFilter),
+  networkIdFilter: live.networkIdFilter,
+  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 `getAclRule`'s own response straight in
+ * and writes the result as `aclRule('<id>', declareAclRule(live, siteId))` — no field is invented
+ * or defaulted beyond what `attributesOf` already reports, so `matches(attributesOf(live, props),
+ * declareAclRule(live, siteId))` is `true` by construction (`acl-rule.test.ts` proves it).
+ */
+export const declareAclRule = (live: aclRules.ACLRule, siteId: string): AclRuleProps => ({
+  siteId,
+  aclRuleId: live.id,
+  action: live.action,
+  description: live.description,
+  destinationFilter: live.destinationFilter,
+  enabled: live.enabled,
+  enforcingDeviceFilter: normalizeDeviceFilter(live.enforcingDeviceFilter),
+  name: live.name,
+  sourceFilter: live.sourceFilter,
+  type: live.type,
+  protocolFilter: normalizeProtocolFilter(live.protocolFilter),
+  networkIdFilter: live.networkIdFilter,
+});

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

@@ -0,0 +1,79 @@
+/**
+ * `Unifi.AclRuleOrdering`'s wire shape — ONE resource per site (`getAclRuleOrdering`'s own scope,
+ * `GET /v1/sites/{siteId}/acl-rules/ordering`), not per rule. Compare with `firewall-zone-form.ts`'s
+ * `networkIds`, which is a genuine SET: this file's `orderedAclRuleIds` is the opposite case.
+ *
+ * ⛔ T5 — `orderedAclRuleIds` IS A SEQUENCE, NEVER RUN THROUGH `sortedSet`. The endpoint's own name
+ *   (`updateAclRuleOrdering`) and its field's own vendor comment on `ACLRule.index` ("Lower index
+ *   has higher priority") both say this list's POSITION is the entire value it carries — rule
+ *   priority. `firewall-zone-form.ts`'s `sortedSet`/`network-form.ts`'s three set normalizers all
+ *   exist to stop the OPPOSITE mistake (treating a set as if order mattered); applying the same
+ *   fix here would silently discard the one thing this resource represents. `drift.ts`'s
+ *   `defaultEqual` (`deepEqual`) already compares arrays element-by-element without sorting them
+ *   (its header: "sorts object KEYS but NOT ARRAY ELEMENTS") — so leaving this field un-normalized
+ *   is what makes the comparison order-sensitive, not an oversight to "fix" later.
+ *
+ * ★ `makeDriftOf` (`drift.ts`), NO CUSTOM `equal` — same framework every other family's
+ *   `matches`/`driftOf` share (MEDIUM-4). Its default `deepEqual` is ALREADY order-sensitive for
+ *   arrays (see the paragraph above), so the absence of a custom `equal` here, unlike
+ *   `firewall-zone-form.ts`'s `networkIds` entry, is itself the "never sortedSet" rule in force —
+ *   not an oversight.
+ */
+import type * as aclRules from '@distilled.cloud/unifi-network/access_control_acl_rules';
+import { makeDriftOf } from './drift.ts';
+
+export interface AclRuleOrderingProps {
+  siteId: string;
+  /** Rule IDs in priority order, highest priority first — never compared as a set (see header). */
+  orderedAclRuleIds: string[];
+}
+
+export interface AclRuleOrderingAttributes {
+  siteId: string;
+  orderedAclRuleIds: string[];
+}
+
+export const attributesOf = (
+  live: aclRules.ACLRuleOrdering,
+  props: AclRuleOrderingProps,
+): AclRuleOrderingAttributes => ({
+  siteId: props.siteId,
+  orderedAclRuleIds: live.orderedAclRuleIds,
+});
+
+/**
+ * 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 `getAclRuleOrdering`'s own response
+ * straight in and writes the result as `aclRuleOrdering('site-1', declareAclRuleOrdering(live,
+ * siteId))` — `matches(attributesOf(live, props), declareAclRuleOrdering(live, siteId))` is `true`
+ * by construction (`acl-rule-ordering.test.ts` proves it).
+ */
+export const declareAclRuleOrdering = (
+  live: aclRules.ACLRuleOrdering,
+  siteId: string,
+): AclRuleOrderingProps => ({
+  siteId,
+  orderedAclRuleIds: live.orderedAclRuleIds,
+});
+
+const fieldDrift = makeDriftOf<AclRuleOrderingAttributes, AclRuleOrderingProps>([
+  {
+    field: 'orderedAclRuleIds',
+    live: (a) => a.orderedAclRuleIds,
+    declared: (p) => p.orderedAclRuleIds,
+  },
+]);
+
+export const matches = (
+  attributes: AclRuleOrderingAttributes,
+  props: AclRuleOrderingProps,
+): 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)`). Only one field exists, so this either reports nothing or the whole
+ * ordered pair, never a per-position breakdown -- a future consumer wanting "which rule moved"
+ * would need to diff the two arrays itself.
+ */
+export const driftOf = (live: aclRules.ACLRuleOrdering, props: AclRuleOrderingProps) =>
+  fieldDrift(attributesOf(live, props), props);

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)));