@homeflare/alchemy 0.37.1 → 0.37.3

package/src/proxmox/notification-target-distilled.ts

@@ -0,0 +1,160 @@
+/** PVE 9.2.11 target operations. Named SDK calls retain each endpoint's own request schema. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import type { ProxmoxOpContext, ProxmoxOpError } from '@distilled.cloud/proxmox/Protocol';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
+import type { NotificationTargetProps as Props } from './notification-target.ts';
+import { addressList, createShape, shape } from './notification-target-form.ts';
+import { notificationRequest, notificationResponse } from './notification-sdk-input.ts';
+import { targetSpec } from './notification-target-spec.ts';
+
+const read = (
+  props: Props,
+): Effect.Effect<Record<string, unknown>, ProxmoxOpError, ProxmoxOpContext> => {
+  const request = { name: props.name };
+  switch (props.type) {
+    case 'gotify':
+      return cluster.getClusterNotificationEndpointGotify(request).pipe(
+        Effect.flatMap(notificationResponse(cluster.GetClusterNotificationEndpointGotifyResponse)),
+        Effect.map((row) => ({ ...row })),
+      );
+    case 'sendmail':
+      return cluster.getClusterNotificationEndpointSendmail(request).pipe(
+        Effect.flatMap(
+          notificationResponse(cluster.GetClusterNotificationEndpointSendmailResponse),
+        ),
+        Effect.map((row) => ({
+          ...row,
+          'from-address': row.from_address,
+          'mailto-user': row.mailto_user,
+        })),
+      );
+    case 'smtp':
+      return cluster.getClusterNotificationEndpointSmtp(request).pipe(
+        Effect.flatMap(notificationResponse(cluster.GetClusterNotificationEndpointSmtpResponse)),
+        Effect.map((row) => ({
+          ...row,
+          'from-address': row.from_address,
+          'mailto-user': row.mailto_user,
+        })),
+      );
+    case 'webhook':
+      return cluster.getClusterNotificationEndpointWebhook(request).pipe(
+        Effect.flatMap(notificationResponse(cluster.GetClusterNotificationEndpointWebhookResponse)),
+        Effect.map((row) => ({ ...row })),
+      );
+  }
+};
+
+export const readTarget = (props: Props) =>
+  runPve(props.target, 'read', false, read(props)).pipe(
+    Effect.map((row) => targetSpec.attributes(row, props)),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+/** The legacy forms spell scalar lists explicitly; SDK arrays preserve each logical value. */
+const fields = (props: Props, create: boolean) => {
+  const form: Record<string, string | string[]> = {
+    ...(create ? createShape(props) : shape(props)),
+    name: props.name,
+  };
+  const cleared: string[] = [];
+  for (const [key, values] of [
+    ['header', props.header === undefined ? undefined : [...props.header]],
+    [
+      'mailto',
+      props.mailto === undefined ? undefined : addressList(props.mailto).split(',').filter(Boolean),
+    ],
+    [
+      'mailto-user',
+      props['mailto-user'] === undefined
+        ? undefined
+        : addressList(props['mailto-user']).split(',').filter(Boolean),
+    ],
+  ] as const) {
+    if (values === undefined) continue;
+    if (values.length > 0) form[key] = values;
+    else {
+      delete form[key];
+      if (!create) cleared.push(key);
+    }
+  }
+  // Empty SDK arrays emit no keys; a PUT must explicitly clear a declared empty list.
+  if (cleared.length > 0) form.delete = cleared;
+  return form;
+};
+
+/** No request: replacement planning must reject SDK-only input errors before any DELETE. */
+export const validateTargetWrite = (props: Props, create: boolean) => {
+  const schema = create
+    ? {
+        sendmail: cluster.CreateClusterNotificationEndpointSendmailRequest,
+        smtp: cluster.CreateClusterNotificationEndpointSmtpRequest,
+        gotify: cluster.CreateClusterNotificationEndpointGotifyRequest,
+        webhook: cluster.CreateClusterNotificationEndpointWebhookRequest,
+      }[props.type]
+    : {
+        sendmail: cluster.PutClusterNotificationEndpointSendmailRequest,
+        smtp: cluster.PutClusterNotificationEndpointSmtpRequest,
+        gotify: cluster.PutClusterNotificationEndpointGotifyRequest,
+        webhook: cluster.PutClusterNotificationEndpointWebhookRequest,
+      }[props.type];
+  return notificationRequest(schema, fields(props, create)).pipe(Effect.asVoid);
+};
+
+export const createTarget = (props: Props) => {
+  const form = fields(props, true);
+  const operation =
+    props.type === 'sendmail'
+      ? notificationRequest(cluster.CreateClusterNotificationEndpointSendmailRequest, form).pipe(
+          Effect.flatMap(cluster.createClusterNotificationEndpointSendmail),
+        )
+      : props.type === 'smtp'
+        ? notificationRequest(cluster.CreateClusterNotificationEndpointSmtpRequest, form).pipe(
+            Effect.flatMap(cluster.createClusterNotificationEndpointSmtp),
+          )
+        : props.type === 'gotify'
+          ? notificationRequest(cluster.CreateClusterNotificationEndpointGotifyRequest, form).pipe(
+              Effect.flatMap(cluster.createClusterNotificationEndpointGotify),
+            )
+          : notificationRequest(cluster.CreateClusterNotificationEndpointWebhookRequest, form).pipe(
+              Effect.flatMap(cluster.createClusterNotificationEndpointWebhook),
+            );
+  return runPve(props.target, 'provision', true, operation);
+};
+
+export const updateTarget = (props: Props) => {
+  const form = fields(props, false);
+  const operation =
+    props.type === 'sendmail'
+      ? notificationRequest(cluster.PutClusterNotificationEndpointSendmailRequest, form).pipe(
+          Effect.flatMap(cluster.putClusterNotificationEndpointSendmail),
+        )
+      : props.type === 'smtp'
+        ? notificationRequest(cluster.PutClusterNotificationEndpointSmtpRequest, form).pipe(
+            Effect.flatMap(cluster.putClusterNotificationEndpointSmtp),
+          )
+        : props.type === 'gotify'
+          ? notificationRequest(cluster.PutClusterNotificationEndpointGotifyRequest, form).pipe(
+              Effect.flatMap(cluster.putClusterNotificationEndpointGotify),
+            )
+          : notificationRequest(cluster.PutClusterNotificationEndpointWebhookRequest, form).pipe(
+              Effect.flatMap(cluster.putClusterNotificationEndpointWebhook),
+            );
+  return runPve(props.target, 'provision', true, operation);
+};
+
+export const deleteTarget = (props: Props) => {
+  const request = { name: props.name };
+  const operation =
+    props.type === 'sendmail'
+      ? cluster.deleteClusterNotificationEndpointSendmail(request)
+      : props.type === 'smtp'
+        ? cluster.deleteClusterNotificationEndpointSmtp(request)
+        : props.type === 'gotify'
+          ? cluster.deleteClusterNotificationEndpointGotify(request)
+          : cluster.deleteClusterNotificationEndpointWebhook(request);
+  return runPve(props.target, 'provision', true, operation).pipe(
+    Effect.catchTag('NotFound', () => Effect.void),
+  );
+};

