@homeflare/alchemy 0.1.0

package/src/proxmox/pbs-verify-job.ts

@@ -0,0 +1,227 @@
+/**
+ * `Pbs.VerifyJob` — one section of PBS's `verification.cfg`, declared.
+ *
+ * ★ THIS IS THE FAMILY THAT ANSWERS "ARE THE BACKUPS ACTUALLY GOOD", AND NOTHING ELSE IN THIS
+ *   PACKAGE DOES. A datastore reports free space, a prune job reports that it ran, and every
+ *   snapshot in the store can still be unreadable: PBS learns a chunk has rotted only when
+ *   something reads it back and checks its digest, and verification is the only thing that does
+ *   that on a schedule. An undeclared verify job is the reason nobody notices for months — and a
+ *   green `Proxmox.BackupJob` makes it worse rather than better, because a vzdump job that says
+ *   "OK" every night is exactly the evidence people stop at.
+ *
+ * ⛔ THIS FILE CANNOT AUTHENTICATE UNTIL TWO THINGS OUTSIDE IT CHANGE, AND IT IS SHIPPED SAYING SO
+ *   RATHER THAN SHIPPED LOOKING FINISHED. Both are recorded on `PbsTarget` below:
+ *     1. `credentials.ts` has no PBS mint. MEASURED 2026-09-13 from this Mac: the `claude-code`
+ *        approle is refused `sys/mounts`, `kv/infra/proxmox` and `proxmox-pbs/creds/read` alike —
+ *        403 permission denied on all three — so there is no mount to name and none is invented.
+ *     2. `client.ts`'s `authorization()` builds a PVE header, and PBS will not accept it. See the
+ *        ⛔ on `PbsTarget`.
+ *   Until both land, every call 401s, `pveOperations.read` folds that into "absent", and the plan
+ *   reports `create` for a job that is plainly there. The deploy then FAILS at the POST rather
+ *   than clobbering anything — an unauthenticated POST 401s, and an authenticated one is refused
+ *   because PBS will not take a duplicate section id — so the cost is a LYING PLAN and a broken
+ *   run, not a lost job. That is still reason enough not to wire it into a stack yet: a plan
+ *   nobody can trust is its own outage.
+ *
+ * ⚠️ THE SHAPES BELOW ARE READ FROM PUBLISHED SOURCE, NOT MEASURED ON THIS ESTATE. Everything is
+ *   taken from `pbs-api-types/src/jobs.rs`, `src/api2/config/verify.rs`, `src/server/verify_job.rs`
+ *   and `src/backup/verify.rs` at HEAD of the Proxmox git mirrors on 2026-09-13. What WAS measured
+ *   here: `pbs.example.com:8007` and `pbs.mgmt.example.com:8007` both answer HTTP 401 under
+ *   STRICT TLS (curl `ssl_verify_result=0`), so no `-k` is needed and `client.ts`'s plain `fetch`
+ *   reaches PBS unchanged. The running host's own schema was NOT read — no credential — so a PBS
+ *   older than HEAD may differ.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type { PbsTarget } from './credentials.ts';
+import { rechecks, shape } from './pbs-verify-job-form.ts';
+import { type PveRequirements, pveHandlers } from './resource.ts';
+import { bool, int, text } from './values.ts';
+
+export interface PbsVerifyJobProps {
+  /** ⛔ A PBS host, never a PVE cluster. See `PbsTarget`. */
+  target: PbsTarget;
+  /**
+   * ⛔ The primary key, REQUIRED, and never left to PBS. 3–32 chars of
+   * `[A-Za-z0-9_][A-Za-z0-9._-]*`. PBS refuses a duplicate section id outright, which is the loud
+   * failure `Proxmox.BackupJob` had to engineer for itself — but only because the id is sent.
+   */
+  id: string;
+  /** Datastore name, 3–32 safe-id chars. ⚠️ MUTABLE — see the ⚠️ on `matches`. */
+  store: string;
+  /**
+   * ⛔ THE KEY IS REQUIRED AND THE VALUE MAY BE `null`. PBS makes the field optional; this family
+   * refuses to let you OMIT it, which is not the same thing. A verification job with no schedule
+   * never runs on its own and PBS reports it as perfectly healthy — and an absent schedule is also
+   * the only way to turn one off, because there is NO `disable` field on a verification job.
+   * ⛔ THAT LAST CLAIM IS NOW MEASURED, not read from source. `proxmox-backup-manager verify-job
+   *   update --help` on the live 4.2 host lists `--delete
+   *   ignore-verified|comment|schedule|outdated-after|ns|max-depth|read-threads|verify-threads`
+   *   and no `--disable` anywhere. So `schedule` is deletable — "parked" is a state PBS supports —
+   *   and `disable` genuinely does not exist. pbs-verify-job-form.ts said this was read off the
+   *   source and NOT verified against a running host; it is now verified, on this one.
+   * ★ SO `null` MEANS "DELIBERATELY PARKED" AND OMITTING IT IS STILL AN ERROR. The original
+   *   required-string kept you from declaring verification that never happens, which is right, but
+   *   it also made a genuinely parked job UNDECLARABLE — and the estate has one: `v-datacenter` is
+   *   parked because syno1 is powered off, comment and runbook and all. A resource that cannot
+   *   describe what is really there pushes the operator back to the CLI, which is the failure this
+   *   package exists to end. Writing `schedule: null` costs a word and says the quiet part out
+   *   loud; leaving the key out still will not compile.
+   * ⚠️ ADOPTING A SCHEDULELESS JOB WITH A SCHEDULE DECLARED GIVES IT ONE ON THE FIRST DEPLOY, which
+   *   is the intended direction and is still a write nobody asked for in words. `matches` compares
+   *   `schedule`, the live value reads `''`, so the first reconcile PUTs the declared one and
+   *   verification starts running that night. Read the first plan against an adopted job.
+   * ⚠️ A systemd calendar event. Spelled `daily`, `sat 02:00`, `mon..fri 23:00`. A step expression
+   *   is legal too and is not written out here: those two characters would close this comment.
+   */
+  schedule: string | null;
+  /**
+   * The namespace to verify, e.g. `tier1/prod`. Omitted means the datastore root.
+   * ⛔ NEVER SENT AS THE EMPTY STRING. MEASURED in the update handler: `if !ns.is_root()` — a root
+   *   namespace on a PUT is accepted by the schema, reaches the handler and is then SILENTLY
+   *   DISCARDED. A job cannot be moved back to the root namespace by this resource at all; that
+   *   needs `--delete ns` by hand. So an undeclared `ns` is neither sent nor compared.
+   */
+  ns?: string;
+  /**
+   * How many namespace levels below `ns` to descend. `0` is that level only; PBS's maximum is 7.
+   * ⚠️ PBS's own default is FULL recursion (7), not 0. Undeclared means undeclared here: not sent,
+   *   not compared, because "unset" and "7" are stored differently and only one is reachable.
+   */
+  'max-depth'?: number;
+  /**
+   * ⛔ THE HALF OF THE PAIR THAT DECIDES WHETHER THIS JOB EVER RE-CHECKS ANYTHING. Defaults to
+   *   TRUE. Read `rechecks` and the ⛔ in pbs-verify-job-form.ts before setting either of these.
+   */
+  'ignore-verified'?: boolean;
+  /** Days after which a past verification is stale. ⛔ See the pair's ⛔ in the form file. */
+  'outdated-after'?: number;
+  /** ⚠️ PBS TRIMS IT AND STORES AN EMPTY ONE AS ABSENT, so `'  '` reads back as `''`. */
+  comment?: string;
+}
+
+export interface PbsVerifyJobAttributes {
+  id: string;
+  store: string;
+  schedule: string;
+  ns: string;
+  /** ⚠️ `-1` means "no max-depth in the section". `0` is a real setting meaning no recursion. */
+  'max-depth': number;
+  'ignore-verified': boolean;
+  /** ⚠️ `-1` means "unset", which is NOT `0`. See the ⛔ in the form file. */
+  'outdated-after': number;
+  comment: string;
+  /**
+   * ★ WHAT THIS JOB ACTUALLY RE-CHECKS, IN ENGLISH, COMPUTED FROM THE LIVE PAIR. REPORTED, NEVER
+   *   COMPARED — it is derived from two fields `matches` already compares, so diffing it would
+   *   double-count them. It exists because the failure this family guards against is a job that
+   *   looks healthy in every column and verifies each snapshot exactly once, ever; that job reads
+   *   `never` here. A plan line is the only place anyone will see it.
+   */
+  rechecks: string;
+}
+
+export interface PbsVerifyJob extends Resource<
+  'Pbs.VerifyJob',
+  PbsVerifyJobProps,
+  PbsVerifyJobAttributes,
+  never,
+  PveRequirements
+> {}
+
+/**
+ * ⚠️ NO `defaultRemovalPolicy: 'retain'`, DELIBERATELY, AND IT IS THE CLOSER CALL THAN IT LOOKS.
+ *   The section holds no data — deleting it destroys nothing, the way `Proxmox.BackupJob`'s delete
+ *   destroys no archives. What it destroys is the CHECKING, silently and permanently, and PBS will
+ *   not refuse it the way it refuses to remove a datastore in use. `retain` would hide that behind
+ *   a state-row drop instead of showing it as a plan line, and the plan line is the only warning
+ *   anyone gets. Pipe `RemovalPolicy.retain()` per declaration where the job must outlive the code.
+ */
+export const PbsVerifyJob = Resource<PbsVerifyJob>('Pbs.VerifyJob');
+
+/**
+ * ⚠️ EVERY FIELD IS READ THROUGH `values.ts` THOUGH PBS RETURNS REAL JSON TYPES. Unlike PVE's
+ *   SectionConfig round-trip, `GET /config/verify/{id}` serialises a Rust struct, so
+ *   `ignore-verified` arrives as a JSON boolean and `max-depth` as a JSON number. `bool` and `int`
+ *   accept both spellings, and using them costs nothing while covering the version that does not.
+ * ⚠️ `digest` IS NOT AN ATTRIBUTE AND CANNOT BECOME ONE BY ACCIDENT. PBS puts it on the rpcenv, and
+ *   the JSON formatter adds rpcenv attributes as SIBLINGS of `data` — `{"data":{…},"digest":"…"}` —
+ *   so `client.ts`, which returns `body.data`, never sees it. That is lucky rather than designed:
+ *   the digest covers verification.cfg as a FILE, so keeping it would churn this resource's state
+ *   whenever an unrelated verify job was edited.
+ */
+const handlers = pveHandlers<PbsVerifyJobProps, PbsVerifyJobAttributes>({
+  attributes: (live, props) => {
+    const ignoreVerified = bool(live['ignore-verified'], true);
+    const outdatedAfter = int(live['outdated-after'], -1);
+    return {
+      comment: text(live['comment'], ''),
+      id: props.id,
+      'ignore-verified': ignoreVerified,
+      'max-depth': int(live['max-depth'], -1),
+      ns: text(live['ns'], ''),
+      'outdated-after': outdatedAfter,
+      rechecks: rechecks(ignoreVerified, outdatedAfter),
+      schedule: text(live['schedule'], ''),
+      store: text(live['store'], props.store),
+    };
+  },
+  /**
+   * 🔴 THIS WAS `config/verification` AND PBS ANSWERS 404 FOR IT. MEASURED on the live 4.2 server:
+   *   `GET /api2/json/config/verification` -> 404 "Path not found"; `GET /api2/json/config/verify`
+   *   -> 200 with both jobs. The struct is `VerificationJobConfig` and the CLI subcommand is
+   *   `verify-job`, so the long spelling reads right and is simply not the route.
+   *   ⛔ THE FAILURE MODE IS THE ONE THIS PACKAGE KEEPS FINDING: `read` folds every failure into
+   *   `undefined`, so a 404 from a WRONG PATH is indistinguishable from an object that is not
+   *   there. The first plan against the live estate said `create` for two verification jobs that
+   *   have existed for weeks — and a create would then have POSTed to a 404 as well, so it fails
+   *   loudly rather than duplicating anything. Nothing caught it earlier because no verification
+   *   job had ever been declared; registering the provider exercises no path at all.
+   */
+  collection: () => 'config/verify',
+  /** ⛔ `id` IS SENT. PBS refuses a duplicate id, and that refusal is this family's safety net. */
+  createForm: (props) => ({ ...shape(props), id: props.id }),
+  /**
+   * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED — the `Proxmox.BackupJob` trade, for the
+   *   same reason and with one extra: this form carries NO `delete` list, so there is nothing it
+   *   could clear even if it wanted to. See the ⛔ on `withClears` in pbs-verify-job-form.ts.
+   * ⚠️ `store` IS COMPARED AND IS MUTABLE, which is unusual and worth reading twice. PBS's update
+   *   handler assigns it and re-checks privileges on both the old and the new path, so changing
+   *   `store` MOVES the job — and the datastore it left is then verified by nothing. That is a
+   *   one-word edit with the same effect as deleting the job, and it plans as a quiet `update`.
+   * ⚠️ `rechecks` IS ABSENT HERE ON PURPOSE. It is a rendering of the two fields on the lines
+   *   above; comparing it too would report the same drift twice.
+   */
+  matches: (attributes, props) =>
+    attributes.store === props.store &&
+    // ⚠️ `null` IS COMPARED AGAINST `''`, NOT SKIPPED. A parked job is a declaration like any
+    //   other, so declaring `null` against a job that HAS a schedule must plan an update — the
+    //   form then omits `schedule`, which is a set-only form, so see the ⛔ on clearing below.
+    attributes.schedule === (props.schedule ?? '') &&
+    attributes['ignore-verified'] === (props['ignore-verified'] !== false) &&
+    (props['outdated-after'] === undefined ||
+      attributes['outdated-after'] === props['outdated-after']) &&
+    (props['max-depth'] === undefined || attributes['max-depth'] === props['max-depth']) &&
+    (props.ns === undefined || attributes.ns === props.ns) &&
+    (props.comment === undefined || attributes.comment === props.comment),
+  path: (props) => `config/verify/${props.id}`,
+  updateForm: shape,
+});
+
+/**
+ * ⛔ `list` IS EMPTY, INHERITED FROM `pveHandlers`, AND THE REASON IS SHARPER HERE THAN ELSEWHERE.
+ *   `GET /config/verify` returns every verification job the caller can see, including the
+ *   ones the PBS installer and a human made. Adopting those would put Alchemy one dropped line
+ *   away from DELETING a datastore's only verification schedule — and deleting it destroys nothing
+ *   visible, so the loss is discovered the day a restore fails and there is no verification history
+ *   to say when the rot started. Adoption stays explicit: declare the existing id.
+ *
+ * ⚠️ NO `digest` IS SENT ON UPDATE OR DELETE, SO THIS IS LAST-WRITER-WINS. PBS accepts an optional
+ *   `digest` on both and would refuse a write made against a stale read. Sending one would need a
+ *   read-then-write window this provider does not have — `pveOperations` reads and writes in two
+ *   separate calls with two separate mints — so a concurrent edit from the PBS UI is overwritten
+ *   rather than refused. Same behaviour as every PVE family here; stated because PBS offers better.
+ */
+export const PbsVerifyJobProvider = () =>
+  Provider.effect(PbsVerifyJob, Effect.succeed(PbsVerifyJob.Provider.of(handlers)));

