@homeflare/alchemy 0.50.0 → 0.51.0

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

package/src/unifi/network.ts

@@ -11,12 +11,11 @@
  *   `FirewallZone`; `FirewallPolicy`'s several discriminated filter variants and its
  *   list-replacing ordering endpoint are a bigger, separate PR).
  *
- * ⛔ THE WHOLE-OBJECT-PUT TRAP (`docs/unifi-api-notes.md`) NEVER FIRES HERE, BY CONSTRUCTION.
- *   `updateNetwork` is a `PUT` that disables `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration`
- *   outright when the caller omits them — the exact failure mode a read-only family cannot cause,
- *   because `resource.ts`'s `reconcile` never calls `updateNetwork` at all. Recorded here for
- *   whoever adds the write path this docs note anticipates: read-merge-write the WHOLE object,
- *   never a props-only body.
+ * ⛔ THE WHOLE-OBJECT-PUT TRAP (packages/distilled-unifi-network/README.md) FIRES HERE, THROUGH `network-update.ts`;
+ *   see its header. `updateNetwork` is a `PUT` that disables `dhcpGuarding`/`ipv4Configuration`/
+ *   `ipv6Configuration` outright when the caller omits them, so the body is the raw live object
+ *   plus only the fields the declaration changed since the last deploy — never props alone.
+ *   This is the ONE family with a write path (Tim 2026-10-10, `policy.ts`); create/delete refuse.
  */
 import { Resource } from 'alchemy';
 import { adopt } from 'alchemy/AdoptPolicy';
@@ -24,9 +23,15 @@ import * as Provider from 'alchemy/Provider';
 import * as networks from '@distilled.cloud/unifi-network/networks';
 import * as Effect from 'effect/Effect';
 import { type NetworkAttributes, type NetworkProps, attributesOf } from './network-form.ts';
-import { matches } from './network-drift.ts';
+import { driftOf, matches } from './network-drift.ts';
+import { type ScopeError, checkNetworkWriteScope } from './network-scope.ts';
+import { writeNetwork } from './network-update.ts';
+import type { UnifiUpdateWouldBeNoop } from './policy.ts';
 import type { UnifiRequirements, UnifiSpec } from './resource.ts';
 import { unifiHandlers } from './resource.ts';
+import type { AllowedWrite } from './wire-guard.ts';
+
+type UpdateError = networks.UpdateNetworkError | UnifiUpdateWouldBeNoop | ScopeError;
 
 export type { NetworkAttributes, NetworkProps } from './network-form.ts';
 export { declareNetwork } from './network-form.ts';
@@ -48,10 +53,11 @@ export const UnifiNetwork = Resource<UnifiNetwork>('Unifi.Network', {
 });
 
 /**
- * `network('lan', props)` — `adopt(true)` piped on by default (H5). This family never writes, so
- * the only thing a first deploy against an existing network could ever do is bind to it or refuse
- * `OwnedBySomeoneElse`; piping `adopt(true)` here picks the former without a stack having to
- * remember `--adopt`, mirroring `discord/application-command.ts`'s `applicationCommand`.
+ * `network('lan', props)` — `adopt(true)` piped on by default (H5). A cold first deploy against an
+ * existing network can still only bind to it or refuse `OwnedBySomeoneElse` — the update path
+ * needs prior Alchemy state (`update-reconcile.ts`), so it cannot fire on adoption. Piping
+ * `adopt(true)` here picks the bind without a stack having to remember `--adopt`, mirroring
+ * `discord/application-command.ts`'s `applicationCommand`.
  */
 export const network = (id: string, props: NetworkProps) =>
   UnifiNetwork(id, props).pipe(adopt(true));
@@ -61,11 +67,42 @@ export const network = (id: string, props: NetworkProps) =>
  *   seam `netbox/prefix.ts`'s `spec` and `discord/application-command.ts`'s `spec` use — `handlers`
  *   bakes in `CredentialsFromEnv`, which resolves environment variables a test cannot repoint.
  */
+/**
+ * Every declarable key: `NetworkProps` minus the two identity ids. A test pins this against a
+ * fully-populated `NetworkProps` literal so a new prop cannot be silently unpatchable.
+ */
+export const NETWORK_PATCH_KEYS: ReadonlyArray<keyof NetworkProps> = [
+  'name',
+  'enabled',
+  'management',
+  'vlanId',
+  'dhcpGuarding',
+  'cellularBackupEnabled',
+  'internetAccessEnabled',
+  'ipv4Configuration',
+  'ipv6Configuration',
+  'isolationEnabled',
+  'mdnsForwardingEnabled',
+  'zoneId',
+  'deviceId',
+];
+
+/**
+ * The only PUT that may pass for this row: its own `/v1/sites/<siteId>/networks/<networkId>` under
+ * the configured base URL. ⛔ Built from the row's NEW props (the ids the write is about to use) and
+ * compared by exact string against the request path, so no id can act as a pattern.
+ */
+export const networkAllowedWrite = (props: NetworkProps): AllowedWrite => ({
+  method: 'PUT',
+  tail: `/v1/sites/${props.siteId}/networks/${props.networkId}`,
+});
+
 export const spec: UnifiSpec<
   NetworkProps,
   networks.NetworkDetails,
   NetworkAttributes,
