@homeflare/alchemy 0.38.0 → 0.39.0

package/dist/unifi/network-form.d.ts

@@ -1,4 +1,38 @@
+/**
+ * `Unifi.Network`'s wire shape: the declarable subset of `NetworkDetails`, and how a live read
+ * becomes both plan attributes and a rendered declaration.
+ *
+ * ⚠️ PROPS MIRROR `UpdateNetworkRequest`, NOT `NetworkDetails`. `default` and `metadata` are
+ *   server-derived — no writable endpoint in `networks.ts` accepts either — so they are
+ *   attributes-only, reported but never compared or declared. Everything else in `NetworkProps`
+ *   is exactly what `updateNetwork`/`createNetwork` would accept, even though this family never
+ *   calls either: the shape is what a future write path would need, and what today's read-only
+ *   `matches` compares against.
+ *
+ * ⛔ `ipv4Configuration` STAYS `unknown`, ON THE SDK'S OWN AUTHORITY. `networks.ts`'s own comment
+ *   ("Shape varies by variant — widened by scripts/convert.ts; see README") says the OpenAPI
+ *   discriminator this field varies over was flattened at generation time, not decoded per
+ *   variant. Comparing it as an opaque JSON value (below) is honest about that; guessing a
+ *   narrower shape here would silently stop matching the day a new variant's key order differs.
+ *   ⚠️ It may ALSO hide an unordered array the way `dhcpGuarding` and `ipv6Configuration` do
+ *   below — this family just can't know, because the shape is never decoded. If a future variant
+ *   plans spurious `update`s, suspect this field first and widen it into a typed, order-normalized
+ *   shape rather than adding another opaque comparison.
+ *
+ * ⛔ THREE FIELDS ARE SETS, NOT SEQUENCES: `dhcpGuarding.trustedDhcpServerIpAddresses`,
+ *   `ipv6Configuration.additionalHostIpSubnets`, and `ipv6Configuration.dnsServerIpAddressesOverride`.
+ *   The vendor document gives no indication any of the three is ordered — same reasoning
+ *   `firewall-zone-form.ts` gives for `networkIds`, and `proxmox/user-wire.ts`'s `groupSet` gives
+ *   for PVE's `groups` — but `matches` compares via alchemy's `deepEqual`, which sorts object KEYS
+ *   but NOT ARRAY ELEMENTS (`node_modules/alchemy/lib/Diff.js`). Left alone, a console that
+ *   returns the same set in a different order between calls plans a spurious `update`, and the
+ *   read-only reconcile then refuses every deploy. `sortedSet` (dedupe + sort) neutralizes that
+ *   before any of the three is attributed, declared, or compared. Every OTHER array field in this
+ *   family (there are none today besides these three) would stay declaration-order as written.
+ */
 import type * as networks from '@distilled.cloud/unifi-network/networks';
+export declare const normalizeDhcpGuarding: (value: networks.NetworkDHCPGuarding | undefined) => networks.NetworkDHCPGuarding | undefined;
+export declare const normalizeIpv6Configuration: (value: networks.NetworkIPv6Configuration | undefined) => networks.NetworkIPv6Configuration | undefined;
 /**
  * ⚠️ EVERY OPTIONAL FIELD SPELLS OUT `| undefined` ON PURPOSE. `tsconfig.json` sets
  *   `exactOptionalPropertyTypes`, which treats `field?: T` (absent-or-T) and
@@ -47,14 +81,13 @@ export interface NetworkAttributes {
 }
 export declare const attributesOf: (live: networks.NetworkDetails, props: NetworkProps) => NetworkAttributes;
 /**
- * ⚠️ `stripNullish: true` ON EVERY COMPARISON. UniFi's JSON answers `null` for an unset optional
- *   field; a declaration that omits the same prop carries `undefined`. Without this option every
- *   plan against an object with one unset optional field would report `update` forever — the
- *   exact "read and write are different shapes" trap `netbox/values.ts` and `proxmox/user-wire.ts`
- *   both work around, here solved once with the engine's own `deepEqual` instead of a per-field
- *   coercion, because nothing here needs PVE's or NetBox's extra wire-format translation.
+ * MEDIUM-4 (red team, 2026-09-26): `matches` used to be a hand-written boolean expression here,
+ * kept in sync BY HAND with `network-drift.ts`'s separately-maintained field list — two comparisons
+ * that could (and, per a red-team mutant, silently did) drift apart. `matches` now lives in
+ * `network-drift.ts`, defined as `fieldDrift(...).length === 0` — the SAME comparison `driftOf`
+ * runs, not a second one. See that file's own header for the `stripNullish`/normalizer reasoning
+ * this expression used to carry.
  */
