@homeflare/alchemy 0.1.0

package/dist/proxmox/sdn-apply-read.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 type { PveTarget } from './credentials.ts';
+/**
+ * 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 declare const UNDIFFABLE: readonly ['cluster/sdn/ipams', 'cluster/sdn/dns'];
+/**
+ * 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 declare const subsystemAbsent: (error: unknown) => boolean;
+/**
+ * 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 declare const fabricStaged: (staged: string | undefined, running: string | undefined) => number | 'inconsistent';
+/** Stable JSON with `digest` removed and every array sorted, so only real differences show. */
+export declare const canonical: (value: unknown) => string;
+/**
+ * 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 declare const sdnPendingCount: (target: PveTarget) => Effect.Effect<number, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=sdn-apply-read.d.ts.map

package/dist/proxmox/sdn-apply-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdn-apply-read.d.ts","sourceRoot":"","sources":["../../src/proxmox/sdn-apply-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAwBlD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,YAAI,mBAAmB,EAAE,iBAAiB,CAAU,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,UAAW,OAAO,KAAG,OACE,CAAC;AAqBpD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,WACf,MAAM,GAAG,SAAS,WACjB,MAAM,GAAG,SAAS,KAC1B,MAAM,GAAG,cAIX,CAAC;AAuCF,+FAA+F;AAC/F,eAAO,MAAM,SAAS,UAAW,OAAO,KAAG,MAAyC,CAAC;AAiBrF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,WAAY,SAAS,uFAG9C,CAAC"}

package/dist/proxmox/sdn-apply.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `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 * as Provider from 'alchemy/Provider';
+import type { PveRequirements } from './resource.ts';
+import type { WithTarget } from './resource.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 declare const ProxmoxSdnApply: import("alchemy").ResourceClass<ProxmoxSdnApply>;
+export declare const ProxmoxSdnApplyProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxSdnApply>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=sdn-apply.d.ts.map

package/dist/proxmox/sdn-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdn-apply.d.ts","sourceRoot":"","sources":["../../src/proxmox/sdn-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAgB,SAAQ,QAAQ,CAC/C,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,eAAe,kDAAgD,CAAC;AAK7E,eAAO,MAAM,uBAAuB,qIA0EjC,CAAC"}

package/dist/proxmox/sdn-subnet-form.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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';
+/** 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 declare const subnetId: (props: Pick<SdnSubnetProps, 'cidr' | 'zone'>) => string;
+/**
+ * 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 declare const dhcpRanges: (value: unknown) => string;
+/** The declared side of that same comparison, through the same funnel so it cannot drift. */
+export declare const declaredRanges: (range: DhcpRange | undefined) => string;
+/**
+ * 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 declare const optional: (props: SdnSubnetProps) => Record<string, string | undefined>;
+/**
+ * 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 declare const body: (props: SdnSubnetProps) => Record<string, string>;
+/**
+ * ⚠️ `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 declare const createForm: (props: SdnSubnetProps) => Record<string, string>;
+/**
+ * ★ 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 declare const updateForm: (props: SdnSubnetProps) => Record<string, string>;
+//# sourceMappingURL=sdn-subnet-form.d.ts.map

package/dist/proxmox/sdn-subnet-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdn-subnet-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/sdn-subnet-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,sGAAsG;AACtG,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,UAAW,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,WACpB,CAAC;AAKlD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,MAK9B,CAAC;AAEf,6FAA6F;AAC7F,eAAO,MAAM,cAAc,UAAW,SAAS,GAAG,SAAS,WACE,CAAC;AAU9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ,UAAW,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAKhF,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,UAAW,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAQhE,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,UAAW,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAItE,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,UAAW,cAAc,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAKvE,CAAC"}

package/dist/proxmox/sdn-subnet.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `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 { type PveRequirements, type WithTarget } from './resource.ts';
+import { type DhcpRange } from './sdn-subnet-form.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 declare const ProxmoxSdnSubnet: import("alchemy").ResourceClass<ProxmoxSdnSubnet>;
+/**
+ * ⛔ `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 declare const ProxmoxSdnSubnetProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxSdnSubnet>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=sdn-subnet.d.ts.map

package/dist/proxmox/sdn-subnet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdn-subnet.d.ts","sourceRoot":"","sources":["../../src/proxmox/sdn-subnet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AACnF,OAAO,EACL,KAAK,SAAS,EAMf,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8FAA8F;IAC9F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAiB,SAAQ,QAAQ,CAChD,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,mDAAkD,CAAC;AA4DhF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,sIACsD,CAAC"}

package/dist/proxmox/sdn-vnet.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `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 { type PveRequirements, type WithTarget } from './resource.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 declare const ProxmoxSdnVnet: import("alchemy").ResourceClass<ProxmoxSdnVnet>;
+/**
+* ⛔ 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 declare const ProxmoxSdnVnetProvider: () => import("effect/Layer").Layer<Provider.Provider<ProxmoxSdnVnet>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=sdn-vnet.d.ts.map

package/dist/proxmox/sdn-vnet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdn-vnet.d.ts","sourceRoot":"","sources":["../../src/proxmox/sdn-vnet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAe,MAAM,eAAe,CAAC;AAGnF,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAe,SAAQ,QAAQ,CAC9C,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,eAAO,MAAM,cAAc,iDAA8C,CAAC;AAyG1E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,oIACoD,CAAC"}