-  networks.GetNetworkDetailsError
+  networks.GetNetworkDetailsError,
+  UpdateError
 > = {
   type: 'Unifi.Network',
   describe: (props) => `sites/${props.siteId}/networks/${props.networkId}`,
@@ -75,6 +112,13 @@ export const spec: UnifiSpec<
       .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   attributes: attributesOf,
   matches,
+  update: {
+    allowedWrite: networkAllowedWrite,
+    patchKeys: NETWORK_PATCH_KEYS,
+    driftOf,
+    checkScope: checkNetworkWriteScope,
+    write: writeNetwork,
+  },
 };
 
 export const handlers = unifiHandlers(spec);

package/src/unifi/policy.ts

@@ -1,12 +1,14 @@
 /**
- * The one refusal every `Unifi.*` write handler returns — never an SDK write call.
+ * The one refusal every refused `Unifi.*` write returns. The family makes exactly one SDK write
+ * call — `networks.updateNetwork`, through `network-update.ts` — and that is the only write that
+ * never sees this error.
  *
- * ⛔ TIM'S RULE, 2026-09-24: UniFi (and OPNsense) are READ-ONLY FOR NOW. This family has no
- *   `create`, no `update` body and no delete call anywhere in its source — `reconcile` and
- *   `delete` both fail with this typed error instead, and `resource.test.ts` proves the point
- *   with a fake `HttpClient` that fails the test on any request that is not a `GET`. Lifting the
- *   policy is a kit change (a new PR that adds a write path, reviewed as one), not a flag a stack
- *   can pass.
+ * ⛔ TIM'S RULE, 2026-09-24: UniFi (and OPNsense) are READ-ONLY. LIFTED FOR EXACTLY ONE CASE on
+ *   2026-10-10 (Tim): `Unifi.Network` update, through `update-reconcile.ts` + `network-update.ts`.
+ *   Every other write — create, delete, any other family's update — still fails with this typed
+ *   error, and `resource.test.ts`/`wire-guard.test.ts` prove it with a fake `HttpClient` that
+ *   records every request. Widening the policy again is a kit change (a new PR, reviewed as one),
+ *   not a flag a stack can pass.
  *
  * ★ A TYPED TAG, NOT A THROWN STRING (S21). `Effect.catchTag('UnifiWriteRefused', …)` lets a
  *   caller (a future import script, a test) branch on the refusal without parsing a message.
@@ -14,8 +16,14 @@
 import * as Data from 'effect/Data';
 import * as Effect from 'effect/Effect';
 
-export const UNIFI_READ_ONLY_POLICY =
-  "read-only by Tim's rule, 2026-09-24; lifting it is a kit change";
+export const UNIFI_WRITE_POLICY =
+  'UniFi is adopt-only except Unifi.Network update: one whole-object PUT built from the live ' +
+  'object plus the declared field changes, only on a row with prior Alchemy state, only through ' +
+  'deploy-approve; create/delete and every other family stay refused -- widening is a kit change ' +
+  '(Tim 2026-10-10 lifts the 2026-09-24 rule for this one case)';
+
+/** @deprecated renamed `UNIFI_WRITE_POLICY`; kept so existing consumer imports do not break. */
+export const UNIFI_READ_ONLY_POLICY = UNIFI_WRITE_POLICY;
 
 /** What kind of write was asked for and refused — for the message only, never acted on. */
 export type UnifiWriteAction = 'create' | 'update' | 'delete';
@@ -28,10 +36,120 @@ export class UnifiWriteRefused extends Data.TaggedError('UnifiWriteRefused')<{
   readonly action: UnifiWriteAction;
 }> {
   override get message(): string {
-    return `${this.type} ${this.identity}: refusing to ${this.action} -- ${UNIFI_READ_ONLY_POLICY}.`;
+    return `${this.type} ${this.identity}: refusing to ${this.action} -- ${UNIFI_WRITE_POLICY}.`;
   }
 }
 
 /** The only thing `reconcile`/`delete` ever return for a write this family cannot make. */
 export const refuseWrite = (type: string, identity: string, action: UnifiWriteAction) =>
   Effect.fail(new UnifiWriteRefused({ type, identity, action }));
