@homeflare/alchemy 0.15.0 → 0.19.0

package/src/linux/unit-lifecycle.ts

@@ -0,0 +1,193 @@
+/**
+ * Systemd.Unit's read / diff / reconcile / delete as plain async functions over a HostRunner, so
+ * the whole lifecycle runs against a fake host with no real systemd.
+ *
+ * ⛔ WHAT A DEPLOY DOES NOT DO — the rule this family was built around. It NEVER mass-restarts.
+ *   A unit is restarted only when THIS resource's unit file changed, or when a digest the
+ *   declaration itself listed in `restartOn` changed. A unit that is already running the content
+ *   we declare is left strictly alone: no restart, no reload, not even a `start`. An estate rebuild
+ *   must be able to reach a host that holds a vault, a UPS handler or a clock without bouncing
+ *   them, and "the deploy ran" must never be a reason anything went down.
+ * ★ THE ORDER IS WRITE, RELOAD, ENABLE, THEN START OR RESTART. systemd reads the unit file at
+ *   `daemon-reload`, so writing it while the old unit runs changes nothing yet, and a write that
+ *   fails leaves the old unit running rather than leaving nothing running.
+ * ⚠️ A FAILED START LEAVES THE UNIT DOWN. On an update the new unit file stays and state keeps the
+ *   previous digest, so the next deploy retries. On a CREATE the file this deploy wrote is removed
+ *   and systemd reloaded again: left behind, the next plan's recovery read finds a unit with no
+ *   state, reports it `Unowned`, and every later deploy demands `--adopt` for our own file.
+ * ⛔ A MASKED UNIT IS SOMEONE'S DECISION, NOT DRIFT. `systemctl mask` survives reboots and makes
+ *   start fail; unmasking here would silently overrule whoever masked it.
+ */
+import type { Diff } from 'alchemy/Diff';
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  UNIT_WRITE,
+  configDigest,
+  digestOf,
+  unitPathFor,
+  unitProblems,
+  unitText,
+} from './unit-form.ts';
+import { type UnitStatus, daemonReload, disableUnit, showUnit, stopUnit } from './systemctl.ts';
+import { attributesOf, refuse, settle } from './unit-settle.ts';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Throw every refusal at once, so one plan shows the whole list. */
+export const assertValid = (props: SystemdUnitProps, expect?: string): void => {
+  const found = unitProblems(props, expect);
+  if (found.length > 0) throw refuse(props.name, found.join('; '));
+};
+
+/** What is on the host now: the unit file's digest and systemd's view. `undefined` when neither. */
+export const readUnit = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+): Promise<SystemdUnitAttributes | undefined> => {
+  const bytes = await runner.readFile(unitPathFor(props));
+  const status = await showUnit(runner, props.name);
+  if (bytes === undefined && !status.known) return undefined;
+  return attributesOf(props, bytes === undefined ? '' : digestOf(decoder.decode(bytes)), status);
+};
+
+/** ⛔ Writing a unit file and driving systemd are root's, so refuse up front rather than mid-apply. */
+export const assertMayWrite = (runner: HostRunner, name: string): void => {
+  if (canActAsRoot(runner)) return;
+  throw refuse(
+    name,
+    'a systemd unit is root-owned and systemctl needs root. Point the runner at a destination ' +
+      'whose ssh user is root, or provide a privileged HostRunner. This provider never calls sudo.',
+  );
+};
+
+const assertUsable = (props: SystemdUnitProps, status: UnitStatus): void => {
+  if (status.loadState === 'masked' || status.unitFileState === 'masked') {
+    throw refuse(
+      props.name,
+      'is masked. If that is stale, `systemctl unmask` it deliberately, then redeploy. Nothing ' +
+        'was written.',
+    );
+  }
+};
+
+export const diffUnit = async (
+  runner: HostRunner,
+  news: SystemdUnitProps,
+  output: SystemdUnitAttributes,
+  expect?: string,
+): Promise<Diff> => {
+  assertValid(news, expect);
+  // ★ The unit's name or its directory is its identity on the host: a change is a replace, and
+  //   delete-first, because two unit files for one name cannot both be the one systemd reads.
+  if (news.name !== output.name || unitPathFor(news) !== output.unitPath) {
+    assertMayWrite(runner, news.name);
+    return { action: 'replace', deleteFirst: true };
+  }
+  const desired = digestOf(unitText(news));
+  const update = async (): Promise<Diff> => {
+    assertMayWrite(runner, news.name);
+    await runner.checkWrite?.(unitPathFor(news), UNIT_WRITE);
+    return { action: 'update' };
+  };
+  // ⛔ BOTH digests: the stored one catches a start that failed after the write landed, the live
+  //   one catches a hand edit. Either alone reports `noop` over a unit that is not what we say.
+  if (desired !== output.unitSha256) return update();
+  if (configDigest(news.restartOn) !== output.configSha256) return update();
+  const live = await readUnit(runner, news);
+  if (live === undefined || live.unitSha256 !== desired) return update();
+  if (live.enabled !== (news.enabled !== false)) return update();
+  if (live.active !== (news.started !== false)) return update();
+  // ⚠️ systemd's own word for "the file on disk is newer than what I loaded" — a write that landed
+  //   without its reload. It is drift that neither digest can see.
+  const status = await showUnit(runner, news.name);
+  return status.needDaemonReload ? update() : { action: 'noop' };
+};
+
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts): it lets such a generation take over a unit already on the host.
+ * ★ AN ADOPTED UNIT THAT ALREADY MATCHES IS NOT RESTARTED. That is the whole point of adopting one:
+ *   the estate's live services come under declaration without a single bounce.
+ */
+export const reconcileUnit = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+  output: SystemdUnitAttributes | undefined,
+  adopt = false,
+  expect?: string,
+): Promise<SystemdUnitAttributes> => {
+  assertValid(props, expect);
+  assertMayWrite(runner, props.name);
+  const path = unitPathFor(props);
+  const status = await showUnit(runner, props.name);
+  assertUsable(props, status);
+  const text = unitText(props);
+  const desired = digestOf(text);
+  const before = await runner.readFile(path);
+  const liveSha = before === undefined ? undefined : digestOf(decoder.decode(before));
+  const moved = output !== undefined && (output.name !== props.name || output.unitPath !== path);
+  const prior = moved ? undefined : output;
+  /**
+   * ⛔ A UNIT THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. Where the engine's probe never
+   *   looked — a replace's new name, a create whose props were still an Output at plan time — a
+   *   unit file already there with other content belongs to someone else, and writing ours over it
+   *   would take their service. ★ A byte-identical file is this declaration's own leftover.
+   */
+  if (
+    prior === undefined &&
+    !(adopt && output === undefined) &&
+    liveSha !== undefined &&
+    liveSha !== desired
+  ) {
+    throw refuse(
+      props.name,
+      `${path} is already on this host and is not this resource. Remove it, or declare it as a ` +
+        'new resource and deploy with --adopt.',
+    );
+  }
+  if (moved && output !== undefined) await deleteUnit(runner, output);
+  const wrote = liveSha !== desired;
+  /**
+   * ⛔ THE THREE THINGS THAT EARN A RESTART, and nothing else:
+   *   - the unit file's bytes changed (`wrote`);
+   *   - state holds an older digest than the file does — a previous deploy's write landed and its
+   *     reload or restart never ran, so systemd is still running the old content;
+   *   - systemd itself says its loaded unit is older than the file (`NeedDaemonReload`, measured);
+   *   - a digest the declaration listed in `restartOn` changed.
+   * ★ An adopted, converged unit hits none of them, which is why adoption never bounces a service.
+   */
+  const stale = prior !== undefined && prior.unitSha256 !== desired;
+  const configChanged = prior !== undefined && prior.configSha256 !== configDigest(props.restartOn);
+  if (wrote) await runner.writeFileAtomic(path, encoder.encode(text), UNIT_WRITE);
+  if (wrote || status.needDaemonReload) await daemonReload(runner);
+  const changed = wrote || stale || status.needDaemonReload;
+  return settle(runner, props, { before, changed, configChanged, desired, path, status });
+};
+
+/**
+ * Stop, disable, remove the unit file, reload. Idempotent.
+ * ⛔ DELETING THE DECLARATION STOPS THE SERVICE. That is what removing it from the stack means, and
+ *   it is why a unit that must outlive its declaration is adopted rather than deleted.
+ */
+export const deleteUnit = async (
+  runner: HostRunner,
+  output: SystemdUnitAttributes,
+): Promise<void> => {
+  assertMayWrite(runner, output.name);
+  const status = await showUnit(runner, output.name);
+  if (status.activeState === 'active' || status.activeState === 'activating') {
+    await stopUnit(runner, output.name);
+  }
+  if (status.unitFileState === 'enabled' || status.unitFileState === 'enabled-runtime') {
+    await disableUnit(runner, output.name);
+  }
+  const stat = await runner.stat(output.unitPath);
+  if (stat !== undefined) {
+    if (stat.kind !== 'file') throw refuse(output.name, `${output.unitPath} is a ${stat.kind}`);
+    await runner.removeFile(output.unitPath);
+  }
+  await daemonReload(runner);
+};

