@homeflare/alchemy 0.1.0

package/src/proxmox/role.ts

@@ -0,0 +1,161 @@
+/**
+ * `Proxmox.Role` — a PVE role: one name, one set of privileges. The object every other resource
+ * in this package stands on, because a role is what the provision credential actually holds.
+ *
+ * ★ THIS IS WHERE pool.ts's ⚠️ STOPS BEING A MEMORY. That file records, in prose, that the
+ *   provision role lacked `Pool.Allocate`, that reconcile answered "Permission check failed", and
+ *   that a human widened the role over SSH with `pveum role modify`. Prose cannot be planned
+ *   against: it goes stale the first time somebody edits the role in the UI and tells nobody.
+ *   Declared here, the same fact is a diff — the privileges the role is SUPPOSED to hold are read
+ *   off the cluster on every plan, and a hand edit shows up as `1 to update` rather than as a 403
+ *   six weeks later in the middle of something else.
+ *
+ * ⛔ THE INDEX AND THE ITEM DISAGREE ABOUT WHAT `privs` IS, AND MISSING THAT COSTS A DIFF THAT
+ *   NEVER CONVERGES. `GET /access/roles` (the index) reports each role's privileges as a COMMA
+ *   STRING. `GET /access/roles/{roleid}` — the path this resource reads — returns a privilege MAP
+ *   instead, `{"VM.Allocate":1,"Sys.Audit":1,…}`, and its key order is a Perl hash's order, so it
+ *   is not stable between two calls to the same endpoint. Compare the raw string, or the raw
+ *   object, or the keys in the order they arrived, and every plan reports an update forever.
+ *   `canonical` below is the whole answer: both sides become a sorted, de-duplicated set before
+ *   anything is compared, and `attributes` STORES the sorted form so Alchemy's state does not
+ *   churn either.
+ *
+ * ⚠️ A DECLARATION REPLACES THE PRIVILEGE SET; IT DOES NOT ADD TO IT. `PUT /access/roles/{roleid}`
+ *   accepts an `append` flag and this resource deliberately never sends it — with append a role
+ *   could only ever grow, so `matches` would report an update forever whenever props were a subset
+ *   of live, which is the same perpetual diff by a different road. The consequence is the one that
+ *   bites: anything a human added by hand is REVOKED on the next deploy unless it is in `privs`.
+ *   Copy the live set out of `pveum role list` before declaring a role that already exists; do not
+ *   type it from memory.
+ *
+ * ⛔ A ROLE CAN LOCK ITS OWN PROVIDER OUT, AND NOTHING IN THIS PACKAGE CAN UNDO IT. Reconcile runs
+ *   as the provision credential, and that credential holds a role. Declare THAT role without the
+ *   privileges the provider needs — `Sys.Modify` on `/access` above all — and the write succeeds,
+ *   after which every later plan reads 403 and the repair has to happen out of band as `root@pam`
+ *   over SSH. It is a one-way door, which is why the privileges a reconcile needs are written
+ *   down at the bottom of this comment rather than left to be rediscovered from an error message.
+ *
+ * ⚠️ PVE REFUSES TO EDIT ITS OWN BUILT-IN ROLES (`Administrator`, `NoAccess`, the `PVE*` set), and
+ *   the item endpoint gives no sign of which those are — only the index carries the `special`
+ *   flag. A declaration aimed at a built-in role therefore READS BACK CLEANLY and fails at write
+ *   time, which reads like a broken provider rather than like a refusal. Declare roles you own.
+ *
+ * ★ PRIVILEGES A RECONCILE NEEDS: `Sys.Audit` on `/access` to read and diff, `Sys.Modify` on
+ *   `/access` to create, update or delete. Not `Permissions.Modify` — binding a role to a user is
+ *   `/access/acl`, a different object, and nothing here writes it. An auditor-shaped credential
+ *   can already PLAN this resource and cannot DEPLOY it, which is the honest failure: the plan is
+ *   true and the deploy says exactly which privilege is missing.
+ */
+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';
+
+export interface RoleProps extends WithTarget {
+  /**
+   * PVE's primary key for a role.
+   *
+   * ⚠️ THERE IS NO RENAME. `path` is built from this, so changing it makes the factory read
+   *   nothing live, create a role under the new name, and leave the old one on the cluster with
+   *   nobody managing it. Delete the resource and declare a new one rather than editing this.
+   */
+  roleid: string;
+  /**
+   * The COMPLETE privilege set, e.g. `['VM.Allocate', 'VM.Audit', 'Sys.Audit']`. Order and
+   * duplicates do not matter — see the ⛔ in the header — but completeness does: this list is the
+   * role, not an addition to it.
+   *
+   * ⚠️ DECLARE AT LEAST ONE. A role with no privileges grants nothing and reads back as an empty
+   *   document, which is the one shape the factory cannot tell apart from an object that is not
+   *   there — reconcile would then refuse with its "the write returned no error but the object is
+   *   still absent" message, which is true of the read and misleading about the cause.
+   */
+  privs: string[];
+}
+
+export interface RoleAttributes {
+  roleid: string;
+  /** Sorted and de-duplicated on the way in, so persisted state is identical across plans. */
+  privs: string[];
+}
+
+export interface ProxmoxRole extends Resource<
+  'Proxmox.Role',
+  RoleProps,
+  RoleAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxRole = Resource<ProxmoxRole>('Proxmox.Role');
+
+/**
+ * The only shape two privilege sets may be compared in: sorted, de-duplicated, blanks dropped.
+ *
+ * ⚠️ THE TRIM AND THE EMPTY FILTER ARE NOT DECORATION. `'A,B,'.split(',')` yields a trailing `''`,
+ *   and a hand-written list is quite likely to carry a stray space after a comma. Either one turns
+ *   into a phantom member that no live answer can contain, so `matches` would be false on every
+ *   plan and the deploy would rewrite the role to exactly what it already was.
+ */
+const canonical = (privs: readonly string[]): string[] =>
+  [...new Set(privs.map((priv) => priv.trim()).filter((priv) => priv.length > 0))].sort();
+
+/**
+ * The privileges in a live answer, from EITHER shape PVE uses for them.
+ *
+ * ⚠️ THE MAP BRANCH IS THE ONE THAT RUNS HERE — the item endpoint answers `{"VM.Allocate":1,…}`,
+ *   so the privilege names are the KEYS and the `1`s carry no information. The string branch
+ *   exists because the index answers `{"privs":"VM.Allocate,Sys.Audit",…}` for that same role, and
+ *   a reader that assumed the map shape for an index entry would compare the words `privs`,
+ *   `roleid` and `special` against real privileges and report drift forever.
+ *
+ * ⚠️ A KEY WITH NO DOT IS NOT A PRIVILEGE. Every PVE privilege is `Category.Name` — VM.Allocate,
+ *   Sys.Modify, Datastore.AllocateSpace, Pool.Audit — while the metadata PVE mixes into role
+ *   answers (`special`, marking a built-in) is a bare word. Filtering on the dot keeps a flag from
+ *   being diffed as though somebody had granted it.
+ */
+const livePrivs = (live: Record<string, unknown>): string[] => {
+  const listed = live['privs'];
+  if (typeof listed === 'string') return canonical(listed.split(','));
+  return canonical(Object.keys(live).filter((key) => key.includes('.')));
+};
+
+const handlers = pveHandlers<RoleProps, RoleAttributes>({
+  attributes: (live, props) => ({ privs: livePrivs(live), roleid: props.roleid }),
+  collection: () => 'access/roles',
+  /** ⚠️ PVE wants ONE comma string here, not a repeated field — `privs=A,B,C`. */
+  createForm: (props) => ({ privs: canonical(props.privs).join(','), roleid: props.roleid }),
+  /**
+   * ⛔ NORMALISED ON BOTH SIDES, even though `attributes` already arrives sorted. This is a
+   *   predicate, not a fast path: the cost of trusting one side's order is not a slow plan, it is
+   *   a plan that reports an update every single time and a deploy that writes the same role back
+   *   forever. Cheap insurance against the exact trap named in the header.
+   */
+  matches: (attributes, props) =>
+    canonical(attributes.privs).join(',') === canonical(props.privs).join(','),
+  path: (props) => `access/roles/${props.roleid}`,
+  /**
+   * ⚠️ NO `append` FIELD, DELIBERATELY. Sending `append=1` would make every update additive, so a
+   *   privilege could be granted from here but never taken away — and a role that cannot narrow
+   *   is not a declaration. See the ⚠️ in the header for what that means for hand edits.
+   */
+  updateForm: (props) => ({ privs: canonical(props.privs).join(',') }),
+});
+
+/**
+* ⛔ AN EMPTY LIST, AND NOWHERE DOES IT MATTER MORE. `GET /access/roles` returns every
+*   role on the cluster, PVE's own built-ins included. Returning them would invite Alchemy
+*   to adopt `Administrator` — and therefore one day to narrow or delete it. Adoption is
+*   an explicit act, here as everywhere else in this package.
+ 
+ *
+* ⛔ DO NOT CARRY THE FACTORY'S REASSURANCE OVER TO THIS ONE. `destroy` there notes that
+*   PVE refuses to delete things still in use — a pool holding guests, a storage with
+*   volumes — and a role is NOT protected that way. Whoever is bound to the role loses
+*   those privileges the moment it goes, and the credential this provider runs with is
+*   bound through exactly such a binding. Checking who holds a role before removing it is
+*   an operator's job, and it is not done here on their behalf while they read a diff.
+ 
+ */
+export const ProxmoxRoleProvider = () =>
+  Provider.effect(ProxmoxRole, Effect.succeed(ProxmoxRole.Provider.of(handlers)));

