@homeflare/alchemy 0.38.0 → 0.40.0

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

@@ -5,7 +5,7 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import { engineOver } from '../verify/fake-engine.ts';
 import { FAKE_TARGET, type FakePve, fakePve, withoutBao } from './fake-pve.ts';
-import { ProxmoxVm, ProxmoxVmProvider } from './qemu.ts';
+import { ProxmoxVm, ProxmoxVmProvider, type VmProps } from './qemu.ts';
 
 const NODE = 'pve1';
 const VMID = 150;
@@ -42,24 +42,27 @@ describe('Proxmox.Vm distilled transport', () => {
   });
 
   test('absence creates on the collection route, waits, then settles', async () => {
-    let exists = false;
+    let posted: Record<string, string> | undefined;
     const fake = fakePve((call) => {
       if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
         return { status: 'stopped', exitstatus: 'OK' };
       }
       if (isIndex(call)) return [];
-      if (call.method === 'GET') return exists ? live : missing();
-      exists = true;
+      // ⚠️ `net0` IS NOW A MANAGED, COMPARED KEY (qemu-props.ts) — the old fixture answered the
+      //   SAME static `live` regardless of what was posted, which only worked because the old
+      //   `matches` never looked at `net0` at all. Echoing the create form back is what proves
+      //   the declared value is what a real PVE config would report.
+      if (call.method === 'GET') return posted === undefined ? missing() : { ...live, ...posted };
+      posted = call.form;
       return UPID;
     });
+    const declared = { ...props, net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0' };
     await withoutBao(async () => {
       const stack = engine(fake);
-      await stack.deploy(
-        ProxmoxVm('row', { ...props, net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0' }),
+      await stack.deploy(ProxmoxVm('row', declared));
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'noop' },
       );
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'noop',
-      });
     });
     expect(fake.writes()).toEqual([`POST nodes/${NODE}/qemu`]);
     expect(fake.calls.find((call) => call.method === 'POST')?.form['net0']).toBe(
@@ -68,6 +71,41 @@ describe('Proxmox.Vm distilled transport', () => {
     expect(fake.calls.some((call) => call.path.includes('/tasks/'))).toBe(true);
   });
 
+  test('C1: a "fresh" disk/cloudinit and a MAC-less NIC do not re-drift after PVE allocates them', async () => {
+    // ⛔ THE MEASURED REGRESSION: before qemu-judge.ts, every deploy after the create re-sent
+    //   scsi0/ide2/net0 in their DECLARED (fresh) spelling, because a plain string compare never
+    //   equals what PVE reports back for an allocated volume or a generated MAC -- reallocating the
+    //   disk and handing out a new MAC on every single deploy.
+    const declared = {
+      ...props,
+      ide2: 'cephtb4:cloudinit',
+      net0: 'virtio,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:32',
+    };
+    const allocated = {
+      ide2: 'cephtb4:vm-150-cloudinit,media=cdrom',
+      net0: 'virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0,tag=20',
+      scsi0: 'cephtb4:vm-150-disk-0,size=32G',
+    };
+    let created = false;
+    const fake = fakePve((call) => {
+      if (call.path.includes('/tasks/') && call.path.endsWith('/status')) {
+        return { status: 'stopped', exitstatus: 'OK' };
+      }
+      if (isIndex(call)) return [];
+      if (call.method === 'GET') return created ? { ...live, ...allocated } : missing();
+      created = true;
+      return UPID;
+    });
+    await withoutBao(async () => {
+      const stack = engine(fake);
+      await stack.deploy(ProxmoxVm('row', declared));
+      await stack.deploy(ProxmoxVm('row', declared));
+      await stack.deploy(ProxmoxVm('row', declared));
+    });
+    expect(fake.writes()).toEqual([`POST nodes/${NODE}/qemu`]);
+  });
+
   test('a transitional task status keeps polling instead of aborting the create', async () => {
     // ⚠️ `GetNodeTaskStatusResponseStatus` types `status` as the closed union
     //   "running" | "stopped", but the runtime validator is `S.String` (distilled-proxmox's
@@ -113,24 +151,45 @@ describe('Proxmox.Vm distilled transport', () => {
     expect(fake.writes()).toEqual([]);
   });
 
-  test('drift updates the config route and the next plan is a no-op', async () => {
-    let current: unknown = { ...live, memory: '256' };
+  test('drift on a declared field updates the config route, and only that field', async () => {
+    // ⛔ THE "5-DEFAULT PUT" REGRESSION TEST. `name` is deliberately left UNDECLARED and deliberately
+    //   NOT what qemu-form.ts's old default would have produced (`vm150`) -- the old `shape()` sent
+    //   it (and `cores`/`sockets`/`onboot`) on every write regardless, silently resetting an
+    //   undeclared field to its factory value. Only `memory` is declared here, so only `memory`
+    //   may appear in the PUT body.
+    const declared = { ...props, memory: 512 };
+    let current: unknown = { ...live, memory: '256', name: 'a-name-nobody-declared' };
     const fake = fakePve((call) => {
       if (call.method === 'GET') return current;
-      current = live;
+      current = { ...(current as Record<string, unknown>), memory: '512' };
       return null;
     });
     await withoutBao(async () => {
       const stack = engine(fake);
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'update',
-      });
-      await stack.deploy(ProxmoxVm('row', props));
-      expect((await stack.verify(ProxmoxVm('row', props), { all: true })).rows[0]).toMatchObject({
-        diff: 'noop',
-      });
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'update' },
+      );
+      await stack.deploy(ProxmoxVm('row', declared));
+      expect((await stack.verify(ProxmoxVm('row', declared), { all: true })).rows[0]).toMatchObject(
+        { diff: 'noop' },
+      );
     });
     expect(fake.writes()).toEqual([`PUT nodes/${NODE}/qemu/${String(VMID)}/config`]);
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.form).toEqual({ memory: '512' });
+  });
+
+  test('an unmanaged key smuggled past the types is refused before any write', async () => {
+    const fake = fakePve((call) => (call.method === 'GET' ? live : null));
+    // ⛔ `cipassword` IS TYPED `never` (qemu-props.ts): a cast is the only way in, exactly the
+    //   scenario the type cannot guard against by itself. `formRefusals` is the runtime backstop.
+    const smuggled = { ...props, cipassword: 'not-a-real-secret' } as unknown as VmProps;
+    await withoutBao(async () => {
+      await expect(engine(fake).deploy(ProxmoxVm('row', smuggled))).rejects.toThrow(
+        /cipassword: not a config key this resource manages/,
+      );
+    });
+    expect(fake.writes()).toEqual([]);
   });
 
   test('unrelated read failures and a digest-less body do not write', async () => {

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).',
+    ]);
+  });
+});