@homeflare/alchemy 0.56.0 → 0.58.0

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

@@ -15,17 +15,18 @@
  *   `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.
+ * ★ SET-LIKE NESTED ARRAYS COMPARE AS SETS (closed 2026-10-19; was T15's accepted gap). The
+ *   vendor's filter variants inside `source`/`destination`/`ipProtocolScope`/`schedule` carry
+ *   arrays with no documented order: `FirewallPolicyIPAddressFilter.items`, the port filter's
+ *   `items`, `FirewallPolicyMACAddressFilter.macAddresses`, `FirewallPolicyNetworkFilter.networkIds`,
+ *   `FirewallPolicyApplicationFilter.applicationIds`, `FirewallPolicyRegionFilter.regions`,
+ *   `FirewallPolicyVPNServerFilter.vpnServerIds`, `FirewallPolicyDomainFilter.domains`,
+ *   `applicationCategoryIds` and `FirewallSchedule.repeatOnDays`. Measured:
+ *   the controller (Network 11.0.83) stored a declared port list [443, 9100] as [9100, 443], so a
+ *   correct create failed its read-back (`UnifiCreateDidNotConverge`, homeflare-network PR 79).
+ *   `normalizeSetArrays` sorts every array under one of those keys (by canonical JSON) on BOTH
+ *   sides before `deepEqual`. Membership still has to match exactly, and duplicates are kept, so a
+ *   real change is never hidden.
  *
  * ⛔ `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
@@ -54,26 +55,78 @@ export const normalizeConnectionStateFilter = (
   value: readonly string[] | undefined,
 ): string[] | undefined => (value == null ? undefined : sortedSet(value));
 
+/** Keys whose array value is a set in the vendor's firewall filter schemas (header). */
+const SET_ARRAY_KEYS: ReadonlySet<string> = new Set([
+  'items',
+  'macAddresses',
+  'networkIds',
+  'applicationIds',
+  'regions',
+  'vpnServerIds',
+  'repeatOnDays',
+  'domains',
+  'applicationCategoryIds',
+]);
+
+/** Key-order-independent JSON: a hand-written `{start, stop, type}` and a decoded `{type, start,
+ *  stop}` must sort to the same place (Opus red team, kit PR 466). */
+const sortKeys = (value: unknown): unknown =>
+  Array.isArray(value)
+    ? value.map(sortKeys)
+    : value !== null && typeof value === 'object'
+      ? Object.fromEntries(
+          Object.keys(value as object)
+            .sort()
+            .map((k) => [k, sortKeys((value as Record<string, unknown>)[k])]),
+        )
+      : value;
+const canonical = (value: unknown): string => JSON.stringify(sortKeys(normalizeSetArrays(value)));
+
+/** A deep copy with every SET_ARRAY_KEYS array sorted by canonical JSON (duplicates kept). */
+export const normalizeSetArrays = <T>(value: T): T => {
+  if (Array.isArray(value)) return value.map((v) => normalizeSetArrays(v)) as T;
+  if (value === null || typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+    out[key] =
+      SET_ARRAY_KEYS.has(key) && Array.isArray(inner)
+        ? [...inner]
+            .map((v) => normalizeSetArrays(v))
+            .sort((x, y) =>
+              canonical(x) < canonical(y) ? -1 : canonical(x) > canonical(y) ? 1 : 0,
+            )
+        : normalizeSetArrays(inner);
+  }
+  return out as T;
+};
+
 /** ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` — `exactOptionalPropertyTypes`; see
- *  `network-form.ts`'s own header. */
+ *  `network-form.ts`'s own header.
+ *
+ * ⛔ `firewallPolicyId` IS OPTIONAL SINCE THE 2026-10-19 hf: CREATE LIFT. An adopt-only
+ *   declaration (`declareFirewallPolicy`, every imported row) always carries the vendor id it was
+ *   read from. A fresh `hf:` creatable declaration (`declareHfFirewallPolicy` below) does not have
+ *   one yet — the vendor assigns it on `createFirewallPolicy`'s response — so `spec.fetchLive`
+ *   (`firewall-policy.ts`) locates by `name` instead of `id` whenever this is absent (netbox's
+ *   `locateOne` is the precedent for identity-by-natural-key over identity-by-vendor-id). */
 export interface FirewallPolicyProps {
   siteId: string;
-  firewallPolicyId: string;
+  firewallPolicyId?: string | undefined;
   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. */
+  /** Traffic destination — compound, compared wholesale with set-like arrays normalized; see the header. */
   destination: firewall.FirewallPolicyDestination;
   enabled: boolean;
-  /** IP version + protocol scope — compound, compared wholesale; see the header's known gap. */
+  /** IP version + protocol scope — compound, compared wholesale with set-like arrays normalized; see the header. */
   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 this policy is active on — compound, compared wholesale with set-like arrays normalized; see the header. */
   schedule?: firewall.FirewallSchedule | undefined;
-  /** Traffic source — compound, compared wholesale; see the header's known gap. */
+  /** Traffic source — compound, compared wholesale with set-like arrays normalized; see the header. */
   source: firewall.FirewallPolicySource;
 }
 

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

