@homeflare/alchemy 0.14.0 → 0.19.0

package/src/proxmox/constraints-host-forms.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The host families' REAL create forms — interfaces and ZFS pools — and PBS's notification
+ * targets, which carry the very rule the 2026-09-22 incident was about.
+ *
+ * ★ SPLIT OUT OF constraints-node-forms.test.ts FOR THE 250-LINE CAP. That file is the Ceph and
+ *   guest families; this one is what a host itself is made of, plus the PBS half.
+ * ⛔ SAME PROOF, SAME REASON: a table that refuses a declaration the vendor would have ACCEPTED is
+ *   worse than the 400 it replaces, so each family's own builder goes through
+ *   `formViolations(key, form, true)` and an empty result is required.
+ */
+import { describe, expect, test } from 'bun:test';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import type { PbsTarget, PveTarget } from './credentials.ts';
+import { createBody as ifaceCreateForm } from './node-network-form.ts';
+import { resolveGroups, targetForm } from './pbs-notification-target-form.ts';
+import { createForm as zfsCreateForm } from './zfs-pool-write.ts';
+
+const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', scheme: 'pve' };
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+
+const onCreate = (key: string, form: Record<string, string | readonly string[]>) =>
+  formViolations(key, form, true);
+
+describe('the host families plan clean against their own creates', () => {
+  /**
+   * 🔴 THE BUG THIS PROOF FOUND. `createForm` was `body`, which never sent `iface` — and PVE marks
+   *   it REQUIRED on the POST while `{node}` is the only path parameter. Every NodeNetwork create
+   *   this repository could have made would have 400ed; nothing caught it because C1's three nodes
+   *   were all adopted, which takes the PUT path. See the 🔴 on `createBody`.
+   */
+  test('an interface create carries iface, which PVE requires in the body', () => {
+    const form = ifaceCreateForm({
+      autostart: true,
+      cidr: '192.0.2.10/24',
+      iface: 'vmbr1.42',
+      node: 'n2',
+      target: TARGET,
+      type: 'vlan',
+      'vlan-raw-device': 'vmbr1',
+    });
+    expect(form['iface']).toBe('vmbr1.42');
+    expect(onCreate('pve:POST /nodes/{node}/network', form)).toEqual([]);
+  });
+
+  test('iface and type are the required pair, and iface is 2..20 characters', () => {
+    const table = constraintsFor('pve:POST /nodes/{node}/network');
+    expect(
+      Object.entries(table)
+        .filter(([, rule]) => rule.required)
+        .map(([name]) => name),
+    ).toEqual(['iface', 'type']);
+    expect(table['iface']).toMatchObject({ maxLength: 20, minLength: 2 });
+  });
+
+  /** ⚠️ The PUT takes `iface` in the path, so the update form is right to leave it out. */
+  test('the update form, without iface, passes the PUT table', () => {
+    expect(constraintsFor('pve:PUT /nodes/{node}/network/{iface}')['iface']).toBeUndefined();
+  });
+
+  test('a ZFS pool create passes, and its three required parameters are all sent', () => {
+    const form = zfsCreateForm({
+      ashift: 12,
+      compression: 'lz4',
+      devices: ['/dev/nvme0n1', '/dev/nvme1n1'],
+      name: 'rpool-data',
+      node: 'n2',
+      raidlevel: 'mirror',
+      target: TARGET,
+    });
+    expect(onCreate('pve:POST /nodes/{node}/disks/zfs', form)).toEqual([]);
+    for (const name of ['devices', 'name', 'raidlevel']) expect(form[name]).toBeDefined();
+  });
+
+  test('an ashift above PVE own maximum of 16 is refused', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/disks/zfs',
+        zfsCreateForm({
+          ashift: 17,
+          devices: ['/dev/nvme0n1'],
+          name: 'rpool-data',
+          node: 'n2',
+          raidlevel: 'single',
+          target: TARGET,
+        }),
+      ),
+    ).toEqual(['ashift: at most 16']);
+  });
+});
+
+/**
+ * 🔴 `Pbs.NotificationTarget` CARRIES THE INCIDENT'S OWN PARAMETER. `comment` is `maxLength: 128`
+ *   with a no-control-characters pattern on all three PBS creates — the same rule, on the same
+ *   product, that failed `POST /config/verify` half a deploy in. This family was missing from the
+ *   list the sweep started from; it is wired with the rest.
+ */
+describe('Pbs.NotificationTarget plans clean, and its comment is the 128 again', () => {
+  const declared = {
+    comment: 'PBS failure mail',
+    mailto: ['someone@example.invalid'],
+    name: 'mail-to-root',
+    target: PBS,
+    type: 'sendmail',
+  } as const;
+  const carry = { header: true, sealed: true } as const;
+
+  test('a sendmail target has no violations', () => {
+    const form = targetForm(declared, resolveGroups(declared, {}), carry, 'create');
+    expect(form['name']).toBe('mail-to-root');
+    expect(onCreate('pbs:POST /config/notifications/endpoints/sendmail', form)).toEqual([]);
+  });
+
+  test('a 129-character comment is refused, exactly as on POST /config/verify', () => {
+    const over = { ...declared, comment: 'c'.repeat(129) };
+    const form = targetForm(over, resolveGroups(over, {}), carry, 'create');
+    expect(onCreate('pbs:POST /config/notifications/endpoints/sendmail', form)).toEqual([
+      'comment: at most 128 characters',
+    ]);
+  });
+
+  test('a webhook target sends the url and method PBS requires', () => {
+    const hook = {
+      method: 'post',
+      name: 'hook-house',
+      target: PBS,
+      type: 'webhook',
+      url: 'https://hooks.example.invalid/pbs',
+    } as const;
+    const form = targetForm(hook, resolveGroups(hook, {}), carry, 'create');
+    expect(onCreate('pbs:POST /config/notifications/endpoints/webhook', form)).toEqual([]);
+  });
+});

