@homeflare/alchemy 0.13.0 → 0.15.0

package/src/proxmox/generated/constraints/pve-cluster.ts

@@ -0,0 +1,174 @@
+/**
+ * Generated pve-manager parameter constraints for `/cluster` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ * Manifest entry: `pve-apidoc` — pve-manager 9.2.11/f6997e698c7933ea
+ *   sha256 9def8f13611184ee, read on a PVE cluster node from
+ *   /usr/share/pve-docs/api-viewer/apidoc.js
+ *
+ * 27 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
+ * and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it is a rule that could NOT be carried into a
+ *   JavaScript RegExp faithfully (codegen/pattern.ts). It is recorded and NOT enforced.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PVE_CLUSTER_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "pve:POST /cluster/backup": {
+    "bwlimit": {"default":"0","minimum":0,"type":"integer"},
+    "comment": {"maxLength":512,"type":"string"},
+    "compress": {"default":"0","enum":["0","1","gzip","lzo","zstd"],"type":"string"},
+    "dow": {"default":"mon,tue,wed,thu,fri,sat,sun","format":"pve-day-of-week-list","type":"string"},
+    "exclude": {"format":"pve-vmid-list","type":"string"},
+    "fleecing": {"format":"backup-fleecing","type":"string"},
+    "id": {"format":"pve-configid","type":"string"},
+    "ionice": {"default":"7","maximum":8,"minimum":0,"type":"integer"},
+    "lockwait": {"default":"180","minimum":0,"type":"integer"},
+    "mailnotification": {"default":"always","enum":["always","failure"],"type":"string"},
+    "mailto": {"format":"email-or-username-list","type":"string"},
+    "mode": {"default":"snapshot","enum":["snapshot","suspend","stop"],"type":"string"},
+    "node": {"format":"pve-node","type":"string"},
+    "notes-template": {"maxLength":1024,"type":"string"},
+    "notification-mode": {"default":"auto","enum":["auto","legacy-sendmail","notification-system"],"type":"string"},
+    "pbs-change-detection-mode": {"enum":["legacy","data","metadata"],"type":"string"},
+    "performance": {"format":"backup-performance","type":"string"},
+    "prune-backups": {"default":"keep-all=1","format":"prune-backups","type":"string"},
+    "schedule": {"format":"pve-calendar-event","maxLength":128,"type":"string"},
+    "starttime": {"pattern":"\\d{1,2}:\\d{1,2}","patternSource":"\\d{1,2}:\\d{1,2}","type":"string"},
+    "stopwait": {"default":"10","minimum":0,"type":"integer"},
+    "storage": {"format":"pve-storage-id","type":"string"},
+    "vmid": {"format":"pve-vmid-list","type":"string"},
+  },
+  "pve:POST /cluster/firewall/aliases": {
+    "cidr": {"format":"IPorCIDR","required":true,"type":"string"},
+    "comment": {"format":"pve-fw-comment-spec","type":"string"},
+    "name": {"maxLength":64,"minLength":2,"pattern":"[A-Za-z][A-Za-z0-9\\-\\_]+","patternSource":"[A-Za-z][A-Za-z0-9\\-\\_]+","required":true,"type":"string"},
+  },
+  "pve:POST /cluster/ha/resources": {
+    "comment": {"maxLength":4096,"type":"string"},
+    "group": {"format":"pve-configid","type":"string"},
+    "max_relocate": {"default":"1","minimum":0,"type":"integer"},
+    "max_restart": {"default":"1","minimum":0,"type":"integer"},
+    "sid": {"format":"pve-ha-resource-or-vm-id","required":true,"type":"string"},
+    "state": {"default":"started","enum":["started","stopped","enabled","disabled","ignored"],"type":"string"},
+    "type": {"enum":["ct","vm"],"type":"string"},
+  },
+  "pve:POST /cluster/ha/rules": {},
+  "pve:POST /cluster/notifications/matchers": {
+    "mode": {"default":"all","enum":["all","any"],"type":"string"},
+    "name": {"format":"pve-configid","required":true,"type":"string"},
+  },
+  "pve:POST /cluster/replication": {
+    "comment": {"maxLength":4096,"type":"string"},
+    "id": {"format":"pve-replication-job-id","pattern":"[1-9][0-9]{2,8}-\\d{1,9}","patternSource":"[1-9][0-9]{2,8}-\\d{1,9}","required":true,"type":"string"},
+    "rate": {"minimum":1,"type":"number"},
+    "remove_job": {"enum":["local","full"],"type":"string"},
+    "schedule": {"default":"*/15","format":"pve-calendar-event","maxLength":128,"type":"string"},
+    "source": {"format":"pve-node","type":"string"},
+    "target": {"format":"pve-node","required":true,"type":"string"},
+    "type": {"enum":["local"],"required":true,"type":"string"},
+  },
+  "pve:POST /cluster/sdn/vnets": {
+    "alias": {"maxLength":256,"patternSource":"(?^i:[\\(\\)-_.\\w\\d\\s]{0,256})","type":"string"},
+    "tag": {"maximum":16777215,"minimum":1,"type":"integer"},
+    "type": {"enum":["vnet"],"type":"string"},
+    "vnet": {"maxLength":8,"minLength":2,"pattern":"[a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]","patternSource":"[a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]","required":true,"type":"string"},
+    "zone": {"required":true,"type":"string"},
+  },
+  "pve:POST /cluster/sdn/zones": {
+    "dhcp": {"enum":["dnsmasq"],"type":"string"},
+    "dnszone": {"format":"dns-name","type":"string"},
+    "exitnodes": {"format":"pve-node-list","type":"string"},
+    "exitnodes-primary": {"format":"pve-node","type":"string"},
+    "fabric": {"format":"pve-sdn-fabric-id","type":"string"},
+    "mac": {"format":"mac-addr","type":"string"},
+    "nodes": {"format":"pve-node-list","type":"string"},
+    "peers": {"format":"ip-list","type":"string"},
+    "rt-import": {"format":"pve-sdn-bgp-rt-list","type":"string"},
+    "tag": {"minimum":0,"type":"integer"},
+    "type": {"enum":["evpn","faucet","qinq","simple","vlan","vxlan"],"format":"pve-configid","required":true,"type":"string"},
+    "vlan-protocol": {"default":"802.1q","enum":["802.1q","802.1ad"],"type":"string"},
+    "vrf-vxlan": {"maximum":16777215,"minimum":1,"type":"integer"},
+    "vxlan-port": {"default":"4789","maximum":65536,"minimum":1,"type":"integer"},
+    "zone": {"maxLength":8,"minLength":2,"pattern":"[a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]","patternSource":"[a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]","required":true,"type":"string"},
+  },
+  "pve:PUT /cluster/backup/{id}": {
+    "bwlimit": {"default":"0","minimum":0,"type":"integer"},
+    "comment": {"maxLength":512,"type":"string"},
+    "compress": {"default":"0","enum":["0","1","gzip","lzo","zstd"],"type":"string"},
+    "delete": {"format":"pve-configid-list","type":"string"},
+    "dow": {"format":"pve-day-of-week-list","type":"string"},
+    "exclude": {"format":"pve-vmid-list","type":"string"},
+    "fleecing": {"format":"backup-fleecing","type":"string"},
+    "ionice": {"default":"7","maximum":8,"minimum":0,"type":"integer"},
+    "lockwait": {"default":"180","minimum":0,"type":"integer"},
+    "mailnotification": {"default":"always","enum":["always","failure"],"type":"string"},
+    "mailto": {"format":"email-or-username-list","type":"string"},
+    "mode": {"default":"snapshot","enum":["snapshot","suspend","stop"],"type":"string"},
+    "node": {"format":"pve-node","type":"string"},
+    "notes-template": {"maxLength":1024,"type":"string"},
+    "notification-mode": {"default":"auto","enum":["auto","legacy-sendmail","notification-system"],"type":"string"},
+    "pbs-change-detection-mode": {"enum":["legacy","data","metadata"],"type":"string"},
+    "performance": {"format":"backup-performance","type":"string"},
+    "prune-backups": {"default":"keep-all=1","format":"prune-backups","type":"string"},
+    "schedule": {"format":"pve-calendar-event","maxLength":128,"type":"string"},
+    "starttime": {"pattern":"\\d{1,2}:\\d{1,2}","patternSource":"\\d{1,2}:\\d{1,2}","type":"string"},
+    "stopwait": {"default":"10","minimum":0,"type":"integer"},
+    "storage": {"format":"pve-storage-id","type":"string"},
+    "vmid": {"format":"pve-vmid-list","type":"string"},
+  },
+  "pve:PUT /cluster/firewall/aliases/{name}": {
+    "cidr": {"format":"IPorCIDR","required":true,"type":"string"},
+    "comment": {"format":"pve-fw-comment-spec","type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "rename": {"maxLength":64,"minLength":2,"pattern":"[A-Za-z][A-Za-z0-9\\-\\_]+","patternSource":"[A-Za-z][A-Za-z0-9\\-\\_]+","type":"string"},
+  },
+  "pve:PUT /cluster/ha/resources/{sid}": {
+    "comment": {"maxLength":4096,"type":"string"},
+    "delete": {"format":"pve-configid-list","maxLength":4096,"type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "group": {"format":"pve-configid","type":"string"},
+    "max_relocate": {"default":"1","minimum":0,"type":"integer"},
+    "max_restart": {"default":"1","minimum":0,"type":"integer"},
+    "state": {"default":"started","enum":["started","stopped","enabled","disabled","ignored"],"type":"string"},
+  },
+  "pve:PUT /cluster/ha/rules/{rule}": {},
+  "pve:PUT /cluster/notifications/matchers/{name}": {
+    "digest": {"maxLength":64,"type":"string"},
+    "mode": {"default":"all","enum":["all","any"],"type":"string"},
+  },
+  "pve:PUT /cluster/replication/{id}": {
+    "comment": {"maxLength":4096,"type":"string"},
+    "delete": {"format":"pve-configid-list","maxLength":4096,"type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "rate": {"minimum":1,"type":"number"},
+    "remove_job": {"enum":["local","full"],"type":"string"},
+    "schedule": {"default":"*/15","format":"pve-calendar-event","maxLength":128,"type":"string"},
+    "source": {"format":"pve-node","type":"string"},
+  },
+  "pve:PUT /cluster/sdn/vnets/{vnet}": {
+    "alias": {"maxLength":256,"patternSource":"(?^i:[\\(\\)-_.\\w\\d\\s]{0,256})","type":"string"},
+    "delete": {"format":"pve-configid-list","maxLength":4096,"type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "tag": {"maximum":16777215,"minimum":1,"type":"integer"},
+  },
+  "pve:PUT /cluster/sdn/zones/{zone}": {
+    "delete": {"format":"pve-configid-list","maxLength":4096,"type":"string"},
+    "dhcp": {"enum":["dnsmasq"],"type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "dnszone": {"format":"dns-name","type":"string"},
+    "exitnodes": {"format":"pve-node-list","type":"string"},
+    "exitnodes-primary": {"format":"pve-node","type":"string"},
+    "fabric": {"format":"pve-sdn-fabric-id","type":"string"},
+    "mac": {"format":"mac-addr","type":"string"},
+    "nodes": {"format":"pve-node-list","type":"string"},
+    "peers": {"format":"ip-list","type":"string"},
+    "rt-import": {"format":"pve-sdn-bgp-rt-list","type":"string"},
+    "tag": {"minimum":0,"type":"integer"},
+    "vlan-protocol": {"default":"802.1q","enum":["802.1q","802.1ad"],"type":"string"},
+    "vrf-vxlan": {"maximum":16777215,"minimum":1,"type":"integer"},
+    "vxlan-port": {"default":"4789","maximum":65536,"minimum":1,"type":"integer"},
+  },
+};

package/src/proxmox/generated/constraints/pve-pools.ts

@@ -0,0 +1,26 @@
+/**
+ * Generated pve-manager parameter constraints for `/pools` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ * Manifest entry: `pve-apidoc` — pve-manager 9.2.11/f6997e698c7933ea
+ *   sha256 9def8f13611184ee, read on a PVE cluster node from
+ *   /usr/share/pve-docs/api-viewer/apidoc.js
+ *
+ * 27 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
+ * and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it is a rule that could NOT be carried into a
+ *   JavaScript RegExp faithfully (codegen/pattern.ts). It is recorded and NOT enforced.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PVE_POOLS_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "pve:POST /pools": {
+    "poolid": {"format":"pve-poolid","required":true,"type":"string"},
+  },
+  "pve:PUT /pools/{poolid}": {
+    "storage": {"format":"pve-storage-id-list","type":"string"},
+    "vms": {"format":"pve-vmid-list","type":"string"},
+  },
+};

package/src/proxmox/generated/constraints/pve-storage.ts

@@ -0,0 +1,75 @@
+/**
+ * Generated pve-manager parameter constraints for `/storage` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ * Manifest entry: `pve-apidoc` — pve-manager 9.2.11/f6997e698c7933ea
+ *   sha256 9def8f13611184ee, read on a PVE cluster node from
+ *   /usr/share/pve-docs/api-viewer/apidoc.js
+ *
+ * 27 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
+ * and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it is a rule that could NOT be carried into a
+ *   JavaScript RegExp faithfully (codegen/pattern.ts). It is recorded and NOT enforced.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PVE_STORAGE_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "pve:POST /storage": {
+    "base": {"format":"pve-volume-id","type":"string"},
+    "blocksize": {"format":"pve-storage-zfs-blocksize","type":"string"},
+    "content": {"format":"pve-storage-content-list","type":"string"},
+    "content-dirs": {"format":"pve-dir-override-list","type":"string"},
+    "domain": {"maxLength":256,"type":"string"},
+    "export": {"format":"pve-storage-path","type":"string"},
+    "fingerprint": {"pattern":"([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}","patternSource":"([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}","type":"string"},
+    "format": {"enum":["raw","qcow2","subvol","vmdk"],"type":"string"},
+    "fs-name": {"format":"pve-configid","type":"string"},
+    "max-protected-backups": {"default":"Unlimited for users with Datastore.Allocate privilege, 5 for other users","minimum":-1,"type":"integer"},
+    "monhost": {"format":"pve-storage-portal-dns-list","type":"string"},
+    "mountpoint": {"format":"pve-storage-path","type":"string"},
+    "nodes": {"format":"pve-node-list","type":"string"},
+    "options": {"format":"pve-storage-options","type":"string"},
+    "password": {"maxLength":256,"type":"string"},
+    "path": {"format":"pve-storage-path","type":"string"},
+    "port": {"maximum":65535,"minimum":1,"type":"integer"},
+    "portal": {"format":"pve-storage-portal-dns","type":"string"},
+    "preallocation": {"default":"metadata","enum":["off","metadata","falloc","full"],"type":"string"},
+    "prune-backups": {"format":"prune-backups","type":"string"},
+    "saferemove-stepsize": {"default":"32","enum":["1","2","4","8","16","32"],"type":"integer"},
+    "server": {"format":"pve-storage-server","type":"string"},
+    "smbversion": {"default":"default","enum":["default","2.0","2.1","3","3.0","3.11"],"type":"string"},
+    "storage": {"format":"pve-storage-id","required":true,"type":"string"},
+    "subdir": {"format":"pve-storage-path","type":"string"},
+    "thinpool": {"format":"pve-storage-vgname","type":"string"},
+    "type": {"enum":["btrfs","cephfs","cifs","dir","esxi","iscsi","iscsidirect","lvm","lvmthin","nfs","pbs","rbd","zfs","zfspool"],"required":true,"type":"string"},
+    "vgname": {"format":"pve-storage-vgname","type":"string"},
+    "zfs-base-path": {"format":"pve-storage-path","type":"string"},
+  },
+  "pve:PUT /storage/{storage}": {
+    "blocksize": {"format":"pve-storage-zfs-blocksize","type":"string"},
+    "content": {"format":"pve-storage-content-list","type":"string"},
+    "content-dirs": {"format":"pve-dir-override-list","type":"string"},
+    "delete": {"format":"pve-configid-list","maxLength":4096,"type":"string"},
+    "digest": {"maxLength":64,"type":"string"},
+    "domain": {"maxLength":256,"type":"string"},
+    "fingerprint": {"pattern":"([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}","patternSource":"([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}","type":"string"},
+    "format": {"enum":["raw","qcow2","subvol","vmdk"],"type":"string"},
+    "fs-name": {"format":"pve-configid","type":"string"},
+    "max-protected-backups": {"default":"Unlimited for users with Datastore.Allocate privilege, 5 for other users","minimum":-1,"type":"integer"},
+    "monhost": {"format":"pve-storage-portal-dns-list","type":"string"},
+    "mountpoint": {"format":"pve-storage-path","type":"string"},
+    "nodes": {"format":"pve-node-list","type":"string"},
+    "options": {"format":"pve-storage-options","type":"string"},
+    "password": {"maxLength":256,"type":"string"},
+    "port": {"maximum":65535,"minimum":1,"type":"integer"},
+    "preallocation": {"default":"metadata","enum":["off","metadata","falloc","full"],"type":"string"},
+    "prune-backups": {"format":"prune-backups","type":"string"},
+    "saferemove-stepsize": {"default":"32","enum":["1","2","4","8","16","32"],"type":"integer"},
+    "server": {"format":"pve-storage-server","type":"string"},
+    "smbversion": {"default":"default","enum":["default","2.0","2.1","3","3.0","3.11"],"type":"string"},
+    "subdir": {"format":"pve-storage-path","type":"string"},
+    "zfs-base-path": {"format":"pve-storage-path","type":"string"},
+  },
+};

package/src/proxmox/group.ts

@@ -176,6 +176,8 @@ const handlers = pveHandlers<GroupProps, GroupAttributes>({
    *   `resource.ts` states once in the ⛔ on adoption: a field deliberately out of `matches` is a
    *   field this resource does not manage.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /access/groups', update: 'pve:PUT /access/groups/{groupid}' },
   matches: (attributes, props) => attributes.comment === storedComment(props.comment),
   path: (props) => `access/groups/${props.groupid}`,
   /**

package/src/proxmox/ha-resource.ts

@@ -137,6 +137,11 @@ const handlers = pveHandlers<HaResourceProps, HaResourceAttributes>({
    * ⚠️ `sid` AND `type` ARE NOT COMPARED EITHER: sid is the path, so a change there is a different
    *   object, and type is create-only — it is read back from the prefix, never edited.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/ha/resources',
+    update: 'pve:PUT /cluster/ha/resources/{sid}',
+  },
   matches: (attributes, props) =>
     attributes.state === (props.state ?? 'started') &&
     attributes.comment === (props.comment ?? '') &&

package/src/proxmox/ha-rule.ts

@@ -206,6 +206,8 @@ const handlers = pveHandlers<HaRuleProps, HaRuleAttributes>({
    * ⚠️ THE COMMENT IS COMPARED AS PVE WILL STORE IT, not as it was declared — `commentText` and
    *   its ⛔ explain why a `%XX` in a comment does not survive the round trip.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/ha/rules', update: 'pve:PUT /cluster/ha/rules/{rule}' },
   matches: (attributes, props) =>
     attributes.resources === csv(props.resources) &&
     attributes.affinity === props.affinity &&

package/src/proxmox/index.ts

@@ -18,6 +18,9 @@
  * ★ THE NOTIFICATION FAMILIES JOINED 2026-09-22: PBS targets and matchers, the PVE matcher, the
  *   `FromEnv` shape their write-only values take, and the Alertmanager body template
  *   (docs/pbs-notifications.md; the template alone: docs/pbs-alertmanager-body.md).
+ * ★ THE VENDOR CONSTRAINT READER JOINED 2026-09-22 (codegen/README.md). `constraintsFor` and
+ *   `violations` are exported so a CONSUMING stack can assert its own declarations offline — the
+ *   `deploy:pbs` that failed on a 128-character comment had no way to ask that question.
  * ★ Anything else unlisted is still reachable by path if you genuinely need
  *   it — that is a deliberate, visible act rather than an accident of barrelling.
  */
@@ -30,6 +33,13 @@ export { ProxmoxCephFlagProvider } from './ceph-flag.ts';
 export { ProxmoxCephFsProvider } from './ceph-fs.ts';
 export { ProxmoxCephOsdProvider } from './ceph-osd.ts';
 export { ProxmoxCephPool, ProxmoxCephPoolProvider } from './ceph-pool.ts';
+export { constraintsFor, formViolations } from './constraint-guard.ts';
+export {
+  type EndpointConstraints,
+  type EndpointKey,
+  type ParamConstraint,
+  violations,
+} from './constraints.ts';
 export { ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
 export { ProxmoxGroup, ProxmoxGroupProvider } from './group.ts';
 export { ProxmoxHaResource, ProxmoxHaResourceProvider } from './ha-resource.ts';
@@ -63,7 +73,9 @@ export { ProxmoxPool, ProxmoxPoolProvider } from './pool.ts';
 export {
   PROVISION_DEFAULTS,
   PROVISION_PRIVILEGES,
+  type CoreProvisionNames,
   type ProvisionBaseline,
+  type ProvisionComments,
   type ProvisionLane,
   type ProvisionNames,
   type ResolvedProvisionNames,

package/src/proxmox/lxc-interior.test.ts

@@ -0,0 +1,61 @@
+/**
+ * PVE exposes no way to reach INSIDE a container, and this pins that as a measured fact rather
+ * than a thing people keep re-deriving.
+ *
+ * ★ WHY A TEST AND NOT ONLY A DOC. `Proxmox.Lxc` declares a guest's PVE-level config and nothing
+ *   within its filesystem, and every consumer that meets that limit goes looking for the resource
+ *   that must surely exist — an exec, a file write, a cloud-init. It does not, for containers. A
+ *   grep proves that once; this proves it on every run, and fails the day PVE adds one, which is
+ *   exactly when the kit would want to wrap it.
+ * ⛔ THE POSITIVE CONTROL IS LOAD BEARING. A test that only asserts absence passes for free if the
+ *   generated file's comment shape ever changes. QEMU's `agent/exec` and `agent/file-write` are
+ *   asserted present in the same pass, so a format change fails here instead of going quiet.
+ * ⚠️ SIBLING FAMILIES ARE NOT AT PARITY. QEMU and LXC sit under the same `/nodes/{node}/…` tree
+ *   and have completely different reach. Never infer one family's endpoints from the other's.
+ */
+import { describe, expect, test } from 'bun:test';
+
+const schema = await Bun.file(new URL('./generated/pve.ts', import.meta.url)).text();
+
+/** Every endpoint the generated schema documents, as `METHOD /path`. */
+const endpoints = [...schema.matchAll(/(GET|POST|PUT|DELETE) (\/[A-Za-z0-9/{}_.-]+)/g)].map(
+  (match) => `${match[1]} ${match[2]}`,
+);
+
+const under = (prefix: string) =>
+  endpoints.filter((line) => line.slice(line.indexOf(' ') + 1).startsWith(prefix));
+
+const LXC = '/nodes/{node}/lxc/{vmid}';
+const QEMU = '/nodes/{node}/qemu/{vmid}';
+
+describe('a container has no interior API', () => {
+  test('the schema was parsed at all', () => {
+    // ⛔ Without this, every absence assertion below would pass on an empty list.
+    expect(endpoints.length).toBeGreaterThan(100);
+    expect(under(LXC).length).toBeGreaterThan(20);
+  });
+
+  test('QEMU can exec and write files inside a guest — the positive control', () => {
+    expect(under(QEMU)).toContain(`POST ${QEMU}/agent/exec`);
+    expect(under(QEMU)).toContain(`POST ${QEMU}/agent/file-write`);
+    expect(under(QEMU)).toContain(`GET ${QEMU}/agent/file-read`);
+  });
+
+  test('no LXC endpoint execs, reads or writes a file, or takes cloud-init', () => {
+    // ⛔ So a generic, vendor-API-based Resource for a container's interior cannot be written:
+    //    there is nothing to wrap. What is left is an image baked before create, a first-boot
+    //    artifact, or a recorded human step — see docs/proxmox-lxc.md.
+    const reaching = under(LXC).filter((line) =>
+      /\/(agent|exec|file-read|file-write|cloudinit|cloud-init)(\/|$)/.test(line),
+    );
+    expect(reaching).toEqual([]);
+  });
+
+  test('the only LXC reach inside is an interactive console, which is not declarative', () => {
+    // ⚠️ `termproxy` and `vncwebsocket` open a terminal for a person. They are not an API a
+    //    resource can diff, and the kit wraps neither.
+    const consoles = under(LXC).filter((line) => /(termproxy|vncwebsocket|spiceproxy)/.test(line));
+    expect(consoles.length).toBeGreaterThan(0);
+    expect(schema.includes('LxcExec')).toBe(false);
+  });
+});

package/src/proxmox/notification-matcher.ts

@@ -64,6 +64,11 @@ const handlers = pveHandlers<NotificationMatcherProps, NotificationMatcherAttrib
   attributes: (live, props) => matcherAttributes(live, props.name),
   collection: () => 'cluster/notifications/matchers',
   createForm: matcherCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/notifications/matchers',
+    update: 'pve:PUT /cluster/notifications/matchers/{name}',
+  },
   matches: matcherMatches,
   path: (props) => `cluster/notifications/matchers/${props.name}`,
   updateForm: matcherUpdateForm,

package/src/proxmox/pbs-datastore-endpoint.ts

@@ -0,0 +1,29 @@
+/**
+ * `Pbs.Datastore`'s two vendor endpoints, and the plan-time check over its two forms.
+ *
+ * ★ A FILE OF ITS OWN BECAUSE THIS FAMILY DOES NOT USE `pveHandlers`. It writes its own `diff` and
+ *   `reconcile` (a create answers with a task id, so it settles rather than reading back once), so
+ *   it cannot inherit the guard from resource.ts — and a copy of the two calls inside that already
+ *   long file is exactly the per-resource copy-paste the shared handler exists to prevent.
+ *
+ * ⛔ THE FOUR FIELDS THAT MADE THIS WORTH DOING, from the PBS 4.2.6 schema: `comment` is
+ *   maxLength 128 with a no-control-characters pattern, `name` is 3..32 with a safe-id pattern,
+ *   and every `keep-*` has minimum 1. All four were `string`/`number` with the limits in prose.
+ */
+import * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+import { createForm, updateForm } from './pbs-datastore-form.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+
+export const DATASTORE_ENDPOINT: { readonly create: EndpointKey; readonly update: EndpointKey } = {
+  create: 'pbs:POST /config/datastore',
+  update: 'pbs:PUT /config/datastore/{name}',
+};
+
+/** ⚠️ Presence on create only — an update form is partial by design (update-guard.ts). */
+export const guardDatastoreForms = (props: PbsDatastoreProps): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    yield* guardForm(DATASTORE_ENDPOINT.create, createForm(props), true);
+    yield* guardForm(DATASTORE_ENDPOINT.update, updateForm(props), false);
+  });

package/src/proxmox/pbs-datastore.ts

@@ -64,6 +64,7 @@ import {
   updateForm,
 } from './pbs-datastore-form.ts';
 import { guardBackend, guardPath, settle } from './pbs-datastore-guard.ts';
+import { guardDatastoreForms } from './pbs-datastore-endpoint.ts';
 import type { PveRequirements } from './resource.ts';
 import { formToSend } from './update-guard.ts';
 
@@ -181,7 +182,11 @@ export const PbsDatastoreProvider = () =>
          */
         diff: ({ news, output }) =>
           Effect.gen(function* () {
-            if (output === undefined || !isResolved(news)) return undefined;
+            if (!isResolved(news)) return undefined;
+            // ⛔ BEFORE the `output === undefined` return: that branch IS the create, which is the
+            //   one this family has never checked. resource.ts carries the argument in full.
+            yield* guardDatastoreForms(news);
+            if (output === undefined) return undefined;
             const live = yield* readOne(news);
             // ⚠️ `update`, not `create` — Alchemy's Diff admits only noop/update/replace, and an
             //   object Alchemy has state for but PBS does not is drift for reconcile to repair.
@@ -198,6 +203,8 @@ export const PbsDatastoreProvider = () =>
          * ⛔ THE `matches` GUARD BEFORE THE PUT IS resource.ts's, AND IT IS WHY ADOPTION IS FREE.
          */
         reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ Again here: an ADOPTED row's diff answer is discarded by Alchemy and reconcile runs.
+          yield* guardDatastoreForms(news);
           const live = yield* readOne(news);
           let upid: string | undefined;
           if (live === undefined) {

package/src/proxmox/pbs-notification-matcher.ts

@@ -69,6 +69,11 @@ const handlers = pveHandlers<PbsNotificationMatcherProps, NotificationMatcherAtt
   attributes: (live, props) => matcherAttributes(live, props.name),
   collection: () => 'config/notifications/matchers',
   createForm: matcherCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pbs:POST /config/notifications/matchers',
+    update: 'pbs:PUT /config/notifications/matchers/{name}',
+  },
   matches: matcherMatches,
   path: (props) => `config/notifications/matchers/${props.name}`,
   updateForm: matcherUpdateForm,

package/src/proxmox/pbs-prune-job.ts

@@ -194,6 +194,8 @@ const handlers = pveHandlers<PruneJobProps, PruneJobAttributes>({
    *   compared unconditionally. A changed `store` is an update, not a replace: PBS accepts `store`
    *   on PUT, so the job is re-pointed in place.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/prune', update: 'pbs:PUT /config/prune/{id}' },
   matches: (attributes, props) =>
     attributes.schedule === props.schedule &&
     attributes.store === props.store &&

package/src/proxmox/pbs-sync-job-form.ts

@@ -209,6 +209,8 @@ export const handlers = pveHandlers<SyncJobProps, SyncJobAttributes>({
    * ⚠️ `id`, `group-filter` AND `sync-direction` ARE OUT. The first is the path, a change to which
    *   is a different object; the other two are argued on their props in pbs-sync-job.ts.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/sync', update: 'pbs:PUT /config/sync/{id}' },
   matches: (attributes, props) =>
     attributes['remove-vanished'] === (props['remove-vanished'] === true) &&
     attributes.store === props.store &&

package/src/proxmox/pbs-verify-job.ts

@@ -193,6 +193,8 @@ const handlers = pveHandlers<PbsVerifyJobProps, PbsVerifyJobAttributes>({
    * ⚠️ `rechecks` IS ABSENT HERE ON PURPOSE. It is a rendering of the two fields on the lines
    *   above; comparing it too would report the same drift twice.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/verify', update: 'pbs:PUT /config/verify/{id}' },
   matches: (attributes, props) =>
     attributes.store === props.store &&
     // ⚠️ `null` IS COMPARED AGAINST `''`, NOT SKIPPED. A parked job is a declaration like any

package/src/proxmox/pool.ts

@@ -71,6 +71,8 @@ const handlers = pveHandlers<PoolProps, PoolAttributes>({
   },
   collection: () => 'pools',
   createForm: poolCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /pools', update: 'pve:PUT /pools/{poolid}' },
   matches: (attributes, props) => attributes.comment === (props.comment ?? ''),
   path: (props) => `pools/${props.poolid}`,
   updateForm: poolUpdateForm,

package/src/proxmox/provision-baseline.test.ts

@@ -84,4 +84,42 @@ describe('provisionBaseline', () => {
   test('refuses one user for both lanes', () => {
     expect(() => provisionBaseline({ readUser: 'hf-provision@pve' })).toThrow(/one user/);
   });
+
+  test('a comment per object, each defaulting to `comment` on its own', () => {
+    // \u2605 THE EXISTING-CLUSTER CASE: the group and the read user already carry their own live
+    //   comments, and only the provision user is new. One shared comment could not say this.
+    const baseline = provisionBaseline({
+      comment: 'shared',
+      groupComment: '',
+      provisionComment: 'mint target: provision (ops)',
+      readComment: 'mint target: read (ops)',
+    });
+    expect(baseline.group.comment).toBe('');
+    expect(baseline.users.map((u) => u.comment)).toEqual([
+      'mint target: provision (ops)',
+      'mint target: read (ops)',
+    ]);
+    // Overriding one leaves the others on `comment`; the generic case is still one string.
+    const one = provisionBaseline({ comment: 'shared', provisionComment: 'only this' });
+    expect([one.group.comment, ...one.users.map((u) => u.comment)]).toEqual([
+      'shared',
+      'only this',
+      'shared',
+    ]);
+    expect(provisionBaseline({ comment: 'shared' }).group.comment).toBe('shared');
+  });
+
+  test('every comment is refused by its own field name', () => {
+    const attempt = () =>
+      provisionBaseline({ groupComment: "it's", provisionComment: 'q{x}', readComment: '$(id)' });
+    expect(attempt).toThrow(/groupComment.*provisionComment.*readComment/);
+  });
+
+  test('readComment goes with its lane: unchecked, and unused, when readUser is null', () => {
+    // ⚠️ Nothing would ever paste it, so refusing it would be a refusal over a field the caller
+    //    is not using. The lane it belongs to is gone.
+    const none = provisionBaseline({ readComment: "would need quoting'", readUser: null });
+    expect(none.users.map((u) => u.lane)).toEqual(['provision']);
+    expect(() => provisionBaseline({ readComment: "would need quoting'" })).toThrow(/readComment/);
+  });
 });