@homeflare/alchemy 0.39.0 → 0.41.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`.

package/docs/unifi-traffic-matching-list.md

@@ -0,0 +1,82 @@
+# UniFi Traffic Matching Lists — `Unifi.TrafficMatchingList`
+
+⛔ **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 never calls `createTrafficMatchingList`, `updateTrafficMatchingList` or
+`deleteTrafficMatchingList` anywhere — `write-op-reference.test.ts` proves it statically.
+
+## The simplest object shape in this directory
+
+`TrafficMatchingList` is `{id, name, type, items?}` — no `metadata` field at all, unlike every
+other family here (`FirewallZone`/`DNSPolicy`/`ACLRule`/`FirewallPolicy` all carry a server-derived
+`metadata.origin`). Nothing in `TrafficMatchingListAttributes` is attributes-only the way
+`metadataOrigin`/`index` are elsewhere: every field this family reads is also declarable.
+
+## `items` is a real TS union post-A3, compared wholesale
+
+`items` decodes as `Array<IPv4Matching> | Array<IPv6Matching> | Array<PortMatching>`, keyed by the
+sibling `type` field (A3, `8ee11f1`) — previously opaque `unknown`. The runtime schema is still a
+passthrough `S.Unknown` (Argo CD's `union:` callback): narrower for a reader at the TYPE level only,
+so decode keeps every key including one this pinned spec doesn't yet declare, the same proof
+`discriminated-filter-decode.test.ts` runs for `FirewallPolicy`/`AclRule`.
+
+⚠️ **Known gap (T15, same shape `acl-rule-form.ts`/`docs/unifi-firewall-policy.md` both carry)**: a
+traffic matching list's `items` is semantically a SET of match entries — matching is "is this
+traffic covered by ANY entry," not order-dependent — but each entry is an OBJECT
+(`{type, value?, start?, stop?}`), not a bare string, so there is no cheap canonical sort key the
+way `sortedSet` gives a `string[]`. `deepEqual` compares `items` 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: a generic object-set normalizer is
+bigger, separate modelling work, not a mechanical extension of typing `items` per-discriminator.
+
+## T11 gate: per-tag closure diff, 10.4.57 vs 10.6.97 (checked 2026-09-26)
+
+Same method `docs/unifi-acl-rule.md`/`docs/unifi-firewall-policy.md` use, run here for the
+`Traffic Matching Lists` tag's 5 operations (`getTrafficMatchingLists`, `createTrafficMatchingList`,
+`deleteTrafficMatchingList`, `getTrafficMatchingList`, `updateTrafficMatchingList`).
+
+- **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 every other family doc cites.
+- **Operation count**: both versions carry exactly the same 5 operations for `Traffic Matching
+Lists` — zero added, zero removed, either direction.
+- **Full raw operation objects** (parameters, request body, responses, unresolved `$ref`s included):
+  byte-identical for all 5, both versions.
+- **Reachability** (`$ref` AND `discriminator.mapping`): the closure is **19 schema names**
+  (`IPv4Matching`/`IPv6Matching`/`Port matching` and each of the three list-shape Dto pairs, plus
+  their subnet/range/address variant Dtos), identical set in both versions. **Zero overlap** with
+  the 14 schemas that changed elsewhere in the document — re-diffed all 19 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; see
+  `docs/unifi-firewall-policy.md`'s own T11 section for why that citation's different-looking
+  mirror commit is the same unchanged file.
+
+**Answer: `TrafficMatchingList` would not 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 renderer
+
+`declareTrafficMatchingList(live, siteId)` is a pure function, same contract as every other
+family's own (`docs/unifi.md`): given one `getTrafficMatchingList` response, it returns the `Props`
+a declaration needs so its plan is a no-op.
+
+## Field-level drift
+
+`traffic-matching-list.ts` exports a pure `driftOf(live, props)` (`traffic-matching-list-drift.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`.

package/docs/unifi-wifi.md

@@ -0,0 +1,120 @@
+# UniFi WiFi Broadcasts — `Unifi.WifiBroadcast`
+
+⛔ **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 `wifi-broadcast.test.ts`'s own write-path tests prove `reconcile`/`destroy` never
+send anything but `GET`s.
+
+## T23: the passphrase-bearing details call is never made
+
+The pinned spec's WiFi Broadcast "details" shape (`getWifiBroadcastDetails`, and the create/update
+request bodies) — `WifiSecurityConfigurationDetailObject` — carries the WPA passphrase AND every
+PPSK entry's own passphrase, with **no `writeOnly` flag on either** (verified: 4 `passphrase`
+properties, 0 `writeOnly` flags, in the staged 10.4.57 spec). `README.md`'s claim that these fields
+are "write-only" was wrong; A2 (kit PR #300) fixed the SDK layer by decoding them `Redacted`
+instead of a plain string, proven at the wire in `errors-and-secrets.test.ts`.
+
+This family goes further and **never calls that shape at all.** The only SDK call
+`wifi-broadcast.ts` makes is `getWifiBroadcastPage` — the LIST endpoint, which answers
+`WifiBroadcastOverview` rows. That type's own `securityConfiguration`
+(`WifiSecurityConfigurationOverview`) is `{type, presharedKeyNetworkIds}`: no passphrase field
+exists on it, so there is no DECLARED field for `attributesOf`/`declareWifiBroadcast` to name a
+passphrase into. A static guard (`wifi-broadcast-details-call.test.ts`) additionally bans any
+source reference to `getWifiBroadcastDetails` itself under `src/unifi` (red team, IMPORTANT-2),
+with one named exception: `errors-and-secrets.test.ts` (A2) calls it directly on purpose, to prove
+the SDK's own redaction happens at the wire — a different, lower-layer claim than this family ever
+needing to make that call.
+
+⛔ **This is NOT enforced by the type system alone** (red team, IMPORTANT-1) — corrected from an
+earlier version of this doc that overclaimed it was. `@distilled.cloud/core`'s wire decode does not
+strip a key a schema doesn't declare, so a stray key nested inside `network`, `hotspotConfiguration`,
+`broadcastingDeviceFilter`, or one `presharedKeyNetworkIds` element could ride through a naive
+pass-through exactly like the top-level `securityConfiguration` object could. See "The stray-key
+defense" below — enumeration at runtime, not the TS annotation, is what actually stops it.
+
+### No get-by-id call exists for the overview shape
+
+Unlike every other family here (`getNetworkDetails`, `getFirewallZone`, `getDnsPolicy`,
+`getAclRule`), `wifi_broadcasts.ts` has no single-object GET that returns the overview shape — only
+the list (safe) and the details call (forbidden above). `wifi-broadcast.ts`'s `fetchLive` walks
+every page with B0b's `pageAll` (`paginate.ts`) and finds the row matching `wifiBroadcastId` — the
+first real resource-level consumer of that pager, previously exercised only in isolation by
+`paginate.test.ts`. A genuine site-not-found 404 on ANY page of the walk — not only the first —
+folds to `undefined` like every other family, discarding whatever rows the walk had already
+collected (red team, MINOR-4: an earlier version of this doc said "on the first page call", which
+overstated how narrowly the catch is scoped); the target id simply not being among the collected
+rows folds to `undefined` too — there is no separate vendor signal to tell any of these cases apart,
+and no other family's `fetchLive` has one either.
+
+### The stray-key defense (why `normalizeSecurityConfiguration` never spreads)
+
+Nothing in `@distilled.cloud/core`'s wire key-mapping strips an object key the schema does not
+declare — it only renames declared ones (measured directly against the installed
+`@distilled.cloud/core@1.0.0-rc.12`: a struct decode keeps every key from the raw response,
+declared or not). So a stray `passphrase`-shaped key on the WIRE `securityConfiguration` object — a
+vendor bug, or a future console version — physically survives into the `live` object `fetchLive`
+returns, even though `WifiBroadcastOverview`'s own TS type has no such field.
+
+`wifi-broadcast-form.ts`'s `normalizeSecurityConfiguration` is the one normalizer in this whole
+`Unifi.*` tree that does **not** use `{...value}` (every sibling normalizer, `network-form.ts`'s
+included, spreads its input). It enumerates exactly `{type, presharedKeyNetworkIds}` instead —
+`attributesOf`/`declareWifiBroadcast` are built the same way, field by field, never `{...live}`.
+
+⛔ **The same discipline applies to every OTHER nested object this family handles, not just
+`securityConfiguration`** (red team, IMPORTANT-1) — `normalizeRef` rebuilds `network` and each
+`presharedKeyNetworkIds` element as `{type, networkId?}`, `normalizeHotspot` rebuilds
+`hotspotConfiguration` as `{type}`, and `normalizeDeviceFilter` no longer spreads
+`broadcastingDeviceFilter` either. A `presharedKeyNetworkIds` element is the single most plausible
+leak site of the four: `IntegrationWifiPresharedKeyDto`, the details-call shape for a PPSK entry, is
+literally `{network: WifiNetworkReference, passphrase}` — the same reference shape this family's
+overview also uses, just with one more field the overview type doesn't declare.
+
+`wifi-broadcast-secrets.test.ts`'s sentinel tests prove the pipeline for all five locations
+(`securityConfiguration`, a `presharedKeyNetworkIds` element, `network`, `hotspotConfiguration`,
+`broadcastingDeviceFilter`): each plants a raw sentinel key that genuinely does survive into `live`
+(asserted directly, not assumed away), then proves `attributesOf`, `declareWifiBroadcast`, and the
+literal string a later import script would render into `alchemy.run.ts` none of them carry it
+forward.
+
+### The forced decode-failure test
+
+`wifi-broadcast-secrets.test.ts`'s decode-failure test sends a non-JSON 200 body (a genuine decode
+failure — this SDK's REST decode has no schema-validating step to reject a malformed body with; see
+`@distilled.cloud/core`'s `protocol-rest.ts`) that happens to contain a sentinel value, the way a
+garbled proxy or debug response might. `pageAll`'s own consistency check (`paginate.ts`) catches it
+— the malformed "page" has no `.offset`, so the walk refuses to trust it — and fails typed as
+`UnifiPaginationInconsistent`. That error's `reason`/`detail`/`message` are built from `offset`/
+`totalCount` values run through `paginate.ts`'s `numOrPlaceholder` (red team, MINOR-3: an earlier
+version of this doc said these fields were "never from the raw response body", but `offset`/
+`totalCount` themselves ARE unvalidated wire values — `paginate.test.ts`'s own test proves a
+non-numeric one renders as a fixed placeholder, never as itself), so none of them can ever echo
+attacker- or vendor-controlled text regardless of what the server actually sent.
+
+## Field-level drift
+
+Three fields are membership SETS, not ordered sequences, by the vendor description's own wording
+("Defines the custom scope of devices…") and unconfirmed against a live console (same caveat
+`network-form.ts` carries for its own three): `broadcastingDeviceFilter.deviceIds`/`.deviceTagIds`
+and `securityConfiguration.presharedKeyNetworkIds`. `wifi-broadcast-form.ts`'s
+`normalizeDeviceFilter`/`normalizeSecurityConfiguration`/`normalizeFrequencies` sort+dedupe them
+before comparison, on both the live AND declared sides (`wifi-broadcast-drift.ts`), the same
+`firewall-zone-form.ts`'s `networkIds` pattern — otherwise a console returning the same set in a
+different order would plan a spurious `update` that a read-only `reconcile` then refuses.
+
+`wifi-broadcast.ts` exports a pure `driftOf(live, props)`, built on `drift.ts`'s `makeDriftOf`
+framework. `matches` is exactly `fieldDrift(...).length === 0` (MEDIUM-4).
+
+## The declaration renderer
+
+`declareWifiBroadcast(live, siteId)` is a pure function: given one `WifiBroadcastOverview` row (as
+`getWifiBroadcastPage` returns it, never `getWifiBroadcastDetails`), it returns the `Props` a
+declaration needs so its plan is a no-op. A later import script pages every WiFi broadcast on a
+site and writes one `wifiBroadcast('<id>', declareWifiBroadcast(live, siteId))` row per result —
+nothing here performs that write.
+
+## 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`.

