@homeflare/alchemy 0.1.0

package/src/proxmox/group.ts

@@ -0,0 +1,199 @@
+/**
+ * `Proxmox.Group` — a PVE group: a name, a comment, and the set of users PVE hangs off it.
+ *
+ * ★ DECLARING `hf-mint` IS THE WHOLE POINT OF THIS FAMILY. `vaultmint@pve` holds the `HFMint` role
+ *   ON THE PATH `/access/groups/hf-mint` — measured from `GET /access/acl`, 2026-09-13 — which is
+ *   what confines the OpenBao proxmox engine to minting inside that one group. The group is the
+ *   fence around the credential every other resource in this package runs on, and until now it was
+ *   something a human typed on a node once. `user.ts` calls that account the branch it sits on;
+ *   this is the branch's other end.
+ *
+ * ⛔ MEMBERSHIP IS NOT SETTABLE HERE, SO IT IS REPORTED AND NEVER DIFFED. Measured from the
+ *   cluster's own schema: `POST /access/groups` and `PUT /access/groups/{groupid}` each accept
+ *   EXACTLY `groupid` and `comment`, both with `additionalProperties: 0`. There is no members
+ *   parameter to send. Membership is written from the other side — the `groups` field on each
+ *   USER, which `user.ts` already owns — so `members` below is an attribute, out of `matches`,
+ *   exactly like `pool.members` and `user.tokens`. Declared here it would be a diff that no write
+ *   in this file could ever settle.
+ *
+ * ⛔ THE INDEX AND THE ITEM DISAGREE ABOUT BOTH THE NAME AND THE TYPE, and this file reads only the
+ *   item. MEASURED against n2, 2026-09-13:
+ *     GET /access/groups         -> [{"groupid":"hf-mint","comment":"…",
+ *                                     "users":"hf-provision@pve,hf-read@pve"}, …]
+ *     GET /access/groups/hf-mint -> {"comment":"…","members":["hf-provision@pve","hf-read@pve"]}
+ *   The index says `users` and hands back a COMMA STRING; the item says `members` and hands back an
+ *   ARRAY. A reader that looked for `users` on the item path would find nothing, report an empty
+ *   group, and quietly show a delete as harmless.
+ *
+ * ⛔ AND THE ITEM'S ORDER IS NOT STABLE BETWEEN TWO CONSECUTIVE CALLS. MEASURED, seconds apart, on
+ *   the same endpoint:
+ *     ["root@pam","tim@pve","tim@pam","tim@<account>.com@Schenanigans"]
+ *     ["tim@pam","tim@pve","tim@<account>.com@Schenanigans","root@pam"]
+ *   `read_group` builds it as `[keys %{ $data->{users} }]` — a bare Perl hash key list, whose order
+ *   is randomised per process — while the INDEX sorts (`join(',', sort keys …)`). So the array is
+ *   sorted on the way into `attributes` as well as being kept out of `matches`: unsorted, Alchemy's
+ *   stored state would churn on every read even with nothing to diff.
+ *
+ * ⚠️ `groupid` IS NOT ECHOED BY THE ITEM READ. Its return schema is `additionalProperties: 0` over
+ *   exactly `comment` and `members`, so the id comes from props — the same arrangement, and the
+ *   same reason, as `user.ts`.
+ *
+ * ★ PRIVILEGES: NOTHING HAD TO BE WIDENED, WHICH MAKES THIS THE FIRST FAMILY HERE THAT COST
+ *   NOTHING. Measured with `pveum user permissions`, 2026-09-13:
+ *     · item GET checks `['perm','/access/groups',['Sys.Audit','Group.Allocate'], any => 1]`, and
+ *       `hf-read@pve` already holds `Sys.Audit` there (propagated from `/` by `PVEAuditor`).
+ *       So `readRole` is left at the default `read` — unlike storage/sdn-zone/sdn-vnet, whose ITEM
+ *       reads PVE gates on an allocate privilege. See the ⛔ on `readRole` in `resource.ts`.
+ *     · POST, PUT and DELETE each check `Group.Allocate` on `/access/groups`, and
+ *       `hf-provision@pve` holds it via `LXCProvisioner`.
+ *
+ * ⛔ `retain` BY DEFAULT, BECAUSE DELETING A GROUP DESTROYS TWO THINGS THIS FILE CANNOT PUT BACK.
+ *   Measured in `PVE::AccessControl` on the node:
+ *     · The member list IS the group. `user.cfg` stores it on the GROUP line (`group:<id>:<users>:
+ *       <comment>:`) and DERIVES each user's `groups` map from it at parse time. Deleting the group
+ *       deletes the list, and this resource has no `members` prop to restore it from.
+ *     · `delete_group_acl` then walks the whole ACL tree and drops every grant where the group is
+ *       the SUBJECT. On this cluster that is `Schenanigans -> Administrator on /` and
+ *       `HomeAssistant -> PVEAuditor on /`: whole populations of access, gone in one call, with no
+ *       confirmation and nothing in the plan to suggest it.
+ *   `delete` is FULLY IMPLEMENTED — `DELETE /access/groups/{groupid}` exists, unlike the ACL
+ *   family's — so `.pipe(RemovalPolicy.destroy())` really removes the group. See the ★ in
+ *   `resource.ts` for why the policy is a guard rather than a stubbed-out operation.
+ *
+ * ⛔ NO SECRET REACHES STATE. A group holds a comment and a list of userids; there is no password,
+ *   no token and no key anywhere on these endpoints. `user.ts`'s ⛔ about unencrypted state applies
+ *   to this package, and this family simply has nothing to trip it.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { csv, text } from './values.ts';
+
+export interface GroupProps extends WithTarget {
+  /**
+   * PVE's primary key for a group.
+   *
+   * ⚠️ THERE IS NO RENAME, AND THE FAILURE IS WORSE HERE THAN FOR A ROLE. Editing this makes `path`
+   *   point at a different group, which reads as absent and is created empty — while the old group
+   *   keeps its members and its ACL grants with nobody managing it. Two groups then both look
+   *   right in the UI and only one of them grants anything.
+   */
+  groupid: string;
+  /** Free text shown in the UI — the only mutable field a group has. See `storedComment` below. */
+  comment?: string;
+}
+
+export interface GroupAttributes {
+  groupid: string;
+  comment: string;
+  /**
+   * Who is in the group, sorted — reported so a plan can say what a delete would strip, never
+   * compared, because this endpoint cannot set it. See the two ⛔s in the header.
+   */
+  members: string[];
+}
+
+export interface ProxmoxGroup extends Resource<
+  'Proxmox.Group',
+  GroupProps,
+  GroupAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ★ `retain` by default — a delete takes the membership and the group's grants. See the header. */
+export const ProxmoxGroup = Resource<ProxmoxGroup>('Proxmox.Group', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/**
+ * The comment PVE will actually END UP HOLDING for a given declaration.
+ *
+ * ⛔ PVE CANNOT STORE THE COMMENT `'0'`, AND A PROVIDER THAT DOES NOT MODEL THAT DIFFS FOREVER.
+ *   Three places in the shipped Perl test the comment for TRUTH rather than for definedness, and
+ *   in Perl the one-character string `'0'` is false:
+ *     `create_group`:      `$group->{comment} = $param->{comment} if $param->{comment};`
+ *     `write_user_config`: `my $comment = $d->{comment} ? encode_text($d->{comment}) : '';`
+ *     the config parser:   `$cfg->{groups}->{$g}->{comment} = decode_text($comment) if $comment;`
+ *   So a declared `comment: '0'` is accepted by the API, dropped on the way to `user.cfg`, and read
+ *   back as absent. Left alone, `matches` would be false on every plan and every deploy would
+ *   rewrite the same value into the same hole. Normalising BOTH the comparison and the form is how
+ *   `values.ts` already treats `''` as the absence of a boolean rather than as `false`.
+ *   ⚠️ MEASURED IN THE SOURCE ON n2, NOT ON THE WIRE — writing `'0'` to the cluster to watch it
+ *     vanish would have been a write, and this agent had read access only.
+ *   ⚠️ `pool.ts` HAS THE SAME LATENT HOLE — `pool:$pool:$comment:…` is written by that same
+ *     truthiness test and is not guarded. Not fixed from here; flagged so it is fixed on purpose.
+ *
+ * ⚠️ EVERY OTHER COMMENT ROUND-TRIPS EXACTLY, colons and newlines included: `write_user_config`
+ *   runs it through `encode_text` and the parser through `decode_text`, so the field separator in
+ *   `user.cfg` cannot be smuggled in.
+ */
+const storedComment = (comment: string | undefined) => {
+  const value = comment ?? '';
+  return value === '0' ? '' : value;
+};
+
+/**
+ * The item read's `members` array, sorted into something two plans can agree on.
+ *
+ * ⚠️ `csv` IS REUSED RATHER THAN RE-IMPLEMENTED, AND ITS OWN ⚠️ IS EXACTLY THIS CASE: a list PVE
+ *   does not promise to give back in the order it was handed. Going out through the joined form
+ *   and back is the price of that reuse, and cheaper than a fourth hand-rolled sorter.
+ * ⚠️ THE ARRAY ONLY — THE COMMA STRING IS NOT ACCEPTED HERE, ON PURPOSE. That spelling belongs to
+ *   the INDEX (`users`), which this provider never reads, so a branch for it would be a guess at a
+ *   shape that cannot arrive. `user.ts` refuses the same guess for `tokens` and for the same
+ *   reason: a wrong guess on a reported-only field surfaces in a plan as a phantom membership.
+ * ⚠️ NO DEDUPLICATION, UNLIKE `user.ts`'s `groupSet`. These names are Perl HASH KEYS —
+ *   `[keys %{ $data->{users} }]` — so a duplicate is not representable. `user.groups` needs the
+ *   dedupe because its value also arrives from a hand-written prop; this one never does.
+ */
+const memberList = (live: unknown): string[] => {
+  const joined = csv((Array.isArray(live) ? live : []).map((member: unknown) => text(member)));
+  return joined === '' ? [] : joined.split(',');
+};
+
+const handlers = pveHandlers<GroupProps, GroupAttributes>({
+  attributes: (live, props) => ({
+    /**
+     * ⚠️ ABSENT IS EMPTY, NOT MISSING. `read_group` sets `comment` only `if defined(…)`, so a group
+     *   without one answers `{"members":[…]}` and nothing else. THAT ONE IS READ OFF THE HANDLER'S
+     *   SOURCE, not off the wire — every group on this cluster happens to carry a comment, so the
+     *   commentless shape was not there to measure. The empty-MEMBERS shape WAS measured —
+     *   `HomeAssistant` answers `{"comment":"…","members":[]}`. `''` is what an undeclared
+     *   `comment` prop normalises to, so the two sides meet either way.
+     */
+    comment: text(live['comment']),
+    /** ⚠️ FROM PROPS: the item read's schema is `additionalProperties: 0` over comment/members. */
+    groupid: props.groupid,
+    members: memberList(live['members']),
+  }),
+  collection: () => 'access/groups',
+  createForm: (props) => ({ comment: storedComment(props.comment), groupid: props.groupid }),
+  /**
+   * ⚠️ `members` IS NOT COMPARED, AND NOTHING ELSE IS LEFT TO COMPARE. `comment` is the only field
+   *   a PUT here accepts, so it is the only field whose drift this provider can repair — the rule
+   *   `resource.ts` states once in the ⛔ on adoption: a field deliberately out of `matches` is a
+   *   field this resource does not manage.
+   */
+  matches: (attributes, props) => attributes.comment === storedComment(props.comment),
+  path: (props) => `access/groups/${props.groupid}`,
+  /**
+   * ⚠️ ALWAYS SENT, EVEN EMPTY — that is how a comment is CLEARED. `update_group` assigns
+   *   `if defined($param->{comment})`, so an omitted field leaves the old text in place and a
+   *   declaration that dropped its comment would report an update the update could not settle. The
+   *   empty string then falls out of `user.cfg` on the truthiness test above and reads back as
+   *   `''`, which is what the props side normalises to. The loop closes.
+   */
+  updateForm: (props) => ({ comment: storedComment(props.comment) }),
+});
+
+/**
+ * ⛔ THE EMPTY `list` IS INHERITED FROM `pveHandlers` AND IT MATTERS HERE. `GET /access/groups`
+ *   answers with every group on the cluster — on this one that is `Schenanigans`, which grants
+ *   `Administrator` on `/` to every human who logs in. Handing it to Alchemy would invite adoption,
+ *   and therefore one day a delete that takes the whole admin group's access with it. Adoption
+ *   stays an explicit act, here as everywhere else in this package.
+ */
+export const ProxmoxGroupProvider = () =>
+  Provider.effect(ProxmoxGroup, Effect.succeed(ProxmoxGroup.Provider.of(handlers)));

package/src/proxmox/ha-resource.ts

@@ -0,0 +1,169 @@
+/**
+ * `Proxmox.HaResource` — a guest's HA membership, declared.
+ *
+ * ★ WITHOUT ONE OF THESE, EVERY GUEST THIS PACKAGE DECLARES IS PINNED TO THE NODE THE LINE NAMED
+ *   AND DIES WITH IT. The target is a three-node quorate cluster holding zero HA resources, so
+ *   `node` in `LxcProps` is the whole of a container's availability story: lose that node and the
+ *   container is simply gone until a person notices. Declaring a guest without declaring its HA
+ *   membership is half a declaration, which is why this lives beside `lxc.ts` rather than in a
+ *   runbook somebody reads after an outage.
+ *
+ * ⚠️ `state` READS LIKE STATUS AND IS CONFIGURATION. `started | stopped | disabled | ignored` is
+ *   the state the CRM is ASKED for; a line in the HA config file, not a reading off the cluster,
+ *   so it is a prop and it is compared. `LxcAttributes.status` is the opposite case — reported,
+ *   never declared — and confusing the two inverts the meaning: `state: 'stopped'` here says "HA
+ *   should hold this guest stopped and still relocate it on node failure", not "it is stopped".
+ *
+ * ⛔ AND YET IT MOVES POWER, WHICH IS THE ONE PLACE THIS PACKAGE'S "PLANS DO NOT START THINGS" RULE
+ *   BENDS. `lxc.ts` and `qemu.ts` refuse to own power state precisely so a deploy is not a
+ *   maintenance window — but the CRM acts on whatever this file says. The default `started` will
+ *   BOOT a stopped guest within seconds of the write, and `stopped` will SHUT DOWN a running one.
+ *   There is no way to declare HA membership without declaring intent, so the intent is at least
+ *   explicit and diffable here; read a plan that touches `state` as a plan that touches uptime.
+ *
+ * ⛔ `sid` CARRIES ITS TYPE PREFIX — `ct:101`, `vm:100` — AND READ ANSWERS IN THE PREFIXED FORM.
+ *   POST also takes the bare `101` shortcut; taking it would leave a resource keyed on a spelling
+ *   PVE never returns, and every plan comparing `101` against `ct:101`. So the prefixed form is
+ *   required here and it is what goes into the path.
+ *   ⚠️ EDITING `sid` IN PLACE ORPHANS THE OLD MEMBERSHIP. `diff` reads the NEW path, finds nothing
+ *     and calls that drift, so reconcile creates the new entry and the old one stays under HA with
+ *     nothing declaring it. Retire the declaration and add a second one instead of renaming.
+ *
+ * ⛔ MEASURED ON PVE 9.2: `/cluster/ha/groups` ANSWERS HTTP 500 — groups were removed in PVE 9,
+ *   even though the published API schema still documents the endpoint AND a `group` parameter on
+ *   this very resource. Nothing here sends `group`. The successor is `/cluster/ha/rules`
+ *   (node-affinity and resource-affinity) and that is the next family to add; do not port the old
+ *   groups endpoint back just because the docs still describe it.
+ *
+ * ⚠️ RECONCILE NEEDS `Sys.Console` ON `/`, WHICH `LXCProvisioner` DOES NOT HOLD. Read and diff are
+ *   fine — `GET /cluster/ha/resources/{sid}` checks `Sys.Audit`, which the role already has — while
+ *   POST, PUT and DELETE all check `Sys.Console` on `/` and will answer "Permission check failed
+ *   (/, Sys.Console)" until the role is widened. Widen it knowingly: `Sys.Console` is also what
+ *   opens a root shell on every node (`/nodes/{node}/vncshell`, `termproxy`), so granting it to the
+ *   provision credential buys HA membership at the price of node console access. A separate role
+ *   for HA writes is the narrower answer if that trade is not wanted.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { num } from './values.ts';
+
+/**
+ * The requested states this provider admits.
+ *
+ * ⚠️ `enabled` IS DELIBERATELY ABSENT. PVE accepts it and documents it as an alias for `started`,
+ *   which means a resource declared as `enabled` can be read back as `started` — and `matches`
+ *   would then report an update on every plan, forever, over a difference in spelling. One spelling
+ *   per state is the only version of this that settles.
+ */
+export type HaState = 'started' | 'stopped' | 'disabled' | 'ignored';
+
+export interface HaResourceProps extends WithTarget {
+  /** ⛔ PREFIXED AND CLUSTER-WIDE: `ct:101`, `vm:100`. Changing it is a different object. */
+  sid: string;
+  /** What the CRM should aim for. Defaults to `started`, PVE's own default. */
+  state?: HaState;
+  /** Free text shown in the HA panel. Max 4096 characters. */
+  comment?: string;
+  /** Restart tries on the SAME node before the manager gives up and relocates. Default 1. */
+  max_restart?: number;
+  /** Relocation tries before the resource is left in `error`. Default 1. */
+  max_relocate?: number;
+}
+
+export interface HaResourceAttributes {
+  /** As PVE returns it, prefix included. */
+  sid: string;
+  /** `ct` | `vm`. Implied by the prefix, reported so a plan can say what is being protected. */
+  type: string;
+  /**
+   * ⚠️ TYPED `string`, NOT `HaState`, because this is whatever the config file holds — including an
+   *   `enabled` a person wrote in the UI. Narrowing it here would be a claim about someone else's
+   *   edit rather than a report of it.
+   */
+  state: string;
+  comment: string;
+  max_restart: number;
+  max_relocate: number;
+}
+
+export interface ProxmoxHaResource extends Resource<
+  'Proxmox.HaResource',
+  HaResourceProps,
+  HaResourceAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxHaResource = Resource<ProxmoxHaResource>('Proxmox.HaResource');
+
+/** `ct:101` -> `ct`. ⚠️ `?? ''` because noUncheckedIndexedAccess types `split()[0]` as optional. */
+const kind = (sid: string) => sid.split(':')[0] ?? '';
+
+/**
+ * ⚠️ NO `type` IN EITHER FORM, ON PURPOSE. The prefix in `sid` already names it on create, and PUT
+ *   does not accept `type` at all — sending it on create only would make the two shapes diverge for
+ *   no gain, and sending it on update is a parameter-verification failure.
+ */
+const shape = (props: HaResourceProps) => ({
+  comment: props.comment ?? '',
+  max_relocate: String(props.max_relocate ?? 1),
+  max_restart: String(props.max_restart ?? 1),
+  state: props.state ?? 'started',
+});
+
+const handlers = pveHandlers<HaResourceProps, HaResourceAttributes>({
+  attributes: (live, props) => ({
+    comment: typeof live['comment'] === 'string' ? live['comment'] : '',
+    max_relocate: num(live['max_relocate'], 1),
+    max_restart: num(live['max_restart'], 1),
+    sid: typeof live['sid'] === 'string' ? live['sid'] : props.sid,
+    state: typeof live['state'] === 'string' ? live['state'] : 'started',
+    type: typeof live['type'] === 'string' ? live['type'] : kind(props.sid),
+  }),
+  /**
+   * ⚠️ CLUSTER-SCOPED, SO THERE IS NO NODE IN THE PATH — and that is the point of the object. The
+   *   guest's node is where it happens to run now; this resource is the statement that it may run
+   *   somewhere else tomorrow.
+   */
+  collection: () => 'cluster/ha/resources',
+  createForm: (props) => ({ ...shape(props), sid: props.sid }),
+  /**
+   * ⚠️ `digest` IS NOT COMPARED AND IS NOT AN ATTRIBUTE. It changes whenever ANY line of the HA
+   *   config changes, including one written for a different guest, so diffing it would report an
+   *   update on this resource because somebody else edited theirs.
+   * ⚠️ `sid` AND `type` ARE NOT COMPARED EITHER: sid is the path, so a change there is a different
+   *   object, and type is create-only — it is read back from the prefix, never edited.
+   */
+  matches: (attributes, props) =>
+    attributes.state === (props.state ?? 'started') &&
+    attributes.comment === (props.comment ?? '') &&
+    attributes.max_restart === (props.max_restart ?? 1) &&
+    attributes.max_relocate === (props.max_relocate ?? 1),
+  /**
+   * ⚠️ THE COLON GOES INTO THE URL RAW. RFC 3986 allows `:` inside a path segment and PVE matches
+   *   the sid as one segment, so no `encodeURIComponent` here; percent-encoding it would make the
+   *   request depend on a proxy normalising `%3A` back before the dispatcher sees it.
+   */
+  path: (props) => `cluster/ha/resources/${props.sid}`,
+  updateForm: shape,
+});
+
+/**
+* ⛔ Empty for the same reason as every other resource here: adoption must be explicit.
+*   `GET /cluster/ha/resources` would hand back every guest an operator has ever put under
+*   HA, and adopting those means one day deleting them.
+ 
+ *
+* ⛔ DELETE DEFAULTS TO `purge=1` AND THE FACTORY SENDS NO FORM, SO THAT DEFAULT APPLIES:
+*   PVE strips the sid out of every HA rule referencing it and DELETES a rule that had no
+*   other member. Destroying an HA membership can therefore take an affinity rule with it,
+*   which matters once the rules family lands.
+* ⚠️ It does NOT stop or remove the guest. The container keeps running exactly where it is,
+*   only unmanaged — so removing this resource is how a guest is handed back to its node,
+*   not how it is decommissioned.
+ 
+ */
+export const ProxmoxHaResourceProvider = () =>
+  Provider.effect(ProxmoxHaResource, Effect.succeed(ProxmoxHaResource.Provider.of(handlers)));

package/src/proxmox/ha-rule-form.ts

@@ -0,0 +1,185 @@
+/**
+ * An HA rule's props as the form PVE wants, and the two lists PVE re-spells on the way back.
+ *
+ * ★ SPLIT OUT OF ha-rule.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is the same
+ *   one metric-server-form.ts and node-network-form.ts cut: this file answers "how does a
+ *   declaration become a PVE form, and what shape does PVE hand back", ha-rule.ts answers "what is
+ *   an HA rule and when has it changed". Nothing here reads the cluster or decides a diff.
+ *
+ * ⚠️ THE `import type` BACK TO ha-rule.ts IS A CYCLE ON PAPER ONLY. It is type-only, so it is
+ *   erased before anything runs, and `HaRuleProps` stays public in the file declaring the resource.
+ */
+import type { HaRuleProps } from './ha-rule.ts';
+import { csv } from './values.ts';
+
+/**
+ * A `<node>[:<pri>]` list, spelled the way PVE gives it back.
+ *
+ * ⛔ THIS IS NOT `csv`, AND THE DIFFERENCE IS A FOREVER-DIFF. MEASURED by reading
+ *   `/usr/share/perl5/PVE/HA/Rules/NodeAffinity.pm` on n2 (2026-09-13): `decode_plugin_value`
+ *   turns the list into a HASH keyed by node name, and `encode_plugin_value` rebuilds it with
+ *   `for my $node (sort keys %$value)` — sorted by NODE NAME, never by the token — emitting the
+ *   bare name whenever the priority is falsy, because `PVE::HA::Tools::parse_node_priority` reads
+ *   a missing priority as 0. So a declared `n3:1,n2:0` is handed back as `n2,n3:1`: re-ordered AND
+ *   re-spelled. Compare the raw strings and every plan reports an update, forever.
+ *
+ * ⚠️ SORTED BY NAME, NOT BY TOKEN, AND THE TWO GENUINELY DIVERGE. `csv` sorts whole tokens. Node
+ *   names may contain `-` — `parse_node_priority`'s own regex is
+ *   `[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?` — and `-` (0x2D) sorts before `:` (0x3A), so `n2-a`
+ *   and `n2:5` come out in one order by token and the other by name. PVE sorts by the name, so
+ *   this does too.
+ *
+ * ⚠️ LAST ENTRY WINS FOR A REPEATED NODE, because PVE's decode is a hash assignment and a hash
+ *   keeps one value per key. A declaration saying `n2:1,n2:5` is stored as `n2:5`; matching that
+ *   is what a Map gives for free.
+ */
+export const nodeList = (value: readonly string[] | string | undefined) => {
+  const ranked = new Map<string, number>();
+  for (const entry of typeof value === 'string' ? value.split(',') : (value ?? [])) {
+    const [node, priority] = entry.trim().split(':');
+    if (node === undefined || node === '') continue;
+    const rank = Number.parseInt(priority ?? '0', 10);
+    ranked.set(node, Number.isNaN(rank) ? 0 : rank);
+  }
+  return [...ranked.keys()]
+    .sort()
+    .map((node) => {
+      const rank = ranked.get(node) ?? 0;
+      return rank === 0 ? node : `${node}:${String(rank)}`;
+    })
+    .join(',');
+};
+
+/**
+ * PVE's own verdict on whether the rule can be satisfied, flattened to one reportable string.
+ *
+ * ⚠️ COMPUTED, NEVER DECLARED, AND NEVER COMPARED. `PVE::API2::HA::Rules` runs `check_feasibility`
+ *   over the WHOLE rule set on every read and attaches whatever it finds to each rule as
+ *   `errors => { <option> => "<message>, <message>" }`. It therefore changes when somebody else's
+ *   rule changes, and none of it is a parameter any write accepts. It belongs in attributes so a
+ *   plan can show that PVE considers this rule unsatisfiable, and nowhere near `matches`.
+ */
+export const problems = (value: unknown) =>
+  typeof value === 'object' && value !== null
+    ? Object.entries(value)
+        .map(([option, message]) => `${option}: ${String(message)}`)
+        .sort()
+        .join('; ')
+    : '';
+
+/**
+ * A comment as PVE will actually STORE it, which is not always the string it was handed.
+ *
+ * ⛔ PVE DECODES `%XX` OUT OF EVERY COMMENT ON THE WAY IN AND NEVER PUTS IT BACK. MEASURED:
+ *   `PVE::SectionConfig::check_config` runs `decode_value` over each submitted field (line 1625 on
+ *   this node), the base rule plugin's `decode_value` sends `comment` through
+ *   `PVE::ParseUtils::decode_text` — `uri_unescape` then a utf8 decode — and `$get_api_ha_rule`
+ *   hands the comment straight back WITHOUT re-encoding it (only `resources` and `nodes` are
+ *   re-encoded there). So a declared `deploy%20window` is stored and returned as `deploy window`,
+ *   and a `matches` comparing the declared string would report an update on every plan forever
+ *   while every PUT wrote exactly what was already there.
+ *
+ * ★ SO THE COMPARISON MIRRORS THE DECODE RATHER THAN FIGHTING IT. Both sides then say what the
+ *   cluster will really hold, which is the same move `nodeList` above makes for a re-sorted list.
+ * ⚠️ GROUPS OF `%XX` ARE DECODED TOGETHER so a multi-byte utf8 sequence survives; a lone `%` or a
+ *   malformed sequence is left alone, as `uri_unescape` leaves it. The one place this differs from
+ *   Perl is a sequence that is valid percent-encoding but invalid utf8: Perl substitutes U+FFFD,
+ *   this leaves the escape. Nothing in a comment should be reaching for that.
+ */
+export const commentText = (raw: string) =>
+  raw.replace(/(?:%[0-9a-fA-F]{2})+/g, (escaped) => {
+    try {
+      return decodeURIComponent(escaped);
+    } catch {
+      return escaped;
+    }
+  });
+
+/**
+ * Every managed optional, per type: the value to send, or undefined for "clear it".
+ *
+ * ⛔ `disable=0` DOES NOT CLEAR A DISABLED RULE, AND THAT IS THE WORST TRAP IN THIS FAMILY.
+ *   MEASURED in `/usr/share/perl5/PVE/API2/HA/Rules.pm`: both `create_rule` and `update_rule` run
+ *   `delete $param->{disable} if !$param->{disable};` BEFORE the plugin sees the form. A PUT
+ *   carrying `disable=0` is therefore a PUT carrying nothing — PVE answers 200, the rule stays
+ *   disabled, `matches` reports an update on the next plan, and the loop never settles. The only
+ *   way back on is `delete=disable`, which is why `disable` is in this table rather than in
+ *   `required` below.
+ *
+ * ⛔ AND THE BRANCHES CANNOT BE ONE SHARED MAP. `PVE::SectionConfig::delete_from_config` dies
+ *   `no such option '<k>'` for an option the plugin does not declare and `unable to delete
+ *   required option '<k>'` for one it requires — so `delete=strict` against a resource-affinity
+ *   rule is a hard failure, and `delete=nodes` or `delete=resources` would be one against either.
+ *   Only `comment`, `disable` and (node-affinity only) `strict` are clearable at all.
+ *
+ * ⚠️ AN EMPTY `comment` IS A CLEARED ONE. PVE stores whatever string it is given, so writing `''`
+ *   would leave the option present and empty rather than absent; `matches` reads both as `''`, but
+ *   only the delete actually removes the line.
+ */
+export const optional = (props: HaRuleProps): Record<string, string | undefined> => ({
+  comment: props.comment === undefined || props.comment === '' ? undefined : props.comment,
+  disable: props.disable === true ? '1' : undefined,
+  ...(props.type === 'node-affinity' ? { strict: props.strict === true ? '1' : undefined } : {}),
+});
+
+/**
+ * The fields sent on EVERY write, create and update alike.
+ *
+ * ⛔ `type` GOES OUT ON THE UPDATE TOO, AND LEAVING IT OFF BREAKS EVERY PUT. It reads like a
+ *   create-only discriminant — the handler certainly treats it as one, taking the plugin from the
+ *   STORED rule — but the PUT is still validated against a `oneOf` keyed on it. MEASURED in
+ *   `PVE::JSONSchema::check_one_of` on this node: when the type property is absent the validator
+ *   marks EVERY other key unknown and, unless the whole `oneOf` is itself optional, errors on the
+ *   type property; its own comment says "Its type property is otherwise never optional", and
+ *   `SectionConfig::updateSchema` builds that `oneOf` through `combine_schemas` without an
+ *   `optional` flag. So an update that omitted it would fail parameter verification with a pile of
+ *   "unexpected property" errors pointing at the fields it did send. It is safe to send because a
+ *   rule of the other type is reported ABSENT by `attributes` and never reaches a PUT.
+ *
+ * ⚠️ `affinity` IS SENT UNCONDITIONALLY FOR BOTH TYPES. PVE requires it on a resource-affinity
+ *   create and defaults it to `positive` on a node-affinity one; sending it either way means the
+ *   read-back matches on the first plan after the create rather than relying on PVE materialising
+ *   its own default into the file.
+ *
+ * ⚠️ THE LISTS GO OUT IN THEIR NORMALISED FORM, which is not required but is free: PVE re-sorts
+ *   them anyway, so writing what it will hand back keeps the config file readable next to the
+ *   declaration that produced it.
+ *
+ * ⚠️ NO `digest`. PVE accepts one on PUT as an optimistic lock, but the only digest this provider
+ *   could send is the one from its own read moments earlier — and it is a digest of the WHOLE
+ *   rules file, so any unrelated rule written in between would turn a correct update into a
+ *   spurious failure. The factory's read-back guard is the check that stays.
+ */
+const required = (props: HaRuleProps): Record<string, string> => ({
+  affinity: props.affinity,
+  resources: csv(props.resources),
+  type: props.type,
+  ...(props.type === 'node-affinity' ? { nodes: nodeList(props.nodes) } : {}),
+});
+
+export const body = (props: HaRuleProps) => {
+  const fields = required(props);
+  for (const [option, value] of Object.entries(optional(props))) {
+    if (value !== undefined) fields[option] = value;
+  }
+  return fields;
+};
+
+/**
+ * The options an update must explicitly remove.
+ *
+ * ⛔ A PUT THAT OMITS A FIELD DOES NOT CLEAR IT — `update_rule` merges the form into the stored
+ *   rule (`$rule->{$_} = $opts->{$_} for keys $opts->%*`) — so a managed optional needs a matching
+ *   `delete=` the moment its prop goes away. Both halves come off the one table above, which makes
+ *   "managed but not clearable" impossible to write here.
+ * ⚠️ NEVER BOTH AT ONCE: `delete_from_config` dies `cannot set and delete property '<k>' at the
+ *   same time!`. The table answers a value or `undefined`, never both, so the two lists are
+ *   disjoint by construction.
+ * ⚠️ THE CREATE FORM CANNOT USE THIS. `POST /cluster/ha/rules` has no `delete` parameter at all
+ *   (MEASURED from the cluster's own schema), and it needs none: an omitted optional on a brand
+ *   new rule is simply absent.
+ */
+export const clearList = (props: HaRuleProps) =>
+  Object.entries(optional(props))
+    .filter(([, value]) => value === undefined)
+    .map(([option]) => option);