@homeflare/alchemy 0.14.0 → 0.19.0

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,77 @@
+/**
+ * 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';
+import { readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+/**
+ * ⚠️ THE GENERATED TYPES ARE A DIRECTORY NOW, NOT ONE FILE. `generated/pve.ts` became a barrel of
+ *   `export *` lines when codegen/types.ts split the 678 endpoints across files that fit the house
+ *   cap, so reading that path alone would find no endpoint at all — and every absence assertion
+ *   below would pass on an empty list. That is what the first test guards.
+ */
+const dir = fileURLToPath(new URL('./generated/pve/', import.meta.url));
+const schema = (
+  await Promise.all(
+    readdirSync(dir)
+      .sort()
+      .map((name) => Bun.file(join(dir, name)).text()),
+  )
+).join('\n');
+
+/** 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/lxc-lifecycle.ts

@@ -25,6 +25,8 @@
  */
 import * as Effect from 'effect/Effect';
 import { PveError, pve, pveWith } from './client.ts';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
 import { type PveTarget, mint } from './credentials.ts';
 import { createForm } from './lxc-create-form.ts';
 import { type LxcChange, judge } from './lxc-judge.ts';
@@ -43,6 +45,26 @@ export type LxcWhere = { readonly target: PveTarget; readonly node: string; read
 
 export const guestPath = (where: LxcWhere) => `nodes/${where.node}/lxc/${String(where.vmid)}`;
 
+/**
+ * The three vendor endpoints a guest is written through, as the generated tables key them.
+ *
+ * ⛔ DECLARED HERE RATHER THAN ON A SPEC BECAUSE `Proxmox.Lxc` HAS NO SPEC — lxc.ts writes all
+ *   five handlers by hand (a guest reads failures as failures, waits on tasks and grows disks
+ *   through a second endpoint), so it cannot inherit the shared guard from resource.ts. Without
+ *   these three it would be the largest write surface in the package with nothing checking the
+ *   body: `POST /nodes/{node}/lxc` alone carries 26 constrained parameters.
+ * ⚠️ THREE, NOT TWO. `resize` is a separate PVE endpoint with its own schema — `disk` against an
+ *   enum of `rootfs` and `mp0..mp255`, `size` against PVE's `+<n>` / `<n>` pattern — and it is
+ *   the one lxc-volume.ts drives.
+ * ⛔ `{vmid}` AND `{node}` ARE PATH SEGMENTS, NOT FORM KEYS, on the two PUTs. On the POST `vmid`
+ *   IS a form key and is required, which is why `createForm` sends it.
+ */
+const LXC_ENDPOINTS = {
+  create: 'pve:POST /nodes/{node}/lxc' as EndpointKey,
+  resize: 'pve:PUT /nodes/{node}/lxc/{vmid}/resize' as EndpointKey,
+  update: 'pve:PUT /nodes/{node}/lxc/{vmid}/config' as EndpointKey,
+};
+
 /** How long each task may run, in one-second polls. ⚠️ A cap, not an estimate. */
 const CREATE_POLLS = 180;
 const TASK_POLLS = 60;
@@ -132,14 +154,25 @@ const task = (
 
 /** POST the create and wait for the template to unpack. ⛔ Refusals are the caller's to check. */
 export const createGuest = (props: LxcProps) =>
-  task(
-    props,
-    'POST',
-    `nodes/${props.node}/lxc`,
-    `create CT ${String(props.vmid)}`,
-    CREATE_POLLS,
-    createForm(props),
-  );
+  Effect.gen(function* () {
+    const form = createForm(props);
+    /**
+     * ⛔ BEFORE THE POST, AND WITH PRESENCE, BECAUSE THIS IS UNCONDITIONALLY A CREATE. Reached
+     *   only when the guest is absent (lxc.ts's reconcile), so the vendor's required parameters
+     *   really are about to go on the wire — `ostemplate` and `vmid`, both of which
+     *   `createRefusals` already insists on, plus every bound the schema carries and nothing here
+     *   knew: `cores` 1..8192, `memory` ≥ 16, `hostname` as a dns-name, `tags`, `startup`.
+     */
+    yield* guardForm(LXC_ENDPOINTS.create, form, true);
+    return yield* task(
+      props,
+      'POST',
+      `nodes/${props.node}/lxc`,
+      `create CT ${String(props.vmid)}`,
+      CREATE_POLLS,
+      form,
+    );
+  });
 
 /**
  * Apply a judged change: the config PUT first, then each resize.
@@ -158,16 +191,22 @@ export const updateGuest = (props: LxcProps, change: LxcChange, digest: string)
         { ...change.put, ...(digest === '' ? {} : { digest }) },
         change.clear,
       );
+      /** ⚠️ NO PRESENCE: this form is partial by construction — it is `judge`'s answer. */
+      yield* guardForm(LXC_ENDPOINTS.update, form, false);
       yield* pve(props.target, 'provision', 'PUT', `${guestPath(props)}/config`, form);
     }
     for (const grow of change.resize) {
+      const grown = { disk: grow.disk, size: grow.size };
+      // ⛔ WITH PRESENCE: `disk` and `size` are both required and both always sent, so this is a
+      //   value check over PVE's own `+<n>` size pattern and its `rootfs|mp0..mp255` enum.
+      yield* guardForm(LXC_ENDPOINTS.resize, grown, true);
       yield* task(
         props,
         'PUT',
         `${guestPath(props)}/resize`,
         `grow ${grow.disk} of CT ${String(props.vmid)} to ${grow.size}`,
         TASK_POLLS,
-        { disk: grow.disk, size: grow.size },
+        grown,
       );
     }
   });