package/src/proxmox/sdn-apply-read.test.ts

@@ -0,0 +1,152 @@
+/**
+ * The fabric comparison, which is what decides whether `Proxmox.SdnApply` publishes.
+ *
+ * ⛔ IT IS TESTED HERE RATHER THAN AGAINST THE CLUSTER BECAUSE STAGING A REAL FABRIC CHANGE MEANS
+ *   TOUCHING CEPH'S CLUSTER NETWORK. TB4's OSPF fabric pins 10.100.0.102/103/104 to en05 and en06,
+ *   and those are the addresses `cluster_network` runs over. The staged-zone path IS proven end to
+ *   end against the live cluster (plan noop -> stage a zone -> plan update -> remove -> plan noop);
+ *   the fabric path is proven by construction, with the two ways it could lie pinned below.
+ *
+ * ★ THE TWO WAYS IT COULD LIE, AND BOTH ARE FALSE POSITIVES. `?pending=1` carries a `digest` and
+ *   `?running=1` does not, and the node list comes back in a different order between the two reads
+ *   — MEASURED. Either would make the comparison report a difference on a cluster where nothing has
+ *   changed, which is a forever-`update` on a resource whose update reloads the network on three
+ *   nodes at once. That is worse than the bug this file was written to fix.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { PveError } from './client.ts';
+import { UNDIFFABLE, canonical, fabricStaged, subsystemAbsent } from './sdn-apply-read.ts';
+
+/** The shape `cluster/sdn/fabrics/all` actually returns, trimmed to what matters. */
+const N2 = {
+  fabric_id: 'tb4',
+  interfaces: ['name=en05', 'name=en06'],
+  ip: '10.100.0.102',
+  node_id: 'n2',
+};
+const N3 = {
+  fabric_id: 'tb4',
+  interfaces: ['name=en05', 'name=en06'],
+  ip: '10.100.0.103',
+  node_id: 'n3',
+};
+
+const running = {
+  fabrics: [{ area: '1', id: 'tb4', ip_prefix: '10.100.0.0/24', protocol: 'ospf' }],
+  nodes: [N2, N3],
+};
+
+describe('fabric canonicalisation', () => {
+  it('ignores the digest the pending view carries and the running view does not', () => {
+    const pending = {
+      fabrics: [
+        {
+          area: '1',
+          digest: '7b94d363ff69',
+          id: 'tb4',
+          ip_prefix: '10.100.0.0/24',
+          protocol: 'ospf',
+        },
+      ],
+      nodes: running.nodes.map((n) => ({ ...n, digest: '7b94d363ff69' })),
+    };
+    assert.equal(canonical(pending), canonical(running));
+  });
+
+  it('ignores node order, which is not stable between the two reads', () => {
+    const reordered = { ...running, nodes: [...running.nodes].reverse() };
+    assert.equal(canonical(reordered), canonical(running));
+  });
+
+  it('ignores key order within a node', () => {
+    const shuffled = {
+      ...running,
+      nodes: running.nodes.map((n) => ({
+        node_id: n.node_id,
+        ip: n.ip,
+        interfaces: n.interfaces,
+        fabric_id: n.fabric_id,
+      })),
+    };
+    assert.equal(canonical(shuffled), canonical(running));
+  });
+
+  // ⛔ AND THE DIRECTION THAT MATTERS: a real change must NOT be canonicalised away.
+  it('sees a changed node address', () => {
+    const moved = {
+      ...running,
+      nodes: [{ ...N2, ip: '10.100.0.199' }, N3],
+    };
+    assert.notEqual(canonical(moved), canonical(running));
+  });
+
+  it('sees an added node — the shape of a fabric gaining a member', () => {
+    const added = {
+      ...running,
+      nodes: [
+        ...running.nodes,
+        { fabric_id: 'tb4', interfaces: ['name=en05'], ip: '10.100.0.104', node_id: 'n4' },
+      ],
+    };
+    assert.notEqual(canonical(added), canonical(running));
+  });
+
+  it('sees a changed interface list, which is what decides where the address lands', () => {
+    const rewired = {
+      ...running,
+      nodes: [{ ...N2, interfaces: ['name=en05'] }, N3],
+    };
+    assert.notEqual(canonical(rewired), canonical(running));
+  });
+});
+
+describe('the stated blind spot', () => {
+  // ⚠️ ipams and dns answer HTTP 400 to ?pending=1 — there is no way to ask them what is staged.
+  //    The list exists so the gap is NAMED rather than silently folded to zero, which is what the
+  //    old `orElseSucceed(() => 0)` would have done if anyone had added them to the counted set.
+  it('names the collections that cannot be diffed at all', () => {
+    assert.deepEqual([...UNDIFFABLE], ['cluster/sdn/ipams', 'cluster/sdn/dns']);
+  });
+});
+
+/**
+ * ⛔ WHAT A FAILED READ IS ALLOWED TO MEAN. Every failure used to read as "nothing staged", so an
+ *   expired read lease answered `noop` — and one failed fabric view, compared with a real one, read
+ *   as a DIFFERENCE, which is `PUT /cluster/sdn` and a network reload carrying Ceph's cluster
+ *   network on all three nodes. Found in review 2026-09-14. A failure other than 501 now fails the
+ *   read outright; that path runs through `pve` and is proven by the live plan, not here.
+ */
+describe('what a failed read is allowed to mean', () => {
+  it('reads only a 501 as an absent subsystem', () => {
+    assert.equal(
+      subsystemAbsent(new PveError(501, 'GET', 'cluster/sdn/zones?pending=1', '')),
+      true,
+    );
+    for (const status of [0, 400, 401, 403, 500, 502, 596]) {
+      const failure = new PveError(status, 'GET', 'cluster/sdn/zones?pending=1', '');
+      assert.equal(subsystemAbsent(failure), false, `status ${String(status)}`);
+    }
+  });
+
+  it('never reads something that is not a PVE answer as an absent subsystem', () => {
+    assert.equal(subsystemAbsent(new Error('501')), false);
+    assert.equal(subsystemAbsent({ status: 501 }), false);
+  });
+
+  it('counts an unchanged fabric as nothing staged and a moved node as staged', () => {
+    const moved = { ...running, nodes: [{ ...N2, ip: '10.100.0.199' }, N3] };
+    assert.equal(fabricStaged(canonical(running), canonical(running)), 0);
+    assert.equal(fabricStaged(canonical(moved), canonical(running)), 1);
+  });
+
+  it('counts a fabric subsystem absent from both views as nothing staged', () => {
+    assert.equal(fabricStaged(undefined, undefined), 0);
+  });
+
+  // ⛔ THE CEPH CASE: one view absent is refused, never counted as a difference.
+  it('refuses one absent view rather than calling it a difference', () => {
+    assert.equal(fabricStaged(undefined, canonical(running)), 'inconsistent');
+    assert.equal(fabricStaged(canonical(running), undefined), 'inconsistent');
+  });
+});

