@homeflare/alchemy 0.39.0 → 0.40.0

package/src/ceph/ceph-transport.test.ts

@@ -0,0 +1,125 @@
+/**
+ * The mon-command transport against `fakeCephDial` — no ssh, no spawned process. Mon-transport doc
+ * acceptance tests #1 ("no ssh at all" for a refused shape) and #2 (try-in-order, transport
+ * failure never reads as absent, quorum re-checked on a fresh connection after a write).
+ */
+import { describe, expect, test } from 'bun:test';
+import { authGetArgv, quorumStatusArgv } from './ceph-argv.ts';
+import { assertFreshQuorum, runCephCommand } from './ceph-transport.ts';
+import { fakeCephDial, fakeCephOk } from './fake-ceph-dial.ts';
+
+const ENTITY = 'client.k8s-rbd';
+const MON_A = 'mon-a.example.test';
+const MON_B = 'mon-b.example.test';
+const MON_C = 'mon-c.example.test';
+
+describe('runCephCommand', () => {
+  test('a refused shape never dials — no mon is ever contacted', async () => {
+    const fake = fakeCephDial({});
+    await expect(
+      runCephCommand({ dial: fake.dial, log: () => {}, nodes: [MON_A] }, [
+        '/usr/bin/ceph',
+        'auth',
+        'del',
+        ENTITY,
+        '-f',
+        'json',
+      ]),
+    ).rejects.toThrow(/never auto-delete/);
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('refuses when no mon nodes are declared, without dialing', async () => {
+    const fake = fakeCephDial({});
+    await expect(
+      runCephCommand({ dial: fake.dial, log: () => {}, nodes: [] }, authGetArgv(ENTITY)),
+    ).rejects.toThrow(/no mon nodes/);
+    expect(fake.seen).toEqual([]);
+  });
+
+  test('tries the next mon on a transport failure, in order, and returns the first that answers', async () => {
+    const fake = fakeCephDial({
+      [MON_B]: [{ kind: 'result', result: { exitCode: 0, stderr: '', stdout: '[]' } }],
+    });
+    const result = await runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B, MON_C] },
+      authGetArgv(ENTITY),
+    );
+    expect(result.node).toBe(MON_B);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A, MON_B]);
+  });
+
+  test('every mon failing at the transport layer propagates as an error, never as absent', async () => {
+    const fake = fakeCephDial({});
+    const attempt = runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B] },
+      authGetArgv(ENTITY),
+    );
+    await expect(attempt).rejects.toThrow(/every mon node failed \(never treated as absent\)/);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A, MON_B]);
+  });
+
+  test('a mon that actually answers, even with a nonzero exit, is not retried on another node', async () => {
+    const fake = fakeCephDial({
+      [MON_A]: [
+        { kind: 'result', result: { exitCode: 2, stderr: 'Error ENOENT: not found', stdout: '' } },
+      ],
+    });
+    const result = await runCephCommand(
+      { dial: fake.dial, log: () => {}, nodes: [MON_A, MON_B] },
+      authGetArgv(ENTITY),
+    );
+    expect(result.node).toBe(MON_A);
+    expect(result.exitCode).toBe(2);
+    expect(fake.seen.map((call) => call.node)).toEqual([MON_A]);
+  });
+
+  test('the log line carries the argv, never any result — including a successful stdout', async () => {
+    const lines: string[] = [];
+    const fake = fakeCephDial({
+      [MON_A]: [
+        fakeCephOk('[{"entity":"client.k8s-rbd","key":"fake-key-not-a-secret","caps":{}}]'),
+      ],
+    });
+    await runCephCommand(
+      { dial: fake.dial, log: (line) => lines.push(line), nodes: [MON_A] },
+      authGetArgv(ENTITY),
+    );
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain(JSON.stringify(authGetArgv(ENTITY)));
+    expect(lines.join('\n')).not.toContain('fake-key-not-a-secret');
+  });
+});
+
+describe('assertFreshQuorum', () => {
+  test('passes on a healthy quorum', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('{"quorum":[0,1,2]}')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).resolves.toBeUndefined();
+    expect(fake.seen).toEqual([{ argv: quorumStatusArgv(), node: MON_A }]);
+  });
+
+  test('fails closed on an empty quorum array', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('{"quorum":[]}')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/degraded/);
+  });
+
+  test('fails closed on unparseable output — never calls a guess "healthy"', async () => {
+    const fake = fakeCephDial({ [MON_A]: [fakeCephOk('not json')] });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/degraded/);
+  });
+
+  test('a nonzero exit from quorum_status itself fails, reporting stderr only', async () => {
+    const fake = fakeCephDial({
+      [MON_A]: [{ kind: 'result', result: { exitCode: 1, stderr: 'mon down', stdout: '' } }],
+    });
+    await expect(
+      assertFreshQuorum({ dial: fake.dial, log: () => {}, nodes: [MON_A] }),
+    ).rejects.toThrow(/mon down/);
+  });
+});

