@homeflare/alchemy 0.14.0 → 0.19.0

package/src/netbox/constraints.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The constraint reader over a JSON body — and the four ways a naive one gets it wrong.
+ *
+ * ★ EVERY RULE EXERCISED HERE COMES FROM THE GENERATED TABLE, not a literal invented in this
+ *   file, wherever a real endpoint states it. A test that made up its own `maxLength` would pass
+ *   forever while the committed table said something else.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bodyViolations, constraintsFor } from './constraint-guard.ts';
+import { violations } from './constraints.ts';
+
+const CREATE = 'netbox:POST /api/ipam/prefixes/';
+const UPDATE = 'netbox:PATCH /api/ipam/prefixes/{id}/';
+
+describe('the generated table is the one being read', () => {
+  test('the prefix create table carries NetBox 4.7.0 own rules', () => {
+    const table = constraintsFor(CREATE);
+    expect(table['prefix']?.required).toBe(true);
+    expect(table['description']?.maxLength).toBe(200);
+    expect(table['status']?.enum).toEqual(['container', 'active', 'reserved', 'deprecated']);
+  });
+
+  /** ⛔ An unknown key is a defect: the tables were not regenerated, and silence would hide it. */
+  test('an endpoint nobody generated throws rather than passing everything', () => {
+    expect(() => constraintsFor('netbox:POST /api/dcim/devices/')).toThrow(
+      /no vendor constraint table/,
+    );
+  });
+});
+
+describe('what it refuses', () => {
+  test('a description one character over the vendor limit', () => {
+    const found = bodyViolations(
+      CREATE,
+      { description: 'x'.repeat(201), prefix: '10.0.0.0/24' },
+      true,
+    );
+    expect(found).toEqual(['description: at most 200 characters']);
+  });
+
+  test('exactly the limit is accepted', () => {
+    expect(
+      bodyViolations(CREATE, { description: 'x'.repeat(200), prefix: '10.0.0.0/24' }, true),
+    ).toEqual([]);
+  });
+
+  /**
+   * ⚠️ `[...value].length`, NOT `value.length`. An emoji is two UTF-16 code units and ONE
+   *   character; Django counts characters. Counting code units would refuse a description NetBox
+   *   accepts — rejecting a legal value at plan time being the failure worse than the 400.
+   */
+  test('a 200-character description made of astral characters is accepted', () => {
+    const found = bodyViolations(
+      CREATE,
+      { description: '🌐'.repeat(200), prefix: '10.0.0.0/24' },
+      true,
+    );
+    expect(found).toEqual([]);
+  });
+
+  test('a status outside the vendor enum', () => {
+    const found = bodyViolations(CREATE, { prefix: '10.0.0.0/24', status: 'retired' }, true);
+    expect(found).toEqual(['status: must be one of container, active, reserved, deprecated']);
+  });
+});
+
+describe('presence is a create-only rule', () => {
+  /** ⛔ A PATCH is deliberately partial; requiring presence would refuse every ordinary edit. */
+  test('a missing required property is refused on create and allowed on update', () => {
+    expect(bodyViolations(CREATE, { status: 'active' }, true)).toEqual(['prefix: required']);
+    expect(bodyViolations(UPDATE, { status: 'active' }, false)).toEqual([]);
+  });
+
+  /**
+   * ⚠️ `null` IS A VALUE, NOT AN ABSENCE. NetBox clears a nullable foreign key with an explicit
+   *   null, so a presence check that used `value === undefined` would call it missing.
+   */
+  test('an explicit null satisfies presence and trips no string rule', () => {
+    expect(bodyViolations(CREATE, { prefix: null }, true)).toEqual([]);
+  });
+});
+
+describe('a JSON body is not a form, and that changes the checks', () => {
+  /**
+   * ⛔ THE REASON THIS READER IS NOT THE PROXMOX ONE. `Number(false)` is 0, so a body that
+   *   coerced its values would pass a boolean straight through a `minimum: 0` and report nothing.
+   */
+  test('a boolean is never coerced into a numeric bound', () => {
+    const table = { count: { minimum: 1, type: 'integer' } } as const;
+    expect(violations(table, { count: false })).toEqual([]);
+    expect(violations(table, { count: 0 })).toEqual(['count: at least 1']);
+  });
+
+  test('an empty string is not treated as zero', () => {
+    const table = { count: { minimum: 0, type: 'integer' } } as const;
+    expect(violations(table, { count: '' })).toEqual([]);
+  });
+
+  /** ⚠️ An array is a repeated value — tags and every many-to-many — so each element is checked. */
+  test('every element of an array faces the same rule', () => {
+    const table = { names: { maxLength: 3, type: 'string' } } as const;
+    expect(violations(table, { names: ['ok', 'toolong', 'alsotoolong'] })).toEqual([
+      'names: at most 3 characters',
+      'names: at most 3 characters',
+    ]);
+  });
+
+  /** ⚠️ The table carries the CONSTRAINED properties, not every property. */
+  test('a key the table does not mention is not an error', () => {
+    expect(bodyViolations(CREATE, { prefix: '10.0.0.0/24', vrf: 4, whatever: 'x' }, true)).toEqual(
+      [],
+    );
+  });
+});