package/src/proxmox/pool.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Pool family — compile-time and runtime checks against generated `/pools` schema types.
+ *
+ * ⚠️ THE DRIFT TEST IS THE POINT: if codegen renames a parameter or marks `poolid` optional on
+ *   POST, this file fails `tsc` before anything reaches a cluster.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import type { PoolsPoolidPutParams, PoolsPostParams } from './generated/pve.ts';
+import { type PoolProps, poolCreateForm, poolUpdateForm } from './pool.ts';
+
+const target: PoolProps['target'] = {
+  members: ['example.test'],
+  mount: 'proxmox-test',
+  scheme: 'pve',
+};
+
+const props = (over: Partial<PoolProps> = {}): PoolProps => ({
+  target,
+  poolid: 'house',
+  ...over,
+});
+
+describe('pool forms match generated POST/PUT parameters', () => {
+  it('createForm sends exactly poolid and comment', () => {
+    const form: PoolsPostParams = poolCreateForm(props({ comment: 'estate' }));
+    assert.deepEqual(form, { poolid: 'house', comment: 'estate' });
+    assert.deepEqual(Object.keys(form).sort(), ['comment', 'poolid']);
+  });
+
+  it('updateForm sends only comment on the deprecated item path', () => {
+    const form: Pick<PoolsPoolidPutParams, 'comment'> = poolUpdateForm(props());
+    assert.deepEqual(form, { comment: '' });
+    assert.deepEqual(Object.keys(form), ['comment']);
+  });
+
+  it('would fail tsc if poolid were dropped from createForm', () => {
+    // @ts-expect-error poolid is required on POST /pools
+    const bad: PoolsPostParams = { comment: '' };
+    assert.equal('poolid' in bad, false);
+  });
+});