package/src/proxmox/notification-target-form.ts

@@ -6,6 +6,8 @@
  *   one metric-server uses: this file turns a declaration into a form, and the resource file says
  *   what a target IS and when it has changed. The `import type` back is erased, so it is a cycle
  *   on paper only.
+ * ★ These shapes still feed specGuards and preserve scalar/default/omission mapping. The
+ *   distilled adapter replaces list fields with typed arrays; the SDK owns their wire encoding.
  */
 import type { NotificationTargetProps } from './notification-target.ts';
 import { text } from './values.ts';

package/src/proxmox/notification-target-lifecycle.ts

@@ -0,0 +1,75 @@
+/** PVE targets: observe before writes, retain secret omission and built-in delete behavior. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type {
+  NotificationTargetAttributes as Attributes,
+  NotificationTargetProps as Props,
+} from './notification-target.ts';
+import { specGuards } from './resource-guard.ts';
+import { targetSpec } from './notification-target-spec.ts';
+import {
+  createTarget,
+  deleteTarget,
+  readTarget,
+  updateTarget,
+  validateTargetWrite,
+} from './notification-target-distilled.ts';
+
+const { guardCreate, guardUpdate } = specGuards(targetSpec);
+const guard = (props: Props, create: boolean) =>
+  guardCreate(props, create).pipe(Effect.andThen(guardUpdate(props)));
+export const targetHandlers = {
+  /** Targets include built-ins and human-owned endpoints; enrollment remains explicit. */
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readTarget(olds);
+      yield* guard(olds, live === undefined);
+      return live;
+    }),
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<Props>;
+    olds: Props;
+    output: Attributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      // Names are unique across endpoint types. A same-name type change must delete first.
+      if (olds.name !== news.name || olds.type !== news.type) {
+        // ⛔ Validate before delete-first can remove the working target. An existing destination
+        // is adoption: do not demand create-only secrets that the provider cannot declare.
+        const destination = yield* readTarget(news);
+        yield* guard(news, destination === undefined);
+        yield* validateTargetWrite(news, destination === undefined);
+        return { action: 'replace', deleteFirst: olds.name === news.name } as const;
+      }
+      yield* guard(news, output === undefined);
+      if (output === undefined) return undefined;
+      const live = yield* readTarget(news);
+      if (live === undefined) {
+        yield* guard(news, true);
+        return { action: 'update' } as const;
+      }
+      return { action: targetSpec.matches(live, news) ? 'noop' : 'update' } as const;
+    }),
+  reconcile: ({ news }: { news: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readTarget(news);
+      yield* guard(news, live === undefined);
+      if (live === undefined) yield* createTarget(news);
+      else if (!targetSpec.matches(live, news)) yield* updateTarget(news);
+      const after = yield* readTarget(news);
+      if (after === undefined)
+        return yield* Effect.die(
+          new Error(`Notification target ${news.name}: write returned but read-back is absent.`),
+        );
+      return after;
+    }),
+  /** Vendor DELETE reverts built-ins; SDK NotFound makes an absent custom target idempotent. */
+  delete: ({ olds }: { olds: Props }) => deleteTarget(olds),
+};

