@homeflare/alchemy 0.56.0 → 0.57.0

package/src/unifi/firewall-policy.ts

@@ -1,9 +1,13 @@
 /**
- * `Unifi.FirewallPolicy` — one firewall policy on a UniFi Network site, READ-ONLY (`policy.ts`).
- * `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`) is the sibling resource for policy
- * ORDER within a zone pair (T5) — one per `(sourceFirewallZoneId, destinationFirewallZoneId)`, never
- * this file's concern. `docs/unifi.md`'s own header names this pair as "a bigger, separate PR";
- * this is that PR — see `docs/unifi-firewall-policy.md` for the full breakdown.
+ * `Unifi.FirewallPolicy` — one firewall policy on a UniFi Network site. READ/ADOPT-ONLY for every
+ * row (`policy.ts`), EXCEPT create for a row whose declared `name` starts `hf: `
+ * (`isHfPolicyName`, Tim 2026-10-19 ~16:20Z) — `update` and `delete` stay refused even for an
+ * `hf:` row. `Unifi.FirewallPolicyOrdering` (`firewall-policy-ordering.ts`) is the sibling
+ * resource for policy ORDER within a zone pair (T5) — one per `(sourceFirewallZoneId,
+ * destinationFirewallZoneId)`, still read-only; this lift does not touch it, so a created `hf:`
+ * row lands wherever the controller places a new policy, and placing it ahead of its zone pair's
+ * "Block All Traffic" (if the controller does not already do that) would need an ordering WRITE —
+ * a second, separate lift this PR does not make (see `docs/unifi-firewall-policy.md`).
  *
  * ★ T11 GATE, CHECKED 2026-09-26: the `Firewall` tag's 13 operations (5 already covered for
  *   `Unifi.FirewallZone` in `docs/unifi.md`, 8 new here for `FirewallPolicy` — `getFirewallPolicies`,
@@ -14,25 +18,47 @@
  *   that DID change elsewhere in the document. Corroborated independently by the A3 changeset's own
  *   broader 25-operation/139-schema re-check (`.changeset/unifi-network-a3-typed-discriminator-filters.md`).
  *   Full breakdown: `docs/unifi-firewall-policy.md`.
+ *
+ * ⛔ `fetchLive` LOCATES BY `name` WHEN `firewallPolicyId` IS ABSENT (an `hf:` creatable
+ *   declaration never has the vendor id before its first successful create). A real site's policy
+ *   count is in the hundreds (T9, 424 live policies), so this walks every page with `pageAll`
+ *   rather than trusting any one page to hold the match — same reasoning netbox's `locateOne`
+ *   gives for a server-side filter that cannot be trusted alone, except here there IS no
+ *   server-side name filter at all, so every row is paged. More than one row sharing a name is a
+ *   defect, not a reason to take the first: `policy.ts`'s naming convention is exactly `hf: <desc>`
+ *   because a free-text description makes a collision astronomically unlikely, but if the console
+ *   ever has one, this engine refuses to guess which row is "the" declared one.
  */
 import { Resource } from 'alchemy';
 import { adopt } from 'alchemy/AdoptPolicy';
 import * as Provider from 'alchemy/Provider';
 import * as firewall from '@distilled.cloud/unifi-network/firewall';
 import * as Effect from 'effect/Effect';
+import {
+  checkHfCreateScope,
+  firewallPolicyCreateAllowedWrite,
+  writeFirewallPolicyCreate,
+} from './firewall-policy-create.ts';
+import { driftOf } from './firewall-policy-drift.ts';
 import {
   type FirewallPolicyAttributes,
   type FirewallPolicyProps,
   attributesOf,
 } from './firewall-policy-form.ts';
 import { matches } from './firewall-policy-drift.ts';
+import { type UnifiPaginationInconsistent, pageAll } from './paginate.ts';
 import type { UnifiRequirements, UnifiSpec } from './resource.ts';
 import { unifiHandlers } from './resource.ts';
+import type { UnifiWriteRefused } from './policy.ts';
 
 export type { FirewallPolicyAttributes, FirewallPolicyProps } from './firewall-policy-form.ts';
 export { declareFirewallPolicy } from './firewall-policy-form.ts';
 export { driftOf } from './firewall-policy-drift.ts';
 
+/** `checkHfCreateScope`'s typed refusal, union'd with the real create call's own error, same
+ *  shape `network.ts`'s own `UpdateError` gives its write half. */
+type CreateError = UnifiWriteRefused | firewall.CreateFirewallPolicyError;
+
 export interface UnifiFirewallPolicy extends Resource<
   'Unifi.FirewallPolicy',
   FirewallPolicyProps,
@@ -45,26 +71,96 @@ export const UnifiFirewallPolicy = Resource<UnifiFirewallPolicy>('Unifi.Firewall
   defaultRemovalPolicy: 'retain',
 });
 
