@homeflare/alchemy 0.37.2 → 0.37.4

package/src/litellm/fake-stack.ts

@@ -19,7 +19,7 @@ import { provideFreshArtifactStore } from 'alchemy/Artifacts';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
-import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
+import { litellmProviders } from './providers.ts';
 
 /** The planned action for each resource, deletions included, keyed by FQN. */
 export type Planned = Readonly<Record<string, string>>;
@@ -51,13 +51,13 @@ const actionsOf = (plan: PlanView): Planned => {
 };
 
 /**
- * ⚠️ CREDENTIALS/HTTPCLIENT ARE PROVIDED AROUND `deploy`, NOT BAKED INTO THE PROVIDER LAYER.
- *   `Provider.effect`'s own construction effect is `Effect.succeed(...)` (pass-through-endpoint.ts)
- *   — it never actually reads `Credentials`/`HttpClient`; only the HANDLERS it returns do, and
- *   those run later, whenever `Apply.ts` calls `provider.reconcile`/`read`/`delete`. Effect
- *   resolves a `yield*`'s service from whatever ambient context wraps the CALL SITE, so the layers
- *   those handlers need must wrap the whole plan+apply pipeline below, exactly where openbao's
- *   fake-stack.ts wraps `BaoEnv` around its own `deploy`.
+ * ⚠️ CREDENTIALS COME FROM `litellmProviders`, NOT AN OUTER `Effect.provide`. The handlers read
+ *   `Credentials` when Apply calls them, not when the provider value is built. `provideMerge`
+ *   keeps that service in the layer output, so it is in `compiled.services` — the context this
+ *   harness gives Apply. An outer `Effect.provide(credentials)` would hide a sealed `Layer.provide`:
+ *   the handlers would still see the key, and this harness would not catch the regression.
+ * ⚠️ `HttpClient` STAYS AMBIENT, wrapped around the pipeline below. `litellmProviders` does not
+ *   bundle one; Alchemy's runtime provides it the same way. Do not add a second client here.
  * ★ `fetchFn` IS `startFakeLitellm(...).fetch` (fake-litellm.ts) — this harness never opens a real
  *   socket; `FetchHttpClient.Fetch` is the seam the SDK's protocol layer calls through, same as
  *   `../netbox/fake-netbox.ts`'s `fakeNetboxLayer`.
@@ -68,7 +68,11 @@ export const fakeStack = (
   name = 'PassThroughStack',
 ): FakeStack => {
   const state = Alchemy.inMemoryState();
-  const providers = LiteLLMPassThroughEndpointProvider();
+  const providers = litellmProviders(credentials(creds));
+  // ⚠️ THE CAST STAYS. `StackBody` is `Effect<unknown, unknown, unknown>` so a test can pass any
+  //   declaration, and that channel is not a legal `Alchemy.Stack` body. The uncast construction
+  //   is pass-through-stack.test.ts. This cast used to also hide `Credentials` leaking out of the
+  //   resource type; that leak is gone, and this harness still has to deploy.
   const stack = Alchemy.Stack as unknown as (
     stackName: string,
     options: { providers: typeof providers; state: typeof state },
@@ -90,7 +94,6 @@ export const fakeStack = (
     }).pipe(
       options.adopt === undefined ? (e) => e : Effect.provideService(AdoptPolicy, options.adopt),
       Effect.provideService(Alchemy.Stage, 'test'),
-      Effect.provide(credentials(creds)),
       Effect.provide(FetchHttpClient.layer),
       Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
       Effect.scoped,

package/src/litellm/pass-through-endpoint.ts

@@ -20,6 +20,10 @@
  * ⛔ NO CREDENTIAL IS A PROP (S25). `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` are read at call
  *   time by `@distilled.cloud/litellm`'s own `CredentialsFromEnv` (providers.ts) — the same two
  *   variable names the retired hand-rolled `credentials.ts` read.
+ * ⛔ CREDENTIALS ARE NOT A RESOURCE REQUIREMENT. `LitellmOpContext` (`Credentials | HttpClient`)
+ *   belongs to the handlers at Apply, on `litellmProviders`'s layer. The 5th `Resource` parameter
+ *   used to be `LitellmRequirements | Stack | Stage`, so a stack body required `Credentials`, and
+ *   `Alchemy.Stack` rejects that (`"LitellmCredentials"` is not `"Stack"`). Measured 2026-09-24.
  */
 import { Resource } from 'alchemy';
 import { Unowned } from 'alchemy/AdoptPolicy';
