@homeflare/alchemy 0.1.0

package/src/proxmox/sdn-zone.ts

@@ -0,0 +1,246 @@
+/**
+ * `Proxmox.SdnZone` — the network a declared guest sits on, finally declared too.
+ *
+ * ★ WHY THIS ONE MATTERS MORE THAN IT LOOKS. Every guest NIC here names a bridge —
+ *   `net0=name=eth0,bridge=vmbr0` — that nothing in this package declares: a hand-built interface,
+ *   repeated per node, that a container silently depends on. A zone is the first piece of that
+ *   dependency PVE will let a plan own.
+ *
+ * ⛔ SDN WRITES ARE STAGED, NOT APPLIED, AND THAT DEFEATS THE FACTORY'S READ-BACK GUARANTEE.
+ *   POST and PUT under `cluster/sdn/zones` edit `/etc/pve/sdn/zones.cfg` and change NOTHING on any
+ *   node. The plain GET reads that same staged file back, so `pveOperations` sees its own write,
+ *   finds the object present, and reports a success in which no node gained an interface. The
+ *   applied state is a different document — `.running-config` beside it — and `?pending=1` is the
+ *   read that tells them apart: it returns a merged view with a `state` of new/changed/deleted.
+ *
+ * ⛔ THE APPLY CANNOT LIVE IN THIS RECONCILE, so it is absent rather than forgotten.
+ *   `PUT /cluster/sdn` is the atomic pending-to-apply and it applies the WHOLE staged config —
+ *   every zone, vnet and subnet, on every node. Called from a per-resource reconcile it would push
+ *   some OTHER resource's half-written zone out to the cluster at whatever point the plan ordering
+ *   reached this one, and PVE has no pre-apply hook to veto that. The apply belongs to ONE object
+ *   that depends on all of them — a sibling `Proxmox.SdnApply` over `cluster/sdn`, or a stack-level
+ *   hook that runs last — so that "declared" and "live on the nodes" stay two visible steps.
+ *
+ * ⚠️ SO THESE ATTRIBUTES DESCRIBE THE STAGED ZONE, and there is deliberately no `applied` flag:
+ *   the factory uses ONE path for GET, PUT and DELETE, and PVE's parameter schemas are closed, so
+ *   an unexpected `pending` on the PUT is a 400 rather than an ignored hint. Reading `?pending=1`
+ *   means re-implementing the operations this file exists to share, and an `applied: true` that
+ *   was never measured is worse than an absent one. Deploying this resource does not change the
+ *   network; it changes what the next apply will do.
+ *
+ * ⛔ THE READ THIS RESOURCE PERFORMS NEEDS SDN.Allocate, NOT SDN.Audit, AND AN EARLIER DRAFT OF
+ *   THIS COMMENT SAID OTHERWISE. Read off the cluster's own schema on 2026-09-13:
+ *
+ *     GET /cluster/sdn/zones          -> "list entries where you have SDN.Audit or SDN.Allocate"
+ *     GET /cluster/sdn/zones/{zone}   -> {"check": ["perm", "/sdn/zones/{zone}", ["SDN.Allocate"]]}
+ *
+ *   `pveOperations.read` calls the ITEM endpoint, so an auditor-shaped `read` lease is REFUSED —
+ *   and the refusal does not surface as a 403. `read` folds every failure into `undefined`, which
+ *   the factory reads as "absent", so the plan says create, the POST goes out, and PVE answers
+ *   that the zone already exists. This is the same class as Proxmox.Storage; see
+ *   docs/privileges.md, "The failure that does not look like a permission problem".
+ *
+ * ⚠️ THE REST OF THE PRIVILEGES. Writes need SDN.Allocate (`/sdn/zones` to create,
+ *   `/sdn/zones/{zone}` to update or delete); the apply — `Proxmox.SdnApply`, which is what
+ *   actually publishes any of this — needs SDN.Allocate on `/sdn` itself. SDN.Use is NOT among
+ *   them: it permits attaching a guest to an existing vnet and nothing else.
+ */
+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 { csv, int, text, withClears } from './values.ts';
+
+/** PVE's zone plugins. Which one a zone is decides which fields below it will even accept. */
+export type SdnZoneType = 'evpn' | 'qinq' | 'simple' | 'vlan' | 'vxlan';
+
+export interface SdnZoneProps extends WithTarget {
+  /**
+   * PVE's primary key. ⚠️ AT MOST EIGHT LOWERCASE ALPHANUMERICS, first one a letter: the id lands
+   *   in generated interface names, so PVE enforces it with a regex whose rejection reads as
+   *   "value does not match the regex pattern" rather than as "your name is too long".
+   */
+  zone: string;
+  /**
+   * ⛔ CREATE-TIME ONLY. `PUT /cluster/sdn/zones/{zone}` has no `type` parameter at all — a
+   *   section's type is fixed when it is written. Changing it here is not an update PVE can
+   *   perform; the ⛔ in `attributes` turns that edit into a refusal instead of a silent no-op.
+   */
+  type: SdnZoneType;
+  /** Accepted by every zone type. Unset means the zone inherits the underlying bridge's MTU. */
+  mtu?: number;
+  /** ⚠️ WHICH NODES THE ZONE IS DEPLOYED TO. Unset means EVERY node, not none. */
+  nodes?: string[];
+  /** IPAM plugin id. Unset is the built-in `pve` one — the two are one zone, see `sameIpam`. */
+  ipam?: string;
+  /** DNS plugin id used to register guest records. */
+  dns?: string;
+  /** The domain those records are registered under, e.g. `example.internal`. */
+  dnszone?: string;
+  /** vxlan only, and REQUIRED there: the peer addresses the tunnel mesh is built from. */
+  peers?: string[];
+  /** evpn only, and required there. PVE's own hyphenated name, so no mapping to get wrong. */
+  'vrf-vxlan'?: number;
+  /** qinq only, and required there: the service VLAN tag the zone's vnets are stacked inside. */
+  tag?: number;
+  /** vlan and qinq only, and required in both: the existing bridge the zone is carved out of. */
+  bridge?: string;
+}
+
+/**
+ * ⛔ NO `digest` HERE, ON PURPOSE. PVE returns one, but it is the digest of the WHOLE zones.cfg
+ *   file rather than of this section — declaring a SECOND zone would rewrite this one's stored
+ *   attributes, and comparing it would report an update on a zone nobody touched.
+ */
+export interface SdnZoneAttributes {
+  zone: string;
+  type: SdnZoneType;
+  /** 0 when unset, which is PVE's "inherit from the bridge" rather than an MTU of zero. */
+  mtu: number;
+  /** Normalised: split, sorted, rejoined. Never compare a raw PVE string to it — see `csv`. */
+  nodes: string;
+  /** The EFFECTIVE ipam: an absent one is reported as `pve`, because that is what will be used. */
+  ipam: string;
+  dns: string;
+  dnszone: string;
+  peers: string;
+  'vrf-vxlan': number;
+  tag: number;
+  bridge: string;
+  /** ⚠️ THE REMINDER IN THE STATE ITSELF: staged config. No value here says a node has the zone. */
+  readonly staged: true;
+}
+
+export interface ProxmoxSdnZone extends Resource<
+  'Proxmox.SdnZone',
+  SdnZoneProps,
+  SdnZoneAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxSdnZone = Resource<ProxmoxSdnZone>('Proxmox.SdnZone');
+
+/**
+ * ⚠️ AN ABSENT `ipam` AND `ipam pve` ARE THE SAME ZONE. `pve` is the built-in default, and whether
+ *   PVE materialises that word into zones.cfg on create is version-dependent — so comparing the
+ *   raw values reports an update on the plan immediately AFTER the create, on a zone this provider
+ *   just wrote itself. Normalising both sides is loop-proof under either behaviour.
+ */
+const sameIpam = (live: string, declared: string | undefined) =>
+  (live === '' ? 'pve' : live) === (declared === undefined || declared === '' ? 'pve' : declared);
+
+/**
+ * The mutable fields, spread in only when defined.
+ *
+ * ⚠️ AN EMPTY STRING IS NOT "UNSET" FOR AN INTEGER FIELD. `mtu=` fails PVE's parameter check
+ *   outright instead of clearing the value, so the pool.ts habit of sending `''` for an absent
+ *   optional does not carry over here. Clearing is a separate verb — see `clearable`.
+ */
+const body = (props: SdnZoneProps): Record<string, string> => ({
+  ...(props.bridge === undefined ? {} : { bridge: props.bridge }),
+  ...(props.dns === undefined ? {} : { dns: props.dns }),
+  ...(props.dnszone === undefined ? {} : { dnszone: props.dnszone }),
+  ...(props.ipam === undefined ? {} : { ipam: props.ipam }),
+  ...(props.mtu === undefined ? {} : { mtu: String(props.mtu) }),
+  ...(props.nodes === undefined ? {} : { nodes: csv(props.nodes) }),
+  ...(props.peers === undefined ? {} : { peers: csv(props.peers) }),
+  ...(props.tag === undefined ? {} : { tag: String(props.tag) }),
+  ...(props['vrf-vxlan'] === undefined ? {} : { 'vrf-vxlan': String(props['vrf-vxlan']) }),
+});
+
+/**
+ * Which managed fields PVE will let `delete=` clear, per zone type.
+ *
+ * ⛔ A PUT THAT SIMPLY OMITS A FIELD DOES NOT CLEAR IT. PVE merges the form into the existing
+ *   section, so dropping `mtu` from a declaration leaves the old MTU in place and `matches`
+ *   reports an update on every plan forever — the exact bug this table exists to prevent.
+ * ⛔ AND THE LIST CANNOT BE THE SAME FOR EVERY TYPE. `delete=<opt>` dies with "no such option"
+ *   when the option is not in that plugin's schema (`peers` on a simple zone) and with "unable to
+ *   delete required option" when it is required there. `bridge`, `tag`, `peers` and `vrf-vxlan`
+ *   are required by the only types that accept them, so none of the four is ever clearable: a
+ *   zone that lost one is a replace, not an update.
+ * ⚠️ `ipam` IS OMITTED FOR evpn DELIBERATELY. It is optional on the other four; on evpn its
+ *   optionality has moved between releases, and a wrong entry here is a hard 400 on EVERY update
+ *   rather than a cosmetic diff. Dropping `ipam` from an evpn declaration therefore reports an
+ *   update that does not converge — visible, unlike a wrong delete that breaks the zone.
+ */
+const clearable: Record<SdnZoneType, readonly string[]> = {
+  evpn: ['dns', 'dnszone', 'mtu', 'nodes'],
+  qinq: ['dns', 'dnszone', 'ipam', 'mtu', 'nodes'],
+  simple: ['dns', 'dnszone', 'ipam', 'mtu', 'nodes'],
+  vlan: ['dns', 'dnszone', 'ipam', 'mtu', 'nodes'],
+  vxlan: ['dns', 'dnszone', 'ipam', 'mtu', 'nodes'],
+};
+
+const handlers = pveHandlers<SdnZoneProps, SdnZoneAttributes>({
+  // ⛔ 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) => {
+    /**
+     * ⛔ A ZONE OF ANOTHER TYPE IS ANOTHER OBJECT, AND "ABSENT" IS THE HONEST ANSWER. A PUT cannot
+     *   change `type`, and the factory only calls a change `replace` for a resource with no update
+     *   path — which this is not. Reporting the foreign zone as missing makes reconcile POST, and
+     *   PVE refuses with "sdn zone ID 'x' already defined": a loud, accurate error instead of a
+     *   silent noop over somebody else's zone. An older PVE that omits `type` falls through.
+     */
+    const liveType = text(live['type']);
+    if (liveType !== '' && liveType !== props.type) return undefined;
+    return {
+      bridge: text(live['bridge']),
+      dns: text(live['dns']),
+      dnszone: text(live['dnszone']),
+      ipam: text(live['ipam']) === '' ? 'pve' : text(live['ipam']),
+      mtu: int(live['mtu'], 0),
+      nodes: csv(text(live['nodes'])),
+      peers: csv(text(live['peers'])),
+      staged: true,
+      tag: int(live['tag'], 0),
+      type: props.type,
+      'vrf-vxlan': int(live['vrf-vxlan'], 0),
+      zone: props.zone,
+    };
+  },
+  collection: () => 'cluster/sdn/zones',
+  createForm: (props) => ({ ...body(props), type: props.type, zone: props.zone }),
+  /**
+   * ⚠️ `type` AND `zone` ARE NOT COMPARED. `zone` is the key the object was read by, and `type` is
+   *   handled above by refusing to recognise a zone of the wrong one. Comparing either here would
+   *   produce a diff whose update can never satisfy it.
+   */
+  matches: (attributes, props) =>
+    attributes.mtu === (props.mtu ?? 0) &&
+    attributes.nodes === csv(props.nodes) &&
+    sameIpam(attributes.ipam, props.ipam) &&
+    attributes.dns === (props.dns ?? '') &&
+    attributes.dnszone === (props.dnszone ?? '') &&
+    attributes.peers === csv(props.peers) &&
+    attributes['vrf-vxlan'] === (props['vrf-vxlan'] ?? 0) &&
+    attributes.tag === (props.tag ?? 0) &&
+    attributes.bridge === (props.bridge ?? ''),
+  path: (props) => `cluster/sdn/zones/${props.zone}`,
+  updateForm: (props) => {
+    const fields = body(props);
+    const clear = clearable[props.type].filter((option) => fields[option] === undefined);
+    return withClears(fields, clear);
+  },
+});
+
+/**
+* ⛔ Empty for the same reason as every other resource here, and with extra force for SDN:
+*   `GET /cluster/sdn/zones` answers with the zones the cluster's whole network already
+*   runs on. Adopting those would make a later `alchemy destroy` a cluster-wide outage.
+ 
+ *
+* ⛔ A DELETE IS STAGED TOO, AND THAT IS THE HALF PEOPLE FORGET. The section leaves
+*   zones.cfg and Alchemy drops the resource, but the zone KEEPS RUNNING on every node
+*   until something applies `PUT /cluster/sdn`: a destroy nobody applies reads as complete
+*   in the plan and has not happened on the cluster.
+* ⚠️ PVE also refuses to remove a zone that still holds vnets. That refusal is kept — it is
+*   the cluster declining to orphan a network because a line left a file.
+ 
+ */
+export const ProxmoxSdnZoneProvider = () =>
+  Provider.effect(ProxmoxSdnZone, Effect.succeed(ProxmoxSdnZone.Provider.of(handlers)));

