@homeflare/alchemy 0.11.0 → 0.13.0

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)),
+  );

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

@@ -0,0 +1,83 @@
+/**
+ * `Pbs.NotificationTarget` drift that is not about a secret's VALUE: a target switched off by hand,
+ * and a secret NAME added to the declaration. Split from pbs-notification-target-state.test.ts for
+ * the 250-line cap; the same fake server (fake-pbs-notify.ts) and the same engine.
+ *
+ * ★ BOTH WERE FOUND BY MUTATION, NOT BY READING. Deleting the `disable` line from `plainMatches`, or
+ *   the secret-name line from `sealedState`, left every other test green: nothing had declared a
+ *   target, changed it on the server, and asked the plan.
+ */
+import { afterEach, 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 { withoutBao } from './fake-pve.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+import { keyAndValue } from './pbs-notification-target-wire.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const PATH = 'config/notifications/endpoints/webhook/alertmanager';
+
+const hook = (over: Partial<PbsNotificationTargetProps> = {}) =>
+  PbsNotificationTarget('alertmanager', {
+    method: 'post',
+    name: 'alertmanager',
+    secret: { token: { fromEnv: 'HF_DRIFT_TOKEN' } },
+    target: PBS,
+    type: 'webhook',
+    url: 'https://alertmanager.example.com/api/v2/alerts',
+    ...over,
+  });
+
+afterEach(() => {
+  delete process.env['HF_DRIFT_TOKEN'];
+  delete process.env['HF_DRIFT_ROUTE'];
+});
+
+const engineFor = (fake: ReturnType<typeof fakeNotify>) =>
+  engineOver(PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)));
+
+test('a target disabled by hand plans an update, and the deploy switches it back on', async () => {
+  process.env['HF_DRIFT_TOKEN'] = 'tok-drift-not-real';
+  const fake = fakeNotify();
+  await withoutBao(async () => {
+    const engine = engineFor(fake);
+    await engine.deploy(hook());
+    fake.objects.set(PATH, { ...fake.objects.get(PATH), disable: true });
+    expect((await engine.verify(hook(), { all: true })).rows[0]?.diff).toBe('update');
+    await engine.deploy(hook());
+  });
+  const put = fake.calls.find((call) => call.method === 'PUT');
+  expect(put?.pairs).toContainEqual(['disable', '0']);
+  expect(put?.pairs.map(([key]) => key)).not.toContain('secret');
+  expect(fake.objects.get(PATH)?.['disable']).toBe(false);
+});
+
+test('a secret name added is stale by PRESENCE — seen with no variables set — and both are sent', async () => {
+  process.env['HF_DRIFT_TOKEN'] = 'tok-drift-not-real';
+  const fake = fakeNotify();
+  const twoSecrets = () =>
+    hook({
+      secret: { route: { fromEnv: 'HF_DRIFT_ROUTE' }, token: { fromEnv: 'HF_DRIFT_TOKEN' } },
+    });
+  await withoutBao(async () => {
+    const engine = engineFor(fake);
+    await engine.deploy(hook());
+    // ⚠️ No variable at plan time, so the seal cannot be checked: only the names can say this.
+    delete process.env['HF_DRIFT_TOKEN'];
+    expect((await engine.verify(twoSecrets(), { all: true })).rows[0]?.diff).toBe('update');
+    process.env['HF_DRIFT_TOKEN'] = 'tok-drift-not-real';
+    process.env['HF_DRIFT_ROUTE'] = 'route-not-real';
+    await engine.deploy(twoSecrets());
+    expect(engine.stored()).not.toContain('route-not-real');
+  });
+  expect((fake.secrets.get(PATH) ?? []).map((item) => keyAndValue(item).name).sort()).toEqual([
+    'route',
+    'token',
+  ]);
+});

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

@@ -0,0 +1,229 @@
+/**
+ * When a PBS notification target has changed, and the forms that change it.
+ *
+ * ★ THREE QUESTIONS, NOT ONE, because the three kinds of field can be checked three ways:
+ *     plain   every field the server returns in full — compared by value, like any family here
+ *     header  names from the read, values by digest (pbs-notification-target-wire.ts)
+ *     sealed  secret values and the smtp password: the server returns names at best, so values
+ *             are checked against the seal of what this provider last wrote (write-only.ts)
+ *   Each answers `match`, `stale` or `unknown`; only `stale` writes. `unknown` is "the plan cannot
+ *   see it" — a variable missing from the plan's environment, or a secret this provider never
+ *   wrote (an adoption) — and it is PRESENCE-ONLY by design: a plan never invents drift it
+ *   cannot see, and adoption stays free.
+ *
+ * ⛔ A WRITE SENDS ONLY THE GROUPS THAT ARE STALE. Omitting `header` or `secret` from a PUT keeps
+ *   what the server holds (api/webhook.rs `update_endpoint`), so a changed comment is written
+ *   without reading a single secret — and a deploy environment without the secrets can still
+ *   repair the rest. A group that IS stale needs every value it holds; a missing one fails the
+ *   deploy by variable name before anything is sent.
+ */
+import type { PveForm } from './client.ts';
+import { literalCredentialHeaders, literalCredentialsInUrl } from './credential-literals.ts';
+import { addressList } from './notification-target-form.ts';
+import type {
+  PbsNotificationTargetAttributes,
+  PbsNotificationTargetProps,
+} from './pbs-notification-target.ts';
+import { base64, headerDigest, names, wireItem } from './pbs-notification-target-wire.ts';
+import { type Environment, type FromEnv, resolveAll, sealMatches } from './write-only.ts';
+
+type Props = PbsNotificationTargetProps;
+type Field = keyof Props;
+
+/** Which family each optional field belongs to. A field outside its family is refused at plan. */
+const OWNED: Readonly<Partial<Record<Field, readonly Props['type'][]>>> = {
+  author: ['sendmail', 'smtp'],
+  body: ['webhook'],
+  'from-address': ['sendmail', 'smtp'],
+  header: ['webhook'],
+  mailto: ['sendmail', 'smtp'],
+  'mailto-user': ['sendmail', 'smtp'],
+  method: ['webhook'],
+  mode: ['smtp'],
+  password: ['smtp'],
+  port: ['smtp'],
+  secret: ['webhook'],
+  server: ['smtp'],
+  url: ['webhook'],
+  username: ['smtp'],
+};
+
+const REQUIRED: Readonly<Record<Props['type'], readonly Field[]>> = {
+  sendmail: [],
+  smtp: ['server', 'from-address'],
+  webhook: ['url', 'method'],
+};
+
+/** A header or secret name lands inside a property string, where `,` and `=` are syntax. */
+const CLEAN_NAME = /^[^,=\s]+$/;
+
+/** How a refused literal credential should be declared instead. */
+const WRITE_ONLY =
+  "declare it { fromEnv: 'NAME' }, or keep it in 'secret' and write {{ secrets.<name> }}";
+
+/**
+ * Why this declaration cannot be written, or nothing. Checked at PLAN, so a webhook without a
+ * URL fails `alchemy plan` naming the field rather than a deploy failing on a 400.
+ * ⚠️ "AT PLAN" MEANS `diff` FOR A TARGET WITH STATE AND THE ADOPTION PROBE (`read`) FOR ONE
+ *   WITHOUT — pbs-notification-target-lifecycle.ts has why both are needed.
+ */
+export const refusals = (props: Props): string[] => {
+  const out: string[] = [];
+  for (const [field, types] of Object.entries(OWNED) as [Field, readonly Props['type'][]][]) {
+    if (props[field] !== undefined && !types.includes(props.type)) {
+      out.push(`'${field}' belongs to ${types.join('/')} targets, not ${props.type}`);
+    }
+  }
+  for (const field of REQUIRED[props.type]) {
+    if (props[field] === undefined || props[field] === '')
+      out.push(`${props.type} needs '${field}'`);
+  }
+  for (const key of [...Object.keys(props.header ?? {}), ...Object.keys(props.secret ?? {})]) {
+    if (!CLEAN_NAME.test(key)) out.push(`'${key}' cannot be a header or secret name`);
+  }
+  // ⛔ credential-literals.ts: a literal credential in a plain prop is a credential in state.
+  for (const name of literalCredentialHeaders(props.header)) {
+    out.push(`header '${name}' holds a literal credential; ${WRITE_ONLY}`);
+  }
+  for (const where of literalCredentialsInUrl(props.url)) {
+    out.push(`'url' ${where} holds a literal credential; ${WRITE_ONLY}`);
+  }
+  return out;
+};
+
+const isFromEnv = (value: string | FromEnv): value is FromEnv => typeof value !== 'string';
+
+/** Each group's values, resolved from `env`, plus the variables that were missing. */
+export const resolveGroups = (props: Props, env: Environment = process.env) => {
+  const headerRefs: Record<string, FromEnv> = {};
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(props.header ?? {})) {
+    if (isFromEnv(value)) headerRefs[name] = value;
+    else headers[name] = value;
+  }
+  const header = resolveAll(headerRefs, env);
+  const sealedRefs: Record<string, FromEnv> = {};
+  for (const [name, ref] of Object.entries(props.secret ?? {})) sealedRefs[`secret:${name}`] = ref;
+  if (props.password !== undefined) sealedRefs['password'] = props.password;
+  const sealed = resolveAll(sealedRefs, env);
+  return {
+    header: { missing: header.missing, values: { ...headers, ...header.values } },
+    sealed,
+  };
+};
+
+export type Groups = ReturnType<typeof resolveGroups>;
+export type GroupState = 'match' | 'stale' | 'unknown';
+
+const same = (declared: string | undefined, live: string): boolean =>
+  declared === undefined || declared === live;
+
+/** Every field the server returns in full. `disable` is the one with no undeclared case. */
+export const plainMatches = (live: PbsNotificationTargetAttributes, props: Props): boolean =>
+  live.disable === (props.disable === true) &&
+  same(props.comment, live.comment) &&
+  same(props.author, live.author) &&
+  same(props['from-address'], live['from-address']) &&
+  same(props.server, live.server) &&
+  (props.port === undefined || props.port === live.port) &&
+  same(props.mode, live.mode) &&
+  same(props.username, live.username) &&
+  same(props.url, live.url) &&
+  same(props.method, live.method) &&
+  same(props.body, live.body) &&
+  (props.mailto === undefined || addressList(props.mailto) === live.mailto) &&
+  (props['mailto-user'] === undefined || addressList(props['mailto-user']) === live['mailto-user']);
+
+export const headerState = (
+  live: PbsNotificationTargetAttributes,
+  props: Props,
+  groups: Groups,
+): GroupState => {
+  if (props.header === undefined) return 'match';
+  if (names(Object.keys(props.header)) !== live.header) return 'stale';
+  if (groups.header.missing.length > 0) return 'unknown';
+  return headerDigest(props.name, groups.header.values) === live.headerDigest ? 'match' : 'stale';
+};
+
+export const sealedState = (
+  live: PbsNotificationTargetAttributes,
+  props: Props,
+  groups: Groups,
+  sealed: string,
+): GroupState => {
+  if (props.secret === undefined && props.password === undefined) return 'match';
+  if (props.secret !== undefined && names(Object.keys(props.secret)) !== live.secret)
+    return 'stale';
+  if (groups.sealed.missing.length > 0 || sealed === '') return 'unknown';
+  return sealMatches(sealed, groups.sealed.values) ? 'match' : 'stale';
+};
+
+/** Which write-only groups a write carries. A create carries every declared one. */
+export interface Carry {
+  readonly header: boolean;
+  readonly sealed: boolean;
+}
+
+const secretItems = (props: Props, groups: Groups): string[] =>
+  Object.keys(props.secret ?? {}).map((name) =>
+    wireItem(name, groups.sealed.values[`secret:${name}`] ?? ''),
+  );
+
+const headerItems = (props: Props, groups: Groups): string[] =>
+  Object.keys(props.header ?? {}).map((name) => wireItem(name, groups.header.values[name] ?? ''));
+
+/** `''`/`[]` means "clear": dropped on a create, turned into a `delete` entry on an update. */
+const plainPairs = (props: Props): [string, string | readonly string[]][] => [
+  ['author', props.author ?? ''],
+  ['body', props.body === undefined ? '' : base64(props.body)],
+  ['comment', props.comment ?? ''],
+  ['from-address', props['from-address'] ?? ''],
+  ['method', props.method ?? ''],
+  ['mode', props.mode ?? ''],
+  ['port', props.port === undefined ? '' : String(props.port)],
+  ['server', props.server ?? ''],
+  ['url', props.url ?? ''],
+  ['username', props.username ?? ''],
+  ['mailto', props.mailto === undefined ? [] : addressList(props.mailto).split(',')],
+  [
+    'mailto-user',
+    props['mailto-user'] === undefined ? [] : addressList(props['mailto-user']).split(','),
+  ],
+];
+
+const declared = (props: Props, key: string): boolean =>
+  (props as unknown as Record<string, unknown>)[key] !== undefined;
+
+const empty = (value: string | readonly string[]): boolean =>
+  typeof value === 'string' ? value === '' : value.filter((item) => item !== '').length === 0;
+
+/**
+ * The body of a create or an update — keys are the server's own, checked against generated/pbs.ts
+ * by pbs-notification-target.test.ts. ⛔ `disable` IS ALWAYS SENT, `0` included — the PVE family's
+ * reason: it is always compared, and "undeclared" and "false" must be one state, not a plan that
+ * asks for an update the PUT never performs.
+ */
+export const targetForm = (
+  props: Props,
+  groups: Groups,
+  carry: Carry,
+  mode: 'create' | 'update',
+): PveForm => {
+  const form: Record<string, string | readonly string[]> = {
+    disable: props.disable === true ? '1' : '0',
+  };
+  const cleared: string[] = [];
+  const put = (key: string, value: string | readonly string[]) => {
+    if (!empty(value)) form[key] = value;
+    else if (mode === 'update') cleared.push(key);
+  };
+  for (const [key, value] of plainPairs(props)) if (declared(props, key)) put(key, value);
+  if (carry.header && props.header !== undefined) put('header', headerItems(props, groups));
+  if (carry.sealed && props.secret !== undefined) put('secret', secretItems(props, groups));
+  if (carry.sealed && props.password !== undefined) {
+    form['password'] = groups.sealed.values['password'] ?? '';
+  }
+  if (mode === 'create') form['name'] = props.name;
+  if (cleared.length > 0) form['delete'] = cleared;
+  return form;
+};

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

@@ -0,0 +1,177 @@
+/**
+ * The lifecycle of a `Pbs.NotificationTarget`: read, diff, reconcile, delete.
+ *
+ * ★ SPLIT OUT OF pbs-notification-target.ts FOR THE 250-LINE CAP. That file says what a target is
+ *   and holds `Provider.of`; this one says what each operation does. The `import type` back is
+ *   erased, so the cycle is on paper only.
+ *
+ * ⚠️ NOT `pveHandlers`, AND IT SHOULD LOOK DIFFERENT (resource.ts asks for exactly that). The
+ *   factory's `diff` sees only the live object, and a secret's value is not in the live object:
+ *   the seal lives in the PREVIOUS STATE, which only a hand-written `diff` and `reconcile` receive
+ *   (`output`). Everything else — the read, the read-back refusal, the `matches` guard that keeps
+ *   adoption free — is the factory's behaviour, written out.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import { pve } from './client.ts';
+import type {
+  PbsNotificationTargetAttributes,
+  PbsNotificationTargetProps,
+} from './pbs-notification-target.ts';
+import {
+  type Carry,
+  type Groups,
+  headerState,
+  plainMatches,
+  refusals,
+  resolveGroups,
+  sealedState,
+  targetForm,
+} from './pbs-notification-target-form.ts';
+import { targetAttributes } from './pbs-notification-target-wire.ts';
+import { seal } from './write-only.ts';
+
+type Props = PbsNotificationTargetProps;
+type Attributes = PbsNotificationTargetAttributes;
+
+const path = (props: Props) => `config/notifications/endpoints/${props.type}/${props.name}`;
+
+/**
+ * ⚠️ A 404 and `{"data": null}` are answers here — and so, resource.ts's ⛔, is a 403. `pve()`
+ *   returns `null` for the second, not `undefined`, so the test is `== null`.
+ */
+const readLive = (props: Props) =>
+  pve<Record<string, unknown>>(props.target, 'read', 'GET', path(props)).pipe(
+    Effect.map((data) => (data == null ? undefined : targetAttributes(data, props))),
+    Effect.orElseSucceed(() => undefined),
+  );
+
+const refuse = (props: Props) => {
+  const reasons = refusals(props);
+  return reasons.length === 0
+    ? Effect.void
+    : Effect.die(new Error(`${path(props)}: ${reasons.join('; ')}.`));
+};
+
+/** What a write must carry, given what is stale. `undefined` means nothing to write. */
+const toCarry = (live: Attributes, props: Props, groups: Groups, sealed: string) => {
+  const header = headerState(live, props, groups) === 'stale';
+  const sealedStale = sealedState(live, props, groups, sealed) === 'stale';
+  return plainMatches(live, props) && !header && !sealedStale
+    ? undefined
+    : ({ header, sealed: sealedStale } satisfies Carry);
+};
+
+/** ⛔ Every variable a carried group needs, or a failure naming the missing ones — never a value. */
+const requireValues = (props: Props, groups: Groups, carry: Carry) => {
+  const missing = [
+    ...(carry.header ? groups.header.missing : []),
+    ...(carry.sealed ? groups.sealed.missing : []),
+  ];
+  return missing.length === 0
+    ? Effect.void
+    : Effect.die(
+        new Error(
+          `${path(props)}: this write must send write-only values, and ${missing.join(', ')} ` +
+            'is unset or empty in the deploying environment. Export it and deploy again.',
+        ),
+      );
+};
+
+export const handlers = {
+  /** ⛔ EMPTY: `mail-to-root` is on every host, and adoption stays an explicit act (resource.ts). */
+  list: () => Effect.succeed([]),
+  /**
+   * ⛔ WITH NO `output` THIS IS ALCHEMY'S ADOPTION PROBE, AND THE ONLY PLAN-TIME HOOK A NEW TARGET
+   *   GETS — so the refusals run here too. Measured on beta.79 (Plan.ts, the `oldState ===
+   *   undefined` branch): a declaration with no state row is `read` with `olds: news` and never
+   *   `diff`ed, and Apply then commits its props as `creating` BEFORE `reconcile` runs. A refusal
+   *   left to `reconcile` fired after the props — a literal token included — were in the store.
+   * ⚠️ ONLY WHEN THE PROPS ARE RESOLVED: Plan skips the probe while any prop is an unresolved
+   *   Output, and then `reconcile` is the first check. docs/pbs-notifications.md says so.
+   * ★ A DEFECT (`Effect.die`), NOT A FAILURE, AND THAT IS WHAT KEEPS IT FROM WEDGING A STAGE. The
+   *   same `read`-with-no-output shape is Alchemy's RECOVERY read of an interrupted create, at plan
+   *   and before a delete (Plan.ts, Apply.ts), with the STORED props — and both wrap it in
+   *   `catchDefect`, degrading to "nothing recovered". A typed failure would pass that catch and
+   *   block the plan or the delete on props the user already fixed. The cold-start probe has no
+   *   catch, so there the defect fails the plan, as intended. A refused create sent no request,
+   *   so "nothing recovered" is also the truth.
+   */
+  read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+    (output === undefined ? refuse(olds) : Effect.void).pipe(
+      Effect.andThen(readLive(olds)),
+      Effect.map((live) =>
+        live === undefined ? undefined : { ...live, sealed: output?.sealed ?? '' },
+      ),
+    ),
+  /**
+   * ⚠️ `Input<Props>` and `isResolved`, resource.ts's reason: at plan time a prop can still be an
+   *   unresolved Output, and comparing a placeholder to a live value reports a phantom update.
+   * ⛔ A NEW `type` UNDER THE SAME `name` REPLACES DELETE-FIRST: names are unique across every
+   *   family on the host (api `ensure_unique`), so creating the new one first would be refused.
+   */
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<Props>;
+    olds: Props;
+    output: Attributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (output === undefined || !isResolved(news)) return undefined;
+      if (olds !== undefined && (olds.type !== news.type || olds.name !== news.name)) {
+        return { action: 'replace', deleteFirst: olds.name === news.name } as const;
+      }
+      yield* refuse(news);
+      const live = yield* readLive(news);
+      if (live === undefined) return { action: 'update' } as const;
+      return toCarry(live, news, resolveGroups(news), output.sealed) === undefined
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+  reconcile: ({ news, output }: { news: Props; output: Attributes | undefined }) =>
+    Effect.gen(function* () {
+      yield* refuse(news);
+      const groups = resolveGroups(news);
+      const live = yield* readLive(news);
+      let sealed = output?.sealed ?? '';
+      if (live === undefined) {
+        const carry = { header: true, sealed: true } as const;
+        yield* requireValues(news, groups, carry);
+        const collection = `config/notifications/endpoints/${news.type}`;
+        yield* pve(
+          news.target,
+          'provision',
+          'POST',
+          collection,
+          targetForm(news, groups, carry, 'create'),
+        );
+        sealed = seal(groups.sealed.values);
+      } else {
+        const carry = toCarry(live, news, groups, sealed);
+        if (carry !== undefined) {
+          yield* requireValues(news, groups, carry);
+          yield* pve(
+            news.target,
+            'provision',
+            'PUT',
+            path(news),
+            targetForm(news, groups, carry, 'update'),
+          );
+          if (carry.sealed) sealed = seal(groups.sealed.values);
+        }
+      }
+      const after = yield* readLive(news);
+      if (after === undefined) {
+        // ⛔ resource.ts's rule: "no error" is not evidence of a write. Read back, or refuse.
+        return yield* Effect.die(
+          new Error(`${path(news)}: the write returned no error but the target is still absent.`),
+        );
+      }
+      return { ...after, sealed } satisfies Attributes;
+    }),
+  delete: ({ olds }: { olds: Props }) => pve(olds.target, 'provision', 'DELETE', path(olds)),
+};