@homeflare/alchemy 0.38.0 → 0.39.0

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

@@ -0,0 +1,80 @@
+/**
+ * Pure unit tests for `judgeDisk` — the red-team C1 fix on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: a "fresh" declaration (new-disk GiB, or `storage:cloudinit`) never re-drifts
+ *   against an existing live volume in the same slot; a genuine volume/storage swap is refused,
+ *   never written; a size change is refused (no resize call exists here); an option-only change is
+ *   written on the LIVE volume id and LIVE size.
+ */
+import { describe, expect, test } from 'bun:test';
+import { judgeDisk, parseDisk } from './qemu-volume.ts';
+
+describe('a "fresh" declaration matches any existing volume in its slot', () => {
+  test('new-disk GiB spelling: the measured C1 regression', () => {
+    expect(judgeDisk('scsi0', 'cephtb4:32', 'cephtb4:vm-101-disk-0,size=32G')).toEqual({});
+  });
+
+  test('cloud-init spelling, QEMU-only: no LXC equivalent', () => {
+    expect(judgeDisk('ide2', 'cephtb4:cloudinit', 'cephtb4:vm-101-cloudinit,media=cdrom')).toEqual(
+      {},
+    );
+  });
+});
+
+describe('an existing-volume declaration', () => {
+  const live = 'cephtb4:vm-101-disk-0,size=32G,ssd=1';
+
+  test('matching options is a noop', () => {
+    expect(judgeDisk('scsi0', live, live)).toEqual({});
+  });
+
+  test('a different storage is refused, never written', () => {
+    const verdict = judgeDisk('scsi0', 'other:vm-101-disk-0,size=32G,ssd=1', live);
+    expect(verdict.refuse).toMatch(/the volume is on cephtb4, declared on other/);
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('a different volume on the same storage is refused: it would detach the live one', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-9,size=32G', live);
+    expect(verdict.refuse).toMatch(/detach the live volume to unusedN/);
+  });
+
+  test('a declared size difference is refused: this resource does not resize', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-0,size=64G,ssd=1', live);
+    expect(verdict.refuse).toMatch(/does not resize a disk/);
+  });
+
+  test('an option-only change writes the LIVE volume id and LIVE size, not the declared ones', () => {
+    const verdict = judgeDisk('scsi0', 'cephtb4:vm-101-disk-0,size=32G,ssd=0', live);
+    expect(verdict.put).toBe('cephtb4:vm-101-disk-0,ssd=0,size=32G');
+  });
+
+  test('the cloud-init slot has no size to carry: the PUT omits it rather than writing size=', () => {
+    const cloudinitLive = 'cephtb4:vm-101-cloudinit,media=cdrom';
+    const verdict = judgeDisk(
+      'ide2',
+      'cephtb4:vm-101-cloudinit,media=cdrom,readonly=1',
+      cloudinitLive,
+    );
+    expect(verdict.put).toBe('cephtb4:vm-101-cloudinit,media=cdrom,readonly=1');
+  });
+});
+
+describe('parseDisk', () => {
+  test('a bare new-disk spelling has no volname and no size stored as an option', () => {
+    expect(parseDisk('cephtb4:32')).toEqual({
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: 'cephtb4',
+      volname: '',
+    });
+  });
+
+  test('an existing volume splits size out of the options map', () => {
+    const disk = parseDisk('cephtb4:vm-101-disk-0,size=32G,ssd=1');
+    expect(disk.kind).toBe('volume');
+    expect(disk.volname).toBe('vm-101-disk-0');
+    expect(disk.size).toBe('32G');
+    expect(disk.options).toEqual(new Map([['ssd', '1']]));
+  });
+});

package/src/proxmox/qemu-volume.ts

