@homeflare/alchemy 0.37.0 → 0.37.2

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.

package/docs/changelog/archive-08.md

@@ -0,0 +1,178 @@
+# Alchemy changelog archive 8
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+Known trade-off (found by adversarial review, 2026-09-24): forcing the ruleset first only helps
+once the repository already exists. A repo and its ruleset created together for the FIRST time,
+with `checks` non-empty from day one, now fails clearly instead of racing — GitHub's own ruleset
+API 404s on a repository that does not exist yet, and the engine now guarantees that order rather
+than leaving it to chance. Both `declareRepoBaseline` and `declareRepoPolicy` document this and a
+new test proves the failure is explicit, not a silent fail-open; the fix is for an ALREADY-LIVE
+repo moving from no checks to some, which is K5's own scenario and the documented use of both
+functions.
+
+## 0.29.0
+
+### Minor Changes
+
+- [#222](https://github.com/taslabs-net/homeflare-kit/pull/222) [`1e6285f`](https://github.com/taslabs-net/homeflare-kit/commit/1e6285fb229dca7455afa5b52e1c79ca3286dc26) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Declare `@distilled.cloud/discord`, `@distilled.cloud/google-workspace` and `@distilled.cloud/grafana` (1.0.0-rc.12) as exact-pinned peers, ahead of the Discord, Google Workspace and Grafana provider families. Per the peer contract they are required, and they appear in the README install line and the smoke install.
+
+- [#208](https://github.com/taslabs-net/homeflare-kit/pull/208) [`2d28264`](https://github.com/taslabs-net/homeflare-kit/commit/2d28264e71d9f141ff0771f57dab49d6daa79904) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `GitHub.RepositoryRuleset`'s `rules.pullRequest.extraApprovalForUnattributedChanges` now accepts
+  `true`, not only `false`. Re-read live 2026-09-23, 8 rulesets carry
+  `require_extra_approval_for_unattributed_changes: true` (aop, cloudflareforms,
+  doesthishelp-workeropen, homeflare-anyauth, homeflare-desktop, loggarr, magictransit,
+  proxmox-tb4), so this resource could not declare their exact shape before: it would either omit
+  the field (leaving it unmanaged, refused once a caller also carries a `bypassActors`/rule
+  declaration for the same ruleset) or send `false`, which is real drift against a live `true` on
+  every plan.
+
+  The wire builder now sends whatever is declared instead of hardcoding `false`; `undefined` still
+  means "no opinion" (GitHub defaults an absent key to `true`). `repoBaselineRuleset()` in
+  repo-baseline-data.ts is unchanged — the house baseline still pins `false` for the repos that
+  fit it; a caller with a live `true` declares `RepositoryRuleset` directly with the live value,
+  the same pattern kit PR 205 established for `bypassActors` and rule presence.
+
+  Tested against aop's full live shape (`gh api repos/taslabs-net/aop/rulesets/14572279`,
+  re-read 2026-09-23): declaring the live value (including `true`) is now a genuine zero-write
+  adopt, and declaring `false` against a live `true` is still real drift, never a silent noop.
+
+- [#214](https://github.com/taslabs-net/homeflare-kit/pull/214) [`9af4441`](https://github.com/taslabs-net/homeflare-kit/commit/9af4441462743476da58ee06af877ec0b346aa1f) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `GitHub.RepositoryRuleset`'s "never-reported context" guard (`refuseUnreportedContexts` /
+  `hasContextReportedSuccess`) checked only the default branch's current tip. The house's rendered
+  CI (`packages/config/src/repo-shape/ci.ts`) triggers on `pull_request` only, deliberately (no
+  `push: [main]` — a squash-merged commit re-testing an already-green PR was ~41% of the mini's CI
+  load, measured 2026-09-15..22), so `ci`, `secret scan` and `CodeQL` never report on the tip
+  itself. The guard refused adding any of them everywhere, including homeflare-builds' pending
+  first ruleset.
+
+  `hasContextReportedSuccess` now falls back to up to `RECENT_MERGED_PR_LIMIT` (10) recent merged
+  pull requests' head SHAs — one bounded list call, never the repo's full PR history — checked only
+  if the tip itself has no reported success. A context that has never reported success ANYWHERE
+  (not the tip, not any recent merged head) is still refused: the guard's whole purpose is
+  unchanged, only where it is willing to look for evidence widened.
+
+  The core logic (`contextReportedSuccess`, `hasRefReportedSuccess`, `recentMergedHeadShas`) is now
+  exported as plain functions over a real `OctokitClient`, not only reachable through the
+  `GitHubCredentials`-gated `RulesetOctokit` — the same pure-function seam `desiredWireRuleset`
+  already uses — so `repository-ruleset-octokit.test.ts` measures it against a real `@octokit/rest`
+  instance with a fetch shim (no network), mirroring the H15 wire test: accepting a context that
+  reports only on a recent merged head, refusing one that reports nowhere, and refusing one whose
+  only success is older than the bound (the limit is real, not decorative).
+
+### Patch Changes
+
+- [#219](https://github.com/taslabs-net/homeflare-kit/pull/219) [`40c08eb`](https://github.com/taslabs-net/homeflare-kit/commit/40c08ebfc3ca04de7338deb95b217fbdce6c50d7) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `caddy/*` family (`Caddy.Config`, `caddyWithFile`, `localCaddyAdmin`) now calls
+  `@distilled.cloud/caddy`'s typed `admin` operations (`adaptConfig`, `loadConfig`,
+  `getConfig`) instead of a hand-rolled promise-based `CaddyAdmin.request()` interface.
+  Every operation's error channel is `catchTag`-able (`Caddy.CaddyOpError`); `isUnreachable`
+  (caddy-http-client.ts) is a type guard over the SDK's own `HttpClientError`, replacing the
+  old `CaddyUnreachableError` class, and gates the same "plan without Caddy" escape hatch
+  config.ts always had.
+
+  The measured local transport survives unchanged in shape: loopback TCP or a unix socket,
+  Host/Origin headers as the Caddy CLI sends them, retrying only a connection nothing
+  accepted (`ECONNREFUSED`/`ENOENT`) — now built as an Effect `HttpClient.HttpClient` layer
+  (`caddy-http-client.ts`) the SDK's protocol runs over, over `node:http` (not
+  `FetchHttpClient`: only `node:http` dials a unix socket on both Bun and Node). The
+  `LoadRefused` 200-trap (a refused `/load` that still answers 200 with the error appended
+  after the adapter's warnings) is first-class in the SDK's own `protocol.ts`, not
+  re-detected here.
+
+  Two real gaps this migration found and fixed at the source, never worked around in the
+  resource:
+
+  - `@distilled.cloud/caddy`'s `AdaptConfig`/`LoadConfig` JSON-encoded the Caddyfile TEXT and
+    overwrote the caller's `Content-Type` — fixed in the distilled clone's `protocol.ts` and
+    shipped as `@homeflare/distilled-caddy@0.2.1` (sibling changeset).
+  - The SDK's own default retry policy treats any transport-level `HttpClientError` as
+    retryable, including a `POST /load` that was already accepted before the connection
+    reset — `local-admin.ts` now disables it (`Caddy.Retry.Retry`) so caddy-http-client.ts's
+    own narrower ECONNREFUSED/ENOENT-only retry is the only one in play.
+
+  `providers.ts`'s `caddyProviders()` (and this family's own tests) also fix a wiring bug the
+  migration surfaced: `CaddyConfigProvider().pipe(Layer.provide(caddyAdminLayer(...)))`
+  seals `caddyAdminLayer`'s services away from the provider's `read`/`diff`/`reconcile`
+  handlers once they are built, so the engine's later call to any of them died with "Service
+  not found". `Layer.provideMerge` keeps those services live for every later call.
+
+  State did not move: props and attributes stay byte-identical (`configSha256`, `endpoint`,
+  `sourceFile`) — proven by the family's existing tests (updated only where the typed-error
+  message text itself changed, from the old ad hoc `method path -> status` strings to the
+  SDK's own tagged errors) plus fake-caddy.ts, a real HTTP server, so every test already
+  drives the real distilled wire protocol, not a re-implementation of it.
+
+- [#209](https://github.com/taslabs-net/homeflare-kit/pull/209) [`1eaf80f`](https://github.com/taslabs-net/homeflare-kit/commit/1eaf80f9ef2ad5e616f1a459ed6396819be15e6c) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `proxmox/*` family's `Proxmox.Acl` (the first resource in the PVE
+  `access/ACL` sub-area, per decision 43's serial proxmox walk-down) now calls
+  `@distilled.cloud/proxmox`'s typed `access.listAccessAcl`/`access.putAccessAcl`
+  operations instead of `client.ts`'s hand-rolled, generic `pve()` call. A new
+  `distilled-pve.ts` module (`runPve`/`runPveWith`) replaces `pve()`/`pveWith`
+  for a migrated family: the same OpenBao lease reuse (`lease-cache.ts`,
+  unchanged) and the same cluster-member failover safety rule (`members.ts`,
+  unchanged — a write may repeat only on a provably pre-send transport
+  failure, never on an HTTP answer or a post-connect timeout), now re-running
+  the whole typed operation per member instead of retrying one already-built
+  request. `client.ts`/`pveOperations` are untouched and still serve every
+  other PVE family; `Proxmox.Acl` is the first to move off them, chosen
+  because it was already the one family that didn't fit the generic
+  path+form shape (no create/delete verb — PVE has only GET/PUT on
+  `/access/acl`).
+
+  One dead branch is removed, not preserved: the old code's generic factory
+  POSTed on a "live read undefined" case that its own comments called
+  unreachable on a healthy cluster and documented as actively misleading (PVE
+  has no POST here, so the 501 it got back said nothing about the real
+  failure). `@distilled.cloud/proxmox` has no `createAccessAcl` at all — the
+  vendor schema has no POST for the generator to make one from — so there is
+  nothing to call that way any more. `reconcile` now always PUTs, the only
+  write PVE actually implements for this path, so a read that genuinely fails
+  surfaces its real cause instead of a confusing 501.
+
+  A trap found while writing the member-failover test: `@distilled.cloud/core`'s
+  default retry policy retries transport failures automatically (not just
+  5xx answers), which could have resent a write to the same member several
+  times before this file's own cluster failover ever saw a result to
+  classify — the hand-rolled client never auto-retried anything. `distilled-pve.ts`
+  disables the SDK's retry (`Retry.none`) on every attempt, keeping
+  member failover the only place a request repeats, matching the original
+  behavior exactly.
+
+  State did not move: `AclProps`/`AclAttributes` are unchanged, and the
+  existing cross-family `adopt-noop.test.ts` case for `Proxmox.Acl` (an
+  already-matching grant is read-only) passes unmodified against the new
+  code. New tests (`acl.test.ts`, `distilled-pve.test.ts`) drive a fake PVE
+  server through the real distilled protocol — real path assembly, real
+  form-urlencoded PUT bodies, real `{"data": ...}` envelope — covering
+  create, drift-correction, delete, identity-replace, the read-back guard,
+  and cluster-member failover for both a read and a write.
+
+  This is PR 1 of a serial, sub-area-by-sub-area migration
+  (access/ACL, then nodes/storage, then notifications, then PBS, …) of the
+  ~98-resource PVE family plus the PBS resources onto
+  `@distilled.cloud/proxmox`/`@distilled.cloud/proxmox-backup`. The other PVE
+  and PBS resources still call `client.ts`'s `pve()`, unchanged; `client.ts`
+  is deleted only once nothing imports it.
+
+- [#215](https://github.com/taslabs-net/homeflare-kit/pull/215) [`72c448d`](https://github.com/taslabs-net/homeflare-kit/commit/72c448dbaec8f2acb7b5109aa7387a4409185fe8) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Fix a review finding on the `litellm/*` distilled migration (`@homeflare/distilled-litellm`'s
+  `CredentialsFromEnv`, S20): a missing or misspelled `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY`
+  used to die as an unrecoverable Effect defect and crash the whole engine, instead of the typed
+  `ConfigError` `LitellmOpError` already declared — a regression this migration made newly
+  reachable from `LiteLLM.PassThroughEndpoint`'s `read`/`reconcile`/`delete` (the retired
+  hand-rolled `credentials.ts` failed typed). Fixed at the source, per house rule: the distilled
+  `litellm` package's own `credentials.ts` no longer ends in `Effect.orDie`, copied forward into
+  `@homeflare/distilled-litellm` unchanged. No prop, attribute or public API changed.
+
+  `netbox/*`'s `CredentialsFromEnv` has the identical shape and is not fixed by this changeset —
+  tracked separately (`docs/upstream-conformance.md` finding 9).
+
+- [#210](https://github.com/taslabs-net/homeflare-kit/pull/210) [`2002713`](https://github.com/taslabs-net/homeflare-kit/commit/20027131b716058de035bd1d8423054f3e9dbff0) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `litellm/*` family (`LiteLLM.PassThroughEndpoint`) now calls `@distilled.cloud/litellm`'s
+  typed `misc` operations instead of a hand-rolled `Effect HttpClient` client. The old
+  status-carrying `LitellmBadRequestError`/`LitellmUnauthorizedError`/`LitellmHttpError`/
+  `LitellmTransportError` are gone: every failure the SDK's four operations declare (`BadRequest`,
+  `NotFound` on update, `UnprocessableEntity`, plus the shared default HTTP errors) is the SDK's own
+  typed error, `catchTag`'d. `deletePassThroughEndpoint`'s re-list-on-ambiguous-delete trick is
+  unchanged, now keyed on the `BadRequest` tag instead of a status code. The per-base-URL write
+  semaphore LiteLLM's whole-list storage forces is unchanged, moved into the new `operations.ts`.
+  `client.ts` and the kit's own hand-generated `generated/pass-through.ts` are both deleted — the
+  SDK's `misc.PassThroughGenericEndpoint` is the same shape, generated from the same LiteLLM 1.100.0
+  OpenAPI document. The `codegen/litellm.ts` generator and `tests/litellm-manifest.test.ts` that
+  kept that file current are retired with it; the `litellm-openapi` manifest entry stays, recorded
+  as consumed by nothing, the same pattern the two UniFi entries already establish.