@homeflare/alchemy 0.50.0 → 0.52.0

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', () => {

package/src/unifi/resource.ts

@@ -1,28 +1,27 @@
 /**
- * One shape for every UniFi Network read-only object — `Unifi.Network`, `Unifi.FirewallZone`,
- * and whatever import adds next.
+ * One shape for every UniFi Network object — `Unifi.Network`, `Unifi.FirewallZone`, and whatever
+ * import adds next. ADOPT-ONLY, except the one `update` a spec may opt into (`Unifi.Network`).
  *
  * ★ MIRRORS `../discord/resource.ts` (S7-S10, H1, H5), NOT `../netbox/resource.ts`. Both are
  *   "marker-less API" families (S8): UniFi Network objects carry no tag or metadata field this
  *   stack could stamp as ownership, so a cold read of a match is `Unowned(attrs)` exactly like
- *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.79#read`, the reference implementation S8 and H1
+ *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.81#read`, the reference implementation S8 and H1
  *   both cite. `adopt(true)`, piped on by each resource's convenience constructor (H5), turns
  *   that into a silent one-time bind instead of an `OwnedBySomeoneElse` refusal.
  *
- * ⛔ THE DIFFERENCE FROM EVERY OTHER FAMILY HERE: THERE IS NO `create`, `update` OR `destroy` IN
- *   THIS SPEC AT ALL. Tim's rule, 2026-09-24 (`policy.ts`): UniFi and OPNsense are read-only. So
- *   `reconcile` below can only ever refuse or report an exact match — it has no write path to
- *   fall into by accident, and no resource file wired through this engine can reach one either.
+ * ⛔ THE POSTURE (`policy.ts`, Tim 2026-09-24, lifted for ONE case 2026-10-10): there is no
+ *   `create` and no `destroy` in this spec at all, and `update` exists only when a spec carries an
+ *   `update` block (`update-reconcile.ts`). `reconcile` is `updateReconcile`: refuse a create,
+ *   report an exact match with zero writes, and otherwise either refuse or run the three-way PUT.
+ *   A spec without `update` (every family but Network) can only ever refuse or report a match.
  *
  * ⚠️ RECONCILE STILL HAS TO SUCCEED ON AN EXACT-MATCH ADOPTION, NOT JUST REFUSE UNCONDITIONALLY.
- *   Measured against `Plan.ts@v2.0.0-beta.79` (`forceUpdateAfterAdoption`, H6): beta.79 forces
+ *   Measured against `Plan.ts@v2.0.0-beta.81` (`forceUpdateAfterAdoption`, H6): beta.81 forces
  *   ONE reconcile call after every cold adoption, whether or not the diff said noop — so a
  *   resource whose `reconcile` always failed would break the ordinary "adopt an unchanged
  *   object" deploy, not just a real write. The fix, exactly like `discordOperations.reconcile`:
- *   read the live object again, and refuse ONLY when it is missing (would need a create) or
- *   drifted (would need a write to converge). An exact match returns the live attributes and
- *   calls nothing — S10's "zero write calls when there is no drift" holds even under the forced
- *   post-adoption call.
+ *   read the live object again and return it on a match. S10's "zero write calls when there is
+ *   no drift" holds even under the forced post-adoption call.
  *
  * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE —
  *   same split netbox's `resource.ts` uses and for the same reason: `Effect.catchTag`'s
@@ -30,15 +29,21 @@
  *   spec's `E` is only concrete at each resource file's own call site. Every OTHER failure (a
  *   real 5xx, a network error, `Forbidden`) is NOT folded anywhere — it fails the plan loudly,
  *   per the task's own rule: only a genuine not-found may mean absent.
+ *
+ * ★ The wire guard (`wire-guard.ts`) and the three-way reconcile (`update-reconcile.ts`) live in
+ *   their own files; `read`/`diff`/`delete` run under `GetOnlyHttpClient`, only `reconcile` gets
+ *   the per-row allow entry of a spec that declares `update`.
  */
 import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
