@homeflare/alchemy 0.50.0 → 0.51.0

package/src/unifi/handler-allow-news.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `unifiHandlers.reconcile` builds the allowed PUT from `news`, never `olds` (red team round 1,
+ * mutation gap), and anchors it to the CONFIGURED base URL read from the credentials.
+ *
+ * ★ A probe spec whose `describe` is constant, so `updateReconcile`'s identity check passes and the
+ *   ONLY thing separating `news.id` from `olds.id` is the wire guard's allow entry.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as ConfigProvider from 'effect/ConfigProvider';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import { FAKE_BASE, FAKE_KEY, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type UnifiSpec, unifiHandlers } from './resource.ts';
+
+interface Probe {
+  id: string;
+}
+interface State {
+  written: boolean;
+}
+
+const probe: UnifiSpec<Probe, State, State, unknown, never> = {
+  type: 'Test.Probe',
+  describe: () => 'probe',
+  fetchLive: () =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      const res = yield* client.execute(HttpClientRequest.get(`${FAKE_BASE}/probe`));
+      return (yield* res.json) as unknown as State;
+    }) as never,
+  attributes: (live) => live,
+  matches: (a) => a.written,
+  update: {
+    allowedWrite: (props) => ({ method: 'PUT', tail: `/probe/${props.id}` }),
+    // `id` differs between news and olds, so the patch is non-empty and the write really runs.
+    patchKeys: ['id'],
+    driftOf: () => [],
+    checkScope: () => Effect.void,
+    write: (_live, _patch, props) =>
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        const res = yield* client.execute(HttpClientRequest.put(`${FAKE_BASE}/probe/${props.id}`));
+        return (yield* res.json) as unknown as State;
+      }) as never,
+  },
+};
+
+const config = ConfigProvider.layer(
+  ConfigProvider.fromUnknown({
+    UNIFI_NETWORK_API_BASE_URL: FAKE_BASE,
+    UNIFI_NETWORK_API_KEY: FAKE_KEY,
+  }),
+);
+
+const reconcile = (news: Probe, olds: Probe) => {
+  let written = false;
+  const fake = fakeUnifi((method) => {
+    if (method === 'PUT') written = true;
+    return Response.json({ written });
+  });
+  const exit = Effect.runPromiseExit(
+    unifiHandlers(probe)
+      .reconcile({ news, olds, output: { written: false }, session: { note: () => Effect.void } })
+      .pipe(Effect.provide(Layer.mergeAll(fakeUnifiLayer(fake.fetch), config))) as never,
+  );
+  return { fake, exit };
+};
+
+describe('unifiHandlers.reconcile allow entry', () => {
+  test('is built from news: a PUT to news.id passes even though olds.id differs', async () => {
+    const { fake, exit } = reconcile({ id: 'NEW' }, { id: 'OLD' });
+    expect(Exit.isSuccess(await exit)).toBe(true);
+    expect(fake.seen.filter((s) => s.method === 'PUT').map((s) => s.path)).toEqual([
+      '/proxy/network/integration/probe/NEW',
+    ]);
+  });
+});

package/src/unifi/index.ts

@@ -1,20 +1,36 @@
 /**
- * UniFi Network providers for Alchemy — READ-ONLY, by Tim's rule (2026-09-24; `policy.ts`).
+ * UniFi Network providers for Alchemy — ADOPT-ONLY, except `Unifi.Network` update (Tim's rule of
+ * 2026-09-24 lifted for that one case on 2026-10-10; `policy.ts`).
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, SMALLER THAN THE DIRECTORY. `resource.ts`'s generic engine
  *   and each `*-form.ts`'s wire helpers are internals a provider needs but a consumer should
  *   not depend on — mirrors `../netbox/index.ts`.
  */
