@homeflare/alchemy 0.15.0 → 0.19.0

package/src/netbox/prefix.ts

@@ -0,0 +1,136 @@
+/**
+ * `Netbox.Prefix` — one IP prefix and the decision recorded against it.
+ *
+ * ★ WHY THIS OBJECT CLASS IS THE FIRST ONE, AND NOT `Device`, `VLAN` OR `Site`. Three reasons,
+ *   each measurable rather than aesthetic:
+ *
+ *   1. **It is the only interesting NetBox object with no foreign-key prerequisite.** MEASURED in
+ *      the 4.7.0 schema: `WritablePrefixRequest.required` is exactly `["prefix"]`. A `VLAN` needs
+ *      `vid` AND `name` and belongs to a group or site; a `Device` needs a role, a type, a site
+ *      and usually a manufacturer — four more Resources before the first one can be declared.
+ *      A scaffold that cannot declare anything until five families exist proves nothing.
+ *   2. **It is what the estate's NetBox is FOR.** The house's own IPAM agent describes its job as
+ *      reconciling "what the network IS against what NetBox says it was DECIDED to be". A prefix
+ *      is the atom of that decision. The estate has prefixes whose status is currently recorded
+ *      only in an SSH config comment and a retirement doc — a management VLAN, a Thunderbolt
+ *      point-to-point, and three ranges that are retired and still resolve in people's heads.
+ *   3. **`status: 'deprecated'` makes retirement declarable.** That is the move this unlocks:
+ *      a retired range stops being folklore and becomes a line in a stack file with a reviewable
+ *      diff. No other NetBox class turns an estate decision into one field this cleanly.
+ *
+ * ⚠️ ADOPT-FRIENDLY BY CONSTRUCTION. `locate` filters on the exact `prefix`; `identifies` then
+ *   picks the declared VRF, because NetBox allows the same CIDR in two VRFs and in the global
+ *   table. An instance that already holds `10.0.0.0/24` is BOUND, never duplicated — and ⛔ an
+ *   adopt never clears prose it did not declare (prefix-form.ts).
+ *
+ * ⛔ THIS RESOURCE DOES NOT REMOVE PREFIXES IT DOES NOT DECLARE, and `defaultRemovalPolicy` is
+ *   `retain` (resource.ts). Deleting a prefix in NetBox reparents its children and detaches its
+ *   IP assignments; the record of why it existed survives only in the change log.
+ *
+ * ⛔ NO CREDENTIAL IS A PROP. `NETBOX_URL` and `NETBOX_TOKEN` are read from the environment at
+ *   call time — the house convention, and the only shape that keeps a token out of Alchemy state.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { prefixBody, prefixMatches } from './prefix-form.ts';
+import { type NetboxRequirements, netboxHandlers } from './resource.ts';
+import { choice, fk, text } from './values.ts';
+
+/**
+ * ⚠️ THE FOUR VALUES ARE THE VENDOR'S, NOT OURS — copied from the generated table, which is
+ *   generated from NetBox's own enum. The table is what ENFORCES them; this type is what makes
+ *   the mistake visible in an editor.
+ */
+export type PrefixStatus = 'container' | 'active' | 'reserved' | 'deprecated';
+
+export interface PrefixProps {
+  /** CIDR, exactly as NetBox stores it — `10.0.0.0/24`. The stable key for locate. */
+  prefix: string;
+  /**
+   * VRF id, or omitted for the global table.
+   *
+   * ⛔ PART OF THE IDENTITY, NOT A SETTING. NetBox's uniqueness on a prefix is per-VRF, so a
+   *   locate that ignored it could match two rows — which `soleMatch` refuses rather than
+   *   guessing between.
+   */
+  vrf?: number;
+  status?: PrefixStatus;
+  /** ⚠️ `maxLength: 200` in the schema; the generated table enforces it at plan time. */
+  description?: string;
+  /** Free text. ⚠️ NetBox states no length limit, so nothing here checks one. */
+  comments?: string;
+  tenant?: number;
+  vlan?: number;
+  /** All addresses inside are usable. */
+  isPool?: boolean;
+  markUtilized?: boolean;
+}
+
+export interface PrefixAttributes {
+  prefixId: number;
+  prefix: string;
+  status: string;
+  description: string;
+  comments: string;
+  vrf: number | undefined;
+  tenant: number | undefined;
+  vlan: number | undefined;
+  isPool: boolean;
+  markUtilized: boolean;
+}
+
+export interface NetboxPrefix extends Resource<
+  'Netbox.Prefix',
+  PrefixProps,
+  PrefixAttributes,
+  never,
+  NetboxRequirements
+> {}
+
+export const NetboxPrefix = Resource<NetboxPrefix>('Netbox.Prefix', {
+  defaultRemovalPolicy: 'retain',
+});
+
+const handlers = netboxHandlers<PrefixProps, PrefixAttributes>({
+  attributes: (live, props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      comments: text(live['comments']),
+      description: text(live['description']),
+      isPool: live['is_pool'] === true,
+      markUtilized: live['mark_utilized'] === true,
+      prefix: text(live['prefix']) || props.prefix,
+      prefixId: id,
+      status: choice(live['status']),
+      tenant: fk(live['tenant']),
+      vlan: fk(live['vlan']),
+      vrf: fk(live['vrf']),
+    };
+  },
+  collection: 'ipam/prefixes',
+  createBody: prefixBody,
+  describe: (props) => `ipam/prefixes ${props.prefix}`,
+  endpoint: {
+    create: 'netbox:POST /api/ipam/prefixes/',
+    update: 'netbox:PATCH /api/ipam/prefixes/{id}/',
+  },
+  /**
+   * 🔴 THE VRF IS **NOT** IN THIS FILTER, AND THE REASON IS A GUESS THAT WAS CAUGHT. This read
+   *   `vrf_id=null` for the global table — NetBox does define `FILTERS_NULL_CHOICE_VALUE = 'null'`
+   *   and does honour it on filters that opt in. ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at
+   *   v4.7.0: `PrefixFilterSet.vrf_id` is a plain `django_filters.ModelMultipleChoiceFilter` with
+   *   no `null_value`, so `'null'` is validated against the VRF queryset, fails, and NetBox
+   *   answers 400 under strict filtering — on EVERY plan for EVERY global prefix.
+   * ★ So the CIDR narrows server-side with a filter the document plainly declares, and `identifies`
+   *   picks the VRF in this process. One extra page of candidates, no vendor semantics guessed.
+   */
+  identifies: (live, props) => fk(live['vrf']) === props.vrf,
+  locate: (props) => [['prefix', props.prefix]],
+  matches: prefixMatches,
+  updateBody: prefixBody,
+});
+
+export const NetboxPrefixProvider = () =>
+  Provider.effect(NetboxPrefix, Effect.succeed(NetboxPrefix.Provider.of(handlers)));