-export declare const matches: (attributes: NetworkAttributes, props: NetworkProps) => boolean;
 /**
  * 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 `getNetworkDetails`'s own response

package/dist/unifi/network-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-form.d.ts","sourceRoot":"","sources":["../../src/unifi/network-form.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,KAAK,QAAQ,MAAM,yCAAyC,CAAC;AAwCzE;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,QAAQ,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACxD,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,QAAQ,CAAC,wBAAwB,GAAG,SAAS,CAAC;IAClE,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,QAAQ,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvD,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,QAAQ,CAAC,wBAAwB,GAAG,SAAS,CAAC;IACjE,gBAAgB,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,eAAO,MAAM,YAAY,SACjB,QAAQ,CAAC,cAAc,SACtB,YAAY,KAClB,iBAiBD,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,eAAgB,iBAAiB,SAAS,YAAY,KAAG,OA6BL,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,SAAU,QAAQ,CAAC,cAAc,UAAU,MAAM,KAAG,YAgB7E,CAAC"}
+{"version":3,"file":"network-form.d.ts","sourceRoot":"","sources":["../../src/unifi/network-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,KAAK,QAAQ,MAAM,yCAAyC,CAAC;AAgBzE,eAAO,MAAM,qBAAqB,UACzB,QAAQ,CAAC,mBAAmB,GAAG,SAAS,KAC9C,QAAQ,CAAC,mBAAmB,GAAG,SAG6D,CAAC;AAOhG,eAAO,MAAM,0BAA0B,UAC9B,QAAQ,CAAC,wBAAwB,GAAG,SAAS,KACnD,QAAQ,CAAC,wBAAwB,GAAG,SAWhC,CAAC;AAER;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,QAAQ,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACxD,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,QAAQ,CAAC,wBAAwB,GAAG,SAAS,CAAC;IAClE,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,qBAAqB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,QAAQ,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvD,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,QAAQ,CAAC,wBAAwB,GAAG,SAAS,CAAC;IACjE,gBAAgB,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,eAAO,MAAM,YAAY,SACjB,QAAQ,CAAC,cAAc,SACtB,YAAY,KAClB,iBAiBD,CAAC;AAEH;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,SAAU,QAAQ,CAAC,cAAc,UAAU,MAAM,KAAG,YAgB7E,CAAC"}

package/dist/unifi/network.d.ts

@@ -26,6 +26,7 @@ import { type NetworkAttributes, type NetworkProps } from './network-form.ts';
 import type { UnifiRequirements, UnifiSpec } from './resource.ts';
 export type { NetworkAttributes, NetworkProps } from './network-form.ts';
 export { declareNetwork } from './network-form.ts';
+export { driftOf } from './network-drift.ts';
 export interface UnifiNetwork extends Resource<'Unifi.Network', NetworkProps, NetworkAttributes, never, UnifiRequirements> {
 }
 export declare const UnifiNetwork: import("alchemy").ResourceClass<UnifiNetwork>;

package/dist/unifi/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/unifi/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,QAAQ,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGlE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAC5C,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,iBAAiB,CAClB;CAAG;AAEJ,eAAO,MAAM,YAAY,+CAEvB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,OAAQ,MAAM,SAAS,YAAY,6FACZ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,SAAS,CAC1B,YAAY,EACZ,QAAQ,CAAC,cAAc,EACvB,iBAAiB,EACjB,QAAQ,CAAC,sBAAsB,CAUhC,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;CAAsB,CAAC;AAE5C,eAAO,MAAM,oBAAoB,kIACkD,CAAC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/unifi/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,QAAQ,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAgB,MAAM,mBAAmB,CAAC;AAE5F,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGlE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAInD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAC5C,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,iBAAiB,CAClB;CAAG;AAEJ,eAAO,MAAM,YAAY,+CAEvB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,OAAQ,MAAM,SAAS,YAAY,6FACZ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,SAAS,CAC1B,YAAY,EACZ,QAAQ,CAAC,cAAc,EACvB,iBAAiB,EACjB,QAAQ,CAAC,sBAAsB,CAUhC,CAAC;AAEF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;CAAsB,CAAC;AAE5C,eAAO,MAAM,oBAAoB,kIACkD,CAAC"}

package/dist/unifi/paginate.d.ts

@@ -0,0 +1,36 @@
+import * as Effect from 'effect/Effect';
+/** The one response shape every UniFi Network list operation already has (`protocol.ts`). */
+export interface OffsetPage<T> {
+    readonly data: readonly T[];
+    readonly offset: number;
+    readonly totalCount: number;
+}
+/** The one request shape every UniFi Network list operation already accepts, plus its own fields. */
+export type OffsetPageRequest = {
+    readonly offset?: number;
+    readonly limit?: number;
+};
+declare const UnifiPaginationInconsistent_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UnifiPaginationInconsistent";
+} & Readonly<A>;
+export declare class UnifiPaginationInconsistent extends UnifiPaginationInconsistent_base<{
+    readonly reason: 'offset-mismatch' | 'total-count-changed' | 'row-count-mismatch' | 'page-ceiling';
+    readonly detail: string;
+}> {
+    get message(): string;
+}
+/**
+ * Walks every page of `fetchPage`, starting at `request.offset ?? 0`, and returns every row in
+ * order. `request.limit`, if given, is kept as the page size for every call; the vendor's own
+ * default applies otherwise — this loop never invents one (T18: "pass ops only their own fields").
+ *
+ * Three self-consistency checks run against fields the vendor already sends with every page —
+ * detection, not a fix, for the "live console mutates mid-walk" case the header above accepts as
+ * unfixable from the client alone: a row added AND removed in the same window can still net out to
+ * a `totalCount` and final row count that agree by coincidence. What this closes is the SILENT
+ * version of every case actually observed in review: an ignored `offset`, a `totalCount` that
+ * drifts between calls, and an undercounted `totalCount` that truncates the walk early.
+ */
+export declare const pageAll: <Req extends OffsetPageRequest, T, E, R>(fetchPage: (request: Req) => Effect.Effect<OffsetPage<T>, E, R>, request: Req) => Effect.Effect<T[], E | UnifiPaginationInconsistent, R>;
+export {};
+//# sourceMappingURL=paginate.d.ts.map

