@homeflare/alchemy 0.14.0 → 0.15.0

package/src/openbao/index-types.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The barrel's TYPE surface, pinned.
+ *
+ * ⛔ THIS IS THE TEST FOR A BUG THAT ONLY A CONSUMER COULD SEE. Every `Bao.*` family already
+ *   re-exported its `…Props` and `…Attributes` from its own module, but `index.ts` forwarded only
+ *   the VALUES for seven of them. A consumer that may not deep-import — which is every consumer,
+ *   by the estate's adoption rules — therefore could not name the props of the very Resource the
+ *   barrel handed it, and had to write the shape out and hope it stayed in step.
+ *   MEASURED 2026-09-22 in homeflare-openbao, which did exactly that for `BaoProxmoxRole`.
+ *
+ * ★ A TYPE-ONLY TEST, ON PURPOSE. Nothing here runs; `tsc --noEmit` is the assertion. If a family's
+ *   props stop being reachable from the package entry, this file stops compiling, which is the
+ *   only moment anyone would otherwise notice — at the next consumer, in another repo.
+ */
+import type {
+  BaoAuthMethodAttributes,
+  BaoAuthMethodProps,
+  BaoAuthRoleAttributes,
+  BaoAuthRoleProps,
+  BaoCloudflareRoleAttributes,
+  BaoCloudflareRoleProps,
+  BaoJwtRoleAttributes,
+  BaoMountAttributes,
+  BaoMountProps,
+  BaoPkiRoleAttributes,
+  BaoPkiRoleProps,
+  BaoPluginAttributes,
+  BaoPluginProps,
+  BaoPolicyAttributes,
+  BaoPolicyProps,
+  BaoProxmoxRoleAttributes,
+  BaoProxmoxRoleProps,
+  BaoSshRoleAttributes,
+  BaoSshRoleProps,
+} from './index.ts';
+import { expect, test } from 'bun:test';
+
+/**
+ * ⛔ The one a consumer was already missing. `mount` + `name` + `mintUser` + `ttl` + `maxTtl` IS the
+ *   whole role, so a consumer that writes this shape out by hand is writing the entire
+ *   server-side state of the family — including `mintUser`, which is its security boundary.
+ */
+const proxmoxRole: BaoProxmoxRoleProps = {
+  maxTtl: '30m',
+  mintUser: 'hf-provision@pve',
+  mount: 'proxmox-ops',
+  name: 'provision',
+  ttl: '5m',
+};
+
+const mount: BaoMountProps = { path: 'proxmox-ops', type: 'openbao-plugin-secrets-proxmox' };
+
+/** ⛔ The plugin catalog key — a consumer needs this to declare a registration at all. */
+const plugin: BaoPluginProps = {
+  command: 'openbao-plugin-secrets-proxmox',
+  name: 'openbao-plugin-secrets-proxmox',
+  sha256: 'a'.repeat(64),
+  type: 'secret',
+  version: 'v0.0.0-dev',
+};
+
+/** ★ Named so the attribute types are reachable too: a consumer reads outputs as well as writing props. */
+type Reachable =
+  | BaoAuthMethodAttributes
+  | BaoAuthMethodProps
+  | BaoAuthRoleAttributes
+  | BaoAuthRoleProps
+  | BaoCloudflareRoleAttributes
+  | BaoCloudflareRoleProps
+  | BaoJwtRoleAttributes
+  | BaoMountAttributes
+  | BaoPkiRoleAttributes
+  | BaoPkiRoleProps
+  | BaoProxmoxRoleAttributes
+  | BaoPluginAttributes
+  | BaoPolicyAttributes
+  | BaoPolicyProps
+  | BaoSshRoleAttributes
+  | BaoSshRoleProps;
+
+test("every openbao family's props are reachable from the package entry", () => {
+  const reachable: Reachable[] = [];
+  expect(reachable).toEqual([]);
+  expect(proxmoxRole.mintUser).toBe('hf-provision@pve');
+  expect(mount.type).toBe('openbao-plugin-secrets-proxmox');
+  expect(plugin.version).toBe('v0.0.0-dev');
+});

