@homeflare/alchemy 0.36.0 → 0.37.1

package/docs/upstream-conformance-bun.md

@@ -0,0 +1,67 @@
+# The Bun line
+
+Status: extracted from the [conformance ledger](./upstream-conformance.md); its dated
+measurements and open findings are preserved below.
+
+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`.

package/docs/upstream-conformance-conforms.md

@@ -0,0 +1,55 @@
+# Upstream conformance: conforming building blocks
+
+Status: extracted from the [conformance ledger](./upstream-conformance.md); its dated
+measurements and open findings are preserved below.
+
+- **`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).

package/docs/upstream-conformance-families.md

@@ -0,0 +1,95 @@
+# Upstream conformance: remaining family findings
+
+Status: extracted from the [conformance ledger](./upstream-conformance.md); its dated
+measurements and open findings are preserved below.
+
+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 (defect risk, not a separate S20 ban);
+   - 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.
+    - **Credentials resolution, decision 49 (2026-09-24):** the temporary typed-`ConfigError`
+      change was reverted in [PR #261](https://github.com/taslabs-net/homeflare-kit/pull/261).
+      `CredentialsFromEnv` retains distilled's own `Effect.orDie` convention. S20 forbids it
+      in lifecycle operations; it is not a separate credentials-layer prohibition. The same
+      shape in NetBox is therefore not an S20 follow-up. See [LiteLLM's Q6 resolution](./litellm.md#credentials).
+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`).

package/docs/upstream-conformance-grafana.md

@@ -0,0 +1,106 @@
+# Upstream conformance: Grafana
+
+Status: extracted from the [conformance ledger](./upstream-conformance.md); its dated
+measurements and open findings are preserved below.
+
+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).
+    - ⚠️ **Knowing departure from upstream (Q8, decision 49 "upstream wins", 2026-09-24, WI-13):**
+      upstream's own rule for a deprecated vendor API is to document it _out of scope_, not
+      implement it — "Deprecated APIs (superseded by Rulesets etc.) … are documented as out of
+      scope in `INDEX.md` rather than implemented" (A `AGENTS.md:155`). The 32 un-deprecated
+      operations above do the opposite: they are un-deprecated and implemented. The reason is that
+      there is no in-scope replacement to point at instead — Grafana's spec marks these
+      `deprecated: true` in favor of a Kubernetes-style aggregated apiserver under
+      `/apis/{folder,dashboard,...}.grafana.app/v1…`, and that route family is **absent from the
+      pinned spec entirely**: MEASURED 2026-09-24 in the grafana worktree
+      (`packages/grafana/specs/spec-mirror-grafana/specs/openapi3.json`), 0 of 207 paths start
+      with `/apis` — the un-deprecation patches' own descriptions already say the same thing
+      (`packages/grafana/patches/001-undeprecate-folders.patch.json`: "That newer route … [is] not
+      present in this spec at all"). Following upstream's rule literally here would mean shipping
+      no `Grafana.Folder`/`Dashboard`/alerting-provisioning family at all, on an API the kit
+      already needs. The departure is scoped to exactly these 32 operations; the other 32 stay
+      excluded, deprecated, out of scope, matching upstream on that half.
+
+    ✅ **`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).
+
+    ✅ **`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).
+
+    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`.