@homeflare/alchemy 0.34.0 → 0.35.0

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

@@ -0,0 +1,239 @@
+/**
+ * `Proxmox.NodeNetwork`'s READ side: the coercions in both directions, the read itself, and
+ * `matches`. Split out of node-network-form.ts (2026-09-24, the distilled migration) — the
+ * storage.ts/storage-wire.ts seam; the write side stays in node-network-form.ts.
+ *
+ * * ⛔ 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 C1: vmbr1.42 is
+ *   priority 16 on node-b and node-c and 15 on node-d, because node-d has no `wlan0` 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: node-b's bond0
+ *   returns `bond_miimon "100"` and vmbr1 returns `bridge_stp "off"`, `bridge_fd "0"`, none of
+ *   which any declaration can set.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
+import {
+  type NodeNetworkProps,
+  UNSET,
+  comment,
+  ifaceList,
+  same,
+  sameComment,
+  sameList,
+} from './node-network-form.ts';
+import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
+import { bool, int, text } from './values.ts';
+
+/**
+ * PVE's interface types. `unknown` is what a NIC it does not manage reports — node-b and node-c
+ * both report `wlan0` that way, and node-d has no such interface at all.
+ *
+ * ⚠️ THAT ASYMMETRY IS A TRAP FOR A DECLARATION SHARED ACROSS NODES. On node-d the read answers
+ *   400 ("interface does not exist"), 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';
+
+/**
+ * ⛔ THE LAST SEVEN ARE REPORTED AND NEVER COMPARED — each is a MEASURED forever-diff, and the
+ *   evidence for every one of them is below, 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;
+}
+
+/**
+ * One live interface as attributes. `live` is cast past `GetNodeNetworkResponse`'s own TS type
+ * (`{method, type}`) — MEASURED: the generated schema is a lower bound, not the full shape (PVE's
+ * response varies by interface type, and the apidoc this was generated from does not enumerate
+ * every field it can carry), but decoding does NOT strip the extras (Effect Schema's `S.Struct` is
+ * structural, not exact) — every field PVE actually returns survives to this object at runtime,
+ * confirmed against the full measured `vmbr0` response below.
+ *
+ * ⚠️ 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 module header.
+ */
+const attributesOf = (
+  live: unknown,
+  props: NodeNetworkProps,
+): NodeNetworkAttributes | undefined => {
+  const data = live as Record<string, unknown>;
+  /**
+   * ⛔ 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.42. Reporting absent instead makes reconcile POST a create,
+   *   which PVE refuses with "interface already exists": loud, and it changes nothing.
+   */
+  const liveType = text(data['type']);
+  if (liveType !== '' && liveType !== props.type) return undefined;
+  return {
+    active: bool(data['active']),
+    autostart: bool(data['autostart']),
+    'bond-primary': text(data['bond-primary']),
+    bond_miimon: text(data['bond_miimon']),
+    bond_mode: text(data['bond_mode']),
+    bond_xmit_hash_policy: text(data['bond_xmit_hash_policy']),
+    bridge_fd: text(data['bridge_fd']),
+    bridge_ports: ifaceList(data['bridge_ports']),
+    bridge_stp: text(data['bridge_stp']),
+    bridge_vids: ifaceList(data['bridge_vids']),
+    bridge_vlan_aware: bool(data['bridge_vlan_aware']),
+    /** ⚠️ DERIVED BY THE READER from address+netmask, and always present when an address is. */
+    cidr: text(data['cidr']),
+    comments: comment(data['comments']),
+    exists: bool(data['exists']),
+    families: Array.isArray(data['families']) ? data['families'].join(',') : '',
+    gateway: text(data['gateway']),
+    iface: props.iface,
+    method: text(data['method']),
+    mtu: int(data['mtu'], UNSET),
+    node: props.node,
+    priority: int(data['priority'], UNSET),
+    slaves: ifaceList(data['slaves']),
+    type: liveType === '' ? props.type : liveType,
+    'vlan-id': int(data['vlan-id'], UNSET),
+    'vlan-raw-device': text(data['vlan-raw-device']),
+  };
+};
+
+/**
+ * ★ Default `read` role — `Sys.Audit` on `/nodes/{node}` (node-network.ts's header).
+ * ⛔ `{ node: props.node, iface: props.iface }`, NEVER THE WHOLE `props` — storage.ts's/user.ts's
+ *   own ⛔, the kit 0.31.1 regression: `GetNodeNetworkRequest`'s schema declares only `node` and
+ *   `iface` (both path labels); any OTHER key on the object passed to `nodes.getNodeNetwork` is
+ *   treated by distilled's `buildRequest` as an "unknown key" and JSON-encoded onto this bodyless
+ *   GET, which a stricter fetch client refuses outright.
+ * ⛔ A MISSING INTERFACE IS A 400, NOT A 500 AND NOT A 404 — MEASURED against the live cluster
+ *   (TB4 `n2`, read-role, read-only probe, 2026-09-24): `GET /nodes/n2/network/vmbr9` answers
+ *   `{"errors":{"iface":"interface does not exist"},"data":null,"message":"Parameter verification
+ *   failed.\n"}` at HTTP 400 — a THIRD shape, different from every other migrated family's
+ *   measured 500. `@distilled.cloud/proxmox` types this as a genuine typed error,
+ *   `ParameterVerificationFailed` (`errors.ts`), carrying the per-field `errors` object rather
+ *   than collapsing it to an opaque `BadRequest` — PVE's OWN 400 is never one shape (it is
+ *   whatever the endpoint's parameter verification rejected), so `errors.ts`'s own header spells
+ *   out why this ONE typed error is global rather than per-operation.
+ * ⛔ ONLY THIS EXACT SIGNAL MEANS ABSENT, EVEN WITH THE FOLD BELOW. A different 400 reason, a
+ *   permission gap, a network blip, or ANY OTHER `ParameterVerificationFailed` reason is never
+ *   read as "this interface is not there" — `diff` calls this directly and propagates every one
+ *   of them loudly.
+ */
+export const readInterfaceOrFail = (props: NodeNetworkProps) =>
+  readOrUnreadable(
+    runPve(
+      props.target,
+      'read',
+      false,
+      nodes.getNodeNetwork({ iface: props.iface, node: props.node }),
+    ).pipe(
+      Effect.catchTag('ParameterVerificationFailed', (error) =>
+        error.errors['iface'] === 'interface does not exist'
+          ? Effect.succeed(undefined)
+          : Effect.fail(error),
+      ),
+    ),
+  ).pipe(
+    Effect.map((live) => {
+      if (live === UNREADABLE) return UNREADABLE;
+      return live === undefined ? undefined : attributesOf(live, props);
+    }),
+  );
+
+/**
+ * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`'s adoption/recovery branch
+ *   AND `reconcile` MAY USE IT — FOUND BY ADVERSARIAL REVIEW, 2026-09-24: a first draft used
+ *   `readInterfaceOrFail` (precise, non-folding) for EVERY caller, on the reasoning that a typed,
+ *   parsed absence signal made folding unnecessary. That reasoning conflated two different
+ *   questions: HOW PRECISELY a signal means absent (this family's is unusually precise), and
+ *   WHETHER a given caller can safely treat an UNRELATED failure as "proceed as though absent"
+ *   (storage.ts's/user.ts's own reasoning: a wrongful fold costs at most a redundant
+ *   `createNodeNetwork` POST, refused loudly). Plan.ts's cold-start adoption probe and
+ *   interrupted-create recovery, and Apply.ts's delete recovery, all call `read` with
+ *   `output: undefined` and NO catch of their own (`Plan.ts` v2.0.0-beta.79 ~line 1308) — and
+ *   Plan.ts fails the WHOLE PLAN, every other resource included, if that call throws. A malformed
+ *   `iface` in ONE brand-new declaration (a DIFFERENT `ParameterVerificationFailed` than the
+ *   absence one) would abort `bun run plan` for the entire stack under the precise-only design,
+ *   where every other migrated family instead defers that same malformed declaration to a scoped,
+ *   loud refusal at apply. This restores that same fold for those three call sites.
+ */
+export const readInterface = (props: NodeNetworkProps) =>
+  readInterfaceOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+export const dropUnreadable = (live: NodeNetworkAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
+
+/**
+ * ⛔ `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 C1 declaration
+ *   plan as `noop` on all three nodes at once — the module header lists them and the
+ *   measurement behind each.
+ */
+export const matches = (attributes: NodeNetworkAttributes, props: NodeNetworkProps) =>
+  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']);

package/src/proxmox/node-network.ts

@@ -11,6 +11,9 @@
  *   that apply — this one never calls it, exactly as `Proxmox.SdnZone` never calls
  *   `Proxmox.SdnApply`.
  *
+ * ⛔ `Proxmox.NetworkApply` STAYS ON `client.ts`, NOT MIGRATED WITH THIS FILE — network-apply-
+ *   read.ts's own header has the two MEASURED reasons distilled cannot represent yet.
+ *
  * ⛔ CEPH ON C1 RIDES TWO NETWORKS AND THIS API ONLY SEES ONE OF THEM. Measured from
  *   `/etc/pve/ceph.conf` on 2026-09-13:
  *
@@ -18,7 +21,8 @@
  *     cluster_network = 203.0.113.0/24     -> every OSD's cluster_addr: .102 / .103 / .104
  *
  *   The cluster network — OSD REPLICATION, the traffic that rebuilds a lost replica — lives on
- *   `203.0.113.10X/32` addresses carried by `tb0`, `tb1` and `dummy_c1`: the Thunderbolt mesh.
+ *   `203.0.113.10X/32` addresses carried by `tb0`, `tb1` and `dummy_c1`: the Thunderbolt mesh —
+ *   TB4's own fabric ports, EXCLUDED from this family by decision 28/29/9 (SdnFabric owns them).
  *
  * ⛔ 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.
@@ -34,8 +38,9 @@
  *   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`).
+ *   unconditionally (node-network-wire.ts's own ⛔ on `matches`), and a live interface whose
+ *   `type` disagrees with the declaration is reported ABSENT rather than retyped
+ *   (node-network-wire.ts's `attributesOf`).
  *
  * ★ 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}`
@@ -48,11 +53,9 @@
  *   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.
+ * ★ A RECONCILE OVER A MATCHING INTERFACE IS A NO-WRITE. `reconcile` below gates the PUT on
+ *   `matches` first — adopting an interface a node already has must not leave it holding a
+ *   pending network change, since a PUT under `/nodes/{node}/network/{iface}` STAGES one.
  *
  * ⚠️ 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.42`, where PVE had
@@ -64,124 +67,41 @@
  *   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.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `nodes.getNodeNetwork`/`createNodeNetwork`/`putNodeNetwork2`/`deleteNodeNetwork2`
+ *   (2026-09-24, decision 43). Dual-path read and `read`'s `output`-branching wired like every
+ *   other migrated family; node-network-wire.ts's `readInterfaceOrFail` has the new nuance.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
 import * as Effect from 'effect/Effect';
+import { guardWrite } from './distilled-guard.ts';
 import {
-  createBody,
-  readAttributes,
-  same,
-  sameComment,
-  sameList,
-  updateBody,
+  NODE_NETWORK_CREATE,
+  NODE_NETWORK_UPDATE,
+  type NodeNetworkProps,
+  createForm,
+  updateForm,
 } 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 — node-b and node-c both
- * report `wlan0` that way, and node-d has no such interface at all.
- *
- * ⚠️ THAT ASYMMETRY IS A TRAP FOR A DECLARATION SHARED ACROSS NODES. On node-d 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.42`. 2-20 characters, PVE's `pve-iface` format. */
-  iface: string;
-  /** ⛔ REQUIRED ON EVERY WRITE, update included, never used to retype — see `readAttributes`. */
-  type: NodeNetworkType;
-  /**
-   * `198.51.100.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 C1 it is vmbr0.41'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 C1 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.42` reports `vlan-id` 42 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;
-}
+import {
+  dropUnreadable,
+  matches,
+  readInterface,
+  readInterfaceOrFail,
+} from './node-network-wire.ts';
+import type { NodeNetworkAttributes } from './node-network-wire.ts';
+import { runPve } from './distilled-pve.ts';
+import { type PveRequirements } from './resource-spec.ts';
+import { UNREADABLE, unreadableWarning } from './unreadable-read.ts';
 
-/**
- * ⛔ 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 type { NodeNetworkAttributes, NodeNetworkType } from './node-network-wire.ts';
+// ⚠️ MOVED TO node-network-form.ts IN THIS PR'S LINE-CAP TRIM — every field on it is already
+//   documented there against `body`/`createForm`/`updateForm`, so it travels with them rather
+//   than duplicating that documentation here. Nothing about its shape changed.
+export type { NodeNetworkProps } from './node-network-form.ts';
 
 export interface ProxmoxNodeNetwork extends Resource<
   'Proxmox.NodeNetwork',
@@ -196,54 +116,122 @@ export const ProxmoxNodeNetwork = Resource<ProxmoxNodeNetwork>('Proxmox.NodeNetw
   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`. `iface` IS in the create
-   *   body though, and was missing until 2026-09-22 — the 🔴 on `createBody`. */
-  createForm: createBody,
-  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /nodes/{node}/network',
-    update: 'pve:PUT /nodes/{node}/network/{iface}',
-  },
-  /**
-   * ⛔ `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 C1 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.
+ * The three fields distilled's generator renamed to an underscore (`bond-primary`, `vlan-id`,
+ * `vlan-raw-device`) — everything else round-trips as-is. `storage-form.ts`'s `underscored` is a
+ * generic transform for a free-form bag; this family's fields are all named ahead of time, so a
+ * small local map is clearer than importing a generic helper for three keys. Moved here from
+ * node-network-form.ts in this PR's line-cap trim — this is the only caller.
  */
