@homeflare/alchemy 0.1.0

package/src/proxmox/lxc.ts

@@ -0,0 +1,117 @@
+/**
+ * `Proxmox.Lxc` — a container, declared. This is what the estate's provision credential exists for.
+ *
+ * ★ `hf-provision@pve` HOLDS EXACTLY THE ROLE THIS NEEDS, and nothing more: `LXCProvisioner` on `/`
+ *   grants VM.Allocate, VM.Audit, VM.Config.{CPU,Disk,HWType,Memory,Network,Options},
+ *   VM.PowerMgmt, Datastore.AllocateSpace, Datastore.Audit, SDN.Use, Sys.Audit. Read that list as a
+ *   specification: the credential was scoped to provision containers and to do nothing else.
+ *
+ * ⛔ `vmid` IS THE PRIMARY KEY AND IT IS CLUSTER-WIDE, not per node. Two resources declaring the
+ *   same vmid on different nodes are the same object, and PVE will refuse the second with
+ *   "already exists". It is required rather than allocated here: letting the provider pick the next
+ *   free id would make the identity of a container depend on the order plans happened to run in.
+ *
+ * ⚠️ MOST FIELDS ARE CREATE-TIME. `ostemplate` and `storage` are consumed when the rootfs is built
+ *   and are not readable back afterwards, so they are deliberately NOT compared in `matches` --
+ *   a provider that diffed them would report an update on every plan, forever. What is compared is
+ *   what PVE will actually tell you about a running container.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { num } from './values.ts';
+
+export interface LxcProps extends WithTarget {
+  /** Which node hosts it. Moving a container between nodes is a migration, not an update. */
+  node: string;
+  /** ⛔ CLUSTER-WIDE primary key. Required, never auto-allocated — see the ⛔ above. */
+  vmid: number;
+  /** e.g. `local:vztmpl/debian-13-standard_13.0-1_amd64.tar.zst`. Create-time only. */
+  ostemplate: string;
+  /** Storage for the rootfs, e.g. `local-zfs`. Create-time only. */
+  storage: string;
+  hostname?: string;
+  /** MiB. Mutable. */
+  memory?: number;
+  cores?: number;
+  /** e.g. `name=eth0,bridge=vmbr0,ip=dhcp`. Mutable. */
+  net0?: string;
+  /** Start on boot. Mutable. */
+  onboot?: boolean;
+}
+
+export interface LxcAttributes {
+  vmid: number;
+  node: string;
+  hostname: string;
+  memory: number;
+  cores: number;
+  onboot: boolean;
+  /** `running` | `stopped`. Reported, never declared — power state is not configuration. */
+  status: string;
+}
+
+export interface ProxmoxLxc extends Resource<
+  'Proxmox.Lxc',
+  LxcProps,
+  LxcAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const ProxmoxLxc = Resource<ProxmoxLxc>('Proxmox.Lxc');
+
+const handlers = pveHandlers<LxcProps, LxcAttributes>({
+  /**
+   * ⚠️ READ FROM `config`, NOT FROM THE GUEST LIST. `GET /nodes/{n}/lxc` reports runtime shape
+   *   (status, uptime, current memory), while `/config` reports DECLARED shape. Diffing against
+   *   runtime memory would report an update every time a container ballooned.
+   */
+  attributes: (live, props) => ({
+    cores: num(live['cores'], 1),
+    hostname: typeof live['hostname'] === 'string' ? live['hostname'] : '',
+    memory: num(live['memory'], 512),
+    node: props.node,
+    onboot: live['onboot'] === 1 || live['onboot'] === true,
+    status: typeof live['status'] === 'string' ? live['status'] : 'unknown',
+    vmid: props.vmid,
+  }),
+  collection: (props) => `nodes/${props.node}/lxc`,
+  createForm: (props) => ({
+    cores: String(props.cores ?? 1),
+    hostname: props.hostname ?? `ct${String(props.vmid)}`,
+    memory: String(props.memory ?? 512),
+    onboot: props.onboot === true ? '1' : '0',
+    ostemplate: props.ostemplate,
+    storage: props.storage,
+    vmid: String(props.vmid),
+    ...(props.net0 === undefined ? {} : { net0: props.net0 }),
+  }),
+  matches: (attributes, props) =>
+    attributes.hostname === (props.hostname ?? `ct${String(props.vmid)}`) &&
+    attributes.memory === (props.memory ?? 512) &&
+    attributes.cores === (props.cores ?? 1) &&
+    attributes.onboot === (props.onboot === true),
+  path: (props) => `nodes/${props.node}/lxc/${String(props.vmid)}/config`,
+  /**
+   * ⚠️ PVE UPDATES A CONTAINER THROUGH `PUT .../config`, THE SAME PATH IT IS READ FROM, which is
+   *   why `path` ends in `/config` while `collection` does not. Create POSTs to the collection;
+   *   read and update both use the config document.
+   */
+  updateForm: (props) => ({
+    cores: String(props.cores ?? 1),
+    hostname: props.hostname ?? `ct${String(props.vmid)}`,
+    memory: String(props.memory ?? 512),
+    onboot: props.onboot === true ? '1' : '0',
+    ...(props.net0 === undefined ? {} : { net0: props.net0 }),
+  }),
+});
+
+/**
+ * ⛔ PVE REFUSES TO DELETE A RUNNING CONTAINER, and that refusal is kept — `handlers.delete`
+ *   passes it straight through. Stopping a guest so that a `destroy` can proceed is a decision an
+ *   operator makes, not one a plan makes on their behalf while they are reading the diff.
+ */
+export const ProxmoxLxcProvider = () =>
+  Provider.effect(ProxmoxLxc, Effect.succeed(ProxmoxLxc.Provider.of(handlers)));

