@homeflare/alchemy 0.1.0

package/src/proxmox/network-apply.ts

@@ -0,0 +1,244 @@
+/**
+ * `Proxmox.NetworkApply` — the call that makes a declared interfaces file real, ON ONE NODE.
+ *
+ * ⛔ WITHOUT IT EVERY NETWORK DECLARATION IS A GREEN PLAN THAT CHANGES NO NETWORK; WITH IT A GREEN
+ *   PLAN CAN TAKE A NODE OFF THE NETWORK. Writes under `nodes/{node}/network/{iface}` edit
+ *   `/etc/network/interfaces.new` and touch no interface. `PUT /nodes/{node}/network` is the apply.
+ *   MEASURED in the cluster's own source on n2, 2026-09-13 — `PVE/API2/Network.pm`:
+ *       rename($new_config_file, $current_config_file) if -e $new_config_file;
+ *       PVE::Tools::run_command(['ifreload', '-a'], errfunc => $err);
+ *       return $rpcenv->fork_worker('srvreload', 'networking', $authuser, $worker);
+ *
+ * ⛔ THIS IS THE MOST DANGEROUS RESOURCE IN THE PACKAGE, AND ON TB4 THE DANGER IS NOT ABSTRACT.
+ *   Ceph runs over `vmbr1.11` on n2, n3 AND n4 (MEASURED 2026-09-13: four pools, size 3 /
+ *   min_size 2, mon+mgr+mds on all three). `ifreload -a` takes that node's OSDs, mons and MDS off
+ *   the cluster network for the length of the reload; two nodes at once puts every pool below
+ *   min_size and blocks IO for every guest with an RBD disk. The management address the API is
+ *   reached on, `vmbr0.10`, is reloaded by the same call.
+ *
+ * ⛔ AND UNLIKE `SdnApply` IT IS PER NODE, SO A HALF-RECONFIGURED CLUSTER IS THE DEFAULT FAILURE
+ *   MODE, NOT AN EDGE CASE. `PUT /cluster/sdn` publishes the whole cluster in one call; this
+ *   publishes exactly one node, so a stack holding three of these can apply n2, fail, and leave n3
+ *   and n4 on the old layout with Ceph spanning all three. Four things here exist only for that:
+ *     1. `after` SERIALISES THEM — chain n3 after n2 and n4 after n3, so at most one node is ever
+ *        mid-reload. Three declared in parallel is the outage, and nothing in Alchemy stops you.
+ *     2. `reconcile` REFUSES TO START on a cluster that is already degraded.
+ *     3. `reconcile` RE-CHECKS quorum and every member's `online` flag AFTER the reload and dies if
+ *        the cluster came back worse — which stops the chain before it reaches the second node.
+ *     4. NOTHING IS EVER APPLIED WITH NOTHING STAGED. See the first branch of `apply`.
+ *
+ * ⚠️ IF THE MEMBER SERVING THE POLL IS THE NODE BEING RELOADED, the reload can drop the connection
+ *   carrying its own status poll — see network-apply-read.ts. Every endpoint is `proxyto =>
+ *   'node'`, so any cluster member can serve any other node's paths; failover in client.ts picks
+ *   whichever member is up, not necessarily one you are not applying.
+ *
+ * ⚠️ `DELETE /nodes/{node}/network` IS THE REVERT, AND IT IS DELIBERATELY NOT WIRED TO `delete`.
+ *   MEASURED: the whole body of `revert_network_changes` is `unlink "/etc/network/interfaces.new"`.
+ *   It discards STAGED edits and cannot undo an APPLIED one, so pointing `delete` at it would throw
+ *   away whatever happened to be staged the moment somebody removed a line from a stack file — the
+ *   worst possible time to do it. Revert by hand, deliberately: `pvesh delete /nodes/<node>/network`.
+ *
+ * ⚠️ PRIVILEGES, so widening stays a deliberate act: the `read` role needs nothing for the pending
+ *   read (`GET /nodes/{node}/network` is `"user": "all"`) and `Sys.Audit` on `/` for the health
+ *   gate; the `provision` role needs `Sys.Modify` on `/nodes/{node}` for the apply, and owns the
+ *   task it starts so it can poll it without `Sys.Audit`. ⛔ `Sys.Modify` ON A NODE IS NOT A SMALL
+ *   GRANT — it also carries that node's DNS, hosts file, time and service configuration. Granting
+ *   it cluster-wide to run this resource widens the provisioning role well beyond networking.
+ */
+import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { pveWith } from './client.ts';
+import { mint } from './credentials.ts';
+import { awaitTask, degradedReason, pendingCount } from './network-apply-read.ts';
+import type { PveRequirements } from './resource.ts';
+import type { WithTarget } from './resource.ts';
+
+export interface NetworkApplyProps extends WithTarget {
+  /**
+   * The node whose staged interfaces file this applies — `n2`.
+   *
+   * ⚠️ ONE APPLY PER NODE, AND NEVER TWO FOR THE SAME NODE. Two would each publish the other's
+   *   staged half, and both would run `ifreload` on a file the other had not finished writing.
+   */
+  node: string;
+
+  /**
+   * The staged interface changes this apply publishes, and the apply that must go before it.
+   *
+   * ⚠️ IT IS NEVER READ, AND IT IS NOT DECORATION — the same contract as `SdnApply.after`. Alchemy
+   *   orders resources by DATA FLOW, so consuming an attribute is the only way to say "after".
+   *   Pass the interfaces this node declares AND the previous node's apply:
+   *   `after: [vmbr1.iface, n2Apply.pending]`. Leave the previous apply out and the three nodes
+   *   reload in parallel, which is the one thing this resource is built to prevent.
+   */
+  after?: readonly unknown[];
+}
+
+export interface NetworkApplyAttributes {
+  /** The node this applies. Identity, echoed so a plan line says which member it will reload. */
+  node: string;
+
+  /**
+   * Changed lines still staged on this node.
+   *
+   * ⚠️ LINES OF A UNIFIED DIFF, NOT INTERFACES, and the number is reported rather than trusted —
+   *   `pendingLines` explains why it can undercount by one and never to zero. Zero is the only
+   *   settled value: anything above it means the running config and the staged config disagree,
+   *   whether this stack staged it or somebody edited the node in the UI and walked away.
+   *
+   * ⛔ THE DIFF ITSELF IS NEVER AN ATTRIBUTE. Alchemy writes attributes to its state store
+   *   UNENCRYPTED, and `/etc/network/interfaces` can carry a `wpa-psk` or a `pre-up` command. Only
+   *   the count leaves `network-apply-read.ts`.
+   *
+   * ⚠️ AND NOTHING OUT OF THE INTERFACE ROWS IS AN ATTRIBUTE EITHER, WHICH IS WHAT KEEPS THIS
+   *   FAMILY NOOP. `GET /nodes/{node}/network` returns eighteen fields it will not accept on write
+   *   — MEASURED by differencing the schema's GET return properties against its POST parameters:
+   *   `active`, `exists`, `families`, `method`, `method6`, `options`, `priority`, `link-type` and
+   *   ten more; `altnames` is returned and is not even in the schema. `priority` is the worst of
+   *   them: PVE ASSIGNS it from the order of the interfaces file, so the same logical layout
+   *   carries different numbers on different nodes (MEASURED: n4's differ from n2/n3's by one).
+   *   Every one of those is a forever-diff waiting for whoever writes `Proxmox.NetworkInterface`.
+   *   This resource compares a single integer against zero and never looks at a row at all.
+   */
+  pending: number;
+}
+
+export interface ProxmoxNetworkApply extends Resource<
+  'Proxmox.NetworkApply',
+  NetworkApplyProps,
+  NetworkApplyAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxNetworkApply = Resource<ProxmoxNetworkApply>('Proxmox.NetworkApply');
+
+const read = (props: NetworkApplyProps) =>
+  pendingCount(props.target, props.node).pipe(
+    Effect.map((pending) => ({ node: props.node, pending })),
+  );
+
+/**
+ * ⚠️ THE DIFF IS ABOUT THE NODE, NOT ABOUT THE PROPS — the same reasoning as `SdnApply`. This
+ *   resource has no settable field (`node` is identity, `after` is an ordering edge), so comparing
+ *   props to props would report `noop` forever and the apply would run exactly once, ever. What
+ *   decides it is whether the node is carrying a staged change right now.
+ *
+ * ★ THIS IS ALSO WHY DECLARING THE LIVE CLUSTER PLANS AS `noop`. VERIFIED 2026-09-13:
+ *   `/etc/network/interfaces.new` is absent on n2, n3 and n4, so `changes` is absent from all three
+ *   answers, so `pending` is 0 on all three and every one of them plans `noop`.
+ */
+const diff = (news: Input<NetworkApplyProps>) =>
+  Effect.gen(function* () {
+    if (!isResolved(news)) return undefined;
+    const { pending } = yield* read(news);
+    return pending === 0 ? ({ action: 'noop' } as const) : ({ action: 'update' } as const);
+  });
+
+/** Stop the deploy, loudly, with the node in the message. ⚠️ A die here is the SAFE outcome. */
+const refuse = (node: string, why: string) =>
+  Effect.die(new Error(`Proxmox.NetworkApply ${node}: ${why}`));
+
+const apply = (props: NetworkApplyProps) =>
+  Effect.gen(function* () {
+    const node = props.node;
+    const staged = yield* pendingCount(props.target, node);
+    /**
+     * ⛔ NOTHING STAGED MEANS NOTHING TO APPLY, AND THIS BRANCH IS A SAFETY PROPERTY RATHER THAN AN
+     *   OPTIMISATION. `reconcile` also runs on CREATE — the first time this resource appears in a
+     *   stack, before `diff` has ever been consulted — and the PVE worker runs `ifreload -a`
+     *   UNCONDITIONALLY, staged file or not. Without this branch, adding `Proxmox.NetworkApply` to
+     *   a stack describing the cluster as it already is would reload networking on every node it
+     *   names, for nothing. Adoption must cost nothing; that is true here in the strongest sense.
+     */
+    if (staged === 0) return { node, pending: 0 };
+
+    const before = yield* degradedReason(props.target);
+    if (before !== undefined) {
+      return yield* refuse(
+        node,
+        `refusing to reload networking on a cluster that is already degraded (${before}). ` +
+          'Ceph spans these nodes -- fix the cluster first, then re-run the deploy.',
+      );
+    }
+
+    /**
+     * ⚠️ ONE LEASE FOR BOTH CALLS, VIA `pveWith` RATHER THAN `pve`. Each mint returns a NEW token
+     *   id, and the task-status endpoint only skips its `Sys.Audit` check for the task's OWNER —
+     *   so polling with a fresh mint is a different identity and needs a privilege this role does
+     *   not have. The `provision` lease is 300s and non-renewable, which is far longer than a
+     *   reload and is the reason no renew path is reached for.
+     */
+    const credential = yield* mint(props.target, 'provision');
+    const upid = yield* pveWith<string>(props.target, credential, 'PUT', `nodes/${node}/network`);
+    if (upid === undefined) {
+      return yield* refuse(
+        node,
+        'the apply returned no UPID. PVE wraps every answer in {"data":...} and can report success ' +
+          'on a call that did nothing -- the reload cannot be confirmed, so it is not claimed.',
+      );
+    }
+
+    /**
+     * ⛔ POLLING `pending` INSTEAD OF THE TASK WOULD REPORT SUCCESS BEFORE THE NETWORK WAS TOUCHED.
+     *   MEASURED in the worker above: the `rename` happens FIRST and `ifreload -a` second, so the
+     *   staged file — and therefore `changes`, and therefore `pending` — disappears while the
+     *   reload has not yet started. A provider that watched the count would call a reload that had
+     *   not run, and a reload that then FAILED, a success. The task's exitstatus is the only
+     *   honest answer.
+     */
+    const exitstatus = yield* awaitTask(props.target, credential, node, upid);
+    if (exitstatus !== 'OK') {
+      return yield* refuse(
+        node,
+        `the reload ended "${exitstatus}" (${upid}). Read it from ANOTHER node -- ` +
+          `\`pvesh get /nodes/${node}/tasks/${upid}/log\` -- and do not apply the next node until ` +
+          'this one is understood.',
+      );
+    }
+
+    const after = yield* degradedReason(props.target);
+    if (after !== undefined) {
+      return yield* refuse(
+        node,
+        `the reload reported OK but the cluster is now degraded (${after}). The next ` +
+          'node has NOT been applied. Restore this one before continuing -- Ceph runs over these ' +
+          'links and a second reload now would take pools below min_size.',
+      );
+    }
+
+    const left = yield* pendingCount(props.target, node);
+    if (left !== 0) {
+      return yield* refuse(
+        node,
+        `the reload reported OK but ${String(left)} staged line(s) remain. The running config does ` +
+          'not match the declared one, and saying otherwise is the lie this resource exists to stop.',
+      );
+    }
+    return { node, pending: left };
+  });
+
+/**
+ * ⛔ HAND-WRITTEN RATHER THAN `pveHandlers`, FOR THE SAME REASON `sdn-apply.ts` IS. The factory's
+ *   spec is create/update/delete over ONE object at ONE path, and an apply is not an object: there
+ *   is nothing to POST, nothing to DELETE, and `matches` would compare a declaration to itself and
+ *   answer `noop` forever, so the apply would run exactly once in the life of the stack. `list` is
+ *   empty for the reason it is everywhere in this package — adoption stays an explicit act.
+ *
+ * ⛔ `delete` APPLIES NOTHING AND UNDOES NOTHING, AND THAT IS CORRECT. There is no un-apply: the
+ *   config is already live on the node, and the way to remove an interface is to delete it and
+ *   apply AGAIN. See the ⚠️ about `DELETE /nodes/{node}/network` at the top of this file.
+ */
+const handlers = {
+  delete: () => Effect.void,
+  diff: ({ news }: { news: Input<NetworkApplyProps> }) => diff(news),
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: NetworkApplyProps }) => read(olds),
+  reconcile: ({ news }: { news: NetworkApplyProps }) => apply(news),
+};
+
+export const ProxmoxNetworkApplyProvider = () =>
+  Provider.effect(ProxmoxNetworkApply, Effect.succeed(ProxmoxNetworkApply.Provider.of(handlers)));

package/src/proxmox/node-network-form.ts

@@ -0,0 +1,213 @@
+/**
+ * How a node interface crosses the wire in both directions — props to a PVE form, a PVE answer to
+ * a comparable attribute — and when two of those values count as the same value.
+ *
+ * ★ SPLIT OUT OF node-network.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is the
+ *   same one metric-server-form.ts uses, one field wider: this file owns the COERCIONS, in both
+ *   directions, because a read that normalises differently from the write that produced it is
+ *   exactly how a forever-diff is born — keeping `ifaceList` next to both ends is what stops that.
+ *   node-network.ts answers "what is an interface, and which of its fields are safe to compare at
+ *   all". Nothing here calls the cluster.
+ *
+ * ⚠️ THE `import type` BACK TO node-network.ts IS A CYCLE ON PAPER ONLY — type-only, erased before
+ *   anything runs, so `NodeNetworkProps` stays in the file that declares the resource.
+ *
+ * * ⛔ THE LAST SEVEN ARE REPORTED AND NEVER COMPARED, AND EACH ONE IS A MEASURED FOREVER-DIFF.
+ *   `priority` is assigned by PVE FROM FILE ORDER — `my $priority = 2; ... $d->{priority} =
+ *   $priority++` — and it is not a POST or PUT parameter at all. MEASURED ACROSS TB4: vmbr1.11 is
+ *   priority 16 on n2 and n3 and 15 on n4, because n4 has no `wlp91s0` above it. One declaration
+ *   reused across three nodes would diff on exactly one of them, forever, over nothing.
+ *   `method` is RECOMPUTED on every write from whether the form carried an address, `families` is
+ *   recomputed the same way and never written to the file, `active` and `exists` describe the
+ *   kernel rather than the config, and `bond_miimon`, `bridge_stp` and `bridge_fd` are emitted by
+ *   PVE's writer with defaults (100, `off`, 0) while appearing in NEITHER write schema —
+ *   `additionalProperties => 0` means sending one is a 400. Live proof of all three: n2's bond0
+ *   returns `bond_miimon "100"` and vmbr1 returns `bridge_stp "off"`, `bridge_fd "0"`, none of
+ *   which any declaration can set.
+ */
+import type { NodeNetworkAttributes, NodeNetworkProps } from './node-network.ts';
+import { bool, flag, int, text, withClears } from './values.ts';
+
+/**
+ * "Not set", for the three integers this family reports.
+ *
+ * ⚠️ 0 CANNOT BE THE ABSENT-MARKER AND -1 CAN. `mtu` is 1280-65520, `vlan-id` 1-4094 and PVE's
+ *   `priority` starts at 1 (1 is reserved for `lo`), so -1 is outside every one of their ranges
+ *   while 0 is merely outside today's. metric-server-form.ts keeps its own constant for the same
+ *   reason and against different ranges; one shared UNSET would have to be right for both.
+ */
+export const UNSET = -1;
+
+/**
+ * A space-separated interface list, flattened to one comparable form.
+ *
+ * ⚠️ `bridge_ports` AND `slaves` ARE SETS, AND PVE NORMALISES THEIR SEPARATORS BUT NOT THEIR ORDER.
+ *   MEASURED in PVE::Network::Interfaces: the writer does `s/[;,\s]+/ /g` on both before emitting
+ *   them, and the reader hands the resulting string straight back — so `enp2s0f1np1 enp2s0f0np0`
+ *   survives a round trip in the order it was written. Order carries no meaning for a bridge's
+ *   ports or a bond's slaves, so a declaration that lists them the other way round is the SAME
+ *   declaration; comparing raw strings would report an update that rewrites the file to say
+ *   exactly what it already said. Both sides are sorted here and only then compared.
+ *
+ * ⚠️ IT IS NOT `csv` FROM values.ts. That one joins with commas, and a comma in
+ *   `/etc/network/interfaces` is not a separator — PVE's own comment above the writer says the
+ *   list "must be space separated! other separators will cause problems". Sending a comma-joined
+ *   value would be accepted by `split_list` and then written back as spaces, which is a second
+ *   spelling of one value and therefore a second chance to diff.
+ *
+ * ⚠️ `bridge_vids` GOES THROUGH THE SAME FUNNEL and its sort is LEXICAL, which is correct only
+ *   because a vid list is a set: `2-4094` is one token, and `100-200 2` and `2 100-200` allow the
+ *   same VLANs. Nothing here should be reused for a list whose order is meaning.
+ */
+export const ifaceList = (value: unknown) =>
+  text(value)
+    .split(/[\s,;]+/)
+    .filter((part) => part !== '')
+    .sort()
+    .join(' ');
+
+/**
+ * A comment off the wire, with the newline PVE adds taken back off.
+ *
+ * ⛔ `comments` NEVER ROUND-TRIPS RAW, AND THAT IS A FOREVER-DIFF IF IT IS NOT NORMALISED.
+ *   MEASURED in the reader: each `#...` line is appended as `$comment . "\n"`, so a declared
+ *   `ceph transport` comes back as `ceph transport\n` and the two never compare equal.
+ * ⚠️ AND THE READER FOLDS `comments6` INTO `comments` (`$d->{comments} .= $comments6`), so on an
+ *   interface that carries an IPv6 comment a declared `comments` CANNOT match what comes back.
+ *   TB4 has none; on an interface that does, leave `comments` undeclared rather than fighting it.
+ */
+export const comment = (value: unknown) => text(value).replace(/\s+$/, '');
+
+/** Undeclared is unmanaged: neither sent nor compared. See the ⚠️ on `body`. */
+export const same = <T>(declared: T | undefined, live: T) =>
+  declared === undefined || declared === live;
+
+export const sameList = (declared: string | undefined, live: string) =>
+  declared === undefined || ifaceList(declared) === live;
+
+export const sameComment = (declared: string | undefined, live: string) =>
+  declared === undefined || comment(declared) === live;
+
+const field = (name: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [name]: value };
+
+/**
+ * The fields sent on EVERY write, create and update alike.
+ *
+ * ⚠️ UNDECLARED IS UNMANAGED — not sent, and not compared either. PVE's PUT MERGES the form into
+ *   the existing stanza (`foreach my $k (keys %$param) { $ifaces->{$iface}->{$k} = $param->{$k} }`),
+ *   so an omitted parameter is left exactly as it was. `cidr` is the one exception and it is not
+ *   a small one — see the ⛔ in node-network.ts.
+ *
+ * ⛔ `type` IS REQUIRED ON THE PUT, NOT ONLY ON THE POST. It carries no `optional` in either
+ *   schema, and the merge above writes it straight into the stanza — so a PUT naming the wrong
+ *   type would RETYPE A LIVE INTERFACE in the file and the writer would then emit a bridge stanza
+ *   for what is really a vlan. node-network.ts refuses that case before it can reach here.
+ *
+ * ⛔ `bridge_vlan_aware` IS SENT ONLY WHEN TRUE, AND A FALSE ONE IS A `delete=`. MEASURED in the
+ *   writer: the test is `if (defined($d->{bridge_vlan_aware}))`, not a truth test, so `0` is
+ *   defined and PVE writes `bridge-vlan-aware yes` anyway. Sending `0` would therefore turn the
+ *   flag ON, read back as `1`, and diff forever while lying about which way it went.
+ *
+ * ⚠️ `netmask` IS A WRITABLE PARAMETER AND IS DELIBERATELY NOT OFFERED. PVE raises
+ *   "netmask conflicts with cidr" when both are sent, and the reader rewrites whatever was written
+ *   into prefix form — MEASURED: n2's vmbr1.11 reports `"netmask":"24"`, never `255.255.255.0`.
+ *   A resource accepting both spellings would let a declaration diff against its own value.
+ */
+export const body = (props: NodeNetworkProps): Record<string, string> => ({
+  ...field('autostart', flag(props.autostart)),
+  ...field('bond-primary', props['bond-primary']),
+  ...field('bond_mode', props.bond_mode),
+  ...field('bond_xmit_hash_policy', props.bond_xmit_hash_policy),
+  ...field('bridge_ports', props.bridge_ports),
+  ...field('bridge_vids', props.bridge_vids),
+  ...field('bridge_vlan_aware', props.bridge_vlan_aware === true ? '1' : undefined),
+  ...field('cidr', props.cidr),
+  ...field('comments', props.comments),
+  ...field('gateway', props.gateway),
+  ...field('mtu', props.mtu === undefined ? undefined : String(props.mtu)),
+  ...field('slaves', props.slaves),
+  ...field('vlan-id', props['vlan-id'] === undefined ? undefined : String(props['vlan-id'])),
+  ...field('vlan-raw-device', props['vlan-raw-device']),
+  type: props.type,
+});
+
+/**
+ * The update form: `body` plus the two fields that can only be cleared explicitly.
+ *
+ * ⛔ `delete=cidr` IS SENT WHENEVER `cidr` IS UNDECLARED, AND IT IS THE LESSER OF TWO EVILS RATHER
+ *   THAN A GOOD OUTCOME. PVE recomputes the method on every write from the form alone —
+ *   `$param->{method} = $param->{address} ? 'static' : 'manual'` — so a PUT WITHOUT an address
+ *   makes the interface manual no matter what the caller intended. Left at that, the merge would
+ *   leave the old `address` and `netmask` in the hash and the writer would emit an `address` line
+ *   under `iface … inet manual`: a stanza PVE's own UI cannot produce, whose behaviour under
+ *   `ifreload -a` I did NOT measure. Clearing cidr explicitly at least produces a clean, honest
+ *   manual interface — and `matches` compares `cidr` UNCONDITIONALLY, so the plan says so first.
+ *
+ * ⛔ ON vmbr1.11 THAT IS THE CEPH TRANSPORT. A declaration of that interface without its `cidr` is
+ *   a declaration that it should have no address, applied across three nodes. The plan will read
+ *   `1 to update` rather than `noop`; do not wave it through.
+ *
+ * ⚠️ `delete` IS A PUT-ONLY PARAMETER. The POST schema is `additionalProperties => 0` and has no
+ *   `delete`, so sending it on a create is a 400 — which is why `createForm` calls `body` directly.
+ */
+export const updateBody = (props: NodeNetworkProps): Record<string, string> => {
+  const clear = [
+    ...(props.cidr === undefined ? ['cidr'] : []),
+    ...(props.bridge_vlan_aware === false ? ['bridge_vlan_aware'] : []),
+  ];
+  const fields = body(props);
+  return withClears(fields, clear);
+};
+
+/**
+ * One live interface as attributes, or `undefined` — "this is not really there".
+ *
+ * ⚠️ EVERY FIELD PVE REPORTS IS CARRIED HERE, INCLUDING THE SEVEN NO DECLARATION CAN SET. A plan
+ *   that cannot show `priority`, `method` or `bond_miimon` cannot explain why it is ignoring them,
+ *   and the next person to read a forever-diff would start by adding them to `matches`. They are
+ *   reported precisely so that they are visibly OUT of it — see the ⛔ above the attribute type.
+ */
+export const readAttributes = (
+  live: Record<string, unknown>,
+  props: NodeNetworkProps,
+): NodeNetworkAttributes | undefined => {
+  /**
+   * ⛔ AN INTERFACE OF ANOTHER TYPE IS ANOTHER OBJECT, AND "ABSENT" IS THE SAFE ANSWER — the
+   *   same call metric-server.ts makes, for a worse reason. `type` is required on the PUT and
+   *   the PUT MERGES, so a declaration naming `bridge` for what is really a vlan would write
+   *   `type bridge` into the stanza and PVE's writer would then emit bridge-ports and
+   *   bridge-stp lines for vmbr1.11. Reporting absent instead makes reconcile POST a create,
+   *   which PVE refuses with "interface already exists": loud, and it changes nothing.
+   */
+  const liveType = text(live['type']);
+  if (liveType !== '' && liveType !== props.type) return undefined;
+  return {
+    active: bool(live['active']),
+    autostart: bool(live['autostart']),
+    'bond-primary': text(live['bond-primary']),
+    bond_miimon: text(live['bond_miimon']),
+    bond_mode: text(live['bond_mode']),
+    bond_xmit_hash_policy: text(live['bond_xmit_hash_policy']),
+    bridge_fd: text(live['bridge_fd']),
+    bridge_ports: ifaceList(live['bridge_ports']),
+    bridge_stp: text(live['bridge_stp']),
+    bridge_vids: ifaceList(live['bridge_vids']),
+    bridge_vlan_aware: bool(live['bridge_vlan_aware']),
+    /** ⚠️ DERIVED BY THE READER from address+netmask, and always present when an address is. */
+    cidr: text(live['cidr']),
+    comments: comment(live['comments']),
+    exists: bool(live['exists']),
+    families: Array.isArray(live['families']) ? live['families'].join(',') : '',
+    gateway: text(live['gateway']),
+    iface: props.iface,
+    method: text(live['method']),
+    mtu: int(live['mtu'], UNSET),
+    node: props.node,
+    priority: int(live['priority'], UNSET),
+    slaves: ifaceList(live['slaves']),
+    type: liveType === '' ? props.type : liveType,
+    'vlan-id': int(live['vlan-id'], UNSET),
+    'vlan-raw-device': text(live['vlan-raw-device']),
+  };
+};