package/dist/unifi/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../../src/unifi/paginate.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,6FAA6F;AAC7F,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qGAAqG;AACrG,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;;;;AAQtF,qBAAa,2BAA4B,SAAQ,iCAAgD;IAC/F,QAAQ,CAAC,MAAM,EACX,iBAAiB,GACjB,qBAAqB,GACrB,oBAAoB,GACpB,cAAc,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAK7B;CACF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,SAAS,iBAAiB,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,aACjD,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,WACtD,GAAG,KACX,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,2BAA2B,EAAE,CAAC,CA4CpD,CAAC"}

package/dist/unifi/resource.d.ts

@@ -1,7 +1,7 @@
 import type { Input } from 'alchemy/Input';
 import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
 import * as Effect from 'effect/Effect';
-import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
 /** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
 export type UnifiRequirements = HttpClient.HttpClient;
 /**
@@ -34,6 +34,41 @@ export declare const unifiOperations: <Props extends object, Live, Attributes ex
     reconcile: (news: Props) => Effect.Effect<Attributes, E | import("./policy.ts").UnifiWriteRefused, UnifiNetworkOpContext>;
     destroy: (olds: Props) => Effect.Effect<never, import("./policy.ts").UnifiWriteRefused, never>;
 };
+/**
+ * B0a / T12 DEFENSE IN DEPTH. `policy.ts`'s `UnifiWriteRefused` stops write INTENT at
+ * `reconcile`/`destroy` — every path this engine exposes already returns that refusal instead of
+ * calling an SDK write op. This guard stops the same thing one layer lower, AT THE WIRE: it wraps
+ * whatever `HttpClient` the caller already provides (the stack's `FetchHttpClient.layer` in
+ * production, `fakeUnifiLayer` in tests — `openbao/bao-http.ts`'s header names this same
+ * "wrap, don't replace" seam) so a future resource file that, by mistake, called an SDK write
+ * operation directly — bypassing `unifiOperations` entirely — would still never reach the vendor
+ * API. `write-op-reference.test.ts` proves no such call exists today; this is what stops one from
+ * ever taking effect if one is ever added.
+ *
+ * ⚠️ `Effect.die`, NOT A TYPED FAILURE — classified per distilled-doctrine's "classify every
+ *   die/orDie". Every generated SDK operation (`networks.getNetworkDetails`, …) declares its OWN
+ *   closed error union from the pinned OpenAPI spec, and generated files are never hand-edited to
+ *   add a member to it. A typed `Effect.fail` here would be a failure mode absent from every op's
+ *   declared type the moment it occurred — a type-system lie. A defect is the sound way to add a
+ *   NEW "this must be structurally impossible" failure underneath types this package does not
+ *   own, exactly like `openbao`'s `refuse()` helpers' `Effect.die(new Error(...))` for a
+ *   configuration move that should never be reachable.
+ */
+export declare class UnifiNonGetRequest extends Error {
+    readonly method: string;
+    /** PATH ONLY, never the full URL — see `requestPath` below. */
+    readonly path: string;
+    constructor(method: string, 
+    /** PATH ONLY, never the full URL — see `requestPath` below. */
+    path: string);
+}
+/**
+ * A `Layer` that reads whatever `HttpClient` is already in the calling context and replaces it,
+ * for everything downstream, with `guardGetOnly`'s wrapped version (`HttpClient.layerMergedContext`
+ * — see the guard above). Exported so `get-only-guard.test.ts` can prove the mechanism directly,
+ * against a bare `HttpClient` service, without needing `CredentialsFromEnv` or any env var at all.
+ */
+export declare const GetOnlyHttpClient: import("effect/Layer").Layer<HttpClient.HttpClient, never, HttpClient.HttpClient>;
 /**
  * The four provider handlers for a spec'd read-only UniFi object, wired once.
  *

package/dist/unifi/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/unifi/resource.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAGnE,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,IAAI;IAChF,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAChG,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAChF,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;kBAEtB,KAAK;oCAQQ;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;iBAUlE,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBAElC,MAAM;;sBAIP,KAAK;oBAYP,KAAK;CAExB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAC9E,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAMzC,IAAI;IACJ,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;IAE5D,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBAtCtB,QAAQ;;yBAElC,MAAM;;IAsCzB,SAAS,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACjC,MAAM,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAEjC,CAAC"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/unifi/resource.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAG9D,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,IAAI;IAChF,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAChG,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAChF,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;kBAEtB,KAAK;oCAQQ;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;iBAUlE,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBAElC,MAAM;;sBAIP,KAAK;oBAYP,KAAK;CAExB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM;IAHvB,YACW,MAAM,EAAE,MAAM;IACvB,+DAA+D;IACtD,IAAI,EAAE,MAAM,EAStB;CACF;AA0BD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,mFAE7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAC9E,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAMzC,IAAI;IACJ,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;IAE5D,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBA5GtB,QAAQ;;yBAElC,MAAM;;IA4GzB,SAAS,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACjC,MAAM,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAEjC,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.md

@@ -74,6 +74,56 @@ need a write); an exact match returns the live attributes and calls nothing.
 `GET /v1/sites/{siteId}/networks` answers every network on the site. Adoption stays explicit —
 the same reasoning `Proxmox.User`'s and NetBox's own `list` give.
 
+## Defense in depth: GET-only at the wire (2026-09-26)
+
+`policy.ts`'s `UnifiWriteRefused` stops write INTENT at `reconcile`/`delete` — this family calls
+no SDK write op anywhere today. `GetOnlyHttpClient` (`resource.ts`, barrel-exported so
+`homeflare-network`'s own import-layer guard can reuse it instead of re-implementing the same
+wrap), installed in `unifiHandlers`'s `withCredentials`, stops the same thing one layer lower, AT
+THE WIRE: it wraps whatever `HttpClient` the caller provides so ANY non-`GET` method dies with
+`UnifiNonGetRequest` (its message carries the request PATH only, never the host — a cloud
+connector's base URL embeds the account's Console ID) before the request reaches the transport —
+a backstop for a future resource file that, by mistake, called an SDK write operation directly.
+`write-op-reference.test.ts` is the matching static check: it harvests the SDK's real write-op
+export names straight from its own service modules (every name starting
+`create`/`update`/`delete`/`patch`/`execute`/`remove`/`adopt`) and fails any file that mentions
+the SDK's package specifier and contains one of those names as a token anywhere — an identifier, a
+bracket key, a destructured binding, a re-export or a dynamic-import property access all read the
+same way, so one scan catches every syntax form without parsing which one it is.
+`get-only-guard.test.ts` proves the wire guard's mechanism directly against a fake `HttpClient`,
+AND that `unifiHandlers` actually installs it (a handler-level probe, not just the mechanism in
+isolation — `network.test.ts`/`firewall-zone.test.ts` call the lower-level `unifiOperations(spec)`
+directly and never exercise `withCredentials` at all).
+
+## Pagination helper
+
+`paginate.ts`'s `pageAll` is a CONSUMER-SIDE sequential offset pager for the SDK's list
+operations (`getNetworksOverviewPage`, `getFirewallZones`, …), none of which paginate on their
+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.
+
+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
+was requested, `totalCount` changes between calls, the final row count disagrees with
+`totalCount - startOffset`, or the walk exceeds a hard page ceiling without ever converging. Each
+is a vendor-data condition, not a defect (distilled-doctrine): the caller may legitimately want to
+retry or report on one, so it is an `Effect.fail`, not an `Effect.die`.
+
+## Field-level drift
+
+`network.ts`/`firewall-zone.ts` each export a pure `driftOf(live, props)` (`network-drift.ts`,
+`firewall-zone-form.ts`). Both `driftOf` and `matches` are now built on the SAME `fieldDrift` list
+(`drift.ts`'s `makeDriftOf` framework) — `matches` is exactly `fieldDrift(...).length === 0`, not
+a second hand-written comparison kept in sync by hand, so the two cannot quietly disagree (a
+red-team mutant that deleted a `fieldDrift` entry outright, 2026-09-26, is what found the previous
+version's gap). Where `matches` collapses a comparison to one boolean, `driftOf` returns one entry
+per field that actually differs, each carrying its own live and declared value — the shape a
+future pre-import drift check (`homeflare-network`) needs to show WHICH fields changed before
+overwriting a committed declaration.
+
 ## The declaration renderer
 
 `declareNetwork(live, siteId)` and `declareFirewallZone(live, siteId)` are pure functions: given
@@ -136,3 +186,9 @@ delete it cannot perform is moot. No `Effect.orDie`/`Effect.die` anywhere in the
 attributed, declared or compared. Both declaration renderers and both `matches` use
 `value == null` / `deepEqual(..., { stripNullish: true })` consistently, per `network-form.ts`'s
 own header. No departure found — nothing in this family needed changing.
+
+⚠️ **Correction (2026-09-26):** the line above is no longer true as written. `resource.ts` now
+has exactly one `Effect.die` — `GetOnlyHttpClient`'s guard (see "Defense in depth" above) —
+classified in its own comment per distilled-doctrine's "classify every die/orDie": it raises a
+NEW defect for a failure mode outside every generated SDK operation's declared error union, never
+converts an existing typed failure the way `orDie` would. Still no `Effect.orDie` anywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.38.0",
+  "version": "0.39.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",
@@ -100,6 +100,10 @@
       "types": "./dist/verify/index.d.ts",
       "default": "./dist/verify/index.js"
     },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "default": "./dist/telemetry/index.js"
+    },
     "./discord": {
       "types": "./dist/discord/index.d.ts",
       "default": "./dist/discord/index.js"
@@ -127,7 +131,7 @@
     "@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.2.0"
+    "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.3.0"
   },
   "peerDependencies": {
     "@distilled.cloud/argocd": "1.0.0-rc.12",

package/src/forgejo/team-member.test.ts

@@ -4,6 +4,7 @@
  * alongside the SDK's own `NotFound`. Proves the two stay distinct: only the SDK's tag folds.
  */
 import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
 import * as organization from '@distilled.cloud/forgejo/organization';
 import * as Effect from 'effect/Effect';
 import { fakeFailure, fakeForgejo, fakeForgejoLayer } from './fake-forgejo.ts';