package/src/proxmox/metric-server-form.ts

@@ -126,3 +126,13 @@ export const update = (props: MetricServerProps) => {
     .map(([option]) => option);
   return withClears(body(props), clear);
 };
+
+/**
+ * The create form: `body` plus the one field only a POST takes.
+ *
+ * ★ EXPORTED SO THE CONSTRAINT PROOF CAN RUN THE REAL FORM. `metric-server.ts` built this inline
+ *   in its spec, which meant the only way to check it against PVE's table was to retype it in a
+ *   test — and a retyped form proves the test, not the provider.
+ * ⚠️ `type` IS REQUIRED ON CREATE AND REFUSED ON UPDATE; `id` is the path, never the body.
+ */
+export const createBody = (props: MetricServerProps) => ({ ...body(props), type: props.type });

package/src/proxmox/metric-server.ts

@@ -31,7 +31,7 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { UNSET, body, update } from './metric-server-form.ts';
+import { UNSET, createBody, update } from './metric-server-form.ts';
 import {
   type MetricServerOtelAttributes,
   type MetricServerOtelProps,
@@ -186,7 +186,16 @@ const handlers = pveHandlers<MetricServerProps, MetricServerAttributes>({
   /** ⛔ THE SAME STRING AS `path`, DELIBERATELY — see the ⛔ in the header. */
   collection: (props) => `cluster/metrics/server/${props.id}`,
   /** ⚠️ `type` IS REQUIRED ON CREATE; `id` IS NOT SENT, because the id is the path. */
-  createForm: (props) => ({ ...body(props), type: props.type }),
+  createForm: createBody,
+  /**
+   * The vendor rules both forms are checked against at plan time — resource-spec.ts.
+   * ⚠️ POST AND PUT ARE THE SAME PATH HERE, and they are still two different tables: only the
+   *   POST marks `type` required, and only the PUT accepts `delete` and `digest`.
+   */
+  endpoint: {
+    create: 'pve:POST /cluster/metrics/server/{id}',
+    update: 'pve:PUT /cluster/metrics/server/{id}',
+  },
   /**
    * ⛔ `id` and `type` are absent: one is the key the object was read by, the other is refused
    *   rather than updated. Everything type-specific is `matchesType`'s, above.

package/src/proxmox/network-apply.ts

@@ -50,6 +50,7 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import { guardNetworkApply } from './apply-endpoints.ts';
 import { pveWith } from './client.ts';
 import { mint } from './credentials.ts';
 import { awaitTask, degradedReason, pendingCount } from './network-apply-read.ts';
@@ -172,6 +173,9 @@ const apply = (props: NetworkApplyProps) =>
      *   not have. The `provision` lease is 300s and non-renewable, which is far longer than a
      *   reload and is the reason no renew path is reached for.
      */
+    // ⛔ BEFORE THE MINT AND THE RELOAD. The apply takes no body, so this is the lookup rather
+    //   than a value check: a vendor that moved this endpoint fails here, not mid-ifreload.
+    yield* guardNetworkApply;
     const credential = yield* mint(props.target, 'provision');
     const upid = yield* pveWith<string>(props.target, credential, 'PUT', `nodes/${node}/network`);
     if (upid === undefined) {

package/src/proxmox/node-network-form.ts

@@ -132,6 +132,25 @@ export const body = (props: NodeNetworkProps): Record<string, string> => ({
   type: props.type,
 });
 
+/**
+ * The create form: `body` plus the name of the interface being created.
+ *
+ * 🔴 `iface` WAS MISSING UNTIL 2026-09-22, AND EVERY CREATE THIS FAMILY HAS EVER PLANNED WOULD
+ *   HAVE 400ed. `POST /nodes/{node}/network` declares `iface` REQUIRED (`pve-iface`, 2..20) and
+ *   `{node}` is its only path parameter, so the name has to travel in the BODY — unlike the PUT,
+ *   where `/network/{iface}` carries it and `updateBody` is right to leave it out. Nothing caught
+ *   it because no NodeNetwork has been created from a declaration yet: C1's three nodes were all
+ *   adopted, which takes the PUT path. Found by wiring this family to the vendor's own table,
+ *   which is exactly the 128-character comment again with a different parameter.
+ *
+ * ⚠️ NOT ADDED TO `body`, BECAUSE THE PUT MUST NOT CARRY IT. `additionalProperties => 0` on the
+ *   update schema makes a second copy of the name a 400 rather than an ignored hint.
+ */
+export const createBody = (props: NodeNetworkProps): Record<string, string> => ({
+  ...body(props),
+  iface: props.iface,
+});
+
 /**
  * The update form: `body` plus the two fields that can only be cleared explicitly.
  *

package/src/proxmox/node-network.ts

@@ -69,7 +69,7 @@ import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import {
-  body,
+  createBody,
   readAttributes,
   same,
   sameComment,
@@ -199,8 +199,14 @@ export const ProxmoxNodeNetwork = Resource<ProxmoxNodeNetwork>('Proxmox.NodeNetw
 const handlers = pveHandlers<NodeNetworkProps, NodeNetworkAttributes>({
   attributes: readAttributes,
   collection: (props) => `nodes/${props.node}/network`,
-  /** ⚠️ No `delete` parameter on a POST — see the ⚠️ on `updateBody`. */
-  createForm: body,
+  /** ⚠️ No `delete` parameter on a POST — see the ⚠️ on `updateBody`. `iface` IS in the create
+   *   body though, and was missing until 2026-09-22 — the 🔴 on `createBody`. */
+  createForm: createBody,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /nodes/{node}/network',
+    update: 'pve:PUT /nodes/{node}/network/{iface}',
+  },
   /**
    * ⛔ `cidr` IS THE ONLY FIELD COMPARED WHEN UNDECLARED, AND THAT ASYMMETRY IS THE POINT. Every
    *   other field here follows storage.ts: undeclared means unmanaged, so it is neither sent nor

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/notification-target-endpoint.ts

@@ -0,0 +1,46 @@
+/**
+ * `Proxmox.NotificationTarget`'s eight vendor endpoints — one create and one update per family.
+ *
+ * ⛔ PVE REGISTERS ONE PATH PER TYPE, NOT A `{type}` PARAMETER, AND THE FOUR SCHEMAS DIFFER IN
+ *   WHAT THEY REQUIRE: gotify wants `server` and `token`, smtp `server` and `from-address`,
+ *   webhook `url` and `method`, sendmail nothing but its name. One key for all four would enforce
+ *   gotify's rules on a sendmail target and let three families through unchecked, which is why
+ *   `PveSpec['endpoint']` admits a function of props.
+ *
+ * ⛔ THE STRINGS ARE LITERALS AND MUST STAY LITERALS. `codegen/constraints.ts` finds the endpoints
+ *   to table by SCANNING THIS PACKAGE'S TEXT, so `` `pve:POST …/${props.type}` `` would be tabled
+ *   by nothing and `constraintsFor` would throw on the first deploy that reached it.
+ *
+ * ⚠️ GOTIFY'S CREATE CAN NEVER SATISFY ITS OWN TABLE, AND THAT IS THE TRUTH RATHER THAN A BUG
+ *   HERE. `token` is required by PVE and is a write-only secret, so it is not a prop — props are
+ *   persisted to the state store unencrypted (the third ⛔ in notification-target.ts). A gotify
+ *   target is created out of band and then DECLARED, which is an adopt followed by updates; the
+ *   shared guard only demands the create form's required parameters when a create is really about
+ *   to happen (`resource-guard.ts`), so declaring an existing gotify target still plans clean and
+ *   asking to CREATE one is refused at plan time with `token: required` instead of by a 400.
+ */
+import type { NotificationTargetProps } from './notification-target.ts';
+import type { EndpointPair } from './resource-spec.ts';
+
+const ENDPOINTS: Readonly<Record<NotificationTargetProps['type'], EndpointPair>> = {
+  gotify: {
+    create: 'pve:POST /cluster/notifications/endpoints/gotify',
+    update: 'pve:PUT /cluster/notifications/endpoints/gotify/{name}',
+  },
+  sendmail: {
+    create: 'pve:POST /cluster/notifications/endpoints/sendmail',
+    update: 'pve:PUT /cluster/notifications/endpoints/sendmail/{name}',
+  },
+  smtp: {
+    create: 'pve:POST /cluster/notifications/endpoints/smtp',
+    update: 'pve:PUT /cluster/notifications/endpoints/smtp/{name}',
+  },
+  webhook: {
+    create: 'pve:POST /cluster/notifications/endpoints/webhook',
+    update: 'pve:PUT /cluster/notifications/endpoints/webhook/{name}',
+  },
+};
+
+/** The pair this declaration writes. ⚠️ `type` is identity here, so it never changes under a row. */
+export const targetEndpoint = (props: NotificationTargetProps): EndpointPair =>
+  ENDPOINTS[props.type];

package/src/proxmox/notification-target-form.ts

@@ -102,3 +102,14 @@ export const shape = (props: NotificationTargetProps): Record<string, string> =>
   ...set('url', props.url),
   ...set('username', props.username),
 });
+
+/**
+ * The create form: `shape` plus the name PVE takes in the body exactly once.
+ *
+ * ★ EXPORTED SO THE CONSTRAINT PROOF CAN RUN THE REAL FORM rather than a retyped copy of it.
+ * ⛔ `name` IS CREATE-ONLY: PVE takes it in the body on the POST and in the path forever after.
+ */
+export const createShape = (props: NotificationTargetProps): Record<string, string> => ({
+  ...shape(props),
+  name: props.name,
+});

package/src/proxmox/notification-target.ts

@@ -53,7 +53,8 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { addressList, headerList, portOf, shape } from './notification-target-form.ts';
+import { targetEndpoint } from './notification-target-endpoint.ts';
+import { addressList, createShape, headerList, portOf, shape } from './notification-target-form.ts';
 import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
 import { text } from './values.ts';
 
@@ -180,7 +181,9 @@ const handlers = pveHandlers<NotificationTargetProps, NotificationTargetAttribut
   }),
   collection: (props) => `cluster/notifications/endpoints/${props.type}`,
   /** ⛔ `name` is create-only: PVE takes it in the body once, and in the path forever after. */
