@homeflare/alchemy 0.37.8 → 0.39.0

package/src/proxmox/qemu-lifecycle.ts

@@ -3,50 +3,56 @@
  * ⛔ GET and PUT use `/nodes/{node}/qemu/{vmid}/config`. DELETE uses `/nodes/{node}/qemu/{vmid}`.
  *   qemu-server Qemu.pm names that second route `destroy_vm`. Sending DELETE to the config
  *   route does not destroy the guest.
+ *
+ * ⛔ WRITES GO THROUGH `qemu-judge.ts`, NOT A WHOLE-FORM PUT (2026-09-26, red-team C1/C2/I1 on
+ *   PR 297). `judge` decides per key, on the live volume id and live MAC (qemu-volume.ts,
+ *   qemu-net.ts); only drifted keys are sent. `ownedRead`/`refuseTakeover` (C2) refuse to adopt or
+ *   write a live VM this stack holds no state for, unless `--adopt` / `adopt(true)` says so —
+ *   ownership.md's rule, ported here the way openbao/policy.ts already does it. `identityRefusal`
+ *   (I1) refuses a changed vmid rather than building a second VM.
  */
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as nodes from '@distilled.cloud/proxmox/nodes';
 import * as Effect from 'effect/Effect';
+import { refuseTakeover } from '../ownership/adopt.ts';
+import { ownedRead } from '../ownership/probe.ts';
 import { runPve } from './distilled-pve.ts';
-import { createForm, shape } from './qemu-form.ts';
+import { createForm, formRefusals, updateForm } from './qemu-form.ts';
 import { QemuRefusedError } from './qemu-errors.ts';
+import { identityRefusal, judge } from './qemu-judge.ts';
+import {
+  type VmAttributes,
+  type VmProps,
+  declaredKeys,
+  declaredValue,
+  isManagedKey,
+  storedConfig,
+  wireValue,
+} from './qemu-props.ts';
 import { readVm } from './qemu-read.ts';
 import { qemuTask } from './qemu-task.ts';
-import type { VmAttributes, VmProps } from './qemu.ts';
 import type { PveSpec } from './resource-spec.ts';
 import { specGuards } from './resource-guard.ts';
-import { formToSend } from './update-guard.ts';
-import { int } from './values.ts';
 
 const CREATE_POLLS = 180;
 const DELETE_POLLS = 60;
 
