@homeflare/alchemy 0.31.1 → 0.32.0

package/src/unifi/network.test.ts

@@ -0,0 +1,209 @@
+/**
+ * `Unifi.Network`'s `spec` against a fake UniFi Network API, proving the real distilled wire
+ * path (path assembly, JSON decode, `NotFound` folding), the declaration renderer, and — the
+ * task's own requirement — that no handler this family exposes ever sends a non-`GET` request.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as networks from '@distilled.cloud/unifi-network/networks';
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+import { attributesOf, matches } from './network-form.ts';
+import { type NetworkProps, declareNetwork, spec } from './network.ts';
+import { unifiOperations } from './resource.ts';
+
+const NETWORK_PATH = '/proxy/network/integration/v1/sites/site-1/networks/net-1';
+
+const liveNetwork = (
+  overrides: Partial<networks.NetworkDetails> = {},
+): networks.NetworkDetails => ({
+  default: false,
+  enabled: true,
+  id: 'net-1',
+  management: 'ADVANCED',
+  metadata: { origin: 'USER' },
+  name: 'Cameras',
+  vlanId: 40,
+  isolationEnabled: true,
+  zoneId: 'zone-1',
+  ...overrides,
+});
+
+const PROPS: NetworkProps = {
+  siteId: 'site-1',
+  networkId: 'net-1',
+  name: 'Cameras',
+  enabled: true,
+  management: 'ADVANCED',
+  vlanId: 40,
+  isolationEnabled: true,
+  zoneId: 'zone-1',
+};
+
+describe('Unifi.Network spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('net-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: NETWORK_PATH }]);
+  });
+
+  test('a genuine 404 folds to undefined -- never a false "unreadable" on anything else', async () => {
+    const fake = fakeUnifi(() => fakeFailure(404, 'not found'));
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live).toBeUndefined();
+  });
+
+  test('a 500 fails loudly -- only a genuine not-found may mean absent', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 (one of core's DEFAULT_ERROR_STATUSES)
+    //   indefinitely with backoff -- this test asserts the FAILURE, not the retry schedule.
+    const fake = fakeUnifi(() => fakeFailure(500, 'boom'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive(PROPS).pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('InternalServerError');
+  });
+});
+
+describe('declareNetwork -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    const live = liveNetwork({ name: 'Guest', vlanId: 99, isolationEnabled: false });
+    const declared = declareNetwork(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+  });
+});
+
+describe('matches -- unordered arrays (dhcpGuarding, ipv6Configuration)', () => {
+  // ⛔ `deepEqual` (alchemy/Diff) sorts object keys but not array elements: without normalizing
+  //   these three fields (see network-form.ts's header), a console returning the same set in a
+  //   different order would plan a spurious update.
+  test('the same trusted DHCP servers in a different order is a noop', () => {
+    const live = liveNetwork({
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.2', '10.0.0.1'] },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.2'] },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+  });
+
+  test('a different set of trusted DHCP servers is an update', () => {
+    const live = liveNetwork({
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.2'] },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      dhcpGuarding: { trustedDhcpServerIpAddresses: ['10.0.0.1', '10.0.0.3'] },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(false);
+  });
+
+  test('the same IPv6 host subnets and DNS overrides in a different order is a noop', () => {
+    const live = liveNetwork({
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:1::/64'],
+        dnsServerIpAddressesOverride: ['2001:4860:4860::8888', '2001:4860:4860::8844'],
+      },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8:1::/64', '2001:db8::/64'],
+        dnsServerIpAddressesOverride: ['2001:4860:4860::8844', '2001:4860:4860::8888'],
+      },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(true);
+  });
+
+  test('a different set of IPv6 host subnets is an update', () => {
+    const live = liveNetwork({
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:1::/64'],
+      },
+    });
+    const props: NetworkProps = {
+      ...PROPS,
+      ipv6Configuration: {
+        clientAddressAssignment: { slaacEnabled: true },
+        interfaceType: 'ETHERNET',
+        additionalHostIpSubnets: ['2001:db8::/64', '2001:db8:2::/64'],
+      },
+    };
+    expect(matches(attributesOf(live, props), props)).toBe(false);
+  });
+
+  test('a live `null` (not `undefined`) for either field does not throw', () => {
+    // UniFi's JSON answers `null` for an unset optional field (see network-form.ts's header) —
+    // a reality the SDK's `T | undefined` types don't model. The double cast lands `null` at
+    // runtime the same way a real JSON decode would, past what the type system alone allows.
+    const live = {
+      ...liveNetwork(),
+      dhcpGuarding: null,
+      ipv6Configuration: null,
+    } as unknown as networks.NetworkDetails;
+    const declared = declareNetwork(live, 'site-1');
+    expect(() => attributesOf(live, declared)).not.toThrow();
+    expect(matches(attributesOf(live, declared), declared)).toBe(true);
+  });
+});
+
+describe('Unifi.Network write paths never reach the vendor API', () => {
+  const ops = unifiOperations(spec);
+
+  test('reconcile on an exact-match adoption (H6) makes no request but the one read', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Success');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('reconcile on drift refuses instead of PUTting a merged body', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork({ vlanId: 999 }))
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+
+  test('delete always refuses -- no DELETE is ever sent', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === NETWORK_PATH
+        ? Response.json(liveNetwork())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const exit = await Effect.runPromiseExit(
+      ops.destroy(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(fake.seen).toEqual([]);
+  });
+});

package/src/unifi/network.ts

@@ -0,0 +1,83 @@
+/**
+ * `Unifi.Network` — one network on a UniFi Network site, READ-ONLY (`policy.ts`).
+ *
+ * ★ WHY NETWORK IS IN THE FIRST IMPORT SET. `getNetworkDetails`/`getNetworksOverviewPage`
+ *   (`../../distilled-unifi-network/src/services/networks.ts`) is a list+get pair over
+ *   genuine configuration — VLAN, DHCP guarding, IPv4/IPv6 addressing, isolation — not runtime
+ *   state like a connected client, a device statistic or a hotspot voucher. It is also the SDK
+ *   package's own README recommendation for a first read/adopt-only resource, alongside `Site`
+ *   (skipped here — no `getSite`, only the list operation, so it fails this task's own "both a
+ *   list and a get" bar) and `FirewallZone`/`FirewallPolicy` (`firewall-zone.ts` ships
+ *   `FirewallZone`; `FirewallPolicy`'s several discriminated filter variants and its
+ *   list-replacing ordering endpoint are a bigger, separate PR).
+ *
+ * ⛔ THE WHOLE-OBJECT-PUT TRAP (`docs/unifi-api-notes.md`) NEVER FIRES HERE, BY CONSTRUCTION.
+ *   `updateNetwork` is a `PUT` that disables `dhcpGuarding`/`ipv4Configuration`/`ipv6Configuration`
+ *   outright when the caller omits them — the exact failure mode a read-only family cannot cause,
+ *   because `resource.ts`'s `reconcile` never calls `updateNetwork` at all. Recorded here for
+ *   whoever adds the write path this docs note anticipates: read-merge-write the WHOLE object,
+ *   never a props-only body.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as networks from '@distilled.cloud/unifi-network/networks';
+import * as Effect from 'effect/Effect';
+import {
+  type NetworkAttributes,
+  type NetworkProps,
+  attributesOf,
+  matches,
+} from './network-form.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { NetworkAttributes, NetworkProps } from './network-form.ts';
+export { declareNetwork } from './network-form.ts';
+
+export interface UnifiNetwork extends Resource<
+  'Unifi.Network',
+  NetworkProps,
+  NetworkAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiNetwork = Resource<UnifiNetwork>('Unifi.Network', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * `network('lan', props)` — `adopt(true)` piped on by default (H5). This family never writes, so
+ * the only thing a first deploy against an existing network could ever do is bind to it or refuse
+ * `OwnedBySomeoneElse`; piping `adopt(true)` here picks the former without a stack having to
+ * remember `--adopt`, mirroring `discord/application-command.ts`'s `applicationCommand`.
+ */
+export const network = (id: string, props: NetworkProps) =>
+  UnifiNetwork(id, props).pipe(adopt(true));
+
+/**
+ * ★ EXPORTED for direct testing against a fake `Credentials` layer (`fake-unifi.ts`), the same
+ *   seam `netbox/prefix.ts`'s `spec` and `discord/application-command.ts`'s `spec` use — `handlers`
+ *   bakes in `CredentialsFromEnv`, which resolves environment variables a test cannot repoint.
+ */
+export const spec: UnifiSpec<
+  NetworkProps,
+  networks.NetworkDetails,
+  NetworkAttributes,
+  networks.GetNetworkDetailsError
+> = {
+  type: 'Unifi.Network',
+  describe: (props) => `sites/${props.siteId}/networks/${props.networkId}`,
+  fetchLive: (props) =>
+    networks
+      .getNetworkDetails({ siteId: props.siteId, networkId: props.networkId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiNetworkProvider = () =>
+  Provider.effect(UnifiNetwork, Effect.succeed(UnifiNetwork.Provider.of(handlers)));

package/src/unifi/policy.ts

@@ -0,0 +1,37 @@
+/**
+ * The one refusal every `Unifi.*` write handler returns — never an SDK write call.
+ *
+ * ⛔ TIM'S RULE, 2026-09-24: UniFi (and OPNsense) are READ-ONLY FOR NOW. This family has no
+ *   `create`, no `update` body and no delete call anywhere in its source — `reconcile` and
+ *   `delete` both fail with this typed error instead, and `resource.test.ts` proves the point
+ *   with a fake `HttpClient` that fails the test on any request that is not a `GET`. Lifting the
+ *   policy is a kit change (a new PR that adds a write path, 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.
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+export const UNIFI_READ_ONLY_POLICY =
+  "read-only by Tim's rule, 2026-09-24; lifting it is a kit change";
+
+/** What kind of write was asked for and refused — for the message only, never acted on. */
+export type UnifiWriteAction = 'create' | 'update' | 'delete';
+
+export class UnifiWriteRefused extends Data.TaggedError('UnifiWriteRefused')<{
+  /** The vendor type string, e.g. `Unifi.Network`. */
+  readonly type: string;
+  /** `spec.describe(props)` — the object the write would have touched. */
+  readonly identity: string;
+  readonly action: UnifiWriteAction;
+}> {
+  override get message(): string {
+    return `${this.type} ${this.identity}: refusing to ${this.action} -- ${UNIFI_READ_ONLY_POLICY}.`;
+  }
+}
+
+/** The only thing `reconcile`/`delete` ever return for a write this family cannot make. */
+export const refuseWrite = (type: string, identity: string, action: UnifiWriteAction) =>
+  Effect.fail(new UnifiWriteRefused({ type, identity, action }));

package/src/unifi/providers.ts

@@ -0,0 +1,15 @@
+/**
+ * Every `Unifi.*` provider as one layer for a stack.
+ *
+ *     Layer.mergeAll(unifiProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * S16: a subpath's `providers()` plays the role upstream's own `Providers.ts` does — one minimal
+ * insertion per family. `FetchHttpClient.layer` is the stack's own responsibility to provide,
+ * mirroring `../discord/providers.ts`.
+ */
+import * as Layer from 'effect/Layer';
+import { UnifiFirewallZoneProvider } from './firewall-zone.ts';
+import { UnifiNetworkProvider } from './network.ts';
+
+export const providers = () => Layer.mergeAll(UnifiNetworkProvider(), UnifiFirewallZoneProvider());

package/src/unifi/resource.test.ts

@@ -0,0 +1,133 @@
+/**
+ * `unifiOperations` in isolation, against a synthetic spec — no real UniFi SDK, no HTTP. Proves
+ * the read-only engine's own contract: `Unowned` on a cold read (H1), `noop`/`update` diff,
+ * `reconcile` succeeding with ZERO write calls on an exact match (the H6 forced post-adoption
+ * call this engine has to survive without writing), and a typed `UnifiWriteRefused` — never a
+ * silent success, never a raw SDK write — every other time `reconcile` or `delete` runs.
+ *
+ * `network.test.ts`/`firewall-zone.test.ts` prove the same contract again against the REAL SDK
+ * and a fake HTTP server, and additionally prove that no non-`GET` request is ever sent.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import { fakeUnifiLayer } from './fake-unifi.ts';
+import { UnifiWriteRefused } from './policy.ts';
+import { type UnifiSpec, unifiOperations } from './resource.ts';
+
+interface WidgetProps {
+  id: string;
+  value: number;
+}
+type WidgetLive = WidgetProps;
+type WidgetAttrs = WidgetProps;
+
+/** `live: undefined` models a declared object nothing on the site matches. */
+const specFor = (
+  live: WidgetLive | undefined,
+): UnifiSpec<WidgetProps, WidgetLive, WidgetAttrs, never> => ({
+  type: 'Test.Widget',
+  describe: (props) => `widgets/${props.id}`,
+  fetchLive: () => Effect.succeed(live),
+  attributes: (l) => l,
+  matches: (attrs, props) => attrs.value === props.value,
+});
+
+const MATCH: WidgetProps = { id: 'w1', value: 1 };
+const DRIFTED_LIVE: WidgetLive = { id: 'w1', value: 99 };
+
+/**
+ * `UnifiSpec`'s `fetchLive` is typed against the real `UnifiNetworkOpContext` (`resource.ts`'s
+ * own header explains why the engine is not generic over it) even though `specFor` above never
+ * touches HTTP — so every run here still needs A layer satisfying that context. This one fails
+ * the test outright if anything ever calls it, which is itself part of the write-refusal proof:
+ * the synthetic spec has no operation that could, but if one ever did, this is not a silent pass.
+ */
+const unreachableFetch = (() => {
+  throw new Error('resource.test.ts: unexpected HTTP call from a spec with no HTTP operations');
+}) as unknown as typeof globalThis.fetch;
+
+const run = <A, E>(effect: Effect.Effect<A, E, UnifiNetworkOpContext>) =>
+  Effect.runPromise(effect.pipe(Effect.provide(fakeUnifiLayer(unreachableFetch))));
+
+const refusal = async (
+  effect: Effect.Effect<unknown, UnifiWriteRefused, UnifiNetworkOpContext>,
+) => {
+  const failure = await run(Effect.flip(effect));
+  expect(failure).toBeInstanceOf(UnifiWriteRefused);
+  return failure;
+};
+
+describe('unifiOperations.readHandler', () => {
+  test('cold read (no persisted output) of a match answers Unowned', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(MATCH)).readHandler({ olds: MATCH, output: undefined }),
+    );
+    expect(Unowned.is(attrs)).toBe(true);
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('warm read (persisted output says ours already) answers plain attributes', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(MATCH)).readHandler({ olds: MATCH, output: MATCH }),
+    );
+    expect(Unowned.is(attrs)).toBe(false);
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('a genuinely absent object answers undefined either way', async () => {
+    const attrs = await run(
+      unifiOperations(specFor(undefined)).readHandler({ olds: MATCH, output: MATCH }),
+    );
+    expect(attrs).toBeUndefined();
+  });
+});
+
+describe('unifiOperations.diff', () => {
+  test('no persisted output defers to the engine default (undefined)', async () => {
+    const diff = await run(unifiOperations(specFor(MATCH)).diff(MATCH, undefined));
+    expect(diff).toBeUndefined();
+  });
+
+  test('declared props match live -- noop', async () => {
+    const diff = await run(unifiOperations(specFor(MATCH)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'noop' });
+  });
+
+  test('live object drifted from the declaration -- update, never silently absorbed', async () => {
+    const diff = await run(unifiOperations(specFor(DRIFTED_LIVE)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'update' });
+  });
+
+  test('live object vanished since it was adopted -- update, never a quiet noop', async () => {
+    const diff = await run(unifiOperations(specFor(undefined)).diff(MATCH, MATCH));
+    expect(diff).toEqual({ action: 'update' });
+  });
+});
+
+describe('unifiOperations.reconcile', () => {
+  test('exact match: zero write calls (the spec has none), returns live attributes -- H6', async () => {
+    const attrs = await run(unifiOperations(specFor(MATCH)).reconcile(MATCH));
+    expect(attrs).toEqual(MATCH);
+  });
+
+  test('missing live object refuses "create", never fabricates one', async () => {
+    const failure = await refusal(unifiOperations(specFor(undefined)).reconcile(MATCH));
+    expect(failure.action).toBe('create');
+    expect(failure.type).toBe('Test.Widget');
+    expect(failure.identity).toBe('widgets/w1');
+  });
+
+  test('drifted live object refuses "update", never converges by writing', async () => {
+    const failure = await refusal(unifiOperations(specFor(DRIFTED_LIVE)).reconcile(MATCH));
+    expect(failure.action).toBe('update');
+  });
+});
+
+describe('unifiOperations.destroy', () => {
+  test('always refuses "delete" -- the spec has no destroy operation at all', async () => {
+    const failure = await refusal(unifiOperations(specFor(MATCH)).destroy(MATCH));
+    expect(failure.action).toBe('delete');
+  });
+});

package/src/unifi/resource.ts

@@ -0,0 +1,131 @@
+/**
+ * One shape for every UniFi Network read-only object — `Unifi.Network`, `Unifi.FirewallZone`,
+ * and whatever import adds next.
+ *
+ * ★ MIRRORS `../discord/resource.ts` (S7-S10, H1, H5), NOT `../netbox/resource.ts`. Both are
+ *   "marker-less API" families (S8): UniFi Network objects carry no tag or metadata field this
+ *   stack could stamp as ownership, so a cold read of a match is `Unowned(attrs)` exactly like
+ *   `Cloudflare/Snippets/Snippet.ts@v2.0.0-beta.79#read`, the reference implementation S8 and H1
+ *   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 DIFFERENCE FROM EVERY OTHER FAMILY HERE: THERE IS NO `create`, `update` OR `destroy` IN
+ *   THIS SPEC AT ALL. Tim's rule, 2026-09-24 (`policy.ts`): UniFi and OPNsense are read-only. So
+ *   `reconcile` below can only ever refuse or report an exact match — it has no write path to
+ *   fall into by accident, and no resource file wired through this engine can reach one either.
+ *
+ * ⚠️ RECONCILE STILL HAS TO SUCCEED ON AN EXACT-MATCH ADOPTION, NOT JUST REFUSE UNCONDITIONALLY.
+ *   Measured against `Plan.ts@v2.0.0-beta.79` (`forceUpdateAfterAdoption`, H6): beta.79 forces
+ *   ONE reconcile call after every cold adoption, whether or not the diff said noop — so a
+ *   resource whose `reconcile` always failed would break the ordinary "adopt an unchanged
+ *   object" deploy, not just a real write. The fix, exactly like `discordOperations.reconcile`:
+ *   read the live object again, and refuse ONLY when it is missing (would need a create) or
+ *   drifted (would need a write to converge). An exact match returns the live attributes and
+ *   calls nothing — S10's "zero write calls when there is no drift" holds even under the forced
+ *   post-adoption call.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE —
+ *   same split netbox's `resource.ts` uses and for the same reason: `Effect.catchTag`'s
+ *   tag-literal inference needs a concrete error union to resolve `"NotFound"` against, and a
+ *   spec's `E` is only concrete at each resource file's own call site. Every OTHER failure (a
+ *   real 5xx, a network error, `Forbidden`) is NOT folded anywhere — it fails the plan loudly,
+ *   per the task's own rule: only a genuine not-found may mean absent.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/unifi-network/Credentials';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { refuseWrite } from './policy.ts';
+
+/** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
+export type UnifiRequirements = HttpClient.HttpClient;
+
+/**
+ * One UniFi Network object's read. `Live` is whatever the SDK decodes (a `NetworkDetails`, a
+ * `FirewallZone`, …); `E` is left to each resource file to declare (its own `fetchLive`'s error
+ * union, with `NotFound` already folded away) so the precise per-operation error union flows
+ * through instead of being widened by hand here.
+ */
+export type UnifiSpec<Props extends object, Live, Attributes extends object, E> = {
+  /** 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). */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, UnifiNetworkOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /** For the refusal message and read-back failures. */
+  readonly describe: (props: Props) => string;
+};
+
+export const unifiOperations = <Props extends object, Live, Attributes extends object, E>(
+  spec: UnifiSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    readHandler: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      Effect.gen(function* () {
+        const attrs = yield* read(olds);
+        if (attrs === undefined) return undefined;
+        // Warm read (persisted `output` says a prior apply already adopted this exact object):
+        // plain attributes. Cold read (fresh store, or state lost): no ownership marker on this
+        // vendor exists to tell "ours" from "someone else's" apart, so Unowned until adopt(true).
+        return output !== undefined ? attrs : Unowned(attrs);
+      }),
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        return spec.matches(live, news)
+          ? ({ action: 'noop' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const live = yield* read(news);
+        if (live === undefined) return yield* refuseWrite(spec.type, spec.describe(news), 'create');
+        if (!spec.matches(live, news)) {
+          return yield* refuseWrite(spec.type, spec.describe(news), 'update');
+        }
+        // Exact match: the object already is what is declared. Zero write calls (S10), correct
+        // whether this is a routine deploy or beta.79's forced post-adoption reconcile (H6).
+        return live;
+      }),
+
+    destroy: (olds: Props) => refuseWrite(spec.type, spec.describe(olds), 'delete'),
+  };
+};
+
+/**
+ * The four provider handlers for a spec'd read-only UniFi object, wired once.
+ *
+ * ⛔ `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>(
+  spec: UnifiSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = unifiOperations(spec);
+  const withCredentials = <A, Err>(effect: Effect.Effect<A, Err, UnifiNetworkOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: (args: { olds: Props; output: Attributes | undefined }) =>
+      withCredentials(ops.readHandler(args)),
+    diff: (args: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(args.news, args.output)),
+    reconcile: (args: { news: Props }) => withCredentials(ops.reconcile(args.news)),
+    delete: (args: { olds: Props }) => withCredentials(ops.destroy(args.olds)),
+  };
+};

package/src/verify/fake-engine.ts

@@ -125,11 +125,24 @@ export type Body = Effect.Effect<unknown, unknown, unknown>;
 type Compiled = { readonly name: string; readonly stage: string; readonly services: never };
 type PlanView = { readonly resources: Readonly<Record<string, { readonly action: string }>> };
 
+/** One row of `Alchemy.Drift.detect`'s dry-run report — the fields `drift` below asserts on. */
+export type DriftRow = { readonly action: string };
+
 export interface FakeEngine {
   /** Plan and apply `body`, as `alchemy deploy --adopt` would; resolves to the planned actions. */
   readonly deploy: (body: Body) => Promise<Record<string, string>>;
   /** Verify `body` against what the earlier deploys recorded. */
   readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+  /**
+   * `alchemy drift`'s own dry-run (`Alchemy.Drift.detect`) over whatever `deploy` already
+   * persisted — `body` is used only to resolve the stack's name/stage/providers, exactly as
+   * `verify` does; drift itself reads the state store, not `body`'s declarations. ⚠️ A DIFFERENT
+   * ENGINE PATH FROM `verify`'s `--all` READ, proxmox/read-failure-propagation.test.ts's own ⛔:
+   * `Drift.ts` calls a provider's `read` with `output` set to the PERSISTED attributes, and folds
+   * a `read` that resolves `undefined` into `{action: 'missing'}` with no error — silent, unlike
+   * `verify.ts`'s `readWithState`, which already wraps that same call in `Effect.catchCause`.
+   */
+  readonly drift: (body: Body) => Promise<Record<string, DriftRow>>;
   /**
    * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
    * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).
@@ -152,6 +165,10 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
   ) => Effect.Effect<Compiled, unknown, never>;
   const plan = Alchemy.Plan.make as unknown as (c: Compiled) => Effect.Effect<PlanView, unknown>;
   const apply = Alchemy.apply as unknown as (planned: PlanView) => Effect.Effect<unknown, unknown>;
+  const detectDrift = Alchemy.Drift.detect as unknown as (stack: {
+    name: string;
+    stage: string;
+  }) => Effect.Effect<{ resources: Record<string, DriftRow> }, unknown>;
 
   const run = <A>(body: Body, next: (compiled: Compiled) => Effect.Effect<A, unknown, unknown>) =>
     Effect.runPromise(
@@ -182,6 +199,12 @@ export const engineOver = <ROut, E, RIn>(layer: Layer.Layer<ROut, E, RIn>): Fake
       run(body, (compiled) =>
         verifySession({ context: compiled.services, stack: compiled as never }, options),
       ),
+    drift: (body) =>
+      run(body, (compiled) =>
+        detectDrift({ name: compiled.name, stage: compiled.stage }).pipe(
+          Effect.map((detected) => detected.resources),
+        ),
+      ),
   };
 };