@@ -27,13 +31,10 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import { createPhysicalName } from 'alchemy/PhysicalName';
 import * as Provider from 'alchemy/Provider';
-import type { Stack } from 'alchemy/Stack';
-import type { Stage } from 'alchemy/Stage';
 import type * as misc from '@distilled.cloud/litellm/misc';
 import * as Effect from 'effect/Effect';
 import * as Predicate from 'effect/Predicate';
 import {
-  type LitellmRequirements,
   createPassThroughEndpoint,
   deletePassThroughEndpoint,
   listPassThroughEndpoints,
@@ -65,9 +66,7 @@ export {
 export interface LiteLLMPassThroughEndpoint extends Resource<
   'LiteLLM.PassThroughEndpoint',
   PassThroughEndpointProps,
-  PassThroughEndpointAttributes,
-  never,
-  LitellmRequirements | Stack | Stage
+  PassThroughEndpointAttributes
 > {}
 
 export const LiteLLMPassThroughEndpoint = Resource<LiteLLMPassThroughEndpoint>(

package/src/litellm/pass-through-stack.test.ts

@@ -0,0 +1,54 @@
+/**
+ * A real `Alchemy.Stack` whose body `yield*`s `LiteLLM.PassThroughEndpoint`, with
+ * `litellmProviders` as the providers layer.
+ *
+ * ⛔ THE TYPE IS THE BUG. The resource used to put `LitellmRequirements`
+ *   (`Credentials | HttpClient`) on its 5th type parameter, so this construction failed
+ *   TS2345: `Credentials` is not `ProviderServices | StackServices`
+ *   (`"LitellmCredentials"` is not `"Stack"`). No cast. `tsc` fails again if that leak
+ *   returns. The stack value is not run — `Alchemy.Stack` returns a lazy effect
+ *   (github/repo-policy-stack.test.ts measured the same).
+ *
+ * ★ THE DEPLOY IS THE OTHER HALF. `fakeStack` runs Alchemy's own Plan and Apply over the
+ *   fake proxy, and its providers layer is `litellmProviders` (`fake-stack.ts`). A sealed
+ *   `Layer.provide` builds the provider and then hides `Credentials`, so `reconcile` dies
+ *   with Service not found before any request. A live row means the handler ran with the
+ *   key present.
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Alchemy from 'alchemy';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, startFakeLitellm } from './fake-litellm.ts';
+import { fakeStack } from './fake-stack.ts';
+import { LiteLLMPassThroughEndpoint } from './pass-through-endpoint.ts';
+import { litellmProviders } from './providers.ts';
+
+const MASTER_KEY = 'sk-test-master';
+const props = { path: '/bria', target: 'https://api.bria.ai' };
+
+test('an Alchemy.Stack body can yield LiteLLMPassThroughEndpoint, and apply reaches the proxy', async () => {
+  const stack = Alchemy.Stack(
+    'litellm-passthrough',
+    {
+      providers: litellmProviders(credentials({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE })),
+      state: Alchemy.inMemoryState(),
+    },
+    Effect.gen(function* () {
+      return yield* LiteLLMPassThroughEndpoint('Endpoint', props);
+    }),
+  );
+  // Not run — see the file header. `tsc` is the assertion on this value.
+  expect(stack).toBeDefined();
+
+  const fake = startFakeLitellm({ masterKey: MASTER_KEY });
+  const planned = await fakeStack({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE }, fake.fetch).deploy(
+    Effect.gen(function* () {
+      yield* LiteLLMPassThroughEndpoint('Endpoint', props);
+    }),
+  );
+
+  expect(planned).toEqual({ Endpoint: 'create' });
+  expect(fake.rows().some((row) => row.path === '/bria')).toBe(true);
+  expect(fake.requests().some((call) => call.method === 'POST')).toBe(true);
+});

package/src/litellm/providers.ts

@@ -10,11 +10,17 @@
  *   source them another way.
  * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime the same way it is
  *   for `netboxProviders`-style families in this kit; a stack that already deploys anything over
- *   HTTP already has one.
+ *   HTTP already has one. Do not add a second client to this layer.
+ * ⚠️ `Layer.provideMerge`, NEVER PLAIN `Layer.provide`, for the credentials layer. The handlers
+ *   still need `Credentials` when the engine calls `read`/`diff`/`reconcile`. `Provider.effect`
+ *   puts that need on the layer. Plain `provide` satisfies it only while the `Provider` value is
+ *   built, then hides `Credentials` from those later calls. Measured on Caddy, 2026-09-23:
+ *   `caddy/providers.ts`. `provideMerge` feeds credentials in and keeps them in the layer the
+ *   engine runs the handlers with.
  */
 import { type Credentials, CredentialsFromEnv } from '@distilled.cloud/litellm/Credentials';
 import * as Layer from 'effect/Layer';
 import { LiteLLMPassThroughEndpointProvider } from './pass-through-endpoint.ts';
 
 export const litellmProviders = (creds: Layer.Layer<Credentials> = CredentialsFromEnv) =>
-  LiteLLMPassThroughEndpointProvider().pipe(Layer.provide(creds));
+  LiteLLMPassThroughEndpointProvider().pipe(Layer.provideMerge(creds));

package/src/proxmox/adopt-noop.test.ts

@@ -2,10 +2,9 @@
  * Adopting an object that already matches must be read-only — measured per reconcile SHAPE, through
  * Alchemy's own Plan and Apply over a fake cluster (fake-pve.ts, ../verify/fake-engine.ts).
  *
- * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Every family built on
- *   `pveHandlers` shares resource.ts's reconcile, so `Proxmox.Pool` stands for all of them; `Acl`
- *   wraps that reconcile; `PbsDatastore` and `SdnApply` write their own. CephPool, the one that got
- *   it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
+ * ★ ONE ROW PER WAY A FAMILY REACHES ITS WRITE, not one per family. Pool now has its own distilled
+ *   lifecycle; `Acl` wraps resource.ts's shared reconcile; `PbsDatastore` and `SdnApply` write their
+ *   own. CephPool, the one that got it wrong, has its own file. docs/adopt-verify.md carries the full per-family table.
  * ⚠️ A FIXTURE THAT DOES NOT MATCH TURNS A ROW INTO A DRIFT TEST, and the assertion on the
  *   verifier's `noop` is what catches that: a wrong fixture fails loudly instead of passing for
  *   the wrong reason. The Pool drift row proves the harness can see a write at all.
@@ -36,7 +35,7 @@ const cases: readonly Case[] = [
   {
     declare: () => ProxmoxPool('lab', { comment: 'x', poolid: 'lab', target: FAKE_TARGET }),
     live: { 'pools/lab': { comment: 'x', members: [] } },
-    name: 'Proxmox.Pool (pveHandlers: every factory family)',
+    name: 'Proxmox.Pool (direct distilled lifecycle)',
     provider: ProxmoxPoolProvider as never,
   },
   {

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

@@ -0,0 +1,95 @@
+/** Pure existing forms, normalization and equality, shared by plan and SDK lifecycle. */
+import type { BackupJobAttributes, BackupJobProps } from './backup-job.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { bool, guestList, propertyString, text } from './values.ts';
+
+/**
+ * The form for both create and update.
+ *
+ * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT, AND THAT IS LOAD BEARING. PVE's PUT can only
+ *   SET a key; clearing one needs `delete=<key>`, which this resource deliberately never sends.
+ *   `updateForm` is handed the props and nothing else, so a `delete` list could only be "every
+ *   field you did not declare" — and on a job adopted out of the UI that would silently strip
+ *   settings this resource does not even model, `compress`, `mailto` and `bwlimit` among them, on
+ *   the first deploy. Leaving undeclared fields alone is the smaller lie, and `matches` tells the
+ *   same lie consistently: it does not compare what it cannot change.
+ *
+ * ⚠️ THE FIVE FIELDS PVE DOCUMENTS A DEFAULT FOR ARE ALWAYS SENT AND ALWAYS COMPARED — `enabled`
+ *   (1), `all` (0), `mode` (snapshot), `notification-mode` (auto), `repeat-missed` (0). That is
+ *   what makes a hand-flipped `enabled 0` show up as drift rather than as silence, and it is also
+ *   what stops those five looping: a field compared against a default must be sent as that
+ *   default, or every plan reports an update the PUT never performs. The cost is worth reading
+ *   before the first deploy against an adopted job — an omitted `all` is a declaration that this
+ *   job backs up NOTHING, and PVE accepts a job that selects nothing without a word. Read that
+ *   first plan; do not deploy it unseen.
+ */
+const shape = (props: BackupJobProps) => ({
+  all: props.all === true ? '1' : '0',
+  enabled: props.enabled === false ? '0' : '1',
+  mode: props.mode ?? 'snapshot',
+  'notification-mode': props['notification-mode'] ?? 'auto',
+  'repeat-missed': props['repeat-missed'] === true ? '1' : '0',
+  schedule: props.schedule,
+  ...(props.comment === undefined ? {} : { comment: props.comment }),
+  ...(props.exclude === undefined ? {} : { exclude: guestList(props.exclude) }),
+  ...(props.fleecing === undefined ? {} : { fleecing: props.fleecing }),
+  ...(props['notes-template'] === undefined ? {} : { 'notes-template': props['notes-template'] }),
+  ...(props.pool === undefined ? {} : { pool: props.pool }),
+  ...(props['prune-backups'] === undefined ? {} : { 'prune-backups': props['prune-backups'] }),
+  ...(props.storage === undefined ? {} : { storage: props.storage }),
+  ...(props.vmid === undefined ? {} : { vmid: guestList(props.vmid) }),
+});
+
+export const backupJobSpec = {
+  /**
+   * ⛔ NO "IS IT REALLY THERE" GUARD, ON PURPOSE. Returning undefined for a job whose JSON is
+   *   missing some key would be a guess about which keys PVE echoes back, and a wrong guess here
+   *   does not read as absent-and-harmless: `reconcile` would POST, and POST creates ANOTHER job.
+   *   Absence is decided by the API declining to answer, which `pveOperations.read` already
+   *   handles — not by a key being missing from an answer that did arrive.
+   */
+  attributes: (live, props) => ({
+    all: bool(live['all'], false),
+    comment: text(live['comment'], ''),
+    enabled: bool(live['enabled'], true),
+    exclude: guestList(live['exclude']),
+    fleecing: propertyString(live['fleecing'], 'enabled'),
+    id: props.id,
+    mode: text(live['mode'], 'snapshot'),
+    'next-run': typeof live['next-run'] === 'number' ? live['next-run'] : 0,
+    'notes-template': text(live['notes-template'], ''),
+    'notification-mode': text(live['notification-mode'], 'auto'),
+    pool: text(live['pool'], ''),
+    'prune-backups': propertyString(live['prune-backups']),
+    'repeat-missed': bool(live['repeat-missed'], false),
+    schedule: text(live['schedule'], ''),
+    storage: text(live['storage'], ''),
+    vmid: guestList(live['vmid']),
+  }),
+  collection: () => 'cluster/backup',
+  /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
+  createForm: (props) => ({ ...shape(props), id: props.id }),
+  /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
+  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
+  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
+  matches: (attributes, props) =>
+    attributes.schedule === props.schedule &&
+    attributes.enabled === (props.enabled !== false) &&
+    attributes.all === (props.all === true) &&
+    attributes.mode === (props.mode ?? 'snapshot') &&
+    attributes['notification-mode'] === (props['notification-mode'] ?? 'auto') &&
+    attributes['repeat-missed'] === (props['repeat-missed'] === true) &&
+    (props.storage === undefined || attributes.storage === props.storage) &&
+    (props.pool === undefined || attributes.pool === props.pool) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.vmid === undefined || attributes.vmid === guestList(props.vmid)) &&
+    (props.exclude === undefined || attributes.exclude === guestList(props.exclude)) &&
+    (props['notes-template'] === undefined ||
+      attributes['notes-template'] === props['notes-template']) &&
+    (props['prune-backups'] === undefined ||
+      attributes['prune-backups'] === propertyString(props['prune-backups'])) &&
+    (props.fleecing === undefined ||
+      attributes.fleecing === propertyString(props.fleecing, 'enabled')),
+  path: (props) => `cluster/backup/${props.id}`,
+  updateForm: shape,
+} satisfies PveSpec<BackupJobProps, BackupJobAttributes>;

package/src/proxmox/backup-job-distilled.ts

@@ -0,0 +1,86 @@
+/** Backup-job operations from distilled-proxmox, walked against pve-manager 9.2.11. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import { backupJobSpec } from './backup-job-config.ts';
+import type { BackupJobProps } from './backup-job.ts';
+import { runPve } from './distilled-pve.ts';
+
+/** SDK member names differ from the vendor's hyphenated form keys; omission stays omission. */
+export const backupJobRequest = (
+  props: BackupJobProps,
+  form = backupJobSpec.updateForm(props),
+): cluster.PutClusterBackupRequest => {
+  const {
+    'notes-template': notes_template,
+    'notification-mode': notification_mode,
+    'prune-backups': prune_backups,
+    'repeat-missed': repeat_missed,
+    ...fields
+  } = form;
+  return {
+    ...fields,
+    id: props.id,
+    notification_mode,
+    repeat_missed,
+    ...(notes_template === undefined ? {} : { notes_template }),
+    ...(prune_backups === undefined ? {} : { prune_backups }),
+  };
+};
+
+/**
+ * SDK decode also renames NESTED retention keys. Restore the vendor's property-string
+ * spelling before the existing canonical comparison, or keep_daily becomes perpetual drift.
+ * A property string from an older server remains a property string.
+ */
+export const readBackupJob = (props: BackupJobProps) =>
+  runPve(props.target, 'read', false, cluster.getClusterBackup({ id: props.id })).pipe(
+    // Legacy PVE emits these two properties as strings; current PVE expands objects.
+    // Validate the generated response's remaining fields without narrowing that compatibility.
+    Effect.flatMap((live) =>
+      Schema.decodeUnknownEffect(Schema.toType(cluster.GetClusterBackupResponse))({
+        ...live,
+        prune_backups: undefined,
+        fleecing: undefined,
+      }).pipe(
+        Effect.mapError(
+          () =>
+            new ProxmoxParseError({
+              body: undefined,
+              cause: 'Backup job response does not match its vendor schema',
+            }),
+        ),
+        Effect.as(live),
+      ),
+    ),
+    Effect.map((live) =>
+      backupJobSpec.attributes(
+        {
+          ...live,
+          'next-run': live.next_run,
+          'notes-template': live.notes_template,
+          'notification-mode': live.notification_mode,
+          'prune-backups':
+            typeof live.prune_backups === 'object' && live.prune_backups !== null
+              ? Object.fromEntries(
+                  Object.entries(live.prune_backups).map(([key, value]) => [
+                    key.replaceAll('_', '-'),
+                    value,
+                  ]),
+                )
+              : live.prune_backups,
+          'repeat-missed': live.repeat_missed,
+        },
+        props,
+      ),
+    ),
+    Effect.catchTag('BackupJobNotFound', () => Effect.succeed(undefined)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const deleteBackupJob = (props: BackupJobProps) =>
+  runPve(props.target, 'provision', true, cluster.deleteClusterBackup({ id: props.id })).pipe(
+    Effect.catchTag('BackupJobNotFound', () => Effect.void),
+    Effect.catchTag('NotFound', () => Effect.void),
+  );

package/src/proxmox/backup-job.ts

@@ -13,14 +13,13 @@
  *   COULD CARRY. PVE's own API schema says so in one parenthesis — `id`: "Job ID (will be
  *   autogenerated)." — and a generated id looks like `backup-f56d8ab7-d524`. A resource that
  *   POSTed without an id would create a SECOND job beside the first on EVERY reconcile, and the
- *   read-back in `pveOperations` would still pass, because a job did appear: that check asks "is
- *   the object there", not "is it the one I meant". So `id` is a REQUIRED prop and is always sent
+ *   read-back could still pass, because a job did appear: that check asks "is the object there",
+ *   not "is it the one I meant". So `id` is a REQUIRED prop and is always sent
  *   on create. To adopt a job that already exists, declare its existing id; any other id is a new
  *   job beside it, not an adoption.
- *   ★ AN EXPLICIT id ALSO CLOSES A SECOND HOLE. `pveOperations.read` turns ANY failed GET into
- *     "absent" — an expired lease, a 403, a node that did not answer — and reconcile then POSTs.
- *     With an id, PVE refuses a duplicate section id and the deploy fails loudly; without one, that
- *     same swallowed error would have quietly doubled the cluster's backup jobs.
+ *   ★ FAILED READS NOW PROPAGATE THROUGH DISTILLED. Only a typed missing-job response means
+ *     absent. An expired lease, a 403 or an unrelated server error stops reconciliation before
+ *     any POST. The explicit id remains a second defense against accidentally duplicating jobs.
  *
  * ⚠️ `Sys.Modify` ON `/` IS THE GATE AND IT IS NOT A SMALL GRANT. PVE has no Backup.* privilege:
  *   create, update and delete of a vzdump job are all checked against `Sys.Modify` at `/` — the
@@ -30,17 +29,21 @@
  *   reaction to a 403.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import { runPve } from './distilled-pve.ts';
+import { specGuards } from './resource-guard.ts';
+import { formToSend } from './update-guard.ts';
+import { backupJobSpec } from './backup-job-config.ts';
+import { backupJobRequest, deleteBackupJob, readBackupJob } from './backup-job-distilled.ts';
+
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, guestList, propertyString, text } from './values.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
 
 /**
- * ⚠️ THE PROPS ARE PVE'S OWN KEY NAMES, DASHES INCLUDED. `notes-template` rather than
- *   `notesTemplate` is deliberate: `createForm` is then a copy rather than a translation table,
- *   and a translation table is one more place for a key to be renamed and silently never sent. A
- *   field that is never sent reads back as whatever it already was, which is indistinguishable
- *   from "PVE ignored me".
+ * ★ Public props retain PVE's own dashed field names. The distilled transport maps those
+ *   existing forms to the SDK's generated identifiers; lifecycle tests check the actual wire.
  */
 export interface BackupJobProps extends WithTarget {
   /** ⛔ The primary key, REQUIRED. Never let PVE generate it — see the ⛔ above. */
@@ -107,109 +110,68 @@ export interface ProxmoxBackupJob extends Resource<
 export const ProxmoxBackupJob = Resource<ProxmoxBackupJob>('Proxmox.BackupJob');
 
 /**
- * The form for both create and update.
- *
- * ⛔ A FIELD THE DECLARATION LEAVES OUT IS NOT SENT, AND THAT IS LOAD BEARING. PVE's PUT can only
- *   SET a key; clearing one needs `delete=<key>`, which this resource deliberately never sends.
- *   `updateForm` is handed the props and nothing else, so a `delete` list could only be "every
- *   field you did not declare" — and on a job adopted out of the UI that would silently strip
- *   settings this resource does not even model, `compress`, `mailto` and `bwlimit` among them, on
- *   the first deploy. Leaving undeclared fields alone is the smaller lie, and `matches` tells the
- *   same lie consistently: it does not compare what it cannot change.
- *
- * ⚠️ THE FIVE FIELDS PVE DOCUMENTS A DEFAULT FOR ARE ALWAYS SENT AND ALWAYS COMPARED — `enabled`
- *   (1), `all` (0), `mode` (snapshot), `notification-mode` (auto), `repeat-missed` (0). That is
- *   what makes a hand-flipped `enabled 0` show up as drift rather than as silence, and it is also
- *   what stops those five looping: a field compared against a default must be sent as that
- *   default, or every plan reports an update the PUT never performs. The cost is worth reading
- *   before the first deploy against an adopted job — an omitted `all` is a declaration that this
- *   job backs up NOTHING, and PVE accepts a job that selects nothing without a word. Read that
- *   first plan; do not deploy it unseen.
+ * ⛔ Adoption stays explicit: listing every backup job could grant Alchemy deletion rights over
+ *   an undeclared schedule. Delete removes the schedule, not its stored archives; that still
+ *   stops future backups, so the plan line is a consequential warning.
  */
-const shape = (props: BackupJobProps) => ({
-  all: props.all === true ? '1' : '0',
-  enabled: props.enabled === false ? '0' : '1',
-  mode: props.mode ?? 'snapshot',
-  'notification-mode': props['notification-mode'] ?? 'auto',
-  'repeat-missed': props['repeat-missed'] === true ? '1' : '0',
-  schedule: props.schedule,
-  ...(props.comment === undefined ? {} : { comment: props.comment }),
-  ...(props.exclude === undefined ? {} : { exclude: guestList(props.exclude) }),
-  ...(props.fleecing === undefined ? {} : { fleecing: props.fleecing }),
-  ...(props['notes-template'] === undefined ? {} : { 'notes-template': props['notes-template'] }),
-  ...(props.pool === undefined ? {} : { pool: props.pool }),
-  ...(props['prune-backups'] === undefined ? {} : { 'prune-backups': props['prune-backups'] }),
-  ...(props.storage === undefined ? {} : { storage: props.storage }),
-  ...(props.vmid === undefined ? {} : { vmid: guestList(props.vmid) }),
-});
+const { guardCreate, guardUpdate } = specGuards(backupJobSpec);
 
-const handlers = pveHandlers<BackupJobProps, BackupJobAttributes>({
-  /**
-   * ⛔ NO "IS IT REALLY THERE" GUARD, ON PURPOSE. Returning undefined for a job whose JSON is
-   *   missing some key would be a guess about which keys PVE echoes back, and a wrong guess here
-   *   does not read as absent-and-harmless: `reconcile` would POST, and POST creates ANOTHER job.
-   *   Absence is decided by the API declining to answer, which `pveOperations.read` already
-   *   handles — not by a key being missing from an answer that did arrive.
-   */
-  attributes: (live, props) => ({
-    all: bool(live['all'], false),
-    comment: text(live['comment'], ''),
-    enabled: bool(live['enabled'], true),
-    exclude: guestList(live['exclude']),
-    fleecing: propertyString(live['fleecing'], 'enabled'),
-    id: props.id,
-    mode: text(live['mode'], 'snapshot'),
-    'next-run': typeof live['next-run'] === 'number' ? live['next-run'] : 0,
-    'notes-template': text(live['notes-template'], ''),
-    'notification-mode': text(live['notification-mode'], 'auto'),
-    pool: text(live['pool'], ''),
-    'prune-backups': propertyString(live['prune-backups']),
-    'repeat-missed': bool(live['repeat-missed'], false),
-    schedule: text(live['schedule'], ''),
-    storage: text(live['storage'], ''),
-    vmid: guestList(live['vmid']),
-  }),
-  collection: () => 'cluster/backup',
-  /** ⛔ `id` IS SENT AND IS NOT OPTIONAL. Everything above depends on PVE not inventing one. */
-  createForm: (props) => ({ ...shape(props), id: props.id }),
-  /** Each line reads "not declared, or equal"; the five defaulted fields have no undeclared case. */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /cluster/backup', update: 'pve:PUT /cluster/backup/{id}' },
-  matches: (attributes, props) =>
-    attributes.schedule === props.schedule &&
-    attributes.enabled === (props.enabled !== false) &&
-    attributes.all === (props.all === true) &&
-    attributes.mode === (props.mode ?? 'snapshot') &&
-    attributes['notification-mode'] === (props['notification-mode'] ?? 'auto') &&
-    attributes['repeat-missed'] === (props['repeat-missed'] === true) &&
-    (props.storage === undefined || attributes.storage === props.storage) &&
-    (props.pool === undefined || attributes.pool === props.pool) &&
-    (props.comment === undefined || attributes.comment === props.comment) &&
-    (props.vmid === undefined || attributes.vmid === guestList(props.vmid)) &&
-    (props.exclude === undefined || attributes.exclude === guestList(props.exclude)) &&
-    (props['notes-template'] === undefined ||
-      attributes['notes-template'] === props['notes-template']) &&
-    (props['prune-backups'] === undefined ||
-      attributes['prune-backups'] === propertyString(props['prune-backups'])) &&
-    (props.fleecing === undefined ||
-      attributes.fleecing === propertyString(props.fleecing, 'enabled')),
-  path: (props) => `cluster/backup/${props.id}`,
-  updateForm: shape,
-});
-
-/**
-* ⛔ Empty for the same reason as every other resource here: adoption must be explicit.
-*   `GET /cluster/backup` would hand back the job somebody made by hand, and adopting it
-*   implicitly would give Alchemy the right to DELETE a cluster's only backup schedule the
-*   first time a line left a stack file.
- 
- *
-* ⚠️ DELETING THE JOB DOES NOT DELETE THE BACKUPS, AND THAT CUTS BOTH WAYS. The archives
-*   stay on the storage, so this looks harmless today; it is destructive in six months,
-*   when the schedule that should have replaced them has not run since. PVE will not
-*   refuse this the way it refuses to delete a pool still holding guests — nothing depends
-*   on a backup job — so the plan line is the only warning anyone gets.
- 
- */
+/** SDK lifecycle walked against pve-manager 9.2.11; failed reads never imply create. */
 export const ProxmoxBackupJobProvider = () =>
-  Provider.effect(ProxmoxBackupJob, Effect.succeed(ProxmoxBackupJob.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxBackupJob,
+    Effect.succeed(
+      ProxmoxBackupJob.Provider.of({
+        list: () => Effect.succeed([]),
+        read: ({ olds }) => readBackupJob(olds),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardCreate(news, output === undefined);
+          yield* guardUpdate(news);
+          if (output === undefined) return undefined;
+          const live = yield* readBackupJob(news);
+          if (live === undefined) {
+            yield* guardCreate(news, true);
+            return { action: 'update' } as const;
+          }
+          return { action: backupJobSpec.matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          const live = yield* readBackupJob(news);
+          yield* guardCreate(news, live === undefined);
+          yield* guardUpdate(news);
+          if (live === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              cluster.createClusterBackup(backupJobRequest(news)),
+            );
+          } else {
+            const form = formToSend(
+              backupJobSpec.matches,
+              live,
+              news,
+              backupJobSpec.updateForm(news),
+            );
+            if (form !== undefined)
+              yield* runPve(
+                news.target,
+                'provision',
+                true,
+                cluster.putClusterBackup(backupJobRequest(news, form)),
+              );
+          }
+          const after = yield* readBackupJob(news);
+          if (after === undefined)
+            return yield* Effect.fail(
+              new Error(
+                `${backupJobSpec.path(news)}: write returned success but the resource is still absent`,
+              ),
+            );
+          return after;
+        }),
+        delete: ({ olds }) => deleteBackupJob(olds),
+      }),
+    ),
+  );

package/src/proxmox/constraints.test.ts

@@ -18,7 +18,8 @@ import { engineOver } from '../verify/fake-engine.ts';
 import { constraintsFor, formViolations } from './constraint-guard.ts';
 import { type EndpointConstraints, refusal, violations } from './constraints.ts';
 import type { PbsTarget } from './credentials.ts';
-import { fakePve, withoutBao } from './fake-pve.ts';
+import { withoutBao } from './fake-pve.ts';
+import { fakePbsJobs } from './fake-pbs-jobs.ts';
 import { PROXMOX_CONSTRAINTS, PROXMOX_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
 import { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
 
@@ -46,12 +47,8 @@ describe('the v-r2-offsite failure, refused at plan instead of by the server', (
      * skip entirely (`output === undefined` returned before any check). It remembers the POST so
      * the read-back in `reconcile` can succeed, which is what the 128-character case needs.
      */
-    const live = new Map<string, Record<string, unknown>>();
-    const fake = fakePve((call) => {
-      if (call.method === 'GET') return live.get(call.path);
-      if (call.method === 'POST') live.set(`config/verify/${String(call.form['id'])}`, call.form);
-      return undefined;
-    });
+    // Missing PBS sections are measured plain-text HTTP400, not HTTP200 data:null.
+    const fake = fakePbsJobs();
     const engine = engineOver(PbsVerifyJobProvider().pipe(Layer.provideMerge(fake.layer)));
     const outcome = await withoutBao(() =>
       engine.deploy(job(comment)).then(
@@ -59,7 +56,11 @@ describe('the v-r2-offsite failure, refused at plan instead of by the server', (
         (error: unknown) => ({ error }),
       ),
     );
-    return { ...outcome, calls: fake.calls, writes: fake.writes() };
+    return {
+      ...outcome,
+      calls: fake.calls,
+      writes: fake.writes.map((row) => `${row.method} ${row.path}`),
+    };
   };
 
   test('129 characters is refused, and NOTHING is written', async () => {