@homeflare/alchemy 0.14.0 → 0.15.0

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

@@ -0,0 +1,61 @@
+/**
+ * PVE exposes no way to reach INSIDE a container, and this pins that as a measured fact rather
+ * than a thing people keep re-deriving.
+ *
+ * ★ WHY A TEST AND NOT ONLY A DOC. `Proxmox.Lxc` declares a guest's PVE-level config and nothing
+ *   within its filesystem, and every consumer that meets that limit goes looking for the resource
+ *   that must surely exist — an exec, a file write, a cloud-init. It does not, for containers. A
+ *   grep proves that once; this proves it on every run, and fails the day PVE adds one, which is
+ *   exactly when the kit would want to wrap it.
+ * ⛔ THE POSITIVE CONTROL IS LOAD BEARING. A test that only asserts absence passes for free if the
+ *   generated file's comment shape ever changes. QEMU's `agent/exec` and `agent/file-write` are
+ *   asserted present in the same pass, so a format change fails here instead of going quiet.
+ * ⚠️ SIBLING FAMILIES ARE NOT AT PARITY. QEMU and LXC sit under the same `/nodes/{node}/…` tree
+ *   and have completely different reach. Never infer one family's endpoints from the other's.
+ */
+import { describe, expect, test } from 'bun:test';
+
+const schema = await Bun.file(new URL('./generated/pve.ts', import.meta.url)).text();
+
+/** Every endpoint the generated schema documents, as `METHOD /path`. */
+const endpoints = [...schema.matchAll(/(GET|POST|PUT|DELETE) (\/[A-Za-z0-9/{}_.-]+)/g)].map(
+  (match) => `${match[1]} ${match[2]}`,
+);
+
+const under = (prefix: string) =>
+  endpoints.filter((line) => line.slice(line.indexOf(' ') + 1).startsWith(prefix));
+
+const LXC = '/nodes/{node}/lxc/{vmid}';
+const QEMU = '/nodes/{node}/qemu/{vmid}';
+
+describe('a container has no interior API', () => {
+  test('the schema was parsed at all', () => {
+    // ⛔ Without this, every absence assertion below would pass on an empty list.
+    expect(endpoints.length).toBeGreaterThan(100);
+    expect(under(LXC).length).toBeGreaterThan(20);
+  });
+
+  test('QEMU can exec and write files inside a guest — the positive control', () => {
+    expect(under(QEMU)).toContain(`POST ${QEMU}/agent/exec`);
+    expect(under(QEMU)).toContain(`POST ${QEMU}/agent/file-write`);
+    expect(under(QEMU)).toContain(`GET ${QEMU}/agent/file-read`);
+  });
+
+  test('no LXC endpoint execs, reads or writes a file, or takes cloud-init', () => {
+    // ⛔ So a generic, vendor-API-based Resource for a container's interior cannot be written:
+    //    there is nothing to wrap. What is left is an image baked before create, a first-boot
+    //    artifact, or a recorded human step — see docs/proxmox-lxc.md.
+    const reaching = under(LXC).filter((line) =>
+      /\/(agent|exec|file-read|file-write|cloudinit|cloud-init)(\/|$)/.test(line),
+    );
+    expect(reaching).toEqual([]);
+  });
+
+  test('the only LXC reach inside is an interactive console, which is not declarative', () => {
+    // ⚠️ `termproxy` and `vncwebsocket` open a terminal for a person. They are not an API a
+    //    resource can diff, and the kit wraps neither.
+    const consoles = under(LXC).filter((line) => /(termproxy|vncwebsocket|spiceproxy)/.test(line));
+    expect(consoles.length).toBeGreaterThan(0);
+    expect(schema.includes('LxcExec')).toBe(false);
+  });
+});

package/src/proxmox/notification-matcher.ts

@@ -64,6 +64,11 @@ const handlers = pveHandlers<NotificationMatcherProps, NotificationMatcherAttrib
   attributes: (live, props) => matcherAttributes(live, props.name),
   collection: () => 'cluster/notifications/matchers',
   createForm: matcherCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/notifications/matchers',
+    update: 'pve:PUT /cluster/notifications/matchers/{name}',
+  },
   matches: matcherMatches,
   path: (props) => `cluster/notifications/matchers/${props.name}`,
   updateForm: matcherUpdateForm,

package/src/proxmox/pbs-datastore-endpoint.ts