package/src/proxmox/members.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Which transport failures prove a request never left this machine: the rule that decides whether
+ * a WRITE may go on to a second cluster member.
+ *
+ * ⛔ BOTH DIRECTIONS ARE PINNED. Too narrow and a write never fails over (Bun's refusal code was
+ *   missing from the first draft); too wide and a write that already landed is sent to a second
+ *   node (the first draft also trusted message text that mentions TLS).
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import { isPreSendTransport, isTransportFailure } from './members.ts';
+
+const transport = (cause: Error) =>
+  new HttpClientError.HttpClientError({
+    reason: new HttpClientError.TransportError({
+      cause,
+      request: { method: 'PUT', url: 'https://n2.mgmt.example.com:8006/api2/json/x' } as never,
+    }),
+  });
+
+const coded = (code: string, message = 'transport') => Object.assign(new Error(message), { code });
+
+describe('transport classification', () => {
+  it('treats timeout TransportError as transport but not pre-send', () => {
+    const timeout = transport(coded('AbortError', 'aborted'));
+    assert.equal(isTransportFailure(timeout), true);
+    assert.equal(isPreSendTransport(timeout), false);
+  });
+
+  // ★ Bun's spelling first — MEASURED 2026-09-14 through FetchHttpClient; see members.ts.
+  it('treats refused, unresolvable and refused-certificate as pre-send', () => {
+    for (const code of [
+      'ConnectionRefused',
+      'ECONNREFUSED',
+      'ENOTFOUND',
+      'ERR_TLS_CERT_ALTNAME_INVALID',
+    ]) {
+      assert.equal(isPreSendTransport(transport(coded(code))), true, code);
+    }
+  });
+
+  // ⛔ A message that merely mentions TLS proves nothing about whether a write was sent.
+  it('never takes message text, a mid-stream TLS error or a reset as proof of pre-send', () => {
+    assert.equal(isPreSendTransport(transport(new Error('TLS connection closed by peer'))), false);
+    assert.equal(isPreSendTransport(transport(coded('ERR_SSL_DECRYPTION_FAILED'))), false);
+    assert.equal(isPreSendTransport(transport(coded('ECONNRESET'))), false);
+  });
+
+  it('never treats an HTTP answer as a transport failure', () => {
+    assert.equal(isTransportFailure(new Error('500')), false);
+    assert.equal(isPreSendTransport(new Error('ConnectionRefused')), false);
+  });
+});

package/src/proxmox/members.ts

