@homeflare/alchemy 0.37.1 → 0.37.3

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.

package/docs/changelog/archive-09.md

@@ -0,0 +1,181 @@
+# Alchemy changelog archive 9
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+Not published upstream yet, so aliased onto `@homeflare/distilled-litellm@0.2.0` as a plain
+`dependencies` entry, not a peer — see `docs/distilled-interim.md`. Credentials still resolve
+from `LITELLM_PROXY_URL` / `LITELLM_PROXY_API_KEY` at call time, now through the package's own
+`CredentialsFromEnv` layer. Props and attributes are unchanged — an adopted pass-through endpoint
+still plans noop.
+
+- [#212](https://github.com/taslabs-net/homeflare-kit/pull/212) [`e419a44`](https://github.com/taslabs-net/homeflare-kit/commit/e419a44f45e3332eb9ae7c3b196d203309668f26) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `paperless/*` family (`Tag`, `DocumentType`, `StoragePath`, `CustomField`) now calls
+  `@distilled.cloud/paperless-ngx`'s typed operations instead of a hand-rolled `Effect HttpClient`
+  client. `client.ts`, `errors.ts` and `credentials.ts` are gone; every status check
+  (`statusToError`, the status-carrying `PaperlessError` union) is replaced by
+  `Effect.catchTag('NotFound', …)` at each resource file's own `getById` call, the same rule
+  `forgejo/*` and `netbox/*` follow — a LIST call is never folded to absent at all, since an empty
+  page is a normal 200 (measured live, kit PR 194). The shared `matching.ts`/`matching-locate.ts`
+  engine (locate-by-name before there is state, by the stored `output.id` after — PR 163) is
+  unchanged in shape, generalized only over the SDK's typed `Live` row and each family's own
+  distilled error union instead of an untyped `PaperlessRow`.
+
+  `@distilled.cloud/paperless-ngx` is not published upstream yet, so this package was already
+  aliased onto `@homeflare/distilled-paperless-ngx@0.3.0` (kit PR 188/194/206 — built the distilled
+  way and shipped from this monorepo, see `docs/distilled-interim.md`); this PR is the first thing
+  that actually imports it. `packages/alchemy`'s own `build:interim-deps` now builds it too, and
+  picks up a pre-existing bug in the same line while doing so: `bun --cwd <dir> run <script>`
+  (space-separated) silently no-ops instead of building — `bun --cwd=<dir> run <script>` is the form
+  that actually works. Fixed for all three interim deps this script already named (netbox, proxmox,
+  paperless-ngx); the root-level `scripts/build-interim-packages.ts` was never affected, since it
+  spawns `bun run build` with an explicit `cwd` option rather than a shell string.
+
+  Credentials still resolve from `PAPERLESS_URL` / `PAPERLESS_TOKEN` at call time, now through the
+  SDK's own `CredentialsFromEnv`, baked directly into each of the four `xxxProvider()`s the same way
+  `netboxHandlers`/`forgejoHandlers` do — `providers.ts`'s `paperlessProviders()` no longer takes a
+  credentials-layer override (nothing in this estate called it with one: measured 2026-09-24, no
+  tray repo under `homeflare-landscape` declares a Paperless resource at all). Props and attributes
+  are unchanged — an adopted tag, document type, storage path or custom field still plans noop.
+
+- [#220](https://github.com/taslabs-net/homeflare-kit/pull/220) [`4da7ecc`](https://github.com/taslabs-net/homeflare-kit/commit/4da7ecc7d5dd59e0c9aab3a4a13dee148f9a14a9) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `client.ts`'s `executeOnCluster` and `distilled-pve.ts`'s `runPveWith`
+  (`members.ts`, shared by both) now bound a single cluster-member attempt with
+  a new `MEMBER_TIMEOUT` (20 seconds). Previously nothing did: a PVE member
+  that accepted the TCP connection but never answered hung the whole call
+  forever, because the cluster-failover loop never got a failure to classify
+  and so never reached a healthy member — this affected every PVE resource,
+  migrated or not, since both codepaths funnel through `executeOnCluster`. A
+  bounded timeout now fails a read over to the next member (no side effect to
+  duplicate) and fails a write outright without resending it, matching the
+  existing rule that a post-connect failure is never pre-send. Found on review
+  of `Proxmox.Acl`'s migration (PR 209); fixed once, shared by every PVE
+  family.
+
+- [#216](https://github.com/taslabs-net/homeflare-kit/pull/216) [`eaa12e5`](https://github.com/taslabs-net/homeflare-kit/commit/eaa12e532fc420a74efd8df717e1fe080f1e3840) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `repoBaselineSettings` (repo-baseline-data.ts) no longer turns `allowAutoMerge` on
+  unconditionally — it now follows `checks.length > 0`, the same as the sibling `repoPolicy` path
+  already refuses to do (`repo-policy-guards.ts`'s `assertAutoMergeWaits`). With zero required
+  status checks, `gh pr merge --auto` (and the ruleset's own auto-merge) has nothing to wait for:
+  GitHub merges a CLEAN pull request on the spot, with no review and no green run required. A repo
+  declared through `declareRepoBaseline` with an empty `checks` list (homeflare-anyauth today, for
+  example — no workflows, so no checks to name) would otherwise get auto-merge turned on with
+  nothing gating it.
+
+  This baseline has no `autoMerge` opt-out prop the way `repoPolicy` does, so the fix is
+  unconditional rather than a thrown refusal: a repo with checks keeps `allowAutoMerge: true`
+  exactly as before; one without simply never gets it turned on by this baseline.
+
+- [#217](https://github.com/taslabs-net/homeflare-kit/pull/217) [`ad397ea`](https://github.com/taslabs-net/homeflare-kit/commit/ad397eadbff8c20fef5c9634980b99ce65203758) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `GitHub.RepositoryRuleset`'s `Resource<>` declaration put `GitHubCredentials` in its 5th
+  (`Providers`) type parameter, which puts that credential requirement on every `yield*
+RepositoryRuleset(...)` call site — including inside `declareRepoPolicy`/`declareRepoBaseline`.
+  A stack body cannot supply `GitHubCredentials` itself (`Alchemy.Stack`'s own `ProviderServices`
+  type is a closed union `GitHubCredentials` does not structurally match), so any consumer whose
+  stack body calls `declareRepoPolicy`/`declareRepoBaseline` — or declares `RepositoryRuleset`
+  directly — failed `tsc` (measured 2026-09-24: homeflare-builds bumping to 0.27.4, TS2345).
+
+  Verified against upstream `alchemy@2.0.0-beta.79`'s own `GitHub.Ruleset`
+  (`node_modules/alchemy/src/GitHub/Ruleset.ts`): its 5th slot is `GitHub.Providers`, the
+  `ProviderCollection` tag `GitHub.providers()` outputs — never the raw `GitHubCredentials`
+  service its own provider handlers pull in via `octokitFor`. `RepositoryRuleset` now omits the
+  5th parameter, defaulting its declaration requirement to `Provider<RepositoryRuleset>` instead —
+  a real `ProviderServices` member, matching the pattern a standalone (non-collection) resource
+  needs.
+
+  Fixing only the declaration was not enough on its own: `GitHub.providers()` and
+  `RepositoryRulesetProvider()` written side by side as a stack's `providers` still fails to
+  typecheck, because `RepositoryRulesetProvider()`'s handlers need `GitHubCredentials` fed in, and
+  merging two layers does not thread one's output into the other's requirement. New export
+  `repoPolicyProviders()` (`repository-ruleset-providers.ts`) composes the two correctly —
+  `RepositoryRulesetProvider().pipe(Layer.provideMerge(GitHub.providers()))` merged with
+  `GitHub.providers()` itself — and is now the documented wiring in `docs/repo-policy.md`,
+  `docs/repository-ruleset.md`, `repo-policy.ts` and `declare-repo-baseline.ts`.
+
+  Added a type-level test (`repo-policy-stack.test.ts`): a real `Alchemy.Stack(...)` whose body
+  calls `declareRepoPolicy` and `declareRepoBaseline` with `repoPolicyProviders()`, built (never
+  run) so `tsc` checks it on every `bun run check` — the test that would have caught this before
+  it reached a consumer's bump PR.
+
+  No runtime behavior changes: every CRUD handler (`read`/`diff`/`reconcile`/`delete`) and its own
+  `GitHubCredentials` requirement is unchanged — only the type surface a stack body sees when
+  declaring the resource, and how the two providers compose, is fixed.
+
+## 0.28.0
+
+### Minor Changes
+
+- [#206](https://github.com/taslabs-net/homeflare-kit/pull/206) [`06591c9`](https://github.com/taslabs-net/homeflare-kit/commit/06591c91d622178fdf1b09d8ac2f455bafa70107) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Aliases four more distilled interim SDKs onto `@homeflare/alchemy`'s
+  `dependencies`, following `docs/distilled-interim.md`'s step 5:
+  `@distilled.cloud/proxmox-backup`, `@distilled.cloud/paperless-ngx`,
+  `@distilled.cloud/litellm` and `@distilled.cloud/caddy`, each aliased onto
+  its published `@homeflare/distilled-<vendor>` interim copy (kit PRs [#200](https://github.com/taslabs-net/homeflare-kit/issues/200),
+  [#194](https://github.com/taslabs-net/homeflare-kit/issues/194)/[#195](https://github.com/taslabs-net/homeflare-kit/issues/195), [#201](https://github.com/taslabs-net/homeflare-kit/issues/201), [#202](https://github.com/taslabs-net/homeflare-kit/issues/202)) at its current workspace version — not opnsense or
+  unifi-network, neither of which is aliased anywhere yet. No resource in this
+  package imports any of the four yet; that migration is each family's own
+  later PR, per `distilled-interim.md`'s "what NOT to do".
+
+  The root `build:interim-packages` script (kept root-level and non-nested,
+  the CI-race fix from kit PR [#193](https://github.com/taslabs-net/homeflare-kit/issues/193)) is now generic: it discovers which
+  `packages/distilled-*` copies to build by scanning every workspace
+  manifest's `dependencies` for a `"@distilled.cloud/<vendor>":
+"npm:@homeflare/distilled-<vendor>@<version>"` alias, instead of a
+  hard-coded netbox/proxmox list — a new alias needs no edit to this script.
+  `tests/catalog.test.ts`'s `EXACT_PEERS` table is now derived the same way
+  for every `distilled-*` interim copy (`effect` alone, one reasoning comment
+  kept in one place) instead of one hand-added entry and comment per vendor,
+  which had become a recurring merge-conflict hot spot across concurrent
+  interim-package PRs landing the same night.
+
+  This is a `minor`, not a `patch`: `@homeflare/alchemy`'s own `dependencies`
+  gained four new runtime entries, even though no exported code changed.
+
+- [#205](https://github.com/taslabs-net/homeflare-kit/pull/205) [`3ab881e`](https://github.com/taslabs-net/homeflare-kit/commit/3ab881ecd53108050b1d23db39d955e82a07c322) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `GitHub.RepositoryRuleset` now expresses a live ruleset's exact shape when that shape is
+  narrower than the house baseline: a `rules.pullRequest: false` declares its deliberate absence
+  (matching the `requiredStatusChecks: false` pattern that already existed), and `bypassActors`
+  already carried an arbitrary `actor_id`/`actor_type`/`bypass_mode` list — the gap was never the
+  prop shape, it was that nothing stopped a declaration from silently narrowing what is live.
+
+  Two new guards close that: `bypassNarrowingRefusal` refuses a declared `bypassActors` that drops
+  a live actor, and `ruleNarrowingRefusal` refuses a declared `false` (any modeled rule) that drops
+  a rule the live ruleset still has — both unless the declaration also carries the matching new
+  prop, `acknowledgeBypassNarrowing: { reason: string }` or `acknowledgeRuleNarrowing: { reason:
+string }`, a reasoned, explicit sign-off. The two acknowledgements are deliberately separate
+  props, not one shared flag: an adversarial review found that a single shared
+  `acknowledgeNarrowing` let a reason worded for one kind of drop silently also excuse the other
+  kind in the same declaration, so each guard now reads only the prop scoped to what it checks.
+  Widening bypass stays refused unconditionally, as before — this only ever loosens the NARROWING
+  side, and only with a recorded, correctly-scoped reason.
+
+  Prompted by a red-team finding against a design for declaring ~88 `taslabs-net` repos' GitHub
+  settings in Alchemy: 5 live repos (`taslabs-net`, `aop`, `magictransit`, `loggarr`,
+  `doesthishelp-workeropen`) carry a non-empty live `bypass_actors`, and `taslabs-net` itself has
+  no live `pull_request` rule — the exact combination `repoBaselineRuleset()`'s hardcoded
+  `bypassActors: []` and always-on `pullRequest` rule could not adopt without silently stripping
+  protection. `repoBaselineRuleset()` itself is unchanged — it keeps its baseline defaults, for
+  repos the baseline shape actually fits; a caller with a narrower live ruleset now declares
+  `RepositoryRuleset` directly with the live shape instead.
+
+  Tested against all 5 live shapes, re-read via `gh api repos/taslabs-net/<repo>/rulesets/<id>`
+  2026-09-23 (not copied from an earlier paraphrase — `doesthishelp-workeropen`'s two bypass
+  actors' `bypass_mode`s differ from how an earlier design doc described them).
+
+## 0.27.4
+
+### Patch Changes
+
+- [#193](https://github.com/taslabs-net/homeflare-kit/pull/193) [`41bdc5d`](https://github.com/taslabs-net/homeflare-kit/commit/41bdc5d8f32fca92d60ee667b85306c77cea2442) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `netbox/*` family (`Netbox.Prefix`) now calls `@distilled.cloud/netbox`'s
+  typed `ipam` operations instead of a hand-rolled `Effect HttpClient` client.
+  The old status-carrying `NetboxError` and its `cause.status === 404` check
+  are gone: `Netbox.Prefix` locates by a server-side list filter, which
+  `@distilled.cloud/netbox` never answers with a 404 (an empty page is a
+  normal 200), so nothing here checks a status code at all — a stronger
+  version of the same rule `catchTag('NotFound', …)` enforces for a
+  distilled-backed family that reads by direct key, like `forgejo/*`.
+  `client.ts` is gone; nothing else in this package imported it. The real
+  `@distilled.cloud/netbox` is not published upstream yet, so this package
+  aliases it onto `@homeflare/distilled-netbox@0.2.0` (built the distilled way
+  and shipped from this monorepo — see `docs/distilled-interim.md`) as a plain
+  `dependencies` entry, not a peer — nothing changes for a consumer's install.
+  Credentials still resolve from `NETBOX_URL` / `NETBOX_TOKEN` at call time,
+  now through the package's own `CredentialsFromEnv` layer. Props and
+  attributes are unchanged — an adopted prefix still plans noop.
+
+## 0.27.3
+
+### Patch Changes

package/docs/changelog/archive-10.md

@@ -0,0 +1,182 @@
+# Alchemy changelog archive 10
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+- [#191](https://github.com/taslabs-net/homeflare-kit/pull/191) [`e991225`](https://github.com/taslabs-net/homeflare-kit/commit/e9912254041b1f15195f8a4cf2917e00a1194d43) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `packages/alchemy` now depends on `@distilled.cloud/proxmox`, aliased per
+  `packages/alchemy/docs/distilled-interim.md`'s interim-package route onto
+  the published `@homeflare/distilled-proxmox@0.2.0`
+  (`"npm:@homeflare/distilled-proxmox@0.2.0"` in `dependencies`, not
+  `peerDependencies` — the package needs it resolved, not left to whoever
+  installs it). This is the follow-up PR `distilled-proxmox-interim.md`
+  called out: the alias, plus `src/proxmox/distilled-task-await.test.ts`
+  (ported off draft PR 182's dev-only `link:` dependency onto the real alias,
+  assertions unchanged) proving `awaitTask`'s poll-until-exitstatus loop
+  against a fake PVE — success only on `exitstatus` exactly `"OK"`,
+  `"OK (warnings)"` fails, and a bare 400 is the non-retryable `BadRequest`
+  (that last case already lives in `packages/distilled-proxmox/src/protocol.test.ts`,
+  merged with the package itself).
+
+  No existing `packages/alchemy/src/proxmox/*` resource is touched or moved
+  onto the distilled package — that migration is still a separate, later PR.
+  Because `@homeflare/distilled-proxmox` is also a sibling workspace package,
+  bun resolves the alias to the local workspace copy rather than fetching the
+  npm tarball (same unmodified code either way); that local copy has no
+  prebuilt `dist` by default, and `tsc`'s `moduleResolution: "bundler"`
+  follows the alias's `exports["."].types` straight to `dist/index.d.ts` when
+  typechecking the new test file — `bun test` itself needs no such build
+  (it resolves the package's own `bun` export condition straight to `src`).
+  `packages/alchemy/package.json` gets a `pretypes` script
+  (`bun run --filter '@homeflare/distilled-proxmox' build`) so `bun run
+types` — and therefore `bun run check` — builds that one dependency first;
+  nothing else changes.
+
+## 0.27.2
+
+### Patch Changes
+
+- [#180](https://github.com/taslabs-net/homeflare-kit/pull/180) [`1a85198`](https://github.com/taslabs-net/homeflare-kit/commit/1a85198349981e04f475c0e08b0aa2a995719ef4) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The `forgejo/*` family (`Forgejo.Repository`, `Forgejo.BranchProtection`,
+  `Forgejo.OrgLabel`, `Forgejo.OrgTeam`, `Forgejo.RepoWebhook`,
+  `Forgejo.OrgSecret`, `Forgejo.TeamMember`) now calls
+  `@distilled.cloud/forgejo@1.0.0-rc.12`'s typed operations instead of a
+  hand-rolled `Effect HttpClient` client — `catchTag('NotFound', …)` in place
+  of a status-carrying `ForgejoError`. `client.ts` is gone; nothing else in
+  this package imported it. Credentials still resolve from `FORGEJO_URL` /
+  `FORGEJO_TOKEN` at call time, now through the package's own
+  `CredentialsFromEnv` layer. Every operation this family calls exists in the
+  package and every error it handles carries a tag, so no distilled patch was
+  needed. Props and attributes are unchanged — an adopted repository, label,
+  team, webhook, branch protection rule, org secret or team membership still
+  plans noop.
+
+- [#179](https://github.com/taslabs-net/homeflare-kit/pull/179) [`0419d30`](https://github.com/taslabs-net/homeflare-kit/commit/0419d30860e4f6ffbf42e0e1257bd5845a00a418) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `Cloudflare.R2BucketLock` now calls `@distilled.cloud/cloudflare/r2`
+  (`getBucketLock`/`putBucketLock`) instead of the `cloudflare` npm SDK, the same
+  distilled package `MeshNode` already used — `catchTag('NoSuchBucket', …)` in
+  place of an `instanceof NotFoundError` status check. The `cloudflare` peer
+  dependency and `client.ts` are gone; nothing else in this package imported
+  them. Props, attributes and the wire body are unchanged — an adopted lock
+  still plans noop.
+
+## 0.27.1
+
+### Patch Changes
+
+- [#177](https://github.com/taslabs-net/homeflare-kit/pull/177) [`615d7f0`](https://github.com/taslabs-net/homeflare-kit/commit/615d7f0f081828a64f2c334ce423324f10e13921) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `launchd-ports.md` and `port-claims.ts`'s header comment no longer cite the
+  house monorepo's path and a pinned commit as the source of the port-collision
+  rule; both now state it as the kit's own rule, matching the estate's existing
+  port-collision strictness on its own terms. No behavior change.
+
+## 0.27.0
+
+### Minor Changes
+
+- [#175](https://github.com/taslabs-net/homeflare-kit/pull/175) [`7767e82`](https://github.com/taslabs-net/homeflare-kit/commit/7767e82d18e74af203ccae108b8e4f3de99be724) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `GitHub.RepositoryRuleset`, a bridge resource under `@homeflare/alchemy/github` that
+  probes for an existing same-named ruleset by name before creating one (closing the
+  duplicate-ruleset hazard in upstream `alchemy@2.0.0-beta.79`'s `GitHub.Ruleset`) and
+  normalizes before comparing so a matching live ruleset is a true noop. Also adds
+  `declareRepoBaseline`, and rewires `declareRepoPolicy`'s ruleset half onto the new
+  resource — `builds` is the only caller, and its ruleset has never been created, so this
+  changes no live resource's identity.
+
+  Versions this was walked against: `alchemy@2.0.0-beta.79`, `@octokit/rest@22.0.1`,
+  `@octokit/openapi-types@27.0.0` (the version the REST method parameter types actually
+  resolve through — see `repository-ruleset-constraints.ts` for the version-chain note).
+
+## 0.26.0
+
+### Minor Changes
+
+- [#171](https://github.com/taslabs-net/homeflare-kit/pull/171) [`66e6e03`](https://github.com/taslabs-net/homeflare-kit/commit/66e6e03060b0cebbf0e326e6f2880f196735fba7) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `sshSudoRunner()` to `@homeflare/alchemy/linux` — the Linux twin of the launchd subpath's
+  `sudoRunner()`, for a host stack whose ssh user is not root but has passwordless sudo
+  (`(ALL) NOPASSWD: ALL`). The deploy runs as the operator, and only a fixed allowlist of absolute
+  `sudo -n` calls elevates: `install`→`mv` (GNU `install` writes through its destination, so this
+  runner stages, installs into a derived temp file, then `mv`s it into place — a rename(2), atomic
+  by construction), `rm`, `mkdir`/`chmod`/`chown`/`rmdir` for `Host.Directory`, and
+  `daemon-reload`/`enable`/`disable`/`start`/`stop`/`restart` for `Systemd.Unit` and
+  `Systemd.Timer` (gated by each unit's own `FragmentPath`, so a vendor unit like
+  `pveproxy.service` stays unreachable). Every privileged argv is logged before it runs; a plan
+  never elevates (`checkWrite` and every read stay on the operator); the host guard reads the whole
+  directory chain from `/` down to the target in one `ls -ldn` call, refusing anything not
+  root-owned, group/other-writable, ACL-flagged, or the wrong kind. See
+  `packages/alchemy/docs/linux-sudo.md` for the full argv table and what is measured versus
+  reasoned — write paths are reasoned, not run live; construction and `checkWrite` were exercised
+  read-only against a real Debian 13 / trixie host (systemd 257.13-1~deb13u1, coreutils 9.7-3),
+  confirming nothing is elevated by a plan.
+
+  homeflare-proxmox's first consumer: a script, systemd service and timer declared per Proxmox
+  node with `sshSudoRunner({ host, prefixes: ['/usr/local/bin', '/etc/systemd/system'] })`.
+  Groundwork from PR 132 (`src/linux/sudo-listing.ts`, the `ls -ldn` chain reader) is now used
+  directly by the new guard rather than left unreferenced.
+
+## 0.25.1
+
+### Patch Changes
+
+- [#168](https://github.com/taslabs-net/homeflare-kit/pull/168) [`f5b8dcf`](https://github.com/taslabs-net/homeflare-kit/commit/f5b8dcf7e5875f1f5f589a73139fa58d8d886a43) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Fix `Systemd.Unit`: for a unit declared `started: false`, `ActiveState=activating` no longer
+  reads as drift. A timer-driven `Type=oneshot` service (no `[Install]`; its `.timer` starts it)
+  reports `activating` for the whole duration of its run, not an instant — so a plan taken
+  mid-run used to show `update`, and a deploy would `systemctl stop` a check that was already
+  running. Now only `ActiveState=active` counts as drift for `started: false`; `started: true`
+  (the default) is unchanged. `activating` with `SubState=auto-restart`/`auto-restart-queued` —
+  systemd's crash-restart backoff, not a fresh start — is excluded from that exemption and still
+  counts as drift, so a crash-looping unit declared `started: false` is still stopped. Both
+  `diffUnit` (unit-lifecycle.ts) and `settle` (unit-settle.ts) now share one predicate,
+  `isUnitRunning` (unit-form.ts), so they can never disagree about it.
+
+## 0.25.0
+
+### Minor Changes
+
+- [#163](https://github.com/taslabs-net/homeflare-kit/pull/163) [`cf301fb`](https://github.com/taslabs-net/homeflare-kit/commit/cf301fba5196056938419140e80754dc7bf34991) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `@homeflare/alchemy/paperless`: `Tag`, `DocumentType`, `StoragePath` and `CustomField` —
+  Paperless-ngx's taxonomy, create-or-update and never deleted by default — generated from
+  Paperless-ngx **3.1.1**'s own served OpenAPI document (API version **10**, sha256 `d0fe550d…`).
+  Types (`generated/types/*.ts`) and constraint tables (`generated/constraints/*.ts`) are both
+  generated by the new `bun codegen/paperless.ts`, which also introduces
+  `codegen/openapi-types.ts` (a component-to-TypeScript emitter over `openapi.ts`'s `JsonSchema`)
+  and `codegen/dialects.ts` (the regex-dialect-plus-anchoring table `codegen/netbox.ts` now reads
+  too, unchanged).
+
+  Every create sends `owner` (null when undeclared) — Paperless-ngx's `OwnedObjectSerializer`
+  defaults an absent `owner` to the token user, so omitting it the way an undeclared NetBox
+  foreign key is omitted would create a second, invisible row on every deploy. `read` answers
+  `Unowned` on every match rather than adopting silently (H1). A `CustomField.dataType` change is
+  refused at plan time — never a PATCH, never a replace — because either one deletes that field's
+  value on every document.
+
+## 0.24.0
+
+### Minor Changes
+
+- [#157](https://github.com/taslabs-net/homeflare-kit/pull/157) [`2a69523`](https://github.com/taslabs-net/homeflare-kit/commit/2a69523410521f8373d2c216070f788df0ca2a64) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `LiteLLM.PassThroughEndpoint` to `@homeflare/alchemy/litellm`, the kit's first LiteLLM
+  resource: one row of LiteLLM's `/config/pass_through_endpoint` family, a route on the proxy that
+  forwards requests to an upstream target. Types are generated from LiteLLM **1.100.0**'s own
+  OpenAPI document (tag `v1.100.0`, commit `e4f25265704e2b2c6cf6e81be2e4c5cffff896f4`), dumped the
+  way the vendor's own CI dumps it — `prisma generate` against `litellm/proxy/schema.prisma`, then
+  the `dumpSpec` program embedded in `ui/litellm-dashboard/scripts/gen-api-types.mjs`, run with
+  `app.routes`' `include_in_schema` forced `True` the way the dashboard's generator does — because
+  the reference proxy's `/openapi.json` could not be reached when this was walked (jetsam restart
+  loop). Cross-checked byte-identically: regenerating with `openapi-typescript@7.13.0` reproduces
+  the tag's committed `ui/litellm-dashboard/src/lib/http/schema.d.ts` exactly, sha256
+  `8bc5d9c9…40b83f9`, 2,334,248 bytes on both sides. The dump itself is sha256
+  `1b3e4d23…4b006399f` (`codegen/manifest.json`'s `litellm-openapi` entry).
+
+  Every pass-through endpoint lives in one `general_settings.pass_through_endpoints` field — every
+  create, update and delete is a read-modify-write of the whole list — so every mutating call is
+  wrapped in a per-base-URL `Effect` semaphore, and `reconcile` reads back after writing rather
+  than trusting the call that just returned. A path already held by a `config.yaml` entry
+  (`is_from_config: true`) is refused at plan rather than silently overridden; a foreign DB row on
+  the same path is `Unowned` and needs `--adopt`; a literal secret in a forwarded `Authorization`,
+  `x-api-key` or `cf-aig-authorization` header is refused unless it carries LiteLLM's own
+  `os.environ/NAME` reference form. Clearing `timeout`, `methods` or `guardrails` is planned as a
+  replace (delete then create), because LiteLLM's update route merges with `exclude_none` and can
+  never clear an already-set field. Credentials (`LITELLM_PROXY_URL`, `LITELLM_PROXY_API_KEY` —
+  LiteLLM's own variable names) are read fresh from the environment on every call, never a prop.
+
+  Deferred: the Claude OAuth model, key and team slice, which needs estate answers only Tim can
+  give. See `docs/litellm.md`.
+
+- [#156](https://github.com/taslabs-net/homeflare-kit/pull/156) [`6b4b58c`](https://github.com/taslabs-net/homeflare-kit/commit/6b4b58c9a207dd4351d80e514ee4b7d09cc74ea0) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Create-and-assert a database on a self-hosted cluster: `Postgres.Database` in the new
+  `@homeflare/alchemy/postgres` subpath. Walked against PostgreSQL 18.6 (`REL_18_6`, commit
+  `724edf9b`) — upstream `alchemy@2.0.0-beta.79` has vendor-API Postgres resources (Planetscale,
+  Neon, Prisma, Fly, Railway) and a runtime binding over `@effect/sql-pg`, but nothing for a
+  database you run yourself, so this builds on that same `@effect/sql-pg` `PgClient` upstream's
+  own `alchemy/SQL/Postgres` uses (new optional peer, `@effect/sql-pg@4.0.0-rc.115`).