@@ -0,0 +1,29 @@
+/**
+ * `Pbs.Datastore`'s two vendor endpoints, and the plan-time check over its two forms.
+ *
+ * ★ A FILE OF ITS OWN BECAUSE THIS FAMILY DOES NOT USE `pveHandlers`. It writes its own `diff` and
+ *   `reconcile` (a create answers with a task id, so it settles rather than reading back once), so
+ *   it cannot inherit the guard from resource.ts — and a copy of the two calls inside that already
+ *   long file is exactly the per-resource copy-paste the shared handler exists to prevent.
+ *
+ * ⛔ THE FOUR FIELDS THAT MADE THIS WORTH DOING, from the PBS 4.2.6 schema: `comment` is
+ *   maxLength 128 with a no-control-characters pattern, `name` is 3..32 with a safe-id pattern,
+ *   and every `keep-*` has minimum 1. All four were `string`/`number` with the limits in prose.
+ */
+import * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+import { createForm, updateForm } from './pbs-datastore-form.ts';
+import type { PbsDatastoreProps } from './pbs-datastore.ts';
+
+export const DATASTORE_ENDPOINT: { readonly create: EndpointKey; readonly update: EndpointKey } = {
+  create: 'pbs:POST /config/datastore',
+  update: 'pbs:PUT /config/datastore/{name}',
+};
+
+/** ⚠️ Presence on create only — an update form is partial by design (update-guard.ts). */
+export const guardDatastoreForms = (props: PbsDatastoreProps): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    yield* guardForm(DATASTORE_ENDPOINT.create, createForm(props), true);
+    yield* guardForm(DATASTORE_ENDPOINT.update, updateForm(props), false);
+  });

package/src/proxmox/pbs-datastore.ts

@@ -64,6 +64,7 @@ import {
   updateForm,
 } from './pbs-datastore-form.ts';
 import { guardBackend, guardPath, settle } from './pbs-datastore-guard.ts';
+import { guardDatastoreForms } from './pbs-datastore-endpoint.ts';
 import type { PveRequirements } from './resource.ts';
 import { formToSend } from './update-guard.ts';
 
@@ -181,7 +182,11 @@ export const PbsDatastoreProvider = () =>
          */
         diff: ({ news, output }) =>
           Effect.gen(function* () {
-            if (output === undefined || !isResolved(news)) return undefined;
+            if (!isResolved(news)) return undefined;
+            // ⛔ BEFORE the `output === undefined` return: that branch IS the create, which is the
+            //   one this family has never checked. resource.ts carries the argument in full.
+            yield* guardDatastoreForms(news);
+            if (output === undefined) return undefined;
             const live = yield* readOne(news);
             // ⚠️ `update`, not `create` — Alchemy's Diff admits only noop/update/replace, and an
             //   object Alchemy has state for but PBS does not is drift for reconcile to repair.
@@ -198,6 +203,8 @@ export const PbsDatastoreProvider = () =>
          * ⛔ THE `matches` GUARD BEFORE THE PUT IS resource.ts's, AND IT IS WHY ADOPTION IS FREE.
          */
         reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ Again here: an ADOPTED row's diff answer is discarded by Alchemy and reconcile runs.
+          yield* guardDatastoreForms(news);
           const live = yield* readOne(news);
           let upid: string | undefined;
           if (live === undefined) {

package/src/proxmox/pbs-notification-matcher.ts

@@ -69,6 +69,11 @@ const handlers = pveHandlers<PbsNotificationMatcherProps, NotificationMatcherAtt
   attributes: (live, props) => matcherAttributes(live, props.name),
   collection: () => 'config/notifications/matchers',
   createForm: matcherCreateForm,
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pbs:POST /config/notifications/matchers',
+    update: 'pbs:PUT /config/notifications/matchers/{name}',
+  },
   matches: matcherMatches,
   path: (props) => `config/notifications/matchers/${props.name}`,
   updateForm: matcherUpdateForm,

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

@@ -194,6 +194,8 @@ const handlers = pveHandlers<PruneJobProps, PruneJobAttributes>({
    *   compared unconditionally. A changed `store` is an update, not a replace: PBS accepts `store`
    *   on PUT, so the job is re-pointed in place.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/prune', update: 'pbs:PUT /config/prune/{id}' },
   matches: (attributes, props) =>
     attributes.schedule === props.schedule &&
     attributes.store === props.store &&

package/src/proxmox/pbs-sync-job-form.ts

@@ -209,6 +209,8 @@ export const handlers = pveHandlers<SyncJobProps, SyncJobAttributes>({
    * ⚠️ `id`, `group-filter` AND `sync-direction` ARE OUT. The first is the path, a change to which
    *   is a different object; the other two are argued on their props in pbs-sync-job.ts.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pbs:POST /config/sync', update: 'pbs:PUT /config/sync/{id}' },
   matches: (attributes, props) =>
     attributes['remove-vanished'] === (props['remove-vanished'] === true) &&
     attributes.store === props.store &&

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/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;
+  };
+};