@homeflare/alchemy 0.12.0 → 0.14.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/docs/repo-policy-ruleset-hazards.md

@@ -0,0 +1,65 @@
+# `declareRepoPolicy` — the ruleset half's hazards
+
+Everything here is about `GitHub.Ruleset` in `alchemy@2.0.0-beta.79`, not about the
+policy this kit declares. It is extracted from [repo-policy.md](./repo-policy.md) so the
+reasoning stays whole rather than being shaved to fit a line cap.
+
+⚠️ **`GitHub.Repository` shares none of it.** Its `reconcile` probes by name, converges
+onto whatever is live, and `PATCH`es only the fields it holds. The two halves of the
+helper fail differently, which is the whole reason this file exists.
+
+## ⛔ The ruleset cannot be adopted — it duplicates
+
+Read out of `alchemy@2.0.0-beta.79`'s own source on 2026-09-22
+(`node_modules/alchemy/lib/github/Ruleset.js`):
+
+- `read` returns `undefined` whenever there is no prior `output`. Alchemy's adoption
+  routes on what `read` reports, so with no state the engine plans a **create**.
+- `reconcile` looks the live ruleset up **only by the id in that output**. With none, it
+  calls `createRepoRuleset` unconditionally — it never searches by name.
+
+GitHub permits several rulesets with the same name on one repository, so nothing errors.
+The repository quietly ends up with **two `main` rulesets, both enforcing**, and the
+second one is the only one Alchemy will ever converge.
+
+**Before the first deploy onto a repository that already has a ruleset:**
+
+```sh
+gh api repos/<owner>/<repo>/rulesets --jq '.[] | select(.target=="branch") | "\(.id) \(.name)"'
+```
+
+Delete the hand-made ruleset of the same name, or give this one a `rulesetName` of its
+own. After the first deploy the state carries the id and every later deploy converges
+that one ruleset.
+
+★ **Or take the repository half only.** `repoPolicy` returns the two prop objects
+separately, so a stack whose ruleset is already owned by something else can declare the
+settings that adopt cleanly and leave the ruleset alone:
+
+```ts
+yield * GitHub.Repository('api', repoPolicy({ owner, repository, checks }).repository);
+```
+
+⚠️ **`GitHub.Repository` does not share the problem.** Its `reconcile` probes by name and
+converges onto whatever is live, so the repository half adopts cleanly on the first
+deploy even though the plan prints `create`. The two halves of this helper fail
+differently, which is exactly why it is worth writing down.
+
+⛔ **The ruleset half never plans a no-op — measured, not inferred.** Alchemy `deepEqual`s
+the live ruleset against the parameters **it** builds, and it builds a strict subset of
+what GitHub stores. Read live on 2026-09-22 from this repo's own ruleset, GitHub returns
+`required_status_checks.parameters.do_not_enforce_on_create: false` and, on a
+`pull_request` rule, `required_reviewers`, `allowed_merge_methods` and
+`require_extra_approval_for_unattributed_changes` — none of which Alchemy sends. The
+comparison is therefore unequal **forever**, and every deploy issues an idempotent
+`updateRepoRuleset`. It is convergence noise, not drift: the write is the same payload
+each time. But do not expect a clean plan, and do not read the write as a change.
+
+⛔ **The ruleset's `rules` and `bypass_actors` are replaced wholesale, not merged.**
+Alchemy sends the full desired list. Any rule type this helper does not express —
+`creation`, `update`, `required_linear_history`, `required_signatures`,
+`required_deployments`, tag and file-path rules — is **dropped** from a ruleset Alchemy
+owns, as is any bypass actor added by hand. Because the ruleset cannot be adopted this
+cannot wipe a pre-existing one on a first deploy; it bites on a ruleset Alchemy created
+that someone later edited in the GitHub UI. The repository half does not behave this way:
+Alchemy `PATCH`es only the fields it holds, so settings outside `settings` are untouched.

package/docs/repo-policy.md