package/src/proxmox/notification-target-spec.ts

@@ -0,0 +1,68 @@
+/** Pure target state and vendor guards, kept separate from the SDK lifecycle. */
+import type {
+  NotificationTargetAttributes,
+  NotificationTargetProps,
+} from './notification-target.ts';
+import type { PveSpec } from './resource-spec.ts';
+import { targetEndpoint } from './notification-target-endpoint.ts';
+import { addressList, createShape, headerList, portOf, shape } from './notification-target-form.ts';
+import { text } from './values.ts';
+
+export const targetSpec: PveSpec<NotificationTargetProps, NotificationTargetAttributes> = {
+  /**
+   * ⛔ NAMED FIELDS, NEVER A SPREAD OF `live`. gotify's `token` and smtp's `password` really are
+   *   absent from their read schemas — but webhook's read schema DECLARES `secret`, so "PVE will
+   *   not hand it to us" is not a defence. Listing what is kept is what keeps secret material out
+   *   of a state row, whatever a future PVE decides to start returning.
+   */
+  attributes: (live, props) => ({
+    author: text(live['author']),
+    body: text(live['body']),
+    comment: text(live['comment']),
+    disable: live['disable'] === 1 || live['disable'] === true,
+    'from-address': text(live['from-address']),
+    header: headerList(live['header']),
+    mailto: addressList(live['mailto']),
+    'mailto-user': addressList(live['mailto-user']),
+    method: text(live['method']),
+    mode: text(live['mode']),
+    name: props.name,
+    port: portOf(live['port']),
+    server: text(live['server']),
+    type: props.type,
+    url: text(live['url']),
+    username: text(live['username']),
+  }),
+  collection: (props) => `cluster/notifications/endpoints/${props.type}`,
+  /** ⛔ `name` is create-only: PVE takes it in the body once, and in the path forever after. */
+  createForm: createShape,
+  /** ⚠️ A function, because the type picks the endpoint — see `targetEndpoint`. */
+  endpoint: targetEndpoint,
+  /**
+   * Each line reads "not declared, or equal"; `disable` is the one field with no undeclared case.
+   *
+   * ⚠️ IF A PLAN NEVER SETTLES, SUSPECT A SCHEMA DEFAULT COMING BACK AS A VALUE. PVE defaults smtp
+   *   `mode` to `tls` and smtp `author` to `Proxmox VE`, and applies both when the mail is sent
+   *   rather than writing them into the config — so an undeclared field reads back empty and its
+   *   line is skipped. A version that STORED them would answer with a field nobody declared. The
+   *   fix is to declare the field, never to stop comparing it.
+   */
+  matches: (attributes, props) =>
+    attributes.disable === (props.disable === true) &&
+    (props.comment === undefined || attributes.comment === props.comment) &&
+    (props.server === undefined || attributes.server === props.server) &&
+    (props.port === undefined || attributes.port === props.port) &&
+    (props.mode === undefined || attributes.mode === props.mode) &&
+    (props.username === undefined || attributes.username === props.username) &&
+    (props['from-address'] === undefined || attributes['from-address'] === props['from-address']) &&
+    (props.author === undefined || attributes.author === props.author) &&
+    (props.url === undefined || attributes.url === props.url) &&
+    (props.method === undefined || attributes.method === props.method) &&
+    (props.body === undefined || attributes.body === props.body) &&
+    (props.mailto === undefined || attributes.mailto === addressList(props.mailto)) &&
+    (props['mailto-user'] === undefined ||
+      attributes['mailto-user'] === addressList(props['mailto-user'])) &&
+    (props.header === undefined || attributes.header === headerList(props.header)),
+  path: (props) => `cluster/notifications/endpoints/${props.type}/${props.name}`,
+  updateForm: shape,
+};