package/src/linux/unit-settle.ts

@@ -0,0 +1,110 @@
+/**
+ * The step that decides whether anything on the host actually moves: enablement, running state and
+ * — only for a real change — a restart. Split from unit-lifecycle.ts because it is the rule the
+ * whole family exists to keep, and it should be readable on its own.
+ *
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT. `changed` is set by the caller from the four
+ *   things that earn one (unit-lifecycle.ts reconcileUnit); `configChanged` is a digest the
+ *   DECLARATION itself listed. Nothing else restarts a unit — not a re-run, not an unrelated
+ *   resource in the same deploy, not `--adopt`.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  configDigest,
+  unitPathFor,
+} from './unit-form.ts';
+import {
+  type UnitStatus,
+  daemonReload,
+  disableUnit,
+  enableUnit,
+  restartUnit,
+  showUnit,
+  startUnit,
+  stopUnit,
+} from './systemctl.ts';
+
+export const refuse = (name: string, message: string): Error =>
+  new Error(`Systemd.Unit ${name}: ${message}`);
+
+export const attributesOf = (
+  props: SystemdUnitProps,
+  unitSha256: string,
+  status: UnitStatus,
+): SystemdUnitAttributes => ({
+  active: status.activeState === 'active' || status.activeState === 'activating',
+  activeState: status.activeState,
+  configSha256: configDigest(props.restartOn),
+  enabled: status.unitFileState === 'enabled' || status.unitFileState === 'enabled-runtime',
+  loadState: status.loadState,
+  name: props.name,
+  unitPath: unitPathFor(props),
+  unitSha256,
+  ...(status.unitFileState === undefined ? {} : { unitFileState: status.unitFileState }),
+});
+
+export type Settle = {
+  readonly before: Uint8Array | undefined;
+  /** The unit file or systemd's view of it changed in a way that earns a restart. */
+  readonly changed: boolean;
+  readonly configChanged: boolean;
+  readonly desired: string;
+  readonly path: string;
+  readonly status: UnitStatus;
+};
+
+/**
+ * Bring enablement and running state to the declaration, restarting ONLY for a real change.
+ * ⛔ THE RESTART CONDITION IS THE WHOLE CONTRACT: the unit file changed, or a digest the caller
+ *   listed changed. Nothing else — not a re-run, not an unrelated resource, not `--adopt`.
+ */
+export const settle = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+  step: Settle,
+): Promise<SystemdUnitAttributes> => {
+  const wantEnabled = props.enabled !== false;
+  const wantStarted = props.started !== false;
+  const isEnabled =
+    step.status.unitFileState === 'enabled' || step.status.unitFileState === 'enabled-runtime';
+  const undo = async (detail: string): Promise<never> => {
+    // ⚠️ A create that never came up leaves nothing behind; an update keeps the new file and the
+    //   old stored digest, so the next deploy retries.
+    if (step.before === undefined) {
+      await runner.removeFile(step.path).catch(() => undefined);
+      await daemonReload(runner).catch(() => undefined);
+    }
+    throw refuse(props.name, `${detail} The unit is NOT running.`);
+  };
+  try {
+    if (wantEnabled && (!isEnabled || step.changed)) await enableUnit(runner, props.name);
+    if (!wantEnabled && isEnabled) await disableUnit(runner, props.name);
+    const active = step.status.activeState === 'active' || step.status.activeState === 'activating';
+    if (!wantStarted) {
+      if (active) await stopUnit(runner, props.name);
+    } else if (!active) await startUnit(runner, props.name);
+    else if (step.changed || step.configChanged) await restartUnit(runner, props.name);
+  } catch (cause) {
+    return undo(cause instanceof Error ? cause.message : String(cause));
+  }
+  /**
+   * ⚠️ READ BACK, never echo the declaration. Returning `enabled: wantEnabled` because we called
+   *   `enable` would put a CLAIM in state instead of a reading, and the next plan would compare
+   *   the declaration against itself — so a link systemd did not actually make would never show up
+   *   as drift, in either direction.
+   */
+  const after = await showUnit(runner, props.name);
+  if (wantStarted && after.activeState !== 'active' && after.activeState !== 'activating') {
+    return undo(`systemctl reported success but the unit is ${after.activeState}.`);
+  }
+  const settled = attributesOf(props, step.desired, after);
+  if (wantEnabled && !settled.enabled) {
+    return undo(
+      `systemctl enable reported success but systemd calls the unit ` +
+        `${JSON.stringify(after.unitFileState ?? '')}, not enabled.`,
+    );
+  }
+  return settled;
+};

