@homeflare/alchemy 0.1.0

package/src/proxmox/replication-job.ts

@@ -0,0 +1,248 @@
+/**
+ * `Proxmox.ReplicationJob` — a guest's ZFS storage replication to a second node, declared.
+ *
+ * ⛔ NOTHING ON TB4 CAN USE THIS FAMILY, AND THAT IS SAID HERE RATHER THAN FOUND OUT LATER. PVE
+ *   storage replication is ZFS-only: `POST /cluster/replication` calls `get_replicatable_volumes`
+ *   and refuses a guest whose disks are anywhere else with "No replicatable volumes found". TB4 is
+ *   Ceph/RBD-backed — shared storage, where replication means nothing because every node already
+ *   sees the volume — so `GET /cluster/replication` answers `[]` (MEASURED on n2, 2026-09-13) and
+ *   on this cluster always will. The file is written for a ZFS cluster; against TB4 a declaration
+ *   is a create that fails with PVE's own sentence, not a plan that quietly does nothing.
+ *
+ * ★ WHAT IS MEASURED HERE AND WHAT IS REASONED. Measured on n2 (pve-manager 9.2.11), read-only:
+ *   the published schema for all five methods; `PVE/ReplicationConfig.pm` and
+ *   `PVE/API2/ReplicationConfig.pm` line by line; `GET /cluster/replication` -> `[]`; and the ACL
+ *   row `{"path":"/","propagate":1,"roleid":"PVEAuditor","ugid":"hf-read@pve"}`. NOT measured: any
+ *   round trip. There is no live job to adopt and none can be created on this cluster, so the
+ *   argument that a matching declaration plans as `noop` rests on the schema and on PVE's own
+ *   source — not on a plan anybody ran. Nobody should claim otherwise until a ZFS cluster exists.
+ *
+ * ⛔ THE ID IS STRUCTURED AND PVE RE-SPELLS IT, so this resource is keyed on the two numbers rather
+ *   than on the string — a deliberate break from `backup-job.ts`'s "props are PVE's own key names".
+ *   MEASURED: `parse_replication_job_id` matches `^(\d+)-(\d+)$`, runs BOTH halves through `int()`
+ *   and returns "$guest-$jobnum", and `parse_section_header` does the same when reading
+ *   replication.cfg. So a declared `100-007` is read back as `100-7`, and a provider holding the
+ *   raw string would compare two spellings of one id forever. Two numbers cannot be spelled two
+ *   ways. PVE also refuses `guest < 100` ("guest IDs < 100 are reserved") and the API pattern
+ *   `[1-9][0-9]{2,8}-\d{1,9}` caps both halves at nine digits.
+ *   ⛔ BOTH HALVES ARE REQUIRED AND NEITHER IS DEFAULTED, for `backup-job.ts`'s reason: a provider
+ *     that picks a job number picks a DIFFERENT job from the one a person meant, and then adopts or
+ *     creates beside the real one. Declare the numbers of the job you mean.
+ *
+ * ⛔ PVE'S `target` AND THIS PACKAGE'S `target` ARE DIFFERENT THINGS, AND THE COMPILER SAID SO
+ *   BEFORE A REVIEWER DID. Every resource here extends `WithTarget`, whose `target` is the CLUSTER
+ *   a call goes to (`PveTarget`, carrying the API base and the credential mount). PVE's replication
+ *   `target` is a NODE NAME. They cannot both be called `target` in one props interface — tsc:
+ *   "Interface 'ReplicationJobProps' incorrectly extends interface 'WithTarget'" — so the prop and
+ *   the attribute are `targetNode`, and PVE's spelling appears exactly once, in `createBody`, where
+ *   it is the wire key. That is the only safe shape: had the collision been resolvable by silence,
+ *   `createForm` would have serialised a whole `PveTarget` object into a form field called `target`
+ *   and PVE would have answered that the node does not exist.
+ *
+ * ⛔ ONE JOB PER (GUEST, TARGET), ENFORCED BY PVE AND NOT BY THIS FILE. MEASURED: `write_config`
+ *   dies "replication job for guest '$vmid' to target '$tid' already exists" where `$tid` is
+ *   `local/<target>`, and `parse_config` DELETES the loser on read if two ever reach the file. Two
+ *   declarations differing only in `jobnum` but naming the same target are not two jobs; the second
+ *   is a create that fails.
+ *
+ * ⚠️ RECONCILE NEEDS `VM.Replicate` ON `/vms/<guest>`, WHICH `LXCProvisioner` DOES NOT HOLD. All
+ *   three writes check it (MEASURED in API2/ReplicationConfig.pm: create, update and delete each
+ *   call `$rpcenv->check($authuser, "/vms/$vmid", ['VM.Replicate'])`), and the role's 27 privileges
+ *   include `VM.Allocate`, `VM.Audit`, `VM.Backup`, `VM.Config.*` and `VM.PowerMgmt` but not
+ *   `VM.Replicate`. Widen it deliberately over SSH, preserving what is there, as `pool.ts` records:
+ *   `pveum role modify LXCProvisioner --privs "<existing>,VM.Replicate"`.
+ *   ★ THE READ LANE NEEDS NOTHING EXTRA, which is why there is no `readRole` below. The ITEM read
+ *     checks `VM.Audit` on `/vms/<guest>`, `hf-read@pve` holds the built-in `PVEAuditor` at `/`
+ *     with propagate — both MEASURED — and `PVEAuditor` carries `VM.Audit`. This family is not a
+ *     fourth one that must borrow the provision lease.
+ *   ⚠️ A MISSING JOB IS A 500, NOT A 404 — "no such replication job '100-0'" — and the factory
+ *     folds any failed read into "absent", so a 403 reads as absent too. A plan insisting on
+ *     creating a job that plainly exists is a credential problem; the honest error arrives one step
+ *     later, from the create.
+ *
+ * ⛔ DELETE DOES NOT DELETE, AND A DESTROY IS NOT FREE. MEASURED: with neither `force` nor `keep` —
+ *   and the factory's `destroy` sends no form at all — the handler only sets `remove_job = 'full'`
+ *   on the job and writes the config back. The job stays in replication.cfg until the SOURCE node's
+ *   `pvesr` timer next runs it, at which point it removes the local replication snapshots, removes
+ *   the replicated volumes on the target, and finally removes itself. So a destroy costs the
+ *   standby copy and the incremental base: re-declaring the job afterwards is a FULL send, not a
+ *   resume. The guest's own disks are untouched, which is exactly why this family does NOT carry
+ *   `defaultRemovalPolicy: 'retain'` the way `ZfsPool` and `Storage` do — what it destroys is a
+ *   copy a re-sync rebuilds, expensively, rather than something irreplaceable.
+ *   ⚠️ AND IF THE SOURCE NODE IS DOWN THE REMOVAL NEVER RUNS. Alchemy drops the state row on a
+ *     DELETE that returned no error, so a destroy against a dead source leaves a marked job on the
+ *     cluster that nothing declares any more. `GET /cluster/replication` is where it shows up.
+ *
+ * ⚠️ THE RUNTIME STATUS IS NOT HERE, AND NOT BECAUSE IT WAS FORGOTTEN. `last_sync`, `last_try`,
+ *   `fail_count`, `error`, `duration` and `pid` come from the per-node replication STATE file and
+ *   are merged in by `GET /nodes/{node}/replication` (MEASURED: API2/Replication.pm line 179,
+ *   `foreach my $k (qw(last_sync last_try fail_count error duration))`). `GET
+ *   /cluster/replication/{id}` — the only endpoint this resource reads — returns not one of them.
+ *   Reporting them would mean a second, per-node call on the read path answering a different value
+ *   every fifteen minutes, and a plan whose output changes when nothing changed is a plan people
+ *   stop reading. Ask the node for status; ask the cluster for configuration.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { DEFAULT_SCHEDULE, createBody, jobId, updateBody } from './replication-job-form.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { bool, int, text } from './values.ts';
+
+export interface ReplicationJobProps extends WithTarget {
+  /** ⛔ The guest being replicated. 100 or above — PVE reserves everything below. Identity. */
+  guest: number;
+  /** ⛔ The job number within that guest, 0 upwards. Identity. Never generated — see the header. */
+  jobnum: number;
+  /**
+   * ⛔ THE NODE THE COPY LANDS ON — PVE's `target`, RENAMED; see the ⛔ in the header — AND IT IS
+   *   CREATE-ONLY. MEASURED: the plugin declares `target => { fixed => 1, optional => 0 }`, so
+   *   `updateSchema()` omits it entirely — `PUT` has no `target` parameter at all, and
+   *   `delete=target` answers "unable to delete fixed option". It is therefore NOT compared; see
+   *   the ⚠️ on `matches`. Changing it in a declaration plans as NOOP. Retire the declaration and
+   *   add another, exactly as `user.ts` says for `userid`.
+   * ⚠️ PVE refuses a target equal to the guest's current node ("Source and target must not be
+   *   identical") and one that is not a cluster member. Neither is checkable from here.
+   */
+  targetNode: string;
+  /**
+   * A subset of systemd calendar events. Unset means PVE's own default — `DEFAULT_SCHEDULE`,
+   * every fifteen minutes — and that default is what gets SENT and compared, not silence.
+   * ⚠️ THIS COMPARES STRINGS, NOT MEANINGS. A calendar event has many equivalent spellings and
+   *   PVE stores the one it was handed, verbatim, so declare the spelling the cluster echoes.
+   */
+  schedule?: string;
+  /** Rate limit in mbps as a float, 1 or above. Unset sends nothing and compares nothing. */
+  rate?: number;
+  /** Keep the job but stop replicating. Unset is an ACTIVE job, and that is what is compared. */
+  disable?: boolean;
+  /** Free text shown in the UI. Round-trips through PVE's `encode_text`/`decode_text`. */
+  comment?: string;
+}
+
+export interface ReplicationJobAttributes {
+  /** `100-0`, in PVE's own int-parsed spelling. */
+  id: string;
+  /**
+   * ⚠️ REPORTED AS INTEGERS, NEVER COMPARED, AND THIS IS THE "id written as a name" TRAP. MEASURED:
+   *   `parse_config` sets both from the section header via `int()`, so they are the id re-spelled
+   *   as numbers and no write accepts either. Compared against anything they would be an update
+   *   forever; reported, they let a plan say which guest is about to lose a replica.
+   */
+  guest: number;
+  jobnum: number;
+  /** Always `local` — the only section type PVE registers. Create-only, reported, not compared. */
+  type: string;
+  /**
+   * ⚠️ REPORTED, NEVER COMPARED. Create-only AND rewritten by PVE — see `matches`. Named for the
+   *   prop rather than for PVE's wire key `target`, so that one file never means two things by one
+   *   word; the header says why the wire name could not be kept.
+   */
+  targetNode: string;
+  /** ⚠️ REPORTED, NEVER SENT. PVE's own bookkeeping — see the ⛔ in replication-job-form.ts. */
+  source: string;
+  schedule: string;
+  /** 0 when unset. See `rateOf`. */
+  rate: number;
+  disable: boolean;
+  comment: string;
+  /**
+   * `''`, `local` or `full`. ⛔ NOT COSMETIC: a non-empty value is a job that is deleting itself,
+   *   so `matches` refuses it and `updateBody` clears it. See both.
+   */
+  remove_job: string;
+}
+
+export interface ProxmoxReplicationJob extends Resource<
+  'Proxmox.ReplicationJob',
+  ReplicationJobProps,
+  ReplicationJobAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxReplicationJob = Resource<ProxmoxReplicationJob>('Proxmox.ReplicationJob');
+
+/**
+ * ⚠️ `rate` IS THE ONLY FLOAT IN THIS PACKAGE, so it gets a coercion of its own rather than a sixth
+ *   entry in `values.ts` — the rule that module states for itself: a coercion only one PVE object
+ *   needs belongs in that object's file, next to the field it serves. `int` cannot serve it, since
+ *   `Number.parseInt('10.5')` is 10 and a rate silently rounded down is both a limit nobody chose
+ *   and a comparison that never settles. It accepts a string for the reason `int` does: these are
+ *   SectionConfig sections, and whether `10` arrives as a number is a property of the release.
+ * ⚠️ 0 MEANS UNSET, and is safe as the marker because PVE's schema gives `rate` a minimum of 1 —
+ *   the same trick as `metric-server.ts`'s `UNSET = -1`, for the same reason.
+ */
+const rateOf = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  const parsed = Number.parseFloat(text(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+const handlers = pveHandlers<ReplicationJobProps, ReplicationJobAttributes>({
+  /**
+   * ⚠️ EVERY FALLBACK IS PVE'S DOCUMENTED DEFAULT, NOT `false`/`''` PICKED FOR CONVENIENCE, so the
+   *   answer does not depend on whether a given release echoes back a key it never wrote.
+   *   SectionConfig stores what it was handed; a job created in the UI without a schedule has no
+   *   schedule line, and reading that absence as anything but `DEFAULT_SCHEDULE` would report
+   *   drift on a job nobody touched and then WRITE the reading back.
+   * ⛔ NO "IS IT REALLY THERE" GUARD, for `backup-job.ts`'s reason: absence is the API declining to
+   *   answer, which `pveOperations.read` already handles, not a key missing from an answer that did
+   *   arrive. `digest` is deliberately absent too — it changes when ANY job in the file changes,
+   *   including one somebody else declared (`ha-resource.ts` hit exactly that).
+   */
+  attributes: (live, props) => ({
+    comment: text(live['comment'], ''),
+    disable: bool(live['disable'], false),
+    guest: int(live['guest'], props.guest),
+    id: text(live['id'], jobId(props)),
+    jobnum: int(live['jobnum'], props.jobnum),
+    rate: rateOf(live['rate']),
+    remove_job: text(live['remove_job'], ''),
+    schedule: text(live['schedule'], DEFAULT_SCHEDULE),
+    source: text(live['source'], ''),
+    targetNode: text(live['target'], props.targetNode),
+    type: text(live['type'], 'local'),
+  }),
+  collection: () => 'cluster/replication',
+  createForm: createBody,
+  /**
+   * ⚠️ `targetNode` AND `source` ARE OUT OF THIS COMPARISON FOR TWO REASONS EACH, AND EITHER ALONE
+   *   WOULD BE ENOUGH. They are create-only — `target` is a `fixed` option, `source` has no honest
+   *   declared value — AND PVE REWRITES BOTH BEHIND YOUR BACK. MEASURED in
+   *   `switch_replication_job_target_nolock`: when a guest migrates, PVE sets
+   *   `$jobcfg->{target} = $new_target` and `$jobcfg->{source} = $old_target`, so the job follows
+   *   the guest. Compared, a single migration would make every later plan report an update that the
+   *   PUT cannot perform, forever. The cost of leaving them out is stated on the `targetNode` prop:
+   *   a changed target plans as noop, and a migrated job is not dragged back.
+   * ⚠️ `guest`, `jobnum`, `type` AND `id` ARE NOT COMPARED EITHER: the first two are the id in
+   *   integer form, `type` has one legal value, and `id` is the path — a change there is a
+   *   different object, which reads as absent and is created.
+   * ⛔ `remove_job` IS COMPARED, AND IT IS THE ONE FIELD HERE THAT LOOKS LIKE A FOREVER-UPDATE AND
+   *   IS NOT. A DELETE marks the job rather than removing it, so a re-declared id can name a job
+   *   that is busy deleting itself, and matching that would be a noop over a vanishing object. It
+   *   settles because `updateBody` actually clears the marker — see there.
+   */
+  matches: (attributes, props) =>
+    attributes.remove_job === '' &&
+    attributes.schedule === (props.schedule ?? DEFAULT_SCHEDULE) &&
+    attributes.disable === (props.disable === true) &&
+    attributes.comment === (props.comment ?? '') &&
+    (props.rate === undefined || attributes.rate === props.rate),
+  path: (props) => `cluster/replication/${jobId(props)}`,
+  updateForm: updateBody,
+});
+
+/**
+ * ⛔ Empty `list` like every other resource here: `GET /cluster/replication` hands back every job an
+ *   operator ever made, and adopting one is how a later `alchemy destroy` takes away a standby copy
+ *   nobody declared. Adoption is an explicit act — declare the `guest` and `jobnum` you mean.
+ * ⚠️ NOTHING BRAKES THIS DESTROY. PVE refuses to delete a pool that still holds guests; it accepts
+ *   this without a word, because nothing depends on a replication job. Re-read the DELETE ⛔ at the
+ *   top of this file before approving a plan line that removes one.
+ */
+export const ProxmoxReplicationJobProvider = () =>
+  Provider.effect(
+    ProxmoxReplicationJob,
+    Effect.succeed(ProxmoxReplicationJob.Provider.of(handlers)),
+  );

package/src/proxmox/resource.ts

@@ -0,0 +1,257 @@
+/**
+ * One shape for every PVE object, so the provider can cover Proxmox rather than a corner of it.
+ *
+ * ⛔ THE ALTERNATIVE IS TWENTY COPIES OF THE SAME 130 LINES. Proxmox exposes LXC, QEMU, storage,
+ *   pools, users, groups, roles, ACLs, API tokens, SDN zones/vnets/subnets, firewall rules and
+ *   groups, HA resources, backup and replication jobs, metric servers and notification targets.
+ *   Each is the same four operations over a different path and a different form body. Written by
+ *   hand, resource number six is where someone quietly drops the read-back or the isResolved guard
+ *   and nobody notices until a plan lies.
+ *
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE, AND A RESOURCE DECLARES ONLY WHAT IS DIFFERENT:
+ *   where it lives, how to recognise it, and which fields are mutable. A new PVE object should be
+ *   thirty lines, not a hundred and thirty.
+ *
+ * ⚠️ EVERY PVE ANSWER IS WRAPPED IN `{"data": ...}` AND A FAILED CALL CAN STILL BE HTTP 200 with
+ *   `{"data": null}`. That is why `reconcile` below READS BACK and refuses when the object is still
+ *   absent, rather than trusting a status code — see the ⛔ in that function.
+ */
+import { 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 { pve } from './client.ts';
+import type { ApiTarget, PbsTarget, PveRole, PveTarget } from './credentials.ts';
+
+/**
+ * ★ WHY SEVERAL FAMILIES HERE DECLARE `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE.
+ *
+ *   Alchemy's own convention: a few resource types default to retain "because their contents are
+ *   irreplaceable" — `GitHub.Repository` and `Cloudflare.Zone` do — and those opt into deletion
+ *   with `destroy()`. `retain` means the engine SKIPS `provider.delete` entirely when a resource
+ *   is orphaned or destroyed: the state row is dropped, the cluster object lives on.
+ *
+ *   So the PVE families whose contents cannot be rebuilt from a line of TypeScript — CephOsd,
+ *   CephPool, CephFs, CephDaemon, ZfsPool, Storage, NodeNetwork — carry that default. Their
+ *   `delete` is FULLY IMPLEMENTED and runs the moment a caller opts in with
+ *   `.pipe(RemovalPolicy.destroy())`. This is deliberately the Terraform `prevent_destroy` shape
+ *   rather than a stubbed-out operation: a `delete` that silently does nothing lies to whoever is
+ *   reading the plan, and the lie is discovered at the worst possible time.
+ *
+ * ⚠️ THE POLICY IS A DECORATION, NOT A PROP, so changing it produces NO DIFF — the resource plans
+ *   as a noop and the deploy re-commits the row's policy in place. A policy change therefore takes
+ *   effect from the very next deploy even though the plan shows nothing.
+ */
+
+/**
+ * ⛔ A RESOURCE IS PINNED TO ITS PRODUCT; ONLY THE FACTORY TAKES EITHER. The two hosts are the same
+ *   two strings, so without a required discriminant TypeScript would accept a PBS host wherever a
+ *   PVE one belongs — silently, with every call 401ing and `read` folding that into "absent". The
+ *   whole argument is on `scheme` in credentials.ts.
+ */
+/**
+ * ★ WHAT EVERY OPERATION IN THIS PACKAGE NEEDS FROM THE RUNTIME, NAMED ONCE.
+ *
+ *   `HttpClient`, for both halves of every call: the credential is minted from OpenBao's HTTP API
+ *   and the PVE call goes through the same client. That is what Alchemy's own providers do
+ *   (src/Hetzner/Providers.ts builds on `FetchHttpClient.layer`, and there is no bare `fetch` in
+ *   its Docker, Kubernetes or GitHub providers).
+ * ★ `ChildProcessSpawner` WAS HERE UNTIL 2026-09-14, while the mint shelled out to `bao`. The HTTP
+ *   client replaced that (credentials.ts), so the requirement went with it.
+ *
+ * ⚠️ SPELLED OUT AT EACH OF THE FORTY-ODD RESOURCES this would be a union nobody keeps in step —
+ *   one file left on the old shape is a type error at the stack, far from the cause. Named here,
+ *   adding a third service later is one edit.
+ */
+export type PveRequirements = HttpClient.HttpClient;
+
+export type WithTarget = { target: PveTarget };
+export type WithPbsTarget = { target: PbsTarget };
+export type WithApiTarget = { target: ApiTarget };
+
+export type PveSpec<Props extends WithApiTarget, Attributes> = {
+  /** `pools/house`, `nodes/n2/lxc/101` — where ONE object is read, updated and deleted. */
+  readonly path: (props: Props) => string;
+  /** `pools`, `nodes/n2/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. */
+  readonly createForm: (props: Props) => Record<string, string>;
+  /**
+   * 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) => Record<string, string>;
+  /** 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 const pveOperations = <Props extends WithApiTarget, Attributes>(
+  spec: PveSpec<Props, Attributes>,
+) => {
+  /** The live object, or undefined. ⚠️ A 404 is an ANSWER here, not a failure. */
+  const read = (props: Props) =>
+    pve<Record<string, unknown>>(
+      props.target,
+      spec.readRole ?? 'read',
+      'GET',
+      spec.path(props),
+    ).pipe(
+      Effect.map((data) => (data === undefined ? undefined : spec.attributes(data, props))),
+      Effect.orElseSucceed(() => undefined),
+    );
+
+  return {
+    read,
+
+    // ⚠️ `Input<Props>`, NOT `Props`. At plan time a prop can still be an unresolved Output or
+    //   Config; `isResolved` is the narrowing, so the parameter has to admit the wider type or
+    //   every caller casts — and a cast here would be a lie about what plan actually has.
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        // ⚠️ 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;
+        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 (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
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const live = yield* read(news);
+        if (live === undefined) {
+          yield* pve(
+            news.target,
+            'provision',
+            'POST',
+            spec.collection(news),
+            spec.createForm(news),
+          );
+        } else if (spec.updateForm !== undefined && !spec.matches(live, news)) {
+          /**
+           * ⛔ ADOPTING AN OBJECT THAT ALREADY MATCHES MUST NOT WRITE TO IT, AND WITHOUT THE
+           *   `matches` GUARD IT DID. Alchemy's `adopted` action is NOT a read: Apply.ts routes it
+           *   down the same branch as `update` and calls `reconcile` (Apply.ts:980 and :1045). So
+           *   the first time a declaration names an object Alchemy has no state for — which is
+           *   exactly what adopting the live estate means — reconcile runs, finds it present, and
+           *   fell through to this PUT.
+           *
+           *   For most families that was a pointless write-back of identical values. For
+           *   `Proxmox.NodeNetwork` it is worse than pointless: a PUT under `/nodes/{node}/network`
+           *   STAGES a change into `/etc/network/interfaces.new`, so merely adopting the interface
+           *   a node already has would leave that node with a pending network change waiting for an
+           *   apply — on a cluster whose Ceph traffic rides vmbr1.11. Adoption has to be free.
+           *
+           * ★ SO THE CONDITION IS THE SAME PREDICATE `diff` USES. If `matches` is true the object
+           *   already says what the declaration says, and there is nothing to write — by
+           *   definition, since every field this provider manages is a field `matches` compares.
+           *   A field deliberately left OUT of `matches` is one this resource does not manage, so
+           *   its drift is not this provider's to repair.
+           *
+           * ⚠️ AN EMPTY FORM IS ALSO NOT A WRITE. `updateForm` can legitimately answer `{}` — a
+           *   storage declaring only `storage`, `type` and its locator has no mutable field at all
+           *   — and PUTting an empty body is a pointless write at best and a 400 that reads as a
+           *   broken provider at worst.
+           */
+          const form = spec.updateForm(news);
+          if (Object.keys(form).length > 0) {
+            yield* pve(news.target, 'provision', 'PUT', spec.path(news), form);
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          /**
+           * ⛔ REFUSE RATHER THAN RETURN THE PROPS AS THOUGH THEY LANDED. PVE answers 200 with
+           *   `{"data": null}` on several endpoints, so "no error" is not evidence of a write. A
+           *   provider that returned its own inputs here would record state for an object that does
+           *   not exist, and the next plan would read `noop` over the gap.
+           */
+          return yield* Effect.die(
+            new Error(
+              `${spec.path(news)}: the write returned no error but the object is still absent. ` +
+                'PVE wraps every answer in {"data":...} and can report success on a call that did ' +
+                'nothing -- read back rather than trusting the status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    /**
+     * ⚠️ PVE REFUSES TO DELETE THINGS THAT ARE STILL IN USE — a pool holding guests, a storage with
+     *   volumes. That refusal is the cluster declining to orphan something because a line left a
+     *   file, so it is surfaced as-is rather than retried with a force flag.
+     */
+    destroy: (olds: Props) => pve(olds.target, 'provision', 'DELETE', spec.path(olds)),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd PVE object, wired once.
+ *
+ * ⛔ THIS BLOCK WAS WRITTEN TEN TIMES BEFORE IT WAS EXTRACTED, and every copy was character for
+ *   character identical apart from its comments: `list` answering empty, and four handlers whose
+ *   entire body was `yield* ops.<same name>(<same argument>)`. Ten copies of a delegation is ten
+ *   chances to delegate to the wrong one — `ops.read(olds)` inside `reconcile` typechecks, returns
+ *   a plausible value, and turns every deploy into a no-op that reports success.
+ *
+ * ★ IT TAKES THE SPEC, NOT THE OPERATIONS, so a resource declares its four spec functions and
+ *   stops. `pveOperations` stays exported for an object that genuinely needs a handler of its own;
+ *   nothing in this package does yet, and the day one does it should be visibly different from the
+ *   ten that are not.
+ *
+ * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER, AND THAT IS NOT AN OVERSIGHT — it was
+ *   written the other way first and reverted. Wrapping `Provider.effect(cls, …)` here means naming
+ *   the resource class generically, and Alchemy's `Props<R>` and `R["Attributes"]` are not the
+ *   plain `Props` and `Attributes` this spec is written against: `Attributes` comes back as
+ *   `Attributes & AttrOutput<Attributes["Attributes"]>`. Against a free type variable TypeScript
+ *   cannot prove those line up — "could be instantiated with a different subtype" — so the only
+ *   way to compile a Layer-returning version is a cast, and a cast is a LIE ABOUT WHETHER THE
+ *   HANDLERS MATCH THE RESOURCE, which is the one thing the call site exists to check. Leaving
+ *   `Cls.Provider.of(...)` in each file keeps that check where the types are concrete and real.
+ *   One line per resource is the price of it, and it is worth paying.
+ *
+ * ⚠️ `list` IS OPTIONAL IN `ProviderServiceInput` AND IS PASSED ANYWAY. An empty list is a claim —
+ *   this provider adopts nothing — and it is made here for every PVE object at once, because the
+ *   reasoning is identical for all of them: every PVE index endpoint answers with the whole
+ *   cluster's objects, PVE's own built-ins included. `GET /pools` returns pools a human made years
+ *   ago; `GET /access/roles` returns `Administrator`. Returning any of them would invite Alchemy to
+ *   adopt an object it never created, and therefore one day to narrow or delete it. Adoption stays
+ *   an explicit act. A resource with a reason to differ passes its own `list` and says why.
+ */
+export const pveHandlers = <Props extends WithApiTarget, Attributes extends object>(
+  spec: PveSpec<Props, Attributes>,
+) => {
+  const ops = pveOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};