@homeflare/alchemy 0.37.1 → 0.37.3

package/docs/changelog/archive-11.md

@@ -0,0 +1,182 @@
+# Alchemy changelog archive 11
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+Create-and-assert only: every optional prop (`encoding`, `localeProvider`, `lcCollate`,
+`lcCtype`, `allowConnections`, `connectionLimit`, `isTemplate`, `tablespace`) is asserted once
+at create and compared against the live row on every later plan — a mismatch is a typed
+`PostgresDatabaseDrift` refusal, never an `ALTER DATABASE`. `name` is refused at plan past 63
+UTF-8 bytes (`NAMEDATALEN`), because the server would otherwise silently truncate it with only
+a `NOTICE`. A rename is refused at plan; `diff` never answers `replace` (a replace here is DROP
+then CREATE, on data). `delete` always refuses with a typed tag and `defaultRemovalPolicy` is
+`retain` — dropping a database stays a human act on the host. `CREATE DATABASE` takes no bind
+parameters at all (measured at `gram.y`), so every value is quoted by hand: a single-token
+identifier quoter for the name (deliberately NOT `alchemy`'s own `sql(value)`, which
+dot-splits a qualified name and would break on a name containing `.`), and a string-literal
+quoter for the rest. `read` always answers `Unowned` for a match — a database carries no
+ownership mark, so an adopting stack needs `adopt(true)`.
+
+Measured path (2026-09-23): only a Unix socket reaches the maintenance database on the mini —
+no `pg_hba` rule opens it over TCP. A JS client reaches that socket: `@effect/sql-pg` under
+Bun, live-checked from scratch space, connected and read all 24 live databases.
+
+- [#160](https://github.com/taslabs-net/homeflare-kit/pull/160) [`26f45bd`](https://github.com/taslabs-net/homeflare-kit/commit/26f45bda0108744994c63b611ca27492aef715fe) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `Release.Binary` can now install from a directory-wrapped vendor archive. `tarReader(wanted, root)`
+  (`packages/alchemy/src/release/tar.ts`) accepts an optional `root`: exactly one declared leading
+  directory (typeflag `5`, size 0) is stripped from every entry name before it is matched, listed or
+  checked for a duplicate. Every entry outside that declared root, a second directory entry, a
+  `<root>-evil/x` sibling (a segment match, not a string prefix), and a `<root>/` entry that is not
+  an empty directory are refused whole, same as every existing refusal (PAX, GNU long-name, `..`,
+  links, devices). Without `root`, behaviour is unchanged: a directory entry — the wrapper included —
+  is still refused exactly as it always was.
+
+  `ReleaseArchive.root?: string` (`binary-form.ts`) carries the pin; `pinProblems` (split out to the
+  new `binary-pins.ts` to stay under the file's 250-line cap, re-exported so no importer moves)
+  refuses a root that is not one safe path segment. `catalogBinary` (`catalog.ts`) carries
+  `archive.root` through when a catalog entry has one. A state row from before this change has no
+  `root`, and `undefined === undefined`, so it is not treated as a moved pin; declaring or changing a
+  root is.
+
+  Measured 2026-09-23 by downloading each vendor's own GitHub release asset into a scratch directory
+  (never executed) and re-hashing: all four Prometheus-family darwin-arm64 archives —
+  `alertmanager` v0.33.1 (37,247,168 B), `blackbox_exporter` v0.28.0 (15,705,022 B), `node_exporter`
+  v1.12.1 (5,368,643 B), `prometheus-community/postgres_exporter` v0.20.1 (10,072,235 B) — recompute
+  to GitHub's own asset `digest`, wrap every entry in exactly one directory named
+  `<binary>-<version>.darwin-arm64/`, and carry no PAX or GNU long-name entries. The worktree's own
+  `tarReader(wanted, root)` was re-run against those same downloaded bytes and now parses each to
+  completion, returning the named member at its full pinned size (`docs/release-binary-catalogs.md`
+  has the full table and commands; `tar-root.test.ts` and `binary-root.test.ts` hold the same proof
+  as committed fixtures).
+
+  This unit adds the reader capability and its tests only. `VICTORIA_RELEASES` and
+  `OPENBAO_RELEASES` are unchanged — no catalog entry for alertmanager, blackbox_exporter,
+  node_exporter or postgres_exporter exists yet; that is its own data-set walk-down and PR.
+
+### Patch Changes
+
+- [#161](https://github.com/taslabs-net/homeflare-kit/pull/161) [`5500f3e`](https://github.com/taslabs-net/homeflare-kit/commit/5500f3e83e90b9e7a0bbad457527f994a741d0d2) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Correct the last stale claim in `Proxmox.ZfsPool`'s docs, per Tim's decision 28 (2026-09-23).
+
+  PR 154 already corrected `zfs-pool.ts`'s header, which previously said destroy was refused and
+  `delete` made no API call — false, since `destroyPool` sends a real `DELETE` under
+  `.pipe(RemovalPolicy.destroy())`, guarded only by the resource's default `retain` removal policy.
+  That fix missed one line: the file's "PRIVILEGES, FROM THE SCHEMA" paragraph still said `delete`
+  "needs nothing at all, since it calls nothing" — the same mistake, left uncorrected in a second
+  place. It now says `delete` needs `Sys.Modify` on `/`, the same as `reconcile`'s POST, per
+  `ceph-osd.ts`'s own privilege comparison (measured against the same 2026-09-13 apidoc read),
+  which names `disks/zfs` as one of the sibling families whose write verbs — not only the create —
+  carry a `Sys.Modify` check.
+
+  No behaviour change. `RemovalPolicy.destroy()` reaching a single `DELETE`, and `retain` sending
+  none, are already pinned in `zfs-pool-adopt.test.ts` (added by PR 154); this PR touches docs only.
+
+## 0.23.0
+
+### Minor Changes
+
+- [#154](https://github.com/taslabs-net/homeflare-kit/pull/154) [`2044487`](https://github.com/taslabs-net/homeflare-kit/commit/2044487b81fecb635da785b0b2637daf2c5b20fe) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export `ProxmoxApiToken` and `ProxmoxZfsPool` from `@homeflare/alchemy/proxmox`, per Tim's
+  decision 9 (2026-09-23): the kit builds an ApiToken export that is metadata-only and a ZfsPool
+  export that is adopt-only. Neither can create what it does not already have to adopt.
+
+  `ProxmoxApiToken` adopts and manages `comment`, `expire` and `privsep` — the whole of a token's
+  policy that PVE will report back — and refuses to mint a new one: the secret exists for one HTTP
+  response and then nowhere (measured from the vendor schema), and this estate's state store
+  persists attributes unencrypted, so a token created here would be a live credential nobody holds.
+  `reconcile` dies by name when the token is absent, naming the two ways to get a usable one
+  (`pveum user token add`, or OpenBao's `proxmox-c1` mount) instead. `shape()` is now typed against
+  the generated `AccessUsersUseridTokenTokenidPutParams` and `PostParams`, so a schema drift fails
+  `tsc` here rather than surfacing as a 400 on a live cluster.
+
+  `ProxmoxZfsPool`'s `devices` and `raidlevel` are now optional: omitting both declares an
+  adopt-only pool, for one PVE's own POST schema cannot fully describe — a stripe layout has no
+  `raidlevel` to declare. `ZfsRaidLevel` and `ZfsCompression` are now generated aliases of
+  `NodesNodeDisksZfsPostParams`'s fields rather than hand-typed, so PVE adding or removing a
+  `raidlevel` value is caught by `tsc`, not discovered on a live cluster. `createPool` refuses
+  before any POST when an adopt-only declaration's pool is not already there. `zfs-pool.ts`'s
+  header previously said destroy was refused and `delete` made no API call — that was false
+  (`destroyPool` sends a real `DELETE`, guarded only by the resource's default `retain` removal
+  policy); the header is corrected, and `delete` is unchanged.
+
+  Walked down against the manifest-verified `pve-apidoc` cache, pve-manager 9.2.11/f6997e698c7933ea,
+  sha256 `9def8f13611184ee1c7d0399713130dfc4a065701d0d91a69b9c03df929344e9` — re-sliced for this
+  change with `codegen/apidoc.ts`'s own parser (2026-09-23), rather than assumed from the header's
+  2026-09-13 measurement. The four endpoint definitions this change touches (`POST`/`GET`/`DELETE`
+  `/nodes/{node}/disks/zfs[/{name}]`, `GET`/`POST`/`PUT`/`DELETE`
+  `/access/users/{userid}/token/{tokenid}`) are byte-identical against the cached 9.2.4 apidoc, so
+  nothing here is pinned to a version drift between them.
+
+### Patch Changes
+
+- [#152](https://github.com/taslabs-net/homeflare-kit/pull/152) [`0a19365`](https://github.com/taslabs-net/homeflare-kit/commit/0a19365c9370f315e0fa0dba6700934e4a7022fc) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Fix the Proxmox type generator (`codegen/`) to read a property's own `oneOf`, not just its outer `optional`. Measured 2026-09-23 against pve-manager 9.2.11: six PVE SDN fabric request parameters and seven return fields under `/cluster/sdn/fabrics/*` (`delete`, `redistribute`, `interfaces`) are spelled `{oneOf: […], type: 'array'}` with no outer `optional`, one branch per routing protocol, every branch `optional: 1` — a property that is optional in every case the vendor states, which the generator previously read as required. `isOptional` (exported from `codegen/tsmap.ts`) now treats a property as optional when it says so itself or when every `oneOf` branch does (one branch without `optional` still keeps it required), and an array property with no `items` of its own but a `oneOf` gets its element type from the deduplicated union of each branch's own mapped `items`. `codegen/emit.ts`'s constraint-table required flag routes through the same helper, so a future fabric Resource is not refused at plan time for omitting a key the vendor never requires. Regeneration touches only `packages/alchemy/src/proxmox/generated/pve/cluster-sdn-fabrics.ts` (+23/−13); nothing in `packages/` imports its types yet. `codegen/TYPES.md` records what stays unclaimed: the branches' own per-protocol `instance-types` are not read, so the element type is a superset across protocols rather than a discriminated union — that decision belongs to the `SdnFabric`/`SdnFabricNode` family this unblocks.
+
+## 0.22.0
+
+### Minor Changes
+
+- [#148](https://github.com/taslabs-net/homeflare-kit/pull/148) [`2a8fc6e`](https://github.com/taslabs-net/homeflare-kit/commit/2a8fc6ef5f634c52a7dfa59f3f0e3464d83aea7c) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Refuse two of a stack's own launchd jobs sharing one port, before either is declared: `@homeflare/alchemy/launchd` now exports `claimPorts(claims)` and the pure `portClaimProblems(claims)` it runs on. Like `catalogBinary()`, this is a plain function the stack program calls itself (a provider never sees its sibling resources, and never diffs a first create whose props still hold an unresolved `Output` — every mini job's does), so a colliding declaration fails the plan before anything is fetched, written or `launchctl`'d. It keys on the port number alone, mirroring `lib-ports.nix`'s `assertNoCollision` in the house repo, the check it replaces for a job once that job moves off Nix — address and protocol are not part of the key, matched against that registry's own strictness rather than a new, looser rule. Walked against Darwin 27.2.0 (macOS 27.2): a wildcard bind and a specific-address bind on the same port both succeed at the OS level (measured with SO_REUSEADDR, which Go sets on every darwin listener unconditionally), so `claimPorts` refuses that pairing deliberately rather than relying on the OS to catch it. It sees only the claims a stack passes it — a forgotten job, or a daemon still on Nix, stays invisible until its port is added as a claim.
+
+- [#149](https://github.com/taslabs-net/homeflare-kit/pull/149) [`6b8d88f`](https://github.com/taslabs-net/homeflare-kit/commit/6b8d88f9d3b68286f2d83a64358ecb1e84909629) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `@homeflare/alchemy/release` gets its second vendor data set, `OPENBAO_RELEASES`: OpenBao 2.6.2 for darwin_arm64, walked down 2026-09-23 (`docs/release-binary-openbao.md` has every command). OpenBao's `checksums.txt` lists archives and SBOMs only, never the `bao` binary inside the archive — the first vendor the kit has pinned where the member digest is not a vendor fact. `catalog.ts` gains an optional `computed` record per archive for exactly that case (hashed from an archive whose own SHA-256 already matched the pin, filed separately from `members` and never both at once — a member pinned in both is refused) and an optional `checksums.signature` record for a vendor that publishes a detached signature over its checksum file; `catalogProblems`, `catalogBinary` and `identifyBinary` all read vendor digests first, then computed ones. Both fields are optional and `VICTORIA_RELEASES` is unchanged, so nothing that already builds against this package needs to change. The `checksums.txt` signature was checked once with `gpgv` against the key published at openbao.org; the accompanying Sigstore bundle was read but not verified (`cosign` is not installed where this was walked down), and is recorded as an unverified identity rather than a passing check. `docs/release-binary.md`'s "Declaring one" example also gets a real bug fixed: `ReleaseBinary('vmalert')` followed by `LaunchdJob('vmalert')` shares one alchemy@2.0.0-beta.79 FQN, so the second declaration silently returns the first resource instead of registering a job — the example now uses distinct ids and says why.
+
+## 0.21.0
+
+### Minor Changes
+
+- [#138](https://github.com/taslabs-net/homeflare-kit/pull/138) [`ef4108a`](https://github.com/taslabs-net/homeflare-kit/commit/ef4108a54c3700485cedb102833f16da54f02d3e) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Install vendor binaries from pinned release archives: `@homeflare/alchemy/release`. `ReleaseBinary` puts one binary out of a GitHub release archive into a directory the stack declares, and installs nothing else. The pinned archive is its props — repository, tag, exact asset name, size, the archive's SHA-256, the archive member and the member's own SHA-256 — so the resource knows no vendor. Each vendor's pinned versions are data kept beside it; `VICTORIA_RELEASES` is the first set, covering `victoria-metrics`, `victoria-logs`, `victoria-traces` and the `vmutils` tools (`vmagent`, `vmalert`, …) at the versions the Mac host runs, each digest copied from the vendor's checksum file with its URL and date. `catalogBinary(VICTORIA_RELEASES, { package, version, platform, binary })` turns an entry into props, and refuses a version the data set does not pin — in the stack program, so the plan fails before anything is fetched. Every pin must be a plain value in the stack program: one wired from another resource's Output (a checksum file read during the deploy) is refused before any request, on a first deploy too. Every download is checked twice: the archive before anything is unpacked, then the binary before it is written. Asset names are matched exactly, so the `-enterprise` and `-cluster` archives next to them are never picked. Only the declared member is extracted, and an archive holding any link, `..` or absolute entry is refused whole. The bytes reach the host only through the existing `HostRunner` write. A new pin at the same path is refused rather than overwriting a running binary; give each version its own directory (`catalogDirectory`). A binary someone already placed is recognised by its SHA-256, never by running it, and is taken over only under `--adopt`, without a download — at apply too, where the plan could not ask. A file with other bytes at the path is never taken over, `--adopt` or not, so a plan never prints `adopted` for a binary it would overwrite. A renamed declaration keeps its binary: declare the rename with `renamedFrom()`, and under `--adopt` the old name's delete leaves a path the new name installed in the same deploy. It never starts anything: the stack's job puts the binary's `path` in its argv. `HostFile` now shares its whole-file convergence with it, with no change in behaviour.
+
+### Patch Changes
+
+- [#138](https://github.com/taslabs-net/homeflare-kit/pull/138) [`ef4108a`](https://github.com/taslabs-net/homeflare-kit/commit/ef4108a54c3700485cedb102833f16da54f02d3e) Thanks [@taslabs-net](https://github.com/taslabs-net)! - A `HostFile` or `ReleaseBinary` whose path is respelled to the same file — through a symlinked parent such as `/etc` and `/private/etc`, or by case alone on case-insensitive APFS — is now planned as an `update` that keeps the file. Before, it was planned as a `replace` whose cleanup deleted the old path, which was the same file: the deploy succeeded and the file was gone until the next one. `HostRunner.stat` may now report `dev` and `ino` (the local runner does); a runner that does not gets a check after the move, so a lost file fails the deploy instead. A create whose read-back throws (not only one that mismatches) is now removed. `ReleaseBinary` also refuses a mode its owner cannot read, and a directory that group or other may write. It refuses, too, a second resource installing the same path in one deploy: two owners of one file meant that dropping either one deleted the file the other still declared.
+
+## 0.20.0
+
+### Minor Changes
+
+- [#139](https://github.com/taslabs-net/homeflare-kit/pull/139) [`70e8899`](https://github.com/taslabs-net/homeflare-kit/commit/70e8899fe70cf5426bcbf11b498a658b60f9488b) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Export `ProxmoxCephDaemon`, `ProxmoxCephFs` and `ProxmoxCephOsd` from `@homeflare/alchemy/proxmox`, so a stack can adopt a live cluster's Ceph monitors, managers, metadata servers, CephFS and OSDs. Each is adopt-only by shape: none has an update path, the daemon and filesystem compare nothing so they can never plan a replace, and an OSD is created only when `dev` is declared. All three retain on destroy, so removing a declaration drops its state row and never sends a DELETE. `ProxmoxCephFlag` stays Provider-only on purpose: a declared flag reasserts a maintenance toggle such as `noout` on every deploy.
+
+### Patch Changes
+
+- [#135](https://github.com/taslabs-net/homeflare-kit/pull/135) [`925454b`](https://github.com/taslabs-net/homeflare-kit/commit/925454b5d9fbefea061a3a204e4b0093a79c0bdc) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Two ways a `Remote.File` managed region could break its own promise, and a systemd rename that
+  refused too late. All three found by reviewing the merged diff and reproduced against the fake
+  Linux host before anything was changed.
+
+  🔴 **A REGION RENAME LEFT THE OLD BLOCK IN THE FILE FOREVER.** Only `path` was identity, so changing
+  `region.name` — or its `comment` token, which is part of the marker line — planned a routine
+  `update`: the new markers were spliced in, the old ones were never touched, and `delete` could only
+  ever look for the name in state, which was now the new one. Reproduced: a vendor file ended up
+  carrying two `BEGIN` blocks and destroying the resource removed one of them. For the named
+  consumers that is two `anchor` lines in a packet filter and a duplicate entry in a host table, with
+  nothing in the stack able to take either back. A rename is now a MOVE: the new block is written and
+  verified, then the old one is removed, and the stored digest is re-read afterwards so it describes
+  the file that is actually there.
+
+  🔴 **DROPPING `region` TOOK OVER A FILE THIS RESOURCE DID NOT OWN.** Same cause, worse effect: the
+  plan said `update` and the apply replaced every byte of the other owner's file with this resource's
+  few lines. That is the one thing the managed-region design exists to make impossible. A flip between
+  owning the whole file and owning a block — in either direction, at the same path — is now a
+  PLAN-TIME REFUSAL, because neither order is safe: writing the whole file first destroys the other
+  owner's bytes before anything can be undone, and removing the block first destroys our own claim and
+  then refuses. Destroy the resource and declare a new one.
+
+  🔴 **A `Systemd.Unit` RENAME WHOSE `content` WAS STILL AN OUTPUT WAS NOT CHECKED AT ALL.** The
+  resolved rename is checked in the plan since the systemd preflight; the branch `diffHandler` takes
+  while `content` is unresolved — exactly the deploy that templates a rendered config's digest into
+  the unit — still returned `{ action: 'replace', deleteFirst: true }` with no check, and Alchemy
+  deletes the old unit BEFORE reconciling the new one. A rename onto a masked name therefore took the
+  service down and only then refused. The half of the check that needs only the new name — the old
+  unit deletable, the new one writable and not masked — now runs there too. ⛔ This forbids nothing
+  that used to work: the identical refusal was always going to fire in reconcile, just later and with
+  nothing running.
+
+- [#142](https://github.com/taslabs-net/homeflare-kit/pull/142) [`1905f18`](https://github.com/taslabs-net/homeflare-kit/commit/1905f18c30f7ae2a6d7294d588bf18396b64f4ed) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Two new docs, and no code change.
+
+  `docs/provider-standard.md` is the kit-side statement of the house standard for a custom
+  Alchemy provider. It keeps the standard's rule numbers, and each rule is cited upstream at
+  `alchemy@2.0.0-beta.79`. It covers four things. First, use upstream's resource when one
+  exists. Second, route every vendor call through `@distilled.cloud/<vendor>` when that
+  package exists. Third, use Alchemy's own helpers (`alchemy/Util/sha256`, `Util/poll`,
+  `Util/AtomicFile`, `Diff`, `Tags`, `PhysicalName`, `AdoptPolicy`, `Auth` and `Test/Bun`)
+  rather than house copies. Fourth, keep `src/**` provider code runtime-portable, because
+  this package builds with `--target node`, while tests, fakes, scripts and codegen stay
+  Bun-native. The page also records, per family, the vendor version each one was walked
+  against and where that record lives. Six families record it only in prose.
+
+  `docs/upstream-conformance.md` is the audit of every family against that standard, as a
+  ranked ledger. It was measured read-only on `925454b`. The findings, in rank order:

package/docs/changelog/archive-12.md

@@ -0,0 +1,183 @@
+# Alchemy changelog archive 12
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+1. `R2BucketLock` uses `Effect.orDie` and `Effect.promise`. Its reconcile trusts `output`
+   rather than the live lock, and it sits on a second Cloudflare SDK where
+   `@distilled.cloud/cloudflare/r2` already has the lock operations.
+2. `forgejo/client.ts` is hand-rolled, while `@distilled.cloud/forgejo@1.0.0-rc.12` is
+   generated against Forgejo 16.0.3.
+3. `MeshNode` is a deliberate twin of `Cloudflare.Tunnel.WarpConnector`.
+4. Shipped provider code calls `Bun.*` or the `node:*` modules upstream bans (14 of 17
+   listed files; the other 3 use only synchronous `node:crypto` or `Buffer`, which upstream
+   allows inside `Effect.sync`), and 51 test files run on `node:test` instead of
+   `bun:test`.
+
+What the ledger records is the gap for each finding. It changes nothing.
+
+## 0.19.1
+
+### Patch Changes
+
+- [#128](https://github.com/taslabs-net/homeflare-kit/pull/128) [`ba55148`](https://github.com/taslabs-net/homeflare-kit/commit/ba5514820e32f9d546f1a5eb0f92c7f156f2a978) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Estate topology out of the constraint proofs. PR [#118](https://github.com/taslabs-net/homeflare-kit/issues/118)'s create-form proofs used the real
+  declarations verbatim, which put a metrics hostname, a cluster's `api-path-prefix` and three Ceph
+  pool names into `src` — and `src` ships in the npm tarball of a public repository, so they would
+  have stayed in the git history forever. `lxc-harness.ts` states the rule and these tests did not
+  follow it: a production-SHAPED declaration with placeholder values, because the proof is about
+  which keys the create form sends and which bounds they face, never about the strings.
+
+  No behaviour changes; the same forms are checked against the same tables.
+
+- [#136](https://github.com/taslabs-net/homeflare-kit/pull/136) [`64d4c36`](https://github.com/taslabs-net/homeflare-kit/commit/64d4c36091054fa05b716f1d4029c1feea955289) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Check a systemd rename at plan time. A unit's name or directory change is a delete-first replace, and Alchemy deletes the old unit before reconciling the new one, so a masked name, a unit file someone else owns, or a runner that will not write the new path used to be noticed only after the old unit was already stopped. Those checks now run while planning, and again at apply when the new name was still an Output and the diff could not see the rename. A file byte-identical to this declaration's render stays exempt: it is a deploy that died between write and reload.
+
+## 0.19.0
+
+### Minor Changes
+
+- [#120](https://github.com/taslabs-net/homeflare-kit/pull/120) [`512bf1a`](https://github.com/taslabs-net/homeflare-kit/commit/512bf1a6a973bdbd1c9688d295dcf8a067820a36) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Linux hosts on the existing HostRunner seam: `@homeflare/alchemy/linux`.
+
+  The kit could declare a guest and nothing inside it. This adds the families that gap
+  was missing, on the same seam the launchd subpath already drives a Mac through — so
+  `HostFile`'s ownership rules, `checkWrite` and the adoption doctrine come along unchanged.
+
+  - `sshRunner({ host })` — a Linux `HostRunner` over the operator's own ssh config.
+    ⛔ `BatchMode=yes` and host verification untouched; ⛔ every remote script reports its
+    status behind a per-runner nonce, so a dropped connection is an Error and never a
+    "nothing is there"; ⛔ `privileged: false` — nothing calls sudo.
+  - `HostDirectory` — because no file resource creates a parent. One directory, never a
+    chain; delete is `rmdir`, never recursive.
+  - `RemoteFile` — a whole file, or one MANAGED REGION (`BEGIN`/`END` markers) inside a
+    file this resource does not own. ⛔ Every byte outside the markers stays identical, the
+    file's own mode and owner are copied back, and a delete removes only the block.
+  - `SystemdUnit` / `SystemdTimer` — unit file, `daemon-reload`, enable/disable,
+    start/stop. ⛔ A deploy NEVER mass-restarts: a unit restarts only when its own file
+    changed, when state or systemd says the loaded copy is stale, or when a digest the
+    declaration listed in `restartOn` changed. An adopted unit that already matches is not
+    restarted, reloaded or started.
+
+  `systemctl` and `stat` shapes measured read-only on Debian 13 / systemd 257, 2026-09-22;
+  the write subcommands are reasoned and read back rather than assumed. Unit files render
+  verbatim — there is no machine-readable directive schema to generate from, so the kit
+  invents none. Guide: `docs/linux-host.md`.
+
+## 0.18.0
+
+### Minor Changes
+
+- [#118](https://github.com/taslabs-net/homeflare-kit/pull/118) [`5ae4e91`](https://github.com/taslabs-net/homeflare-kit/commit/5ae4e91919a101da3d8605a069c65e0301d0cccc) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Every Proxmox family that writes to the vendor is now checked against the vendor's own schema —
+  35 of 35, up from 19, covering 75 endpoints instead of 37. A family left unwired was a write this
+  package made with nothing between the declaration and the server's 400, which is the shape of the
+  2026-09-22 `deploy:pbs` incident this feature exists for.
+
+  Newly wired: `Proxmox.ApiToken`, `CephDaemon`, `CephFlag`, `CephFs`, `CephOsd`, `CephPool`, `Lxc`,
+  `MetricServer`, `NetworkApply`, `NodeNetwork`, `NotificationTarget`, `SdnApply`, `SdnSubnet`, `Vm`,
+  `ZfsPool`, and `Pbs.NotificationTarget` — which was missing from the sweep list and carries the
+  incident's own rule, `comment: maxLength 128`, on all three of its creates. Families that write
+  their own handlers (`CephOsd`, `Lxc`, the two applies, `Pbs.NotificationTarget`) reach the same
+  check by name through `guardForm`, as `Pbs.Datastore` already did; families with a spec declare
+  `endpoint`. `tests/constraint-wiring.test.ts` derives the census from the ownership ledger, so a
+  family added without an endpoint fails there rather than on a deploy, and each newly wired family
+  has a proof test that runs its REAL create form through the vendor's create table and requires no
+  violations.
+
+  🔴 **A live bug this found.** `Proxmox.NodeNetwork`'s create form never sent `iface`, which PVE
+  marks required on `POST /nodes/{node}/network` while `{node}` is its only path parameter. Every
+  interface create this package could have made would have 400ed; nothing caught it because the
+  estate's interfaces were all adopted, which takes the PUT path. `createBody` now sends it, and the
+  PUT still does not — there `iface` is the path.
+
+  ⛔ **Presence of a vendor-required parameter is now demanded only when a create is really about to
+  happen**, not whenever the create form is built. `Proxmox.NotificationTarget` cannot send gotify's
+  `token` or smtp's `password` — they are write-only secrets and props are persisted unencrypted — so
+  the documented workflow is to create the target out of band and then declare it. Under the old
+  unconditional check that adopt-then-update would have been refused forever; now it plans clean,
+  while asking to CREATE a gotify target fails at plan with PVE's own `token: required`. The guards
+  move into `resource-guard.ts` and are exported from `pveOperations`, so `CephPool`'s hand-written
+  reconcile gets them too.
+
+  An **action** endpoint with no form is wired as well (`PUT /cluster/sdn`, `PUT /nodes/{node}/network`):
+  the table is empty, but the key is resolved against the vendor schema at generation time, so a PVE
+  that moves or withdraws an apply fails `bun run check` instead of an `ifreload -a` on three nodes.
+
+  `PveSpec['endpoint']` now also admits a function of props, for the two families whose endpoint is
+  chosen by a prop — `NotificationTarget`'s four PVE types and `CephDaemon`'s mds/mgr/mon, each with
+  its own parameter schema. Every key it can return is still a literal in this package's source,
+  because the generator finds endpoints by scanning text.
+
+  Generator changes that came with the volume: `/cluster` and `/nodes/{node}` are split one level
+  further down, because they are routes rather than areas — PVE's own viewer expands them — so the
+  tables are now 18 files (`pve-cluster-sdn.ts`, `pve-nodes-ceph.ts`, …), all inside the 250-line
+  house cap. The generator deletes a file it no longer produces, `tests/schema-manifest.test.ts`
+  enumerates the directory instead of a hand-written list and checks every table is claimed by the
+  manifest entry it came from, and two PVE bounds published as JSON strings (`bwlimit`'s
+  `minimum: "0"`, `count`'s `maximum: "16777216"`) are parsed to numbers — a faithful reading of a
+  stated value; a bound that is not a number at all is still dropped rather than guessed at.
+
+## 0.17.0
+
+### Minor Changes
+
+- [#114](https://github.com/taslabs-net/homeflare-kit/pull/114) [`3316006`](https://github.com/taslabs-net/homeflare-kit/commit/3316006513196622551d4cc041986089dc28ffc4) Thanks [@taslabs-net](https://github.com/taslabs-net)! - The Proxmox API type generator, written from the vendor schemas, and the widening it removes.
+  `packages/alchemy/src/proxmox/generated/{pve,pbs}.ts` carried the header
+  `Run: bun codegen/generate.ts` from the day they were committed, and
+  `git log --oneline --all -- 'codegen/generate*'` is empty at every commit: that file existed
+  nowhere. The mapping was therefore readable only as its own 8,196 lines of output — nobody could
+  reproduce it, correct it, or say which schema version it described. Because nobody could read it,
+  nobody noticed what it did: it kept `type`, `enum` and `optional`, dropped every `maxLength`,
+  `minLength`, `minimum`, `maximum`, `pattern`, `format`, `typetext`, `default` and description, and
+  covered 407 of PVE's 678 endpoints and 46 of PBS's 367 with no record of which 407 or why.
+
+  `bun codegen/types.ts` is that generator, with `--check`, the same manifest and the same
+  sha256-as-identity rule as `codegen/constraints.ts`. It emits every endpoint both products
+  document — 678 PVE and 367 PBS, 1,619 exported types — split across 89 files by the vendor's own
+  path and packed back up so the split is no deeper than the 250-line house cap requires. Every file
+  names its manifest entry, the product version the host reported and the sha256 of the bytes it was
+  read from. `generated/pve.ts` and `generated/pbs.ts` stay as `export *` barrels, so no import in
+  this package or any consumer moves.
+
+  ⛔ **An integer request parameter is `` `${number}` ``, not `string`.** `pbs:POST /config/verify`'s
+  `max-depth` is `integer, minimum 0, maximum 7` in PBS's schema and was `'max-depth'?: string` in
+  the type, which accepts `'banana'`; 480 PVE and 151 PBS parameters were widened that way. They are
+  now the wire spelling of a number: still assignable to `PveForm`, still carried unchanged through
+  `violations`' bound check, and no longer satisfied by an arbitrary string. It is deliberately NOT
+  `number`: `client.ts` sends `application/x-www-form-urlencoded` and types the body
+  `Record<string, readonly string[] | string>`, so a `number` could not be handed to `pve()` at all,
+  and `constraints.ts` iterates a form value on `typeof value === 'string'`. ⚠️ `String(n)` does not
+  typecheck against it — write `` `${n}` ``. A boolean parameter stays `'0' | '1'`, which is the
+  encoding `values.ts`'s `flag()` already produces rather than a widening. Responses are JSON and
+  keep their real `number` and `boolean | 0 | 1`.
+
+  The old output is reproduced before it is changed, which is what makes the diff reviewable: run
+  against the same two schemas with integers left widened, the pipeline re-emits all 646 PVE and 69
+  PBS declarations identically, with two recorded exceptions — `NodesNodeLxcVmidConfigGetReturn`'s
+  `lxc` becomes `readonly (readonly string[])[]` rather than a readonly array of mutable ones, and 21
+  declarations break lines differently because `oxfmt` had reformatted the committed files before
+  every `generated` directory reached its ignore list. The naming is the old generator's, reproduced
+  rather than improved: `ClusterBackupIdIncluded_volumesGetReturn` keeps its underscore, because
+  renaming sixty exported types in the commit that changes what the types mean would hide the second
+  change inside the first.
+
+  ⛔ Parameter schemas wrapped in `allOf`/`oneOf` are read through `codegen/parameters.ts` (PR [#113](https://github.com/taslabs-net/homeflare-kit/issues/113)),
+  not asked for as `parameters.properties`. `POST /cluster/ha/rules` and `PUT /cluster/ha/rules/{rule}`
+  are the two PVE endpoints that need it; a reader that misses them emits a type with no fields, which
+  is indistinguishable from an endpoint that takes nothing. An unresolvable schema gets a doc comment
+  naming the construct and **no** `Params` type — neither product needs that on these versions.
+
+  ⛔ "Closed object" is spelled differently by the two products, and a test for one lies about the
+  other. Measured over both whole schemas: PVE writes numbers (`additionalProperties: 0` on 617
+  objects, `1` on 21, absent on 352), PBS writes booleans (`false` on 560, `true` on 36). An absent
+  `additionalProperties` is open — the vendor never promised the list was exhaustive.
+
+  ⛔ Eight PVE files are over the house cap and cannot be split. Each holds the endpoints of one
+  vendor path whose parameters carry enums of hundreds of members — `rootfs`, `mp0`…`mp255`,
+  `unused0`…`unused255` for the volume moves, the ACME DNS provider list, the QEMU CPU model list. A
+  single type declaration is the smallest unit there is; dropping the enum would widen the parameter
+  back to `string`. Each says so in its own header and `tests/schema-types.test.ts` pins the list.
+
+  `tests/schema-type-mapping.test.ts` holds the mapping to shapes lifted from the committed files and
+  needs no schema cache, so it runs on CI. `tests/schema-types.test.ts` checks provenance, the
+  barrel against the files on disk, the cap, the coverage counts and five endpoints the old generator
+  omitted, and runs `bun codegen/types.ts --check` when the cache is present — skipping with the
+  refresh command when it is not. `codegen/TYPES.md` carries the reasoning.
+
+## 0.16.1

package/docs/changelog/archive-13.md

@@ -0,0 +1,180 @@
+# Alchemy changelog archive 13
+
+[Current changelog](../../CHANGELOG.md) · [Archive index](./README.md)
+
+### Patch Changes
+
+- [#113](https://github.com/taslabs-net/homeflare-kit/pull/113) [`4fe8cef`](https://github.com/taslabs-net/homeflare-kit/commit/4fe8cef3154ad0f373b291f413dcbd570602e6fa) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `Proxmox.HaRule`'s constraint table was empty and nothing said so.
+
+  MEASURED 2026-09-22: PVE spells `POST /cluster/ha/rules` as `parameters: {allOf: [{properties:
+{rule}}, {oneOf: [node-affinity, resource-affinity]}]}` — a discriminated union. The apidoc reader
+  asked for `parameters.properties`, got `undefined`, and emitted `{}`. A wired family's plan-time
+  guard therefore checked **nothing**, and an empty table is indistinguishable from an endpoint whose
+  parameters happen to carry no rules. `comment` there has a `maxLength` of 4096 and `affinity` an
+  enum of two.
+
+  `codegen/parameters.ts` reads both combinators, and their logic is their meaning. `allOf` branches
+  all apply, so their properties MERGE — a key claimed by two branches would have to satisfy both,
+  which this does not compute, so it stops rather than picking one. `oneOf` branches are
+  ALTERNATIVES, so they INTERSECT: only what every branch states identically survives, because
+  enforcing a rule from one branch would refuse a legal declaration of the other kind. `nodes` and
+  `strict` exist only on node-affinity and are therefore not enforced. ⚠️ `optional` is intersected
+  toward optional rather than field-by-field: its ABSENCE means required, so dropping a disagreeing
+  `optional` would have read as required and refused every legal node-affinity rule, whose `affinity`
+  is optional where resource-affinity's is not.
+
+  ⛔ And a parameter schema this file cannot read is now recorded as `unresolved` and **stops the
+  generator** for any endpoint this package writes to, rather than producing the empty table that hid
+  the problem. `tests/schema-manifest.test.ts` covers the reader directly.
+
+  ⛔ `docs/api-coverage.*` had the identical blind spot from its own parser: it reported
+  `/cluster/ha/rules` as having **zero** parameters and zero gaps. `scripts/api-schema.ts` now reads
+  the combinators through the same resolver — 5 parameters, 2 unenforced, both `format` names.
+  ⚠️ Two parsers for one file format is the deeper defect; merging them is its own change.
+
+- [#116](https://github.com/taslabs-net/homeflare-kit/pull/116) [`54479fc`](https://github.com/taslabs-net/homeflare-kit/commit/54479fc7792076fb0e718b55588cc815823818c2) Thanks [@taslabs-net](https://github.com/taslabs-net)! - `Netbox.Prefix` no longer erases prose it did not declare.
+
+  🔴 **The bug, found by review rather than by an incident.** The resource sent `description: ''`
+  whenever the prop was absent. On a create that is invisible — the field was empty anyway. ⛔ On an
+  **adopt** it is data loss: NetBox is the estate's record of DECISIONS, so a prefix's description is
+  usually the only written trace of why that range exists. The first deploy that adopted one would
+  have PATCHed it to empty, `matches` would have reported drift, the plan would have said `update`,
+  and the diff would have read as converging a declaration rather than deleting a sentence.
+
+  ★ **The tell was an inconsistency inside the same file, not a failure.** Optional foreign keys were
+  already omitted when undeclared, with a comment explaining that sending `null` would clear a tenant
+  somebody set in the UI. Free text had the identical hazard and the opposite treatment. Two fields,
+  one hazard, two answers — that gap is the defect.
+
+  ★ **The line is now drawn at what the vendor itself defaults.** `status`, `is_pool` and
+  `mark_utilized` have defaults in NetBox's schema, so omitting one genuinely means "the default" and
+  settling it says what NetBox would have done anyway. `description`, `comments` and the optional
+  foreign keys have no such default — the schema's `''` is the absence of a value, not a decision —
+  so they are omitted from the body and left uncompared until declared.
+
+  ⛔ **Whatever `matches` compares, `body` must send**, or the plan says `update` forever: the PATCH
+  omits the field, so the next read is unchanged. The two moved together here and
+  `prefix-form.test.ts` asserts the invariant.
+
+  ⚠️ **The cost, stated:** prose can no longer be cleared by omission. Clearing it is
+  `description: ''`, written on purpose — the readable way to say a destructive thing.
+
+  `body` and `matches` are extracted to `prefix-form.ts` so both are pure functions a test can call
+  with a literal, the way the Proxmox families keep their `*-form.ts` beside the resource.
+
+## 0.16.0
+
+### Minor Changes
+
+- [#110](https://github.com/taslabs-net/homeflare-kit/pull/110) [`9fa5800`](https://github.com/taslabs-net/homeflare-kit/commit/9fa5800c8a1d2d3fb831d29ae64e9145e82fe48f) Thanks [@taslabs-net](https://github.com/taslabs-net)! - A NetBox provider, generated from NetBox's own OpenAPI document — `@homeflare/alchemy/netbox`.
+
+  `Netbox.Prefix` declares one IP prefix and the decision recorded against it. It is the first object
+  class for three measurable reasons: `WritablePrefixRequest.required` is exactly `["prefix"]`, so it
+  is the only interesting NetBox object with **no foreign-key prerequisite** (a VLAN needs `vid` and
+  a group; a Device needs a role, a type and a site — four more Resources before the first one can be
+  declared); a prefix is the atom of what NetBox is for, the record of what the network was DECIDED
+  to be; and `status: 'deprecated'` is how a retired range stops being folklore in an SSH config
+  comment and becomes a line with a reviewable diff.
+
+  ⛔ **The constraint tables are generated, never hand-typed.** `bun codegen/netbox.ts` reads NetBox
+  4.7.0's OpenAPI 3.0.3 document, verifies its sha256 against `codegen/manifest.json`, and emits the
+  committed tables plus `docs/netbox-coverage.md`. A key naming an endpoint the vendor does not have
+  stops the generator. This is the same pipeline that exists because a PBS deploy adopted ten objects
+  and then failed its one create on a `maxLength: 128` the generated type did not carry — NetBox gets
+  it **before** its first write rather than after.
+
+  ⛔ **Two of NetBox's seven regexes are not JavaScript in meaning, and both compile cleanly.**
+  Measured over the whole document: `^[-\w]+$` (`slug`) and `^[\w.@+-]+$` (`username`). Python's `\w`
+  is Unicode on a `str`, so Django accepts `zürich-core` and a verbatim JavaScript copy refuses it —
+  a plan blaming the operator for a legal value, which is worse than the server-side 400 the table
+  replaces. ⚠️ The `u` flag does not fix it. Both are dropped, recorded as `patternSource` with no
+  `pattern`, and the generated header says nothing enforces them.
+
+  ⚠️ **The document was pinned to the vendor's release tag, not read from an instance, and the
+  manifest says why.** The reference instance could not answer `/api/schema/`. The published document
+  was then cross-checked against a snapshot the estate took from its own instance while it was up:
+  1256 operations on each side, `(method, path)` sets identical with zero difference. ⛔ That verifies
+  the path surface only — the snapshot discards request bodies, which is the half this generates —
+  so every constraint rests on the vendor document alone.
+
+  Also here:
+
+  - Adopt-first by construction: `reconcile` locates before it writes, and ⛔ an ambiguous identity
+    **fails** rather than binding to whichever row NetBox ordered first.
+  - 🔴 **One guessed filter shape was caught before it shipped, and the fix is structural.** The
+    prefix locate first narrowed server-side with `vrf_id=null`, the sentinel NetBox uses for "no
+    foreign key" — `FILTERS_NULL_CHOICE_VALUE = 'null'` is real. ⛔ But in the vendor's own source
+    at v4.7.0, `PrefixFilterSet.vrf_id` is a plain `ModelMultipleChoiceFilter` with no `null_value`:
+    it never opted in, so `'null'` fails queryset validation and NetBox answers **400 on every plan
+    for every global-table prefix**. `locate` now sends only filters the document declares and a new
+    `identifies` picks the row in this process, where the rule is readable and testable offline.
+  - `retain` on removal for every family, because deleting a NetBox row reparents children and
+    detaches IP assignments; the `delete` handler is fully implemented anyway.
+  - Read/write shape asymmetry handled in `values.ts` — `status` is written as `"active"` and read
+    back as `{value, label}`; a foreign key is written as `4` and read back as `{id, url, display}`.
+    Comparing those directly reports drift on every plan, forever.
+  - ⛔ No credential is ever a prop. `NETBOX_URL` and `NETBOX_TOKEN` are read at call time, and
+    `Authorization: Token`, not `Bearer` — a wrong scheme and a wrong credential look identical in
+    the response.
+  - ★ **`codegen/param-rules.ts` gains a dialect table, and `emit.ts` is untouched.** There are
+    exactly two vendor facts about a pattern — which dialect it is written in, and whether the
+    vendor anchors it — so they live together per product rather than as a string every function
+    switches on. ⛔ NetBox gets the Django translator and no anchoring: its own 7 patterns already
+    carry `^…$` and Django validates with `re.search`, so re-anchoring would invent a rule. PVE is
+    the opposite case and keeps its measured anchoring. Every existing Proxmox table regenerates
+    byte-identical.
+
+### Patch Changes
+
+- [#108](https://github.com/taslabs-net/homeflare-kit/pull/108) [`6586b0d`](https://github.com/taslabs-net/homeflare-kit/commit/6586b0decb5201e57f9e086619d1f658e5bce94d) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Adversarial review of the vendor-constraint guard, same day it shipped: two rule kinds were passing
+  through it unchecked, and the coverage report did not know the guard existed.
+
+  ⛔ **PVE anchors every pattern and the tables did not.** MEASURED read-only on a cluster node,
+  `/usr/share/perl5/PVE/JSONSchema.pm:1636`: `if ($value !~ m/^$pattern$/)`. The published pattern is
+  the INSIDE of an anchored match — PVE ships `[A-Za-z][A-Za-z0-9\-\_]+` for a firewall alias name —
+  and `RegExp.test` is a search, so `ok name!` matched on its `ok`, planned clean and was rejected by
+  PVE with the 400 the guard exists to prevent. All eleven PVE patterns in the tables were toothless
+  this way. The anchoring is textual rather than `(?:…)`, because Perl's is: three of PVE's 72
+  patterns carry a top-level `|`, and `^a|b$` is not `^(?:a|b)$`. `\n?` before the `$` is Perl's `$`,
+  which matches before a final newline where JavaScript's does not — without it the guard would refuse
+  values PVE accepts, which is worse than the 400. PBS is untouched: all 37 of its patterns already
+  carry their own `^…$` and Rust's `is_match` is a search.
+
+  ⛔ **An array states its rules on `items`, and the emitter read only the parameter.** 30 tabled
+  parameters are arrays and 11 state real limits one level down — PBS `target` (2–32 chars, a name
+  pattern), `associated-key`, the `delete` enums, PVE `secondary-controllers` (max 64). `violations`
+  was already checking every element of a repeated key against a row that had no rules in it. Those
+  rules now merge into the row, which says `each: true`; `required` is never taken from `items`.
+
+  ⛔ **`patternFlags` is emitted instead of discarded.** `translatePattern` lifts PBS's leading `(?m)`
+  to a flag and the first generation returned it and threw it away, so a multi-line rule would have
+  been enforced with single-line semantics. No tabled endpoint uses one today; this is the guard for
+  the day one does.
+
+  ⛔ **`docs/api-coverage.md` called the 128-character comment unenforced.** It was generated from the
+  vendor schema alone, hours after the tables started enforcing 321 rows of it, so the gap column
+  counted every rule the guard had just closed — including the one the report opens by describing.
+  `POST /config/verify` now reads `unenforced: []`, PBS's owned gap falls 144 → 62 and PVE's 545 →
+  490, and a `format` is still never subtracted because the tables record the name and check nothing.
+
+  ⛔ **The two manifests named two different PVE schemas.** `codegen/manifest.json` said 9.2.11 and
+  `schemas/manifest.json` said 9.2.4 — both true of this genuinely mixed-version cluster, differing by
+  two write endpoints, and nothing said so. Both now name the same bytes and the same versioned cache
+  filename, and `tests/schema-manifest.test.ts` fails if they ever diverge again.
+
+  New tests: `constraints-dialect.test.ts` holds a mutant for each newly enforced kind, and
+  `constraints-live.test.ts` runs all ten objects of the live PBS inventory — the real ids, stores,
+  schedules and retention values, comment text replaced by same-length filler because this package is
+  public — through their create AND update tables expecting zero violations, which is the false
+  positive this feature could itself cause. `constraints.test.ts` is split at the 250-line house cap.
+
+## 0.15.0
+
+### Minor Changes
+
+- [#106](https://github.com/taslabs-net/homeflare-kit/pull/106) [`fc026e7`](https://github.com/taslabs-net/homeflare-kit/commit/fc026e7b81d937f614515abe8b2a2d7bb2a2d019) Thanks [@taslabs-net](https://github.com/taslabs-net)! - Forward every `Bao.*` family's `Props` and `Attributes` types from `@homeflare/alchemy/openbao`.
+
+  Each family already re-exported its own types from its module, but the barrel forwarded only the
+  VALUES for seven of them — `BaoAuthMethod`, `BaoCloudflareRole`, `BaoMount`, `BaoPkiRole`,
+  `BaoPolicy`, `BaoProxmoxRole` and `BaoSshRole` — plus `BaoAuthRoleAttributes`,
+  `BaoPluginAttributes`, `BaoJwtRoleAttributes` and `BaoJwtCallbackMode`.