package/src/linux/unit.ts

@@ -0,0 +1,81 @@
+/**
+ * `Systemd.Unit` and `Systemd.Timer` — one systemd unit file and systemd's view of it, declared.
+ *
+ * - create / update — write the unit file atomically, `daemon-reload`, enable or disable, then
+ *   start, stop, or RESTART ONLY when something actually changed (unit-lifecycle.ts settle).
+ * - read — the unit file's SHA-256 plus `systemctl show` (load state, active state, enablement).
+ * - diff — the rendered digest against the stored AND the on-disk one, the declared enablement and
+ *   running state against systemd's, and systemd's own `NeedDaemonReload`.
+ * - replace — only when the unit's name or directory changes, and DELETE FIRST: two unit files for
+ *   one name cannot both be the one systemd reads.
+ * - delete — stop, disable, remove the file, reload.
+ *
+ * ⛔ A DEPLOY NEVER MASS-RESTARTS — see the ⛔ at the top of unit-lifecycle.ts. It is the property
+ *   that lets this family reach a host holding a vault, a clock or a UPS handler.
+ * ⛔ THE UNIT FILE IS NEVER A SECRET (unit-form.ts): it is 0644 and its props sit in state.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`. A unit already on the host reads as `Unowned`; adopting
+ *   one that already matches the declaration does not restart it.
+ * ★ TWO RESOURCES, ONE LIFECYCLE. A timer is a unit whose file ends `.timer` and carries a
+ *   `[Timer]` section; splitting the TYPE rather than the code means a plan says which of the two
+ *   a row is, and a `.service` declared as a timer is a refusal instead of a puzzle.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { HostRunnerService } from '../launchd/runner.ts';
+import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
+import { deleteHandler, diffHandler, readHandler, reconcileHandler } from './unit-handlers.ts';
+
+export type { SystemdUnitAttributes, SystemdUnitProps, UnitSection } from './unit-form.ts';
+
+export interface SystemdUnit extends Resource<
+  'Systemd.Unit',
+  SystemdUnitProps,
+  SystemdUnitAttributes
+> {}
+
+export interface SystemdTimer extends Resource<
+  'Systemd.Timer',
+  SystemdUnitProps,
+  SystemdUnitAttributes
+> {}
+
+export const SystemdUnit = Resource<SystemdUnit>('Systemd.Unit');
+export const SystemdTimer = Resource<SystemdTimer>('Systemd.Timer');
+
+export const SystemdUnitProvider = () =>
+  Provider.effect(
+    SystemdUnit,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return SystemdUnit.Provider.of({
+        /**
+         * ⛔ systemd's unit list is not a list of things this stack owns — it is every vendor,
+         *   package and hand-written unit on the host. Returning them would invite a nuke to stop
+         *   services nothing here declared.
+         */
+        list: () => Effect.succeed([]),
+        read: ({ olds, output }) => readHandler(runner, olds, output),
+        diff: ({ instanceId, news, output }) => diffHandler(runner, instanceId, news, output),
+        reconcile: (args) => reconcileHandler(runner, args),
+        delete: ({ output }) => deleteHandler(runner, output),
+      });
+    }),
+  );
+
+export const SystemdTimerProvider = () =>
+  Provider.effect(
+    SystemdTimer,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return SystemdTimer.Provider.of({
+        list: () => Effect.succeed([]),
+        read: ({ olds, output }) => readHandler(runner, olds, output),
+        // ★ `'timer'` is the whole difference: the same lifecycle, refusing a name that is not one.
+        diff: ({ instanceId, news, output }) =>
+          diffHandler(runner, instanceId, news, output, 'timer'),
+        reconcile: (args) => reconcileHandler(runner, args, 'timer'),
+        delete: ({ output }) => deleteHandler(runner, output),
+      });
+    }),
+  );