-  createForm: (props) => ({ ...shape(props), name: props.name }),
+  createForm: createShape,
+  /** ⚠️ A function, because the type picks the endpoint — see `targetEndpoint`. */
+  endpoint: targetEndpoint,
   /**
    * Each line reads "not declared, or equal"; `disable` is the one field with no undeclared case.
    *

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-notification-target-endpoint.ts

@@ -0,0 +1,45 @@
+/**
+ * `Pbs.NotificationTarget`'s six vendor endpoints — one create and one update per family.
+ *
+ * 🔴 THIS FAMILY WAS THE ONE THE 2026-09-22 SWEEP NEARLY MISSED, and it carries the very
+ *   parameter the incident was about: `comment` is `maxLength: 128` with a no-control-characters
+ *   pattern on all three PBS creates, exactly as it is on `POST /config/verify`. A 129-character
+ *   comment on a notification target would have failed the same way, half a deploy in, on the
+ *   family whose whole purpose is to make failures visible.
+ *
+ * ⛔ PBS REGISTERS ONE PATH PER TYPE, NOT A `{type}` PARAMETER, and the three schemas differ:
+ *   smtp requires `server` and `from-address`, webhook `url` and `method`, sendmail nothing but
+ *   its name. One key would enforce one family's rules on all three.
+ * ⛔ THE STRINGS MUST STAY LITERALS. `codegen/constraints.ts` finds the endpoints to table by
+ *   SCANNING THIS PACKAGE'S TEXT, so a key built from `props.type` would be tabled by nothing.
+ *
+ * ⚠️ NO GOTIFY KEY, BECAUSE THIS RESOURCE HAS NO GOTIFY TYPE. `PbsNotificationTargetType` is
+ *   sendmail | smtp | webhook; PBS 4.2 does publish a gotify endpoint, and nothing here writes to
+ *   it. ⛔ `scripts/proxmox-ownership-pbs.ts` says otherwise — it claims all four families
+ *   through the shared `notificationEndpoints` helper — so `docs/api-coverage.md` credits this
+ *   resource with twelve write endpoints where it really makes nine. That is an overclaim in the
+ *   hand-written ownership ledger, recorded here rather than fixed in passing: correcting it
+ *   regenerates a report built from a DIFFERENT (older, 9.2.4) schema manifest, which is its own
+ *   change with its own diff.
+ */
+import type { PbsNotificationTargetProps } from './pbs-notification-target.ts';
+import type { EndpointPair } from './resource-spec.ts';
+
+const ENDPOINTS: Readonly<Record<PbsNotificationTargetProps['type'], EndpointPair>> = {
+  sendmail: {
+    create: 'pbs:POST /config/notifications/endpoints/sendmail',
+    update: 'pbs:PUT /config/notifications/endpoints/sendmail/{name}',
+  },
+  smtp: {
+    create: 'pbs:POST /config/notifications/endpoints/smtp',
+    update: 'pbs:PUT /config/notifications/endpoints/smtp/{name}',
+  },
+  webhook: {
+    create: 'pbs:POST /config/notifications/endpoints/webhook',
+    update: 'pbs:PUT /config/notifications/endpoints/webhook/{name}',
+  },
+};
+
+/** The pair this declaration writes. ⚠️ `type` is identity here — changing it is a replace. */
+export const pbsTargetEndpoint = (props: PbsNotificationTargetProps): EndpointPair =>
+  ENDPOINTS[props.type];