package/src/proxmox/pool.ts

@@ -0,0 +1,80 @@
+/**
+ * `Proxmox.Pool` — a PVE resource pool. Guests grouped for permissions and quota.
+ *
+ * ★ PROVEN END TO END AGAINST THE LIVE CLUSTER, 2026-09-13. create -> verified with `pvesh get
+ *   /pools` on the node rather than by believing Alchemy; second plan -> `no changes / noop`; then
+ *   the comment was edited ON THE CLUSTER and plan said `1 to update`, and a deploy repaired it.
+ *   That drift case is the one that matters: `diff` reads the LIVE pool, so a provider trusting
+ *   its own state would have reported noop straight past a hand-edit in the UI.
+ *
+ * ⚠️ IT 403'd UNTIL THE ROLE WAS WIDENED, AND THE HISTORY IS WORTH KEEPING. `hf-provision@pve`
+ *   held `LXCProvisioner` on `/` with no `Pool.Allocate`, so reconcile answered
+ *   "Permission check failed (/pool/house, Pool.Allocate)". The credential could not widen itself
+ *   — `PUT /access/roles` is 403 for it too — so the role was extended over SSH with
+ *   `pveum role modify LXCProvisioner --privs "<existing>,Pool.Allocate,Pool.Audit"`, preserving
+ *   every existing privilege. Each new resource in this package should state the privileges its
+ *   reconcile needs, so widening stays a deliberate act rather than a reaction to a 403.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import type {
+  PoolsPoolidGetReturn,
+  PoolsPoolidPutParams,
+  PoolsPostParams,
+} from './generated/pve.ts';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+
+export interface PoolProps extends WithTarget {
+  /** PVE's primary key for a pool. Changing it is a replace, not an update. */
+  poolid: string;
+  /** Free text shown in the UI — the only mutable field a pool has. */
+  comment?: string;
+}
+
+export interface PoolAttributes {
+  poolid: string;
+  comment: string;
+  /** Guests currently in the pool, so a plan can say what a delete would refuse to orphan. */
+  members: number;
+}
+
+export interface ProxmoxPool extends Resource<
+  'Proxmox.Pool',
+  PoolProps,
+  PoolAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxPool = Resource<ProxmoxPool>('Proxmox.Pool');
+
+/** Form bodies this family sends — exported for the drift test in pool.test.ts. */
+export const poolCreateForm = (props: PoolProps): PoolsPostParams => ({
+  comment: props.comment ?? '',
+  poolid: props.poolid,
+});
+
+/** PUT body — only `comment`; path carries `poolid`. Matches deprecated `/pools/{poolid}`. */
+export const poolUpdateForm = (props: PoolProps): Pick<PoolsPoolidPutParams, 'comment'> => ({
+  comment: props.comment ?? '',
+});
+
+const handlers = pveHandlers<PoolProps, PoolAttributes>({
+  attributes: (live, props) => {
+    const row = live as PoolsPoolidGetReturn;
+    return {
+      comment: typeof row.comment === 'string' ? row.comment : '',
+      members: Array.isArray(row.members) ? row.members.length : 0,
+      poolid: props.poolid,
+    };
+  },
+  collection: () => 'pools',
+  createForm: poolCreateForm,
+  matches: (attributes, props) => attributes.comment === (props.comment ?? ''),
+  path: (props) => `pools/${props.poolid}`,
+  updateForm: poolUpdateForm,
+});
+
+export const ProxmoxPoolProvider = () =>
+  Provider.effect(ProxmoxPool, Effect.succeed(ProxmoxPool.Provider.of(handlers)));

