@homeflare/alchemy 0.38.0 → 0.40.0

package/src/forgejo/team-member.ts

@@ -22,6 +22,31 @@
  *   cannot create a team.
  *
  * ⛔ TOKEN NEEDS `write:organization` TO ADD OR REMOVE, and an identity allowed to manage the team.
+ *
+ * ⛔ `defaultRemovalPolicy: 'retain'` — FOUND 2026-09-25 by reading the source, not by measuring
+ *   anything (mini PR 82's red team, `homeflare-mini` 970e8be): before this, `ForgejoRepository`/
+ *   `ForgejoOrgLabel` defaulted to retain in the kit itself but this family did not, so alchemy's
+ *   own engine fallback (`destroy`) applied to it — every caller had to remember its own
+ *   `.pipe(RemovalPolicy.retain())`, the way mini's `src/forgejo/declare.ts` did for
+ *   `forgejo-provision`'s row. Dropping a `TeamMember` declaration — toggling a feature gate off,
+ *   renaming the resource id — must not silently call `organization.orgRemoveTeamMember` and
+ *   revoke a real membership; that is the same "removal from the stack is not removal from
+ *   Forgejo" posture `ForgejoOrgLabel` and `ForgejoBranchProtection` already take, this family
+ *   exists to attach a stack's identity to a team it never creates or destroys (`teamIdOf` below
+ *   only ever locates the team, never manages it), and the same trade-off alchemy's own
+ *   `GitHub.Collaborator` and `GitHub.TeamAccess` make for the identical reason — "preventing
+ *   accidental lockout" (`GitHub/Collaborator.ts:127`, `GitHub/TeamAccess.ts:145` in the pinned
+ *   alchemy source). The trade-off, stated plainly: removing a declaration no longer revokes
+ *   access on its own — the plan shows that row as `orphaned`, not `delete`. Opt into a real
+ *   revoke with `.pipe(RemovalPolicy.destroy())`; `destroy` below is fully implemented.
+ *
+ * ⚠️ THE DEFAULT ONLY PROTECTS A ROW ALREADY IN STATE ONCE THIS RELEASE IS DEPLOYED. Alchemy's
+ *   plan reads `removalPolicy` off the *persisted row* (`Plan.ts`'s delete-node builder), not off
+ *   this default; the default only reaches an existing row's state on a deploy where the resource
+ *   plans as a no-op (`Apply.ts`'s noop path rewrites it and logs "removal policy destroy →
+ *   retain"). A consumer that bumps to this release and drops a `TeamMember` declaration in the
+ *   SAME deploy still gets `delete`, not `orphaned` — see the changeset for the two-deploy shape
+ *   this implies for both adopting retain and opting back into destroy.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
@@ -52,7 +77,9 @@ export interface ForgejoTeamMember extends Resource<
   ForgejoRequirements
 > {}
 
-export const ForgejoTeamMember = Resource<ForgejoTeamMember>('Forgejo.TeamMember');
+export const ForgejoTeamMember = Resource<ForgejoTeamMember>('Forgejo.TeamMember', {
+  defaultRemovalPolicy: 'retain',
+});
 
 export class ForgejoTeamNotFoundError extends Data.TaggedError('ForgejoTeamNotFoundError')<{
   readonly message: string;

package/src/index.ts

@@ -10,6 +10,7 @@
  *     import { BaoMount } from '@homeflare/alchemy/openbao';
  *     import { TalosCluster } from '@homeflare/alchemy/talos';
  *     import { ProxmoxAcl } from '@homeflare/alchemy/proxmox';
+ *     import { CephAuthEntity } from '@homeflare/alchemy/ceph';
  *     import { LaunchdJob } from '@homeflare/alchemy/launchd';
  *     import { ReleaseBinary } from '@homeflare/alchemy/release';
  *     import { CaddyConfig } from '@homeflare/alchemy/caddy';

package/src/proxmox/constraints-required.test.ts

@@ -80,6 +80,7 @@ describe('every create this package makes, and what the vendor requires of it',
       'pve:POST /nodes/{node}/lxc': ['ostemplate', 'vmid'],
       'pve:POST /nodes/{node}/network': ['iface', 'type'],
       'pve:POST /nodes/{node}/qemu': ['vmid'],
+      'pve:POST /nodes/{node}/storage/{storage}/download-url': ['content', 'filename', 'url'],
       'pve:POST /pools': ['poolid'],
       'pve:POST /storage': ['storage', 'type'],
     });

package/src/proxmox/generated/constraints/index.ts

@@ -22,6 +22,7 @@ import { PVE_NODES_DISKS_CONSTRAINTS } from './pve-nodes-disks.ts';
 import { PVE_NODES_LXC_CONSTRAINTS } from './pve-nodes-lxc.ts';
 import { PVE_NODES_NETWORK_CONSTRAINTS } from './pve-nodes-network.ts';
 import { PVE_NODES_QEMU_CONSTRAINTS } from './pve-nodes-qemu.ts';
+import { PVE_NODES_STORAGE_CONSTRAINTS } from './pve-nodes-storage.ts';
 import { PVE_POOLS_CONSTRAINTS } from './pve-pools.ts';
 import { PVE_STORAGE_CONSTRAINTS } from './pve-storage.ts';
 import { PBS_CONFIG_CONSTRAINTS } from './pbs-config.ts';
@@ -41,6 +42,7 @@ export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>>
   ...PVE_NODES_LXC_CONSTRAINTS,
   ...PVE_NODES_NETWORK_CONSTRAINTS,
   ...PVE_NODES_QEMU_CONSTRAINTS,
+  ...PVE_NODES_STORAGE_CONSTRAINTS,
   ...PVE_POOLS_CONSTRAINTS,
   ...PVE_STORAGE_CONSTRAINTS,
   ...PBS_CONFIG_CONSTRAINTS,
@@ -52,4 +54,4 @@ export const PROXMOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>>
  * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
  *   changing a 128 to a 129 by hand is. `tests/schema-manifest.test.ts` recomputes it.
  */
-export const PROXMOX_CONSTRAINTS_DIGEST = '56eba80750ddb1d2';
+export const PROXMOX_CONSTRAINTS_DIGEST = '8b6745a471839974';

package/src/proxmox/generated/constraints/pve-access.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-backup.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-firewall.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-ha.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-metrics.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-notifications.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-replication.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-cluster-sdn.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-ceph.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-disks.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-lxc.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-network.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-qemu.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-nodes-storage.ts

@@ -0,0 +1,30 @@
+/**
+ * Generated pve-manager parameter constraints for `/nodes/{node}/storage` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/constraints.ts
+ * Manifest entry: `pve-apidoc` — pve-manager 9.2.11/f6997e698c7933ea
+ *   sha256 9def8f13611184ee, read on a PVE cluster node from
+ *   /usr/share/pve-docs/api-viewer/apidoc.js
+ *
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
+ * and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it is a rule that could NOT be carried into a
+ *   JavaScript RegExp faithfully (codegen/pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ `pattern` IS NOT THE VENDOR'S SPELLING. For PVE it is anchored, because PVE applies
+ *   `m/^$pattern$/` itself (JSONSchema.pm); for PBS it is the vendor's own, which already
+ *   carries its anchors. `patternSource` is the spelling to quote at a human — param-rules.ts.
+ * ⚠️ `each: true` means the value rules describe every ELEMENT of a repeated key, because the
+ *   parameter is an array and stated its limits on `items`.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const PVE_NODES_STORAGE_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "pve:POST /nodes/{node}/storage/{storage}/download-url": {
+    "checksum-algorithm": {"enum":["md5","sha1","sha224","sha256","sha384","sha512"],"type":"string"},
+    "content": {"enum":["iso","vztmpl","import"],"format":"pve-storage-content","required":true,"type":"string"},
+    "filename": {"maxLength":255,"required":true,"type":"string"},
+    "url": {"pattern":"^https?://.*\\n?$","patternSource":"https?://.*","required":true,"type":"string"},
+  },
+};

package/src/proxmox/generated/constraints/pve-pools.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/generated/constraints/pve-storage.ts

@@ -6,7 +6,7 @@
  *   sha256 9def8f13611184ee, read on a PVE cluster node from
  *   /usr/share/pve-docs/api-viewer/apidoc.js
  *
- * 58 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
+ * 59 of this product's 258 POST/PUT endpoints are tabled across all areas: the ones
  * this package writes to, named in its own source. Every other vendor write endpoint is UNTABLED
  * and therefore unchecked at plan time.
  *

package/src/proxmox/index.test.ts

@@ -1,15 +1,19 @@
 /**
- * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not QEMU or NIC apply.
+ * Public barrel: control-plane Resource constructors and `ProxmoxLxc`, not NIC apply.
  *
- * ⛔ Vm stays Provider-only. NodeNetwork/NetworkApply stay off the barrel — they stage
- *   interfaces.new. ★ Lxc is a Resource since 2026-09-21: adopt-first, refuse-not-replace,
- *   retain on destroy (lxc.ts).
+ * ⛔ NodeNetwork/NetworkApply stay off the barrel — they stage interfaces.new. ★ Lxc is a
+ *   Resource since 2026-09-21: adopt-first, refuse-not-replace, retain on destroy (lxc.ts).
  * ★ CephDaemon, CephFs and CephOsd are Resources since 2026-09-22: adopt-only by shape and retain
  *   on destroy (ceph-adopt.test.ts). ⛔ CephFlag stays Provider-only: a declared flag reasserts a
  *   maintenance toggle on every deploy (ceph-flag.ts).
  * ★ ApiToken and ZfsPool are Resources since 2026-09-23, decision 9: ApiToken metadata-only,
  *   ZfsPool adopt-only when `devices`/`raidlevel` are left undeclared (api-token-adopt.test.ts,
  *   zfs-pool-adopt.test.ts).
+ * ★ Vm and StorageDownload are Resources since 2026-09-26, for Talos: Vm's declared-keys model
+ *   (qemu-props.ts) and retain-by-default; StorageDownload's checksum-pinned, create-oriented
+ *   `download-url` (storage-download.ts). Neither was Provider-only for a design reason that
+ *   changed — Vm's old "5-default PUT" is what kept it off this barrel until qemu-props.ts fixed
+ *   it, per qemu-lifecycle.test.ts's own regression test.
  */
 import { expect, test } from 'bun:test';
 import { PbsDatastore, ProxmoxStorage } from './index.ts';
@@ -42,7 +46,9 @@ const resourceExports = [
   'ProxmoxSdnVnet',
   'ProxmoxSdnZone',
   'ProxmoxStorage',
+  'ProxmoxStorageDownload',
   'ProxmoxUser',
+  'ProxmoxVm',
   'ProxmoxZfsPool',
 ] as const;
 
@@ -61,8 +67,7 @@ test('the provisioning baseline is on the barrel: the list, the declaration, the
   expect(barrel.provisionBootstrap()).toStartWith('#!/bin/sh\n');
 });
 
-test('QEMU, NIC apply and the Ceph flag stay Provider-only', () => {
-  expect(src).not.toMatch(/export \{ ProxmoxVm[, }]/);
+test('NIC apply and the Ceph flag stay Provider-only', () => {
   expect(src).not.toMatch(/export \{ ProxmoxNodeNetwork[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxNetworkApply[, }]/);
   expect(src).not.toMatch(/export \{ ProxmoxCephFlag[, }]/);

package/src/proxmox/index.ts

@@ -6,8 +6,18 @@
  *   provider needs but a consumer should not depend on. An `export *` here would publish
  *   every helper as API and make the next refactor a breaking change.
  * ★ Control-plane Resource constructors (Storage, SDN, access, HA, backup,
- *   metrics, PBS) sit next to their Providers. NIC apply and QEMU stay
- *   Provider-only so a stack cannot declare them by accident.
+ *   metrics, PBS) sit next to their Providers. NIC apply stays Provider-only
+ *   so a stack cannot declare it by accident.
+ * ★ `ProxmoxVm` JOINED THEM 2026-09-26, FOR TALOS. Its declared-keys model (qemu-props.ts) is
+ *   what let it join safely: an undeclared field is unmanaged, so it is never sent and never
+ *   compared — the fix for the "5-default PUT" a Provider-only `Proxmox.Vm` never exercised.
+ *   `cipassword` and `machine` are typed `never` and refused if smuggled past the types
+ *   (qemu-form.ts's `formRefusals`); `defaultRemovalPolicy: 'retain'` means dropping a
+ *   declaration never destroys a guest's disks. Node-pinned semantics (qemu-read.ts's "A
+ *   migration is not an update") are unchanged by the export.
+ * ★ `Proxmox.StorageDownload` JOINED 2026-09-26 TOO, ALONGSIDE IT: `download-url` (content
+ *   `import`, checksum-pinned) as a CREATE-oriented family — no adoption, no update, a task-poll
+ *   failure (a checksum mismatch included) refuses rather than reports success.
  * ★ `ProxmoxLxc` JOINED THEM 2026-09-21, AND IT WAS KEPT OFF UNTIL IT COULD NOT HURT A GUEST.
  *   The provider-only version diffed four fields and would have planned a create over any read
  *   failure. The Resource now adopts from the live config, refuses every change PVE cannot make
@@ -102,7 +112,13 @@ export {
 } from './provision-baseline.ts';
 export { provisionBootstrap } from './provision-bootstrap.ts';
 export { type DeclareProvisionOptions, declareProvisionBaseline } from './provision-declare.ts';
-export { ProxmoxVmProvider } from './qemu.ts';
+export { ProxmoxVm, ProxmoxVmProvider, type VmAttributes, type VmProps } from './qemu.ts';
+export {
+  ProxmoxStorageDownload,
+  ProxmoxStorageDownloadProvider,
+  type StorageDownloadAttributes,
+  type StorageDownloadProps,
+} from './storage-download.ts';
 export { ProxmoxReplicationJobProvider } from './replication-job.ts';
 export { ProxmoxRole, ProxmoxRoleProvider } from './role.ts';
 export { ProxmoxSdnApply, ProxmoxSdnApplyProvider } from './sdn-apply.ts';

package/src/proxmox/qemu-form.ts

@@ -1,15 +1,51 @@
-/** QEMU create and update forms. Path identity stays out of the body. */
-import type { VmProps } from './qemu.ts';
-
-/** Fields both create and update send. `net0` is optional and is not compared. */
-export const shape = (props: VmProps) => ({
-  cores: String(props.cores ?? 1),
-  memory: String(props.memory ?? 512),
-  name: props.name ?? `vm${String(props.vmid)}`,
-  onboot: props.onboot === true ? '1' : '0',
-  sockets: String(props.sockets ?? 1),
-  ...(props.net0 === undefined ? {} : { net0: props.net0 }),
+/**
+ * QEMU create and update forms — declared keys only. Path identity stays out of the body.
+ *
+ * ⛔ NO DEFAULT IS EVER SUBSTITUTED FOR AN UNDECLARED FIELD. See qemu-props.ts's header for the
+ *   "5-default PUT" this replaces: the old `shape()` sent `cores`/`memory`/`name`/`onboot`/
+ *   `sockets` on every write, defaults included for whichever the declaration left out, so
+ *   editing one field on an adopted VM silently reset every other to its factory value.
+ */
+import {
+  type VmProps,
+  declaredKeys,
+  declaredValue,
+  isManagedKey,
+  wireValue,
+} from './qemu-props.ts';
+
+/**
+ * Why a declared key cannot go on the wire, checked before every create and every update.
+ * ★ THE SAME RULE `lxc-create-form.ts` ENFORCES FOR `Proxmox.Lxc`: a key smuggled past the types
+ *   (a cast, a JS caller) is refused here rather than silently dropped or silently sent.
+ */
+export const formRefusals = (props: VmProps): string[] =>
+  declaredKeys(props)
+    .filter((key) => !isManagedKey(key))
+    .map((key) => `${key}: not a config key this resource manages (vmid ${String(props.vmid)}).`);
+
+/** The declared config, wire-spelled — every key `formRefusals` did not already refuse. */
+export const form = (props: VmProps): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const key of declaredKeys(props)) {
+    if (!isManagedKey(key)) continue;
+    out[key] = wireValue(declaredValue(props, key));
+  }
+  return out;
+};
+
+/**
+ * The create body: the declared form plus the vmid a create needs.
+ * ⚠️ NO RETURN-TYPE ANNOTATION, ON PURPOSE. Annotating this `Record<string, string>` erases the
+ *   object literal's own inferred shape, and with it the one thing `nodes.createNodeQemu({
+ *   ...createForm(news), node: news.node })` (qemu-lifecycle.ts) needs: TypeScript only accepts a
+ *   spread as satisfying `CreateNodeQemuRequest`'s required `vmid` when the spread's inferred type
+ *   still carries `vmid` as a literal key, which an index-signature-only type cannot prove.
+ */
+export const createForm = (props: VmProps) => ({
+  ...form(props),
+  vmid: String(props.vmid),
 });
 
-/** ★ Exported so the constraint proof can run the REAL create form, not a retyped copy of it. */
-export const createForm = (props: VmProps) => ({ ...shape(props), vmid: String(props.vmid) });
+/** The update body — identical construction to `createForm`, minus `vmid`, which PUT never sends. */
+export const updateForm = form;

package/src/proxmox/qemu-identity.test.ts

@@ -0,0 +1,30 @@
+/**
+ * `Proxmox.Vm` identity — red-team I1 on PR 297, through the real engine over a stub fetch.
+ * ⛔ WHAT THIS PINS: a changed `vmid` on an already-managed VM is refused as a different machine,
+ *   never planned as an `update` (which used to POST a second VM and leave the first one running
+ *   and untracked).
+ */
+import { expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxVm, ProxmoxVmProvider } from './qemu.ts';
+
+const NODE = 'pve1';
+const props = { node: NODE, target: FAKE_TARGET, vmid: 150 };
+const live = { digest: 'a'.repeat(40), memory: '512' };
+
+const engine = (fake: ReturnType<typeof fakePve>) =>
+  engineOver(ProxmoxVmProvider().pipe(Layer.provideMerge(fake.layer)));
+
+test('a changed vmid is refused as a different VM, never planned as an update', async () => {
+  const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+  await withoutBao(async () => {
+    const stack = engine(fake);
+    await stack.deploy(ProxmoxVm('row', props));
+    await expect(stack.deploy(ProxmoxVm('row', { ...props, vmid: 151 }))).rejects.toThrow(
+      /vmid: 150 -> 151 is a different VM/,
+    );
+  });
+  expect(fake.writes()).toEqual([]);
+});

package/src/proxmox/qemu-judge.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure unit tests for `judge`/`identityRefusal` — red-team C1/I1 on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: only drifted keys are ever PUT (an unrelated field's drift does not drag the
+ *   disk/NIC keys along, the failure mode a whole-form resend had); a vmid change is refused, never
+ *   built as a second VM.
+ */
+import { describe, expect, test } from 'bun:test';
+import { FAKE_TARGET } from './fake-pve.ts';
+import { identityRefusal, judge } from './qemu-judge.ts';
+import type { VmProps } from './qemu-props.ts';
+
+const base = { node: 'pve1', target: FAKE_TARGET, vmid: 101 } as const;
+
+describe('judge', () => {
+  test('a fresh-spelled disk and a MAC-less NIC both settle against live, drifting nothing', () => {
+    const props: VmProps = {
+      ...base,
+      ide2: 'cephtb4:cloudinit',
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const config = {
+      ide2: 'cephtb4:vm-101-cloudinit,media=cdrom',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-101-disk-0,size=32G',
+    };
+    expect(judge(props, config)).toEqual({ drift: [], put: {}, refuse: [] });
+  });
+
+  test('an unrelated field drifting does not drag the settled disk/NIC keys into the PUT', () => {
+    const props: VmProps = {
+      ...base,
+      memory: 4096,
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const config = {
+      memory: '2048',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-101-disk-0,size=32G',
+    };
+    const change = judge(props, config);
+    expect(change.drift).toEqual(['memory']);
+    expect(change.put).toEqual({ memory: '4096' });
+  });
+
+  test('a scalar key not yet on the live config is put as declared', () => {
+    const change = judge({ ...base, agent: true }, {});
+    expect(change.put).toEqual({ agent: '1' });
+  });
+});
+
+describe('identityRefusal', () => {
+  test('no prior vmid: never refused (a fresh create)', () => {
+    expect(identityRefusal(101, undefined)).toBeUndefined();
+  });
+
+  test('the same vmid: never refused', () => {
+    expect(identityRefusal(101, 101)).toBeUndefined();
+  });
+
+  test('a changed vmid: refused, naming both -- a new resource, not an update', () => {
+    expect(identityRefusal(151, 150)).toMatch(/vmid: 150 -> 151 is a different VM/);
+  });
+});

package/src/proxmox/qemu-judge.ts

@@ -0,0 +1,84 @@
+/**
+ * Declared against live: what a `Proxmox.Vm` deploy would write, per key — the QEMU sibling of
+ * lxc-judge.ts, added 2026-09-26 (red-team C1/I1 on PR 297).
+ *
+ * ⛔ REPLACES A WHOLE-STRING, WHOLE-FORM COMPARISON. Before this, `matches` compared each declared
+ *   key to live BYTE FOR BYTE and, on any drift, `formToSend` re-PUT every declared key at once
+ *   (qemu-lifecycle.ts). A `scsi0`/`ide2`/`net0` declared in the "new" or MAC-less spelling then
+ *   NEVER matched its own live volume/NIC (qemu-volume.ts / qemu-net.ts explain why), so every
+ *   deploy re-sent all three -- reallocating the disk, re-importing it, and handing out a fresh MAC
+ *   each time, even when nothing else changed. `judge` below decides per key, on the LIVE volume id
+ *   and LIVE MAC, so an unrelated field's drift no longer drags the disk/NIC keys along with it.
+ */
+import { type VmProps, declaredKeys, declaredValue, indexedKey, wireValue } from './qemu-props.ts';
+import { judgeDisk } from './qemu-volume.ts';
+import { netWrite, sameNet } from './qemu-net.ts';
+
+export type VmChange = {
+  /** Keys to `PUT …/config`, wire-spelled and built on live ids where one exists. */
+  readonly put: Record<string, string>;
+  /** Why a key cannot be written as an update. Non-empty means nothing is written. */
+  readonly refuse: readonly string[];
+  /** Every declared key that differs from live, refused or not. */
+  readonly drift: readonly string[];
+};
+
+export const judge = (props: VmProps, config: Record<string, string>): VmChange => {
+  const put: Record<string, string> = {};
+  const refuse: string[] = [];
+  const drift = new Set<string>();
+
+  for (const key of declaredKeys(props)) {
+    const want = wireValue(declaredValue(props, key));
+    const have = config[key];
+    const family = indexedKey(key)?.[0];
+
+    if (family === 'scsi' || family === 'ide') {
+      if (have === undefined) {
+        drift.add(key);
+        put[key] = want;
+      } else {
+        const verdict = judgeDisk(key, want, have);
+        if (verdict.refuse !== undefined) {
+          drift.add(key);
+          refuse.push(verdict.refuse);
+        } else if (verdict.put !== undefined) {
+          drift.add(key);
+          put[key] = verdict.put;
+        }
+      }
+      continue;
+    }
+
+    if (family === 'net') {
+      if (have === undefined) {
+        drift.add(key);
+        put[key] = want;
+      } else if (!sameNet(want, have)) {
+        drift.add(key);
+        put[key] = netWrite(want, have);
+      }
+      continue;
+    }
+
+    // Scalars, `ipconfigN`, `serialN`: a plain string compare, as the old whole-form model did.
+    // ⚠️ No "new spelling" or MAC ambiguity applies to these -- see qemu-props.ts's own doc per key.
+    if (want !== (have ?? '')) {
+      drift.add(key);
+      put[key] = want;
+    }
+  }
+  return { drift: [...drift].sort(), put, refuse };
+};
+
+/**
+ * What makes a `Proxmox.Vm` a DIFFERENT machine: a new vmid (red-team I1). Never planned as a
+ * replace -- see qemu.ts's header on why nothing here replaces a running VM.
+ * ⚠️ `was` PREFERS THE RECORDED ATTRIBUTE, so a `node` change (HA failover, a hand `qm migrate`)
+ *   never reads as a vmid change: only `vmid` is judged here, mirroring lxc-identity.ts.
+ */
+export const identityRefusal = (vmid: number, was: number | undefined): string | undefined =>
+  was === undefined || vmid === was
+    ? undefined
+    : `vmid: ${String(was)} -> ${String(vmid)} is a different VM. Declare it as a new resource; ` +
+      'this one is retained when its declaration goes.';