package/src/proxmox/pbs-notification-target-lifecycle.ts

@@ -15,6 +15,8 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
 import { pve } from './client.ts';
+import { guardForm } from './constraint-guard.ts';
+import { pbsTargetEndpoint } from './pbs-notification-target-endpoint.ts';
 import type {
   PbsNotificationTargetAttributes,
   PbsNotificationTargetProps,
@@ -142,25 +144,25 @@ export const handlers = {
         const carry = { header: true, sealed: true } as const;
         yield* requireValues(news, groups, carry);
         const collection = `config/notifications/endpoints/${news.type}`;
-        yield* pve(
-          news.target,
-          'provision',
-          'POST',
-          collection,
-          targetForm(news, groups, carry, 'create'),
-        );
+        const form = targetForm(news, groups, carry, 'create');
+        /**
+         * ⛔ WITH PRESENCE, BECAUSE THIS BRANCH IS UNCONDITIONALLY THE CREATE. PBS marks `name` on
+         *   every family and `server`/`from-address` on smtp, `url`/`method` on webhook — and it
+         *   is the same `comment: maxLength 128` that failed `POST /config/verify`.
+         * ⚠️ THE FORM CARRIES SECRETS ON THIS PATH. `violations` reads values and builds only the
+         *   parameter NAME into its message (constraints.ts), so a refusal never quotes one.
+         */
+        yield* guardForm(pbsTargetEndpoint(news).create, form, true);
+        yield* pve(news.target, 'provision', 'POST', collection, form);
         sealed = seal(groups.sealed.values);
       } else {
         const carry = toCarry(live, news, groups, sealed);
         if (carry !== undefined) {
           yield* requireValues(news, groups, carry);
-          yield* pve(
-            news.target,
-            'provision',
-            'PUT',
-            path(news),
-            targetForm(news, groups, carry, 'update'),
-          );
+          const form = targetForm(news, groups, carry, 'update');
+          /** ⚠️ NO PRESENCE: an update form is partial by design — it carries what `toCarry` said. */
+          yield* guardForm(pbsTargetEndpoint(news).update, form, false);
+          yield* pve(news.target, 'provision', 'PUT', path(news), form);
           if (carry.sealed) sealed = seal(groups.sealed.values);
         }
       }

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 &&