package/docs/unifi.md

@@ -6,6 +6,11 @@ with a typed `UnifiWriteRefused` naming the policy rather than calling any SDK w
 Lifting the rule is a kit change — a PR that adds a write path, reviewed as one — not a flag a
 stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
 
+This page covers `Unifi.Network`/`Unifi.FirewallZone` only. Every other read-only family has its
+own doc, per family (`docs/unifi.md` would breach the 200-line cap otherwise): [`Unifi.DnsPolicy`](./unifi-dns-policy.md), [`Unifi.AclRule`/`Unifi.AclRuleOrdering`](./unifi-acl-rule.md),
+[`Unifi.WifiBroadcast`](./unifi-wifi.md), [`Unifi.FirewallPolicy`/`Unifi.FirewallPolicyOrdering`](./unifi-firewall-policy.md),
+and [`Unifi.TrafficMatchingList`](./unifi-traffic-matching-list.md).
+
 ## What's declared, and why these two first
 
 `Unifi.Network` (`getNetworkDetails`/`getNetworksOverviewPage`) and `Unifi.FirewallZone`
@@ -13,9 +18,8 @@ stack can pass. See `packages/alchemy/src/unifi/policy.ts`.
 not runtime state (a connected client, a device statistic, a hotspot voucher, a switch stack).
 `Site` was the SDK README's other first suggestion; it has no `getSite`, only the list operation,
 so it fails this house's own "both a list and a get" bar for a first import. `FirewallPolicy` is