package/src/ceph/ceph-transport.ts

@@ -0,0 +1,117 @@
+/**
+ * The Ceph mon-command transport (K-A4, T-A): ssh to one of the TB4 mon nodes, `sudo -n
+ * /usr/bin/ceph …`, tried in node order. Every call is checked against ceph-argv.ts's allowlist
+ * BEFORE anything dials — a refused shape never opens a connection, never mind runs a command.
+ *
+ * ★ BUILT ON THE SAME WIRE FORMAT sshSudoRunner USES, NOT A SECOND ONE. `runRemote` (the framed
+ *   script + nonce marker `../linux/ssh-command.ts` and `../linux/ssh-runner.ts` already ship and
+ *   test) is reused directly: same fail-closed behaviour on a dropped connection, same
+ *   `BatchMode=yes`, same host-key verification left to the operator's own ssh config.
+ * ⛔ THE DIAL IS AN INJECTED SEAM, NOT child_process MOCKED. `CephDial` is the same idea as
+ *   `HostRunner` (../launchd/runner.ts): production code gets `sshCephDial`, tests hand a fake
+ *   function directly (fake-ceph-dial.ts) — no ssh binary, no spawned process, ever, in a test.
+ * ⛔ A TRANSPORT FAILURE (no mon reachable) IS NEVER "ABSENT". Only a mon that actually ran the
+ *   command and answered gets to say whether an entity exists; every node failing to connect
+ *   propagates as an Error, so a down anchor can never read as "recreate it".
+ * ⛔ ONLY ARGV IS EVER LOGGED. `log` is called with the shape being attempted, never with a
+ *   result's stdout or stderr — `auth get`/`auth get-or-create`'s stdout carries the entity's key.
+ */
+import { randomBytes } from 'node:crypto';
+import { quoteArgv } from '../linux/ssh-command.ts';
+import { runRemote } from '../linux/ssh-runner.ts';
+import { SUDO, SudoRefusedError } from '../linux/sudo-allowlist.ts';
+import { cephCommandProblem, quorumStatusArgv } from './ceph-argv.ts';
+import { parseQuorumStatus } from './ceph-auth-parse.ts';
+
+export type CephExecResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+/** One attempt against one mon: run `argv` (already sudo-wrapped by the caller) and report. */
+export type CephDial = (node: string, argv: readonly string[]) => Promise<CephExecResult>;
+
+const CONNECT_TIMEOUT_SEC = 10;
+const EXEC_TIMEOUT_MS = 30_000;
+
+/** ★ A fresh nonce per attempt — this dial never reuses a connection or a marker across calls. */
+export const sshCephDial: CephDial = async (node, argv) => {
+  const nonce = randomBytes(8).toString('hex');
+  const script = `${SUDO} -n -- ${quoteArgv(argv)}`;
+  return runRemote(
+    { connectTimeoutSec: CONNECT_TIMEOUT_SEC, execTimeoutMs: EXEC_TIMEOUT_MS, host: node },
+    nonce,
+    script,
+  );
+};
+
+export type CephTransportOptions = {
+  /** TB4 mon ssh destinations, tried in this order. Required; at least one. */
+  readonly nodes: readonly string[];
+  readonly dial?: CephDial;
+  /** One line per attempted argv, before it dials. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+const defaultLog = (line: string) => process.stderr.write(`${line}\n`);
+
+/**
+ * Run one allowed ceph shape against the first mon that answers.
+ *
+ * ⛔ THE ALLOWLIST CHECK HAPPENS BEFORE THE FIRST NODE IS EVEN TRIED — a refused argv dials no
+ *   ssh at all, so a bug that builds a bad shape cannot leak so much as a connection attempt.
+ */
+export const runCephCommand = async (
+  options: CephTransportOptions,
+  argv: readonly string[],
+): Promise<CephExecResult & { readonly node: string }> => {
+  const problem = cephCommandProblem(argv);
+  if (problem !== undefined) {
+    throw new SudoRefusedError(`ceph transport refused ${JSON.stringify(argv)}: ${problem}`);
+  }
+  if (options.nodes.length === 0) throw new Error('ceph transport: no mon nodes were declared');
+  const dial = options.dial ?? sshCephDial;
+  const log = options.log ?? defaultLog;
+  const attempts: { readonly node: string; readonly message: string }[] = [];
+  for (const node of options.nodes) {
+    log(`homeflare/ceph sudo -n ${JSON.stringify(argv)} @ ${node}`);
+    try {
+      const result = await dial(node, argv);
+      return { ...result, node };
+    } catch (cause) {
+      attempts.push({ message: cause instanceof Error ? cause.message : String(cause), node });
+    }
+  }
+  // ⛔ NEVER "ABSENT". Every mon this call knew about failed at the transport layer; that is a
+  //   down anchor (or a network problem), not proof the entity does not exist.
+  const detail = attempts.map((a) => `${a.node}: ${a.message}`).join('; ');
+  throw new Error(`ceph transport: every mon node failed (never treated as absent) — ${detail}`);
+};
+
+/**
+ * ★ LOCKOUT SAFETY, THE UFW-ESTABLISHED PATTERN: after every write, re-check quorum on a FRESH
+ *   connection (a new dial, never the one the write used) and fail the row if it degraded. Never
+ *   auto-repair, never continue — the caller's write is reported as failed even though it may
+ *   itself have succeeded, because a write that broke quorum is not a success this transport will
+ *   call one.
+ * ⚠️ THE SHAPE OF `quorum_status -f json` IS REASONED FROM PUBLIC CEPH DOCS, NOT MEASURED against
+ *   this estate's Ceph release — there is no mon yet. An unparseable or missing `quorum` array
+ *   fails closed as "degraded", never as "healthy"; see ceph-auth-parse.ts.
+ */
+export const assertFreshQuorum = async (options: CephTransportOptions): Promise<void> => {
+  const result = await runCephCommand(options, quorumStatusArgv());
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `ceph quorum_status failed after a write (mon ${result.node}): ` +
+        `${result.stderr.trim().slice(0, 300)}`,
+    );
+  }
+  const quorum = parseQuorumStatus(result.stdout);
+  if (!quorum.healthy) {
+    throw new Error(
+      `ceph quorum degraded after a write (mon ${result.node}): ${quorum.reason} — the write is ` +
+        'reported as failed even if it landed; nothing here auto-repairs a quorum problem.',
+    );
+  }
+};