package/src/proxmox/notification-target.ts

@@ -45,18 +45,15 @@
  *   ⚠️ PREFER A SECOND ROLE GRANTED AT `/mapping/notifications` OVER WIDENING THE PROVISIONING ROLE
  *     ON `/`. `/mapping` also holds the PCI and USB passthrough maps, so Mapping.Modify at the root
  *     lets a credential scoped to make containers rewire somebody's hardware.
- *   ⛔ A MISSING READ PRIVILEGE DOES NOT LOOK LIKE A 403. `pveOperations.read` ends in
- *     `orElseSucceed(() => undefined)`, so a 403 on the GET is indistinguishable from "absent": the
- *     plan says create, PVE answers "already exists", and the fault was an ACL all along. That pair
- *     is the signature — grant Mapping.Audit to the READ role before changing anything else.
+ *   ⛔ THE OLD HAND CLIENT FOLDED 403 INTO "ABSENT": the plan said create, PVE refused the
+ *     duplicate, and the fault was an ACL all along. Distilled now propagates that failure.
+ *     Grant Mapping.Audit to the READ role before adopting; only typed NotFound means absent.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { targetEndpoint } from './notification-target-endpoint.ts';
-import { addressList, createShape, headerList, portOf, shape } from './notification-target-form.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { text } from './values.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { targetHandlers } from './notification-target-lifecycle.ts';
 
 /** The four families PVE ships. `GET /cluster/notifications/endpoints` lists exactly these. */
 export type NotificationTargetType = 'gotify' | 'sendmail' | 'smtp' | 'webhook';
@@ -154,65 +151,6 @@ export const ProxmoxNotificationTarget = Resource<ProxmoxNotificationTarget>(
   'Proxmox.NotificationTarget',
 );
 
