@homeflare/alchemy 0.15.0 → 0.19.1

package/src/proxmox/apply-endpoints.ts

@@ -0,0 +1,34 @@
+/**
+ * The two applies, and the vendor endpoints they publish through.
+ *
+ * ★ AN ACTION ENDPOINT IS STILL WIRED, EVEN THOUGH ITS TABLE IS EMPTY, AND THE REASON IS THE
+ *   GENERATOR RATHER THAN THE VALIDATOR. `PUT /nodes/{node}/network` and `PUT /cluster/sdn` take
+ *   no body at all — there is nothing for a length or a range to be wrong about — but
+ *   `codegen/constraints.ts` RESOLVES every key named in this package against the vendor's own
+ *   schema and STOPS when one is absent. So the key buys the thing these two families most need:
+ *   a PVE that moves, renames or withdraws the apply fails `bun run check` instead of failing an
+ *   `ifreload -a` on three nodes at once.
+ * ⚠️ AND THE LOOKUP IS NOT FREE EITHER. `constraintsFor` throws when a key has no table, so a
+ *   checkout whose generated tables were never refreshed refuses the apply with the command to
+ *   run rather than quietly doing nothing — the same defect `constraint-guard.ts` names.
+ *
+ * ⛔ NEITHER OF THESE IS A CREATE, AND NEITHER FAMILY HAS A `PveSpec`. Both write their own five
+ *   handlers (an apply is not an object — see the ⛔ in each file), so they reach the shared check
+ *   through `guardForm` by name, exactly as `pbs-datastore-endpoint.ts` does.
+ */
+import type * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/** ⚠️ `{node}` is a path segment, so this really does take no form keys at all. */
+export const NETWORK_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /nodes/{node}/network';
+
+/**
+ * ⛔ CLUSTER-WIDE. One PUT publishes every staged zone, vnet and subnet on every node; there is no
+ *   per-object apply and no pre-apply veto. `sdn-apply.ts` is the whole argument.
+ */
+export const SDN_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /cluster/sdn';
+
+export const guardNetworkApply: Effect.Effect<void> = guardForm(NETWORK_APPLY_ENDPOINT, {}, true);
+
+export const guardSdnApply: Effect.Effect<void> = guardForm(SDN_APPLY_ENDPOINT, {}, true);

package/src/proxmox/ceph-daemon-form.ts

@@ -28,8 +28,30 @@
  *   the task in the PVE UI before concluding the create failed.
  *
  */
