@homeflare/alchemy 0.55.0 → 0.57.0

package/src/linux/sudo-runner-privileged-read.test.ts

@@ -4,7 +4,8 @@
  */
 import { describe, expect, test } from 'bun:test';
 import type { FileStat, HostRunner } from '../launchd/runner.ts';
-import { SUDO } from './sudo-allowlist.ts';
+import { CHOWN, INSTALL, SUDO } from './sudo-allowlist.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
 import {
   BASE64,
   SudoRefusedError,
@@ -90,3 +91,110 @@ describe('privilegedReads', () => {
     expect(checkPrivilegedReads([SECRETISH]).has(SECRETISH)).toBe(true);
   });
 });
+
+/**
+ * The write side of the same grant (the /etc/nut convergence, 2026-10-18): a file the runner
+ * reads back as root may be WRITTEN with a mode that hides it from the operator — its read-back
+ * goes through `sudo -n base64`, so it cannot strand itself. Every other refusal (setuid,
+ * group-writable, the path chain) still applies, and an UNLISTED file with the same mode keeps
+ * refusing exactly as before.
+ */
+describe('privilegedReads on the write path', () => {
+  const NUTISH = '/etc/nut/upsd.users';
+  const bytes = new TextEncoder().encode('new bytes\n');
+  const owner = { gid: 113, mode: 0o640, uid: 0 };
+
+  const mk = (options: { readonly listed?: boolean } = {}) =>
+    fakeSudoHost({}, new Set(), {
+      operatorGroups: [1000],
+      prefixes: ['/etc/nut'],
+      ...(options.listed === false ? {} : { privilegedReads: [NUTISH] }),
+    });
+
+  test('plan-time checkWrite passes for the listed 0640 root:nut file, refuses when unlisted', async () => {
+    const { runner } = mk();
+    const unlisted = mk({ listed: false });
+    if (runner.checkWrite === undefined || unlisted.runner.checkWrite === undefined) {
+      throw new Error('sshSudoRunner must expose checkWrite');
+    }
+    await runner.checkWrite(NUTISH, owner);
+    await expect(unlisted.runner.checkWrite(NUTISH, owner)).rejects.toThrow('would hide it');
+  });
+
+  test('writeFileAtomic installs and chowns the listed 0640 root:nut file under the prefix', async () => {
+    const { fake, privileged, runner } = mk();
+    fake.files.set(NUTISH, {
+      bytes: new TextEncoder().encode('old'),
+      gid: 113,
+      kind: 'file',
+      mode: 0o640,
+      uid: 0,
+    });
+    await runner.writeFileAtomic(NUTISH, bytes, owner);
+    const root = privileged();
+    expect(root.some((call) => call[0] === INSTALL)).toBe(true);
+    expect(root.some((call) => call[0] === CHOWN && call[1] === ':+113')).toBe(true);
+    const after = fake.files.get(NUTISH);
+    expect(new TextDecoder().decode(after?.bytes)).toBe('new bytes\n');
+    expect(after?.mode).toBe(0o640);
+    expect(after?.uid).toBe(0);
+    expect(after?.gid).toBe(113);
+    /**
+     * ★ THE JOINED GUARANTEE (deepseek round-2 ask): the file the guard let us write in a mode
+     *   that hides it from the operator reads back AS ROOT through the listed path — never
+     *   EACCES, never the operator's own read. This is the stranding the guard existed to
+     *   prevent, now provably absent end-to-end.
+     */
+    const before = root.length;
+    expect(new TextDecoder().decode(await runner.readFile(NUTISH))).toBe('new bytes\n');
+    expect(privileged()[before]).toEqual([BASE64, '--', NUTISH]);
+  });
+
+  test('an unlisted 0640 write still refuses, and nothing runs as root', async () => {
+    const { privileged, runner } = mk({ listed: false });
+    await expect(runner.writeFileAtomic(NUTISH, bytes, owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('with the set non-empty, a sibling under the same prefix still refuses', async () => {
+    // The skip is set MEMBERSHIP, never a prefix match: with NUTISH listed, its sibling
+    // upsmon.conf — same directory, same shape, same mode — keeps the refusal
+    // (glm round-2 ask, 2026-10-18).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite('/etc/nut/upsmon.conf', owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('a listed file still refuses setuid and group-writable modes', async () => {
+    const { runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o4755, uid: 0 })).rejects.toThrow(
+      'setuid/setgid',
+    );
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o0660, uid: 0 })).rejects.toThrow(
+      'writable by group',
+    );
+  });
+
+  test('a listed path handed to a non-root uid is refused outright, whatever its mode', async () => {
+    // The elevated read itself refuses anything but a root-owned regular file, so a handoff —
+    // even one with operator-readable other bits (0644 uid 1001) that the plain read-back check
+    // would pass — would land and then fail EVERY read: the stranding the guard exists to
+    // prevent (deepseek round-1; the other-readable case is the glm round ask).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    for (const handoff of [
+      { gid: 113, mode: 0o640, uid: 1001 },
+      { gid: 0, mode: 0o644, uid: 1001 },
+    ]) {
+      await expect(runner.checkWrite(NUTISH, handoff)).rejects.toThrow(
+        'Handing it to uid 1001 would land and then fail every read',
+      );
+      await expect(runner.writeFileAtomic(NUTISH, bytes, handoff)).rejects.toThrow(
+        'Keep it root-owned',
+      );
+    }
+    expect(privileged()).toEqual([]);
+  });
+});

