@homeflare/alchemy 0.49.0 → 0.51.0

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());
+  });
+});

package/src/unifi/network-update.ts

@@ -0,0 +1,95 @@
+/**
+ * `Unifi.Network`'s one write: `updateNetwork`. THE ONLY FILE UNDER `src/unifi` ALLOWED TO NAME IT
+ * (`write-op-reference.test.ts`'s `WRITE_OP_ALLOWLIST` pins that, and still refuses
+ * `createNetwork`/`deleteNetwork` here).
+ *
+ * ⛔ THE WHOLE-OBJECT-PUT TRAP (packages/distilled-unifi-network/README.md). `PUT .../networks/{id}` disables
+ *   `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration` outright when the body omits them. So
+ *   the body is never `props`: it is the RAW live object (as `fetchLive` decoded it) minus the
+ *   server fields (`SERVER_FIELDS`: `id`/`default`/`metadata`), plus ONLY the patch (HIGH-2). A
+ *   hand edit on a field
+ *   the declaration never touched rides through byte-for-byte; `update-reconcile.ts` has already
+ *   refused any hand edit on a declared field.
+ *
+ * ★ WHY RAW LIVE, NOT THE ATTRIBUTES VIEW (LOW-6). `attributesOf` normalizes (sorted sets) and
+ *   drops keys this kit does not model. Unknown keys must survive the round trip or the PUT would
+ *   silently delete a setting the console added after the SDK was generated (F2). Measured by
+ *   reading `@distilled.cloud/core` `protocol-http.ts`: `validateResponse` returns the ORIGINAL
+ *   decoded value and `mapKeys` passes unknown keys through at every level, so top-level and
+ *   nested unknown keys both survive; `network-update.test.ts` is the alarm if that ever changes.
+ *
+ * ★ WHY `unset` EXISTS (HIGH-1). Reverting a declaration (dropping `ipv6Configuration`) must plan
+ *   and execute a real update back to the pre-image. A key in `patch.unset` is DELETED from the
+ *   body, which is exactly "absent = off" for the optional blocks above.
+ *
+ * ⛔ NO-OP GUARD. If the merged body equals live (ignoring the ids), the PUT would change nothing;
+ *   `UnifiUpdateWouldBeNoop` refuses so a normalizer gap can never become a re-PUT loop.
+ *
+ * ⛔ NO RETRY ON THE PUT (red team round 1, reversing the earlier Q7 decision). The SDK's default
+ *   policy would replay a write whose first attempt may already have landed (a dropped response
+ *   during a reprovision); a replay then runs against a controller state this reconcile never
+ *   read. One attempt, and a failure surfaces for the operator. Reads keep the default policy.
+ *
+ * ⛔ SCOPE FIRST (`network-scope.ts`): the management LAN, immutable fields and non-removable keys
+ *   are refused before the body is even built, so none of them can reach the wire.
+ */
+import * as networks from '@distilled.cloud/unifi-network/networks';
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import { deepEqual } from 'alchemy/Diff';
+import * as Effect from 'effect/Effect';
+import { type NetworkProps } from './network-form.ts';
+import { checkNetworkWriteScope } from './network-scope.ts';
+import { UnifiUpdateWouldBeNoop } from './policy.ts';
+import type { Patch } from './update-reconcile.ts';
+
+export const SERVER_FIELDS = ['id', 'default', 'metadata'] as const;
+
+/**
+ * The live object minus `SERVER_FIELDS` — ONE list drives the strip. The destructure this
+ * replaced hard-coded the same three names a second time, so a key added to the export was
+ * silently NOT stripped (and a removed one still was): two lists that could drift apart. Own
+ * enumerable string keys only, exactly what object-rest destructure copies; a decoded JSON body
+ * has no symbol keys.
+ */
+const withoutServerFields = (live: networks.NetworkDetails): Record<string, unknown> => {
+  const server = new Set<string>(SERVER_FIELDS);
+  const rest: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(live)) {
+    if (!server.has(key)) rest[key] = value;
+  }
+  return rest;
+};
+
+export const mergeForUpdate = (
+  live: networks.NetworkDetails,
+  patch: Patch<NetworkProps>,
+  props: NetworkProps,
+): Effect.Effect<networks.UpdateNetworkRequest, UnifiUpdateWouldBeNoop> => {
+  // Raw copy minus the server fields: unknown top-level keys stay in `rest` (F2).
+  const rest = withoutServerFields(live);
+  const body: Record<string, unknown> = { ...rest, ...patch.set };
+  for (const key of patch.unset) delete body[key];
+  if (deepEqual(body, rest, { stripNullish: true })) {
+    return Effect.fail(
+      new UnifiUpdateWouldBeNoop({
+        type: 'Unifi.Network',
+        identity: `sites/${props.siteId}/networks/${props.networkId}`,
+      }),
+    );
+  }
+  return Effect.succeed({
+    ...body,
+    siteId: props.siteId,
+    networkId: live.id,
+  } as networks.UpdateNetworkRequest);
+};
+
+export const writeNetwork = (
+  live: networks.NetworkDetails,
+  patch: Patch<NetworkProps>,
+  props: NetworkProps,
+) =>
+  checkNetworkWriteScope(live, patch, props).pipe(
+    Effect.andThen(mergeForUpdate(live, patch, props)),
+    Effect.flatMap((body) => networks.updateNetwork(body).pipe(Retry.none)),
+  );

package/src/unifi/network.test.ts

@@ -90,7 +90,7 @@ describe('declareNetwork -- the declaration renderer', () => {
   });
 });
 
-describe('Unifi.Network write paths never reach the vendor API', () => {
+describe('Unifi.Network: only the one allowed PUT ever reaches the vendor API', () => {
   const ops = unifiOperations(spec);
 
   test('reconcile on an exact-match adoption (H6) makes no request but the one read', async () => {
@@ -119,6 +119,32 @@ describe('Unifi.Network write paths never reach the vendor API', () => {
     expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
   });
 
+  test('a missing network still refuses create -- nothing is ever POSTed', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toMatchObject({ _tag: 'UnifiWriteRefused', action: 'create' });
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('drift with olds undefined (first deploy) refuses update, all-GET', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork({ vlanId: 999 }))
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        ops
+          .reconcile(PROPS, { olds: undefined, output: undefined })
+          .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure).toMatchObject({ _tag: 'UnifiWriteRefused', action: 'update' });
+    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 === NETWORK_PATH