-import type { CephDaemonProps } from './ceph-daemon.ts';
-import { flag } from './values.ts';
+import type { CephDaemonAttributes, CephDaemonKind, CephDaemonProps } from './ceph-daemon.ts';
+import type { EndpointPair } from './resource-spec.ts';
+import { bool, flag, num, text } from './values.ts';
+
+/**
+ * The vendor endpoint each kind is created at, as the generated tables key it.
+ *
+ * ⛔ ONE PER KIND, NOT A `{type}` PATH. PVE registers `mds`, `mgr` and `mon` as three separate
+ *   nodes with three separate parameter schemas — `hotstandby` belongs to the first and
+ *   `mon-address` to the third — so a single key would enforce one kind's rules on all three.
+ *   That is why `PveSpec['endpoint']` admits a function of props at all.
+ * ⛔ THE STRINGS MUST STAY LITERALS. `codegen/constraints.ts` finds the endpoints to table by
+ *   SCANNING THIS PACKAGE'S TEXT, so a key assembled from `props.kind` would be tabled by
+ *   nothing and `constraintsFor` would throw on the first deploy that reached it.
+ * ⚠️ THE PARAMETER NAMES DIFFER AND ARE THE VENDOR'S OWN — `{name}`, `{id}`, `{monid}`. The
+ *   generator resolves each against the schema, so a tidied-up spelling stops the build.
+ * ⚠️ NO `update` ON ANY OF THEM: none of the three has a PUT, which is why the spec declares no
+ *   `updateForm` either.
+ */
+export const DAEMON_ENDPOINTS: Readonly<Record<CephDaemonKind, EndpointPair>> = {
+  mds: { create: 'pve:POST /nodes/{node}/ceph/mds/{name}' },
+  mgr: { create: 'pve:POST /nodes/{node}/ceph/mgr/{id}' },
+  mon: { create: 'pve:POST /nodes/{node}/ceph/mon/{monid}' },
+};
 
 /**
  * PVE defaults the id to the nodename for all three kinds, and that default is resolved HERE
@@ -82,3 +104,35 @@ export const findRow = (live: unknown, props: CephDaemonProps) =>
   (Array.isArray(live) ? live : [])
     .filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null)
     .find((row) => row['name'] === daemonId(props));
+
+/**
+ * One live row as attributes, or `undefined` — "no daemon of this kind carries this name".
+ *
+ * ★ HERE RATHER THAN IN ceph-daemon.ts FOR THE REASON THAT FILE'S SIBLING EXISTS AT ALL: the
+ *   250-line cap, and a seam that is real. It reads the row `findRow` picked out of an answer its
+ *   caller already fetched, three lines above, so the lookup and the mapping now live together
+ *   instead of a function call apart.
+ *
+ * ⚠️ `undefined` WHEN NO ROW CARRIES THIS NAME: that is how the factory learns to create.
+ */
+export const daemonAttributes = (
+  live: Record<string, unknown>,
+  props: CephDaemonProps,
+): CephDaemonAttributes | undefined => {
+  const row = findRow(live, props);
+  if (row === undefined) return undefined;
+  return {
+    addr: text(row['addr']),
+    fsName: text(row['fs_name']),
+    host: text(row['host']),
+    kind: props.kind,
+    name: daemonId(props),
+    node: props.node,
+    quorum: bool(row['quorum']),
+    rank: num(row['rank'], -1),
+    service: bool(row['service']),
+    standbyReplay: bool(row['standby_replay']),
+    state: text(row['state']),
+    version: text(row['ceph_version_short']),
+  };
+};

package/src/proxmox/ceph-daemon.ts

@@ -49,10 +49,15 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { collectionPath, createForm, daemonId, daemonPath, findRow } from './ceph-daemon-form.ts';
+import {
+  DAEMON_ENDPOINTS,
+  collectionPath,
+  createForm,
+  daemonAttributes,
+  daemonPath,
+} from './ceph-daemon-form.ts';
 import { pve } from './client.ts';
 import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, num, text } from './values.ts';
 
 /**
  * Which Ceph daemon this is. The discriminant picks the collection, the create parameters and
@@ -176,28 +181,12 @@ export const ProxmoxCephDaemon = Resource<ProxmoxCephDaemon>('Proxmox.CephDaemon
 });
 
 const handlers = pveHandlers<CephDaemonProps, CephDaemonAttributes>({
-  /** ⚠️ `undefined` when no row carries this name: that is how the factory learns to create. */
-  attributes: (live, props) => {
-    const row = findRow(live, props);
-    if (row === undefined) return undefined;
-    return {
-      addr: text(row['addr']),
-      fsName: text(row['fs_name']),
-      host: text(row['host']),
-      kind: props.kind,
-      name: daemonId(props),
-      node: props.node,
-      quorum: bool(row['quorum']),
-      rank: num(row['rank'], -1),
-      service: bool(row['service']),
-      standbyReplay: bool(row['standby_replay']),
-      state: text(row['state']),
-      version: text(row['ceph_version_short']),
-    };
-  },
+  attributes: daemonAttributes,
   /** ⛔ The ID path, not the collection — POST is registered on `{id}`, exactly like a metric server. */
   collection: daemonPath,
   createForm,
+  /** ⚠️ A function, because the kind picks the endpoint — see `DAEMON_ENDPOINTS`. */
+  endpoint: (props: CephDaemonProps) => DAEMON_ENDPOINTS[props.kind],
   /**
    * ⛔ TOTAL, AND THIS IS THE REASON THE FILE EXISTS RATHER THAN A SHORTCUT PAST WRITING IT. Every
    *   field a declaration can carry is CREATE-ONLY and unreadable — `mon-address` comes back as a

package/src/proxmox/ceph-flag.ts

@@ -181,6 +181,7 @@ const handlers = pveHandlers<CephFlagProps, CephFlagAttributes>({
    *   only body `cluster/ceph/flags` has ever documented. Nothing sends it today.
    */
   createForm: (props) => ({ [props.flag]: flag(props.value) ?? '0' }),
