@homeflare/alchemy 0.56.0 → 0.58.0

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

@@ -8,81 +8,23 @@
  */
 import { describe, expect, test } from 'bun:test';
 import type * as networks from '@distilled.cloud/unifi-network/networks';
-import * as Retry from '@distilled.cloud/unifi-network/Retry';
-import * as Effect from 'effect/Effect';
-import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
-import { NETWORK_PATCH_KEYS, type NetworkProps, spec } from './network.ts';
+import { fakeFailure } from './fake-unifi.ts';
+import { NETWORK_PATCH_KEYS, type NetworkProps } from './network.ts';
+import {
+  BASE,
+  IPV6,
+  WITH_V6,
+  answering,
+  live,
+  putBody,
+  reconcile,
+} from './network-update.fixtures.ts';
 import { SERVER_FIELDS } from './network-update.ts';
 import {
   UnifiLiveDriftedSinceDeploy,
   UnifiUpdateDidNotConverge,
   UnifiWriteRefused,
 } from './policy.ts';
-import { unifiOperations } from './resource.ts';
-
-const PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
-const IPV6 = {
-  interfaceType: 'STATIC',
-  prefixLength: 64,
-  hostIpAddress: '2602:f660:0:16::254',
-  clientAddressAssignment: { slaacEnabled: true },
-  routerAdvertisement: { priority: 'HIGH' },
-};
-
-const BASE: NetworkProps = {
-  siteId: 'site-1',
-  networkId: 'net-1',
-  name: 'Compute',
-  enabled: true,
-  management: 'ADVANCED',
-  vlanId: 16,
-  dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1'] },
-  ipv4Configuration: { dhcpConfiguration: { mode: 'SERVER' }, hostIpAddress: '10.20.16.254' },
-};
-const WITH_V6 = { ...BASE, ipv6Configuration: IPV6 } as NetworkProps;
-
-/** Raw live object, with a key the SDK schema has never heard of. */
-const live = (extra: Record<string, unknown> = {}) => ({
-  id: 'net-1',
-  default: false,
-  metadata: { origin: 'USER' },
-  futureTopLevelKey: 'x',
-  ...BASE,
-  siteId: undefined,
-  networkId: undefined,
-  ...extra,
-});
-
-const reconcile = (
-  route: (method: string, url: URL) => Response,
-  news: NetworkProps,
-  olds: NetworkProps | undefined,
-  outputArg: object | null = {},
-) => {
-  const output = outputArg ?? undefined;
-  const fake = fakeUnifi(route);
-  const notes: string[] = [];
-  const run = unifiOperations(spec)
-    .reconcile(news, {
-      olds,
-      output,
-      note: (m) => Effect.sync(() => void notes.push(m)),
-    })
-    .pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch)));
-  return { fake, notes, exit: Effect.runPromiseExit(run) };
-};
-
-const answering =
-  (liveBody: object, put: () => Response = () => Response.json(liveBody)) =>
-  (method: string, url: URL) =>
-    url.pathname === PATH
-      ? method === 'GET'
-        ? Response.json(liveBody)
-        : put()
-      : fakeFailure(400, 'unexpected');
-
-const putBody = (seen: ReadonlyArray<{ method: string; body?: unknown }>) =>
-  seen.filter((s) => s.method === 'PUT').map((s) => s.body as Record<string, unknown>);
 
 describe('Unifi.Network update', () => {
   test('(1) one GET then one PUT: live carried through byte-equal, server fields dropped, patch added', async () => {

package/src/unifi/policy.ts

@@ -1,14 +1,17 @@
 /**
- * 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.
+ * The one refusal every refused `Unifi.*` write returns. The family makes exactly two SDK write
+ * calls — `networks.updateNetwork` (`network-update.ts`) and, as of the lift below,
+ * `firewall.createFirewallPolicy` (`firewall-policy-create.ts`) — and those are the only writes
+ * that do not see this error.
  *
- * ⛔ 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.
+ * ⛔ TIM'S RULE, 2026-09-24: UniFi (and OPNsense) are READ-ONLY. LIFTED FOR TWO CASES SINCE:
+ *   2026-10-10, `Unifi.Network` update, through `update-reconcile.ts` + `network-update.ts`; and
+ *   2026-10-19 ~16:20Z ("Allow kit to create hf: rules"), `Unifi.FirewallPolicy` CREATE, and ONLY
+ *   when the declared `name` starts `hf: ` (`isHfPolicyName` below). Every other write — every
+ *   other family's create, every update of an `hf:` row (or any other), every delete — still fails
+ *   with this typed error, and `resource.test.ts`/`wire-guard.test.ts`/`firewall-policy.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.
@@ -17,10 +20,22 @@ import * as Data from 'effect/Data';
 import * as Effect from 'effect/Effect';
 
 export const UNIFI_WRITE_POLICY =
-  'UniFi is adopt-only except Unifi.Network update: one whole-object PUT built from the live ' +
+  'UniFi is adopt-only except (1) 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)';
+  'deploy-approve; and (2) Unifi.FirewallPolicy create, only when the declared name starts "hf: ", ' +
+  'one POST built from only the declared fields, read back and checked to match after; every ' +
+  'other create, every update of an hf: row, every delete and every other family stay refused -- ' +
+  'widening is a kit change (Tim 2026-10-10 lifts the 2026-09-24 rule for Network update, Tim ' +
+  '2026-10-19 lifts it again for hf:-named FirewallPolicy create)';
+
+/**
+ * ⛔ THE ONE GATE THAT DECIDES "hf:" (Tim 2026-10-19, `nas-firewall`'s own naming:
+ *   `hf: CT100 to NAS https`). The space after the colon is deliberate and checked: `"hf:foo"`
+ *   (no space) is NOT an hf: name under this policy, so a typo can never silently slip past the
+ *   create gate by omitting it. Exported so `firewall-policy-create.ts`'s `checkScope` and every
+ *   test that proves the boundary use this ONE function, never a second regex hand-copied nearby.
+ */
+export const isHfPolicyName = (name: string): boolean => name.startsWith('hf: ');
 
 /** @deprecated renamed `UNIFI_WRITE_POLICY`; kept so existing consumer imports do not break. */
 export const UNIFI_READ_ONLY_POLICY = UNIFI_WRITE_POLICY;
@@ -89,6 +104,24 @@ export class UnifiUpdateDidNotConverge extends Data.TaggedError('UnifiUpdateDidN
   }
 }
 
+/** The POST answered, a read-back ran, yet the read-back object still differs from the
+ *  declaration — the hf: create path's own convergence check (`create-reconcile.ts`'s sibling in
+ *  `update-reconcile.ts`), same shape as `UnifiUpdateDidNotConverge` for the same reason: the
+ *  object now exists on the console, unrolled-back, so the operator needs to know and re-import. */
+export class UnifiCreateDidNotConverge extends Data.TaggedError('UnifiCreateDidNotConverge')<{
+  readonly type: string;
+  readonly identity: string;
+  readonly fields: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `${this.type} ${this.identity}: the POST created an object, but the read-back differs from ` +
+      `the declaration on ${fieldList(this.fields)}. The object 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.
 

package/src/unifi/resource.test.ts

@@ -14,10 +14,12 @@ import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Proto
 import * as Effect from 'effect/Effect';
 import { fakeUnifiLayer } from './fake-unifi.ts';
 import {
+  type UnifiCreateDidNotConverge,
   type UnifiIdentityChanged,
   type UnifiLiveDriftedSinceDeploy,
   type UnifiUpdateDidNotConverge,
   UnifiWriteRefused,
+  refuseWrite,
 } from './policy.ts';
 import { type UnifiSpec, unifiOperations } from './resource.ts';
 
@@ -62,6 +64,7 @@ const refusal = async (
     | UnifiWriteRefused
     | UnifiLiveDriftedSinceDeploy
     | UnifiUpdateDidNotConverge
+    | UnifiCreateDidNotConverge
     | UnifiIdentityChanged,
     UnifiNetworkOpContext
   >,
@@ -143,3 +146,103 @@ describe('unifiOperations.destroy', () => {
     expect(failure.action).toBe('delete');
   });
 });
+
+/**
+ * The generic `create` branch (`resource.ts`'s `reconcile`, `update-reconcile.ts`'s
+ * `createReconcile`), against a synthetic spec -- mirrors `specFor` above, but models a family
+ * that DOES declare `create`, the same way `firewall-policy.test.ts` proves the real one. Every
+ * assertion here is about the ENGINE's own gating (no prior state, live absent, `checkScope`
+ * passes before `write` ever runs); `firewall-policy.test.ts` separately proves the real hf: name
+ * check and the real POST body.
+ */
+/**
+ * `store` models "nothing live yet" (`undefined`) until `write` is called, at which point
+ * `fetchLive` (called again by `createReconcile`'s own read-back, never trusting `write`'s return
+ * value alone) starts answering the written row -- the same before/after a real `createFirewallPolicy`
+ * POST gives `getFirewallPolicy`.
+ */
+const specWithCreate = (
+  initiallyLive: WidgetLive | undefined,
+  opts: { allow: boolean; writeCalls: WidgetProps[]; writtenMismatch?: boolean },
+): UnifiSpec<WidgetProps, WidgetLive, WidgetAttrs, never, never, UnifiWriteRefused> => {
+  let store = initiallyLive;
+  return {
+    type: 'Test.Widget',
+    describe: (props) => `widgets/${props.id}`,
+    fetchLive: () => Effect.succeed(store),
+    attributes: (l) => l,
+    matches: (attrs, props) => attrs.value === props.value,
+    create: {
+      allowedWrite: () => ({ method: 'POST', tail: '/widgets' }),
+      checkScope: (props) =>
+        opts.allow ? Effect.void : refuseWrite('Test.Widget', `widgets/${props.id}`, 'create'),
+      write: (props) => {
+        opts.writeCalls.push(props);
+        store = { ...props, value: opts.writtenMismatch ? props.value + 1 : props.value };
+        return Effect.succeed(store);
+      },
+      identify: (props) => props,
+      driftOf: (liveNow, props) =>
+        liveNow.value === props.value
+          ? []
+          : [{ field: 'value', live: liveNow.value, declared: props.value }],
+    },
+  };
+};
+
+describe('unifiOperations.reconcile -- the create branch', () => {
+  test('no prior state, live absent, scope allows: one write call, reads back and matches', async () => {
+    const writeCalls: WidgetProps[] = [];
+    const spec = specWithCreate(undefined, { allow: true, writeCalls });
+    const attrs = await run(unifiOperations(spec).reconcile(MATCH));
+    expect(attrs).toEqual(MATCH);
+    expect(writeCalls).toEqual([MATCH]);
+  });
+
+  test('no prior state, live absent, scope refuses: zero write calls, typed refusal', async () => {
+    const writeCalls: WidgetProps[] = [];
+    const spec = specWithCreate(undefined, { allow: false, writeCalls });
+    const failure = await refusal(unifiOperations(spec).reconcile(MATCH));
+    expect(failure.action).toBe('create');
+    expect(writeCalls).toEqual([]);
+  });
+
+  test('a read-back mismatch after a successful create fails typed, not silently', async () => {
+    const writeCalls: WidgetProps[] = [];
+    const spec = specWithCreate(undefined, { allow: true, writeCalls, writtenMismatch: true });
+    const failure = await run(
+      Effect.flip(
+        unifiOperations(spec).reconcile(MATCH) as Effect.Effect<
+          unknown,
+          UnifiCreateDidNotConverge,
+          UnifiNetworkOpContext
+        >,
+      ),
+    );
+    expect(failure._tag).toBe('UnifiCreateDidNotConverge');
+    expect(writeCalls).toEqual([MATCH]);
+  });
+
+  test('live already exists (first deploy, no state, but a row matches): no create attempted', async () => {
+    const writeCalls: WidgetProps[] = [];
+    const spec = specWithCreate(MATCH, { allow: true, writeCalls });
+    const attrs = await run(unifiOperations(spec).reconcile(MATCH));
+    expect(attrs).toEqual(MATCH);
+    expect(writeCalls).toEqual([]); // exact match -- zero writes, same H6 guarantee as every other family
+  });
+
+  test('prior state present (olds/output set): create is never attempted even if live is absent', async () => {
+    const writeCalls: WidgetProps[] = [];
+    const spec = specWithCreate(undefined, { allow: true, writeCalls });
+    const failure = await refusal(
+      unifiOperations(spec).reconcile(MATCH, { olds: MATCH, output: MATCH }),
+    );
+    expect(failure.action).toBe('create'); // falls through to updateReconcile's own "create" refusal
+    expect(writeCalls).toEqual([]);
+  });
+
+  test('a family with no create block behaves exactly as before (back-compat)', async () => {
+    const failure = await refusal(unifiOperations(specFor(undefined)).reconcile(MATCH));
+    expect(failure.action).toBe('create');
+  });
+});

package/src/unifi/resource.ts

@@ -9,11 +9,15 @@
  *   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 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.
+ * ⛔ THE POSTURE (`policy.ts`, Tim 2026-09-24, lifted for TWO cases since): there is no `destroy`
+ *   in this spec at all, ever. `update` exists only when a spec carries an `update` block
+ *   (`update-reconcile.ts`'s `updateReconcile`, `Unifi.Network` only). `create` exists only when a
+ *   spec carries a `create` block (`update-reconcile.ts`'s `createReconcile`, `Unifi.FirewallPolicy`
+ *   only, and only for a row whose declared name passes `create.checkScope`). `reconcile`: an exact
+ *   match reports with zero writes; otherwise a family with `create` and no prior state (`olds`/
+ *   `output` both absent) AND an absent live read attempts the create branch; everything else
+ *   either refuses or runs the three-way PUT. A spec with neither block 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.81` (`forceUpdateAfterAdoption`, H6): beta.81 forces
@@ -42,7 +46,13 @@ import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Proto
 import * as Effect from 'effect/Effect';
 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 ReconcileArgs,
+  type UnifiCreate,
+  type UnifiUpdate,
+  createReconcile,
+  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. */
@@ -54,7 +64,14 @@ export type UnifiRequirements = HttpClient.HttpClient;
  * union, with `NotFound` already folded away) so the precise per-operation error union flows
  * 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, E2 = never> = {
+export type UnifiSpec<
+  Props extends object,
+  Live,
+  Attributes extends object,
+  E,
+  E2 = never,
+  E3 = 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). */
@@ -65,10 +82,13 @@ export type UnifiSpec<Props extends object, Live, Attributes extends object, E,
   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>;
+  /** Present only on a family allowed to create (`Unifi.FirewallPolicy`, `hf:` rows only); see
+   *  `update-reconcile.ts`'s `createReconcile`. */
+  readonly create?: UnifiCreate<Props, Live, E3>;
 };
 
-export const unifiOperations = <Props extends object, Live, Attributes extends object, E, E2>(
-  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
+export const unifiOperations = <Props extends object, Live, Attributes extends object, E, E2, E3>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2, E3>,
 ) => {
   const read = (props: Props) =>
     spec
@@ -98,14 +118,36 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
           : ({ action: 'update' } as const);
       }),
 
-    /** 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),
-      }),
+    /**
+     * Pre-state callers (tests, adopt-only probes) pass just `news`: `olds`/`output` unset — the
+     * SAME calling convention a plain cold adoption already uses (H6), so the existence GET must
+     * run FIRST, for every name, exactly as it always has: a row that already exists is adopted
+     * (exact match, zero writes) regardless of its name, and ONLY an absent row ever reaches
+     * `create.checkScope`. "A non-hf: create sends nothing" therefore means no WRITE (no
+     * POST/PUT/DELETE) — the same guarantee every other refusal in this engine gives, and the one
+     * `wire-guard.ts`'s allow list enforces at the wire; the existence GET is not a write.
+     *
+     * ⛔ THE CREATE BRANCH ONLY RUNS WHEN THERE IS NO PRIOR STATE AT ALL (`olds`/`output` both
+     *   absent — a genuine first deploy, never a re-declare of an adopted row) AND the family
+     *   declares `create` AND the live read comes back absent. A row that already exists (someone
+     *   else's object with a colliding identity, or a retried deploy that already created it)
+     *   takes the ordinary `updateReconcile` path instead — exact match reports with zero writes,
+     *   anything else refuses (there is no `olds` to PUT a patch against, so it can never silently
+     *   fall through to an update of an existing row).
+     */
+    reconcile: (news: Props, rest: Partial<Omit<ReconcileArgs<Props>, 'news'>> = {}) => {
+      const note = rest.note ?? (() => Effect.void);
+      const create = spec.create;
+      if (create !== undefined && rest.olds === undefined && rest.output === undefined) {
+        return Effect.gen(function* () {
+          const live = yield* spec.fetchLive(news);
+          return live === undefined
+            ? yield* createReconcile(spec, news, note)
+            : yield* updateReconcile(spec, { news, olds: undefined, output: undefined, note });
+        });
+      }
+      return updateReconcile(spec, { news, olds: rest.olds, output: rest.output, note });
+    },
 
     destroy: (olds: Props) => refuseWrite(spec.type, spec.describe(olds), 'delete'),
   };