@@ -0,0 +1,155 @@
+# Repository policy
+
+One call that declares a GitHub repository's merge policy and the ruleset that enforces
+it: squash-only merges, auto-merge on, head branches deleted, and a ruleset over the
+default branch that blocks deletion and force pushes and requires the checks you name.
+
+```ts
+import { declareRepoPolicy } from '@homeflare/alchemy/github';
+import * as Effect from 'effect/Effect';
+
+Effect.gen(function* () {
+  // policy.repository → GitHub.Repository, policy.ruleset → GitHub.Ruleset
+  const policy = yield* declareRepoPolicy('api', {
+    owner: 'my-org',
+    repository: 'api',
+    checks: ['ci', 'secret scan'],
+  });
+});
+```
+
+Provide `GitHub.providers()`. This subpath ships **no provider of its own** — everything
+here composes Alchemy's first-class `GitHub.Repository` and `GitHub.Ruleset`.
+
+`repoPolicy(options)` is the same thing without the resources: the two prop objects, pure,
+for a test or for a stack that wants to declare them itself.
+
+## What it declares
+
+| where               | property                                 | value           |
+| ------------------- | ---------------------------------------- | --------------- |
+| `GitHub.Repository` | `allowSquashMerge`                       | `true`          |
+| `GitHub.Repository` | `allowMergeCommit`, `allowRebaseMerge`   | `false`         |
+| `GitHub.Repository` | `allowAutoMerge`                         | `autoMerge`     |
+| `GitHub.Repository` | `deleteBranchOnMerge`                    | `true`          |
+| `GitHub.Ruleset`    | `conditions.include`                     | `include`       |
+| `GitHub.Ruleset`    | `rules.deletion`, `rules.nonFastForward` | `true`          |
+| `GitHub.Ruleset`    | `rules.requiredStatusChecks.checks`      | `checks`        |
+| `GitHub.Ruleset`    | `strictRequiredStatusChecksPolicy`       | always `false`  |
+| `GitHub.Ruleset`    | `bypassActors`                           | `[]` by default |
+| `GitHub.Ruleset`    | `rules.pullRequest`                      | only if asked   |
+
+Everything about the repository that is **not** merge policy — description, topics,
+visibility, `hasWiki` — goes in `settings` and is merged underneath. ⛔ The policy fields
+are spread after it, and `RepoPolicyRepositorySettings` omits them, so `settings` cannot
+re-open a merge method through the back door.
+
+⛔ **`baseUrl` is a top-level option, not a `settings` field.** GitHub Enterprise has to
+apply to both resources or to neither; setting it on one would leave the repository on an
+Enterprise host and its ruleset on github.com.
+
+## ⛔ Auto-merge with nothing required merges immediately
+
+`gh pr merge --auto` reads like a queue. It is one **only while something is
+outstanding**. With no required status check and no required review pending, GitHub
+merges the pull request on the spot — the flag does not wait for CI that was never
+required to start.
+
+So `repoPolicy` refuses `autoMerge` whenever the ruleset would not hold anything back.
+⛔ **Five different inputs produce "nothing outstanding", and all five are refused:**
+
+| input                                     | why it merges anyway                                          |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| no `checks` and no `requiredApprovals`    | nothing is pending, so `--auto` merges now                    |
+| `enforcement: 'disabled'` / `'evaluate'`  | the rules are listed and none of them block — the quiet door  |
+| `include: []`                             | the ruleset matches no ref; GitHub still shows it as `active` |
+| a blank ref pattern, e.g. `include: ['']` | length is not coverage — matches no ref, past the guard       |
+| `exclude` cancelling every `include`      | exclusions win; reads as a narrowing, acts as an off switch   |
+
+★ The last two were found by adversarial review after the first cut shipped. The guard
+counted the array and spread `exclude` raw, so `include: ['   ']` and
+`include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` both produced an active
+ruleset over nothing with `allowAutoMerge: true` — the same end state the empty-array
+guard exists to prevent, through the door beside it.
+
+⚠️ **Exact cancellation only.** Deciding in general whether a glob `exclude` swallows an
+`include` means reimplementing GitHub's matcher and being quietly wrong about it. The
+helper refuses the decidable case — every `include` pattern appearing verbatim in
+`exclude` — and leaves `exclude: ['refs/heads/*']` to the operator.
+
+⚠️ **`bypassActors` is not checked against `autoMerge`, and is `[]` by default.** An actor
+you add can bypass the required checks; whether GitHub's auto-merge then lands the pull
+request on red was not measured here. Add bypass actors deliberately.
+
+⚠️ The test is "nothing outstanding", not "no checks" — a required review holds the pull
+request open just as a required check does, so `requiredApprovals` with an empty `checks`
+is allowed.
+
+A repository that has no green run to require yet is a real state; say so explicitly:
+
+```ts
+declareRepoPolicy('new-repo', { owner, repository, checks: [], autoMerge: false });
+```
+
+The branch is still protected — deletion and force pushes are blocked either way. Turn
+`autoMerge` and `checks` on together once there is a green run to name.
+
+## ⛔ Every context in `checks` must always report
+
+A required context that never reports is not "passed", it is **pending**, and the pull
+request waits on it forever — auto-merge included, which is the failure that looks like
+the tool being broken.
+
+Name an aggregate job that runs `if: always()` and fails when any upstream job did. Do
+not name a job behind a `paths:` filter, a matrix leg, or anything a skipped workflow can
+silence. Contexts are trimmed, de-duplicated and **sorted**, so writing the same two the
+other way round is not a diff.
+
+## ⛔ The ruleset half has hazards of its own
+
+The vendor `Ruleset` **cannot be adopted** — a first deploy onto a repository that
+already has a ruleset of that name creates a **second** one beside it, both enforcing —
+it **never plans a no-op**, and it replaces its `rules` and `bypass_actors` **wholesale**.
+None of that applies to the repository half.
+
+⛔ Read [repo-policy-ruleset-hazards.md](./repo-policy-ruleset-hazards.md) before the
+first deploy. It carries the preflight `gh api repos/<owner>/<repo>/rulesets` command and
+the repository-half-only escape hatch.
+
+## Required reviews are opt-in, and `0` is refused
+
+Omit `requiredApprovals` and no `pull_request` rule is declared at all — the house
+default, where a pull request is gated by its checks.
+
+`requiredApprovals: 2` declares the rule, with stale reviews dismissed on push.
+
+⛔ `requiredApprovals: 0` is **refused**, not treated as "no reviews". Zero approvals is
+the solo-maintainer shape — every change through a pull request, no second person — and
+it works only with `require_extra_approval_for_unattributed_changes: false`. Alchemy's
+`Ruleset` has no property for that field, and GitHub defaults it to `true` when it is
+omitted (measured 2026-09-17), which blocks the very pull requests the zero was meant to
+let through. Accepting it would ship a rule that does the opposite of what it says.
+
+## ★ `strict` is always off, and is not a parameter
+
+"Require branches to be up to date before merging" means every merge to the default
+branch invalidates every other open pull request. With auto-merge on, that is a re-run
+storm that settles only when the queue empties. The checks still have to pass; they just
+do not have to have passed against the very tip.
+
+## ★ `~DEFAULT_BRANCH`, not `refs/heads/main`
+
+`include` defaults to `['~DEFAULT_BRANCH']`, which GitHub resolves per repository. One
+policy covers a repo whose default branch is `master` or `trunk`, and renaming the
+default branch later does not leave the ruleset pointing at a branch that no longer
+exists. Pass your own `include`/`exclude` for anything else.
+
+## ★ Both resources retain
+
+`retain` is already the vendor default for `Repository` and `Ruleset`. The helper pipes
+it anyway, so that a vendor change cannot quietly turn "drop this call from the stack"
+into "delete the repository" or "unprotect the default branch". Opt into deletion with
+`RemovalPolicy.destroy()` at the call site if you really mean it.
+
+`adopt: true` / `adopt: false` pipe Alchemy's adopt policy onto both resources; omitted,
+the deploy's own policy decides. ⚠️ It changes nothing about the ruleset hazard above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -36,6 +36,10 @@
       "types": "./dist/forgejo/index.d.ts",
       "default": "./dist/forgejo/index.js"
     },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "default": "./dist/github/index.js"