package/src/proxmox/storage.ts

@@ -0,0 +1,245 @@
+/**
+ * `Proxmox.Storage` — one entry in `/etc/pve/storage.cfg`, declared. Cluster-scoped like a pool,
+ * which is why `path` and `collection` carry no node segment though a storage is used per node.
+ *
+ * ★ THIS IS THE OBJECT EVERY CONTAINER ALREADY DEPENDS ON AND NOTHING DECLARES. `LxcProps.storage`
+ *   and the prefix of `LxcProps.ostemplate` (`local:vztmpl/...`) are bare strings, so a container's
+ *   rootfs points at something outside the graph: rebuild a node and the plan still reads `noop`
+ *   right up to the create that fails because the storage is not there. Passing this resource's
+ *   `storage` attribute into `LxcProps.storage` makes the dependency real — Alchemy orders by data
+ *   flow, so the storage reconciles first because the container reads a value out of it.
+ *
+ * ⛔ ONE PRIVILEGE COVERS THIS WHOLE FAMILY AND IT IS `Datastore.Allocate` ON `/storage`. Create,
+ *   update, delete AND the single-object read all check it — `Datastore.Audit` is not enough for
+ *   any of them. MEASURED: `GET /storage/local` under the auditor-scoped `read` lease answers 403
+ *   "Permission check failed (/storage/local, Datastore.Allocate)". `pveOperations.read` folds
+ *   every failure into `undefined`, i.e. "absent", because a 404 is a legitimate answer there and
+ *   it cannot tell the two apart — so under that lease this resource NEVER CONVERGES, in two
+ *   directions: reconcile reads "absent" and POSTs a create over a storage that is already defined,
+ *   and where a create does land the read-back is 403 too, so reconcile dies with "the write
+ *   returned no error but the object is still absent" about an object it has just built. Both
+ *   messages point away from the cause.
+ *   ★ SO WIDEN OR RE-POINT BEFORE THE FIRST PLAN, outside this file: give the credential mount's
+ *     `read` role `Datastore.Allocate` on `/storage`, or read this family with `provision`. The
+ *     provision role in the estate this was written for holds `Datastore.AllocateSpace` and
+ *     `Datastore.Audit`, and NEITHER IS IT — AllocateSpace writes volumes INTO a storage, Allocate
+ *     DEFINES one — so it 403s here until widened the way `Pool.Allocate` was for `Proxmox.Pool`.
+ *
+ * ⛔ THERE IS NO `password` PROP AND THERE MUST NEVER BE ONE. PBS and CIFS storages take one at
+ *   create time, and Alchemy persists attributes UNENCRYPTED — a secret in props is one careless
+ *   line away from being an attribute, and from there it is in the state store's nightly dump. So
+ *   `StorageLocator` types `password`, `keyring` and `encryption-key` as `never`: declaring one is
+ *   a COMPILE ERROR rather than a leak somebody finds in a backup months later. Set it once out of
+ *   band (`pvesm set <id> --password`); PVE never returns it on read, so nothing here could diff it
+ *   anyway.
+ */
+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, flag } from './values.ts';
+
+/**
+ * The create-time, plugin-specific half of a storage: `dir` wants `path`, `nfs` `server`+`export`,
+ * `cifs` `server`+`share`, `pbs` `server`+`datastore`, `rbd` `pool`+`monhost`, `lvmthin`
+ * `vgname`+`thinpool`, `zfspool` `pool`. A bag rather than two dozen named fields, because PVE
+ * ships about that many plugins and each brings its own locator. ⚠️ Never diffed — see `matches`.
+ *
+ * ⛔ `password`, `keyring` AND `encryption-key` ARE `never` ON PURPOSE — see the ⛔ in the header.
+ *   POSITIVE-CONTROLLED rather than assumed: all three are a compile error, `TS2322: Type 'string'
+ *   is not assignable to type 'undefined'`.
+ */
+export type StorageLocator = Record<string, string> & {
+  password?: never;
+  keyring?: never;
+  'encryption-key'?: never;
+};
+
+export interface StorageProps extends WithTarget {
+  /** PVE's primary key, cluster-wide — the string an LXC's `storage` and `ostemplate` name. */
+  storage: string;
+  /**
+   * `dir` | `nfs` | `cifs` | `pbs` | `zfspool` | `lvmthin` | `rbd` | … ⚠️ CREATE-ONLY, so a changed
+   * `type` plans as `noop` (see `matches`). PVE cannot retype a storage: remove and redeclare.
+   */
+  type: string;
+  /** ⚠️ Create-only, one shape per plugin. See `StorageLocator`. */
+  locator?: StorageLocator;
+  /** `images,rootdir,vztmpl,iso,backup,snippets`. PVE reports `none` for an empty set. */
+  content?: string;
+  /**
+   * Node restriction, e.g. `n1,n2`. ⚠️ A STORAGE WITH A `nodes` LIST DOES NOT EXIST ANYWHERE ELSE:
+   * an LXC declared on a node outside it fails at create with "storage not available on node".
+   */
+  nodes?: string;
+  /** Keeps the definition but stops PVE using it. */
+  disable?: boolean;
+  /** Tells PVE the same volumes are visible from every node — a claim, not a mechanism. */
+  shared?: boolean;
+  /** `off` | `metadata` | `falloc` | `full`. File-based plugins only. */
+  preallocation?: string;
+  /**
+   * `keep-last=3,keep-daily=7,…`. ⚠️ THE WIRE NAME IS KEPT, HYPHEN AND ALL: a `pruneBackups` that
+   * quietly becomes `prune-backups` in the form body is a second name for one thing.
+   */
+  'prune-backups'?: string;
+  comment?: string;
+  /**
+   * ⚠️ THE DEPRECATED PREDECESSOR OF `prune-backups`, and the two do not mix — declare one or the
+   *   other. `0` means UNLIMITED to PVE rather than "unset", hence the `-1` in the attribute.
+   */
+  maxfiles?: number;
+}
+
+export interface StorageAttributes {
+  storage: string;
+  /** Reported so a plan can show what it points at; never diffed — see `type` above. */
+  type: string;
+  content: string;
+  nodes: string;
+  disable: boolean;
+  shared: boolean;
+  preallocation: string;
+  'prune-backups': string;
+  comment: string;
+  /** ⚠️ `-1` means "no maxfiles in storage.cfg". `0` is a real setting meaning unlimited. */
+  maxfiles: number;
+}
+
+export interface ProxmoxStorage extends Resource<
+  'Proxmox.Storage',
+  StorageProps,
+  StorageAttributes,
+  never,
+  PveRequirements
+> {}
+
+/** ★ `retain` by default — a storage holding volumes cannot be rebuilt. See the ★ in resource.ts. */
+export const ProxmoxStorage = Resource<ProxmoxStorage>('Proxmox.Storage', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const str = (value: unknown, fallback = '') => (typeof value === 'string' ? value : fallback);
+
+const field = (name: string, value: string | undefined): Record<string, string> =>
+  value === undefined ? {} : { [name]: value };
+
+/**
+ * ⚠️ THE CAST DROPS THE THREE `never` GUARDS AND NOTHING ELSE, and it is load-bearing rather than
+ *   lazy: an intersection carrying OPTIONAL properties is not assignable to `Record<string,string>`
+ *   at all, so the guards and the form body cannot both exist without one conversion. At runtime a
+ *   locator is a plain string map; the guards only ever existed to fail a declaration.
+ */
+const locatorForm = (locator: StorageLocator | undefined) =>
+  ({ ...locator }) as Record<string, string>;
+
+/**
+ * ⚠️ PVE RE-SERIALISES ITS LIST FIELDS IN ITS OWN ORDER — `content` and `nodes` are parsed into a
+ *   set and written back sorted, `prune-backups` is a property string that comes back in schema
+ *   order. Comparing raw strings would report an update for `iso,backup` against `backup,iso` on
+ *   every plan, and the PUT would "fix" it into the identical string. Trimming matters too: a
+ *   declared `iso, backup` would otherwise never equal what PVE stores.
+ */
+const tokens = (value: string) =>
+  value
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .sort()
+    .join(',');
+
+const sameList = (declared: string | undefined, live: string) =>
+  declared === undefined || tokens(declared) === tokens(live);
+
+const same = <T>(declared: T | undefined, live: T) => declared === undefined || declared === live;
+
+/**
+ * The mutable half, for create and update alike.
+ *
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED: undeclared means UNMANAGED here, unlike
+ *   `Proxmox.Pool` where an absent comment means `''`. A storage has no single default to fall back
+ *   on — `content` defaults per plugin, and clearing a field needs an explicit `delete=` parameter
+ *   rather than an empty value — so a guessed default would rewrite a storage somebody tuned by
+ *   hand, and comparing one would report drift nobody declared.
+ *
+ * ⚠️ RECONCILE PUTs UNCONDITIONALLY whenever the object exists (resource.ts), so this form must be
+ *   safe to re-apply to a storage that already matches. It is: the declared set and nothing else,
+ *   and PVE leaves absent parameters alone.
+ */
+const mutable = (props: StorageProps): Record<string, string> => ({
+  ...field('comment', props.comment),
+  ...field('content', props.content),
+  ...field('disable', flag(props.disable)),
+  ...field('maxfiles', props.maxfiles === undefined ? undefined : String(props.maxfiles)),
+  ...field('nodes', props.nodes),
+  ...field('preallocation', props.preallocation),
+  ...field('prune-backups', props['prune-backups']),
+  ...field('shared', flag(props.shared)),
+});
+
+const handlers = pveHandlers<StorageProps, StorageAttributes>({
+  // ⛔ 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',
+  /**
+   * ⚠️ `digest` IS DELIBERATELY NOT AN ATTRIBUTE. PVE returns one on every storage read and it
+   *   covers storage.cfg as a FILE, not this section of it, so keeping it would rewrite this
+   *   resource's state whenever an unrelated storage was edited — churn that reads like drift.
+   */
+  attributes: (live, props) => ({
+    comment: str(live['comment']),
+    content: str(live['content']),
+    disable: bool(live['disable']),
+    maxfiles: typeof live['maxfiles'] === 'number' ? live['maxfiles'] : -1,
+    nodes: str(live['nodes']),
+    preallocation: str(live['preallocation']),
+    'prune-backups': str(live['prune-backups']),
+    shared: bool(live['shared']),
+    storage: props.storage,
+    type: str(live['type'], props.type),
+  }),
+  collection: () => 'storage',
+  /**
+   * ⚠️ THE BAG IS SPREAD FIRST SO NOTHING IN IT CAN SHADOW A FIELD THIS RESOURCE MANAGES. A stray
+   *   `storage` or `type` in a locator would otherwise rename the object being created, and PVE
+   *   would build the wrong thing under a name Alchemy then records as the declared one.
+   */
+  createForm: (props) => ({
+    ...locatorForm(props.locator),
+    ...mutable(props),
+    storage: props.storage,
+    type: props.type,
+  }),
+  /**
+   * ⚠️ `type` AND THE LOCATOR ARE NEVER COMPARED, AND AN UNDECLARED FIELD IS NOT COMPARED EITHER.
+   *   PVE returns the create-only fields on read but refuses them on PUT, so diffing one could only
+   *   plan an update that no write can apply: a plan that reports work on every run, forever.
+   */
+  matches: (attributes, props) =>
+    sameList(props.content, attributes.content) &&
+    sameList(props.nodes, attributes.nodes) &&
+    sameList(props['prune-backups'], attributes['prune-backups']) &&
+    same(props.disable, attributes.disable) &&
+    same(props.shared, attributes.shared) &&
+    same(props.preallocation, attributes.preallocation) &&
+    same(props.comment, attributes.comment) &&
+    same(props.maxfiles, attributes.maxfiles),
+  path: (props) => `storage/${props.storage}`,
+  updateForm: mutable,
+});
+
+/**
+* ⛔ EMPTY, AND HERE IT MATTERS MORE THAN ANYWHERE ELSE IN THIS PACKAGE. `GET /storage`
+*   returns every definition on the cluster, `local` and `local-lvm`/`local-zfs` included:
+*   the installer's own, that every guest's rootfs sits on. Adopting those would put
+*   Alchemy one `delete` away from the cluster's disks. Adoption is explicit, always.
+ 
+ *
+* ⚠️ THIS REMOVES THE DEFINITION, NOT THE DATA. PVE drops the section from storage.cfg and
+*   leaves the volumes on disk untouched — so the loss is not the bytes, it is that guests
+*   whose config still names this storage can no longer resolve their own disks.
+ 
+ */
+export const ProxmoxStorageProvider = () =>
+  Provider.effect(ProxmoxStorage, Effect.succeed(ProxmoxStorage.Provider.of(handlers)));