@@ -95,3 +96,16 @@ describe('Forgejo.TeamMember spec — the actual exported production functions',
     expect(await readThrough(fake.fetch)).toBeUndefined();
   });
 });
+
+test('ForgejoTeamMember declares defaultRemovalPolicy: retain on the Resource() call itself', () => {
+  // ⛔ Anchored on the `Resource<ForgejoTeamMember>(...)` CALL, not on the substring appearing
+  //   anywhere in the file — team-member.ts's own header comment also says the phrase in prose, so
+  //   a plain `source.toContain(...)` (database-refusals.test.ts's simpler version, safe there
+  //   because database.ts's header never repeats the phrase) would pass here even if the option
+  //   were dropped from the actual call. mini PR 82's red team (970e8be) had to pipe
+  //   `RemovalPolicy.retain()` onto every call site because the kit resource had no default; this
+  //   proves the kit default carries the fix so a caller no longer has to remember its own.
+  const source = readFileSync(new URL('./team-member.ts', import.meta.url), 'utf8');
+  const call = source.match(/Resource<ForgejoTeamMember>\([\s\S]*?\);/);
+  expect(call?.[0]).toContain("defaultRemovalPolicy: 'retain'");
+});

package/src/forgejo/team-member.ts

@@ -22,6 +22,31 @@
  *   cannot create a team.
  *
  * ⛔ TOKEN NEEDS `write:organization` TO ADD OR REMOVE, and an identity allowed to manage the team.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — FOUND 2026-09-25 by reading the source, not by measuring