@@ -23,7 +23,13 @@ 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 {
+  type FirewallPolicyProps,
+  declareFirewallPolicy,
+  hfFirewallPolicy,
+  spec,
+} from './firewall-policy.ts';
+import { UnifiCreateDidNotConverge, UnifiWriteRefused } from './policy.ts';
 import { pageAll } from './paginate.ts';
 import { unifiOperations } from './resource.ts';
 
@@ -152,6 +158,187 @@ describe('Unifi.FirewallPolicy write paths never reach the vendor API', () => {
   });
 });
 
+/**
+ * The hf: create lift (Tim 2026-10-19 ~16:20Z) -- the one write `Unifi.FirewallPolicy` may now
+ * make, and only for a declared `name` starting `hf: `. Mirrors the write-refusal tests above,
+ * plus the one path that now DOES reach the vendor API.
+ */
+const POLICIES_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies';
+const NEW_ID = 'hf-new-1';
+
+const emptyPage = () => Response.json({ count: 0, data: [], limit: 0, offset: 0, totalCount: 0 });
+
+/** No `firewallPolicyId`: the shape `hfFirewallPolicy` declares before anything is created. */
+const HF_PROPS: FirewallPolicyProps = {
+  siteId: 'site-1',
+  action: { type: 'ALLOW', allowReturnTraffic: true },
+  destination: { zoneId: 'zone-storage' },
+  enabled: true,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: true,
+  name: 'hf: CT100 to NAS https',
+  source: { zoneId: 'zone-internal' },
+};
+
+describe('Unifi.FirewallPolicy hf: create', () => {
+  const ops = unifiOperations(spec);
+
+  test('an hf:-named create: one locate GET, one POST of only the declared fields, one read-back GET', async () => {
+    let createdLive: firewall.FirewallPolicy | undefined;
+    const fake = fakeUnifi((method, url) => {
+      if (url.pathname === POLICIES_PATH && method === 'GET') return emptyPage();
+      if (url.pathname === POLICIES_PATH && method === 'POST') {
+        createdLive = {
+          ...HF_PROPS,
+          id: NEW_ID,
+          index: 0,
+          metadata: { origin: 'USER' },
+        } as firewall.FirewallPolicy;
+        return Response.json(createdLive);
+      }
+      if (url.pathname === `${POLICIES_PATH}/${NEW_ID}` && method === 'GET') {
+        return Response.json(createdLive);
+      }
+      return fakeFailure(400, 'unexpected request');
+    });
+
+    const attrs = await Effect.runPromise(
+      ops.reconcile(HF_PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(attrs.firewallPolicyId).toBe(NEW_ID);
+    expect(attrs.name).toBe('hf: CT100 to NAS https');
+    expect(fake.seen.map((s) => `${s.method} ${s.path}`)).toEqual([
+      `GET ${POLICIES_PATH}?offset=0`,
+      `POST ${POLICIES_PATH}`,
+      `GET ${POLICIES_PATH}/${NEW_ID}`,
+    ]);
+    // ⛔ ONLY the declared fields -- no firewallPolicyId (there was none), no stray key.
+    // `siteId` is a path label (`T.Http`'s `uri: "/v1/sites/{siteId}/..."`), not a body field.
+    expect(fake.seen[1]?.body).toEqual({
+      action: { type: 'ALLOW', allowReturnTraffic: true },
+      destination: { zoneId: 'zone-storage' },
+      enabled: true,
+      ipProtocolScope: { ipVersion: 'IPV4' },
+      loggingEnabled: true,
+      name: 'hf: CT100 to NAS https',
+      source: { zoneId: 'zone-internal' },
+    });
+  });
+
+  test('a non-hf: name refuses create, typed, sending the existence GET but no write', async () => {
+    // ★ The existence GET (does a row this name already matches exist?) runs for every name --
+    //   the SAME GET a plain cold adoption needs (H6) -- and answers empty here. Only the WRITE
+    //   is refused: `fake.seen.every(GET)` is this file's own standing idiom for that proof.
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICIES_PATH
+        ? emptyPage()
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const notHf: FirewallPolicyProps = { ...HF_PROPS, name: 'Not hf-named' };
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(notHf).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect((failure as UnifiWriteRefused).action).toBe('create');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen.length).toBeGreaterThan(0);
+  });
+
+  test('"hf:foo" with no space after the colon is NOT an hf: name -- refused, no write', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICIES_PATH
+        ? emptyPage()
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const noSpace: FirewallPolicyProps = { ...HF_PROPS, name: 'hf:no-space' };
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(noSpace).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a read-back mismatch after the POST fails typed (UnifiCreateDidNotConverge), not silently', async () => {
+    const fake = fakeUnifi((method, url) => {
+      if (url.pathname === POLICIES_PATH && method === 'GET') return emptyPage();
+      if (url.pathname === POLICIES_PATH && method === 'POST') {
+        return Response.json({ ...HF_PROPS, id: NEW_ID, index: 0, metadata: { origin: 'USER' } });
+      }
+      if (url.pathname === `${POLICIES_PATH}/${NEW_ID}` && method === 'GET') {
+        // The read-back disagrees with what was declared (e.g. the console normalized `enabled`).
+        return Response.json({
+          ...HF_PROPS,
+          id: NEW_ID,
+          index: 0,
+          metadata: { origin: 'USER' },
+          enabled: false,
+        });
+      }
+      return fakeFailure(400, 'unexpected request');
+    });
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(HF_PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiCreateDidNotConverge);
+    expect((failure as UnifiCreateDidNotConverge).fields).toEqual(['enabled']);
+  });
+
+  test('an hf:-named row with an id that 404s refuses -- never silently creates a duplicate (Opus red team)', async () => {
+    // ★ THE SCENARIO THE RED TEAM FOUND: an hf:-named row that ALREADY has Alchemy state's
+    //   `firewallPolicyId` but whose live object is gone (state lost and rebuilt with no `olds`/
+    //   `output`, a hand-deleted-and-recreated rule, a wrong id in a generated declaration) must
+    //   still refuse "create" -- not fall through and POST a second copy just because the name
+    //   happens to start `hf: ` (Tim's own hand-made console rules already do).
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-gone' };
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === `${POLICIES_PATH}/fp-gone`
+        ? fakeFailure(404, 'not found')
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(hfWithId).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect((failure as UnifiWriteRefused).action).toBe('create');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('hfFirewallPolicy throws immediately when props already carries a firewallPolicyId', () => {
+    const withId = { ...HF_PROPS, firewallPolicyId: 'fp-1' };
+    expect(() => hfFirewallPolicy('bad', withId)).toThrow(/already carries a firewallPolicyId/);
+  });
+
+  test('update (drift) of an existing hf: row still refuses -- the lift is create only', async () => {
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-hf-1' };
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === `${POLICIES_PATH}/fp-hf-1`
+        ? Response.json({
+            ...HF_PROPS,
+            id: 'fp-hf-1',
+            index: 0,
+            metadata: { origin: 'USER' },
+            enabled: false,
+          })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(hfWithId).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete of an hf: row still refuses -- no DELETE is ever sent', async () => {
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-hf-1' };
+    const exit = await Effect.runPromiseExit(ops.destroy(hfWithId));
+    expect(exit._tag).toBe('Failure');
+  });
+
+  test('hfFirewallPolicy throws immediately for a name that is not hf:-prefixed', () => {
+    expect(() => hfFirewallPolicy('bad', { ...HF_PROPS, name: 'Not hf-named' })).toThrow(/hf: /);
+  });
+});
+
 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) =>

package/src/unifi/firewall-policy.ts

@@ -1,9 +1,13 @@
 /**
- * `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.
+ * `Unifi.FirewallPolicy` — one firewall policy on a UniFi Network site. READ/ADOPT-ONLY for every
+ * row (`policy.ts`), EXCEPT create for a row whose declared `name` starts `hf: `
+ * (`isHfPolicyName`, Tim 2026-10-19 ~16:20Z) — `update` and `delete` stay refused even for an
+ * `hf:` row. `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`) is the sibling
+ * resource for policy ORDER within a zone pair (T5) — one per `(sourceFirewallZoneId,
+ * destinationFirewallZoneId)`, still read-only; this lift does not touch it, so a created `hf:`
+ * row lands wherever the controller places a new policy, and placing it ahead of its zone pair's
+ * "Block All Traffic" (if the controller does not already do that) would need an ordering WRITE —
+ * a second, separate lift this PR does not make (see `docs/unifi-firewall-policy.md`).
  *
  * ★ 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`,
@@ -14,25 +18,47 @@
  *   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`.
+ *
+ * ⛔ `fetchLive` LOCATES BY `name` WHEN `firewallPolicyId` IS ABSENT (an `hf:` creatable
+ *   declaration never has the vendor id before its first successful create). A real site's policy
+ *   count is in the hundreds (T9, 424 live policies), so this walks every page with `pageAll`
+ *   rather than trusting any one page to hold the match — same reasoning netbox's `locateOne`
+ *   gives for a server-side filter that cannot be trusted alone, except here there IS no
+ *   server-side name filter at all, so every row is paged. More than one row sharing a name is a
+ *   defect, not a reason to take the first: `policy.ts`'s naming convention is exactly `hf: <desc>`
+ *   because a free-text description makes a collision astronomically unlikely, but if the console
+ *   ever has one, this engine refuses to guess which row is "the" declared one.
  */
 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 {
+  checkHfCreateScope,
+  firewallPolicyCreateAllowedWrite,
+  writeFirewallPolicyCreate,
+} from './firewall-policy-create.ts';
+import { driftOf } from './firewall-policy-drift.ts';
 import {
   type FirewallPolicyAttributes,
   type FirewallPolicyProps,
   attributesOf,
 } from './firewall-policy-form.ts';
 import { matches } from './firewall-policy-drift.ts';
+import { type UnifiPaginationInconsistent, pageAll } from './paginate.ts';
 import type { UnifiRequirements, UnifiSpec } from './resource.ts';
 import { unifiHandlers } from './resource.ts';
+import type { UnifiWriteRefused } from './policy.ts';
 
 export type { FirewallPolicyAttributes, FirewallPolicyProps } from './firewall-policy-form.ts';
 export { declareFirewallPolicy } from './firewall-policy-form.ts';
 export { driftOf } from './firewall-policy-drift.ts';
 
+/** `checkHfCreateScope`'s typed refusal, union'd with the real create call's own error, same
+ *  shape `network.ts`'s own `UpdateError` gives its write half. */
+type CreateError = UnifiWriteRefused | firewall.CreateFirewallPolicyError;
+
 export interface UnifiFirewallPolicy extends Resource<
   'Unifi.FirewallPolicy',
   FirewallPolicyProps,
@@ -45,26 +71,96 @@ export const UnifiFirewallPolicy = Resource<UnifiFirewallPolicy>('Unifi.Firewall
   defaultRemovalPolicy: 'retain',
 });
 
