@homeflare/alchemy 0.11.0 → 0.13.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/notification-target.ts

@@ -39,8 +39,9 @@
  *     reconcile  POST + PUT                   Mapping.Modify on /mapping/notifications AND one of
  *                                             Sys.Audit / Sys.Modify / Sys.AccessNetwork on /
  *     delete     DELETE                       Mapping.Modify on /mapping/notifications
- *   `LXCProvisioner` already carries Sys.Audit on `/` (see lxc.ts), so the delta is the two Mapping
- *   privileges — notably NOT the `Sys.Modify` a backup job costs.
+ *   The provision role already carried Sys.Audit on `/` (see lxc.ts), so the delta was the two
+ *   Mapping privileges — notably NOT the `Sys.Modify` a backup job costs. `PROVISION_PRIVILEGES`
+ *   carries both on `/`: the baseline took the trade below knowingly.
  *   ⚠️ PREFER A SECOND ROLE GRANTED AT `/mapping/notifications` OVER WIDENING THE PROVISIONING ROLE
  *     ON `/`. `/mapping` also holds the PCI and USB passthrough maps, so Mapping.Modify at the root
  *     lets a credential scoped to make containers rewire somebody's hardware.

package/src/proxmox/pbs-datastore-guard.ts

@@ -54,7 +54,7 @@ export const guardPath = (live: PbsDatastoreAttributes, props: PbsDatastoreProps
  *
  * ⚠️ AN UNDECLARED `backend` IS NOT A DIVERGENCE. Undeclared is unmanaged everywhere in this
  *   family, and this guard keeps that rule: it fires only when the declaration says something and
- *   PBS says something else. Adopting `r2-offsite` without mentioning `backend` still plans noop.
+ *   PBS says something else. Adopting `offsite` without mentioning `backend` still plans noop.
  *
  * ⚠️ COMPARED AS A CANONICAL PROPERTY STRING, so `bucket=x,type=s3` and `type=s3,bucket=x` are the
  *   same backend and key order cannot deadlock a plan — the reason `samePath` trims a slash.

package/src/proxmox/pbs-datastore.ts

@@ -10,7 +10,7 @@
  *   `{"data":{"pong":true}}` against a Let's Encrypt certificate for CN=pbs.example.com;
  *   `/version` and `/config/datastore` answer 401 "authentication failed";
  *   `pbs.mgmt.example.com:8007` answers 401 and its certificate verifies too; and
- *   `/access/domains` lists the realms `pbs`, `pam` and an openid realm `Schenanigans`. So the
+ *   `/access/domains` lists the realms `pbs`, `pam` and an openid realm. So the
  *   prefix, the `{"data": …}` envelope and the strict-TLS story are PVE's exactly — and only the
  *   credential differs. There is no `pve` realm here; a PVE token cannot authenticate at all.
  *   The header differs too, which is why `pve()` exists rather than `pve()` being reused — see the
@@ -18,18 +18,18 @@
  *
  * ⛔ THERE IS NO OPENBAO MOUNT FOR PBS TODAY, SO NOTHING HERE CAN DEPLOY YET. `PbsTarget.mount` is
  *   a parameter for the reason `PveTarget.mount` is — the provider must be able to leave this
- *   estate — but the estate has nothing to put in it. MEASURED: under the `claude-code` approle,
- *   `bao token capabilities` answers `deny` for `proxmox-tb4/creds/{read,provision}`,
- *   `proxmox-ops/creds/read` and every `…pbs…` path tried, and `sys/mounts` is 403 — so I could
+ *   estate — but the estate has nothing to put in it. MEASURED: under the agent's approle,
+ *   `bao token capabilities` answers `deny` for `proxmox-c1/creds/{read,provision}`,
+ *   `proxmox-c2/creds/read` and every `…pbs…` path tried, and `sys/mounts` is 403 — so I could
  *   not enumerate the mounts to PROVE a PBS one is absent. That it is absent is the brief's
  *   statement, not my measurement.
  *   ★ WHAT THE MOUNT MUST VEND, so `mint()` is reused unchanged: `bao read -format=json
  *     <mount>/creds/<role>` answering `{"data":{"token_id":…,"secret":…}}`, where `token_id` is a
  *     PBS token id `user@realm!tokenname` — `hf-read@pbs!…` and `hf-provision@pbs!…`. Same short,
- *     non-renewable lease contract as `proxmox-tb4`.
+ *     non-renewable lease contract as `proxmox-c1`.
  *   ⚠️ PBS HAS NO DYNAMIC-SECRETS PLUGIN OF ITS OWN — OpenBao's Proxmox support is a PVE thing — so
  *     the mount is a small custom vendor against `POST /access/users/{id}/token/{name}`. Say which
- *     mount and role you needed rather than reaching for the read-only `monitoring@pbs` token on
+ *     mount and role you needed rather than reaching for the read-only `metrics@pbs` token on
  *     the kv shelf: widening that would delete the outer lock for every reader of the shelf.
  *
  * ⛔ A DATASTORE HOLDS THE BACKUPS, SO `retain` IS THE DEFAULT AND `delete` IS FULLY IMPLEMENTED —
@@ -47,7 +47,7 @@
  * ⛔ NO SECRET IS A PROP OR AN ATTRIBUTE, AND THIS FAMILY IS CLEAN BY CONSTRUCTION: a datastore
  *   section holds no password, token or key — encryption keys belong to the backup CLIENT. Every
  *   field below is a name, a path, a schedule, a count or a policy string, all of which are safe in
- *   a state store Alchemy writes UNENCRYPTED and this estate dumps to CT100 nightly.
+ *   a state store Alchemy writes UNENCRYPTED and this estate copies to a backup guest nightly.
  */
 import { Resource } from 'alchemy';
 import { isResolved } from 'alchemy/Diff';
@@ -131,11 +131,11 @@ export interface PbsDatastoreProps {
    *   `datastore create --help` offers `--backend`, `datastore update --help` does NOT, and
    *   `backend` is absent from update's `--delete` enum. PBS will not move a datastore between
    *   local disk and object storage, ever.
-   * ★ IT IS A PROP AT ALL BECAUSE THE ESTATE HAS ONE. `r2-offsite` holds
-   *   `type=s3,client=cloudflare-r2,bucket=homeflare-pbs`. Leaving it undeclared would still plan
+   * ★ IT IS A PROP AT ALL BECAUSE THE ESTATE HAS ONE. `offsite` holds
+   *   `type=s3,client=cloudflare-r2,bucket=example-pbs`. Leaving it undeclared would still plan
    *   noop — undeclared is unmanaged here — but the declaration would then describe a LOCAL
    *   datastore, and anyone recreating from it would get exactly that: an empty directory on the
-   *   mini's disk where the offsite copy used to be, behind a green plan the whole way.
+   *   host's disk where the offsite copy used to be, behind a green plan the whole way.
    * ⚠️ A property string. Compared canonically, so key order is never a diff.
    */
   backend?: string;