@homeflare/alchemy 0.12.0 → 0.13.0

package/dist/proxmox/write-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-only.d.ts","sourceRoot":"","sources":["../../src/proxmox/write-only.ts"],"names":[],"mappings":"AA2BA,+FAA+F;AAC/F,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,SACf,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAClC,WAAW,KACf;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAS1F,CAAC;AAqBF;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,WAAY,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,SAAS,MAAM,KAAG,MAI9E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,OAStF,CAAC"}

package/dist/verify/fake-engine.d.ts

@@ -53,6 +53,11 @@ export interface FakeEngine {
     readonly deploy: (body: Body) => Promise<Record<string, string>>;
     /** Verify `body` against what the earlier deploys recorded. */
     readonly verify: (body: Body, options?: VerifyOptions) => Promise<AdoptReport>;
+    /**
+     * Every state row the store holds, as JSON — what a Postgres store would persist. ★ For tests
+     * that must prove a value NEVER reaches state (proxmox/pbs-notification-target-state.test.ts).
+     */
+    readonly stored: () => string;
 }
 /**
  * One stack over one state store and any providers, shared by every call — a family's own test

package/dist/verify/fake-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-engine.d.ts","sourceRoot":"","sources":["../../src/verify/fake-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAKnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AACnG,eAAO,MAAM,QAAQ,iCAA8C,CAAC;AAEpE,gGAAgG;AAChG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,OAAO,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAQ,KAI1D,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,MAAM,EAC2C,CAAC;AAyB1F,4FAA4F;AAC5F,eAAO,MAAM,cAAc,UAAW,KAAK,8GAmCxC,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAK5D,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAChF;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAAG,UAuC3E,CAAC;AAEF,oCAAoC;AACpC,eAAO,MAAM,UAAU,UAAW,KAAK,KAAG,UAA+C,CAAC"}
+{"version":3,"file":"fake-engine.d.ts","sourceRoot":"","sources":["../../src/verify/fake-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAKnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAiB,MAAM,aAAa,CAAC;AAElF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,KAAM,SAAQ,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AAC7F,eAAO,MAAM,KAAK,8BAAwC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,EAAE,eAAe,CAAC;CAAG;AACnG,eAAO,MAAM,QAAQ,iCAA8C,CAAC;AAEpE,gGAAgG;AAChG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,OAAO,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAQ,KAI1D,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,MAAM,EAC2C,CAAC;AAyB1F,4FAA4F;AAC5F,eAAO,MAAM,cAAc,UAAW,KAAK,8GAmCxC,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAK5D,MAAM,WAAW,UAAU;IACzB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAAG,UAyC3E,CAAC;AAEF,oCAAoC;AACpC,eAAO,MAAM,UAAU,UAAW,KAAK,KAAG,UAA+C,CAAC"}

package/docs/adopted-deploys.md

@@ -38,6 +38,7 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Proxmox.BackupJob`            | `cluster/backup/{id}`                                           | read        | shared path — no write                                                                               |
 | `Proxmox.MetricServer`         | `cluster/metrics/server/{id}`                                   | read        | shared path — no write                                                                               |
 | `Proxmox.NotificationTarget` ² | `cluster/notifications/endpoints/{type}/{name}`                 | read        | shared path — no write                                                                               |
+| `Proxmox.NotificationMatcher`  | `cluster/notifications/matchers/{name}`                         | read        | shared path — no write                                                                               |
 | `Proxmox.HaResource`           | `cluster/ha/resources/{sid}`                                    | read        | shared path — no write                                                                               |
 | `Proxmox.HaRule`               | `cluster/ha/rules/{rule}`                                       | read        | shared path — no write                                                                               |
 | `Proxmox.SdnZone`              | `cluster/sdn/zones/{zone}`                                      | provision ¹ | shared path — no write                                                                               |
@@ -47,6 +48,8 @@ API token on the cluster, just as it does for `alchemy plan`.
 | `Pbs.PruneJob`                 | `config/prune/{id}`                                             | read (PBS)  | shared path — no write                                                                               |
 | `Pbs.SyncJob`                  | `config/sync/{id}`                                              | read (PBS)  | shared path — no write                                                                               |
 | `Pbs.VerifyJob`                | `config/verify/{id}`                                            | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.NotificationMatcher`      | `config/notifications/matchers/{name}`                          | read (PBS)  | shared path — no write                                                                               |
+| `Pbs.NotificationTarget` ⁵     | `config/notifications/endpoints/{type}/{name}`                  | read (PBS)  | own: GET, PUT only for a stale group, GET — no write                                                 |
 | `Proxmox.Acl`                  | `access/acl` (whole list, filtered)                             | provision ¹ | shared path, then its own `bound` check — no write                                                   |
 | `Pbs.Datastore`                | `config/datastore/{name}`                                       | read (PBS)  | own: GET, path/backend guards, PUT skipped on `matches`, settle GET — no write                       |
 | `Proxmox.SdnApply`             | 5 × `cluster/sdn/*?pending=1` + fabrics `?pending` / `?running` | read        | own: counts staged objects; zero returns at once — **no `PUT /cluster/sdn`**                         |
@@ -65,6 +68,11 @@ no-write row applies. Pinned by `src/proxmox/lxc-adopt.test.ts` ("deploys with n
 declared ratio that differs from the live one is never written on a no-op adoption and never
 reported as a diff.
 
+⁵ Its own `diff` and `reconcile`, because a secret's value is not in the live object: the plan
+compares a seal kept in the previous state ([pbs-notifications.md](./pbs-notifications.md)). An
+adopted target has no seal, so its secret values are presence-only and adoption writes nothing.
+Pinned by `src/proxmox/pbs-notification-target-state.test.ts`.
+
 ## Before the fix: `Proxmox.CephPool`
 
 `reconcile` read the pool and, whenever it existed, PUT the declared `size`, `min_size`,

package/docs/pbs-alertmanager-body.md

@@ -0,0 +1,73 @@
+# A PBS webhook body that posts an Alertmanager alert
+
+`alertmanagerAlertBody()` ([alertmanager-body.ts](../src/proxmox/alertmanager-body.ts)) is the
+body of a PBS webhook target that posts one alert to Alertmanager's `POST /api/v2/alerts`.
+Declaring the target and the matcher that routes to it: [pbs-notifications.md](./pbs-notifications.md).
+
+With the default options it returns exactly this text:
+
+```text
+[
+  {
+    "labels": {
+      {{#if fields.type}}"job_type": {{ json fields.type }},{{/if}}
+      {{#if fields.job-id}}"job_id": {{ json fields.job-id }},{{/if}}
+      {{#if fields.datastore}}"datastore": {{ json fields.datastore }},{{/if}}
+      {{#if fields.hostname}}"hostname": {{ json fields.hostname }},{{/if}}
+      "severity": {{ json severity }},
+      "alertname": "PbsNotification",
+      "source": "pbs"
+    },
+    "annotations": {
+      "summary": {{ json title }},
+      "description": {{ json message }},
+      "timestamp": "{{ timestamp }}"
+    }
+  }
+]
+```
+
+The fence is `text` on purpose. As a `handlebars` fence the formatter reflowed it into
+something the function does not return.
+
+Options: `alertname`, `source` and an optional `generatorURL`. Braces and backslashes are
+refused in all three. `generatorURL` must also be an absolute `http` or `https` URL, because
+Alertmanager validates it as a URI and rejects the whole post if it is not one.
+
+## Why it is valid JSON for every PBS notification
+
+Each point is from the proxmox-notify, proxmox-backup and Alertmanager source, read 2026-09-22.
+
+- **The webhook renderer has no escaping** (`register_escape_fn(no_escape)`). Every value that
+  comes from the notification goes through `json`, which is `serde_json::to_string`. It writes
+  a complete, quoted JSON string with quotes, backslashes and control characters escaped. A task
+  log with a quote, a tab or a newline stays valid JSON.
+- **`escape` on a missing field fails the whole render**, and the notification is lost.
+  `json` on a missing field writes `null`, which is valid JSON but not a label value. So every
+  `fields.*` label sits inside `{{#if}}` and ends with its own comma, and the constant labels
+  close the object. The UI's **Test** button sends a notification with no fields at all.
+- **Every field value is a string.** proxmox-notify turns each metadata field into a JSON string
+  before rendering. `severity` serialises as `info`, `notice`, `warning`, `error` or `unknown`,
+  and `timestamp` is an integer (epoch seconds). Nothing else in the data is rendered.
+- **The helpers are `json`, `escape` and `url-encode`, and nothing else.** The mail templates'
+  `timestamp` and `duration` helpers are not registered for webhooks, so `timestamp` is sent as
+  epoch seconds in an annotation.
+- **Alertmanager takes an array** (`postableAlerts`). `labels` is required and must not be empty.
+  Every label and annotation value must be a string. It drops empty labels.
+
+`tests/alertmanager-body.test.ts` renders the template with handlebars.js set up the way
+proxmox-notify sets up its renderer. It covers the field set of every event type in PBS's
+`src/server/notifications/mod.rs`, the Test notification, forwarded system mail, and hostile
+strings (quotes, backslashes, control characters, `{{`, U+2028). Each result must parse as an
+Alertmanager v2 alert array. A scratch build of handlebars-rust 5.1.2, the major version
+proxmox-notify pins, rendered the same cases to valid JSON. The first real notification is
+still the check that counts: press **Test** on the target, then read what Alertmanager received.
+
+## What it does not do
+
+- **With no `endsAt`, Alertmanager resolves the alert itself** after `resolve_timeout` (5 min by
+  default), and PBS never sends a resolve. Treat a "resolved" notification as a timeout, not a
+  recovery.
+- **`severity` uses PBS's names.** Route on `severity="error"`, or relabel in Alertmanager.
+- **Alertmanager deduplicates by label set.** Two failures of the same job within
+  `resolve_timeout` are one alert, not two.

package/docs/pbs-notifications.md

@@ -0,0 +1,163 @@
+# PBS and PVE notifications — targets, matchers, and an Alertmanager webhook
+
+`@homeflare/alchemy/proxmox` declares both halves of the Proxmox notification system:
+
+| family                        | what it is                                          | source                                                                    |
+| ----------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- |
+| `Pbs.NotificationTarget`      | where PBS sends: `webhook`, `smtp`, `sendmail`      | [pbs-notification-target.ts](../src/proxmox/pbs-notification-target.ts)   |
+| `Pbs.NotificationMatcher`     | which PBS notifications go to which targets         | [pbs-notification-matcher.ts](../src/proxmox/pbs-notification-matcher.ts) |
+| `Proxmox.NotificationMatcher` | the same on a PVE cluster                           | [notification-matcher.ts](../src/proxmox/notification-matcher.ts)         |
+| `Proxmox.NotificationTarget`  | PVE targets (existing; declares no secret)          | [notification-target.ts](../src/proxmox/notification-target.ts)           |
+| `alertmanagerAlertBody()`     | a webhook body that posts one Alertmanager v2 alert | [pbs-alertmanager-body.md](./pbs-alertmanager-body.md)                    |
+
+A target that no matcher names receives nothing. Declare both.
+
+## Paging on a failed verify, sync, prune or garbage collection
+
+```ts
+import * as Effect from 'effect/Effect';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationTarget,
+  alertmanagerAlertBody,
+} from '@homeflare/alchemy/proxmox';
+
+const pbs = {
+  api: 'https://pbs.example.com:8007/api2/json',
+  mount: 'pbs-mount',
+  scheme: 'pbs',
+} as const;
+
+export const notifications = Effect.gen(function* () {
+  const hook = yield* PbsNotificationTarget('alertmanager', {
+    target: pbs,
+    type: 'webhook',
+    name: 'alertmanager',
+    method: 'post',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+    header: {
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer {{ secrets.token }}', // template text, not the token
+    },
+    secret: { token: { fromEnv: 'PBS_ALERTMANAGER_TOKEN' } }, // the token, by variable name
+    body: alertmanagerAlertBody(),
+  });
+  yield* PbsNotificationMatcher('page-on-failure', {
+    target: pbs,
+    name: 'page-on-failure',
+    targets: [hook.name], // the Output, not a string: it orders create and delete
+    'match-severity': ['error'],
+    'match-field': ['exact:type=gc,prune,sync,verify'],
+  });
+});
+```
+
+Drop the `Authorization` header and the `secret` when Alertmanager takes unauthenticated posts
+on a trusted network. The provider layer is `PbsNotificationTargetProvider()` and
+`PbsNotificationMatcherProvider()`. `targets: [hook.name]` matters: PBS refuses a matcher that
+names a missing target, and refuses to delete a target a matcher still names. The Output gives
+Alchemy that ordering; a bare string does not (`pbs-notifications-stack.test.ts`).
+
+⛔ **A datastore in `legacy-sendmail` mode never reaches a matcher.** PBS mails its `notify-user`
+directly. `notification-system` is the default, but a datastore created before PBS 3.2 can say
+otherwise. Check with `proxmox-backup-manager datastore show <name>`.
+
+⚠️ **A verification job's event `type` is `verify`**, not `verification`. PBS's own event table
+says `verification`, and the source (`send_verify_status`) sets `verify`. The other types are
+`gc`, `prune`, `sync`, `tape-backup`, `tape-load`, `package-updates`, `acme`, `thresholds` and
+`system-mail`. Garbage collection has no `job-id`.
+
+⚠️ **`match-severity: ['warning', 'error']` under the default `mode: 'all'` matches nothing.**
+Each item is combined with `mode`. The severities inside one item are OR-ed, so write
+`['warning,error']`.
+
+## Write-only values: `{ fromEnv }`
+
+Alchemy stores props and attributes unencrypted, and a `Redacted` value is tagged, not
+encrypted. A secret prop would be a secret in the state database. So `secret`, the smtp
+`password` and any header value that is a credential are declared as `{ fromEnv: 'NAME' }`.
+The deploying process reads the variable at call time.
+
+| what            | in state                                       | how a plan compares it                                                           |
+| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| secret values   | names (PBS returns names only), and a **seal** | seal of what this provider last wrote, checked against the env value             |
+| smtp password   | the seal only (PBS returns nothing)            | the same seal                                                                    |
+| header values   | names, and a scrypt digest of the live pairs   | digest of the declared values (env-resolved) against the digest of the live ones |
+| everything else | the value                                      | by value, like every family here                                                 |
+
+The seal is `scrypt:<salt>:<digest>`, with a random salt per write. It proves "unchanged" and
+holds nothing a reader could send to PBS. A guessable secret stays guessable, so use a random
+token.
+
+- **A plan without the variables is presence-only.** Names are compared and values are
+  `unknown`. `unknown` plans `noop`, never an invented update.
+- **A write carries only the stale groups.** A PUT without `secret` or `header` leaves those on
+  the server as they are, so a changed comment deploys without the secrets.
+- **A write that needs a missing variable fails by name**, before any request is sent.
+- **Adoption is free.** A webhook adopted with secrets has no seal. Its values stay unverified
+  (presence-only) until the first write that carries them: a create, a changed secret name, or
+  a value rotated after that first write. A value the server already holds is never replaced by
+  adoption alone. To write yours, rename the secret once, together with its `{{ secrets.* }}`
+  references.
+- **Rotation.** Change the variable's value and plan: the seal no longer matches, and the deploy
+  PUTs the secret group alone.
+
+⛔ **A literal credential in a plain prop is refused.** A plain prop is stored as written, so an
+`Authorization`, `Proxy-Authorization` or `Cookie` header, a header or URL query parameter
+named like `token`, `key`, `secret`, `password` or `signature`, or a password in the URL's
+userinfo must be `{ fromEnv }` or read `{{ secrets.<name> }}`. The plan fails and names the
+field, never the value.
+
+⚠️ **What the guard cannot see.** A token in a URL path (Slack-style webhooks), in `body` or in
+`comment` is still a plain prop. Put it in `secret` and reference it from the template. The
+check runs at plan only while every prop is resolved. If a prop is an unresolved Output, Alchemy
+records the props before `reconcile` refuses them.
+
+⚠️ **Prefer `secret` over a `{ fromEnv }` header for a credential.** PBS returns header values
+to anyone with `Sys.Audit`, and prints a header's value unmasked when it fails to render. It
+masks only `secret` values.
+
+## The body template
+
+`alertmanagerAlertBody()` has its own page, with the exact text it returns and why it is valid
+JSON for every notification PBS sends: [pbs-alertmanager-body.md](./pbs-alertmanager-body.md).
+
+## Adopting the built-in `default-matcher`
+
+A matcher is compared as its whole rule: `match-*`, `mode`, `invert-match` and `disable`,
+declared or not. Only `comment` is left alone when undeclared. Adopting a built-in means
+declaring what it holds. Measured 2026-09-22:
+
+```ts
+// PVE 9.2.11: everything to mail-to-root
+ProxmoxNotificationMatcher('default-matcher', {
+  target: cluster,
+  name: 'default-matcher',
+  targets: ['mail-to-root'],
+});
+// PBS 4.2: everything except successful prune jobs
+PbsNotificationMatcher('default-matcher', {
+  target: pbs,
+  name: 'default-matcher',
+  targets: ['mail-to-root'],
+  'invert-match': true,
+  'match-field': ['exact:type=prune'],
+  'match-severity': ['info'],
+});
+```
+
+Both plan `noop` and deploy with no write (`notification-matcher.test.ts`). ⛔ **Deleting a
+built-in reverts it to the shipped rule**, and the server reports success. The attributes show
+`origin` so you can see which kind you have.
+
+## Privileges
+
+| server | read                                                            | write                                        |
+| ------ | --------------------------------------------------------------- | -------------------------------------------- |
+| PBS    | `Sys.Audit` on `/system/notifications`                          | `Sys.Modify` on `/system/notifications`      |
+| PVE    | `Mapping.Audit` or `Mapping.Modify` on `/mapping/notifications` | `Mapping.Modify` on `/mapping/notifications` |
+
+⚠️ A missing read privilege looks like "absent". The plan says `create` and the server answers
+that the object already exists. Grant the read before changing anything else. On PVE,
+`Mapping.Use` is not enough: it opens the matcher list, not the per-matcher read this package
+makes (`get_matcher` in pve-manager's `Notifications.pm`).

package/docs/proxmox.md

@@ -15,6 +15,9 @@ or creates one from a template.
 - ★ **One provisioning baseline for every cluster and node**: the privilege list, a helper that
   declares it, and the one-time root commands that bootstrap it
   ([provision-baseline.md](./provision-baseline.md)).
+- ★ **Notifications that page**: PBS webhook, smtp and sendmail targets with write-only secrets
+  (`{ fromEnv }`, never in state), PBS and PVE matchers, and a webhook body that posts an
+  Alertmanager v2 alert ([pbs-notifications.md](./pbs-notifications.md)).
 - ★ **Measurements in the source name a reference cluster with placeholders**: `C1`, three nodes
   `node-b`, `node-c` and `node-d` with Ceph on a Thunderbolt mesh, and documentation addresses
   (RFC 5737). The shapes and counts are measured; the names and addresses are not the real ones.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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",

package/src/proxmox/alertmanager-body.ts

@@ -0,0 +1,125 @@
+/**
+ * A PBS webhook body that posts one Alertmanager v2 alert — `POST /api/v2/alerts` takes a JSON
+ * ARRAY of `postableAlert`, each with a required `labels` map and an optional `annotations` map,
+ * every value a string (Alertmanager's api/v2/openapi.yaml, read at main 2026-09-22).
+ *
+ * ★ PURE TEXT, NOT A RENDERER. PBS renders it, with Handlebars, at send time: `{{ severity }}`,
+ *   `{{ title }}`, `{{ message }}`, `{{ timestamp }}` and `{{ fields.<name> }}` are the
+ *   notification, and `json`, `escape` and `url-encode` are the only helpers
+ *   (proxmox-notify endpoints/webhook.rs `setup_handlebars`, read at HEAD 2026-09-22).
+ *
+ * ⛔ THERE IS NO ESCAPING UNLESS THE TEMPLATE ASKS FOR IT. The webhook's Handlebars registers
+ *   `no_escape` ("There is no escape."), so `"{{ message }}"` breaks the JSON the first time a
+ *   task log holds a quote or a newline — and a failed job's message is exactly a task log. Every
+ *   value below goes through `json`, which emits a complete, quoted JSON string.
+ * ⛔ A FIELD THE NOTIFICATION DOES NOT CARRY MUST NOT BE REACHED FOR BARE. `escape` on a missing
+ *   field fails the whole render, and the notification is then lost — not degraded. MEASURED
+ *   (2026-09-22) with handlebars-rust 5.1.2 and the webhook's three helpers restated from source:
+ *   `{{ escape fields.job-id }}` over no fields errors "param at index 0 required but not found";
+ *   `{{ json fields.job-id }}` renders `null`, valid JSON but not a label value. Garbage
+ *   collection has no `job-id`, and the UI's "Test" button sends a notification with NO fields at
+ *   all (lib.rs `test_target`). So every field-derived label sits inside
+ *   `{{#if}}`, ends with its own comma, and the labels after them are always there: whichever
+ *   fields are present, the object stays valid JSON.
+ *
+ * ⚠️ ALERTMANAGER RESOLVES IT BY ITSELF. With no `endsAt` it sets `now + resolve_timeout` (5m by
+ *   default, api/v2/api.go `postAlertsHandler`), and PBS never sends a resolve — so a receiver
+ *   with `send_resolved: true` reports "resolved" five minutes after a failure that nobody fixed.
+ *   Page on the firing notification; do not read the resolve as a recovery.
+ * ⚠️ `severity` IS PBS'S WORD, not Alertmanager convention: `info`, `notice`, `warning`, `error`,
+ *   `unknown`. Route on `severity="error"`, or relabel it in the Alertmanager config.
+ */
+
+export interface AlertmanagerBodyOptions {
+  /** The `alertname` label. Default `PbsNotification`; `job_type` says which job it was. */
+  readonly alertname?: string;
+  /** The `source` label. Default `pbs`. */
+  readonly source?: string;
+  /** Optional `generatorURL` — an absolute link back to the PBS UI. */
+  readonly generatorURL?: string;
+}
+
+/**
+ * ⛔ AN OPTION IS PASTED INTO THE TEMPLATE, SO IT MAY NOT CARRY TEMPLATE SYNTAX. A `{{` in an
+ *   alert name would be rendered by PBS as an expression; a brace or backslash is refused here
+ *   rather than escaped, because Handlebars' escape rules are the renderer's, not this file's.
+ */
+const literal = (label: string, value: string): string => {
+  if (/[{}\\]/.test(value) || value === '') {
+    throw new Error(
+      `alertmanagerAlertBody: ${label} must be non-empty and hold no '{', '}' or '\\'`,
+    );
+  }
+  return JSON.stringify(value);
+};
+
+/**
+ * ⛔ AN ABSOLUTE http(s) URL OR NOTHING. Alertmanager validates `generatorURL` as `format: uri`
+ *   (api/v2/openapi.yaml) and answers 422 for the WHOLE post — so a typo here would not degrade
+ *   one field, it would lose every notification, and only at send time.
+ */
+const absoluteUrl = (value: string): string => {
+  const text = literal('generatorURL', value);
+  let protocol = '';
+  try {
+    protocol = new URL(value).protocol;
+  } catch {
+    // not a URL at all: refused below, like a relative one
+  }
+  if (protocol !== 'https:' && protocol !== 'http:') {
+    throw new Error('alertmanagerAlertBody: generatorURL must be an absolute http(s) URL');
+  }
+  return text;
+};
+
+/** Label name → notification field. ⚠️ Label names must match `[a-zA-Z_][a-zA-Z0-9_]*`. */
+const FIELD_LABELS: readonly (readonly [label: string, field: string])[] = [
+  ['job_type', 'type'],
+  ['job_id', 'job-id'],
+  ['datastore', 'datastore'],
+  ['hostname', 'hostname'],
+];
+
+/**
+ * The body template. Declare it on a webhook target together with `Content-Type:
+ * application/json`, method `post`, and the URL `<alertmanager>/api/v2/alerts`.
+ *
+ * ★ `fields.job-id` IS A VALID PATH: Handlebars-rust 5 (the version proxmox-notify pins) allows
+ *   `-` in an identifier (grammar.pest `symbol_char`), as handlebars.js does. The same scratch
+ *   build rendered this template for a GC failure, a verify failure and a field-less test
+ *   notification, and each parsed as JSON with string-only labels. The adversarial review re-ran
+ *   it over the test file's whole matrix — every PBS event's fields x five severities x hostile
+ *   text, 840 renders with and without `generatorURL` — and every one parsed (2026-09-22).
+ * ⚠️ THAT BUILD IS NOT PBS. The first real notification is the measurement that counts: send one
+ *   with the target's "Test" button and read what Alertmanager received.
+ */
+export const alertmanagerAlertBody = (options: AlertmanagerBodyOptions = {}): string => {
+  const alertname = literal('alertname', options.alertname ?? 'PbsNotification');
+  const source = literal('source', options.source ?? 'pbs');
+  const labels = FIELD_LABELS.map(
+    ([label, field]) =>
+      `      {{#if fields.${field}}}"${label}": {{ json fields.${field} }},{{/if}}`,
+  );
+  const link =
+    options.generatorURL === undefined
+      ? ''
+      : `,\n    "generatorURL": ${absoluteUrl(options.generatorURL)}`;
+  return [
+    '[',
+    '  {',
+    '    "labels": {',
+    ...labels,
+    '      "severity": {{ json severity }},',
+    `      "alertname": ${alertname},`,
+    `      "source": ${source}`,
+    '    },',
+    '    "annotations": {',
+    '      "summary": {{ json title }},',
+    '      "description": {{ json message }},',
+    '      "timestamp": "{{ timestamp }}"',
+    `    }${link}`,
+    '  }',
+    ']',
+    '',
+  ].join('\n');
+};

