@homeflare/alchemy 0.37.0 → 0.37.2

package/docs/changelog/archive-03.md

@@ -0,0 +1,179 @@
+# Alchemy changelog archive 3
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+**The unit is the group, not the rule** — measured: `PUT /v1/provisioning/folder/{FolderUID}/
+rule-groups/{Group}` takes the evaluation `interval` AND the full ordered `rules[]` together,
+replacing the whole group in one call; the individual per-rule operations have no `interval` field
+at all and cannot reorder rules within a group. Declaring rules one at a time would leave a group's
+interval and rule order either undeclarable or racy across independent resources with no shared
+source of truth. Mirrors Terraform's own `grafana_rule_group` resource.
+
+Rule order is significant and never reordered — `subset-match.ts`'s existing position-significant
+array comparison, proven by a dedicated test that declares the same two rules reversed and asserts
+a mismatch. `uid` is required on every declared rule (this family's doctrine everywhere else).
+Volatile fields (`id`, `updated`, `provenance`) are stripped before comparison by a new
+`normalizeRule` (`alert-rule-group-model.ts`, mirroring `dashboard-model.ts`'s `normalizeModel`),
+each measured against the read vs. write SDK shapes; `folderUID`/`ruleGroup` are forced to the
+group's own canonical values and `orgID` defaults to `1` (not measured against a multi-org
+instance — none exists in this house yet).
+
+**Foreign-provenance refusal is per rule, whole-group refuse.** The `AlertRuleGroup` type itself
+carries no top-level `provenance` field (measured) — each rule inside `rules[]` has its own, and
+Grafana's docs say a new rule's provenance must match its group's, so this resource checks every
+live rule via the shared `alerting-provenance.ts` (including the missing-means-foreign fix an
+adversarial review of kit PR 250 established) and refuses the whole group's write if any rule is
+foreign, naming the first one found. An empty live group has nothing to refuse on.
+
+**A declared group whose folder does not exist refuses — it is never auto-created.** This resource
+makes no folder-existence check of its own and never invokes `Grafana.Folder`'s create path.
+Measured: `RoutePutAlertRuleGroupError` is `BadRequest | Forbidden | GrafanaOpError` with no
+`NotFound` case, so a nonexistent `folderUid` fails the PUT as a typed, uncaught `BadRequest`
+rather than being folded to absent or silently scaffolded — declare a `Grafana.Folder` first.
+
+Delete defaults to `retain` (`defaultRemovalPolicy`) — deleting a group deletes every rule in it in
+one call, the same multi-object-cascade class `Grafana.Folder` already guards this way.
+
+⛔ **Fixed after an adversarial review of this PR: a whole-group write silently dropped any live
+rule not in the declaration.** A human adding a rule in the Grafana UI minutes before a deploy
+(ordinary, writable provenance — nothing for the foreign-provenance refusal to catch) would have
+had it removed with no error, and `diff` only ever said `"update"` with no hint why —
+`alchemy/Diff`'s `Diff` type has no fourth action to carry a lossy update through as. Fixed with a
+loud, non-blocking warning (`alert-rule-group-drop-warning.ts`'s `warnOnDroppedRules`, mirroring
+`proxmox/unreadable-read.ts`'s established pattern): every dropped rule is named by title and uid
+in an `Effect.logWarning`, logged from both a local reimplementation of `diff` (so `bun run plan`
+shows it before anything is written) and from `update` itself. This does NOT refuse the write —
+the group is still the unit, by design — only makes the loss visible.
+
+Tests (`alert-rule-group.test.ts` + `alert-rule-group-model.test.ts` +
+`alert-rule-group-provenance.test.ts`, split three ways to stay under the house's 250-line file cap,
+sharing fixtures from `alert-rule-group-fixtures.ts`) use the family's existing `fake-grafana.ts`
+harness and prove: a GET never carries a body; a nonexistent folder propagates `BadRequest`; a
+foreign-provenance rule (explicit or missing) refuses the whole group while an explicit `""` is
+writable; reordering the same rules shows `update`; and an unchanged declaration is a noop despite
+every rule's `id`/`updated`/`provenance` differing.
+
+### Patch Changes
+
+- [#251](https://github.com/taslabs-net/homeflare-kit/pull/251) [`4ef7909`](https://github.com/taslabs-net/homeflare-kit/commit/4ef790926bdcf5033aae1e31585e9490803aadf7) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `proxmox/*` family's `nodes/storage` sub-area, third resource (decision 43's serial proxmox
+  walk-down, after `access` in PR 231/239, `storage` in PR 243 and `ZfsPool` in PR 246): migrates
+  `Proxmox.NodeNetwork` off `client.ts`'s hand-rolled `pve()`/`pveHandlers` onto
+  `@distilled.cloud/proxmox`'s typed `nodes.getNodeNetwork`/`createNodeNetwork`/`putNodeNetwork2`/
+  `deleteNodeNetwork2`. Split into `node-network.ts` (the resource and its provider),
+  `node-network-wire.ts` (the read side — `readInterfaceOrFail`/`readInterface`, `matches`,
+  `attributesOf`) and `node-network-form.ts` (`NodeNetworkProps`, the write side, and the
+  coercion helpers both other files need) — the storage.ts/storage-form.ts seam.
+
+  **`Proxmox.NetworkApply` stays on `client.ts`, deliberately, not migrated with this PR.** Decision
+  28/29/9 ("NetworkApply stays an operator step") plus two MEASURED reasons, checked directly
+  against `@distilled.cloud/proxmox`'s own source before deciding, not assumed:
+
+  1. `network-apply-read.ts`'s `stagedDiff` reads the ONLY signal this family has for "is anything
+     staged" — `changes`, a SIBLING of `data` in PVE's own envelope
+     (`{"data":[...],"changes":"<unified diff>"}`), not inside it. `@distilled.cloud/proxmox`'s
+     `protocol.ts` `transformResponse` unconditionally returns `body.data ?? {}` for EVERY operation
+     on the protocol, discarding any sibling field before a generated operation's typed output is
+     even built. There is no typed call, current or future, that could see `changes` without a
+     protocol-level change upstream in the distilled package itself.
+  2. `network-apply-read.ts`'s hand-rolled `awaitTask` deliberately collapses a failed poll to
+     "outcome unknown" rather than "task failed", because the member serving the poll can be the
+     very node whose reload just dropped the connection the poll rides on. `@distilled.cloud/
+proxmox`'s own `Task.awaitTask` (`src/task.ts`) does not have this behaviour — it propagates a
+     poll failure as a genuine typed `GetNodeTaskStatusError`, which would fail `NetworkApply`'s
+     `reconcile` outright on the one failure mode it most needs to tolerate.
+
+  Both gaps are documented in `network-apply-read.ts`'s own header now, next to the functions they
+  affect. Revisit when distilled's protocol layer exposes the raw envelope, or its `awaitTask` grows
+  an option to treat a poll failure as unknown rather than fatal.
+
+  **A missing interface is a 400, not a 404 and not the 500 every other migrated family has** —
+  MEASURED against the live cluster (TB4 `n2`, read-role, read-only probe): `GET
+/nodes/n2/network/vmbr9` answers `{"errors":{"iface":"interface does not exist"},"data":null,
+"message":"Parameter verification failed.\n"}` at HTTP 400. `@distilled.cloud/proxmox` types PVE's
+  400 as a genuine typed error, `ParameterVerificationFailed`, carrying the per-field `errors`
+  object rather than collapsing it to an opaque `BadRequest`. Only that exact signal —
+  `error.errors.iface === 'interface does not exist'` — means absent; a different 400 reason, a
+  genuine 500, or a network blip all propagate as real failures rather than being read as "gone".
+
+  **A precise absence signal does not remove the need for the dual-path read.** A first draft
+  reasoned that a parsed, specific absence signal made `readXOrFail`/folding-`readX` and `read`'s
+  `output`-branching unnecessary — every other migrated family carries that pair for the
+  `Drift.ts` gap, but this family's absence check already rejects anything that is not the exact
+  measured 400, so nothing wrongly propagates as absence. A Sonnet adversarial review caught the
+  flaw: precision of the absence signal and safety of folding at a given call site are separate
+  questions. Three of Alchemy's four `read` call sites (`Plan.ts`'s cold-start adoption probe,
+  `Plan.ts`'s interrupted-create recovery, `Apply.ts`'s delete recovery) call `provider.read` with
+  no state to compare against yet and no catch of their own around a typed failure — and `Plan.ts`
+  aggregates every resource's diff/probe effects fail-fast, so one resource's malformed or
+  transiently-failing declaration would abort the whole plan. Folding at those sites is what turns
+  that into a normal `create`/`noop` instead. Fixed by restoring the pair:
+  `readInterfaceOrFail` (non-folding, used by `diff` always and by `reconcile`'s write path) and
+  `readInterface` (folding, used by `read` when `output` is `undefined`, mirroring
+  user.ts/group.ts/storage.ts/zfs-pool.ts). `node-network-wire.ts`'s own header on both functions
+  has the full reasoning.
+
+  **TB4's fabric ports stay excluded, unchanged.** `tb0`/`tb1`/`dummy_c1` (the Thunderbolt mesh
+  SdnFabric owns, per decision 28/29/9) were never declared through this family and still are not —
+  this migration touches only how an interface this family DOES manage gets read and written, never
+  what gets declared through it. The header's own warning about them is carried forward verbatim,
+  now with an explicit pointer to decision 28/29/9.
+
+  Bugs caught before opening the PR, all fixed: an early draft's `diff` forgot to call
+  `unreadableWarning` on a refused-credential row (every OTHER migrated family logs it; this one
+  silently didn't) — self-caught, re-running the full test suite, fixed and now covered by
+  `node-network-read-failure.test.ts`'s own cries-wolf test. An unused import
+  (`ParameterVerificationFailed` imported as a value, needed only as the string tag
+  `Effect.catchTag` matches against) — caught by the pre-commit lint gate. And the dual-path
+  regression above — caught by the adversarial review, not self-caught.
+
+  `node-network-read-failure.test.ts` (new — this family had no dedicated test file before this
+  migration, only the create-form's vendor-constraint proof in `constraints-host-forms.test.ts`)
+  pins the cries-wolf fix, the precise absence signal (a genuinely new interface creates from
+  exactly that 400; a different 400 and a genuine 500 both propagate instead of creating), and the
+  `alchemy drift` fix. Each assertion was confirmed to fail against a deliberately weakened check
+  before landing (the "different 400 propagates" test specifically catches a version of the absence
+  check that matches any 400, not just the measured one).
+
+  **Expected after this releases and the consumer bumps:** no live plan change is expected for
+  `Proxmox.NodeNetwork` specifically — its `read`-role lease could always read the family's three
+  declared interfaces cleanly, so this is a transport migration plus a defensive fix for a bug class
+  not yet measured live for this family. `Proxmox.NetworkApply`'s own plan is unaffected, since it
+  is untouched by this PR.
+
+## 0.34.0
+
+### Minor Changes
+
+- [#250](https://github.com/taslabs-net/homeflare-kit/pull/250) [`0e9c010`](https://github.com/taslabs-net/homeflare-kit/commit/0e9c0109ea21ffaf142db35f6a19bd424b23b9c2) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `grafana/*` ships `Grafana.ContactPoint`, `Grafana.MuteTiming` and `Grafana.MessageTemplate` — the
+  first of three stacked PRs bringing Grafana alerting provisioning under Alchemy (decision 40: every
+  internal alert lands in one place), on the same `@distilled.cloud/grafana@0.2.0` operations that
+  unblocked `Grafana.Folder`/`Grafana.Dashboard`. `Grafana.AlertRuleGroup` and
+  `Grafana.NotificationPolicy` follow in two later PRs. Full detail, including what was measured
+  against the SDK's generated types versus Grafana's own docs (no live call was made in this PR):
+  `docs/grafana-alerting.md`.
+
+  **Shared across the family:** a foreign-provenance refusal (`alerting-provenance.ts`) — every
+  resource reads Grafana's own `provenance` field and refuses a write when it names an owner other
+  than this API (an allowlist of `""`/`"api"`, not a denylist of the known foreign values, so an
+  unnamed future provenance source refuses by default). This is defense in depth: Grafana's alerting
+  provisioning API also enforces it server-side, unlike the classic folder/dashboard write API. No
+  resource in this family ever sets `X-Disable-Provenance` — an object this family declares stays
+  owned by the declaration.
+
+  ⛔ **Fixed after an adversarial review of this PR: the guard failed OPEN.** The first version
+  mapped `live.provenance ?? ''`, so a response that simply omitted the field was indistinguishable
+  from an explicit `""` (`ProvenanceNone`, writable) — a real risk for `Grafana.MuteTiming`
+  specifically, whose `provenance` isn't even in the SDK's declared type and survives only through an
+  unmodeled-key passthrough this house has never observed against a live response. `undefined` is now
+  kept as its own value all the way through `isForeignProvenance`/`refuseIfForeignProvenance`: ONLY a
+  field Grafana explicitly reports as `""` or `"api"` is writable; a missing field refuses, with a
+  message that says so. Every resource has a test pinning all three cases (missing refuses, explicit
+  `""` is writable, `"file"` refuses).
+
+  **`Grafana.ContactPoint`:** no by-uid GET route exists (measured), so `fetchLive` lists every
+  contact point and matches `uid` client-side rather than narrowing by the renameable `name` label. A
+  secure `settings` key is never a literal prop — `secureSettingsRefs` names it, resolved from an env
+  var fresh at write time and merged into `settings` only there (`secret-refs.ts`, extracted from
+  `Grafana.Datasource`'s identical `secureJsonDataRefs` seam so both share one implementation).
+  `matches` excludes every `secureSettingsRefs` key from comparison entirely, since Grafana's plain
+  GET always redacts a secure field.

package/docs/changelog/archive-04.md

@@ -0,0 +1,178 @@
+# Alchemy changelog archive 4
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+**`Grafana.MuteTiming`:** a genuine SDK finding worth restating here — the generated
+`MuteTimeInterval` type has no `provenance`/`version` fields, and its `TimeInterval` type is
+missing the real Alertmanager time-interval fields (`weekdays`/`times`/`months`/etc.) entirely, even
+though Grafana's real API sends and accepts all of them. Proven NOT to be a data-loss gap:
+`@distilled.cloud/core`'s response decoding never runs a strict schema decode, only `JSON.parse`
+plus a key-rename pass that leaves any key a type doesn't model verbatim — confirmed by driving the
+real operation through this family's own fake-Grafana test harness. `mute-timing.ts` reads/writes
+through a small locally-widened type instead of the SDK's own. Tracked in
+`docs/upstream-conformance.md` as a real SDK type-generation gap (the same fix route as the other
+named gaps there) — not attempted here, since `packages/distilled-grafana/src/` is vendored code
+this kit never hand-edits.
+
+**`Grafana.MessageTemplate`:** create and update are the same `PUT` wire call — measured, no
+`routePostTemplate` exists — kept as two spec functions anyway so the shared engine's `diff` reports
+a content change as `update`, not the `replace` it shows for any resource whose `spec.update` is
+undefined.
+
+Tests (`contact-point.test.ts` + `contact-point-secrets.test.ts` + `contact-point-provenance.test.ts`,
+`mute-timing.test.ts`, `message-template.test.ts` — `ContactPoint`'s split three ways to stay under
+the house's 250-line file cap) use the family's existing `fake-grafana.ts` harness and prove: a GET
+never carries a body; a foreign-provenance object (explicit `"file"` or a MISSING field) refuses
+update/destroy with no write sent, and an explicit `""` is writable; a transient failure (401/403)
+propagates rather than folding to absent; an unchanged declaration is a noop despite an injected
+field the declaration never mentioned; and, for `Grafana.ContactPoint`, that a secret value never
+appears in a real `reconcile`'s returned attributes (not just in the declaration, which never held
+it to begin with) — driven end to end through create, then the read-back `resource.ts` always does.
+`subset-match.ts`'s array-length rule is flagged as unverified against a live mute timing and pinned
+by its own test, per the same review.
+
+### Patch Changes
+
+- [#248](https://github.com/taslabs-net/homeflare-kit/pull/248) [`4681702`](https://github.com/taslabs-net/homeflare-kit/commit/46817022ef49186139287d8706be30cb57dbd742) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `@homeflare/alchemy/linux` now re-exports `renderContainerFile` and `containerPathFor` from
+  `Podman.Container`'s pure `.container` file renderer — the same kind of pure helper `renderUnit`/
+  `DEFAULT_UNIT_DIRECTORY` already are for `Systemd.Unit`. A consumer proving its own declared
+  props render into the directive set it expects (an equivalence/fixture test against a live host)
+  previously had no import path to the real renderer and had to reimplement the render contract by
+  hand to write that test at all (found: homeflare-ct100 PR [#1](https://github.com/taslabs-net/homeflare-kit/issues/1)).
+
+## 0.33.0
+
+### Minor Changes
+
+- [#245](https://github.com/taslabs-net/homeflare-kit/pull/245) [`672f60f`](https://github.com/taslabs-net/homeflare-kit/commit/672f60f8ad43b02b1dd151540a2d5f13e716e4f9) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `grafana/*` ships `Grafana.Folder` and `Grafana.Dashboard`, on top of the same
+  `@distilled.cloud/grafana@0.2.0` (aliased onto `@homeflare/distilled-grafana`) operations that
+  fixed the family's SDK gap: `createFolder`/`getFolderByUID`/`updateFolder`/`deleteFolder` and
+  `postDashboard`/`getDashboard`/`deleteDashboard`, plus the typed `PreconditionFailed` (412) for
+  dashboard version conflicts. Same file shape and uid-required doctrine as the existing
+  `Grafana.Datasource` (`resource.ts`'s shared `GrafanaSpec`/`grafanaOperations`/`grafanaHandlers`,
+  `grafanaProviders(target)` for credentials). Full detail, including which claims were measured
+  against the SDK's generated types versus inferred (no live call was made in this PR):
+  `docs/grafana-folder-dashboard.md`.
+
+  **`Grafana.Folder`:** `description` is write-only — MEASURED against the SDK's generated types,
+  `Folder`'s GET response has no `description` field at all though create/update both accept one —
+  so it is sent on every write that declares it but never diffed, the same treatment
+  `Grafana.Datasource` gives `secureJsonDataRefs`. Nesting (`parentUid`) is create-only — MEASURED,
+  `UpdateFolderRequest` has no `parentUid` field — so a declaration whose `parentUid` no longer
+  matches the live folder REFUSES with `GrafanaFolderReparentError` instead of silently doing
+  nothing or deleting-and-recreating under the new parent. `update` sends `version` for optimistic
+  concurrency, but the SDK's own doc comment on `UpdateFolderRequest.version` says "only used by the
+  legacy folder implementation" — unverified whether Grafana's newer unified-storage folder backend
+  honors it at all, flagged rather than presented as a verified 412-style guard. Delete defaults to
+  `defaultRemovalPolicy: 'retain'`: `deleteFolder` takes every dashboard and alert rule in the
+  folder with it, the same multi-object-cascade class `openbao/mount.ts` already guards this way
+  (verified there against Alchemy's own `Apply.ts`, not re-verified here — same engine, same
+  option). A stack that wants the cascade opts in with `.pipe(RemovalPolicy.destroy())`.
+
+  **`Grafana.Dashboard`:** the declared content is the dashboard JSON model, the same shape
+  Grafana's "Export as JSON" produces. `dashboard-model.ts`'s `normalizeModel` strips
+  `id`/`version`/`iteration` and forces `uid` to the resource's own value before any comparison, so
+  a pasted export and a freshly-read live model compare equal and an unchanged dashboard plans as a
+  true noop despite those fields moving on every live save. `panels` and each panel's `targets` are
+  array-order-significant and compared positionally; nothing in a dashboard model needed UniFi's
+  `sortedSet` treatment. **`matches` compares "declaration is a subset of live", not plain
+  equality** (`declaredContentMatches`) — an adversarial review of this PR found plain structural
+  equality made an ordinary, never-edited dashboard show `update` forever, because Grafana's own
+  schema migration on save decorates any panel/target whose `datasource` is absent with an explicit
+  reference; a declaration silent about a field is now tolerated rather than compared, while a field
+  it DOES mention is still caught exactly as before (traded off: an omitted field can no longer
+  force-clear one Grafana or a prior declaration set — see the doc for the full reasoning). Version
+  conflicts (412) fail loudly and are never overwritten blindly: `update` injects the version this
+  resource just read into the model it sends and never sets `overwrite`; a genuine conflict
+  propagates `PreconditionFailed` uncaught and fails the whole reconcile, with the next
+  plan/deploy's own `fetchLive` serving as the re-read. Delete does **not** default to retain — a
+  single-object blast radius, the same class `Grafana.Datasource` already accepts.
+
+  **Both refuse writes to a provisioned (file-managed) object** — `Folder.managedBy` (non-empty) and
+  `DashboardMeta.provisioned`/`provisionedExternalId`, checked in `update`/`destroy` before any SDK
+  call, naming the owning file when Grafana reports one. `matches` still compares structurally
+  regardless, so a mismatched declaration against a provisioned object shows `update` in a plan
+  rather than a silently-hidden noop, and only fails at the point reconcile would actually write;
+  adopting a provisioned object read-only (a declaration matching what is live) never reaches the
+  refusal. ⚠️ `Folder.managedBy`'s exact values are INFERRED from the SDK's schema, not measured —
+  no live instance in this house currently has a file-provisioned folder to read (`teslamate-grafana`
+  has none at all).
+
+  Tests (`folder.test.ts`, `dashboard.test.ts`, `dashboard-model.test.ts`) use the family's existing
+  `fake-grafana.ts` harness — the real distilled protocol, only wire responses faked — and prove:
+  every request carries only its own declared fields (a GET's body is asserted `undefined`, the
+  exact "distilled JSON-encodes unknown keys as a body" trap this family's shared memory names);
+  provisioned objects refuse update/destroy with no write sent; a transient failure (401/403)
+  propagates rather than folding to absent; an unchanged declaration is a noop despite volatile
+  fields differing; and a 412 propagates uncaught.
+
+### Patch Changes
+
+- [#246](https://github.com/taslabs-net/homeflare-kit/pull/246) [`953c361`](https://github.com/taslabs-net/homeflare-kit/commit/953c3617ac5b1cbd06d1c91f6562d2b4f3db346f) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `proxmox/*` family's `nodes/storage` sub-area, second resource (decision 43's serial proxmox
+  walk-down, after `access` in PR 231/239 and `storage` in PR 243): migrates `Proxmox.ZfsPool` off
+  `client.ts`'s hand-rolled `pve()`/`pveOperations` onto `@distilled.cloud/proxmox`'s typed
+  `nodes.getNodeDiskZfs`/`createNodeDiskZfs`/`deleteNodeDiskZfs`. Split into `zfs-pool.ts`
+  (resource + props), `zfs-pool-wire.ts` (the read side) and `zfs-pool-form.ts` (the write side) —
+  the api-token.ts/api-token-form.ts seam.
+
+  **Clears this family's own cries-wolf false updates.** `Proxmox.ZfsPool` reads with the `read`
+  role (`Sys.Audit` on `/` — unlike `Proxmox.Storage`/`Proxmox.Acl`, it never needed `provision` for
+  a GET), and the pre-migration `pveOperations.read` folded any REFUSED mint into "absent" the same
+  way every family did before its own fix — this family just hadn't been measured failing on the
+  agent lane yet, since its privilege requirement is looser. Now wired the same dual-path pattern
+  PR 239/243 established: `readPoolOrFail` (non-folding, used by `diff`, so a genuine transient
+  failure propagates and fails the plan loudly) and `readPool` (folding, used by `createPool`'s
+  settle-poll and by `read`/`reconcile`'s create-detection) — `read`'s own provider hook branches on
+  `output` from the start, so `alchemy drift` never reports a transient failure as a silent
+  `{action: 'missing'}` either.
+
+  **A missing pool is a 500, not a 404** — MEASURED against the live cluster (TB4 `n2`, read-role,
+  read-only probe): `GET /nodes/n2/disks/zfs/<missing>` answers a generic shelled-out `zpool status`
+  command failure at HTTP 500, the same class of measured 500 every other migrated family has.
+
+  **Decision 9's adopt-only mode is preserved exactly**, including the one nuance new to this
+  family: distilled's generated `CreateNodeDiskZfsRequest` marks `devices` and `raidlevel` as
+  REQUIRED fields (no `?`), unlike PVE's own runtime behaviour, which this resource's adopt-only
+  declarations depend on being able to omit. `createForm` stays a loosely-typed `Record<string,
+string>` that can omit both — used for the vendor-constraint check (now `guardForm`, called
+  directly rather than through `guardWrite`, since this is the first migrated family whose
+  create-guard is CONDITIONAL: `guardWrite`'s own signature requires a real `EndpointKey`, but an
+  adopt-only declaration needs `undefined` some of the time) — and a separate `as unknown as` cast
+  builds the distilled-shaped request only at the point `createPool`'s own runtime guard has already
+  confirmed both fields are genuinely present, exactly preserving the pre-migration behaviour.
+
+  **One field needed distilled's hyphen-to-underscore rename** (`draid-config` -> `draid_config`,
+  the property `T.Body("draid-config")` maps back to the wire on the way out) — `storage.ts`/
+  `storage-form.ts`'s own measured finding from PR 243, here for a single field rather than a
+  free-form locator bag.
+
+  **`createPool`'s settle-poll (30 reads, 2s apart) is unchanged in behaviour** — still polling
+  `readPool`, not `@distilled.cloud/proxmox`'s own `Task.awaitTask`, which exists and would remove
+  the "not yet vs. forbidden" ambiguity the settle-poll's own comment already names as a known
+  weakness. Left as a documented follow-up rather than folded into this migration silently: swapping
+  it changes this resource's OBSERVABLE behaviour on a slow create (what a caller sees, and how),
+  which is an improvement to weigh on its own, not a transport swap.
+
+  **Two findings from adversarial review, both pre-existing (unchanged in shape from before this
+  migration, per `git blame`) but newly documented or fixed here:**
+
+  1. A re-run of `deploy` after `createPool`'s give-up `die` can, in a narrow window, POST a SECOND
+     `zpool create` at the same devices while the first worker is still writing them — the same
+     "not yet vs. forbidden" ambiguity the settle-poll already has, just for a retry rather than the
+     first attempt. Not fixed (a real fix needs task-status tracking, not a transport swap); the
+     give-up message and `createPool`'s own header now say so explicitly, where before they only
+     described the ambiguity as a slow-create observability gap.
+  2. `diff` (and its vendor-constraint check) never runs for a genuinely first-ever declaration —
+     upstream `Plan.ts` routes a brand-new resource straight to `create` without ever calling
+     `provider.diff` — so THIS WAS THE ONLY WRITE PATH IN THE FAMILY WITH NO VENDOR CHECK AT ALL,
+     before or after the migration started. Fixed: `createPool` now re-runs `guardForm` immediately
+     before its own POST, the same pattern `ceph-pool.ts`'s hand-written `reconcile` already uses
+     for the same reason.
+
+  **Also found and fixed while responding to that review** (not a finding from the review itself,
+  caught by re-running the full test suite after the changes above): an edit made to drop a dead
+  `matches()` export accidentally deleted the entire `live === undefined` branch of `diff` alongside
+  it, which would have made a genuinely-vanished pool plan `noop` forever instead of `update` —
+  caught immediately by `zfs-pool-adopt.test.ts`'s own pre-existing "an adopted pool that vanishes"
+  test failing, restored before this PR opened, left here for the record rather than silently
+  squashed into the diff.

package/docs/changelog/archive-05.md

@@ -0,0 +1,177 @@
+# Alchemy changelog archive 5
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+`zfs-pool-adopt.test.ts` (the existing coverage — adopt-only noop/adopted, retain-vs-destroy, the
+`ZfsRaidLevel` compile-time refusal) passes unchanged against the migrated code — `fake-pve.ts`'s
+stub is transport-agnostic — plus one new case for finding 2 above (confirmed to reach a live
+`POST` on the fake cluster without the fix, before timing out at the settle-poll). `zfs-pool-read-
+failure.test.ts` (new) pins the cries-wolf fix, the transient-failure propagation, and the
+`alchemy drift` fix, mirroring PR 243's `storage-read-failure.test.ts` — each assertion confirmed
+to fail against the pre-fix code before landing.
+
+**Scope note, not fixed by this PR:** `Proxmox.NodeNetwork` and `Proxmox.NetworkApply` (the rest
+of the "ZFS pools + node network" sub-area) are deferred to a follow-up PR — see that PR's own
+description for why they don't travel with this one.
+
+**Expected after this releases and the consumer bumps:** no live plan change is expected — no
+`Proxmox.ZfsPool` row was among the false-update rows PR 239/243 already fixed (this family's
+`read`-role lease could always read it), so this PR is a transport migration plus a defensive fix
+for a bug class not yet measured live for this specific family.
+
+## 0.32.0
+
+### Minor Changes
+
+- [#236](https://github.com/taslabs-net/homeflare-kit/pull/236) [`3b4a5eb`](https://github.com/taslabs-net/homeflare-kit/commit/3b4a5eb37b1d136d1f899c48bccf50824c13f9bc) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New `@homeflare/alchemy/opnsense` subpath, built on `@distilled.cloud/opnsense` (aliased onto
+  `@homeflare/distilled-opnsense@0.2.0`, generated against `opnsense/core`/`opnsense/plugins`
+  `26.7.2` — **measured live 2026-09-24** over the HTTPS API only, no SSH: the edge reports
+  `26.7.2_2`, one patch ahead of the generation tag, same series; see `docs/opnsense.md`).
+  `Opnsense.Firewall.Alias`, `.Category` and `.Group` (interface groups) are **READ-ONLY BY
+  DESIGN**: `reconcile` and `delete` always fail with a typed `OpnsenseWriteRefused`, naming the
+  policy ("read-only by Tim's rule, 2026-09-24; lifting it is a kit change") — neither handler
+  imports an `add`/`set`/`del`/`toggle` operation from the SDK, and `write-refusal.test.ts` proves
+  no write is reachable from any handler against a fake that fails on any non-GET request.
+
+  `read` follows upstream's `Snippet.ts` reference for a marker-less API exactly: a cold match is
+  `Unowned`, never a silent adopt, and each resource's convenience constructor
+  (`firewallAlias`/`firewallCategory`/`firewallGroup`) pipes `adopt(true)` on by default. All three
+  read through `get()` (the whole model tree, keyed by uuid) rather than a per-item endpoint —
+  `firewall_alias` has none, and `firewall_category`/`firewall_group`'s own `getCategory`/`getGroup`
+  carry no `uuid` in their generated request schema, a measured SDK generation gap this family works
+  around uniformly rather than relies on. Each resource also exports a pure declaration renderer
+  (`aliasPropsFromLive`/`categoryPropsFromLive`/`groupPropsFromLive`): given one live item, it
+  returns exactly the props a declaration needs to plan noop against it — what a later import
+  script will use to generate `alchemy.run.ts` rows from a live read.
+
+  This first import pass covers the three SDK modules that export both a `get` and a `search<Item>`
+  operation and are stable configuration (not runtime state): `firewall_alias`, `firewall_category`,
+  `firewall_group`. Skipped, and why, in `docs/opnsense.md`: `firewall_filter` (rules) and
+  `routing_settings` (gateways) have `get` but no `search*`; `quagga_general` is a settings
+  singleton with no uuid; `quagga_bgp` mixes several item types with no `search*` for any of them;
+  `quagga_service` is pure runtime control (start/stop/restart/status).
+
+  Credentials are `OPNSENSE_URL`/`OPNSENSE_API_KEY`/`OPNSENSE_API_SECRET`, read at call time through
+  the SDK's own `CredentialsFromEnv` (HTTP Basic, the vendor's own scheme), never a prop — today the
+  only key that exists is ROOT-level, one more reason writes stay refused unconditionally. This
+  family's own test suite makes no live call — every test runs against `fake-opnsense.ts`, a
+  loopback fake; the SDK's `26.7.2` version pin was measured separately, live and read-only
+  (`docs/opnsense.md`).
+
+- [#238](https://github.com/taslabs-net/homeflare-kit/pull/238) [`d28861f`](https://github.com/taslabs-net/homeflare-kit/commit/d28861f00dce0d9dd17e5857e95332f8d009fa2c) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New `Podman.Container` resource in `@homeflare/alchemy/linux` — one Podman Quadlet `.container`
+  file, declared, plus the systemd unit Podman's own generator turns it into. Built for Tim's
+  2026-09-24 decision that CT100's containers (the two Grafanas, shared Postgres, shared Valkey,
+  later TeslaMate and NetBox) are owned by Alchemy through Quadlet rather than upstream Alchemy's
+  `Docker.Container`, which was measured and rejected: no host-network prop (every container here
+  runs `--network host`), `environment` puts `Redacted` secrets in Alchemy state, and systemd
+  already supervises the containers.
+
+  Reuses the `Systemd.Unit` family's lifecycle machinery directly (`renderUnit`, `isUnitRunning`,
+  `UNIT_WRITE`, `daemonReload`/`showUnit`/`startUnit`/`stopUnit`/`restartUnit` from `systemctl.ts`,
+  which also gains `SourcePath` to `SHOW_PROPERTIES` — additive for `Systemd.Unit`). `[Container]`
+  is typed and checked against `podman-systemd.unit(5)`, Podman 5.4 (CT100 runs 5.4.2): `Image`,
+  `ContainerName`, `Network` (supports `'host'`), `Volume`, `EnvironmentFile`, `Environment`
+  (never a secret — refused by name and value shape if it looks like one, `container-secrets.ts`),
+  `PublishPort`, `Exec`, `User`, `AutoUpdate`, `PodmanArgs`; `[Unit]`/`[Service]`/`[Install]` mirror
+  `Systemd.Unit`'s verbatim-lines approach with typed conveniences for `Description`/`Documentation`,
+  `Restart`/`RestartSec` and `WantedBy`/`RequiredBy`/`Alias` (the only three `[Install]` keys
+  Quadlet honours for a `.container` file, doc-confirmed).
+
+  The lifecycle differs from `Systemd.Unit` in the one place the generator forces it to: there is
+  no `enabled` prop and the resource never calls `systemctl enable`/`disable` — MEASURED on CT100
+  (`caddy.container`) that a generated unit is transient and doc-confirmed
+  (`podman-systemd.unit(5)`) that `systemctl enable` does not work on one; Quadlet applies
+  `[Install]` itself at every `daemon-reload`. A generator failure (a `.container` file Quadlet
+  refuses) surfaces as a typed `QuadletGeneratorError`, never "absent" — reasoned from
+  `systemd.generator(7)` (`daemon-reload` deletes and regenerates ALL generator output): an UPDATE
+  that fails verification restores the LAST-KNOWN-GOOD file and reloads again, so a container this
+  resource already promised running never loses its systemd unit to a bad update, rather than
+  leaving the new file for the next deploy to retry the way `Systemd.Unit` does.
+
+  `container-fixture.test.ts` renders the same directives as CT100's live `caddy.container`
+  (read read-only over `ssh ct100`), and documents why byte-for-byte is not the right bar for a
+  typed `[Container]` section (CT100's file interleaves prose comments between directives, which a
+  typed prop has nowhere to attach). Full guide: `docs/quadlet-container.md`.
+
+  Two rounds of review before opening/landing this PR — one foreground Sonnet adversarial pass
+  before opening it, aimed at restart-safety and secret leakage, and one inline coordinator
+  review after. All three findings were real and are fixed:
+
+  - **Restart-safety, interrupted UPDATE (high).** `reconcileContainer`'s reload gate (`wrote ||
+preStatus.needDaemonReload`) could not see that the SOURCE `.container` file had already been
+    written by an apply that crashed before its `daemon-reload` ran: on retry, the file already held
+    the new content (`wrote: false`) and the still-stale GENERATED unit hadn't changed either
+    (`needDaemonReload: false`), so no reload ever happened, `settle` restarted the container onto
+    its OLD definition, and state recorded the new digest as if it had taken effect — permanently and
+    silently. Fixed by gating the reload on `stale` (state's digest disagreeing with what was just
+    rendered) too, the same signal `changed` already used to gate the restart.
+  - **Restart-safety, interrupted CREATE (high, found on the coordinator's inline re-review).** The
+    same bug for a resource with NO prior state: a create whose write landed but crashed before
+    `daemon-reload` retried with `wrote: false` and no `stale` to disagree with either, so
+    `verifyGenerated` threw on the still-missing generated unit forever — loud, but permanently
+    stuck, since nothing about a plain retry ever changed any of those signals. Fixed with
+    `needsVerificationReload` (`container-generator.ts`), sharing its predicate with
+    `verifyGenerated` itself so the reload gate and the check it is gating can never disagree; an
+    ordinary adoption whose generation was already proven fine still skips the extra reload.
+  - **Secret leakage (high).** `containerProblems` only ran `secretLikeEnvironment` over
+    `container.environment`; `exec`, `podmanArgs` (rendered verbatim) and the `unit.lines`/
+    `service.lines` escape hatches (which can spell a raw systemd `Environment=` outside the typed
+    map entirely) were unchecked. Fixed with `secretLikeLines` (the same value-shape and embedded
+    `KEY=VALUE` heuristics, run over every other rendered line) and an outright refusal of `-e`/
+    `--env` in `podmanArgs` (`podmanArgsProblems`), both in container-secrets.ts and wired into
+    `containerProblems`.
+
+  Regression tests for all three live in container-generator.test.ts ("an interrupted apply that
+  crashed before daemon-reload", "an interrupted CREATE that crashed before daemon-reload") and
+  container-secrets.test.ts (one per affected field); each was confirmed to fail without its fix.
+
+- [#237](https://github.com/taslabs-net/homeflare-kit/pull/237) [`1c90063`](https://github.com/taslabs-net/homeflare-kit/commit/1c9006369dd623c522a0a1c0e747582800a4d981) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New `@homeflare/alchemy/unifi` subpath: `Unifi.Network` and `Unifi.FirewallZone`,
+  generated from Ubiquiti's own UniFi Network Integration API **10.4.57** (OpenAPI 3.1.0)
+  via `@distilled.cloud/unifi-network` (aliased onto `@homeflare/distilled-unifi-network@0.2.0`,
+  `docs/distilled-interim.md`).
+
+  ⛔ **READ-ONLY, by Tim's rule (2026-09-24).** Neither resource has a create, an update body
+  or a working delete — `reconcile` and `delete` both fail with a typed `UnifiWriteRefused`
+  naming the policy, and no handler ever calls an SDK write operation (proved by fakes in
+  `resource.test.ts`, `network.test.ts` and `firewall-zone.test.ts` that record every request
+  sent and assert none is anything but `GET`). `read` answers `Unowned` on every match — never
+  a silent adopt — with `adopt(true)` piped on by default via the `network`/`firewallZone`
+  convenience constructors, so a first deploy against an existing object binds without a stack
+  needing `--adopt`. `list` answers `[]`; adoption stays explicit.
+
+  `declareNetwork(live, siteId)` and `declareFirewallZone(live, siteId)` are the declaration
+  renderers this PR ships alongside the resources: pure functions from one live read
+  (`getNetworkDetails`/`getFirewallZone`'s own response shape) to the `Props` a declaration
+  needs so its plan is a no-op — what a later import script will call to generate
+  `alchemy.run.ts` rows from a live site.
+
+  `Unifi.Network`/`Unifi.FirewallZone` were chosen as the first import set because both have a
+  list+get pair over genuine, stable configuration (not runtime state like a connected client,
+  a device statistic or a hotspot voucher) and a simple, non-discriminated wire shape. `Site`
+  (list-only, no `getSite`) and `Unifi.FirewallPolicy` (several converter-flattened
+  discriminator variants, and an ordering endpoint that replaces the whole rule list) are
+  deliberately out of scope for this PR — see `docs/unifi.md`.
+
+  `Unifi.Network`'s `matches` now normalizes the three fields the vendor document never says are
+  ordered — `dhcpGuarding.trustedDhcpServerIpAddresses`, `ipv6Configuration.additionalHostIpSubnets`,
+  `ipv6Configuration.dnsServerIpAddressesOverride` — before comparing, the same `sortedSet`
+  (dedupe + sort) fix `Unifi.FirewallZone` already applied to `networkIds`: alchemy's `deepEqual`
+  sorts object keys but not array elements, so an unchanged network whose console answered the same
+  set in a different order would otherwise plan a spurious `update` that the read-only reconcile
+  then refuses.
+
+  Auth was measured live, read-only, on 2026-09-24: `X-API-KEY` against the estate's local console
+  returns HTTP 200 on `GET /v1/info` and `GET /v1/sites`; the same key against the `api.ui.com`
+  cloud connector returns 401 (the wrong door, not a broken header) — see `docs/unifi.md`'s
+  "Credentials" section. This PR's own code still never calls the vendor API live.
+
+### Patch Changes
+
+- [#243](https://github.com/taslabs-net/homeflare-kit/pull/243) [`823c1a8`](https://github.com/taslabs-net/homeflare-kit/commit/823c1a88fe1f8d34b90acb576231a18b7b04f0c3) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `proxmox/*` family's `nodes/storage` sub-area (decision 43's serial proxmox walk-down, PR 3
+  after `access` in PR 231/239) migrates `Proxmox.Storage` off `client.ts`'s hand-rolled `pve()`
+  (`resource.ts`'s `pveHandlers`) onto `@distilled.cloud/proxmox`'s typed `storage.getStorage`/
+  `createStorage`/`putStorage`/`deleteStorage` — the first resource of this sub-area; the rest of
+  `nodes`/`storage` (ZFS pools, Ceph, node network) follows in later PRs, split out because each is
+  independently substantial (see this PR's own description for why). `storage-wire.ts` (the read
+  side) and `storage-form.ts` (the write side) hold the pure wire-shape functions, the
+  api-token.ts/api-token-form.ts seam.