@homeflare/alchemy 0.13.0 → 0.15.0

package/src/github/repo-policy-guards.ts

@@ -0,0 +1,179 @@
+/**
+ * Everything `repoPolicy` refuses, and why. Extracted from repo-policy-form.ts so the
+ * shape stays readable and the reasoning stays whole.
+ *
+ * ⛔ FIVE DIFFERENT DOORS LEAD TO THE SAME FAILURE — auto-merge with nothing to wait for.
+ *   `gh pr merge --auto` is a queue only while something is outstanding; with nothing
+ *   outstanding GitHub merges the pull request on the spot. An empty `checks` is the
+ *   obvious door. `enforcement: 'disabled'` or `'evaluate'` is the quiet one: the ruleset
+ *   exists, the required checks are listed on it, and none of them block anything. Then
+ *   three ways to end up with a ruleset that matches NO REF — which enforces on no ref
+ *   while the GitHub UI still shows it as `active`: an empty `include`, a blank ref
+ *   pattern, and an `exclude` that cancels every `include`. All five are refused.
+ *
+ * ★ THE REF DOORS WERE FOUND BY ADVERSARIAL REVIEW, NOT BY DESIGN. The first cut of this
+ *   module guarded `include.length === 0` and spread `exclude` raw, so
+ *   `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` and `include: ['   ']`
+ *   both sailed through with `allowAutoMerge: true` — the exact end state the empty-array
+ *   guard exists to prevent, reached by a door beside it. Checked by execution, not by
+ *   reading: see the `matches no ref` tests in repo-policy-form.test.ts.
+ */
+
+/** A non-empty, trimmed identifier, or an error naming the field. */
+export function requireName(field: string, value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === '') throw new Error(`repoPolicy: ${field} is required`);
+  return trimmed;
+}
+
+/**
+ * Trim, de-duplicate, sort. ★ The sort is what makes a second deploy a no-op: GitHub
+ * stores the contexts in the order they were sent, so an unsorted list would diff against
+ * itself the first time a caller wrote the same contexts in a different order.
+ */
+export function normalizeChecks(checks: readonly string[]): string[] {
+  const seen = new Set<string>();
+  for (const raw of checks) {
+    const context = raw.trim();
+    // ⚠️ A blank context is a typo that reads as coverage: GitHub happily stores it and
+    //   no job ever reports it, so every pull request waits on a check that cannot come.
+    if (context === '') {
+      throw new Error(
+        'repoPolicy: a required check context is blank — name it exactly as the job reports it',
+      );
+    }
+    seen.add(context);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * Trim, de-duplicate, sort one list of ref patterns, refusing a blank one.
+ *
+ * ⚠️ A BLANK PATTERN IS NOT AN EMPTY LIST, AND THAT IS THE WHOLE TRAP. `['   ']` has
+ *   length 1, so a guard that counts the array waves it through; GitHub then stores a ref
+ *   condition that matches nothing. Same end state as `[]`, reached past the guard.
+ * ★ Sorted for the same reason `normalizeChecks` is: GitHub echoes the patterns back in
+ *   the order they were sent, so an unsorted list diffs against itself the first time a
+ *   caller writes the same patterns in a different order.
+ */
+function normalizeRefs(field: string, patterns: readonly string[]): string[] {
+  const seen = new Set<string>();
+  for (const raw of patterns) {
+    const pattern = raw.trim();
+    if (pattern === '') {
+      throw new Error(
+        `repoPolicy: a ${field} ref pattern is blank — a ruleset that matches no ref enforces nothing.`,
+      );
+    }
+    seen.add(pattern);
+  }
+  return [...seen].sort();
+}
+
+/**
+ * ⛔ AN EMPTY `include` IS REFUSED. Alchemy defaults `conditions.include` to `['~ALL']`
+ *   when it is absent, but an explicitly empty array is sent as an empty array, and a
+ *   ruleset that matches no ref protects nothing while still reading as `active` in the
+ *   GitHub UI — the worst possible combination, because it looks like it worked.
+ */
+export function normalizeInclude(
+  include: readonly string[] | undefined,
+  fallback: readonly string[],
+): string[] {
+  if (include === undefined) return [...fallback];
+  if (include.length === 0) {
+    throw new Error(
+      'repoPolicy: include is empty — a ruleset that matches no ref enforces nothing. Omit it for the default branch.',
+    );
+  }
+  return normalizeRefs('include', include);
+}
+
+/**
+ * ⛔ AN `exclude` THAT CANCELS EVERY `include` IS REFUSED. In a GitHub ruleset the
+ *   exclusions win, so `include: ['~DEFAULT_BRANCH'], exclude: ['~DEFAULT_BRANCH']` is a
+ *   ruleset over nothing — and it reads as a narrowing, which is what makes it worse than
+ *   the empty array: the caller believes they scoped the policy, not switched it off.
+ *
+ * ⚠️ EXACT CANCELLATION ONLY, DELIBERATELY. GitHub's patterns are globs, so deciding in
+ *   general whether some exclude swallows some include means implementing GitHub's
+ *   matcher and being wrong about it quietly. This refuses the case that is decidable —
+ *   every include pattern also appears verbatim in `exclude` — and leaves
+ *   `exclude: ['refs/heads/*']` against `include: ['~DEFAULT_BRANCH']` to the operator.
+ *   A narrower guard that is always right beats a broad one that false-refuses.
+ */
+export function normalizeExclude(
+  exclude: readonly string[] | undefined,
+  include: readonly string[],
+): string[] {
+  const patterns = exclude === undefined ? [] : normalizeRefs('exclude', exclude);
+  if (patterns.length === 0) return patterns;
+  const excluded = new Set(patterns);
+  if (include.every((pattern) => excluded.has(pattern))) {
+    throw new Error(
+      [
+        'repoPolicy: exclude cancels every include pattern, so the ruleset matches no ref and enforces nothing.',
+        `include ${JSON.stringify(include)} is fully covered by exclude ${JSON.stringify(patterns)}.`,
+      ].join(' '),
+    );
+  }
+  return patterns;
+}
+
+/**
+ * ⛔ `0` IS REFUSED, NOT TREATED AS "NO REVIEWS". A `pull_request` rule with zero
+ *   approvals is the solo-maintainer shape — every change through a PR, no second person
+ *   — and it only works with `require_extra_approval_for_unattributed_changes: false`.
+ *   alchemy@2.0.0-beta.79's `Ruleset` cannot express that field, and GitHub defaults it
+ *   to `true` when it is omitted (measured 2026-09-17), which blocks the very PRs the
+ *   zero was meant to let through. Omitting `requiredApprovals` declares no rule at all,
+ *   which is a different and honest thing.
+ */
+export function resolveApprovals(requested: number | undefined): number | undefined {
+  if (requested === undefined) return undefined;
+  if (!Number.isInteger(requested) || requested < 1) {
+    throw new Error(
+      [
+        'repoPolicy: requiredApprovals must be a whole number of 1 or more.',
+        'Omit it to declare no pull_request rule.',
+        '0 is not that: it needs require_extra_approval_for_unattributed_changes: false,',
+        'which alchemy@2.0.0-beta.79 cannot send and GitHub defaults to true.',
+      ].join(' '),
+    );
+  }
+  return requested;
+}
+
+/**
+ * ⚠️ THE TEST IS "SOMETHING OUTSTANDING", NOT "SOME CHECKS". A required review holds a
+ *   pull request open just as a required check does, so `requiredApprovals` with an empty
+ *   `checks` is a legitimate policy. What is refused is auto-merge over a ruleset that
+ *   will not hold anything back.
+ */
+export function assertAutoMergeWaits(input: {
+  readonly autoMerge: boolean;
+  readonly checkCount: number;
+  readonly approvals: number | undefined;
+  readonly enforcement: 'active' | 'disabled' | 'evaluate';
+}): void {
+  if (!input.autoMerge) return;
+  if (input.enforcement !== 'active') {
+    throw new Error(
+      [
+        `repoPolicy: autoMerge with enforcement '${input.enforcement}' merges every pull request immediately.`,
+        'A ruleset that is not active enforces none of its rules, so auto-merge has nothing to wait for.',
+        'Pass autoMerge: false while the ruleset is being evaluated.',
+      ].join(' '),
+    );
+  }
+  if (input.checkCount === 0 && input.approvals === undefined) {
+    throw new Error(
+      [
+        'repoPolicy: autoMerge with nothing required merges every pull request immediately.',
+        'Name at least one always-reporting check context, or ask for requiredApprovals,',
+        'or pass autoMerge: false for a repository that has no green run to require yet.',
+      ].join(' '),
+    );
+  }
+}

package/src/github/repo-policy.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The declaring half, and the two docs that carry its traps.
+ *
+ * ★ WHY TEST A DOC. Both files ship in the tarball and are the only place a consumer is
+ *   told that the vendor ruleset adopts nothing and that auto-merge with nothing required
+ *   merges on the spot. A silent edit that drops either warning would fail nothing else
+ *   in this repo, and would cost the consumer a duplicate ruleset or a PR merged on red.
+ * ⛔ THE HAZARDS LIVE IN A SIBLING FILE, AND THE POINTER IS TESTED TOO. Extracting them
+ *   is only safe while `repo-policy.md` still sends the reader there; a dangling pointer
+ *   would read as "no hazard" rather than as a broken link.
+ */
+import { describe, expect, test } from 'bun:test';
+import { declareRepoPolicy } from './index.ts';
+
+const doc = await Bun.file(new URL('../../docs/repo-policy.md', import.meta.url)).text();
+const hazards = await Bun.file(
+  new URL('../../docs/repo-policy-ruleset-hazards.md', import.meta.url),
+).text();
+
+describe('declareRepoPolicy', () => {
+  test('is a function, not a factory that reaches GitHub at import time', () => {
+    // ⚠️ Importing this module must not construct a resource or an Octokit client: the
+    //   barrel is loaded by the consumer smoke test with no credentials in the process.
+    expect(typeof declareRepoPolicy).toBe('function');
+    expect(declareRepoPolicy.length).toBe(2);
+  });
+});
+
+describe('docs/repo-policy.md', () => {
+  test('stays under the 200-line cap', () => {
+    expect(doc.split('\n').length).toBeLessThanOrEqual(200);
+  });
+
+  test('warns that auto-merge with nothing required merges immediately', () => {
+    expect(doc).toContain('auto-merge');
+    expect(doc).toMatch(/merges? (the pull request )?immediately/i);
+  });
+
+  test('sends the reader to the ruleset hazards, which is where they now live', () => {
+    expect(doc).toContain('repo-policy-ruleset-hazards.md');
+    expect(doc).toMatch(/cannot be adopted/i);
+  });
+});
+
+describe('docs/repo-policy-ruleset-hazards.md', () => {
+  test('stays under the 200-line cap', () => {
+    expect(hazards.split('\n').length).toBeLessThanOrEqual(200);
+  });
+
+  test('warns that the vendor ruleset cannot be adopted and duplicates instead', () => {
+    expect(hazards).toContain('createRepoRuleset');
+    expect(hazards).toContain('rulesets');
+  });
+
+  test('carries the preflight that keeps a first deploy from duplicating', () => {
+    expect(hazards).toContain('gh api repos/<owner>/<repo>/rulesets');
+  });
+});

package/src/github/repo-policy.ts

@@ -0,0 +1,65 @@
+/**
+ * `declareRepoPolicy` — the policy from repo-policy-form.ts, as resources.
+ *
+ *     const policy = yield* declareRepoPolicy('api', {
+ *       owner: 'my-org',
+ *       repository: 'api',
+ *       checks: ['ci', 'secret scan'],
+ *     });
+ *
+ * Provide `GitHub.providers()`; this subpath adds no provider of its own.
+ *
+ * ⛔ THE RULESET CANNOT BE ADOPTED, AND A FIRST DEPLOY ONTO A REPO THAT ALREADY HAS ONE
+ *   MAKES A SECOND. Read out of alchemy@2.0.0-beta.79's own source on 2026-09-22
+ *   (`node_modules/alchemy/lib/github/Ruleset.js`): `read` returns `undefined` whenever
+ *   there is no prior output, and `reconcile` looks the live ruleset up only BY THE ID IN
+ *   THAT OUTPUT — with none, it calls `createRepoRuleset` unconditionally. GitHub permits
+ *   several rulesets with the same name on one repository, so nothing errors; the repo
+ *   quietly ends up with two, both enforcing.
+ *   ★ SO, BEFORE THE FIRST DEPLOY: `gh api repos/<owner>/<repo>/rulesets` and delete a
+ *     hand-made ruleset of the same name, or give this one a `rulesetName` of its own.
+ *     Afterwards the state carries the id and every later deploy converges that one.
+ *   ⚠️ `GitHub.Repository` does NOT share the problem — its `reconcile` probes by name
+ *     and converges onto whatever is live — so only half of this helper is adopt-safe,
+ *     and the halves fail differently. See docs/repo-policy.md.
+ *
+ * ⛔ BOTH RESOURCES RETAIN. `retain` is already the vendor default for each of them; it
+ *   is piped anyway so that a vendor change cannot quietly turn "drop this call from the
+ *   stack" into "delete the repository" or "unprotect the default branch".
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import * as GitHub from 'alchemy/GitHub';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { type RepoPolicyOptions, repoPolicy } from './repo-policy-form.ts';
+
+export interface DeclareRepoPolicyOptions extends RepoPolicyOptions {
+  /**
+   * `true`/`false` pipe `adopt(…)` onto both resources; omitted, the deploy's own policy
+   * decides. ⚠️ It changes nothing about the ruleset hazard above: adoption routes on
+   * what a provider's `read` reports, and this one reports nothing without prior state.
+   */
+  readonly adopt?: boolean;
+}
+
+/**
+ * Declares the repository and its ruleset under `<id>` and `<id>-ruleset`. Fails, before
+ * declaring either, on any policy the form refuses.
+ */
+export const declareRepoPolicy = (id: string, options: DeclareRepoPolicyOptions) =>
+  Effect.gen(function* () {
+    const policy = yield* Effect.try({
+      catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+      try: () => repoPolicy(options),
+    });
+    // ⚠️ `never` in the error channel, not a generic `E`: `AdoptPolicy.adopt` is typed
+    //   `Effect<A, never, R> => Effect<A, never, R>`, so a wider error type fails to
+    //   compile here rather than at the call site. Alchemy's resources declare `never`.
+    const owned = <A, R>(resource: Effect.Effect<A, never, R>) => {
+      const kept = resource.pipe(RemovalPolicy.retain());
+      return options.adopt === undefined ? kept : kept.pipe(adopt(options.adopt));
+    };
+    const repository = yield* owned(GitHub.Repository(id, policy.repository));
+    const ruleset = yield* owned(GitHub.Ruleset(`${id}-ruleset`, policy.ruleset));
+    return { policy, repository, ruleset };
+  });

package/src/index.ts

@@ -6,6 +6,7 @@
  *
  *     import { R2BucketLock } from '@homeflare/alchemy/cloudflare';
  *     import { BranchProtection } from '@homeflare/alchemy/forgejo';
+ *     import { declareRepoPolicy } from '@homeflare/alchemy/github';
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';

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