@homeflare/alchemy 0.37.2 → 0.37.3

package/src/proxmox/notification-replacement.test.ts

@@ -0,0 +1,190 @@
+/** Real Plan/Apply must refuse an invalid replacement before deleting its working target. */
+import { afterEach, beforeEach, expect } from 'bun:test';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { FAKE_TARGET, fakePve } from './fake-pve.ts';
+import {
+  type NotificationTargetProps,
+  ProxmoxNotificationTarget,
+  ProxmoxNotificationTargetProvider,
+} from './notification-target.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+
+const MISSING = 'HF_NOTIFICATION_REPLACEMENT_MISSING';
+const PBS = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' } as const;
+const fake = fakeNotify();
+let saved: [string, string | undefined][] = [];
+beforeEach(() => {
+  saved = Object.entries(process.env).filter(
+    ([key]) => /^(BAO|VAULT)_/.test(key) || key === MISSING,
+  );
+  for (const [key] of saved) delete process.env[key];
+  process.env['BAO_ADDR'] = 'http://bao.invalid';
+  fake.objects.clear();
+  fake.secrets.clear();
+  fake.calls.length = 0;
+});
+afterEach(() => {
+  for (const key of Object.keys(process.env))
+    if (/^(BAO|VAULT)_/.test(key) || key === MISSING) delete process.env[key];
+  for (const [key, value] of saved) process.env[key] = value;
+});
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    PbsNotificationTargetProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+
+const pve = (props: Omit<NotificationTargetProps, 'target'>) =>
+  ProxmoxNotificationTarget('endpoint', { ...props, target: FAKE_TARGET });
+const pbs = (props: Omit<PbsNotificationTargetProps, 'target'>) =>
+  PbsNotificationTarget('endpoint', { ...props, target: PBS });
+const invalidPve: readonly Omit<NotificationTargetProps, 'target' | 'name'>[] = [
+  { type: 'webhook', method: 'post' },
+  { type: 'gotify', server: 'https://gotify.example.com' },
+  { type: 'smtp', server: 'smtp.example.com' },
+  {
+    type: 'webhook',
+    method: 'post',
+    url: 'https://pager.example.com',
+    mailto: ['ops@example.com'],
+  },
+];
+const invalidPbs: readonly Omit<PbsNotificationTargetProps, 'target' | 'name'>[] = [
+  { type: 'webhook', method: 'post' },
+  {
+    type: 'webhook',
+    method: 'post',
+    url: 'https://pager.example.com',
+    secret: { token: { fromEnv: MISSING } },
+  },
+  { type: 'webhook', method: 'post', url: 'https://pager.example.com', comment: 'x'.repeat(129) },
+];
+for (const [index, props] of invalidPve.entries()) {
+  test.provider(`PVE replacement refusal ${index} preserves the old target`, (scratch) =>
+    Effect.gen(function* () {
+      const old = pve({ name: 'pager', type: 'sendmail' });
+      yield* scratch.deploy(old);
+      const path = 'cluster/notifications/endpoints/sendmail/pager';
+      const before = fake.objects.get(path);
+      fake.calls.length = 0;
+      expect((yield* Effect.exit(scratch.deploy(pve({ ...props, name: 'pager' }))))._tag).toBe(
+        'Failure',
+      );
+      expect(fake.writes()).toEqual([]);
+      expect(fake.objects.get(path)).toEqual(before);
+      expect(Object.values((yield* scratch.plan(old)).resources).map((row) => row.action)).toEqual([
+        'noop',
+      ]);
+    }),
+  );
+}
+for (const [index, props] of invalidPbs.entries()) {
+  test.provider(`PBS replacement refusal ${index} preserves the old target`, (scratch) =>
+    Effect.gen(function* () {
+      const old = pbs({ name: 'pager', type: 'sendmail' });
+      yield* scratch.deploy(old);
+      const path = 'config/notifications/endpoints/sendmail/pager';
+      const before = fake.objects.get(path);
+      fake.calls.length = 0;
+      expect((yield* Effect.exit(scratch.deploy(pbs({ ...props, name: 'pager' }))))._tag).toBe(
+        'Failure',
+      );
+      expect(fake.writes()).toEqual([]);
+      expect(fake.objects.get(path)).toEqual(before);
+      expect(Object.values((yield* scratch.plan(old)).resources).map((row) => row.action)).toEqual([
+        'noop',
+      ]);
+    }),
+  );
+}
+test.provider(
+  'PVE can replace by adopting an existing renamed gotify target without its token',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(pve({ name: 'old', type: 'sendmail' }));
+      const path = 'cluster/notifications/endpoints/gotify/existing';
+      fake.objects.set(path, { name: 'existing', server: 'https://gotify.example.com' });
+      fake.calls.length = 0;
+      yield* scratch.deploy(
+        pve({ name: 'existing', type: 'gotify', server: 'https://gotify.example.com' }),
+      );
+      expect(fake.objects.has(path)).toBe(true);
+      expect(fake.writes()).toEqual(['DELETE cluster/notifications/endpoints/sendmail/old']);
+    }),
+);
+
+const forbidden = fakePve((call) =>
+  call.path.endsWith('/sendmail/pager')
+    ? { name: 'pager' }
+    : Response.json({ message: 'forbidden' }, { status: 403 }),
+);
+const blocked = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    PbsNotificationTargetProvider(),
+  ).pipe(Layer.provideMerge(forbidden.layer)),
+}).test;
+for (const declare of [pve, pbs]) {
+  blocked.provider(`${declare.name} destination refusal prevents replacement deletion`, (scratch) =>
+    Effect.gen(function* () {
+      forbidden.calls.length = 0;
+      yield* scratch.deploy(
+        Effect.gen(function* () {
+          yield* declare({ name: 'pager', type: 'sendmail' });
+        }),
+      );
+      const replacement = Effect.gen(function* () {
+        yield* declare({
+          name: 'pager',
+          type: 'webhook',
+          url: 'https://pager.example.com',
+          method: 'post',
+        });
+      });
+      expect((yield* Effect.exit(scratch.deploy(replacement)))._tag).toBe('Failure');
+      expect(forbidden.writes()).toEqual([]);
+    }),
+  );
+}
+test.provider(
+  'PBS can replace by adopting an existing renamed webhook without its secret value',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(pbs({ name: 'old', type: 'sendmail' }));
+      const path = 'config/notifications/endpoints/webhook/existing';
+      fake.objects.set(path, {
+        name: 'existing',
+        url: 'https://pager.example.com',
+        method: 'post',
+        secret: ['name=token'],
+      });
+      fake.calls.length = 0;
+      yield* scratch.deploy(
+        pbs({
+          name: 'existing',
+          type: 'webhook',
+          url: 'https://pager.example.com',
+          method: 'post',
+          secret: { token: { fromEnv: MISSING } },
+        }),
+      );
+      expect(fake.objects.has(path)).toBe(true);
+      expect(fake.writes()).toEqual(['DELETE config/notifications/endpoints/sendmail/old']);
+    }),
+);