-const attributesOf = (
-  live: {
-    cores?: unknown;
-    memory?: unknown;
-    name?: unknown;
-    onboot?: unknown;
-    sockets?: unknown;
-  },
-  props: VmProps,
-): VmAttributes => ({
-  cores: int(live.cores, 1),
-  memory: int(live.memory, 512),
-  name: typeof live.name === 'string' ? live.name : '',
+const attributesOf = (live: Record<string, unknown>, props: VmProps): VmAttributes => ({
+  config: storedConfig(live),
   node: props.node,
-  onboot: live.onboot === 1 || live.onboot === true,
-  sockets: int(live.sockets, 1),
   vmid: props.vmid,
 });
 
+/**
+ * ⚠️ KEPT ONLY TO SATISFY `PveSpec`'S REQUIRED FIELD — `qemu-judge.ts`'s `judge` is what diff and
+ *   reconcile actually decide by, since a plain string compare is exactly the bug C1 found (it
+ *   never matches the "new disk" or MAC-less spellings a declaration may use).
+ */
 const matches = (attributes: VmAttributes, props: VmProps) =>
-  attributes.name === (props.name ?? `vm${String(props.vmid)}`) &&
-  attributes.memory === (props.memory ?? 512) &&
-  attributes.cores === (props.cores ?? 1) &&
-  attributes.sockets === (props.sockets ?? 1) &&
-  attributes.onboot === (props.onboot === true);
+  declaredKeys(props)
+    .filter(isManagedKey)
+    .every((key) => attributes.config[key] === wireValue(declaredValue(props, key)));
 
 const spec = {
   attributes: attributesOf,
@@ -58,14 +64,24 @@ const spec = {
   },
   matches,
   path: (props: VmProps) => `nodes/${props.node}/qemu/${String(props.vmid)}/config`,
-  updateForm: shape,
+  updateForm,
 } satisfies PveSpec<VmProps, VmAttributes>;
 
 const { guardCreate, guardUpdate } = specGuards(spec);
 
 export const readQemu = (props: VmProps) =>
   readVm(props).pipe(
-    Effect.map((live) => (live === undefined ? undefined : attributesOf(live, props))),
+    Effect.map((live) =>
+      live === undefined
+        ? undefined
+        : // ⚠️ WIDENED ON PURPOSE. `GetNodeQemuConfigResponse` types only the keys pve-manager's
+          //   apidoc names as SCALARS; it cannot express `scsi[n]`/`net[n]`/`ipconfig[n]` at all
+          //   (qemu-props.ts's header), so it carries no index signature. `storedConfig` reads
+          //   those keys anyway, because the ACTUAL wire response has them (protocol-http.ts's
+          //   `mapKeys` passes an unrecognised key through undecoded, both directions) — this
+          //   cast only tells TypeScript what runtime already knows.
+          attributesOf(live as unknown as Record<string, unknown>, props),
+    ),
   );
 
 /** No purge, no skiplock, no destroy-unreferenced-disks. A missing config is already gone. */
@@ -77,28 +93,95 @@ export const deleteQemu = (props: VmProps) =>
     DELETE_POLLS,
   ).pipe(Effect.catchTag('QemuConfigNotFound', () => Effect.void));
 
+/**
+ * ★ ONE PLACE, RUN BEFORE EVERY DIFF AND EVERY RECONCILE. A key smuggled past `VmProps`'s types
+ *   (a cast, a JS caller: `cipassword`, `machine`, `hookscript`) is refused here rather than
+ *   silently dropped from the form or silently sent — the same rule `lxc-create-form.ts` enforces
+ *   for `Proxmox.Lxc`, and the check `qemu-props.ts`'s `cipassword?: never`/`machine?: never`
+ *   cannot make by itself once a caller casts around the type.
+ */
+const refuseUnmanaged = (props: VmProps) => {
+  const refused = formRefusals(props);
+  return refused.length === 0 ? Effect.void : Effect.fail(new QemuRefusedError(refused.join('\n')));
+};
+
+const refuseChange = (change: { readonly refuse: readonly string[] }) =>
+  change.refuse.length === 0
+    ? Effect.void
+    : Effect.fail(new QemuRefusedError(change.refuse.join('\n')));
+
 export const qemuHandlers = {
   list: () => Effect.succeed([]),
-  read: ({ olds }: { olds: VmProps }) => readQemu(olds),
+  /**
+   * ⛔ `Unowned` UNLESS STATE ALREADY VOUCHES FOR IT (C2). With no attributes this is Alchemy's
+   *   adoption probe or the recovery read for an interrupted create (ownership/probe.ts); `settled`
+   *   is the same `judge` reconcile uses, so "proven ours" and "reconcile would write nothing" are
+   *   the same question asked once.
+   */
+  read: Effect.fn(function* ({
+    fqn,
+    instanceId,
+    olds,
+    output,
+  }: {
+    fqn: string;
+    instanceId: string;
+    olds: VmProps;
+    output: VmAttributes | undefined;
+  }) {
+    const found = yield* readQemu(olds);
+    const settled = Effect.sync(
+      () => found !== undefined && judge(olds, found.config).drift.length === 0,
+    );
+    return yield* ownedRead({ fqn, instanceId, output }, found, settled);
+  }),
   diff: Effect.fn(function* ({
     news,
+    olds,
     output,
   }: {
     news: Input<VmProps>;
+    olds: VmProps;
     output: VmAttributes | undefined;
   }) {
     if (!isResolved(news)) return undefined;
+    const identity = identityRefusal(news.vmid, output?.vmid ?? olds.vmid);
+    if (identity !== undefined) return yield* Effect.fail(new QemuRefusedError(identity));
+    yield* refuseUnmanaged(news);
     yield* guardCreate(news, output === undefined);
     yield* guardUpdate(news);
     if (output === undefined) return undefined;
     const live = yield* readQemu(news);
     if (live === undefined) {
+      // ⚠️ `update`, not `create`: state exists and the VM does not. reconcile rebuilds it from the
+      //   declaration -- said here too, so an operator reading the plan sees it before the deploy.
+      yield* Effect.logWarning(
+        `Proxmox.Vm ${news.node}/${String(news.vmid)}: the cluster lists no VM with this vmid -- ` +
+          'a deploy CREATES it again, with new, empty volumes.',
+      );
       yield* guardCreate(news, true);
       return { action: 'update' } as const;
     }
-    return { action: spec.matches(live, news) ? 'noop' : 'update' } as const;
+    const change = judge(news, live.config);
+    yield* refuseChange(change);
+    return { action: change.drift.length === 0 ? 'noop' : 'update' } as const;
   }),
-  reconcile: Effect.fn(function* ({ news }: { news: VmProps }) {
+  reconcile: Effect.fn(function* ({
+    fqn,
+    instanceId,
+    news,
+    olds,
+    output,
+  }: {
+    fqn: string;
+    instanceId: string;
+    news: VmProps;
+    olds: VmProps | undefined;
+    output: VmAttributes | undefined;
+  }) {
+    const identity = identityRefusal(news.vmid, output?.vmid ?? olds?.vmid);
+    if (identity !== undefined) return yield* Effect.fail(new QemuRefusedError(identity));
+    yield* refuseUnmanaged(news);
     const live = yield* readQemu(news);
     yield* guardCreate(news, live === undefined);
     yield* guardUpdate(news);
@@ -110,13 +193,20 @@ export const qemuHandlers = {
         CREATE_POLLS,
       );
     } else {
-      const form = formToSend(spec.matches, live, news, spec.updateForm(news));
-      if (form !== undefined) {
+      // ⛔ C2: a live VM this stack holds no state for is refused unless adoption is on — dies
+      //   (never returns) for a fresh create/replace generation; a no-op otherwise (adopt.ts).
+      yield* refuseTakeover(
+        { fqn, instanceId, output },
+        `Proxmox.Vm VM ${String(news.vmid)} on ${news.node}`,
+      );
+      const change = judge(news, live.config);
+      yield* refuseChange(change);
+      if (Object.keys(change.put).length > 0) {
         yield* runPve(
           news.target,
           'provision',
           true,
-          nodes.putNodeQemuConfig({ ...form, node: news.node, vmid: String(news.vmid) }),
+          nodes.putNodeQemuConfig({ ...change.put, node: news.node, vmid: String(news.vmid) }),
         );
       }
     }
@@ -128,6 +218,15 @@ export const qemuHandlers = {
         ),
       );
     }
+    const left = judge(news, after.config);
+    if (left.drift.length > 0) {
+      return yield* Effect.fail(
+        new QemuRefusedError(
+          `${spec.path(news)}: after the write, ${left.drift.join(', ')} still differ from the ` +
+            'declaration. PVE may have normalised the value -- declare what it stores.',
+        ),
+      );
+    }
     return after;
   }),
   delete: ({ olds }: { olds: VmProps }) => deleteQemu(olds),

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

@@ -0,0 +1,48 @@
+/**
+ * Pure unit tests for `sameNet`/`netWrite` — the red-team C1 fix on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: a MAC-less (or bare-model) declaration matches a live NIC with any MAC, and
+ *   never generates a new one when written; an explicit MAC is compared and written as declared; a
+ *   real drift elsewhere on the line (VLAN tag, bridge) still shows up.
+ */
+import { describe, expect, test } from 'bun:test';
+import { netWrite, sameNet } from './qemu-net.ts';
+
+const LIVE = 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20';
+
+describe('a MAC-less declaration', () => {
+  test('bare model token matches a live NIC with any MAC: the measured C1 regression', () => {
+    expect(sameNet('virtio,bridge=vmbr0,tag=20', LIVE)).toBe(true);
+  });
+
+  test('empty-value spelling matches too', () => {
+    expect(sameNet('virtio=,bridge=vmbr0,tag=20', LIVE)).toBe(true);
+  });
+
+  test('writing it carries the LIVE mac forward, never regenerating one', () => {
+    expect(netWrite('virtio,bridge=vmbr0,tag=21', LIVE)).toBe(
+      'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=21',
+    );
+  });
+});
+
+describe('an explicit MAC', () => {
+  test('a matching MAC is a noop', () => {
+    expect(sameNet(LIVE, LIVE)).toBe(true);
+  });
+
+  test('a different MAC is real drift and is written as declared', () => {
+    const declared = 'virtio=11:22:33:44:55:66,bridge=vmbr0,tag=20';
+    expect(sameNet(declared, LIVE)).toBe(false);
+    expect(netWrite(declared, LIVE)).toBe(declared);
+  });
+});
+
+describe('a real change elsewhere on the line', () => {
+  test('a different VLAN tag is drift even with the MAC substituted', () => {
+    expect(sameNet('virtio,bridge=vmbr0,tag=42', LIVE)).toBe(false);
+  });
+
+  test('a different bridge is drift', () => {
+    expect(sameNet('virtio,bridge=vmbr1,tag=20', LIVE)).toBe(false);
+  });
+});

package/src/proxmox/qemu-net.ts

@@ -0,0 +1,78 @@
+/**
+ * `netN`: comparing a declared NIC against a live one without regenerating its MAC every deploy.
+ *
+ * ★ PORTED FROM lxc-wire.ts's `netMaps`/`netWrite` (2026-09-26, red-team C1 on PR 297), adapted for
+ *   QEMU's spelling. A container's `net0` carries a `hwaddr=` sub-key; a VM's carries the MAC as the
+ *   VALUE of whichever NIC-model key is present — `virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0` — with the
+ *   model itself (`e1000`, `virtio`, …) chosen by pve-qemu-server's own model list, not a fixed key
+ *   name. A declaration with no MAC spells the model bare (`virtio,bridge=vmbr0,tag=20`) or with an
+ *   empty value (`virtio=,bridge=vmbr0`); PVE generates one on create either way.
+ * ⛔ WITHOUT THIS, A PUT OF AN UNCHANGED NIC GENERATES A NEW MAC — a new DHCP lease and a new IPv6
+ *   link-local address for a guest that only had, say, its VLAN tag edited. Measured by the
+ *   builder's red team against a MAC-less `net0` declaration.
+ * ⚠️ OTHER SUB-KEYS (`firewall`, `link_down`, `mtu`, `queues`, `rate`, `tag`, `trunks`) COMPARE
+ *   RAW, NO DEFAULTS DROPPED — that table is unverified here, unlike lxc-wire.ts's `DEFAULTS`. A
+ *   difference in one is real drift and gets written, exactly as the whole-string comparison this
+ *   replaces already did; only the MAC is special-cased, the minimum that fixes the measured bug.
+ */
+/** pve-qemu-server's own `$nic_model_list` — whichever of these is present is the MAC-bearing key. */
+const NIC_MODELS = [
+  'e1000',
+  'e1000e',
+  'i82551',
+  'i82557b',
+  'i82559er',
+  'i82562',
+  'i82801',
+  'ne2k_isa',
+  'ne2k_pci',
+  'pcnet',
+  'rtl8139',
+  'virtio',
+  'vmxnet3',
+] as const;
+
+/** `a=1,b=2` or a bare `a` (→ `['a', '']`) — the one-off parser this file needs, not lxc-wire's. */
+const netPairs = (value: string): Map<string, string> =>
+  new Map(
+    value
+      .split(',')
+      .map((part) => part.trim())
+      .filter((part) => part !== '')
+      .map((part): [string, string] => {
+        const at = part.indexOf('=');
+        return at === -1 ? [part, ''] : [part.slice(0, at), part.slice(at + 1)];
+      }),
+  );
+
+const modelKey = (map: ReadonlyMap<string, string>): string | undefined =>
+  NIC_MODELS.find((model) => map.has(model));
+
+/** The MAC-substituted comparison maps: an undeclared/blank MAC is PVE's, not drift. */
+export const netMaps = (declared: string, live: string) => {
+  const want = netPairs(declared);
+  const have = netPairs(live);
+  const wantModel = modelKey(want);
+  const haveModel = modelKey(have);
+  if (wantModel !== undefined && (want.get(wantModel) ?? '') === '' && haveModel !== undefined) {
+    want.set(wantModel, have.get(haveModel) ?? '');
+  }
+  return { have, want };
+};
+
+export const sameNet = (declared: string, live: string): boolean => {
+  const { have, want } = netMaps(declared, live);
+  return have.size === want.size && [...want].every(([k, v]) => have.get(k) === v);
+};
+
+/** The value to PUT: the declaration, plus the live MAC when it names none. */
+export const netWrite = (declared: string, live: string): string => {
+  const want = netPairs(declared);
+  const wantModel = modelKey(want);
+  const have = netPairs(live);
+  const haveModel = modelKey(have);
+  if (wantModel !== undefined && (want.get(wantModel) ?? '') === '' && haveModel !== undefined) {
+    want.set(wantModel, have.get(haveModel) ?? '');
+  }
+  return [...want].map(([k, v]) => (v === '' ? k : `${k}=${v}`)).join(',');
+};

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

@@ -0,0 +1,44 @@
+/**
+ * Whose VM it is — docs/ownership.md applied to `Proxmox.Vm` (red-team C2 on PR 297), through the
+ * real engine over a stub fetch (fake-pve.ts).
+ *
+ * ⛔ WHAT THIS PINS: a live VM this stack holds no state for is never adopted or written silently
+ *   (the measured regression: `adopt(false)` on an existing VM still planned `adopted` and PUT it).
+ *   `adopt(false)` on the declaration wins over the test harness's own forced `AdoptPolicy: true`
+ *   (fake-engine.ts) — a resource-scoped `adopt(...)` overrides the ambient policy both ways
+ *   (ownership/adopt.ts), which is what lets this test observe the refusal at all.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adopt } from 'alchemy/AdoptPolicy';
+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 VMID = 150;
+const props = { node: NODE, target: FAKE_TARGET, vmid: VMID };
+const live = { digest: 'a'.repeat(40), memory: '512' };
+
+const engine = (fake: ReturnType<typeof fakePve>) =>
+  engineOver(ProxmoxVmProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.Vm ownership', () => {
+  test('adopt(false): a live VM with no state is refused, and nothing is written', async () => {
+    const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxVm('row', props).pipe(adopt(false)))).rejects.toThrow(
+        /adopt|exists, and this stack holds no state/i,
+      );
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+
+  test('the harness default (adoption on) still adopts with no write — unchanged behaviour', async () => {
+    const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+    await withoutBao(async () => {
+      expect(await engine(fake).deploy(ProxmoxVm('row', props))).toEqual({ row: 'adopted' });
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+});

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

@@ -0,0 +1,87 @@
+/**
+ * Pure unit tests for the declared-keys model: no network, no fake PVE. The engine-level proof
+ * that an unmanaged key is refused before any write lives in qemu-lifecycle.test.ts, alongside
+ * the node-pinned-refusal and 5-default-PUT regression tests.
+ */
+import { describe, expect, test } from 'bun:test';
+import { formRefusals } from './qemu-form.ts';
+import {
+  type VmProps,
+  declaredKeys,
+  indexedKey,
+  isManagedKey,
+  storedConfig,
+  wireValue,
+} from './qemu-props.ts';
+import { FAKE_TARGET } from './fake-pve.ts';
+
+const base = { node: 'pve1', target: FAKE_TARGET, vmid: 150 } as const;
+
+describe('declaredKeys', () => {
+  test('excludes identity fields and undeclared ones, and sorts what is left', () => {
+    const props: VmProps = { ...base, cores: 2, memory: 4096 };
+    expect(declaredKeys(props)).toEqual(['cores', 'memory']);
+  });
+
+  test('an empty declaration manages nothing — the base for every "adopt as-is" test', () => {
+    expect(declaredKeys(base as unknown as VmProps)).toEqual([]);
+  });
+});
+
+describe('isManagedKey / indexedKey', () => {
+  test('the scalar and indexed families Talos needs are all managed', () => {
+    for (const key of [
+      'agent',
+      'boot',
+      'cpu',
+      'memory',
+      'scsihw',
+      'scsi0',
+      'net0',
+      'ide2',
+      'ipconfig0',
+      'serial0',
+    ]) {
+      expect(isManagedKey(key)).toBe(true);
+    }
+  });
+
+  test('⛔ no secret prop exists: cipassword and machine are never managed keys', () => {
+    expect(isManagedKey('cipassword')).toBe(false);
+    expect(isManagedKey('machine')).toBe(false);
+  });
+
+  test('an out-of-range index is not a PVE key this resource recognises', () => {
+    expect(indexedKey('scsi31')).toBeUndefined(); // pve-qemu-server's own 0-30
+    expect(indexedKey('ide4')).toBeUndefined(); // 0-3
+    expect(indexedKey('scsi03')).toBeUndefined(); // not how PVE spells it
+  });
+});
+
+describe('wireValue / storedConfig', () => {
+  test('booleans go as 1/0, everything else as String()', () => {
+    expect(wireValue(true)).toBe('1');
+    expect(wireValue(false)).toBe('0');
+    expect(wireValue(4096)).toBe('4096');
+    expect(wireValue('local-zfs:32')).toBe('local-zfs:32');
+  });
+
+  test('storedConfig is an allowlist: an unmanaged live key never reaches state', () => {
+    const live = { cipassword: 'leaked', cores: 2, digest: 'a'.repeat(40), scsi0: 'local:32' };
+    expect(storedConfig(live)).toEqual({ cores: '2', scsi0: 'local:32' });
+  });
+});
+
+describe('formRefusals — the runtime backstop behind the never-typed props', () => {
+  test('a clean declaration is refused nothing', () => {
+    expect(formRefusals({ ...base, agent: true, net0: 'bridge=vmbr0,tag=42' })).toEqual([]);
+  });
+
+  test('a key smuggled past the types is named, not silently dropped or silently sent', () => {
+    const smuggled = { ...base, cipassword: 'x', machine: 'q35' } as unknown as VmProps;
+    expect(formRefusals(smuggled)).toEqual([
+      'cipassword: not a config key this resource manages (vmid 150).',
+      'machine: not a config key this resource manages (vmid 150).',
+    ]);
+  });
+});

package/src/proxmox/qemu-props.ts

@@ -0,0 +1,157 @@
+/**
+ * What a `Proxmox.Vm` declaration says, and what its state keeps.
+ *
+ * ★ THE SAME "DECLARED KEYS" MODEL AS `Proxmox.Lxc` (lxc-props.ts, joined 2026-09-21): an
+ *   undeclared key is UNMANAGED — never sent, never compared, never overwritten. Adopting a live
+ *   VM is then a paste of its config, not a translation of it, and the wire spelling is PVE's own
+ *   (`scsi0`, `net0`, `ipconfig0`, as `pvesh get .../qemu/{vmid}/config` prints them).
+ *
+ * ⛔ THIS REPLACES THE "5-DEFAULT PUT". Before 2026-09-26, `qemu-form.ts`'s `shape()` sent
+ *   `cores`/`memory`/`name`/`onboot`/`sockets` on EVERY write with a hard default substituted for
+ *   whichever of the five was left undeclared, so declaring only `memory: 4096` on an adopted VM
+ *   still PUT `name: 'vm101'` and `sockets: '1'` over whatever the guest actually had. Harmless
+ *   while `ProxmoxVm` stayed Provider-only (nothing declared it), load-bearing the moment Talos
+ *   does. `declaredKeys` below is the fix: a field absent from the declaration is never read,
+ *   never compared and never written — see qemu-form.ts's `form()`.
+ *
+ * ⛔ NO SECRET IS A PROP. `cipassword` (cloud-init's password) is write-only and Alchemy persists
+ *   props in plaintext (this estate's state store is dumped nightly) — typed `never`, exactly
+ *   like lxc-props.ts's `password`. A VM that needs a login uses `sshkeys`-free image defaults or
+ *   an out-of-band secret; this resource never carries one.
+ * ⛔ `machine` IS NEVER A PROP EITHER. It pins the emulated chipset/firmware revision a guest boots
+ *   against; PVE already resolves it from the node's installed QEMU version, and declaring it here
+ *   would fight every future node upgrade instead of tracking it. Typed `never` for the same
+ *   reason `cipassword` is: a cast is the only way in, and this file's helpers below never read
+ *   an unmanaged key onto the wire regardless.
+ */
+import type { WithTarget } from './resource.ts';
+
+/** A PVE boolean as pvesh prints it (`1`) or as TypeScript writes it (`true`). The same value. */
+export type PveFlag = boolean | 0 | 1;
+
+export interface VmProps extends WithTarget {
+  /** ⛔ This resource never migrates: qemu-read.ts refuses a VM found on another node. */
+  node: string;
+  /** ⛔ Cluster-wide, and shared with LXC. See qemu.ts's header. */
+  vmid: number;
+  name?: string;
+  /** MiB. */
+  memory?: number;
+  cores?: number;
+  sockets?: number;
+  /** Emulated CPU type, e.g. `host`. */
+  cpu?: string;
+  onboot?: PveFlag;
+  /** The QEMU guest agent. Talos reports its addresses through it once this is enabled. */
+  agent?: PveFlag;
+  /** `order=scsi0;ide2;net0`. */
+  boot?: string;
+  /** e.g. `virtio-scsi-single`. */
+  scsihw?: string;
+  /**
+   * `local-zfs:32` to create a new volume, or the live volume string as adopted —
+   * `cephtb4:vm-101-disk-0,size=32G` (n is 0 to 30, pve-qemu-server's own `$MAX_SCSI_DISKS`).
+   */
+  [scsi: `scsi${number}`]: string | undefined;
+  /**
+   * `virtio=<mac>,bridge=vmbr0,tag=<vlan>` — a VLAN-aware bridge with an 802.1q tag is a bridge
+   * plus this one sub-property; PVE's SDN stays out of it entirely (n is 0 to 31).
+   */
+  [nic: `net${number}`]: string | undefined;
+  /**
+   * The cloud-init drive, e.g. `cephtb4:cloudinit`. PVE's own web UI puts it on `ide2`, but any
+   * free `ide`/`sata`/`scsi` slot works; declaring one is what gives `ipconfig0` below somewhere
+   * to write the generated seed image (n is 0 to 3).
+   */
+  [cloudinit: `ide${number}`]: string | undefined;
+  /** cloud-init network config: `ip=dhcp`, or `ip=<cidr>,gw=<gw>` (n is 0 to 31). */
+  [ipconfig: `ipconfig${number}`]: string | undefined;
+  /** `socket` — a serial console, the way Talos exposes its own (n is 0 to 3). */
+  [serial: `serial${number}`]: string | undefined;
+  /** ⛔ A secret. See the header. */
+  cipassword?: never;
+  /** ⛔ Machine config. See the header. */
+  machine?: never;
+}
+
+export interface VmAttributes {
+  node: string;
+  vmid: number;
+  /** The live config, MANAGED keys only — see `storedConfig`. An allowlist, not a mirror. */
+  config: Record<string, string>;
+}
+
+/** Props that identify the object rather than configure it: never sent, never compared. */
+const NOT_CONFIG: ReadonlySet<string> = new Set(['node', 'target', 'vmid']);
+
+/** The indexed families this resource manages, with pve-qemu-server's own published range. */
+export const INDEXED = {
+  ide: 4,
+  ipconfig: 32,
+  net: 32,
+  scsi: 31,
+  serial: 4,
+} as const;
+export type IndexedFamily = keyof typeof INDEXED;
+
+/** `scsi3` → `['scsi', 3]`; anything else, including an out-of-range index, → undefined. */
+export const indexedKey = (key: string): readonly [IndexedFamily, number] | undefined => {
+  const match = /^(ide|ipconfig|net|scsi|serial)(0|[1-9]\d*)$/.exec(key);
+  if (match === null) return undefined;
+  const family = match[1] as IndexedFamily;
+  const index = Number(match[2]);
+  return index < INDEXED[family] ? [family, index] : undefined;
+};
+
+/** The scalar (non-indexed) keys this resource manages. */
+const SCALAR_KEYS: ReadonlySet<string> = new Set([
+  'agent',
+  'boot',
+  'cores',
+  'cpu',
+  'memory',
+  'name',
+  'onboot',
+  'scsihw',
+  'sockets',
+]);
+
+/**
+ * A key this resource compares and may write. ⛔ EVERYTHING ELSE IS REFUSED, NEVER SILENTLY
+ *   DROPPED OR SILENTLY SENT — `qemu-form.ts`'s `formRefusals` is what a declared key smuggled
+ *   past the types (a cast, a JS caller: `cipassword`, `machine`, `hookscript`) meets before any
+ *   write, the same rule `lxc-create-form.ts` enforces for `Proxmox.Lxc`.
+ */
+export const isManagedKey = (key: string): boolean =>
+  SCALAR_KEYS.has(key) || indexedKey(key) !== undefined;
+
+/** A declaration read by key. ⚠️ The cast is the one place a template-literal index meets a plain string. */
+export const declaredValue = (props: VmProps, key: string): unknown =>
+  (props as unknown as Record<string, unknown>)[key];
+
+/** The declared keys with a value, in a stable order — never `node`/`target`/`vmid`. */
+export const declaredKeys = (props: VmProps): string[] =>
+  Object.keys(props)
+    .filter((key) => !NOT_CONFIG.has(key) && declaredValue(props, key) !== undefined)
+    .sort();
+
+/** One declared value as PVE's wire string. Booleans go as `1`/`0`, numbers as their decimal. */
+export const wireValue = (value: unknown): string =>
+  value === true ? '1' : value === false ? '0' : String(value);
+
+/**
+ * The live config as strings: managed keys only.
+ * ⛔ AN ALLOWLIST, NOT "EVERYTHING BUT A DENYLIST" — same reasoning as `lxc-props.ts`'s
+ *   `storedConfig`. `digest` covers the whole file, `lock`/`pending` are transient, and a future
+ *   PVE release's new key does not land in this estate's unencrypted state store until this
+ *   resource is taught to manage it.
+ */
+export const storedConfig = (live: Record<string, unknown>): Record<string, string> => {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(live)) {
+    if (!isManagedKey(key)) continue;
+    if (value === null || value === undefined || typeof value === 'object') continue;
+    out[key] = wireValue(value);
+  }
+  return out;
+};