@homeflare/alchemy 0.13.0 → 0.15.0

package/src/proxmox/provision-baseline.ts

@@ -54,7 +54,7 @@ export const PROVISION_PRIVILEGES: readonly string[] = Object.freeze([
 ]);
 
 /** The names a baseline uses. Every field has a generic default (`PROVISION_DEFAULTS`). */
-export interface ProvisionNames {
+export interface CoreProvisionNames {
   /** The role holding `PROVISION_PRIVILEGES` on `/`. */
   readonly role?: string | undefined;
   /** The user OpenBao's `provision` role mints tokens for, realm-qualified. */
@@ -69,11 +69,41 @@ export interface ProvisionNames {
   readonly comment?: string | undefined;
 }
 
-/** Every name, resolved: what `PROVISION_DEFAULTS` holds and what a baseline is built from. */
+/** Every core name, resolved: what `PROVISION_DEFAULTS` holds and what a baseline is built from. */
 export type ResolvedProvisionNames = {
-  readonly [K in keyof ProvisionNames]-?: Exclude<ProvisionNames[K], undefined>;
+  readonly [K in keyof CoreProvisionNames]-?: Exclude<CoreProvisionNames[K], undefined>;
 };
 
+/**
+ * `CoreProvisionNames` plus a comment per object, each defaulting to `comment`.
+ *
+ * ⛔ WHY PER OBJECT: AN EXISTING CLUSTER IS THE NORMAL CASE, NOT THE EXCEPTION. One `comment` for
+ *   three objects can only describe a cluster this baseline made. On one that already has a mint
+ *   group and a read user — with their own live comments, which a stack elsewhere may already
+ *   declare — a single comment makes `provisionBootstrap` rewrite objects nobody asked it to
+ *   touch, and the next deploy of that stack writes them back. Measured on an estate cluster
+ *   2026-09-22, where `hf-mint` had NO comment and `hf-read@pve` named its own mount.
+ * ★ Overriding one does not change the others: `comment` stays the default for every object that
+ *   has no override, so the generic case is still one string.
+ * ⚠️ Each is checked like `comment` is, and a `null` `readUser` drops `readComment` with its lane.
+ */
+export interface ProvisionNames extends CoreProvisionNames {
+  /** The mint group's comment. Defaults to `comment`. */
+  readonly groupComment?: string | undefined;
+  /** The provision user's comment. Defaults to `comment`. */
+  readonly provisionComment?: string | undefined;
+  /** The read user's comment. Defaults to `comment`. Ignored when `readUser` is `null`. */
+  readonly readComment?: string | undefined;
+}
+
+/** The resolved comment for each object a baseline holds. */
+export type ProvisionComments = {
+  readonly [K in 'group' | ProvisionLane]: string;
+};
+
+/** Which credential lane a user or a grant belongs to — the OpenBao role that mints for it. */
+export type ProvisionLane = 'provision' | 'read';
+
 /** ★ Generic, kit-prefixed names: nothing here is any one estate's. */
 export const PROVISION_DEFAULTS: ResolvedProvisionNames = Object.freeze({
   comment:
@@ -85,9 +115,6 @@ export const PROVISION_DEFAULTS: ResolvedProvisionNames = Object.freeze({
   role: 'HfProvisioner',
 });
 
-/** Which credential lane a user or a grant belongs to — the OpenBao role that mints for it. */
-export type ProvisionLane = 'provision' | 'read';
-
 /** A baseline, resolved: exactly what the declaration holds and the bootstrap makes. */
 export interface ProvisionBaseline {
   readonly role: { readonly roleid: string; readonly privs: readonly string[] };
@@ -113,9 +140,13 @@ export interface ProvisionBaseline {
  */
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const USERID = /^[A-Za-z0-9][A-Za-z0-9._-]*@[A-Za-z][A-Za-z0-9._-]*$/;
-const COMMENT = /^[A-Za-z0-9 ._,()@/+-]*$/;
+const COMMENT = /^[A-Za-z0-9 ._,:()@/+-]*$/;
 
-const problems = (names: ResolvedProvisionNames): string[] => {
+const problems = (
+  names: ResolvedProvisionNames,
+  comments: ProvisionComments,
+  given: ProvisionNames,
+): string[] => {
   const found: string[] = [];
   if (!ID.test(names.role)) found.push(`role \`${names.role}\` is not a PVE role id`);
   if (!ID.test(names.mintGroup)) found.push(`mintGroup \`${names.mintGroup}\` is not a group id`);
@@ -129,20 +160,48 @@ const problems = (names: ResolvedProvisionNames): string[] => {
     }
   }
   if (names.readUser === names.provisionUser) found.push('readUser and provisionUser are one user');
-  if (!COMMENT.test(names.comment))
-    found.push('comment holds a character the bootstrap will not quote');
+  // ⛔ EVERY comment THE BASELINE WILL HOLD, not just the shared one: each is pasted into `sh` and
+  //    into a Perl `q{}`. ⚠️ `readComment` only when there is a read lane — a `null` `readUser`
+  //    drops the user, so nothing would ever be pasted.
+  // ★ NAMED BY WHERE THE VALUE CAME FROM, and said once. A bad shared `comment` is one problem
+  //   called `comment`, not three called after overrides the caller never passed.
+  const source = (override: string | undefined, field: string) =>
+    override === undefined ? 'comment' : field;
+  const checked: (readonly [string, string])[] = [
+    [source(given.groupComment, 'groupComment'), comments.group],
+    [source(given.provisionComment, 'provisionComment'), comments.provision],
+  ];
+  if (names.readUser !== null) {
+    checked.push([source(given.readComment, 'readComment'), comments.read]);
+  }
+  const said = new Set<string>();
+  for (const [field, comment] of checked) {
+    if (COMMENT.test(comment) || said.has(field)) continue;
+    said.add(field);
+    found.push(`${field} holds a character the bootstrap will not quote`);
+  }
   return found;
 };
 
 /** Resolve `names` over the defaults and check them. Throws with every problem at once. */
 export const provisionBaseline = (names: ProvisionNames = {}): ProvisionBaseline => {
+  // ⚠️ The per-object comments are taken out first: they are not core names, so they must not land
+  //    in `resolved`, which `PROVISION_DEFAULTS` types and a caller may build a literal of.
+  const { groupComment, provisionComment, readComment, ...core } = names;
   // ⚠️ An explicit `undefined` means "the default", not "blank": spread alone would keep it.
-  const given = Object.entries(names).filter(([, value]) => value !== undefined);
+  const given = Object.entries(core).filter(([, value]) => value !== undefined);
   const resolved: ResolvedProvisionNames = {
     ...PROVISION_DEFAULTS,
     ...Object.fromEntries(given),
   };
-  const found = problems(resolved);
+  // ★ `?? resolved.comment`, so an override changes ONE object and the generic case stays one
+  //   string. ⚠️ `??` and not `||`: an empty comment is a real value — a live object with none.
+  const comments: ProvisionComments = {
+    group: groupComment ?? resolved.comment,
+    provision: provisionComment ?? resolved.comment,
+    read: readComment ?? resolved.comment,
+  };
+  const found = problems(resolved, comments, names);
   if (found.length > 0) throw new Error(`provision baseline: ${found.join('; ')}`);
   const lanes: [ProvisionLane, string, string][] = [
     ['provision', resolved.provisionUser, resolved.role],
@@ -150,10 +209,10 @@ export const provisionBaseline = (names: ProvisionNames = {}): ProvisionBaseline
   if (resolved.readUser !== null) lanes.push(['read', resolved.readUser, resolved.readRole]);
   return {
     grants: lanes.map(([lane, userid, roleid]) => ({ lane, roleid, userid })),
-    group: { comment: resolved.comment, groupid: resolved.mintGroup },
+    group: { comment: comments.group, groupid: resolved.mintGroup },
     role: { privs: PROVISION_PRIVILEGES, roleid: resolved.role },
     users: lanes.map(([lane, userid]) => ({
-      comment: resolved.comment,
+      comment: comments[lane],
       groups: [resolved.mintGroup],
       lane,
       userid,

package/src/proxmox/provision-bootstrap.test.ts

@@ -113,6 +113,57 @@ describe('run against a cluster', () => {
     expect(run.state.acl.map((g) => g.ugid)).toEqual(['hf-provision@pve']);
   });
 
+  test('an EXISTING cluster: only the new object is written, comments and all', async () => {
+    // \u2605 THE CASE ONE SHARED COMMENT COULD NOT DESCRIBE. The cluster already has the mint group
+    //   (no comment at all) and the read user (its own wording), both of them declared elsewhere
+    //   at those live values. Only the provision user is new. With per-object comments the script
+    //   writes exactly that user and its grant -- it does not touch the two that already match,
+    //   so nothing is left for another stack's next deploy to write back.
+    const existing: CliState = {
+      acl: [{ path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'hf-read@pve' }],
+      // \u26a0\ufe0f '' IS "no comment live": the fake's view drops an empty one, as PVE does.
+      groups: { 'hf-mint': { comment: '' } },
+      roles: { ...freshCluster().roles, Provisioner: ['VM.Audit'] },
+      users: { 'hf-read@pve': { ...lane(['hf-mint']), comment: 'mint target: read (ops)' } },
+    };
+    const run = await runScript(
+      provisionBootstrap({
+        groupComment: '',
+        provisionComment: 'mint target: provision (ops)',
+        readComment: 'mint target: read (ops)',
+        role: 'Provisioner',
+      }),
+      existing,
+    );
+    expect(run.code).toBe(0);
+    expect(run.stdout).toContain('group hf-mint: ok');
+    expect(run.stdout).toContain('user hf-read@pve: ok');
+    // The only writes: the role widened to the baseline, the new user, and its grant.
+    expect(run.writes.map((w) => w.split(' ').slice(0, 3).join(' '))).toEqual([
+      'pveum role modify',
+      'pveum user add',
+      'pveum acl modify',
+    ]);
+    expect(run.state.groups['hf-mint']).toEqual({ comment: '' });
+    expect(run.state.users['hf-read@pve']?.comment).toBe('mint target: read (ops)');
+    expect(run.state.users['hf-provision@pve']?.comment).toBe('mint target: provision (ops)');
+    expect(run.state.roles['Provisioner']).toEqual([...PROVISION_PRIVILEGES]);
+
+    // \u26d4 NEGATIVE CONTROL, so this test can fail: the SAME cluster with one shared comment
+    //   rewrites both objects that already matched. That is the write per-object comments exist
+    //   to avoid, and it is what another stack's next deploy would put back.
+    const shared = await runScript(
+      provisionBootstrap({ comment: 'mint target: provision (ops)', role: 'Provisioner' }),
+      existing,
+    );
+    expect(shared.code).toBe(0);
+    expect(shared.writes.map((w) => w.split(' ').slice(0, 3).join(' '))).toContain(
+      'pveum group modify',
+    );
+    expect(shared.state.groups['hf-mint']).toEqual({ comment: 'mint target: provision (ops)' });
+    expect(shared.state.users['hf-read@pve']?.comment).toBe('mint target: provision (ops)');
+  });
+
   test("a site's own names flow through every step", async () => {
     const names = {
       mintGroup: 'mint',

package/src/proxmox/replication-job.ts

@@ -224,6 +224,11 @@ const handlers = pveHandlers<ReplicationJobProps, ReplicationJobAttributes>({
    *   that is busy deleting itself, and matching that would be a noop over a vanishing object. It
    *   settles because `updateBody` actually clears the marker — see there.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/replication',
+    update: 'pve:PUT /cluster/replication/{id}',
+  },
   matches: (attributes, props) =>
     attributes.remove_job === '' &&
     attributes.schedule === (props.schedule ?? DEFAULT_SCHEDULE) &&

package/src/proxmox/resource-spec.ts

@@ -0,0 +1,117 @@
+/**
+ * WHAT A PVE OBJECT DECLARES: one shape for every one of them, so the provider can cover Proxmox
+ * rather than a corner of it. The four operations that read this spec are in resource.ts.
+ *
+ * ⛔ THE ALTERNATIVE IS TWENTY COPIES OF THE SAME 130 LINES. Proxmox exposes LXC, QEMU, storage,
+ *   pools, users, groups, roles, ACLs, API tokens, SDN zones/vnets/subnets, firewall rules and
+ *   groups, HA resources, backup and replication jobs, metric servers and notification targets.
+ *   Each is the same four operations over a different path and a different form body. Written by
+ *   hand, resource number six is where someone quietly drops the read-back or the isResolved guard
+ *   and nobody notices until a plan lies.
+ *
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE, AND A RESOURCE DECLARES ONLY WHAT IS DIFFERENT:
+ *   where it lives, how to recognise it, and which fields are mutable. A new PVE object should be
+ *   thirty lines, not a hundred and thirty.
+ *
+ * ⚠️ EVERY PVE ANSWER IS WRAPPED IN `{"data": ...}` AND A FAILED CALL CAN STILL BE HTTP 200 with
+ *   `{"data": null}`. That is why `reconcile` below READS BACK and refuses when the object is still
+ *   absent, rather than trusting a status code — see the ⛔ in that function.
+ */
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import type { PveForm } from './client.ts';
+import type { EndpointKey } from './constraints.ts';
+import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
+
+/**
+ * ★ WHY SEVERAL FAMILIES HERE DECLARE `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE.
+ *
+ *   Alchemy's own convention: a few resource types default to retain "because their contents are
+ *   irreplaceable" — `GitHub.Repository` and `Cloudflare.Zone` do — and those opt into deletion
+ *   with `destroy()`. `retain` means the engine SKIPS `provider.delete` entirely when a resource
+ *   is orphaned or destroyed: the state row is dropped, the cluster object lives on.
+ *
+ *   So the PVE families whose contents cannot be rebuilt from a line of TypeScript — CephOsd,
+ *   CephPool, CephFs, CephDaemon, ZfsPool, Storage, NodeNetwork — carry that default. Their
+ *   `delete` is FULLY IMPLEMENTED and runs the moment a caller opts in with
+ *   `.pipe(RemovalPolicy.destroy())`. This is deliberately the Terraform `prevent_destroy` shape
+ *   rather than a stubbed-out operation: a `delete` that silently does nothing lies to whoever is
+ *   reading the plan, and the lie is discovered at the worst possible time.
+ *
+ * ⚠️ THE POLICY IS A DECORATION, NOT A PROP, so changing it produces NO DIFF — the resource plans
+ *   as a noop and the deploy re-commits the row's policy in place. A policy change therefore takes
+ *   effect from the very next deploy even though the plan shows nothing.
+ */
+
+/**
+ * ⛔ A RESOURCE IS PINNED TO ITS PRODUCT; ONLY THE FACTORY TAKES EITHER. The two hosts are the same
+ *   two strings, so without a required discriminant TypeScript would accept a PBS host wherever a
+ *   PVE one belongs — silently, with every call 401ing and `read` folding that into "absent". The
+ *   whole argument is on `scheme` in credentials.ts.
+ */
+/**
+ * ★ WHAT EVERY OPERATION IN THIS PACKAGE NEEDS FROM THE RUNTIME, NAMED ONCE.
+ *
+ *   `HttpClient`, for both halves of every call: the credential is minted from OpenBao's HTTP API
+ *   and the PVE call goes through the same client. That is what Alchemy's own providers do
+ *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`, and there is no bare `fetch` in
+ *   its Docker, Kubernetes or GitHub providers).
+ * ★ `ChildProcessSpawner` WAS HERE UNTIL 2026-09-14, while the mint shelled out to `bao`. The HTTP
+ *   client replaced that (credentials.ts), so the requirement went with it.
+ *
+ * ⚠️ SPELLED OUT AT EACH OF THE FORTY-ODD RESOURCES this would be a union nobody keeps in step —
+ *   one file left on the old shape is a type error at the stack, far from the cause. Named here,
+ *   adding a third service later is one edit.
+ */
+export type PveRequirements = HttpClient.HttpClient;
+
+export type WithTarget = { target: PveTarget };
+export type WithPbsTarget = { target: PbsTarget };
+export type WithApiTarget = { target: ApiTarget };
+
+export type PveSpec<Props extends WithApiTarget, Attributes> = {
+  /** `pools/lab`, `nodes/node-b/lxc/101` — where ONE object is read, updated and deleted. */
+  readonly path: (props: Props) => string;
+  /** `pools`, `nodes/node-b/lxc` — where a NEW one is POSTed. */
+  readonly collection: (props: Props) => string;
+  /** Live JSON to attributes. Returning undefined means "this is not really there". */
+  readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
+  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. Arrays: client.ts. */
+  readonly createForm: (props: Props) => PveForm;
+  /**
+   * The form for an update, or undefined when the object has no mutable fields.
+   *
+   * ⚠️ SOME PVE OBJECTS CANNOT BE UPDATED AT ALL. Returning undefined makes a changed prop a
+   *   REPLACE rather than a silent no-op, which is the honest answer for an immutable object.
+   */
+  readonly updateForm?: (props: Props) => PveForm;
+  /** True when live already matches props. Decides noop vs update. */
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /**
+   * Which lease reads this family. Defaults to `read`, the 3600s auditor-shaped one.
+   *
+   * ⛔ THREE FAMILIES SET THIS TO `provision`, AND THE FAILURE IT AVOIDS IS SILENT. PVE gates some
+   *   SINGLE-OBJECT reads on the allocate privilege rather than the audit one — `/storage/{id}`,
+   *   `/cluster/sdn/zones/{zone}`, `/cluster/sdn/vnets/{vnet}` — while their COLLECTION reads
+   *   accept audit, so nothing looks wrong until a resource reads one object. `read` below folds
+   *   every failure into `undefined`, right for a 404 and wrong for a 403, so the plan says create
+   *   and PVE answers that the object already exists. Measured both ways on `local`, and written
+   *   up with the alternative that was rejected, in docs/privileges.md.
+   */
+  readonly readRole?: PveRole;
+  /**
+   * The vendor endpoints this family writes, as the generated tables key them —
+   * `'pbs:POST /config/verify'`, `'pve:PUT /cluster/sdn/zones/{zone}'`.
+   *
+   * ⛔ DECLARING IT IS WHAT MAKES THE VENDOR'S OWN LIMITS RUN AT PLAN TIME. Without it the family
+   *   behaves exactly as it did on 2026-09-22, when `deploy:pbs` adopted ten objects and then
+   *   failed its one create on a `maxLength` PBS publishes and our generated `comment?: string`
+   *   does not carry. `codegen/constraints.ts` scans this package for these strings, so a key that
+   *   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.
+   */
+  readonly endpoint?: {
+    readonly create?: EndpointKey;
+    readonly update?: EndpointKey;
+  };
+};

package/src/proxmox/resource.ts

@@ -1,16 +1,10 @@
 /**
- * One shape for every PVE object, so the provider can cover Proxmox rather than a corner of it.
+ * The four operations every PVE object shares, and the five handlers that wire them to Alchemy.
  *
- * ⛔ THE ALTERNATIVE IS TWENTY COPIES OF THE SAME 130 LINES. Proxmox exposes LXC, QEMU, storage,
- *   pools, users, groups, roles, ACLs, API tokens, SDN zones/vnets/subnets, firewall rules and
- *   groups, HA resources, backup and replication jobs, metric servers and notification targets.
- *   Each is the same four operations over a different path and a different form body. Written by
- *   hand, resource number six is where someone quietly drops the read-back or the isResolved guard
- *   and nobody notices until a plan lies.
- *
- * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE, AND A RESOURCE DECLARES ONLY WHAT IS DIFFERENT:
- *   where it lives, how to recognise it, and which fields are mutable. A new PVE object should be
- *   thirty lines, not a hundred and thirty.
+ * ★ THE SHAPE THEY READ IS `PveSpec`, IN resource-spec.ts, WITH THE ARGUMENT FOR IT. This file was
+ *   one file until 2026-09-22, when the vendor-constraint guard took it past the 250-line cap; the
+ *   split is by what a reader is doing — declaring an object, or changing how every object is
+ *   written — and the types are re-exported below so no importer moved.
  *
  * ⚠️ EVERY PVE ANSWER IS WRAPPED IN `{"data": ...}` AND A FAILED CALL CAN STILL BE HTTP 200 with
  *   `{"data": null}`. That is why `reconcile` below READS BACK and refuses when the object is still
@@ -19,92 +13,45 @@
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
-import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { type PveForm, pve } from './client.ts';
-import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
+import { pve } from './client.ts';
+import { guardForm } from './constraint-guard.ts';
+import type { PveSpec, WithApiTarget } from './resource-spec.ts';
 import { formToSend } from './update-guard.ts';
 
-/**
- * ★ WHY SEVERAL FAMILIES HERE DECLARE `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE.
- *
- *   Alchemy's own convention: a few resource types default to retain "because their contents are
- *   irreplaceable" — `GitHub.Repository` and `Cloudflare.Zone` do — and those opt into deletion
- *   with `destroy()`. `retain` means the engine SKIPS `provider.delete` entirely when a resource
- *   is orphaned or destroyed: the state row is dropped, the cluster object lives on.
- *
- *   So the PVE families whose contents cannot be rebuilt from a line of TypeScript — CephOsd,
- *   CephPool, CephFs, CephDaemon, ZfsPool, Storage, NodeNetwork — carry that default. Their
- *   `delete` is FULLY IMPLEMENTED and runs the moment a caller opts in with
- *   `.pipe(RemovalPolicy.destroy())`. This is deliberately the Terraform `prevent_destroy` shape
- *   rather than a stubbed-out operation: a `delete` that silently does nothing lies to whoever is
- *   reading the plan, and the lie is discovered at the worst possible time.
- *
- * ⚠️ THE POLICY IS A DECORATION, NOT A PROP, so changing it produces NO DIFF — the resource plans
- *   as a noop and the deploy re-commits the row's policy in place. A policy change therefore takes
- *   effect from the very next deploy even though the plan shows nothing.
- */
-
-/**
- * ⛔ A RESOURCE IS PINNED TO ITS PRODUCT; ONLY THE FACTORY TAKES EITHER. The two hosts are the same
- *   two strings, so without a required discriminant TypeScript would accept a PBS host wherever a
- *   PVE one belongs — silently, with every call 401ing and `read` folding that into "absent". The
- *   whole argument is on `scheme` in credentials.ts.
- */
-/**
- * ★ WHAT EVERY OPERATION IN THIS PACKAGE NEEDS FROM THE RUNTIME, NAMED ONCE.
- *
- *   `HttpClient`, for both halves of every call: the credential is minted from OpenBao's HTTP API
- *   and the PVE call goes through the same client. That is what Alchemy's own providers do
- *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`, and there is no bare `fetch` in
- *   its Docker, Kubernetes or GitHub providers).
- * ★ `ChildProcessSpawner` WAS HERE UNTIL 2026-09-14, while the mint shelled out to `bao`. The HTTP
- *   client replaced that (credentials.ts), so the requirement went with it.
- *
- * ⚠️ SPELLED OUT AT EACH OF THE FORTY-ODD RESOURCES this would be a union nobody keeps in step —
- *   one file left on the old shape is a type error at the stack, far from the cause. Named here,
- *   adding a third service later is one edit.
- */
-export type PveRequirements = HttpClient.HttpClient;
-
-export type WithTarget = { target: PveTarget };
-export type WithPbsTarget = { target: PbsTarget };
-export type WithApiTarget = { target: ApiTarget };
+export type {
+  PveRequirements,
+  PveSpec,
+  WithApiTarget,
+  WithPbsTarget,
+  WithTarget,
+} from './resource-spec.ts';
 
-export type PveSpec<Props extends WithApiTarget, Attributes> = {
-  /** `pools/lab`, `nodes/node-b/lxc/101` — where ONE object is read, updated and deleted. */
-  readonly path: (props: Props) => string;
-  /** `pools`, `nodes/node-b/lxc` — where a NEW one is POSTed. */
-  readonly collection: (props: Props) => string;
-  /** Live JSON to attributes. Returning undefined means "this is not really there". */
-  readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
-  /** The form PVE wants on create. ⚠️ PVE takes form encoding, not JSON. Arrays: client.ts. */
-  readonly createForm: (props: Props) => PveForm;
-  /**
-   * The form for an update, or undefined when the object has no mutable fields.
-   *
-   * ⚠️ SOME PVE OBJECTS CANNOT BE UPDATED AT ALL. Returning undefined makes a changed prop a
-   *   REPLACE rather than a silent no-op, which is the honest answer for an immutable object.
-   */
-  readonly updateForm?: (props: Props) => PveForm;
-  /** True when live already matches props. Decides noop vs update. */
-  readonly matches: (attributes: Attributes, props: Props) => boolean;
+export const pveOperations = <Props extends WithApiTarget, Attributes>(
+  spec: PveSpec<Props, Attributes>,
+) => {
   /**
-   * Which lease reads this family. Defaults to `read`, the 3600s auditor-shaped one.
+   * Both forms against their own endpoint's table.
    *
-   * ⛔ THREE FAMILIES SET THIS TO `provision`, AND THE FAILURE IT AVOIDS IS SILENT. PVE gates some
-   *   SINGLE-OBJECT reads on the allocate privilege rather than the audit one — `/storage/{id}`,
-   *   `/cluster/sdn/zones/{zone}`, `/cluster/sdn/vnets/{vnet}` — while their COLLECTION reads
-   *   accept audit, so nothing looks wrong until a resource reads one object. `read` below folds
-   *   every failure into `undefined`, right for a 404 and wrong for a 403, so the plan says create
-   *   and PVE answers that the object already exists. Measured both ways on `local`, and written
-   *   up with the alternative that was rejected, in docs/privileges.md.
+   * ⚠️ 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.
    */
-  readonly readRole?: PveRole;
-};
+  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);
+    });
 
-export const pveOperations = <Props extends WithApiTarget, Attributes>(
-  spec: PveSpec<Props, Attributes>,
-) => {
   /** The live object, or undefined. ⚠️ A 404 and `{"data": null}` are ANSWERS, not failures. */
   const read = (props: Props) =>
     pve<Record<string, unknown>>(
@@ -128,7 +75,15 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
         // ⚠️ A prop can still be an unresolved Output at plan time. Alchemy's own providers guard
         //   with isResolved and skip rather than guess; comparing a placeholder to a live value
         //   reports an update nobody asked for.
-        if (output === undefined || !isResolved(news)) return undefined;
+        if (!isResolved(news)) return undefined;
+        /**
+         * ⛔ THE VENDOR CHECK RUNS BEFORE THE `output === undefined` RETURN, AND THE ORDER IS THE
+         *   WHOLE FIX. `output === undefined` IS the resource Alchemy has no state for — the
+         *   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);
+        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.
@@ -142,6 +97,10 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
 
     reconcile: (news: Props) =>
       Effect.gen(function* () {
+        // ⚠️ 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);
         if (live === undefined) {
           yield* pve(

package/src/proxmox/role.ts

@@ -131,6 +131,8 @@ const handlers = pveHandlers<RoleProps, RoleAttributes>({
    *   a plan that reports an update every single time and a deploy that writes the same role back
    *   forever. Cheap insurance against the exact trap named in the header.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /access/roles', update: 'pve:PUT /access/roles/{roleid}' },
   matches: (attributes, props) =>
     canonical(attributes.privs).join(',') === canonical(props.privs).join(','),
   path: (props) => `access/roles/${props.roleid}`,

package/src/proxmox/sdn-vnet.ts

@@ -193,6 +193,8 @@ const handlers = pveHandlers<SdnVnetProps, SdnVnetAttributes>({
    *   would report an update on every plan until somebody ran the apply, and then report another
    *   one the moment anybody else staged anything at all.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/sdn/vnets', update: 'pve:PUT /cluster/sdn/vnets/{vnet}' },
   matches: (attributes, props) =>
     attributes.zone === props.zone &&
     attributes.alias === (props.alias ?? '') &&

package/src/proxmox/sdn-zone.ts

@@ -210,6 +210,8 @@ const handlers = pveHandlers<SdnZoneProps, SdnZoneAttributes>({
    *   handled above by refusing to recognise a zone of the wrong one. Comparing either here would
    *   produce a diff whose update can never satisfy it.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/sdn/zones', update: 'pve:PUT /cluster/sdn/zones/{zone}' },
   matches: (attributes, props) =>
     attributes.mtu === (props.mtu ?? 0) &&
     attributes.nodes === csv(props.nodes) &&

package/src/proxmox/storage.ts

@@ -217,6 +217,8 @@ const handlers = pveHandlers<StorageProps, StorageAttributes>({
    *   PVE returns the create-only fields on read but refuses them on PUT, so diffing one could only
    *   plan an update that no write can apply: a plan that reports work on every run, forever.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /storage', update: 'pve:PUT /storage/{storage}' },
   matches: (attributes, props) =>
     sameList(props.content, attributes.content) &&
     sameList(props.nodes, attributes.nodes) &&

package/src/proxmox/user.ts

@@ -186,6 +186,8 @@ const handlers = pveHandlers<UserProps, UserAttributes>({
    *   what a PUT can put back; a field that PVE reports but will not accept is drift nobody can
    *   fix, and diffing it would report an update on every plan forever.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /access/users', update: 'pve:PUT /access/users/{userid}' },
   matches: (attributes, props) =>
     attributes.comment === (props.comment ?? '') &&
     attributes.email === (props.email ?? '') &&