@homeflare/alchemy 0.12.0 → 0.14.0

package/src/proxmox/notification-matcher-form.ts

@@ -0,0 +1,221 @@
+/**
+ * A notification matcher — the rule that routes a notification to its targets — as ONE shape
+ * shared by PVE (`Proxmox.NotificationMatcher`) and PBS (`Pbs.NotificationMatcher`).
+ *
+ * ★ ONE FILE FOR BOTH PRODUCTS BECAUSE IT IS ONE IMPLEMENTATION. Both servers run the same Rust
+ *   crate, `proxmox-notify` (matcher.rs), PVE through its Perl bindings; the schemas in
+ *   generated/pve.ts and generated/pbs.ts carry the same nine fields, and the forms below are
+ *   typed against BOTH, so a drift on either side fails `tsc` here rather than on a server.
+ *
+ * ⚠️ A MATCHER IS ITS WHOLE RULE, SO EVERY RULE FIELD IS COMPARED, DECLARED OR NOT. Most families
+ *   here leave an undeclared field alone (backup-job.ts's trade). A matcher cannot: an undeclared
+ *   `match-field` on a matcher that has one is a declaration claiming "route everything" over a
+ *   server that routes one job type — and `invert-match` flips the meaning of every other line.
+ *   So `match-*` default to empty, `mode` to `all`, `invert-match` and `disable` to false, all are
+ *   compared, and a PUT sends all of them (an emptied list as `delete`). Only `comment` keeps the
+ *   usual "undeclared is unmanaged" rule, because nothing routes on it.
+ *   ★ THE COST IS THAT ADOPTING A MATCHER MEANS DECLARING IT AS IT IS. PBS ships `default-matcher`
+ *     with `invert-match`, a `match-field` and a `match-severity` (measured on PBS 4.2, 2026-09-22),
+ *     so adopting it as-is means writing those three down. A declaration that leaves them out
+ *     plans an UPDATE, which is the plan telling the truth about what the deploy would do.
+ */
+import type {
+  ClusterNotificationsMatchersNamePutParams,
+  ClusterNotificationsMatchersPostParams,
+} from './generated/pve.ts';
+import type {
+  ConfigNotificationsMatchersNamePutParams,
+  ConfigNotificationsMatchersPostParams,
+} from './generated/pbs.ts';
+import { bool, text } from './values.ts';
+
+/** Everything a matcher declares except where it lives — the resource files add `target`. */
+export interface NotificationMatcherFields {
+  /** The primary key, a safe id (2–32 chars on PBS). Changing it is a replace. */
+  name: string;
+  /**
+   * ⛔ THE TARGETS, BY NAME, AND REQUIRED: a matcher that notifies nobody is a routing rule for
+   *   silence. `[]` is still declarable, and clears the list.
+   * ⚠️ `targets`, NOT THE SERVER'S `target`: every resource here already spends `target` on the
+   *   HOST (resource.ts `WithTarget`), and one key cannot mean both. The wire still says `target`.
+   */
+  targets: readonly string[];
+  /**
+   * Severity rules. EACH ITEM IS ITSELF A COMMA LIST: `'warning,error'` matches either.
+   * ⛔ `['warning', 'error']` IS NOT THE SAME RULE AND UNDER `mode: 'all'` NEVER MATCHES. Items are
+   *   combined with `mode`; the severities inside one item are always OR-ed (matcher.rs
+   *   `SeverityMatcher`). A notification has one severity, so two items under AND ask for a
+   *   notification that is both — and routing nothing is the quietest failure a matcher has.
+   * Severities: `info`, `notice`, `warning`, `error`, `unknown`.
+   */
+  'match-severity'?: readonly string[];
+  /**
+   * Metadata rules, `exact:<field>=<v1>,<v2>` or `regex:<field>=<re>`. ⚠️ THE PREFIX IS REQUIRED:
+   * the schema's pattern makes it optional and the parser then refuses it. A notification WITHOUT
+   * the field never matches its rule — so `exact:job-id=…` excludes every garbage collection.
+   */
+  'match-field'?: readonly string[];
+  /** Time windows, e.g. `mon-fri 9:00-17:00`. Compared as written; the server keeps the text. */
+  'match-calendar'?: readonly string[];
+  /** How the rule items combine. The server's default, and this package's, is `all`. */
+  mode?: 'all' | 'any';
+  /** Invert the whole rule. ⚠️ IGNORED WHEN THERE ARE NO RULES — an empty matcher always matches. */
+  'invert-match'?: boolean;
+  /** A disabled matcher routes nothing. */
+  disable?: boolean;
+  /** Free text. The one field left alone when undeclared; `''` clears it. */
+  comment?: string;
+}
+
+/** ⚠️ Lists are CANONICAL and SORTED, so a re-ordered declaration is not a diff. */
+export interface NotificationMatcherAttributes {
+  name: string;
+  /**
+   * `builtin`, `modified-builtin` or `user-created`. REPORTED, NEVER COMPARED.
+   * ⛔ ON A BUILT-IN A DELETE REVERTS RATHER THAN REMOVES, and reports success either way — Alchemy
+   *   drops the row while `default-matcher` goes on routing. Read this before destroying one.
+   * ★ MEASURED ON THE PER-OBJECT READ, which the published schema does not list: PVE 9.2.11 and
+   *   PBS 4.2 both return it from `…/matchers/default-matcher` (2026-09-22).
+   */
+  origin: string;
+  comment: string;
+  disable: boolean;
+  'invert-match': boolean;
+  mode: string;
+  targets: readonly string[];
+  'match-severity': readonly string[];
+  'match-field': readonly string[];
+  'match-calendar': readonly string[];
+}
+
+const list = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.map((item: unknown) => String(item)) : [];
+
+/** Trimmed items, empty ones dropped. */
+const items = (values: readonly string[], canonical: (item: string) => string): string[] =>
+  values.map((item) => canonical(item.trim())).filter((item) => item !== '');
+
+/**
+ * ⚠️ THE SERVER WRITES A RULE BACK IN ITS OWN SPELLING, SO BOTH SIDES ARE SPELLED ITS WAY FIRST.
+ *   matcher.rs parses `exact:type=gc, verify` into values and `Display`s them joined by a bare
+ *   comma; a severity item is split, trimmed and re-joined the same way. Without this a
+ *   declaration with a space after a comma would plan an update forever.
+ */
+const severity = (item: string): string =>
+  item
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .sort()
+    .join(',');
+
+const field = (item: string): string => {
+  if (!item.startsWith('exact:')) return item;
+  const at = item.indexOf('=');
+  if (at < 0) return item;
+  const values = item.slice(at + 1).split(',');
+  return `${item.slice(0, at)}=${values.map((value) => value.trim()).join(',')}`;
+};
+
+const same = (item: string): string => item;
+
+/** A declaration's lists, canonical and sorted — the form `matches` compares. */
+export const canonicalRules = (fields: NotificationMatcherFields) => ({
+  'match-calendar': items(fields['match-calendar'] ?? [], same).sort(),
+  'match-field': items(fields['match-field'] ?? [], field).sort(),
+  'match-severity': items(fields['match-severity'] ?? [], severity).sort(),
+  targets: items(fields.targets, same).sort(),
+});
+
+export const matcherAttributes = (
+  live: Record<string, unknown>,
+  name: string,
+): NotificationMatcherAttributes => ({
+  comment: text(live['comment']),
+  disable: bool(live['disable']),
+  'invert-match': bool(live['invert-match']),
+  'match-calendar': items(list(live['match-calendar']), same).sort(),
+  'match-field': items(list(live['match-field']), field).sort(),
+  'match-severity': items(list(live['match-severity']), severity).sort(),
+  // ⚠️ ABSENT IS `all` — matcher.rs `mode.unwrap_or_default()`, and `All` is the default variant.
+  mode: text(live['mode'], 'all') || 'all',
+  name,
+  origin: text(live['origin']),
+  targets: items(list(live['target']), same).sort(),
+});
+
+const equal = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((item, index) => item === b[index]);
+
+export const matcherMatches = (
+  attributes: NotificationMatcherAttributes,
+  fields: NotificationMatcherFields,
+): boolean => {
+  const rules = canonicalRules(fields);
+  return (
+    attributes.disable === (fields.disable === true) &&
+    attributes['invert-match'] === (fields['invert-match'] === true) &&
+    attributes.mode === (fields.mode ?? 'all') &&
+    equal(attributes.targets, rules.targets) &&
+    equal(attributes['match-severity'], rules['match-severity']) &&
+    equal(attributes['match-field'], rules['match-field']) &&
+    equal(attributes['match-calendar'], rules['match-calendar']) &&
+    (fields.comment === undefined || attributes.comment === fields.comment)
+  );
+};
+
+type Deletable = NonNullable<ConfigNotificationsMatchersNamePutParams['delete']>[number];
+type Lists = 'match-calendar' | 'match-field' | 'match-severity' | 'target';
+
+/**
+ * The fields both forms send. ⚠️ LISTS GO AS ARRAYS — REPEATED KEYS ON THE WIRE (client.ts
+ * `encode`) — because every list here is `type: array` on both servers, and a comma inside a
+ * severity item or an `exact:` rule means a comma-joined string could not carry them anyway.
+ */
+const always = (fields: NotificationMatcherFields) => ({
+  disable: fields.disable === true ? ('1' as const) : ('0' as const),
+  'invert-match': fields['invert-match'] === true ? ('1' as const) : ('0' as const),
+  mode: fields.mode ?? ('all' as const),
+});
+
+const lists = (fields: NotificationMatcherFields): Partial<Record<Lists, readonly string[]>> => {
+  const rules = canonicalRules(fields);
+  const out: Partial<Record<Lists, readonly string[]>> = {};
+  if (rules['match-calendar'].length > 0) out['match-calendar'] = rules['match-calendar'];
+  if (rules['match-field'].length > 0) out['match-field'] = rules['match-field'];
+  if (rules['match-severity'].length > 0) out['match-severity'] = rules['match-severity'];
+  if (rules.targets.length > 0) out.target = rules.targets;
+  return out;
+};
+
+export type MatcherCreateForm = ConfigNotificationsMatchersPostParams &
+  ClusterNotificationsMatchersPostParams;
+export type MatcherUpdateForm = ConfigNotificationsMatchersNamePutParams &
+  ClusterNotificationsMatchersNamePutParams;
+
+/** ⛔ `name` is create-only: the body carries it once and the path forever after. */
+export const matcherCreateForm = (fields: NotificationMatcherFields): MatcherCreateForm => ({
+  ...always(fields),
+  ...lists(fields),
+  ...(fields.comment === undefined || fields.comment === '' ? {} : { comment: fields.comment }),
+  name: fields.name,
+});
+
+/**
+ * ⛔ AN EMPTIED LIST IS A `delete`, NOT AN EMPTY VALUE. A form cannot carry an empty array — no
+ *   key is sent at all — so without the `delete` entry a declaration of `'match-field': []`
+ *   would plan an update, PUT nothing for that field, and plan the same update forever.
+ */
+export const matcherUpdateForm = (fields: NotificationMatcherFields): MatcherUpdateForm => {
+  const present = lists(fields);
+  const cleared: Deletable[] = (
+    ['match-calendar', 'match-field', 'match-severity', 'target'] as const
+  ).filter((key) => present[key] === undefined);
+  if (fields.comment === '') cleared.push('comment');
+  return {
+    ...always(fields),
+    ...present,
+    ...(fields.comment === undefined || fields.comment === '' ? {} : { comment: fields.comment }),
+    ...(cleared.length === 0 ? {} : { delete: cleared }),
+  };
+};

