@homeflare/alchemy 0.1.0

package/src/proxmox/sdn-subnet-form.ts

@@ -0,0 +1,156 @@
+/**
+ * How a subnet crosses the wire in both directions, and what PVE actually calls its path.
+ *
+ * ★ SPLIT OUT OF sdn-subnet.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, on the seam
+ *   node-network-form.ts cuts rather than at a convenient line number: this file owns the
+ *   COERCIONS in BOTH directions plus the derived id, because a read that normalises differently
+ *   from the write that produced it is exactly how a forever-diff is born. sdn-subnet.ts answers
+ *   "what is a subnet, and when has it changed". Nothing here calls the cluster.
+ *
+ * ⚠️ THE `import type` BACK TO sdn-subnet.ts IS A CYCLE ON PAPER ONLY — type-only, so it is erased
+ *   before anything runs and `SdnSubnetProps` stays in the file that declares the resource.
+ */
+import type { SdnSubnetProps } from './sdn-subnet.ts';
+import { propertyString, withClears } from './values.ts';
+
+/** One DHCP pool. PVE's property-string keys are `start-address`/`end-address`; see `rangeString`. */
+export type DhcpRange = { start: string; end: string };
+
+/**
+ * The id PVE files a subnet under — and therefore the path segment GET, PUT and DELETE address it
+ * by, which is NOT the value POST is handed.
+ *
+ * ⛔ MEASURED from `/usr/share/perl5/PVE/API2/Network/SDN/Subnets.pm` on pve-manager 9.2.11, in
+ *   the create handler: `my $id = $cidr =~ s/\//-/r; $id = "$zoneid-$id";`. So `subnet=10.0.0.0/24`
+ *   goes out and `house-10.0.0.0-24` is what exists afterwards. A CIDR cannot be a path segment
+ *   anyway — it carries a slash — so there is no spelling of this endpoint that takes the CIDR.
+ *
+ * ⚠️ `.replace`, NOT `.replaceAll`, AND THE PARITY IS DELIBERATE. Perl's `s/\//-/r` has no `/g`, so
+ *   it rewrites the FIRST slash only. A CIDR has exactly one, so the two agree on every legal
+ *   input; they would stop agreeing on an illegal one, and agreeing with PVE is the point.
+ */
+export const subnetId = (props: Pick<SdnSubnetProps, 'cidr' | 'zone'>) =>
+  `${props.zone}-${props.cidr.replace('/', '-')}`;
+
+/** A range on its way OUT. PVE stores the string verbatim; nothing rewrites it. */
+const rangeString = (range: DhcpRange) => `start-address=${range.start},end-address=${range.end}`;
+
+/**
+ * DHCP ranges, from either shape, as one comparable string.
+ *
+ * ⛔ THIS FAMILY'S WRITE SHAPE AND READ SHAPE ARE DIFFERENT, WHICH IS THE CLASSIC FOREVER-DIFF.
+ *   MEASURED from the API module: `$scfg->{'dhcp-range'} = get_dhcp_ranges($scfg)` runs
+ *   `parse_property_string` over every stored element, so a range WRITTEN as the string
+ *   `start-address=10.0.0.10,end-address=10.0.0.20` is READ BACK as the object
+ *   `{"start-address":"10.0.0.10","end-address":"10.0.0.20"}`. `propertyString` in values.ts
+ *   flattens both shapes to one sorted form and exists for exactly this — see its own ⚠️.
+ *
+ * ⚠️ AND IT IS A LIST, SO ORDER MUST NOT BE MEANING. PVE validates only that ranges do not overlap
+ *   and stores them in the order given; two declarations naming the same pools the other way round
+ *   are the same subnet. Sorting is what stops that being an update, exactly as `csv` does for a
+ *   zone's `nodes`.
+ *
+ * ⚠️ `;` IS THE JOINER BECAUSE `,` AND `=` ARE BOTH INSIDE THE VALUES. It never appears in an IPv4
+ *   or IPv6 address or in a property-string key, so the joined form cannot be ambiguous.
+ */
+export const dhcpRanges = (value: unknown): string =>
+  (Array.isArray(value) ? value : [])
+    .map((entry: unknown) => propertyString(entry))
+    .filter((entry) => entry !== '')
+    .sort()
+    .join(';');
+
+/** The declared side of that same comparison, through the same funnel so it cannot drift. */
+export const declaredRanges = (range: DhcpRange | undefined) =>
+  range === undefined ? '' : dhcpRanges([rangeString(range)]);
+
+/**
+ * ⚠️ AN EMPTY STRING IS HOW A CALLER SPELLS "UNSET", AND IT MUST NOT REACH PVE. `gateway` and
+ *   `dhcp-dns-server` are `format => 'ip'` and `dnszoneprefix` is `format => 'dns-name'`, so `''`
+ *   is a parameter-verification 400 rather than a clear. Clearing is a separate verb — `delete=`.
+ */
+const unset = (value: string | undefined) =>
+  value === undefined || value === '' ? undefined : value;
+
+/**
+ * Every optional this resource MANAGES: the value to send, or `undefined` meaning "clear it".
+ *
+ * ⛔ ONE TABLE FEEDS BOTH HALVES OF AN UPDATE, the way metric-server-form.ts does it, and for the
+ *   same measured reason: A PUT THAT OMITS A FIELD DOES NOT CLEAR IT. PVE merges the form into the
+ *   existing section (`$data->{$_} = $opts->{$_} for keys $opts->%*`), so dropping `gateway` from a
+ *   declaration leaves the old gateway in place and `matches` asks for the same update forever.
+ *   Deriving the form and the `delete=` list from one map makes "managed but not clearable"
+ *   impossible to write here.
+ *
+ * ⛔ AND THE TWO HALVES MUST NOT OVERLAP. MEASURED in `PVE::SectionConfig::delete_from_config`
+ *   (SectionConfig.pm:1853): naming a key in BOTH the form and `delete=` dies with "cannot set and
+ *   delete property '<k>' at the same time!". Because both halves are read off this one map, an
+ *   entry is in exactly one of them by construction.
+ *
+ * ⛔ NOTHING SET OUT OF BAND MAY BE LISTED HERE. A field in this map is CLEARED the moment it is
+ *   undeclared, so a live subnet whose DHCP pool an operator widened in the UI is narrowed back on
+ *   the next deploy. That is full ownership, the same bargain sdn-vnet.ts strikes over `alias`, and
+ *   it is a bargain rather than an accident only while this list stays deliberate.
+ *
+ * ⚠️ `snat` IS ABSENT ON PURPOSE AND LIVES IN `body` INSTEAD. It is a boolean, and `0` and "never
+ *   declared" are the same subnet to PVE and to `matches`, so sending an explicit `0` converges
+ *   without a `delete=` — the same choice sdn-vnet.ts makes for `vlanaware` and `isolate-ports`.
+ */
+export const optional = (props: SdnSubnetProps): Record<string, string | undefined> => ({
+  'dhcp-dns-server': unset(props.dhcpDnsServer),
+  'dhcp-range': props.dhcpRange === undefined ? undefined : rangeString(props.dhcpRange),
+  dnszoneprefix: unset(props.dnszoneprefix),
+  gateway: unset(props.gateway),
+});
+
+/**
+ * The fields sent on EVERY write, create and update alike.
+ *
+ * ⚠️ `vnet` IS SENT THOUGH THE URL ALREADY CARRIES IT. PVE's handler reads `$param->{vnet}` to
+ *   resolve the zone for its permission check, and it is a declared parameter of both the create
+ *   and the update schema, so sending the same value the path carries is accepted and removes this
+ *   file's dependence on the router injecting a path placeholder into the parameter hash.
+ */
+export const body = (props: SdnSubnetProps): Record<string, string> => ({
+  snat: props.snat === true ? '1' : '0',
+  vnet: props.vnet,
+  ...Object.fromEntries(
+    Object.entries(optional(props)).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  ),
+});
+
+/**
+ * ⚠️ `type` IS HARDCODED, NOT A PROP. PVE's create schema declares it as an enum with exactly one
+ *   member, `subnet`, so a prop for it could only ever hold one value — and the POST refuses to
+ *   proceed without it, which is the parameter-verification error sdn-vnet.ts records.
+ */
+export const createForm = (props: SdnSubnetProps): Record<string, string> => ({
+  ...body(props),
+  subnet: props.cidr,
+  type: 'subnet',
+});
+
+/**
+ * ★ CLEARING AN OPTION THAT WAS NEVER SET IS A SILENT NO-OP, AND THIS IS MEASURED RATHER THAN
+ *   HOPED FOR. sdn-vnet.ts flags the same `delete=` habit as REASONED-not-measured and warns that a
+ *   first update on a bare object would carry `delete=alias,tag`. Read off the code both endpoints
+ *   share — `PVE::SectionConfig::delete_from_config`, SectionConfig.pm:1853-1866 — the loop dies
+ *   only for an option that is unknown to the plugin, not optional, fixed, or also being set; for
+ *   an option simply absent from the section it runs `delete $config->{$k}` on a missing key and
+ *   moves on. All four keys above are `optional => 1` in `SubnetPlugin::options`, so a bare
+ *   subnet's first update carries `delete=dhcp-dns-server,dhcp-range,dnszoneprefix,gateway` and
+ *   PVE accepts it. `vnet` is `optional => 0` there and is never in this list.
+ *
+ * ⚠️ TWO OF THOSE FOUR NAMES ARE HYPHENATED, WHICH NO OTHER FAMILY HERE HAS PUT IN A `delete=`.
+ *   The parameter's format is `pve-configid-list`, and a name that failed it would 400 the whole
+ *   update rather than skip one field. MEASURED: `$CONFIGID_RE` is `qr/[a-z][a-z0-9_-]+/i`
+ *   (JSONSchema.pm:30), so a hyphen after the first character is legal and all four pass.
+ */
+export const updateForm = (props: SdnSubnetProps): Record<string, string> => {
+  const clear = Object.entries(optional(props))
+    .filter(([, value]) => value === undefined)
+    .map(([key]) => key);
+  return withClears(body(props), clear);
+};