@@ -0,0 +1,121 @@
+/**
+ * `scsiN` and `ideN`: what a declared disk may change on a live VM, and how.
+ *
+ * ★ PORTED FROM lxc-volume.ts (2026-09-26, red-team C1 on PR 297): pve-qemu-server shares the same
+ *   "new-disk spelling" rule pve-container has. `storage:GiB` in a PUT means "allocate a fresh
+ *   volume" — so a declared `cephtb4:32` that already has a live `cephtb4:vm-101-disk-0,size=32G`
+ *   in that slot must compare EQUAL, never be re-sent. Measured by the builder's red team: resending
+ *   it allocated a second volume every deploy and parked the guest's real disk at `unusedN` (or left
+ *   the swap pending on a running boot disk until the next reboot).
+ * ⚠️ `ideN` HAS A SECOND NEW-VOLUME SPELLING QEMU DOES NOT SHARE WITH LXC: `<storage>:cloudinit`
+ *   creates a fresh cloud-init seed drive; the live slot then reads back
+ *   `<storage>:vm-<vmid>-cloudinit,media=cdrom`. Both spellings compare equal to an existing volume
+ *   already in the slot, for the same reason `storage:GiB` does.
+ * ⛔ NO RESIZE IS MADE HERE. lxc-volume.ts drives a second endpoint (`PUT .../resize`) this resource
+ *   does not call — Talos's disks are declared once at their create size. A size difference between
+ *   two already-adopted volume declarations is REFUSED with the `qm resize` to run by hand, never
+ *   guessed at or silently written.
+ * ⚠️ OPTIONS BEYOND `size` ARE COMPARED AS A WHOLE, NOT KEY BY KEY. Unlike lxc-volume.ts, this file
+ *   does not model pve-qemu-server's per-option defaults (`ssd`, `discard`, `iothread`, …) — that
+ *   table is unverified here. So an option difference is real drift and gets written, exactly as the
+ *   whole-string comparison this replaces already did; only the two "new volume" spellings and the
+ *   live volume id/size are special-cased, which is the minimum that fixes the measured bug.
+ */
+import { sameMap } from './lxc-wire.ts';
+
+/** PVE's own new-disk spelling: `storage:SIZE`, SIZE in GiB, fractional allowed. */
+const NEW_DISK = /^([^:\s]+):(\d+(?:\.\d+)?)$/;
+/** The `ideN` cloud-init-drive spelling — QEMU only, no GiB, no LXC equivalent. */
+const NEW_CLOUDINIT = /^([^:\s]+):cloudinit$/;
+
+export type Disk = {
+  /** `fresh`: either new-disk spelling above. `volume`: an existing volume, `storage:volname,...`. */
+  readonly kind: 'fresh' | 'volume';
+  readonly source: string;
+  readonly volname: string;
+  readonly size: string | undefined;
+  readonly options: Map<string, string>;
+};
+
+/** `storage:volname,k=v,...` (or one of the two "fresh" spellings) into its comparable parts. */
+export const parseDisk = (text: string): Disk => {
+  const fresh = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
+  if (fresh !== null) {
+    return {
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: fresh[1] ?? '',
+      volname: '',
+    };
+  }
+  const [first, ...rest] = text.split(',');
+  const at = (first ?? '').indexOf(':');
+  const source = at === -1 ? (first ?? '') : (first ?? '').slice(0, at);
+  const volname = at === -1 ? '' : (first ?? '').slice(at + 1);
+  const options = new Map(
+    rest.map((part): [string, string] => {
+      const eq = part.indexOf('=');
+      return eq === -1 ? [part, ''] : [part.slice(0, eq), part.slice(eq + 1)];
+    }),
+  );
+  const size = options.get('size');
+  options.delete('size');
+  return { kind: 'volume', options, size, source, volname };
+};
+
+export type DiskVerdict = {
+  readonly refuse?: string;
+  /** The value to PUT, built on the LIVE volume id and LIVE size — never the declared spelling. */
+  readonly put?: string;
+};
+
+/**
+ * A map back to `key=value,...` — mirrors lxc-wire.ts's `printMap`.
+ * ⚠️ `size` OMITTED WHEN THE LIVE SLOT HAS NONE (the cloud-init drive: no GiB figure to carry).
+ *   Writing `size=` empty is not a value PVE's own parser accepts.
+ */
+const printOptions = (
+  source: string,
+  volname: string,
+  options: Map<string, string>,
+  size: string | undefined,
+) =>
+  [
+    `${source}:${volname}`,
+    ...[...options].map(([k, v]) => `${k}=${v}`),
+    ...(size === undefined ? [] : [`size=${size}`]),
+  ].join(',');
+
+export const judgeDisk = (key: string, declared: string, live: string): DiskVerdict => {
+  const want = parseDisk(declared);
+  const have = parseDisk(live);
+  if (want.source !== have.source) {
+    return {
+      refuse:
+        `${key}: the volume is on ${have.source}, declared on ${want.source}. Moving a disk ` +
+        'between storages is not an update this resource makes -- move it by hand, then declare it.',
+    };
+  }
+  // ⛔ A "fresh" declaration always matches an existing volume already in this slot: PVE holds one
+  //   there, and re-sending storage:GiB / storage:cloudinit would allocate a SECOND volume and park
+  //   the live one at unusedN (the header's ⛔, ported from lxc-volume.ts's own).
+  if (want.kind === 'fresh') return {};
+  if (want.volname !== have.volname) {
+    return {
+      refuse:
+        `${key}: declared volume ${want.volname} is not the live ${have.volname}. Writing it ` +
+        'would detach the live volume to unusedN; attach or swap volumes by hand.',
+    };
+  }
+  if (want.size !== undefined && have.size !== undefined && want.size !== have.size) {
+    return {
+      refuse:
+        `${key}: declared size ${want.size} differs from the live ${have.size}. This resource does ` +
+        'not resize a disk -- grow it by hand (`qm resize`) and declare the size it then reports.',
+    };
+  }
+  if (sameMap(want.options, have.options)) return {};
+  // ⚠️ THE LIVE SIZE, NOT THE DECLARED ONE — see the header's ⛔ on why no resize happens here.
+  return { put: printOptions(have.source, have.volname, want.options, have.size) };
+};