package/src/netbox/resource.ts

@@ -0,0 +1,208 @@
+/**
+ * One shape for every NetBox object — the same four operations, different path and JSON body.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Prefixes, VLANs, devices, tenants
+ *   and interfaces are all create / read / update / delete over `/api` with JSON bodies and a
+ *   numeric primary key. Hand-rolling the fourth copy is where someone drops the read-back or the
+ *   constraint guard and the plan lies.
+ *
+ * ★ ADOPT IS THE DEFAULT POSTURE, NOT A FLAG. `reconcile` LOCATES before it writes: an object the
+ *   estate already has is bound, not duplicated. NetBox is a record that predates this code by
+ *   years; a provider that created a second `10.20.10.0/24` on first deploy would be worse than
+ *   no provider.
+ *
+ * ★ `defaultRemovalPolicy: 'retain'` ON EVERY FAMILY. NetBox holds the estate's record of what
+ *   the network was DECIDED to be, and deleting a row deletes history — child prefixes reparent,
+ *   IP assignments detach, and the change log is the only trace left. `retain` means the engine
+ *   skips `delete` when a resource is orphaned unless the caller opts into
+ *   `.pipe(RemovalPolicy.destroy())`. The `delete` handler is FULLY IMPLEMENTED anyway: a stub
+ *   that silently does nothing lies to whoever reads the plan.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { NetboxError, type NetboxList, type NetboxRow, netbox, soleMatch } from './client.ts';
+import { guardBody } from './constraint-guard.ts';
+import type { EndpointKey, NetboxBody } from './constraints.ts';
+
+/**
+ * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME, AND NOTHING MORE. The token comes from
+ *   `NETBOX_TOKEN` in the environment, so there is no process to spawn and no `bao` to shell out
+ *   to. Declaring a service you never use is not harmless — it makes a stack provide a layer for
+ *   nothing, and it hides the one service you DO need.
+ */
+export type NetboxRequirements = HttpClient.HttpClient;
+
+export interface NetboxSpec<Props extends object, Attributes> {
+  /** `ipam/prefixes` — where a new one is POSTed and where `locate` filters. */
+  readonly collection: string;
+  /**
+   * The query that narrows the candidates, as `URLSearchParams` pairs.
+   *
+   * ⛔ ONLY FILTERS THE VENDOR DOCUMENT DECLARES, AND ONLY IN THE FORM IT DECLARES THEM. A
+   *   filter NetBox rejects answers 400, which `absentOn404` correctly does NOT fold to "absent" —
+   *   so a guessed filter shape is a hard failure on every plan, not a soft one.
+   * ★ IT DOES NOT HAVE TO BE UNIQUE. `identifies` finishes the job in this process, where the
+   *   rule is readable and testable offline.
+   */
+  readonly locate: (props: Props) => readonly (readonly [string, string])[];
+  /**
+   * Which of the returned rows IS this object.
+   *
+   * 🔴 THIS EXISTS BECAUSE THE OBVIOUS ALTERNATIVE WAS A GUESS. `Netbox.Prefix` first narrowed
+   *   server-side with `vrf_id=null`, the sentinel NetBox uses elsewhere for "no foreign key".
+   *   ⛔ MEASURED IN THE VENDOR'S OWN SOURCE at v4.7.0: `PrefixFilterSet.vrf_id` is a plain
+   *   `django_filters.ModelMultipleChoiceFilter` with NO `null_value`, so `'null'` is validated
+   *   against the VRF queryset, fails, and NetBox answers 400 under strict filtering. The
+   *   sentinel is real (`FILTERS_NULL_CHOICE_VALUE = 'null'`) but it is opt-in per filter, and
+   *   this one did not opt in.
+   * ★ SO THE DISCRIMINATOR MOVED INTO THIS PROCESS. It costs one page of candidates and buys a
+   *   rule that can be read, tested without a server, and cannot be wrong about a vendor's
+   *   filter semantics. Omit it when `locate` really is unique on its own.
+   */
+  readonly identifies?: (live: NetboxRow, props: Props) => boolean;
+  readonly attributes: (live: NetboxRow, props: Props) => Attributes | undefined;
+  readonly createBody: (props: Props) => NetboxBody;
+  /** ⚠️ PARTIAL BY DESIGN: NetBox updates are PATCH, so presence is not checked on this body. */
+  readonly updateBody?: (props: Props) => NetboxBody;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  /** The generated constraint table to check each body against, by endpoint key. */
+  readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
+  /** For the message `soleMatch` raises and for read-back failures. */
+  readonly describe: (props: Props) => string;
+}
+
+/** ⚠️ Only 404 folds to "absent". A 403 or a 502 is a real failure — folding it would plan a create over an existing object. */
+const absentOn404 = <A>(io: Effect.Effect<A, NetboxError, NetboxRequirements>) =>
+  io.pipe(
+    Effect.catchIf(
+      (cause): cause is NetboxError => cause instanceof NetboxError && cause.status === 404,
+      () => Effect.succeed(undefined as A),
+    ),
+  );
+
+/**
+ * ⚠️ NOT `limit=1`, AND NOT `limit=2` EITHER. One row is all a caller wants, but the page has to
+ *   be wide enough for `identifies` to see every candidate `locate` matched — a prefix that
+ *   exists in several VRFs comes back several times, and a page of two would hide the third.
+ * ★ TWENTY, AND THE NUMBER IS AN ASSERTION: a natural key matching more than twenty rows is not
+ *   a natural key. `count` is checked against it, so the failure is "your filter is too broad"
+ *   rather than a silent truncation.
+ */
+const LOCATE_PAGE = 20;
+
+const query = (pairs: readonly (readonly [string, string])[]): string =>
+  new URLSearchParams([
+    ...pairs.map(([k, v]) => [k, v] as [string, string]),
+    ['limit', String(LOCATE_PAGE)],
+  ]).toString();
+
+export const netboxOperations = <Props extends object, Attributes>(
+  spec: NetboxSpec<Props, Attributes>,
+) => {
+  const fetchLive = (props: Props) =>
+    absentOn404(
+      netbox<NetboxList<NetboxRow>>('GET', `${spec.collection}/?${query(spec.locate(props))}`),
+    ).pipe(
+      Effect.map((list) => {
+        if (list !== undefined && list.count > LOCATE_PAGE) {
+          throw new Error(
+            `${spec.describe(props)}: the locate filter matched ${String(list.count)} rows, more ` +
+              `than the ${String(LOCATE_PAGE)}-row page this reads. That is not a natural key — ` +
+              'narrow the filter rather than paging through candidates.',
+          );
+        }
+        const rows = list?.results ?? [];
+        const narrow = spec.identifies;
+        return soleMatch(
+          narrow === undefined ? rows : rows.filter((row) => narrow(row, props)),
+          spec.describe(props),
+        );
+      }),
+    );
+
+  /** ⛔ The numeric `id` is the wire path. NetBox has no update-by-natural-key. */
+  const objectPath = (live: NetboxRow): string => `${spec.collection}/${String(live['id'])}`;
+
+  const read = (props: Props) =>
+    fetchLive(props).pipe(
+      Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+    );
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.updateBody === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* fetchLive(news);
+        if (before === undefined) {
+          const body = spec.createBody(news);
+          // ⛔ GUARD BEFORE THE REQUEST, WITH PRESENCE ON. This is the only place a missing
+          //   required property can still be caught locally.
+          yield* guardBody(spec.endpoint.create, body, true);
+          yield* netbox('POST', `${spec.collection}/`, body);
+        } else if (spec.updateBody !== undefined) {
+          const mapped = spec.attributes(before, news);
+          // ⚠️ ADOPTION IS THE `mapped === undefined` CASE TOO: a row this spec cannot map is not
+          //   a row to PATCH blindly.
+          if (mapped !== undefined && !spec.matches(mapped, news)) {
+            const body = spec.updateBody(news);
+            yield* guardBody(spec.endpoint.update, body, false);
+            if (Object.keys(body).length > 0) {
+              yield* netbox('PATCH', `${objectPath(before)}/`, body);
+            }
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              `${spec.describe(news)}: the write returned no error but the object is still ` +
+                'absent. NetBox returns the object it wrote — read back rather than trusting the ' +
+                'status code.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* fetchLive(olds);
+        if (live === undefined) return;
+        yield* netbox('DELETE', `${objectPath(live)}/`);
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd NetBox object, wired once.
+ *
+ * ⚠️ `list` answers empty. NetBox index endpoints return the whole estate — tens of thousands of
+ *   rows on a real instance — so adoption stays explicit rather than sweeping.
+ */
+export const netboxHandlers = <Props extends object, Attributes extends object>(
+  spec: NetboxSpec<Props, Attributes>,
+) => {
+  const ops = netboxOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};

package/src/netbox/values.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Read-versus-write asymmetry — the bug that makes a resource never converge.
+ *
+ * 🔴 THE SHAPE IS DIFFERENT IN EACH DIRECTION AND NOTHING IN THE TYPES SAYS SO. Measured in the
+ *   NetBox 4.7.0 document: a prefix is WRITTEN with `status: "active"` and READ BACK as
+ *   `status: {value: "active", label: "Active"}`; a foreign key is written as `4` and read back
+ *   as `{id: 4, url: …, display: …}`. A `matches` that compared those directly would report drift
+ *   on every plan, for every object, forever — and each "update" would PATCH the same value back.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bool, choice, fk, text } from './values.ts';
+
+describe('a choice field reads back as an object', () => {
+  test('the object form reduces to the string a declaration writes', () => {
+    expect(choice({ label: 'Active', value: 'active' })).toBe('active');
+  });
+
+  /** ⚠️ Both directions must work: a fixture or a brief serialisation gives the bare string. */
+  test('the bare string passes through unchanged', () => {
+    expect(choice('deprecated')).toBe('deprecated');
+  });
+
+  test('anything else is empty rather than undefined, so a comparison stays total', () => {
+    expect(choice(undefined)).toBe('');
+    expect(choice(null)).toBe('');
+    expect(choice({ label: 'Active' })).toBe('');
+  });
+});
+
+describe('a foreign key reads back as a nested object', () => {
+  test('the nested object reduces to its id', () => {
+    expect(
+      fk({ display: 'HomeFlare', id: 4, url: 'https://example.invalid/api/tenancy/tenants/4/' }),
+    ).toBe(4);
+  });
+
+  test('the bare integer passes through', () => {
+    expect(fk(7)).toBe(7);
+  });
+
+  /**
+   * ⛔ `undefined`, NOT `0`. A cleared foreign key and "tenant 0" are different facts, and zero
+   *   is falsy — a `matches` written against it would treat an unset tenant as a match for every
+   *   declaration that omitted one.
+   */
+  test('an absent or unrecognisable key is undefined', () => {
+    expect(fk(null)).toBeUndefined();
+    expect(fk(undefined)).toBeUndefined();
+    expect(fk({ display: 'no id here' })).toBeUndefined();
+  });
+});
+
+describe('text and booleans', () => {
+  /** ⚠️ NetBox stores an empty string for absent text, never null — so `''` is the settled value. */
+  test('absent text settles to the empty string', () => {
+    expect(text(undefined)).toBe('');
+    expect(text(null)).toBe('');
+    expect(text('a note')).toBe('a note');
+  });
+
+  test('only a real true is true', () => {
+    expect(bool(true)).toBe(true);
+    expect(bool('true')).toBe(false);
+    expect(bool(1)).toBe(false);
+  });
+});

package/src/netbox/values.ts

@@ -0,0 +1,40 @@
+/**
+ * Reading a NetBox row into settled values.
+ *
+ * ⛔ A NETBOX READ AND A NETBOX WRITE ARE NOT THE SAME SHAPE, AND THIS IS WHERE THAT IS HANDLED.
+ *   MEASURED in the 4.7.0 document: `WritablePrefixRequest.status` is a bare string enum
+ *   (`"active"`), while `Prefix.status` on the way back is an OBJECT — `{value, label}`. A `diff`
+ *   that compared the declared string against the live object would see drift on every plan, for
+ *   every prefix, forever, and each "update" would PATCH the same value back.
+ * ⚠️ The same asymmetry holds for every choice field in NetBox (`dcim` device `status`,
+ *   `ipam` IP `role`, …). Anything read through `choice` is safe against it.
+ */
+
+/** ⚠️ `''` for absent, not `undefined` — NetBox stores an empty string, never null, for text. */
+export const text = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+export const bool = (value: unknown): boolean => value === true;
+
+/** A `{value, label}` choice object, reduced to the string a declaration writes. */
+export const choice = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object' && value !== null && 'value' in value) {
+    return text((value as { value: unknown }).value);
+  }
+  return '';
+};
+
+/**
+ * A foreign key, as the integer a declaration writes.
+ *
+ * ⚠️ IT ARRIVES AS A NESTED OBJECT ON READ AND AN INTEGER ON WRITE — `{id, url, display, …}`
+ *   versus `4`. Comparing the two directly is the same never-converges bug as `choice`.
+ */
+export const fk = (value: unknown): number | undefined => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'object' && value !== null && 'id' in value) {
+    const id = (value as { id: unknown }).id;
+    return typeof id === 'number' ? id : undefined;
+  }
+  return undefined;
+};

