@homeflare/alchemy 0.12.0 → 0.13.0

package/src/proxmox/pbs-notification-target-wire.ts

@@ -0,0 +1,112 @@
+/**
+ * How a PBS notification target looks on the wire, and what of it may be remembered.
+ *
+ * ★ SPLIT OUT OF pbs-notification-target.ts FOR THE 250-LINE CAP, on the seam
+ *   notification-target-form.ts cut for PVE: the resource file says what a target IS and when it
+ *   changed; this file turns a live answer into attributes and a value into a wire item. The
+ *   `import type` back is erased, so the cycle is on paper only.
+ *
+ * ⛔ THE LIVE ANSWER HOLDS HEADER VALUES, AND NONE OF THEM REACHES AN ATTRIBUTE. PBS returns a
+ *   webhook's headers in full — `name=Authorization,value=<base64>` — to anyone with Sys.Audit on
+ *   /system/notifications (proxmox-notify api/webhook.rs `get_endpoint`, read at HEAD 2026-09-22).
+ *   Copying them into attributes would copy whatever a human pasted into a header, a bearer token
+ *   included, into the unencrypted state store. So attributes keep header NAMES and a fixed-salt
+ *   scrypt digest of the pairs (write-only.ts), enough to notice a change and nothing to send.
+ * ⚠️ SECRETS ARE SAFER ON THE SERVER, AND THE READ SHOWS IT: `get_endpoint` blanks every secret's
+ *   value and returns names only, from a root-only `notifications-priv.cfg`. A credential belongs
+ *   in `secret` and is referenced as `{{ secrets.<name> }}` from a header, the URL or the body.
+ */
+import { Buffer } from 'node:buffer';
+import { addressList, portOf } from './notification-target-form.ts';
+import type {
+  PbsNotificationTargetAttributes,
+  PbsNotificationTargetProps,
+} from './pbs-notification-target.ts';
+import { bool, text } from './values.ts';
+import { seal } from './write-only.ts';
+
+export const base64 = (value: string): string => Buffer.from(value, 'utf8').toString('base64');
+
+/** ⚠️ Node's decoder skips characters it does not know rather than throwing, so this never throws. */
+export const unbase64 = (value: string): string => Buffer.from(value, 'base64').toString('utf8');
+
+/**
+ * One `KeyAndBase64Val` property string — `name=<name>,value=<base64>` — split into its halves.
+ * ⚠️ KEYED BY NAME, NOT BY POSITION: the server serialises `name` first today, and a parser that
+ *   relied on that would read a reordered item as a header called `value=…`.
+ * ★ A comma cannot occur inside either half: base64 has none, and `refusals` keeps names clean.
+ */
+export const keyAndValue = (item: string): { name: string; value?: string } => {
+  const parts: Record<string, string> = {};
+  for (const part of item.split(',')) {
+    const at = part.indexOf('=');
+    if (at > 0) parts[part.slice(0, at).trim()] = part.slice(at + 1).trim();
+  }
+  const value = parts['value'];
+  return value === undefined ? { name: parts['name'] ?? '' } : { name: parts['name'] ?? '', value };
+};
+
+/** The wire item for one header or secret. The value is base64 — the server decodes it to use it. */
+export const wireItem = (name: string, value: string): string =>
+  `name=${name},value=${base64(value)}`;
+
+const list = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.map((item: unknown) => String(item)) : [];
+
+/** Sorted, comma-joined names — presence, the only thing the store may know about the values. */
+export const names = (keys: readonly string[]): string =>
+  [...keys]
+    .filter((key) => key !== '')
+    .sort()
+    .join(',');
+
+/**
+ * ★ A FIXED SALT PER TARGET, SO AN UNCHANGED HEADER SET DIGESTS THE SAME ON EVERY READ. A random
+ *   one would rewrite the state row on every plan. The server shows these values to its auditors
+ *   anyway; what the salt and scrypt buy is that the STORE does not become a second, weaker copy.
+ */
+export const headerDigest = (target: string, pairs: Readonly<Record<string, string>>): string =>
+  seal(pairs, `hf:pbs-notification-target:${target}:header`);
+
+/**
+ * Live JSON to attributes. `sealed` is left empty here: it is not the server's to report, and the
+ * handlers in pbs-notification-target.ts carry it forward from the previous state.
+ */
+export const targetAttributes = (
+  live: Record<string, unknown>,
+  props: PbsNotificationTargetProps,
+): PbsNotificationTargetAttributes => {
+  const headers: Record<string, string> = {};
+  for (const item of list(live['header'])) {
+    const { name, value } = keyAndValue(item);
+    if (name !== '') headers[name] = unbase64(value ?? '');
+  }
+  const secrets = list(live['secret']).map((item) => keyAndValue(item).name);
+  return {
+    author: text(live['author']),
+    // ⚠️ DECODED, unlike the PVE family's: the server stores exactly the base64 it was handed and
+    //   decodes it to render (endpoints/webhook.rs `build_request`), so decoding here is a pure
+    //   function of what was written and `matches` compares readable text rather than base64.
+    body: unbase64(text(live['body'])),
+    comment: text(live['comment']),
+    disable: bool(live['disable']),
+    'from-address': text(live['from-address']),
+    header: names(Object.keys(headers)),
+    headerDigest: headerDigest(props.name, headers),
+    mailto: addressList(live['mailto']),
+    'mailto-user': addressList(live['mailto-user']),
+    method: text(live['method']),
+    mode: text(live['mode']),
+    name: props.name,
+    // ★ ON THE PER-OBJECT READ, MEASURED on PBS 4.2 (`notification endpoint sendmail show
+    //   mail-to-root` answers `origin: builtin`). Reported, never compared.
+    origin: text(live['origin']),
+    port: portOf(live['port']),
+    secret: names(secrets),
+    sealed: '',
+    server: text(live['server']),
+    type: props.type,
+    url: text(live['url']),
+    username: text(live['username']),
+  };
+};