package/src/proxmox/qemu.ts

@@ -1,5 +1,7 @@
 /**
- * `Proxmox.Vm` — a QEMU virtual machine, declared.
+ * `Proxmox.Vm` — a QEMU virtual machine, declared. Exported (not just Provider-only) since
+ * 2026-09-26 for Talos: see qemu-props.ts for what a declaration may say and why `cipassword`
+ * and `machine` may never be one of them.
  *
  * ⚠️ CREATE is `POST /nodes/{node}/qemu`. GET and PUT stay on `.../qemu/{vmid}/config`.
  *   ⛔ DELETE is `DELETE /nodes/{node}/qemu/{vmid}` (`destroy_vm` in qemu-server Qemu.pm). The
@@ -10,39 +12,22 @@
  *   collision Alchemy can see -- they are different resource types -- and PVE refuses the second
  *   with "already exists". Pick ids per cluster, not per kind.
  *
- * ⚠️ POWER STATE IS REPORTED, NEVER DECLARED. `status` is an attribute so a plan can show it; there
- *   is no `running` prop. Starting and stopping a VM from a plan would make a deploy a maintenance
- *   window, and the estate has one of those already.
+ * ⛔ THIS RESOURCE NEVER MIGRATES. `qemu-read.ts` refuses the plan outright when the declared vmid
+ *   is found running on a DIFFERENT node than the one declared ("A migration is not an update") --
+ *   unchanged by the 2026-09-26 export, and exactly what keeps a node-pinned Talos VM pinned.
+ *
+ * ⚠️ POWER STATE IS NEITHER DECLARED NOR REPORTED. There is no `running` prop and `VmAttributes`
+ *   carries no `status` field (qemu-props.ts) — starting and stopping a VM from a plan would make a
+ *   deploy a maintenance window, and the estate has one of those already.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
 import { qemuHandlers } from './qemu-lifecycle.ts';
-import type { PveRequirements, WithTarget } from './resource.ts';
-
-export interface VmProps extends WithTarget {
-  node: string;
-  /** ⛔ Cluster-wide, and shared with LXC. See the ⛔ above. */
-  vmid: number;
-  name?: string;
-  /** MiB. */
-  memory?: number;
-  cores?: number;
-  sockets?: number;
-  /** e.g. `virtio=<mac>,bridge=vmbr0`. */
-  net0?: string;
-  onboot?: boolean;
-}
+import type { PveRequirements } from './resource.ts';
+import type { VmAttributes, VmProps } from './qemu-props.ts';
 
-export interface VmAttributes {
-  vmid: number;
-  node: string;
-  name: string;
-  memory: number;
-  cores: number;
-  sockets: number;
-  onboot: boolean;
-}
+export type { VmAttributes, VmProps } from './qemu-props.ts';
 
 export interface ProxmoxVm extends Resource<
   'Proxmox.Vm',
@@ -52,7 +37,8 @@ export interface ProxmoxVm extends Resource<
   PveRequirements
 > {}
 
