@homeflare/alchemy 0.38.0 → 0.40.0

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

@@ -0,0 +1,142 @@
+/**
+ * `Unifi.DnsPolicy`'s wire shape — the declarable subset of `DNSPolicy`, and how a live read
+ * becomes both plan attributes and a rendered declaration.
+ *
+ * ★ ONE FLAT DTO FOR EVERY DNS RECORD `type` (`A_RECORD`/`AAAA_RECORD`/`CNAME_RECORD`/
+ *   `FORWARD_DOMAIN`/`MX_RECORD`/`SRV_RECORD`/`TXT_RECORD` — the pinned spec's `DNS policy` schema
+ *   DOES discriminate on `type`, via `discriminator.mapping` to 7 variant DTOs; see
+ *   `docs/unifi-dns-policy.md`'s "One flat DTO" section, corrected 2026-09-26). Unlike
+ *   `access_control_acl_rules.ts`'s `sourceFilter`/`destinationFilter` or `firewall.ts`'s policy
+ *   filters, NONE of `dns_policies.ts`'s fields were widened to `unknown` by the converter (T10) —
+ *   `scripts/convert.ts` flattens the 7 variants into one struct instead, because no two variants
+ *   collide on a field name, so every optional field still decodes as a plain scalar and there is
+ *   no discriminated-variant trap here to flag or defer past this PR.
+ *
+ * ⚠️ PROPS MIRROR `UpdateDnsPolicyRequest`, NOT `DNSPolicy` — same split `network-form.ts` and
+ *   `firewall-zone-form.ts` both use. `id` and `metadata` are server-derived (no writable field
+ *   accepts either), so they are attributes-only, reported but never compared or declared.
+ *   Everything else in `DnsPolicyProps` is exactly what `updateDnsPolicy`/`createDnsPolicy` would
+ *   accept, even though this family never calls either.
+ *
+ * ⛔ NO ARRAY FIELD ANYWHERE IN THIS SHAPE. Every field below is a scalar (`string`/`number`/
+ *   `boolean`), so none of `network-form.ts`'s/`firewall-zone-form.ts`'s `sortedSet` normalizing
+ *   is needed — `deepEqual`'s default `stripNullish` handling (`drift.ts`) is the whole story.
+ */
+import type * as dnsPolicies from '@distilled.cloud/unifi-network/dns_policies';
+
+/**
+ * ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` ON PURPOSE (`exactOptionalPropertyTypes` —
+ *   see `network-form.ts`'s own header for why `declareDnsPolicy` below needs it: it assigns a
+ *   live optional field straight through, so the target type must admit an explicit `undefined`,
+ *   not just omission).
+ */
+export interface DnsPolicyProps {
+  siteId: string;
+  dnsPolicyId: string;
+  enabled: boolean;
+  /** DNS record type: `A_RECORD`, `AAAA_RECORD`, `CNAME_RECORD`, `FORWARD_DOMAIN`, `MX_RECORD`,
+   *  `SRV_RECORD` or `TXT_RECORD` (the discriminator's own mapping keys, see the header). */
+  type: string;
+  domain?: string | undefined;
+  ipv6Address?: string | undefined;
+  /** Time to live in seconds. */
+  ttlSeconds?: number | undefined;
+  ipv4Address?: string | undefined;
+  targetDomain?: string | undefined;
+  /** IP address of the DNS Server that the DNS query is forwarded to. */
+  ipAddress?: string | undefined;
+  mailServerDomain?: string | undefined;
+  /** Priority. A lower number is preferred. */
+  priority?: number | undefined;
+  port?: number | undefined;
+  /** Protocol used by the service. */
+  protocol?: string | undefined;
+  /** Domain of the server that is running the service. */
+  serverDomain?: string | undefined;
+  /** Service associated with this SRV record. */
+  service?: string | undefined;
+  /** Weight. A relative value applicable for records with the same priority. A lower number is
+   *  preferred. */
+  weight?: number | undefined;
+  /** The text value associated with this TXT DNS record. Text can contain up to four
+   *  255-character strings. Lines containing commas must be enclosed in double quotes ("). */
+  text?: string | undefined;
+}
+
+export interface DnsPolicyAttributes {
+  siteId: string;
+  dnsPolicyId: string;
+  enabled: boolean;
+  type: string;
+  domain: string | undefined;
+  ipv6Address: string | undefined;
+  ttlSeconds: number | undefined;
+  ipv4Address: string | undefined;
+  targetDomain: string | undefined;
+  ipAddress: string | undefined;
+  mailServerDomain: string | undefined;
+  priority: number | undefined;
+  port: number | undefined;
+  protocol: string | undefined;
+  serverDomain: string | undefined;
+  service: string | undefined;
+  weight: number | undefined;
+  text: string | undefined;
+  /** `metadata.origin` (e.g. `USER`) — server-derived, never declared; see
+   *  `firewall-zone-form.ts`'s own `metadataOrigin` for the same split. */
+  metadataOrigin: string;
+}
+
+export const attributesOf = (
+  live: dnsPolicies.DNSPolicy,
+  props: DnsPolicyProps,
+): DnsPolicyAttributes => ({
+  siteId: props.siteId,
+  dnsPolicyId: live.id,
+  enabled: live.enabled,
+  type: live.type,
+  domain: live.domain,
+  ipv6Address: live.ipv6Address,
+  ttlSeconds: live.ttlSeconds,
+  ipv4Address: live.ipv4Address,
+  targetDomain: live.targetDomain,
+  ipAddress: live.ipAddress,
+  mailServerDomain: live.mailServerDomain,
+  priority: live.priority,
+  port: live.port,
+  protocol: live.protocol,
+  serverDomain: live.serverDomain,
+  service: live.service,
+  weight: live.weight,
+  text: live.text,
+  metadataOrigin: live.metadata.origin,
+});
+
+/**
+ * The declaration renderer (task spec: "given one live object, return the props a declaration
+ * needs so its plan is noop"). A later import script feeds `getDnsPolicy`'s own response straight
+ * in and writes the result into `alchemy.run.ts` as `dnsPolicy('<id>', declareDnsPolicy(live,
+ * siteId))` — no field is invented or defaulted here beyond what `attributesOf` already reports,
+ * so `matches(attributesOf(live, props), declareDnsPolicy(live, siteId))` is `true` by
+ * construction (`dns-policy.test.ts` proves it) for any live object this SDK can decode.
+ */
+export const declareDnsPolicy = (live: dnsPolicies.DNSPolicy, siteId: string): DnsPolicyProps => ({
+  siteId,
+  dnsPolicyId: live.id,
+  enabled: live.enabled,
+  type: live.type,
+  domain: live.domain,
+  ipv6Address: live.ipv6Address,
+  ttlSeconds: live.ttlSeconds,
+  ipv4Address: live.ipv4Address,
+  targetDomain: live.targetDomain,
+  ipAddress: live.ipAddress,
+  mailServerDomain: live.mailServerDomain,
+  priority: live.priority,
+  port: live.port,
+  protocol: live.protocol,
+  serverDomain: live.serverDomain,
+  service: live.service,
+  weight: live.weight,
+  text: live.text,
+});

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

