@homeflare/alchemy 0.14.0 → 0.19.0

package/src/proxmox/pbs-verify-job.ts

@@ -193,6 +193,8 @@ const handlers = pveHandlers<PbsVerifyJobProps, PbsVerifyJobAttributes>({
    * ⚠️ `rechecks` IS ABSENT HERE ON PURPOSE. It is a rendering of the two fields on the lines
    *   above; comparing it too would report the same drift twice.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/verify', update: 'pbs:PUT /config/verify/{id}' },
   matches: (attributes, props) =>
     attributes.store === props.store &&
     // ⚠️ `null` IS COMPARED AGAINST `''`, NOT SKIPPED. A parked job is a declaration like any

package/src/proxmox/pool.ts

@@ -71,6 +71,8 @@ const handlers = pveHandlers<PoolProps, PoolAttributes>({
   },
   collection: () => 'pools',
   createForm: poolCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /pools', update: 'pve:PUT /pools/{poolid}' },
   matches: (attributes, props) => attributes.comment === (props.comment ?? ''),
   path: (props) => `pools/${props.poolid}`,
   updateForm: poolUpdateForm,

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

@@ -84,4 +84,42 @@ describe('provisionBaseline', () => {
   test('refuses one user for both lanes', () => {
     expect(() => provisionBaseline({ readUser: 'hf-provision@pve' })).toThrow(/one user/);
   });
+
+  test('a comment per object, each defaulting to `comment` on its own', () => {
+    // \u2605 THE EXISTING-CLUSTER CASE: the group and the read user already carry their own live
+    //   comments, and only the provision user is new. One shared comment could not say this.
+    const baseline = provisionBaseline({
+      comment: 'shared',
+      groupComment: '',
+      provisionComment: 'mint target: provision (ops)',
+      readComment: 'mint target: read (ops)',
+    });
+    expect(baseline.group.comment).toBe('');
+    expect(baseline.users.map((u) => u.comment)).toEqual([
+      'mint target: provision (ops)',
+      'mint target: read (ops)',
+    ]);
+    // Overriding one leaves the others on `comment`; the generic case is still one string.
+    const one = provisionBaseline({ comment: 'shared', provisionComment: 'only this' });
+    expect([one.group.comment, ...one.users.map((u) => u.comment)]).toEqual([
+      'shared',
+      'only this',
+      'shared',
+    ]);
+    expect(provisionBaseline({ comment: 'shared' }).group.comment).toBe('shared');
+  });
+
+  test('every comment is refused by its own field name', () => {
+    const attempt = () =>
+      provisionBaseline({ groupComment: "it's", provisionComment: 'q{x}', readComment: '$(id)' });
+    expect(attempt).toThrow(/groupComment.*provisionComment.*readComment/);
+  });
+
+  test('readComment goes with its lane: unchecked, and unused, when readUser is null', () => {
+    // ⚠️ Nothing would ever paste it, so refusing it would be a refusal over a field the caller
+    //    is not using. The lane it belongs to is gone.
+    const none = provisionBaseline({ readComment: "would need quoting'", readUser: null });
+    expect(none.users.map((u) => u.lane)).toEqual(['provision']);
+    expect(() => provisionBaseline({ readComment: "would need quoting'" })).toThrow(/readComment/);
+  });
 });

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

@@ -0,0 +1,129 @@
+/**
+ * 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.
+   *
+   * ⚠️ 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?: 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;
+};