package/src/netbox/constraints.ts

@@ -0,0 +1,152 @@
+/**
+ * NetBox's own rules, checked here, before the request is built.
+ *
+ * 🔴 THE INCIDENT THIS PATTERN EXISTS FOR, 2026-09-22 (Proxmox, not NetBox). `homeflare-proxmox`'s
+ *   first `deploy:pbs` adopted ten objects and then failed its one create:
+ *   `comment: value may only be 128 characters long`. Half a deploy in, on the server, from a
+ *   limit the vendor publishes in its own schema and the generated type did not carry. Plan was
+ *   green, `bun run check` was green, the adopt verifier was green. ★ NetBox gets the same
+ *   treatment BEFORE its first write rather than after it.
+ *
+ * ★ SO THE TABLE IS GENERATED AND THIS FILE IS THE READER. `generated/constraints/*` is emitted
+ *   from NetBox's own OpenAPI document by `bun codegen/netbox.ts`; nothing here is hand-typed,
+ *   because a hand-typed limit is tribal knowledge that does not run.
+ *
+ * ⛔ A SEPARATE READER FROM `../proxmox/constraints.ts`, AND IT IS NOT DUPLICATION. That one
+ *   checks a `PveForm` — every value already a string, because PVE takes form encoding. A NetBox
+ *   body is JSON: a number stays a number, a boolean stays a boolean, a foreign key is an
+ *   integer, and `String(value)` on any of them would make `minimum: 0` pass for `false` and
+ *   `maxLength` meaningless. Sharing one reader would mean stringifying at the door, which is
+ *   exactly the mangling the Proxmox version's own ⛔ warns about.
+ *
+ * ⚠️ WHAT IT DELIBERATELY DOES NOT ENFORCE, so nobody reads a green plan as more than it is:
+ *   - a `format` NAME (`uri`, `email`, `date-time`): a validator DRF implements server-side.
+ *     Recorded, never checked.
+ *   - a pattern the generator could not carry faithfully (codegen/py-pattern.ts). Recorded
+ *     verbatim as `patternSource`, never checked.
+ *   - UNIQUENESS, VRF containment, custom-field validators, and every other rule that lives in
+ *     Django rather than in the schema. Those still arrive as a server-side 400.
+ *   Each is a fact in the table rather than a guess, which is the rule this follows: if the
+ *   vendor did not state it, it is not enforced and the table says so.
+ */
+
+export interface ParamConstraint {
+  readonly type?: string;
+  /** From the schema's `required` array. ⚠️ Checked on CREATE only — see `violations`. */
+  readonly required?: boolean;
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly enum?: readonly string[];
+  /** A JavaScript-safe translation. Absent when Python's dialect could not be carried over. */
+  readonly pattern?: string;
+  /** The vendor's own spelling, always — what a violation message quotes, and the audit trail. */
+  readonly patternSource?: string;
+  /** DRF's server-side validator name. Recorded so a reader knows what is NOT checked here. */
+  readonly format?: string;
+  readonly default?: string;
+}
+
+export type EndpointConstraints = Readonly<Record<string, ParamConstraint>>;
+
+/** `netbox:POST /api/ipam/prefixes/` — exactly how the generated tables key an endpoint. */
+export type EndpointKey = string;
+
+/** A NetBox request body: JSON, with the types the schema declares. */
+export type NetboxBody = Record<string, unknown>;
+
+export interface ViolationOptions {
+  /**
+   * Check that every schema-required property is present.
+   *
+   * ⛔ CREATE ONLY. A NetBox update is a PATCH and is deliberately PARTIAL — it carries the fields
+   *   that changed and nothing else — so requiring presence there would refuse every ordinary
+   *   edit.
+   */
+  readonly presence?: boolean;
+}
+
+/**
+ * ⚠️ `[...value].length`, NOT `value.length`. Django counts characters (Python `len` on a `str`
+ *   counts code points); JavaScript counts UTF-16 code units, so an emoji in a description counts
+ *   twice and a 200-character limit would refuse a description NetBox accepts. Rejecting a legal
+ *   value at plan time is the one failure mode worse than the server 400 this replaces.
+ */
+const lengthOf = (value: string): number => [...value].length;
+
+const checkString = (name: string, value: string, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (rule.maxLength !== undefined && lengthOf(value) > rule.maxLength) {
+    out.push(`${name}: at most ${String(rule.maxLength)} characters`);
+  }
+  if (rule.minLength !== undefined && lengthOf(value) < rule.minLength) {
+    out.push(`${name}: at least ${String(rule.minLength)} characters`);
+  }
+  if (rule.enum !== undefined && !rule.enum.includes(value)) {
+    out.push(`${name}: must be one of ${rule.enum.join(', ')}`);
+  }
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern).test(value)) {
+    out.push(`${name}: must match ${rule.patternSource ?? rule.pattern}`);
+  }
+  return out;
+};
+
+/**
+ * ⛔ BOUNDS ARE CHECKED ONLY ON A REAL NUMBER, NEVER ON A COERCED ONE. `Number(false)` is 0 and
+ *   `Number('')` is 0, so coercing would silently pass a boolean and an empty string through a
+ *   `minimum: 0`. A NetBox body carries real numbers; anything else is a type error upstream.
+ */
+const checkNumber = (name: string, value: number, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (!Number.isFinite(value)) return out;
+  if (rule.minimum !== undefined && value < rule.minimum) {
+    out.push(`${name}: at least ${String(rule.minimum)}`);
+  }
+  if (rule.maximum !== undefined && value > rule.maximum) {
+    out.push(`${name}: at most ${String(rule.maximum)}`);
+  }
+  return out;
+};
+
+const checkValue = (name: string, value: unknown, rule: ParamConstraint): readonly string[] => {
+  if (typeof value === 'string') return checkString(name, value, rule);
+  if (typeof value === 'number') return checkNumber(name, value, rule);
+  return [];
+};
+
+/**
+ * Every vendor rule this body breaks, in the order the properties are declared. Pure: no network,
+ * no clock, no environment — so `diff` can call it and a test can call it with a literal.
+ *
+ * ⚠️ A KEY THE TABLE DOES NOT MENTION IS NOT AN ERROR. The table carries the constrained
+ *   properties, not every property, and a body may legitimately send an unconstrained one.
+ * ⚠️ `null` IS A VALUE, NOT AN ABSENCE. NetBox uses explicit `null` to CLEAR a nullable foreign
+ *   key, so it must not trip the presence check — and no string or number rule applies to it.
+ */
+export const violations = (
+  table: EndpointConstraints,
+  body: NetboxBody,
+  options: ViolationOptions = {},
+): readonly string[] => {
+  const out: string[] = [];
+  for (const [name, rule] of Object.entries(table)) {
+    if (!Object.hasOwn(body, name)) {
+      if (options.presence === true && rule.required === true) out.push(`${name}: required`);
+      continue;
+    }
+    const value = body[name];
+    // ⚠️ AN ARRAY IS A REPEATED VALUE (tags, and every many-to-many), so every element faces the
+    //   same rule rather than the array being skipped as "not a scalar".
+    for (const item of Array.isArray(value) ? value : [value]) {
+      out.push(...checkValue(name, item, rule));
+    }
+  }
+  return out;
+};
+
+/** The message a plan dies with. ⛔ Names the endpoint, because the rule belongs to the vendor. */
+export const refusal = (endpoint: EndpointKey, found: readonly string[]): string =>
+  `${endpoint} would be rejected by the vendor:\n  - ${found.join('\n  - ')}\n` +
+  "These are NetBox's own limits, read from its published OpenAPI document " +
+  '(packages/alchemy/src/netbox/generated/constraints). Fix the declaration.';