package/src/netbox/client.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Identity resolution, and the two ways it must refuse.
+ *
+ * ⛔ THE FAILURE THIS GUARDS IS SILENT AND SELF-RENEWING. If an ambiguous match took the first
+ *   row, adopt would bind to it, the next plan would bind to the other, and every plan after that
+ *   would report drift that is not there — while "fixing" it PATCHed one object with the other's
+ *   declaration. Failing loudly is the only outcome an operator can act on.
+ */
+import { describe, expect, test } from 'bun:test';
+import { NetboxError, apiBase, soleMatch } from './client.ts';
+
+describe('soleMatch', () => {
+  test('no candidate is absent, not an error — that is what plans a create', () => {
+    expect(soleMatch([], 'ipam/prefixes 10.0.0.0/24')).toBeUndefined();
+  });
+
+  test('exactly one candidate is the object', () => {
+    expect(soleMatch([{ id: 7 }], 'ipam/prefixes 10.0.0.0/24')).toEqual({ id: 7 });
+  });
+
+  /** ⛔ Two rows means the identity rule is wrong, and the message says which object it was. */
+  test('more than one candidate throws and names the object', () => {
+    expect(() => soleMatch([{ id: 7 }, { id: 8 }], 'ipam/prefixes 10.0.0.0/24')).toThrow(
+      /ipam\/prefixes 10\.0\.0\.0\/24 matched 2 NetBox objects/,
+    );
+  });
+});
+
+describe('the instance origin', () => {
+  /**
+   * ⛔ NO DEFAULT HOSTNAME. A published package that fell back to a loopback address would let a
+   *   consumer who forgot the variable watch every call fail against a machine that is not
+   *   theirs, rather than being told which variable is missing.
+   */
+  test('an unset or blank NETBOX_URL names the variable', () => {
+    const before = process.env['NETBOX_URL'];
+    try {
+      delete process.env['NETBOX_URL'];
+      expect(() => apiBase()).toThrow(/NETBOX_URL is not set/);
+      process.env['NETBOX_URL'] = '   ';
+      expect(() => apiBase()).toThrow(/NETBOX_URL is not set/);
+    } finally {
+      if (before === undefined) delete process.env['NETBOX_URL'];
+      else process.env['NETBOX_URL'] = before;
+    }
+  });
+
+  test('a trailing slash is stripped so paths do not double up', () => {
+    const before = process.env['NETBOX_URL'];
+    try {
+      process.env['NETBOX_URL'] = 'https://netbox.example.com/';
+      expect(apiBase()).toBe('https://netbox.example.com');
+    } finally {
+      if (before === undefined) delete process.env['NETBOX_URL'];
+      else process.env['NETBOX_URL'] = before;
+    }
+  });
+});
+
+describe('NetboxError', () => {
+  /** ⚠️ The status is on the instance, because `absentOn404` folds ONLY 404 and nothing else. */
+  test('it carries the status a caller has to branch on', () => {
+    const error = new NetboxError(404, 'GET', 'ipam/prefixes/', 'Not found.');
+    expect(error.status).toBe(404);
+    expect(error.message).toContain('NetBox GET ipam/prefixes/ -> 404');
+  });
+});

