@homeflare/alchemy 0.37.1 → 0.37.3

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.

package/docs/changelog/archive-06.md

@@ -0,0 +1,180 @@
+# Alchemy changelog archive 6
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+**Clears this family's own cries-wolf false updates**, MEASURED live 2026-09-24: on the agent
+(`read`-role) lane, `bun run plan` showed all 5 storages (`cephfs-tb4`, `cephtb4`, `local`,
+`local-zfs`, `pbs`) as `update` with no warning, because this family reads with `provision`
+(`Datastore.Allocate` on `/storage` — `Datastore.Audit` is not enough) and the pre-migration
+`pveOperations.read` folded a REFUSED `provision` mint into "absent" exactly like every family
+before PR 231/239's fix — `unreadable-read.ts`'s own header already named this family as one of
+the two the fix was written for. Now wired the same way: a refused mint reports `noop` with a
+logged warning.
+
+**A missing storage is a 500, not a 404** — MEASURED against the live cluster (TB4, admin lane,
+read-only `GET /storage/hf-measure-nonexistent-probe`): `{"message":"storage '...' does not
+exist\n"}` at HTTP 500, the same shape user.ts/group.ts measured for a missing user/group. So
+`storage-wire.ts` carries the same dual-path read PR 239 established for those two families:
+`readStorageOrFail` (non-folding, used by `diff`, so a genuine transient failure propagates and
+fails the plan loudly) and `readStorage` (folding, used by `read`/`reconcile`'s create-detection).
+`read`'s own provider hook also branches on `output` from the start (PR 239's own follow-up
+finding, applied here proactively): `output === undefined` (Plan.ts's adoption probe, Apply.ts's
+delete recovery — nothing confirmed exists yet) keeps the fold; `output !== undefined`
+(`Drift.ts`'s already-confirmed row) uses the non-folding read instead, so `alchemy drift` never
+reports a transient failure as a silent `{action: 'missing'}` either.
+
+**Two measured gaps in `@distilled.cloud/proxmox`'s generated schema, handled rather than
+papered over:**
+
+- No `maxfiles` field at all (grepped across the whole package). Silently dropping a declared
+  value would be the exact class of bug this migration exists to close, so `StorageProps.maxfiles`
+  is now `never` — a compile error, the same treatment `StorageLocator`'s `password`/`keyring`/
+  `encryption-key` already get — rather than a silent no-op. None of this cluster's 5 live
+  storages set it; a consumer that genuinely needs it should file the gap upstream in the SDK's
+  generator, not work around it here.
+- Every hyphenated PVE field name becomes an underscore in distilled's generated TypeScript
+  (`prune-backups` -> `prune_backups`, `fs-name` -> `fs_name`, and so on for every plugin field
+  `StorageLocator`'s free-form bag can carry — `cephfs-tb4`'s own live locator uses `fs-name`).
+  No other migrated family has a hyphenated field, so this is new here. `storage-form.ts`'s
+  `underscored` translates a form built with PVE's own names into distilled's shape before the
+  actual SDK call, never before the form the generated vendor-constraint tables check
+  (`guardWrite`, keyed by PVE's own hyphenated names), which would otherwise silently stop
+  inspecting the very fields it exists to catch. MEASURED both ways (a `storage-read-failure.test.ts`
+  case run once with the translation and once without it): the wire itself carries PVE's own
+  hyphenated name either way — distilled's own "unknown key" passthrough happens to re-encode an
+  untranslated key correctly for a body-bearing POST/PUT (unlike the GET case that caused PR 239's
+  regression, where no body should exist at all). The translation is still the right call: it
+  routes every field through distilled's own declared, typed property rather than its passthrough
+  fallback, so whatever per-field wire logic a future plugin field carries beyond a plain rename
+  runs correctly rather than silently not running.
+
+`storage-read-failure.test.ts` pins all of this against real-shaped fixtures (live TB4 response
+bodies, measured 2026-09-24, nothing secret): the cries-wolf fix, `diff`/`verify()` rejecting on a
+transient failure instead of a false `update`, `alchemy drift` rejecting instead of a silent
+`missing`, and — added after an adversarial review found every test above only ever adopted an
+EXISTING storage, never exercising `reconcile`'s actual create path — a brand-new storage's create
+translating a hyphenated locator field for the real SDK call, and a vendor-constraint violation on
+a hyphenated locator field refused before any write. Each assertion confirmed to fail against the
+pre-fix code (or, for the translation claim, against the untranslated code) before landing.
+`verify/fake-engine.ts` gained a `drift` capability (driving the real `Alchemy.Drift.detect`) in
+PR 239, reused here; that PR's `read-failure-propagation.test.ts` already established the
+transient-failure/drift test pattern for User/Group.
+
+**Expected after this releases and the consumer bumps:** on the agent lane, `bun run plan`'s
+5 storage rows return to `noop`; ACLs and users/groups (PR 231/239) stay unaffected.
+
+## 0.31.2
+
+### Patch Changes
+
+- [#239](https://github.com/taslabs-net/homeflare-kit/pull/239) [`1e8985f`](https://github.com/taslabs-net/homeflare-kit/commit/1e8985fc8359304b2c6d03df0fba00781e5e32a0) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Fixes a live regression from kit 0.31.1 (PR 231, the `proxmox/access`
+  distilled migration): on the agent (`read`-role) lane, `bun run plan` showed
+  every `Proxmox.User`/`Proxmox.Group` row as `update` with no warning — a
+  silent false diff, not the loud "read was refused" case that migration was
+  meant to fix.
+
+  **Root cause, measured against the live cluster.** `user.ts`/`group.ts`
+  called `access.getAccessUser(props)`/`access.getAccessGroup(props)` with the
+  whole declared props object, not just the schema's own `{userid}`/
+  `{groupid}` label field. distilled's `buildRequest` treats any OTHER key on
+  that object (`target`, `comment`, every other prop this family carries) as
+  an "unknown key" and JSON-encodes it onto the request as a body — on what
+  must stay a bodyless GET. A permissive client tolerates this; Node/Bun's own
+  `fetch` refuses it outright
+  (`TypeError [ERR_INVALID_ARG_VALUE]: fetch() request with GET/HEAD method
+cannot have body`), which `runPveWith` retried across every cluster member
+  and exhausted identically (`PveClusterExhausted`). The old
+  `Effect.orElseSucceed(() => undefined)` then folded that failure into
+  "absent", forcing a false `update` on every account and every group — the
+  same cries-wolf bug PR 231 had just fixed for a refused credential, now
+  triggered by a genuine transport failure instead. Fixed by calling both
+  operations with only their declared label field.
+
+  **The fold itself was too broad, independent of the request-shape bug.**
+  `orElseSucceed` turning ANY read failure into "absent" is unsound at `diff`
+  time: only a genuine not-found may mean absent, every other failure must
+  fail the plan loudly rather than silently forcing a write. `acl.ts` (already
+  migrated pre-231) and `role.ts` never needed a fold at all — an ACL/role's
+  absence is always a successful list read that just doesn't contain the row,
+  so any thrown failure was already a bug; the fold there is now removed
+  outright. `api-token.ts`'s absence signal is likewise a measured
+  success-path check (`expire`/`privsep` both undefined on a 200), so its
+  fold is also removed outright.
+
+  `user.ts`/`group.ts` are different: a genuinely missing user or group is a
+  thrown 500 on this cluster (`"no such user"`/`"no such group"`, not a clean
+  404), MEASURED live — so `reconcile`'s create workflow still needs "absent"
+  derived from exactly that failure, or a brand-new declaration could never be
+  created. Each now has a dual-path read in its `*-wire.ts` sibling: a
+  non-folding `read...OrFail` (used by `diff`, so a genuine transient failure
+  propagates and fails the plan loudly) and a folding wrapper kept only for
+  `read`/`reconcile` (where folding costs at most a redundant, loudly-refused
+  create, never a silent wrong write).
+
+  **A second, deeper instance of the same bug class, found by adversarial
+  review of this fix rather than measured live.** The engine calls a
+  provider's `read` hook from four places — an adoption probe and
+  interrupted-create recovery in `Plan.ts`, delete recovery in `Apply.ts`, and
+  `Drift.ts` (`alchemy drift`/`sync`/`deploy --detect-drift`) — and only the
+  first three are "nothing confirmed exists yet" cases where `read`'s own
+  fold is safe. `Drift.ts` calls `read` on an ALREADY-CONFIRMED row (its own
+  persisted `output`), the same situation `diff` handles, and a folded
+  failure there is reported as `{action: 'missing'}` with no error anywhere —
+  worse than the original bug, since nothing even logs a warning. Fixed by
+  having `user.ts`/`group.ts`'s `read` hook branch on the input's own
+  `output` field (documented on `Provider.read`'s own type as "current state
+  -> synced state"): `output === undefined` still uses the folding read
+  (unchanged, for the three recovery/adoption cases), `output !== undefined`
+  now uses the same non-folding `read...OrFail` `diff` already calls.
+
+  `read-failure-propagation.test.ts` pins all three fixes end to end against
+  real-shaped PVE fixtures (live response bodies, nothing secret): a GET that
+  would carry a body now fails the assertion outright; a transient 500 on an
+  already-adopted `Proxmox.User`/`Proxmox.Group` now rejects `verify()`
+  instead of resolving with a false `update`; and (a new `drift` capability
+  on the shared `fake-engine.ts` test harness, driving the real
+  `Alchemy.Drift.detect`) the same transient failure now rejects `alchemy
+drift` instead of silently reporting the resource missing — each of the
+  three new/changed tests was confirmed to fail against the pre-fix code
+  before this change landed.
+
+  **Expected after this releases and the consumer bumps:** on the agent
+  lane, `bun run plan`'s users/groups return to `noop`, ACLs stay
+  `noop`-with-warning, and the five pre-existing storage rows (a separate,
+  not-yet-migrated family) are unaffected.
+
+- [#234](https://github.com/taslabs-net/homeflare-kit/pull/234) [`3357caa`](https://github.com/taslabs-net/homeflare-kit/commit/3357caa7c9a412365d3959bbb306628329eba4f8) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `@distilled.cloud/grafana` is not published upstream yet, so this package
+  now aliases it onto `@homeflare/distilled-grafana` (0.1.0 pre-release,
+  built the distilled way and shipped from this monorepo — see
+  `docs/distilled-interim.md`) as a plain `dependencies` entry instead of a
+  `1.0.0-rc.12` peer — nothing changes for a consumer's install (the peer
+  line is simply gone from the README and the smoke install, the same way
+  `/netbox` and `/litellm` already read). `Grafana.Datasource`'s props,
+  attributes and generated calls are unchanged — its existing tests pass
+  unmodified.
+
+  The alias also picks up `@distilled.cloud/grafana`'s newly-added folder,
+  dashboard and alerting-provisioning operations (see the
+  `@homeflare/distilled-grafana` changeset), which fixes the SDK-level gap
+  `docs/grafana.md` and `docs/upstream-conformance.md` recorded. No new house
+  `Resource` is added here — `Grafana.Folder`/`Dashboard`/`AlertRule`/etc. on
+  top of these operations is follow-up work, not part of this change.
+
+  ⚠️ **Deliberate deviation from `docs/distilled-interim.md`'s step 5.** That
+  doc has the interim package publish and get confirmed live
+  (`npm view @homeflare/distilled-grafana version`) in its own PR _before_ a
+  second PR adds the alias — exactly to dodge the propagation window
+  `scripts/publish.ts`'s own comments document twice (2026-09-15,
+  `kit@0.1.1`/`cloudflare@0.1.1`: "Your package is being processed and may
+  take a few minutes to become available"). This PR does both at once, on
+  purpose, so the next teams building `Grafana.Folder`/`Dashboard`/`AlertRule`
+  aren't blocked on a second release cycle. `scripts/publish.ts` has no
+  dependency-aware ordering, so **after this releases, confirm
+  `npm view @homeflare/distilled-grafana version` resolves before anyone
+  depends on the new `@homeflare/alchemy` version** — a few minutes' wait,
+  not a code change, and self-healing either way (the publish script is
+  idempotent and a stuck install just needs a retry).
+
+## 0.31.1
+
+### Patch Changes

package/docs/changelog/archive-07.md

@@ -0,0 +1,180 @@
+# Alchemy changelog archive 7
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+- [#231](https://github.com/taslabs-net/homeflare-kit/pull/231) [`11705f2`](https://github.com/taslabs-net/homeflare-kit/commit/11705f2b88d19335be5a115e06f7f6ca883b63b3) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `proxmox/*` family's `access` sub-area (decision 43's serial proxmox
+  walk-down, PR 2 after `Proxmox.Acl` in PR 209/220) now calls
+  `@distilled.cloud/proxmox`'s typed `access.*` operations instead of
+  `client.ts`'s hand-rolled, generic `pve()` call: `Proxmox.User`, `Proxmox.Group`,
+  `Proxmox.Role` and `Proxmox.ApiToken`. Each gets its own hand-written
+  reconcile (read/diff/reconcile/delete), the way `acl.ts` established, rather
+  than the shared `pveHandlers`/`pveOperations` factory — a `*-wire.ts` sibling
+  per family holds the pure wire-shape functions (create/update forms,
+  attributes, `matches`), keeping every file under the house's 250-line cap.
+  `client.ts`/`pveOperations` are untouched and still serve every other PVE
+  family; nothing in `nodes`, `storage`, `notifications` or PBS has moved yet.
+
+  `Proxmox.Role` reads via `GET /access/roles` (the list), not the item
+  `GET /access/roles/{roleid}` this family used before: distilled's generated
+  schema for the item response enumerates a FIXED set of ~47 known privilege
+  field names, and a privilege outside that set would silently vanish from
+  state on every read. The list's `privs` field is the same plain comma string
+  PVE's item read also disagreed with the index about pre-migration, with no
+  fixed enumeration to fall behind — `role-wire.ts`'s `find` does the item
+  read's old client-side job. Every other family in this PR still reads the
+  item it read before.
+
+  A `distilled-guard.ts` module (`asForm`/`guardWrite`) is the generalized
+  form of `acl.ts`'s own local `guardWrite`, needed because distilled's
+  generated request interfaces have no index signature and TypeScript refuses
+  `Record<string, string | undefined>` for them directly — `body: object`
+  plus one internal cast is the fix, applied once here rather than at every
+  call site.
+
+  **The cries-wolf fix** (measured 2026-09-24: `bun run plan` on the agent lane
+  showed "19 to update" — 14 ACLs and 5 storages — because a REFUSED read
+  folded into "absent" and `diff` forced `update` without comparing a field).
+  `credentials.ts`'s `mint` now fails a 403 from OpenBao (a denied
+  role — "this identity's AppRole has no grant") with a new typed
+  `PveCredentialDenied` (`credential-errors.ts`), split out from the newly
+  `mint.ts`-housed `mint`/`authorization` to keep `credentials.ts` under the
+  line cap. A new `unreadable-read.ts` module's `readOrUnreadable` `catchTag`s
+  exactly that one tag — never any other read failure — turning it into an
+  `UNREADABLE` sentinel `diff` can tell apart from a genuine absence. Upstream's
+  `Diff` type is exactly `NoopDiff | UpdateDiff | ReplaceDiff`
+  (`packages/alchemy/src/Diff.ts@v2.0.0-beta.79`) with no fourth action, and
+  `Plan.ts`'s resource pass fails the WHOLE plan if even one resource's `diff`
+  throws — so `diff` now reports `{action: 'noop'}` plus a logged warning for
+  an unreadable row, never a failed plan and never a forced write. Wired into
+  `acl.ts` (the already-migrated family) and every family in this PR;
+  `unreadable-read.test.ts` proves it end to end through Alchemy's real Plan
+  and Apply, with a fake OpenBao that denies `provision` mid-test. `storage.ts`
+  and the other five false updates stay open until `nodes`/`storage` migrates.
+
+  Distilled's `{userid}`/`{tokenid}` label substitution percent-encodes them
+  (`iac@pve` -> `iac%40pve`), where `client.ts`'s plain string concatenation
+  sent the `@` literally — a real PVE decodes both the same way, so this is
+  not a behaviour change a stack observes, but every fake cluster with an `@`
+  in a userid (`user.test.ts`, `api-token-adopt.test.ts`,
+  `provision-declare.test.ts`) now decodes the path before matching it.
+
+  State did not move: every Props/Attributes interface is unchanged, and the
+  existing cross-family `adopt-noop.test.ts` cases (now extended with `Group`
+  and `User` rows for the new hand-written reconciles) and
+  `api-token-adopt.test.ts` pass with the same assertions the pre-migration
+  code made. New tests (`group.test.ts`, `user.test.ts`, `role.test.ts`)
+  drive a fake PVE server through the real distilled protocol, covering
+  create, drift-correction, delete, retain-by-default and the read-back guard.
+
+  `codegen/constraints.ts` regenerated: `Proxmox.ApiToken` no longer names its
+  (always-unreachable) create endpoint anywhere in source, so the generated
+  tables and the hand-written ownership ledger
+  (`scripts/proxmox-ownership-pve.ts`) both drop that one claim — 74 tabled
+  endpoints, not 75.
+
+## 0.31.0
+
+### Minor Changes
+
+- [#228](https://github.com/taslabs-net/homeflare-kit/pull/228) [`25610e8`](https://github.com/taslabs-net/homeflare-kit/commit/25610e890ac360456c318dd8dbefd0d54ccf0d3e) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New `@homeflare/alchemy/discord` subpath, built directly on `@distilled.cloud/discord`
+  (1.0.0-rc.12) — no hand-rolled client ever existed for this vendor to retire.
+  `Discord.ApplicationCommand` (global) and `Discord.GuildApplicationCommand` (guild-scoped)
+  declare a slash/user/message command; `reconcile` is one upsert call, matching Discord's own
+  create-endpoint semantics (a command with the same name overwrites the old one), the same shape
+  `Cloudflare.Snippets.Snippet`'s `putSnippet` uses upstream. `read` follows that same upstream
+  reference for a marker-less API exactly: a cold match is `Unowned`, never a silent adopt, and
+  both convenience constructors (`applicationCommand`, `guildApplicationCommand`) pipe `adopt(true)`
+  by default. Rate limits are handled entirely by the SDK's own bounded default retry policy
+  (`Schedule.recurs(8)`, honoring a `429`'s `Retry-After`); this family adds no retry logic of its
+  own. Credentials are `DISCORD_BOT_TOKEN`/`DISCORD_TOKEN`, read at call time through the SDK's own
+  `CredentialsFromEnv`, never a prop.
+
+  Walked read-only against the live target, `hf-discord-halibut.service` on CT100: the bot
+  self-registers nine guild-scoped commands at every startup (Sapphire's `BulkOverwrite`), so
+  `docs/discord.md` documents the ownership conflict and the handover sequence rather than
+  declaring `Discord.GuildApplicationCommand` against Halibut's own guilds — that would fight the
+  bot's own registration, not replace it. Guild roles, channels and webhooks are not built: Halibut
+  uses none of them (measured on CT100), and the engine in `resource.ts` generalizes cleanly to a
+  future spec file if a stack ever needs one.
+
+  SDK gaps recorded in `docs/discord.md`: every generated operation's typed error union is narrower
+  than the protocol's own status map (`Forbidden`/`NotFound`/`BadRequest`/`Conflict` are built at
+  runtime but not in the exported type — measured via `tsc`, not assumed); `options` is passed
+  through opaquely rather than re-modeled from the ~40-type generated union; there is no vendor
+  constraint table (unlike NetBox/Paperless); global command propagation (up to an hour, Discord's
+  own docs) is not polled.
+
+## 0.30.0
+
+### Minor Changes
+
+- [#229](https://github.com/taslabs-net/homeflare-kit/pull/229) [`b4d714e`](https://github.com/taslabs-net/homeflare-kit/commit/b4d714eff527c8c875afca2cb529d5f312bd1efa) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Added `caddy/formatCaddyfile(text)`: pipes a Caddyfile through the LOCAL
+  `caddy fmt -` binary (stdin in, formatted text out) — the same formatter the
+  `caddy fmt` CLI command runs. There is no admin API endpoint for this
+  (`cmd/commandfuncs.go` is CLI-only), so it shells out with
+  `ChildProcessSpawner` (S19) rather than going through `@distilled.cloud/caddy`,
+  and it never reimplements the formatter in TypeScript: a missing or failing
+  binary fails the Effect with a typed `CaddyFmtNotFound` / `CaddyFmtFailed`,
+  it never silently returns the input unformatted.
+
+  Also: `Caddy.Config`'s plan (`diffConfig`) and deploy (`CaddyConfigProvider`'s
+  `reconcile`) now surface the adapter's "Caddyfile input is not formatted"
+  warning as its own clear line naming the fix, separately from any other
+  adapter warnings — it used to be silent at plan time, and just another line
+  in the pile at deploy time. Nothing here changes what gets loaded onto Caddy:
+  formatting should never change the adapted JSON digest.ts compares (reasoned
+  from the Caddyfile grammar; not measured against a real Caddy in this
+  package — see docs/caddy-fmt.md).
+
+- [#226](https://github.com/taslabs-net/homeflare-kit/pull/226) [`bfc71a3`](https://github.com/taslabs-net/homeflare-kit/commit/bfc71a31e811aab0ccdbbc5ce82ee6803c7ad277) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add the Google Workspace provider family (`@homeflare/alchemy/google-workspace`): `Group`,
+  `GroupMember`, `DomainAlias` and `OrgUnit` over the Admin SDK Directory API, built on
+  `@distilled.cloud/google-workspace@1.0.0-rc.12`'s typed `admin_directory_v1` operations
+  (S23 — no hand-rolled client). Adopt-first by get-by-key, `retain` on removal for everything
+  but membership, and no `User` resource (Google's own `User` schema carries a `password` field).
+  Credential setup — domain-wide delegation, the least OAuth scopes each resource needs, and
+  where the service-account key lives in OpenBao — is in
+  `packages/alchemy/docs/google-workspace.md`.
+
+- [#225](https://github.com/taslabs-net/homeflare-kit/pull/225) [`a68c021`](https://github.com/taslabs-net/homeflare-kit/commit/a68c0212f951d3492e5fde981f7f334f777d21fe) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New family: `@homeflare/alchemy/grafana`. `Grafana.Datasource` declares one data source, keyed by
+  `uid`, calling `@distilled.cloud/grafana`'s typed `addDataSource`/`getDataSourceByUID`/
+  `updateDataSourceByUID`/`deleteDataSourceByUID` operations, `catchTag('NotFound', ...)` in place of
+  a status check. Credentials are a `GrafanaTarget` (instance origin + a token env var NAME, never a
+  literal value) resolved lazily per call, parameterized per instance rather than fixed like
+  Forgejo's — this estate runs more than one Grafana. `grafanaProviders(target)` composes the
+  provider with its credentials, mirroring `litellmProviders`.
+
+  Only `Datasource` ships: `@distilled.cloud/grafana@1.0.0-rc.12` has no create/update/delete
+  operations for folders, dashboards, alert rules or contact points, measured against its published
+  types — recorded in `docs/grafana.md` and `docs/upstream-conformance.md` rather than worked
+  around with a hand-rolled client for the missing pieces.
+
+  Built and measured, read-only, against the live target `teslamate-grafana.service` on CT100
+  (Grafana 13.1.3, `teslamate/grafana:4.2.0`): one file-provisioned datasource, image-baked
+  dashboards, no folders, alert rules or contact points. No stack yet imports this subpath.
+
+## 0.29.1
+
+### Patch Changes
+
+- [#223](https://github.com/taslabs-net/homeflare-kit/pull/223) [`dc37600`](https://github.com/taslabs-net/homeflare-kit/commit/dc37600d0bb1c72ed2711351e498949af81271c6) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `declareRepoBaseline` and `declareRepoPolicy` declared `GitHub.Repository` and their
+  `RepositoryRuleset` as two independent resources with no dependency edge between them (K5,
+  kit PR 216). `repoBaselineSettings`/`repoPolicy` already gate `allowAutoMerge` on
+  `checks.length > 0`, but with nothing ordering the two resources, a deploy that moves a repo
+  from `checks: []` to a non-empty list could apply the repository (turning auto-merge on) before
+  the ruleset (adding the required check) — or the ruleset apply could fail outright, leaving
+  auto-merge on with nothing required. `gh pr merge --auto` merges a CLEAN pull request the instant
+  nothing is outstanding, so that window is exactly the fail-open state K5 exists to prevent.
+
+  Both callers now thread the ruleset's `rulesetId` through `allowAutoMerge`'s own value
+  (`repo-auto-merge-gate.ts`'s `gateAutoMergeOnRuleset`, via `alchemy/Output`'s `map`) whenever a
+  declaration turns auto-merge on, instead of writing it as a literal. Alchemy orders resources by
+  Output references in props (`Plan.ts`'s `Output.upstreamAny`, `Apply.ts`'s `waitForDeps` —
+  see the kit's own `alchemy-output-refs-order-resources` memory), so this makes the engine apply
+  the ruleset first, with no change to the value actually sent (`allowAutoMerge` is still exactly
+  `true`). A ruleset apply failure now leaves the repository's `reconcile` — and `allowAutoMerge`
+  — untouched, proved by a new engine-level ordering test and failure test for each caller.
+
+  The reverse transition (checks/approvals removed) needs no matching edge: neither caller ever
+  declares a rule's removal explicitly, only omits it, and `repository-ruleset-guards.ts`'s
+  `requiredChecksOmissionRefusal`/`undeclaredLiveRuleRefusal` already refuse — regardless of apply
+  order — to drop a still-live required rule by omission.