package/src/proxmox/sdn-apply-read.ts

@@ -0,0 +1,189 @@
+/**
+ * What is staged on the SDN, across the WHOLE surface the apply publishes — not just the two
+ * collections this package declares resources for.
+ *
+ * 🔴 THE GAP THIS FILE CLOSES, AND IT WAS FOUND BY ALMOST DECLARING THE APPLY. `pendingCount` in
+ *   sdn-apply.ts counted `cluster/sdn/zones` and `cluster/sdn/vnets`. TB4 has zero of each — and a
+ *   staged OSPF FABRIC that nothing counted. MEASURED 2026-09-13 on n2:
+ *
+ *     /etc/pve/sdn/fabrics.cfg   ospf_fabric: tb4, area 1, ip_prefix 10.100.0.0/24
+ *                                ospf_node: tb4_n2/n3/n4, interfaces en05 + en06,
+ *                                ip 10.100.0.102 / .103 / .104
+ *     /etc/network/interfaces.d/sdn   the file PVE GENERATES from it, carrying those /32s
+ *
+ *   Those addresses are Ceph's `cluster_network`. So `diff` would have answered `noop` for ever
+ *   while `PUT /cluster/sdn` republished the fabric and reloaded networking on all three nodes at
+ *   once — the simultaneity the NetworkApply chain exists to prevent, arriving through the door
+ *   nobody was watching.
+ *
+ * ⛔ THE SURFACE IS NOT UNIFORM, AND ASSUMING IT WAS IS WHAT MADE THE GAP INVISIBLE. Measured, one
+ *   request per collection, per query:
+ *
+ *     zones, vnets, controllers, prefix-lists, route-maps   accept ?pending=1 and ?running=1,
+ *                                                           and mark a staged row with `state`
+ *     fabrics                                               accepts both, and its rows carry NO
+ *                                                           `state` marker at all
+ *     ipams, dns                                            REJECT both with HTTP 400,
+ *                                                           "property is not defined in schema"
+ *
+ * ⛔ SO A `state`-ONLY TEST IS WRONG FOR FABRICS, AND `orElseSucceed(() => 0)` IS WORSE THAN WRONG
+ *   FOR ipams AND dns. The old code folded an unreadable collection to zero — right for a cluster
+ *   with no SDN at all, and indistinguishable from "this collection rejects the question". Adding
+ *   ipams and dns to the old list would have counted them as 0 for ever and read as coverage.
+ */
+import * as Effect from 'effect/Effect';
+import { PveError, pve } from './client.ts';
+import type { PveTarget } from './credentials.ts';
+
+/** A staged row. `state` is present only under `?pending=1`, and only when it differs from running. */
+type PendingRow = { state?: string };
+
+/**
+ * Collections that answer `?pending=1` AND mark a staged row with `state`.
+ *
+ * ⚠️ THIS LIST IS WIDER THAN THE RESOURCES THIS PACKAGE SHIPS, ON PURPOSE, AND THAT REVERSES THE
+ *   OLD COMMENT. It used to say counting a collection nothing declares would turn somebody else's
+ *   hand-staged object into a permanent `update`. True — and the alternative is publishing that
+ *   object without ever showing it in a plan. An apply that is cluster-wide must be honest about
+ *   the whole cluster: a controller staged by hand in the UI is a thing this resource WILL push,
+ *   so it has to be a thing this resource ADMITS to. A permanent `update` on somebody's abandoned
+ *   half-edit is a loud, safe failure; publishing it silently is not.
+ */
+const MARKED = [
+  'cluster/sdn/zones',
+  'cluster/sdn/vnets',
+  'cluster/sdn/controllers',
+  'cluster/sdn/prefix-lists',
+  'cluster/sdn/route-maps',
+] as const;
+
+/**
+ * Collections with NO pending view at all.
+ *
+ * ⚠️ NAMED RATHER THAN SILENTLY SKIPPED. `ipams` and `dns` answer HTTP 400 to both `?pending=1` and
+ *   `?running=1`, so there is no way to ask them what is staged. They are a REAL blind spot: an
+ *   ipam edited by hand is published by the apply and cannot be seen from here. TB4 has one ipam
+ *   (`pve`, the built-in) and zero dns entries, so the blind spot is currently empty — which is a
+ *   fact about today, not a property of the design.
+ */
+export const UNDIFFABLE = ['cluster/sdn/ipams', 'cluster/sdn/dns'] as const;
+
+/**
+ * Whether a failed read means "this SDN subsystem does not exist here" — the ONE failure that may
+ * read as nothing staged.
+ *
+ * 🔴 IT USED TO BE EVERY FAILURE. `orElseSucceed` caught 401, 403, 5xx and a dropped connection
+ *   along with the 501 it was written for, so an expired read lease or a missing grant answered
+ *   "nothing staged": `diff` said noop, and the read-back after a real apply said settled while
+ *   objects were still staged. The fabric views were worse because they are COMPARED — one view
+ *   failing while the other succeeded read as a DIFFERENCE, which is `PUT /cluster/sdn` and a
+ *   network reload carrying Ceph's cluster network on all three nodes, over a timeout. Found in
+ *   review on 2026-09-14 and confirmed by reading.
+ * ⛔ SO ANYTHING ELSE FAILS THE READ. A plan that stops on an unreadable SDN is loud and safe; a
+ *   plan that guesses is neither.
+ */
+export const subsystemAbsent = (error: unknown): boolean =>
+  error instanceof PveError && error.status === 501;
+
+/** Staged rows in the collections that mark them. */
+const markedPending = (target: PveTarget) =>
+  Effect.all(
+    MARKED.map((collection) =>
+      pve<PendingRow[]>(target, 'read', 'GET', `${collection}?pending=1`).pipe(
+        Effect.map((rows) => (rows ?? []).filter((row) => row.state !== undefined).length),
+        /**
+         * ⚠️ AN ABSENT COLLECTION COUNTS AS ZERO, AND THAT IS STILL RIGHT HERE — but ONLY an absent
+         *   one. Some versions answer 501 for an SDN subsystem that has never been configured, and
+         *   failing the whole plan over it would make this resource undeclarable on a cluster with
+         *   no SDN. The collections that REJECT the question are handled by not asking them — see
+         *   UNDIFFABLE — and every other failure is a failure; see `subsystemAbsent`.
+         */
+        Effect.catchIf(subsystemAbsent, () => Effect.succeed(0)),
+      ),
+    ),
+    { concurrency: 'unbounded' },
+  ).pipe(Effect.map((counts) => counts.reduce((total, count) => total + count, 0)));
+
+/**
+ * Staged fabric changes from the two canonical views, where `undefined` is a view whose subsystem
+ * answered 501.
+ *
+ * ⛔ ONE VIEW ABSENT AND ONE PRESENT IS NOT A DIFFERENCE. It is one endpoint answering two
+ *   questions inconsistently, and a difference is exactly what triggers the publish — so it is
+ *   refused rather than counted.
+ */
+export const fabricStaged = (
+  staged: string | undefined,
+  running: string | undefined,
+): number | 'inconsistent' => {
+  if (staged === undefined && running === undefined) return 0;
+  if (staged === undefined || running === undefined) return 'inconsistent';
+  return staged === running ? 0 : 1;
+};
+
+/**
+ * Whether the fabric config differs between staged and applied.
+ *
+ * ★ COMPARING THE TWO VIEWS IS THE TEST, BECAUSE THERE IS NO `state` TO READ. `?pending=1` is the
+ *   staged config and `?running=1` is what the nodes are actually running; equal means nothing to
+ *   publish. `cluster/sdn/fabrics/all` returns both fabrics and nodes in ONE call, which is why it
+ *   is asked rather than the two subdirectories.
+ *
+ * ⚠️ `digest` IS STRIPPED BEFORE COMPARING. The pending view carries one and the running view does
+ *   not — MEASURED — so comparing raw bodies reports a difference on a cluster where nothing has
+ *   changed, which is exactly the forever-diff this package has fixed three times elsewhere.
+ * ⚠️ AND THE ORDER OF THE NODE LIST IS NOT STABLE between the two reads, so both sides are
+ *   canonically sorted. Order is not meaning in a set of fabric nodes.
+ */
+const fabricPending = (target: PveTarget) =>
+  Effect.all(
+    ['pending', 'running'].map((view) =>
+      pve<unknown>(target, 'read', 'GET', `cluster/sdn/fabrics/all?${view}=1`).pipe(
+        Effect.map(canonical),
+        Effect.catchIf(subsystemAbsent, () => Effect.succeed(undefined)),
+      ),
+    ),
+    { concurrency: 'unbounded' },
+  ).pipe(
+    Effect.flatMap(([staged, running]) => {
+      const verdict = fabricStaged(staged, running);
+      return verdict === 'inconsistent'
+        ? Effect.die(
+            new Error(
+              'cluster/sdn/fabrics/all answered 501 for one of ?pending=1 and ?running=1 and not ' +
+                'the other. Refusing to read that as a staged fabric change.',
+            ),
+          )
+        : Effect.succeed(verdict);
+    }),
+  );
+
+/** Stable JSON with `digest` removed and every array sorted, so only real differences show. */
+export const canonical = (value: unknown): string => JSON.stringify(sortDeep(value));
+
+const sortDeep = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value
+      .map(sortDeep)
+      .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  }
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => key !== 'digest')
+      .sort(([left], [right]) => left.localeCompare(right));
+    return Object.fromEntries(entries.map(([key, inner]) => [key, sortDeep(inner)]));
+  }
+  return value;
+};
+
+/**
+ * How many staged changes the apply would publish, across everything it is capable of publishing.
+ *
+ * ⛔ ZERO HERE IS THE ONLY THING THAT MAKES DECLARING THE APPLY SAFE. `reconcile` runs on CREATE —
+ *   Alchemy always calls it the first time a resource appears — and `PUT /cluster/sdn` regenerates
+ *   `/etc/network/interfaces.d/sdn` on every node. On TB4 that file carries Ceph's cluster network.
+ */
+export const sdnPendingCount = (target: PveTarget) =>
+  Effect.all([markedPending(target), fabricPending(target)], { concurrency: 'unbounded' }).pipe(
+    Effect.map(([marked, fabric]) => marked + fabric),
+  );

