@homeflare/alchemy 0.8.0 → 0.10.0

package/src/proxmox/lxc-wire.ts

@@ -0,0 +1,210 @@
+/**
+ * How a container's config values are spelled on the wire, and when two spellings are one value.
+ *
+ * ★ EVERY RULE HERE IS READ OFF pve-container 6.1.14 (the PVE 9 line, `src/PVE/LXC/Config.pm` at
+ *   git.proxmox.com HEAD, 2026-09-21) or off a live guest's config read with
+ *   `pvesh get /nodes/<node>/lxc/100/config`. A rule nobody measured is a forever-diff waiting to
+ *   happen: the plan reports an update, the deploy writes the same value back, and the next plan
+ *   reports it again.
+ *
+ * ⚠️ PVE PRINTS A PROPERTY STRING IN ITS OWN KEY ORDER AND WITH ITS OWN DEFAULTS FILLED IN.
+ *   MEASURED on a live guest: `net0` comes back `name=eth0,bridge=…,firewall=0,gw=…,hwaddr=…,ip=…,
+ *   mtu=1500,tag=…,type=veth` — `name` first, then alphabetical, with `type=veth` and a generated
+ *   `hwaddr` nobody declared — and `mp0` carries `backup=0` although `0` is what absent means.
+ *   So values are compared as maps with the defaults dropped, never as strings.
+ */
+import { canonicalToken, propertyString } from './values.ts';
+
+/** `a=1,b=2` → `[['a','1'],['b','2']]`. A bare token is `defaultKey`'s value. */
+export const pairs = (value: string, defaultKey?: string): [string, string][] =>
+  value
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .map((part): [string, string] => {
+      const at = part.indexOf('=');
+      if (at === -1) return [defaultKey ?? part, defaultKey === undefined ? '' : part];
+      return [part.slice(0, at).trim(), part.slice(at + 1).trim()];
+    });
+
+/**
+ * A key's default, per family: the value PVE treats absence as.
+ * ⚠️ `replicate` DEFAULTS ON and everything else here defaults off. `backup` on a mount point is
+ *   off when absent: vzdump skips any `mpN` without `backup=1` (the rootfs is always included).
+ */
+const DEFAULTS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  dev: { 'deny-write': '0' },
+  features: { force_rw_sys: '0', fuse: '0', keyctl: '0', mknod: '0', nesting: '0' },
+  net: { firewall: '0', 'host-managed': '0', link_down: '0', type: 'veth' },
+  volume: { backup: '0', keepattrs: '0', quota: '0', replicate: '1', ro: '0', shared: '0' },
+};
+
+/** Boolean keys, whose `1`/`true`/`on` spellings are one value. */
+const FLAGS = new Set([
+  'acl',
+  'backup',
+  'deny-write',
+  'firewall',
+  'force_rw_sys',
+  'fuse',
+  'host-managed',
+  'keepattrs',
+  'keyctl',
+  'link_down',
+  'mknod',
+  'nesting',
+  'quota',
+  'replicate',
+  'ro',
+  'shared',
+]);
+
+/** Keys holding a `;` list PVE does not promise to keep in order. */
+const SETS = new Set(['mount', 'mountoptions']);
+
+/** One option value in its comparable spelling. ⚠️ A MAC is upper-cased: PVE stores it that way. */
+const canonicalValue = (key: string, value: string) => {
+  if (FLAGS.has(key)) return canonicalToken(value);
+  if (SETS.has(key))
+    return [...new Set(value.split(';').map((part) => part.trim()))].sort().join(';');
+  if (key === 'hwaddr') return value.toUpperCase();
+  return value;
+};
+
+/** A property string as a map of comparable values, with `family`'s defaults dropped. */
+export const optionMap = (
+  value: string,
+  family: keyof typeof DEFAULTS,
+  defaultKey?: string,
+): Map<string, string> => {
+  const defaults = DEFAULTS[family] ?? {};
+  const out = new Map<string, string>();
+  for (const [key, raw] of pairs(value, defaultKey)) {
+    const canonical = canonicalValue(key, raw);
+    if (defaults[key] !== canonical) out.set(key, canonical);
+  }
+  return out;
+};
+
+export const sameMap = (left: Map<string, string>, right: Map<string, string>) =>
+  left.size === right.size && [...left].every(([key, value]) => right.get(key) === value);
+
+/** A map as one order-free string, for comparing and for naming a value in a message. */
+export const sortedForm = (map: Map<string, string>) =>
+  [...map]
+    .map(([key, value]) => `${key}=${value}`)
+    .sort()
+    .join(',');
+
+/** A map back to a property string, `lead` keys first — PVE wants `name` and the volume first. */
+export const printMap = (map: Map<string, string>, lead: readonly string[] = []) =>
+  [...lead.filter((key) => map.has(key)), ...[...map.keys()].filter((k) => !lead.includes(k))]
+    .map((key) => `${key}=${map.get(key) ?? ''}`)
+    .join(',');
+
+/**
+ * `net` maps for comparison. ⚠️ AN UNDECLARED `hwaddr` IS PVE'S, NOT DRIFT: PVE generates one on
+ * create, so the live MAC is dropped before comparing when the declaration names none.
+ */
+export const netMaps = (declared: string, live: string) => {
+  const want = optionMap(declared, 'net');
+  const have = optionMap(live, 'net');
+  if (!want.has('hwaddr')) have.delete('hwaddr');
+  return { have, want };
+};
+
+/**
+ * The `net` value to PUT: the declaration, plus the live MAC when it names none.
+ * ⛔ WITHOUT THE LIVE MAC, A PUT OF AN UNCHANGED NIC WOULD GENERATE A NEW ONE — a new MAC is a new
+ *   DHCP lease and a new IPv6 link-local address for a guest that only had its MTU edited.
+ */
+export const netWrite = (declared: string, live: string | undefined) => {
+  const want = new Map(pairs(declared));
+  const mac = live === undefined ? undefined : new Map(pairs(live)).get('hwaddr');
+  if (!want.has('hwaddr') && mac !== undefined) want.set('hwaddr', mac);
+  return printMap(want, ['name']);
+};
+
+/** Tags as PVE stores them: split on `;`, `,` or space, deduplicated, sorted, lower-cased. */
+export const tagSet = (value: string) =>
+  [...new Set(value.split(/[;,\s]+/).filter((tag) => tag !== ''))]
+    .map((tag) => tag.toLowerCase())
+    .sort()
+    .join(';');
+
+/** A resolver list: order matters, the separator does not. */
+export const orderedList = (value: string) =>
+  value
+    .split(/[;,\s]+/)
+    .filter((part) => part !== '')
+    .join(' ');
+
+/**
+ * ⚠️ PVE STORES A DESCRIPTION AS `#` COMMENT LINES AND READS EACH BACK WITH `"\n"` APPENDED
+ *   (`parse_pct_config`), so `foo` comes back `foo\n`. Trailing whitespace is not the value.
+ */
+export const descriptionText = (value: string) => value.replace(/\s+$/, '');
+
+/** How each scalar config key is compared. A key missing here is not one this resource manages. */
+export const SCALAR_KINDS: Readonly<Record<string, 'text' | 'number' | 'flag' | 'form'>> = {
+  arch: 'text',
+  cmode: 'text',
+  console: 'flag',
+  cores: 'number',
+  cpulimit: 'number',
+  cpuunits: 'number',
+  description: 'form',
+  features: 'form',
+  hostname: 'text',
+  memory: 'number',
+  nameserver: 'form',
+  onboot: 'flag',
+  ostype: 'text',
+  protection: 'flag',
+  searchdomain: 'form',
+  startup: 'form',
+  swap: 'number',
+  tags: 'form',
+  timezone: 'text',
+  tty: 'number',
+};
+
+/** Keys a declaration may set to `''` to mean "remove it". `delete=` takes them; nothing else may. */
+export const CLEARABLE: ReadonlySet<string> = new Set([
+  'description',
+  'features',
+  'nameserver',
+  'searchdomain',
+  'startup',
+  'tags',
+  'timezone',
+]);
+
+/**
+ * What an absent key means, from the confdesc defaults. ⚠️ Only these compare equal to absence;
+ * `cores` absent means "every host core", which no number declares.
+ */
+export const SCALAR_DEFAULTS: Readonly<Record<string, string>> = {
+  arch: 'amd64',
+  cmode: 'tty',
+  console: '1',
+  cpulimit: '0',
+  memory: '512',
+  onboot: '0',
+  protection: '0',
+  swap: '512',
+  tty: '2',
+};
+
+/** One scalar value in its comparable spelling. */
+export const scalarForm = (key: string, value: string): string => {
+  const kind = SCALAR_KINDS[key];
+  if (kind === 'number') return String(Number(value));
+  if (kind === 'flag') return canonicalToken(value);
+  if (key === 'description') return descriptionText(value);
+  if (key === 'features') return sortedForm(optionMap(value, 'features'));
+  if (key === 'nameserver' || key === 'searchdomain') return orderedList(value);
+  if (key === 'startup') return propertyString(value, 'order');
+  if (key === 'tags') return tagSet(value);
+  return value;
+};

