@homeflare/alchemy 0.15.0 → 0.19.1

package/src/netbox/prefix-form.test.ts

@@ -0,0 +1,127 @@
+/**
+ * What an undeclared property means — and the day it meant "delete that".
+ *
+ * 🔴 THE BUG THIS PINS, FOUND BY REVIEW RATHER THAN BY AN INCIDENT. `Netbox.Prefix` shipped
+ *   sending `description: ''` whenever the prop was absent. On a create that is invisible. ⛔ On
+ *   an ADOPT it is data loss: NetBox is the estate's record of DECISIONS, and a prefix's
+ *   description is usually the only written trace of why that range exists. The first deploy that
+ *   adopted one would have PATCHed it to empty, and the plan would have read `update` — a diff
+ *   that looks like converging a declaration and is really deleting a sentence.
+ *
+ * ★ THE TELL WAS THE INCONSISTENCY, not a failure. Foreign keys were already omitted when
+ *   undeclared, with a comment saying why; free text was not. Two fields, the same hazard, two
+ *   answers — that gap is the defect.
+ */
+import { describe, expect, test } from 'bun:test';
+import { prefixBody, prefixMatches } from './prefix-form.ts';
+import type { PrefixAttributes } from './prefix.ts';
+
+const live = (over: Partial<PrefixAttributes> = {}): PrefixAttributes => ({
+  comments: '',
+  description: '',
+  isPool: false,
+  markUtilized: false,
+  prefix: '10.0.0.0/24',
+  prefixId: 1,
+  status: 'active',
+  tenant: undefined,
+  vlan: undefined,
+  vrf: undefined,
+  ...over,
+});
+
+describe('an undeclared field is not an instruction to clear it', () => {
+  test('the body omits description and comments entirely when they are absent', () => {
+    const body = prefixBody({ prefix: '10.0.0.0/24' });
+    expect(Object.hasOwn(body, 'description')).toBe(false);
+    expect(Object.hasOwn(body, 'comments')).toBe(false);
+  });
+
+  /** ⛔ The regression itself: a prefix carrying a human's note must read as converged. */
+  test('a live description nobody declared does NOT count as drift', () => {
+    expect(
+      prefixMatches(live({ description: 'retired 2026-09-14, do not reuse' }), {
+        prefix: '10.0.0.0/24',
+      }),
+    ).toBe(true);
+  });
+
+  test('the same is true of comments and of an optional foreign key', () => {
+    const attributes = live({ comments: 'see the retirement doc', tenant: 4, vlan: 9 });
+    expect(prefixMatches(attributes, { prefix: '10.0.0.0/24' })).toBe(true);
+  });
+
+  /**
+   * ⚠️ THE COST, STATED: prose is cleared by declaring it empty, on purpose. That is the readable
+   *   way to say a destructive thing, and it still reaches the wire.
+   */
+  test('an explicitly empty description IS sent and IS compared', () => {
+    expect(prefixBody({ description: '', prefix: '10.0.0.0/24' })['description']).toBe('');
+    expect(
+      prefixMatches(live({ description: 'a note' }), { description: '', prefix: '10.0.0.0/24' }),
+    ).toBe(false);
+  });
+});
+
+describe('a field NetBox itself defaults is still settled', () => {
+  /**
+   * ★ THE LINE BETWEEN THE TWO GROUPS. `status`, `is_pool` and `mark_utilized` have vendor
+   *   defaults in the schema, so omitting one genuinely means "the default" and settling it says
+   *   what NetBox would have done anyway. Free text has no such default.
+   */
+  test('status, is_pool and mark_utilized are always on the wire', () => {
+    const body = prefixBody({ prefix: '10.0.0.0/24' });
+    expect(body['status']).toBe('active');
+    expect(body['is_pool']).toBe(false);
+    expect(body['mark_utilized']).toBe(false);
+  });
+
+  test('a live status that differs from the settled default IS drift', () => {
+    expect(prefixMatches(live({ status: 'reserved' }), { prefix: '10.0.0.0/24' })).toBe(false);
+    expect(
+      prefixMatches(live({ status: 'reserved' }), {
+        prefix: '10.0.0.0/24',
+        status: 'reserved',
+      }),
+    ).toBe(true);
+  });
+
+  /** ★ The move this resource exists for: recording a retirement as a declaration. */
+  test('declaring deprecated is drift against an active prefix, and converges', () => {
+    const props = { prefix: '10.1.1.0/24', status: 'deprecated' } as const;
+    expect(prefixMatches(live({ prefix: '10.1.1.0/24' }), props)).toBe(false);
+    expect(prefixBody(props)['status']).toBe('deprecated');
+    expect(prefixMatches(live({ prefix: '10.1.1.0/24', status: 'deprecated' }), props)).toBe(true);
+  });
+});
+
+/**
+ * ⛔ THE INVARIANT THAT KEEPS THE TWO IN STEP. A field compared but never sent produces a plan
+ *   that says `update` forever: the PATCH omits it, so the next read is unchanged.
+ */
+describe('body and matches agree about which fields are ours', () => {
+  test('every field matches compares as optional is one the body sends when declared', () => {
+    const declared = prefixBody({
+      comments: 'c',
+      description: 'd',
+      prefix: '10.0.0.0/24',
+      tenant: 4,
+      vlan: 9,
+    });
+    for (const key of ['description', 'comments', 'tenant', 'vlan']) {
+      expect(Object.hasOwn(declared, key)).toBe(true);
+    }
+  });
+
+  test('an undeclared optional is neither sent nor compared', () => {
+    const bare = prefixBody({ prefix: '10.0.0.0/24' });
+    for (const key of ['description', 'comments', 'tenant', 'vlan', 'vrf']) {
+      expect(Object.hasOwn(bare, key)).toBe(false);
+    }
+    expect(
+      prefixMatches(live({ comments: 'x', description: 'y', tenant: 1, vlan: 2 }), {
+        prefix: '10.0.0.0/24',
+      }),
+    ).toBe(true);
+  });
+});