package/src/proxmox/pbs-notification-target.test.ts

@@ -0,0 +1,226 @@
+/**
+ * `Pbs.NotificationTarget` — refusals, the wire forms against the generated PBS schema, and the
+ * rule that no header or secret VALUE reaches an attribute.
+ *
+ * ⚠️ THE DRIFT CHECK IS A TYPED KEY LIST PER FAMILY. `targetForm` builds one flat body for three
+ *   families, so it cannot be typed as any one of them; instead each list below `satisfies` the
+ *   generated parameter keys (and each `delete` value the generated enum), and every form this file
+ *   builds is asserted to stay inside its list. A renamed parameter fails `tsc` on the list.
+ */
+import { describe, expect, test } from 'bun:test';
+import type {
+  ConfigNotificationsEndpointsSendmailNamePutParams,
+  ConfigNotificationsEndpointsSmtpPostParams,
+  ConfigNotificationsEndpointsWebhookNamePutParams,
+  ConfigNotificationsEndpointsWebhookPostParams,
+} from './generated/pbs.ts';
+import type { PbsTarget } from './credentials.ts';
+import type { PbsNotificationTargetProps } from './pbs-notification-target.ts';
+import { refusals, resolveGroups, targetForm } from './pbs-notification-target-form.ts';
+import { keyAndValue, targetAttributes, unbase64 } from './pbs-notification-target-wire.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const TOKEN = 'tok-5f0c1d2e-not-real';
+const ENV = { HOOK_TOKEN: TOKEN, SMTP_PASSWORD: 'pw-not-real' };
+
+const WEBHOOK_POST = [
+  'body',
+  'comment',
+  'disable',
+  'header',
+  'method',
+  'name',
+  'secret',
+  'url',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsWebhookPostParams)[];
+const WEBHOOK_PUT = [
+  'body',
+  'comment',
+  'delete',
+  'disable',
+  'header',
+  'method',
+  'secret',
+  'url',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsWebhookNamePutParams)[];
+const WEBHOOK_DELETE = [
+  'body',
+  'comment',
+  'header',
+  'secret',
+] as const satisfies readonly NonNullable<
+  ConfigNotificationsEndpointsWebhookNamePutParams['delete']
+>[number][];
+const SMTP_POST = [
+  'author',
+  'comment',
+  'disable',
+  'from-address',
+  'mailto',
+  'mailto-user',
+  'mode',
+  'name',
+  'password',
+  'port',
+  'server',
+  'username',
+] as const satisfies readonly (keyof ConfigNotificationsEndpointsSmtpPostParams)[];
+const SENDMAIL_DELETE = [
+  'author',
+  'comment',
+  'from-address',
+  'mailto',
+  'mailto-user',
+] as const satisfies readonly NonNullable<
+  ConfigNotificationsEndpointsSendmailNamePutParams['delete']
+>[number][];
+
+const webhook = (over: Partial<PbsNotificationTargetProps> = {}): PbsNotificationTargetProps => ({
+  body: '{"text": {{ json title }}}',
+  header: { Authorization: 'Bearer {{ secrets.token }}', 'Content-Type': 'application/json' },
+  method: 'post',
+  name: 'alertmanager',
+  secret: { token: { fromEnv: 'HOOK_TOKEN' } },
+  target: PBS,
+  type: 'webhook',
+  url: 'https://alertmanager.example.com/api/v2/alerts',
+  ...over,
+});
+
+const all = { header: true, sealed: true } as const;
+const keysOf = (form: object) => Object.keys(form).sort();
+
+describe('refusals, at plan, by field name', () => {
+  test('a field outside its family, a missing required field, a name that breaks the wire', () => {
+    expect(refusals(webhook())).toEqual([]);
+    expect(refusals({ name: 'm', target: PBS, type: 'sendmail', url: 'https://x.test' })).toEqual([
+      "'url' belongs to webhook targets, not sendmail",
+    ]);
+    expect(refusals(webhook({ url: undefined as never }))).toContain("webhook needs 'url'");
+    expect(refusals({ name: 's', server: 'mx.test', target: PBS, type: 'smtp' })).toEqual([
+      "smtp needs 'from-address'",
+    ]);
+    expect(refusals(webhook({ header: { 'X-A,b': 'v' } }))).toEqual([
+      "'X-A,b' cannot be a header or secret name",
+    ]);
+  });
+});
+
+describe('webhook forms', () => {
+  const groups = resolveGroups(webhook(), ENV);
+
+  test('a create carries base64 body, header and secret items, and stays inside the schema', () => {
+    const form = targetForm(webhook(), groups, all, 'create');
+    expect(keysOf(form).every((key) => (WEBHOOK_POST as readonly string[]).includes(key))).toBe(
+      true,
+    );
+    expect(unbase64(String(form['body']))).toBe('{"text": {{ json title }}}');
+    const secret = (form['secret'] as readonly string[]).map(keyAndValue);
+    expect(secret).toEqual([{ name: 'token', value: Buffer.from(TOKEN).toString('base64') }]);
+    const headers = (form['header'] as readonly string[]).map(keyAndValue);
+    expect(headers.map((h) => [h.name, unbase64(h.value ?? '')])).toEqual([
+      ['Authorization', 'Bearer {{ secrets.token }}'],
+      ['Content-Type', 'application/json'],
+    ]);
+    expect(form['disable']).toBe('0');
+  });
+
+  test('an update carries only the groups it was told to — omitted means "keep"', () => {
+    const form = targetForm(
+      webhook({ comment: 'x' }),
+      groups,
+      { header: false, sealed: false },
+      'update',
+    );
+    expect(keysOf(form)).toEqual(['body', 'comment', 'disable', 'method', 'url']);
+    expect(keysOf(form).every((key) => (WEBHOOK_PUT as readonly string[]).includes(key))).toBe(
+      true,
+    );
+  });
+
+  test('clearing is a `delete` inside the generated enum', () => {
+    const cleared = webhook({ body: '', comment: '', header: {}, secret: {} });
+    const form = targetForm(cleared, resolveGroups(cleared, ENV), all, 'update');
+    expect(form['delete']).toEqual(['body', 'comment', 'header', 'secret']);
+    expect(
+      (form['delete'] as readonly string[]).every((d) =>
+        (WEBHOOK_DELETE as readonly string[]).includes(d),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('mail forms', () => {
+  test('smtp: recipients sorted, password sent only when its group is carried', () => {
+    const smtp: PbsNotificationTargetProps = {
+      'from-address': 'pbs@example.com',
+      mailto: ['b@example.com', 'a@example.com'],
+      name: 'relay',
+      password: { fromEnv: 'SMTP_PASSWORD' },
+      server: 'mx.example.com',
+      target: PBS,
+      type: 'smtp',
+      username: 'pbs',
+    };
+    const groups = resolveGroups(smtp, ENV);
+    const create = targetForm(smtp, groups, all, 'create');
+    expect(create['mailto']).toEqual(['a@example.com', 'b@example.com']);
+    expect(create['password']).toBe('pw-not-real');
+    expect(keysOf(create).every((key) => (SMTP_POST as readonly string[]).includes(key))).toBe(
+      true,
+    );
+    expect(
+      targetForm(smtp, groups, { header: false, sealed: false }, 'update')['password'],
+    ).toBeUndefined();
+  });
+
+  test('sendmail: an emptied list and an empty from-address clear, inside the enum', () => {
+    const sendmail: PbsNotificationTargetProps = {
+      'from-address': '',
+      mailto: [],
+      name: 'mail-to-root',
+      target: PBS,
+      type: 'sendmail',
+    };
+    const form = targetForm(sendmail, resolveGroups(sendmail, ENV), all, 'update');
+    expect(form['delete']).toEqual(['from-address', 'mailto']);
+    expect(
+      (form['delete'] as readonly string[]).every((d) =>
+        (SENDMAIL_DELETE as readonly string[]).includes(d),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('attributes', () => {
+  const live = {
+    body: Buffer.from('{}').toString('base64'),
+    header: [`name=Authorization,value=${Buffer.from(`Bearer ${TOKEN}`).toString('base64')}`],
+    method: 'post',
+    name: 'alertmanager',
+    origin: 'user-created',
+    secret: ['name=token'],
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+  };
+
+  test('keep header and secret NAMES and a digest — never a value, raw or base64', () => {
+    const attributes = targetAttributes(live, webhook());
+    expect(attributes.header).toBe('Authorization');
+    expect(attributes.secret).toBe('token');
+    expect(attributes.headerDigest).toStartWith('scrypt:');
+    const text = JSON.stringify(attributes);
+    expect(text).not.toContain(TOKEN);
+    expect(text).not.toContain(Buffer.from(`Bearer ${TOKEN}`).toString('base64'));
+    expect(attributes.body).toBe('{}');
+  });
+
+  test('the header digest is stable across reads and moves with the value', () => {
+    const again = targetAttributes(live, webhook());
+    expect(again.headerDigest).toBe(targetAttributes(live, webhook()).headerDigest);
+    const other = {
+      ...live,
+      header: [`name=Authorization,value=${Buffer.from('Bearer other').toString('base64')}`],
+    };
+    expect(targetAttributes(other, webhook()).headerDigest).not.toBe(again.headerDigest);
+  });
+});

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

@@ -0,0 +1,139 @@
+/**
+ * `Pbs.NotificationTarget` — where a Proxmox Backup Server sends a notification: a `webhook`, or
+ * mail through `sendmail` or `smtp`.
+ *
+ * ★ THE WEBHOOK IS THE POINT. A failed verify, sync or garbage collection reaches a human through a
+ *   target a matcher names (pbs-notification-matcher.ts). Out of the box that is `mail-to-root`,
+ *   one mailbox on one host; a webhook can post an Alertmanager alert instead, and then the failure
+ *   pages like everything else. docs/pbs-alertmanager-body.md has the body template.
+ *
+ * ⛔ SECRETS ARE DECLARED BY THE NAME OF AN ENVIRONMENT VARIABLE, NEVER BY VALUE, and NO VALUE EVER
+ *   REACHES STATE — not as a prop, not as an attribute. write-only.ts has the whole argument; the
+ *   short form: Alchemy stores props and attributes unencrypted, so `secret`, `password` and any
+ *   header holding a credential take `{ fromEnv: 'NAME' }`, read by the deploying process at call
+ *   time. What the store keeps is presence (names) and digests, and the plan diffs on those.
+ *   ★ THIS IS WHERE THE PBS FAMILY PARTS FROM notification-target.ts (PVE), which refuses every
+ *     secret and so cannot create a signed webhook at all.
+ *
+ * ⛔ THE PER-OBJECT PATH CARRIES THE FAMILY: `config/notifications/endpoints/{type}/{name}`. `type`
+ *   is identity, and changing it or `name` plans a REPLACE here — `diff` compares them with the
+ *   recorded props. `/config/notifications/targets` is a read-only union view, as on PVE.
+ *
+ * ⚠️ A BUILT-IN TARGET REVERTS ON DELETE instead of disappearing (`origin: builtin`, measured on
+ *   PBS 4.2 for `mail-to-root`), and PBS reports success either way — notification-target.ts has
+ *   the consequence. Read `origin` before declaring a name you did not create.
+ *
+ * ★ WHAT THIS NEEDS (generated/pbs.ts source): Sys.Audit on /system/notifications to read,
+ *   Sys.Modify there to write. A datastore-scoped credential reads every target as absent.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { handlers } from './pbs-notification-target-lifecycle.ts';
+import type { PveRequirements, WithPbsTarget } from './resource.ts';
+import type { FromEnv } from './write-only.ts';
+
+export type PbsNotificationTargetType = 'sendmail' | 'smtp' | 'webhook';
+
+/**
+ * ⚠️ PBS'S OWN KEY NAMES, DASHES INCLUDED, for the reason backup-job.ts gives. A field outside its
+ *   family (a `url` on a sendmail target) is refused at plan by name, not sent for a 400.
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED; `''` or `[]` (or `{}`) CLEARS ONE.
+ */
+export interface PbsNotificationTargetProps extends WithPbsTarget {
+  /** ⛔ IDENTITY: it picks the family and the URL. Changing it is a replace. */
+  type: PbsNotificationTargetType;
+  /** Unique across ALL families on the host: a webhook cannot be called `mail-to-root`. */
+  name: string;
+  comment?: string;
+  /** Configured but not delivering. Always sent and always compared. */
+  disable?: boolean;
+  /** sendmail, smtp: recipient addresses. Order is not meaning. */
+  mailto?: readonly string[];
+  /** sendmail, smtp: PBS users whose configured address receives the mail. */
+  'mailto-user'?: readonly string[];
+  /** smtp: required. sendmail: optional. */
+  'from-address'?: string;
+  author?: string;
+  /** smtp: the relay host. Required. */
+  server?: string;
+  /** smtp. Unset lets PBS pick from `mode`. */
+  port?: number;
+  /** smtp. PBS's default is `tls`. */
+  mode?: 'insecure' | 'starttls' | 'tls';
+  /** smtp. */
+  username?: string;
+  /** smtp: ⛔ WRITE-ONLY. The server never returns it; the plan compares its seal. */
+  password?: FromEnv;
+  /** webhook: required. Supports templating: `{{ secrets.<name> }}` keeps a token out of it. */
+  url?: string;
+  /** webhook: required. */
+  method?: 'get' | 'post' | 'put';
+  /**
+   * webhook: header name → template text, or `{ fromEnv }` for a value that is itself a secret.
+   * ⚠️ PLAIN VALUES ARE PROPS, AND PROPS ARE STORED: `Content-Type` is fine, a token is not. Put a
+   *   credential in `secret` and write `'Bearer {{ secrets.token }}'` here instead.
+   */
+  header?: Readonly<Record<string, FromEnv | string>>;
+  /**
+   * webhook: the body TEMPLATE, as text. ★ Declared DECODED — the wire is base64, and this family
+   *   encodes on write and decodes on read, so a plan shows a readable diff.
+   */
+  body?: string;
+  /** webhook: ⛔ WRITE-ONLY. Name → variable. Referenced as `{{ secrets.<name> }}`. */
+  secret?: Readonly<Record<string, FromEnv>>;
+}
+
+/** ⛔ NO VALUE OF A SECRET, PASSWORD OR HEADER — names and digests only. */
+export interface PbsNotificationTargetAttributes {
+  name: string;
+  type: PbsNotificationTargetType;
+  /** `builtin`, `modified-builtin`, `user-created` — reported, never compared. */
+  origin: string;
+  comment: string;
+  disable: boolean;
+  mailto: string;
+  'mailto-user': string;
+  'from-address': string;
+  author: string;
+  server: string;
+  /** 0 means PBS holds no port. */
+  port: number;
+  mode: string;
+  username: string;
+  url: string;
+  method: string;
+  /** The decoded body template. */
+  body: string;
+  /** Header NAMES, sorted — presence. */
+  header: string;
+  /** scrypt digest of the live header pairs, fixed salt per target. */
+  headerDigest: string;
+  /** Secret NAMES, sorted — all PBS will say. */
+  secret: string;
+  /**
+   * Seal of the secret values and password THIS PROVIDER LAST WROTE; `''` if it never wrote them
+   * (an adoption). ⚠️ `''` makes those values presence-only until the first write that carries them.
+   */
+  sealed: string;
+}
+
+export interface PbsNotificationTarget extends Resource<
+  'Pbs.NotificationTarget',
+  PbsNotificationTargetProps,
+  PbsNotificationTargetAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const PbsNotificationTarget = Resource<PbsNotificationTarget>('Pbs.NotificationTarget');
+
+/**
+ * ⛔ `Provider.of` STAYS HERE, for resource.ts's reason: it is the one place the handlers are
+ *   checked against the concrete resource types, so the lifecycle file cannot drift from them.
+ */
+export const PbsNotificationTargetProvider = () =>
+  Provider.effect(
+    PbsNotificationTarget,
+    Effect.succeed(PbsNotificationTarget.Provider.of(handlers)),
+  );

package/src/proxmox/pbs-notifications-stack.test.ts

@@ -0,0 +1,94 @@
+/**
+ * A target and the matcher that routes to it, declared together the way docs/pbs-notifications.md
+ * shows — with the matcher naming the target through its OUTPUT, not a string.
+ *
+ * ★ WHY THE OUTPUT: PBS refuses to create a matcher naming a target that does not exist, and
+ *   refuses to delete a target a matcher still names. `targets: [hook.name]` gives Alchemy the
+ *   dependency edge that orders both; a bare `'alertmanager'` string gives it nothing, and the
+ *   order is then whatever the engine picks. This pins that the Output resolves inside the list
+ *   (the matcher's `isResolved` guard) and that the target is written first.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { alertmanagerAlertBody } from './alertmanager-body.ts';
+import type { PbsTarget } from './credentials.ts';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationMatcherProvider,
+} from './pbs-notification-matcher.ts';
+import { PbsNotificationTarget, PbsNotificationTargetProvider } from './pbs-notification-target.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+
+const stack = Effect.gen(function* () {
+  const hook = yield* PbsNotificationTarget('alertmanager', {
+    body: alertmanagerAlertBody(),
+    header: { 'Content-Type': 'application/json' },
+    method: 'post',
+    name: 'alertmanager',
+    target: PBS,
+    type: 'webhook',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+  });
+  yield* PbsNotificationMatcher('page-on-failure', {
+    'match-field': ['exact:type=gc,prune,sync,verify'],
+    'match-severity': ['error'],
+    name: 'page-on-failure',
+    target: PBS,
+    targets: [hook.name],
+  });
+});
+
+test('the matcher resolves the target by Output and is written after it', async () => {
+  const fake = fakeNotify();
+  const providers = Layer.mergeAll(
+    PbsNotificationTargetProvider(),
+    PbsNotificationMatcherProvider(),
+  );
+  await withoutBao(async () => {
+    const engine = engineOver(providers.pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(stack);
+    const again = await engine.verify(stack, { all: true });
+    expect(again.rows.map((row) => row.diff)).toEqual(['noop', 'noop']);
+  });
+  expect(fake.writes()).toEqual([
+    'POST config/notifications/endpoints/webhook',
+    'POST config/notifications/matchers',
+  ]);
+  expect(fake.objects.get('config/notifications/matchers/page-on-failure')?.['target']).toEqual([
+    'alertmanager',
+  ]);
+});
+
+test('a new type under the same name replaces delete-first — names are unique across families', async () => {
+  const fake = fakeNotify();
+  const declare = (type: 'sendmail' | 'webhook') =>
+    type === 'webhook'
+      ? PbsNotificationTarget('pager', {
+          method: 'post',
+          name: 'pager',
+          target: PBS,
+          type,
+          url: 'https://alertmanager.example.com/api/v2/alerts',
+        })
+      : PbsNotificationTarget('pager', {
+          mailto: ['ops@example.com'],
+          name: 'pager',
+          target: PBS,
+          type,
+        });
+  await withoutBao(async () => {
+    const engine = engineOver(PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(declare('webhook'));
+    await engine.deploy(declare('sendmail'));
+  });
+  expect(fake.writes()).toEqual([
+    'POST config/notifications/endpoints/webhook',
+    'DELETE config/notifications/endpoints/webhook/pager',
+    'POST config/notifications/endpoints/sendmail',
+  ]);
+});

package/src/proxmox/resource.ts

@@ -20,7 +20,7 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { pve } from './client.ts';
+import { type PveForm, pve } from './client.ts';
 import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
 import { formToSend } from './update-guard.ts';
 
@@ -77,15 +77,15 @@ export type PveSpec<Props extends WithApiTarget, Attributes> = {
   readonly collection: (props: Props) => string;
   /** Live JSON to attributes. Returning undefined means "this is not really there". */
   readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
-  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. */
-  readonly createForm: (props: Props) => Record<string, string>;
+  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. Arrays: client.ts. */
+  readonly createForm: (props: Props) => PveForm;
   /**
    * The form for an update, or undefined when the object has no mutable fields.
    *
    * ⚠️ SOME PVE OBJECTS CANNOT BE UPDATED AT ALL. Returning undefined makes a changed prop a
    *   REPLACE rather than a silent no-op, which is the honest answer for an immutable object.
    */
-  readonly updateForm?: (props: Props) => Record<string, string>;
+  readonly updateForm?: (props: Props) => PveForm;
   /** True when live already matches props. Decides noop vs update. */
   readonly matches: (attributes: Attributes, props: Props) => boolean;
   /**
@@ -105,7 +105,7 @@ export type PveSpec<Props extends WithApiTarget, Attributes> = {
 export const pveOperations = <Props extends WithApiTarget, Attributes>(
   spec: PveSpec<Props, Attributes>,
 ) => {
-  /** The live object, or undefined. ⚠️ A 404 is an ANSWER here, not a failure. */
+  /** The live object, or undefined. ⚠️ A 404 and `{"data": null}` are ANSWERS, not failures. */
   const read = (props: Props) =>
     pve<Record<string, unknown>>(
       props.target,
@@ -113,7 +113,7 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
       'GET',
       spec.path(props),
     ).pipe(
-      Effect.map((data) => (data === undefined ? undefined : spec.attributes(data, props))),
+      Effect.map((data) => (data == null ? undefined : spec.attributes(data, props))),
       Effect.orElseSucceed(() => undefined),
     );