+    },
     "./openbao": {
       "types": "./dist/openbao/index.d.ts",
       "default": "./dist/openbao/index.js"

package/src/github/index.ts

@@ -0,0 +1,23 @@
+/**
+ * GitHub helpers for Alchemy — one repository's house policy in one call.
+ *
+ * ⛔ THIS SUBPATH SHIPS NO PROVIDER, AND DELIBERATELY SO. GitHub is first-class in
+ *   Alchemy; everything here composes the vendor's own `Repository` and `Ruleset`.
+ *   Provide `GitHub.providers()` exactly as you would without it.
+ * ★ WHY IT EXISTS ANYWAY. "Open a pull request, let auto-merge land it" is safe only when
+ *   five repository properties and four ruleset rules all agree, and every way of getting
+ *   one of them wrong is silent — an auto-merge that lands on red, a force push that
+ *   rewrites the branch a release tagged, a required context nothing ever reports. One
+ *   call puts the whole policy in one place, and one place is where it gets fixed.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API. `repo-policy-form.ts` is reachable by path if you
+ *   genuinely need an internal — a deliberate act rather than an accident of barrelling.
+ */
+export {
+  type RepoPolicy,
+  type RepoPolicyBypassActor,
+  type RepoPolicyOptions,
+  type RepoPolicyRepositorySettings,
+  repoPolicy,
+} from './repo-policy-form.ts';
+export { type DeclareRepoPolicyOptions, declareRepoPolicy } from './repo-policy.ts';