package/src/proxmox/sdn-subnet.ts

@@ -0,0 +1,238 @@
+/**
+ * `Proxmox.SdnSubnet` — the addresses on a declared bridge: the CIDR, its gateway, its DHCP pool.
+ *
+ * ★ THE THIRD LINK OF ONE CHAIN, AND THE ORDER IS DATA FLOW RATHER THAN CONVENTION. A subnet
+ *   belongs to a vnet and a vnet belongs to a zone. MEASURED and recorded in sdn-vnet.ts: creating
+ *   a vnet is permission-checked at `/sdn/zones/-`, so a missing zone surfaces as a PERMISSION
+ *   error rather than as "no such zone". One level deeper the same shape holds — PVE's
+ *   `check_vnet_access` looks the vnet's ZONE up and checks `/sdn/zones/<zone>/<vnet>` — so a
+ *   subnet declared against a vnet that does not exist yet dies inside that lookup, with the vnet
+ *   named and the zone not. Pass the zone and vnet resources' OWN attributes into `zone` and
+ *   `vnet`; a literal buys no ordering, and here it also buys a wrong path.
+ *
+ * ⛔ THE ID PVE FILES A SUBNET UNDER IS NOT THE ONE YOU WRITE, AND IT IS THIS FAMILY'S SHARPEST
+ *   EDGE. `POST` takes `subnet=10.0.0.0/24` while GET, PUT and DELETE address `house-10.0.0.0-24`.
+ *   One PVE parameter name, `subnet`, carrying two different values — so they are named APART here,
+ *   `cidr` for the declared one and `subnetId` for the derived one, for the reason values.ts gives
+ *   about `flag`: a name that means two things is a bug waiting for whoever reads one meaning. The
+ *   derivation, and its measurement, live in `subnetId` in sdn-subnet-form.ts.
+ *
+ * ⛔ WHICH IS WHY `zone` IS A PROP THOUGH PVE NEVER ACCEPTS IT ON A SUBNET WRITE. The path cannot
+ *   be built without it and it is knowable only from the VNET. Declare the wrong zone and the id is
+ *   wrong: the POST still succeeds, because PVE computes the real id itself from the vnet, and the
+ *   read-back then looks for a subnet that is not there. The factory's guard in resource.ts DIES on
+ *   that first deploy — "the write returned no error but the object is still absent" — which is
+ *   loud and immediate, and much better than the alternative it replaces: a plan that says create,
+ *   forever, against a subnet PVE insists is already defined.
+ *
+ * ⛔ SDN WRITES ARE STAGED, NOT APPLIED — the same trap as sdn-zone.ts and sdn-vnet.ts, and it
+ *   walks straight through the factory's read-back, which proves the staging file and nothing more.
+ *   Nothing here applies. `Proxmox.SdnApply` (sdn-apply.ts) publishes the whole staged config with
+ *   `PUT /cluster/sdn`; declare one and pass this resource's `subnetId` in its `after`.
+ *
+ * ⛔ AND `Proxmox.SdnApply` CANNOT YET SEE A STAGED SUBNET, SO ITS PLAN WILL LIE ABOUT THIS FAMILY.
+ *   MEASURED: its `COLLECTIONS` list is `cluster/sdn/zones` and `cluster/sdn/vnets`, while
+ *   `PVE::Network::SDN::pending_config` keys the pending view on a SEPARATE `subnets` section of
+ *   the running config. A run that stages only a subnet therefore leaves both counted collections
+ *   at zero, the apply diffs as `noop`, and the subnet never reaches a node. It is NOT fixable by
+ *   adding a string to that list: the subnet index is PER VNET
+ *   (`cluster/sdn/vnets/{vnet}/subnets?pending=1`), so SdnApply needs the vnet names before it can
+ *   count them. Until that lands, a subnet-only change needs `pvesh set /cluster/sdn` by hand.
+ *
+ * ★ THE READ LANE IS ENOUGH HERE, AND THAT IS A REAL DIFFERENCE FROM BOTH SIBLINGS. The zone and
+ *   vnet ITEM reads are gated on SDN.Allocate, which is why each sets `readRole: 'provision'`. This
+ *   one is not. MEASURED from the cluster's own schema on 2026-09-13:
+ *
+ *     GET /cluster/sdn/vnets/{vnet}/subnets/{subnet}
+ *       -> "Require 'SDN.Audit' or 'SDN.Allocate' permissions on '/sdn/zones/<zone>/<vnet>'"
+ *
+ *   and `GET /access/acl` the same day shows `hf-read@pve` holding the built-in PVEAuditor — whose
+ *   seven privileges include SDN.Audit — at `/` with propagate=1. So the default 3600s auditor
+ *   lease reads this family, and a `readRole: 'provision'` here would be privilege nobody needed.
+ *   Writes are a different answer: POST, PUT and DELETE all require SDN.Allocate on
+ *   `/sdn/zones/<zone>/<vnet>`, which `LXCProvisioner` gained on 2026-09-13.
+ *
+ * ⚠️ NO LIVE SUBNET EXISTS ON TB4 TO ROUND-TRIP AGAINST — there are no SDN zones and no vnets, so
+ *   there can be no subnets. Every claim above is read off PVE 9.2.11's own schema and Perl sources
+ *   on n2, and the noop argument below rests on those rather than on a plan this file has watched.
+ *
+ * ⚠️ TWO REFUSALS TO EXPECT, both from `SubnetPlugin::on_update_hook`: PVE will not put a subnet on
+ *   a vnet with `vlanaware` set ("you can't add a subnet on a vlanaware vnet"), and it rejects a
+ *   gateway outside the CIDR unless the mask is /32. Both are create-time 400s, not drift.
+ */
+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 {
+  type DhcpRange,
+  createForm,
+  declaredRanges,
+  dhcpRanges,
+  subnetId,
+  updateForm,
+} from './sdn-subnet-form.ts';
+import { bool, int, text } from './values.ts';
+
+export interface SdnSubnetProps extends WithTarget {
+  /**
+   * The vnet whose bridge carries these addresses. Identity AND a written field.
+   *
+   * ⛔ MOVING A SUBNET BETWEEN VNETS IS NOT SOMETHING THIS RESOURCE CAN DO, and the symptom is
+   *   worth knowing before you meet it. The id is built from the zone and the CIDR, so it does not
+   *   change; but the read goes to `.../vnets/<declared>/subnets/<id>`, and PVE answers a subnet
+   *   filed under another vnet with `raise_param_exc({ vnet => "wrong vnet" })`. `read` folds that
+   *   into "absent", reconcile POSTs, and PVE refuses with "sdn subnet object ID ... already
+   *   defined". Loud and accurate, but it does not converge: change the vnet by removing the
+   *   declaration and writing a new one.
+   */
+  vnet: string;
+  /**
+   * The zone that vnet lives in. ⚠️ PATH INPUT ONLY — PVE accepts no `zone` on a subnet write, and
+   *   nothing here sends one. It is a prop because the path cannot be spelled without it.
+   */
+  zone: string;
+  /** `10.0.0.0/24`. Identity: PVE builds the id from it, so a new CIDR is a new subnet. */
+  cidr: string;
+  /** Handed to guests as their default route, and registered in the zone's IPAM as `<vnet>-gw`. */
+  gateway?: string;
+  /**
+   * Masquerade this subnet. ⚠️ INERT UNTIL THE CLUSTER FIREWALL IS ON — PVE's own description is
+   *   "enable masquerade for this subnet if pve-firewall", and TB4's cluster firewall was empty and
+   *   disabled when this was written. It still round-trips, so declaring it does not diff.
+   */
+  snat?: boolean;
+  /** `adm` -> `<hostname>.adm.example.internal` for records the zone's DNS plugin registers. */
+  dnszoneprefix?: string;
+  /** ⚠️ WIRE NAME `dhcp-dns-server`; see the ⚠️ on `isolatePorts` in sdn-vnet.ts about mappings. */
+  dhcpDnsServer?: string;
+  /**
+   * ⛔ ONE POOL, NOT A LIST, AND THE LIMIT IS THE CLIENT'S RATHER THAN PVE'S. `dhcp-range` is a PVE
+   *   `type => 'array'` parameter, and an array reaches a form-encoded body only as a REPEATED KEY
+   *   — which `client.ts` cannot express, because `pve()` takes `Record<string, string>` and one
+   *   key holds one value. A single occurrence works today because `PVE::RESTHandler`'s
+   *   `$normalize_legacy_param_formats` wraps a scalar into `[$value]` for an array parameter, so
+   *   the type is declared as one range and a second one is unspellable rather than silently lost.
+   * ⛔ THAT COERCION IS MARKED FOR REMOVAL. Its own comment in RESTHandler.pm reads "mark the
+   *   behaviour deprecated with 9.x, and remove it with 10.x", and this cluster runs 9.2.11 — so on
+   *   PVE 10 every write carrying a range becomes a hard 400. The fix is not here: it is a form
+   *   type in client.ts that admits repeated keys.
+   * ⚠️ A LIVE SUBNET CARRYING TWO POOLS IS THEREFORE NARROWED TO ONE by the first deploy that
+   *   declares one. `matches` compares the WHOLE live list, so the narrowing is visible in the plan
+   *   as an update rather than happening quietly, and it converges.
+   */
+  dhcpRange?: DhcpRange;
+}
+
+/**
+ * ⛔ NO `digest` HERE, for the reason sdn-zone.ts gives: PVE returns the digest of the WHOLE
+ *   subnets.cfg, so declaring a SECOND subnet would rewrite this one's stored attributes and
+ *   comparing it would report an update on a subnet nobody touched.
+ */
+export interface SdnSubnetAttributes {
+  /** `<zone>-<network>-<mask>` — the path segment, and the name to use in `pvesh`. */
+  subnetId: string;
+  vnet: string;
+  zone: string;
+  /** `10.0.0.0/24`, as PVE reassembles it from the id. */
+  cidr: string;
+  /** Prefix length, so a guest's `ip=10.0.0.5/24` can be built from a reference. */
+  mask: number;
+  gateway: string;
+  snat: boolean;
+  dnszoneprefix: string;
+  dhcpDnsServer: string;
+  /** Normalised and sorted — never compare a raw PVE value to it. See `dhcpRanges`. */
+  dhcpRange: string;
+  /** ⚠️ THE REMINDER IN THE STATE ITSELF: staged config. No value here says a node has the subnet. */
+  readonly staged: true;
+}
+
+export interface ProxmoxSdnSubnet extends Resource<
+  'Proxmox.SdnSubnet',
+  SdnSubnetProps,
+  SdnSubnetAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ⚠️ NO `defaultRemovalPolicy: 'retain'`, UNLIKE THE SEVEN FAMILIES THAT CARRY IT, AND THE ★ IN
+ *   resource.ts IS THE TEST IT FAILS: a subnet's whole content is a CIDR, a gateway and a pool,
+ *   which a line of TypeScript rebuilds exactly. The part that is NOT rebuildable is the guest
+ *   addresses the zone's IPAM handed out, and PVE guards that itself — MEASURED in the built-in
+ *   `pve` IPAM plugin, which answers a delete with "cannot delete subnet '<cidr>', not empty"
+ *   whenever anything beyond the gateway still holds an address. That refusal is surfaced as-is.
+ */
+export const ProxmoxSdnSubnet = Resource<ProxmoxSdnSubnet>('Proxmox.SdnSubnet');
+
+const handlers = pveHandlers<SdnSubnetProps, SdnSubnetAttributes>({
+  attributes: (live, props) => {
+    /**
+     * ⚠️ UNREACHABLE ON A HEALTHY CLUSTER, AND KEPT BECAUSE "UNREACHABLE" IS A FACT ABOUT TODAY'S
+     *   PVE. The read handler already refuses a subnet filed under another vnet, so this row should
+     *   never arrive — see the ⛔ on `vnet` above for what that refusal costs. If a future PVE
+     *   answers instead of raising, reporting the foreign subnet as absent makes reconcile POST and
+     *   PVE say "already defined": still loud, rather than a silent noop over somebody else's
+     *   addresses.
+     */
+    const liveVnet = text(live['vnet']);
+    if (liveVnet !== '' && liveVnet !== props.vnet) return undefined;
+    return {
+      cidr: text(live['cidr']),
+      dhcpDnsServer: text(live['dhcp-dns-server']),
+      dhcpRange: dhcpRanges(live['dhcp-range']),
+      dnszoneprefix: text(live['dnszoneprefix']),
+      gateway: text(live['gateway']),
+      mask: int(live['mask'], 0),
+      snat: bool(live['snat']),
+      staged: true,
+      subnetId: subnetId(props),
+      vnet: props.vnet,
+      zone: text(live['zone']),
+    };
+  },
+  collection: (props) => `cluster/sdn/vnets/${props.vnet}/subnets`,
+  createForm,
+  /**
+   * ⛔ FIVE REPORTED FIELDS ARE DELIBERATELY ABSENT FROM THIS COMPARISON, and each is a
+   *   forever-diff if it goes back in.
+   *   `subnetId`, `cidr`, `zone` and `mask` are all DERIVED BY PVE FROM THE ID — measured in
+   *   `Subnets::sdn_subnets_config`, which splits the id and synthesises cidr/zone/network/mask on
+   *   every read. None of the four is a POST or PUT parameter, so a difference could never be
+   *   written; and since the id IS the path this read used, a difference cannot arise either — the
+   *   GET would have failed and the factory would report "absent" instead.
+   *   `vnet` is the FILTER that produced this row rather than a reading of it: PVE refuses to
+   *   answer with a subnet on another vnet, so comparing it can only ever be true.
+   *   `staged` is a fact about the cluster, not about the declaration: diffing it would report an
+   *   update on every plan until somebody applied, then another the moment anyone staged anything.
+   *   `digest` is not even reported — see the ⛔ above the attributes.
+   */
+  matches: (attributes, props) =>
+    attributes.gateway === (props.gateway ?? '') &&
+    attributes.snat === (props.snat === true) &&
+    attributes.dnszoneprefix === (props.dnszoneprefix ?? '') &&
+    attributes.dhcpDnsServer === (props.dhcpDnsServer ?? '') &&
+    attributes.dhcpRange === declaredRanges(props.dhcpRange),
+  /**
+   * ⚠️ NO `?pending=1` AND NO `?running=1`, HOWEVER TEMPTING — the same refusal sdn-vnet.ts makes.
+   *   The factory uses this one path for GET, PUT and DELETE alike, every one of those schemas
+   *   declares `additionalProperties => 0`, and PVE answers an unexpected parameter on a write with
+   *   "parameter verification failed". Staged-ness is documented at the top of this file instead.
+   */
+  path: (props) => `cluster/sdn/vnets/${props.vnet}/subnets/${subnetId(props)}`,
+  updateForm,
+});
+
+/**
+ * ⛔ `list` IS EMPTY LIKE EVERY OTHER RESOURCE HERE. `GET /cluster/sdn/vnets/{vnet}/subnets` answers
+ *   with every subnet on that bridge, guest addresses and all; adopting one would invite Alchemy to
+ *   narrow or delete a network nobody declared. Adoption stays an explicit act.
+ *
+ * ⛔ AND A DELETE IS STAGED TOO, WHICH IS THE HALF PEOPLE FORGET. The section leaves subnets.cfg and
+ *   Alchemy drops the resource, but the gateway stays on the bridge and DHCP keeps answering until
+ *   something applies `PUT /cluster/sdn`: a destroy nobody applies reads as complete in the plan and
+ *   has not happened on the cluster.
+ */
+export const ProxmoxSdnSubnetProvider = () =>
+  Provider.effect(ProxmoxSdnSubnet, Effect.succeed(ProxmoxSdnSubnet.Provider.of(handlers)));