-const handlers = pveHandlers<NotificationTargetProps, NotificationTargetAttributes>({
-  /**
-   * ⛔ NAMED FIELDS, NEVER A SPREAD OF `live`. gotify's `token` and smtp's `password` really are
-   *   absent from their read schemas — but webhook's read schema DECLARES `secret`, so "PVE will
-   *   not hand it to us" is not a defence. Listing what is kept is what keeps secret material out
-   *   of a state row, whatever a future PVE decides to start returning.
-   */
-  attributes: (live, props) => ({
-    author: text(live['author']),
-    body: text(live['body']),
-    comment: text(live['comment']),
-    disable: live['disable'] === 1 || live['disable'] === true,
-    'from-address': text(live['from-address']),
-    header: headerList(live['header']),
-    mailto: addressList(live['mailto']),
-    'mailto-user': addressList(live['mailto-user']),
-    method: text(live['method']),
-    mode: text(live['mode']),
-    name: props.name,
-    port: portOf(live['port']),
-    server: text(live['server']),
-    type: props.type,
-    url: text(live['url']),
-    username: text(live['username']),
-  }),
-  collection: (props) => `cluster/notifications/endpoints/${props.type}`,
-  /** ⛔ `name` is create-only: PVE takes it in the body once, and in the path forever after. */
-  createForm: createShape,
-  /** ⚠️ A function, because the type picks the endpoint — see `targetEndpoint`. */
-  endpoint: targetEndpoint,
-  /**
-   * Each line reads "not declared, or equal"; `disable` is the one field with no undeclared case.
-   *
-   * ⚠️ IF A PLAN NEVER SETTLES, SUSPECT A SCHEMA DEFAULT COMING BACK AS A VALUE. PVE defaults smtp
-   *   `mode` to `tls` and smtp `author` to `Proxmox VE`, and applies both when the mail is sent
-   *   rather than writing them into the config — so an undeclared field reads back empty and its
-   *   line is skipped. A version that STORED them would answer with a field nobody declared. The
-   *   fix is to declare the field, never to stop comparing it.
-   */
-  matches: (attributes, props) =>
-    attributes.disable === (props.disable === true) &&
-    (props.comment === undefined || attributes.comment === props.comment) &&
-    (props.server === undefined || attributes.server === props.server) &&
-    (props.port === undefined || attributes.port === props.port) &&
-    (props.mode === undefined || attributes.mode === props.mode) &&
-    (props.username === undefined || attributes.username === props.username) &&
-    (props['from-address'] === undefined || attributes['from-address'] === props['from-address']) &&
-    (props.author === undefined || attributes.author === props.author) &&
-    (props.url === undefined || attributes.url === props.url) &&
-    (props.method === undefined || attributes.method === props.method) &&
-    (props.body === undefined || attributes.body === props.body) &&
-    (props.mailto === undefined || attributes.mailto === addressList(props.mailto)) &&
-    (props['mailto-user'] === undefined ||
-      attributes['mailto-user'] === addressList(props['mailto-user'])) &&
-    (props.header === undefined || attributes.header === headerList(props.header)),
-  path: (props) => `cluster/notifications/endpoints/${props.type}/${props.name}`,
-  updateForm: shape,
-});
-
 /**
  * ⚠️ ON A BUILT-IN TARGET A DELETE REVERTS RATHER THAN REMOVES, and PVE reports success either way.
  *   It is passed through unguarded because everywhere else in this package the cluster's answer is
@@ -222,5 +160,5 @@ const handlers = pveHandlers<NotificationTargetProps, NotificationTargetAttribut
 export const ProxmoxNotificationTargetProvider = () =>
   Provider.effect(
     ProxmoxNotificationTarget,
-    Effect.succeed(ProxmoxNotificationTarget.Provider.of(handlers)),
+    Effect.succeed(ProxmoxNotificationTarget.Provider.of(targetHandlers)),
   );

package/src/proxmox/pbs-datastore-endpoint.ts

@@ -2,7 +2,7 @@
  * `Pbs.Datastore`'s two vendor endpoints, and the plan-time check over its two forms.
  *
  * ★ A FILE OF ITS OWN BECAUSE THIS FAMILY DOES NOT USE `pveHandlers`. It writes its own `diff` and
- *   `reconcile` (a create answers with a task id, so it settles rather than reading back once), so
+ *   `reconcile` (bounded readback handles settling after a write; create returns no task id), so
  *   it cannot inherit the guard from resource.ts — and a copy of the two calls inside that already
  *   long file is exactly the per-resource copy-paste the shared handler exists to prevent.
  *

package/src/proxmox/pbs-datastore-form.ts

@@ -1,42 +1,41 @@
 /**
- * A PBS datastore on the wire: the transport that reaches PBS, the form it wants, and the coercion
- * back to something comparable.
+ * A PBS datastore's pure vendor forms and coercion back to comparable state. SDK transport is
+ * in pbs-datastore-wire.ts; lifecycle behavior is in pbs-datastore-lifecycle.ts.
  *
  * ★ SPLIT OUT OF pbs-datastore.ts FOR THE 250-LINE CAP, the seam notification-target-form.ts uses:
- *   this file is everything that touches PBS's encoding, and the resource file is the declaration
- *   and the five handlers. The `import type` back is erased, so it is a cycle on paper only.
+ *   this file originally held PBS encoding beside forms, while the resource held its declaration
+ *   and five handlers. The `import type` back is erased, so it is a cycle on paper only.
  *
- * ⛔ THIS FILE IS OVER THE 250-LINE CAP AND THE EXTRACTION IS NAMED RATHER THAN FUDGED. `PbsTarget`,
+ * ⛔ HISTORICAL EXTRACTION NOTE: THIS FILE EXCEEDED THE 250-LINE CAP IN THE ORIGINAL DRAFT. `PbsTarget`,
  *   `PbsRole`, `PbsError`, `pbsAuthorization`, `PveForm`, `encode`, `pbs` and `settle` — about 150
  *   lines — are a PBS CLIENT, not a datastore form, and belong in `pbs-client.ts`. Lifting them
  *   leaves this file near 200 and costs nothing but a move. It was not done here only because the
  *   family was commissioned as a two-file split; ceph-pool is the in-package precedent for three
  *   (ceph-pool.ts + ceph-pool-form.ts + ceph-pool-settle.ts, 532 lines for one family). Everything
  *   in that list is also what Pbs.SyncJob, Pbs.PruneJob and Pbs.Remote will each need unchanged,
- *   so the second PBS family forces the move anyway. ⛔ DO NOT MEET THE CAP BY CUTTING COMMENTS.
+ *   so the second PBS family forced that move. The SDK and focused siblings now own these seams.
+ *   ⛔ DO NOT MEET THE CAP BY CUTTING COMMENTS.
  */