package/src/ceph/fake-ceph-dial.ts

@@ -0,0 +1,55 @@
+/**
+ * A fake `CephDial` for the tests beside it — no ssh, no spawned process, ever. The same idea as
+ * `../linux/fake-sudo.ts` and `../openbao/fake-bao.ts`: production code is handed the real
+ * implementation, a test hands this instead, and neither one's internals change to make room for
+ * the other.
+ *
+ * ⛔ TEST-ONLY. Nothing in `src/` imports this outside a `.test.ts` file.
+ */
+import type { CephDial, CephExecResult } from './ceph-transport.ts';
+
+/** One call this fake received. */
+export type SeenCephCall = { readonly node: string; readonly argv: readonly string[] };
+
+/** What a scripted node answers: a result, or a thrown transport failure. */
+export type CephAnswer =
+  | { readonly kind: 'result'; readonly result: CephExecResult }
+  | { readonly kind: 'transport-error'; readonly message: string };
+
+export type FakeCephDial = {
+  readonly dial: CephDial;
+  readonly seen: SeenCephCall[];
+};
+
+const ok = (stdout: string, exitCode = 0, stderr = ''): CephAnswer => ({
+  kind: 'result',
+  result: { exitCode, stderr, stdout },
+});
+
+/**
+ * `script` maps a node to the fixed sequence of answers it gives, one per call that reaches it —
+ * the last entry repeats once exhausted. A node with no entry always transport-fails, which is
+ * exactly "an unreachable mon" without a special case.
+ */
+export const fakeCephDial = (
+  script: Readonly<Record<string, readonly CephAnswer[]>>,
+): FakeCephDial => {
+  const seen: SeenCephCall[] = [];
+  const counts = new Map<string, number>();
+  const dial: CephDial = async (node, argv) => {
+    seen.push({ argv, node });
+    const answers = script[node];
+    if (answers === undefined || answers.length === 0) {
+      throw new Error(`fakeCephDial: ${node} is not reachable (no script entry)`);
+    }
+    const at = counts.get(node) ?? 0;
+    counts.set(node, at + 1);
+    const answer = answers[Math.min(at, answers.length - 1)];
+    if (answer === undefined) throw new Error(`fakeCephDial: ${node} has no answer`);
+    if (answer.kind === 'transport-error') throw new Error(answer.message);
+    return answer.result;
+  };
+  return { dial, seen };
+};
+
+export { ok as fakeCephOk };