-export { UNIFI_READ_ONLY_POLICY, UnifiWriteRefused, type UnifiWriteAction } from './policy.ts';
+export {
+  UNIFI_READ_ONLY_POLICY,
+  UNIFI_WRITE_POLICY,
+  UnifiFieldNotRemovable,
+  UnifiFieldNotSettable,
+  UnifiIdentityChanged,
+  UnifiImmutableFieldChanged,
+  UnifiLiveDriftedSinceDeploy,
+  UnifiManagementNetworkRefused,
+  UnifiUpdateDidNotConverge,
+  UnifiUpdateWouldBeNoop,
+  UnifiWriteRefused,
+  type UnifiWriteAction,
+} from './policy.ts';
 export {
   // Barrel-exported (not just internal to `unifiHandlers`) so `homeflare-network`'s own
   // import-layer guard (plan item C0) can reuse this instead of re-implementing the same
   // `HttpClient` wrap against a second copy of the SDK's `HttpClient.HttpClient` service.
+  type AllowedWrite,
   GetOnlyHttpClient,
   UnifiNonGetRequest,
-  type UnifiRequirements,
-  type UnifiSpec,
-} from './resource.ts';
+  UnifiRefusedRequest,
+  guardedHttpClient,
+} from './wire-guard.ts';
+export { type UnifiRequirements, type UnifiSpec } from './resource.ts';
 export type { FieldDrift } from './drift.ts';
 export {
   UnifiNetwork,

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

@@ -0,0 +1,203 @@
+/**
+ * `Unifi.Network`'s write SCOPE (`network-scope.ts`), identity check, no-retry PUT and message
+ * wording — red team round 1 on PR 377. Drives `unifiOperations(spec).reconcile` against `fakeUnifi`,
+ * so the real SDK `updateNetwork` assembles the request and the fake records every one.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { type NetworkProps, spec } from './network.ts';
+import { UnifiLiveDriftedSinceDeploy, UnifiUpdateDidNotConverge } 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;
+
+const live = (extra: Record<string, unknown> = {}) => ({
+  id: 'net-1',
+  default: false,
+  metadata: { origin: 'USER' },
+  ...BASE,
+  siteId: undefined,
+  networkId: undefined,
+  ...extra,
+});
+
+const run = (
+  liveBody: object,
+  news: NetworkProps,
+  olds: NetworkProps,
+  put: () => Response = () => Response.json(liveBody),
+) => {
+  const fake = fakeUnifi((method, url) =>
+    url.pathname === PATH
+      ? method === 'GET'
+        ? Response.json(liveBody)
+        : put()
+      : fakeFailure(400, 'unexpected'),
+  );
+  const exit = Effect.runPromiseExit(
+    unifiOperations(spec)
+      .reconcile(news, { olds, output: {} })
+      .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+  );
+  return { fake, exit };
+};
+
+const tagOf = (exit: Exit.Exit<unknown, unknown>) => {
+  if (!Exit.isFailure(exit)) return 'Success';
+  const error = Cause.squash(exit.cause) as { _tag?: string; message?: string };
+  return error._tag ?? 'defect';
+};
+const puts = (fake: { seen: ReadonlyArray<{ method: string }> }) =>
+  fake.seen.filter((s) => s.method === 'PUT');
+
+describe('removable-field allowlist (omission would turn the block off)', () => {
+  test.each([
+    ['ipv4Configuration', 'ipv4Configuration'],
+    ['dhcpGuarding', 'dhcpGuarding'],
+    ['a required key (name)', 'name'],
+  ])('dropping %s => UnifiFieldNotRemovable, zero PUTs', async (_n, key) => {
+    const { [key as 'name']: _gone, ...news } = { ...WITH_V6 } as NetworkProps;
+    const { fake, exit } = run(live({ ipv6Configuration: IPV6 }), news as NetworkProps, WITH_V6);
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiFieldNotRemovable');
+    expect(JSON.stringify(result)).toContain(key);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  // ⚠️ Mutation gap: an explicit `null` removes a key just like absence (`== null`, not `=== undefined`).
+  test('an explicit null on ipv6Configuration removes it from the body', async () => {
+    const news = { ...BASE, ipv6Configuration: null } as unknown as NetworkProps;
+    const { fake, exit } = run(live({ ipv6Configuration: IPV6 }), news, WITH_V6, () =>
+      Response.json(live()),
+    );
+    expect(tagOf(await exit)).toBe('Success');
+    const body = puts(fake)[0] as { body?: Record<string, unknown> };
+    expect(body.body).toBeDefined();
+    expect('ipv6Configuration' in (body.body as object)).toBe(false);
+  });
+});
+
+describe('settable-field allowlist (only ipv6Configuration may be written)', () => {
+  // ⛔ Round-2 BLOCKING finding: the PR claimed this scope but sent these PUTs. Each case is a real
+  //   change to a non-ipv6 key, with live matching the prior state, so only the allowlist stops it.
+  test.each([
+    ['enabled', { enabled: false }, {}],
+    ['internetAccessEnabled', { internetAccessEnabled: false }, { internetAccessEnabled: true }],
+    [
+      'ipv4Configuration',
+      { ipv4Configuration: { dhcpConfiguration: { mode: 'NONE' }, hostIpAddress: '10.9.9.1' } },
+      {},
+    ],
+    ['dhcpGuarding', { dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.9'] } }, {}],
+  ])('a patch that sets %s => UnifiFieldNotSettable, zero PUTs', async (field, change, olds) => {
+    const oldProps = { ...WITH_V6, ...olds } as NetworkProps;
+    const { fake, exit } = run(
+      live({ ipv6Configuration: IPV6, ...olds }),
+      { ...oldProps, ...change } as NetworkProps,
+      oldProps,
+    );
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiFieldNotSettable');
+    expect(JSON.stringify(result)).toContain(field);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('setting ipv6Configuration is still allowed', async () => {
+    const { fake, exit } = run(live(), WITH_V6, BASE, () =>
+      Response.json(live({ ipv6Configuration: IPV6 })),
+    );
+    expect(tagOf(await exit)).toBe('Success');
+    expect(puts(fake)).toHaveLength(1);
+  });
+});
+
+describe('write scope', () => {
+  test('a live default (management) network is refused, zero PUTs', async () => {
+    const { fake, exit } = run(live({ default: true }), WITH_V6, BASE);
+    expect(tagOf(await exit)).toBe('UnifiManagementNetworkRefused');
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test.each([
+    ['zoneId', { zoneId: 'zone-2' }, { zoneId: 'zone-1' }],
+    ['vlanId', { vlanId: 17 }, {}],
+    ['management', { management: 'GATEWAY' }, {}],
+    ['deviceId', { deviceId: 'dev-2' }, { deviceId: 'dev-1' }],
+  ])('a patch that changes %s is refused, zero PUTs', async (field, change, olds) => {
+    const oldProps = { ...WITH_V6, ...olds } as NetworkProps;
+    const { fake, exit } = run(
+      live({ ipv6Configuration: IPV6, ...olds }),
+      { ...oldProps, ...change } as NetworkProps,
+      oldProps,
+    );
+    const result = await exit;
+    expect(tagOf(result)).toBe('UnifiImmutableFieldChanged');
+    expect(JSON.stringify(result)).toContain(field);
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('olds naming another network id => UnifiIdentityChanged, zero PUTs', async () => {
+    const { fake, exit } = run(live(), WITH_V6, { ...BASE, networkId: 'net-OLD' });
+    expect(tagOf(await exit)).toBe('UnifiIdentityChanged');
+    expect(puts(fake)).toHaveLength(0);
+  });
+
+  test('olds naming another site id => UnifiIdentityChanged, zero PUTs', async () => {
+    const { fake, exit } = run(live(), WITH_V6, { ...BASE, siteId: 'site-OLD' });
+    expect(tagOf(await exit)).toBe('UnifiIdentityChanged');
+    expect(puts(fake)).toHaveLength(0);
+  });
+});
+
+describe('the PUT is attempted once', () => {
+  test('a 503 on the PUT is not retried', async () => {
+    const { fake, exit } = run(live(), WITH_V6, BASE, () => fakeFailure(503, 'busy'));
+    expect((await exit)._tag).toBe('Failure');
+    expect(puts(fake)).toHaveLength(1);
+  });
+});
+
+describe('error wording', () => {
+  test('did-not-converge says the PUT landed and names re-import', () => {
+    const message = new UnifiUpdateDidNotConverge({
+      type: 'Unifi.Network',
+      identity: 'sites/s/networks/n',
+      fields: ['ipv6Configuration'],
+    }).message;
+    expect(message).toContain('LANDED');
+    expect(message).toContain('differs from the declaration');
+    expect(message).toContain('re-import');
+    expect(message).toContain('[ipv6Configuration]');
+  });
+
+  test('live-drifted names both causes, not only a hand edit', () => {
+    const message = new UnifiLiveDriftedSinceDeploy({
+      type: 'Unifi.Network',
+      identity: 'sites/s/networks/n',
+      fields: ['name'],
+    }).message;
+    expect(message).toContain('hand edit');
+    expect(message).toContain('UnifiUpdateDidNotConverge');
+  });
+});

package/src/unifi/network-scope.ts

@@ -0,0 +1,75 @@
+/**
+ * The write SCOPE of `Unifi.Network`: the one intended consumer is a single VLAN's
+ * `ipv6Configuration`, so everything else a whole-object PUT could reach is refused BEFORE any
+ * request, with a typed error that carries field names only.
+ *
+ * ⛔ SETTABLE ALLOWLIST. A key in `patch.set` is written into the PUT body, so only
+ *   `ipv6Configuration` may be set: `enabled`, `internetAccessEnabled`, `ipv4Configuration`,
+ *   `dhcpGuarding` and every other declared key are refused with `UnifiFieldNotSettable` (a touched
+ *   immutable key gets `UnifiImmutableFieldChanged` first). Widening it is a kit change.
+ * ⛔ REMOVABLE ALLOWLIST. A key in `patch.unset` is deleted from the PUT body, and the controller
+ *   reads an omitted `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration` as "off". Dropping a
+ *   declaration key therefore must not silently turn a live block off: only `ipv6Configuration`
+ *   (the block this write path exists for, and the revert target) may be removed. A required key
+ *   (`name`, `vlanId`, …) removed from a declaration would fail the SDK schema or send a body the
+ *   controller rejects, so it is refused here with the same error.
+ * ⛔ `default: true` IS THE MANAGEMENT LAN. Writing it can cut the admin off the console.
+ * ⛔ `zoneId`/`vlanId`/`management`/`deviceId` decide where the network lives and what serves it;
+ *   a patch (set OR unset) touching one is refused. Non-USER `metadata.origin` is deliberately NOT
+ *   handled yet: no rule exists for it.
+ */
+import type * as networks from '@distilled.cloud/unifi-network/networks';
+import * as Effect from 'effect/Effect';
+import type { NetworkProps } from './network-form.ts';
+import {
+  UnifiFieldNotRemovable,
+  UnifiFieldNotSettable,
+  UnifiImmutableFieldChanged,
+  UnifiManagementNetworkRefused,
+} from './policy.ts';
+import type { Patch } from './update-reconcile.ts';
+
+export const SETTABLE_KEYS: ReadonlyArray<keyof NetworkProps> = ['ipv6Configuration'];
+export const REMOVABLE_KEYS: ReadonlyArray<keyof NetworkProps> = ['ipv6Configuration'];
+export const IMMUTABLE_KEYS: ReadonlyArray<keyof NetworkProps> = [
+  'zoneId',
+  'vlanId',
+  'management',
+  'deviceId',
+];
+
+export type ScopeError =
+  | UnifiFieldNotRemovable
+  | UnifiFieldNotSettable
+  | UnifiImmutableFieldChanged
+  | UnifiManagementNetworkRefused;
+
+const isIn = (list: ReadonlyArray<string>) => (key: string) => list.includes(key);
+
+export const checkNetworkWriteScope = (
+  live: networks.NetworkDetails,
+  patch: Patch<NetworkProps>,
+  props: NetworkProps,
+): Effect.Effect<void, ScopeError> => {
+  const type = 'Unifi.Network';
+  const identity = `sites/${props.siteId}/networks/${props.networkId}`;
+  if (live.default === true) {
+    return Effect.fail(new UnifiManagementNetworkRefused({ type, identity }));
+  }
+  const touched = [...Object.keys(patch.set), ...patch.unset.map(String)];
+  const immutable = touched.filter(isIn(IMMUTABLE_KEYS as ReadonlyArray<string>));
+  if (immutable.length > 0) {
+    return Effect.fail(new UnifiImmutableFieldChanged({ type, identity, fields: immutable }));
+  }
+  const removable = isIn(REMOVABLE_KEYS as ReadonlyArray<string>);
+  const notRemovable = patch.unset.map(String).filter((k) => !removable(k));
+  if (notRemovable.length > 0) {
+    return Effect.fail(new UnifiFieldNotRemovable({ type, identity, fields: notRemovable }));
+  }
+  const settable = isIn(SETTABLE_KEYS as ReadonlyArray<string>);
+  const notSettable = Object.keys(patch.set).filter((k) => !settable(k));
+  if (notSettable.length > 0) {
+    return Effect.fail(new UnifiFieldNotSettable({ type, identity, fields: notSettable }));
+  }
+  return Effect.void;
+};

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

@@ -0,0 +1,250 @@
+/**
+ * `Unifi.Network`'s three-way update against `fakeUnifi`, driving `unifiOperations(spec).reconcile`
+ * with `olds`/`output` set. The PUT goes through the real SDK `updateNetwork`, so path assembly,
+ * JSON encode and status→error matching are the production ones.
+ *
+ * ⚠️ These call `unifiOperations` directly, which bypasses the wire guard (see `wire-guard.test.ts`
+ *   for that); here the question is WHICH BODY is sent and WHEN. The fake records every request.
+ */
+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 { 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 () => {
+    const liveBody = live();
+    const after = { ...liveBody, ipv6Configuration: IPV6 };
+    const route = answering(liveBody, () => Response.json(after));
+    const { fake, exit, notes } = reconcile(route, WITH_V6, 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>;
+    for (const k of ['id', 'default', 'metadata']) expect(k in body).toBe(false);
+    expect(body.futureTopLevelKey).toBe('x');
+    expect(body.dhcpGuarding).toEqual(liveBody.dhcpGuarding);
+    expect(body.ipv4Configuration).toEqual(liveBody.ipv4Configuration);
+    expect(body.ipv6Configuration).toEqual(IPV6);
+    // (8) one note, field names only
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toContain('changes [ipv6Configuration]');
+    expect(notes[0]).not.toContain('2602');
+  });
+
+  test('(2) an unknown NESTED key in live ipv6Configuration survives into the body (F2 alarm)', async () => {
+    const nested = { ...IPV6, futureNestedKey: 'keep' };
+    const liveBody = live({ ipv6Configuration: nested });
+    // olds mirrors live (as an import of the live object would), so there is no drift; news
+    // changes only `ipv6Configuration` (the one settable key) and keeps the unknown nested key.
+    const olds = { ...BASE, ipv6Configuration: nested } as NetworkProps;
+    const news = {
+      ...olds,
+      ipv6Configuration: { ...nested, routerAdvertisement: { priority: 'LOW' } },
+    } as NetworkProps;
+    const { fake, exit } = reconcile(answering(liveBody), news, olds);
+    await exit;
+    const body = putBody(fake.seen)[0] as {
+      ipv6Configuration: Record<string, unknown>;
+      futureTopLevelKey: string;
+    };
+    expect(body.ipv6Configuration.futureNestedKey).toBe('keep');
+    expect(body.ipv6Configuration.routerAdvertisement).toEqual({ priority: 'LOW' });
+    expect(body.futureTopLevelKey).toBe('x');
+  });
+
+  test('(3) revert: olds has ipv6Configuration, news omits it => PUT body has no such key', async () => {
+    const liveBody = live({ ipv6Configuration: IPV6 });
+    const { fake, exit } = reconcile(
+      answering(liveBody, () => Response.json(live())),
+      BASE,
+      WITH_V6,
+    );
+    expect((await exit)._tag).toBe('Success');
+    const bodies = putBody(fake.seen);
+    expect(bodies).toHaveLength(1);
+    expect('ipv6Configuration' in (bodies[0] as object)).toBe(false);
+  });
+
+  test.each([401, 403])('(4) PUT %d => typed failure, exactly one PUT', async (status) => {
+    const { fake, exit } = reconcile(
+      answering(live(), () => fakeFailure(status, 'no')),
+      WITH_V6,
+      BASE,
+    );
+    const result = await exit;
+    expect(result._tag).toBe('Failure');
+    expect(fake.seen.map((s) => s.method)).toEqual(['GET', 'PUT']);
+  });
+
+  test('(5) PUT 200 whose body still mismatches => UnifiUpdateDidNotConverge', async () => {
+    const { fake, exit } = reconcile(answering(live()), WITH_V6, BASE);
+    const result = await exit;
+    expect(JSON.stringify(result)).toContain('UnifiUpdateDidNotConverge');
+    expect(fake.seen.filter((s) => s.method === 'PUT')).toHaveLength(1);
+    expect(UnifiUpdateDidNotConverge.name).toBe('UnifiUpdateDidNotConverge');
+  });
+
+  test('(6) live drifted from olds on name => UnifiLiveDriftedSinceDeploy[name], zero PUTs', async () => {
+    const { fake, exit } = reconcile(answering(live({ name: 'Renamed' })), WITH_V6, BASE);
+    const result = await exit;
+    expect(JSON.stringify(result)).toContain('UnifiLiveDriftedSinceDeploy');
+    expect(JSON.stringify(result)).toContain('"fields":["name"]');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(UnifiLiveDriftedSinceDeploy.name).toBe('UnifiLiveDriftedSinceDeploy');
+  });
+
+  test.each([
+    ['output undefined', BASE, null],
+    ['olds undefined', undefined, {}],
+  ])('(7) %s => refuses update, all-GET', async (_n, olds, output) => {
+    const { fake, exit } = reconcile(answering(live()), WITH_V6, olds, output);
+    const result = await exit;
+    expect(JSON.stringify(result)).toContain('UnifiWriteRefused');
+    expect(JSON.stringify(result)).toContain('"action":"update"');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(UnifiWriteRefused.name).toBe('UnifiWriteRefused');
+  });
+
+  test('declared change equal to olds (pure drift driftOf missed is impossible) writes nothing', async () => {
+    // news == olds but live differs only in a field driftOf compares: that is drift, refused.
+    const { fake, exit } = reconcile(answering(live({ vlanId: 99 })), BASE, BASE);
+    expect((await exit)._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('an exact match writes nothing even with olds/output set (H6)', async () => {
+    const { fake, exit } = reconcile(answering(live()), BASE, BASE);
+    expect((await exit)._tag).toBe('Success');
+    expect(fake.seen.map((s) => s.method)).toEqual(['GET']);
+  });
+});
+
+describe('SERVER_FIELDS: one list drives the strip', () => {
+  // ⛔ PINNED, like NETWORK_PATCH_KEYS above: the values are load-bearing (id travels as the path
+  //   param instead; default/metadata are controller-owned), so the list cannot be quietly
+  //   emptied or widened. The body test below proves the list is actually USED on the wire.
+  test('is exactly the three controller-owned keys', () => {
+    expect([...SERVER_FIELDS]).toEqual(['id', 'default', 'metadata']);
+  });
+
+  test('the PUT body omits exactly those keys from live — every one of them, no other live key', async () => {
+    const liveBody = live();
+    // Only `ipv6Configuration` may be set (network-scope.ts SETTABLE_KEYS), so the change is that.
+    const news = WITH_V6;
+    const { fake, exit } = reconcile(
+      answering(liveBody, () => Response.json({ ...liveBody, ipv6Configuration: IPV6 })),
+      news,
+      BASE,
+    );
+    expect((await exit)._tag).toBe('Success');
+    const body = putBody(fake.seen)[0] as Record<string, unknown>;
+    const server: ReadonlyArray<string> = SERVER_FIELDS;
+    // Exactly, both ways: every SERVER_FIELDS key is gone from the body ...
+    expect(Object.keys(body).filter((k) => server.includes(k))).toEqual([]);
+    // ... and no other live key was stripped on the way. The two identity ids are the one
+    // legitimate extra omission: they travel as the PUT's PATH params — `answering` serves only
+    // PATH, which embeds them — never as body fields.
+    const ids = ['siteId', 'networkId'];
+    expect(
+      Object.keys(liveBody).filter((k) => !server.includes(k) && !ids.includes(k) && !(k in body)),
+    ).toEqual([]);
+  });
+});
+
+describe('NETWORK_PATCH_KEYS', () => {
+  test('equals every NetworkProps key except the two ids', () => {
+    const full: Required<NetworkProps> = {
+      siteId: 's',
+      networkId: 'n',
+      name: 'x',
+      enabled: true,
+      management: 'm',
+      vlanId: 2,
+      dhcpGuarding: { trustedDhcpServerIpAddresses: [] },
+      cellularBackupEnabled: true,
+      internetAccessEnabled: true,
+      ipv4Configuration: {},
+      ipv6Configuration: {} as networks.NetworkIPv6Configuration,
+      isolationEnabled: true,
+      mdnsForwardingEnabled: true,
+      zoneId: 'z',
+      deviceId: 'd',
+    };
+    const ids = ['siteId', 'networkId'];
+    const expected = Object.keys(full).filter((k) => !ids.includes(k));
+    expect([...NETWORK_PATCH_KEYS].map(String).sort()).toEqual(expected.sort());
+  });
+});