@homeflare/alchemy 0.14.0 → 0.19.0

package/src/proxmox/resource.ts

@@ -1,16 +1,10 @@
 /**
- * One shape for every PVE object, so the provider can cover Proxmox rather than a corner of it.
+ * The four operations every PVE object shares, and the five handlers that wire them to Alchemy.
  *
- * ⛔ 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.
+ * ★ THE SHAPE THEY READ IS `PveSpec`, IN resource-spec.ts, WITH THE ARGUMENT FOR IT. This file was
+ *   one file until 2026-09-22, when the vendor-constraint guard took it past the 250-line cap; the
+ *   split is by what a reader is doing — declaring an object, or changing how every object is
+ *   written — and the types are re-exported below so no importer moved.
  *
  * ⚠️ 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
@@ -19,92 +13,24 @@
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
-import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { type PveForm, pve } from './client.ts';
-import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
+import { pve } from './client.ts';
+import { specGuards } from './resource-guard.ts';
+import type { PveSpec, WithApiTarget } from './resource-spec.ts';
 import { formToSend } from './update-guard.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;
-};
+export type {
+  PveRequirements,
+  PveSpec,
+  WithApiTarget,
+  WithPbsTarget,
+  WithTarget,
+} from './resource-spec.ts';
 
 export const pveOperations = <Props extends WithApiTarget, Attributes>(
   spec: PveSpec<Props, Attributes>,
 ) => {
+  const { guardCreate, guardUpdate } = specGuards(spec);
+
   /** The live object, or undefined. ⚠️ A 404 and `{"data": null}` are ANSWERS, not failures. */
   const read = (props: Props) =>
     pve<Record<string, unknown>>(
@@ -118,6 +44,15 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
     );
 
   return {
+    /**
+     * ★ EXPORTED SO A FAMILY THAT WRITES ITS OWN `reconcile` REACHES THE SAME CHECK BY THE SAME
+     *   NAME. CephPool, CephFs and ZfsPool all bypass the reconcile below — forked workers, a
+     *   settle loop, a destructive create — and without these two they would be checked at plan
+     *   time and not at apply time, which is exactly the gap an ADOPTED row falls through.
+     */
+    guardCreate,
+    guardUpdate,
+
     read,
 
     // ⚠️ `Input<Props>`, NOT `Props`. At plan time a prop can still be an unresolved Output or
@@ -128,11 +63,28 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
         // ⚠️ A prop can still be an unresolved Output at plan time. Alchemy's own providers guard
         //   with isResolved and skip rather than guess; comparing a placeholder to a live value
         //   reports an update nobody asked for.
-        if (output === undefined || !isResolved(news)) return undefined;
+        if (!isResolved(news)) return undefined;
+        /**
+         * ⛔ THE VENDOR CHECK RUNS BEFORE THE `output === undefined` RETURN, AND THE ORDER IS THE
+         *   WHOLE FIX. `output === undefined` IS the resource Alchemy has no state for — the
+         *   create. Checking after it would leave exactly the case that failed on 2026-09-22
+         *   unchecked, and the refusal would arrive from the server, half a deploy in.
+         */
+        yield* guardCreate(news, output === undefined);
+        yield* guardUpdate(news);
+        if (output === undefined) return undefined;
         const live = yield* read(news);
         // ⚠️ `update`, NOT `create` — Alchemy's Diff admits only noop/update/replace. An object
         //   Alchemy has state for but the cluster does not is drift, and reconcile repairs it.
-        if (live === undefined) return { action: 'update' } as const;
+        if (live === undefined) {
+          /**
+           * ⛔ DRIFT REACHES `reconcile`'s POST, so the create form's required parameters ARE
+           *   about to go on the wire after all. Saying so here rather than leaving it to
+           *   reconcile keeps the refusal in `plan`, where an operator is reading.
+           */
+          yield* guardCreate(news, true);
+          return { action: 'update' } as const;
+        }
         if (spec.matches(live, news)) return { action: 'noop' } as const;
         // An object with no update path cannot be edited in place; say replace and mean it.
         return spec.updateForm === undefined
@@ -143,6 +95,13 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
     reconcile: (news: Props) =>
       Effect.gen(function* () {
         const live = yield* read(news);
+        // ⚠️ CHECKED AGAIN HERE, AND NOT BECAUSE `diff` IS UNTRUSTED. `reconcile` also runs for an
+        //   ADOPTED row, whose diff answer Alchemy discards (verify/fake-engine.ts records it), and
+        //   a family that writes its own reconcile bypasses the one above entirely.
+        // ⛔ AFTER THE READ, BECAUSE THE READ IS WHAT SAYS WHICH REQUEST IS ABOUT TO BE MADE. A GET
+        //   changes nothing, so nothing has been written by the time a violation refuses the plan.
+        yield* guardCreate(news, live === undefined);
+        yield* guardUpdate(news);
         if (live === undefined) {
           yield* pve(
             news.target,

package/src/proxmox/role.ts

@@ -131,6 +131,8 @@ const handlers = pveHandlers<RoleProps, RoleAttributes>({
    *   a plan that reports an update every single time and a deploy that writes the same role back
    *   forever. Cheap insurance against the exact trap named in the header.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /access/roles', update: 'pve:PUT /access/roles/{roleid}' },
   matches: (attributes, props) =>
     canonical(attributes.privs).join(',') === canonical(props.privs).join(','),
   path: (props) => `access/roles/${props.roleid}`,

package/src/proxmox/sdn-apply.ts

@@ -35,6 +35,7 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import { guardSdnApply } from './apply-endpoints.ts';
 import { pve } from './client.ts';
 import type { PveRequirements } from './resource.ts';
 import type { WithTarget } from './resource.ts';
@@ -121,6 +122,9 @@ export const ProxmoxSdnApplyProvider = () =>
           const staged = yield* read(news);
           if (staged.pending === 0) return staged;
 
+          // ⛔ BEFORE THE PUBLISH. The apply takes no body, so this is the lookup rather than a
+          //   value check: a vendor that moved this endpoint fails here, not on three nodes.
+          yield* guardSdnApply;
           yield* pve(news.target, 'provision', 'PUT', 'cluster/sdn');
           /**
            * ⛔ READ BACK, FOR THE SAME REASON THE FACTORY DOES. PVE answers 200 on writes that did

package/src/proxmox/sdn-subnet.ts

@@ -194,6 +194,11 @@ const handlers = pveHandlers<SdnSubnetProps, SdnSubnetAttributes>({
   },
   collection: (props) => `cluster/sdn/vnets/${props.vnet}/subnets`,
   createForm,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/sdn/vnets/{vnet}/subnets',
+    update: 'pve:PUT /cluster/sdn/vnets/{vnet}/subnets/{subnet}',
+  },
   /**
    * ⛔ FIVE REPORTED FIELDS ARE DELIBERATELY ABSENT FROM THIS COMPARISON, and each is a
    *   forever-diff if it goes back in.

package/src/proxmox/sdn-vnet.ts

@@ -193,6 +193,8 @@ const handlers = pveHandlers<SdnVnetProps, SdnVnetAttributes>({
    *   would report an update on every plan until somebody ran the apply, and then report another
    *   one the moment anybody else staged anything at all.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/sdn/vnets', update: 'pve:PUT /cluster/sdn/vnets/{vnet}' },
   matches: (attributes, props) =>
     attributes.zone === props.zone &&
     attributes.alias === (props.alias ?? '') &&

package/src/proxmox/sdn-zone.ts

@@ -210,6 +210,8 @@ const handlers = pveHandlers<SdnZoneProps, SdnZoneAttributes>({
    *   handled above by refusing to recognise a zone of the wrong one. Comparing either here would
    *   produce a diff whose update can never satisfy it.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/sdn/zones', update: 'pve:PUT /cluster/sdn/zones/{zone}' },
   matches: (attributes, props) =>
     attributes.mtu === (props.mtu ?? 0) &&
     attributes.nodes === csv(props.nodes) &&

package/src/proxmox/storage.ts

@@ -217,6 +217,8 @@ const handlers = pveHandlers<StorageProps, StorageAttributes>({
    *   PVE returns the create-only fields on read but refuses them on PUT, so diffing one could only
    *   plan an update that no write can apply: a plan that reports work on every run, forever.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /storage', update: 'pve:PUT /storage/{storage}' },
   matches: (attributes, props) =>
     sameList(props.content, attributes.content) &&
     sameList(props.nodes, attributes.nodes) &&

package/src/proxmox/user.ts

@@ -186,6 +186,8 @@ const handlers = pveHandlers<UserProps, UserAttributes>({
    *   what a PUT can put back; a field that PVE reports but will not accept is drift nobody can
    *   fix, and diffing it would report an update on every plan forever.
    */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /access/users', update: 'pve:PUT /access/users/{userid}' },
   matches: (attributes, props) =>
     attributes.comment === (props.comment ?? '') &&
     attributes.email === (props.email ?? '') &&

package/src/proxmox/zfs-pool-write.ts

@@ -19,6 +19,7 @@
  */
 import * as Effect from 'effect/Effect';
 import { pve } from './client.ts';
+import type { EndpointPair } from './resource-spec.ts';
 import { text } from './values.ts';
 import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
 
@@ -36,6 +37,17 @@ import type { ZfsPoolAttributes, ZfsPoolProps } from './zfs-pool.ts';
  *   are unreadable afterwards either way — but it would put a number in the request that no
  *   declaration asked for, and this is the one call that writes to physical disks.
  */
+/**
+ * The vendor rules the create form is checked against at plan time.
+ *
+ * ⛔ HERE RATHER THAN INLINE IN zfs-pool.ts BECAUSE THAT FILE IS ALREADY OVER THE 250-LINE CAP,
+ *   and a `pve:POST …` literal has to live in a non-test source file for the generator to table
+ *   it at all. The spec imports it on the line it already imports `createForm` from.
+ * ⚠️ NO UPDATE KEY: PVE registers no PUT under `/nodes/{node}/disks/zfs`, which is exactly why
+ *   the spec declares no `updateForm` and a changed prop is a REPLACE.
+ */
+export const ZFS_POOL_ENDPOINT: EndpointPair = { create: 'pve:POST /nodes/{node}/disks/zfs' };
+
 export const createForm = (props: ZfsPoolProps): Record<string, string> => ({
   devices: props.devices.join(','),
   name: props.name,

package/src/proxmox/zfs-pool.ts

@@ -65,7 +65,7 @@ import {
   pveOperations,
 } from './resource.ts';
 import { text } from './values.ts';
-import { createForm, createPool, destroyPool } from './zfs-pool-write.ts';
+import { ZFS_POOL_ENDPOINT, createForm, createPool, destroyPool } from './zfs-pool-write.ts';
 
 /** PVE's layouts. ⚠️ Each has a minimum disk count PVE enforces, and `raid10` needs an even one. */
 export type ZfsRaidLevel =
@@ -213,6 +213,7 @@ const spec: PveSpec<ZfsPoolProps, ZfsPoolAttributes> = {
   },
   collection: (props) => `nodes/${props.node}/disks/zfs`,
   createForm,
+  endpoint: ZFS_POOL_ENDPOINT,
   /**
    * ⛔ IT ALWAYS ANSWERS TRUE, AND THAT IS THE POINT OF THIS FILE. A pool that is there under the
    *   declared name on the declared node IS the declaration, because there is nothing else the two