package/src/proxmox/notification-matcher.test.ts

@@ -0,0 +1,234 @@
+/**
+ * `Proxmox.NotificationMatcher` and `Pbs.NotificationMatcher` — forms against the generated
+ * schemas, the canonical spellings, and both built-in `default-matcher`s adopted as they are.
+ *
+ * ★ THE LIVE FIXTURES ARE THE MEASURED ONES (2026-09-22): PVE 9.2.11 `pvesh get
+ *   /cluster/notifications/matchers/default-matcher` and PBS 4.2 `proxmox-backup-manager
+ *   notification matcher show default-matcher`, comment text shortened.
+ */
+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 { fakeNotify } from './fake-pbs-notify.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+import type {
+  ClusterNotificationsMatchersNamePutParams,
+  ClusterNotificationsMatchersPostParams,
+} from './generated/pve.ts';
+import type {
+  ConfigNotificationsMatchersNamePutParams,
+  ConfigNotificationsMatchersPostParams,
+} from './generated/pbs.ts';
+import {
+  ProxmoxNotificationMatcher,
+  ProxmoxNotificationMatcherProvider,
+} from './notification-matcher.ts';
+import {
+  type NotificationMatcherFields,
+  matcherAttributes,
+  matcherCreateForm,
+  matcherMatches,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationMatcherProvider,
+} from './pbs-notification-matcher.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const PVE_PATH = 'cluster/notifications/matchers/default-matcher';
+const PBS_PATH = 'config/notifications/matchers/default-matcher';
+
+/** ★ The live shape, `digest` included: the per-object GET carries one, the collection GET not. */
+const PVE_DEFAULT = {
+  comment: 'Route all notifications to mail-to-root',
+  digest: 'd1'.repeat(32), // placeholder; a real one is a sha256 of notifications.cfg
+  mode: 'all',
+  name: 'default-matcher',
+  origin: 'builtin',
+  target: ['mail-to-root'],
+};
+const PBS_DEFAULT = {
+  comment: 'Route everything but successful prune jobs',
+  'invert-match': true,
+  'match-field': ['exact:type=prune'],
+  'match-severity': ['info'],
+  mode: 'all',
+  name: 'default-matcher',
+  origin: 'builtin',
+  target: ['mail-to-root'],
+};
+
+const pbsDefault = (over: Partial<NotificationMatcherFields> = {}) =>
+  PbsNotificationMatcher('default-matcher', {
+    'invert-match': true,
+    'match-field': ['exact:type=prune'],
+    'match-severity': ['info'],
+    name: 'default-matcher',
+    target: PBS,
+    targets: ['mail-to-root'],
+    ...over,
+  });
+
+describe('forms are typed against BOTH generated schemas', () => {
+  const fields: NotificationMatcherFields = {
+    'match-severity': ['error'],
+    name: 'pager',
+    targets: ['hook'],
+  };
+
+  test('create and update assign to PVE and PBS params without a cast', () => {
+    const pveCreate: ClusterNotificationsMatchersPostParams = matcherCreateForm(fields);
+    const pbsCreate: ConfigNotificationsMatchersPostParams = matcherCreateForm(fields);
+    const pveUpdate: ClusterNotificationsMatchersNamePutParams = matcherUpdateForm(fields);
+    const pbsUpdate: ConfigNotificationsMatchersNamePutParams = matcherUpdateForm(fields);
+    expect(pveCreate).toEqual(pbsCreate);
+    expect(pveUpdate).toEqual(pbsUpdate);
+  });
+
+  test('would fail tsc if `name` were dropped from a create', () => {
+    // @ts-expect-error name is required on POST .../matchers
+    const bad: ConfigNotificationsMatchersPostParams = { target: ['hook'] };
+    expect('name' in bad).toBe(false);
+  });
+
+  test('create sends lists as lists and the three always-compared flags', () => {
+    expect(matcherCreateForm(fields)).toEqual({
+      disable: '0',
+      'invert-match': '0',
+      'match-severity': ['error'],
+      mode: 'all',
+      name: 'pager',
+      target: ['hook'],
+    });
+  });
+
+  test('update clears every emptied rule list with `delete`, and an empty comment too', () => {
+    expect(matcherUpdateForm({ ...fields, comment: '', 'match-severity': [] })).toEqual({
+      delete: ['match-calendar', 'match-field', 'match-severity', 'comment'],
+      disable: '0',
+      'invert-match': '0',
+      mode: 'all',
+      target: ['hook'],
+    });
+  });
+});
+
+describe('matches reads both sides in the server spelling', () => {
+  const live = matcherAttributes(
+    {
+      'match-field': ['exact:type=gc,verify'],
+      'match-severity': ['error,warning'],
+      target: ['b', 'a'],
+    },
+    'm',
+  );
+  const base: NotificationMatcherFields = { name: 'm', targets: ['a', 'b'] };
+
+  test('spaces after commas and list order are not a diff; absent mode is `all`', () => {
+    expect(
+      matcherMatches(live, {
+        ...base,
+        'match-field': ['exact:type=gc, verify'],
+        'match-severity': ['warning, error'],
+        mode: 'all',
+      }),
+    ).toBe(true);
+  });
+
+  test('an undeclared rule is compared as empty — a matcher is its whole rule', () => {
+    expect(matcherMatches(live, { ...base, 'match-severity': ['error,warning'] })).toBe(false);
+  });
+
+  test('invert-match, mode and disable are compared against their defaults', () => {
+    const rules = { 'match-field': ['exact:type=gc,verify'], 'match-severity': ['error,warning'] };
+    expect(matcherMatches(live, { ...base, ...rules })).toBe(true);
+    expect(matcherMatches(live, { ...base, ...rules, 'invert-match': true })).toBe(false);
+    expect(matcherMatches(live, { ...base, ...rules, mode: 'any' })).toBe(false);
+    expect(matcherMatches(live, { ...base, ...rules, disable: true })).toBe(false);
+  });
+});
+
+describe('adopting a built-in default-matcher as it is only reads', () => {
+  test('PVE: target and name, nothing else, is a noop with no write', async () => {
+    const fake = fakeNotify({ [PVE_PATH]: PVE_DEFAULT });
+    const declare = () =>
+      ProxmoxNotificationMatcher('default-matcher', {
+        name: 'default-matcher',
+        target: FAKE_TARGET,
+        targets: ['mail-to-root'],
+      });
+    await withoutBao(async () => {
+      const engine = engineOver(
+        ProxmoxNotificationMatcherProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      expect((await engine.verify(declare())).rows).toEqual([
+        expect.objectContaining({ diff: 'noop', ok: true }),
+      ]);
+      expect(Object.values(await engine.deploy(declare()))).toEqual(['adopted']);
+      expect((await engine.verify(declare(), { all: true })).rows[0]).toMatchObject({
+        diff: 'noop',
+      });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('PBS: its three rule fields declared is a noop with no write', async () => {
+    const fake = fakeNotify({ [PBS_PATH]: PBS_DEFAULT });
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationMatcherProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      expect((await engine.verify(pbsDefault())).rows).toEqual([
+        expect.objectContaining({ diff: 'noop', ok: true }),
+      ]);
+      await engine.deploy(pbsDefault());
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('PBS: leaving the rules out plans an update, and the PUT clears them by name', async () => {
+    const fake = fakeNotify({ [PBS_PATH]: PBS_DEFAULT });
+    const bare = () =>
+      pbsDefault({ 'invert-match': false, 'match-field': [], 'match-severity': [] });
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationMatcherProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      expect((await engine.verify(bare())).rows[0]).toMatchObject({ diff: 'update', ok: false });
+      await engine.deploy(bare());
+    });
+    expect(fake.writes()).toEqual([`PUT ${PBS_PATH}`]);
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.pairs).toContainEqual(['delete', 'match-field']);
+    expect(put?.pairs).toContainEqual(['delete', 'match-severity']);
+    expect(put?.pairs).toContainEqual(['invert-match', '0']);
+    expect(fake.objects.get(PBS_PATH)?.['match-field']).toBeUndefined();
+  });
+
+  test('PBS: a new matcher is POSTed with each list item as its own repeated key', async () => {
+    const fake = fakeNotify();
+    const pager = () =>
+      PbsNotificationMatcher('pager', {
+        'match-field': ['exact:type=gc,sync,verify'],
+        'match-severity': ['error'],
+        name: 'pager',
+        target: PBS,
+        targets: ['alertmanager', 'mail-to-root'],
+      });
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationMatcherProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      await engine.deploy(pager());
+      expect((await engine.verify(pager(), { all: true })).rows[0]).toMatchObject({ diff: 'noop' });
+    });
+    const post = fake.calls.find((call) => call.method === 'POST');
+    expect(post?.path).toBe('config/notifications/matchers');
+    expect(post?.pairs.filter(([key]) => key === 'target')).toEqual([
+      ['target', 'alertmanager'],
+      ['target', 'mail-to-root'],
+    ]);
+  });
+});

package/src/proxmox/notification-matcher.ts

@@ -0,0 +1,76 @@
+/**
+ * `Proxmox.NotificationMatcher` — which notifications a PVE cluster sends to which targets.
+ *
+ * ★ THE HALF OF THE NOTIFICATION SYSTEM notification-target.ts LEAVES OPEN. A target is where a
+ *   message CAN go; a matcher decides whether it DOES. A cluster ships one, `default-matcher`,
+ *   routing everything to `mail-to-root`, and a target no matcher names receives nothing — so a
+ *   declared webhook with no matcher is a delivery path that is never used, and looks finished.
+ *
+ * ★ ADOPTING THE BUILT-IN AS IT IS: declare what it holds and nothing more. MEASURED on PVE
+ *   9.2.11 (2026-09-22, `pvesh get /cluster/notifications/matchers/default-matcher`): mode `all`,
+ *   one target `mail-to-root`, no rules, the comment "Route all notifications to mail-to-root".
+ *   ```ts
+ *   ProxmoxNotificationMatcher('default-matcher', {
+ *     target: cluster, name: 'default-matcher', targets: ['mail-to-root'],
+ *   });
+ *   ```
+ *   That plans `noop` and deploys with no write (notification-matcher.test.ts). Leaving `comment`
+ *   out leaves it alone; every rule field is compared — notification-matcher-form.ts says why.
+ *
+ * ★ WHAT THIS NEEDS, READ OFF THE CLUSTER'S OWN SCHEMA (generated/pve.ts source, 9.2.11):
+ *     read      GET matchers/{name}   Mapping.Audit or Mapping.Modify on /mapping/notifications
+ *     write     POST, PUT, DELETE     Mapping.Modify on /mapping/notifications
+ *   The same pair as `Proxmox.NotificationTarget`, with that file's ⚠️ about granting it on `/`.
+ *   ⛔ `Mapping.Use` IS NOT ENOUGH, though the COLLECTION GET accepts it: the per-object read this
+ *     family makes lists only Audit and Modify (pve-manager API2/Cluster/Notifications.pm
+ *     `get_matcher`, read at HEAD 2026-09-22 — corrected here; PR 95 said Use sufficed).
+ *   ⛔ A MISSING READ PRIVILEGE LOOKS LIKE "ABSENT", not like a 403 — see the same file. For
+ *     `default-matcher` that turns an adoption into a planned CREATE that PVE refuses as a
+ *     duplicate: the noop below needs a read lease holding Mapping.Audit.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  type NotificationMatcherAttributes,
+  type NotificationMatcherFields,
+  matcherAttributes,
+  matcherCreateForm,
+  matcherMatches,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+
+export interface NotificationMatcherProps extends NotificationMatcherFields, WithTarget {}
+
+export interface ProxmoxNotificationMatcher extends Resource<
+  'Proxmox.NotificationMatcher',
+  NotificationMatcherProps,
+  NotificationMatcherAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ⚠️ NO `defaultRemovalPolicy: 'retain'`, for notification-target.ts's reason: a matcher holds no
+ *   data, and a plan line is the only warning a delete gets. On `default-matcher` the delete
+ *   REVERTS it to the shipped rule instead — see `origin` on the attributes.
+ */
+export const ProxmoxNotificationMatcher = Resource<ProxmoxNotificationMatcher>(
+  'Proxmox.NotificationMatcher',
+);
+
+const handlers = pveHandlers<NotificationMatcherProps, NotificationMatcherAttributes>({
+  attributes: (live, props) => matcherAttributes(live, props.name),
+  collection: () => 'cluster/notifications/matchers',
+  createForm: matcherCreateForm,
+  matches: matcherMatches,
+  path: (props) => `cluster/notifications/matchers/${props.name}`,
+  updateForm: matcherUpdateForm,
+});
+
+export const ProxmoxNotificationMatcherProvider = () =>
+  Provider.effect(
+    ProxmoxNotificationMatcher,
+    Effect.succeed(ProxmoxNotificationMatcher.Provider.of(handlers)),
+  );

package/src/proxmox/pbs-notification-matcher.ts

@@ -0,0 +1,81 @@
+/**
+ * `Pbs.NotificationMatcher` — which Proxmox Backup Server notifications reach which targets.
+ *
+ * ★ THIS IS WHERE A FAILED VERIFY, SYNC OR GARBAGE COLLECTION BECOMES A PAGE. pbs-verify-job.ts
+ *   explains why verification is the only thing that notices rotten chunks; a matcher is what
+ *   turns what it notices into a message. Route `match-severity: ['error']` to a webhook target
+ *   (pbs-notification-target.ts, docs/pbs-notifications.md) and a failure pages someone.
+ *
+ * ⛔ A DATASTORE IN `legacy-sendmail` MODE BYPASSES EVERY MATCHER. PBS reads the datastore's
+ *   `notification-mode` before it builds anything (src/server/notifications/mod.rs
+ *   `lookup_datastore_notify_settings`, read at HEAD 2026-09-22): `legacy-sendmail` mails the
+ *   `notify-user` directly and never consults a matcher. The default is `notification-system`
+ *   today (pbs-api-types `NotificationMode`), but a datastore created before PBS 3.2 may say
+ *   `legacy-sendmail` explicitly. `Pbs.Datastore` deliberately does not declare the mode (see
+ *   `notify` in pbs-datastore.ts), so check it by hand before trusting a matcher with a datastore:
+ *   `proxmox-backup-manager datastore show <name>`.
+ *
+ * ⚠️ THE EVENT `type` FOR A VERIFICATION JOB IS `verify`, NOT `verification`. PBS's own
+ *   notifications chapter lists `verification` in its event table and `verify` in its example,
+ *   and the source settles it: `send_verify_status` sets `("type", "verify")` (same file). A
+ *   `match-field: ['exact:type=verification']` rule matches nothing, silently.
+ *   Types at HEAD: `gc`, `prune`, `sync`, `verify`, `tape-backup`, `tape-load`,
+ *   `package-updates`, `acme`, `thresholds`, `system-mail`. GC carries `datastore` and `hostname`
+ *   but NO `job-id`; prune, sync and verify carry all three; the UI's "Test" carries no fields.
+ *
+ * ★ ADOPTING THE BUILT-IN AS IT IS. MEASURED on PBS 4.2 (2026-09-22, `proxmox-backup-manager
+ *   notification matcher show default-matcher`): it routes everything EXCEPT successful prune
+ *   jobs to `mail-to-root` — `invert-match` over `exact:type=prune` AND severity `info`:
+ *   ```ts
+ *   PbsNotificationMatcher('default-matcher', {
+ *     target: pbs, name: 'default-matcher', targets: ['mail-to-root'],
+ *     'invert-match': true, 'match-field': ['exact:type=prune'], 'match-severity': ['info'],
+ *   });
+ *   ```
+ *
+ * ★ WHAT THIS NEEDS, READ OFF THE SERVER'S SCHEMA (generated/pbs.ts source):
+ *     read      GET                 Sys.Audit  on /system/notifications
+ *     write     POST, PUT, DELETE   Sys.Modify on /system/notifications
+ *   ⚠️ NOT A DATASTORE PRIVILEGE. A PBS credential scoped to `/datastore/...` reads every matcher
+ *     as absent — the "absent, then already exists" signature notification-target.ts describes.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  type NotificationMatcherAttributes,
+  type NotificationMatcherFields,
+  matcherAttributes,
+  matcherCreateForm,
+  matcherMatches,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { type PveRequirements, type WithPbsTarget, pveHandlers } from './resource.ts';
+
+export interface PbsNotificationMatcherProps extends NotificationMatcherFields, WithPbsTarget {}
+
+export interface PbsNotificationMatcher extends Resource<
+  'Pbs.NotificationMatcher',
+  PbsNotificationMatcherProps,
+  NotificationMatcherAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ⚠️ No `retain`, for notification-matcher.ts's reason; a built-in REVERTS on delete. */
+export const PbsNotificationMatcher = Resource<PbsNotificationMatcher>('Pbs.NotificationMatcher');
+
+const handlers = pveHandlers<PbsNotificationMatcherProps, NotificationMatcherAttributes>({
+  attributes: (live, props) => matcherAttributes(live, props.name),
+  collection: () => 'config/notifications/matchers',
+  createForm: matcherCreateForm,
+  matches: matcherMatches,
+  path: (props) => `config/notifications/matchers/${props.name}`,
+  updateForm: matcherUpdateForm,
+});
+
+export const PbsNotificationMatcherProvider = () =>
+  Provider.effect(
+    PbsNotificationMatcher,
+    Effect.succeed(PbsNotificationMatcher.Provider.of(handlers)),
+  );