package/src/proxmox/api-token-form.ts

@@ -103,6 +103,11 @@ export const apiTokenSpec: PveSpec<ApiTokenProps, ApiTokenAttributes> = {
    */
   collection: (props) => `access/users/${props.userid}/token/${props.tokenid}`,
   createForm: shape,
+  /** The vendor rules both forms are checked against at plan time — resource-spec.ts. */
+  endpoint: {
+    create: 'pve:POST /access/users/{userid}/token/{tokenid}',
+    update: 'pve:PUT /access/users/{userid}/token/{tokenid}',
+  },
   /**
    * ⚠️ EXACTLY THE THREE FIELDS A PUT CAN PUT BACK, WHICH IS ALSO EXACTLY WHAT THE GET REPORTS.
    *   MEASURED, by replaying these two functions over the live GET bodies of all four token

package/src/proxmox/apply-endpoints.ts

@@ -0,0 +1,34 @@
+/**
+ * The two applies, and the vendor endpoints they publish through.
+ *
+ * ★ AN ACTION ENDPOINT IS STILL WIRED, EVEN THOUGH ITS TABLE IS EMPTY, AND THE REASON IS THE
+ *   GENERATOR RATHER THAN THE VALIDATOR. `PUT /nodes/{node}/network` and `PUT /cluster/sdn` take
+ *   no body at all — there is nothing for a length or a range to be wrong about — but
+ *   `codegen/constraints.ts` RESOLVES every key named in this package against the vendor's own
+ *   schema and STOPS when one is absent. So the key buys the thing these two families most need:
+ *   a PVE that moves, renames or withdraws the apply fails `bun run check` instead of failing an
+ *   `ifreload -a` on three nodes at once.
+ * ⚠️ AND THE LOOKUP IS NOT FREE EITHER. `constraintsFor` throws when a key has no table, so a
+ *   checkout whose generated tables were never refreshed refuses the apply with the command to
+ *   run rather than quietly doing nothing — the same defect `constraint-guard.ts` names.
+ *
+ * ⛔ NEITHER OF THESE IS A CREATE, AND NEITHER FAMILY HAS A `PveSpec`. Both write their own five
+ *   handlers (an apply is not an object — see the ⛔ in each file), so they reach the shared check
+ *   through `guardForm` by name, exactly as `pbs-datastore-endpoint.ts` does.
+ */
+import type * as Effect from 'effect/Effect';
+import { guardForm } from './constraint-guard.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/** ⚠️ `{node}` is a path segment, so this really does take no form keys at all. */
+export const NETWORK_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /nodes/{node}/network';
+
+/**
+ * ⛔ CLUSTER-WIDE. One PUT publishes every staged zone, vnet and subnet on every node; there is no
+ *   per-object apply and no pre-apply veto. `sdn-apply.ts` is the whole argument.
+ */
+export const SDN_APPLY_ENDPOINT: EndpointKey = 'pve:PUT /cluster/sdn';
+
+export const guardNetworkApply: Effect.Effect<void> = guardForm(NETWORK_APPLY_ENDPOINT, {}, true);
+
+export const guardSdnApply: Effect.Effect<void> = guardForm(SDN_APPLY_ENDPOINT, {}, true);

package/src/proxmox/ceph-daemon-form.ts

@@ -28,8 +28,30 @@
  *   the task in the PVE UI before concluding the create failed.
  *
  */
-import type { CephDaemonProps } from './ceph-daemon.ts';
-import { flag } from './values.ts';
+import type { CephDaemonAttributes, CephDaemonKind, CephDaemonProps } from './ceph-daemon.ts';
+import type { EndpointPair } from './resource-spec.ts';
+import { bool, flag, num, text } from './values.ts';
+
+/**
+ * The vendor endpoint each kind is created at, as the generated tables key it.
+ *
+ * ⛔ ONE PER KIND, NOT A `{type}` PATH. PVE registers `mds`, `mgr` and `mon` as three separate
+ *   nodes with three separate parameter schemas — `hotstandby` belongs to the first and
+ *   `mon-address` to the third — so a single key would enforce one kind's rules on all three.
+ *   That is why `PveSpec['endpoint']` admits a function of props at all.
+ * ⛔ THE STRINGS MUST STAY LITERALS. `codegen/constraints.ts` finds the endpoints to table by
+ *   SCANNING THIS PACKAGE'S TEXT, so a key assembled from `props.kind` would be tabled by
+ *   nothing and `constraintsFor` would throw on the first deploy that reached it.
+ * ⚠️ THE PARAMETER NAMES DIFFER AND ARE THE VENDOR'S OWN — `{name}`, `{id}`, `{monid}`. The
+ *   generator resolves each against the schema, so a tidied-up spelling stops the build.
+ * ⚠️ NO `update` ON ANY OF THEM: none of the three has a PUT, which is why the spec declares no
+ *   `updateForm` either.
+ */
+export const DAEMON_ENDPOINTS: Readonly<Record<CephDaemonKind, EndpointPair>> = {
+  mds: { create: 'pve:POST /nodes/{node}/ceph/mds/{name}' },
+  mgr: { create: 'pve:POST /nodes/{node}/ceph/mgr/{id}' },
+  mon: { create: 'pve:POST /nodes/{node}/ceph/mon/{monid}' },
+};
 
 /**
  * PVE defaults the id to the nodename for all three kinds, and that default is resolved HERE
@@ -82,3 +104,35 @@ export const findRow = (live: unknown, props: CephDaemonProps) =>
   (Array.isArray(live) ? live : [])
     .filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null)
     .find((row) => row['name'] === daemonId(props));
+
+/**
+ * One live row as attributes, or `undefined` — "no daemon of this kind carries this name".
+ *
+ * ★ HERE RATHER THAN IN ceph-daemon.ts FOR THE REASON THAT FILE'S SIBLING EXISTS AT ALL: the
+ *   250-line cap, and a seam that is real. It reads the row `findRow` picked out of an answer its
+ *   caller already fetched, three lines above, so the lookup and the mapping now live together
+ *   instead of a function call apart.
+ *
+ * ⚠️ `undefined` WHEN NO ROW CARRIES THIS NAME: that is how the factory learns to create.
+ */
+export const daemonAttributes = (
+  live: Record<string, unknown>,
+  props: CephDaemonProps,
+): CephDaemonAttributes | undefined => {
+  const row = findRow(live, props);
+  if (row === undefined) return undefined;
+  return {
+    addr: text(row['addr']),
+    fsName: text(row['fs_name']),
+    host: text(row['host']),
+    kind: props.kind,
+    name: daemonId(props),
+    node: props.node,
+    quorum: bool(row['quorum']),
+    rank: num(row['rank'], -1),
+    service: bool(row['service']),
+    standbyReplay: bool(row['standby_replay']),
+    state: text(row['state']),
+    version: text(row['ceph_version_short']),
+  };
+};

package/src/proxmox/ceph-daemon.ts

@@ -49,10 +49,15 @@
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { collectionPath, createForm, daemonId, daemonPath, findRow } from './ceph-daemon-form.ts';
+import {
+  DAEMON_ENDPOINTS,
+  collectionPath,
+  createForm,
+  daemonAttributes,
+  daemonPath,
+} from './ceph-daemon-form.ts';
 import { pve } from './client.ts';
 import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool, num, text } from './values.ts';
 
 /**
  * Which Ceph daemon this is. The discriminant picks the collection, the create parameters and
@@ -176,28 +181,12 @@ export const ProxmoxCephDaemon = Resource<ProxmoxCephDaemon>('Proxmox.CephDaemon
 });
 
 const handlers = pveHandlers<CephDaemonProps, CephDaemonAttributes>({
-  /** ⚠️ `undefined` when no row carries this name: that is how the factory learns to create. */
-  attributes: (live, props) => {
-    const row = findRow(live, props);
-    if (row === undefined) return undefined;
-    return {
-      addr: text(row['addr']),
-      fsName: text(row['fs_name']),
-      host: text(row['host']),
-      kind: props.kind,
-      name: daemonId(props),
-      node: props.node,
-      quorum: bool(row['quorum']),
-      rank: num(row['rank'], -1),
-      service: bool(row['service']),
-      standbyReplay: bool(row['standby_replay']),
-      state: text(row['state']),
-      version: text(row['ceph_version_short']),
-    };
-  },
+  attributes: daemonAttributes,
   /** ⛔ The ID path, not the collection — POST is registered on `{id}`, exactly like a metric server. */
   collection: daemonPath,
   createForm,
