@homeflare/alchemy 0.38.0 → 0.40.0

package/dist/unifi/wifi-broadcast.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `Unifi.WifiBroadcast` — one WiFi network (SSID) broadcast on a UniFi Network site, READ-ONLY
+ * (`policy.ts`).
+ *
+ * ⛔ T23, THE REASON THIS FAMILY NEVER CALLS `getWifiBroadcastDetails`. That single-object GET
+ *   returns `WifiBroadcastDetails`, whose `securityConfiguration`
+ *   (`WifiSecurityConfigurationDetailObject`) carries the WPA passphrase AND every PPSK entry's
+ *   passphrase — the pinned spec has NO `writeOnly` flag on either (verified: 4 `passphrase`
+ *   props, 0 `writeOnly`; A2 already redacts them to `Redacted.Redacted<string>` at the SDK layer,
+ *   `errors-and-secrets.test.ts`). This family goes further and never fetches that shape AT ALL:
+ *   the only call below is `getWifiBroadcastPage`, which answers `WifiBroadcastOverview` instead —
+ *   whose own `securityConfiguration` (`WifiSecurityConfigurationOverview`) is `{type,
+ *   presharedKeyNetworkIds}`. No passphrase field exists in that type, so `WifiBroadcastProps`/
+ *   `Attributes` (`wifi-broadcast-form.ts`) cannot carry one even by a future mistake.
+ *
+ * ⚠️ NO GET-BY-ID CALL EXISTS FOR THE OVERVIEW SHAPE — unlike every other family in this
+ *   directory (`getNetworkDetails`, `getFirewallZone`, `getDnsPolicy`, `getAclRule`),
+ *   `wifi_broadcasts.ts` only has `getWifiBroadcastPage` (list) and `getWifiBroadcastDetails`
+ *   (single, passphrase-bearing — forbidden above). `fetchLive` below walks every page with B0b's
+ *   `pageAll` and finds the one row matching `wifiBroadcastId` — the first real resource-level
+ *   consumer of that pager (previously exercised only by `paginate.test.ts` in isolation).
+ *
+ * ⚠️ THE `NotFound` CATCH BELOW IS FOR THE WHOLE WALK, NOT JUST THE FIRST PAGE CALL (red team,
+ *   MINOR-4, 2026-09-26 — corrected from an earlier claim that it only applied to the first call).
+ *   `pageAll` makes its sequential page calls inside one Effect pipeline, and `catchTag` here wraps
+ *   that entire pipeline; a 404 on ANY page of the walk — not only the first — folds to `undefined`
+ *   and discards whatever rows the walk had already collected. In practice this means "the site
+ *   vanished partway through listing its broadcasts" is indistinguishable from "the site was never
+ *   there" and from "the target id just isn't among the collected rows" — none of these three cases
+ *   has a separate vendor signal, and no other family's `fetchLive` distinguishes its own analogous
+ *   cases either. Read-only reporting treats all three the same conservative way (absent, not an
+ *   error); a write path would need to tell them apart.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as wifiBroadcasts from '@distilled.cloud/unifi-network/wifi_broadcasts';
+import * as Effect from 'effect/Effect';
+import { type WifiBroadcastAttributes, type WifiBroadcastProps } from './wifi-broadcast-form.ts';
+import { type UnifiPaginationInconsistent } from './paginate.ts';
+import type { UnifiRequirements, UnifiSpec } from './resource.ts';
+export type { WifiBroadcastAttributes, WifiBroadcastProps } from './wifi-broadcast-form.ts';
+export { declareWifiBroadcast } from './wifi-broadcast-form.ts';
+export { driftOf } from './wifi-broadcast-drift.ts';
+export interface UnifiWifiBroadcast extends Resource<'Unifi.WifiBroadcast', WifiBroadcastProps, WifiBroadcastAttributes, never, UnifiRequirements> {
+}
+export declare const UnifiWifiBroadcast: import("alchemy").ResourceClass<UnifiWifiBroadcast>;
+/** `wifiBroadcast('guest', props)` — `adopt(true)` piped on by default (H5); see `network.ts`. */
+export declare const wifiBroadcast: (id: string, props: WifiBroadcastProps) => Effect.Effect<UnifiWifiBroadcast, never, import("effect/unstable/http/HttpClient").HttpClient>;
+/** ★ EXPORTED for direct testing against a fake `Credentials` layer — see `network.ts`'s own. */
+export declare const spec: UnifiSpec<WifiBroadcastProps, wifiBroadcasts.WifiBroadcastOverview, WifiBroadcastAttributes, wifiBroadcasts.GetWifiBroadcastPageError | UnifiPaginationInconsistent>;
+export declare const handlers: {
+    list: () => Effect.Effect<never[], never, never>;
+    read: (args: {
+        olds: WifiBroadcastProps;
+        output: WifiBroadcastAttributes | undefined;
+    }) => Effect.Effect<WifiBroadcastAttributes | undefined, UnifiPaginationInconsistent | wifiBroadcasts.UnifiNetworkOpError, import("effect/unstable/http/HttpClient").HttpClient>;
+    diff: (args: {
+        news: import("alchemy").Input<WifiBroadcastProps>;
+        output: WifiBroadcastAttributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | undefined, UnifiPaginationInconsistent | wifiBroadcasts.UnifiNetworkOpError, import("effect/unstable/http/HttpClient").HttpClient>;
+    reconcile: (args: {
+        news: WifiBroadcastProps;
+    }) => Effect.Effect<WifiBroadcastAttributes, UnifiPaginationInconsistent | import("./policy.ts").UnifiWriteRefused | wifiBroadcasts.UnifiNetworkOpError, import("effect/unstable/http/HttpClient").HttpClient>;
+    delete: (args: {
+        olds: WifiBroadcastProps;
+    }) => Effect.Effect<never, import("./policy.ts").UnifiWriteRefused, import("effect/unstable/http/HttpClient").HttpClient>;
+};
+export declare const UnifiWifiBroadcastProvider: () => import("effect/Layer").Layer<Provider.Provider<UnifiWifiBroadcast>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=wifi-broadcast.d.ts.map

package/dist/unifi/wifi-broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wifi-broadcast.d.ts","sourceRoot":"","sources":["../../src/unifi/wifi-broadcast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,cAAc,MAAM,gDAAgD,CAAC;AACjF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,KAAK,2BAA2B,EAAW,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGlE,YAAY,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEpD,MAAM,WAAW,kBAAmB,SAAQ,QAAQ,CAClD,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,EACL,iBAAiB,CAClB;CAAG;AAEJ,eAAO,MAAM,kBAAkB,qDAE7B,CAAC;AAEH,kGAAkG;AAClG,eAAO,MAAM,aAAa,OAAQ,MAAM,SAAS,kBAAkB,mGAClB,CAAC;AAElD,iGAAiG;AACjG,eAAO,MAAM,IAAI,EAAE,SAAS,CAC1B,kBAAkB,EAClB,cAAc,CAAC,qBAAqB,EACpC,uBAAuB,EACvB,cAAc,CAAC,yBAAyB,GAAG,2BAA2B,CAWvE,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;CAAsB,CAAC;AAE5C,eAAO,MAAM,0BAA0B,wIACwD,CAAC"}

package/docs/telemetry-spike.md

@@ -0,0 +1,94 @@
+# Spike: what a stack's `providers` Layer captures (2026-09-26)
+
+Offline, no live Victoria call, per the workflow's own rule. A throwaway script (deleted after this
+was recorded — not committed; `layer.test.ts` and `http-client-sealing.test.ts` are what's kept) ran
+`verify/fake-engine.ts`'s `engineOver` — the REAL `Alchemy.Stack` + `Plan.make` + `apply` over an
+in-memory state store, alchemy `2.0.0-beta.79` — with:
+
+- a fake OTLP collector (`fake-collector.ts`'s `Bun.serve`, capturing every POST's path/headers/body)
+- `telemetryLayer({ endpoints: { traces: '<collector>/v1/traces' }, serviceName: 'spike' })` merged
+  into the stack's `providers`
+- one fake resource (`Spike.Thing`) whose `reconcile` wraps an `Effect.withSpan('spike.provider.
+custom-span')` around an `HttpClient` `GET` to a SECOND fake server (`target`, standing in for
+  whatever real endpoint a provider calls) at `<target>/probe?token=SECRET123` with an
+  `authorization: Bearer sekrit` header
+- a real `FetchHttpClient.layer` merged in as `ambient`, standing in for the platform layer a real
+  `alchemy.run.ts`'s `Stack.ts` provides underneath the merged `providers` (admin-transport-
+  scope.test.ts's own pattern) — `telemetryLayer`'s own `FetchHttpClient` is sealed, so without this
+  the fake provider's `HttpClient.HttpClient` requirement has nothing to resolve to
+
+## Question 1: which spans arrive when the tracer is provided via `providers`?
+
+**All of them.** One `deploy()` (a create) produced exactly one POST to `/v1/traces` containing:
+
+```
+state_store.init, plan.diff.resource, plan.make,
+http.client GET, spike.provider.custom-span,
+provider.create, apply.resource, apply
+```
+
+- **The provider's own span** (`spike.provider.custom-span`) arrived.
+- **The `HttpClient` client span** (`http.client GET`, effect's own `HttpClient.make` instrumentation)
+  arrived — effect's tracing reads whatever `Tracer.Tracer` is ambient when the request runs, and
+  the stack's `providers` context is exactly that.
+- **Alchemy's own engine spans arrived too**: `plan.make` (Plan.ts), `apply`/`apply.resource`
+  (Apply.ts's own `Effect.withSpan` calls), and `provider.create` — alchemy's OWN
+  `instrumentLifecycle` wrapper (Apply.ts) puts every provider lifecycle call (`read`/`reconcile`/
+  `delete`) in a `provider.${op}` span ALREADY, with `alchemy.resource.fqn`/`type`/`op` attributes —
+  a provider doesn't need to add its own span just to get lifecycle-level tracing.
+- `state_store.init` and `plan.diff.resource` are alchemy internals not named in the facts this
+  workflow started from — recorded here since "measure which spans arrive" means all of them, not
+  only the three anticipated.
+
+**Why**: `verify/fake-engine.ts`'s `engineOver` builds `compiled.services` from the `providers`
+layer, then runs `Plan.make`/`apply` with `Effect.provide(Layer.succeedContext(compiled.services))`
+around them (`fake-engine.ts`'s `run`). Since `Tracer.Tracer` is an `effect/Tracer` `Context.
+Reference` (a value with a process-wide default that any `Effect.provide` can override for the
+effects it wraps), and `telemetryLayer` sets that reference via `Layer.effect(Tracer.Tracer, …)`
+(the same shape `OtlpTracer.layer` itself uses), every span created inside that `Effect.provide` —
+alchemy's own internals included — reads the OTLP-backed, redacting tracer, not effect's default.
+**This holds specifically because the tracer is installed through the stack's OWN `providers`
+option**, the mechanism `alchemy.run.ts` already exposes to every consumer stack — not through
+alchemy's separate CLI-wide `Telemetry/Layer.ts` install this workflow's decision explicitly does
+not touch.
+
+## Question 2: does redaction hold on a REAL span, not just the unit tests?
+
+Yes — the captured `http.client GET` span's `url.full` was `http://127.0.0.1:<port>/probe`: no
+`?token=SECRET123`. With a `redaction: { denylist: [<target's host>, 'secret-site-abc123'] }` policy
+and a target URL of `<target>/secret-site-abc123/probe?token=SECRET`, the captured attributes were:
+
+```
+server.address: "<redacted>"
+url.full:       "http://<redacted>/<redacted>/probe"
+url.path:       "/<redacted>/probe"
+```
+
+with **no `http.request.header.*` key at all** — the `authorization: Bearer sekrit` header was
+dropped outright, not value-redacted. One correction this made to the implementation: effect's
+`HttpClient.make` sets `server.address` to `url.origin` (`http://host:port`), not a bare hostname —
+`redactAttribute`'s `server.address` branch now parses it with `URL` before comparing to the
+denylist, rather than comparing the raw scheme-prefixed string (which would never match a
+consumer's hostname-only denylist entry).
+
+## Question 3: does the sealed transport actually seal?
+
+Confirmed twice, once by accident: the FIRST version of this spike's script had no `ambient`
+`FetchHttpClient` merged in, on the assumption that a leaking `telemetryLayer` would supply one. It
+crashed instead — `error: Service not found: effect/HttpClient` — which is direct, if accidental,
+proof that `telemetryLayer`'s own `FetchHttpClient` never reaches a sibling provider.
+`http-client-sealing.test.ts`'s second test makes that assertion explicit and permanent
+(`.rejects.toThrow()` with no `ambient` layer present) rather than relying on stumbling into it
+again; its first test is the positive case (a sibling gets the real `ambient` client, not
+telemetry's).
+
+## Question 4: does the shutdown flush actually deliver a short CLI run's spans?
+
+Yes, with no extra wait beyond `engine.deploy()`'s own returned `Promise` resolving. `OtlpExporter.
+make` (effect's shared batch exporter) registers a `Scope.addFinalizer` that forces one more export
+and awaits it (bounded by `shutdownTimeout`, default 3s) — and `engineOver`'s `run` wraps the whole
+plan+apply effect in `Effect.scoped`, so that finalizer runs, and is awaited, before `deploy()`'s
+promise settles. The spike's default `exportInterval` ('1 second') never even had to fire for the
+one-resource run above; the shutdown flush alone delivered the batch. Confirmed separately: with
+`endpoints: {}`, the fake collector saw zero requests even after waiting 1.5s (longer than the
+default interval) past `deploy()` returning — nothing fires later on some other timer.

package/docs/telemetry.md

@@ -0,0 +1,109 @@
+# `@homeflare/alchemy/telemetry` — OTLP tracing/logging/metrics for a stack
+
+`telemetryLayer` builds an OTLP/HTTP `Layer` for a stack's own `providers` — spans, logs and
+metrics from `Effect.withSpan`, `HttpClient` calls and alchemy's own plan/apply engine, exported to
+whatever OTLP collector a consumer names. Read 2026-09-26 against `alchemy@2.0.0-beta.79` and
+`effect@4.0.0-rc.115`'s `effect/unstable/observability` module (this file names no estate host — see
+below). See `telemetry-spike.md` for what was actually measured arriving at a collector.
+
+Bodies are sent **protobuf-encoded** (`content-type: application/x-protobuf`), not JSON — measured
+against the pinned binaries in homeflare-mini's own `src/obs`: VictoriaLogs 1.52.0 and
+VictoriaMetrics 1.151.0 both answer OTLP/HTTP JSON with a `400`, and effect's exporter treats a 400
+as non-transient and drops the batch silently at debug-only log level, so a JSON-encoded consumer
+would see traces (VictoriaTraces alone tolerates JSON) but never logs or metrics, with no visible
+error. There is no option to choose JSON instead.
+
+## Off unless you give it endpoints
+
+```ts
+import { telemetryLayer } from '@homeflare/alchemy/telemetry';
+
+export const providers = Layer.mergeAll(
+  myProviders(),
+  telemetryLayer({
+    endpoints: {
+      traces: 'http://victoria.example.test:10428/insert/opentelemetry/v1/traces',
+      logs: 'http://victoria.example.test:9428/insert/opentelemetry/v1/logs',
+      metrics: 'http://victoria.example.test:8428/opentelemetry/v1/metrics',
+    },
+    serviceName: 'my-stack',
+  }),
+);
+```
+
+Every entry in `endpoints` is optional and `undefined` by default — an entry you leave out sends
+nothing for that signal, and `telemetryLayer({ endpoints: {} , … })` sends nothing at all
+(`layer.test.ts`'s own "nothing sent when unconfigured"). There is no default collector anywhere in
+this module; a consumer's own site config supplies real hosts. `victoria.example.test` above is an
+RFC 2606 reserved name — put your actual Victoria host there, e.g. from a `bao read` or an
+environment variable your site file already has.
+
+The three paths above are VictoriaTraces/Logs/Metrics's own OTLP ingest paths (their upstream docs,
+version-specific — verify against the versions you run, not this file, per this repo's own house
+rule that a documented path is not true because it is written down). They are examples, not
+defaults: `telemetryLayer` never assumes a path shape, since `OtlpTracer`/`OtlpLogger`/`OtlpMetrics`
+each post to the exact `url` given, with nothing appended.
+
+## Options
+
+| option               | type                           | notes                                                              |
+| -------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| `endpoints`          | `{ traces?, logs?, metrics? }` | full URLs, each independent — see above.                           |
+| `serviceName`        | `string`                       | required — OTLP `service.name`.                                    |
+| `serviceVersion`     | `string?`                      | OTLP `service.version`.                                            |
+| `resourceAttributes` | `Record<string, unknown>?`     | extra OTLP resource attributes, e.g. `deployment.environment`.     |
+| `redaction`          | `{ denylist?: string[] }?`     | see below.                                                         |
+| `exportInterval`     | `Duration.Input?`              | default `'1 second'` — short on purpose, see `telemetry-spike.md`. |
+| `logsMinimumLevel`   | `LogLevel.LogLevel?`           | default `'Info'` — floor for what `logs` exports; see below.       |
+
+## Redaction — what leaves this process
+
+Two passes run, at two different points, because no single hook sees every field (redteam PR 302,
+2026-09-26 — `redact.ts`/`redact-serialization.ts` have the full detail):
+
+1. **`redactAttribute`** (`redact.ts`) wraps the `Tracer.Tracer` itself, so it runs on every span
+   attribute AS IT IS SET — provider spans, `HttpClient` client spans, and alchemy's own engine
+   spans:
+   - **Every HTTP header is dropped**, request or response, never merely value-redacted — a header
+     NAME can itself be sensitive.
+   - **Every query string is dropped** — `url.query` outright, and `url.full`'s own `?…`/`#…` — no
+     per-parameter allowlist, since the next secret param a provider adds would otherwise leak.
+   - **A denylisted host or path segment is blanked to `<redacted>`**, exact-segment match (never a
+     substring), in `url.full`, `url.path` and `server.address` (bare hostname or full origin, both).
+2. **`scrubText`/`redactTraceData`/`redactLogsData`** (`redact-serialization.ts`) run at
+   `OtlpSerialization`, right before the wire body is built — the one place that also sees fields
+   `redactAttribute` never does: `status.message` and the `exception.*` event attributes
+   `OtlpTracer` builds from a failed span's `Cause` at export time, and a log line inside a span
+   (turned into a span event by effect's default `tracerLogger` — the log message becomes the event
+   NAME). These are free text, not a structured URL, so this pass matches a denylist entry as a
+   **substring anywhere** in the string, and strips the query from any embedded URL. **Logs get the
+   same pass** (`redactLogsData`) — a log record's body and its `log.error` (`Cause.pretty`, full
+   formatted error text) attribute.
+
+```ts
+telemetryLayer({
+  endpoints: { traces: 'http://victoria.example.test:10428/insert/opentelemetry/v1/traces' },
+  redaction: { denylist: ['a1b2c3d4e5f6'] }, // e.g. a UniFi console id in the request path
+  serviceName: 'my-stack',
+});
+```
+
+Everything else — span names once scrubbed, timing, alchemy's own `alchemy.resource.*`/
+`alchemy.stack` attributes, non-URL attributes a provider sets itself — passes through untouched. A
+provider that puts a secret in a NON-url, non-header, non-denylisted attribute (e.g.
+`Effect.withSpan('x', { attributes: { 'my.token': secret } })`) is not caught by either pass; that is
+a provider bug this module cannot see, not a gap in the redaction rules above.
+
+`logsMinimumLevel` (default `'Info'`) is a separate concern from redaction: the `alchemy` CLI sets
+the GLOBAL minimum log level to Debug, and without a floor of its own the OTLP logger would ship
+every Debug-level record. It applies only to what this layer exports — a consumer's console/file
+loggers are unaffected. Metrics carry numeric data points, not provider-supplied free text, and pass
+through both passes untouched.
+
+## What this is not
+
+This is **not** alchemy's own CLI telemetry (`alchemy`'s `src/Telemetry/Layer.ts`, hard-coded to
+`otel.alchemy.run`, opted out of estate-wide via `~/.alchemy/telemetry-disabled`). That stays
+retired for this decision (2026-09-26): this module is a per-stack, explicit-endpoint layer
+each consumer opts into, not a CLI-wide install, and it never calls alchemy's endpoint or reads its
+opt-out file.

package/docs/unifi-acl-rule.md

@@ -0,0 +1,122 @@
+# UniFi ACL Rules — `Unifi.AclRule` / `Unifi.AclRuleOrdering`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** Same posture as `docs/unifi.md`'s `Unifi.Network`/
+`Unifi.FirewallZone`: `reconcile`/`delete` both fail with a typed `UnifiWriteRefused`, and the
+`GetOnlyHttpClient` wire guard (`resource.ts`) refuses any non-`GET` request before it reaches the
+transport. Neither family here calls `createAclRule`, `updateAclRule`, `deleteAclRule` or
+`updateAclRuleOrdering` anywhere — `write-op-reference.test.ts` proves it statically.
+
+## Two resources, because rule order is not a rule's own property (T5)
+
+`Unifi.AclRule` is one user-defined ACL rule (`getAclRule`/`getAclRulePage`).
+`Unifi.AclRuleOrdering` is the site's ONE ordered list of rule IDs (`getAclRuleOrdering`,
+`GET /v1/sites/{siteId}/acl-rules/ordering`) — not one-per-rule and not one-per-zone-pair the way a
+future `Unifi.FirewallPolicyOrdering` will be (`network.ts`'s header names that as a separate,
+bigger PR), because ACL rule ordering is site-wide, not keyed by a source/destination zone pair.
+
+⛔ **`orderedAclRuleIds` IS NEVER RUN THROUGH `sortedSet`.** Every other multi-value field in this
+directory that gets normalized (`firewall-zone-form.ts`'s `networkIds`, this family's own
+`enforcingDeviceFilter.deviceIds`/`protocolFilter` below) is a SET with no documented order.
+`orderedAclRuleIds` is the opposite: its position IS the value — `ACLRule.index`'s own field
+comment says "Lower index has higher priority," and the whole point of `updateAclRuleOrdering` is
+to change that priority by reordering the list. `acl-rule-ordering-form.ts`'s `matches`/`driftOf`
+compare it with plain `deepEqual`, which — per `drift.ts`'s own header — sorts object keys but
+never array elements, so leaving this one field un-normalized is what makes the resource actually
+represent order.
+
+## `Unifi.AclRule`'s own fields
+
+- **`sourceFilter`/`destinationFilter` stay opaque `unknown`**, on the SDK's own authority
+  (`access_control_acl_rules.ts`'s comment on both: "Shape varies by variant — widened by
+  scripts/convert.ts"). This is the same converter-flattening trap (T10) `network-form.ts` already
+  documents for `ipv4Configuration`; typing these per-discriminator (A3) is explicitly scoped OUT
+  of this PR. Compared with plain `deepEqual` — honest about not being decoded, not a guess at a
+  narrower shape. ⚠️ **Known gap until A3 (T15, red team, Minor finding 4)**: the vendor's own
+  filter variants (`IntegrationIpAclRuleNetworkEndpointFilterDto`'s `networkIds`,
+  `IntegrationIpAclRuleSubnetEndpointFilterDto`'s `ipAddressesOrSubnets`, both variants'
+  `portFilter`, `IntegrationMacAclRuleMacAddressEndpointFilterDto`'s `macAddresses`) are themselves
+  set-like arrays — `deepEqual` compares them order-sensitively, the same false-`update` risk
+  already fixed for `deviceIds`/`protocolFilter` below, just not fixable here without decoding the
+  filter first.
+- **`enforcingDeviceFilter.deviceIds` and `protocolFilter` are SETS**, normalized with the same
+  `sortedSet` `firewall-zone-form.ts` uses for `networkIds`: neither field's own vendor description
+  ("IDs of the Switch-capable devices used to enforce the ACL rule," "Protocols this ACL rule will
+  be applied to") indicates order, and leaving either un-normalized would let a console-side
+  reorder plan a spurious `update` this read-only family's `reconcile` then refuses forever.
+- **`index` is attributes-only, never declared.** `CreateAclRuleRequest`'s own comment on the
+  field: "This property is deprecated and has no effect. Use the dedicated ACL rule reordering
+  endpoint." Reported so a reader can see a rule's current position, but never compared —
+  `Unifi.AclRuleOrdering` above is where that position is actually declared.
+- **`metadata.origin` is attributes-only**, same split `firewall-zone-form.ts`'s `metadataOrigin`
+  uses — `UserDefinedOrDerivedEntityMetadata` is server-derived, no writable field accepts it.
+
+## T11 gate: per-tag closure diff, 10.4.57 vs 10.6.97 (checked 2026-09-26)
+
+Same method `spec-version-provenance.md` (distilled package) used for Networks/FirewallZones,
+run here for `DNS Policies` (5 ops) and `Access Control (ACL Rules)` (7 ops) — 12 operations total,
+covering both families in this PR plus `Unifi.DnsPolicy` (`docs/unifi-dns-policy.md`).
+
+- **Pin**: `~/.cache/homeflare/schemas/unifi/network_v10.4.57_openapi.json`, re-verified against
+  its own `SHA256SUMS` today (`3773947b…c9df59d`).
+- **Mirror**: `raw.githubusercontent.com/beezly/unifi-apis/main/unifi-network/10.6.97.json`,
+  diffing aid only, never a spec of record (Q5/M9) — `info.version: "10.6.97"`,
+  `sha256: 44fd0e7f81603bb1279889a528a443d8f1a0102436e4a29675d8451adf32bd78`, mirror commit
+  `f979dd64ec0ea6008c2a698c278fe49a10e102c8` (Andrew Beresford, 2026-08-20, "Add UniFi API specs:
+  Network 10.6.97", GitHub-verified signature).
+- **Operation count**: both versions carry exactly the same 12 operations for these two tags — zero
+  added, zero removed, in either direction.
+- **Full raw operation objects** (parameters, request body, responses, unresolved `$ref`s
+  included — not just named schemas, the same reason `unifi.md`'s own check goes past a
+  schema-name diff): byte-identical for all 12, both versions.
+- **14 component schemas differ somewhere in the whole document** (of 379/380 total) — the SAME 14
+  `unifi.md`'s own Networks/FirewallZones check found: 9 switch-stack/LAG schemas (`Switching`
+  tag), 4 generic `filter`-query-syntax schemas (`FilterExpression` and its three siblings,
+  matching the new `Filtering` tag), and one mDNS enum addition (`SHELLY`, `UniFi Devices` tag).
+  Full per-schema breakdown: the distilled package's own `docs/spec-version-provenance.md`.
+- **Reachability, corrected 2026-09-26 (red team, Important finding 1)**: the original pass
+  resolved only plain `$ref`s reachable from the 12 operations' full parameter/body/response trees
+  — 17 schema names. ⛔ **That walk is wrong for any discriminated schema**: both `DNS policy`
+  (`type`: `A_RECORD`…`TXT_RECORD`, `FORWARD_DOMAIN` — 7-way) and `ACL rule` (`type`: `IPV4`, `MAC`
+  — 2-way) are `discriminator`-typed, and a variant reachable only via `discriminator.mapping`
+  carries no `$ref` from its parent at all. Re-walked following `$ref` **and** `mapping` targets:
+  the closure is **46 schema names**, identical set in both versions. The 29 names the `$ref`-only
+  walk missed: all 7 DNS record variant DTOs (`IntegrationDnsARecordDto`,
+  `IntegrationDnsAaaaRecordDto`, `IntegrationDnsCnameRecordDto`, `IntegrationDnsForwardDomainPolicyDto`,
+  `IntegrationDnsMxRecordDto`, `IntegrationDnsSrvRecordDto`, `IntegrationDnsTxtRecordDto`) plus their
+  7 `*CreateUpdateDto` siblings; both ACL rule variant DTOs (`IntegrationIpAclRuleDto`,
+  `IntegrationMacAclRuleDto`) plus their 2 `*CreateUpdateDto` siblings; the IP/MAC endpoint-filter
+  DTOs (`IP ACL rule endpoint`, `MAC ACL rule endpoint`, `IntegrationIpAclRuleNetworkEndpointFilterDto`,
+  `IntegrationIpAclRulePortEndpointFilterDto`, `IntegrationIpAclRuleSubnetEndpointFilterDto`,
+  `IntegrationMacAclRuleMacAddressEndpointFilterDto`); `IntegrationAclRuleDevicesFilterDto`
+  (the device-filter's own `DEVICES` mapping target); and 2 more entity-metadata variants beyond the
+  five the original count already had. Re-diffed all 46 against the mirror with an order-independent
+  structural compare (not a byte/string compare — JSON key order differs between the pin and the
+  mirror file): **zero differ.** **Zero overlap** with the 14 schemas that changed elsewhere in the
+  document.
+
+**Answer unchanged: neither `DnsPolicy` nor `AclRule`/`AclRuleOrdering` would decode differently
+against 10.6.97** — the conclusion survives the correction; only the closure method and the schema
+count were wrong. **This does not generalize past 10.6.97 or to any other tag — re-run this check,
+following BOTH `$ref` and `discriminator.mapping`, before importing or declaring against `Clients`,
+`WiFi Broadcasts`, `Traffic Matching Lists`, `Switching`, or `Firewall` (`FirewallPolicy`); a
+`$ref`-only walk on `WiFi Broadcasts` finds 15 schemas and would miss
+`IntegrationWifiMdnsProxyPredefinedServiceDto`, which DID change (10.6.97 added the `SHELLY` enum
+member) and is reachable only through a `mapping`.**
+
+## The declaration renderers
+
+`declareAclRule(live, siteId)` and `declareAclRuleOrdering(live, siteId)` are pure functions, same
+contract as `declareNetwork`/`declareFirewallZone` (`docs/unifi.md`): given one live read, they
+return the `Props` a declaration needs so its plan is a no-op. Neither performs the read itself.
+
+## Field-level drift
+
+`acl-rule.ts`/`acl-rule-ordering.ts` each export a pure `driftOf(live, props)`
+(`acl-rule-drift.ts`, `acl-rule-ordering-form.ts`), built on the same `drift.ts`'s `makeDriftOf`
+framework as `Unifi.Network`/`Unifi.FirewallZone` — `matches` is exactly
+`fieldDrift(...).length === 0`, never a second hand-written comparison (MEDIUM-4).
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57**, same pin as `docs/unifi.md`, via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.2.0`.

package/docs/unifi-dns-policy.md

@@ -0,0 +1,75 @@
+# UniFi DNS Policies — `Unifi.DnsPolicy`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** Same posture as `docs/unifi.md`'s `Unifi.Network`/
+`Unifi.FirewallZone`: `reconcile`/`delete` both fail with a typed `UnifiWriteRefused`, and the
+`GetOnlyHttpClient` wire guard (`resource.ts`) refuses any non-`GET` request before it reaches the
+transport. This family calls no SDK write op anywhere — `write-op-reference.test.ts` proves it
+statically, and `dns-policy.test.ts`'s own write-path tests prove `reconcile`/`destroy` never send
+anything but the one `GET` this spec's `fetchLive` makes.
+
+## One flat DTO for every DNS record type
+
+⚠️ **Corrected 2026-09-26 (red team, Important finding 1): the vendor spec DOES discriminate.**
+The pinned spec's `DNS policy` schema carries a 7-way `discriminator.mapping` on `type`
+(`A_RECORD`, `AAAA_RECORD`, `CNAME_RECORD`, `FORWARD_DOMAIN`, `MX_RECORD`, `SRV_RECORD`,
+`TXT_RECORD`), each mapping to its own variant DTO (`IntegrationDnsARecordDto`, …) that carries the
+record-specific fields (`ipv4Address`, `ttlSeconds`, `text`, …) — the base `DNS policy` schema
+itself has only `domain`/`enabled`/`id`/`metadata`/`type`. None of those variant DTOs are reachable
+from the base schema by a plain `$ref` walk; they exist only behind the `mapping` (T11 gate below).
+
+What IS still true: `scripts/convert.ts` FLATTENS all 7 variants into one struct — every variant
+field becomes optional on the same `DNSPolicy`/`CreateDnsPolicyRequest`/`UpdateDnsPolicyRequest`
+type, rather than widening any of them to `unknown` (T10). No two variants collide on a field name,
+so the flattening loses no information. **That means `dns-policy-form.ts` still has no opaque-JSON
+field to flag or defer, unlike `acl-rule-form.ts`'s `sourceFilter`/`destinationFilter`
+(`docs/unifi-acl-rule.md`)** — that conclusion holds; only the "never discriminates" reason given
+for it originally was wrong.
+
+⛔ **No array field exists anywhere in this shape**, so none of `network-form.ts`'s/
+`firewall-zone-form.ts`'s/`acl-rule-form.ts`'s `sortedSet` set-normalizing applies here —
+`drift.ts`'s default `stripNullish` tolerance for UniFi's `null`-for-unset-optional fields is the
+whole story for `dns-policy-drift.ts`.
+
+## `id`/`metadata` are attributes-only, same split as every other family here
+
+`DnsPolicyProps` mirrors `UpdateDnsPolicyRequest`, not `DNSPolicy`: `id` and `metadata.origin` are
+server-derived (no writable field accepts either), reported in `DnsPolicyAttributes` but never
+compared or declared — the same split `network-form.ts` and `firewall-zone-form.ts` document for
+their own server-derived fields.
+
+## T11 gate: per-tag closure diff, 10.4.57 vs 10.6.97 (checked 2026-09-26, corrected same day)
+
+Run together with `Unifi.AclRule`'s own gate, since both tags were diffed in the same pass —
+**full breakdown, pin/mirror checksums and mirror commit are in
+[`docs/unifi-acl-rule.md`](./unifi-acl-rule.md), not repeated here.** Summary for this family: all
+5 `DNS Policies` operations are byte-identical between 10.4.57 and 10.6.97 (parameters, request
+body, responses, unresolved `$ref`s included). ⚠️ The schema closure is **46 schemas, not 17** — a
+plain `$ref` walk misses everything reachable only through `discriminator.mapping` (see "One flat
+DTO" above), which for this tag is all 7 DNS record variant DTOs plus their 7 create/update
+siblings. Re-run with `$ref` + `mapping` both followed, the full 46-schema closure (both tags
+together) shares zero names with the 14 schemas that changed anywhere in the document between the
+two versions — all 14 are `Switching`-, `Filtering`- or one `UniFi Devices` enum-shaped, none of it
+DNS- or ACL-shaped. **Answer unchanged: `Unifi.DnsPolicy` would not decode differently against a
+10.6.97 console** — the conclusion survives the correction; only the closure method and count were
+wrong. **Method note for the next family (B4+): always follow `discriminator.mapping`, not just
+`$ref` — a `$ref`-only walk silently under-counts any tag with a discriminated schema.**
+
+## The declaration renderer
+
+`declareDnsPolicy(live, siteId)` is a pure function, same contract as `declareNetwork`/
+`declareFirewallZone` (`docs/unifi.md`): given one `getDnsPolicy` response, it returns the `Props`
+a declaration needs so its plan is a no-op. A later import script reads every DNS policy on a site
+and writes one `dnsPolicy('<id>', declareDnsPolicy(live, siteId))` row per result — nothing here
+performs that write.
+
+## Field-level drift
+
+`dns-policy.ts` exports a pure `driftOf(live, props)` (`dns-policy-drift.ts`), built on `drift.ts`'s
+`makeDriftOf` framework — the same one `Unifi.Network`/`Unifi.FirewallZone`/`Unifi.AclRule` use.
+`matches` is exactly `fieldDrift(...).length === 0`, never a second hand-written comparison
+(MEDIUM-4, `network-drift.ts`'s own header).
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57**, same pin as `docs/unifi.md`, via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.2.0`.

package/docs/unifi-firewall-policy.md

@@ -0,0 +1,109 @@
+# UniFi Firewall Policies — `Unifi.FirewallPolicy` / `Unifi.FirewallPolicyOrdering`
+
+⛔ **READ-ONLY, BY TIM'S RULE (2026-09-24).** Same posture as `docs/unifi.md`'s `Unifi.Network`/
+`Unifi.FirewallZone`: `reconcile`/`delete` both fail with a typed `UnifiWriteRefused`, and the
+`GetOnlyHttpClient` wire guard (`resource.ts`) refuses any non-`GET` request before it reaches the
+transport. Neither family here calls `createFirewallPolicy`, `updateFirewallPolicy`,
+`patchFirewallPolicy`, `deleteFirewallPolicy` or `updateFirewallPolicyOrdering` anywhere —
+`write-op-reference.test.ts` proves it statically.
+
+## Two resources, because policy order is not a policy's own property (T5)
+
+`Unifi.FirewallPolicy` is one policy (`getFirewallPolicy`/`getFirewallPolicies`).
+`Unifi.FirewallPolicyOrdering` is the ordered `before`/`afterSystemDefined` policy-id lists for ONE
+`(sourceFirewallZoneId, destinationFirewallZoneId)` zone pair (`getFirewallPolicyOrdering`,
+`GET /v1/sites/{siteId}/firewall/policies/ordering?sourceFirewallZoneId=…&destinationFirewallZoneId=…`)
+— unlike `Unifi.AclRuleOrdering` (`docs/unifi-acl-rule.md`), which is site-wide, because firewall
+policies are scoped to a zone pair and the vendor keys ordering the same way. There is no "list
+every zone pair" endpoint; a caller has to already know which pairs exist, typically by walking
+`getFirewallPolicies` (T9 — see below) and grouping by each policy's `source.zoneId`/
+`destination.zoneId`. Neither resource performs that discovery.
+
+⛔ **`beforeSystemDefined`/`afterSystemDefined` ARE NEVER RUN THROUGH `sortedSet`.** Both are
+sequences — within each half, position is priority — the same "order IS the value" reasoning
+`docs/unifi-acl-rule.md` gives for `orderedAclRuleIds`. `firewall-policy-ordering-form.ts` compares
+each half independently with plain `deepEqual`, so a policy moving from one half to the other
+reports as drift on BOTH fields rather than one combined reorder.
+
+## `Unifi.FirewallPolicy`'s own fields
+
+- **`action`/`destination`/`ipProtocolScope`/`schedule`/`source` are compound, compared wholesale.**
+  Post-A3 (`8ee11f1`), these decode as real per-discriminator TS unions instead of `unknown`
+  (`discriminated-filter-decode.test.ts` proves the wire path keeps every key, including one this
+  pinned spec doesn't yet declare) — but this PR does not go on to build a leaf-by-leaf declarable
+  schema for all 12 filter variants underneath them. Each is compared as ONE value with plain
+  `deepEqual` (`stripNullish`), the same proportion `acl-rule-form.ts`'s `enforcingDeviceFilter`
+  gets (one level of structure, not exploded into scalars).
+  ⚠️ **Known gap (T15, same shape as `acl-rule-form.ts`'s own)**: several of the vendor's filter
+  variants nested inside these fields are themselves set-like arrays with no documented order
+  (`FirewallPolicyMACAddressFilter.macAddresses`, `FirewallPolicyNetworkFilter.networkIds`,
+  `FirewallPolicyApplicationFilter.applicationIds`, `FirewallPolicyIPAddressFilter.items`,
+  `FirewallPolicyRegionFilter.regions`, `FirewallPolicyVPNServerFilter.vpnServerIds`,
+  `FirewallSchedule.repeatOnDays`) — `deepEqual` compares them order-sensitively, so a console-side
+  reorder with no membership change would report a spurious drift this read-only family's
+  `reconcile` then refuses forever. Accepted, not fixed: normalizing 12 filter variants' own nested
+  arrays is bigger, separate modelling work, not a mechanical extension of A3.
+- **`connectionStateFilter` is the one top-level Props array, and is a SET** — "matches all
+  connection states" if null describes membership, not a sequence (unlike the ordering resource's
+  own lists, where position IS the value). Normalized with the same `sortedSet` every other family
+  here uses for a set-shaped array.
+- **`index` is attributes-only, never declared.** `CreateFirewallPolicyRequest` has no `index`
+  field — the live object's position among ALL policies on the site is reported, but its priority
+  relative to its own zone pair is `Unifi.FirewallPolicyOrdering`'s concern, same split
+  `acl-rule-form.ts`'s own `index` documents.
+- **`metadata.origin` is attributes-only**, same split every family here uses.
+
+## T11 gate: per-tag closure diff, 10.4.57 vs 10.6.97 (checked 2026-09-26)
+
+Same method `docs/unifi-acl-rule.md` used, run here for the `Firewall` tag's 13 operations (5
+already covered for `Unifi.FirewallZone` in `docs/unifi.md`; 8 new here: `getFirewallPolicies`,
+`createFirewallPolicy`, `getFirewallPolicyOrdering`, `updateFirewallPolicyOrdering`,
+`deleteFirewallPolicy`, `getFirewallPolicy`, `patchFirewallPolicy`, `updateFirewallPolicy`).
+
+- **Pin**: `~/.cache/homeflare/schemas/unifi/network_v10.4.57_openapi.json`, re-verified against
+  its own `SHA256SUMS` today (`3773947b…c9df59d`).
+- **Mirror**: `raw.githubusercontent.com/beezly/unifi-apis/main/unifi-network/10.6.97.json`,
+  diffing aid only, never a spec of record — re-fetched today, still `info.version: "10.6.97"`,
+  `sha256: 44fd0e7f81603bb1279889a528a443d8f1a0102436e4a29675d8451adf32bd78`, unchanged since mirror
+  commit `f979dd64ec0ea6008c2a698c278fe49a10e102c8` (Andrew Beresford, 2026-08-20, "Add UniFi API
+  specs: Network 10.6.97", GitHub-verified signature) — the same file `docs/unifi-acl-rule.md` cites.
+- **Operation count**: both versions carry exactly the same 13 operations for `Firewall` — zero
+  added, zero removed, either direction.
+- **Full raw operation objects** (parameters, request body, responses, unresolved `$ref`s included):
+  byte-identical for all 13, both versions.
+- **Reachability** (`$ref` AND `discriminator.mapping`, per `docs/unifi-acl-rule.md`'s corrected
+  method): the closure is **106 schema names**, identical set in both versions. Every one of the 12
+  filter variants' own sub-schemas (`IntegrationFirewallPolicySourceMacAddressFilterDto`, all three
+  IP-protocol-scope Dto families, both action Dtos, etc.) is in it. **Zero overlap** with the 14
+  schemas that changed elsewhere in the document (the same 9 `Switching`, 4 `Filtering`, 1 mDNS
+  schemas `docs/unifi.md`/`docs/unifi-acl-rule.md` already found) — re-diffed all 106 with an
+  order-independent structural compare: **zero differ**.
+- **Corroboration**: the A3 changeset's own broader re-check
+  (`.changeset/unifi-network-a3-typed-discriminator-filters.md`) independently walked all 25
+  FirewallPolicy/ACL rule/TrafficMatchingList operations together — a 139-schema closure, also
+  byte-identical between versions — against a mirror fetch the same day citing commit
+  `2457b337173c83599c583993210218b1b6c0f8e7` (that commit only touches `README.md`; the spec file
+  itself has been untouched, hence unchanged, since `f979dd64` above).
+
+**Answer: neither `FirewallPolicy` nor `FirewallPolicyOrdering` would decode differently against
+10.6.97.** This does not generalize past 10.6.97 or to any other tag — re-run this check, following
+BOTH `$ref` and `discriminator.mapping`, before importing or declaring against `Clients`,
+`Switching`, or any tag not yet covered by an existing `docs/unifi-*.md`.
+
+## The declaration renderers
+
+`declareFirewallPolicy(live, siteId)` and `declareFirewallPolicyOrdering(live, siteId, sourceZoneId,
+destZoneId)` are pure functions, same contract as every other family's own (`docs/unifi.md`): given
+one live read, they return the `Props` a declaration needs so its plan is a no-op.
+
+## Field-level drift
+
+`firewall-policy.ts`/`firewall-policy-ordering.ts` each export a pure `driftOf(live, props)`
+(`firewall-policy-drift.ts`, `firewall-policy-ordering-form.ts`), built on the same `drift.ts`'s
+`makeDriftOf` framework as every other family — `matches` is exactly `fieldDrift(...).length === 0`,
+never a second hand-written comparison (MEDIUM-4).
+
+## Vendor version
+
+UniFi Network Integration API **10.4.57**, same pin as `docs/unifi.md`, via
+`@distilled.cloud/unifi-network` aliased onto `@homeflare/distilled-unifi-network@0.3.0`.