package/src/proxmox/constraints-live.test.ts

@@ -0,0 +1,155 @@
+/**
+ * The whole live PBS estate, through its own create and update tables, expecting NOTHING.
+ *
+ * ⛔ THIS IS THE RISK THE CONSTRAINT GUARD CARRIES, NOT THE ONE IT FIXES. A table that refuses a
+ *   declaration the vendor would have ACCEPTED blocks a deploy that was always legal, and the
+ *   operator cannot tell that from a genuine violation. `guardForms` runs in `diff` AND in
+ *   `reconcile`, and `reconcile` runs for an ADOPTED row — so every object the estate has already
+ *   adopted faces these tables on its next plan. A false positive here is a broken plan for ten
+ *   live objects, including a datastore holding the offsite copies.
+ *
+ * ★ THE VALUES ARE THE LIVE ONES, read from homeflare-proxmox's own inventory fixture
+ *   (`tests/fixtures/pbs-live-2026-09-21.json`, captured read-only 2026-09-21): the ten objects
+ *   PBS actually holds, with their real ids, stores, schedules and retention numbers.
+ *   ⚠️ EXCEPT THE COMMENT TEXT, WHICH IS REPLACED BY A STRING OF THE SAME CHARACTER LENGTH. This
+ *     package is public and the live comments name hosts and runbook paths. Length and character
+ *     class are the whole of what a `maxLength`/`pattern` rule sees, so the substitution costs the
+ *     test nothing — and the lengths (106, 116, 88, 107, 120) are the live ones, asserted below.
+ */
+import { describe, expect, test } from 'bun:test';
+import { formViolations } from './constraint-guard.ts';
+import type { PbsTarget } from './credentials.ts';
+import { createForm as datastoreCreateForm, updateForm } from './pbs-datastore-form.ts';
+import { createBody as pruneCreateBody, updateBody as pruneUpdate } from './pbs-prune-job-form.ts';
+import { createBody as syncCreateBody, updateBody as syncUpdate } from './pbs-sync-job-form.ts';
+import type { PbsVerifyJobProps } from './pbs-verify-job.ts';
+import { shape as verifyShape } from './pbs-verify-job-form.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const filler = (length: number) => 'c'.repeat(length);
+
+/** What `pbs-verify-job.ts` builds inline for a create: the update shape plus the required `id`. */
+const verifyCreate = (props: PbsVerifyJobProps) => ({ ...verifyShape(props), id: props.id });
+
+describe('every live PBS object passes its own create table', () => {
+  test('the three prune jobs, including the parked one', () => {
+    for (const job of [
+      { id: 'prune-cluster-all', keep: 3, schedule: 'Sat 06:00', store: 'cluster' },
+      { comment: filler(88), id: 'prune-datacenter-all', keep: 3, store: 'datacenter' },
+      { id: 'prune-r2-offsite-all', keep: 3, schedule: 'Sat 07:30', store: 'r2-offsite' },
+    ]) {
+      const form = pruneCreateBody({
+        ...job,
+        'keep-daily': 7,
+        'keep-last': job.keep,
+        'keep-monthly': 3,
+        'keep-weekly': 4,
+        'max-depth': 7,
+        schedule: job.schedule ?? 'Sat 08:00',
+        target: PBS,
+      });
+      expect([job.id, formViolations('pbs:POST /config/prune', form, true)]).toEqual([job.id, []]);
+    }
+  });
+
+  /**
+   * ⚠️ `sync-all-to-dc` HAS NO `schedule` AND `v-datacenter` HAS NEITHER `schedule` NOR `ns`. Both
+   *   are parked, and both are legal: PBS marks `schedule` optional on sync and verify jobs. If
+   *   the presence check ever read `required` from the wrong place, these two rows are what fails.
+   */
+  test('the two sync jobs, one of them parked with no schedule', () => {
+    const parked = syncCreateBody({
+      comment: filler(107),
+      id: 'sync-all-to-dc',
+      'max-depth': 7,
+      'remote-store': 'cluster',
+      'remove-vanished': false,
+      store: 'datacenter',
+      target: PBS,
+      'verified-only': true,
+    });
+    expect(formViolations('pbs:POST /config/sync', parked, true)).toEqual([]);
+    const live = syncCreateBody({
+      id: 'sync-all-to-r2',
+      owner: 'root@pam',
+      'remote-store': 'cluster',
+      schedule: '08:30',
+      store: 'r2-offsite',
+      target: PBS,
+    });
+    expect(formViolations('pbs:POST /config/sync', live, true)).toEqual([]);
+  });
+
+  /**
+   * ⚠️ `{...shape(props), id}` IS THE CREATE FORM, SPELLED OUT. `pbs-verify-job.ts` builds it
+   *   inline and exports only `shape`, which is the UPDATE form and carries no `id` — and `id` is
+   *   one of the two parameters PBS marks required on this endpoint. Calling `shape` here and
+   *   expecting no violations reported `id: required`, which is the presence check working, not a
+   *   defect. If that inline `id` is ever dropped, this test is what says so.
+   * ⚠️ `ns: ''` IS A LIVE VALUE AND `shape` DROPS IT rather than sending the empty string, so the
+   *   table never sees it. The vendor's pattern would accept it either way — it ends `)?$`.
+   */
+  test('the two verify jobs, one with an empty namespace', () => {
+    const running = verifyCreate({
+      id: 'v-b7d7ff81-17d6',
+      'ignore-verified': true,
+      ns: '',
+      'outdated-after': 30,
+      schedule: '06:30',
+      store: 'cluster',
+      target: PBS,
+    });
+    expect(formViolations('pbs:POST /config/verify', running, true)).toEqual([]);
+    const parked = verifyCreate({
+      comment: filler(120),
+      id: 'v-datacenter',
+      'ignore-verified': true,
+      'outdated-after': 30,
+      schedule: null,
+      store: 'datacenter',
+      target: PBS,
+    });
+    expect(formViolations('pbs:POST /config/verify', parked, true)).toEqual([]);
+  });
+
+  test('the three datastores, on create and on update', () => {
+    for (const store of [
+      { comment: filler(106), name: 'cluster', path: '/mnt/datastore/cluster' },
+      { comment: filler(116), name: 'datacenter', path: '/mnt/cluster_pbs' },
+      { comment: filler(106), name: 'r2-offsite', path: '/mnt/datastore/r2-cache' },
+    ]) {
+      const props = { ...store, target: PBS };
+      expect([
+        store.name,
+        formViolations('pbs:POST /config/datastore', datastoreCreateForm(props), true),
+      ]).toEqual([store.name, []]);
+      // ⚠️ THE UPDATE FORM IS PARTIAL BY DESIGN, so presence is off — value rules still apply.
+      expect([
+        store.name,
+        formViolations('pbs:PUT /config/datastore/{name}', updateForm(props), false),
+      ]).toEqual([store.name, []]);
+    }
+  });
+
+  test('the prune and sync update forms, which send only what changed', () => {
+    const prune = pruneUpdate({
+      id: 'prune-cluster-all',
+      'keep-daily': 7,
+      'keep-last': 3,
+      'max-depth': 7,
+      schedule: 'Sat 06:00',
+      store: 'cluster',
+      target: PBS,
+    });
+    expect(formViolations('pbs:PUT /config/prune/{id}', prune, false)).toEqual([]);
+    const sync = syncUpdate({
+      id: 'sync-all-to-r2',
+      owner: 'root@pam',
+      'remote-store': 'cluster',
+      schedule: '08:30',
+      store: 'r2-offsite',
+      target: PBS,
+    });
+    expect(formViolations('pbs:PUT /config/sync/{id}', sync, false)).toEqual([]);
+  });
+});