@@ -0,0 +1,154 @@
+/**
+ * `Unifi.DnsPolicy`'s `spec` against a fake UniFi Network API — mirrors `network.test.ts`/
+ * `firewall-zone.test.ts`. `driftOf`/`matches` coverage lives here too (not split into its own
+ * file, unlike `network-drift.test.ts`): this family's field list is flat scalars only, so there
+ * is no unordered-array normalizer to exercise and the whole file stays well under the house cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as dnsPolicies from '@distilled.cloud/unifi-network/dns_policies';
+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 } from './dns-policy-form.ts';
+import { driftOf, matches } from './dns-policy-drift.ts';
+import { type DnsPolicyProps, declareDnsPolicy, spec } from './dns-policy.ts';
+import { unifiOperations } from './resource.ts';
+
+const POLICY_PATH = '/proxy/network/integration/v1/sites/site-1/dns/policies/dns-1';
+
+const liveDnsPolicy = (overrides: Partial<dnsPolicies.DNSPolicy> = {}): dnsPolicies.DNSPolicy => ({
+  enabled: true,
+  id: 'dns-1',
+  metadata: { origin: 'USER' },
+  type: 'A_RECORD',
+  domain: 'cameras.example.test',
+  ipv4Address: '192.0.2.10',
+  ttlSeconds: 300,
+  ...overrides,
+});
+
+const PROPS: DnsPolicyProps = {
+  siteId: 'site-1',
+  dnsPolicyId: 'dns-1',
+  enabled: true,
+  type: 'A_RECORD',
+  domain: 'cameras.example.test',
+  ipv4Address: '192.0.2.10',
+  ttlSeconds: 300,
+};
+
+describe('Unifi.DnsPolicy spec.fetchLive', () => {
+  test('a real GET response decodes into the typed live object', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === POLICY_PATH
+        ? Response.json(liveDnsPolicy())
+        : fakeFailure(400, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(PROPS).pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('dns-1');
+    expect(fake.seen).toEqual([{ method: 'GET', path: POLICY_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 (T14)', async () => {
+    // ⚠️ `Retry.none`: the default policy retries a 500 indefinitely with backoff -- this test
+    //   asserts the FAILURE, not the retry schedule. Regression for red-team Important finding 2:
+    //   a blanket `Effect.orElseSucceed(() => undefined)` fold would pass every test above too.
+    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('declareDnsPolicy -- the declaration renderer', () => {
+  test('its output matches attributesOf(live) by construction, for any live object', () => {
+    // A record shape with a DIFFERENT set of fields present than `liveDnsPolicy`'s default (a
+    // TXT record has no `ipv4Address`/`ttlSeconds`, but DOES require its own `domain` --
+    // `IntegrationDnsTxtRecordDto` lists `domain` as required, unlike the A-record-only fields) --
+    // a fresh literal, not the `A_RECORD` fixture's overrides, so no field is merely omitted from
+    // an override that would otherwise still carry the base fixture's value.
+    const live: dnsPolicies.DNSPolicy = {
+      enabled: true,
+      id: 'dns-2',
+      metadata: { origin: 'USER' },
+      type: 'TXT_RECORD',
+      domain: 'spf.example.test',
+      text: '"v=spf1 -all"',
+    };
+    const declared = declareDnsPolicy(live, 'site-1');
+    const attrs = attributesOf(live, declared);
+    expect(matches(attrs, declared)).toBe(true);
+    expect(driftOf(live, declared)).toEqual([]);
+  });
+});
+
+describe('driftOf -- B6 field-level drift, straight from one live read', () => {
+  test('a drifted field reports its own live and declared values, by name', () => {
+    const live = liveDnsPolicy({ ttlSeconds: 60 });
+    expect(driftOf(live, PROPS)).toEqual([{ field: 'ttlSeconds', live: 60, declared: 300 }]);
+  });
+
+  test('a live `null` for an unset optional field is a noop, not a spurious update', () => {
+    // UniFi's JSON answers `null` for an unset optional (see `dns-policy-drift.ts`'s header);
+    // the double cast lands `null` at runtime past what the SDK's `T | undefined` types allow.
+    const live = { ...liveDnsPolicy(), ipv6Address: null } as unknown as dnsPolicies.DNSPolicy;
+    expect(matches(attributesOf(live, PROPS), PROPS)).toBe(true);
+    expect(driftOf(live, PROPS)).toEqual([]);
+  });
+});
+
+describe('Unifi.DnsPolicy 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 === POLICY_PATH
+        ? Response.json(liveDnsPolicy())
+        : 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 === POLICY_PATH
+        ? Response.json(liveDnsPolicy({ ttlSeconds: 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 === POLICY_PATH
+        ? Response.json(liveDnsPolicy())
+        : 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/dns-policy.ts

@@ -0,0 +1,67 @@
+/**
+ * `Unifi.DnsPolicy` — one DNS policy on a UniFi Network site, READ-ONLY (`policy.ts`).
+ *
+ * ★ T11 GATE, CHECKED 2026-09-26, CORRECTED SAME DAY (red team, Important finding 1): `DNS
+ *   Policies` is 5 operations, `Access Control (ACL Rules)` (`acl-rule.ts`) is 7 — 12 total.
+ *   Diffed the pinned 10.4.57 spec against a 10.6.97 mirror (`beezly/unifi-apis`, diffing aid
+ *   only, `docs/unifi-acl-rule.md` records the sha256 + mirror commit): all 12 full operation
+ *   objects (parameters, request body, responses, unresolved `$ref`s included) are byte-identical
+ *   across versions. ⚠️ The schema closure is 46, not 17 — a `$ref`-only walk misses every schema
+ *   reachable only via a `discriminator.mapping` (both `DNS policy` and `ACL rule` discriminate on
+ *   `type`); the 46-schema closure, `$ref` + `mapping` together, shares zero names with the 14
+ *   schemas that DID change between the two versions (all in `Switching`, `Filtering`, or one
+ *   `UniFi Devices` enum — none of it DNS- or ACL-shaped). Same reachability method
+ *   `spec-version-provenance.md` (distilled package) used for Networks/FirewallZones, extended to
+ *   follow `mapping` too; full breakdown in `docs/unifi-acl-rule.md`, not repeated per family.
+ */
+import { Resource } from 'alchemy';
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as Provider from 'alchemy/Provider';
+import * as dnsPolicies from '@distilled.cloud/unifi-network/dns_policies';
+import * as Effect from 'effect/Effect';
+import { type DnsPolicyAttributes, type DnsPolicyProps, attributesOf } from './dns-policy-form.ts';
+import { matches } from './dns-policy-drift.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+import { unifiHandlers } from './resource.ts';
+
+export type { DnsPolicyAttributes, DnsPolicyProps } from './dns-policy-form.ts';
+export { declareDnsPolicy } from './dns-policy-form.ts';
+export { driftOf } from './dns-policy-drift.ts';
+
+export interface UnifiDnsPolicy extends Resource<
+  'Unifi.DnsPolicy',
+  DnsPolicyProps,
+  DnsPolicyAttributes,
+  never,
+  UnifiRequirements
+> {}
+
+export const UnifiDnsPolicy = Resource<UnifiDnsPolicy>('Unifi.DnsPolicy', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** `dnsPolicy('lan-forwarding', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export const dnsPolicy = (id: string, props: DnsPolicyProps) =>
+  UnifiDnsPolicy(id, props).pipe(adopt(true));
+
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export const spec: UnifiSpec<
+  DnsPolicyProps,
+  dnsPolicies.DNSPolicy,
+  DnsPolicyAttributes,
+  dnsPolicies.GetDnsPolicyError
+> = {
+  type: 'Unifi.DnsPolicy',
+  describe: (props) => `sites/${props.siteId}/dns/policies/${props.dnsPolicyId}`,
+  fetchLive: (props) =>
+    dnsPolicies
+      .getDnsPolicy({ siteId: props.siteId, dnsPolicyId: props.dnsPolicyId })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  attributes: attributesOf,
+  matches,
+};
+
+export const handlers = unifiHandlers(spec);
+
+export const UnifiDnsPolicyProvider = () =>
+  Provider.effect(UnifiDnsPolicy, Effect.succeed(UnifiDnsPolicy.Provider.of(handlers)));

package/src/unifi/drift.test.ts

@@ -0,0 +1,78 @@
+/**
+ * `makeDriftOf` (B6) against a synthetic field list — no SDK, no HTTP. `network.test.ts` and
+ * `firewall-zone.test.ts` each prove their own family's `driftOf` on top of this; this file proves
+ * the framework itself: an exact match reports nothing, a drifted field reports its own live and
+ * declared values (never swallowing a real difference into a single boolean), several drifted
+ * fields all report, and a custom `equal` overrides the default `deepEqual`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { type DriftField, makeDriftOf } from './drift.ts';
+
+interface Widget {
+  name: string;
+  tags: string[];
+  nested: { count: number } | undefined;
+}
+
+const FIELDS: readonly DriftField<Widget, Widget>[] = [
+  { field: 'name', live: (a) => a.name, declared: (p) => p.name },
+  { field: 'nested', live: (a) => a.nested, declared: (p) => p.nested },
+  {
+    field: 'tags',
+    live: (a) => a.tags,
+    declared: (p) => p.tags,
+    equal: (live, declared) =>
+      [...(live as string[])].sort().join(',') === [...(declared as string[])].sort().join(','),
+  },
+];
+
+const widget = (overrides: Partial<Widget> = {}): Widget => ({
+  name: 'lan',
+  nested: { count: 1 },
+  tags: ['a', 'b'],
+  ...overrides,
+});
+
+describe('makeDriftOf', () => {
+  const driftOf = makeDriftOf(FIELDS);
+
+  test('an exact match reports nothing', () => {
+    const attrs = widget();
+    expect(driftOf(attrs, widget())).toEqual([]);
+  });
+
+  test('a drifted field reports its own live and declared values', () => {
+    const attrs = widget({ name: 'lan' });
+    const props = widget({ name: 'guest' });
+    expect(driftOf(attrs, props)).toEqual([{ field: 'name', live: 'lan', declared: 'guest' }]);
+  });
+
+  test('several drifted fields all report, independently', () => {
+    const attrs = widget({ name: 'lan', nested: { count: 1 } });
+    const props = widget({ name: 'guest', nested: { count: 2 } });
+    expect(driftOf(attrs, props)).toEqual([
+      { field: 'name', live: 'lan', declared: 'guest' },
+      { field: 'nested', live: { count: 1 }, declared: { count: 2 } },
+    ]);
+  });
+
+  test('the default comparison strips nullish, matching every matches() in this directory', () => {
+    const attrs = widget({ nested: undefined });
+    const props = { ...widget(), nested: null as unknown as undefined };
+    expect(driftOf(attrs, props)).toEqual([]);
+  });
+
+  test('a custom `equal` overrides the default -- an unordered set is not drift', () => {
+    const attrs = widget({ tags: ['b', 'a'] });
+    const props = widget({ tags: ['a', 'b'] });
+    expect(driftOf(attrs, props)).toEqual([]);
+  });
+
+  test('a custom `equal` still reports a genuine difference', () => {
+    const attrs = widget({ tags: ['a', 'b'] });
+    const props = widget({ tags: ['a', 'c'] });
+    expect(driftOf(attrs, props)).toEqual([
+      { field: 'tags', live: ['a', 'b'], declared: ['a', 'c'] },
+    ]);
+  });
+});

package/src/unifi/drift.ts

@@ -0,0 +1,56 @@
+/**
+ * B6: the field-level drift framework every family's own `driftOf(live, props)` is built on
+ * (`network-form.ts`, `firewall-zone-form.ts`, and whatever family follows). Consumed by
+ * `homeflare-network`'s pre-import drift check (its own C4, not built here) to show WHICH fields
+ * a live object and a committed declaration disagree on, before that script overwrites the
+ * committed module — never by a `Unifi.*` provider itself, which only ever needs `matches`'s
+ * boolean.
+ *
+ * ★ BUILT ON `matches`, NOT A SEPARATE COMPARISON. Each family's `driftOf` reuses the SAME
+ *   normalizers (`sortedSet`, the `dhcpGuarding`/`ipv6Configuration` null-vs-undefined handling)
+ *   its own `matches` already applies — so this reports NOTHING `matches` would call a noop, and
+ *   everything `matches` would call `update`, broken down by field instead of collapsed to one
+ *   boolean. Two comparisons drifting apart would be its own bug class; there is exactly one.
+ */
+import { deepEqual } from 'alchemy/Diff';
+
+/** One field whose live and declared values differ, as `makeDriftOf` reports it. */
+export interface FieldDrift {
+  readonly field: string;
+  readonly live: unknown;
+  readonly declared: unknown;
+}
+
+/** One field's comparison recipe for `makeDriftOf`. */
+export interface DriftField<Attributes, Props> {
+  readonly field: string;
+  readonly live: (attributes: Attributes) => unknown;
+  readonly declared: (props: Props) => unknown;
+  /**
+   * Defaults to `alchemy/Diff`'s `deepEqual` with `stripNullish: true` — the same tolerance
+   * every `matches` in this directory already gives UniFi's `null`-for-unset optionals (see
+   * `network-form.ts`'s header). Pass one explicitly for a field `matches` compares as a
+   * normalized SET (`firewall-zone-form.ts`'s `networkIds`), where plain `deepEqual` would
+   * report order as drift `matches` never would.
+   */
+  readonly equal?: (live: unknown, declared: unknown) => boolean;
+}
+
+const defaultEqual = (live: unknown, declared: unknown) =>
+  deepEqual(live, declared, { stripNullish: true });
+
+/**
+ * Builds a `(attributes, props) => FieldDrift[]` from a field list — the framework a family's own
+ * `*-form.ts` calls once, then wraps as `driftOf(live, props)` by feeding it `attributesOf(live,
+ * props)` (the task's own API: callers have a live SDK object, not `Attributes`, on hand).
+ */
+export const makeDriftOf =
+  <Attributes, Props>(fields: readonly DriftField<Attributes, Props>[]) =>
+  (attributes: Attributes, props: Props): FieldDrift[] =>
+    fields.flatMap(({ field, live, declared, equal = defaultEqual }) => {
+      const liveValue = live(attributes);
+      const declaredValue = declared(props);
+      return equal(liveValue, declaredValue)
+        ? []
+        : [{ field, live: liveValue, declared: declaredValue }];
+    });

package/src/unifi/errors-and-secrets.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Runtime proof for A12 (T8/T23): the distilled regen's two behavioral changes actually decode
+ * through the real fake-fetch path every other `*.test.ts` in this family uses — not just typecheck.
+ *
+ * ⛔ WITHOUT THESE, A FUTURE REGEN THAT DROPS `sensitivePatterns` OR `errorEnvelope` STAYS GREEN.
+ *   Every other test here fixes response bodies before A2/A1 landed, so none of them would notice
+ *   either regressing back to a plain string / an always-`undefined` envelope.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+import * as applicationInfo from '@distilled.cloud/unifi-network/application_info';
+import * as Retry from '@distilled.cloud/unifi-network/Retry';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { fakeUnifi, fakeUnifiLayer } from './fake-unifi.ts';
+
+const WIFI_PATH = '/proxy/network/integration/v1/sites/site-1/wifi/broadcasts/wifi-1';
+
+// A fabricated sentinel, not a real WiFi passphrase (kit is PUBLIC — see fake-unifi.ts).
+const SENTINEL = 'sentinel-wpa-passphrase-do-not-log-me';
+
+const liveWifiBroadcast = () => ({
+  channel2gLockedTo6: false,
+  clientIsolationEnabled: false,
+  dtimPeriod2gLockedTo3: false,
+  enabled: true,
+  hideName: false,
+  id: 'wifi-1',
+  metadata: { origin: 'USER' },
+  multicastToUnicastConversionEnabled: false,
+  name: 'Guest',
+  type: 'STANDARD',
+  securityConfiguration: {
+    type: 'WPA_PERSONAL',
+    passphrase: SENTINEL,
+    presharedKeys: [{ network: { type: 'VLAN', networkId: 'net-1' }, passphrase: SENTINEL }],
+  },
+});
+
+describe('A2/T23 — WPA/PPSK passphrase decodes Redacted, not a plain string', () => {
+  test('both the single passphrase and every PPSK entry come back Redacted', async () => {
+    const fake = fakeUnifi((method, url) =>
+      method === 'GET' && url.pathname === WIFI_PATH
+        ? Response.json(liveWifiBroadcast())
+        : new Response('unexpected request', { status: 400 }),
+    );
+    const live = await Effect.runPromise(
+      wifiBroadcasts
+        .getWifiBroadcastDetails({ siteId: 'site-1', wifiBroadcastId: 'wifi-1' })
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    const { passphrase, presharedKeys } = live.securityConfiguration;
+    expect(Redacted.isRedacted(passphrase)).toBe(true);
+    expect(Redacted.value(passphrase as Redacted.Redacted<string>)).toBe(SENTINEL);
+    expect(Redacted.isRedacted(presharedKeys?.[0]?.passphrase)).toBe(true);
+  });
+
+  test('neither JSON.stringify nor String() ever shows the sentinel value', async () => {
+    const fake = fakeUnifi(() => Response.json(liveWifiBroadcast()));
+    const live = await Effect.runPromise(
+      wifiBroadcasts
+        .getWifiBroadcastDetails({ siteId: 'site-1', wifiBroadcastId: 'wifi-1' })
+        .pipe(Effect.provide(fakeUnifiLayer(fake.fetch))),
+    );
+    expect(JSON.stringify(live)).not.toContain(SENTINEL);
+    expect(String(live.securityConfiguration.passphrase)).not.toContain(SENTINEL);
+  });
+});
+
+/** The pinned spec's `Error Message` schema (T8) — see `src/protocol.ts`'s module doc. */
+const envelopeBody = (over: Record<string, unknown> = {}) => ({
+  code: 'api.example.not-found',
+  message: 'vendor-provided failure text',
+  requestId: 'req-sentinel-1',
+  requestPath: '/v1/sites/site-1/secret-console-path',
+  statusCode: 404,
+  statusName: 'Not Found',
+  timestamp: '2026-01-01T00:00:00.000Z',
+  ...over,
+});
+
+describe('A1/T8 — the vendor Error Message envelope actually decodes', () => {
+  test('a mapped status (404) carries the vendor message, not a bare "HTTP 404"', async () => {
+    const fake = fakeUnifi(() => Response.json(envelopeBody(), { status: 404 }));
+    const failure = await Effect.runPromise(
+      Effect.flip(applicationInfo.getInfo({}).pipe(Effect.provide(fakeUnifiLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('NotFound');
+    expect((failure as { message?: string }).message).toBe('vendor-provided failure text');
+  });
+
+  test('an unmapped status (418) becomes UnknownUnifiNetworkError with the extra envelope fields', async () => {
+    // ⚠️ `Retry.none`: `UnknownUnifiNetworkError` is tagged a retryable server error by core's
+    //   default policy regardless of the actual (client, 4xx) status — this test asserts the
+    //   FAILURE, not the retry schedule (same reason `network.test.ts`'s 500 test needs it).
+    const fake = fakeUnifi(() =>
+      Response.json(envelopeBody({ statusCode: 418, statusName: "I'm a teapot" }), {
+        status: 418,
+      }),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        applicationInfo.getInfo({}).pipe(Retry.none, Effect.provide(fakeUnifiLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('UnknownUnifiNetworkError');
+    const err = failure as unknown as {
+      code?: string;
+      requestId?: string;
+      statusCode?: number;
+      statusName?: string;
+      timestamp?: string;
+      body: unknown;
+    };
+    expect(err.code).toBe('api.example.not-found');
+    expect(err.requestId).toBe('req-sentinel-1');
+    expect(err.statusCode).toBe(418);
+    expect(err.statusName).toBe("I'm a teapot");
+    expect(err.timestamp).toBe('2026-01-01T00:00:00.000Z');
+    // T3: requestPath is never plucked into its own field or into `message` …
+    expect('requestPath' in err).toBe(false);
+    // … but it IS still inside the raw body for anyone who reads that on purpose (README/errors.ts).
+    expect((err.body as { requestPath?: string }).requestPath).toBe(
+      '/v1/sites/site-1/secret-console-path',
+    );
+  });
+});

package/src/unifi/fake-unifi.ts

@@ -19,7 +19,11 @@ export const FAKE_KEY = 'placeholder-unifi-key';
 
 export type Seen = { readonly method: string; readonly path: string };
 
-/** No documented failure envelope (see `protocol.ts`) — plain text is all a failure needs. */
+/**
+ * Plain-text failure. `protocol.ts`'s `errorEnvelope` also decodes a documented JSON shape
+ * (`components.schemas["Error Message"]`, A1/T8) when a scenario needs that instead — see
+ * `errors-and-secrets.test.ts`'s `envelopeBody` helper for a fixture in that shape.
+ */
 export const fakeFailure = (status: number, detail: string) => new Response(detail, { status });
 
 /**