package/src/proxmox/lxc.ts

@@ -1,56 +1,56 @@
 /**
- * `Proxmox.Lxc` — a container, declared. This is what the estate's provision credential exists for.
+ * `Proxmox.Lxc` — a container, declared: adopted as it runs, or created from a template.
  *
- * ★ `hf-provision@pve` HOLDS EXACTLY THE ROLE THIS NEEDS, and nothing more: `LXCProvisioner` on `/`
- *   grants VM.Allocate, VM.Audit, VM.Config.{CPU,Disk,HWType,Memory,Network,Options},
- *   VM.PowerMgmt, Datastore.AllocateSpace, Datastore.Audit, SDN.Use, Sys.Audit. Read that list as a
- *   specification: the credential was scoped to provision containers and to do nothing else.
+ * ★ `hf-provision@pve` HOLDS EXACTLY THE ROLE THIS NEEDS: `LXCProvisioner` on `/` grants
+ *   VM.Allocate, VM.Audit, VM.Config.{CPU,Disk,HWType,Memory,Network,Options}, VM.PowerMgmt,
+ *   Datastore.AllocateSpace, Datastore.Audit, SDN.Use, Sys.Audit. What that role cannot do — device
+ *   passthrough, bind mounts, features beyond nesting — PVE keeps for root@pam, and lxc-judge.ts
+ *   refuses at plan with the `pct set` to run instead.
  *
- * ⛔ `vmid` IS THE PRIMARY KEY AND IT IS CLUSTER-WIDE, not per node. Two resources declaring the
- *   same vmid on different nodes are the same object, and PVE will refuse the second with
- *   "already exists". It is required rather than allocated here: letting the provider pick the next
- *   free id would make the identity of a container depend on the order plans happened to run in.
+ * ⛔ NOTHING HERE PLANS A REPLACE, AND NOTHING DESTROYS A GUEST BY DEFAULT. A replace of a guest is
+ *   a delete of a running machine and its disks, so every change PVE cannot make in place — a new
+ *   vmid, another template, an unprivileged flip, a storage move, a smaller disk, a move to
+ *   another node — FAILS the plan with a sentence instead. `defaultRemovalPolicy: 'retain'`:
+ *   dropping the declaration drops the state row and leaves the guest running; only
+ *   `RemovalPolicy.destroy()` reaches `destroyGuest`, which deletes only a guest that still
+ *   matches its last declaration, and PVE still refuses a running or protected one.
+ * ⛔ AND NOTHING HERE WRITES A VOLUME IT DID NOT ALLOCATE. A create takes `storage:GiB` only
+ *   (lxc-create-form.ts), and a deploy that planned a create never writes onto a guest it finds.
  *
- * ⚠️ MOST FIELDS ARE CREATE-TIME. `ostemplate` and `storage` are consumed when the rootfs is built
- *   and are not readable back afterwards, so they are deliberately NOT compared in `matches` --
- *   a provider that diffed them would report an update on every plan, forever. What is compared is
- *   what PVE will actually tell you about a running container.
+ * ⚠️ AN ADOPTION ALWAYS PLANS `adopted`, EVEN WHEN IT WOULD WRITE. alchemy 2.0.0-beta.79 turns a
+ *   cold adoption's diff into an update whatever it answered (Plan.ts, `forceUpdateAfterAdoption`)
+ *   and prints no property diff for it. So `diff` LOGS the keys a deploy would write, by name
+ *   (never by value), as a warning — the only place a plan can say the declaration is not the live
+ *   config yet. A clean adoption logs nothing, and its deploy writes nothing (lxc-judge.ts).
+ *
+ * ⚠️ POWER STATE IS NOT DECLARED. `onboot` is config; start and stop are an operator's act, as for
+ *   `Proxmox.Vm`. `start: 1` starts a guest once, after the create that built it, and never again.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { num } from './values.ts';
-
-export interface LxcProps extends WithTarget {
-  /** Which node hosts it. Moving a container between nodes is a migration, not an update. */
-  node: string;
-  /** ⛔ CLUSTER-WIDE primary key. Required, never auto-allocated — see the ⛔ above. */
-  vmid: number;
-  /** e.g. `local:vztmpl/debian-13-standard_13.0-1_amd64.tar.zst`. Create-time only. */
-  ostemplate: string;
-  /** Storage for the rootfs, e.g. `local-zfs`. Create-time only. */
-  storage: string;
-  hostname?: string;
-  /** MiB. Mutable. */
-  memory?: number;
-  cores?: number;
-  /** e.g. `name=eth0,bridge=vmbr0,ip=dhcp`. Mutable. */
-  net0?: string;
-  /** Start on boot. Mutable. */
-  onboot?: boolean;
-}
+import { type Owner, refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
+import { provingResumes } from '../ownership/resume.ts';
+import { createRefusals } from './lxc-create-form.ts';
+import { identityRefusals } from './lxc-identity.ts';
+import { judge } from './lxc-judge.ts';
+import {
+  LxcRefusedError,
+  type LxcWhere,
+  attributesOf,
+  createGuest,
+  destroyGuest,
+  readLive,
+  updateGuest,
+} from './lxc-lifecycle.ts';
+import type { LxcAttributes, LxcProps } from './lxc-props.ts';
+import type { PveRequirements } from './resource.ts';
+import { text } from './values.ts';
 
-export interface LxcAttributes {
-  vmid: number;
-  node: string;
-  hostname: string;
-  memory: number;
-  cores: number;
-  onboot: boolean;
-  /** `running` | `stopped`. Reported, never declared — power state is not configuration. */
-  status: string;
-}
+export type { LxcAttributes, LxcProps } from './lxc-props.ts';
 
 export interface ProxmoxLxc extends Resource<
   'Proxmox.Lxc',
@@ -60,58 +60,181 @@ export interface ProxmoxLxc extends Resource<
   PveRequirements
 > {}
 
-export const ProxmoxLxc = Resource<ProxmoxLxc>('Proxmox.Lxc');
+/** ★ `retain` by default — a guest's disks cannot be rebuilt from a line. See resource.ts. */
+export const ProxmoxLxc = Resource<ProxmoxLxc>('Proxmox.Lxc', { defaultRemovalPolicy: 'retain' });
+
+/** The ownership fields of one call (ownership/adopt.ts), with this resource's attributes. */
+type LxcOwner = Owner & { readonly output: LxcAttributes | undefined };
+
+const refused = (reasons: readonly string[]) =>
+  Effect.fail(new LxcRefusedError(reasons.join('\n')));
 
-const handlers = pveHandlers<LxcProps, LxcAttributes>({
-  /**
-   * ⚠️ READ FROM `config`, NOT FROM THE GUEST LIST. `GET /nodes/{n}/lxc` reports runtime shape
-   *   (status, uptime, current memory), while `/config` reports DECLARED shape. Diffing against
-   *   runtime memory would report an update every time a container ballooned.
-   */
-  attributes: (live, props) => ({
-    cores: num(live['cores'], 1),
-    hostname: typeof live['hostname'] === 'string' ? live['hostname'] : '',
-    memory: num(live['memory'], 512),
-    node: props.node,
-    onboot: live['onboot'] === 1 || live['onboot'] === true,
-    status: typeof live['status'] === 'string' ? live['status'] : 'unknown',
-    vmid: props.vmid,
-  }),
-  collection: (props) => `nodes/${props.node}/lxc`,
-  createForm: (props) => ({
-    cores: String(props.cores ?? 1),
-    hostname: props.hostname ?? `ct${String(props.vmid)}`,
-    memory: String(props.memory ?? 512),
-    onboot: props.onboot === true ? '1' : '0',
-    ostemplate: props.ostemplate,
-    storage: props.storage,
-    vmid: String(props.vmid),
-    ...(props.net0 === undefined ? {} : { net0: props.net0 }),
-  }),
-  matches: (attributes, props) =>
-    attributes.hostname === (props.hostname ?? `ct${String(props.vmid)}`) &&
-    attributes.memory === (props.memory ?? 512) &&
-    attributes.cores === (props.cores ?? 1) &&
-    attributes.onboot === (props.onboot === true),
-  path: (props) => `nodes/${props.node}/lxc/${String(props.vmid)}/config`,
-  /**
-   * ⚠️ PVE UPDATES A CONTAINER THROUGH `PUT .../config`, THE SAME PATH IT IS READ FROM, which is
-   *   why `path` ends in `/config` while `collection` does not. Create POSTs to the collection;
-   *   read and update both use the config document.
-   */
-  updateForm: (props) => ({
-    cores: String(props.cores ?? 1),
-    hostname: props.hostname ?? `ct${String(props.vmid)}`,
-    memory: String(props.memory ?? 512),
-    onboot: props.onboot === true ? '1' : '0',
-    ...(props.net0 === undefined ? {} : { net0: props.net0 }),
-  }),
+/**
+ * ★ A ROW WITH NO ATTRIBUTES IS AN UNFINISHED CREATE. provingResumes (ownership/resume.ts) asks
+ *   `read` whether the guest there is that create's before this runs, and notes it for the apply
+ *   that follows, so reconcile can tell our own interrupted create from a guest somebody else put
+ *   at this vmid.
+ */
+const diff = (news: Input<LxcProps>, olds: LxcProps, output: LxcAttributes | undefined) =>
+  Effect.gen(function* () {
+    const identity = identityRefusals(news, olds, output);
+    if (identity.length > 0) return yield* refused(identity);
+    if (output === undefined) return undefined;
+    if (!isResolved(news)) return undefined;
+    const live = yield* readLive(news);
+    // ⚠️ `update`, not `create`: state exists and the guest does not. reconcile rebuilds it from
+    //   `ostemplate`, or refuses when there is none — an adopted guest has no recipe.
+    // ⛔ AND THE PLAN SAYS SO. A bare `update` here read as an edit while the deploy would build a
+    //   NEW guest with empty volumes; an uncreatable one now fails at plan rather than at deploy.
+    if (live === undefined) {
+      const refusals = createRefusals(news);
+      if (refusals.length > 0) return yield* refused(refusals);
+      yield* Effect.logWarning(
+        `Proxmox.Lxc ${news.node}/${String(news.vmid)}: the cluster lists no guest with this ` +
+          'vmid -- a deploy CREATES it again from ostemplate, with new, empty volumes.',
+      );
+      return { action: 'update' } as const;
+    }
+    const change = judge(news, live);
+    if (change.refuse.length > 0) return yield* refused(change.refuse);
+    const moved = news.node !== output.node;
+    if (change.drift.length === 0 && !moved) return { action: 'noop' } as const;
+    const what =
+      change.drift.length === 0
+        ? `the guest is on ${news.node} now, not ${output.node} -- a deploy re-records it, ` +
+          'writing nothing.'
+        : `live config differs from the declaration in ${change.drift.join(', ')} -- a ` +
+          'deploy writes these.';
+    yield* Effect.logWarning(`Proxmox.Lxc ${news.node}/${String(news.vmid)}: ${what}`);
+    return { action: 'update' } as const;
+  });
+
+/**
+ * ⛔ THE SAME JUDGE AS `diff`, RE-RUN AGAINST A FRESH READ, AND AN EMPTY CHANGE WRITES NOTHING.
+ *   Apply routes `adopted` through reconcile (resource.ts has the Apply.ts lines), so this is what
+ *   runs on the first deploy after an adoption; for a guest that already matches it is two GETs.
+ * ⛔ AND IT READS BACK AND JUDGES AGAIN. PVE answers 200 on writes that did nothing, so a change
+ *   that did not land is a failure here, not a state row claiming it did. ⚠️ A change PVE parked
+ *   as pending on a running guest DOES read back (GET config merges `[pending]` unless asked for
+ *   `current`), so it passes here and takes effect at the guest's next restart.
+ * ⛔ A CREATE NEVER WRITES ONTO A GUEST THAT IS ALREADY THERE. `output` undefined means the plan
+ *   said `create`: its adoption probe saw no guest, or never ran (Plan.ts skips it while any prop
+ *   is an unresolved Output — a `net0` built from a vnet created in the same deploy). Finding one
+ *   now, it is first an OWNERSHIP question (docs/ownership.md): `refuseTakeover` lets it through
+ *   only for this resource's own interrupted create or under `--adopt` / `adopt(true)`, and
+ *   otherwise refuses and forgets the `creating` row, a matching guest included. Then a CONTENT
+ *   one: a guest that already matches is recorded with no write; any other refuses even under
+ *   `--adopt`, until a plan can show the keys a deploy would write onto it.
+ */
+const reconcile = (owner: LxcOwner, news: LxcProps) =>
+  Effect.gen(function* () {
+    const { output } = owner;
+    const identity = identityRefusals(news, news, output);
+    if (identity.length > 0) return yield* refused(identity);
+    const live = yield* readLive(news);
+    if (live === undefined) {
+      const refusals = createRefusals(news);
+      if (refusals.length > 0) return yield* refused(refusals);
+      yield* createGuest(news);
+    } else {
+      if (output === undefined) {
+        yield* refuseTakeover(owner, `Proxmox.Lxc CT ${String(news.vmid)} on ${news.node}`);
+      }
+      const change = judge(news, live);
+      if (output === undefined && change.drift.length > 0) {
+        return yield* refused([
+          `CT ${String(news.vmid)} already exists on ${news.node} and differs in ` +
+            `${change.drift.join(', ')}, but this deploy planned a create. A create never writes ` +
+            'onto an existing guest: plan again, so the plan can show it and adopt it.',
+        ]);
+      }
+      if (change.refuse.length > 0) return yield* refused(change.refuse);
+      if (change.drift.length > 0) yield* updateGuest(news, change, text(live['digest']));
+    }
+    const after = yield* readLive(news);
+    if (after === undefined) {
+      return yield* refused([
+        `CT ${String(news.vmid)}: the write returned no error but the guest is still absent.`,
+      ]);
+    }
+    const left = judge(news, after).drift;
+    if (left.length > 0) {
+      return yield* refused([
+        `CT ${String(news.vmid)}: after the write, ${left.join(', ')} still differ from the ` +
+          'declaration. PVE may have normalised the value (tags are lower-cased by default) -- ' +
+          'declare what it stores.',
+      ]);
+    }
+    return attributesOf(news, after);
+  });
+
+const whereOf = (olds: LxcProps, output: LxcAttributes | undefined): LxcWhere => ({
+  node: output?.node ?? olds.node,
+  target: olds.target,
+  vmid: output?.vmid ?? olds.vmid,
 });
 
 /**
- * ⛔ PVE REFUSES TO DELETE A RUNNING CONTAINER, and that refusal is kept — `handlers.delete`
- *   passes it straight through. Stopping a guest so that a `destroy` can proceed is a decision an
- *   operator makes, not one a plan makes on their behalf while they are reading the diff.
+ * ⛔ NO LIVE GUEST IS ADOPTED WITHOUT `--adopt`, NOT EVEN ONE THAT MATCHES (docs/ownership.md,
+ *   decided 2026-09-21). With no state this read is Alchemy's adoption probe (Plan.ts), and plain
+ *   attributes would mean "ours", adopted silently. Matching is not proof: a pasted config or a
+ *   mistyped vmid reads the same as our own guest, and once state claims it,
+ *   `RemovalPolicy.destroy()` deletes it and its volumes from its real owner. So it reads
+ *   `Unowned`, and the plan fails "Cannot adopt" until `adopt(true)` or `--adopt` says so.
+ * ★ THE RECOVERY READ STILL FINISHES OUR OWN CREATE. A `creating` row whose deploy died after the
+ *   POST carries its own instance id; `ownedRead` accepts the guest when the state store records
+ *   that id AND the guest still matches the row's props — the same judge `diff` uses.
+ * ⚠️ UNLIKE `CaddyConfig`, which keeps adopting an identical config because its delete never
+ *   touches Caddy: a container's delete removes a machine and its disks.
  */
+const read = (owner: LxcOwner, olds: LxcProps) =>
+  Effect.gen(function* () {
+    const where = whereOf(olds, owner.output);
+    const live = yield* readLive(where);
+    if (live === undefined) return undefined;
+    const settled = Effect.sync(() => judge(olds, live).drift.length === 0);
+    return yield* ownedRead(owner, attributesOf(where, live), settled);
+  });
+
+/**
+ * ⛔ HAND-WRITTEN RATHER THAN `pveHandlers`: a guest reads failures as failures, grows disks
+ *   through a second endpoint, waits on tasks and refuses what the factory would replace. `list`
+ *   is empty for the reason it is everywhere here: `GET /nodes/{n}/lxc` lists every guest on the
+ *   node, and adopting one is a declaration, never a side effect of registering the provider.
+ */
+type Asked = { readonly fqn: string; readonly instanceId: string };
+
+const handlers = {
+  delete: ({ olds, output }: { olds: LxcProps; output: LxcAttributes }) =>
+    destroyGuest(whereOf(olds, output), olds),
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<LxcProps>;
+    olds: LxcProps;
+    output: LxcAttributes | undefined;
+  }) => diff(news, olds, output),
+  list: () => Effect.succeed([]),
+  read: ({
+    fqn,
+    instanceId,
+    olds,
+    output,
+  }: Asked & { olds: LxcProps; output: LxcAttributes | undefined }) =>
+    read({ fqn, instanceId, output }, olds),
+  reconcile: ({
+    fqn,
+    instanceId,
+    news,
+    output,
+  }: Asked & { news: LxcProps; output: LxcAttributes | undefined }) =>
+    reconcile({ fqn, instanceId, output }, news),
+};
+
 export const ProxmoxLxcProvider = () =>
-  Provider.effect(ProxmoxLxc, Effect.succeed(ProxmoxLxc.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxLxc,
+    Effect.succeed(ProxmoxLxc.Provider.of(handlers)).pipe(Effect.map(provingResumes)),
+  );

package/src/proxmox/network-apply-read.ts

@@ -194,6 +194,8 @@ export const awaitTask = (
   credential: PveCredential,
   node: string,
   upid: string,
+  // ★ A CALLER WHOSE TASK IS SLOWER THAN A RELOAD SAYS SO: an LXC create unpacks a template.
+  attempts: number = ATTEMPTS,
 ) =>
   Effect.gen(function* () {
     /**
@@ -206,7 +208,7 @@ export const awaitTask = (
      *   and a perfectly good reload would stop the deploy. Raw removes the assumption.
      */
     const path = `nodes/${node}/tasks/${upid}/status`;
-    for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
       /**
        * ⛔ A FAILED POLL IS NOT A FAILED RELOAD, AND CALLING IT ONE WOULD BE THE WORST KIND OF
        *   WRONG. If the member serving the poll is the node being reloaded, `ifreload -a` can drop

package/src/proxmox/pbs-datastore.ts

@@ -65,6 +65,7 @@ import {
 } from './pbs-datastore-form.ts';
 import { guardBackend, guardPath, settle } from './pbs-datastore-guard.ts';
 import type { PveRequirements } from './resource.ts';
+import { formToSend } from './update-guard.ts';
 
 export type { PbsDatastoreAttributes, PbsTarget };
 
@@ -210,9 +211,9 @@ export const PbsDatastoreProvider = () =>
           } else {
             yield* guardPath(live, news);
             yield* guardBackend(live, news);
-            // ⚠️ An empty form is not a write — resource.ts skips one for the same reason.
-            const form = updateForm(news);
-            if (!matches(live, news) && Object.keys(form).length > 0) {
+            // ⚠️ An empty form is not a write, and a match is not one either — update-guard.ts.
+            const form = formToSend(matches, live, news, updateForm(news));
+            if (form !== undefined) {
               yield* pve(news.target, 'provision', 'PUT', object(news), form);
             }
           }

package/src/proxmox/resource.ts

@@ -22,6 +22,7 @@ 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';
+import { formToSend } from './update-guard.ts';
 
 /**
  * ★ WHY SEVERAL FAMILIES HERE DECLARE `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE.
@@ -150,7 +151,7 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
             spec.collection(news),
             spec.createForm(news),
           );
-        } else if (spec.updateForm !== undefined && !spec.matches(live, news)) {
+        } else if (spec.updateForm !== undefined) {
           /**
            * ⛔ 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
@@ -171,13 +172,12 @@ export const pveOperations = <Props extends WithApiTarget, Attributes>(
            *   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.
+           * ★ THE PREDICATE LIVES IN update-guard.ts NOW, with the ⚠️ on why an empty form is not a
+           *   write either, because CephPool and PbsDatastore write their own reconcile and need
+           *   the same one — CephPool did not have it (see that file).
            */
-          const form = spec.updateForm(news);
-          if (Object.keys(form).length > 0) {
+          const form = formToSend(spec.matches, live, news, spec.updateForm(news));
+          if (form !== undefined) {
             yield* pve(news.target, 'provision', 'PUT', spec.path(news), form);
           }
         }