-import { CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
+import { Credentials, CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
 import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
 import * as Effect from 'effect/Effect';
-import * as HttpClient from 'effect/http/HttpClient';
-import { UNIFI_READ_ONLY_POLICY, refuseWrite } from './policy.ts';
+import type * as HttpClient from 'effect/http/HttpClient';
+import { refuseWrite } from './policy.ts';
+import { type ReconcileArgs, type UnifiUpdate, updateReconcile } from './update-reconcile.ts';
+import { type AllowedWrite, guardedHttpClient } from './wire-guard.ts';
 
 /** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
 export type UnifiRequirements = HttpClient.HttpClient;
@@ -47,9 +52,9 @@ export type UnifiRequirements = HttpClient.HttpClient;
  * One UniFi Network object's read. `Live` is whatever the SDK decodes (a `NetworkDetails`, a
  * `FirewallZone`, …); `E` is left to each resource file to declare (its own `fetchLive`'s error
  * union, with `NotFound` already folded away) so the precise per-operation error union flows
- * through instead of being widened by hand here.
+ * through instead of being widened by hand here. `E2` is the error union of the optional write.
  */
-export type UnifiSpec<Props extends object, Live, Attributes extends object, E> = {
+export type UnifiSpec<Props extends object, Live, Attributes extends object, E, E2 = never> = {
   /** The vendor type string, e.g. `Unifi.Network` — for the refusal message only. */
   readonly type: string;
   /** Already folds a genuine not-found to `undefined`; nothing else is folded (see header). */
@@ -58,10 +63,12 @@ export type UnifiSpec<Props extends object, Live, Attributes extends object, E>
   readonly matches: (attributes: Attributes, props: Props) => boolean;
   /** For the refusal message and read-back failures. */
   readonly describe: (props: Props) => string;
+  /** Present only on a family allowed to write (`Unifi.Network`); see `update-reconcile.ts`. */
+  readonly update?: UnifiUpdate<Props, Live, E2>;
 };
 
-export const unifiOperations = <Props extends object, Live, Attributes extends object, E>(
-  spec: UnifiSpec<Props, Live, Attributes, E>,
+export const unifiOperations = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
 ) => {
   const read = (props: Props) =>
     spec
@@ -91,16 +98,13 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
           : ({ action: 'update' } as const);
       }),
 
-    reconcile: (news: Props) =>
-      Effect.gen(function* () {
-        const live = yield* read(news);
-        if (live === undefined) return yield* refuseWrite(spec.type, spec.describe(news), 'create');
-        if (!spec.matches(live, news)) {
-          return yield* refuseWrite(spec.type, spec.describe(news), 'update');
-        }
-        // Exact match: the object already is what is declared. Zero write calls (S10), correct
-        // whether this is a routine deploy or beta.79's forced post-adoption reconcile (H6).
-        return live;
+    /** Pre-state callers (tests, adopt-only probes) pass just `news`: `olds`/`output` unset. */
+    reconcile: (news: Props, rest: Partial<Omit<ReconcileArgs<Props>, 'news'>> = {}) =>
+      updateReconcile(spec, {
+        news,
+        olds: rest.olds,
+        output: rest.output,
+        note: rest.note ?? (() => Effect.void),
       }),
 
     destroy: (olds: Props) => refuseWrite(spec.type, spec.describe(olds), 'delete'),
@@ -108,94 +112,49 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
 };
 
 /**
- * B0a / T12 DEFENSE IN DEPTH. `policy.ts`'s `UnifiWriteRefused` stops write INTENT at
- * `reconcile`/`destroy` — every path this engine exposes already returns that refusal instead of
- * calling an SDK write op. This guard stops the same thing one layer lower, AT THE WIRE: it wraps
- * whatever `HttpClient` the caller already provides (the stack's `FetchHttpClient.layer` in
- * production, `fakeUnifiLayer` in tests — `openbao/bao-http.ts`'s header names this same
- * "wrap, don't replace" seam) so a future resource file that, by mistake, called an SDK write
- * operation directly — bypassing `unifiOperations` entirely — would still never reach the vendor
- * API. `write-op-reference.test.ts` proves no such call exists today; this is what stops one from
- * ever taking effect if one is ever added.
- *
- * ⚠️ `Effect.die`, NOT A TYPED FAILURE — classified per distilled-doctrine's "classify every
- *   die/orDie". Every generated SDK operation (`networks.getNetworkDetails`, …) declares its OWN
- *   closed error union from the pinned OpenAPI spec, and generated files are never hand-edited to
- *   add a member to it. A typed `Effect.fail` here would be a failure mode absent from every op's
- *   declared type the moment it occurred — a type-system lie. A defect is the sound way to add a
- *   NEW "this must be structurally impossible" failure underneath types this package does not
- *   own, exactly like `openbao`'s `refuse()` helpers' `Effect.die(new Error(...))` for a
- *   configuration move that should never be reachable.
- */
-export class UnifiNonGetRequest extends Error {
-  constructor(
-    readonly method: string,
-    /** PATH ONLY, never the full URL — see `requestPath` below. */
-    readonly path: string,
-  ) {
-    super(
-      `UniFi HttpClient guard: refused ${method} ${path} -- ${UNIFI_READ_ONLY_POLICY}. This is a ` +
-        'defect, not a recoverable condition: something under src/unifi tried to send a non-GET ' +
-        "request, which policy.ts's per-operation refusal should already have made impossible. " +
-        'Fix the kit code that produced this request.',
-    );
-    this.name = 'UnifiNonGetRequest';
-  }
-}
-
-/**
- * ⛔ PATH ONLY, NEVER THE HOST. A cloud connector's base URL embeds the account's Console ID
- *   (`docs/unifi.md`'s Credentials section, T3) — a defect message is still a message that can
- *   reach a log, a CI failure body or a pasted error report, so it gets the same treatment as
- *   `redactUrls` gives the import layer's own error text. Falls back to a fixed placeholder rather
- *   than the raw string on a parse failure, so a malformed URL can never leak through unredacted.
- */
-const requestPath = (url: string): string => {
-  try {
-    return new URL(url).pathname;
-  } catch {
-    return '<unparseable request url>';
-  }
-};
-
-const guardGetOnly = (client: HttpClient.HttpClient): HttpClient.HttpClient =>
-  client.pipe(
-    HttpClient.mapRequestEffect((request) =>
-      request.method === 'GET'
-        ? Effect.succeed(request)
-        : Effect.die(new UnifiNonGetRequest(request.method, requestPath(request.url))),
-    ),
-  );
-
-/**
- * A `Layer` that reads whatever `HttpClient` is already in the calling context and replaces it,
- * for everything downstream, with `guardGetOnly`'s wrapped version (`HttpClient.layerMergedContext`
- * — see the guard above). Exported so `get-only-guard.test.ts` can prove the mechanism directly,
- * against a bare `HttpClient` service, without needing `CredentialsFromEnv` or any env var at all.
- */
-export const GetOnlyHttpClient = HttpClient.layerMergedContext(
-  Effect.map(HttpClient.HttpClient, guardGetOnly),
-);
-
-/**
- * The four provider handlers for a spec'd read-only UniFi object, wired once.
+ * The four provider handlers for a spec'd UniFi object, wired once.
  *
  * ⛔ `list` ANSWERS EMPTY. `GET /v1/sites/{siteId}/networks` answers every network on the site;
  *   adoption stays explicit, the same reasoning `Proxmox.User`'s and NetBox's `list` give.
  */
-export const unifiHandlers = <Props extends object, Live, Attributes extends object, E>(
-  spec: UnifiSpec<Props, Live, Attributes, E>,
+export const unifiHandlers = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
 ) => {
   const ops = unifiOperations(spec);
-  const withCredentials = <A, Err>(effect: Effect.Effect<A, Err, UnifiNetworkOpContext>) =>
-    effect.pipe(Effect.provide(GetOnlyHttpClient), Effect.provide(CredentialsFromEnv));
+  const withCredentials = <A, Err>(
+    effect: Effect.Effect<A, Err, UnifiNetworkOpContext>,
+    allow: ReadonlyArray<AllowedWrite> = [],
+  ) =>
+    Effect.gen(function* () {
+      // ⛔ The guard anchors the allowed PUT to the CONFIGURED base URL (`wire-guard.ts`), so it is
+      //   read from the same credentials the SDK uses.
+      const { apiBaseUrl } = yield* yield* Credentials;
+      return yield* effect.pipe(Effect.provide(guardedHttpClient(allow, apiBaseUrl)));
+    }).pipe(Effect.provide(CredentialsFromEnv)) as Effect.Effect<A, Err, HttpClient.HttpClient>;
+
   return {
     list: () => Effect.succeed([]),
     read: (args: { olds: Props; output: Attributes | undefined }) =>
       withCredentials(ops.readHandler(args)),
     diff: (args: { news: Input<Props>; output: Attributes | undefined }) =>
       withCredentials(ops.diff(args.news, args.output)),
-    reconcile: (args: { news: Props }) => withCredentials(ops.reconcile(args.news)),
+    // ⛔ ONLY `reconcile` gets the per-row allow entry, and only when the spec declares `update`.
+    reconcile: (args: {
+      news: Props;
+      olds: Props | undefined;
+      output: Attributes | undefined;
+      session: { note: (message: string) => Effect.Effect<void, never, never> };
+    }) =>
+      withCredentials(
+        ops.reconcile(args.news, {
+          olds: args.olds,
+          output: args.output,
+          note: (message) => args.session.note(message),
+        }),
+        // ⛔ From `news` (the ids the write will use), never `olds`; reconcile also refuses when
+        //   `olds` names another object (`update-reconcile.ts`).
+        spec.update ? [spec.update.allowedWrite(args.news)] : [],
+      ),
     delete: (args: { olds: Props }) => withCredentials(ops.destroy(args.olds)),
   };
 };

package/src/unifi/update-reconcile.ts

@@ -0,0 +1,126 @@
+/**
+ * The three-way `reconcile` every updatable `Unifi.*` family shares (today: `Unifi.Network`).
+ *
+ * ⛔ THREE INPUTS, NOT TWO. `news` is the declaration now, `olds` is the declaration the LAST
+ *   DEPLOY wrote (Alchemy state), `live` is the raw object read right now. The PUT body is built
+ *   from `live` plus ONLY the fields where `news` differs from `olds` (`computePatch`) — never
+ *   from `news` alone. So (HIGH-2) a hand edit on a field the declaration never touched is carried
+ *   through unchanged instead of reverted, and a hand edit on ANY declared field is refused
+ *   outright (step 4) rather than overwritten.
+ *
+ * ★ `unset` IS WHAT MAKES A REVERT REAL (HIGH-1). Deleting an override from a declaration makes
+ *   `news[k]` absent while `olds[k]` is set; a patch that only carried `set` would see "nothing
+ *   changed" and the revert would never write. A key present in `olds` and null/absent in `news`
+ *   lands in `unset`, and the family's `write` removes it from the body.
+ *
+ * ⛔ FIRST DEPLOY IS ADOPT-ONLY BY CONSTRUCTION (F1, LOW-8). Without BOTH `olds` and `output` there
+ *   is no last-deployed baseline to patch against, so the write refuses. That also covers beta.81's
+ *   forced post-adoption reconcile (H6): on a match (step 2) it returns live with zero writes.
+ *   `olds` must also name the SAME object as `news` (`UnifiIdentityChanged`).
+ *
+ * ⛔ SCOPE (`update.checkScope`) runs before the note and any request: the family decides what a
+ *   patch may touch (`network-scope.ts`). An omitted optional block is turned OFF by a whole-object
+ *   PUT, so removing a key is allowed only for an explicit allowlist.
+ *
+ * ⚠️ NOTES AND ERRORS CARRY FIELD NAMES ONLY, NEVER VALUES.
+ */
+import { deepEqual } from 'alchemy/Diff';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import type { FieldDrift } from './drift.ts';
+import {
+  UnifiIdentityChanged,
+  UnifiLiveDriftedSinceDeploy,
+  UnifiUpdateDidNotConverge,
+  refuseWrite,
+} from './policy.ts';
+import type { UnifiSpec } from './resource.ts';
+import type { AllowedWrite } from './wire-guard.ts';
+
+export type Patch<Props> = { set: Partial<Props>; unset: ReadonlyArray<keyof Props> };
+
+/** The write half of a spec: everything needed to PUT one object, and nothing to create/delete. */
+export type UnifiUpdate<Props extends object, Live, E2> = {
+  /** The one PUT the wire guard may pass for this row (path pinned to the row's own ids). */
+  readonly allowedWrite: (props: Props) => AllowedWrite;
+  /** Declarable keys; never the identity keys. */
+  readonly patchKeys: ReadonlyArray<keyof Props>;
+  readonly driftOf: (live: Live, props: Props) => ReadonlyArray<FieldDrift>;
+  /** Refuses (typed, before any note or request) a patch outside this family's write scope. */
+  readonly checkScope: (live: Live, patch: Patch<Props>, props: Props) => Effect.Effect<void, E2>;
+  readonly write: (
+    live: Live,
+    patch: Patch<Props>,
+    props: Props,
+  ) => Effect.Effect<Live, E2, UnifiNetworkOpContext>;
+};
+
+/** Keys whose `news` value differs from `olds`: set when still declared, unset when dropped. */
+export const computePatch = <Props extends object>(
+  news: Props,
+  olds: Props,
+  patchKeys: ReadonlyArray<keyof Props>,
+): Patch<Props> => {
+  const set: Partial<Props> = {};
+  const unset: Array<keyof Props> = [];
+  for (const key of patchKeys) {
+    if (deepEqual(news[key], olds[key], { stripNullish: true })) continue;
+    if (news[key] == null) unset.push(key);
+    else set[key] = news[key];
+  }
+  return { set, unset };
+};
+
+export type ReconcileArgs<Props extends object> = {
+  readonly news: Props;
+  readonly olds: Props | undefined;
+  readonly output: unknown;
+  readonly note: (message: string) => Effect.Effect<void>;
+};
+
+export const updateReconcile = <Props extends object, Live, Attributes extends object, E, E2>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
+  { news, olds, output, note }: ReconcileArgs<Props>,
+) =>
+  Effect.gen(function* () {
+    const identity = spec.describe(news);
+    const live = yield* spec.fetchLive(news);
+    if (live === undefined) return yield* refuseWrite(spec.type, identity, 'create');
+    const attrs = spec.attributes(live, news);
+    // Exact match: zero writes, correct for a routine deploy and the forced post-adoption call.
+    if (spec.matches(attrs, news)) return attrs;
+    const update = spec.update;
+    if (update === undefined || olds === undefined || output === undefined) {
+      return yield* refuseWrite(spec.type, identity, 'update');
+    }
+    // ⛔ `olds` is the baseline for THIS object only; another site or network id is no baseline.
+    const previous = spec.describe(olds);
+    if (previous !== identity) {
+      return yield* new UnifiIdentityChanged({ type: spec.type, identity, previous });
+    }
+    const drifted = update.driftOf(live, olds).map((d) => d.field);
+    if (drifted.length > 0) {
+      return yield* new UnifiLiveDriftedSinceDeploy({
+        type: spec.type,
+        identity,
+        fields: drifted,
+      });
+    }
+    const patch = computePatch(news, olds, update.patchKeys);
+    if (Object.keys(patch.set).length === 0 && patch.unset.length === 0) {
+      return yield* refuseWrite(spec.type, identity, 'update');
+    }
+    yield* update.checkScope(live, patch, news);
+    yield* note(
+      `${spec.type} ${identity}: PUT changes [${Object.keys(patch.set).join(', ')}] ` +
+        `removes [${patch.unset.map(String).join(', ')}]`,
+    );
+    const written = yield* update.write(live, patch, news);
+    const writtenAttrs = spec.attributes(written, news);
+    if (spec.matches(writtenAttrs, news)) return writtenAttrs;
+    return yield* new UnifiUpdateDidNotConverge({
+      type: spec.type,
+      identity,
+      fields: update.driftOf(written, news).map((d) => d.field),
+    });
+  });