@homeflare/alchemy 0.57.0 → 0.59.0

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

@@ -10,9 +10,9 @@
  *   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.
+ * ★ `destination`/`ipProtocolScope`/`schedule`/`source` run through `normalizeSetArrays` on BOTH
+ *   sides (set-like nested arrays compare as sets; `firewall-policy-form.ts`'s header), then the
+ *   default `deepEqual`. `action` compares wholesale.
  */
 import type * as firewall from '@distilled.cloud/unifi-network/firewall';
 import { makeDriftOf } from './drift.ts';
@@ -21,6 +21,7 @@ import {
   type FirewallPolicyProps,
   attributesOf,
   normalizeConnectionStateFilter,
+  normalizeSetArrays,
 } from './firewall-policy-form.ts';
 
 const fieldDrift = makeDriftOf<FirewallPolicyAttributes, FirewallPolicyProps>([
@@ -31,14 +32,30 @@ const fieldDrift = makeDriftOf<FirewallPolicyAttributes, FirewallPolicyProps>([
     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: 'destination',
+    live: (a) => normalizeSetArrays(a.destination),
+    declared: (p) => normalizeSetArrays(p.destination),
+  },
   { field: 'enabled', live: (a) => a.enabled, declared: (p) => p.enabled },
-  { field: 'ipProtocolScope', live: (a) => a.ipProtocolScope, declared: (p) => p.ipProtocolScope },
+  {
+    field: 'ipProtocolScope',
+    live: (a) => normalizeSetArrays(a.ipProtocolScope),
+    declared: (p) => normalizeSetArrays(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 },
+  {
+    field: 'schedule',
+    live: (a) => normalizeSetArrays(a.schedule),
+    declared: (p) => normalizeSetArrays(p.schedule),
+  },
+  {
+    field: 'source',
+    live: (a) => normalizeSetArrays(a.source),
+    declared: (p) => normalizeSetArrays(p.source),
+  },
 ]);
 
 export const matches = (

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,6 +55,51 @@ 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.
  *
@@ -70,17 +116,17 @@ export interface FirewallPolicyProps {
   /** 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/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>);

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

@@ -8,81 +8,23 @@
  */
 import { describe, expect, test } from 'bun:test';
 import type * as networks from '@distilled.cloud/unifi-network/networks';
-import * as Retry from '@distilled.cloud/unifi-network/Retry';
-import * as Effect from 'effect/Effect';
-import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
-import { NETWORK_PATCH_KEYS, type NetworkProps, spec } from './network.ts';
+import { fakeFailure } from './fake-unifi.ts';
+import { NETWORK_PATCH_KEYS, type NetworkProps } from './network.ts';
+import {
+  BASE,
+  IPV6,
+  WITH_V6,
+  answering,
+  live,
+  putBody,
+  reconcile,
+} from './network-update.fixtures.ts';
 import { SERVER_FIELDS } from './network-update.ts';
 import {
   UnifiLiveDriftedSinceDeploy,
   UnifiUpdateDidNotConverge,
   UnifiWriteRefused,
 } from './policy.ts';
-import { unifiOperations } from './resource.ts';
-
-const PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
-const IPV6 = {
-  interfaceType: 'STATIC',
-  prefixLength: 64,
-  hostIpAddress: '2602:f660:0:16::254',
-  clientAddressAssignment: { slaacEnabled: true },
-  routerAdvertisement: { priority: 'HIGH' },
-};
-
-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' },
-};
-const WITH_V6 = { ...BASE, ipv6Configuration: IPV6 } as NetworkProps;
-
-/** Raw live object, with a key the SDK schema has never heard of. */
-const live = (extra: Record<string, unknown> = {}) => ({
-  id: 'net-1',
-  default: false,
-  metadata: { origin: 'USER' },
-  futureTopLevelKey: 'x',
-  ...BASE,
-  siteId: undefined,
-  networkId: undefined,
-  ...extra,
-});
-
-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) };
-};
-
-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');
-
-const putBody = (seen: ReadonlyArray<{ method: string; body?: unknown }>) =>
-  seen.filter((s) => s.method === 'PUT').map((s) => s.body as Record<string, unknown>);
 
 describe('Unifi.Network update', () => {
   test('(1) one GET then one PUT: live carried through byte-equal, server fields dropped, patch added', async () => {

package/src/unifi/update-reconcile.ts

@@ -72,6 +72,21 @@ export const computePatch = <Props extends object>(
   return { set, unset };
 };
 
+/** `olds` with each accepted field taken from `news` (which equals live there), so the patch
+ *  skips it. A `FieldDrift.field` names a props key; one that is not is left alone. */
+const acceptInto = <Props extends object>(
+  olds: Props,
+  news: Props,
+  accepted: ReadonlyArray<unknown>,
+): Props => {
+  const next: Record<string, unknown> = { ...(olds as Record<string, unknown>) };
+  for (const field of accepted) {
+    const key = String(field);
+    if (key in (news as object) || key in next) next[key] = (news as Record<string, unknown>)[key];
+  }
+  return next as Props;
+};
+
 export type ReconcileArgs<Props extends object> = {
   readonly news: Props;
   readonly olds: Props | undefined;
@@ -99,15 +114,34 @@ export const updateReconcile = <Props extends object, Live, Attributes extends o
     if (previous !== identity) {
       return yield* new UnifiIdentityChanged({ type: spec.type, identity, previous });
     }
+    // ★ A FIELD THAT DRIFTED SINCE THE LAST DEPLOY IS A CONFLICT ONLY IF THE DECLARATION STILL
+    //   DISAGREES WITH LIVE ON IT. When the declaration already equals live there (a re-import
+    //   recorded the console edit, the documented recovery for UnifiLiveDriftedSinceDeploy),
+    //   the edit is ACCEPTED: folded into the baseline, so it is neither refused nor patched. The
+    //   PUT is live plus the patch, so live's value survives untouched. Without this, `olds`
+    //   (the last deployed state) only moves on a successful deploy, so a re-import could never
+    //   clear the refusal (homeflare-network VLAN 16, 2026-10-19: mdnsForwardingEnabled edited on
+    //   the console, re-imported, and still refused on every deploy).
+    // ⛔ A drifted field the declaration DISAGREES with stays a refusal: the PUT would overwrite
+    //   a hand edit nobody re-imported.
+    const disagrees = new Set(update.driftOf(live, news).map((d) => String(d.field)));
     const drifted = update.driftOf(live, olds).map((d) => d.field);
-    if (drifted.length > 0) {
+    const conflicts = drifted.filter((field) => disagrees.has(String(field)));
+    if (conflicts.length > 0) {
       return yield* new UnifiLiveDriftedSinceDeploy({
         type: spec.type,
         identity,
-        fields: drifted,
+        fields: conflicts,
       });
     }
-    const patch = computePatch(news, olds, update.patchKeys);
+    const accepted = drifted.filter((field) => !disagrees.has(String(field)));
+    const baseline = acceptInto(olds, news, accepted);
+    if (accepted.length > 0) {
+      yield* note(
+        `${spec.type} ${identity}: live edits since the last deploy already match the declaration, accepted: [${accepted.map(String).join(', ')}]`,
+      );
+    }
+    const patch = computePatch(news, baseline, update.patchKeys);
     if (Object.keys(patch.set).length === 0 && patch.unset.length === 0) {
       return yield* refuseWrite(spec.type, identity, 'update');
     }