package/src/proxmox/constraints-node-forms.test.ts

@@ -0,0 +1,188 @@
+/**
+ * The node-scoped families' REAL create forms, against the vendor's own tables — and PBS's
+ * notification targets, which carry the very rule the 2026-09-22 incident was about.
+ *
+ * ⛔ SAME PROOF AS constraints-forms.test.ts, AND THE SAME REASON FOR IT: a table that refuses a
+ *   declaration the vendor would have ACCEPTED is worse than the 400 it replaces, because the
+ *   operator cannot tell it from a genuine violation. Each family's own builder, through
+ *   `formViolations(key, form, true)`, empty result required.
+ */
+import { describe, expect, test } from 'bun:test';
+import { createForm as daemonCreateForm } from './ceph-daemon-form.ts';
+import { createForm as cephFsCreateForm } from './ceph-fs-wire.ts';
+import { createOsdForm } from './ceph-osd-write.ts';
+import { createBody as cephPoolCreateForm } from './ceph-pool-form.ts';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import type { PveTarget } from './credentials.ts';
+import { TARGET as LXC_TARGET, pasted } from './lxc-harness.ts';
+import { createForm as lxcCreateForm } from './lxc-create-form.ts';
+import { createForm as vmCreateForm } from './qemu.ts';
+
+const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', scheme: 'pve' };
+
+const onCreate = (key: string, form: Record<string, string | readonly string[]>) =>
+  formViolations(key, form, true);
+
+describe('the Ceph families plan clean against their own creates', () => {
+  /** ⚠️ Three kinds, three endpoints, three parameter schemas — see `DAEMON_ENDPOINTS`. */
+  test('a mon, an mds and a mgr each pass their own table', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/mon/{monid}',
+        daemonCreateForm({ kind: 'mon', 'mon-address': '192.0.2.11', node: 'n2', target: TARGET }),
+      ),
+    ).toEqual([]);
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/mds/{name}',
+        daemonCreateForm({ hotstandby: true, kind: 'mds', node: 'n2', target: TARGET }),
+      ),
+    ).toEqual([]);
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/mgr/{id}',
+        daemonCreateForm({ kind: 'mgr', node: 'n2', target: TARGET }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('a CephFS create passes, and pg_num carries the vendor own 8..32768', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/fs/{name}',
+        cephFsCreateForm({ 'add-storage': true, name: 'cephfs-c1', node: 'n2', target: TARGET }),
+      ),
+    ).toEqual([]);
+    expect(constraintsFor('pve:POST /nodes/{node}/ceph/fs/{name}')['pg_num']).toMatchObject({
+      maximum: 32_768,
+      minimum: 8,
+    });
+  });
+
+  test('an OSD create passes, and dev is the parameter PVE requires', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/osd',
+        createOsdForm({ node: 'n2', osdid: 4, target: TARGET }, '/dev/nvme1n1'),
+      ),
+    ).toEqual([]);
+    expect(constraintsFor('pve:POST /nodes/{node}/ceph/osd')['dev']?.required).toBe(true);
+  });
+
+  /** The estate's own pools: `cephtb4` and the two `cephfs-tb4_*` halves, size 3 / min_size 2. */
+  test('the live CephPool declarations have no violations', () => {
+    for (const name of ['cephtb4', 'cephfs-tb4_data', 'cephfs-tb4_metadata']) {
+      expect(
+        onCreate(
+          'pve:POST /nodes/{node}/ceph/pool',
+          cephPoolCreateForm({
+            crush_rule: 'replicated_rule',
+            min_size: 2,
+            name,
+            node: 'n2',
+            pg_autoscale_mode: 'on',
+            size: 3,
+            target: TARGET,
+          }),
+        ),
+        name,
+      ).toEqual([]);
+    }
+  });
+
+  test('a pool asking for size 8 is refused: PVE own maximum is 7', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/ceph/pool',
+        cephPoolCreateForm({ name: 'toobig', node: 'n2', size: 8, target: TARGET }),
+      ),
+    ).toEqual(['size: at most 7']);
+  });
+});
+
+describe('the guest families plan clean against their own creates', () => {
+  /**
+   * ⚠️ THE HARNESS DECLARATION, PLUS THE ONE CREATE-ONLY KEY IT CANNOT CARRY. `pasted()` is the
+   *   production-SHAPED config with placeholder values (lxc-harness.ts); `ostemplate` is absent
+   *   from it because a live config never reports one, and PVE requires it on create.
+   */
+  test('a full LXC declaration with its template has no violations', () => {
+    const form = lxcCreateForm(
+      pasted({ ostemplate: 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst' }),
+    );
+    expect(form['vmid']).toBe('900');
+    expect(onCreate('pve:POST /nodes/{node}/lxc', form)).toEqual([]);
+  });
+
+  /** ⛔ `ostemplate` AND `vmid` ARE THE TWO PVE MARKS REQUIRED, and `{node}` is the path. */
+  test('ostemplate and vmid are the required pair, and node is not in the table', () => {
+    const table = constraintsFor('pve:POST /nodes/{node}/lxc');
+    expect(
+      Object.entries(table)
+        .filter(([, rule]) => rule.required)
+        .map(([name]) => name),
+    ).toEqual(['ostemplate', 'vmid']);
+    expect(table['node']).toBeUndefined();
+  });
+
+  /** ⚠️ The same harness props, against the SECOND endpoint this family writes. */
+  test('a resize form passes its own table', () => {
+    expect(
+      formViolations(
+        'pve:PUT /nodes/{node}/lxc/{vmid}/resize',
+        { disk: 'rootfs', size: '+8G' },
+        true,
+      ),
+    ).toEqual([]);
+    expect(LXC_TARGET.scheme).toBe('pve');
+  });
+
+  /**
+   * ⛔ THE ONE VALUE THIS PACKAGE ECHOES BACK TO PVE UNCHANGED, AND IT HAS A BOUND. `updateGuest`
+   *   carries the `digest` of the config it was judged against so PVE can refuse a write over an
+   *   edit that landed meanwhile — and PVE's own schema caps that parameter at 40 characters,
+   *   which is exactly a sha1_hex. A version that started returning a longer digest would refuse
+   *   its own echo server-side; the point of the assertion is that 40 is not refused HERE.
+   */
+  test('a config PUT carrying a 40-character digest is not refused', () => {
+    expect(
+      formViolations(
+        'pve:PUT /nodes/{node}/lxc/{vmid}/config',
+        { digest: 'a'.repeat(40), memory: '8192' },
+        false,
+      ),
+    ).toEqual([]);
+    expect(constraintsFor('pve:PUT /nodes/{node}/lxc/{vmid}/config')['digest']).toMatchObject({
+      maxLength: 40,
+    });
+  });
+
+  test('a VM create passes, and vmid carries PVE own 100..999999999', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/qemu',
+        vmCreateForm({
+          cores: 2,
+          memory: 2048,
+          name: 'vm-example',
+          node: 'n2',
+          target: TARGET,
+          vmid: 150,
+        }),
+      ),
+    ).toEqual([]);
+    expect(constraintsFor('pve:POST /nodes/{node}/qemu')['vmid']).toMatchObject({
+      maximum: 999_999_999,
+      minimum: 100,
+    });
+  });
+
+  test('a vmid below PVE own minimum is refused rather than sent', () => {
+    expect(
+      onCreate(
+        'pve:POST /nodes/{node}/qemu',
+        vmCreateForm({ node: 'n2', target: TARGET, vmid: 99 }),
+      ),
+    ).toEqual(['vmid: at least 100']);
+  });
+});

package/src/proxmox/constraints-required.test.ts

@@ -0,0 +1,172 @@
+/**
+ * What the create check will actually DEMAND, committed — plus the families PR 102 wired without
+ * a create-form proof of their own.
+ *
+ * ⛔ THE OBJECTION THIS ANSWERS. Since 2026-09-22 the create form's required parameters are
+ *   demanded only when a create is really about to happen (resource-guard.ts), which is correct —
+ *   refusing a plan over a request that will never be made is a false positive by construction —
+ *   but it moves some coverage out of the runtime and into here. So the required set is written
+ *   down: a schema refresh that adds a required parameter to an endpoint this package writes to
+ *   is EXACTLY the change that would start refusing creates, and it fails here, with a diff a
+ *   reviewer can read, instead of on the first deploy that creates one.
+ *
+ * ⚠️ THE LIST IS THE VENDOR'S, NOT OURS. Nothing here asserts that a rule is sensible, only that
+ *   it is what the two products publish today (pve-manager 9.2.11, proxmox-backup-server 4.2.6-1).
+ */
+import { describe, expect, test } from 'bun:test';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import type { PveTarget } from './credentials.ts';
+import { body as aliasBody } from './firewall-alias-form.ts';
+import { PROXMOX_CONSTRAINTS } from './generated/constraints/index.ts';
+import { body as haRuleBody } from './ha-rule-form.ts';
+import { matcherCreateForm } from './notification-matcher-form.ts';
+import { poolCreateForm } from './pool.ts';
+import { createBody as replicationCreateBody } from './replication-job-form.ts';
+
+const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', scheme: 'pve' };
+
+const onCreate = (key: string, form: Record<string, string | readonly string[]>) =>
+  formViolations(key, form, true);
+
+const requiredOf = (key: string) =>
+  Object.entries(constraintsFor(key))
+    .filter(([, rule]) => rule.required === true)
+    .map(([name]) => name)
+    .sort();
+
+describe('every create this package makes, and what the vendor requires of it', () => {
+  /**
+   * ⚠️ AN ENDPOINT WITH NO REQUIRED PARAMETER IS NOT A MISTAKE. `POST /cluster/backup` genuinely
+   *   marks nothing required; recording the empty set is the same information as recording a full
+   *   one. ⛔ `POST /cluster/ha/rules` LOOKED LIKE ONE OF THOSE until PR 113 taught the reader to
+   *   follow PVE's `allOf`/`oneOf`, which is exactly the class of change this census exists to
+   *   make visible in a diff.
+   */
+  test('the required set of every tabled POST is exactly this', () => {
+    const creates = Object.keys(PROXMOX_CONSTRAINTS)
+      .filter((key) => key.includes(':POST '))
+      .sort();
+    const census = Object.fromEntries(
+      creates.map((key) => [key, requiredOf(key)] as const).filter(([, names]) => names.length > 0),
+    );
+    expect(census).toEqual({
+      'pbs:POST /config/datastore': ['name', 'path'],
+      'pbs:POST /config/notifications/endpoints/sendmail': ['name'],
+      'pbs:POST /config/notifications/endpoints/smtp': ['from-address', 'name', 'server'],
+      'pbs:POST /config/notifications/endpoints/webhook': ['method', 'name', 'url'],
+      'pbs:POST /config/notifications/matchers': ['name'],
+      'pbs:POST /config/prune': ['id', 'schedule', 'store'],
+      'pbs:POST /config/sync': ['id', 'remote-store', 'store'],
+      'pbs:POST /config/verify': ['id', 'store'],
+      'pve:POST /access/groups': ['groupid'],
+      'pve:POST /access/roles': ['roleid'],
+      'pve:POST /access/users': ['userid'],
+      'pve:POST /cluster/firewall/aliases': ['cidr', 'name'],
+      'pve:POST /cluster/ha/resources': ['sid'],
+      'pve:POST /cluster/ha/rules': ['resources', 'rule'],
+      'pve:POST /cluster/metrics/server/{id}': ['port', 'server', 'type'],
+      'pve:POST /cluster/notifications/endpoints/gotify': ['name', 'server', 'token'],
+      'pve:POST /cluster/notifications/endpoints/sendmail': ['name'],
+      'pve:POST /cluster/notifications/endpoints/smtp': ['from-address', 'name', 'server'],
+      'pve:POST /cluster/notifications/endpoints/webhook': ['method', 'name', 'url'],
+      'pve:POST /cluster/notifications/matchers': ['name'],
+      'pve:POST /cluster/replication': ['id', 'target', 'type'],
+      'pve:POST /cluster/sdn/vnets': ['vnet', 'zone'],
+      'pve:POST /cluster/sdn/vnets/{vnet}/subnets': ['subnet', 'type'],
+      'pve:POST /cluster/sdn/zones': ['type', 'zone'],
+      'pve:POST /nodes/{node}/ceph/osd': ['dev'],
+      'pve:POST /nodes/{node}/ceph/pool': ['name'],
+      'pve:POST /nodes/{node}/disks/zfs': ['devices', 'name', 'raidlevel'],
+      'pve:POST /nodes/{node}/lxc': ['ostemplate', 'vmid'],
+      'pve:POST /nodes/{node}/network': ['iface', 'type'],
+      'pve:POST /nodes/{node}/qemu': ['vmid'],
+      'pve:POST /pools': ['poolid'],
+      'pve:POST /storage': ['storage', 'type'],
+    });
+  });
+
+  /**
+   * ⛔ `PUT /access/acl` IS A CREATE HERE. PVE registers no POST on the ACL collection, so acl.ts
+   *   names the same PUT for both — which means its required pair IS demanded on the create path.
+   */
+  test('the ACL PUT requires a path and a role list, and both are its own props', () => {
+    expect(requiredOf('pve:PUT /access/acl')).toEqual(['path', 'roles']);
+  });
+
+  /** ⚠️ No POST/PUT this package writes requires a parameter it sends only as a path segment. */
+  test('no required parameter is also a path segment of its own endpoint', () => {
+    for (const key of Object.keys(PROXMOX_CONSTRAINTS)) {
+      const segments = new Set([...key.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]));
+      for (const name of requiredOf(key)) expect(segments.has(name), `${key} ${name}`).toBe(false);
+    }
+  });
+});
+
+/**
+ * ★ THE FAMILIES PR 102 WIRED, WITH THE PROOF IT DID NOT WRITE. Five of them build their create
+ *   form from a builder that is already exported, so covering them costs nothing but this file.
+ *   The rest build theirs inline in a spec literal and are covered by the required-set census
+ *   above instead — recorded honestly rather than claimed.
+ */
+describe('the families wired before this sweep pass their own create tables', () => {
+  test('Proxmox.Pool', () => {
+    expect(
+      onCreate(
+        'pve:POST /pools',
+        poolCreateForm({ comment: 'house', poolid: 'house', target: TARGET }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('Proxmox.FirewallAlias', () => {
+    const form = {
+      ...aliasBody({ cidr: '192.0.2.0/24', name: 'lab', target: TARGET }),
+      name: 'lab',
+    };
+    expect(onCreate('pve:POST /cluster/firewall/aliases', form)).toEqual([]);
+  });
+
+  test('Proxmox.HaRule', () => {
+    const form = {
+      ...haRuleBody({
+        affinity: 'positive',
+        nodes: ['n2', 'n3'],
+        resources: ['ct:101', 'ct:102'],
+        rule: 'keep-together',
+        strict: true,
+        target: TARGET,
+        type: 'node-affinity',
+      }),
+      rule: 'keep-together',
+    };
+    expect(onCreate('pve:POST /cluster/ha/rules', form)).toEqual([]);
+  });
+
+  test('Proxmox.ReplicationJob', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/replication',
+        replicationCreateBody({
+          guest: 150,
+          jobnum: 0,
+          schedule: '*/15',
+          target: TARGET,
+          targetNode: 'n3',
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  /** ⚠️ One builder, two products: both matcher families share `matcherCreateForm`. */
+  test('Proxmox.NotificationMatcher and Pbs.NotificationMatcher', () => {
+    const form = matcherCreateForm({
+      comment: 'route everything to mail-to-root',
+      'match-severity': ['warning', 'error'],
+      mode: 'all',
+      name: 'default-matcher',
+      targets: ['mail-to-root'],
+    });
+    expect(onCreate('pve:POST /cluster/notifications/matchers', form)).toEqual([]);
+    expect(onCreate('pbs:POST /config/notifications/matchers', form)).toEqual([]);
+  });
+});