package/src/netbox/generated/constraints/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Every generated NetBox constraint table, merged — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/netbox.ts
+ *
+ * ⚠️ EVERY KEY IS PREFIXED `netbox:` FOR THE SAME REASON THE PROXMOX TABLES ARE PREFIXED. One
+ *   estate runs several vendors and the reader is shared; an unprefixed `POST /api/…` would be
+ *   one vendor away from colliding.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+import { NETBOX_IPAM_CONSTRAINTS } from './netbox-ipam.ts';
+
+export const NETBOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  ...NETBOX_IPAM_CONSTRAINTS,
+};
+
+/**
+ * sha256 of the merged table, truncated.
+ *
+ * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
+ *   changing a 200 to a 201 by hand is. `tests/netbox-manifest.test.ts` recomputes it.
+ */
+export const NETBOX_CONSTRAINTS_DIGEST = '1de1cebe7491d94f';

package/src/netbox/generated/constraints/netbox-ipam.ts

@@ -0,0 +1,32 @@
+/**
+ * Generated NetBox REST API (OpenAPI 3.0.3) request-body constraints for `/api/ipam` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/netbox.ts
+ * Manifest entry: `netbox-openapi` — NetBox REST API (OpenAPI 3.0.3) 4.7.0
+ *   sha256 be7f971179b1d6ba, vendor repository, pinned to the release tag
+ *   contrib/openapi.json in netbox-community/netbox, at tag v4.7.0
+ *
+ * 2 of this product's 949 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Python's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ A FOREIGN KEY CARRIES ONLY ITS TYPE. `tenant`, `vlan`, `role` and friends are
+ *   `integer|object` in the schema, and the related object's own rules do not govern them.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const NETBOX_IPAM_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "netbox:PATCH /api/ipam/prefixes/{id}/": {
+    "description": {"maxLength":200,"type":"string"},
+    "prefix": {"minLength":1,"type":"string"},
+    "status": {"enum":["container","active","reserved","deprecated"],"type":"string"},
+  },
+  "netbox:POST /api/ipam/prefixes/": {
+    "description": {"maxLength":200,"type":"string"},
+    "prefix": {"minLength":1,"required":true,"type":"string"},
+    "status": {"enum":["container","active","reserved","deprecated"],"type":"string"},
+  },
+};

package/src/netbox/index.ts

@@ -0,0 +1,34 @@
+/**
+ * NetBox providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
+ *   the symbols a real stack consumes; the rest of the files are internals a provider needs but a
+ *   consumer should not depend on. An `export *` here would publish every helper as API and make
+ *   the next refactor a breaking change.
+ * ★ The constraint reader IS exported, because a consumer writing its own family needs the same
+ *   guard — and because a table nobody can reach is a table nobody uses.
+ */
+export { NetboxError, apiBase } from './client.ts';
+export {
+  NETBOX_CONSTRAINTS,
+  bodyViolations,
+  constraintsFor,
+  guardBody,
+} from './constraint-guard.ts';
+export {
+  type EndpointConstraints,
+  type EndpointKey,
+  type NetboxBody,
+  type ParamConstraint,
+  refusal,
+  violations,
+} from './constraints.ts';
+export { NETBOX_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
+export {
+  NetboxPrefix,
+  NetboxPrefixProvider,
+  type PrefixAttributes,
+  type PrefixProps,
+  type PrefixStatus,
+} from './prefix.ts';
+export { type NetboxRequirements, type NetboxSpec, netboxHandlers } from './resource.ts';

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)
+  );
+};