-also a list+get config object, but its `source`/`destination`/`ipProtocolScope` fields carry
-several of the vendor's converter-flattened discriminator variants each, and its ordering
-endpoint replaces the whole rule list — modelling that correctly is a bigger, separate PR.
+also a list+get config object; modelling it correctly needed its own PR (now shipped — [`docs/unifi-firewall-policy.md`](./unifi-firewall-policy.md)) because its ordering endpoint replaces the whole
+rule list per zone pair, and it was gated on A3 typing its filter fields' discriminator variants first.
 
 ## Credentials
 
@@ -102,8 +106,9 @@ operations (`getNetworksOverviewPage`, `getFirewallZones`, …), none of which p
 own — no `smithy.api#paginated` trait exists in the pinned spec, and neither the SDK nor
 `@distilled.cloud/core` gained one for this. It stops on the response's `totalCount`, never on
 `data.length < limit` (a page can legitimately come back short of the requested limit without
-being the last page). No family here has enough rows to need it yet; it exists ahead of
-`Unifi.FirewallPolicy` (hundreds of rows on a real console), which does.
+being the last page). `Unifi.WifiBroadcast` (`docs/unifi-wifi.md`) is its first resource-level
+consumer, walking every page because that family has no get-by-id call at all; `docs/unifi-firewall-policy.md`'s own decode-proof test exercises the same page shape for `getFirewallPolicies`
+(hundreds of rows on a real console — T9), though `Unifi.FirewallPolicy` itself still reads by id.
 
 It also fails with a typed `UnifiPaginationInconsistent` — never silently returns a wrong row
 set — the moment a paged response contradicts itself: a page's echoed `offset` doesn't match what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -56,6 +56,10 @@
       "types": "./dist/proxmox/index.d.ts",
       "default": "./dist/proxmox/index.js"
     },