package/src/proxmox/sdn-vnet.ts

@@ -0,0 +1,228 @@
+/**
+ * `Proxmox.SdnVnet` — the bridge a guest actually attaches to.
+ *
+ * ★ THIS IS THE OBJECT THAT CLOSES THE GAP BETWEEN A DECLARED CONTAINER AND A DECLARED NETWORK.
+ *   `Proxmox.Lxc` takes `net0: name=eth0,bridge=vmbr0,ip=dhcp`, in which the bridge is a string
+ *   nothing checks. A vnet's id IS the bridge PVE builds on every node of its zone, so declaring
+ *   the vnet and passing its `bridge` attribute into `net0` turns that string into a reference
+ *   Alchemy can order and a plan can show.
+ *
+ * ⚠️ MEASURED: CREATING A VNET CHECKS PERMISSION AT `/sdn/zones/-`, NOT AT THE VNET. The ACL path
+ *   is the ZONE's, so a vnet whose zone does not exist yet fails as a PERMISSION error rather than
+ *   as "no such zone" — and you go off widening a role that was never the problem. `zone` is
+ *   therefore a hard dependency edge, not a convention: pass the zone resource's own attribute so
+ *   Alchemy creates the zone first. A zone name typed in as a literal buys no ordering at all.
+ *
+ * ⛔ THE READ-BACK AFTER A WRITE PROVES THE STAGING FILE AND NOTHING MORE — the same trap as
+ *   `sdn-zone`, and it walks straight through the factory's guard. PVE's SDN endpoints write
+ *   `/etc/pve/sdn/vnets.cfg`; nothing reaches a node's `/etc/network/interfaces` until
+ *   `PUT /cluster/sdn` applies the staged config. `pveOperations.reconcile` reads back and refuses
+ *   when an object is absent, and a vnet that exists only on paper SATISFIES that read: reconcile
+ *   reports success, the next plan says noop, and no bridge exists anywhere on the cluster.
+ *   This resource does NOT issue the apply, deliberately. One vnet's reconcile cannot decide to
+ *   commit every other pending SDN change in the cluster, including ones a human staged in the UI
+ *   and has not finished. Apply stays an operator's act — `pvesh set /cluster/sdn`.
+ *
+ * ★ SUBNETS ARE A SIBLING RESOURCE, NOT A FIELD HERE. The gateway and the DHCP ranges guests take
+ *   addresses from hang off `cluster/sdn/vnets/{vnet}/subnets`, which MEASURED refuses a POST that
+ *   omits `type` or `subnet` ("parameter verification failed"). Same factory, one path deeper, and
+ *   it depends on this resource the way this one depends on the zone.
+ *
+ * ⛔ read/diff NEED SDN.Allocate TOO, NOT SDN.Audit — corrected 2026-09-13 against the cluster's
+ *   schema. `GET /cluster/sdn/vnets/{vnet}` is checked against SDN.Allocate exactly as the zone
+ *   item endpoint is, while only the COLLECTION read accepts SDN.Audit. An auditor-shaped `read`
+ *   lease is therefore refused, and `pveOperations.read` turns that refusal into "absent" rather
+ *   than an error — see the ⛔ in sdn-zone.ts and docs/privileges.md.
+ *
+ * ⚠️ PRIVILEGES, AND THE ESTATE'S CREDENTIAL HELD NONE OF THEM UNTIL 2026-09-13. reconcile and
+ *   delete mint `provision` and need SDN.Allocate on `/sdn/zones`, or on the one zone if scoped. `LXCProvisioner` grants
+ *   SDN.Use, which is what a GUEST needs in order to attach to a vnet and NOT what creating one
+ *   needs, so a container declared on this vnet works today while the vnet itself 403s. Widen
+ *   deliberately, the way Pool.Allocate was:
+ *   `pveum role modify LXCProvisioner --privs "<existing>,SDN.Allocate,SDN.Audit"` over SSH,
+ *   preserving every existing privilege.
+ */
+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 { bool, withClears } from './values.ts';
+
+export interface SdnVnetProps extends WithTarget {
+  /**
+   * ⛔ THE PRIMARY KEY AND THE BRIDGE NAME AT ONCE. PVE caps it at eight alphanumeric characters
+   *   because it becomes a real interface on every node in the zone. There is no rename: a new id
+   *   is a new bridge, and every guest whose `net0` still names the old one stays on the old one.
+   */
+  vnet: string;
+  /**
+   * The SDN zone that owns it. Mutable — a vnet can be moved between zones — but see the ⚠️ at the
+   * top of this file: the zone has to exist first, and passing a zone resource's attribute instead
+   * of a literal is the only thing that makes Alchemy order them.
+   */
+  zone: string;
+  /** Free text shown in the UI. Mutable; clear it by dropping the prop, never by passing `''`. */
+  alias?: string;
+  /** VLAN id or VXLAN VNI, depending on the zone's type. Mutable. Absent means untagged. */
+  tag?: number;
+  /** Let guests on this bridge carry their own VLAN tags. Mutable. */
+  vlanaware?: boolean;
+  /**
+   * Stop guests on this bridge from reaching each other directly. Mutable.
+   * ⚠️ The wire name is `isolate-ports`, with a hyphen — see the ⚠️ on `shape` for why that costs
+   *   attention in two places rather than one.
+   */
+  isolatePorts?: boolean;
+}
+
+export interface SdnVnetAttributes {
+  vnet: string;
+  /**
+   * The same string as `vnet`, duplicated on purpose: it is the name a guest's `net0` must carry.
+   * Referencing it from a `Proxmox.Lxc`'s props is what makes Alchemy build the network before the
+   * container. A hardcoded `vmbr1` in `net0` is a string nothing checks and nothing orders.
+   */
+  bridge: string;
+  zone: string;
+  alias: string;
+  /**
+   * Absent when the vnet is untagged — see `tagOf` for why this is optional and not `0`.
+   * ⚠️ `| undefined` IS LOAD-BEARING under exactOptionalPropertyTypes: the attributes
+   *   builder always sets this key, writing `undefined` for an untagged vnet, so the type
+   *   must permit a present-but-undefined value as well as an absent one. Without it the
+   *   read path does not typecheck, and 0 is a real VLAN id so it cannot be the sentinel.
+   */
+  tag?: number | undefined;
+  vlanaware: boolean;
+  isolatePorts: boolean;
+}
+
+export interface ProxmoxSdnVnet extends Resource<
+  'Proxmox.SdnVnet',
+  SdnVnetProps,
+  SdnVnetAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxSdnVnet = Resource<ProxmoxSdnVnet>('Proxmox.SdnVnet');
+
+/**
+ * ⚠️ AN ABSENT TAG IS `undefined`, NOT 0, which is why `SdnVnetAttributes.tag` is optional rather
+ *   than falling back the way `memory` does in lxc.ts. VLAN id 0 and VXLAN VNI 0 are real values,
+ *   so a 0 fallback would report an untagged vnet as tagged 0 and then diff forever against a
+ *   declaration that asks for no tag at all.
+ */
+const tagOf = (value: unknown) => (typeof value === 'number' ? value : undefined);
+
+/**
+ * The fields PVE accepts on create and on update alike.
+ *
+ * ⚠️ THE WIRE NAME IS `isolate-ports`, WITH A HYPHEN; the prop is `isolatePorts` so no call site
+ *   has to quote it. Both halves of that mapping have to be right: the form key here AND the read
+ *   in `attributes`. `live['isolatePorts']` would be `undefined` forever, which reads as "the
+ *   cluster does not have it set" and makes every plan ask for the same update, for good.
+ */
+const shape = (props: SdnVnetProps): Record<string, string> => {
+  const alias = props.alias ?? '';
+  return {
+    // ⚠️ THE TWO BOOLEANS ARE ALWAYS SENT, `0` INCLUDED, AND THAT IS NOT AN OVERSIGHT. `0` and
+    //   "never declared" mean the same thing to PVE and to `matches` below, so an explicit `0`
+    //   makes the two converge — which is why neither ever appears in the `delete` list.
+    'isolate-ports': props.isolatePorts === true ? '1' : '0',
+    vlanaware: props.vlanaware === true ? '1' : '0',
+    zone: props.zone,
+    // ⚠️ AN EMPTY ALIAS IS OMITTED, NOT SENT AS `''`. `''` is how this file spells "unset", and
+    //   unset goes through the `delete` parameter below; sending it as a value would ask PVE to
+    //   store an empty description, which is a different request from having none.
+    ...(alias === '' ? {} : { alias }),
+    ...(props.tag === undefined ? {} : { tag: String(props.tag) }),
+  };
+};
+
+/**
+ * ⛔ OMITTING A FIELD DOES NOT CLEAR IT. PVE keeps whatever the config already holds, so a
+ *   declaration that DROPS its alias would diff as `update` forever: `matches` compares `''`
+ *   against the live text, the PUT says nothing about alias, and the next plan asks for the very
+ *   same update. PVE's own answer is the `delete` parameter — a comma-separated list of properties
+ *   to unset — which exists on the update endpoint only. That is why create does not come through
+ *   here and calls `shape` directly.
+ *
+ * ⚠️ REASONED FROM PVE'S UPDATE SCHEMA, NOT MEASURED ON A CLUSTER — unlike the two MEASURED facts
+ *   at the top of this file, and the difference is worth a reader's attention. `delete` is what
+ *   `SectionConfig::updateSchema` adds to every PVE update endpoint, and unsetting a property that
+ *   was never set is a no-op there. If THIS endpoint turns out to disagree, the blast radius is
+ *   wider than the feature: a plain `{ vnet, zone }` vnet has neither alias nor tag, so its very
+ *   first update carries `delete=alias,tag` and every update fails, not just an unset. The symptom
+ *   is a 400 "parameter verification failed" naming `delete`; the fix is to drop this list and
+ *   accept the forever-update on unset instead. Verify it once against a live vnet.
+ */
+const updateForm = (props: SdnVnetProps): Record<string, string> => {
+  const unset = [
+    ...((props.alias ?? '') === '' ? ['alias'] : []),
+    ...(props.tag === undefined ? ['tag'] : []),
+  ];
+  return withClears(shape(props), unset);
+};
+
+const handlers = pveHandlers<SdnVnetProps, SdnVnetAttributes>({
+  // ⛔ PVE gates this family's ITEM read on the allocate privilege, not the audit one — see
+  //   `readRole` in resource.ts. The auditor-shaped lease reads 403, which `read` turns into
+  //   "absent", and the plan then says create for an object that is plainly there.
+  readRole: 'provision',
+  attributes: (live, props) => ({
+    alias: typeof live['alias'] === 'string' ? live['alias'] : '',
+    bridge: props.vnet,
+    isolatePorts: bool(live['isolate-ports']),
+    tag: tagOf(live['tag']),
+    vlanaware: bool(live['vlanaware']),
+    vnet: props.vnet,
+    /**
+     * ⚠️ `''` RATHER THAN `props.zone` WHEN PVE DOES NOT SAY. Echoing the declared zone back would
+     *   make an unreadable zone look like agreement; `''` matches no declared zone, so the plan
+     *   reports drift instead. A vnet in the wrong zone is attached to the wrong network, and this
+     *   is the one field here where a spurious update costs less than a missed one.
+     */
+    zone: typeof live['zone'] === 'string' ? live['zone'] : '',
+  }),
+  collection: () => 'cluster/sdn/vnets',
+  createForm: (props) => ({ ...shape(props), vnet: props.vnet }),
+  /**
+   * ⚠️ `vnet`, `bridge` AND WHETHER THE CONFIG IS APPLIED ARE ABSENT FROM THIS COMPARISON ON
+   *   PURPOSE. The first two are the path — a changed id is a different object, not an edit — and
+   *   staged-vs-running is a fact about the cluster rather than about the declaration. Diffing it
+   *   would report an update on every plan until somebody ran the apply, and then report another
+   *   one the moment anybody else staged anything at all.
+   */
+  matches: (attributes, props) =>
+    attributes.zone === props.zone &&
+    attributes.alias === (props.alias ?? '') &&
+    attributes.tag === props.tag &&
+    attributes.vlanaware === (props.vlanaware === true) &&
+    attributes.isolatePorts === (props.isolatePorts === true),
+  /**
+   * ⚠️ NO QUERY STRING HERE, HOWEVER TEMPTING. `?pending=1` would surface whether the staged
+   *   config has been applied, but the factory uses this one path for GET, PUT and DELETE alike,
+   *   and PVE answers an unexpected parameter on a write with "parameter verification failed".
+   *   That is why staged-ness is documented at the top of this file rather than made an attribute.
+   */
+  path: (props) => `cluster/sdn/vnets/${props.vnet}`,
+  updateForm,
+});
+
+/**
+* ⛔ EMPTY, LIKE EVERY OTHER RESOURCE IN THIS PACKAGE. `GET /cluster/sdn/vnets` answers
+*   with every vnet on the cluster, and on an estate already running SDN those are
+*   load-bearing bridges with guests on them. Returning them would invite Alchemy to
+*   adopt — and therefore one day delete — a network nobody declared here. Adoption is an
+*   explicit act.
+ 
+ *
+* ⛔ A DELETE IS STAGED LIKE EVERY OTHER SDN WRITE. The vnet leaves `vnets.cfg` at once and
+*   the bridge stays up on every node until `PUT /cluster/sdn` applies the removal, so a
+*   plan reporting "1 deleted" has taken nothing off the network yet. Nothing here applies
+*   on the operator's behalf: see the ⛔ at the top of this file.
+ 
+ */
+export const ProxmoxSdnVnetProvider = () =>
+  Provider.effect(ProxmoxSdnVnet, Effect.succeed(ProxmoxSdnVnet.Provider.of(handlers)));