@homeflare/alchemy 0.15.0 → 0.19.1

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

@@ -14,8 +14,24 @@
  *   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';
 
-const schema = await Bun.file(new URL('./generated/pve.ts', import.meta.url)).text();
+/**
+ * ⚠️ 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(

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-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-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/qemu.ts

@@ -54,6 +54,9 @@ export interface ProxmoxVm extends Resource<
 
 export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm');
 
+/** ★ Exported so the constraint proof can run the REAL create form, not a retyped copy of it. */
+export const createForm = (props: VmProps) => ({ ...shape(props), vmid: String(props.vmid) });
+
 const shape = (props: VmProps) => ({
   cores: String(props.cores ?? 1),
   memory: String(props.memory ?? 512),
@@ -74,7 +77,12 @@ const handlers = pveHandlers<VmProps, VmAttributes>({
     vmid: props.vmid,
   }),
   collection: (props) => `nodes/${props.node}/qemu`,
-  createForm: (props) => ({ ...shape(props), vmid: String(props.vmid) }),
+  createForm,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /nodes/{node}/qemu',
+    update: 'pve:PUT /nodes/{node}/qemu/{vmid}/config',
+  },
   matches: (attributes, props) =>
     attributes.name === (props.name ?? `vm${String(props.vmid)}`) &&
     attributes.memory === (props.memory ?? 512) &&

package/src/proxmox/resource-guard.ts

@@ -0,0 +1,61 @@
+/**
+ * A spec's two forms, checked against the vendor's own tables before either goes on the wire.
+ *
+ * ★ A FILE OF ITS OWN BECAUSE resource.ts REACHED THE 250-LINE CAP, and the seam is the same one
+ *   resource-spec.ts cuts on: that file says what a PVE object DECLARES, resource.ts says how one
+ *   is read and written, and this one says what makes a declaration legal. `constraint-guard.ts`
+ *   is the layer below — it owns the lookup and the refusal; this owns which form to check when.
+ */
+import * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { PveSpec, WithApiTarget } from './resource-spec.ts';
+
+export const specGuards = <Props extends WithApiTarget, Attributes>(
+  spec: PveSpec<Props, Attributes>,
+) => {
+  /** ⚠️ A function for the two families whose endpoint is a prop — see `PveSpec['endpoint']`. */
+  const endpointsOf = (props: Props) =>
+    typeof spec.endpoint === 'function' ? spec.endpoint(props) : spec.endpoint;
+
+  /**
+   * The create form against its own endpoint's table.
+   *
+   * ⛔ `presence` MEANS "A CREATE IS REALLY ABOUT TO HAPPEN", NOT "THIS IS THE CREATE FORM", AND
+   *   THE DIFFERENCE IS A WHOLE FAMILY. `Proxmox.NotificationTarget` cannot send gotify's `token`
+   *   or smtp's `password` — they are write-only secrets and props are persisted to the state
+   *   store unencrypted (notification-target.ts's third ⛔) — so PVE's `token: required` is
+   *   permanently unsatisfiable here. The documented way to run one is to create it out of band
+   *   with its secret and then DECLARE it, which is an adopt and then updates forever after.
+   *   Requiring the create form's parameters on that path would refuse a deploy that has worked
+   *   all along, which is the one failure worse than the 400 this feature removes.
+   * ⚠️ VALUE RULES STILL RUN ON EVERY PLAN, presence or not: a 129-character comment is wrong
+   *   whether it is being created or edited, and that is the case this whole feature exists for.
+   *
+   * ⛔ THE FORM IS BUILT ONLY WHEN THERE IS A TABLE TO CHECK IT AGAINST. Calling `spec.createForm`
+   *   unconditionally would run every family's form builder on every diff — work nobody asked
+   *   for, and a new way for a builder that throws on an update-only path to break a plan it
+   *   never touched.
+   */
+  const guardCreate = (props: Props, presence: boolean): Effect.Effect<void> =>
+    Effect.suspend(() => {
+      const create = endpointsOf(props)?.create;
+      return create === undefined
+        ? Effect.void
+        : guardForm(create, spec.createForm(props), presence);
+    });
+
+  /**
+   * ⛔ NEVER WITH PRESENCE. An update form is deliberately PARTIAL — `formToSend` sends the fields
+   *   that changed and nothing else — so requiring the vendor's required parameters here would
+   *   refuse every ordinary edit. Value rules (length, range, enum, pattern) apply to both forms.
+   */
+  const guardUpdate = (props: Props): Effect.Effect<void> =>
+    Effect.suspend(() => {
+      const update = endpointsOf(props)?.update;
+      if (update === undefined) return Effect.void;
+      const form = spec.updateForm?.(props);
+      return form === undefined ? Effect.void : guardForm(update, form, false);
+    });
+
+  return { guardCreate, guardUpdate };
+};

package/src/proxmox/resource-spec.ts

@@ -109,9 +109,21 @@ export type PveSpec<Props extends WithApiTarget, Attributes> = {
    *   names an endpoint the vendor does not have stops the GENERATOR rather than a deploy.
    * ⚠️ The spelling is the vendor's own path TEMPLATE, braces and all — not `spec.path(props)`,
    *   which has the ids substituted in.
+   *
+   * ⚠️ A FUNCTION FOR THE TWO FAMILIES WHOSE ENDPOINT IS CHOSEN BY A PROP, AND FOR NO OTHER
+   *   REASON. `Proxmox.NotificationTarget` POSTs to one of four `endpoints/{type}` paths and
+   *   `Proxmox.CephDaemon` to one of `ceph/mds|mgr|mon`, each with its own parameter schema, so a
+   *   single key would table the wrong rules for three declarations out of four.
+   *   ⛔ EVERY KEY THE FUNCTION CAN RETURN STILL HAS TO EXIST AS A LITERAL IN THIS PACKAGE'S
+   *     SOURCE. `codegen/constraints.ts` finds keys by scanning text, so a key assembled from a
+   *     template literal is tabled by nothing and `constraintsFor` throws on the deploy that first
+   *     reaches it. Write the keys out in a record and index it — see `ceph-endpoints.ts`.
    */
-  readonly endpoint?: {
-    readonly create?: EndpointKey;
-    readonly update?: EndpointKey;
-  };
+  readonly endpoint?: EndpointPair | ((props: Props) => EndpointPair);
+};
+
+/** The two endpoints a family writes. Either may be absent — see `PveSpec['endpoint']`. */
+export type EndpointPair = {
+  readonly create?: EndpointKey;
+  readonly update?: EndpointKey;
 };

package/src/proxmox/resource.ts

@@ -14,7 +14,7 @@ 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 { specGuards } from './resource-guard.ts';
 import type { PveSpec, WithApiTarget } from './resource-spec.ts';
 import { formToSend } from './update-guard.ts';
 
@@ -29,28 +29,7 @@ export type {
 export const pveOperations = <Props extends WithApiTarget, Attributes>(
   spec: PveSpec<Props, Attributes>,
 ) => {
-  /**
-   * Both forms against their own endpoint's table.
-   *
-   * ⚠️ PRESENCE IS CHECKED ON CREATE ONLY. An update form is deliberately partial — `formToSend`
-   *   sends what changed — so requiring the vendor's required parameters there would refuse every
-   *   ordinary edit. Value rules (length, range, enum, pattern) apply to both.
-   */
-  const guardForms = (props: Props) =>
-    Effect.gen(function* () {
-      /**
-       * ⛔ THE FORM IS BUILT ONLY WHEN THERE IS A TABLE TO CHECK IT AGAINST. Calling
-       *   `spec.createForm` unconditionally would run every family's form builder on every diff,
-       *   including the fifteen that declare no `endpoint` — work nobody asked for, and a new way
-       *   for a builder that throws on an update-only path to break a plan it never touched.
-       */
-      const create = spec.endpoint?.create;
-      if (create !== undefined) yield* guardForm(create, spec.createForm(props), true);
-      const update = spec.endpoint?.update;
-      if (update === undefined) return;
-      const form = spec.updateForm?.(props);
-      if (form !== undefined) yield* guardForm(update, form, false);
-    });
+  const { guardCreate, guardUpdate } = specGuards(spec);
 
   /** The live object, or undefined. ⚠️ A 404 and `{"data": null}` are ANSWERS, not failures. */
   const read = (props: Props) =>
@@ -65,6 +44,15 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
     );
 
   return {
+    /**
+     * ★ EXPORTED SO A FAMILY THAT WRITES ITS OWN `reconcile` REACHES THE SAME CHECK BY THE SAME
+     *   NAME. CephPool, CephFs and ZfsPool all bypass the reconcile below — forked workers, a
+     *   settle loop, a destructive create — and without these two they would be checked at plan
+     *   time and not at apply time, which is exactly the gap an ADOPTED row falls through.
+     */
+    guardCreate,
+    guardUpdate,
+
     read,
 
     // ⚠️ `Input<Props>`, NOT `Props`. At plan time a prop can still be an unresolved Output or
@@ -82,12 +70,21 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
          *   create. Checking after it would leave exactly the case that failed on 2026-09-22
          *   unchecked, and the refusal would arrive from the server, half a deploy in.
          */
-        yield* guardForms(news);
+        yield* guardCreate(news, output === undefined);
+        yield* guardUpdate(news);
         if (output === undefined) return undefined;
         const live = yield* read(news);
         // ⚠️ `update`, NOT `create` — Alchemy's Diff admits only noop/update/replace. An object
         //   Alchemy has state for but the cluster does not is drift, and reconcile repairs it.
-        if (live === undefined) return { action: 'update' } as const;
+        if (live === undefined) {
+          /**
+           * ⛔ DRIFT REACHES `reconcile`'s POST, so the create form's required parameters ARE
+           *   about to go on the wire after all. Saying so here rather than leaving it to
+           *   reconcile keeps the refusal in `plan`, where an operator is reading.
+           */
+          yield* guardCreate(news, true);
+          return { action: 'update' } as const;
+        }
         if (spec.matches(live, news)) return { action: 'noop' } as const;
         // An object with no update path cannot be edited in place; say replace and mean it.
         return spec.updateForm === undefined
@@ -97,11 +94,14 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
 
     reconcile: (news: Props) =>
       Effect.gen(function* () {
+        const live = yield* read(news);
         // ⚠️ CHECKED AGAIN HERE, AND NOT BECAUSE `diff` IS UNTRUSTED. `reconcile` also runs for an
         //   ADOPTED row, whose diff answer Alchemy discards (verify/fake-engine.ts records it), and
         //   a family that writes its own reconcile bypasses the one above entirely.
-        yield* guardForms(news);
-        const live = yield* read(news);
+        // ⛔ AFTER THE READ, BECAUSE THE READ IS WHAT SAYS WHICH REQUEST IS ABOUT TO BE MADE. A GET
+        //   changes nothing, so nothing has been written by the time a violation refuses the plan.
+        yield* guardCreate(news, live === undefined);
+        yield* guardUpdate(news);
         if (live === undefined) {
           yield* pve(
             news.target,

package/src/proxmox/sdn-apply.ts

@@ -35,6 +35,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 { guardSdnApply } from './apply-endpoints.ts';
 import { pve } from './client.ts';
 import type { PveRequirements } from './resource.ts';
 import type { WithTarget } from './resource.ts';
@@ -121,6 +122,9 @@ export const ProxmoxSdnApplyProvider = () =>
           const staged = yield* read(news);
           if (staged.pending === 0) return staged;
 
+          // ⛔ BEFORE THE PUBLISH. The apply takes no body, so this is the lookup rather than a
+          //   value check: a vendor that moved this endpoint fails here, not on three nodes.
+          yield* guardSdnApply;
           yield* pve(news.target, 'provision', 'PUT', 'cluster/sdn');
           /**
            * ⛔ READ BACK, FOR THE SAME REASON THE FACTORY DOES. PVE answers 200 on writes that did