@@ -0,0 +1,174 @@
+/**
+ * TB4 cluster members: ordered failover, last-good preference, transport classification.
+ *
+ * ★ ANY MEMBER'S :8006 API MANAGES THE WHOLE CLUSTER — PVE proxies node paths itself — so the
+ *   provider reaches the cluster through whichever member is up, not through one pinned node.
+ *
+ * ⛔ NEVER cluster-tb4.example.com: it resolves to 10.20.10.250, which nothing serves.
+ */
+import * as Effect from 'effect/Effect';
+import * as Result from 'effect/Result';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientError from 'effect/unstable/http/HttpClientError';
+import type * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import type * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import type { PveTarget } from './credentials.ts';
+
+export const PVE_API_PORT = 8006;
+
+/** Strict TLS, always :8006 — each node's certificate carries its mgmt name as a SAN. */
+export const pveApiBase = (member: string) => `https://${member}:${String(PVE_API_PORT)}/api2/json`;
+
+/** Process-scoped last member that answered, keyed by OpenBao mount (= one PVE cluster). */
+const lastGoodByMount = new Map<string, string>();
+
+/** ⚠️ TESTS ONLY — resets sticky member choice between cases. */
+export const resetLastGoodForTest = () => lastGoodByMount.clear();
+
+export const noteGoodMember = (target: PveTarget, member: string) => {
+  lastGoodByMount.set(target.mount, member);
+};
+
+/** Last-good first, then the rest in configuration order. */
+export const orderedMembers = (target: PveTarget): readonly string[] => {
+  const preferred = lastGoodByMount.get(target.mount);
+  if (preferred === undefined || !target.members.includes(preferred)) return target.members;
+  return [preferred, ...target.members.filter((member) => member !== preferred)];
+};
+
+const errorCode = (cause: unknown): string | undefined => {
+  if (cause !== null && typeof cause === 'object') {
+    if ('code' in cause && typeof cause.code === 'string') return cause.code;
+    if ('cause' in cause) return errorCode((cause as { cause: unknown }).cause);
+  }
+  return undefined;
+};
+
+const isTimeoutCause = (cause: unknown): boolean => {
+  const code = errorCode(cause);
+  if (code === 'AbortError' || code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT') {
+    return true;
+  }
+  return cause instanceof Error && /timed out|timeout/i.test(cause.message);
+};
+
+/**
+ * Error codes that PROVE the request never left this machine.
+ *
+ * ★ MEASURED 2026-09-14 through Effect's FetchHttpClient on Bun 1.4. The codes are Bun's, not
+ *   Node's, which made the first draft's Node-only list dead code for the commonest case:
+ *     connection refused        cause.code = "ConnectionRefused"   (Node says ECONNREFUSED)
+ *     name does not resolve     cause.code = "ENOTFOUND"
+ *     wrong certificate name    cause.code = "ERR_TLS_CERT_ALTNAME_INVALID"
+ *     no answer after connect   Effect's TimeoutError — not an HttpClientError at all
+ * ⛔ CODES ONLY, NEVER MESSAGE TEXT. The first draft also matched /TLS|SSL|certificate/ in the
+ *   message, and a connection that drops mid-response can mention TLS too — which would have sent a
+ *   write that had already landed to a second node.
+ * ⚠️ A CERTIFICATE failure is pre-send: the handshake has to finish before a byte of the request is
+ *   written. A generic ERR_SSL_* is deliberately absent, because it can happen mid-stream.
+ */
+const PRE_SEND_CODES = new Set(['ConnectionRefused', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN']);
+
+const isCertificateCode = (code: string) =>
+  /^(ERR_TLS_CERT_|CERT_|UNABLE_TO_VERIFY_|DEPTH_ZERO_SELF_SIGNED|SELF_SIGNED_CERT)/.test(code);
+
+const isPreSendCause = (cause: unknown): boolean => {
+  const code = errorCode(cause);
+  return code !== undefined && (PRE_SEND_CODES.has(code) || isCertificateCode(code));
+};
+
+/**
+ * Effect HttpClientError.reason._tag — see effect HttpClientError.ts RequestError vs ResponseError.
+ * ★ TransportError | InvalidUrlError | EncodeError occur before a response exists; StatusCodeError
+ *   and kin include a response. client.execute does NOT filter status, so HTTP answers are never
+ *   TransportError — only the transport layer is.
+ */
+export const isTransportFailure = (cause: unknown): boolean => {
+  if (!HttpClientError.isHttpClientError(cause)) return false;
+  const tag = cause.reason._tag;
+  return tag === 'TransportError' || tag === 'InvalidUrlError' || tag === 'EncodeError';
+};
+
+/** Pre-send only: connection refused, DNS, a certificate refused — never a timeout after connect. */
+export const isPreSendTransport = (cause: unknown): boolean => {
+  if (!HttpClientError.isHttpClientError(cause)) return false;
+  const { reason } = cause;
+  if (reason._tag === 'InvalidUrlError' || reason._tag === 'EncodeError') return true;
+  if (reason._tag === 'TransportError') {
+    if (isTimeoutCause(reason.cause)) return false;
+    return isPreSendCause(reason.cause);
+  }
+  return false;
+};
+
+export const describeTransport = (cause: unknown): string => {
+  if (HttpClientError.isHttpClientError(cause)) return cause.message;
+  return String(cause);
+};
+
+export type MemberAttempt = { readonly member: string; readonly why: string };
+
+export type PveMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+/**
+ * Run one request against cluster members with failover.
+ *
+ * ⛔ A POST/PUT/DELETE WHOSE REQUEST MAY HAVE REACHED A MEMBER MUST NOT BE SENT AGAIN TO ANOTHER.
+ *   Only fail over a write on a provably pre-send transport failure — connection refused, DNS or a
+ *   refused certificate. A timeout after sending is NOT pre-send: fail it, never repeat it. An HTTP
+ *   status of any kind, including 5xx and PVE's 596, is the answer from a live member — retrying
+ *   elsewhere can repeat a write.
+ *
+ * ★ Reads fail over on any transport failure, including timeout — no side effect to duplicate.
+ *   MEASURED 2026-09-14: full TB4 plans stayed all-noop with the first member refused (127.0.0.1)
+ *   and with it unresolvable (n9.invalid).
+ */
+export const executeOnCluster = (
+  target: PveTarget,
+  method: PveMethod,
+  path: string,
+  build: (apiBase: string) => HttpClientRequest.HttpClientRequest,
+): Effect.Effect<
+  HttpClientResponse.HttpClientResponse,
+  {
+    readonly tag: 'cluster';
+    readonly method: PveMethod;
+    readonly path: string;
+    readonly attempts: readonly MemberAttempt[];
+  },
+  HttpClient.HttpClient
+> =>
+  Effect.gen(function* () {
+    /**
+     * ★ `HttpClient`, NOT RAW `fetch`, BECAUSE THAT IS WHAT ALCHEMY'S OWN PROVIDERS USE. Its
+     *   Hetzner provider builds on `FetchHttpClient.layer` and the `HttpClient` service
+     *   (src/Hetzner/Providers.ts), and there is no bare `fetch` anywhere in its Docker,
+     *   Kubernetes or GitHub providers. Going through the service rather than the global buys
+     *   the things a provider actually needs: a typed error channel instead of a thrown promise,
+     *   interruption when a plan is cancelled, whatever tracing the runtime has installed, and a
+     *   client that can be swapped for a stub in a test without monkey-patching a global.
+     *
+     * ⚠️ THE REQUIREMENT IS REAL AND IT PROPAGATES. Every operation carries `HttpClient`, so every
+     *   resource's Requirements type names it (PveRequirements in resource.ts) and the stack
+     *   provides `FetchHttpClient.layer`. That is the cost of the above, paid once.
+     */
+    const client = yield* HttpClient.HttpClient;
+    const isWrite = method !== 'GET';
+    const attempts: MemberAttempt[] = [];
+    for (const member of orderedMembers(target)) {
+      const outcome = yield* client.execute(build(pveApiBase(member))).pipe(Effect.result);
+      if (Result.isSuccess(outcome)) {
+        noteGoodMember(target, member);
+        return outcome.success;
+      }
+      const why = describeTransport(outcome.failure);
+      attempts.push({ member, why });
+      const mayRetry = isWrite
+        ? isPreSendTransport(outcome.failure)
+        : isTransportFailure(outcome.failure);
+      if (!mayRetry) {
+        return yield* Effect.fail({ attempts, method, path, tag: 'cluster' as const });
+      }
+    }
+    return yield* Effect.fail({ attempts, method, path, tag: 'cluster' as const });
+  });

package/src/proxmox/metric-server-form.ts

@@ -0,0 +1,128 @@
+/**
+ * A metric server's props, as the form PVE wants.
+ *
+ * ★ SPLIT OUT OF metric-server.ts TO KEEP BOTH FILES UNDER THE 250-LINE CAP, and the seam is a
+ *   real one rather than a convenient line number: this file answers "how does a declaration
+ *   become a PVE form", and metric-server.ts answers "what is a metric server and when has it
+ *   changed". Nothing here reads the cluster and nothing here decides a diff.
+ *
+ * ⚠️ THE `import type` BACK TO metric-server.ts IS A CYCLE ON PAPER ONLY. It is type-only, so it
+ *   is erased before anything runs — `MetricServerProps` stays the resource's public shape, in the
+ *   file that declares the resource, rather than being moved somewhere odd to dodge the arrow.
+ *   metric-server-otel.ts imports `UNSET` from here and this file imports nothing back from it,
+ *   so no runtime cycle exists either.
+ */
+import type { MetricServerProps } from './metric-server.ts';
+import { withClears } from './values.ts';
+
+/**
+ * ⚠️ "NOT SET" CANNOT BE 0 HERE, WHICH IS WHY IT IS -1. `timeout` has a minimum of 0 in PVE's
+ *   schema, so a deliberate `timeout 0` exists; a provider using 0 as its absent-marker reads that
+ *   zero as "unset" and never clears it. -1 is outside every one of these fields' ranges.
+ */
+export const UNSET = -1;
+
+const str = (value: number | undefined) => (value === undefined ? undefined : String(value));
+
+/**
+ * Every managed optional, per type: the value to send, or undefined for "clear it".
+ *
+ * ⛔ ONE TABLE FEEDS BOTH HALVES OF AN UPDATE, AND THAT IS THE POINT. A PUT THAT OMITS A FIELD DOES
+ *   NOT CLEAR IT — PVE merges the form into the existing section — so a managed optional needs a
+ *   matching `delete=` the moment its prop goes away, or `matches` reports an update on every plan
+ *   forever. Deriving the form and the delete list from one map makes "managed but not clearable"
+ *   impossible to write here, which a separate clear-list would not.
+ * ⛔ NOTHING SET OUT OF BAND MAY BE LISTED HERE, `token` FIRST AMONG THEM: a field in this map is
+ *   CLEARED whenever it is undeclared, so adding the token would strip a working target's
+ *   credential on the next plan — metrics stop, nothing errors, the graph goes flat. `otel-headers`
+ *   is absent for the same reason: it is where an OTLP server's bearer token lives.
+ * ⚠️ AND THE BRANCHES CANNOT BE ONE SHARED MAP. PVE validates a section against that plugin's own
+ *   option set, so `path` on an influxdb server is a hard 400 and `delete=path` there answers "no
+ *   such option" — neither is an ignored hint. The opentelemetry plugin has no `mtu` and no
+ *   `timeout` at all (its option list is `server`, `port`, `disable` and the `otel-*` family), so
+ *   that branch carries neither.
+ * ⚠️ graphite's `proto` (udp or tcp) is deliberately absent: a transport chosen by hand stays put
+ *   and no plan diffs it. Managing it means adding it HERE, where it is clearable by construction.
+ *   `otel-resource-attributes` is absent for the reason metric-server-otel.ts gives.
+ */
+export const optional = (props: MetricServerProps): Record<string, string | undefined> => {
+  switch (props.type) {
+    case 'graphite':
+      return { mtu: str(props.mtu), path: props.path, timeout: str(props.timeout) };
+    case 'influxdb':
+      return {
+        'api-path-prefix': props['api-path-prefix'],
+        bucket: props.bucket,
+        influxdbproto: props.influxdbproto,
+        'max-body-size': str(props['max-body-size']),
+        mtu: str(props.mtu),
+        organization: props.organization,
+        timeout: str(props.timeout),
+      };
+    case 'opentelemetry':
+      return {
+        'otel-compression': props['otel-compression'],
+        'otel-max-body-size': str(props['otel-max-body-size']),
+        'otel-path': props['otel-path'],
+        'otel-protocol': props['otel-protocol'],
+        'otel-timeout': str(props['otel-timeout']),
+      };
+  }
+};
+
+/**
+ * The certificate-verification flag, for the one plugin that owns it.
+ *
+ * ⛔ EACH FLAG GOES ONLY TO ITS OWN PLUGIN. `verify-certificate` is influxdb's, `otel-verify-ssl` is
+ *   opentelemetry's, graphite has neither — and PVE refuses an option outside the section's plugin
+ *   rather than ignoring it, the same way it refuses `path` on influxdb.
+ */
+const verification = (props: MetricServerProps): Record<string, string> => {
+  switch (props.type) {
+    case 'graphite':
+      return {};
+    case 'influxdb':
+      return { 'verify-certificate': props['verify-certificate'] === false ? '0' : '1' };
+    case 'opentelemetry':
+      return { 'otel-verify-ssl': props['otel-verify-ssl'] === false ? '0' : '1' };
+  }
+};
+
+/**
+ * The fields sent on EVERY write, create and update alike.
+ *
+ * ⚠️ `server` AND `port` ARE REQUIRED BY THE PUT TOO, not only by the POST: a PUT that omits either
+ *   fails parameter verification rather than leaving them alone. PVE also refuses to clear them —
+ *   "unable to delete required option" — which is why they are here and not in `optional`.
+ * ⚠️ `disable` AND THE VERIFY FLAG ARE SENT WITH THEIR DEFAULTS rather than left out. Writing the
+ *   value PVE would have assumed makes the read-back match on the first plan after the create,
+ *   whether or not that PVE materialises defaults into the file.
+ */
+const required = (props: MetricServerProps): Record<string, string> => ({
+  disable: props.disable === true ? '1' : '0',
+  port: String(props.port),
+  server: props.server,
+  ...verification(props),
+});
+
+export const body = (props: MetricServerProps) => {
+  const fields = required(props);
+  for (const [option, value] of Object.entries(optional(props))) {
+    if (value !== undefined) fields[option] = value;
+  }
+  return fields;
+};
+
+/**
+ * An update's form: everything `body` sends, plus a `delete=` naming each managed optional that is
+ * no longer declared.
+ *
+ * ★ MOVED HERE FROM metric-server.ts UNCHANGED, so the test beside this file can reach the form an
+ *   update really sends instead of re-deriving it and testing its own copy.
+ */
+export const update = (props: MetricServerProps) => {
+  const clear = Object.entries(optional(props))
+    .filter(([, value]) => value === undefined)
+    .map(([option]) => option);
+  return withClears(body(props), clear);
+};

package/src/proxmox/metric-server-otel.ts

@@ -0,0 +1,99 @@
+/**
+ * The `opentelemetry` plugin's option set: what a metric server of that type accepts, how it reads
+ * back, and when it has changed.
+ *
+ * ★ SPLIT OUT OF metric-server.ts TO KEEP IT UNDER THE 250-LINE CAP, AND THE SEAM IS THE PLUGIN.
+ *   PVE validates a section against ONE plugin's option set, so these fields mean nothing to a
+ *   graphite or influxdb section and theirs mean nothing here. This file answers "what is an OTLP
+ *   metric server"; metric-server-form.ts still builds every form, so the clear-list keeps coming
+ *   from the one table that also builds the body.
+ *
+ * ⛔ PVE'S OTLP EXPORTER SPEAKS JSON AND NOTHING ELSE. `PVE::Status::OpenTelemetry::send` sets
+ *   `Content-Type: application/json` (pve-manager PVE/Status/OpenTelemetry.pm:643) and gzips by
+ *   default; there is no protobuf option. vector's opentelemetry source and VictoriaMetrics both
+ *   take protobuf only — measured 2026-09-14 — so a server pointed straight at either fails every
+ *   push. That is why TB4's declaration points at each node's own vector bridge
+ *   (hosts/pve/vector/vector.yaml in homeflare-config) rather than at the estate's intake.
+ *
+ * ⛔ `otel-headers` IS `never`, FOR THE REASON `token` IS. It is where an OTLP bearer token goes —
+ *   base64 of a JSON object of arbitrary HTTP headers — and Alchemy persists attributes UNENCRYPTED.
+ *   It is also absent from `optional` in metric-server-form.ts, so an undeclared one is never
+ *   cleared off a working target on the next plan.
+ *
+ * ⚠️ `otel-resource-attributes` IS NOT MANAGED AT ALL: not a prop, not read, not compared, not
+ *   cleared. It is base64 of a JSON object whose key order nothing canonicalises, so comparing it
+ *   means decoding both sides — work with no consumer yet, since nothing sets it and PVE already
+ *   stamps `service.name`, `proxmox.cluster` and `proxmox.node` on every request
+ *   (`_build_otlp_metrics`, lines 207-228). A hand-set one therefore survives every plan and never
+ *   shows as drift. The day one matters, it goes into `optional` and here together.
+ */
+import { UNSET } from './metric-server-form.ts';
+import { bool, int, text } from './values.ts';
+
+export interface MetricServerOtelProps {
+  /**
+   * ⚠️ PVE'S DEFAULT IS `https`. `http` is for a receiver on the node itself, where the plaintext
+   *   never leaves the host; anything further away belongs on `https`.
+   */
+  'otel-protocol'?: 'http' | 'https';
+  /** Unset is PVE's `/v1/metrics`. */
+  'otel-path'?: string;
+  /** Unset is PVE's `gzip`, sent as `Content-Encoding: gzip`. */
+  'otel-compression'?: 'none' | 'gzip';
+  /**
+   * Per-request HTTP timeout, 1-10 seconds; unset is PVE's 5.
+   * ⚠️ pvestatd WAITS THIS LONG, PER REQUEST, AGAINST A RECEIVER THAT HANGS — the send is inline in
+   *   its update loop (`send`, line 635) — so this is also how long a broken receiver can stretch
+   *   one status cycle.
+   */
+  'otel-timeout'?: number;
+  /** Minimum 1024; unset is PVE's 10000000. pvestatd splits one flush into requests under it. */
+  'otel-max-body-size'?: number;
+  /** ⚠️ An unset `otel-verify-ssl` means VERIFY — PVE's default, and the safe one. */
+  'otel-verify-ssl'?: boolean;
+  /** ⛔ `never` ON PURPOSE — see the ⛔ in the header. The compile error is the feature. */
+  'otel-headers'?: never;
+}
+
+/**
+ * ⚠️ THE SAME RULES AS THE REST OF `MetricServerAttributes`. The strings report `''` when the
+ *   section carries none — PVE's default is then what the target uses — the numbers report `UNSET`
+ *   for the same reason, and `otel-verify-ssl` reports its default directly, because "absent"
+ *   there means the target verifies.
+ */
+export interface MetricServerOtelAttributes {
+  'otel-compression': string;
+  'otel-max-body-size': number;
+  'otel-path': string;
+  'otel-protocol': string;
+  'otel-timeout': number;
+  'otel-verify-ssl': boolean;
+}
+
+/** The `otel-*` half of a live section. Read for every type; compared only for this one. */
+export const otelAttributes = (live: Record<string, unknown>): MetricServerOtelAttributes => ({
+  'otel-compression': text(live['otel-compression']),
+  'otel-max-body-size': int(live['otel-max-body-size'], UNSET),
+  'otel-path': text(live['otel-path']),
+  'otel-protocol': text(live['otel-protocol']),
+  'otel-timeout': int(live['otel-timeout'], UNSET),
+  'otel-verify-ssl': bool(live['otel-verify-ssl'], true),
+});
+
+/**
+ * True when every managed `otel-*` field already says what the declaration says.
+ *
+ * ⛔ EVERY FIELD `optional` SENDS OR CLEARS IS COMPARED HERE, AND NOTHING ELSE IS. A field sent but
+ *   not compared is drift a plan can never show; a field compared but not sent is an update the
+ *   PUT it triggers can never satisfy, reported forever.
+ */
+export const otelMatches = (
+  attributes: MetricServerOtelAttributes,
+  props: MetricServerOtelProps,
+): boolean =>
+  attributes['otel-compression'] === (props['otel-compression'] ?? '') &&
+  attributes['otel-max-body-size'] === (props['otel-max-body-size'] ?? UNSET) &&
+  attributes['otel-path'] === (props['otel-path'] ?? '') &&
+  attributes['otel-protocol'] === (props['otel-protocol'] ?? '') &&
+  attributes['otel-timeout'] === (props['otel-timeout'] ?? UNSET) &&
+  attributes['otel-verify-ssl'] === (props['otel-verify-ssl'] !== false);