package/src/proxmox/credential-literals.test.ts

@@ -0,0 +1,148 @@
+/**
+ * A literal credential in a plain `Pbs.NotificationTarget` prop is refused — and refused BEFORE
+ * Alchemy writes the props to the state store, which is the whole point.
+ *
+ * ★ THE END-TO-END CASES RUN ALCHEMY'S OWN PLAN AND APPLY (verify/fake-engine.ts) and dump the
+ *   store, because the failure being pinned is not "a refusal exists" but "the token never
+ *   reached the row": before the fix a refused create had already committed its props.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import type { PbsTarget } from './credentials.ts';
+import {
+  isCredentialName,
+  literalCredentialHeaders,
+  literalCredentialsInUrl,
+} from './credential-literals.ts';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+import { refusals } from './pbs-notification-target-form.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const LITERAL = 'lit-7a1c-not-real';
+const AM = 'https://alertmanager.example.com/api/v2/alerts';
+
+const hook = (over: Partial<PbsNotificationTargetProps> = {}): PbsNotificationTargetProps => ({
+  method: 'post',
+  name: 'alertmanager',
+  target: PBS,
+  type: 'webhook',
+  url: AM,
+  ...over,
+});
+
+describe('which names are credentials', () => {
+  test('authorization, cookie and credential words — whole names or dash/underscore words', () => {
+    for (const name of ['Authorization', 'proxy-authorization', 'Cookie', 'X-Api-Key', 'api_key']) {
+      expect(isCredentialName(name)).toBe(true);
+    }
+    for (const name of ['X-Auth-Token', 'Private-Token', 'X-Gotify-Key', 'token', 'sig', 'code']) {
+      expect(isCredentialName(name)).toBe(true);
+    }
+    for (const name of ['Content-Type', 'X-Scope-OrgID', 'Author', 'Keyword', 'Passthrough']) {
+      expect(isCredentialName(name)).toBe(false);
+    }
+  });
+});
+
+describe('literal credentials are found by where they sit', () => {
+  test('headers: a literal is refused; a secrets template, `{ fromEnv }` and `""` are not', () => {
+    expect(
+      literalCredentialHeaders({
+        'Content-Type': 'application/json',
+        Cookie: `session=${LITERAL}`,
+        'X-Api-Key': { fromEnv: 'HOOK_KEY' },
+        Authorization: `Bearer ${LITERAL}`,
+        'X-Auth-Token': '{{secrets.token}}',
+        'X-Empty-Token': '',
+      }),
+    ).toEqual(['Authorization', 'Cookie']);
+    expect(literalCredentialHeaders({ Authorization: 'Bearer {{ secrets.token }}' })).toEqual([]);
+    expect(literalCredentialHeaders(undefined)).toEqual([]);
+  });
+
+  test('a URL: a userinfo password and credential-named query parameters, by name', () => {
+    expect(literalCredentialsInUrl(`https://pbs:${LITERAL}@am.example.com/x`)).toEqual([
+      'userinfo',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}?token=${LITERAL}&team=ops&api_key=${LITERAL}`)).toEqual([
+      '?token',
+      '?api_key',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}?code=${LITERAL}#token=${LITERAL}`)).toEqual([
+      '?code',
+      '?token',
+    ]);
+    expect(literalCredentialsInUrl(`${AM}#team=ops&sig=${LITERAL}`)).toEqual(['?sig']);
+  });
+
+  test('a URL that references its secrets, or has no password, is clean', () => {
+    for (const url of [
+      AM,
+      `${AM}?team=ops`,
+      `${AM}?token={{ url-encode secrets.token }}`,
+      'https://pbs:{{ secrets.pw }}@am.example.com/',
+      'https://pbs@am.example.com/',
+      `${AM}?token=`,
+      undefined,
+    ]) {
+      expect(literalCredentialsInUrl(url)).toEqual([]);
+    }
+  });
+
+  test('refusals name the header or the URL part — never the value', () => {
+    const reasons = refusals(
+      hook({ header: { Authorization: `Bearer ${LITERAL}` }, url: `${AM}?token=${LITERAL}` }),
+    );
+    expect(reasons).toHaveLength(2);
+    expect(reasons[0]).toStartWith("header 'Authorization' holds a literal credential");
+    expect(reasons[1]).toStartWith("'url' ?token holds a literal credential");
+    expect(reasons.join(' ')).not.toContain(LITERAL);
+  });
+});
+
+describe('through Alchemy: refused at plan, before anything is stored or sent', () => {
+  const run = async (props: PbsNotificationTargetProps) => {
+    const fake = fakeNotify();
+    let failure = '';
+    let stored = '';
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      await engine.deploy(PbsNotificationTarget('alertmanager', props)).catch((error: unknown) => {
+        failure = String(error);
+      });
+      stored = engine.stored();
+    });
+    return { failure, stored, writes: fake.writes() };
+  };
+
+  test('a literal Authorization header on a NEW target never reaches the store', async () => {
+    const { failure, stored, writes } = await run(
+      hook({ header: { Authorization: `Bearer ${LITERAL}` } }),
+    );
+    expect(failure).toContain("header 'Authorization' holds a literal credential");
+    expect(stored).not.toContain(LITERAL);
+    expect(writes).toEqual([]);
+  });
+
+  test('a literal query token on a NEW target never reaches the store', async () => {
+    const { failure, stored, writes } = await run(hook({ url: `${AM}?token=${LITERAL}` }));
+    expect(failure).toContain("'url' ?token holds a literal credential");
+    expect(stored).not.toContain(LITERAL);
+    expect(writes).toEqual([]);
+  });
+
+  test('any other refusal on a new target also fails before the row is written', async () => {
+    const { failure, stored } = await run(hook({ comment: LITERAL, mailto: ['x@example.com'] }));
+    expect(failure).toContain("'mailto' belongs to sendmail/smtp targets, not webhook");
+    expect(stored).not.toContain(LITERAL);
+  });
+});