package/src/linux/sudo-runner.ts

@@ -8,7 +8,9 @@
  *   is the "no silent sudo" failure this exists to prevent.
  * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and a file's bytes never reach argv or the
  *   log: they travel through the staged file (sudo-stage.ts) alone.
- * ⛔ A PLAN NEVER ELEVATES. `checkWrite` and every read run through `base` — the plain
+ * ⛔ A PLAN ELEVATES EXACTLY ONE KIND OF CALL: the `privilegedReads` file's own read (below) —
+ *   the read a plan diff needs on a declared root-owned file. Every other read, and every
+ *   `checkWrite` host probe (`id -G`, `ls`, `stat`), runs through `base` — the plain
  *   `sshRunner()` — never through sudo. Nothing here probes sudo at construction.
  * ★ PROMISES, NOT EFFECTS, ON PURPOSE — the same divergence `../launchd/runner.ts` documents
  *   (H3 in the provider-standard skill): a consumer's own runner is a plain async implementation.
@@ -120,7 +122,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
 
   return {
     checkWrite: async (path, options) => {
-      await vetWrite(base, prefixes, path, options);
+      await vetWrite(base, prefixes, path, options, readable);
     },
     effectiveUid: () => base.effectiveUid(),
     exec: async (argv) => {
@@ -174,7 +176,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     sleep: (ms) => base.sleep(ms),
     stat: (path) => base.stat(path),
     writeFileAtomic: async (path, bytes, options) => {
-      const vetted = await vetWrite(base, prefixes, path, options);
+      const vetted = await vetWrite(base, prefixes, path, options, readable);
       if (vetted === undefined) {
         return base.writeFileAtomic(path, bytes, options).catch(outsidePrefixHint(path, prefixes));
       }

package/src/linux/sudo-write.ts

@@ -73,12 +73,16 @@ export type Elevate = (
  * Plan-time and write-time share this: valid mode, the path chain, mode/owner refusals and the
  * read-back — everything a write can be refused for before anything is staged or run as root.
  * `undefined` outside every prefix, where the caller falls back to `base` directly.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set: a file on it is read back as
+ *   root (sudo-runner.ts's readFile), so the read-back refusal does not apply to it — the other
+ *   checks in assertInstallable still do.
  */
 export const vetWrite = async (
   base: HostRunner,
   prefixes: readonly string[],
   path: string,
   options: WriteOptions,
+  privilegedReads?: ReadonlySet<string>,
 ): Promise<{ readonly mode: string; readonly prefix: string } | undefined> => {
   const prefix = prefixOf(path, prefixes);
   if (prefix === undefined) return undefined;
@@ -86,7 +90,7 @@ export const vetWrite = async (
   if (mode === undefined)
     throw new SudoRefusedError(`sshSudoRunner ${path}: mode must be 0–0o7777`);
   const groups = await operatorGroups(base);
-  await assertInstallable(base, prefix, path, options, groups);
+  await assertInstallable(base, prefix, path, options, groups, privilegedReads);
   return { mode, prefix };
 };
 

package/src/talos/talosctl.test.ts

@@ -2,7 +2,7 @@
  * talosctl binary override. Fake spawner only — the named path is never executed (it only has to
  * exist and be a trusted file; the fake answers `version --client` with the pinned version).
  */
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, expect, test } from 'bun:test';
@@ -26,6 +26,8 @@ trustBoundaryForTests(dir);
 const fixture = join(dir, 'talosctl');
 writeFileSync(fixture, '#!/bin/sh\n', { mode: 0o755 });
 chmodSync(fixture, 0o755);
+// macOS tmpdir is /var, a symlink to /private/var. The vetted command is the real path.
+const resolved = realpathSync(fixture);
 afterAll(() => rmSync(dir, { force: true, recursive: true }));
 
 const run = (binary: string | undefined, calls: FakeCall[]) =>
@@ -56,7 +58,7 @@ test('the binary option wins over HF_TALOSCTL', async () => {
   await withEnv('/definitely/not/here/talosctl', async () => {
     const calls: FakeCall[] = [];
     await run(fixture, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -64,7 +66,7 @@ test('HF_TALOSCTL selects the binary when the option is omitted', async () => {
   await withEnv(fixture, async () => {
     const calls: FakeCall[] = [];
     await run(undefined, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -84,7 +86,7 @@ test('the default talosctl is resolved on PATH, vetted and version-checked by ab
     withPath(dir, async () => {
       const calls: FakeCall[] = [];
       await run(undefined, calls);
-      expect(calls.map((call) => call.command)).toEqual([fixture, fixture]);
+      expect(calls.map((call) => call.command)).toEqual([resolved, resolved]);
     }),
   );
 });

package/src/unifi/firewall-policy-create.ts

@@ -0,0 +1,94 @@
+/**
+ * `Unifi.FirewallPolicy`'s CREATE — the one write this family may make, and only for a row whose
+ * declared `name` passes `policy.ts`'s `isHfPolicyName` (Tim 2026-10-19 ~16:20Z, "Allow kit to
+ * create hf: rules"). THE ONLY FILE UNDER `src/unifi` ALLOWED TO NAME `createFirewallPolicy`
+ * (`write-op-reference.test.ts`'s `WRITE_OP_ALLOWLIST` pins that, alongside `network-update.ts`'s
+ * own `updateNetwork` entry).
+ *
+ * ⛔ A CREATE SENDS ONLY THE FIELDS THE DECLARATION OWNS — NEVER A SPREAD OF ANYTHING ELSE. Unlike
+ *   `network-update.ts`'s whole-object PUT (which must carry the untouched live object forward so
+ *   an omitted optional block is not read by the controller as "turn it off"), there IS no live
+ *   object yet: `createBody` builds `CreateFirewallPolicyRequest` field by field from `props`,
+ *   omitting every optional key `props` itself leaves `undefined` rather than sending it as
+ *   `null`/`undefined` (UniFi's "missing = off" rule cuts both ways — a key that is actually absent
+ *   from the JSON body is what "this policy does not restrict on this axis" means here, same as a
+ *   declaration that never sets `connectionStateFilter` means "match every connection state").
+ * ⛔ `checkScope` RUNS BEFORE THE REQUEST, TYPED, NEVER A STRING COMPARISON INLINE AT THE CALL
+ *   SITE — one function (`policy.ts`'s `isHfPolicyName`) decides "hf:" everywhere this boundary is
+ *   checked, so a future second caller cannot drift from this one with a slightly different regex.
+ *
+ * 🔴 `checkScope` ALSO REFUSES A `firewallPolicyId` THAT IS ALREADY SET (Opus red team,
+ *   2026-10-19, PRIMARY FINDING). `resource.ts`'s `create` branch runs for EVERY
+ *   `Unifi.FirewallPolicy` declaration with no prior Alchemy state, not only ones meant to
+ *   create — including every `firewallPolicy()` import `.pipe(adopt(true))`, and Tim's own live
+ *   console ALREADY names hand-made rules `hf: <desc>` (this file's sibling `policy.ts` cites
+ *   `hf: Vpn to MGMT (Magic WAN site-to-site)` as the existing convention). Before this check, an
+ *   hf:-named IMPORTED row whose `firewallPolicyId` stopped resolving (state lost, the rule
+ *   hand-deleted and recreated with a new id, a wrong id in a generated declaration) would GET
+ *   404, fall into `createReconcile`, pass the name check, and POST A DUPLICATE — silently, with
+ *   a green plan, where every other family still refuses "declared row absent" outright
+ *   (`update-reconcile.ts`'s original behavior, unchanged for every family but this one). A
+ *   declaration carrying a vendor id is BY DEFINITION an existing row, adopted or updated, never
+ *   a fresh create; `firewallPolicyId !== undefined` is refused here before `isHfPolicyName` is
+ *   even checked, so this holds regardless of what the name says.
+ */
+import * as firewall from '@distilled.cloud/unifi-network/firewall';
+import * as Effect from 'effect/Effect';
+import { isHfPolicyName, refuseWrite } from './policy.ts';
+import type { FirewallPolicyProps } from './firewall-policy-form.ts';
+import type { AllowedWrite } from './wire-guard.ts';
+
+/** The site's fixed firewall-policies COLLECTION route — never a per-row path, since there is no
+ *  row id before this POST creates one. Takes `props` (not just a bare `siteId`) to match
+ *  `UnifiUpdate.allowedWrite`'s own shape, so `resource.ts`'s wiring treats both the same way. */
+export const firewallPolicyCreateAllowedWrite = (props: FirewallPolicyProps): AllowedWrite => ({
+  method: 'POST',
+  tail: `/v1/sites/${props.siteId}/firewall/policies`,
+});
+
+const describeByName = (props: FirewallPolicyProps) =>
+  `sites/${props.siteId}/firewall/policies/by-name/${props.name}`;
+
+/** Refuses, typed, before any request: the one gate `createReconcile` calls before `write`.
+ *  Order matters for the message only (both refuse the same way) — the identity check runs
+ *  first because it is the one that must hold regardless of what the name says (see header). */
+export const checkHfCreateScope = (props: FirewallPolicyProps) => {
+  if (props.firewallPolicyId !== undefined) {
+    return refuseWrite(
+      'Unifi.FirewallPolicy',
+      `sites/${props.siteId}/firewall/policies/${props.firewallPolicyId}`,
+      'create',
+    );
+  }
+  return isHfPolicyName(props.name)
+    ? Effect.void
+    : refuseWrite('Unifi.FirewallPolicy', describeByName(props), 'create');
+};
+
+/** Every field `CreateFirewallPolicyRequest` accepts, straight from the declaration, with an
+ *  absent optional field left OUT of the body entirely (never sent as `undefined`/`null`) —
+ *  `JSON.stringify` already drops an `undefined` value, but building the object field-by-field
+ *  rather than spreading `props` keeps this list the single place that enumerates exactly what a
+ *  create may send, so a future prop added to `FirewallPolicyProps` for some OTHER purpose cannot
+ *  silently become a wire field here without this file changing too. */
+export const firewallPolicyCreateBody = (
+  props: FirewallPolicyProps,
+): firewall.CreateFirewallPolicyRequest => ({
+  siteId: props.siteId,
+  action: props.action,
+  ...(props.connectionStateFilter === undefined
+    ? {}
+    : { connectionStateFilter: props.connectionStateFilter }),
+  ...(props.description === undefined ? {} : { description: props.description }),
+  destination: props.destination,
+  enabled: props.enabled,
+  ipProtocolScope: props.ipProtocolScope,
+  ...(props.ipsecFilter === undefined ? {} : { ipsecFilter: props.ipsecFilter }),
+  loggingEnabled: props.loggingEnabled,
+  name: props.name,
+  ...(props.schedule === undefined ? {} : { schedule: props.schedule }),
+  source: props.source,
+});
+
+export const writeFirewallPolicyCreate = (props: FirewallPolicyProps) =>
+  firewall.createFirewallPolicy(firewallPolicyCreateBody(props));

package/src/unifi/firewall-policy-form.ts

@@ -55,10 +55,17 @@ export const normalizeConnectionStateFilter = (
 ): string[] | undefined => (value == null ? undefined : sortedSet(value));
 
 /** ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` — `exactOptionalPropertyTypes`; see
- *  `network-form.ts`'s own header. */
+ *  `network-form.ts`'s own header.
+ *
+ * ⛔ `firewallPolicyId` IS OPTIONAL SINCE THE 2026-10-19 hf: CREATE LIFT. An adopt-only
+ *   declaration (`declareFirewallPolicy`, every imported row) always carries the vendor id it was
+ *   read from. A fresh `hf:` creatable declaration (`declareHfFirewallPolicy` below) does not have
+ *   one yet — the vendor assigns it on `createFirewallPolicy`'s response — so `spec.fetchLive`
+ *   (`firewall-policy.ts`) locates by `name` instead of `id` whenever this is absent (netbox's
+ *   `locateOne` is the precedent for identity-by-natural-key over identity-by-vendor-id). */
 export interface FirewallPolicyProps {
   siteId: string;
-  firewallPolicyId: string;
+  firewallPolicyId?: string | undefined;
   action: firewall.FirewallPolicyAction;
   /** Connection states this policy matches — compared as a SET, see the header. */
   connectionStateFilter?: string[] | undefined;

package/src/unifi/firewall-policy.test.ts

@@ -23,7 +23,13 @@ import * as Effect from 'effect/Effect';
 import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
 import { attributesOf } from './firewall-policy-form.ts';
 import { driftOf, matches } from './firewall-policy-drift.ts';
-import { type FirewallPolicyProps, declareFirewallPolicy, spec } from './firewall-policy.ts';
+import {
+  type FirewallPolicyProps,
+  declareFirewallPolicy,
+  hfFirewallPolicy,
+  spec,
+} from './firewall-policy.ts';
+import { UnifiCreateDidNotConverge, UnifiWriteRefused } from './policy.ts';
 import { pageAll } from './paginate.ts';
 import { unifiOperations } from './resource.ts';
 
@@ -152,6 +158,187 @@ describe('Unifi.FirewallPolicy write paths never reach the vendor API', () => {
   });
 });
 
+/**
+ * The hf: create lift (Tim 2026-10-19 ~16:20Z) -- the one write `Unifi.FirewallPolicy` may now
+ * make, and only for a declared `name` starting `hf: `. Mirrors the write-refusal tests above,
+ * plus the one path that now DOES reach the vendor API.
+ */
+const POLICIES_PATH = '/proxy/network/integration/v1/sites/site-1/firewall/policies';
+const NEW_ID = 'hf-new-1';
+
+const emptyPage = () => Response.json({ count: 0, data: [], limit: 0, offset: 0, totalCount: 0 });
+
+/** No `firewallPolicyId`: the shape `hfFirewallPolicy` declares before anything is created. */
+const HF_PROPS: FirewallPolicyProps = {
+  siteId: 'site-1',
+  action: { type: 'ALLOW', allowReturnTraffic: true },
+  destination: { zoneId: 'zone-storage' },
+  enabled: true,
+  ipProtocolScope: { ipVersion: 'IPV4' },
+  loggingEnabled: true,
+  name: 'hf: CT100 to NAS https',
+  source: { zoneId: 'zone-internal' },
+};
+
+describe('Unifi.FirewallPolicy hf: create', () => {
+  const ops = unifiOperations(spec);
+
+  test('an hf:-named create: one locate GET, one POST of only the declared fields, one read-back GET', async () => {
+    let createdLive: firewall.FirewallPolicy | undefined;
+    const fake = fakeUnifi((method, url) => {
+      if (url.pathname === POLICIES_PATH && method === 'GET') return emptyPage();
+      if (url.pathname === POLICIES_PATH && method === 'POST') {
+        createdLive = {
+          ...HF_PROPS,
+          id: NEW_ID,
+          index: 0,
+          metadata: { origin: 'USER' },
+        } as firewall.FirewallPolicy;
+        return Response.json(createdLive);
+      }
+      if (url.pathname === `${POLICIES_PATH}/${NEW_ID}` && method === 'GET') {
+        return Response.json(createdLive);
+      }
+      return fakeFailure(400, 'unexpected request');
+    });
+
+    const attrs = await Effect.runPromise(
+      ops.reconcile(HF_PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(attrs.firewallPolicyId).toBe(NEW_ID);
+    expect(attrs.name).toBe('hf: CT100 to NAS https');
+    expect(fake.seen.map((s) => `${s.method} ${s.path}`)).toEqual([
+      `GET ${POLICIES_PATH}?offset=0`,
+      `POST ${POLICIES_PATH}`,
+      `GET ${POLICIES_PATH}/${NEW_ID}`,
+    ]);
+    // ⛔ ONLY the declared fields -- no firewallPolicyId (there was none), no stray key.
+    // `siteId` is a path label (`T.Http`'s `uri: "/v1/sites/{siteId}/..."`), not a body field.
+    expect(fake.seen[1]?.body).toEqual({
+      action: { type: 'ALLOW', allowReturnTraffic: true },
+      destination: { zoneId: 'zone-storage' },
+      enabled: true,
+      ipProtocolScope: { ipVersion: 'IPV4' },
+      loggingEnabled: true,
+      name: 'hf: CT100 to NAS https',
+      source: { zoneId: 'zone-internal' },
+    });
+  });
+
+  test('a non-hf: name refuses create, typed, sending the existence GET but no write', async () => {
+    // ★ The existence GET (does a row this name already matches exist?) runs for every name --
+    //   the SAME GET a plain cold adoption needs (H6) -- and answers empty here. Only the WRITE
+    //   is refused: `fake.seen.every(GET)` is this file's own standing idiom for that proof.
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICIES_PATH
+        ? emptyPage()
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const notHf: FirewallPolicyProps = { ...HF_PROPS, name: 'Not hf-named' };
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(notHf).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect((failure as UnifiWriteRefused).action).toBe('create');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen.length).toBeGreaterThan(0);
+  });
+
+  test('"hf:foo" with no space after the colon is NOT an hf: name -- refused, no write', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICIES_PATH
+        ? emptyPage()
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const noSpace: FirewallPolicyProps = { ...HF_PROPS, name: 'hf:no-space' };
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(noSpace).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('a read-back mismatch after the POST fails typed (UnifiCreateDidNotConverge), not silently', async () => {
+    const fake = fakeUnifi((method, url) => {
+      if (url.pathname === POLICIES_PATH && method === 'GET') return emptyPage();
+      if (url.pathname === POLICIES_PATH && method === 'POST') {
+        return Response.json({ ...HF_PROPS, id: NEW_ID, index: 0, metadata: { origin: 'USER' } });
+      }
+      if (url.pathname === `${POLICIES_PATH}/${NEW_ID}` && method === 'GET') {
+        // The read-back disagrees with what was declared (e.g. the console normalized `enabled`).
+        return Response.json({
+          ...HF_PROPS,
+          id: NEW_ID,
+          index: 0,
+          metadata: { origin: 'USER' },
+          enabled: false,
+        });
+      }
+      return fakeFailure(400, 'unexpected request');
+    });
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(HF_PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiCreateDidNotConverge);
+    expect((failure as UnifiCreateDidNotConverge).fields).toEqual(['enabled']);
+  });
+
+  test('an hf:-named row with an id that 404s refuses -- never silently creates a duplicate (Opus red team)', async () => {
+    // ★ THE SCENARIO THE RED TEAM FOUND: an hf:-named row that ALREADY has Alchemy state's
+    //   `firewallPolicyId` but whose live object is gone (state lost and rebuilt with no `olds`/
+    //   `output`, a hand-deleted-and-recreated rule, a wrong id in a generated declaration) must
+    //   still refuse "create" -- not fall through and POST a second copy just because the name
+    //   happens to start `hf: ` (Tim's own hand-made console rules already do).
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-gone' };
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === `${POLICIES_PATH}/fp-gone`
+        ? fakeFailure(404, 'not found')
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(ops.reconcile(hfWithId).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure).toBeInstanceOf(UnifiWriteRefused);
+    expect((failure as UnifiWriteRefused).action).toBe('create');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('hfFirewallPolicy throws immediately when props already carries a firewallPolicyId', () => {
+    const withId = { ...HF_PROPS, firewallPolicyId: 'fp-1' };
+    expect(() => hfFirewallPolicy('bad', withId)).toThrow(/already carries a firewallPolicyId/);
+  });
+
+  test('update (drift) of an existing hf: row still refuses -- the lift is create only', async () => {
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-hf-1' };
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === `${POLICIES_PATH}/fp-hf-1`
+        ? Response.json({
+            ...HF_PROPS,
+            id: 'fp-hf-1',
+            index: 0,
+            metadata: { origin: 'USER' },
+            enabled: false,
+          })
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(hfWithId).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete of an hf: row still refuses -- no DELETE is ever sent', async () => {
+    const hfWithId: FirewallPolicyProps = { ...HF_PROPS, firewallPolicyId: 'fp-hf-1' };
+    const exit = await Effect.runPromiseExit(ops.destroy(hfWithId));
+    expect(exit._tag).toBe('Failure');
+  });
+
+  test('hfFirewallPolicy throws immediately for a name that is not hf:-prefixed', () => {
+    expect(() => hfFirewallPolicy('bad', { ...HF_PROPS, name: 'Not hf-named' })).toThrow(/hf: /);
+  });
+});
+
 describe("T9/B0b -- pageAll walks this family's own page shape (decode proof)", () => {
   test('every row across several pages of getFirewallPolicies decodes, in order', async () => {
     const rows = Array.from({ length: 7 }, (_, i) =>