+    "./ceph": {
+      "types": "./dist/ceph/index.d.ts",
+      "default": "./dist/ceph/index.js"
+    },
     "./launchd": {
       "types": "./dist/launchd/index.d.ts",
       "default": "./dist/launchd/index.js"
@@ -127,11 +131,11 @@
     "@distilled.cloud/litellm": "npm:@homeflare/distilled-litellm@0.2.0",
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/openbao": "npm:@homeflare/distilled-openbao@0.2.2",
-    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
+    "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.3.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
     "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.3",
     "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",
-    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.3.0"
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.4.0"
   },
   "peerDependencies": {
     "@distilled.cloud/argocd": "1.0.0-rc.12",

package/src/ceph/auth-entity.ts

@@ -0,0 +1,74 @@
+/**
+ * `Ceph.AuthEntity` (K-A4) — a Ceph client auth entity (`client.k8s-*`), minted over the ssh
+ * mon-command transport and stored only in OpenBao. Design: docs/plans/2026-09-26-ceph-mon-
+ * transport.md, "`Ceph.AuthEntity` (K-A4)"; the loop itself lives in ceph-auth-reconcile.ts, the
+ * transport in ceph-transport.ts, the allowlist in ceph-argv.ts.
+ *
+ * ⛔ `read` AND `diff` NEVER SSH. "A plan never elevates" (../linux/sudo-runner.ts's own header
+ *   makes the same rule for the file family): this family's props/state comparison is the whole
+ *   of `diff`, and `read` hands back exactly the attributes state already holds. Live drift is
+ *   caught only at `reconcile` (which does elevate, on the admin lane) and by the post-deploy
+ *   operator check — this family cannot prove live convergence at plan time, and says so rather
+ *   than pretending an unprivileged probe exists where none does.
+ * ⛔ `delete` IS REFUSED UNCONDITIONALLY. `defaultRemovalPolicy: 'retain'` keeps Alchemy from ever
+ *   calling it on an ordinary `destroy`, and the handler itself refuses too — belt and suspenders
+ *   with ceph-argv.ts's own refusal of the `auth del` shape, so there is no path, `--adopt` or a
+ *   resource-level removal-policy override included, that ever reaches it (D3).
+ * ⛔ NEVER ADOPTED. See ceph-auth-reconcile.ts's header for why the generic `refuseTakeover` is not
+ *   used here.
+ * ⛔ ROWS ARE CREATES THROUGH THE FIRST-CREATE GATE, NO `adopt()` — `list` answers empty, the same
+ *   as every Ceph family in this kit (ceph-pool.ts's header has the reason a non-empty list would
+ *   invite exactly the takeover this family refuses).
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { CephAuthEntityAttributes, CephAuthEntityProps } from './ceph-auth-form.ts';
+import { planCephAuthEntity } from './ceph-auth-form.ts';
+import { reconcileCephAuthEntity } from './ceph-auth-reconcile.ts';
+
+export type { CephAuthEntityAttributes, CephAuthEntityProps } from './ceph-auth-form.ts';
+export type { CephCaps } from './ceph-auth-parse.ts';
+
+export interface CephAuthEntity extends Resource<
+  'Ceph.AuthEntity',
+  CephAuthEntityProps,
+  CephAuthEntityAttributes,
+  never,
+  HttpClient.HttpClient
+> {}
+
+/** ★ `retain` — the delete handler below refuses regardless, but this stops Alchemy calling it. */
+export const CephAuthEntity = Resource<CephAuthEntity>('Ceph.AuthEntity', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const refusedDelete = (entity: string): Error =>
+  new Error(
+    `Ceph.AuthEntity ${entity}: 'ceph auth del' is refused entirely — lockout safety, never ` +
+      'auto-delete (D3). Nothing was sent to any mon. If the entity truly must go, remove it by ' +
+      'hand, deliberately, along with its OpenBao key — this family will never do it for you.',
+  );
+
+export const CephAuthEntityProvider = () =>
+  Provider.effect(
+    CephAuthEntity,
+    Effect.succeed(
+      CephAuthEntity.Provider.of({
+        list: () => Effect.succeed([]),
+
+        /** State only — see the header. Never `Unowned`: this family is never adopted. */
+        read: ({ output }) => Effect.succeed(output),
+
+        /** State only — see the header. `output === undefined` lets reconcile decide (a create). */
+        diff: ({ news, output }) =>
+          Effect.succeed(isResolved(news) ? planCephAuthEntity(news, output) : undefined),
+
+        reconcile: ({ news, output }) => reconcileCephAuthEntity(news, output, {}),
+
+        delete: ({ output }) => Effect.die(refusedDelete(output.entity)),
+      }),
+    ),
+  );

package/src/ceph/ceph-argv-config.ts

@@ -0,0 +1,78 @@
+/**
+ * The `ceph config get/set/rm` half of the argv allowlist — split out of ceph-argv.ts (which
+ * re-exports `configProblem`) purely to keep that file under the house's 250-line file cap; the
+ * split follows the same line the design docs already draw (2026-09-26-ceph-config-options.md is
+ * its own companion to 2026-09-26-ceph-mon-transport.md).
+ *
+ * ⚠️ `<who>` IS NOT YET BOUNDED TO K-D's "declared daemons" (the config-options design's own
+ *   acceptance test #1). `client.admin` still matches this shape. Latent today:
+ *   `NAMED_CONFIG_OPTIONS` starts empty, so `namedOptionProblem` refuses every `config get/set/rm`
+ *   regardless of `who` — LAND red team, 2026-09-26, flagged this as armed only once K-D's first
+ *   named option lands, and narrowing it needs that family's own declared-daemon list, which does
+ *   not exist yet. Tracked for `CephConfigOption` (K-D), not fixed here.
+ */
+import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+
+/** `config`'s `<who>`: a daemon class, optionally `.id` — never a path, never free text. */
+const WHO = /^(global|mon|osd|mgr|mds|client)(\.[A-Za-z0-9_-]{1,32})?$/;
+/** A ceph option name's own shape — snake_case, lowercase. Independent of the named list below. */
+const OPTION_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+/**
+ * No shell metacharacters; the named list (below) is what actually decides secrecy, not this.
+ * ⛔ NO LEADING `-` EXCEPT A NEGATIVE INTEGER, AND NEVER EMPTY. LAND red team (2026-09-26),
+ *   CONFIRMED: the prior pattern let a config VALUE start with `-`, and this argv reaches
+ *   `sudo -n /usr/bin/ceph` with no shell in between — no shell means no quoting boundary, so
+ *   `ceph config set global x -o/etc/ceph/ceph.conf` parses as ceph's own `-o <file>` flag, not
+ *   as the string `-o/etc/ceph/ceph.conf`. Accepted flag-shaped values included
+ *   `--admin-daemon=/var/run/ceph/ceph-mon.a.asok`, `--conf=/tmp/x`, `-n`, and the empty string.
+ *   The sudoers entry has no argument restriction of its own (that is D4, a later step), so this
+ *   allowlist is the only thing standing between a config value and an arbitrary ceph CLI flag.
+ *   Latent while `NAMED_CONFIG_OPTIONS` is empty; K-D's first entry arms it.
+ */
+const CONFIG_VALUE = /^(?:[A-Za-z0-9][A-Za-z0-9 ._:/=,-]{0,255}|-[0-9]{1,255})$/;
+
+/**
+ * `undefined` when `value` is a safe ceph config value — exported (like `boundedEntityProblem`)
+ * so the shape itself is directly testable, since `NAMED_CONFIG_OPTIONS` being empty today means
+ * `cephCommandProblem` never reaches this check on any real argv (`namedOptionProblem` refuses
+ * first) — this stays exercised until K-D's first named option arms the path for real.
+ */
+export const configValueProblem = (value: string): string | undefined =>
+  CONFIG_VALUE.test(value)
+    ? undefined
+    : `config value ${JSON.stringify(value)} contains characters outside the safe set`;
+
+/**
+ * `undefined` when `name` may be declared, adopted, read by value or written — see
+ * ceph-config-options.ts's header for why the list starts empty and stays reviewed line by line.
+ */
+const namedOptionProblem = (name: string): string | undefined => {
+  if (!OPTION_NAME.test(name)) return `${JSON.stringify(name)} is not a plain ceph option name`;
+  if (isLockoutConfigOption(name))
+    return `${name} is a lockout-class option and can never be declared`;
+  return NAMED_CONFIG_OPTIONS.has(name)
+    ? undefined
+    : `${name} is not on the named option list (it starts empty — see ceph-config-options.ts)`;
+};
+
+/** `config get|set|rm <who> <name> [value]`, called with the operands after `config` stripped. */
+export const configProblem = (rest: readonly string[]): string | undefined => {
+  const [verb, who, name, ...extra] = rest;
+  if (who === undefined || !WHO.test(who)) {
+    return 'config takes a bounded `<who>` (global/mon/osd/mgr/mds/client[.id])';
+  }
+  if (name === undefined) return 'config takes a `<name>` from the named option list';
+  if (verb === 'get' || verb === 'rm') {
+    return extra.length === 0
+      ? namedOptionProblem(name)
+      : `config ${String(verb)} takes exactly \`<who> <name>\``;
+  }
+  if (verb === 'set') {
+    const [value, ...more] = extra;
+    if (value === undefined || more.length !== 0)
+      return 'config set takes exactly `<who> <name> <value>`';
+    const named = namedOptionProblem(name);
+    return named !== undefined ? named : configValueProblem(value);
+  }
+  return `ceph config ${String(verb)} is not on the allowlist`;
+};