@homeflare/alchemy 0.36.0 → 0.37.1

package/docs/upstream-conformance.md

@@ -1,10 +1,11 @@
 # Upstream conformance, family by family
 
-Status: open ledger. Verified 2026-09-22 by reading `origin/main` `925454b` against
+Status: open ledger. Original audit: 2026-09-22, reading `origin/main` `925454b` against
 [provider-standard.md](./provider-standard.md) (`alchemy@2.0.0-beta.79`). Nothing in any
 family was changed by this audit. Each row names the rule it breaks and the upstream
 replacement or fix. A row is crossed off in the PR that fixes it, with that PR's evidence.
-A decision marked **maintainer** is not an agent's to make.
+A decision marked **maintainer** is not an agent's to make. S20/S21 and decision-49
+corrections below were checked on 2026-09-24; this is not a fresh audit of every row.
 
 ## Ranked findings
 
@@ -22,12 +23,12 @@ then tidiness.
    `reconcileLock`/`deleteLock` (S19): distilled's operations are already Effects, so there
    is nothing left to promise-wrap.
 
-   Still open, and out of scope for that task (props/attributes were required to stay
-   byte-identical, so neither touches the wire contract):
-   - `readLock`, and now `reconcileLock`/`deleteLock` too, end in `Effect.orDie` for the
-     error channel distilled leaves after `NoSuchBucket` (S20). A full fix means a typed
-     refusal error for `InvalidRoute`/`CloudflareRateLimited`/`CloudflareError`, which is a
-     separate, larger change than the transport swap.
+   ✅ **S20 and idempotent delete fixed 2026-09-24:** [kit PR #266](https://github.com/taslabs-net/homeflare-kit/pull/266)
+   removes lifecycle `Effect.orDie`, propagates distilled's typed SDK tags unchanged, and
+   folds `NoSuchBucket` to success on delete. This follows beta.79's `R2/BucketSippy.ts`;
+   no blanket refusal remap is needed. The existing read already folds that tag to absence.
+
+   Still open (outside that error-handling change):
    - `reconcileLock` still skips the PUT whenever `output.rules` equals the declaration,
      without reading the live lock (S10). Neither `--force` nor `drift --repair` can
      restore lock rules removed out of band. ⚠️ Reasoned from the source, not measured live.
@@ -139,7 +140,7 @@ then tidiness.
 6. **`openbao/*` has no upstream equivalent, and it conforms on the contract** (Effect
    `HttpClient`, strict `Unowned`, retain). It diverges in three ways:
    - 30 `Effect.die` sites in non-test source, several of them on `diff` and
-     `reconcile` paths (S20);
+     `reconcile` paths (defect risk; S20 no longer separately bans `Effect.die`);
    - 42 test files on `node:test` (S43);
    - `Bao.*` type strings, where the vendor name is `OpenBao` (H14).
 
@@ -147,300 +148,21 @@ then tidiness.
    distilled's shape is the S23 path. **Decision:** maintainer, on whether the kit authors
    a distilled package.
 
-7. **`proxmox/*` is the model for S38.** Its types and constraints are generated from the
-   vendor schema, and a manifest records the version and sha256. It diverges in four ways:
-   - the generic factory's `read` returns plain attributes, so every family except `Lxc`
-     adopts silently, against the house's own H1;
-   - 27 `Effect.die` sites in non-test source (S20);
-   - 7 test files on `node:test`;
-   - `Pbs.*` type strings (H14).
-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
-   kubeconfig it writes is meant to be consumed through upstream's
-   `Kubernetes.KubeConfig({ path })`.
-9. **`netbox/*` conforms mostly.** Its constraints are generated from NetBox 4.7.0's
-   OpenAPI. Adopting first is documented as deliberate.
-   - ✅ **S23 fixed 2026-09-23** (branch `claude2/distilled-netbox-family`, mirroring the
-     Forgejo migration above, decision 42). `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 entirely — `Netbox.Prefix` locates by a server-side list filter,
-     which never 404s (an empty page is a normal 200), so nothing here checks a status
-     code at all, a stronger form of the same rule `catchTag('NotFound', …)` enforces for
-     a family that reads by direct key. `client.ts` is deleted. Not published upstream
-     yet, so aliased onto `@homeflare/distilled-netbox@0.2.0` as a plain `dependencies`
-     entry, not a peer — [distilled-interim.md](./distilled-interim.md). State did not
-     move: props/attributes stay byte-identical, proven by the family's unchanged
-     existing tests plus new tests against a fake NetBox exercising the real distilled
-     protocol.
-   - ⛔ **Still diverges on credentials (S24):** `NETBOX_TOKEN` / `NETBOX_URL` are read at
-     call time, now through the SDK's `CredentialsFromEnv` rather than a hand-rolled
-     `token()` — same divergence, unchanged by the transport swap.
-10. **`litellm/*` has no upstream equivalent** (LiteLLM has no upstream Alchemy family, the
-    same situation `openbao/*` is in above), and conforms on the transport contract.
-    - ✅ **S23 fixed 2026-09-24** (branch `claude2/litellm-distilled`, mirroring the NetBox
-      migration above, decision 43). `LiteLLM.PassThroughEndpoint` now calls
-      `@distilled.cloud/litellm`'s typed `misc` operations (`operations.ts`) instead of a
-      hand-rolled `Effect HttpClient` client. The old status-carrying `LitellmBadRequestError`
-      family is gone: every failure the four operations declare (`BadRequest`, `NotFound` on
-      update, `UnprocessableEntity`, plus the shared `Unauthorized`/`TooManyRequests`/server
-      errors) is the SDK's own typed error, `catchTag`'d — `deletePassThroughEndpoint`'s
-      re-list-on-ambiguous-`BadRequest` trick (S21: a status-and-a-real-read decision, never
-      body text) is unchanged, now keyed on the tag instead of the status code. The
-      per-base-URL write semaphore this vendor's whole-list storage forces (docs/litellm.md)
-      is unchanged too — the SDK has no opinion on it, so it stays one layer above the typed
-      calls, in `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 — see
-      `codegen/manifest.json`'s `litellm-openapi` entry, left in place and unconsumed rather
-      than deleted, the same pattern the two UniFi entries already establish). Not published
-      upstream yet, so aliased onto `@homeflare/distilled-litellm@0.2.0` as a plain
-      `dependencies` entry, not a peer — [distilled-interim.md](./distilled-interim.md). State
-      did not move: props/attributes stay byte-identical, proven by the family's unchanged
-      existing tests (now against a fake LiteLLM exercising the real distilled protocol
-      through `FetchHttpClient.Fetch`, not a loopback `Bun.serve`) plus the engine-level
-      replace test through `fake-stack.ts`. No stack in this estate currently imports
-      `litellmProviders`/`LiteLLM.PassThroughEndpoint` (measured 2026-09-24 across
-      homeflare-landscape's own repositories, including this one's `stacks/`), so there is no
-      live plan to re-run.
-    - ⛔ **Still diverges on credentials (S24):** `LITELLM_PROXY_URL` / `LITELLM_PROXY_API_KEY`
-      are read at call time, now through the SDK's `CredentialsFromEnv` rather than a
-      hand-rolled `resolveCreds` — same divergence, unchanged by the transport swap.
-    - ✅ **S20 fixed 2026-09-24** (same branch, PR review pass): `CredentialsFromEnv` ended in
-      `Effect.orDie`, so a missing/misspelled env var died as an engine-crashing defect
-      instead of the typed `ConfigError` `LitellmOpError` already declared — a regression
-      this migration made newly reachable (the retired hand-rolled `credentials.ts` failed
-      typed). Fixed at the source: `@distilled.cloud/litellm`'s own `credentials.ts`
-      (`homeflare/litellm@4ad19154`, commit local, not pushed — S22), copied forward here.
-      `netbox/*`'s `CredentialsFromEnv` has the identical `orDie` shape and is unfixed —
-      out of scope for this item; tracked as its own follow-up (task `task_3bbe1684`).
-11. **Every family repeats `list: () => Effect.succeed([])`**, 30 times, and only
-    `R2BucketLock` and `MeshNode` declare `nuke`. The constructor already defaults `list`
-    (S12). **Fix:** write the reason where it differs, and declare `nuke: { skip: true }`
-    where nuke must never reach the object.
-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.
-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
-    typed operations, `catchTag`'d through the shared `DiscordOpError` union (S21), with no
-    status sniffing anywhere in `resource.ts`. It follows upstream's `Snippet.ts` reference
-    exactly for a marker-less API (S7, S8): a cold `read` returns `Unowned(attrs)`, and both
-    convenience constructors pipe `adopt(true)` (H5) — a stricter posture than `netbox/*`'s
-    documented H1 gap, not a repeat of it. Rate-limit handling is the SDK's own default
-    `Retry` policy (bounded: `Schedule.recurs(8)`, S26) — this family adds nothing on top.
-    Full detail, the live Halibut census and its ownership-handover sequence, and every SDK
-    gap: [`discord.md`](./discord.md). ⛔ **Diverges on S24/S25 the same way every distilled
-    family in this ledger does:** credentials are read at call time through the SDK's own
-    `CredentialsFromEnv`, not a house `alchemy/Auth` provider — unchanged from `netbox/*`
-    and `litellm/*`'s entries above. **Gap, not yet fixed:** no vendor constraint table
-    (unlike NetBox/Paperless); `options` passed through opaquely rather than modeled from
-    the schema (`docs/discord.md#sdk-gaps`).
-
-15. **`grafana/*` (added 2026-09-24) ships only `Datasource` — a real SDK gap, not scope-trimming.**
-    Measured against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball's
-    `lib/services/grafana.d.ts` (4,938 lines): the package has no create/read/update/delete
-    operations for folders (only `updateFolderPermissions` exists), plain dashboards (only
-    snapshot/public-dashboard routes exist — no `POST /dashboards/db`, no
-    `GET/DELETE /dashboards/uid/{uid}`), alert rules or contact points (both have only a
-    `routeGet*Export` read-only route under `/v1/provisioning/`, no create/update/delete). S1
-    found no upstream `Alchemy` family for any of these either. Full detail:
-    [grafana.md](./grafana.md#the-sdk-gap--why-only-datasource-ships).
-
-    ✅ **S22 fixed 2026-09-24** (branch `claude2/distilled-grafana`): root cause measured to be
-    `skipDeprecated: true` dropping 64 operations Grafana's own spec marks `deprecated: true` in
-    favor of a separate, undocumented-here Kubernetes-apiserver route — not a spec omission. RFC-6902
-    patches un-deprecate exactly the 32 operations this finding named (folders, dashboards,
-    alerting-provisioning writes); the other 32 stay excluded. Shipped as
-    `@homeflare/distilled-grafana` (0.1.0 pre-release, 0.2.0 once this PR's `minor` changeset
-    releases it), aliased onto `@distilled.cloud/grafana` the same S22 route
-    `@homeflare/distilled-netbox` established. `Grafana.Datasource`'s props/attributes/generated code
-    are unchanged (diffed operation-by-operation against the prior commit).
-
-    ✅ **`Grafana.Folder`/`Grafana.Dashboard` shipped** (PR 245, on top of the same
-    `@distilled.cloud/grafana` operations S22 unblocked) — the uid-required doctrine, the
-    provisioned-object refusal, the parentUid-is-create-only refusal and the volatile-field
-    normalization that makes an unchanged dashboard a true noop are all in
-    [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
-
-    ✅ **`Grafana.ContactPoint`/`Grafana.MuteTiming`/`Grafana.MessageTemplate` shipped** (kit PR
-    250, first of three stacked PRs — `Grafana.AlertRuleGroup` then `Grafana.NotificationPolicy`
-    follow):
-    the foreign-provenance refusal (`alerting-provenance.ts`, an allowlist of Grafana's own
-    `ProvenanceNone`/`ProvenanceAPI` values, measured against `pkg/services/ngalert/models` and
-    Grafana's v13.1 docs) and the secret-settings-ref seam (`secret-refs.ts`, shared with
-    `Grafana.Datasource`) are both new shared building blocks — full detail:
-    [grafana-alerting.md](./grafana-alerting.md).
-    - 🔴 **New SDK gap found, not fixed here:** `MuteTimeInterval`'s generated type has no
-      `provenance`/`version` fields, and the SDK's own `TimeInterval` type is missing the real
-      Alertmanager time-interval fields (`weekdays`/`times`/`months`/etc.) entirely — Grafana's real
-      API returns and accepts all of them. NOT a data-loss gap: `@distilled.cloud/core`'s response
-      decoding never runs a strict schema decode (`JSON.parse` + a key-rename pass that leaves any
-      unmodeled key verbatim — `protocol-http.ts`'s `mapKeys`, confirmed by driving the real
-      operation through this family's fake-Grafana harness), so `mute-timing.ts` reads/writes both
-      through a locally-widened type instead. Same S22 fix route as the other named gaps
-      (regenerate the distilled clone's spec, copy forward) — not attempted here, since
-      `packages/distilled-grafana/src/` is vendored and never hand-edited.
-    - Measured, read-only, same census as PR 245's: `teslamate-grafana` has no contact points, mute
-      timings or templates configured either (consistent with the alerting-provisioning gap having
-      been real, not merely unexploited).
-
-    ✅ **`Grafana.AlertRuleGroup` shipped** (kit PR 254, second of three, branched fresh off `main`
-    after PR 250 merged): group, not per-rule, is the unit — `PUT .../rule-groups/{Group}` owns
-    evaluation `interval` and the full ordered `rules[]` together, which per-rule operations
-    cannot express (no `interval` field, no reordering). Rule order is significant, proven by a
-    dedicated test. The per-rule provenance refusal (each `ProvisionedAlertRule.provenance`, since
-    the group type itself carries none) reuses `alerting-provenance.ts` unchanged, including the
-    missing-means-foreign fix from PR 250's review. A declared group whose folder does not exist
-    refuses as a typed `BadRequest` (`RoutePutAlertRuleGroupError` has no `NotFound` case) rather
-    than being auto-created — this resource never calls `Grafana.Folder`'s create path. A whole-group
-    write silently dropping a live rule not in the declaration (found by that PR's own adversarial
-    review) is now warned about loudly rather than silent, never a refusal. Full detail:
-    [grafana-alerting-rules.md](./grafana-alerting-rules.md).
+## Remaining family findings
 
-    ✅ **`Grafana.NotificationPolicy` shipped** (this PR, third and last of the stacked PRs,
-    branched fresh off `main` after PR 254 merged): a SINGLETON — `fetchLive` never returns
-    `undefined` (`RouteGetPolicyTreeError` has no `NotFound` case), so this resource has no create
-    or delete in the sense every sibling resource does, only adopt-and-update. `destroy` never
-    calls `routeResetPolicyTree` without an explicit `allowReset: true` prop, a gate independent of
-    (and in addition to) `defaultRemovalPolicy: 'retain'` — two gates, since resetting wipes the
-    WHOLE instance's routing back to Grafana's bare default, not one object. The tree is opaque
-    `Record<string, unknown>` (same reasoning as `mute-timing.ts`'s `timeIntervals` — Grafana's
-    matcher-expression types are complex unions this family does not hand-model), compared via
-    `subset-match.ts` for Grafana-injected-default tolerance, with route order significant. The
-    same dropped-item warning kit PR 254 introduced for rule groups is mirrored here for dropped
-    routes. Full detail: [grafana-notification-policy.md](./grafana-notification-policy.md).
+The remaining sequence is split into smaller documents to keep each below 200 lines.
 
-    This completes the alerting-provisioning family this project set out to cover.
-    - ⛔ **Same open gaps as `forgejo/*` and `netbox/*` above:** `read` never answers `Unowned`
-      (H1), and credentials come from an explicit env var NAME at call time rather than an
-      `alchemy/Auth` provider (S24) — here the house's own `grafanaCredentials(target)`, not the
-      SDK's `CredentialsFromEnv`, because more than one Grafana instance exists on this estate
-      (grafana.md's own Credentials section).
-    - Measured, read-only, on `teslamate-grafana.service` (CT100, `teslamate/grafana:4.2.0`,
-      Grafana 13.1.3): one datasource (file-provisioned, not API-managed — a live example this
-      family COULD adopt), dashboards baked into the image (not API-managed either way), and no
-      folders, alert rules or contact points configured — consistent with the gap being real
-      rather than merely unexploited. No stack yet imports `@homeflare/alchemy/grafana`.
+[Findings 7–14](./upstream-conformance-families.md) cover Proxmox, Talos, NetBox,
+LiteLLM, list/JSDoc/test conventions and Discord. [Finding 15: Grafana](./upstream-conformance-grafana.md)
+records the SDK migration, shipped resources and the scoped deprecated-API departure.
 
 ## Conforms
 
-- **`paperless/*` (`Tag`, `DocumentType`, `StoragePath`, `CustomField`)** — ✅ **S23 fixed
-  2026-09-24** (branch `claude2/distilled-paperless-family`, decision 43, mirroring the
-  netbox/forgejo migrations above). Every call now goes through `@distilled.cloud/paperless-ngx`'s
-  typed operations, `catchTag('NotFound', …)` replaced the status-carrying `PaperlessError`
-  union, and `client.ts`/`errors.ts`/`credentials.ts` are deleted. The shared
-  `matching.ts`/`matching-locate.ts` engine (locate-by-name before state, by `output.id` after —
-  PR 163) is unchanged in shape. Not published upstream yet, aliased onto
-  `@homeflare/distilled-paperless-ngx@0.3.0` — [distilled-interim.md](./distilled-interim.md).
-  State did not move: props/attributes stay byte-identical, proven by `tag.test.ts` and the full
-  PR 163 regression suite (`tag-identity.test.ts`) against a fake exercising the real distilled
-  protocol. ⛔ **Still diverges on credentials (S24):** `PAPERLESS_URL`/`PAPERLESS_TOKEN` are read
-  at call time, now through the SDK's `CredentialsFromEnv` — same divergence, unchanged by the
-  transport swap.
-- **`github/RepositoryRuleset`** (added 2026-09-23) closes the hazard the row above names:
-  probes by name (`read`/`reconcile` both), answers `Unowned` on a cold name match (H1),
-  normalizes before comparing so a matching live ruleset is a true noop, and refuses
-  (rather than silently drops) a live rule type it does not model. Two recorded
-  divergences: the type string sits in upstream's own `GitHub` namespace (H14), and the
-  client is Octokit rather than distilled because distilled's `S.Struct` request schemas
-  have no field for `require_extra_approval_for_unattributed_changes` (H15) — see
-  [repository-ruleset.md](./repository-ruleset.md). `declareRepoPolicy` is rewired onto
-  it; the row below is now describing upstream `GitHub.Ruleset` itself, which this family
-  does not touch and remains usable directly.
-- **`github/declareRepoPolicy`** composes upstream `GitHub.Repository` and
-  `GitHub.Ruleset`. Its one hazard is upstream's own: `Ruleset.read` returns `undefined`
-  without prior output, so a first deploy creates a duplicate
-  ([repo-policy.md](./repo-policy.md)). The fix belongs upstream: read by name and answer
-  `Unowned`. Since 2026-09-23 `declareRepoPolicy` no longer takes this path (see the
-  `RepositoryRuleset` row above); this remains accurate for upstream `Ruleset` on its own.
-- **`cloudflare/website.ts`** sets house defaults over upstream `Website.Astro` and
-  `Website.Vite`.
-- **`ownership/*`** is built only on `AdoptPolicy`, `Stack`, `State` and `Artifacts`. Its
-  apply-time re-check (H2) exists because beta.79 skips the adoption probe while props hold
-  an Output. That fix also belongs in the engine upstream.
-- **`verify/*`** (`hf-adopt-verify`) runs Alchemy's own planner. It exists because beta.79
-  labels every cold adoption as an update (H6).
-- **`google-workspace/*`** (new 2026-09-24, `Group`, `GroupMember`, `DomainAlias`, `OrgUnit`)
-  is built directly on `@distilled.cloud/google-workspace@1.0.0-rc.12`'s typed
-  `unstable/admin_directory_v1` operations from the first commit — no hand-rolled client ever
-  existed for it to migrate off (S23), so there is no `client.ts` deletion to record. Every
-  `fetchLive` is get-by-key with its own `catchTag('NotFound', …)`, the same split forgejo's and
-  netbox's engines use (resource.ts). Get-by-key rather than NetBox's list-then-disambiguate,
-  since Directory addresses every object this family models by a stable key. ⛔ **Diverges on
-  credentials, same shape as the rest of this ledger (S24):** `GOOGLE_ACCESS_TOKEN` is read at
-  call time through the SDK's own `CredentialsFromEnv` — but here the SDK provides no way to
-  MINT that token at all (no service-account/DWD support), so a Bun wrapper outside this
-  package (H8, unwritten by this PR) is load-bearing in a way NetBox's/Forgejo's simple
-  API-token env vars are not. SDK gaps (the `unstable/` service tree, no per-operation error
-  beyond the shared 4xx set, no group-alias update) and the full credential/scope setup:
-  [google-workspace.md](./google-workspace.md).
+[Conforming building blocks](./upstream-conformance-conforms.md) records the measured
+conformance and remaining exceptions for Paperless, GitHub, ownership, verify and
+Google Workspace.
 
 ## The Bun line
 
-These are non-test files under `src/` that the standard (S42) says must be portable. "Exp"
-marks files exported from a subpath `index.ts`. `git grep` on `origin/main` finds 23 non-test
-files under `src/` that call `Bun.*` or import `node:*`/`bun:*`. Six of them are outside
-S42's scope:
-
-- four loopback fakes (`caddy/fake-caddy.ts`, `openbao/fake-bao.ts`, `proxmox/fake-pve.ts`,
-  `proxmox/fake-pve-lxc.ts`), which are test-side under S44;
-- `proxmox/provision-cli-fake.ts`, which is used only by tests;
-- `verify/args.ts`, which belongs to the CLI and so is tooling under S43.
-
-That leaves 17 files. The table lists them, plus `provision-cli-fake.ts`, which should move
-out of `src/`. The six out-of-scope files still ship in the tarball's `src/`, but no export
-reaches them.
-⚠️ The first version of this table said 16 files and left out `launchd/job-form.ts`.
-⚠️ Corrected 2026-09-22: 14 of the 17 break upstream's rule. `launchd/job-form.ts`,
-`proxmox/write-only.ts` and `proxmox/pbs-notification-target-wire.ts` use only synchronous
-`node:crypto` or `Buffer`. Upstream allows those inside `Effect.sync`
-(`AGENTS.md@v2.0.0-beta.79#Workflow`), and 40 upstream `src/` files import `node:crypto`,
-among them `Fly/Secret.ts` and `Railway/Variable.ts`. They were listed under a blanket
-`node:*` ban that upstream does not have.
-
-| file                                                       | API                                          | exp | portable replacement                         |
-| ---------------------------------------------------------- | -------------------------------------------- | --- | -------------------------------------------- |
-| `openbao/cloudflare-roles-config.ts`                       | `Bun.YAML`                                   | yes | parse on the tooling side; pass data in      |
-| `openbao/digest.ts` (14 importers)                         | `Bun.CryptoHasher`                           | —   | `Crypto.digest` + hex; keep `canonical()` ⚠️ |
-| `openbao/cloudflare-parity-snapshot.ts`                    | `Bun.file`, `Bun.Glob`                       | —   | `FileSystem` + `Path`                        |
-| `openbao/approle-login-form.ts`                            | `Bun.file`                                   | —   | `FileSystem.readFileString`                  |
-| `openbao/approle-login-result.ts`                          | `Bun.inspect`                                | —   | a plain formatter                            |
-| `openbao/forgejo-bootstrap.ts`                             | `Bun.spawn`                                  | —   | unreferenced; `ChildProcessSpawner` or drop  |
-| `talos/credentials.ts`                                     | `Bun.write/file/env/randomUUIDv7`, `node:fs` | —   | `FileSystem.makeTempFileScoped`              |
-| `talos/kubeconfig.ts`                                      | `Bun.file`                                   | yes | `FileSystem`                                 |
-| `talos/talos-machine-config.ts`                            | `Bun.file`                                   | yes | `FileSystem`                                 |
-| `talos/values.ts`                                          | `Bun.YAML`, `node:crypto`                    | —   | tooling-side parse; hash may stay            |
-| `launchd/local-runner.ts`                                  | `node:child_process`, `node:fs/promises`     | yes | H3 above                                     |
-| `launchd/sudo-stage.ts`                                    | `node:fs/promises`, `node:os`, `node:path`   | —   | `FileSystem`, `Path`                         |
-| `launchd/job-form.ts`                                      | `node:crypto` (`createHash`)                 | —   | allowed in `Effect.sync`                     |
-| `linux/ssh-runner.ts`                                      | `node:child_process`, `node:crypto`          | yes | H3 above                                     |
-| `caddy/caddy-http-client.ts`                               | `node:http`, `node:stream` (unix socket)     | yes | inherent — an Effect `HttpClient`, not H3 ⚠️ |
-| `proxmox/write-only.ts`, `pbs-notification-target-wire.ts` | `node:crypto`, `node:buffer`                 | —   | allowed in `Effect.sync` ⚠️                  |
-| `proxmox/provision-cli-fake.ts`                            | `Bun.spawn`, `node:fs`                       | —   | test-only; move out of `src/`                |
-
-The ⚠️ rows:
-
-- `openbao/digest.ts`: every `Bao.*` family persists this digest in state, so a swap must
-  hash the same bytes (`canonical()`, lowercase hex), or every row plans an update.
-  `Crypto.digest` from `effect/Crypto` is in every stack's services and fails with a typed
-  error; `alchemy/Util/sha256` wraps WebCrypto in `Effect.promise`.
-- `proxmox/write-only.ts`: a salted scrypt seal with `timingSafeEqual`. No Alchemy helper
-  replaces it. A plain `sha256` would make a write-only secret cheap to brute-force from
-  state, and it would change the persisted seal format.
-- `caddy/caddy-http-client.ts`: unlike `launchd/local-runner.ts` and `linux/ssh-runner.ts`
-  (H3, plain `async` interfaces), this is already the Effect `HttpClient.HttpClient` the
-  distilled SDK's own protocol runs on — `node:http` here is the same kind of unavoidable,
-  bottom-of-the-stack platform adapter `@effect/platform-node`'s own `NodeHttpClient.ts` is,
-  extended with `socketPath` dialing (that module has none) because a unix socket is the
-  measured transport a local Caddy needs and neither `FetchHttpClient` (Bun-only `unix`
-  option) nor stock `NodeHttpClient` (URL-only) speaks one on both Bun and Node. There is no
-  more-portable replacement to point to; the file already conforms to S19 (no async/await,
-  no raw `Promise` — `Effect.callback`/`Effect.tryPromise` throughout).
-
-Test runners: 51 files import `node:test`/`node:assert` (openbao 42, proxmox 7, forgejo 1,
-talos 1), and 126 import `bun:test`. S43 says `bun:test`.
+[The Bun line inventory](./upstream-conformance-bun.md) preserves the runtime-boundary
+measurements, portable replacements and state-format constraints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "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",
@@ -28,6 +28,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./argocd": {
+      "types": "./dist/argocd/index.d.ts",
+      "default": "./dist/argocd/index.js"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.ts",
       "default": "./dist/cloudflare/index.js"
@@ -120,11 +124,12 @@
     "@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.2.0",
-    "@distilled.cloud/proxmox-backup": "npm:@homeflare/distilled-proxmox-backup@0.2.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/unifi-network": "npm:@homeflare/distilled-unifi-network@0.2.0"
   },
   "peerDependencies": {
+    "@distilled.cloud/argocd": "1.0.0-rc.12",
     "@distilled.cloud/cloudflare": "1.0.0-rc.12",
     "@distilled.cloud/discord": "1.0.0-rc.12",
     "@distilled.cloud/forgejo": "1.0.0-rc.12",

package/src/argocd/cluster.test.ts

@@ -0,0 +1,120 @@
+/**
+ * `Argocd.Cluster`'s `spec` against a fake Argo CD — the same three doctrine-required shapes as
+ * `repository.test.ts`, plus the nested `config.tlsClientConfig` credential path.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeArgocd, fakeArgocdLayer, fakeFailure } from './fake-argocd.ts';
+import { argocdOperations } from './resource.ts';
+import { spec } from './cluster.ts';
+
+const SERVER = 'https://talos.example.com:6443';
+const ENV_VAR = 'ARGOCD_CLUSTER_TALOS_BEARER_TOKEN';
+
+const liveCluster = (overrides: Record<string, unknown> = {}) =>
+  Response.json({ name: 'talos', server: SERVER, ...overrides });
+
+describe('Argocd.Cluster spec.fetchLive', () => {
+  test('a live cluster decodes into attributes, including nested tls config', async () => {
+    const fake = fakeArgocd((method) =>
+      method === 'GET'
+        ? liveCluster({
+            config: { tlsClientConfig: { insecure: false, serverName: 'talos.internal' } },
+          })
+        : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(live?.server).toBe(SERVER);
+    expect(live?.config?.tlsClientConfig?.serverName).toBe('talos.internal');
+  });
+
+  test('a 404 folds to undefined', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    const result = await Effect.runPromise(
+      spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — not folded to absent', async () => {
+    const fake = fakeArgocd(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec.fetchLive({ server: SERVER }).pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('Argocd.Cluster destroy — idempotent (S11)', () => {
+  test('deleting an already-absent cluster makes no DELETE call', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'cluster not found'));
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.every((call) => call.method !== 'DELETE')).toBe(true);
+  });
+
+  test('the DELETE call itself returning 404 (a race with an external removal) still succeeds', async () => {
+    // ⚠️ fetchLive's pre-check finds the cluster live, but something else deregisters it before
+    //   this call's own DELETE lands — matching upstream's Hetzner/Certificate.ts `deleteById`.
+    const fake = fakeArgocd((method) =>
+      method === 'GET' ? liveCluster() : fakeFailure(404, 'cluster not found'),
+    );
+    await Effect.runPromise(
+      argocdOperations(spec)
+        .destroy({ server: SERVER })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    expect(fake.seen.filter((call) => call.method === 'DELETE')).toHaveLength(1);
+  });
+});
+
+describe('Argocd.Cluster spec.upsert — write-only bearer token', () => {
+  beforeEach(() => {
+    delete process.env[ENV_VAR];
+  });
+  afterEach(() => {
+    delete process.env[ENV_VAR];
+  });
+
+  test('refuses with a typed domain error when the declared env var is unset', async () => {
+    const fake = fakeArgocd(() => fakeFailure(404, 'unused'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        spec
+          .upsert({ credentials: { bearerToken: { fromEnv: ENV_VAR } }, server: SERVER })
+          .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+      ),
+    );
+    expect(failure._tag).toBe('ArgocdClusterSecretEnvUnsetError');
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('resolves the bearer token into config, never the FromEnv reference itself', async () => {
+    process.env[ENV_VAR] = 'kube-bearer-abc123';
+    const fake = fakeArgocd((method) =>
+      method === 'POST' ? Response.json({ server: SERVER }) : fakeFailure(404, 'x'),
+    );
+    await Effect.runPromise(
+      spec
+        .upsert({
+          credentials: { bearerToken: { fromEnv: ENV_VAR } },
+          namespaces: ['argocd', 'apps'],
+          server: SERVER,
+        })
+        .pipe(Effect.provide(fakeArgocdLayer(fake.fetch))),
+    );
+    const [create] = fake.seen.filter((call) => call.method === 'POST');
+    expect(create?.path).toContain('upsert=true');
+    const body = create?.body as { config?: { bearerToken?: string }; namespaces?: string[] };
+    expect(body.config?.bearerToken).toBe('kube-bearer-abc123');
+    expect(body.namespaces).toEqual(['argocd', 'apps']);
+    expect(JSON.stringify(body)).not.toContain('fromEnv');
+  });
+});