@homeflare/alchemy 0.38.0 → 0.40.0

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([]);
+  });
+});

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

@@ -0,0 +1,38 @@
+/** What a `Proxmox.StorageDownload` declaration says, and what its state keeps. See storage-download.ts's header. */
+import type { WithTarget } from './resource.ts';
+
+export type ChecksumAlgorithm = 'md5' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512';
+
+export interface StorageDownloadProps extends WithTarget {
+  /** The node this download runs on. Content lands on `storage`, shared or not — see the header. */
+  node: string;
+  storage: string;
+  /** The name PVE gives the file under `storage`'s `import` content. Normalized by PVE on write. */
+  filename: string;
+  /** Where to fetch the image from. ⚠️ Not re-verified after create — PVE does not store it. */
+  url: string;
+  /** ⛔ Required. See storage-download.ts's header on why this resource narrows the vendor's own optional field. */
+  checksum: string;
+  checksumAlgorithm: ChecksumAlgorithm;
+  /** Decompress the downloaded file with this algorithm before it lands on `storage`. */
+  compression?: string;
+  /** Verify the source's TLS certificate. PVE defaults this on; declare `false` for a self-signed mirror. */
+  verifyCertificates?: boolean;
+}
+
+export interface StorageDownloadAttributes {
+  node: string;
+  storage: string;
+  filename: string;
+  /**
+   * ⚠️ REASONED, NOT MEASURED LIVE. PVE's file-based content types spell a volid
+   *   `<storage>:<segment>/<filename>` — this codebase already relies on that shape for `iso` and
+   *   `vztmpl` (lxc-create-form.ts's `existingVolume`, lxc-create.test.ts's own fixture) — but the
+   *   exact `<segment>` spelling for `import` content is not independently confirmed against a
+   *   live cluster. `storage-download-lifecycle.ts`'s `readDownload` does not depend on knowing
+   *   it: it matches by filename SUFFIX within a list already server-filtered to `content=import`.
+   */
+  volid: string;
+  size: number;
+  format: string;
+}

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

@@ -0,0 +1,72 @@
+/**
+ * `download-url` and the content DELETE both answer a UPID (protocol.ts's "three 200-traps",
+ * trap (a)) — bounded task observation on the exact credential that started the worker.
+ * ★ THE SAME SHAPE AS qemu-task.ts/lxc-task.ts. Not merged with either: a fourth near-identical
+ *   copy would be the moment to extract a shared poller, not this one (⚠️ flagged, not fixed here
+ *   — see the PR description).
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import type { ProxmoxOpContext } from '@distilled.cloud/proxmox/Protocol';
+import * as Effect from 'effect/Effect';
+import { runPveWith } from './distilled-pve.ts';
+import { mint } from './mint.ts';
+import { StorageDownloadRefusedError } from './storage-download-errors.ts';
+import { text } from './values.ts';
+import type { PveTarget } from './credentials.ts';
+
+export interface StorageDownloadWhere {
+  readonly node: string;
+  readonly target: PveTarget;
+}
+
+/**
+ * ⛔ A CHECKSUM MISMATCH SURFACES HERE, NOT AS A DISTINCT TYPED ERROR. `download-url`'s POST
+ *   answers 200 with a UPID regardless of whether the checksum will match — PVE validates the
+ *   download itself, INSIDE the task, and reports the mismatch as that task's `exitstatus`. So
+ *   the refusal below (`exit !== 'OK'`) IS the checksum-mismatch refusal: this poller fails the
+ *   plan whenever the task did not report exactly `"OK"`, whatever the reason, without needing a
+ *   new SDK tag to name it.
+ */
+export const storageDownloadTask = <E>(
+  where: StorageDownloadWhere,
+  operation: Effect.Effect<string, E, ProxmoxOpContext>,
+  what: string,
+  polls: number,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* mint(where.target, 'provision');
+    const upid = text(yield* runPveWith(where.target, credential, true, operation));
+    if (upid === '') {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${what}: PVE returned no task id, so the write cannot be confirmed and is not claimed.`,
+        ),
+      );
+    }
+    let exit = 'still running when this provider stopped waiting';
+    for (let attempt = 0; attempt < polls; attempt++) {
+      const status = yield* runPveWith(
+        where.target,
+        credential,
+        false,
+        nodes.getNodeTaskStatus({ node: where.node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
+      // ⚠️ Matches qemu-task.ts's own note: only exactly "stopped" ends the poll.
+      if (status === undefined || status.status === undefined) {
+        exit = 'the task could not be read';
+        break;
+      }
+      if (status.status === 'stopped') {
+        exit = text(status.exitstatus, 'stopped with no exitstatus');
+        break;
+      }
+      yield* Effect.sleep('1 second');
+    }
+    if (exit !== 'OK') {
+      return yield* Effect.fail(
+        new StorageDownloadRefusedError(
+          `${what}: task ${upid} ended "${exit}". Read the task log before running the deploy again.`,
+        ),
+      );
+    }
+  });