-import * as Effect from 'effect/Effect';
-import { type PveForm, pve } from './client.ts';
 import type { PbsTarget as ApiPbsTarget } from './credentials.ts';
 import type { PbsDatastoreProps } from './pbs-datastore.ts';
 import { bool, flag, int, propertyString, text } from './values.ts';
 
 /**
- * ★ PBS REUSES THE PVE CLIENT RATHER THAN OWNING ONE. An earlier draft of this file carried its
- *   own `PbsTarget`, `PbsError`, `pbsAuthorization`, form encoder and `pve()` — a near-copy of
- *   client.ts differing in one header. They are gone: `PveTarget` now carries a `scheme`, and
- *   `authorization()` spells the header `PBSAPIToken=<id>:<secret>` when it is `'pbs'`. The
- *   insight that survived is the FORM TYPE — PBS decodes a multi-valued field from repeated keys
- *   where PVE wants a comma string — and that now lives on `PveForm` in client.ts, so both
- *   products share one encoder and neither can reach for the other's convention by accident.
+ * ★ PBS ORIGINALLY REUSED THE PVE CLIENT RATHER THAN OWNING ANOTHER. An earlier draft carried
+ *   its own `PbsTarget`, `PbsError`, `pbsAuthorization`, form encoder and `pve()` — a near-copy of
+ *   client.ts differing in one header. The shared target's `scheme` replaced that copy. This
+ *   family now uses the distilled PBS SDK through `distilled-pbs.ts`, retaining the same leased
+ *   credentials and PBS authorization scheme. The important encoding distinction survives:
+ *   PBS decodes a multi-valued field from repeated keys where PVE wants a comma string. The SDK
+ *   protocol owns that behavior; these pure forms describe only this datastore's scalar fields.
  *
  * 🔴 THIS ALIAS SAID `= PveTarget` AND IT WAS WRONG — Pbs.Datastore REQUIRED A PVE TARGET. When
  *   `credentials.ts` grew a real `PbsTarget` with `scheme: 'pbs'`, this line was left pointing at
  *   the PVE type, which pins `scheme: 'pve'`. So the one family that most needs the discriminant
  *   was the one family that refused the correct value: declaring a datastore against the PBS host
  *   failed to compile with `Type '"pbs"' is not assignable to type 'Input<"pve">'`, and passing a
- *   PVE target compiled fine and would have 401'd every call — which `read` folds into "absent",
- *   so the plan would say CREATE for a datastore holding the estate's backups.
+ *   PVE target compiled fine and would have 401'd every call — which the old `read` folded into
+ *   "absent", so the plan would say CREATE for a datastore holding the estate's backups.
  *   ⛔ IT SURVIVED BECAUSE NOTHING EVER DECLARED ONE. The provider was registered in
  *   alchemy.run.ts from the day it was written and `pveHandlers`' `list` answers empty, so
  *   registration exercises no call site at all. Three sibling families import `PbsTarget` from
@@ -183,7 +182,7 @@ const mutable = (props: PbsDatastoreProps): Record<string, string> => ({
  *   slot, not of the declaration; one that could re-point it is one that can send backups to the
  *   wrong drive.
  */