+  /** ⚠️ A function, because the kind picks the endpoint — see `DAEMON_ENDPOINTS`. */
+  endpoint: (props: CephDaemonProps) => DAEMON_ENDPOINTS[props.kind],
   /**
    * ⛔ TOTAL, AND THIS IS THE REASON THE FILE EXISTS RATHER THAN A SHORTCUT PAST WRITING IT. Every
    *   field a declaration can carry is CREATE-ONLY and unreadable — `mon-address` comes back as a

package/src/proxmox/ceph-flag.ts

@@ -181,6 +181,7 @@ const handlers = pveHandlers<CephFlagProps, CephFlagAttributes>({
    *   only body `cluster/ceph/flags` has ever documented. Nothing sends it today.
    */
   createForm: (props) => ({ [props.flag]: flag(props.value) ?? '0' }),
+  endpoint: { update: 'pve:PUT /cluster/ceph/flags/{flag}' }, // ⛔ No create: see above.
   /**
    * ⚠️ `value` IS THE ONLY THING COMPARED, AND THE LIST OF THINGS DELIBERATELY NOT COMPARED IS THE
    *   point of this resource. `flag` is props-derived (see `CephFlagAttributes`). `description`

package/src/proxmox/ceph-fs.ts

@@ -148,6 +148,7 @@ const ops = pveOperations<CephFsProps, CephFsAttributes>({
   /** ⚠️ The `{name}` path — longer than `path()`, deliberately. See the second ⛔ in the header. */
   collection: objectPath,
   createForm,
+  endpoint: { create: 'pve:POST /nodes/{node}/ceph/fs/{name}' }, // ⚠️ POSTed on the object.
   /**
    * ⛔ NOTHING IS COMPARED, AND THAT IS THE MOST DELIBERATE LINE IN THIS FILE. A CephFS has no
    *   readable, writable field: the index returns only the name and the pools behind it, and every