-/** `firewallPolicy('block-iot-wan', props)` — `adopt(true)` piped on by default (H5); see
- *  `network.ts`. */
+/** `firewallPolicy('block-iot-wan', props)` — for an IMPORTED, adopt-only row (always carries the
+ *  vendor's `firewallPolicyId`). `adopt(true)` piped on by default (H5); see `network.ts`. */
 export const firewallPolicy = (id: string, props: FirewallPolicyProps) =>
   UnifiFirewallPolicy(id, props).pipe(adopt(true));
 
+/**
+ * `hfFirewallPolicy('ct100-to-nas-https', props)` — for a NEW, kit-creatable row: `props` has no
+ * `firewallPolicyId` (the vendor assigns one), and `name` MUST start `hf: ` or this throws
+ * immediately, at declaration time, rather than waiting for `createReconcile`'s own typed refusal
+ * at deploy time. That typed refusal (`checkHfCreateScope`) is still the authoritative gate — this
+ * is a second, earlier check for the common case of a typo, not a replacement for it; a caller
+ * that builds `FirewallPolicyProps` by hand and calls `UnifiFirewallPolicy` directly still goes
+ * through `checkHfCreateScope` and is still refused the same way.
+ *
+ * ⛔ NO `adopt(true)` HERE. This is a create path, not an adoption: a cold read finding an
+ *  existing row of this exact name is `Unowned`, same as any other family, and a plan that adopts
+ *  one silently is not what "create" means for this lift.
+ */
+export const hfFirewallPolicy = (
+  id: string,
+  props: Omit<FirewallPolicyProps, 'firewallPolicyId'>,
+) => {
+  // ⚠️ `Omit` only rejects an excess property on a FRESH object literal passed at the call site —
+  //   a variable typed `FirewallPolicyProps` (which still has the field) passes the parameter type
+  //   check silently (Opus red team, 2026-10-19, SECONDARY FINDING). Checked at runtime so this
+  //   constructor cannot be the route past `checkHfCreateScope`'s own identity check either.
+  if (
+    'firewallPolicyId' in props &&
+    (props as { firewallPolicyId?: unknown }).firewallPolicyId !== undefined
+  ) {
+    throw new Error(
+      `hfFirewallPolicy(${id}): props already carries a firewallPolicyId -- this constructor is ` +
+        'for a row that does not exist yet. A row with a vendor id is adopted or updated, never ' +
+        'created; use firewallPolicy() instead.',
+    );
+  }
+  if (!props.name.startsWith('hf: ')) {
+    throw new Error(
+      `hfFirewallPolicy(${id}): name "${props.name}" does not start "hf: " -- only hf:-named ` +
+        'policies may be created by this kit (Tim 2026-10-19); rename the declaration.',
+    );
+  }
+  return UnifiFirewallPolicy(id, props as FirewallPolicyProps);
+};
+
+/** One page of `getFirewallPolicies`, walked end to end and narrowed to the sole row named
+ *  `name` — the locate path `fetchLive` uses when `firewallPolicyId` is not yet known. */
+const locateByName = (siteId: string, name: string) =>
+  pageAll(firewall.getFirewallPolicies, { siteId }).pipe(
+    Effect.map((rows) => {
+      const matching = rows.filter((row) => row.name === name);
+      if (matching.length > 1) {
+        throw new Error(
+          `Unifi.FirewallPolicy: ${String(matching.length)} live policies are named "${name}" on ` +
+            `site ${siteId}. A name this engine locates by must be unique; rename one on the console.`,
+        );
+      }
+      return matching[0];
+    }),
+  );
+
 /** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
 export const spec: UnifiSpec<
   FirewallPolicyProps,
   firewall.FirewallPolicy,
   FirewallPolicyAttributes,
-  firewall.GetFirewallPolicyError
+  firewall.GetFirewallPolicyError | firewall.GetFirewallPoliciesError | UnifiPaginationInconsistent,
+  never,
+  CreateError
 > = {
   type: 'Unifi.FirewallPolicy',
-  describe: (props) => `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
+  describe: (props) =>
+    props.firewallPolicyId === undefined
+      ? `sites/${props.siteId}/firewall/policies/by-name/${props.name}`
+      : `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
   fetchLive: (props) =>
-    firewall
-      .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
-      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+    props.firewallPolicyId === undefined
+      ? locateByName(props.siteId, props.name)
+      : firewall
+          .getFirewallPolicy({ siteId: props.siteId, firewallPolicyId: props.firewallPolicyId })
+          .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   attributes: attributesOf,
   matches,
+  create: {
+    allowedWrite: firewallPolicyCreateAllowedWrite,
+    checkScope: checkHfCreateScope,
+    write: writeFirewallPolicyCreate,
+    identify: (props, written) => ({ ...props, firewallPolicyId: written.id }),
+    driftOf,
+  },
 };
 
 export const handlers = unifiHandlers(spec);

package/src/unifi/index.ts

@@ -94,6 +94,7 @@ export {
   UnifiFirewallPolicyProvider,
   declareFirewallPolicy,
   firewallPolicy,
+  hfFirewallPolicy,
   type FirewallPolicyAttributes,
   type FirewallPolicyProps,
   driftOf as firewallPolicyDriftOf,

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,
@@ -78,8 +79,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* () {
@@ -124,3 +125,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),
+    });
+  });