-export const createForm = (props: PbsDatastoreProps): PveForm => ({
+export const createForm = (props: PbsDatastoreProps): Record<string, string> => ({
   ...mutable(props),
   name: props.name,
   path: props.path,
@@ -213,36 +212,6 @@ export const createForm = (props: PbsDatastoreProps): PveForm => ({
  *     element that fails the enum check. `PveForm` and `encode` already carry arrays for exactly
  *     this. ⚠️ REASONED FROM THE PUBLISHED SCHEMA, NOT PROVEN ON A WIRE.
  */
-export const updateForm = (props: PbsDatastoreProps): PveForm => mutable(props);
+export const updateForm = (props: PbsDatastoreProps): Record<string, string> => mutable(props);
 
 export const object = (props: PbsDatastoreProps) => `config/datastore/${props.name}`;
-
-/**
- * The live datastore, or undefined.
- *
- * ⛔ `name` IS THE PRESENCE TEST, NOT THE STATUS CODE — PBS does not answer 404 for a section that
- *   is missing from `datastore.cfg`, it answers a generic error, so there is no code to key off.
- * ⛔ A MISSING READ PRIVILEGE THEREFORE LOOKS EXACTLY LIKE ABSENCE, because the fold below cannot
- *   tell them apart. The signature is a plan that says CREATE followed by PBS answering
- *   "datastore '<name>' already exists." — that pair means Datastore.Audit, not a missing
- *   datastore. It is loud and non-destructive, which is the only reason the fold is tolerable here;
- *   see the ⛔ on `readRole` in resource.ts for the PVE families where it is not.
- * ⛔ ON THE DELETE PATH THE SAME FOLD IS A LIE, AND THIS IS THE ONE HAZARD IN THIS FAMILY I COULD
- *   NOT CLOSE. `delete` settles by polling this read until it answers `undefined` — and a `read`
- *   role that lacks `Datastore.Audit` answers `undefined` from the very first poll, so EVERY delete
- *   would report success while the datastore stood. Worse, the two lanes are different leases: the
- *   DELETE goes out under `provision` and may genuinely fail, and this read cannot see that it did.
- *   ★ THE SHAPE OF THE FIX IS ALREADY IN THIS PACKAGE: `confirmAbsent` in ceph-pool-settle.ts asks
- *     a SECOND, DIFFERENT question — does the collection LIST this object? — and lets a failure
- *     PROPAGATE rather than folding it, so "I could not ask" fails the deploy instead of passing
- *     it. Add the same over `GET /config/datastore` before anyone relies on a reported deletion.
- *   ⚠️ UNTIL THEN THE PRECONDITION IS EXPLICIT: the `read` role MUST hold `Datastore.Audit` on the
- *     datastore, or this provider cannot tell a deletion from a refusal.
- */
-export const readOne = (props: PbsDatastoreProps) =>
-  pve<Record<string, unknown>>(props.target, 'read', 'GET', object(props)).pipe(
-    Effect.map((live) =>
-      live === undefined || typeof live['name'] !== 'string' ? undefined : attributes(live, props),
-    ),
-    Effect.orElseSucceed(() => undefined),
-  );

package/src/proxmox/pbs-datastore-guard.ts

@@ -76,13 +76,15 @@ export const guardBackend = (live: PbsDatastoreAttributes, props: PbsDatastorePr
 /**
  * Wait for PBS to finish, then answer the last thing it said.
  *
- * ⛔ IT EXISTS BECAUSE A PBS CREATE IS A FORKED WORKER AND THE CONFIG SECTION IS WRITTEN LAST.
+ * ⛔ THE ORIGINAL CREATE-WORKER ASSUMPTION BELOW WAS REASONED, NOT MEASURED.
  *   `POST /config/datastore` answers with a UPID while a `create-datastore` task builds the chunk
  *   store's 65536 directories; only when that finishes does the section reach `datastore.cfg`. An
  *   immediate read-back therefore sees a datastore that is not there yet, and the factory's "the
  *   write returned no error but the object is still absent" would fire on a create going perfectly.
  *   The DELETE forks a worker too. ⚠️ DOCUMENTED FROM THE PUBLISHED SCHEMA, NOT MEASURED — I hold
- *   no PBS token. If a create turns out to be synchronous, the first poll simply succeeds.
+ *   no PBS token. The pinned PBS 4.2.6-1 schema actually declares a NULL create response,
+ *   while DELETE declares a UPID. We preserve bounded readback for both; a synchronous create
+ *   succeeds at the first poll rather than depending on the old UPID assumption.
  * ★ IT TAKES THE READ AS AN EFFECT RATHER THAN A FUNCTION — the one simplification over
  *   ceph-pool-settle.ts: an Effect is a description, so re-running it re-reads and no dependency
  *   has to be threaded back in to avoid a cycle.
@@ -91,8 +93,9 @@ export const guardBackend = (live: PbsDatastoreAttributes, props: PbsDatastorePr
  *   Anything still unsettled after two minutes is a fault to surface, not a wait to lengthen, and
  *   the caller's message points at the task log, which is where the real answer is. `Effect.sleep`
  *   yields between polls; nothing here parks a call on one long wait.
- * ⚠️ POLLING THE TASK STATUS INSTEAD WOULD BE WORSE, for ceph-pool-settle.ts's reason: every call
- *   mints a FRESH token, so the token asking about the task is not the one that started it.
+ * ⚠️ THE ORIGINAL TRANSPORT MINTED A TOKEN PER CALL, making task-owner polling unreliable.
+ *   The SDK runner now reuses leases, but create has no task id in its measured response schema.
+ *   This migration therefore preserves bounded readback rather than inventing a task handle.
  */
 export const settle = <A, E, R>(read: Effect.Effect<A, E, R>, done: (live: A) => boolean) =>
   Effect.gen(function* () {