-export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm');
+/** ★ `retain` by default — a VM's disks cannot be rebuilt from a line. See resource.ts / lxc.ts. */
+export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm', { defaultRemovalPolicy: 'retain' });
 
 export { createForm } from './qemu-form.ts';
 

package/src/proxmox/storage-download-errors.ts

@@ -0,0 +1,7 @@
+/** A `Proxmox.StorageDownload` write or observation this provider will not turn into a claim of success. */
+export class StorageDownloadRefusedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StorageDownloadRefusedError';
+  }
+}

package/src/proxmox/storage-download-identity.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure unit tests for `judgeIdentity` — red-team I1/I2 on PR 297. No network, no fake PVE.
+ * ⛔ WHAT THESE PIN: a changed `filename`/`storage` is a `replace`, never a silent `update` that
+ *   orphans the old file; a changed pin (`checksum`/`url`/…) on the SAME `filename` is named for a
+ *   refusal, never treated as a matching declaration; nothing changing is `same`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { FAKE_TARGET } from './fake-pve.ts';
+import { judgeIdentity } from './storage-download-identity.ts';
+import type { StorageDownloadProps } from './storage-download-props.ts';
+
+const base: StorageDownloadProps = {
+  checksum: 'a'.repeat(64),
+  checksumAlgorithm: 'sha256',
+  filename: 'talos-v1.13.0-metal-amd64.qcow2',
+  node: 'pve1',
+  storage: 'cephfs-tb4',
+  target: FAKE_TARGET,
+  url: 'https://images.example.test/talos.qcow2',
+};
+
+describe('judgeIdentity', () => {
+  test('no prior declaration: always "same" -- a fresh create has nothing to compare', () => {
+    expect(judgeIdentity(base, undefined)).toEqual({ kind: 'same' });
+  });
+
+  test('nothing changed: "same"', () => {
+    expect(judgeIdentity(base, { ...base })).toEqual({ kind: 'same' });
+  });
+
+  test('a changed filename is a "replace": the measured I1 regression (silent orphan)', () => {
+    expect(judgeIdentity({ ...base, filename: 'talos-v1.14.0-metal-amd64.qcow2' }, base)).toEqual({
+      kind: 'replace',
+    });
+  });
+
+  test('a changed storage is a "replace" too', () => {
+    expect(judgeIdentity({ ...base, storage: 'cephtb4' }, base)).toEqual({ kind: 'replace' });
+  });
+
+  test('a changed checksum on the same filename is "pin-changed": the measured I2 regression', () => {
+    const verdict = judgeIdentity({ ...base, checksum: 'b'.repeat(64) }, base);
+    expect(verdict.kind).toBe('pin-changed');
+    expect((verdict as { refuse: string }).refuse).toMatch(/checksum changed but filename did not/);
+  });
+
+  test('a changed url on the same filename is "pin-changed" too', () => {
+    const verdict = judgeIdentity(
+      { ...base, url: 'https://images.example.test/other.qcow2' },
+      base,
+    );
+    expect(verdict.kind).toBe('pin-changed');
+  });
+});

package/src/proxmox/storage-download-identity.ts

@@ -0,0 +1,50 @@
+/**
+ * What makes a `Proxmox.StorageDownload` a DIFFERENT file, and what a changed pin on the SAME
+ * file means. (2026-09-26, red-team I1/I2 on PR 297.)
+ *
+ * ★ `filename` (WITH `storage`) IS THE IDENTITY. PVE does not record what a volume was downloaded
+ *   from — `GET .../content` reports only `format`/`size`/`volid` (storage-download-props.ts) — so
+ *   once the file exists there is nothing left to compare a new `url`/`checksum` against except the
+ *   PREVIOUS DECLARATION. `storage-download-lifecycle.ts`'s `diff` asks `judgeIdentity` before
+ *   touching the file; a genuine identity change plans `replace` (delete the old file, download the
+ *   new one under its own name) rather than the silent `update` that used to orphan the old file
+ *   forever, and a changed pin on the SAME filename refuses rather than silently planning `noop`.
+ */
+import type { StorageDownloadProps } from './storage-download-props.ts';
+
+/** The fields PVE never stores back, so a change in them is only visible against `olds`. */
+const PINNED: readonly (keyof StorageDownloadProps)[] = [
+  'checksum',
+  'checksumAlgorithm',
+  'compression',
+  'url',
+  'verifyCertificates',
+];
+
+export type IdentityVerdict =
+  | { readonly kind: 'same' }
+  | { readonly kind: 'replace' }
+  | { readonly kind: 'pin-changed'; readonly refuse: string };
+
+/**
+ * `olds` is undefined for a resource with no prior declaration (a fresh create, or the recovery
+ * read for an interrupted one) — neither case has a pin to compare, so both are `same`.
+ */
+export const judgeIdentity = (
+  news: StorageDownloadProps,
+  olds: StorageDownloadProps | undefined,
+): IdentityVerdict => {
+  if (olds === undefined) return { kind: 'same' };
+  if (news.filename !== olds.filename || news.storage !== olds.storage) {
+    return { kind: 'replace' };
+  }
+  const changed = PINNED.filter((key) => news[key] !== olds[key]);
+  if (changed.length === 0) return { kind: 'same' };
+  return {
+    kind: 'pin-changed',
+    refuse:
+      `${news.filename}: ${changed.join(', ')} changed but filename did not. filename is the ` +
+      'identity -- PVE does not record what a volume was downloaded from, so this declaration ' +
+      'cannot be verified or rewritten in place. Change filename to force a new download.',
+  };
+};

