@homeflare/alchemy 0.31.1 → 0.32.0

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

@@ -0,0 +1,89 @@
+/**
+ * `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.
+ */
+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';
+
+const UUID = '11111111-1111-1111-1111-111111111111';
+
+const liveHost = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
+  content: '10.20.10.1',
+  enabled: '1',
+  name: 'homeflare_edge',
+  type: 'host',
+  ...overrides,
+});
+
+describe('alias-form attributesOf', () => {
+  test('settles OPNsense wire spellings to plain values', () => {
+    expect(attributesOf(UUID, liveHost())).toEqual({
+      categories: [],
+      content: '10.20.10.1',
+      counters: false,
+      description: '',
+      enabled: true,
+      interface: '',
+      name: 'homeflare_edge',
+      proto: '',
+      type: 'host',
+      updatefreq: 0,
+      uuid: UUID,
+    });
+  });
+
+  test('"0" is disabled, not absent', () => {
+    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' });
+    expect(attributesOf(UUID, live).categories).toEqual(['c-one', 'c-two']);
+  });
+});
+
+describe('alias-form matches', () => {
+  const props: AliasProps = {
+    content: '10.20.10.1',
+    name: 'homeflare_edge',
+    type: 'host',
+    uuid: UUID,
+  };
+
+  test('a live item decoded through attributesOf matches its own declaration', () => {
+    expect(matches(attributesOf(UUID, liveHost()), props)).toBe(true);
+  });
+
+  test('content drift is caught', () => {
+    const drifted = attributesOf(UUID, liveHost({ content: '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 declared: AliasProps = { ...props, categories: ['a', 'b'] };
+    expect(matches(live, declared)).toBe(true);
+  });
+
+  test('an undeclared optional field takes its settled default, not a mismatch', () => {
+    // `proto`/`interface`/`description` etc. are absent from `props` here; `liveHost()` also
+    // never sets them, so both sides settle to the same empty defaults.
+    expect(matches(attributesOf(UUID, liveHost()), props)).toBe(true);
+  });
+});
+
+describe('propsFromLive round-trip — the declaration renderer whole contract', () => {
+  test('the props it returns plan noop against the exact live object they came from', () => {
+    // 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',
+    });
+    const rendered = attributesOf(UUID, live);
+    expect(matches(attributesOf(UUID, live), rendered)).toBe(true);
+  });
+});

package/src/opnsense/alias-form.ts

@@ -0,0 +1,53 @@
+/**
+ * `Opnsense.Firewall.Alias`'s wire shape: how a live `AliasItem` becomes attributes, and the
+ * comparison that decides whether a declaration already matches it. Split out of alias.ts to
+ * keep that file under the house's 250-line cap, mirroring `../proxmox/user-wire.ts`.
+ *
+ * ⛔ SCOPE, STATED ONCE. `AliasItem` (firewall_alias.ts) carries far more fields than this props
+ *   type declares — three groups are left out on purpose:
+ *     1. Runtime counters (`current_items`, `last_updated`, `eval_nomatch`, `eval_match`,
+ *        `in_block_p`/`_b`, `in_pass_p`/`_b`, `out_block_p`/`_b`, `out_pass_p`/`_b`) — these are
+ *        the alias's hit/block statistics, not configuration, exactly the "stats" the task that
+ *        opened this family says to exclude.
+ *     2. `path_expression` — only meaningful for the `urljson` alias type; a niche field this
+ *        first import pass leaves for a later one rather than modelling one type's one field.
+ *     3. `password`/`username`/`authtype`/`expire` — the URL-fetch credential fields for the
+ *        `url`/`urltable`/`urljson` alias types. S25 (secrets stay out of props/attributes):
+ *        `password` is a literal stored credential and Alchemy persists Attributes unencrypted,
+ *        the same reasoning `../proxmox/user.ts` gives for shipping no `password` prop at all.
+ */
+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';
+
+/**
+ * ★ 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).
+ */
+export const attributesOf = (uuid: string, live: alias.AliasItem): AliasAttributes => ({
+  categories: csvSet(live.categories),
+  content: live.content ?? '',
+  counters: bool01(live.counters, false),
+  description: live.description ?? '',
+  enabled: bool01(live.enabled, true),
+  interface: live.interface ?? '',
+  name: live.name,
+  proto: live.proto ?? '',
+  type: live.type,
+  updatefreq: numField(live.updatefreq, 0),
+  uuid,
+});
+
+export const matches = (attributes: AliasAttributes, props: AliasProps): boolean =>
+  attributes.name === props.name &&
+  attributes.type === props.type &&
+  attributes.enabled === (props.enabled ?? true) &&
+  attributes.content === (props.content ?? '') &&
+  attributes.interface === (props.interface ?? '') &&
+  attributes.proto === (props.proto ?? '') &&
+  attributes.counters === (props.counters ?? false) &&
+  attributes.updatefreq === (props.updatefreq ?? 0) &&
+  attributes.description === (props.description ?? '') &&
+  attributes.categories.join(',') === csvSetOf(props.categories).join(',');

package/src/opnsense/alias.test.ts

@@ -0,0 +1,203 @@
+/**
+ * `Opnsense.Firewall.Alias`'s `spec` against a fake OPNsense, proving the real distilled wire
+ * path — path assembly, JSON decode and typed-error propagation — exercised through
+ * `@distilled.cloud/opnsense/firewall_alias`'s real `get`, never re-implemented here. Also proves
+ * `opnsenseOperations(spec)`'s read/diff/reconcile/destroy flow (resource.ts), the exact object
+ * `opnsenseHandlers` wraps into `OpnsenseFirewallAliasProvider`. Mirrors
+ * `../discord/guild-application-command.test.ts`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type * as alias from '@distilled.cloud/opnsense/firewall_alias';
+import * as Effect from 'effect/Effect';
+import { attributesOf } from './alias-form.ts';
+import type { AliasProps } from './alias.ts';
+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';
+
+/** `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. */
+const asRefusal = (value: unknown) => value as OpnsenseWriteRefused;
+
+const UUID = '11111111-1111-1111-1111-111111111111';
+const GET_PATH = '/api/firewall/alias/get';
+const PROPS: AliasProps = {
+  content: '10.20.10.1',
+  name: 'homeflare_edge',
+  type: 'host',
+  uuid: UUID,
+};
+
+const liveItem = (overrides: Partial<alias.AliasItem> = {}): alias.AliasItem => ({
+  content: '10.20.10.1',
+  enabled: '1',
+  name: 'homeflare_edge',
+  type: 'host',
+  ...overrides,
+});
+
+const getResponse = (items: Record<string, alias.AliasItem>) =>
+  Response.json({ alias: { aliases: { alias: items } } });
+
+describe('Opnsense.Firewall.Alias spec.fetchLive', () => {
+  test('finds the item whose uuid is the map key, among others', async () => {
+    const fake = getOnlyOrFail((url) =>
+      url.pathname === GET_PATH
+        ? getResponse({ 'other-uuid': liveItem({ name: 'other' }), [UUID]: liveItem() })
+        : fakeFailure(400, { errorMessage: 'unexpected request' }),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live?.name).toBe('homeflare_edge');
+    expect(fake.seen).toHaveLength(1);
+  });
+
+  test('no matching uuid key is absent, not an error', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ 'other-uuid': liveItem() }));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('an empty model (no aliases section at all) is absent, not a crash', async () => {
+    const fake = getOnlyOrFail(() => Response.json({ alias: {} }));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 401 propagates — never folded to absent (the live bug this family avoids)', async () => {
+    const fake = fakeOpnsense(() => fakeFailure(401, { message: 'Unauthorized' }));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('opnsenseOperations(spec).read — S7/S8, marker-less API', () => {
+  test('cold read (no output) answers Unowned', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const attrs = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(attrs).toBeDefined();
+    expect(Unowned.is(attrs)).toBe(true);
+  });
+
+  test('warm read (output already ours) answers plain attributes', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const priorOutput = attributesOf(UUID, liveItem());
+    const attrs = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: priorOutput })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(Unowned.is(attrs)).toBe(false);
+  });
+
+  test('absent is undefined either way', async () => {
+    const fake = getOnlyOrFail(() => getResponse({}));
+    const attrs = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(attrs).toBeUndefined();
+  });
+});
+
+describe('opnsenseOperations(spec).diff', () => {
+  test('noop when the declaration already matches live', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff(PROPS, attributesOf(UUID, liveItem()))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  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 result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff(PROPS, attributesOf(UUID, liveItem()))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});
+
+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 failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .reconcile(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure._tag).toBe('OpnsenseWriteRefused');
+    expect(failure.action).toBe('update');
+    expect(fake.seen).toHaveLength(1);
+    expect(fake.seen[0]?.method).toBe('GET');
+  });
+
+  test('reconcile against an absent uuid reports it would have created', async () => {
+    const fake = getOnlyOrFail(() => getResponse({}));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .reconcile(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure.action).toBe('create');
+  });
+
+  // ⛔ THE ONE CASE THAT MATTERS MOST: a genuine failure of the observe step (auth, network,
+  //   a vendor error) must propagate AS ITSELF, never get swallowed and re-reported as the
+  //   write-refusal — the same "only a genuine not-found may mean absent; every other error
+  //   fails loudly" rule this family exists to honour, extended to reconcile's own observe.
+  test('reconcile propagates a genuine read failure — never masks it as the write-refusal', async () => {
+    const fake = fakeOpnsense(() => fakeFailure(401, { message: 'Unauthorized' }));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        opnsenseOperations(spec)
+          .reconcile(PROPS)
+          .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+    expect(failure._tag).not.toBe('OpnsenseWriteRefused');
+  });
+
+  test('delete refuses unconditionally, with zero requests', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .destroy(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure._tag).toBe('OpnsenseWriteRefused');
+    expect(failure.action).toBe('delete');
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/opnsense/alias.ts

@@ -0,0 +1,117 @@
+/**
+ * `Opnsense.Firewall.Alias` — a read-only declaration of one `firewall/alias` item on the edge.
+ * 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.
+ *
+ * ⛔ 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
+ *   exposes, so a large alias set could silently page-truncate through it. `get()` has neither
+ *   problem: GET, and the WHOLE model in one call, no pagination to fall short of.
+ *
+ * ⚠️ `uuid` IS THE ONLY STABLE IDENTITY THIS FAMILY DECLARES BY. A name is close to stable
+ *   (`AliasNameField` is unique) but is not what `get()`'s map is keyed on — obtain the live
+ *   uuid once (a future import script does this from a live read, via `propsFromLive` below)
+ *   and declare it from then on, the same "adoption is explicit, one identity at a time" posture
+ *   `../proxmox/user.ts` and `../netbox/resource.ts` document for their own families.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Alias from '@distilled.cloud/opnsense/firewall_alias';
+import type { OpnsenseOpError } from '@distilled.cloud/opnsense/Protocol';
+import * as Effect from 'effect/Effect';
+import { attributesOf, matches } from './alias-form.ts';
+import type { OpnsenseRequirements, OpnsenseSpec } from './resource.ts';
+import { opnsenseHandlers } from './resource.ts';
+
+export interface AliasProps {
+  /** OPNsense-assigned uuid — see the file header on why this is the only identity to declare by. */
+  readonly uuid: string;
+  readonly name: string;
+  /** e.g. `host`, `network`, `port`, `url`, `geoip`, `networkgroup` — OPNsense's own alias types. */
+  readonly type: string;
+  /** Default true, matching OPNsense's own `enabled=1`. */
+  readonly enabled?: boolean;
+  /** The alias's members — a host list, a CIDR, a URL, depending on `type`. */
+  readonly content?: string;
+  readonly interface?: string;
+  /** `IPv4` or `IPv6`, for a `geoip`/`networkgroup` alias; comma-joined on the wire (wire.ts). */
+  readonly proto?: string;
+  readonly counters?: boolean;
+  /** Minutes between refreshes, for a `url`/`urltable` alias. */
+  readonly updatefreq?: number;
+  readonly categories?: readonly string[];
+  readonly description?: string;
+}
+
+export interface AliasAttributes {
+  readonly uuid: string;
+  readonly name: string;
+  readonly type: string;
+  readonly enabled: boolean;
+  readonly content: string;
+  readonly interface: string;
+  readonly proto: string;
+  readonly counters: boolean;
+  readonly updatefreq: number;
+  readonly categories: readonly string[];
+  readonly description: string;
+}
+
+export interface OpnsenseFirewallAlias extends Resource<
+  'Opnsense.Firewall.Alias',
+  AliasProps,
+  AliasAttributes,
+  never,
+  OpnsenseRequirements
+> {}
+
+export const OpnsenseFirewallAlias = Resource<OpnsenseFirewallAlias>('Opnsense.Firewall.Alias', {
+  // The edge's own config, not this stack's to reclaim — see policy.ts.
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isOpnsenseFirewallAlias = (value: unknown): value is OpnsenseFirewallAlias =>
+  typeof value === 'object' &&
+  value !== null &&
+  (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> = {
+  attributes: attributesOf,
+  fetchLive: (props) =>
+    Alias.get({}).pipe(Effect.map((res) => res.alias?.aliases?.alias?.[props.uuid])),
+  matches,
+  resourceType: 'Opnsense.Firewall.Alias',
+};
+
+/**
+ * The pure declaration renderer: given the uuid `get()`'s map key names and the `AliasItem`
+ * decoded at that key, return the props a declaration needs so `firewallAlias.spec.matches`
+ * reports noop against it. A later import script iterates `Object.entries(map)` and calls this
+ * once per row to generate an `alchemy.run.ts` row — see `alias-form.test.ts`'s round-trip test.
+ */
+export const propsFromLive = attributesOf;
+
+export const handlers = opnsenseHandlers(spec);
+
+export const OpnsenseFirewallAliasProvider = () =>
+  Provider.effect(
+    OpnsenseFirewallAlias,
+    Effect.succeed(OpnsenseFirewallAlias.Provider.of(handlers)),
+  );
+
+/** `firewallAlias('name-alias', { uuid, name, type })` — `adopt(true)` piped by default (H5), so
+ * declaring a live alias's own uuid takes it over silently instead of failing `OwnedBySomeoneElse`. */
+export const firewallAlias = (id: string, props: AliasProps) =>
+  OpnsenseFirewallAlias(id, props).pipe(adopt(true));

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

@@ -0,0 +1,54 @@
+/**
+ * `category-form.ts`'s pure functions against literal `CategoryItem` fixtures — no network.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as category from '@distilled.cloud/opnsense/firewall_category';
+import { attributesOf, matches } from './category-form.ts';
+import type { CategoryProps } from './category.ts';
+
+const UUID = '22222222-2222-2222-2222-222222222222';
+
+const liveCategory = (overrides: Partial<category.CategoryItem> = {}): category.CategoryItem => ({
+  name: 'vpn-clients',
+  ...overrides,
+});
+
+describe('category-form attributesOf', () => {
+  test('settles OPNsense wire spellings to plain values', () => {
+    expect(attributesOf(UUID, liveCategory())).toEqual({
+      auto: false,
+      color: '',
+      name: 'vpn-clients',
+      uuid: UUID,
+    });
+  });
+
+  test('auto="1" is the OPNsense-created flag, not absent', () => {
+    expect(attributesOf(UUID, liveCategory({ auto: '1' })).auto).toBe(true);
+  });
+
+  test('a declared color is passed through', () => {
+    expect(attributesOf(UUID, liveCategory({ color: '0000FF' })).color).toBe('0000FF');
+  });
+});
+
+describe('category-form matches', () => {
+  const props: CategoryProps = { name: 'vpn-clients', uuid: UUID };
+
+  test('a live item decoded through attributesOf matches its own declaration', () => {
+    expect(matches(attributesOf(UUID, liveCategory()), props)).toBe(true);
+  });
+
+  test('a renamed category is drift', () => {
+    const drifted = attributesOf(UUID, liveCategory({ name: 'renamed' }));
+    expect(matches(drifted, props)).toBe(false);
+  });
+});
+
+describe('propsFromLive round-trip', () => {
+  test('the props it returns plan noop against the exact live object they came from', () => {
+    const live = liveCategory({ auto: '1', color: 'FF0000' });
+    const rendered = attributesOf(UUID, live);
+    expect(matches(attributesOf(UUID, live), rendered)).toBe(true);
+  });
+});

package/src/opnsense/category-form.ts

@@ -0,0 +1,20 @@
+/**
+ * `Opnsense.Firewall.Category`'s wire shape: how a live `CategoryItem` becomes attributes, and
+ * the comparison that decides whether a declaration already matches it. Mirrors alias-form.ts.
+ */
+import type { CategoryAttributes, CategoryProps } from './category.ts';
+import type * as category from '@distilled.cloud/opnsense/firewall_category';
+import { bool01 } from './wire.ts';
+
+/** ★ Attributes and the declaration renderer are one function — see alias-form.ts's header note. */
+export const attributesOf = (uuid: string, live: category.CategoryItem): CategoryAttributes => ({
+  auto: bool01(live.auto, false),
+  color: live.color ?? '',
+  name: live.name,
+  uuid,
+});
+
+export const matches = (attributes: CategoryAttributes, props: CategoryProps): boolean =>
+  attributes.name === props.name &&
+  attributes.auto === (props.auto ?? false) &&
+  attributes.color === (props.color ?? '');

package/src/opnsense/category.test.ts

@@ -0,0 +1,138 @@
+/**
+ * `Opnsense.Firewall.Category`'s `spec` against a fake OPNsense — mirrors `alias.test.ts` for the
+ * category family. See that file's header for what each block proves.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type * as category from '@distilled.cloud/opnsense/firewall_category';
+import * as Effect from 'effect/Effect';
+import { attributesOf } from './category-form.ts';
+import type { CategoryProps } from './category.ts';
+import { spec } from './category.ts';
+import { fakeFailure, fakeOpnsense, fakeOpnsenseLayer, getOnlyOrFail } from './fake-opnsense.ts';
+import type { OpnsenseWriteRefused } from './policy.ts';
+import { opnsenseOperations } from './resource.ts';
+
+const asRefusal = (value: unknown) => value as OpnsenseWriteRefused;
+
+const UUID = '22222222-2222-2222-2222-222222222222';
+const GET_PATH = '/api/firewall/category/get';
+const PROPS: CategoryProps = { name: 'vpn-clients', uuid: UUID };
+
+const liveItem = (overrides: Partial<category.CategoryItem> = {}): category.CategoryItem => ({
+  name: 'vpn-clients',
+  ...overrides,
+});
+
+const getResponse = (items: Record<string, category.CategoryItem>) =>
+  Response.json({ category: { categories: { category: items } } });
+
+describe('Opnsense.Firewall.Category spec.fetchLive', () => {
+  test('finds the item whose uuid is the map key, among others', async () => {
+    const fake = getOnlyOrFail((url) =>
+      url.pathname === GET_PATH
+        ? getResponse({ 'other-uuid': liveItem({ name: 'other' }), [UUID]: liveItem() })
+        : fakeFailure(400, { errorMessage: 'unexpected request' }),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live?.name).toBe('vpn-clients');
+  });
+
+  test('no matching uuid key is absent, not an error', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ 'other-uuid': liveItem() }));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  // ⚠️ 403, NOT 500: a 5xx is a transient-error tag the SDK's default retry policy (retry.ts)
+  //   retries with backoff (S26) — a real, useful behaviour, but one that would make this test
+  //   itself slow. 403 (`Forbidden`, OPNsense's own auth-gate shape — protocol.ts) is not
+  //   retried, so the propagation is provable in one request.
+  test('a 403 propagates — never folded to absent (the live bug this family avoids)', async () => {
+    const fake = fakeOpnsense(() => fakeFailure(403, { message: 'Forbidden' }));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(PROPS).pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('opnsenseOperations(spec).read — S7/S8, marker-less API', () => {
+  test('cold read answers Unowned; warm read answers plain attributes', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const cold = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: undefined })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(Unowned.is(cold)).toBe(true);
+
+    const fakeWarm = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const warm = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .read({ olds: PROPS, output: attributesOf(UUID, liveItem()) })
+        .pipe(Effect.provide(fakeOpnsenseLayer(fakeWarm.fetch))),
+    );
+    expect(Unowned.is(warm)).toBe(false);
+  });
+});
+
+describe('opnsenseOperations(spec).diff', () => {
+  test('noop when the declaration already matches live', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff(PROPS, attributesOf(UUID, liveItem()))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('update when the live color drifted', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem({ color: 'FF0000' }) }));
+    const result = await Effect.runPromise(
+      opnsenseOperations(spec)
+        .diff({ ...PROPS, color: '0000FF' }, attributesOf(UUID, liveItem({ color: '0000FF' })))
+        .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+    );
+    expect(result).toEqual({ action: 'update' });
+  });
+});
+
+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({ name: 'drifted' }) }));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .reconcile(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure._tag).toBe('OpnsenseWriteRefused');
+    expect(failure.action).toBe('update');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+    expect(fake.seen).toHaveLength(1);
+  });
+
+  test('delete refuses unconditionally, with zero requests', async () => {
+    const fake = getOnlyOrFail(() => getResponse({ [UUID]: liveItem() }));
+    const failure = asRefusal(
+      await Effect.runPromise(
+        Effect.flip(
+          opnsenseOperations(spec)
+            .destroy(PROPS)
+            .pipe(Effect.provide(fakeOpnsenseLayer(fake.fetch))),
+        ),
+      ),
+    );
+    expect(failure.action).toBe('delete');
+    expect(fake.seen).toHaveLength(0);
+  });
+});