@homeflare/alchemy 0.39.0 → 0.41.0

package/src/launchd/local-runner.ts

@@ -15,7 +15,7 @@ import { randomBytes } from 'node:crypto';
 import { lstat, open, readFile, rename, unlink } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { groupQuery, parseGroup, parseUser, userQuery } from './host-lookup.ts';
-import type { ExecResult, FileStat, HostRunner, WriteOptions } from './runner.ts';
+import type { ExecResult, FileStat, HostPlatform, HostRunner, WriteOptions } from './runner.ts';
 
 export type LocalRunnerOptions = {
   /** Kill a spawned program after this long. @default 120_000 */
@@ -98,6 +98,20 @@ const writeAtomic = async (path: string, bytes: Uint8Array, options: WriteOption
 export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
   const timeoutMs = options.execTimeoutMs ?? 120_000;
   const platform = process.platform;
+  // ★ THE ONE PLACE `process.platform` MAY DECIDE HOST BEHAVIOUR: here, the target IS this
+  //   process's own machine, so `process.platform` and `HostRunner.platform` name the same host.
+  //   Everywhere else (chmodChownEnd, host-lookup's callers over ssh) reads `runner.platform`
+  //   instead — see the incident on `HostRunner.platform`'s own doc comment.
+  // ⛔ DECLARED, NEVER GUESSED, past these two: silently folding freebsd/win32/etc. into 'linux'
+  //   would hand a BSD host GNU's `--`, which macOS's own (BSD-flavoured) chmod/chown already
+  //   reject — the same shape of bug this PR fixes. sshRunner's own `uname -s` probe refuses a
+  //   non-Linux target the same way; localRunner refuses here instead of guessing.
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error(
+      `localRunner(): unsupported process.platform ${JSON.stringify(platform)} — HostRunner only targets darwin and linux.`,
+    );
+  }
+  const hostPlatform: HostPlatform = platform;
   return {
     effectiveUid: () => process.geteuid?.() ?? -1,
     exec: (argv) => run(argv, timeoutMs),
@@ -109,6 +123,7 @@ export const localRunner = (options: LocalRunnerOptions = {}): HostRunner => {
       const result = await run(userQuery(platform, nameOrId), timeoutMs);
       return result.exitCode === 0 ? parseUser(platform, result.stdout) : undefined;
     },
+    platform: hostPlatform,
     privileged: false,
     readFile: async (path) => {
       try {

package/src/launchd/runner.ts

@@ -59,7 +59,29 @@ export type WriteOptions = {
 
 export type HostUser = { readonly uid: number; readonly gid: number; readonly home: string };
 
+/**
+ * The two host families a HostRunner ever actually targets. ★ Not `NodeJS.Platform`: nothing
+ *   here runs against `win32`/`aix`/etc, and a narrower type is what makes `runner.platform ===
+ *   'darwin'` exhaustive rather than a string comparison that silently matches nothing.
+ */
+export type HostPlatform = 'darwin' | 'linux';
+
 export interface HostRunner {
+  /**
+   * ⛔ DECLARED, NEVER INFERRED — same rule as `privileged`, and the same failure mode. The OS of
+   *   the TARGET this runner writes to, never of the process running Alchemy: `localRunner()` may
+   *   run ON either, but `sshRunner()`/`sshSudoRunner()` always reach a Linux host from wherever
+   *   Alchemy itself happens to run.
+   * 🔴 INCIDENT, homeflare-ct100 2026-09-27: `Host.Directory`'s chmod/chown end-of-options token
+   *   (directory-lifecycle.ts `chmodChownEnd`) read `process.platform` — the Mac mini's own OS —
+   *   instead of the runner's target. Deploying from the Mac to CT100 (a Debian LXC over
+   *   `sshSudoRunner`) dropped GNU's required `--`, and `sudo-allowlist-dir.ts`'s `dirProgramProblem`
+   *   refused every chown with `SudoRefusedError` even though the path was under a declared prefix.
+   *   `localRunner()`'s own local deploys never showed it: there, `process.platform` and the
+   *   target happen to be the same machine. This field is the fix: every call site that needs to
+   *   know the target's OS reads `runner.platform`, never `process.platform`.
+   */
+  readonly platform: HostPlatform;
   /**
    * ⛔ DECLARED, NEVER INFERRED. `true` only when this runner can do every root-needing call the
    *   providers make of it: every call already runs as root (a runner that talks to a root helper,

package/src/launchd/sudo-runner.ts

@@ -162,6 +162,9 @@ export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): H
     },
     lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
     lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ Forwarded, never hardcoded: this runner elevates on the SAME target `base` already
+    //   declared (localRunner's own machine), so it carries no opinion of its own.
+    platform: base.platform,
     // ★ True, so the providers let a system-domain job through to this runner (canActAsRoot).
     privileged: true,
     readFile: (path) => base.readFile(path),

package/src/linux/directory-lifecycle.ts

@@ -100,8 +100,18 @@ const octal = (mode: number) => mode.toString(8).padStart(3, '0');
  *   keep it. These paths are absolute, so the token is only an option guard.
  * ⛔ Linux keeps `--`. The sudo allowlist requires that exact token; dropping it there
  *   refuses the elevation.
+ * 🔴 INCIDENT, homeflare-ct100 2026-09-27: this used to decide on `process.platform` — the OS of
+ *   the machine RUNNING Alchemy — instead of `runner.platform`, the OS of the TARGET the runner
+ *   actually writes to. Deploying from the Mac mini (`darwin`) to CT100, a Debian LXC reached
+ *   over `sshSudoRunner`, dropped the required `--` and `sudo-allowlist-dir.ts`'s
+ *   `dirProgramProblem` refused every chown with `SudoRefusedError`, even though the path was
+ *   under a declared prefix — `localRunner()`'s own local (Mac-to-Mac) deploys never showed it,
+ *   because there `process.platform` and the target happen to be the same machine. Reading
+ *   `runner.platform` instead (declared by every HostRunner — see its own doc comment) makes the
+ *   decision follow the target, not the caller.
  */
-const chmodChownEnd = (): readonly string[] => (process.platform === 'darwin' ? [] : ['--']);
+const chmodChownEnd = (runner: HostRunner): readonly string[] =>
+  runner.platform === 'darwin' ? [] : ['--'];
 
 /** One program, checked: anything but exit 0 is an Error naming the argv and the host's words. */
 const must = async (runner: HostRunner, path: string, argv: readonly string[]): Promise<void> => {
@@ -160,7 +170,12 @@ export const reconcileDirectory = async (
     }
     await must(runner, props.path, ['mkdir', '-m', octal(want.mode), '--', props.path]);
   } else if (stat.mode !== want.mode) {
-    await must(runner, props.path, ['chmod', octal(want.mode), ...chmodChownEnd(), props.path]);
+    await must(runner, props.path, [
+      'chmod',
+      octal(want.mode),
+      ...chmodChownEnd(runner),
+      props.path,
+    ]);
   }
   /**
    * ★ Only when it is actually wrong. A `chown` that changes nothing is still a write on the host
@@ -174,7 +189,7 @@ export const reconcileDirectory = async (
     ? undefined
     : ownerArg(want);
   if (owner !== undefined)
-    await must(runner, props.path, ['chown', owner, ...chmodChownEnd(), props.path]);
+    await must(runner, props.path, ['chown', owner, ...chmodChownEnd(runner), props.path]);
   const after = await readDirectory(runner, props.path);
   // ⚠️ READ BACK: a runner that ignored the mode shows up here, not as a forever-`update`.
   if (after === undefined || after.mode !== want.mode || !ownerMatches(after, want)) {

package/src/linux/directory-sudo.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Host.Directory driven through sshSudoRunner — the exact path the homeflare-ct100 incident
+ * (2026-09-27) broke: a deploy running on a Mac (darwin) targeting a Linux host over ssh dropped
+ * the sudo allowlist's required `--`, because directory-lifecycle.ts's `chmodChownEnd()` read
+ * `process.platform` — the Mac's own OS — instead of the runner's own declared target.
+ *
+ * ★ WHY A SEPARATE FILE FROM directory.test.ts. Those tests exercise the lifecycle directly
+ *   against a bare fake host; these go through the REAL `sshSudoRunner` + `sudo-allowlist.ts`
+ *   layer (`canonicalize`, `dirProgramProblem`), which is what actually enforces the `--` token
+ *   and is what refused the live deploy with `SudoRefusedError`.
+ * ⛔ NEITHER TEST BELOW READS `process.platform`. `fakeLinuxHost()` (via `fakeSudoHost()`)
+ *   declares `platform: 'linux'` itself — sshRunner's own probe requires it — so this suite
+ *   catches the regression on every machine that runs `bun test`, regardless of that machine's
+ *   own OS. (This repo's own `check` job runs on `ubuntu-latest`, not the mini, so CI alone never
+ *   reproduces the "darwin process, Linux target" split the live incident measured; this suite's
+ *   fixed, declared target is what actually proves the fix, on any OS.)
+ */
+import { describe, expect, test } from 'bun:test';
+import { reconcileDirectory } from './directory-lifecycle.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
+
+describe('Host.Directory through sshSudoRunner (a Linux target)', () => {
+  test('the elevated chown and chmod carry -- and the allowlist accepts them', async () => {
+    const { privileged, runner } = fakeSudoHost();
+    expect(runner.platform).toBe('linux'); // ★ declared by sshRunner's own uname probe.
+
+    // A fresh create under a declared prefix: mkdir runs as root, then chown (owner/group
+    // declared) also runs as root — both routed through routeExec()/elevatedExec().
+    const created = await reconcileDirectory(runner, {
+      group: 0,
+      mode: 0o755,
+      owner: 0,
+      path: '/etc/systemd/system/hf-test-dir',
+    });
+    expect(created).toEqual({
+      gid: 0,
+      mode: 0o755,
+      path: '/etc/systemd/system/hf-test-dir',
+      uid: 0,
+    });
+
+    // A mode drift on the next reconcile routes an elevated chmod too.
+    await reconcileDirectory(
+      runner,
+      { group: 0, mode: 0o750, owner: 0, path: '/etc/systemd/system/hf-test-dir' },
+      created,
+    );
+
+    const chown = privileged().find((call) => call[0] === '/usr/bin/chown');
+    const chmod = privileged().find((call) => call[0] === '/usr/bin/chmod');
+    // ⛔ REGRESSION: before the fix, these two calls carried no `--` whenever `bun test` ran on a
+    //   Mac, and `sudo-allowlist-dir.ts`'s `dirProgramProblem` refused them with
+    //   `SudoRefusedError` — the exact failure measured against homeflare-ct100 2026-09-27.
+    expect(chown).toBeDefined();
+    expect(chown).toContain('--');
+    expect(chmod).toBeDefined();
+    expect(chmod).toContain('--');
+  });
+});

package/src/linux/directory.test.ts

@@ -3,6 +3,7 @@
  * to create a parent.
  */
 import { describe, expect, test } from 'bun:test';
+import type { HostRunner } from '../launchd/runner.ts';
 import {
   deleteDirectory,
   diffDirectory,
@@ -105,8 +106,16 @@ describe('drift', () => {
 });
 
 describe('argv', () => {
-  test('chmod and chown omit -- on Darwin; mkdir keeps it on every platform', async () => {
+  // ⛔ REGRESSION, 2026-09-27: this used to read `process.platform !== 'darwin'` to decide what
+  //   the fake (a LINUX host) should have produced — so it only ever proved the real behaviour
+  //   when `bun test` itself happened to run on Linux (matching the fake's target by
+  //   coincidence), and passed just as happily on a Mac while asserting the bug itself (no `--`
+  //   for a Linux target). `runner.platform` is declared by the fixture instead, so these two
+  //   tests hold regardless of what OS actually runs the suite — the exact "darwin process,
+  //   Linux target" split the homeflare-ct100 incident measured.
+  test('mkdir keeps --, and chmod/chown carry -- for a Linux target', async () => {
     const fake = host();
+    expect(fake.runner.platform).toBe('linux'); // ★ fakeLinuxHost's own declaration.
     const created = await reconcileDirectory(fake.runner, {
       group: 0,
       mode: 0o755,
@@ -118,13 +127,30 @@ describe('argv', () => {
       { group: 0, mode: 0o750, owner: 0, path: '/opt/app/bin' },
       created,
     );
-    const gnu = process.platform !== 'darwin';
-    const chown = fake.calls.find((call) => call[0] === 'chown');
-    const chmod = fake.calls.find((call) => call[0] === 'chmod');
-    const mkdir = fake.calls.find((call) => call[0] === 'mkdir');
-    expect(chown?.includes('--')).toBe(gnu);
-    expect(chmod?.includes('--')).toBe(gnu);
-    expect(mkdir).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'mkdir')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chown')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chmod')).toContain('--');
+  });
+
+  test('mkdir still keeps --, but chmod/chown omit it for a runner declared as Darwin', async () => {
+    const fake = host();
+    // ★ Same fake host, only the declared target changes — proves chmodChownEnd() reads
+    //   `runner.platform`, never the machine `bun test` itself happens to run on.
+    const darwinRunner: HostRunner = { ...fake.runner, platform: 'darwin' };
+    const created = await reconcileDirectory(darwinRunner, {
+      group: 0,
+      mode: 0o755,
+      owner: 0,
+      path: '/opt/app/bin',
+    });
+    await reconcileDirectory(
+      darwinRunner,
+      { group: 0, mode: 0o750, owner: 0, path: '/opt/app/bin' },
+      created,
+    );
+    expect(fake.calls.find((call) => call[0] === 'mkdir')).toContain('--');
+    expect(fake.calls.find((call) => call[0] === 'chown')?.includes('--')).toBe(false);
+    expect(fake.calls.find((call) => call[0] === 'chmod')?.includes('--')).toBe(false);
   });
 });
 

package/src/linux/fake-linux-host.ts

@@ -127,6 +127,8 @@ export const fakeLinuxHost = (options: FakeLinuxOptions = {}) => {
     lookupUser: async (nameOrId) =>
       options.users?.[nameOrId] ??
       Object.values(options.users ?? {}).find((user) => String(user.uid) === nameOrId),
+    // ★ This fake models sshRunner()'s own target, which is always Linux — fixed, not an option.
+    platform: 'linux',
     privileged,
     readFile: async (path) => files.get(path)?.bytes,
     removeFile: async (path) => {

package/src/linux/index.ts

@@ -24,6 +24,7 @@ export { sshSudoRunner } from './sudo-runner.ts';
 export type {
   ExecResult,
   FileStat,
+  HostPlatform,
   HostRunner,
   HostUser,
   WriteOptions,

package/src/linux/ssh-runner.ts

@@ -154,6 +154,10 @@ export const sshRunner = async (options: SshRunnerOptions): Promise<HostRunner>
       const result = await run(execScript(userQuery('linux', nameOrId)));
       return result.exitCode === 0 ? parseUser('linux', result.stdout) : undefined;
     },
+    // ★ Fixed, not read from the caller's own `process.platform`: the probe above already
+    //   refused anything but `uname -s` = Linux, so this is the one true answer for this runner —
+    //   whatever OS is running Alchemy itself is irrelevant (HostRunner.platform's doc comment).
+    platform: 'linux',
     privileged: false,
     readFile: async (path) => {
       const result = await run(readScript(path));

package/src/linux/sudo-runner.ts

@@ -99,6 +99,9 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     },
     lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
     lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ Forwarded, never hardcoded — same reasoning as ../launchd/sudo-runner.ts's own forward:
+    //   this runner elevates on the SAME target `base` (sshRunner) already declared.
+    platform: base.platform,
     privileged: true,
     readFile: (path) => base.readFile(path),
     removeFile: async (path) => {

package/src/opnsense/alias-form.test.ts

@@ -1,19 +1,21 @@
 /**
- * `alias-form.ts`'s pure functions against literal `AliasItem` fixtures — no network, no fake
- * server. Mirrors `../discord/command-form.ts`'s own test file in spirit.
+ * `alias-form.ts`'s pure functions against literal `ModelAliasReadItem` fixtures (the WHOLE-MODEL
+ * `get()`'s read-shaped item, option maps and all — OPNSENSE-2) — no network, no fake server.
+ * Mirrors `../discord/command-form.ts`'s own test file in spirit.
  */
 import { describe, expect, test } from 'bun:test';
 import type * as alias from '@distilled.cloud/opnsense/firewall_alias';
 import { attributesOf, matches } from './alias-form.ts';
 import type { AliasProps } from './alias.ts';
+import { optionMap } from './wire.ts';
 
 const UUID = '11111111-1111-1111-1111-111111111111';
 
-const liveHost = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
-  content: '10.20.10.1',
+const liveHost = (overrides: Partial<alias.ModelAliasReadItem> = {}): alias.ModelAliasReadItem => ({
+  content: optionMap('10.20.10.1'),
   enabled: '1',
   name: 'homeflare_edge',
-  type: 'host',
+  type: optionMap('host'),
   ...overrides,
 });
 
@@ -38,10 +40,20 @@ describe('alias-form attributesOf', () => {
     expect(attributesOf(UUID, liveHost({ enabled: '0' })).enabled).toBe(false);
   });
 
-  test('categories are split, sorted and deduplicated', () => {
-    const live = liveHost({ categories: 'c-two,c-one,c-one' });
+  test('categories are the selected keys, sorted and deduplicated', () => {
+    const live = liveHost({ categories: optionMap('c-two', 'c-one') });
     expect(attributesOf(UUID, live).categories).toEqual(['c-one', 'c-two']);
   });
+
+  test('an unselected option-map entry is not returned (single-select `type`)', () => {
+    const live = liveHost({
+      type: {
+        host: { value: 'Host(s)', selected: 1 },
+        network: { value: 'Network(s)', selected: 0 },
+      },
+    });
+    expect(attributesOf(UUID, live).type).toBe('host');
+  });
 });
 
 describe('alias-form matches', () => {
@@ -57,12 +69,12 @@ describe('alias-form matches', () => {
   });
 
   test('content drift is caught', () => {
-    const drifted = attributesOf(UUID, liveHost({ content: '10.20.10.2' }));
+    const drifted = attributesOf(UUID, liveHost({ content: optionMap('10.20.10.2') }));
     expect(matches(drifted, props)).toBe(false);
   });
 
   test('category order alone is not drift — both sides normalise through the same set', () => {
-    const live = attributesOf(UUID, liveHost({ categories: 'b,a' }));
+    const live = attributesOf(UUID, liveHost({ categories: optionMap('b', 'a') }));
     const declared: AliasProps = { ...props, categories: ['a', 'b'] };
     expect(matches(live, declared)).toBe(true);
   });
@@ -79,9 +91,9 @@ describe('propsFromLive round-trip — the declaration renderer whole contract',
     // alias.ts re-exports `attributesOf` itself as `propsFromLive`; tested directly here since
     // alias.ts also wires up the Resource machinery this file does not need to import.
     const live = liveHost({
-      categories: 'c-two,c-one',
-      content: '203.0.113.0/24',
-      type: 'network',
+      categories: optionMap('c-two', 'c-one'),
+      content: optionMap('203.0.113.0/24'),
+      type: optionMap('network'),
     });
     const rendered = attributesOf(UUID, live);
     expect(matches(attributesOf(UUID, live), rendered)).toBe(true);

package/src/opnsense/alias-form.ts

@@ -18,24 +18,37 @@
  */
 import type { AliasAttributes, AliasProps } from './alias.ts';
 import type * as alias from '@distilled.cloud/opnsense/firewall_alias';
-import { bool01, csvSet, csvSetOf, numField } from './wire.ts';
+import { bool01, csvSetOf, numField, selectedOf, selectedOneOf } from './wire.ts';
 
 /**
  * ★ ATTRIBUTES AND THE DECLARATION RENDERER ARE ONE FUNCTION. Attributes ARE exactly the props a
  *   noop declaration needs — see the exported `propsFromLive` alias in alias.ts's barrel and
  *   `alias-form.test.ts`'s round-trip test (`matches(attributesOf(uuid, live), attributesOf(uuid,
  *   live))` is always true by construction, and so is the general case).
+ *
+ * `live` is `ModelAliasReadItem` (the WHOLE-MODEL `get()`'s read-shaped item), not `AliasItem` —
+ * `type`/`interface`/`proto`/`categories` decode as option maps, not strings (OPNSENSE-2; see
+ * wire.ts's module doc). `selectedOf`/`selectedOneOf` extract the selected key(s) back to the
+ * same plain-string/string[] shape `AliasAttributes` already declared.
+ *
+ * `content` is `.\AliasContentField`, which overrides `getNodeData()` independently of
+ * `BaseListField` (`Firewall/FieldTypes/AliasContentField.php:69-76`) — it still decodes as a map,
+ * but every entry is unconditionally `selected: 1` (it is a raw newline-separated list, not a
+ * real option set), and ITS wire separator is `\n`, not `,`. `Object.keys` preserves the
+ * insertion order OPNsense's own `explode()` built the map in, which matters for a host/URL list
+ * in a way `selectedOf`'s alphabetical sort does not preserve — so this one field is reconstructed
+ * directly rather than through `selectedOf`.
  */
-export const attributesOf = (uuid: string, live: alias.AliasItem): AliasAttributes => ({
-  categories: csvSet(live.categories),
-  content: live.content ?? '',
+export const attributesOf = (uuid: string, live: alias.ModelAliasReadItem): AliasAttributes => ({
+  categories: selectedOf(live.categories),
+  content: Object.keys(live.content ?? {}).join('\n'),
   counters: bool01(live.counters, false),
   description: live.description ?? '',
   enabled: bool01(live.enabled, true),
-  interface: live.interface ?? '',
+  interface: selectedOneOf(live.interface),
   name: live.name,
-  proto: live.proto ?? '',
-  type: live.type,
+  proto: selectedOf(live.proto).join(','),
+  type: selectedOneOf(live.type),
   updatefreq: numField(live.updatefreq, 0),
   uuid,
 });

package/src/opnsense/alias.test.ts

@@ -16,6 +16,7 @@ import { spec } from './alias.ts';
 import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
 import type { OpnsenseWriteRefused } from './policy.ts';
 import { opnsenseOperations } from './resource.ts';
+import { optionMap } from './wire.ts';
 
 /** `Effect.flip`'s promise resolves to the union of every error this spec can raise; every
  * refusal test below is asserting specifically on the `OpnsenseWriteRefused` member. */
@@ -30,15 +31,17 @@ const PROPS: AliasProps = {
   uuid: UUID,
 };
 
-const liveItem = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
-  content: '10.20.10.1',
+// `liveItem` builds a `ModelAliasReadItem` — the WHOLE-MODEL `get()`'s read-shaped item, whose
+// `content`/`type` decode as option maps, not strings (OPNSENSE-2 — see alias-form.ts).
+const liveItem = (overrides: Partial<alias.ModelAliasReadItem> = {}): alias.ModelAliasReadItem => ({
+  content: optionMap('10.20.10.1'),
   enabled: '1',
   name: 'homeflare_edge',
-  type: 'host',
+  type: optionMap('host'),
   ...overrides,
 });
 
-const getResponse = (items: Record<string, alias.AliasItem>) =>
+const getResponse = (items: Record<string, alias.ModelAliasReadItem>) =>
   Response.json({ alias: { aliases: { alias: items } } });
 
 describe('Opnsense.Firewall.Alias spec.fetchLive', () => {
@@ -126,7 +129,9 @@ describe('opnsenseOperations(spec).diff', () => {
   });
 
   test('update when live content drifted from the declaration — never from a read error', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ content: '10.20.10.9' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ content: optionMap('10.20.10.9') }) }),
+    );
     const result = await Effect.runPromise(
       opnsenseOperations(spec)
         .diff(PROPS, attributesOf(UUID, liveItem()))
@@ -138,7 +143,9 @@ describe('opnsenseOperations(spec).diff', () => {
 
 describe('opnsenseOperations(spec).reconcile and destroy — the read-only policy', () => {
   test('reconcile observes with one GET, then refuses — never a write', async () => {
-    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ content: 'drifted' }) }));
+    const fake = getOnlyOrFail(() =>
+      getResponse({ [UUID]: liveItem({ content: optionMap('drifted') }) }),
+    );
     const failure = asRefusal(
       await Effect.runPromise(
         Effect.flip(

package/src/opnsense/alias.ts

@@ -3,15 +3,16 @@
  * READ-ONLY BY DESIGN — see policy.ts's header. `reconcile`/`delete` always refuse.
  *
  * ★ READ GOES THROUGH `get()`, NEVER `getItem`/`searchItem`. `get()` (`firewall_alias.ts#get`)
- *   returns the WHOLE model tree — `{ alias: { aliases: { alias: { <uuid>: AliasItem, ... } } } }`
- *   — so finding one item by uuid is an object-key lookup, not a request the vendor could answer
- *   ambiguously. That sidesteps two real gaps in this early SDK, both measured against the
- *   generated `firewall_alias.ts`: (1) there is no per-item `getAlias` operation at all — only
- *   `get` (whole model) and `searchAlias` (paginated, see below) exist; (2) `firewall_category.ts`
- *   and `firewall_group.ts` DO export a `getCategory`/`getGroup`, but their generated request
- *   schema carries no `uuid` path parameter (`GetCategoryRequest`/`GetGroupRequest` are both
- *   `S.Struct({})` against a `uri` with no `{uuid}` placeholder) — a generation gap, not a design
- *   choice, so this family does not rely on them for any of the three resources, uniformly.
+ *   returns the WHOLE model tree — `{ alias: { aliases: { alias: { <uuid>: ModelAliasReadItem,
+ *   ... } } } }` — so finding one item by uuid is an object-key lookup, not a request the vendor
+ *   could answer ambiguously. `Alias` has no per-item `getAlias` operation at all (`getItemAction`
+ *   decorates its result — see the distilled clone's package README) — only `get` (whole model)
+ *   and `searchAlias` (paginated, see below) exist, so this family's whole-model read is the only
+ *   option here (unlike Category/Group, whose `getCategory`/`getGroup` per-item operations now
+ *   exist correctly — OPNSENSE-1 — but this file still uses `get()` uniformly across the three
+ *   resources; switching Category/Group to their per-item operation is a separate, later PR).
+ *   `ModelAliasReadItem`'s list-shaped fields (`type`/`interface`/`proto`/`categories`) decode as
+ *   option maps, not strings (OPNSENSE-2) — see `alias-form.ts`'s `attributesOf`.
  *
  * ⛔ NOT `searchAlias`. It is POST-shaped (a read, per OPNsense's own MVC convention — see the
  *   family's docs page) and paginated with no typed limit/offset the generated request schema
@@ -87,7 +88,12 @@ export const isOpnsenseFirewallAlias = (value: unknown): value is OpnsenseFirewa
   (value as { Type?: unknown }).Type === 'Opnsense.Firewall.Alias';
 
 /** Exported for direct testing against `fake-opnsense.ts` — the same seam `../discord/*.ts` uses. */
-export const spec: OpnsenseSpec<AliasProps, Alias.AliasItem, AliasAttributes, OpnsenseOpError> = {
+export const spec: OpnsenseSpec<
+  AliasProps,
+  Alias.ModelAliasReadItem,
+  AliasAttributes,
+  OpnsenseOpError
+> = {
   attributes: attributesOf,
   fetchLive: (props) =>
     Alias.get({}).pipe(Effect.map((res) => res.alias?.aliases?.alias?.[props.uuid])),

package/src/opnsense/group-form.test.ts

@@ -1,16 +1,20 @@
 /**
- * `group-form.ts`'s pure functions against literal `GroupItem` fixtures — no network.
+ * `group-form.ts`'s pure functions against literal `ModelIfgroupentryReadItem` fixtures (the
+ * WHOLE-MODEL `get()`'s read-shaped item — `members` is an option map, OPNSENSE-2) — no network.
  */
 import { describe, expect, test } from 'bun:test';
 import type * as group from '@distilled.cloud/opnsense/firewall_group';
 import { attributesOf, matches } from './group-form.ts';
 import type { GroupProps } from './group.ts';
+import { optionMap } from './wire.ts';
 
 const UUID = '33333333-3333-3333-3333-333333333333';
 
-const liveGroup = (overrides: Partial<group.GroupItem> = {}): group.GroupItem => ({
+const liveGroup = (
+  overrides: Partial<group.ModelIfgroupentryReadItem> = {},
+): group.ModelIfgroupentryReadItem => ({
   ifname: 'IOT_DEVICES',
-  members: 'opt1,opt2',
+  members: optionMap('opt1', 'opt2'),
   sequence: '1',
   ...overrides,
 });
@@ -27,8 +31,8 @@ describe('group-form attributesOf', () => {
     });
   });
 
-  test('members are split, sorted and deduplicated', () => {
-    const live = liveGroup({ members: 'opt2,opt1,opt1' });
+  test('members are the selected keys, sorted and deduplicated', () => {
+    const live = liveGroup({ members: optionMap('opt2', 'opt1') });
     expect(attributesOf(UUID, live).members).toEqual(['opt1', 'opt2']);
   });
 
@@ -50,13 +54,13 @@ describe('group-form matches', () => {
   });
 
   test('member-list order alone is not drift', () => {
-    const live = attributesOf(UUID, liveGroup({ members: 'opt2,opt1' }));
+    const live = attributesOf(UUID, liveGroup({ members: optionMap('opt2', 'opt1') }));
     const declared: GroupProps = { ...props, members: ['opt1', 'opt2'] };
     expect(matches(live, declared)).toBe(true);
   });
 
   test('a removed member is drift', () => {
-    const live = attributesOf(UUID, liveGroup({ members: 'opt1' }));
+    const live = attributesOf(UUID, liveGroup({ members: optionMap('opt1') }));
     expect(matches(live, props)).toBe(false);
   });
 });
@@ -65,7 +69,7 @@ describe('propsFromLive round-trip', () => {
   test('the props it returns plan noop against the exact live object they came from', () => {
     const live = liveGroup({
       descr: 'IoT VLANs',
-      members: 'opt3,opt1,opt2',
+      members: optionMap('opt3', 'opt1', 'opt2'),
       nogroup: '1',
       sequence: '5',
     });

package/src/opnsense/group-form.ts

@@ -5,13 +5,22 @@
  */
 import type { GroupAttributes, GroupProps } from './group.ts';
 import type * as group from '@distilled.cloud/opnsense/firewall_group';
-import { bool01, csvSet, csvSetOf, numField } from './wire.ts';
+import { bool01, csvSetOf, numField, selectedOf } from './wire.ts';
 
-/** ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note. */
-export const attributesOf = (uuid: string, live: group.GroupItem): GroupAttributes => ({
+/**
+ * ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note.
+ *
+ * `live` is `ModelIfgroupentryReadItem` (the WHOLE-MODEL `get()`'s read-shaped item), not
+ * `GroupItem` — `members` (`.\InterfaceField`, `Multiple="Y"`) decodes as an option map, not a
+ * comma string (OPNSENSE-2; see wire.ts's module doc).
+ */
+export const attributesOf = (
+  uuid: string,
+  live: group.ModelIfgroupentryReadItem,
+): GroupAttributes => ({
   description: live.descr ?? '',
   ifname: live.ifname,
-  members: csvSet(live.members),
+  members: selectedOf(live.members),
   nogroup: bool01(live.nogroup, false),
   sequence: numField(live.sequence, 0),
   uuid,