package/src/proxmox/sdn-apply.ts

@@ -0,0 +1,154 @@
+/**
+ * `Proxmox.SdnApply` — the call that makes a declared network real.
+ *
+ * ⛔ WITHOUT THIS RESOURCE, EVERY SDN DEPLOY IS A GREEN PLAN THAT CHANGES NO NETWORK. Writes under
+ *   `cluster/sdn/*` edit files in `/etc/pve/sdn/` and touch nothing on any node. `PUT /cluster/sdn`
+ *   is the apply, and it is CLUSTER-WIDE — it publishes every staged object at once, not the one
+ *   that happened to reconcile.
+ *
+ * ★ MEASURED ON TB4 ON 2026-09-13, NOT INFERRED. A probe zone was created, inspected and removed:
+ *
+ *     pvesh create /cluster/sdn/zones --zone zzprobe --type simple
+ *     GET /cluster/sdn/zones/zzprobe              -> {"digest":"c438…","type":"simple","zone":"zzprobe"}
+ *     GET /cluster/sdn/zones/zzprobe?pending=1    -> {"digest":null,"pending":{},"state":"new",…}
+ *     GET /cluster/sdn/zones?running=1            -> []            ⬅ THE APPLIED CONFIG WAS EMPTY
+ *
+ *   So the plain read — the one `pveOperations` performs — answers from the STAGED file and cannot
+ *   tell staged from applied. `state` appears only under `?pending=1`, and `?running=1` is the
+ *   applied view. That is the whole basis for this resource.
+ *
+ * ★ IT IS A RESOURCE RATHER THAN A HOOK SO THAT THE GRAPH ORDERS IT. Pass the zones and vnets it
+ *   should follow in `after`; Alchemy orders by data flow, so reading their attributes is what
+ *   puts the apply last. A stack-level hook would fire on every run, including runs where no SDN
+ *   object changed, and would be invisible in `plan`.
+ *
+ * ⚠️ ONE APPLY PER STACK. Two of these would each publish the other's staged half, so whichever
+ *   ran first would apply a zone its own declaration had not finished writing. Declare one.
+ *
+ * ⚠️ THE COLLECTION READ IS DELIBERATE, AND IT IS WHAT LETS THE READ LEASE SEE ANYTHING AT ALL.
+ *   `GET /cluster/sdn/zones/{zone}` is checked against SDN.Allocate — read the ⛔ in sdn-zone.ts —
+ *   but `GET /cluster/sdn/zones` is "list entries where you have SDN.Audit or SDN.Allocate", so
+ *   the collection answers an auditor-shaped credential. This resource only ever reads collections.
+ */
+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 { pve } from './client.ts';
+import type { PveRequirements } from './resource.ts';
+import type { WithTarget } from './resource.ts';
+import { sdnPendingCount } from './sdn-apply-read.ts';
+
+export interface SdnApplyProps extends WithTarget {
+  /**
+   * The staged objects this apply publishes.
+   *
+   * ⚠️ IT IS NEVER READ, AND IT IS NOT DECORATION. Alchemy orders resources by DATA FLOW, so the
+   *   only way to say "after the zones" is to consume something the zones produced. Pass their
+   *   attributes here — `after: [zone.zone, vnet.vnet]` — and the apply lands last. Leave it out
+   *   and the apply may run BEFORE the zone it was meant to publish, which plans green and
+   *   changes nothing.
+   */
+  after?: readonly unknown[];
+}
+
+export interface SdnApplyAttributes {
+  /**
+   * How many SDN objects are still staged.
+   *
+   * ⚠️ ZERO IS THE ONLY SETTLED VALUE. Anything above it means the running config and the staged
+   *   config disagree — which is drift whether this stack caused it or somebody staged a zone in
+   *   the UI and walked away.
+   */
+  pending: number;
+}
+
+export interface ProxmoxSdnApply extends Resource<
+  'Proxmox.SdnApply',
+  SdnApplyProps,
+  SdnApplyAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxSdnApply = Resource<ProxmoxSdnApply>('Proxmox.SdnApply');
+
+const read = (props: SdnApplyProps) =>
+  sdnPendingCount(props.target).pipe(Effect.map((pending) => ({ pending })));
+
+export const ProxmoxSdnApplyProvider = () =>
+  Provider.effect(
+    ProxmoxSdnApply,
+    Effect.succeed(
+      ProxmoxSdnApply.Provider.of({
+        /** ⛔ Empty for the same reason as every other resource here: adoption must be explicit. */
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds }) {
+          return yield* read(olds);
+        }),
+
+        /**
+         * ⚠️ THE DIFF IS ABOUT THE CLUSTER, NOT ABOUT THE PROPS. This resource has no settable
+         *   field — `after` exists only to create 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 anything is staged right now.
+         */
+        diff: Effect.fn(function* ({ news }: { news: Input<SdnApplyProps> }) {
+          if (!isResolved(news)) return undefined;
+          const { pending } = yield* read(news);
+          return pending === 0 ? ({ action: 'noop' } as const) : ({ action: 'update' } as const);
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          /**
+           * ⛔ NOTHING STAGED MEANS NOTHING TO PUBLISH, AND THIS BRANCH IS A SAFETY PROPERTY RATHER
+           *   THAN AN OPTIMISATION — the same one network-apply.ts has carried all along, and the
+           *   absence of which is why this resource could not be declared at all.
+           *
+           * 🔴 WHAT IT PREVENTS. `reconcile` runs on CREATE, the first time this resource appears
+           *   in a stack, before `diff` has ever been consulted. `PUT /cluster/sdn` regenerates
+           *   `/etc/network/interfaces.d/sdn` on EVERY node at once — and on TB4 that file carries
+           *   the OSPF fabric holding Ceph's `cluster_network` on en05/en06. Without this branch,
+           *   adding one line to a stack file reloads networking on all three nodes simultaneously,
+           *   which is precisely what the serialised NetworkApply chain exists to prevent.
+           *
+           * ⚠️ IT DEPENDS ON sdn-apply-read.ts BEING HONEST ABOUT THE WHOLE SURFACE. A count that
+           *   only looks at zones and vnets answers zero on a cluster with a staged fabric, and
+           *   this branch would then wave through the exact publish it is here to stop.
+           */
+          const staged = yield* read(news);
+          if (staged.pending === 0) return staged;
+
+          yield* pve(news.target, 'provision', 'PUT', 'cluster/sdn');
+          /**
+           * ⛔ READ BACK, FOR THE SAME REASON THE FACTORY DOES. PVE answers 200 on writes that did
+           *   nothing, and here "nothing" is indistinguishable from success by status code alone.
+           *   If objects are still staged after an apply, the network does NOT match the
+           *   declaration and saying otherwise is the exact lie this resource was added to stop.
+           */
+          const after = yield* read(news);
+          if (after.pending !== 0) {
+            return yield* Effect.die(
+              new Error(
+                `PUT /cluster/sdn returned no error but ${String(after.pending)} SDN object(s) ` +
+                  'are still staged. The running config does not match the declared one -- check ' +
+                  '`pvesh get /cluster/sdn/zones --pending 1` for the objects PVE refused.',
+              ),
+            );
+          }
+          return after;
+        }),
+
+        /**
+         * ⛔ DELETING THIS RESOURCE APPLIES NOTHING AND UNDOES NOTHING, AND THAT IS CORRECT. There
+         *   is no un-apply in PVE: the running config is already published on every node, and the
+         *   way to remove a network is to delete the zone or vnet and apply AGAIN. Making this
+         *   destroy call `PUT /cluster/sdn` would publish whatever happened to be staged at the
+         *   moment somebody removed a line from a stack file, which is the worst possible time.
+         */
+        delete: () => Effect.void,
+      }),
+    ),
+  );