+  endpoint: { update: 'pve:PUT /cluster/ceph/flags/{flag}' }, // ⛔ No create: see above.
   /**
    * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
    *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`

package/src/proxmox/ceph-fs.ts

@@ -148,6 +148,7 @@ const ops = pveOperations<CephFsProps, CephFsAttributes>({
   /** ⚠️ The `{name}` path — longer than `path()`, deliberately. See the second ⛔ in the header. */
   collection: objectPath,
   createForm,
+  endpoint: { create: 'pve:POST /nodes/{node}/ceph/fs/{name}' }, // ⚠️ POSTed on the object.
   /**
    * ⛔ NOTHING IS COMPARED, AND THAT IS THE MOST DELIBERATE LINE IN THIS FILE. A CephFS has no
    *   readable, writable field: the index returns only the name and the pools behind it, and every

package/src/proxmox/ceph-osd-write.ts

@@ -15,9 +15,34 @@ import * as Effect from 'effect/Effect';
 import { readOsd } from './ceph-osd-tree.ts';
 import type { CephOsdProps } from './ceph-osd.ts';
 import { pve } from './client.ts';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/**
+ * The vendor rules the create form is checked against at plan time.
+ *
+ * ⛔ DECLARED HERE RATHER THAN ON A SPEC BECAUSE THIS FAMILY HAS NO SPEC — `ceph-osd.ts` writes
+ *   all five handlers by hand (the ⛔ there says why), so it cannot inherit the shared guard and
+ *   would otherwise be the one family that writes to Ceph with nothing checking the body.
+ * ⚠️ `dev` IS REQUIRED AND THE REFUSAL BELOW ALREADY COVERS IT, with a message about a missing
+ *   replica that is far more useful than `dev: required`. The table is still worth checking: it
+ *   also carries `db_dev_size` ≥ 1, `wal_dev_size` ≥ 0.5 and `osds-per-device` ≥ 1, and nothing
+ *   else in this package knows those numbers.
+ * ⚠️ THERE IS NO UPDATE KEY: PVE registers no PUT under `ceph/osd`, and an OSD is not editable.
+ */
+export const OSD_CREATE_ENDPOINT: EndpointKey = 'pve:POST /nodes/{node}/ceph/osd';
 
 const describe = (props: CephOsdProps) => `osd.${String(props.osdid)} on ${props.node}`;
 
+/**
+ * The create body. ★ Exported so the constraint proof can run the REAL form.
+ * ⚠️ `dev` is `string | undefined` on the props and non-optional here: `createOsd` refuses first.
+ */
+export const createOsdForm = (props: CephOsdProps, dev: string): Record<string, string> => ({
+  dev,
+  ...(props.device_class === undefined ? {} : { 'crush-device-class': props.device_class }),
+});
+
 export const createOsd = Effect.fn(function* (news: CephOsdProps) {
   if (news.dev === undefined) {
     return yield* Effect.die(
@@ -30,10 +55,11 @@ export const createOsd = Effect.fn(function* (news: CephOsdProps) {
       ),
     );
   }
-  yield* pve(news.target, 'provision', 'POST', `nodes/${news.node}/ceph/osd`, {
-    dev: news.dev,
-    ...(news.device_class === undefined ? {} : { 'crush-device-class': news.device_class }),
-  });
+  const form = createOsdForm(news, news.dev);
+  // ⛔ BEFORE THE POST, BECAUSE THE POST ZAPS A BLOCK DEVICE. A vendor rule broken here is worth
+  //   refusing at plan rather than discovering from a 400 after `ceph-volume` has run.
+  yield* guardForm(OSD_CREATE_ENDPOINT, form, true);
+  yield* pve(news.target, 'provision', 'POST', `nodes/${news.node}/ceph/osd`, form);
   const created = yield* readOsd(news);
   if (created === undefined) {
     return yield* Effect.die(

package/src/proxmox/ceph-pool.ts

@@ -101,6 +101,11 @@ const spec: PveSpec<CephPoolProps, CephPoolAttributes> = {
   },
   collection,
   createForm: createBody,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /nodes/{node}/ceph/pool',
+    update: 'pve:PUT /nodes/{node}/ceph/pool/{name}',
+  },
   /**
    * ⛔ DECLARING WHAT IS LIVE MUST PLAN noop, AND EVERY OMISSION HERE IS WHY. Out, each with its
    *   reason on the prop it belongs to: `pg_num` (the autoscaler rewrites it), `application` (the
@@ -152,6 +157,10 @@ export const ProxmoxCephPoolProvider = () =>
           const live = yield* ops.read(news);
           let upid: string | undefined;
           if (live === undefined) {
+            // ⛔ THE GUARD `ops.reconcile` WOULD HAVE RUN, RESTORED. This handler replaces it
+            //   wholesale, so without these two calls an ADOPTED pool — whose diff answer Alchemy
+            //   discards — would reach the cluster with nothing having checked its body.
+            yield* ops.guardCreate(news, true);
             yield* confirmAbsent(news, spec.collection(news), object(news));
             upid = yield* pve<string>(
               news.target,
@@ -170,6 +179,7 @@ export const ProxmoxCephPoolProvider = () =>
              */
             const form = formToSend(spec.matches, live, news, updateBody(news));
             if (form !== undefined) {
+              yield* ops.guardUpdate(news);
               upid = yield* pve<string>(news.target, 'provision', 'PUT', object(news), form);
             }
           }

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

@@ -0,0 +1,165 @@
+/**
+ * The two rule kinds the first generation dropped, and the false positive neither may cause.
+ *
+ * 🔴 ADVERSARIAL REVIEW OF THE 2026-09-22 CONSTRAINT GUARD, SAME DAY. The guard caught the
+ *   128-character comment, and two whole rule kinds were passing through it unchecked:
+ *   - PVE applies `m/^$pattern$/` (MEASURED in JSONSchema.pm:1636) and the table carried the
+ *     UNANCHORED body, so `RegExp.test` searched: a firewall alias named `ok name!` matched on
+ *     `ok`, passed plan, and was rejected by PVE with the 400 this feature exists to prevent.
+ *   - An array parameter states its rules on `items`, and the emitter read only the parameter,
+ *     so `target`, `associated-key` and `secondary-controllers` were tabled with no rule at all —
+ *     while `violations` was already checking every element against that empty rule.
+ *
+ * ★ EVERY CASE HERE IS A MUTANT: it passes on the fixed generator and fails on the one that
+ *   shipped. The last describe is the opposite risk and the more dangerous one — a rule that
+ *   refuses a declaration the vendor ACCEPTS breaks a stack that was always legal.
+ */
+import { describe, expect, test } from 'bun:test';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import { matcherCreateForm, matcherUpdateForm } from './notification-matcher-form.ts';
+
+const ALIAS = 'pve:POST /cluster/firewall/aliases';
+const PBS_MATCHER = 'pbs:POST /config/notifications/matchers';
+const PBS_MATCHER_PUT = 'pbs:PUT /config/notifications/matchers/{name}';
+const PVE_MATCHER = 'pve:POST /cluster/notifications/matchers';
+const BACKUP = 'pve:POST /cluster/backup';
+
+describe('a PVE pattern is anchored the way PVE anchors it', () => {
+  /**
+   * ⛔ THE MUTANT. `[A-Za-z][A-Za-z0-9\-\_]+` unanchored matches the `ok` inside `ok name!`, so
+   *   `RegExp.test` said yes and PVE said 400. Deleting the `^`/`$` in param-rules.ts brings this
+   *   failure back exactly.
+   */
+  test('a name PVE rejects is refused, not matched on its prefix', () => {
+    expect(formViolations(ALIAS, { cidr: '10.0.0.0/24', name: 'ok-name' }, false)).toEqual([]);
+    expect(formViolations(ALIAS, { cidr: '10.0.0.0/24', name: 'ok name!' }, false)).toEqual([
+      'name: must match [A-Za-z][A-Za-z0-9\\-\\_]+',
+    ]);
+  });
+
+  /** The violation quotes the VENDOR's spelling, so an operator can search PVE's own docs for it. */
+  test('the message is the vendor pattern, never the anchored translation', () => {
+    const rule = constraintsFor(ALIAS)['name'];
+    expect(rule?.pattern).toBe('^[A-Za-z][A-Za-z0-9\\-\\_]+\\n?$');
+    expect(rule?.patternSource).toBe('[A-Za-z][A-Za-z0-9\\-\\_]+');
+  });
+
+  /**
+   * ⚠️ PERL'S `$`, NOT JAVASCRIPT'S. `m/^x$/` matches `"x\n"`; a bare `$` in JavaScript does not.
+   *   Without the `\n?` this line would be a refusal of a value PVE accepts — the false positive
+   *   that is worse than the server 400 it replaces.
+   */
+  test('a trailing newline is accepted, because Perl accepts it', () => {
+    expect(formViolations(BACKUP, { starttime: '02:00\n' }, false)).toEqual([]);
+    expect(formViolations(BACKUP, { starttime: '02:00' }, false)).toEqual([]);
+    expect(formViolations(BACKUP, { starttime: 'at 02:00' }, false)).toEqual([
+      'starttime: must match \\d{1,2}:\\d{1,2}',
+    ]);
+  });
+
+  /** ⚠️ PBS patterns already carry their own `^…$`; anchoring them again would invent a rule. */
+  test('a PBS pattern is left exactly as the vendor wrote it', () => {
+    const rule = constraintsFor(PBS_MATCHER)['name'];
+    expect(rule?.pattern).toBe('^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$');
+    expect(rule?.patternSource).toStartWith('/^');
+  });
+});
+
+describe("an array's rules come from its items, and reach every element", () => {
+  const fields = (targets: readonly string[]) => ({ name: 'default-matcher', targets });
+
+  test('PBS bounds each target name, and the table says the rule is per element', () => {
+    const rule = constraintsFor(PBS_MATCHER)['target'];
+    expect(rule).toMatchObject({ each: true, maxLength: 32, minLength: 2, type: 'array' });
+  });
+
+  test('one over-long element is refused although the parameter is a list', () => {
+    expect(formViolations(PBS_MATCHER, matcherCreateForm(fields(['mail-to-root'])), false)).toEqual(
+      [],
+    );
+    expect(formViolations(PBS_MATCHER, matcherCreateForm(fields(['m'.repeat(33)])), false)).toEqual(
+      ['target: at most 32 characters'],
+    );
+    // ⚠️ AND THE SHORT ONE TOO: `minLength` on an element is the bound a joined string would hide.
+    expect(formViolations(PBS_MATCHER, matcherCreateForm(fields(['m'])), false)).toEqual([
+      'target: at least 2 characters',
+    ]);
+  });
+
+  /**
+   * ⛔ `delete` IS AN ARRAY OF AN ENUM ON PBS, and `matcherUpdateForm` fills it from its own
+   *   `Deletable` union. This is the one place the two could drift: a member this package clears
+   *   that PBS does not accept is a 400 the vendor's own enum can refuse at plan time.
+   */
+  test("the update form's cleared fields are all members of PBS's own delete enum", () => {
+    const form = matcherUpdateForm({ comment: '', name: 'default-matcher', targets: [] });
+    expect(form.delete).toEqual([
+      'match-calendar',
+      'match-field',
+      'match-severity',
+      'target',
+      'comment',
+    ]);
+    expect(formViolations(PBS_MATCHER_PUT, form, false)).toEqual([]);
+  });
+
+  /** PVE spells the same list with `format: pve-configid`, which is a NAME and stays unchecked. */
+  test('a PVE element rule with only a format is recorded and not enforced', () => {
+    expect(constraintsFor(PVE_MATCHER)['target']).toMatchObject({
+      each: true,
+      format: 'pve-configid',
+    });
+    expect(formViolations(PVE_MATCHER, matcherCreateForm(fields(['m'.repeat(80)])), false)).toEqual(
+      [],
+    );
+  });
+});
+
+/**
+ * 🔴 `Proxmox.HaRule`'s TABLE WAS EMPTY AND NOTHING SAID SO. PVE spells `POST /cluster/ha/rules`
+ *   as `allOf: [{properties: {rule}}, {oneOf: [node-affinity, resource-affinity]}]`, the reader
+ *   asked for `parameters.properties`, got `undefined`, and emitted `{}` — which is exactly what
+ *   an endpoint with no rules emits. A wired family's guard checked nothing, silently.
+ */
+describe('a parameter schema wrapped in allOf/oneOf is read, not skipped', () => {
+  const CREATE = 'pve:POST /cluster/ha/rules';
+
+  test('the table is no longer empty, and carries the limits both branches agree on', () => {
+    const table = constraintsFor(CREATE);
+    expect(Object.keys(table).sort()).toEqual(['affinity', 'comment', 'resources', 'rule']);
+    expect(table['comment']).toMatchObject({ maxLength: 4096 });
+    expect(table['affinity']).toMatchObject({ enum: ['positive', 'negative'] });
+  });
+
+  /**
+   * ⛔ `nodes` AND `strict` EXIST ONLY ON THE node-affinity BRANCH, so enforcing them would refuse
+   *   a resource-affinity rule for breaking a rule PVE never applies to it. `oneOf` intersects.
+   */
+  test('a rule only one branch states is NOT enforced', () => {
+    expect(constraintsFor(CREATE)['nodes']).toBeUndefined();
+    expect(constraintsFor(CREATE)['strict']).toBeUndefined();
+  });
+
+  /**
+   * ⚠️ `affinity` IS REQUIRED ON resource-affinity AND OPTIONAL ON node-affinity, so presence is
+   *   not enforced. Dropping a disagreeing `optional` would have read as REQUIRED — absence means
+   *   required in this schema — and refused every legal node-affinity rule.
+   */
+  test('presence is required only where every branch requires it', () => {
+    const table = constraintsFor(CREATE);
+    expect(table['rule']?.required).toBe(true);
+    expect(table['resources']?.required).toBe(true);
+    expect(table['affinity']?.required).toBeUndefined();
+    expect(formViolations(CREATE, { affinity: 'positive', resources: 'vm:100' }, true)).toEqual([
+      'rule: required',
+    ]);
+  });
+
+  test('the live shape of a node-affinity rule has no violations', () => {
+    const form = { affinity: 'positive', nodes: 'n1:2,n2:1', resources: 'vm:100', rule: 'pin-100' };
+    expect(formViolations(CREATE, form, true)).toEqual([]);
+    expect(formViolations(CREATE, { ...form, comment: 'c'.repeat(4097) }, true)).toEqual([
+      'comment: at most 4096 characters',
+    ]);
+  });
+});

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

@@ -0,0 +1,228 @@
+/**
+ * The cluster-scoped families' REAL create forms, against the vendor's own tables.
+ *
+ * ⛔ THE RISK THIS FEATURE CARRIES IS 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. So every family wired on 2026-09-22 gets the same proof: build
+ *   the form the provider really builds, run it through `formViolations(key, form, true)` — the
+ *   create check, presence included — and require an empty result.
+ *
+ * ⛔ THE FORM, NEVER A RETYPED COPY OF IT. Four families built their create form inline in a spec
+ *   literal; each one gained an exported builder that the provider now uses, so this file and the
+ *   provider cannot disagree. A test that retypes the form proves the test.
+ *
+ * ★ THE NODE-SCOPED HALF IS IN constraints-node-forms.test.ts — split for the 250-line cap, on the
+ *   same seam the generated tables are split on (`/cluster` and `/access` here, `/nodes/{node}`
+ *   there).
+ */
+import { describe, expect, test } from 'bun:test';
+import { shape as apiTokenForm } from './api-token-form.ts';
+import { NETWORK_APPLY_ENDPOINT, SDN_APPLY_ENDPOINT } from './apply-endpoints.ts';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import type { PveTarget } from './credentials.ts';
+import { createBody as metricCreateForm } from './metric-server-form.ts';
+import { createShape as targetCreateForm } from './notification-target-form.ts';
+import { createForm as subnetCreateForm } from './sdn-subnet-form.ts';
+
+const TARGET: PveTarget = { members: ['pve.test:8006'], mount: 'pve-test', scheme: 'pve' };
+
+/** `formViolations` with presence — the create check, exactly as `resource-guard.ts` runs it. */
+const onCreate = (key: string, form: Record<string, string | readonly string[]>) =>
+  formViolations(key, form, true);
+
+describe('Proxmox.ApiToken plans clean against POST /access/users/{userid}/token/{tokenid}', () => {
+  /** ⚠️ `expire: 0` is "never", and PVE's `minimum: 0` accepts it — the bound the table carries. */
+  test('the estate-shaped token declaration has no violations', () => {
+    expect(
+      onCreate(
+        'pve:POST /access/users/{userid}/token/{tokenid}',
+        apiTokenForm({
+          comment: 'Declared by Alchemy',
+          expire: 0,
+          privsep: false,
+          target: TARGET,
+          tokenid: 'apply',
+          userid: 'iac@pve',
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  /** ⛔ `{userid}` AND `{tokenid}` ARE PATH SEGMENTS. A table that kept them would refuse every
+   *   create for a "missing" parameter that was never missing (codegen/emit.ts). */
+  test('neither path parameter is in the table', () => {
+    const table = constraintsFor('pve:POST /access/users/{userid}/token/{tokenid}');
+    expect(table['userid']).toBeUndefined();
+    expect(table['tokenid']).toBeUndefined();
+  });
+});
+
+describe('Proxmox.MetricServer plans clean against POST /cluster/metrics/server/{id}', () => {
+  /**
+   * The estate's own row, SHAPED: InfluxDB v2 over https with an api-path-prefix, an
+   * organization and a bucket, every value a placeholder.
+   *
+   * ⛔ SHAPE ONLY, FOR THE REASON lxc-harness.ts GIVES. `src` ships in the npm tarball and this
+   *   repository is public, so a real metrics host, cluster name or organization here would be
+   *   estate topology published forever in the git history. The proof is about which KEYS the
+   *   create form sends and which bounds they face; the strings carry none of it.
+   */
+  const declared = {
+    'api-path-prefix': '/cluster-a/',
+    bucket: 'pve',
+    disable: false,
+    id: 'metrics-example',
+    influxdbproto: 'https',
+    'max-body-size': 10_000_000,
+    organization: 'example',
+    port: 443,
+    server: 'metrics.example.invalid',
+    target: TARGET,
+    type: 'influxdb',
+    'verify-certificate': true,
+  } as const;
+
+  test('the live declaration has no violations', () => {
+    expect(onCreate('pve:POST /cluster/metrics/server/{id}', metricCreateForm(declared))).toEqual(
+      [],
+    );
+  });
+
+  /** ⛔ PVE MARKS THREE PARAMETERS REQUIRED AND THE CREATE FORM SENDS ALL THREE. `id` is the path. */
+  test('port, server and type are required and all three are sent', () => {
+    const table = constraintsFor('pve:POST /cluster/metrics/server/{id}');
+    expect(
+      Object.entries(table)
+        .filter(([, rule]) => rule.required)
+        .map(([name]) => name),
+    ).toEqual(['port', 'server', 'type']);
+    expect(Object.keys(metricCreateForm(declared))).toContain('type');
+  });
+
+  test('a port past PVE own maximum is refused rather than sent', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/metrics/server/{id}',
+        metricCreateForm({ ...declared, port: 70_000 }),
+      ),
+    ).toEqual(['port: at most 65536']);
+  });
+});
+
+describe('Proxmox.NotificationTarget plans clean per family', () => {
+  /** The shipped `mail-to-root`, edited — the shape every estate has. sendmail needs only a name. */
+  test('the live sendmail declaration has no violations', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/notifications/endpoints/sendmail',
+        targetCreateForm({
+          comment: "Send mails to root@pam's email address",
+          disable: false,
+          mailto: ['someone@example.invalid'],
+          'mailto-user': ['root@pam'],
+          name: 'mail-to-root',
+          target: TARGET,
+          type: 'sendmail',
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  test('an smtp target that declares its server and sender has no violations', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/notifications/endpoints/smtp',
+        targetCreateForm({
+          'from-address': 'pve@example.invalid',
+          mode: 'tls',
+          name: 'smtp-relay',
+          port: 465,
+          server: 'smtp.example.invalid',
+          target: TARGET,
+          type: 'smtp',
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  /**
+   * ⛔ THE ONE FAMILY THAT CANNOT SATISFY ITS OWN CREATE, PROVEN RATHER THAN ASSERTED IN PROSE.
+   *   PVE requires gotify's `token` and it is a write-only secret, so it is not a prop — props are
+   *   persisted to the state store unencrypted. `notification-target.ts` has said so in a comment
+   *   since the family was written; this is the comment made executable.
+   * ★ AND IT IS WHY THE CREATE CHECK IS CONDITIONAL. `resource-guard.ts` demands presence only
+   *   when a create is really about to happen, so the documented workflow — create it out of band
+   *   with its secret, then declare it — still plans clean. Asking to CREATE one fails at plan
+   *   with the vendor's own word instead of a 400 half a deploy in.
+   */
+  test('a gotify create is refused for the token it may never carry', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/notifications/endpoints/gotify',
+        targetCreateForm({
+          name: 'gotify-house',
+          server: 'https://gotify.example.invalid',
+          target: TARGET,
+          type: 'gotify',
+        }),
+      ),
+    ).toEqual(['token: required']);
+  });
+});
+
+describe('Proxmox.SdnSubnet plans clean against POST /cluster/sdn/vnets/{vnet}/subnets', () => {
+  test('a declared subnet has no violations', () => {
+    expect(
+      onCreate(
+        'pve:POST /cluster/sdn/vnets/{vnet}/subnets',
+        subnetCreateForm({
+          cidr: '192.0.2.0/24',
+          gateway: '192.0.2.1',
+          target: TARGET,
+          vnet: 'vnet0',
+          zone: 'zone0',
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  /** ⚠️ `subnet` and `type` are the two PVE marks required, and `createForm` sends both. */
+  test('subnet and type are required and both are sent', () => {
+    const table = constraintsFor('pve:POST /cluster/sdn/vnets/{vnet}/subnets');
+    expect(table['subnet']?.required).toBe(true);
+    expect(table['type']).toMatchObject({ enum: ['subnet'], required: true });
+  });
+});
+
+/**
+ * ★ AN ACTION ENDPOINT IS WIRED TOO, AND THE TABLE IS SUPPOSED TO BE EMPTY. Neither apply takes a
+ *   body, so there is nothing for a length or a range to be wrong about — the key exists so that
+ *   `codegen/constraints.ts` resolves it against the vendor schema at generation time. A PVE that
+ *   moves or withdraws either one fails `bun run check` rather than an `ifreload -a` on three
+ *   nodes at once. ⛔ An empty table is NOT the same as a missing one: a missing one throws.
+ */
+describe('the two applies are wired although they carry no form', () => {
+  test('both tables exist and both are empty', () => {
+    expect(constraintsFor(NETWORK_APPLY_ENDPOINT)).toEqual({});
+    expect(constraintsFor(SDN_APPLY_ENDPOINT)).toEqual({});
+  });
+
+  test('a key the generator never tabled is a defect that names the command', () => {
+    expect(() => constraintsFor('pve:PUT /cluster/sdn/nope')).toThrow('bun codegen/constraints.ts');
+  });
+});
+
+/**
+ * ⛔ `Proxmox.CephFlag` HAS NO CREATE KEY, AND THAT IS THE VENDOR'S DOING. PVE registers only PUT
+ *   on `/cluster/ceph/flags/{flag}`; `POST /cluster/ceph/flags` does not exist, which is why
+ *   ceph-flag.ts documents its create branch as unreachable. Naming that POST would stop the
+ *   generator — correctly — so the family declares the update alone.
+ */
+describe('Proxmox.CephFlag is wired through its PUT alone', () => {
+  test('the update form passes, and value is the one rule PVE publishes', () => {
+    expect(formViolations('pve:PUT /cluster/ceph/flags/{flag}', { value: '1' }, false)).toEqual([]);
+    expect(constraintsFor('pve:PUT /cluster/ceph/flags/{flag}')).toEqual({
+      value: { required: true, type: 'boolean' },
+    });
+  });
+});