-/** `firewallPolicy('block-iot-wan', props)` — `adopt(true)` piped on by default (H5); see
- *  `network.ts`. */
+/** `firewallPolicy('block-iot-wan', props)` — for an IMPORTED, adopt-only row (always carries the
+ *  vendor's `firewallPolicyId`). `adopt(true)` piped on by default (H5); see `network.ts`. */
 export const firewallPolicy = (id: string, props: FirewallPolicyProps) =>
   UnifiFirewallPolicy(id, props).pipe(adopt(true));
 
+/**
+ * `hfFirewallPolicy('ct100-to-nas-https', props)` — for a NEW, kit-creatable row: `props` has no
+ * `firewallPolicyId` (the vendor assigns one), and `name` MUST start `hf: ` or this throws
+ * immediately, at declaration time, rather than waiting for `createReconcile`'s own typed refusal
+ * at deploy time. That typed refusal (`checkHfCreateScope`) is still the authoritative gate — this
+ * is a second, earlier check for the common case of a typo, not a replacement for it; a caller
+ * that builds `FirewallPolicyProps` by hand and calls `UnifiFirewallPolicy` directly still goes
+ * through `checkHfCreateScope` and is still refused the same way.
+ *
+ * ⛔ NO `adopt(true)` HERE. This is a create path, not an adoption: a cold read finding an
+ *  existing row of this exact name is `Unowned`, same as any other family, and a plan that adopts
+ *  one silently is not what "create" means for this lift.
+ */
+export const hfFirewallPolicy = (
+  id: string,
+  props: Omit<FirewallPolicyProps, 'firewallPolicyId'>,
+) => {
+  // ⚠️ `Omit` only rejects an excess property on a FRESH object literal passed at the call site —
+  //   a variable typed `FirewallPolicyProps` (which still has the field) passes the parameter type
+  //   check silently (Opus red team, 2026-10-19, SECONDARY FINDING). Checked at runtime so this
+  //   constructor cannot be the route past `checkHfCreateScope`'s own identity check either.
+  if (
+    'firewallPolicyId' in props &&
+    (props as { firewallPolicyId?: unknown }).firewallPolicyId !== undefined
+  ) {
+    throw new Error(
+      `hfFirewallPolicy(${id}): props already carries a firewallPolicyId -- this constructor is ` +
+        'for a row that does not exist yet. A row with a vendor id is adopted or updated, never ' +
+        'created; use firewallPolicy() instead.',
+    );
+  }
+  if (!props.name.startsWith('hf: ')) {
+    throw new Error(
+      `hfFirewallPolicy(${id}): name "${props.name}" does not start "hf: " -- only hf:-named ` +
+        'policies may be created by this kit (Tim 2026-10-19); rename the declaration.',
+    );
+  }
+  return UnifiFirewallPolicy(id, props as FirewallPolicyProps);
+};
+
+/** One page of `getFirewallPolicies`, walked end to end and narrowed to the sole row named
+ *  `name` — the locate path `fetchLive` uses when `firewallPolicyId` is not yet known. */
+const locateByName = (siteId: string, name: string) =>
+  pageAll(firewall.getFirewallPolicies, { siteId }).pipe(
+    Effect.map((rows) => {
+      const matching = rows.filter((row) => row.name === name);
+      if (matching.length > 1) {
+        throw new Error(
+          `Unifi.FirewallPolicy: ${String(matching.length)} live policies are named "${name}" on ` +
+            `site ${siteId}. A name this engine locates by must be unique; rename one on the console.`,
+        );
+      }
+      return matching[0];
+    }),
+  );
+
 /** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
 export const spec: UnifiSpec<
   FirewallPolicyProps,
   firewall.FirewallPolicy,
   FirewallPolicyAttributes,
-  firewall.GetFirewallPolicyError
+  firewall.GetFirewallPolicyError | firewall.GetFirewallPoliciesError | UnifiPaginationInconsistent,
+  never,
+  CreateError
 > = {
   type: 'Unifi.FirewallPolicy',
-  describe: (props) => `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
+  describe: (props) =>
+    props.firewallPolicyId === undefined
+      ? `sites/${props.siteId}/firewall/policies/by-name/${props.name}`
+      : `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
   fetchLive: (props) =>
-    firewall
-      .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
-      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+    props.firewallPolicyId === undefined
+      ? locateByName(props.siteId, props.name)
+      : firewall
+          .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
+          .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   attributes: attributesOf,
   matches,
+  create: {
+    allowedWrite: firewallPolicyCreateAllowedWrite,
+    checkScope: checkHfCreateScope,
+    write: writeFirewallPolicyCreate,
+    identify: (props, written) => ({ ...props, firewallPolicyId: written.id }),
+    driftOf,
+  },
 };
 
 export const handlers = unifiHandlers(spec);

package/src/unifi/index.ts

@@ -94,6 +94,7 @@ export {
   UnifiFirewallPolicyProvider,
   declareFirewallPolicy,
   firewallPolicy,
+  hfFirewallPolicy,
   type FirewallPolicyAttributes,
   type FirewallPolicyProps,
   driftOf as firewallPolicyDriftOf,

package/src/unifi/network-update-accept.test.ts

@@ -0,0 +1,59 @@
+/**
+ * A live edit made since the last deploy that the declaration ALREADY matches (a re-import
+ * recorded it) is accepted, not refused: it is folded into the baseline, so it is neither a
+ * conflict nor part of the PUT patch. A live edit the declaration disagrees with is still
+ * refused (network-update.test.ts case 6). Measured case: homeflare-network VLAN 16,
+ * 2026-10-19 (mdnsForwardingEnabled edited on the console, re-imported, refused forever).
+ */
+import { describe, expect, test } from 'bun:test';
+import type { NetworkProps } from './network.ts';
+import {
+  BASE,
+  IPV6,
+  WITH_V6,
+  answering,
+  live,
+  putBody,
+  reconcile,
+} from './network-update.fixtures.ts';
+
+describe('Unifi.Network update: accepted live drift', () => {
+  test('a console edit the re-import recorded is accepted; the declared change still PUTs', async () => {
+    const liveBody = live({ mdnsForwardingEnabled: true });
+    const news = { ...WITH_V6, mdnsForwardingEnabled: true } as NetworkProps;
+    const route = answering(liveBody, () =>
+      Response.json({ ...liveBody, ipv6Configuration: IPV6 }),
+    );
+    const { fake, exit, notes } = reconcile(route, news, BASE);
+    expect((await exit)._tag).toBe('Success');
+    expect(fake.seen.map((s) => s.method)).toEqual(['GET', 'PUT']);
+    const body = putBody(fake.seen)[0] as Record<string, unknown>;
+    expect(body.ipv6Configuration).toEqual(IPV6);
+    expect(body.mdnsForwardingEnabled).toBe(true);
+    expect(notes.some((n) => n.includes('accepted: [mdnsForwardingEnabled]'))).toBe(true);
+    expect(notes.some((n) => /PUT changes \[ipv6Configuration\]/.test(n))).toBe(true);
+  });
+
+  test('accepted drift never widens the patch past the declared change', async () => {
+    const liveBody = live({ name: 'Renamed' });
+    const news = { ...WITH_V6, name: 'Renamed' } as NetworkProps;
+    const route = answering(liveBody, () =>
+      Response.json({ ...liveBody, ipv6Configuration: IPV6 }),
+    );
+    const { exit, notes } = reconcile(route, news, BASE);
+    expect((await exit)._tag).toBe('Success');
+    expect(notes.find((n) => n.includes('PUT changes'))).toContain(
+      'PUT changes [ipv6Configuration]',
+    );
+  });
+
+  test('drift the declaration disagrees with stays refused, even beside an accepted field', async () => {
+    const liveBody = live({ mdnsForwardingEnabled: true, name: 'Renamed' });
+    const news = { ...WITH_V6, mdnsForwardingEnabled: true } as NetworkProps;
+    const { fake, exit } = reconcile(answering(liveBody), news, BASE);
+    const result = JSON.stringify(await exit);
+    expect(result).toContain('UnifiLiveDriftedSinceDeploy');
+    expect(result).toContain('"fields":["name"]');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});

package/src/unifi/network-update.fixtures.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared fixtures for the `Unifi.Network` update tests (network-update.test.ts,
+ * network-update-accept.test.ts): the fake controller route, the base declaration and the
+ * reconcile driver. Extracted so neither test file passes the 250-line cap.
+ */
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type NetworkProps, spec } from './network.ts';
+import { unifiOperations } from './resource.ts';
+
+export const PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
+export const IPV6 = {
+  interfaceType: 'STATIC',
+  prefixLength: 64,
+  hostIpAddress: '2602:f660:0:16::254',
+  clientAddressAssignment: { slaacEnabled: true },
+  routerAdvertisement: { priority: 'HIGH' },
+};
+
+export const BASE: NetworkProps = {
+  siteId: 'site-1',
+  networkId: 'net-1',
+  name: 'Compute',
+  enabled: true,
+  management: 'ADVANCED',
+  vlanId: 16,
+  dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1'] },
+  ipv4Configuration: { dhcpConfiguration: { mode: 'SERVER' }, hostIpAddress: '10.20.16.254' },
+};
+export const WITH_V6 = { ...BASE, ipv6Configuration: IPV6 } as NetworkProps;
+
+/** Raw live object, with a key the SDK schema has never heard of. */
+export const live = (extra: Record<string, unknown> = {}) => ({
+  id: 'net-1',
+  default: false,
+  metadata: { origin: 'USER' },
+  futureTopLevelKey: 'x',
+  ...BASE,
+  siteId: undefined,
+  networkId: undefined,
+  ...extra,
+});
+
+export const reconcile = (
+  route: (method: string, url: URL) => Response,
+  news: NetworkProps,
+  olds: NetworkProps | undefined,
+  outputArg: object | null = {},
+) => {
+  const output = outputArg ?? undefined;
+  const fake = fakeUnifi(route);
+  const notes: string[] = [];
+  const run = unifiOperations(spec)
+    .reconcile(news, {
+      olds,
+      output,
+      note: (m) => Effect.sync(() => void notes.push(m)),
+    })
+    .pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch)));
+  return { fake, notes, exit: Effect.runPromiseExit(run) };
+};
+
+export const answering =
+  (liveBody: object, put: () => Response = () => Response.json(liveBody)) =>
+  (method: string, url: URL) =>
+    url.pathname === PATH
+      ? method === 'GET'
+        ? Response.json(liveBody)
+        : put()
+      : fakeFailure(400, 'unexpected');
+
+export const putBody = (seen: ReadonlyArray<{ method: string; body?: unknown }>) =>
+  seen.filter((s) => s.method === 'PUT').map((s) => s.body as Record<string, unknown>);