+
+// ⛔ THE THREE ERRORS BELOW CARRY FIELD NAMES ONLY, NEVER VALUES: a network row holds addressing
+//   detail, and an error message reaches logs, CI bodies and pasted reports.
+const fieldList = (fields: ReadonlyArray<string>) => `[${fields.join(', ')}]`;
+
+/** Live no longer equals what the last deploy wrote: a hand edit is never overwritten. */
+export class UnifiLiveDriftedSinceDeploy extends Data.TaggedError('UnifiLiveDriftedSinceDeploy')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `${this.type} ${this.identity}: live differs from the last deployed state on ` +
+      `${fieldList(this.fields)}; refusing to PUT over it. Two causes look identical from here: a ` +
+      'hand edit on the console, or an earlier PUT that landed but did not converge ' +
+      '(UnifiUpdateDidNotConverge). Re-import the live object first.'
+    );
+  }
+}
+
+/** The merged body equals live: a PUT would change nothing (keeps a re-PUT loop impossible). */
+export class UnifiUpdateWouldBeNoop extends Data.TaggedError('UnifiUpdateWouldBeNoop')<{
+  readonly type: string;
+  readonly identity: string;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: the merged update body equals live; refusing a no-op PUT.`;
+  }
+}
+
+/** The PUT answered, yet the response still differs from the declaration. */
+export class UnifiUpdateDidNotConverge extends Data.TaggedError('UnifiUpdateDidNotConverge')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `${this.type} ${this.identity}: the PUT LANDED, but live now differs from the declaration on ` +
+      `${fieldList(this.fields)}. The change is on the console and is not rolled back; the next ` +
+      'deploy will see this as drift. Recovery is a re-import of the live object.'
+    );
+  }
+}
+
+// ⛔ THE FIVE ERRORS BELOW BOUND THE WRITE SCOPE (`network-scope.ts`, `update-reconcile.ts`): the
+//   one intended consumer is a single VLAN's `ipv6Configuration`. Field names only, as above.
+
+/** A patch would remove a key outside the removable allowlist (an omitted block is turned off). */
+export class UnifiFieldNotRemovable extends Data.TaggedError('UnifiFieldNotRemovable')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `${this.type} ${this.identity}: refusing to remove ${fieldList(this.fields)}; a whole-object ` +
+      'PUT turns an omitted block off, and only the removable allowlist may be dropped.'
+    );
+  }
+}
+
+/** A patch would SET a key outside the settable allowlist (only `ipv6Configuration` may be written). */
+export class UnifiFieldNotSettable extends Data.TaggedError('UnifiFieldNotSettable')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `${this.type} ${this.identity}: refusing to set ${fieldList(this.fields)}; this write path ` +
+      'only sets the settable allowlist (ipv6Configuration).'
+    );
+  }
+}
+
+/** The live object is the site's default (management) network: never written. */
+export class UnifiManagementNetworkRefused extends Data.TaggedError(
+  'UnifiManagementNetworkRefused',
+)<{
+  readonly type: string;
+  readonly identity: string;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: live is the default (management) network; refusing any write to it.`;
+  }
+}
+
+/** A patch changes a field that decides where the network lives or what serves it. */
+export class UnifiImmutableFieldChanged extends Data.TaggedError('UnifiImmutableFieldChanged')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: refusing to change ${fieldList(this.fields)}; those fields are never written.`;
+  }
+}
+
+/** `olds` and `news` name different objects: the prior state is no baseline for this write. */
+export class UnifiIdentityChanged extends Data.TaggedError('UnifiIdentityChanged')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly previous: string;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: the last deploy named ${this.previous}; refusing to PUT against another object.`;
+  }
+}

package/src/unifi/resource.test.ts

@@ -13,7 +13,12 @@ import { Unowned } from 'alchemy/AdoptPolicy';
 import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
 import * as Effect from 'effect/Effect';
 import { fakeUnifiLayer } from './fake-unifi.ts';
-import { UnifiWriteRefused } from './policy.ts';
+import {
+  type UnifiIdentityChanged,
+  type UnifiLiveDriftedSinceDeploy,
+  type UnifiUpdateDidNotConverge,
+  UnifiWriteRefused,
+} from './policy.ts';
 import { type UnifiSpec, unifiOperations } from './resource.ts';
 
 interface WidgetProps {
@@ -52,11 +57,18 @@ const run = <A, E>(effect: Effect.Effect<A, E, UnifiNetworkOpContext>) =>
   Effect.runPromise(effect.pipe(Effect.provide(fakeUnifiLayer(unreachableFetch))));
 
 const refusal = async (
-  effect: Effect.Effect<unknown, UnifiWriteRefused, UnifiNetworkOpContext>,
+  effect: Effect.Effect<
+    unknown,
+    | UnifiWriteRefused
+    | UnifiLiveDriftedSinceDeploy
+    | UnifiUpdateDidNotConverge
+    | UnifiIdentityChanged,
+    UnifiNetworkOpContext
+  >,
 ) => {
   const failure = await run(Effect.flip(effect));
   expect(failure).toBeInstanceOf(UnifiWriteRefused);
-  return failure;
+  return failure as UnifiWriteRefused;
 };
 
 describe('unifiOperations.readHandler', () => {