package/src/netbox/prefix-form.ts

@@ -0,0 +1,84 @@
+/**
+ * The wire body for a `Netbox.Prefix`, and the comparison that decides whether it needs writing.
+ *
+ * ★ EXTRACTED SO IT CAN BE TESTED WITHOUT A SERVER. `body` and `matches` are where a NetBox
+ *   resource either converges or quietly destroys something, and both are pure functions of the
+ *   props — so they belong somewhere a test can call them with a literal, the way the Proxmox
+ *   families keep their `*-form.ts` beside the resource.
+ */
+import type { PrefixAttributes, PrefixProps, PrefixStatus } from './prefix.ts';
+
+/** ⚠️ NetBox's own default when the property is omitted, copied from the schema, not assumed. */
+const DEFAULT_STATUS: PrefixStatus = 'active';
+
+/**
+ * The fields an undeclared prop still settles, because NetBox itself would.
+ *
+ * ⛔ FREE TEXT IS NOT IN HERE, AND THE LINE IS NOT COSMETIC. `status`, `is_pool` and
+ *   `mark_utilized` have vendor defaults in the schema — omitting one genuinely means "the
+ *   default", so settling it says what NetBox would have done anyway. `description` and
+ *   `comments` have no such default: the schema's `''` is the absence of a value, not a decision.
+ *   Treating "I did not mention it" as "set it to empty" is how a declaration that says nothing
+ *   about prose ERASES prose somebody wrote.
+ */
+export const settled = (props: PrefixProps) => ({
+  isPool: props.isPool ?? false,
+  markUtilized: props.markUtilized ?? false,
+  status: props.status ?? DEFAULT_STATUS,
+});
+
+/**
+ * ⛔ THE BODY IS BUILT ONCE AND USED FOR BOTH CREATE AND UPDATE, so a field cannot be settable on
+ *   one path and forgotten on the other — the failure mode that makes a resource converge on
+ *   create and drift forever after.
+ *
+ * 🔴 AN UNDECLARED FIELD THAT NETBOX DOES NOT DEFAULT IS OMITTED, NEVER SENT EMPTY OR NULL. This
+ *   resource shipped sending `description: ''` whenever the prop was absent. On a fresh create
+ *   that is invisible — the field was empty anyway. ⛔ ON AN ADOPT IT IS DATA LOSS: NetBox is the
+ *   estate's record of DECISIONS, so the description on an existing prefix is usually the only
+ *   written trace of why that range exists, and the first deploy that adopted it would have
+ *   PATCHed it to empty. `matches` would have reported drift, the plan would have said `update`,
+ *   and the diff would have read as converging a declaration rather than deleting a sentence.
+ * ★ THE TELL WAS ALREADY IN THIS FILE: foreign keys were omitted for exactly this reason while
+ *   free text was not. An inconsistency between two fields with the same hazard is the bug.
+ * ⚠️ THE COST IS THAT PROSE CANNOT BE CLEARED BY OMISSION — clearing it is `description: ''`,
+ *   written on purpose, which is the readable way to say a destructive thing.
+ */
+export const prefixBody = (props: PrefixProps): Record<string, unknown> => {
+  const fixed = settled(props);
+  const out: Record<string, unknown> = {
+    is_pool: fixed.isPool,
+    mark_utilized: fixed.markUtilized,
+    prefix: props.prefix,
+    status: fixed.status,
+  };
+  if (props.description !== undefined) out['description'] = props.description;
+  if (props.comments !== undefined) out['comments'] = props.comments;
+  if (props.vrf !== undefined) out['vrf'] = props.vrf;
+  if (props.tenant !== undefined) out['tenant'] = props.tenant;
+  if (props.vlan !== undefined) out['vlan'] = props.vlan;
+  return out;
+};
+
+/**
+ * Whether the live object already says what the declaration says.
+ *
+ * ⛔ EVERY FIELD `prefixBody` OMITS IS ALSO UNCOMPARED HERE, AND THE TWO MUST MOVE TOGETHER. A
+ *   comparison against a field the body does not send reports drift no write can fix: the plan
+ *   says `update`, the PATCH omits the field, and the next plan says `update` again — forever.
+ *   An undeclared prop means "not mine", in both directions.
+ * ⚠️ `vrf` IS ABSENT ON PURPOSE. It is identity, not settings: `identifies` has already proved
+ *   this row is in the declared VRF, and a prefix's VRF cannot be edited into another one here.
+ */
+export const prefixMatches = (attributes: PrefixAttributes, props: PrefixProps): boolean => {
+  const fixed = settled(props);
+  return (
+    attributes.status === fixed.status &&
+    attributes.isPool === fixed.isPool &&
+    attributes.markUtilized === fixed.markUtilized &&
+    (props.description === undefined || attributes.description === props.description) &&
+    (props.comments === undefined || attributes.comments === props.comments) &&
+    (props.tenant === undefined || attributes.tenant === props.tenant) &&
+    (props.vlan === undefined || attributes.vlan === props.vlan)
+  );
+};

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