@@ -117,8 +159,8 @@ export const unifiOperations = <Props extends object, Live, Attributes extends o
  * ⛔ `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, E2>(
-  spec: UnifiSpec<Props, Live, Attributes, E, E2>,
+export const unifiHandlers = <Props extends object, Live, Attributes extends object, E, E2, E3>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2, E3>,
 ) => {
   const ops = unifiOperations(spec);
   const withCredentials = <A, Err>(
@@ -152,8 +194,18 @@ export const unifiHandlers = <Props extends object, Live, Attributes extends obj
           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)] : [],
+        //   `olds` names another object (`update-reconcile.ts`). The create entry (a POST to the
+        //   site's fixed collection route, never a per-row path) is listed ONLY when there is no
+        //   prior state at all — the exact same condition `ops.reconcile` itself gates the create
+        //   branch on, so the wire guard never allows a POST wider than what the engine could ever
+        //   attempt. The hf: NAME check is NOT this list's job (`create.checkScope`'s, before the
+        //   POST): this only bounds METHOD and PATH.
+        [
+          ...(spec.update ? [spec.update.allowedWrite(args.news)] : []),
+          ...(spec.create && args.olds === undefined && args.output === undefined
+            ? [spec.create.allowedWrite(args.news)]
+            : []),
+        ],
       ),
     delete: (args: { olds: Props }) => withCredentials(ops.destroy(args.olds)),
   };

package/src/unifi/update-reconcile.ts

@@ -29,6 +29,7 @@ import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Proto
 import * as Effect from 'effect/Effect';
 import type { FieldDrift } from './drift.ts';
 import {
+  UnifiCreateDidNotConverge,
   UnifiIdentityChanged,
   UnifiLiveDriftedSinceDeploy,
   UnifiUpdateDidNotConverge,
@@ -71,6 +72,21 @@ export const computePatch = <Props extends object>(
   return { set, unset };
 };
 
+/** `olds` with each accepted field taken from `news` (which equals live there), so the patch
+ *  skips it. A `FieldDrift.field` names a props key; one that is not is left alone. */
+const acceptInto = <Props extends object>(
+  olds: Props,
+  news: Props,
+  accepted: ReadonlyArray<unknown>,
+): Props => {
+  const next: Record<string, unknown> = { ...(olds as Record<string, unknown>) };
+  for (const field of accepted) {
+    const key = String(field);
+    if (key in (news as object) || key in next) next[key] = (news as Record<string, unknown>)[key];
+  }
+  return next as Props;
+};
+
 export type ReconcileArgs<Props extends object> = {
   readonly news: Props;
   readonly olds: Props | undefined;
@@ -78,8 +94,8 @@ export type ReconcileArgs<Props extends object> = {
   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>,
+export const updateReconcile = <Props extends object, Live, Attributes extends object, E, E2, E3>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2, E3>,
   { news, olds, output, note }: ReconcileArgs<Props>,
 ) =>
   Effect.gen(function* () {
@@ -98,15 +114,34 @@ export const updateReconcile = <Props extends object, Live, Attributes extends o
     if (previous !== identity) {
       return yield* new UnifiIdentityChanged({ type: spec.type, identity, previous });
     }
+    // ★ A FIELD THAT DRIFTED SINCE THE LAST DEPLOY IS A CONFLICT ONLY IF THE DECLARATION STILL
+    //   DISAGREES WITH LIVE ON IT. When the declaration already equals live there (a re-import
+    //   recorded the console edit, the documented recovery for UnifiLiveDriftedSinceDeploy),
+    //   the edit is ACCEPTED: folded into the baseline, so it is neither refused nor patched. The
+    //   PUT is live plus the patch, so live's value survives untouched. Without this, `olds`
+    //   (the last deployed state) only moves on a successful deploy, so a re-import could never
+    //   clear the refusal (homeflare-network VLAN 16, 2026-10-19: mdnsForwardingEnabled edited on
+    //   the console, re-imported, and still refused on every deploy).
+    // ⛔ A drifted field the declaration DISAGREES with stays a refusal: the PUT would overwrite
+    //   a hand edit nobody re-imported.
+    const disagrees = new Set(update.driftOf(live, news).map((d) => String(d.field)));
     const drifted = update.driftOf(live, olds).map((d) => d.field);
-    if (drifted.length > 0) {
+    const conflicts = drifted.filter((field) => disagrees.has(String(field)));
+    if (conflicts.length > 0) {
       return yield* new UnifiLiveDriftedSinceDeploy({
         type: spec.type,
         identity,
-        fields: drifted,
+        fields: conflicts,
       });
     }
-    const patch = computePatch(news, olds, update.patchKeys);
+    const accepted = drifted.filter((field) => !disagrees.has(String(field)));
+    const baseline = acceptInto(olds, news, accepted);
+    if (accepted.length > 0) {
+      yield* note(
+        `${spec.type} ${identity}: live edits since the last deploy already match the declaration, accepted: [${accepted.map(String).join(', ')}]`,
+      );
+    }
+    const patch = computePatch(news, baseline, update.patchKeys);
     if (Object.keys(patch.set).length === 0 && patch.unset.length === 0) {
       return yield* refuseWrite(spec.type, identity, 'update');
     }
@@ -124,3 +159,72 @@ export const updateReconcile = <Props extends object, Live, Attributes extends o
       fields: update.driftOf(written, news).map((d) => d.field),
     });
   });
+
+/**
+ * The write half of a CREATE-capable family: today, only `Unifi.FirewallPolicy`, and only for an
+ * `hf:`-named row (`policy.ts`'s `isHfPolicyName`). Deliberately NOT a merge-with-live update —
+ * there is no live object yet — so there is no `patchKeys`/`checkScope(live, patch, …)` here: a
+ * create sends exactly the fields the declaration owns, nothing echoed from elsewhere, nothing to
+ * accidentally reset.
+ *
+ * ⛔ `checkScope` RUNS BEFORE THE POST (same ordering `update.checkScope` already has): a
+ *   non-`hf:` name is refused here, typed, never reaching the wire at all.
+ * ★ `identify` CLOSES THE LOOP FROM THE POST'S RESPONSE TO A FRESH GET. The vendor assigns the id
+ *   on create; `write`'s response carries it, but a response body is not proof the object is
+ *   actually readable back (`createReconcile` re-fetches with the id `identify` folds in, rather
+ *   than trusting the POST's own echo — same reasoning `network-update.ts`'s header gives for
+ *   never trusting a write's own response over a real read).
+ */
+export type UnifiCreate<Props extends object, Live, E3> = {
+  /** The one POST the wire guard may pass for this family (the site's fixed collection route,
+   *  built from `props` the same way `UnifiUpdate.allowedWrite` reads a row's ids from `props`). */
+  readonly allowedWrite: (props: Props) => AllowedWrite;
+  /** Refuses (typed, before any note or request) a create outside this family's write scope. */
+  readonly checkScope: (props: Props) => Effect.Effect<void, E3>;
+  readonly write: (props: Props) => Effect.Effect<Live, E3, UnifiNetworkOpContext>;
+  /** `props` plus the vendor id the POST's response assigned, for the read-back `fetchLive`. */
+  readonly identify: (props: Props, written: Live) => Props;
+  readonly driftOf: (live: Live, props: Props) => ReadonlyArray<FieldDrift>;
+};
+
+/**
+ * CREATE for a family whose live read came back absent AND which has no prior Alchemy state
+ * (`resource.ts`'s `unifiOperations.reconcile` is the only caller, and only under that same
+ * condition — see its own header). Refuses (untyped-to-typed, same `refuseWrite` every other
+ * refusal uses) when the family declares no `create` at all; `create.checkScope` then refuses
+ * again, more specifically, for a declared row the create scope itself does not allow.
+ */
+export const createReconcile = <Props extends object, Live, Attributes extends object, E, E2, E3>(
+  spec: UnifiSpec<Props, Live, Attributes, E, E2, E3>,
+  news: Props,
+  note: (message: string) => Effect.Effect<void, never, never>,
+) =>
+  Effect.gen(function* () {
+    const identity = spec.describe(news);
+    const create = spec.create;
+    if (create === undefined) return yield* refuseWrite(spec.type, identity, 'create');
+    yield* create.checkScope(news);
+    yield* note(`${spec.type} ${identity}: POST create`);
+    const written = yield* create.write(news);
+    const withId = create.identify(news, written);
+    // ⛔ A FRESH GET, NOT THE POST'S OWN RESPONSE (see the header): `fetchLive` is the same read
+    //   every adoption and every later plan uses, so the convergence check and every future read
+    //   of this row go through one path.
+    const confirmed = yield* spec.fetchLive(withId);
+    if (confirmed === undefined) {
+      return yield* Effect.die(
+        new Error(
+          `${spec.type} ${identity}: the create POST answered, but the read-back found nothing ` +
+            'at the id it assigned. The object may or may not exist on the console; re-import ' +
+            'before trying again rather than retrying this create blindly.',
+        ),
+      );
+    }
+    const attrs = spec.attributes(confirmed, withId);
+    if (spec.matches(attrs, withId)) return attrs;
+    return yield* new UnifiCreateDidNotConverge({
+      type: spec.type,
+      identity,
+      fields: create.driftOf(confirmed, withId).map((d) => d.field),
+    });
+  });