@homeflare/alchemy 0.37.1 → 0.37.3

package/docs/changelog/archive-02.md

@@ -0,0 +1,180 @@
+# Alchemy changelog archive 2
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+The read (the directory index, `nodes.listNodeCephFs`) and the create (`nodes.updateNodeCephFs` —
+distilled's generator MISNAMES the create a "update"; checked directly against its `T.Http`
+annotation, it is genuinely `POST /nodes/{node}/ceph/fs/{name}`, PVE's only write on that path,
+harmless once named for what it is) both move to a new `ceph-fs-distilled.ts`. The create's forked-
+worker wait is its OWN function there, polling the RAW `nodes.getNodeTaskStatus` operation directly
+rather than `@distilled.cloud/proxmox`'s own `Task.awaitTask` — checked against `task.ts` before
+deciding: `Task.awaitTask` propagates a poll failure as a genuine typed error instead of treating
+it as "not settled yet", which would turn a missing `Sys.Audit` grant or a node mid-restart into a
+failed create instead of a patient one, the same failure mode `Proxmox.NetworkApply`'s own header
+already names. The raw operation carries none of that behaviour — it is a plain typed GET — so
+wrapping it in the SAME tolerant retry loop `ceph-fs-wire.ts`'s own (unmigrated, delete-only) poll
+already uses reproduces the exact policy: same cadence (`POLL_SECONDS`/`POLL_ATTEMPTS`, one
+constant, imported not retyped), same "an unreadable status is not a failure" tolerance.
+
+**Live measurement note.** This session's own OpenBao policy has no Proxmox grant; the live probes
+above ran through `homeflare-proxmox`'s `scripts/with-mini-bao.ts` (the `macmini-agent` AppRole's
+`read` role for TB4), from a detached worktree, read-only, per the coordinator's direction — not
+through this repo's own credentials, and nothing here reads one.
+
+**One distilled generator quirk recorded to the shared `distilled-sdk-path.md` memory**, since it
+is an upstream-distilled fact rather than a kit one: `DeleteNodeCephFsRequest` types
+`remove_pools`/`remove_storages` as `T.Body` on a DELETE, which PVE's own server never reads a
+body on — the same class of finding as `Proxmox.NetworkApply`'s two, worth the same upstream
+attention if `@distilled.cloud/proxmox` is ever patched again.
+
+**New tests**, every one proven against a deliberately weakened check before landing:
+`ceph-pool-write.test.ts` (a genuinely new pool creates once the index is confirmed empty; the
+PG-merge guard refuses a create when the index lists the name but the status read still fails —
+confirmed this fails without the guard by temporarily removing the `confirmAbsent` call and
+re-running; `RemovalPolicy.destroy()` then undeclaring sends exactly one DELETE) and
+`ceph-fs-write.test.ts` (a genuinely new filesystem POSTs, polls a forked task that answers
+`running` before `stopped`/`OK` — proving the poll loop actually loops — and reads the index back;
+a task that finishes with a real Ceph error dies with the task-log pointer rather than a false
+create).
+
+**`ceph-fs-delete.test.ts` (new, added after the adversarial review's finding).** The review's one
+substantive finding: `Proxmox.CephFs`'s `delete` handler is the single place in this PR that
+composes a distilled call (`readFs`, before and after) with the unmigrated hand-client one
+(`destroyFs`) inside one handler — the exact boundary this PR's whole design rests on — and that
+composition had zero test coverage anywhere in the repo, before or after the rest of this PR
+(each half was proven separately, never together, and the destroy is destructive and hard to
+reverse). Added two tests: a genuine `RemovalPolicy.destroy()` then undeclare, confirmed to fail
+(the read-back reports the filesystem still present) by temporarily removing the `destroyFs` call
+and re-running; and a filesystem removed by hand between the adopt and the undeclare, proving
+`delete` is a silent no-op rather than a false DELETE against an object already gone.
+
+**Expected after this releases and the consumer bumps:** no live plan change for either family —
+C1's read-role lease could always read the live Ceph objects cleanly, so this is a transport
+migration on tested paths, not a behaviour change.
+
+- [#261](https://github.com/taslabs-net/homeflare-kit/pull/261) [`ee3f452`](https://github.com/taslabs-net/homeflare-kit/commit/ee3f4526d8fa2991837a8d7931b2fb37df921eda) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `@distilled.cloud/litellm` (interim, via `packages/distilled-litellm`): reverts `credentials.ts`
+  to `Effect.orDie` on a missing or misspelled `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY`.
+
+  Q6 of the 2026-09-24 walk-down (decision 49 "upstream wins"): distilled's own convention for a
+  missing credential is `Effect.orDie`, not a typed `ConfigError` — 73 of 80 `packages/*/src/credentials.ts`
+  end this way at `homeflare/base`, 78 of 80 at `origin/main`. A worktree commit (`4ad19154`) had
+  made LiteLLM's `Credentials` the one exception, declaring `Effect.Effect<Config, ConfigError>` and
+  dropping the `orDie`. Distilled is not silent on this convention, so the divergence was the house
+  going stricter than distilled's own practice on a point it already has an answer for — the thing
+  decision 49 says to stop doing. Reverted in the litellm worktree (`homeflare/litellm`
+  `cbd6bbb890066e57fb0224b96c27fca91d89e0a6`, a `git revert` of `4ad19154`, confirmed byte-identical
+  to `4ad19154`'s parent), gated on `typecheck:ci`/`specs:check`/`format:check`, then byte-copied
+  into `packages/distilled-litellm/src/credentials.ts` (confirmed with `diff -rq` against the
+  worktree's `src/`).
+
+  **The typed-error idea is not discarded**, just not spread further: it is written up as a HELD
+  upstream proposal in [`litellm.md`](../litellm.md#credentials) — distilled's
+  own `LitellmOpError` already declares `ConfigError` and threads a real credentials failure into an
+  operation's error channel, so the plumbing for a typed refusal genuinely exists; nobody has raised
+  it to `alchemy-run/distilled`, and this PR doesn't either.
+
+  **`packages/alchemy/src/litellm/operations.ts`'s `mutate` helper needed no functional change.**
+  Its `| ConfigError` widening was always redundant with the operation-level `LitellmOpError` union
+  (which declares `ConfigError` unconditionally, regardless of `Credentials`'s own type) — confirmed
+  by re-reading `protocol.ts` — so it still typechecks and the widening is still a real no-op for
+  callers. Its comment is corrected: it no longer claims resolving `Credentials` can itself fail
+  typed, since post-revert it cannot.
+
+  **Verified**: `bun run build:interim-packages`, `tsc --noEmit` for the whole `@homeflare/alchemy`
+  package, `bun test src/litellm` (28/28), and `packages/distilled-litellm`'s own `types` and
+  `smoke` — all clean.
+
+  No live plan change: this only affects what happens when the two env vars are missing or
+  misspelled, which was never a state this family's tests exercised as "succeeds."
+
+- [#266](https://github.com/taslabs-net/homeflare-kit/pull/266) [`c6f3f9a`](https://github.com/taslabs-net/homeflare-kit/commit/c6f3f9a33fa2ed72c5d73586fa74090582330cd0) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Make `Cloudflare.R2BucketLock` deletion succeed when its bucket is already gone.
+  Read, reconcile and delete now propagate distilled's typed SDK failures instead of
+  turning them into `Effect.orDie` defects. Error identities such as `InvalidRoute`,
+  `TooManyRequests` and reconcile's `NoSuchBucket` remain available to callers.
+
+  This follows the lifecycle pattern in upstream `Cloudflare/R2/BucketSippy.ts` at
+  `alchemy@2.0.0-beta.79` (`473c3959`): catch the missing bucket only where it means
+  absence or successful deletion, and propagate other SDK errors without a blanket remap.
+  Walked against Cloudflare API v4 via `@distilled.cloud/cloudflare@1.0.0-rc.12`,
+  the version pinned by Alchemy beta.79. No props, attributes or SDK pins change.
+
+  Fake-transport tests cover missing-bucket reads and deletes, missing-bucket reconcile
+  failures, other 404 errors, and rate-limited reads/deletes with retries disabled.
+
+## 0.36.0
+
+### Minor Changes
+
+- [#255](https://github.com/taslabs-net/homeflare-kit/pull/255) [`74310b5`](https://github.com/taslabs-net/homeflare-kit/commit/74310b5fcbd6ab1ddbebe607c2693c34d664bf30) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `grafana/*` ships `Grafana.NotificationPolicy` — third and last of the stacked PRs bringing Grafana
+  alerting provisioning under Alchemy (decision 40), completing the family alongside
+  `Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate` (kit PR 250) and
+  `Grafana.AlertRuleGroup` (kit PR 254). 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-notification-policy.md`.
+
+  **A singleton — adopt and update only.** Measured: `RouteGetPolicyTreeError` has no `NotFound`
+  case, so `fetchLive` never returns `undefined` — this resource has no create or delete in the sense
+  every sibling resource has, only ever `PUT`-replaces the one tree an instance has. `spec.create`
+  exists only because `GrafanaSpec`'s shared type requires it; it is never actually reached.
+
+  **`routeResetPolicyTree` needs TWO explicit gates, not one.** `defaultRemovalPolicy: 'retain'`
+  means Alchemy's engine never calls `destroy` at all unless a stack opts in with
+  `.pipe(RemovalPolicy.destroy())` — the convention every multi-object-cascade resource in this
+  family already uses. On top of that, `destroy` itself refuses to reset unless the resource's own
+  `allowReset: true` prop is set — even a stack that opted in at the Alchemy level still needs this.
+  Without it, `destroy` logs a warning and retains the tree. Two gates because `routeResetPolicyTree`
+  is uniquely destructive here: it wipes every route, receiver reference and matcher back to
+  Grafana's bare default for the WHOLE instance, not one object. A test proves `destroy` sends no
+  `DELETE` without `allowReset`, and that a foreign-provenance tree still refuses destroy even WITH
+  it.
+
+  **The tree is opaque `Record<string, unknown>`**, same reasoning as `Grafana.MuteTiming`'s
+  `timeIntervals` — Grafana's matcher-expression types (`Matchers`/`ObjectMatchers`/`MatchRegexps`)
+  are complex nested unions this family does not hand-model, and the SDK's own unmodeled-key
+  passthrough (measured for `Grafana.MuteTiming`, mute-timing.ts's file header) means an opaque
+  pass-through round-trips correctly regardless.
+
+  **Route order is significant**, same as `Grafana.AlertRuleGroup`'s rules — Alertmanager routes an
+  alert to the first matching route in array order, proven by a test that reverses the same two
+  routes and asserts a mismatch. **Foreign-provenance refusal** reuses `alerting-provenance.ts`
+  unchanged, including the missing-means-foreign fix an adversarial review of kit PR 250 established.
+  **Grafana-injected defaults** are tolerated the `subset-match.ts` way (the same mechanism
+  `Grafana.Dashboard`/`Grafana.ContactPoint` already rely on), not hand-normalized — not measured
+  against a live instance, since none exists in this house to read.
+
+  **Dropped-route warning**, mirroring kit PR 254's `Grafana.AlertRuleGroup` fix for the identical
+  risk: a whole-tree `PUT` replaces every route, so a nested route added out-of-band is removed with
+  no error. `notification-policy-drop-warning.ts`'s `warnOnDroppedRoutes` logs every dropped route by
+  receiver and dotted-index path, from both a local reimplementation of `diff` and from `update`
+  itself — never a refusal, since the tree stays the unit by design.
+
+  ⛔ **Fixed after an adversarial review of this PR: the identity the warning used collided across
+  the WHOLE TREE, not just among siblings.** The first version keyed every node by its own-fields
+  JSON alone in a `Set`; a duplicate route added anywhere in the tree matched an unrelated declared
+  node with the same fields and the drop went unwarned, even though the `PUT` still removes it —
+  worse than the "structural, siblings-only" limitation the original comment claimed. `FlatRoute.key`
+  (`notification-policy-model.ts`) is now the chain of ancestor own-fields from the root down to a
+  node (`\0`-joined) — order-insensitive among siblings, but distinct across different parents — and
+  `warnOnDroppedRoutes` counts each key as a MULTISET (live count vs. declared count) rather than
+  checking `Set` membership, so N identical live occurrences under one parent are dropped only past
+  however many the declaration itself repeats. Four tests pin this: a duplicate added live warns; a
+  plain sibling reorder doesn't; an identical route under a different, undeclared parent still warns;
+  and two declared duplicates against two live duplicates warns nothing.
+
+  Tests (`notification-policy.test.ts` + `-model.test.ts` + `-refusals.test.ts` +
+  `-drop-warning.test.ts`, split four ways to stay under the house's 250-line file cap, sharing
+  fixtures from `notification-policy-fixtures.ts`) use the family's existing `fake-grafana.ts`
+  harness and prove: a GET never carries a body; reconcile never sends a create-shaped write; a
+  foreign-provenance tree (explicit `"file"` or MISSING) refuses update while an explicit `""` is
+  writable; `destroy` never resets without `allowReset: true`; reordering routes shows `update`; and
+  the dropped-route warning's multiset identity behaves as described above.
+
+## 0.35.0
+
+### Minor Changes
+
+- [#254](https://github.com/taslabs-net/homeflare-kit/pull/254) [`e6788af`](https://github.com/taslabs-net/homeflare-kit/commit/e6788af70a34495af64d9bc0a4fce112e59bf561) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `grafana/*` ships `Grafana.AlertRuleGroup` — second of three stacked PRs bringing Grafana alerting
+  provisioning under Alchemy (decision 40), on the same `@distilled.cloud/grafana@0.2.0` operations
+  as `Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate`. `Grafana.NotificationPolicy`
+  follows in one more PR. 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-rules.md`.

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.