+ *   anything (mini PR 82's red team, `homeflare-mini` 970e8be): before this, `ForgejoRepository`/
+ *   `ForgejoOrgLabel` defaulted to retain in the kit itself but this family did not, so alchemy's
+ *   own engine fallback (`destroy`) applied to it — every caller had to remember its own
+ *   `.pipe(RemovalPolicy.retain())`, the way mini's `src/forgejo/declare.ts` did for
+ *   `forgejo-provision`'s row. Dropping a `TeamMember` declaration — toggling a feature gate off,
+ *   renaming the resource id — must not silently call `organization.orgRemoveTeamMember` and
+ *   revoke a real membership; that is the same "removal from the stack is not removal from
+ *   Forgejo" posture `ForgejoOrgLabel` and `ForgejoBranchProtection` already take, this family
+ *   exists to attach a stack's identity to a team it never creates or destroys (`teamIdOf` below
+ *   only ever locates the team, never manages it), and the same trade-off alchemy's own
+ *   `GitHub.Collaborator` and `GitHub.TeamAccess` make for the identical reason — "preventing
+ *   accidental lockout" (`GitHub/Collaborator.ts:127`, `GitHub/TeamAccess.ts:145` in the pinned
+ *   alchemy source). The trade-off, stated plainly: removing a declaration no longer revokes
+ *   access on its own — the plan shows that row as `orphaned`, not `delete`. Opt into a real
+ *   revoke with `.pipe(RemovalPolicy.destroy())`; `destroy` below is fully implemented.
+ *
+ * ⚠️ THE DEFAULT ONLY PROTECTS A ROW ALREADY IN STATE ONCE THIS RELEASE IS DEPLOYED. Alchemy's
+ *   plan reads `removalPolicy` off the *persisted row* (`Plan.ts`'s delete-node builder), not off
+ *   this default; the default only reaches an existing row's state on a deploy where the resource
+ *   plans as a no-op (`Apply.ts`'s noop path rewrites it and logs "removal policy destroy →
+ *   retain"). A consumer that bumps to this release and drops a `TeamMember` declaration in the
+ *   SAME deploy still gets `delete`, not `orphaned` — see the changeset for the two-deploy shape
+ *   this implies for both adopting retain and opting back into destroy.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
@@ -52,7 +77,9 @@ export interface ForgejoTeamMember extends Resource<
   ForgejoRequirements
 > {}
 
-export const ForgejoTeamMember = Resource<ForgejoTeamMember>('Forgejo.TeamMember');
+export const ForgejoTeamMember = Resource<ForgejoTeamMember>('Forgejo.TeamMember', {
+  defaultRemovalPolicy: 'retain',
+});
 
 export class ForgejoTeamNotFoundError extends Data.TaggedError('ForgejoTeamNotFoundError')<{
   readonly message: string;

package/src/proxmox/constraints-required.test.ts

@@ -80,6 +80,7 @@ describe('every create this package makes, and what the vendor requires of it',
       'pve:POST /nodes/{node}/lxc': ['ostemplate', 'vmid'],
       'pve:POST /nodes/{node}/network': ['iface', 'type'],
       'pve:POST /nodes/{node}/qemu': ['vmid'],
+      'pve:POST /nodes/{node}/storage/{storage}/download-url': ['content', 'filename', 'url'],
       'pve:POST /pools': ['poolid'],
       'pve:POST /storage': ['storage', 'type'],
     });

package/src/proxmox/generated/constraints/index.ts

@@ -22,6 +22,7 @@ import { PVE_NODES_DISKS_CONSTRAINTS } from './pve-nodes-disks.ts';
 import { PVE_NODES_LXC_CONSTRAINTS } from './pve-nodes-lxc.ts';
 import { PVE_NODES_NETWORK_CONSTRAINTS } from './pve-nodes-network.ts';
 import { PVE_NODES_QEMU_CONSTRAINTS } from './pve-nodes-qemu.ts';
+import { PVE_NODES_STORAGE_CONSTRAINTS } from './pve-nodes-storage.ts';
 import { PVE_POOLS_CONSTRAINTS } from './pve-pools.ts';
 import { PVE_STORAGE_CONSTRAINTS } from './pve-storage.ts';
 import { PBS_CONFIG_CONSTRAINTS } from './pbs-config.ts';
@@ -41,6 +42,7 @@ export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>>
   ...PVE_NODES_LXC_CONSTRAINTS,
   ...PVE_NODES_NETWORK_CONSTRAINTS,
   ...PVE_NODES_QEMU_CONSTRAINTS,
+  ...PVE_NODES_STORAGE_CONSTRAINTS,
   ...PVE_POOLS_CONSTRAINTS,
   ...PVE_STORAGE_CONSTRAINTS,
   ...PBS_CONFIG_CONSTRAINTS,
@@ -52,4 +54,4 @@ export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>>
  * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
  *   changing a 128 to a 129 by hand is. `tests/schema-manifest.test.ts` recomputes it.
  */
-export const PROXMOX_CONSTRAINTS_DIGEST = '56eba80750ddb1d2';
+export const PROXMOX_CONSTRAINTS_DIGEST = '8b6745a471839974';

package/src/proxmox/generated/constraints/pve-access.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-backup.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *