@homeflare/alchemy 0.1.0

package/src/proxmox/node-network.ts

@@ -0,0 +1,243 @@
+/**
+ * `Proxmox.NodeNetwork` — one stanza of a node's `/etc/network/interfaces`, declared.
+ *
+ * ⛔ DECLARING THIS RESOURCE IS SAFE. APPLYING IT IS A SEPARATE, DELIBERATE ACT, AND IT IS NOT
+ *   PERFORMED HERE. Every write under `/nodes/{node}/network/{iface}` lands in
+ *   `/etc/network/interfaces.new` and changes no running interface. MEASURED, from PVE::INotify:
+ *   `$shadowfiles = { '/etc/network/interfaces' => '/etc/network/interfaces.new' }`, and
+ *   `read_file` reads the SHADOW when it exists. The apply is `PUT /nodes/{node}/network`, which
+ *   renames the shadow over the real file and runs `ifreload -a`; the revert is
+ *   `DELETE /nodes/{node}/network`, which simply unlinks the shadow. A sibling resource models
+ *   that apply — this one never calls it, exactly as `Proxmox.SdnZone` never calls
+ *   `Proxmox.SdnApply`.
+ *
+ * ⛔ CEPH ON TB4 RIDES TWO NETWORKS AND THIS API ONLY SEES ONE OF THEM. Measured from
+ *   `/etc/pve/ceph.conf` on 2026-09-13:
+ *
+ *     public_network  = 10.20.11.0/24     -> vmbr1.11, which this resource DOES see
+ *     cluster_network = 10.100.0.0/24     -> every OSD's cluster_addr: .102 / .103 / .104
+ *
+ *   The cluster network — OSD REPLICATION, the traffic that rebuilds a lost replica — lives on
+ *   `10.100.0.10X/32` addresses carried by `en05`, `en06` and `dummy_tb4`: the Thunderbolt mesh.
+ *
+ * ⛔ AND THOSE ADDRESSES ARE INVISIBLE HERE, WHICH IS THE TRAP. They are declared in
+ *   `/etc/network/interfaces.d/sdn`, and PVE's network API does not parse that directory.
+ *   MEASURED: `GET /nodes/n2/network/en05` answers `{"method":"manual","type":"eth",…}` with NO
+ *   address, while `ip -br -4 addr` shows `en05  UP  10.100.0.102/32`. So this resource reports
+ *   en05 and en06 as address-less manual ports and will plan `noop` over them — implicitly
+ *   asserting they carry no address, which is FALSE.
+ *
+ *   The consequence, stated plainly: declaring en05/en06 from what this API reports and then
+ *   DESTROYING or applying over them takes out OSD replication on a cluster whose pools are
+ *   size 3 / min_size 2. They read as the most boring interfaces on the node and are the two most
+ *   dangerous. Leave them undeclared; if they must be managed, manage the file that actually
+ *   owns them, not this resource.
+ *
+ * ⚠️ Two ways this file limits the damage on the interfaces it CAN see: `cidr` is compared
+ *   unconditionally (the ⛔ on `matches`), and a live interface whose `type` disagrees with the
+ *   declaration is reported ABSENT rather than retyped (the ⛔ in `attributes`).
+ *
+ * ★ THE REASON IT EXISTS IS THAT THE STAGED READ CANNOT TELL YOU THE NETWORK IS RIGHT — it can
+ *   only tell you the FILE is. Once anything is staged, `GET /nodes/{node}/network/{iface}`
+ *   answers from `interfaces.new`, so `matches` compares a declaration against a pending file and
+ *   reports `noop` over a node whose running config has not moved. The apply resource is what
+ *   closes that gap; this resource's `noop` means "the file says what you said", no more.
+ *
+ * ⚠️ PRIVILEGES ARE COARSER HERE THAN ANYWHERE ELSE IN THE PACKAGE: reads want `Sys.Audit` on
+ *   `/nodes/{node}`, every write `Sys.Modify` on it — and there is no `/nodes/{node}/network` ACL
+ *   object to scope to, so that also buys the node's services, certificates, DNS and time.
+ *   Collected with every other family in docs/privileges.md.
+ *
+ * ★ A RECONCILE OVER A MATCHING INTERFACE IS A NO-WRITE, AND AN EARLIER DRAFT OF THIS COMMENT
+ *   SAID THE OPPOSITE. `pveOperations.reconcile` gates on `matches` BEFORE the PUT
+ *   (`resource.ts`: `else if (spec.updateForm !== undefined && !spec.matches(live, news))`), and
+ *   the ⛔ above that line names THIS family as the reason the guard was added — adopting an
+ *   interface a node already has would otherwise leave it holding a pending network change.
+ *
+ * ⚠️ WHAT IS STILL TRUE: when `matches` is false the PUT rewrites the whole stanza, and that can
+ *   ADD lines the file did not have — a `vlan-raw-device vmbr1` under `vmbr1.11`, where PVE had
+ *   been deriving it from the name. Harmless in content, and it costs nothing until somebody
+ *   applies; one more reason the apply is a separate resource.
+ *
+ * ⚠️ `list` IS EMPTY, AND HERE THAT MATTERS MORE THAN ANYWHERE ELSE IN THIS PACKAGE. The index
+ *   returns every interface the node has, `vmbr0`, `bond0` and the Ceph vlan included. Adopting
+ *   them would put Alchemy one `destroy` away from staging the removal of a node's uplink — and
+ *   `delete_network` has NO in-use check at all: MEASURED, it deletes the hash entry and writes
+ *   the file. Adoption stays explicit.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import {
+  body,
+  readAttributes,
+  same,
+  sameComment,
+  sameList,
+  updateBody,
+} from './node-network-form.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+
+/**
+ * PVE's interface types. `unknown` is what a NIC it does not manage reports — n2 and n3 both
+ * report `wlp91s0` that way, and n4 has no such interface at all.
+ *
+ * ⚠️ THAT ASYMMETRY IS A TRAP FOR A DECLARATION SHARED ACROSS NODES. On n4 the read answers 404,
+ *   which this provider cannot tell from "deleted", so reconcile POSTs — writing a stanza for a
+ *   card that is not in the machine. Declare per node what each node actually has; a physical
+ *   interface is discovered, not decided.
+ */
+export type NodeNetworkType =
+  | 'OVSBond'
+  | 'OVSBridge'
+  | 'OVSIntPort'
+  | 'OVSPort'
+  | 'alias'
+  | 'bond'
+  | 'bridge'
+  | 'eth'
+  | 'fabric'
+  | 'unknown'
+  | 'vlan'
+  | 'vnet';
+
+export interface NodeNetworkProps extends WithTarget {
+  /** Which node's file this stanza lives in. Interfaces are per node, never cluster-wide. */
+  node: string;
+  /** `vmbr0`, `bond0`, `vmbr1.11`. 2-20 characters, PVE's `pve-iface` format. */
+  iface: string;
+  /** ⛔ REQUIRED ON EVERY WRITE, update included, never used to retype — see `readAttributes`. */
+  type: NodeNetworkType;
+  /**
+   * `10.20.11.12/24`. ⛔ THE ONE FIELD WITH NO UNMANAGED MODE: leaving it out is an instruction
+   * to make the interface `manual`, not an instruction to leave its address alone. The ⛔ on
+   * `updateBody` in node-network-form.ts has the measurement and the consequence.
+   */
+  cidr?: string;
+  /** ⚠️ PVE allows exactly ONE default gateway per node and refuses a second with "Default
+   *  gateway already exists on interface '<other>'". On TB4 it is vmbr0.10's. */
+  gateway?: string;
+  /**
+   * `auto <iface>` in the file. Absent on read means off, which is why `bool`'s fallback is used.
+   * ⚠️ UNDECLARED IS UNMANAGED ON AN UPDATE AND OFF ON A CREATE — the same asymmetry storage.ts
+   *   has, and it bites harder here: an interface created without `autostart` is one the node
+   *   will not bring up at boot. Every TB4 bridge, bond and vlan carries it.
+   */
+  autostart?: boolean;
+  /** 1280-65520. Unset leaves the file without an `mtu` line and the kernel default in force. */
+  mtu?: number;
+  /** ⚠️ Round-trips only after normalisation — see `comment` in node-network-form.ts. */
+  comments?: string;
+  /** Space-separated, a SET: `enp87s0`, or `bond0`. ⚠️ PVE refuses a port already used elsewhere. */
+  bridge_ports?: string;
+  /** `2-4094`, or `2 100-200`. Only written when `bridge_vlan_aware` is on. */
+  bridge_vids?: string;
+  /** ⛔ A `false` here is sent as `delete=`, never as `0` — the ⛔ on `body` says why. */
+  bridge_vlan_aware?: boolean;
+  /**
+   * A bond's members, space separated. ⚠️ THE PARAMETER IS `slaves`, NOT `bond_slaves`, in BOTH
+   * directions on this PVE: MEASURED, the POST/PUT schema names only `slaves` and the GET returns
+   * `"slaves":"enp2s0f0np0 enp2s0f1np1"`. `bond_slaves` appears nowhere in Network.pm here.
+   */
+  slaves?: string;
+  bond_mode?: string;
+  /** ⚠️ Only written when `bond_mode` is `balance-xor` or `802.3ad`; ignored otherwise. */
+  bond_xmit_hash_policy?: string;
+  /** active-backup only. Kept hyphenated because that is the wire name. */
+  'bond-primary'?: string;
+  /** ⚠️ DERIVED FROM A DOTTED NAME. `vmbr1.11` reports `vlan-id` 11 with no such line in the file;
+   *  declaring it there is harmless but adds a line the file did not have. */
+  'vlan-id'?: number;
+  'vlan-raw-device'?: string;
+}
+
+/**
+ * ⛔ THE LAST SEVEN ARE REPORTED AND NEVER COMPARED — each is a MEASURED forever-diff, and the
+ *   evidence for every one of them is in node-network-form.ts, beside the code that reads them.
+ */
+export interface NodeNetworkAttributes {
+  node: string;
+  iface: string;
+  type: string;
+  cidr: string;
+  gateway: string;
+  autostart: boolean;
+  mtu: number;
+  comments: string;
+  bridge_ports: string;
+  bridge_vids: string;
+  bridge_vlan_aware: boolean;
+  slaves: string;
+  bond_mode: string;
+  bond_xmit_hash_policy: string;
+  'bond-primary': string;
+  'vlan-id': number;
+  'vlan-raw-device': string;
+  priority: number;
+  method: string;
+  families: string;
+  active: boolean;
+  exists: boolean;
+  bond_miimon: string;
+  bridge_stp: string;
+  bridge_fd: string;
+}
+
+export interface ProxmoxNodeNetwork extends Resource<
+  'Proxmox.NodeNetwork',
+  NodeNetworkProps,
+  NodeNetworkAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ★ `retain` by default — a node's only uplink cannot be rebuilt. See the ★ in resource.ts. */
+export const ProxmoxNodeNetwork = Resource<ProxmoxNodeNetwork>('Proxmox.NodeNetwork', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = pveHandlers<NodeNetworkProps, NodeNetworkAttributes>({
+  attributes: readAttributes,
+  collection: (props) => `nodes/${props.node}/network`,
+  /** ⚠️ No `delete` parameter on a POST — see the ⚠️ on `updateBody`. */
+  createForm: body,
+  /**
+   * ⛔ `cidr` IS THE ONLY FIELD COMPARED WHEN UNDECLARED, AND THAT ASYMMETRY IS THE POINT. Every
+   *   other field here follows storage.ts: undeclared means unmanaged, so it is neither sent nor
+   *   compared and a plan cannot report an update no write could satisfy. `cidr` cannot be
+   *   unmanaged, because PVE derives `method` from the presence of an address IN THE FORM — an
+   *   omission is an edit. Comparing it unconditionally is what makes that edit visible in `plan`
+   *   instead of at `ifreload` time.
+   *
+   * ⚠️ NOTHING IN THE REPORTED-ONLY BLOCK IS HERE, and that is what makes the TB4 declaration
+   *   plan as `noop` on all three nodes at once — the ⛔ above `NodeNetworkAttributes` lists them
+   *   and the measurement behind each.
+   */
+  matches: (attributes, props) =>
+    attributes.cidr === (props.cidr ?? '') &&
+    same(props.gateway, attributes.gateway) &&
+    same(props.autostart, attributes.autostart) &&
+    same(props.mtu, attributes.mtu) &&
+    sameComment(props.comments, attributes.comments) &&
+    sameList(props.bridge_ports, attributes.bridge_ports) &&
+    sameList(props.bridge_vids, attributes.bridge_vids) &&
+    same(props.bridge_vlan_aware, attributes.bridge_vlan_aware) &&
+    sameList(props.slaves, attributes.slaves) &&
+    same(props.bond_mode, attributes.bond_mode) &&
+    same(props.bond_xmit_hash_policy, attributes.bond_xmit_hash_policy) &&
+    same(props['bond-primary'], attributes['bond-primary']) &&
+    same(props['vlan-id'], attributes['vlan-id']) &&
+    same(props['vlan-raw-device'], attributes['vlan-raw-device']),
+  path: (props) => `nodes/${props.node}/network/${props.iface}`,
+  updateForm: updateBody,
+});
+
+/**
+ * ⚠️ THE DESTROY IS STAGED LIKE EVERY OTHER WRITE, WHICH MAKES IT THE ONE RECOVERABLE DESTROY IN
+ *   THIS PACKAGE. It removes the stanza from `interfaces.new` and nothing else;
+ *   `DELETE /nodes/{node}/network` puts the node back by unlinking that file. It becomes
+ *   irreversible the moment somebody applies — and PVE performs NO in-use check before removing
+ *   an interface other bridges or Ceph still stand on.
+ */
+export const ProxmoxNodeNetworkProvider = () =>
+  Provider.effect(ProxmoxNodeNetwork, Effect.succeed(ProxmoxNodeNetwork.Provider.of(handlers)));

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

@@ -0,0 +1,104 @@
+/**
+ * A notification target's props, as the form PVE wants — including the one field in this package
+ * that cannot be spelled as a comma list.
+ *
+ * ★ SPLIT OUT OF notification-target.ts TO KEEP BOTH UNDER THE 250-LINE CAP. The seam is the same
+ *   one metric-server uses: this file turns a declaration into a form, and the resource file says
+ *   what a target IS and when it has changed. The `import type` back is erased, so it is a cycle
+ *   on paper only.
+ */
+import type { NotificationTargetProps } from './notification-target.ts';
+import { text } from './values.ts';
+
+/**
+ * ⛔ A MULTI-VALUED PARAMETER GOES ON THE WIRE DIFFERENTLY HERE THAN ANYWHERE ELSE IN THIS PACKAGE,
+ *   AND THE DIFFERENCE IS MEASURED. Every other PVE endpoint spells a list `type: string, format:
+ *   pve-configid-list` — comma-joined, which is what sdn-vnet.ts sends. On the notification
+ *   endpoints `mailto`, `mailto-user`, `header` and `delete` are `type: array`, and PVE's own web
+ *   UI submits those as REPEATED KEYS (`header=a&header=b`). `Record<string, string>` cannot repeat
+ *   a key, so one value carrying a NUL goes instead: it percent-encodes to `%00`, and PVE's
+ *   urlencoded decoder joins repeated keys with exactly that byte, rebuilding the same parameter.
+ *   ⚠️ ONLY `header` NEEDS IT, and only past one entry. A header item is ITSELF the property string
+ *     `name=<name>,value=<base64>`, so a comma cannot express even one of them. Addresses hold no
+ *     commas and PVE's UI submits `mailto` as a comma-separated text field, so those go that way.
+ *   ⚠️ REASONED FROM THE DECODER AND THE UI, NOT PROVEN BY A LIVE MULTI-HEADER WRITE. One header
+ *     carries no separator and is unaffected either way; a longer list, if rejected, fails with a
+ *     400 naming `header` rather than quietly dropping one, and the fix is one line here.
+ */
+const REPEATED_KEY = '\0';
+
+/** ⚠️ `0` is "PVE holds no port". Integers have come back as strings elsewhere, so parse both. */
+export const portOf = (value: unknown): number => {
+  const parsed = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+  return Number.isNaN(parsed) ? 0 : parsed;
+};
+
+const sorted = (parts: readonly string[]): string =>
+  parts
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .sort()
+    .join(',');
+
+/**
+ * ⚠️ ORDER IS NOT MEANING IN A RECIPIENT LIST, SO IT MUST NOT BE A DIFF — backup-job.ts's reasoning
+ *   about guest ids, applied to addresses. Both sides are sorted before they meet.
+ *
+ * ⚠️ PVE ANSWERS WITH AN ARRAY AND ACCEPTS A DELIMITED STRING, and this package has already been
+ *   bitten by a list coming back flattened on one version and structured on another (`groups` in
+ *   user.ts). PVE's UI calls `mailto` "separated by spaces, commas or semicolons", so all three are
+ *   split here and both shapes funnel into one comparable value.
+ */
+export const addressList = (value: unknown): string =>
+  sorted(
+    Array.isArray(value)
+      ? value.map((item: unknown) => String(item))
+      : typeof value === 'string'
+        ? value.split(/[\s,;]+/)
+        : [],
+  );
+
+/** ⛔ NEVER SPLIT ON A COMMA: a header item contains one. A lone string is one item, not a list. */
+export const headerList = (value: unknown): string =>
+  sorted(Array.isArray(value) ? value.map((item: unknown) => String(item)) : [text(value)]);
+
+const set = (key: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [key]: value };
+
+/**
+ * The form for both create and update.
+ *
+ * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT AND NOT COMPARED — backup-job.ts's rule rather
+ *   than sdn-vnet.ts's `delete` list, and here the choice is not close. That list would have to
+ *   name `mailto`, so a target adopted from the UI and declared without its recipients would have
+ *   them stripped on the first deploy: the one object that makes failures visible, turned back into
+ *   silence. `delete` on this family is also `type: array` rather than the comma string every other
+ *   endpoint takes, so sdn-vnet's encoding would not even carry.
+ *   ⚠️ THE PRICE IS THAT REMOVING A LINE DOES NOT CLEAR A FIELD. Declare it as `''` to clear it,
+ *     which IS sent: an empty string is a value, an absent prop is no request at all.
+ *
+ * ⚠️ `disable` IS ALWAYS SENT AND ALWAYS COMPARED, `0` INCLUDED. PVE documents the default as 0, so
+ *   sending it explicitly is what makes "not declared" and "declared false" one state instead of a
+ *   plan that asks for an update the PUT never performs. It is also the drift that matters most
+ *   here: a target disabled by hand during a maintenance window and never re-enabled looks exactly
+ *   like a healthy cluster.
+ */
+export const shape = (props: NotificationTargetProps): Record<string, string> => ({
+  disable: props.disable === true ? '1' : '0',
+  ...set('author', props.author),
+  ...set('body', props.body),
+  ...set('comment', props.comment),
+  ...set('from-address', props['from-address']),
+  ...set('header', props.header === undefined ? undefined : props.header.join(REPEATED_KEY)),
+  ...set('mailto', props.mailto === undefined ? undefined : addressList(props.mailto)),
+  ...set(
+    'mailto-user',
+    props['mailto-user'] === undefined ? undefined : addressList(props['mailto-user']),
+  ),
+  ...set('method', props.method),
+  ...set('mode', props.mode),
+  ...set('port', props.port === undefined ? undefined : String(props.port)),
+  ...set('server', props.server),
+  ...set('url', props.url),
+  ...set('username', props.username),
+});

package/src/proxmox/notification-target.ts

@@ -0,0 +1,222 @@
+/**
+ * `Proxmox.NotificationTarget` — where a failed backup goes to be seen.
+ *
+ * ★ THE FAILURE MODE THIS REMOVES IS SILENCE. A failed vzdump, a lost HA service and a broken
+ *   replication job all reach a human through one mechanism: a notification target. Out of the box
+ *   a cluster has exactly one, the built-in `mail-to-root` — one mailbox, on one node, delivered by
+ *   that node's local MTA. Declared, a failure becomes visible; undeclared, nothing looks wrong
+ *   until somebody goes looking for a backup that was never taken. Every other resource in this
+ *   package fails loudly. This is the one whose absence fails quietly.
+ *
+ * ⛔ THE PER-OBJECT READ GOES THROUGH `endpoints/{type}/{name}`, NEVER `targets/{name}`.
+ *   `GET /cluster/notifications/targets/{name}` answers "Method not implemented" — MEASURED, and
+ *   corroborated by the cluster's own apidoc, where that path node carries no methods at all.
+ *   `/targets` is a READ-ONLY UNION VIEW implementing the collection GET and `{name}/test` and
+ *   nothing else. So `type` is IDENTITY here, not a setting: it appears in both `path()` and
+ *   `collection()`, and changing it is a replace rather than an update.
+ *
+ * ⚠️ A BUILT-IN TARGET CAN BE ADOPTED AND STILL NOT BE OWNED. The shipped entries report
+ *   `origin: builtin` or `modified-builtin`, and a DELETE on one REVERTS it to shipped defaults
+ *   instead of removing it: Alchemy drops the resource from state while the target is still on the
+ *   cluster delivering mail. Check `origin` on `/cluster/notifications/targets` before declaring a
+ *   name you did not create. ⚠️ `origin` IS DELIBERATELY NOT AN ATTRIBUTE — the schema returns it
+ *   on the collection view only, never on the per-object read, so an attribute would read "unknown"
+ *   for every object forever, and an attribute that always lies is worse than a true comment.
+ *
+ * ⛔ NO SECRET IS A PROP, LET ALONE AN ATTRIBUTE. smtp `password`, gotify `token` and webhook
+ *   `secret` are write-only and none is declarable here. Props are persisted too, not just
+ *   attributes — `delete` is handed `olds`, which can only have come from the state store — so a
+ *   secret prop would sit unencrypted in the state Postgres for as long as the resource exists.
+ *   ⚠️ THE COST IS REAL: `token` is REQUIRED on a gotify create, so a gotify target cannot be
+ *     created from here at all. Create one out of band with its secret and then declare it — the
+ *     read finds it, reconcile takes the PUT path, and PVE leaves any field the body does not
+ *     mention alone. The secret half stays a human's; the rest is declared. Same for an
+ *     authenticated smtp target and a signed webhook.
+ *
+ * ★ WHAT THIS NEEDS, READ OFF THE CLUSTER'S OWN SCHEMA:
+ *     read/diff  GET endpoints/{type}/{name}  Mapping.Audit (or Mapping.Modify) on
+ *                                             /mapping/notifications
+ *     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.
+ *   ⚠️ 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.
+ *   ⛔ A MISSING READ PRIVILEGE DOES NOT LOOK LIKE A 403. `pveOperations.read` ends in
+ *     `orElseSucceed(() => undefined)`, so a 403 on the GET is indistinguishable from "absent": the
+ *     plan says create, PVE answers "already exists", and the fault was an ACL all along. That pair
+ *     is the signature — grant Mapping.Audit to the READ role before changing anything else.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { addressList, headerList, portOf, shape } from './notification-target-form.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { text } from './values.ts';
+
+/** The four families PVE ships. `GET /cluster/notifications/endpoints` lists exactly these. */
+export type NotificationTargetType = 'gotify' | 'sendmail' | 'smtp' | 'webhook';
+
+/**
+ * ⚠️ PVE'S OWN KEY NAMES, DASHES INCLUDED, for the reason backup-job.ts gives: the form is then a
+ *   copy rather than a translation table, and a translation table is one more place for a key to be
+ *   renamed and silently never sent.
+ *
+ * ⚠️ A FIELD THAT DOES NOT BELONG TO `type` IS STILL SENT, and PVE refuses it by name. That 400
+ *   beats this file quietly dropping a `mailto` somebody wrote on a webhook.
+ */
+export interface NotificationTargetProps extends WithTarget {
+  /** ⛔ IDENTITY: it picks the family AND the URL, so changing it is a replace. */
+  type: NotificationTargetType;
+  /**
+   * PVE's primary key, unique ACROSS ALL FOUR FAMILIES: a webhook cannot be called `mail-to-root`,
+   * because a sendmail target already is. Format `pve-configid`.
+   */
+  name: string;
+  /** Free text in the UI. */
+  comment?: string;
+  /** Configured but not delivering. Always sent and always compared — see `shape`. */
+  disable?: boolean;
+  /** sendmail, smtp: recipients. ⚠️ Order is not meaning — see `addressList`. */
+  mailto?: readonly string[];
+  /** sendmail, smtp: PVE users, whose own configured address receives the mail. */
+  'mailto-user'?: readonly string[];
+  /** smtp: the SMTP host. gotify: the server URL. PVE requires it on create for both. */
+  server?: string;
+  /** smtp only. Unset lets PVE pick from `mode`: 465 tls, 587 starttls, 25 insecure. */
+  port?: number;
+  /** smtp only. PVE's schema default is `tls`. */
+  mode?: 'insecure' | 'starttls' | 'tls';
+  /** smtp only. ⛔ The matching `password` is not declarable — see the header. */
+  username?: string;
+  /** smtp: PVE requires it on create. sendmail: optional. */
+  'from-address'?: string;
+  /** Display name on the mail. PVE's smtp schema defaults it to `Proxmox VE`. */
+  author?: string;
+  /** webhook: PVE requires it on create. */
+  url?: string;
+  /** webhook: PVE requires it on create. Lower case — PVE's enum is `post|put|get`. */
+  method?: 'get' | 'post' | 'put';
+  /**
+   * webhook: `name=<name>,value=<base64 of value>` property strings, as PVE stores them.
+   * ⚠️ MORE THAN ONE HEADER IS THE ONE THING HERE NOT PROVEN ON A WIRE — see `REPEATED_KEY`.
+   */
+  header?: readonly string[];
+  /**
+   * webhook: the request body, base64, as PVE stores it.
+   * ⚠️ THE UI SHOWS THE DECODED BODY AND THIS DOES NOT. Declaring the base64 is what keeps
+   *   `matches` symmetric with the read; decoding for display would mean encoding on write, and a
+   *   round trip PVE normalises differently is a forever-update. The cost is an unreadable diff.
+   */
+  body?: string;
+}
+
+/**
+ * ⚠️ EVERY FIELD IS PRESENT FOR EVERY FAMILY, with `''` / `0` meaning "PVE holds nothing". A
+ *   webhook reads back an empty `mailto`, which is also what a webhook declares, so the
+ *   cross-family fields cost one comparison each and never a false update.
+ */
+export interface NotificationTargetAttributes {
+  name: string;
+  type: NotificationTargetType;
+  comment: string;
+  disable: boolean;
+  /** Sorted and comma-joined, so re-ordering a declaration is not a diff. See `addressList`. */
+  mailto: string;
+  'mailto-user': string;
+  server: string;
+  /** 0 means PVE holds no port and will pick one from `mode`. */
+  port: number;
+  mode: string;
+  username: string;
+  'from-address': string;
+  author: string;
+  url: string;
+  method: string;
+  /** Sorted and comma-joined for COMPARISON only; the wire form differs. See `headerList`. */
+  header: string;
+  body: string;
+}
+
+export interface ProxmoxNotificationTarget extends Resource<
+  'Proxmox.NotificationTarget',
+  NotificationTargetProps,
+  NotificationTargetAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxNotificationTarget = Resource<ProxmoxNotificationTarget>(
+  'Proxmox.NotificationTarget',
+);
+
+const handlers = pveHandlers<NotificationTargetProps, NotificationTargetAttributes>({
+  /**
+   * ⛔ NAMED FIELDS, NEVER A SPREAD OF `live`. gotify's `token` and smtp's `password` really are
+   *   absent from their read schemas — but webhook's read schema DECLARES `secret`, so "PVE will
+   *   not hand it to us" is not a defence. Listing what is kept is what keeps secret material out
+   *   of a state row, whatever a future PVE decides to start returning.
+   */
+  attributes: (live, props) => ({
+    author: text(live['author']),
+    body: text(live['body']),
+    comment: text(live['comment']),
+    disable: live['disable'] === 1 || live['disable'] === true,
+    'from-address': text(live['from-address']),
+    header: headerList(live['header']),
+    mailto: addressList(live['mailto']),
+    'mailto-user': addressList(live['mailto-user']),
+    method: text(live['method']),
+    mode: text(live['mode']),
+    name: props.name,
+    port: portOf(live['port']),
+    server: text(live['server']),
+    type: props.type,
+    url: text(live['url']),
+    username: text(live['username']),
+  }),
+  collection: (props) => `cluster/notifications/endpoints/${props.type}`,
+  /** ⛔ `name` is create-only: PVE takes it in the body once, and in the path forever after. */
+  createForm: (props) => ({ ...shape(props), name: props.name }),
+  /**
+   * Each line reads "not declared, or equal"; `disable` is the one field with no undeclared case.
+   *
+   * ⚠️ IF A PLAN NEVER SETTLES, SUSPECT A SCHEMA DEFAULT COMING BACK AS A VALUE. PVE defaults smtp
+   *   `mode` to `tls` and smtp `author` to `Proxmox VE`, and applies both when the mail is sent
+   *   rather than writing them into the config — so an undeclared field reads back empty and its
+   *   line is skipped. A version that STORED them would answer with a field nobody declared. The
+   *   fix is to declare the field, never to stop comparing it.
+   */
+  matches: (attributes, props) =>
+    attributes.disable === (props.disable === true) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.server === undefined || attributes.server === props.server) &&
+    (props.port === undefined || attributes.port === props.port) &&
+    (props.mode === undefined || attributes.mode === props.mode) &&
+    (props.username === undefined || attributes.username === props.username) &&
+    (props['from-address'] === undefined || attributes['from-address'] === props['from-address']) &&
+    (props.author === undefined || attributes.author === props.author) &&
+    (props.url === undefined || attributes.url === props.url) &&
+    (props.method === undefined || attributes.method === props.method) &&
+    (props.body === undefined || attributes.body === props.body) &&
+    (props.mailto === undefined || attributes.mailto === addressList(props.mailto)) &&
+    (props['mailto-user'] === undefined ||
+      attributes['mailto-user'] === addressList(props['mailto-user'])) &&
+    (props.header === undefined || attributes.header === headerList(props.header)),
+  path: (props) => `cluster/notifications/endpoints/${props.type}/${props.name}`,
+  updateForm: shape,
+});
+
+/**
+ * ⚠️ ON A BUILT-IN TARGET A DELETE REVERTS RATHER THAN REMOVES, and PVE reports success either way.
+ *   It is passed through unguarded because everywhere else in this package the cluster's answer is
+ *   the answer — but this is the one case where a green plan and the cluster disagree, and the
+ *   object left standing is the one carrying the estate's failure mail.
+ */
+export const ProxmoxNotificationTargetProvider = () =>
+  Provider.effect(
+    ProxmoxNotificationTarget,
+    Effect.succeed(ProxmoxNotificationTarget.Provider.of(handlers)),
+  );