@homeflare/alchemy 0.37.1 → 0.37.3

package/docs/changelog/archive-17.md

@@ -0,0 +1,183 @@
+# Alchemy changelog archive 17
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+### Minor Changes
+
+- [#67](https://github.com/taslabs-net/homeflare-kit/pull/67) [`48163cf`](https://github.com/taslabs-net/homeflare-kit/commit/48163cfc83ad7deac8720be2e8fb7fe964ade7a3) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add to `@homeflare/alchemy/openbao`:
+
+  - **`BaoJwtRole`**: roles on `jwt` and `oidc` mounts.
+  - **`BaoKubernetesRole`**: roles on `kubernetes` mounts. `aliasNameSource` is required, because changing it on a live role moves every pod to a new entity.
+  - **`BaoJwtAuthConfig`**: the non-secret config of a JWT-validating mount. It deliberately has no OIDC client secret, and it refuses a mount that has one, because its full-replace write would erase it.
+  - **`BaoMfaTotpMethod`** and **`BaoMfaLoginEnforcement`**: login MFA. A TOTP method is found by name. Renaming one is refused, because a rename would strand every enrolled secret. A name already held by another MFA method type is refused too, because the write would convert that method. Deleting an enforcement is refused, because in OpenBao 2.6.2 the delete comes back after a restart (openbao/openbao#4030).
+  - **`assertBaoIdentity`** (with `assertBaoIdentityEffect` and `BaoIdentityError`): refuses to proceed unless unauthenticated `sys/health` reports the expected `cluster_name` and the namespace is the expected one.
+  - **`hostAppRoles`**: a pure generator that makes one AppRole per host, named `<class>--<host>`. It refuses a secret_id TTL of 0.
+
+  Behaviour changes:
+
+  - A changed `path` on `BaoMount` or `BaoAuthMethod` now **fails the plan** unless the new `remountFrom` prop names the old path. With `remountFrom`, the mount is moved with `sys/remount`, keeping its data (leases under it are revoked). Before, the plan answered `update` and enabled an empty mount at the new path.
+  - A changed `name` on `BaoAuthRole`, or a changed `name` on `BaoPkiRole`, now plans `replace`. Before, it answered `update` and left the old role live with no state record.
+  - `BaoPkiRole` now manages `requireCn`, `enforceHostnames`, `keyUsage`, `allowedDomainsTemplate`, `noStore` and `generateLease`, defaulting to OpenBao's own values. Its full-replace write already reset these fields silently, so a role whose live values differ from those defaults now plans `update` instead of being reset unseen. `noStore` together with `generateLease` is refused.
+
+  See `src/openbao/REPLACE.md` for what every family does on a rename.
+
+- [#68](https://github.com/taslabs-net/homeflare-kit/pull/68) [`b023bae`](https://github.com/taslabs-net/homeflare-kit/commit/b023bae8f20d6aa33239107dc0538750efc466ca) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add the `@homeflare/alchemy/launchd` subpath, so a Mac host can be declared with Alchemy.
+
+  - `LaunchdJob` / `LaunchdJobProvider` (`Launchd.Job`): one launchd job in the `system` domain or a `gui/<uid>` domain. The provider renders the plist itself, writes it atomically to the derived path (`/Library/LaunchDaemons` or the user's `LaunchAgents`) and drives `launchctl`. Create bootstraps; update writes, boots out and bootstraps (a restart); read uses `launchctl print`; diff compares the rendered plist's SHA-256 with the stored and on-disk digests. Replace happens only on a `label` or `domain` change, delete-first — so everything the new job would be refused for is refused at plan time, while the old job still runs, and a rename is seen even while other props are unresolved. A label another job already holds is never booted out or overwritten. A failed first bootstrap removes the plist it wrote. A disabled label is refused, not re-enabled. Labels under `org.nixos.`, `com.apple.` and `homebrew.mxcl.` are refused; `docs/launchd.md` describes the nix-darwin cutover.
+  - `HostFile` / `HostFileProvider` (`Host.File`): a text file with mode, owner and group. It is written atomically (temp file, then rename), diffed by SHA-256, mode and owner, and refused over a symlink, a directory, or a different file at a new path.
+  - `HostRunner`, `localRunner()`, `hostRunnerLayer()` and `launchdProviders()`: every filesystem and `launchctl` call goes through one injectable runner. The local runner never elevates. System-domain writes are refused unless the deploy runs as root or the runner is explicitly `privileged`.
+  - `renderPlist`: a small, deterministic XML plist serializer, round-tripped through `plutil` in the tests.
+
+  Props are stored unencrypted in Alchemy state, so `environment`, `programArguments` and file `content` must not hold secrets. A tripwire refuses the obvious cases; secret files stay rendered by openbao-agent, and the stack declares only their path. Anything already on the host is read as `Unowned`, so it is never adopted without `--adopt`.
+
+## 0.5.0
+
+### Minor Changes
+
+- [#64](https://github.com/taslabs-net/homeflare-kit/pull/64) [`3ed9771`](https://github.com/taslabs-net/homeflare-kit/commit/3ed977142ffe2fe6dd02359a3a87b1a0a84c9952) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `appRoleLogin` / `revokeSelf` (with `appRoleLoginEffect`, `revokeSelfEffect` and `BaoLoginError`) to `@homeflare/alchemy/openbao`, so wrapper scripts can log in with an AppRole and revoke on exit. They use the same address resolution and transport as the `Bao.*` families. The login never sends `BAO_TOKEN`, and error strings are redacted, because OpenBao 2.6.2 can echo a secret_id back in an error. `clientToken` is a getter over a private field, so printing or serialising the result does not show the token under Bun or Node.
+
+  Add `BaoPlugin` / `BaoPluginProvider` for the plugin catalog (`sys/plugins/catalog/<type>/<name>`). It has no `env` prop and retains on destroy. It refuses to shadow a builtin or overwrite a declarative entry, and it names the fix when an unversioned registration is filed under the binary's self-reported version.
+
+  Fix `BaoSshRole` writes. `default_extensions` and `default_critical_options` were sent as JSON strings. OpenBao's field validation rejects that with a 400, so every role write failed. They are now sent as objects.
+
+## 0.4.1
+
+### Patch Changes
+
+- [#62](https://github.com/taslabs-net/homeflare-kit/pull/62) [`93b7107`](https://github.com/taslabs-net/homeflare-kit/commit/93b71070b1a64701cadc1a547044a3ec4da26a50) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export TB4 control-plane Resource constructors from `@homeflare/alchemy/proxmox` (Storage, SDN, access, HA, backup, metrics, PBS). Guests and NIC apply stay Provider-only.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#60](https://github.com/taslabs-net/homeflare-kit/pull/60) [`df34d27`](https://github.com/taslabs-net/homeflare-kit/commit/df34d2750fca4a2b6b86490ddb0a819c12f9ea39) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `BaoAuthMethod` so a stack can enable `approle` (or jwt/oidc) instead of running `configure-engines`. Metadata only — no role ids or OIDC secrets. File audit stays out: OpenBao 2.6 file audit is config-only.
+
+## 0.3.2
+
+### Patch Changes
+
+- [#58](https://github.com/taslabs-net/homeflare-kit/pull/58) [`e7c101f`](https://github.com/taslabs-net/homeflare-kit/commit/e7c101faada2b14466a1f0bbf1f93da46e5e06cb) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Bump Alchemy to 2.0.0-beta.79. Effect stays rc.115. 79 starts Bun with production JSX (the `jsxDEV` CLI crash on 78) and declares `mime` on cloudflare-runtime; the `mime` peer stays so existing consumer installs do not drop a required line.
+
+## 0.3.1
+
+### Patch Changes
+
+- [#56](https://github.com/taslabs-net/homeflare-kit/pull/56) [`5f41ad7`](https://github.com/taslabs-net/homeflare-kit/commit/5f41ad7ab59375e42bb4757dd5b4b81f4a7b6cd9) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export `BaoPkiRole` and `BaoSshRole` from `@homeflare/alchemy/openbao`. The barrel already shipped both providers; stacks constructing either role had to import the resource from internals.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#54](https://github.com/taslabs-net/homeflare-kit/pull/54) [`d526365`](https://github.com/taslabs-net/homeflare-kit/commit/d526365a51deac968e5b0076e88b2e68b866534f) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Bump Alchemy to 2.0.0-beta.78 and Effect to 4.0.0-rc.115. Consumers must move the override set with it — Alchemy 78's peer is `effect >= rc.115`. Effect rc.115 renamed `Config.redacted` to `Config.Redacted`. `mime@4.1.0` is now a required peer: Alchemy's cloudflare-runtime imports it and does not declare it.
+
+## 0.2.2
+
+### Patch Changes
+
+- [#46](https://github.com/taslabs-net/homeflare-kit/pull/46) [`9bc37f8`](https://github.com/taslabs-net/homeflare-kit/commit/9bc37f8bd7b9af1fd5c62cc4bc48597251ef61ab) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export `BaoMount` and `BaoAuthRole` from `@homeflare/alchemy/openbao`.
+
+  The docs already showed `import { BaoMount } from '@homeflare/alchemy/openbao'`, but the barrel only shipped the providers. Stacks constructing those resources had to import from internals.
+
+- [#48](https://github.com/taslabs-net/homeflare-kit/pull/48) [`4967118`](https://github.com/taslabs-net/homeflare-kit/commit/4967118cc887faba34b17cd48588102736be49bb) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export `BaoCloudflareRole` and the Cloudflare role catalog helpers from `@homeflare/alchemy/openbao`, and retry dropped OpenBao transports.
+
+  Stacks declaring mint roles need the resource constructor plus `parseRolesConfig` / `expandAll` / `permissionGroupsFromEngine`. The barrel previously shipped only `BaoCloudflareRoleProvider`. A 585-role plan against a Mesh-fronted vault died mid-diff with an empty transport error; status-0 calls now retry twice.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#40](https://github.com/taslabs-net/homeflare-kit/pull/40) [`60c90eb`](https://github.com/taslabs-net/homeflare-kit/commit/60c90eb4682d0ded2597a79033159ab71cc7a649) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Pin `rolldown` in the consumer overrides so an unlocked install cannot float a missing tarball.
+
+  Alchemy's optional peer `vite@^8` depends on `rolldown: ~1.2.6`. A consumer `bun add`
+  (no lockfile) resolved that to 1.2.9; npm listed the version and 404'd
+  `rolldown-1.2.9.tgz`. Main CI failed on that fetch after [#39](https://github.com/taslabs-net/homeflare-kit/issues/39). The override holds 1.2.8 —
+  the last tarball a green smoke actually installed.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#36](https://github.com/taslabs-net/homeflare-kit/pull/36) [`cff4111`](https://github.com/taslabs-net/homeflare-kit/commit/cff4111c2f4461a45be5811547125b1f5d98c6d2) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Ship the HTTP and Website SDK surfaces apps were hand-rolling.
+
+  **`@homeflare/kit/openapi`** — `createOpenApiApp()` is OpenAPIHono with one
+  readable validation hook. The document and the request share a Zod schema.
+  Subpath, not the main entry: a Node script that only wants `parseEnv` must not
+  resolve Hono. Peers: `hono`, `@hono/zod-openapi`, `zod` (optional). Import `z`
+  from `@hono/zod-openapi`.
+
+  **`astroWebsite` / `viteWebsite`** on `@homeflare/alchemy/cloudflare` — house
+  flags on Alchemy's own stacks. Astro gets `disable_nodejs_process_v2` (workerd
+  process-v2 returns `[object Object]`). Vite is TanStack Start / static Vite.
+  Not Nextjs: that helper hashes source and plans as create against a live Worker.
+
+  Catalog also pins `@tanstack/react-router` 1.170.35, `@tanstack/react-start`
+  1.168.52, `@tanstack/react-query` 5.102.8 — match these, do not wrap them.
+
+## 0.1.3
+
+### Patch Changes
+
+- [#32](https://github.com/taslabs-net/homeflare-kit/pull/32) [`5cc2cd6`](https://github.com/taslabs-net/homeflare-kit/commit/5cc2cd62241f926aace1646fd3a1e0057e96cddd) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Add `accessIdentity` (ctx.access) and RFC 9728 MCP discovery; fix three doc defects.
+
+  An app team reviewed the published packages before adopting and was right on every point.
+
+  **`accessIdentity(ctx)` — Access identity without parsing a JWT.** Cloudflare attaches the
+  authenticated identity to the execution context (shipped 2026-08-14), so a Worker behind
+  Access reads `ctx.access.getIdentity()` with no token handling. The kit only offered
+  `verifyAccessJwt`, which is the older path.
+
+  ⛔ Both stay, because they are not alternatives: `accessIdentity` for a Worker behind
+  Access, `verifyAccessJwt` for an origin that has no `ctx.access` — service-to-service, a
+  non-Worker origin, or a Worker reached by service binding, since **`ctx.access` does not
+  propagate through bindings**.
+
+  ⚠️ Read groups from `accessIdentity`, not from a token: Cloudflare trims the JWT's
+  `custom` claim at roughly 1 KB _silently_, so token-read group membership can be
+  incomplete — an authorization bug that only appears for users in many groups.
+
+  **`serveMcpMetadata` / `unauthorizedResponse` — RFC 9728.** The MCP spec requires a server
+  to publish Protected Resource Metadata _and_ a 401 naming it in `WWW-Authenticate`.
+  Publishing the document while answering a bare 401 leaves clients that follow the header
+  with nowhere to go.
+
+  **Three documentation defects, all reported and all real:**
+
+  - `@homeflare/alchemy`'s README documented `@homeflare/alchemy/providers`, which does not
+    exist. The real path is `/cloudflare`.
+  - `@homeflare/cloudflare`'s npm description advertised "typed bindings" — it exports none.
+  - `@homeflare/kit`'s advertised "logging" — `log` lives in `@homeflare/cloudflare`.
+
+  **Packing no longer edits a manifest on disk.** `packForPublish` stripped `scripts` and
+  `devDependencies` from the real `package.json`, packed, then restored it — which is a race
+  when two smoke tests pack the same workspace dependency in parallel. It destroyed
+  `@homeflare/kit`'s `scripts` block during this branch, _after_ `verify` had passed. The
+  strip now happens inside the packed tarball, so nothing in the repository is written to.
+
+## 0.1.2
+
+### Patch Changes
+
+- [#29](https://github.com/taslabs-net/homeflare-kit/pull/29) [`72f0787`](https://github.com/taslabs-net/homeflare-kit/commit/72f0787952b3a71bb6573476918e79117250409e) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `cloudflare` is a required peer, not an optional one.
+
+  Measured 2026-09-16 against the published 0.1.1 in a clean consumer install: importing
+  `@homeflare/alchemy/cloudflare` without it throws `Cannot find package 'cloudflare'`.
+  Marking it optional claimed the subpath would degrade gracefully; it does not load at all.
+  An optional peer should mean a _feature_ is absent, not that an import fails.
+
+  ⛔ **Why this got through, and what now stops it.** The README's pinned install command and
+  the smoke test's install command disagreed — the smoke test installed `cloudflare`, the
+  README never mentioned it, and nothing compared the two. So the gate proved an install no
+  consumer would ever perform.
+
+  `tests/peers.test.ts` now asserts the manifest, the README and the smoke script agree:
+  every declared peer appears in all three, peers are pinned rather than ranged, and none is
+  marked optional.
+
+## 0.1.1
+
+### Patch Changes
+
+- [#27](https://github.com/taslabs-net/homeflare-kit/pull/27) [`5b73400`](https://github.com/taslabs-net/homeflare-kit/commit/5b73400e7fc2dd8e28a0368db3e5aa105ebdde9a) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Fix the peer contract: 0.1.0 installed cleanly and threw at import.
+
+  Measured 2026-09-16 against the published 0.1.0 in a clean consumer install — three
+  defects, none of which failed at install time:

package/docs/changelog/archive-18.md

@@ -0,0 +1,55 @@
+# Alchemy changelog archive 18
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+1. **`@effect/platform-node` was a devDependency**, so a consumer got
+   `Cannot find module '@effect/platform-node/NodeServices'`. Alchemy's module graph
+   reaches `Cloudflare/Workers/WorkerBridge` even when you only import `/proxmox`, so it
+   is a required peer, not an optional one.
+2. **The `effect` peer was ranged** `>=4.0.0-rc.112`, which resolves to rc.115 —
+   `TypeError: Config.string is not a function`. Effect's rc line is not
+   semver-compatible with itself, so a range is a promise this package cannot keep. Peers
+   are pinned exactly now.
+3. **`@effect/platform-node-shared` still resolves up** to rc.115 against effect rc.112
+   (`Cannot find module 'effect/ByteSize'`), because `platform-bun@rc.112` asks for
+   `^4.0.0-rc.112`. Only a consumer-side `overrides` block holds the set together, and the
+   README now says so with the exact block to paste.
+
+⛔ The smoke script was `echo '…exercised by the consuming stack'` — a check that cannot
+fail, which is how all three shipped. It now packs the tarball, installs it the way the
+README says, and **imports every subpath**, because each of these threw at import rather
+than at install.
+
+## 0.1.0
+
+### Minor Changes
+
+- [#25](https://github.com/taslabs-net/homeflare-kit/pull/25) [`309c644`](https://github.com/taslabs-net/homeflare-kit/commit/309c644d83c7149571f4caada135d1b8d141a484) Thanks [@taslabs-net](https://github.com/taslabs-net)! - New package: custom Alchemy providers for five systems the vendor has none for.
+
+  **`R2BucketLock`** — an R2 bucket's lock rules, declared rather than applied by hand. A
+  lock rule is a retention floor: while a rule covers an object, no API call, no lifecycle
+  rule and no credential can delete it.
+
+  ★ Alchemy 2.0.0-beta.77 has no lock property anywhere in its R2 namespace, so the
+  alternative was a runbook step a human runs once — and a plan can never show a missing
+  runbook step. Covering the gap with a resource makes the drift visible in `plan`.
+
+  ⛔ Deletion is refused by design: removing a lock removes a retention floor, which is the
+  one operation this resource exists to make hard.
+
+  ⚠️ `alchemy`, `cloudflare` and `effect` are **peers**, not dependencies — Alchemy's
+  resource registry and Effect's context both break if two copies load in one process.
+
+  **Also in this release** — the same treatment for four more systems, 140 files in all:
+
+  - **`/proxmox`** (61 source files) — ACLs, API tokens, backup jobs, Ceph, SDN, storage.
+  - **`/openbao`** (33) — mounts, policies, PKI/SSH/auth roles, Cloudflare role expansion.
+  - **`/forgejo`** (12) — branch protection, org secrets, labels, webhooks.
+  - **`/talos`** (8) — cluster bootstrap, machine config, health.
+
+  ⛔ **Import a subpath, never the root.** Each system carries its own client, so a root
+  barrel would pull Proxmox into a stack that only wanted Forgejo.
+
+  ★ **The barrels are deliberately smaller than the directories** — 70 exported symbols out
+  of 606 defined, chosen from what a real stack actually consumes. An `export *` would
+  publish every helper as API and make the next refactor a breaking change.

package/docs/pbs-distilled-jobs.md

@@ -0,0 +1,31 @@
+# PBS jobs on distilled
+
+The datastore, prune, sync and verification providers use the typed operations in
+`@distilled.cloud/proxmox-backup`, generated from **proxmox-backup-server 4.2.6-1**.
+`distilled-pbs.ts` supplies the existing leased read/provision credentials to the SDK's
+Credentials service. The SDK owns the `PBSAPIToken` header and request serialization.
+
+Existing props and state remain unchanged: retention windows omitted from a declaration
+stay unmanaged, `remove-vanished` still defaults to false, a verification schedule may be
+explicitly null, and a datastore path or backend change is refused. No automatic clearing,
+new deletion flag or live job execution is introduced.
+
+Read-only probes on 2026-09-24 found that missing configuration sections answer plain-text
+HTTP 400: `no such datastore`, `no such prune`, `no such sync`, or `no such verification`.
+The SDK patches those specific GET errors as `DatastoreNotFound`, `PruneJobNotFound`,
+`SyncJobNotFound` and `VerifyJobNotFound`. Providers catch those tags only. Permission
+errors, unrelated 400/500 responses, malformed replies and failed transports propagate.
+A failed read can no longer become a speculative create or a successful deletion.
+
+Delete first reads the declared item. A typed absent item needs no DELETE. When it exists,
+the provider calls the SDK delete operation; any unclassified error during a concurrent
+removal propagates. The datastore retains its bounded readback and default retain policy;
+`destroy-data` is never sent.
+
+The pinned schema declares a null result for datastore create and a UPID for delete. The
+provider verifies the resulting configuration rather than inventing a create task id.
+
+The offline lifecycle suite uses `alchemy/Test/Bun` and a strict in-memory PBS HTTP
+fixture. It covers matching adoption without writes, genuine create, drift repair followed
+by a no-op plan, and refused reads. Live adoption remains a separate consumer gate against
+the released package; an offline fixture is not proof of the running estate.

package/docs/pbs-notifications.md

@@ -12,6 +12,11 @@
 
 A target that no matcher names receives nothing. Declare both.
 
+PBS lifecycle calls use `@distilled.cloud/proxmox-backup` (vendor schema PBS 4.2.6-1).
+The runner reuses short-lived OpenBao leases and bounds each request to 20 seconds, with SDK
+retries disabled. A typed `NotFound` alone means absence or an already completed delete.
+Other read failures stop the plan, so a denied read cannot silently plan a create.
+
 ## Paging on a failed verify, sync, prune or garbage collection
 
 ```ts
@@ -157,7 +162,8 @@ built-in reverts it to the shipped rule**, and the server reports success. The a
 | PBS    | `Sys.Audit` on `/system/notifications`                          | `Sys.Modify` on `/system/notifications`      |
 | PVE    | `Mapping.Audit` or `Mapping.Modify` on `/mapping/notifications` | `Mapping.Modify` on `/mapping/notifications` |
 
-⚠️ A missing read privilege looks like "absent". The plan says `create` and the server answers
-that the object already exists. Grant the read before changing anything else. On PVE,
+⚠️ The old shared client hid missing read privileges as "absent", planning a `create` that the
+server rejected as already existing. PBS now preserves the SDK refusal and fails the plan.
+Grant the required read privilege before changing infrastructure. On PVE,
 `Mapping.Use` is not enough: it opens the matcher list, not the per-matcher read this package
 makes (`get_matcher` in pve-manager's `Notifications.pm`).

package/docs/proxmox-notification-sdk.md

@@ -0,0 +1,28 @@
+# PVE notification SDK migration
+
+PVE 9.2.11 notification targets and matchers use named distilled SDK operations
+for every lifecycle call. Their existing declaration forms, comparison rules,
+secret omission and vendor constraint guards remain in place.
+
+A missing matcher or target returns HTTP 404, confirmed by read-only probes on
+2026-09-24. The provider catches the SDK's typed `NotFound` for absent reads and
+idempotent deletes. Authentication, permissions, transport failures and unrelated
+server errors propagate. A malformed successful read fails against the SDK's
+response schema; diagnostics do not retain response contents.
+
+SDK request schemas validate the form-name translation before sending a write.
+Arrays use repeated form keys. Commas within matcher rules and webhook property
+strings remain part of each item. An explicitly empty recipient/header list uses
+the vendor's update `delete` field, because an empty SDK array emits no keys.
+Undeclared fields remain unmanaged.
+
+A matching adoption sends no write. A changed name replaces the resource; an
+endpoint changing type under the same name replaces delete-first because the
+name is unique across types. Built-in deletion still reverts the vendor default,
+and a gotify create still refuses its missing write-only token: this migration
+does not introduce secrets into persisted props.
+
+`notification-distilled.test.ts` exercises create, matching adoption, list clearing,
+identity replacement, malformed/refused reads and subsequent no-op plans through
+the upstream Alchemy harness and real SDK protocol. Live verification follows the
+published release in the consuming stack; fixtures do not prove live writes.

package/docs/proxmox-sdk-migration.md

@@ -0,0 +1,60 @@
+# PVE/PBS SDK migration
+
+2026-09-24. Transport completion and live adoption are separate gates. The interim
+SDKs follow [the distilled route](./distilled-interim.md): generated vendor schemas,
+local distilled fixes first, verbatim source copies, and published npm aliases.
+
+## Implemented transport
+
+Seventeen existing PVE resource families use named distilled operations throughout:
+ACL, ApiToken, BackupJob, CephDaemon, CephFs, CephOsd, CephPool, Group, MetricServer,
+NodeNetwork, NotificationMatcher, NotificationTarget, Pool, Role, Storage, User and
+ZfsPool. All six existing PBS families now do too: Datastore, NotificationMatcher,
+NotificationTarget, PruneJob, SyncJob and VerifyJob.
+
+The latest migration preserves credential leases, safe member failover, bounded
+polling, vendor constraints, write-only secret handling and existing state shapes.
+The newly migrated pool, metric, job and notification providers fold only typed
+missing-resource errors to absence; their other SDK failures propagate.
+Protocol fixtures exercise the generated operations; Alchemy engine tests prove
+matching adoption does not write and a real update settles to a no-op.
+
+The SDK patches record PVE 9.2.11 source and PBS 4.2.6-1 schema provenance. Read-only
+probes against PVE 9.2.11 and PBS 4.2.3 distinguish notification HTTP404 responses
+from PBS configuration HTTP400 responses. Resource providers do not inspect status
+codes or message text to make that distinction.
+
+## Consumer gate
+
+These families cover the default TB4/HF-Ops/PBS adoption declarations in
+`homeflare-proxmox` at commit `91b31b0`. Its opt-in vault-door Lxc is still a later
+slice. This source migration alone does not establish live adoption.
+After both SDKs and the provider release publish, the consumer pins those exact
+versions, runs its full check and all three adoption verifiers, then compares the
+read and admin plans at stage `live`. A write requires a fresh matching proof.
+
+## Remaining PVE families
+
+Twelve existing families still retain some hand-client transport: Lxc, Vm (QEMU),
+NetworkApply, SdnApply, SdnZone, SdnVnet, SdnSubnet, HaResource, HaRule,
+ReplicationJob, FirewallAlias and CephFlag. Their previous measured-none records
+are historical inventories, not a current census or permission to skip migration.
+
+- NetworkApply needs the `changes` sibling beside the response's `data`; generic
+  unwrapping discards it. Fix the distilled protocol/schema boundary before moving
+  this read. The network diff can contain secrets and must not enter state or logs.
+- Lxc task polling must keep the credential that started the task, preserve bounded
+  uncertainty after connection loss, and retain its cluster-wide identity checks.
+- SdnApply distinguishes an unavailable subsystem from failed reads and refuses
+  undiffable settings. Those semantics need vendor-backed typed SDK errors.
+- Qemu's guest DELETE route differs from its configuration GET/PUT route; copying
+  the old generic factory path would keep an existing bug.
+
+Complete vendor coverage additionally requires a census of families not yet modeled
+as resources. The 23 migrated families above are a transport milestone, not that
+larger completion claim. No upstream push or pull request was made.
+
+Existing NodeNetwork and ZfsPool adoption/reconcile reads still contain broad failure
+folds. Their strict diff reads do not remove that separate conformance gap. CephFs
+task polling also tolerates temporary read failures, but uses a bounded uncertainty
+policy rather than treating a resource as absent.

package/docs/proxmox.md

@@ -37,7 +37,13 @@ CephFS index cannot produce a successful delete. Existing adoption fixtures prov
 matching objects remain no-ops. Credential-denied warnings are still not live no-op
 evidence; use the consumer's authorized read lane and `hf-adopt-verify --all`.
 
-This is a scoped follow-up to the transport migration. CephFS delete still uses the old
-client despite the SDK's now-fixed DELETE query encoding; bounded task polling and
-other pre-existing provider refusals retain their own policies. No live writes are part
+This is a scoped follow-up to the transport migration. CephFS delete now uses SDK 0.3.0's fixed
+DELETE query binding and folds only CephFsNotFound. Its existing destructive flags,
+bounded task polling and final index read remain in place. Other provider families
+retain their own policies. No live writes are part
 of this validation. Released-consumer plans remain a separate gate from these fixtures.
+
+`ceph-fs-destroy-sdk.test.ts` verifies that remove-pools/remove-storages are query
+parameters with an empty DELETE body, omitted flags retain the safe defaults, an
+already-missing filesystem succeeds, and unrelated 401/403/500 responses fail.
+The engine destroy fixture still proves the complete read/delete/poll/read-back flow.

package/docs/upstream-conformance-families.md

@@ -10,6 +10,9 @@ measurements and open findings are preserved below.
    - 27 `Effect.die` sites in non-test source (defect risk, not a separate S20 ban);
    - 7 test files on `node:test`;
    - `Pbs.*` type strings (H14).
+     **SDK progress, 2026-09-24:** 17 PVE and all six existing PBS resource families now
+     call named distilled operations. The [migration record](./proxmox-sdk-migration.md)
+     separates that transport milestone, the published-consumer gate and remaining families.
 8. **`talos/*`.** Its `talosctl` calls go through `ChildProcessSpawner`, as upstream's Docker
    provider does, which conforms. Its file handling uses `Bun.file`, `Bun.write`,
    `Bun.YAML` and `node:fs` (S42), and it uses `Effect.promise` in 3 files (S19). The
@@ -75,8 +78,9 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
 12. **Resource JSDoc is not in upstream's generator format.** Zero files use `@resource`,
     `**Example:**` or `### Section` (S31, H10). **Decision:** maintainer, because it moves
     the house's glyph rationale into `//` comments.
-13. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
-    fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
+13. **Original finding: tests did not use `alchemy/Test/Bun`.** The PVE/PBS SDK migration
+    now exercises provider lifecycles through that upstream engine harness with fake HTTP
+    responses. It does not claim live write coverage; live suites still need a place to run.
 14. **`discord/*` is new (2026-09-24, task-authorized, kit PR TBD) and built directly on
     `@distilled.cloud/discord` — no hand-rolled `client.ts` ever existed to retire.**
     `Discord.ApplicationCommand` and `Discord.GuildApplicationCommand` call the SDK's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.37.1",
+  "version": "0.37.3",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -124,8 +124,8 @@
     "@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@0.3.0",
     "@distilled.cloud/opnsense": "npm:@homeflare/distilled-opnsense@0.2.0",
     "@distilled.cloud/paperless-ngx": "npm:@homeflare/distilled-paperless-ngx@0.3.0",
-    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.0",
+    "@distilled.cloud/proxmox": "npm:@homeflare/distilled-proxmox@0.3.1",
+    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.3.1",
     "@distilled.cloud/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {

package/src/proxmox/adopt-noop.test.ts

@@ -2,10 +2,9 @@
  * Adopting an object that already matches must be read-only — measured per reconcile SHAPE, through
  * Alchemy's own Plan and Apply over a fake cluster (fake-pve.ts, ../verify/fake-engine.ts).
  *
- * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Every family built on
- *   `pveHandlers` shares resource.ts's reconcile, so `Proxmox.Pool` stands for all of them; `Acl`
- *   wraps that reconcile; `PbsDatastore` and `SdnApply` write their own. CephPool, the one that got
- *   it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
+ * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Pool now has its own distilled
+ *   lifecycle; `Acl` wraps resource.ts's shared reconcile; `PbsDatastore` and `SdnApply` write their
+ *   own. CephPool, the one that got it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
  * ⚠️ A FIXTURE THAT DOES NOT MATCH TURNS A ROW INTO A DRIFT TEST, and the assertion on the
  *   verifier's `noop` is what catches that: a wrong fixture fails loudly instead of passing for
  *   the wrong reason. The Pool drift row proves the harness can see a write at all.
@@ -36,7 +35,7 @@ const cases: readonly Case[] = [
   {
     declare: () => ProxmoxPool('lab', { comment: 'x', poolid: 'lab', target: FAKE_TARGET }),
     live: { 'pools/lab': { comment: 'x', members: [] } },
-    name: 'Proxmox.Pool (pveHandlers: every factory family)',
+    name: 'Proxmox.Pool (direct distilled lifecycle)',
     provider: ProxmoxPoolProvider as never,
   },
   {

package/src/proxmox/backup-job-config.ts

@@ -0,0 +1,95 @@
+/** Pure existing forms, normalization and equality, shared by plan and SDK lifecycle. */
+import type { BackupJobAttributes, BackupJobProps } from './backup-job.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { bool, guestList, propertyString, text } from './values.ts';
+
+/**
+ * The form for both create and update.
+ *
+ * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT, AND THAT IS LOAD BEARING. PVE's PUT can only
+ *   SET a key; clearing one needs `delete=<key>`, which this resource deliberately never sends.
+ *   `updateForm` is handed the props and nothing else, so a `delete` list could only be "every
+ *   field you did not declare" — and on a job adopted out of the UI that would silently strip
+ *   settings this resource does not even model, `compress`, `mailto` and `bwlimit` among them, on
+ *   the first deploy. Leaving undeclared fields alone is the smaller lie, and `matches` tells the
+ *   same lie consistently: it does not compare what it cannot change.
+ *
+ * ⚠️ THE FIVE FIELDS PVE DOCUMENTS A DEFAULT FOR ARE ALWAYS SENT AND ALWAYS COMPARED — `enabled`
+ *   (1), `all` (0), `mode` (snapshot), `notification-mode` (auto), `repeat-missed` (0). That is
+ *   what makes a hand-flipped `enabled 0` show up as drift rather than as silence, and it is also
+ *   what stops those five looping: a field compared against a default must be sent as that
+ *   default, or every plan reports an update the PUT never performs. The cost is worth reading
+ *   before the first deploy against an adopted job — an omitted `all` is a declaration that this
+ *   job backs up NOTHING, and PVE accepts a job that selects nothing without a word. Read that
+ *   first plan; do not deploy it unseen.
+ */
+const shape = (props: BackupJobProps) => ({
+  all: props.all === true ? '1' : '0',
+  enabled: props.enabled === false ? '0' : '1',
+  mode: props.mode ?? 'snapshot',
+  'notification-mode': props['notification-mode'] ?? 'auto',
+  'repeat-missed': props['repeat-missed'] === true ? '1' : '0',
+  schedule: props.schedule,
+  ...(props.comment === undefined ? {} : { comment: props.comment }),
+  ...(props.exclude === undefined ? {} : { exclude: guestList(props.exclude) }),
+  ...(props.fleecing === undefined ? {} : { fleecing: props.fleecing }),
+  ...(props['notes-template'] === undefined ? {} : { 'notes-template': props['notes-template'] }),
+  ...(props.pool === undefined ? {} : { pool: props.pool }),
+  ...(props['prune-backups'] === undefined ? {} : { 'prune-backups': props['prune-backups'] }),
+  ...(props.storage === undefined ? {} : { storage: props.storage }),
+  ...(props.vmid === undefined ? {} : { vmid: guestList(props.vmid) }),
+});
+
+export const backupJobSpec = {
+  /**
+   * ⛔ NO "IS IT REALLY THERE" GUARD, ON PURPOSE. Returning undefined for a job whose JSON is
+   *   missing some key would be a guess about which keys PVE echoes back, and a wrong guess here
+   *   does not read as absent-and-harmless: `reconcile` would POST, and POST creates ANOTHER job.
+   *   Absence is decided by the API declining to answer, which `pveOperations.read` already
+   *   handles — not by a key being missing from an answer that did arrive.
+   */
+  attributes: (live, props) => ({
+    all: bool(live['all'], false),
+    comment: text(live['comment'], ''),
+    enabled: bool(live['enabled'], true),
+    exclude: guestList(live['exclude']),
+    fleecing: propertyString(live['fleecing'], 'enabled'),
+    id: props.id,
+    mode: text(live['mode'], 'snapshot'),
+    'next-run': typeof live['next-run'] === 'number' ? live['next-run'] : 0,
+    'notes-template': text(live['notes-template'], ''),
+    'notification-mode': text(live['notification-mode'], 'auto'),
+    pool: text(live['pool'], ''),
+    'prune-backups': propertyString(live['prune-backups']),
+    'repeat-missed': bool(live['repeat-missed'], false),
+    schedule: text(live['schedule'], ''),
+    storage: text(live['storage'], ''),
+    vmid: guestList(live['vmid']),
+  }),
+  collection: () => 'cluster/backup',
+  /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
+  createForm: (props) => ({ ...shape(props), id: props.id }),
+  /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
+  matches: (attributes, props) =>
+    attributes.schedule === props.schedule &&
+    attributes.enabled === (props.enabled !== false) &&
+    attributes.all === (props.all === true) &&
+    attributes.mode === (props.mode ?? 'snapshot') &&
+    attributes['notification-mode'] === (props['notification-mode'] ?? 'auto') &&
+    attributes['repeat-missed'] === (props['repeat-missed'] === true) &&
+    (props.storage === undefined || attributes.storage === props.storage) &&
+    (props.pool === undefined || attributes.pool === props.pool) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.vmid === undefined || attributes.vmid === guestList(props.vmid)) &&
+    (props.exclude === undefined || attributes.exclude === guestList(props.exclude)) &&
+    (props['notes-template'] === undefined ||
+      attributes['notes-template'] === props['notes-template']) &&
+    (props['prune-backups'] === undefined ||
+      attributes['prune-backups'] === propertyString(props['prune-backups'])) &&
+    (props.fleecing === undefined ||
+      attributes.fleecing === propertyString(props.fleecing, 'enabled')),
+  path: (props) => `cluster/backup/${props.id}`,
+  updateForm: shape,
+} satisfies PveSpec<BackupJobProps, BackupJobAttributes>;