package/src/netbox/client.ts

@@ -0,0 +1,146 @@
+/**
+ * One authenticated call to the NetBox REST API at `/api`.
+ *
+ * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. NetBox is Django REST Framework using DRF's own
+ *   `TokenAuthentication`. MEASURED on this estate's own instance while it was up: `Bearer`
+ *   returns 401 and `Token` returns 200. ⛔ A wrong scheme and a wrong credential are
+ *   indistinguishable in the response, which is why this is written down rather than inferred.
+ *
+ * ⚠️ NETBOX DOES NOT WRAP A DETAIL RESPONSE THE WAY PVE DOES — a GET of one object returns the
+ *   object. A LIST, however, IS wrapped: `{count, next, previous, results: [...]}`. A caller that
+ *   treats a list like a detail sees `undefined` and calls a healthy object absent, which plans a
+ *   create over something that already exists.
+ *
+ * ⛔ THE TOKEN IS NEVER A PROP. It is read from `NETBOX_TOKEN` at call time only. Alchemy persists
+ *   attributes unencrypted; nothing stored here may be a credential.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+
+const PATH_PREFIX = '/api';
+
+/**
+ * The instance, from `NETBOX_URL`. Trailing slash stripped.
+ *
+ * ⛔ NO DEFAULT HOSTNAME AND NO DEFAULT PORT. A published package that fell back to a loopback
+ *   address would let a consumer who forgot the variable watch every call fail against a machine
+ *   that is not theirs, instead of being told which variable is missing.
+ * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to whatever
+ *   the first isolate saw.
+ */
+export const apiBase = (): string => {
+  const raw = process.env['NETBOX_URL'];
+  if (raw === undefined || raw.trim() === '') {
+    throw new Error(
+      'NETBOX_URL is not set. Point it at your NetBox instance, e.g. https://netbox.example.com',
+    );
+  }
+  return raw.trim().replace(/\/$/, '');
+};
+
+export class NetboxError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    detail: string,
+  ) {
+    super(`NetBox ${method} ${path} -> ${String(status)}: ${detail}`);
+    this.name = 'NetboxError';
+  }
+}
+
+const token = (): Effect.Effect<string, NetboxError> =>
+  Effect.gen(function* () {
+    const raw = process.env['NETBOX_TOKEN'];
+    if (raw === undefined || raw.trim() === '') {
+      return yield* Effect.fail(
+        new NetboxError(
+          0,
+          'GET',
+          '',
+          'NETBOX_TOKEN is unset. Mint a scoped token and export it — never store it in Alchemy props.',
+        ),
+      );
+    }
+    return raw.trim();
+  });
+
+/** A NetBox list response. ⚠️ Paginated: `next` is a URL, not a cursor to guess at. */
+export interface NetboxList<T> {
+  readonly count: number;
+  readonly next: string | null;
+  readonly results: readonly T[];
+}
+
+export type NetboxRow = Record<string, unknown>;
+
+/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
+export const netbox = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* token();
+    const url = `${apiBase()}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    /**
+     * ★ THROUGH `HttpClient`, NOT THE GLOBAL `fetch` — the idiom Alchemy's own providers follow.
+     *   It buys a typed error channel, interruption when a plan is cancelled, the runtime's
+     *   tracing, and a client a test can replace without monkey-patching a global.
+     */
+    const client = yield* HttpClient.HttpClient;
+    /**
+     * ⛔ THE CONTENT TYPE GOES ON `bodyText`, NOT IN THE HEADER MAP. `bodyText(s)` with no second
+     *   argument sets `text/plain` and OVERWRITES a `Content-Type` set by `setHeaders`, because it
+     *   is piped afterwards. That shipped `@homeflare/alchemy/forgejo` unable to write at all —
+     *   every create and update in the package, broken identically, for as long as the only
+     *   credential on the shelf was read-only and so never reached a request body.
+     */
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: 'application/json',
+        Authorization: `Token ${credential}`,
+      }),
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(Effect.mapError((cause) => new NetboxError(0, method, path, String(cause))));
+    // ⛔ Status first, body once — a NetBox error body is JSON but a reverse proxy's 502 is not.
+    //   ⚠️ AND A 502 IS THE EXPECTED SYMPTOM WHEN NETBOX IS DOWN BUT ITS FRONT DOOR IS UP, which
+    //   is the state the reference instance has been in since 2026-09-14. Folding it to "absent"
+    //   would plan a create for every object that already exists.
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(
+        new NetboxError(response.status, method, path, detail.slice(0, 300)),
+      );
+    }
+    // ⚠️ 204 AND AN EMPTY BODY ARE REAL: a DELETE answers no content, and parsing an empty body
+    //   throws. Read the text once and parse only when there is something to parse.
+    const text = yield* response.text.pipe(
+      Effect.mapError((cause) => new NetboxError(0, method, path, String(cause))),
+    );
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });
+
+/**
+ * The single row a filtered list returns, or `undefined`.
+ *
+ * ⛔ MORE THAN ONE MATCH IS A DEFECT, NOT A REASON TO TAKE THE FIRST. A `locate` filter that is
+ *   not unique would let adopt bind to whichever row NetBox happened to order first, and the next
+ *   plan would bind to the other one and report drift that is not there.
+ */
+export const soleMatch = <T>(rows: readonly T[], describe: string): T | undefined => {
+  if (rows.length > 1) {
+    throw new Error(
+      `${describe} matched ${String(rows.length)} NetBox objects. An object's identity must be ` +
+        'unique; narrow it (the VRF, the site, the tenant) rather than taking the first row.',
+    );
+  }
+  return rows[0];
+};

package/src/netbox/constraint-guard.ts

@@ -0,0 +1,57 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ★ ONE FILE BETWEEN THE PROVIDERS AND THE GENERATED DATA, so `resource.ts` gains three lines
+ *   rather than an import of the generated module and a merge, and so a family that writes its
+ *   own handlers reaches the same check by the same name.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK. Silently passing would put us
+ *   back where this started: a declaration nothing checked, and a plan that says so in no way at
+ *   all. The generator resolves every key in its source scan against the vendor document, so a
+ *   key that is absent here means the tables were not regenerated — which the message says.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type EndpointConstraints,
+  type EndpointKey,
+  type NetboxBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+import { NETBOX_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { NETBOX_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = NETBOX_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/netbox.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+/** Every vendor rule this body breaks. Pure — a test calls it with a literal body. */
+export const bodyViolations = (
+  key: EndpointKey,
+  body: NetboxBody,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), body, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition: there is no retry and no fallback that makes a
+ *   201-character description legal.
+ */
+export const guardBody = (
+  key: EndpointKey | undefined,
+  body: NetboxBody,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = bodyViolations(key, body, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });