@homeflare/alchemy 0.15.0 → 0.19.0

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,220 @@
+/**
+ * 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: InfluxDB v2 over https, in a section named `macmini`. */
+  const declared = {
+    'api-path-prefix': '/tb4/',
+    bucket: 'pve',
+    disable: false,
+    id: 'macmini',
+    influxdbproto: 'https',
+    'max-body-size': 10_000_000,
+    organization: 'homeflare',
+    port: 443,
+    server: 'metrics.homeflare.dev',
+    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 estate's only target: the shipped `mail-to-root`, edited. sendmail requires 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' },
+    });
+  });
+});

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([]);
+  });
+});