package/src/proxmox/storage-download-lifecycle.ts

@@ -0,0 +1,226 @@
+/**
+ * StorageDownload lifecycle. Read finds a content row by filename; create downloads and polls;
+ * delete is idempotent — a volume already gone is success, not a refusal.
+ *
+ * ⛔ 2026-09-26, red-team C2/I1/I2/I3 on PR 297: `read` and `reconcile` now go through
+ *   `ownedRead`/`refuseTakeover` (C2) so a pre-existing file is never silently adopted — and then
+ *   deleted, since this family is not retain-by-default; `diff` asks `storage-download-identity.ts`
+ *   (I1/I2) before touching the file; the content list read uses the `read` role, not `provision`
+ *   (I3, `credentials.ts`: "read for read/diff, provision for reconcile/delete").
+ */
+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 { formViolations } from './constraint-guard.ts';
+import { runPve } from './distilled-pve.ts';
+import { judgeIdentity } from './storage-download-identity.ts';
+import { StorageDownloadRefusedError } from './storage-download-errors.ts';
+import type { StorageDownloadAttributes, StorageDownloadProps } from './storage-download-props.ts';
+import { storageDownloadTask } from './storage-download-task.ts';
+import { int, text } from './values.ts';
+
+const CREATE_POLLS = 600; // an image download can run far longer than a config write
+const DELETE_POLLS = 60;
+
+/** ⚠️ Named as a literal so `codegen/constraints.ts`'s text scan tables it (that file's own header). */
+const DOWNLOAD_ENDPOINT = 'pve:POST /nodes/{node}/storage/{storage}/download-url';
+
+/**
+ * The wire form, PVE-spelled (`checksum-algorithm`, `verify-certificates`) — what the generated
+ * vendor table keys by, and what `formViolations` checks. ⚠️ NOT re-spelled for the SDK call:
+ * `nodes.downloadNodesStorageUrl` never declares these two hyphenated names as typed properties
+ * either (its schema names them `checksum_algorithm`/`verify_certificates`), so passing this
+ * object straight through relies on protocol-http.ts's own documented "unknown keys pass through
+ * as body fields" rule — the same spec-drift path qemu-props.ts leans on for `scsi0`/`net0`, and
+ * unlike storage-wire.ts's `underscored()` this family has no reason to translate: the schema's
+ * OWN property names would just be a second spelling of the same two fields.
+ */
+export const downloadForm = (props: StorageDownloadProps) => ({
+  checksum: props.checksum,
+  'checksum-algorithm': props.checksumAlgorithm,
+  ...(props.compression === undefined ? {} : { compression: props.compression }),
+  content: 'import',
+  filename: props.filename,
+  node: props.node,
+  storage: props.storage,
+  url: props.url,
+  ...(props.verifyCertificates === undefined
+    ? {}
+    : { 'verify-certificates': props.verifyCertificates ? '1' : '0' }),
+});
+
+/**
+ * Why this declaration cannot be sent, checked before every diff and every reconcile.
+ * ⛔ `checksum` REQUIRED, EVEN THOUGH THE TYPE ALREADY SAYS SO — a JS caller or a cast can still
+ *   leave it `''`; this is the runtime backstop storage-download.ts's header promises.
+ */
+export const createRefusals = (props: StorageDownloadProps): string[] => {
+  const refuse: string[] = [];
+  if (props.checksum.trim() === '') {
+    refuse.push(
+      `${props.filename}: checksum is required — an unpinned download is not a declaration.`,
+    );
+  }
+  return refuse.concat(
+    formViolations(DOWNLOAD_ENDPOINT, downloadForm(props), true).map(
+      (why) => `${props.filename}: ${why}`,
+    ),
+  );
+};
+
+/**
+ * `GET .../content?content=import`, matched by filename suffix — see storage-download-props.ts's
+ * `volid` doc for why a suffix match, not an assumed prefix. `content` is already server-filtered.
+ * ⛔ I3: THE `read` ROLE, NOT `provision` — this is a plain GET, and every caller (read/diff AND
+ *   reconcile/delete, which mint their own `provision` credential for the actual write) may use the
+ *   cheaper, longer-lived one, exactly as `qemu-read.ts`'s `readVm` already does for its own GET.
+ */
+export const readDownload = (props: StorageDownloadProps) =>
+  Effect.gen(function* () {
+    const rows = yield* runPve(
+      props.target,
+      'read',
+      false,
+      nodes.listNodeStorageContent({
+        content: 'import',
+        node: props.node,
+        storage: props.storage,
+      }),
+    );
+    if (!Array.isArray(rows)) {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${props.storage}: the content list did not come back as a list.`,
+        ),
+      );
+    }
+    const found = rows.find((row) => row.volid.endsWith(`/${props.filename}`));
+    if (found === undefined) return undefined;
+    return {
+      filename: props.filename,
+      format: text(found.format, 'raw'),
+      node: props.node,
+      size: int(found.size, 0),
+      storage: props.storage,
+      volid: text(found.volid, ''),
+    } satisfies StorageDownloadAttributes;
+  });
+
+/** ⛔ IDEMPOTENT DELETE (distilled doctrine): a volume already gone is success, never a refusal. */
+export const destroyDownload = (props: StorageDownloadProps) =>
+  Effect.gen(function* () {
+    const live = yield* readDownload(props);
+    if (live === undefined) return;
+    yield* storageDownloadTask(
+      props,
+      nodes.deleteNodeStorageContent({
+        node: props.node,
+        storage: props.storage,
+        volume: live.volid,
+      }),
+      `delete ${live.volid}`,
+      DELETE_POLLS,
+    );
+  });
+
+export const storageDownloadHandlers = {
+  list: () => Effect.succeed([]),
+  /**
+   * ⛔ C2: `Unowned` unless state already vouches for it. With no attributes this is the adoption
+   *   probe or the recovery read for an interrupted download; `filename` (with `storage`) is the
+   *   whole identity this family has (storage-download-identity.ts), so once the row's own instance
+   *   is proven to hold the WHOLE declaration (`ownership/rows.ts`, inside `ownedRead`), a matching
+   *   file is ours -- there is no further per-key drift to prove, unlike a config-bearing resource.
+   */
+  read: Effect.fn(function* ({
+    fqn,
+    instanceId,
+    olds,
+    output,
+  }: {
+    fqn: string;
+    instanceId: string;
+    olds: StorageDownloadProps;
+    output: StorageDownloadAttributes | undefined;
+  }) {
+    const found = yield* readDownload(olds);
+    return yield* ownedRead({ fqn, instanceId, output }, found, Effect.succeed(true));
+  }),
+  diff: Effect.fn(function* ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<StorageDownloadProps>;
+    olds: StorageDownloadProps;
+    output: StorageDownloadAttributes | undefined;
+  }) {
+    if (!isResolved(news)) return undefined;
+    const refused = createRefusals(news);
+    if (refused.length > 0) {
+      return yield* Effect.fail(new StorageDownloadRefusedError(refused.join('\n')));
+    }
+    if (output === undefined) return undefined;
+    // ⛔ I1: a changed filename/storage is a DIFFERENT file -- plan a replace (delete the old one,
+    //   download the new one under its own name) rather than the `update` that used to leave the
+    //   old file orphaned forever with no state pointing at it.
+    const identity = judgeIdentity(news, olds);
+    if (identity.kind === 'replace') return { action: 'replace' } as const;
+    const live = yield* readDownload(news);
+    // ⛔ I2: a changed url/checksum/etc on the SAME filename is refused, never silently `noop` --
+    //   PVE does not record what a volume was downloaded from, so this declaration cannot be
+    //   verified or rewritten in place. Only when the file is actually there: if it already vanished
+    //   out of band, the pin change is simply what the next download uses.
+    if (identity.kind === 'pin-changed' && live !== undefined) {
+      return yield* Effect.fail(new StorageDownloadRefusedError(identity.refuse));
+    }
+    return { action: live === undefined ? 'update' : 'noop' } as const;
+  }),
+  reconcile: Effect.fn(function* ({
+    fqn,
+    instanceId,
+    news,
+    output,
+  }: {
+    fqn: string;
+    instanceId: string;
+    news: StorageDownloadProps;
+    output: StorageDownloadAttributes | undefined;
+  }) {
+    const refused = createRefusals(news);
+    if (refused.length > 0) {
+      return yield* Effect.fail(new StorageDownloadRefusedError(refused.join('\n')));
+    }
+    const live = yield* readDownload(news);
+    if (live === undefined) {
+      yield* storageDownloadTask(
+        news,
+        nodes.downloadNodesStorageUrl(downloadForm(news)),
+        `download ${news.filename} onto ${news.storage}`,
+        CREATE_POLLS,
+      );
+    } else {
+      // ⛔ C2: a file already at this filename that this stack holds no state for is refused unless
+      //   adoption is on. Without this, dropping the declaration later DELETES a file this stack
+      //   never created — this family is not retain-by-default (storage-download.ts's header).
+      yield* refuseTakeover(
+        { fqn, instanceId, output },
+        `Proxmox.StorageDownload ${news.filename} on ${news.storage}`,
+      );
+    }
+    const after = yield* readDownload(news);
+    if (after === undefined) {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${news.filename}: the write returned no error but ${news.storage} still has no ` +
+            'matching content — PVE may have normalised the filename; read it back by hand.',
+        ),
+      );
+    }
+    return after;
+  }),
+  delete: ({ olds }: { olds: StorageDownloadProps }) => destroyDownload(olds),
+};