package/src/proxmox/qemu.ts

@@ -0,0 +1,89 @@
+/**
+ * `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.
+ *
+ * ⛔ `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
+ *   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.
+ */
+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';
+
+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;
+}
+
+export interface VmAttributes {
+  vmid: number;
+  node: string;
+  name: string;
+  memory: number;
+  cores: number;
+  sockets: number;
+  onboot: boolean;
+}
+
+export interface ProxmoxVm extends Resource<
+  'Proxmox.Vm',
+  VmProps,
+  VmAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxVm = Resource<ProxmoxVm>('Proxmox.Vm');
+
+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: (props) => ({ ...shape(props), vmid: String(props.vmid) }),
+  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 const ProxmoxVmProvider = () =>
+  Provider.effect(ProxmoxVm, Effect.succeed(ProxmoxVm.Provider.of(handlers)));

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

@@ -0,0 +1,89 @@
+/**
+ * A replication job's props, as the id and the forms PVE wants.
+ *
+ * ★ SPLIT OUT OF replication-job.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, on the same seam
+ *   metric-server-form.ts uses and for the same reason: this file answers "how does a declaration
+ *   become a PVE write", and replication-job.ts answers "what is a replication job and when has it
+ *   changed". Nothing here reads the cluster and nothing here decides a diff.
+ *
+ * ⚠️ THE `import type` BACK TO replication-job.ts IS A CYCLE ON PAPER ONLY. It is type-only, so it
+ *   is erased before anything runs, and `ReplicationJobProps` stays the resource's public shape in
+ *   the file that declares the resource rather than being moved somewhere odd to dodge the arrow.
+ */
+import type { ReplicationJobProps } from './replication-job.ts';
+
+/**
+ * PVE's own documented default for `schedule`, applied on BOTH sides of the comparison.
+ *
+ * ⚠️ IT LIVES HERE BECAUSE BOTH HALVES NEED THE SAME STRING. `shape` sends it and `attributes`
+ *   falls back to it; two copies of that literal in two files is exactly the drift that makes a
+ *   plan report an update over a value nobody set.
+ * ⚠️ AND IT IS NEVER SPELLED OUT IN A COMMENT, because the string PVE chose ENDS A BLOCK COMMENT:
+ *   the two characters before the `15` are the comment terminator, and tsc says so loudly. It is
+ *   referred to by name everywhere else in these two files for that reason, not for style.
+ */
+export const DEFAULT_SCHEDULE = '*/15';
+
+/**
+ * `{guest, jobnum}` -> `100-0`, the id in the only spelling PVE ever answers with.
+ *
+ * ⚠️ NUMBERS IN, SO CANONICAL OUT. PVE runs both halves of a job id through `int()` on parse — see
+ *   the ⛔ in replication-job.ts — and a JavaScript number has no leading-zero spelling to lose.
+ *   That is the whole reason this resource is keyed on two numbers instead of one string.
+ */
+export const jobId = (props: ReplicationJobProps) =>
+  `${String(props.guest)}-${String(props.jobnum)}`;
+
+/**
+ * The mutable half, shared by create and update.
+ *
+ * ⚠️ `schedule`, `disable` AND `comment` ARE ALWAYS SENT, EVEN AT THEIR DEFAULTS, because they are
+ *   always compared — and a field compared against a default but not SENT as that default is an
+ *   update reported on every plan that the PUT never performs (backup-job.ts records the same
+ *   trade). The empty string is how PVE is told to clear a comment. `rate` is the opposite case:
+ *   not declared, not sent, not compared, so a rate limit set by hand survives adoption untouched.
+ * ⛔ `source` IS NEVER SENT, AND SENDING IT WOULD BE WORSE THAN REDUNDANT. MEASURED in
+ *   API2/ReplicationConfig.pm: create does `$param->{source} //= $guest_info->{node}` — PVE fills
+ *   it from wherever the guest actually is — and DIES with "Source '<x>' does not match current
+ *   node of guest" when a declaration disagrees. There is no correct value to hold here.
+ */
+const shape = (props: ReplicationJobProps) => ({
+  comment: props.comment ?? '',
+  disable: props.disable === true ? '1' : '0',
+  schedule: props.schedule ?? DEFAULT_SCHEDULE,
+  ...(props.rate === undefined ? {} : { rate: String(props.rate) }),
+});
+
+/**
+ * ⚠️ `type` IS A CONSTANT RATHER THAN A PROP: `local` is the only section type PVE registers, and
+ *   an enum of one value is a prop that can only ever be wrong. `id` and `target` are both required
+ *   by the create schema and neither belongs in `shape` — `target` because PUT will not take it.
+ * ⛔ THIS LINE IS THE ONLY PLACE PVE'S KEY `target` IS SPELLED, and the value beside it comes from
+ *   `targetNode`. The two words are different objects — a node name here, the whole cluster in
+ *   `WithTarget.target` — and the ⛔ in replication-job.ts explains why the rename was forced.
+ */
+export const createBody = (props: ReplicationJobProps) => ({
+  ...shape(props),
+  id: jobId(props),
+  target: props.targetNode,
+  type: 'local',
+});
+
+/**
+ * ⛔ `delete=remove_job` ON EVERY UPDATE IS THE DELIBERATE PART. PVE's PUT merges the form into the
+ *   section and cannot unset anything, so without this the removal marker a DELETE wrote would
+ *   survive every reconcile and `matches` would report an update that never lands. MEASURED as
+ *   legal: the update handler refuses `delete` only for required or `fixed` options, and
+ *   `remove_job => { optional => 1 }` is neither; deleting a key that is not set is a no-op, so
+ *   this is safe to send unconditionally.
+ * ⛔ AND THE DELETE LIST IS THIS ONE CONSTANT KEY, NEVER A COMPUTED "everything you did not
+ *   declare". backup-job.ts spells out why the computed form is dangerous — it strips settings the
+ *   resource does not even model off a job adopted from the UI. `remove_job` cannot be declared
+ *   here at all, so clearing it can only ever undo a removal this stack did not ask for.
+ *   ⚠️ IT CANCELS A REMOVAL SOMEBODY STARTED, WHICH IS THE POINT AND IS STILL WORTH KNOWING. If the
+ *     removal pass already ran its local-snapshot half, the revived job re-sends in full.
+ */
+export const updateBody = (props: ReplicationJobProps) => ({
+  ...shape(props),
+  delete: 'remove_job',
+});