package/src/openbao/index.ts

@@ -23,11 +23,13 @@ export {
   revokeSelf,
   revokeSelfEffect,
 } from './approle-login.ts';
+export type { BaoAuthMethodAttributes, BaoAuthMethodProps } from './auth-method.ts';
 export { BaoAuthMethod, BaoAuthMethodProvider } from './auth-method.ts';
-export type { BaoAuthRoleProps } from './auth-role.ts';
+export type { BaoAuthRoleAttributes, BaoAuthRoleProps } from './auth-role.ts';
 export { BaoAuthRole, BaoAuthRoleProvider } from './auth-role.ts';
 export type { BaoIdentity, BaoIdentityExpected, BaoIdentityFailure } from './bao-identity.ts';
 export { BaoIdentityError, assertBaoIdentity, assertBaoIdentityEffect } from './bao-identity.ts';
+export type { BaoCloudflareRoleAttributes, BaoCloudflareRoleProps } from './cloudflare-role.ts';
 export { BaoCloudflareRole, BaoCloudflareRoleProvider } from './cloudflare-role.ts';
 export {
   CloudflarePermissionGroups,
@@ -42,7 +44,12 @@ export type { HostAppRolesInput, HostRoleClass, HostRoleHost } from './host-appr
 export { HOST_ROLE_SEPARATOR, hostAppRoles, hostRoleName } from './host-approles.ts';
 export type { BaoJwtAuthConfigProps } from './jwt-config.ts';
 export { BaoJwtAuthConfig, BaoJwtAuthConfigProvider } from './jwt-config.ts';
-export type { BaoJwtRoleProps, BaoJwtRoleType } from './jwt-role.ts';
+export type {
+  BaoJwtCallbackMode,
+  BaoJwtRoleAttributes,
+  BaoJwtRoleProps,
+  BaoJwtRoleType,
+} from './jwt-role.ts';
 export { BaoJwtRole, BaoJwtRoleProvider } from './jwt-role.ts';
 export type { BaoKubernetesAliasSource, BaoKubernetesRoleProps } from './kubernetes-role.ts';
 export { BaoKubernetesRole, BaoKubernetesRoleProvider } from './kubernetes-role.ts';
@@ -50,10 +57,15 @@ export type { BaoMfaLoginEnforcementProps } from './mfa-enforcement.ts';
 export { BaoMfaLoginEnforcement, BaoMfaLoginEnforcementProvider } from './mfa-enforcement.ts';
 export type { BaoMfaTotpMethodProps, BaoTotpAlgorithm } from './mfa-totp.ts';
 export { BaoMfaTotpMethod, BaoMfaTotpMethodProvider } from './mfa-totp.ts';
+export type { BaoMountAttributes, BaoMountProps } from './mount.ts';
 export { BaoMount, BaoMountProvider } from './mount.ts';
+export type { BaoPkiRoleAttributes, BaoPkiRoleProps } from './pki-role.ts';
 export { BaoPkiRole, BaoPkiRoleProvider } from './pki-role.ts';
-export type { BaoPluginProps, BaoPluginType } from './plugin.ts';
+export type { BaoPluginAttributes, BaoPluginProps, BaoPluginType } from './plugin.ts';
 export { BaoPlugin, BaoPluginProvider } from './plugin.ts';
+export type { BaoPolicyAttributes, BaoPolicyProps } from './policy.ts';
 export { BaoPolicy, BaoPolicyProvider } from './policy.ts';
+export type { BaoProxmoxRoleAttributes, BaoProxmoxRoleProps } from './proxmox-role.ts';
 export { BaoProxmoxRole, BaoProxmoxRoleProvider } from './proxmox-role.ts';
+export type { BaoSshRoleAttributes, BaoSshRoleProps } from './ssh-role.ts';
 export { BaoSshRole, BaoSshRoleProvider } from './ssh-role.ts';

package/src/proxmox/acl.ts

@@ -189,6 +189,8 @@ const ops = pveOperations<AclProps, AclAttributes>({
    *   the props they came from is true by construction. An identity change is a DIFFERENT grant,
    *   which `diff` in the provider handles.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:PUT /access/acl', update: 'pve:PUT /access/acl' },
   matches: (attributes, props) =>
     attributes.bound && attributes.propagate === (props.propagate !== false),
   path: () => 'access/acl',

package/src/proxmox/backup-job.ts

@@ -173,6 +173,8 @@ const handlers = pveHandlers<BackupJobProps, BackupJobAttributes>({
   /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
   createForm: (props) => ({ ...shape(props), id: props.id }),
   /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
   matches: (attributes, props) =>
     attributes.schedule === props.schedule &&
     attributes.enabled === (props.enabled !== false) &&

package/src/proxmox/constraint-guard.ts

@@ -0,0 +1,53 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ★ ONE FILE BETWEEN THE PROVIDERS AND THE GENERATED DATA, so `resource.ts` gains three lines
+ *   rather than an import of two generated modules and a merge, and so a family that writes its
+ *   own handlers (CephPool, PbsDatastore) reaches the same check by the same name.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK. Silently passing would put us back
+ *   where this started: a declaration nothing checked, and a plan that says so in no way at all.
+ *   The generator resolves every key in its source scan against the vendor schema, so a key that
+ *   is absent here means the tables were not regenerated — which the message says.
+ */
+import * as Effect from 'effect/Effect';
+import type { PveForm } from './client.ts';
+import { type EndpointConstraints, type EndpointKey, refusal, violations } from './constraints.ts';
+import { PROXMOX_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { PROXMOX_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = PROXMOX_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/constraints.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+/** Every vendor rule this form breaks. Pure — a test calls it with a literal form. */
+export const formViolations = (
+  key: EndpointKey,
+  form: PveForm,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), form, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition: there is no retry and no fallback that makes a
+ *   129-character comment legal. The same call that refuses a write-back with no read-back
+ *   (resource.ts) dies for the same reason.
+ */
+export const guardForm = (
+  key: EndpointKey | undefined,
+  form: PveForm,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = formViolations(key, form, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });

package/src/proxmox/constraints.test.ts

@@ -0,0 +1,260 @@
+/**
+ * The vendor's own limits, enforced at plan time — built from the failure that made them necessary.
+ *
+ * 🔴 2026-09-22, `homeflare-proxmox` `deploy:pbs`: ten objects adopted, then
+ *   `POST config/verify -> 400: parameter verification failed - comment: value may only be 128
+ *   characters long`. The job was `v-r2-offsite`, the monthly read-back of the R2 copy. Plan,
+ *   `bun run check`, the family's own tests and `hf-adopt-verify` were all green, because the only
+ *   place the number 128 existed was PBS's published schema.
+ *
+ * ★ SO THE FIRST TEST IS THAT JOB, WITH A 129-CHARACTER COMMENT, THROUGH ALCHEMY'S OWN ENGINE, and
+ *   the assertion that matters is not only the message: it is that `fake.writes()` is EMPTY. The
+ *   incident was half a deploy landing before the refusal.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { constraintsFor, formViolations } from './constraint-guard.ts';
+import { type EndpointConstraints, refusal, violations } from './constraints.ts';
+import type { PbsTarget } from './credentials.ts';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import { createForm as datastoreCreateForm } from './pbs-datastore-form.ts';
+import { createBody as pruneCreateBody } from './pbs-prune-job-form.ts';
+import { createBody as syncCreateBody } from './pbs-sync-job-form.ts';
+import { PROXMOX_CONSTRAINTS, PROXMOX_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
+import { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' };
+const VERIFY = 'pbs:POST /config/verify';
+const BELL = String.fromCodePoint(7);
+const ROCKET = String.fromCodePoint(0x1f680);
+
+/** The real declaration, comment length made an argument. */
+const job = (comment: string) =>
+  PbsVerifyJob('v-r2-offsite', {
+    comment,
+    id: 'v-r2-offsite',
+    'ignore-verified': true,
+    'outdated-after': 30,
+    schedule: 'Sun *-1..7 11:00',
+    store: 'r2-offsite',
+    target: PBS,
+  });
+
+describe('the v-r2-offsite failure, refused at plan instead of by the server', () => {
+  const deployWith = async (comment: string) => {
+    /**
+     * A PBS that does not have this job yet, so the plan is a CREATE — the branch `diff` used to
+     * skip entirely (`output === undefined` returned before any check). It remembers the POST so
+     * the read-back in `reconcile` can succeed, which is what the 128-character case needs.
+     */
+    const live = new Map<string, Record<string, unknown>>();
+    const fake = fakePve((call) => {
+      if (call.method === 'GET') return live.get(call.path);
+      if (call.method === 'POST') live.set(`config/verify/${String(call.form['id'])}`, call.form);
+      return undefined;
+    });
+    const engine = engineOver(PbsVerifyJobProvider().pipe(Layer.provideMerge(fake.layer)));
+    const outcome = await withoutBao(() =>
+      engine.deploy(job(comment)).then(
+        () => ({ error: undefined as unknown }),
+        (error: unknown) => ({ error }),
+      ),
+    );
+    return { ...outcome, calls: fake.calls, writes: fake.writes() };
+  };
+
+  test('129 characters is refused, and NOTHING is written', async () => {
+    const { calls, error, writes } = await deployWith('c'.repeat(129));
+    expect(String(error)).toContain('comment: at most 128 characters');
+    expect(String(error)).toContain(VERIFY);
+    // ⛔ THE ASSERTION THE INCIDENT IS ABOUT. A refusal after the POST is the server's own 400.
+    expect(writes).toEqual([]);
+    /**
+     * ⚠️ ONE CALL IS MADE, AND IT IS A GET. Measured 2026-09-22: Alchemy runs the provider's
+     *   `read` handler before `diff`, so the plan has already asked PBS whether the job exists by
+     *   the time the constraint is checked. Every call is a read; nothing is created or changed.
+     */
+    expect(calls.map((call) => call.method)).toEqual(['GET']);
+  });
+
+  test('128 characters is accepted and the create goes through', async () => {
+    const { error, writes } = await deployWith('c'.repeat(128));
+    expect(error).toBeUndefined();
+    expect(writes).toEqual(['POST config/verify']);
+  });
+});
+
+describe('the table is the vendor own rule set, read from the generated file', () => {
+  test('POST /config/verify carries the 128 and the safe-id rules PBS publishes', () => {
+    const table = constraintsFor(VERIFY);
+    expect(table['comment']).toMatchObject({ maxLength: 128, type: 'string' });
+    expect(table['id']).toMatchObject({ maxLength: 32, minLength: 3, required: true });
+    expect(table['max-depth']).toMatchObject({ maximum: 7, minimum: 0 });
+  });
+
+  test('an unknown endpoint is a defect that names the command, not a silent pass', () => {
+    expect(() => constraintsFor('pbs:POST /config/nope')).toThrow('bun codegen/constraints.ts');
+  });
+
+  /**
+   * ⚠️ PBS's `comment` pattern is a POSIX class inside Rust regex delimiters, neither of which
+   *   JavaScript reads the same way. `new RegExp` accepts BOTH silently and means something else.
+   *   This asserts the translation, because a wrong one refuses every legal comment.
+   */
+  test('the PBS comment pattern is translated, not copied', () => {
+    const rule = constraintsFor(VERIFY)['comment'];
+    expect(rule?.patternSource).toContain('cntrl');
+    expect(formViolations(VERIFY, { comment: 'nightly read-back of the R2 copy' }, false)).toEqual(
+      [],
+    );
+    expect(formViolations(VERIFY, { comment: `bell${BELL}here` }, false)).toEqual([
+      `comment: must match ${rule?.patternSource ?? ''}`,
+    ]);
+  });
+
+  /**
+   * ⚠️ THE SORT IS PART OF THE DIGEST, and it is spelled out here rather than imported from
+   *   `codegen/emit.ts`: `src/` is published, and a test that reached out of the package would
+   *   ship a broken import in the tarball. The generator sorts for the same reason it must be
+   *   sorted here — it merges per area, this module spreads per import.
+   */
+  test('the committed tables match their own digest, so no value was hand-edited', () => {
+    const sorted = Object.fromEntries(
+      Object.keys(PROXMOX_CONSTRAINTS)
+        .sort()
+        .map((key) => [key, PROXMOX_CONSTRAINTS[key]]),
+    );
+    const recomputed = new Bun.CryptoHasher('sha256')
+      .update(JSON.stringify(sorted))
+      .digest('hex')
+      .slice(0, 16);
+    expect(recomputed).toBe(PROXMOX_CONSTRAINTS_DIGEST);
+  });
+});
+
+/**
+ * ★ ONE MUTANT PER BRANCH. Each case below fails if that single comparison is deleted, inverted or
+ *   its boundary moved by one — which is the only way to know the validator checks what it claims
+ *   rather than passing everything.
+ */
+describe('every rule kind, at and past its boundary', () => {
+  const table: EndpointConstraints = {
+    depth: { maximum: 7, minimum: 0, type: 'integer' },
+    mode: { enum: ['all', 'any'], type: 'string' },
+    name: { maxLength: 4, minLength: 2, pattern: '^[a-z]+$', patternSource: '/^[a-z]+$/' },
+    store: { required: true, type: 'string' },
+    tags: { maxLength: 3, type: 'string' },
+  };
+  const at = (form: Record<string, string | readonly string[]>, presence = false) =>
+    violations(table, form, { presence });
+
+  test('maxLength: 4 passes, 5 does not', () => {
+    expect(at({ name: 'abcd' })).toEqual([]);
+    expect(at({ name: 'abcde' })).toEqual(['name: at most 4 characters']);
+  });
+
+  test('minLength: 2 passes, 1 does not', () => {
+    expect(at({ name: 'ab' })).toEqual([]);
+    expect(at({ name: 'a' })).toEqual(['name: at least 2 characters']);
+  });
+
+  test('minimum and maximum are inclusive on both sides', () => {
+    expect(at({ depth: '0' })).toEqual([]);
+    expect(at({ depth: '7' })).toEqual([]);
+    expect(at({ depth: '-1' })).toEqual(['depth: at least 0']);
+    expect(at({ depth: '8' })).toEqual(['depth: at most 7']);
+  });
+
+  test('enum quotes the vendor own members', () => {
+    expect(at({ mode: 'any' })).toEqual([]);
+    expect(at({ mode: 'ALL' })).toEqual(['mode: must be one of all, any']);
+  });
+
+  test('pattern reports the VENDOR spelling, not the translated one', () => {
+    expect(at({ name: 'abc' })).toEqual([]);
+    expect(at({ name: 'ab1' })).toEqual(['name: must match /^[a-z]+$/']);
+  });
+
+  test('required is checked only when presence is asked for — an update form is partial', () => {
+    expect(at({})).toEqual([]);
+    expect(at({}, true)).toEqual(['store: required']);
+    expect(at({ store: 'r2' }, true)).toEqual([]);
+  });
+
+  /** ⚠️ Characters, not UTF-16 code units: an astral character is ONE character to Proxmox. */
+  test('length counts characters, so an astral character is one', () => {
+    expect(at({ tags: `${ROCKET}ab` })).toEqual([]);
+    expect(at({ tags: `${ROCKET}abc` })).toEqual(['tags: at most 3 characters']);
+  });
+
+  /** ⚠️ A list is repeated keys on the wire (client.ts), so every element faces the same rule. */
+  test('every element of an array value is checked', () => {
+    expect(at({ tags: ['ab', 'abcd'] })).toEqual(['tags: at most 3 characters']);
+  });
+
+  test('a key the table does not mention is not an error', () => {
+    expect(at({ unlisted: 'anything at all' })).toEqual([]);
+  });
+
+  test('the refusal names the endpoint and points at the generated table', () => {
+    expect(refusal(VERIFY, ['comment: at most 128 characters'])).toContain(VERIFY);
+    expect(refusal(VERIFY, ['comment: at most 128 characters'])).toContain('generated/constraints');
+  });
+});
+
+/**
+ * ★ THE OTHER THREE PBS FAMILIES, WITH THE ESTATE'S OWN DECLARATIONS, AGAINST THEIR CREATE TABLE.
+ *   The risk this feature carries is not the one it fixes: a table that refuses a declaration the
+ *   vendor would have ACCEPTED blocks a deploy that was always legal, and the operator cannot tell
+ *   that from a genuine violation. These are the jobs `homeflare-proxmox` actually declares
+ *   (`prune-cluster-all`, `sync-all-to-r2`, the `r2-offsite` datastore), so a false positive in the
+ *   presence check or a mistranslated pattern fails here rather than on a Sunday morning.
+ */
+describe('the live PBS declarations pass their own create tables', () => {
+  test('prune, sync and datastore create forms have no violations', () => {
+    expect(
+      formViolations(
+        'pbs:POST /config/prune',
+        pruneCreateBody({
+          comment: 'cluster retention',
+          id: 'prune-cluster-all',
+          'keep-daily': 7,
+          'keep-last': 3,
+          'keep-monthly': 6,
+          'keep-weekly': 4,
+          schedule: 'sat 03:00',
+          store: 'cluster',
+          target: PBS,
+        }),
+        true,
+      ),
+    ).toEqual([]);
+    expect(
+      formViolations(
+        'pbs:POST /config/sync',
+        syncCreateBody({
+          comment: 'offsite copy to R2',
+          id: 'sync-all-to-r2',
+          'remote-store': 'r2-offsite',
+          schedule: 'mon 08:30',
+          store: 'cluster',
+          target: PBS,
+        }),
+        true,
+      ),
+    ).toEqual([]);
+    expect(
+      formViolations(
+        'pbs:POST /config/datastore',
+        datastoreCreateForm({
+          comment: 'offsite',
+          name: 'r2-offsite',
+          path: '/mnt/datastore/r2-offsite',
+          target: PBS,
+        }),
+        true,
+      ),
+    ).toEqual([]);
+  });
+});

package/src/proxmox/constraints.ts

@@ -0,0 +1,135 @@
+/**
+ * The vendor's own rules, checked here, before the request is built.
+ *
+ * 🔴 THE INCIDENT THIS EXISTS FOR, 2026-09-22. `homeflare-proxmox`'s first `deploy:pbs` adopted ten
+ *   objects and then failed its one create: `PVE POST config/verify -> 400: parameter verification
+ *   failed - comment: value may only be 128 characters long`. Half a deploy in, on the server, from
+ *   a limit PBS publishes in its own schema and the generated `comment?: string` does not carry.
+ *   Plan was green. `bun run check` was green. `hf-adopt-verify` was green — its offline fake serves
+ *   a fixture and refuses anything but GET, so a newly declared object's VALUES are never exercised.
+ *
+ * ★ SO THE TABLE IS GENERATED AND THIS FILE IS THE READER. `generated/constraints/*` is emitted
+ *   from the cluster's own `apidoc.js` by `bun codegen/constraints.ts`; nothing here is hand-typed,
+ *   because a hand-typed limit is the tribal knowledge that was already in a doc comment and
+ *   already did not run.
+ *
+ * ⛔ IT CHECKS THE FORM, NOT THE PROPS, AND THAT IS THE WHOLE POINT. The form is what goes on the
+ *   wire: `String(props['max-depth'])`, `'0' | '1'` for a boolean, an omitted key for an undeclared
+ *   field. A props-level check would pass values the form then mangles, and would have to be
+ *   written once per family — which is how the copy that forgets a field gets written.
+ *
+ * ⚠️ WHAT IT DELIBERATELY DOES NOT ENFORCE, so nobody reads a green plan as more than it is:
+ *   - a `format` NAME (PVE's `pve-calendar-event`, `pve-node`, 216 of them): the name is a
+ *     validator PVE implements server-side and publishes nothing about. Recorded, never checked.
+ *   - a pattern the generator could not translate faithfully (codegen/pattern.ts). Recorded
+ *     verbatim as `patternSource`, never checked.
+ *   - PBS `schedule`, which carries `typetext: <calendar-event>` and NO pattern and NO maxLength.
+ *     The schema cannot help there; a malformed schedule still reaches PBS.
+ *   Each of those is a fact in the table rather than a guess, which is the rule this follows:
+ *   if the vendor did not state it, it is not enforced and the table says so.
+ */
+import type { PveForm } from './client.ts';
+
+export interface ParamConstraint {
+  readonly type?: string;
+  /** From the vendor's `optional`. ⚠️ Checked on CREATE only — see `violations`. */
+  readonly required?: boolean;
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly enum?: readonly string[];
+  /** A JavaScript-safe translation. Absent when the vendor's dialect could not be carried over. */
+  readonly pattern?: string;
+  /** The vendor's own spelling, always — what a violation message quotes, and the audit trail. */
+  readonly patternSource?: string;
+  /** PVE's server-side validator name. Recorded so a reader knows what is NOT checked here. */
+  readonly format?: string;
+  readonly default?: string;
+}
+
+export type EndpointConstraints = Readonly<Record<string, ParamConstraint>>;
+
+/** `POST /config/verify` — exactly how the generated tables key an endpoint. */
+export type EndpointKey = string;
+
+export interface ViolationOptions {
+  /**
+   * Check that every vendor-required parameter is present.
+   *
+   * ⛔ CREATE ONLY. An update form is deliberately PARTIAL — `formToSend` sends the fields that
+   *   changed and nothing else — so requiring presence there would refuse every ordinary edit.
+   */
+  readonly presence?: boolean;
+}
+
+const lengthOf = (value: string): number => [...value].length;
+
+/**
+ * ⚠️ `[...value].length`, NOT `value.length`. Proxmox counts characters; JavaScript counts UTF-16
+ *   code units, so an emoji in a comment counts twice and a 128-character limit would refuse a
+ *   comment PBS accepts. Rejecting a legal value at plan time is the one failure mode worse than
+ *   the server 400 this replaces.
+ */
+const checkValue = (name: string, value: string, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (rule.maxLength !== undefined && lengthOf(value) > rule.maxLength) {
+    out.push(`${name}: at most ${rule.maxLength} characters`);
+  }
+  if (rule.minLength !== undefined && lengthOf(value) < rule.minLength) {
+    out.push(`${name}: at least ${rule.minLength} characters`);
+  }
+  if (rule.enum !== undefined && !rule.enum.includes(value)) {
+    out.push(`${name}: must be one of ${rule.enum.join(', ')}`);
+  }
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern).test(value)) {
+    out.push(`${name}: must match ${rule.patternSource ?? rule.pattern}`);
+  }
+  // ⚠️ NUMBER-NESS IS NOT CHECKED, ONLY THE BOUND. The form is strings by construction and a
+  //   non-numeric string is a type error upstream; `Number('')` is 0, so a blank would read as in
+  //   range. Guarding on Number.isFinite keeps a blank from silently passing a minimum of 0.
+  const numeric = Number(value);
+  const bounded = rule.minimum !== undefined || rule.maximum !== undefined;
+  if (bounded && value !== '' && Number.isFinite(numeric)) {
+    if (rule.minimum !== undefined && numeric < rule.minimum) {
+      out.push(`${name}: at least ${rule.minimum}`);
+    }
+    if (rule.maximum !== undefined && numeric > rule.maximum) {
+      out.push(`${name}: at most ${rule.maximum}`);
+    }
+  }
+  return out;
+};
+
+/**
+ * Every vendor rule this form breaks, in the order the parameters are declared. Pure: no network,
+ * no clock, no environment — so `diff` can call it and a test can call it with a literal.
+ *
+ * ⚠️ A KEY THE TABLE DOES NOT MENTION IS NOT AN ERROR. The table carries the constrained
+ *   parameters, not every parameter, and a form may legitimately send an unconstrained one.
+ */
+export const violations = (
+  table: EndpointConstraints,
+  form: PveForm,
+  options: ViolationOptions = {},
+): readonly string[] => {
+  const out: string[] = [];
+  for (const [name, rule] of Object.entries(table)) {
+    const value = form[name];
+    if (value === undefined) {
+      if (options.presence === true && rule.required === true) out.push(`${name}: required`);
+      continue;
+    }
+    // ⚠️ AN ARRAY IS REPEATED KEYS ON THE WIRE (client.ts), so every element faces the same rule.
+    for (const item of typeof value === 'string' ? [value] : value) {
+      out.push(...checkValue(name, item, rule));
+    }
+  }
+  return out;
+};
+
+/** The message a plan dies with. ⛔ Names the endpoint, because the rule belongs to the vendor. */
+export const refusal = (endpoint: EndpointKey, found: readonly string[]): string =>
+  `${endpoint} would be rejected by the vendor:\n  - ${found.join('\n  - ')}\n` +
+  "These are the vendor's own limits, read from its published schema " +
+  '(packages/alchemy/src/proxmox/generated/constraints). Fix the declaration.';

package/src/proxmox/firewall-alias.ts

@@ -171,6 +171,11 @@ const handlers = pveHandlers<FirewallAliasProps, FirewallAliasAttributes>({
    *   is identity and case-only drift (see the header); `ipversion` is derived and unwritable.
    *   Comparing either would report an update that no update can settle.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/firewall/aliases',
+    update: 'pve:PUT /cluster/firewall/aliases/{name}',
+  },
   matches: (attributes, props) =>
     attributes.cidr === cidr(props.cidr) && attributes.comment === comment(props.comment),
   /**

package/src/proxmox/generated/constraints/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Every generated Proxmox constraint table, merged — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ *
+ * ⚠️ MERGING IS SAFE ONLY BECAUSE EVERY KEY IS PREFIXED `pve:`/`pbs:`. PVE and PBS both publish
+ *   `PUT /access/acl` and `PUT /access/password` with DIFFERENT rules; an unprefixed merge would
+ *   silently enforce one product's limits on the other's objects.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+import { PVE_ACCESS_CONSTRAINTS } from './pve-access.ts';
+import { PVE_CLUSTER_CONSTRAINTS } from './pve-cluster.ts';
+import { PVE_POOLS_CONSTRAINTS } from './pve-pools.ts';
+import { PVE_STORAGE_CONSTRAINTS } from './pve-storage.ts';
+import { PBS_CONFIG_CONSTRAINTS } from './pbs-config.ts';
+
+export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  ...PVE_ACCESS_CONSTRAINTS,
+  ...PVE_CLUSTER_CONSTRAINTS,
+  ...PVE_POOLS_CONSTRAINTS,
+  ...PVE_STORAGE_CONSTRAINTS,
+  ...PBS_CONFIG_CONSTRAINTS,
+};
+
+/**
+ * sha256 of the merged table, truncated.
+ *
+ * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
+ *   changing a 128 to a 129 by hand is. `tests/schema-manifest.test.ts` recomputes it.
+ */
+export const PROXMOX_CONSTRAINTS_DIGEST = '03f403e0c6b3cf7d';