package/src/ceph/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Ceph providers for Alchemy — the mon-command transport and `Ceph.AuthEntity` (K-A4).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, DELIBERATELY SMALLER THAN THE DIRECTORY — see
+ *   `../openbao/index.ts`'s header for why. The allowlist internals (ceph-argv.ts), the parsing
+ *   (ceph-auth-parse.ts) and the reconcile loop (ceph-auth-reconcile.ts) are exported by path for
+ *   a future `CephConfigOption` (K-D) or a test to reach directly, not published here.
+ */
+export type { CephAuthEntityAttributes, CephAuthEntityProps, CephCaps } from './auth-entity.ts';
+export { CephAuthEntity, CephAuthEntityProvider } from './auth-entity.ts';
+export type { CephDial, CephExecResult, CephTransportOptions } from './ceph-transport.ts';
+export { assertFreshQuorum, runCephCommand, sshCephDial } from './ceph-transport.ts';

package/src/index.ts

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

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

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * ⛔ WHAT THESE PIN: a "fresh" declaration (new-disk GiB, `storage:cloudinit`, or
+ *   `storage:0,import-from=...`) 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';
@@ -20,6 +20,145 @@ describe('a "fresh" declaration matches any existing volume in its slot', () =>
   });
 });
 
+/**
+ * The disk-import convergence bug homeflare-proxmox PR 84's red team found (2026-09-26, real
+ * fake-PVE engine): `judgeDisk` never recognized `<storage>:0,import-from=<volid>` as a new-disk
+ * spelling, so it compared the literal volname `"0"` against PVE's live read-back of the real
+ * `vm-<vmid>-disk-<n>` it allocated on import and refused -- on the very deploy that created the
+ * disk, and on every plan after (Talos's `declareTalos` declares the import spelling every time,
+ * never switches to the resolved volname). Each `judgeDisk` call below stands in for one PVE read
+ * a real Talos deploy makes; none of them are a live PVE call.
+ */
+describe('the import-from create spelling converges (PR 84 red team)', () => {
+  const IMPORT_DECLARED = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('create: post-write verification reads back the real volume PVE allocated', () => {
+    // The deploy that creates the VM re-reads the config right after the PUT to verify it landed.
+    // Before the fix this was refused (declared volname "0" vs live "vm-10000-disk-0").
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G')).toEqual({});
+  });
+
+  test('re-plan: the same declared import spelling against the now-adopted live disk', () => {
+    // A later `bun run plan` fabricates the same live read as create did; declared is unchanged
+    // (declareTalos always emits import-from, never the resolved volname). Must still be a no-op.
+    const verdict = judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toBeUndefined();
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('second deploy: PVE has since filled in defaults the fresh check must not treat as drift', () => {
+    // pve-qemu-server fills in options nobody declared (ssd/discard/etc.). A "fresh" declaration
+    // skips option comparison entirely, so this must be a no-op too -- not a PUT trying to "fix"
+    // options that were never wrong, and not a resize of the placeholder "0" against the real size.
+    const verdict = judgeDisk(
+      'scsi0',
+      IMPORT_DECLARED,
+      'cephtb4:vm-10000-disk-0,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('no resize is ever attempted for an import-from disk', () => {
+    // The live size (2G, from the imported image) never appears in a `put` -- there is no `put` at
+    // all, because `want.kind === 'fresh'` returns before size or options are ever inspected.
+    expect(judgeDisk('scsi0', IMPORT_DECLARED, 'cephtb4:vm-10000-disk-0,size=200G')).toEqual({});
+  });
+
+  test('a volid with its own colon (storage:path) still parses as one fresh spelling', () => {
+    // import-from points at cephfs-tb4:import/talos-factory.raw -- a second colon inside the value,
+    // which a colon-anchored regex could truncate. Confirms the whole declared string is consumed.
+    expect(
+      judgeDisk(
+        'scsi0',
+        'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+        'cephtb4:vm-10042-disk-0,size=2G',
+      ),
+    ).toEqual({});
+  });
+
+  test('a genuine size mismatch on an already-adopted volume is still refused', () => {
+    // Not an import-from declaration: a plain adopted volume whose declared size disagrees with the
+    // live one. Must still hit the existing no-resize refusal, unchanged by the new spelling.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:vm-10000-disk-0,size=4G',
+      'cephtb4:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/does not resize a disk/);
+    expect(verdict.put).toBeUndefined();
+  });
+
+  test('volname "0" without import-from is not swept into the new "fresh" spelling', () => {
+    // Guards NEW_IMPORT's literal ",import-from=" requirement: a coincidental "storage:0,k=v" (no
+    // import-from) must still be judged as a real volume named "0", not treated as always-matching.
+    const verdict = judgeDisk('scsi0', 'cephtb4:0,ssd=1', 'cephtb4:vm-10000-disk-0,size=2G');
+    expect(verdict.refuse).toMatch(/is not the live vm-10000-disk-0/);
+  });
+
+  test('a mismatched storage on an import-from declaration is still refused, not silently matched', () => {
+    // "fresh" only skips the volname/size/options checks -- the storage check above it still runs.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw',
+      'local-zfs:vm-10000-disk-0,size=2G',
+    );
+    expect(verdict.refuse).toMatch(/the volume is on local-zfs, declared on cephtb4/);
+  });
+});
+
+/**
+ * The LAND red team's Important finding on this same PR (2026-09-26): options declared alongside
+ * `import-from` were either silently dropped (declared after it -- `.+` swallowed them uncompared)
+ * or stranded the disk forever (declared before it -- missed the old regex, fell to the `volume`
+ * branch, and got refused against the real live volname just like the bug this file fixes). Fixed by
+ * detecting `import-from` after the general comma split instead of a position-anchored regex.
+ */
+describe('options declared alongside import-from are enforced, in either order (LAND red team)', () => {
+  const IMPORT = 'cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw';
+
+  test('an option after import-from that already matches live is a noop', () => {
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('an option after import-from that disagrees with live is written, on the live volume id', () => {
+    // Scenario B from the red team: iothread was declared and honored at create; discard/ssd are
+    // added later. Before this fix, verify said `noop` and the deploy wrote nothing.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1,discard=on,ssd=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict.put).toBe('cephtb4:vm-150-disk-0,iothread=1,discard=on,ssd=1,size=2G');
+  });
+
+  test('an option BEFORE import-from is still recognized as fresh, not a stranded volume', () => {
+    // Scenario C from the red team: `cephtb4:0,iothread=1,import-from=...` missed the old
+    // position-anchored regex entirely and was refused forever as a volname "0" vs the live one.
+    const verdict = judgeDisk(
+      'scsi0',
+      'cephtb4:0,iothread=1,import-from=cephfs-tb4:import/talos-factory.raw',
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G',
+    );
+    expect(verdict).toEqual({});
+  });
+
+  test('a live-only default the caller never declared is not treated as drift', () => {
+    // Only iothread was declared; ssd/discard are PVE's own fill-in. A full-map compare (sameMap)
+    // would call this drift and rewrite the disk on every plan -- the subset check must not.
+    const verdict = judgeDisk(
+      'scsi0',
+      `${IMPORT},iothread=1`,
+      'cephtb4:vm-150-disk-0,iothread=1,size=2G,ssd=1,discard=on',
+    );
+    expect(verdict).toEqual({});
+  });
+});
+
 describe('an existing-volume declaration', () => {
   const live = 'cephtb4:vm-101-disk-0,size=32G,ssd=1';
 
@@ -77,4 +216,14 @@ describe('parseDisk', () => {
     expect(disk.size).toBe('32G');
     expect(disk.options).toEqual(new Map([['ssd', '1']]));
   });
+
+  test('the import-from spelling parses as fresh, same shape as the other two', () => {
+    expect(parseDisk('cephtb4:0,import-from=cephfs-tb4:import/talos-factory.raw')).toEqual({
+      kind: 'fresh',
+      options: new Map(),
+      size: undefined,
+      source: 'cephtb4',
+      volname: '',
+    });
+  });
 });

package/src/proxmox/qemu-volume.ts

@@ -11,15 +11,48 @@
  *   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.
+ * ⛔ A THIRD NEW-VOLUME SPELLING, FOUND BY homeflare-proxmox PR 84's RED TEAM (2026-09-26, real
+ *   fake-PVE engine): `<storage>:0,import-from=<volid>` imports a disk from another volume or a
+ *   downloaded image at create time. Before this fix it fell through to the `volume` branch below
+ *   (it has a comma, so `NEW_DISK` never matched it), so `want.volname` stayed the literal `"0"`
+ *   forever while PVE's live read-back reported the real `vm-<vmid>-disk-<n>` it allocated on
+ *   import -- a volname mismatch, REFUSED. That refusal fired on the very deploy that created the
+ *   disk (post-write verification reads the config right back) and on every plan after, because
+ *   the declared value is `import-from=...` again each time (Talos's `declareTalos` recomputes it
+ *   from the download resource, never switches to the resolved volname). Fixed the same way as the
+ *   other two: an `import-from` disk also counts as `kind: 'fresh'`, which already matches whatever
+ *   is live unconditionally when nothing else is declared (see `want.kind === 'fresh'` below) -- no
+ *   special-casing of the live side needed.
+ * ⛔ IMPORT-FROM IMPORTS ONLY AT CREATE. Changing just the `import-from=` *source* (e.g. bumping a
+ *   factory image path) on an already-created disk still reads as `noop`: PVE does not re-import an
+ *   existing volume, and this resource has no rebuild-the-disk path. That is correct for Talos, which
+ *   upgrades in place through `talosctl`, not by recreating its disk -- a caller that DOES want a
+ *   fresh import on image change must delete and recreate the row itself.
+ * ⛔ LAND RED TEAM (2026-09-26): OPTIONS DECLARED ALONGSIDE `import-from` MUST STILL BE ENFORCED, AND
+ *   MUST BE RECOGNIZED REGARDLESS OF WHERE `import-from` SITS IN THE LIST. The first cut matched
+ *   `import-from` only when it came immediately after `:0,`, via a regex whose `.+` then swallowed
+ *   every option after it uncompared (silently never written) while any option declared BEFORE it
+ *   (`cephtb4:0,iothread=1,import-from=...`) missed the regex entirely and fell to the `volume`
+ *   branch, comparing literal volname `"0"` against the live real one forever -- REFUSED, same
+ *   stranded-disk failure this file exists to fix, just for a different option order. Fixed by
+ *   folding the import check into the general `storage:volname,k=v,...` parse below: ANY declaration
+ *   whose volname is the literal `"0"` and whose options include an `import-from` key is `fresh`,
+ *   with `import-from` itself dropped and every other declared option carried through for
+ *   `judgeDisk` to enforce (see its `want.kind === 'fresh'` branch) -- independent of option order.
  * ⛔ 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.
+ * ⚠️ OPTIONS BEYOND `size` ARE COMPARED AS A WHOLE, NOT KEY BY KEY, FOR AN ADOPTED `volume` -- BUT AS
+ *   A SUBSET FOR A `fresh` IMPORT. Unlike lxc-volume.ts, this file does not model pve-qemu-server's
+ *   per-option defaults (`ssd`, `discard`, `iothread`, …) — that table is unverified here. For an
+ *   already-adopted volume, any options difference from live is real drift and gets written in full,
+ *   exactly as the whole-string comparison this replaces already did. An `import-from` disk cannot
+ *   use that same whole-map comparison: nobody declares PVE's post-import defaults, so comparing the
+ *   full map would treat every default PVE fills in as drift and rewrite the disk on every plan (the
+ *   builder's "second deploy" test below pins this). So a `fresh` import instead checks only the
+ *   options the caller actually declared against live, ignoring any live-only keys, and PUTs the
+ *   declared options (not merged with what live already has) when one of them disagrees.
  */
 import { sameMap } from './lxc-wire.ts';
 
@@ -29,7 +62,8 @@ const NEW_DISK = /^([^:\s]+):(\d+(?:\.\d+)?)$/;
 const NEW_CLOUDINIT = /^([^:\s]+):cloudinit$/;
 
 export type Disk = {
-  /** `fresh`: either new-disk spelling above. `volume`: an existing volume, `storage:volname,...`. */
+  /** `fresh`: a new-disk spelling (`storage:GiB`, `storage:cloudinit`, or `storage:0,import-from=...`
+   *  possibly with more options). `volume`: an existing volume, `storage:volname,...`. */
   readonly kind: 'fresh' | 'volume';
   readonly source: string;
   readonly volname: string;
@@ -37,15 +71,24 @@ export type Disk = {
   readonly options: Map<string, string>;
 };
 
-/** `storage:volname,k=v,...` (or one of the two "fresh" spellings) into its comparable parts. */
+/**
+ * `storage:volname,k=v,...` (or one of the "fresh" spellings) into its comparable parts.
+ * ⚠️ THE IMPORT SPELLING IS DETECTED AFTER THE GENERAL SPLIT, NOT BY ITS OWN REGEX: `import-from`'s
+ *   value can itself contain a colon (e.g. `cephfs-tb4:import/talos-factory.raw`) and other options
+ *   can come before or after it, so a regex anchored on `:0,import-from=` right after the colon (as
+ *   the first cut had) misses that ordering and swallows everything after it into one opaque match.
+ *   Splitting on commas like any `volume` spelling first, THEN checking for a literal `"0"` volname
+ *   plus an `import-from` key among the parsed options, catches every ordering and keeps every other
+ *   declared option (`iothread=1`, `discard=on`, …) visible to `judgeDisk` instead of swallowed.
+ */
 export const parseDisk = (text: string): Disk => {
-  const fresh = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
-  if (fresh !== null) {
+  const bare = NEW_DISK.exec(text) ?? NEW_CLOUDINIT.exec(text);
+  if (bare !== null) {
     return {
       kind: 'fresh',
       options: new Map(),
       size: undefined,
-      source: fresh[1] ?? '',
+      source: bare[1] ?? '',
       volname: '',
     };
   }
@@ -61,6 +104,10 @@ export const parseDisk = (text: string): Disk => {
   );
   const size = options.get('size');
   options.delete('size');
+  if (volname === '0' && options.has('import-from')) {
+    options.delete('import-from');
+    return { kind: 'fresh', options, size: undefined, source, volname: '' };
+  }
   return { kind: 'volume', options, size, source, volname };
 };
 
@@ -97,10 +144,20 @@ export const judgeDisk = (key: string, declared: string, live: string): DiskVerd
         '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 {};
+  // ⛔ A "fresh" declaration never re-triggers create: PVE holds a real volume in this slot already,
+  //   and re-sending storage:GiB / storage:cloudinit / storage:0,import-from=... as the PUT value
+  //   would allocate a SECOND volume and park the live one at unusedN (the header's ⛔, ported from
+  //   lxc-volume.ts's own). So a `fresh` PUT, when one is needed, is always built from the LIVE
+  //   volume id (`have.volname`/`have.size`), never the declared placeholder -- same as `volume`.
+  // ⚠️ ONLY THE OPTIONS THE CALLER ACTUALLY DECLARED ARE CHECKED (a subset, not `sameMap`): nobody
+  //   declares PVE's post-import defaults, so an empty `want.options` (plain import-from, nothing
+  //   else declared) is always a noop no matter what live has filled in, and a non-empty one is
+  //   compared key-by-key against live, ignoring any key live has that the caller never declared.
+  if (want.kind === 'fresh') {
+    if (want.options.size === 0) return {};
+    if ([...want.options].every(([k, v]) => have.options.get(k) === v)) return {};
+    return { put: printOptions(have.source, have.volname, want.options, have.size) };
+  }
   if (want.volname !== have.volname) {
     return {
       refuse: