@homeflare/alchemy 0.37.5 → 0.37.7

package/src/proxmox/qemu-read.ts

@@ -0,0 +1,73 @@
+/**
+ * One QEMU config read, then a cluster-wide vmid check when that file is absent.
+ * ⛔ QemuConfigNotFound means the file is missing on THIS node. AbstractConfig raises it
+ *   before any other guest type is considered. A vmid is shared with containers, so absence
+ *   here is not permission to POST until the same credential's guest index agrees.
+ */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import * as Effect from 'effect/Effect';
+import { runPveWith } from './distilled-pve.ts';
+import { leased } from './lease-cache.ts';
+import { QemuRefusedError } from './qemu-errors.ts';
+import type { VmProps } from './qemu.ts';
+import { text } from './values.ts';
+
+const guestTypes = ['lxc', 'qemu'] as const;
+
+export const readVm = (props: VmProps) =>
+  Effect.gen(function* () {
+    const credential = yield* leased(props.target, 'read');
+    const answer = yield* runPveWith(
+      props.target,
+      credential,
+      false,
+      nodes.getNodeQemuConfig({ node: props.node, vmid: String(props.vmid) }),
+    ).pipe(
+      Effect.map((data) => ({ data, error: undefined })),
+      Effect.catchTag('QemuConfigNotFound', (error) => Effect.succeed({ data: undefined, error })),
+    );
+    if (answer.error === undefined) {
+      const live = answer.data;
+      // ⛔ The vendor requires digest. Null or an empty object is not absence.
+      if (typeof live.digest !== 'string' || live.digest === '') {
+        return yield* Effect.fail(
+          new QemuRefusedError(
+            `VM ${String(props.vmid)}: config read did not return a digest-bearing config.`,
+          ),
+        );
+      }
+      return live;
+    }
+    const rows = yield* runPveWith(
+      props.target,
+      credential,
+      false,
+      cluster.listClusterResources({ type: 'vm' }),
+    );
+    if (
+      !Array.isArray(rows) ||
+      rows.some(
+        (row) =>
+          !Number.isSafeInteger(Number(row?.vmid)) ||
+          Number(row?.vmid) <= 0 ||
+          typeof row?.node !== 'string' ||
+          row.node === '' ||
+          !guestTypes.includes(row.type as (typeof guestTypes)[number]),
+      )
+    ) {
+      return yield* Effect.fail(
+        new QemuRefusedError('The cluster guest index did not identify its rows.'),
+      );
+    }
+    const found = rows.find((row) => Number(row.vmid) === props.vmid);
+    if (found === undefined) return undefined;
+    if (found.node === props.node && found.type === 'qemu') return yield* Effect.fail(answer.error);
+    return yield* Effect.fail(
+      new QemuRefusedError(
+        `vmid ${String(props.vmid)} is a ${text(found.type, 'guest')} on ` +
+          `${text(found.node, '?')}, not a VM on ${props.node}. A migration is not an ` +
+          'update and vmids are cluster-wide: declare the node it is on, or pick a free vmid.',
+      ),
+    );
+  });

package/src/proxmox/qemu-task.ts

@@ -0,0 +1,64 @@
+/** Bounded QEMU task observation on the credential that started the worker. */
+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 { QemuRefusedError } from './qemu-errors.ts';
+import type { VmProps } from './qemu.ts';
+import { text } from './values.ts';
+
+/**
+ * ⛔ Fresh provision mint, then the same lease for every poll. A timed-out poll is uncertainty,
+ *   never a reason to send the write again.
+ */
+export const qemuTask = <E>(
+  props: VmProps,
+  operation: Effect.Effect<string, E, ProxmoxOpContext>,
+  what: string,
+  polls: number,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* mint(props.target, 'provision');
+    const upid = text(yield* runPveWith(props.target, credential, true, operation));
+    if (upid === '') {
+      return yield* Effect.fail(
+        new QemuRefusedError(
+          `${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(
+        props.target,
+        credential,
+        false,
+        nodes.getNodeTaskStatus({ node: props.node, upid }),
+      ).pipe(Effect.orElseSucceed(() => undefined));
+      // ⚠️ "COULD NOT BE READ" IS A MISSING ANSWER OR A MISSING `status` FIELD, NOT AN UNEXPECTED
+      //   ONE. `GetNodeTaskStatusResponseStatus` types `status` as the closed union
+      //   `"running" | "stopped"`, but the runtime validator is `S.String` (measured in
+      //   distilled-proxmox's nodes.ts), so a well-formed answer with a status word this
+      //   endpoint's contract was never proven to exclude (something other than exactly
+      //   "running") must keep polling rather than abort, since only "stopped" ends the task
+      //   (2026-09-25 adversarial review; matches lxc-task.ts and network-apply-read.ts's
+      //   awaitTask).
+      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 QemuRefusedError(
+          `${what}: task ${upid} ended "${exit}". Read the task log before running the deploy again.`,
+        ),
+      );
+    }
+  });

package/src/proxmox/qemu.ts

@@ -1,9 +1,9 @@
 /**
  * `Proxmox.Vm` — a QEMU virtual machine, declared.
  *
- * ⚠️ THE SAME FOUR OPERATIONS AS AN LXC OVER A DIFFERENT PATH, which is the point of the factory:
- *   `nodes/{node}/qemu` to create, `nodes/{node}/qemu/{vmid}/config` to read and update. A VM and a
- *   container differ in what they carry, not in how they are reconciled.
+ * ⚠️ 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
+ *   config route is not a destroy. A missing config file is `QemuConfigNotFound` only.
  *
  * ⛔ `vmid` IS CLUSTER-WIDE AND SHARED WITH CONTAINERS. A VM and an LXC cannot hold the same id, so
  *   these two resources compete for one number space. Declaring both with vmid 101 is not a
@@ -17,8 +17,8 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { num } from './values.ts';
+import { qemuHandlers } from './qemu-lifecycle.ts';
+import type { PveRequirements, WithTarget } from './resource.ts';
 
 export interface VmProps extends WithTarget {
   node: string;
@@ -54,44 +54,11 @@ export interface ProxmoxVm extends Resource<
 
 export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm');
 
-/** ★ Exported so the constraint proof can run the REAL create form, not a retyped copy of it. */
-export const createForm = (props: VmProps) => ({ ...shape(props), vmid: String(props.vmid) });
-
-const shape = (props: VmProps) => ({
-  cores: String(props.cores ?? 1),
-  memory: String(props.memory ?? 512),
-  name: props.name ?? `vm${String(props.vmid)}`,
-  onboot: props.onboot === true ? '1' : '0',
-  sockets: String(props.sockets ?? 1),
-  ...(props.net0 === undefined ? {} : { net0: props.net0 }),
-});
-
-const handlers = pveHandlers<VmProps, VmAttributes>({
-  attributes: (live, props) => ({
-    cores: num(live['cores'], 1),
-    memory: num(live['memory'], 512),
-    name: typeof live['name'] === 'string' ? live['name'] : '',
-    node: props.node,
-    onboot: live['onboot'] === 1 || live['onboot'] === true,
-    sockets: num(live['sockets'], 1),
-    vmid: props.vmid,
-  }),
-  collection: (props) => `nodes/${props.node}/qemu`,
-  createForm,
-  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /nodes/{node}/qemu',
-    update: 'pve:PUT /nodes/{node}/qemu/{vmid}/config',
-  },
-  matches: (attributes, props) =>
-    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),
-  path: (props) => `nodes/${props.node}/qemu/${String(props.vmid)}/config`,
-  updateForm: shape,
-});
+export { createForm } from './qemu-form.ts';
 
+/**
+ * ⛔ Destroy uses deleteNodeQemu (`DELETE /nodes/{node}/qemu/{vmid}`), not the config path.
+ *   The old factory sent both reads and deletes to `.../config`.
+ */
 export const ProxmoxVmProvider = () =>
-  Provider.effect(ProxmoxVm, Effect.succeed(ProxmoxVm.Provider.of(handlers)));
+  Provider.effect(ProxmoxVm, Effect.succeed(ProxmoxVm.Provider.of(qemuHandlers)));

package/src/proxmox/replication-firewall-fixtures.ts

@@ -0,0 +1,71 @@
+/** Source-backed vendor responses; no live host or credential is used by these tests. */
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET } from './fake-pve.ts';
+import type { CoreCase } from './live-core-fixtures.ts';
+import { ProxmoxReplicationJob, ProxmoxReplicationJobProvider } from './replication-job.ts';
+import { deleteReplicationJob, readReplicationJob } from './replication-job-lifecycle.ts';
+import { ProxmoxFirewallAlias, ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
+import { deleteFirewallAlias, readFirewallAlias } from './firewall-alias-lifecycle.ts';
+
+export const replicationProps = { target: FAKE_TARGET, guest: 900, jobnum: 0, targetNode: 'pve-b' };
+export const aliasProps = {
+  target: FAKE_TARGET,
+  name: 'HomeLan',
+  cidr: '192.0.2.1/32',
+  comment: ' 0 ',
+};
+export const replicationLive = {
+  id: '900-0',
+  guest: 900,
+  jobnum: 0,
+  target: 'pve-b',
+  type: 'local',
+  source: 'pve-a',
+};
+export const aliasLive = { name: 'homelan', cidr: '192.0.2.1', ipversion: 4 };
+export const replicationMissing = () =>
+  Response.json({ data: null, message: "no such replication job '900-0'\n" }, { status: 500 });
+export const aliasMissing = () =>
+  Response.json(
+    { data: null, message: 'Parameter verification failed.\n', errors: { name: 'no such alias' } },
+    { status: 400 },
+  );
+
+export const replicationFirewallCases: CoreCase[] = [
+  {
+    name: 'ReplicationJob',
+    path: 'cluster/replication/900-0',
+    createPath: 'cluster/replication',
+    declare: () => ProxmoxReplicationJob('row', replicationProps),
+    engine: (fake) =>
+      engineOver(ProxmoxReplicationJobProvider().pipe(Layer.provideMerge(fake.layer))),
+    read: () => readReplicationJob(replicationProps),
+    remove: () => deleteReplicationJob(replicationProps),
+    live: replicationLive,
+    drift: { ...replicationLive, remove_job: 'full' },
+    missing: replicationMissing,
+    createForm: {
+      id: '900-0',
+      type: 'local',
+      target: 'pve-b',
+      comment: '',
+      disable: '0',
+      schedule: '*/15',
+    },
+  },
+  {
+    name: 'FirewallAlias',
+    path: 'cluster/firewall/aliases/HomeLan',
+    createPath: 'cluster/firewall/aliases',
+    declare: () => ProxmoxFirewallAlias('row', aliasProps),
+    engine: (fake) =>
+      engineOver(ProxmoxFirewallAliasProvider().pipe(Layer.provideMerge(fake.layer))),
+    read: () => readFirewallAlias(aliasProps),
+    remove: () => deleteFirewallAlias(aliasProps),
+    live: aliasLive,
+    drift: { ...aliasLive, comment: 'old' },
+    missing: aliasMissing,
+    createForm: { name: 'HomeLan', cidr: '192.0.2.1' },
+  },
+];

package/src/proxmox/replication-firewall-lifecycle.test.ts

@@ -0,0 +1,109 @@
+/** Real Alchemy Plan/Apply and distilled requests; fixtures never reach a real host. */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import { replicationFirewallCases } from './replication-firewall-fixtures.ts';
+
+for (const entry of replicationFirewallCases) {
+  describe(`distilled ${entry.name}`, () => {
+    test('adoption, subsequent plan and apply have zero writes', async () => {
+      const fake = fakePve(() => entry.live);
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        expect((await engine.verify(entry.declare(), { all: true })).rows).toEqual([
+          expect.objectContaining({ diff: 'noop', ok: true }),
+        ]);
+        expect(await engine.deploy(entry.declare())).toEqual({ row: 'adopted' });
+        expect((await engine.verify(entry.declare(), { all: true })).rows).toEqual([
+          expect.objectContaining({ diff: 'noop', ok: true }),
+        ]);
+        await engine.deploy(entry.declare());
+        expect(engine.stored()).not.toContain('fake-not-a-secret');
+      });
+      expect(fake.writes()).toEqual([]);
+    });
+
+    test('genuine absence creates once, then reads and converges', async () => {
+      let exists = false;
+      const fake = fakePve((call) => {
+        if (call.method === 'GET') return exists ? entry.live : entry.missing();
+        exists = true;
+        return null;
+      });
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        await engine.deploy(entry.declare());
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'noop',
+        });
+      });
+      expect(fake.writes()).toEqual([`POST ${entry.createPath}`]);
+      expect(fake.calls.find((call) => call.method === 'POST')?.form).toEqual(entry.createForm);
+    });
+
+    test('live drift produces exactly one PUT and preserves omitted fields', async () => {
+      let live = entry.drift;
+      const fake = fakePve((call) => {
+        if (call.method === 'GET') return live;
+        live = entry.live;
+        return null;
+      });
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'update',
+        });
+        await engine.deploy(entry.declare());
+        expect((await engine.verify(entry.declare(), { all: true })).rows[0]).toMatchObject({
+          diff: 'noop',
+        });
+      });
+      expect(fake.writes()).toEqual([`PUT ${entry.path}`]);
+      const form = fake.calls.find((call) => call.method === 'PUT')?.form;
+      if (entry.name === 'ReplicationJob') {
+        expect(form).toEqual({ comment: '', disable: '0', schedule: '*/15', delete: 'remove_job' });
+      } else {
+        // PUT replaces the alias entry: omitted comment clears it, no delete/rename/id fields.
+        expect(form).toEqual({ cidr: '192.0.2.1' });
+      }
+    });
+
+    for (const status of [401, 403, 500]) {
+      test(`${status} read failure stops cold adoption and confirmed drift before writes`, async () => {
+        let fail = true;
+        const fake = fakePve(() =>
+          fail
+            ? Response.json({ data: null, message: 'unrelated failure' }, { status })
+            : entry.live,
+        );
+        await withoutBao(async () => {
+          const engine = entry.engine(fake);
+          await expect(engine.deploy(entry.declare())).rejects.toBeDefined();
+          fail = false;
+          await engine.deploy(entry.declare());
+          fail = true;
+          await expect(engine.drift(entry.declare())).rejects.toBeDefined();
+          await expect(engine.deploy(entry.declare())).rejects.toBeDefined();
+        });
+        expect(fake.writes()).toEqual([]);
+      });
+    }
+
+    test('delete failure retains the engine state and propagates', async () => {
+      let failing = false;
+      const fake = fakePve(() =>
+        failing
+          ? Response.json({ data: null, message: 'permission denied' }, { status: 403 })
+          : entry.live,
+      );
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        await engine.deploy(entry.declare().pipe(RemovalPolicy.destroy()));
+        failing = true;
+        await expect(engine.deploy(Effect.void)).rejects.toBeDefined();
+        expect(engine.stored()).toContain('row');
+      });
+    });
+  });
+}

package/src/proxmox/replication-firewall-wire.test.ts

@@ -0,0 +1,173 @@
+/** Exact absence, state identity and deletion semantics through the real distilled protocol. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import { engineOver } from '../verify/fake-engine.ts';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import {
+  aliasLive,
+  aliasProps,
+  replicationFirewallCases,
+  replicationLive,
+  replicationProps,
+} from './replication-firewall-fixtures.ts';
+import { ProxmoxFirewallAlias, ProxmoxFirewallAliasProvider } from './firewall-alias.ts';
+import { ProxmoxReplicationJob, ProxmoxReplicationJobProvider } from './replication-job.ts';
+
+for (const entry of replicationFirewallCases) {
+  test(`${entry.name}: malformed successful reads never authorize a create`, async () => {
+    for (const live of [null, {}, [], 'invalid', { ...entry.live, name: 'wrong', id: '901-0' }]) {
+      const fake = fakePve(() => live);
+      await withoutBao(async () => {
+        expect(
+          await Effect.runPromise(entry.read().pipe(Effect.flip, Effect.provide(fake.layer))),
+        ).toMatchObject({ _tag: 'ProxmoxParseError', body: undefined });
+        await expect(entry.engine(fake).deploy(entry.declare())).rejects.toBeDefined();
+      });
+      expect(fake.writes()).toEqual([]);
+    }
+  });
+
+  test(`${entry.name}: only source-backed absence is folded`, async () => {
+    const fake = fakePve(entry.missing);
+    await withoutBao(async () => {
+      expect(
+        await Effect.runPromise(entry.read().pipe(Effect.provide(fake.layer))),
+      ).toBeUndefined();
+    });
+    for (const [status, tag] of [
+      [401, 'Unauthorized'],
+      [403, 'Forbidden'],
+      [500, 'InternalServerError'],
+    ] as const) {
+      const failed = fakePve(() =>
+        Response.json({ data: null, message: 'unrelated failure' }, { status }),
+      );
+      await withoutBao(async () => {
+        expect(
+          await Effect.runPromise(entry.read().pipe(Effect.flip, Effect.provide(failed.layer))),
+        ).toMatchObject({ _tag: tag });
+        expect(
+          await Effect.runPromise(entry.remove().pipe(Effect.flip, Effect.provide(failed.layer))),
+        ).toMatchObject({ _tag: tag });
+      });
+    }
+  });
+
+  test(`${entry.name}: deletion succeeds when already absent`, async () => {
+    const fake = fakePve(() =>
+      entry.name === 'ReplicationJob'
+        ? Response.json({ data: null, message: "no such job '900-0'\n" }, { status: 500 })
+        : null,
+    );
+    await withoutBao(async () => {
+      await Effect.runPromise(entry.remove().pipe(Effect.provide(fake.layer)));
+    });
+    expect(fake.writes()).toEqual([`DELETE ${entry.path}`]);
+    expect(fake.calls[0]?.form).toEqual({});
+  });
+
+  test(`${entry.name}: explicit retain avoids DELETE, default destroy is implemented`, async () => {
+    for (const retain of [true, false]) {
+      const fake = fakePve((call) => (call.method === 'GET' ? entry.live : null));
+      await withoutBao(async () => {
+        const engine = entry.engine(fake);
+        await engine.deploy(
+          retain ? entry.declare().pipe(RemovalPolicy.retain()) : entry.declare(),
+        );
+        await engine.deploy(Effect.void);
+      });
+      expect(fake.writes()).toEqual(retain ? [] : [`DELETE ${entry.path}`]);
+      expect(fake.calls.find((call) => call.method === 'DELETE')?.form ?? {}).toEqual({});
+    }
+  });
+}
+
+test('alias rename is create-first replacement; case-only rename remains no-op', async () => {
+  const rows = new Map([['homelan', aliasLive]]);
+  const fake = fakePve((call) => {
+    const name = call.path.split('/').at(-1)?.toLowerCase() ?? '';
+    if (call.method === 'GET')
+      return (
+        rows.get(name) ??
+        Response.json(
+          {
+            data: null,
+            message: 'Parameter verification failed.\n',
+            errors: { name: 'no such alias' },
+          },
+          { status: 400 },
+        )
+      );
+    if (call.method === 'POST') {
+      const createdName = call.form['name'];
+      if (createdName === undefined) throw new Error('alias create omitted its required name');
+      rows.set(createdName.toLowerCase(), { ...aliasLive, name: createdName });
+    }
+    if (call.method === 'DELETE') rows.delete(name);
+    return null;
+  });
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxFirewallAliasProvider().pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(ProxmoxFirewallAlias('row', aliasProps));
+    await engine.deploy(ProxmoxFirewallAlias('row', { ...aliasProps, name: 'HOMELAN' }));
+    expect(fake.writes()).toEqual([]);
+    await engine.deploy(ProxmoxFirewallAlias('row', { ...aliasProps, name: 'NewLan' }));
+  });
+  expect(fake.writes()).toEqual([
+    'POST cluster/firewall/aliases',
+    'DELETE cluster/firewall/aliases/HomeLan',
+  ]);
+});
+
+test('replication ignores migrated source/target and undeclared fractional rate', async () => {
+  const fake = fakePve(() => ({
+    ...replicationLive,
+    target: 'pve-c',
+    source: 'pve-b',
+    rate: '10.5',
+  }));
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxReplicationJobProvider().pipe(Layer.provideMerge(fake.layer)));
+    await engine.deploy(ProxmoxReplicationJob('row', replicationProps));
+    expect(
+      (
+        await engine.verify(ProxmoxReplicationJob('row', { ...replicationProps, rate: 10.5 }), {
+          all: true,
+        })
+      ).rows[0],
+    ).toMatchObject({ diff: 'noop' });
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+test('replication tolerates guest/jobnum echoed as text, not just as numbers', async () => {
+  // ⚠️ SectionConfig releases can echo `guest`/`jobnum` as text the same way `rate` sometimes
+  //   arrives as text above; a strict `===` against the raw wire value would misread the exact
+  //   same job as an identity mismatch and fail the read closed (2026-09-25 adversarial review).
+  const fake = fakePve(() => ({ ...replicationLive, guest: '900', jobnum: '0' }));
+  await withoutBao(async () => {
+    const engine = engineOver(ProxmoxReplicationJobProvider().pipe(Layer.provideMerge(fake.layer)));
+    expect(
+      (await engine.verify(ProxmoxReplicationJob('row', replicationProps), { all: true })).rows[0],
+    ).toMatchObject({ diff: 'noop', ok: true });
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+test('vendor constraints reject invalid declarations before any write', async () => {
+  for (const replication of [true, false]) {
+    const fake = fakePve(() => (replication ? replicationLive : { ...aliasLive, name: 'x' }));
+    await withoutBao(async () => {
+      const engine = replication
+        ? engineOver(ProxmoxReplicationJobProvider().pipe(Layer.provideMerge(fake.layer)))
+        : engineOver(ProxmoxFirewallAliasProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declaration = replication
+        ? ProxmoxReplicationJob('row', { ...replicationProps, rate: 0 })
+        : ProxmoxFirewallAlias('row', { ...aliasProps, name: 'x' });
+      await expect(engine.deploy(declaration)).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  }
+});

package/src/proxmox/replication-job-config.ts

@@ -0,0 +1,79 @@
+/** Existing comparison and form semantics, separated from the named SDK transport. */
+import type { ReplicationJobAttributes, ReplicationJobProps } from './replication-job.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { DEFAULT_SCHEDULE, createBody, jobId, updateBody } from './replication-job-form.ts';
+import { bool, int, text } from './values.ts';
+
+/**
+ * ⚠️ `rate` IS THE ONLY FLOAT IN THIS PACKAGE, so it gets a coercion of its own rather than a sixth
+ *   entry in `values.ts` — the rule that module states for itself: a coercion only one PVE object
+ *   needs belongs in that object's file, next to the field it serves. `int` cannot serve it, since
+ *   `Number.parseInt('10.5')` is 10 and a rate silently rounded down is both a limit nobody chose
+ *   and a comparison that never settles. It accepts a string for the reason `int` does: these are
+ *   SectionConfig sections, and whether `10` arrives as a number is a property of the release.
+ * ⚠️ 0 MEANS UNSET, and is safe as the marker because PVE's schema gives `rate` a minimum of 1 —
+ *   the same trick as `metric-server.ts`'s `UNSET = -1`, for the same reason.
+ */
+const rateOf = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  const parsed = Number.parseFloat(text(value));
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+export const replicationJobSpec = {
+  /**
+   * ⚠️ EVERY FALLBACK IS PVE'S DOCUMENTED DEFAULT, NOT `false`/`''` PICKED FOR CONVENIENCE, so the
+   *   answer does not depend on whether a given release echoes back a key it never wrote.
+   *   SectionConfig stores what it was handed; a job created in the UI without a schedule has no
+   *   schedule line, and reading that absence as anything but `DEFAULT_SCHEDULE` would report
+   *   drift on a job nobody touched and then WRITE the reading back.
+   * ⛔ The distilled read validates the response and requested identity before applying defaults.
+   *   Only the precise typed vendor exception means absence. `digest` is deliberately absent
+   *   here — it changes when ANY job changes, including one somebody else declared.
+   */
+  attributes: (live, props) => ({
+    comment: text(live['comment'], ''),
+    disable: bool(live['disable'], false),
+    guest: int(live['guest'], props.guest),
+    id: text(live['id'], jobId(props)),
+    jobnum: int(live['jobnum'], props.jobnum),
+    rate: rateOf(live['rate']),
+    remove_job: text(live['remove_job'], ''),
+    schedule: text(live['schedule'], DEFAULT_SCHEDULE),
+    source: text(live['source'], ''),
+    targetNode: text(live['target'], props.targetNode),
+    type: text(live['type'], 'local'),
+  }),
+  collection: () => 'cluster/replication',
+  createForm: createBody,
+  /**
+   * ⚠️ `targetNode` AND `source` ARE OUT OF THIS COMPARISON FOR TWO REASONS EACH, AND EITHER ALONE
+   *   WOULD BE ENOUGH. They are create-only — `target` is a `fixed` option, `source` has no honest
+   *   declared value — AND PVE REWRITES BOTH BEHIND YOUR BACK. MEASURED in
+   *   `switch_replication_job_target_nolock`: when a guest migrates, PVE sets
+   *   `$jobcfg->{target} = $new_target` and `$jobcfg->{source} = $old_target`, so the job follows
+   *   the guest. Compared, a single migration would make every later plan report an update that the
+   *   PUT cannot perform, forever. The cost of leaving them out is stated on the `targetNode` prop:
+   *   a changed target plans as noop, and a migrated job is not dragged back.
+   * ⚠️ `guest`, `jobnum`, `type` AND `id` ARE NOT COMPARED EITHER: the first two are the id in
+   *   integer form, `type` has one legal value, and `id` is the path — a change there is a
+   *   different object, which reads as absent and is created.
+   * ⛔ `remove_job` IS COMPARED, AND IT IS THE ONE FIELD HERE THAT LOOKS LIKE A FOREVER-UPDATE AND
+   *   IS NOT. A DELETE marks the job rather than removing it, so a re-declared id can name a job
+   *   that is busy deleting itself, and matching that would be a noop over a vanishing object. It
+   *   settles because `updateBody` actually clears the marker — see there.
+   */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /cluster/replication',
+    update: 'pve:PUT /cluster/replication/{id}',
+  },
+  matches: (attributes, props) =>
+    attributes.remove_job === '' &&
+    attributes.schedule === (props.schedule ?? DEFAULT_SCHEDULE) &&
+    attributes.disable === (props.disable === true) &&
+    attributes.comment === (props.comment ?? '') &&
+    (props.rate === undefined || attributes.rate === props.rate),
+  path: (props) => `cluster/replication/${jobId(props)}`,
+  updateForm: updateBody,
+} satisfies PveSpec<ReplicationJobProps, ReplicationJobAttributes>;