package/src/proxmox/storage-download-ownership.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Whose file it is — docs/ownership.md applied to `Proxmox.StorageDownload` (red-team C2 on PR
+ * 297), through the real engine over a stub fetch (fake-pve.ts).
+ *
+ * ⛔ WHAT THIS PINS: a pre-existing file at the declared filename, that this stack holds no state
+ *   for, is never adopted silently. The measured regression was worse than a pointless write-back:
+ *   this family is not retain-by-default, so a silent adoption followed by dropping the declaration
+ *   later DELETES a file this stack never created. `adopt(false)` wins over the test harness's own
+ *   forced `AdoptPolicy: true` (fake-engine.ts), same as qemu-ownership.test.ts.
+ */
+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 type { StorageDownloadProps } from './storage-download-props.ts';
+import { ProxmoxStorageDownload, ProxmoxStorageDownloadProvider } from './storage-download.ts';
+
+const NODE = 'pve1';
+const STORAGE = 'cephfs-tb4';
+const FILENAME = 'talos-v1.13.0-metal-amd64.qcow2';
+const row = { format: 'qcow2', size: 1, volid: `${STORAGE}:import/${FILENAME}` };
+const declare = (): StorageDownloadProps => ({
+  checksum: 'a'.repeat(64),
+  checksumAlgorithm: 'sha256',
+  filename: FILENAME,
+  node: NODE,
+  storage: STORAGE,
+  target: FAKE_TARGET,
+  url: 'https://images.example.test/talos.qcow2',
+});
+
+const isList = (call: { method: string; path: string }) =>
+  call.method === 'GET' && call.path.includes('/content?');
+
+const engine = (fake: ReturnType<typeof fakePve>) =>
+  engineOver(ProxmoxStorageDownloadProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.StorageDownload ownership', () => {
+  test('adopt(false): a pre-existing file is refused, and nothing is downloaded or deleted', async () => {
+    const fake = fakePve((call) => (isList(call) ? [row] : null));
+    await withoutBao(async () => {
+      const declared = ProxmoxStorageDownload('image', declare()).pipe(adopt(false));
+      await expect(engine(fake).deploy(declared)).rejects.toThrow(
+        /adopt|exists, and this stack holds no state/i,
+      );
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+});