+const RENAMED: Readonly<Record<string, string>> = {
+  'bond-primary': 'bond_primary',
+  'vlan-id': 'vlan_id',
+  'vlan-raw-device': 'vlan_raw_device',
+};
+
+const toDistilled = (form: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(Object.entries(form).map(([key, value]) => [RENAMED[key] ?? key, value]));
+
+/** The actual `createNodeNetwork` call body — `createForm`, translated once. See `toDistilled`. */
+const toDistilledCreate = (props: NodeNetworkProps): nodes.CreateNodeNetworkRequest =>
+  ({
+    ...toDistilled(createForm(props)),
+    node: props.node,
+  }) as unknown as nodes.CreateNodeNetworkRequest;
+
+/** The actual `putNodeNetwork2` call body — `updateForm`, translated once. See `toDistilledCreate`. */
+const toDistilledUpdate = (props: NodeNetworkProps): nodes.PutNodeNetwork2Request =>
+  ({
+    ...toDistilled(updateForm(props)),
+    iface: props.iface,
+    node: props.node,
+  }) as unknown as nodes.PutNodeNetwork2Request;
+
 export const ProxmoxNodeNetworkProvider = () =>
-  Provider.effect(ProxmoxNodeNetwork, Effect.succeed(ProxmoxNodeNetwork.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxNodeNetwork,
+    Effect.succeed(
+      ProxmoxNodeNetwork.Provider.of({
+        /**
+         * ⛔ EMPTY, AND HERE IT MATTERS MORE THAN ANYWHERE ELSE IN THIS PACKAGE. `GET
+         *   /nodes/{node}/network` returns every interface the node has. Adoption stays explicit.
+         */
+        list: () => Effect.succeed([]),
+        // ⚠️ FOLDS ONLY WHEN `output` IS `undefined`, restored by adversarial review after a
+        //   first draft dropped it — node-network-wire.ts's `readInterface` has the reasoning.
+        read: Effect.fn(function* ({ olds, output }) {
+          return dropUnreadable(
+            yield* output === undefined ? readInterface(olds) : readInterfaceOrFail(olds),
+          );
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(NODE_NETWORK_CREATE, createForm(news), output === undefined);
+          yield* guardWrite(NODE_NETWORK_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          const live = yield* readInterfaceOrFail(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused mint used to fall into `undefined` and force `update`
+          //   on an interface that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.NodeNetwork', `${news.node}/${news.iface}`);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            yield* guardWrite(NODE_NETWORK_CREATE, createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        /**
+         * ⛔ 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` (a DIFFERENT, collection-level endpoint —
+         *   `Proxmox.NetworkApply`'s own revert, never called here) 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.
+         */
+        reconcile: Effect.fn(function* ({ news }) {
+          const before = dropUnreadable(yield* readInterface(news));
+          yield* guardWrite(NODE_NETWORK_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(NODE_NETWORK_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              nodes.createNodeNetwork(toDistilledCreate(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              nodes.putNodeNetwork2(toDistilledUpdate(news)),
+            );
+          }
+          const after = dropUnreadable(yield* readInterface(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `nodes/${news.node}/network/${news.iface}: wrote with no error, but the ` +
+                  'interface is still absent -- PVE wraps every answer in {"data":...} and can ' +
+                  'report success on a call that did nothing, so read back rather than trust it.',
+              ),
+            );
+          }
+          return after;
+        }),
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            nodes.deleteNodeNetwork2({ iface: olds.iface, node: olds.node }),
+          );
+        }),
+      }),
+    ),
+  );