package/src/proxmox/notification-sdk-input.ts

@@ -0,0 +1,39 @@
+/** PVE 9.2.11 form names mapped to the generated SDK's TypeScript field names. */
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+/** Local schema refusal names the operation, never a form value (headers may be sensitive). */
+export class NotificationRequestInvalid extends Data.TaggedError('NotificationRequestInvalid')<{
+  readonly operation: string;
+}> {}
+
+/**
+ * The provider's forms already enforce vendor constraints. This final generated-schema
+ * check validates the translated Type-side fields without a cast. Unexpected family fields
+ * fail explicitly instead of disappearing through the decoder's default excess-property stripping.
+ */
+export const notificationRequest = <S extends Schema.Top>(schema: S, fields: object) =>
+  Schema.decodeUnknownEffect(Schema.toType(schema), { onExcessProperty: 'error' })(
+    Object.fromEntries(
+      Object.entries(fields).map(([key, value]) => [key.replaceAll('-', '_'), value]),
+    ),
+  ).pipe(
+    Effect.mapError(() => new NotificationRequestInvalid({ operation: 'PVE notification write' })),
+  );
+
+/** Validate required response fields with the SDK schema without discarding vendor extras. */
+export const notificationResponse =
+  <S extends Schema.Top>(schema: S) =>
+  (body: S['Type']) =>
+    Schema.decodeUnknownEffect(Schema.toType(schema))(body).pipe(
+      Effect.as(body),
+      Effect.mapError(
+        () =>
+          new ProxmoxParseError({
+            body: undefined,
+            cause: 'PVE notification response does not match its SDK schema',
+          }),
+      ),
+    );

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.
  *