@homeflare/alchemy 0.14.0 → 0.19.0

package/src/proxmox/constraints.test.ts

@@ -0,0 +1,205 @@
+/**
+ * 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';
+// ⚠️ The estate's own declarations live in constraints-live.test.ts — split at the 250-line cap.
+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 { 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([]);
+    /**
+     * ⚠️ EVERY CALL IS A READ, AND THERE ARE NOW TWO OF THEM. Measured 2026-09-22: Alchemy runs
+     *   the provider's `read` handler first, and `reconcile` reads again — the guard moved to
+     *   AFTER that second read the same day, because the read is the only thing that says whether
+     *   a create or an update is about to be made, and demanding the create form's required
+     *   parameters on an update refuses edits that were always legal (resource-guard.ts).
+     *   ⛔ THE COUNT IS NOT THE ASSERTION; THE METHOD IS. Nothing is created or changed.
+     */
+    expect(calls.map((call) => call.method)).toEqual(['GET', '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');
+  });
+});

package/src/proxmox/constraints.ts

@@ -0,0 +1,160 @@
+/**
+ * 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. The
+ *   full kind-by-kind table, with the counts measured over the 37 tabled endpoints, is in
+ *   codegen/README.md. The short version:
+ *   - a `format` NAME (PVE's `pve-calendar-event`, `pve-node`; 105 parameters here): the name is a
+ *     validator PVE implements server-side and publishes nothing about. Recorded, never checked.
+ *   - a `format` OBJECT — PBS's `notify`, `tuning`, `maintenance-mode`, PVE's `bwlimit`; 10
+ *     parameters. It is a sub-schema for the inside of a PROPERTY STRING, and the packed keys
+ *     carry their own limits. Not flattened, because a rule about `notify` is not a rule about
+ *     `notify.gc`. ⛔ This is the largest remaining gap and it is a gap on purpose.
+ *   - `requires` (8 parameters): "this one needs that one". A dependency, not a value rule.
+ *   - `typetext` with nothing else, such as PBS `schedule`'s `<calendar-event>` (21 parameters).
+ *     The schema states a syntax it does not describe; a malformed schedule still reaches PBS.
+ *   - a pattern the generator could not translate faithfully (codegen/pattern.ts). Recorded
+ *     verbatim as `patternSource`, never checked.
+ *   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 EQUIVALENT. Absent when the vendor's dialect could not be carried over.
+   *
+   * ⛔ NOT THE VENDOR'S SPELLING, AND FOR PVE NOT EVEN THE SAME SHAPE. PVE publishes the inside of
+   *   an anchored match and applies `m/^$pattern$/` itself (MEASURED in JSONSchema.pm), so the
+   *   generator anchors it here. Quote `patternSource` at a human, never this.
+   */
+  readonly pattern?: string;
+  /** `m` when the vendor asked for multi-line. ⚠️ Dropping it enforces the wrong semantics. */
+  readonly patternFlags?: 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;
+  /**
+   * The value rules describe each ELEMENT of a repeated key, not one joined string.
+   *
+   * ⚠️ RECORDED, NOT BRANCHED ON. `violations` already checks every element of an array value, so
+   *   this changes no behaviour — it tells a reader of the generated table why a `maxLength` of 32
+   *   sits on a parameter that carries a list.
+   */
+  readonly each?: true;
+}
+
+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(', ')}`);
+  }
+  // ⚠️ `patternFlags` IS PASSED, NOT IGNORED. It carries the vendor's own `(?m)`; enforcing a
+  //   multi-line rule with single-line semantics refuses values the vendor accepts.
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern, rule.patternFlags).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,55 @@
+/**
+ * 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_BACKUP_CONSTRAINTS } from './pve-cluster-backup.ts';
+import { PVE_CLUSTER_CEPH_CONSTRAINTS } from './pve-cluster-ceph.ts';
+import { PVE_CLUSTER_FIREWALL_CONSTRAINTS } from './pve-cluster-firewall.ts';
+import { PVE_CLUSTER_HA_CONSTRAINTS } from './pve-cluster-ha.ts';
+import { PVE_CLUSTER_METRICS_CONSTRAINTS } from './pve-cluster-metrics.ts';
+import { PVE_CLUSTER_NOTIFICATIONS_CONSTRAINTS } from './pve-cluster-notifications.ts';
+import { PVE_CLUSTER_REPLICATION_CONSTRAINTS } from './pve-cluster-replication.ts';
+import { PVE_CLUSTER_SDN_CONSTRAINTS } from './pve-cluster-sdn.ts';
+import { PVE_NODES_CEPH_CONSTRAINTS } from './pve-nodes-ceph.ts';
+import { PVE_NODES_DISKS_CONSTRAINTS } from './pve-nodes-disks.ts';
+import { PVE_NODES_LXC_CONSTRAINTS } from './pve-nodes-lxc.ts';
+import { PVE_NODES_NETWORK_CONSTRAINTS } from './pve-nodes-network.ts';
+import { PVE_NODES_QEMU_CONSTRAINTS } from './pve-nodes-qemu.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_BACKUP_CONSTRAINTS,
+  ...PVE_CLUSTER_CEPH_CONSTRAINTS,
+  ...PVE_CLUSTER_FIREWALL_CONSTRAINTS,
+  ...PVE_CLUSTER_HA_CONSTRAINTS,
+  ...PVE_CLUSTER_METRICS_CONSTRAINTS,
+  ...PVE_CLUSTER_NOTIFICATIONS_CONSTRAINTS,
+  ...PVE_CLUSTER_REPLICATION_CONSTRAINTS,
+  ...PVE_CLUSTER_SDN_CONSTRAINTS,
+  ...PVE_NODES_CEPH_CONSTRAINTS,
+  ...PVE_NODES_DISKS_CONSTRAINTS,
+  ...PVE_NODES_LXC_CONSTRAINTS,
+  ...PVE_NODES_NETWORK_CONSTRAINTS,
+  ...PVE_NODES_QEMU_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 = '33b42b52d396c9e0';