@remodex/rmx 1.0.2

package/src/integrations/native/ownership-preflight.ts

@@ -0,0 +1,202 @@
+/**
+ * The service-home preflight for native-client teardown (WP2, audit r1 #5;
+ * devlog 260803_integrations_toggle_all/012).
+ *
+ * `rmx stop` has honored `ServiceOwnershipError` since it started catching it
+ * (src/cli/index.ts:464); nothing on the HTTP side ever did. A route that calls
+ * `stripGrokConfig` directly would otherwise pull the fence out from under a
+ * service running from another CODEX_HOME/OPENCODEX_HOME — the installed
+ * service is still live and the shared state belongs to it.
+ *
+ * ENABLE is not gated by this: writing our own fence is not a shared teardown,
+ * and `injectGrokConfig` already runs unguarded from `rmx start`/`ensure`.
+ */
+import {
+  assertServiceEnvironmentMatchesInstall,
+  isServiceOwnershipError,
+} from "../../service";
+import {
+  currentServiceHomes,
+  inspectServiceStateEvidence,
+  serviceHomeMatches,
+  type ServiceStateEvidence,
+} from "../../service";
+import {
+  inspectServiceManagerInstallation,
+  type ProbeDeps,
+  type ServiceManagerClaim,
+} from "../../service-manager-probe";
+
+export type NativeTeardownOwnership = { ok: true } | { ok: false; message: string };
+
+export function assertNativeTeardownOwned(): NativeTeardownOwnership {
+  try {
+    assertServiceEnvironmentMatchesInstall();
+    return { ok: true };
+  } catch (error) {
+    if (isServiceOwnershipError(error)) {
+      // The message names both the recorded and the current home — that is the
+      // refusal text, verbatim, because the user has to act on it.
+      return { ok: false, message: error.message };
+    }
+    // Unrelated failure (corrupt state file, IO): mirror
+    // `serviceEnvironmentOwnedHere` and fail open rather than wedging the route
+    // behind a check whose own input is broken.
+    return { ok: true };
+  }
+}
+
+/**
+ * Tri-state ownership for UNATTENDED writes.
+ *
+ * Deliberately not `assertNativeTeardownOwned`. That one fails OPEN — a corrupt
+ * state file yields `{ok:true}` — which is right for a teardown route a human
+ * just invoked, and catastrophic as an authority for automatic convergence:
+ * "could not read" would become "belongs to me".
+ *
+ * `owned` here means NO PERSISTENT SERVICE CLAIM WAS OBSERVED. It does not mean
+ * this process is the only writer. Two foreground `rmx start` processes on one
+ * home both read `owned`, and correctly so, because neither installs a service —
+ * keeping them apart is the write lock's job, not this function's.
+ */
+export type NativeCodexOwnership = "owned" | "foreign" | "unknown";
+
+export interface OwnershipInspection {
+  readonly ownership: NativeCodexOwnership;
+  /** Why, in the words a refusal message can use. */
+  readonly reason: string;
+}
+
+function claimNamesDifferentHome(
+  claim: ServiceManagerClaim,
+  current: { codexHome: string; opencodexHome: string },
+): boolean {
+  // A definition that OMITS a home is not a definition that disagrees about it:
+  // an install run without CODEX_HOME set writes no such key at all.
+  if (claim.homes.codexHome !== null && !serviceHomeMatches(claim.homes.codexHome, current.codexHome)) return true;
+  if (claim.homes.opencodexHome !== null && !serviceHomeMatches(claim.homes.opencodexHome, current.opencodexHome)) return true;
+  return false;
+}
+
+/**
+ * Map a service-manager claim backend to the `ServiceInstallState.backend`
+ * value it corresponds to. `scheduler` (Task Scheduler) and `winsw` (native)
+ * are the two Windows manager backends; launchd/systemd claims have no Windows
+ * backend and can never mismatch a v2 state file.
+ */
+function claimBackendToStateBackend(backend: ServiceManagerClaim["backend"]): "scheduler" | "native" | null {
+  if (backend === "scheduler") return "scheduler";
+  if (backend === "winsw") return "native";
+  return null;
+}
+
+/** True when the recorded state backend disagrees with the manager claim. Legacy v1 means scheduler. */
+function claimBackendMismatchesState(claim: ServiceManagerClaim, state: { backend?: "scheduler" | "native" }): boolean {
+  const expected = claimBackendToStateBackend(claim.backend);
+  if (expected === null) return false;
+  return (state.backend ?? "scheduler") !== expected;
+}
+
+export interface OwnershipDeps extends ProbeDeps {
+  /**
+   * Which state paths to consult. Injectable because the default set includes
+   * the DEFAULT home mirror, resolved from `homedir()` — which no test sandbox
+   * moves. Without this a fixture reads the developer's real installation and
+   * calls their own machine foreign.
+   */
+  readonly statePaths?: readonly string[];
+  readonly currentHomes?: { codexHome: string; opencodexHome: string };
+}
+
+export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): OwnershipInspection {
+  const current = deps.currentHomes ?? currentServiceHomes();
+  const evidence = deps.statePaths
+    ? inspectServiceStateEvidence(deps.statePaths)
+    : inspectServiceStateEvidence();
+
+  const unreadable = evidence.find((e): e is Extract<ServiceStateEvidence, { kind: "unreadable" }> => e.kind === "unreadable");
+  if (unreadable) {
+    return { ownership: "unknown", reason: `service state at ${unreadable.path} could not be read (${unreadable.reason})` };
+  }
+  const invalid = evidence.find(e => e.kind === "invalid");
+  if (invalid) {
+    return { ownership: "unknown", reason: `service state at ${invalid.path} is malformed` };
+  }
+
+  const valid = evidence.filter((e): e is Extract<ServiceStateEvidence, { kind: "valid" }> => e.kind === "valid");
+  // Mirrors that disagree with each other are not a majority vote.
+  for (const one of valid) {
+    for (const other of valid) {
+      if (!serviceHomeMatches(one.state.codexHome, other.state.codexHome)
+        || !serviceHomeMatches(one.state.opencodexHome, other.state.opencodexHome)) {
+        return { ownership: "unknown", reason: "two service state files disagree about which homes are installed" };
+      }
+    }
+  }
+
+  const foreign = valid.find(e =>
+    !serviceHomeMatches(e.state.codexHome, current.codexHome)
+    || !serviceHomeMatches(e.state.opencodexHome, current.opencodexHome));
+  if (foreign) {
+    return {
+      ownership: "foreign",
+      reason: `a service is installed for CODEX_HOME=${foreign.state.codexHome} / OPENCODEX_HOME=${foreign.state.opencodexHome}`,
+    };
+  }
+
+  // The manager assets live under the effective OPENCODEX_HOME. Production
+  // callers do not inject ProbeDeps.configDir, so derive it from the same
+  // current-home snapshot used for ownership comparison rather than silently
+  // falling back to <homedir>/.opencodex.
+  const manager = inspectServiceManagerInstallation({
+    ...deps,
+    configDir: deps.configDir ?? current.opencodexHome,
+  });
+  if (manager.kind === "unknown") {
+    return { ownership: "unknown", reason: manager.reason };
+  }
+  if (manager.kind === "conflict") {
+    return { ownership: "unknown", reason: "more than one service manager holds a registration for this proxy" };
+  }
+  if (manager.kind === "present") {
+    const disagreeing = manager.claims.find(claim => claimNamesDifferentHome(claim, current));
+    if (disagreeing) {
+      /*
+       * The state file says this home and the definition says another. An
+       * interrupted reinstall looks exactly like this — installation writes the
+       * definition BEFORE the state file — and picking a winner unattended would
+       * be guessing which half of a half-finished operation to believe.
+       */
+      return {
+        ownership: "unknown",
+        reason: `${disagreeing.backend} is installed from ${disagreeing.definitionPath}, which names different homes than the recorded service state`,
+      };
+    }
+    // A manager backend that disagrees with the recorded state (e.g. state says
+    // native/WinSW but a scheduler task is found) is an interrupted backend
+    // switch: it does not prove which manager owns the installation. v1 state
+    // predates the field and is scheduler by contract.
+    const stateBackendMismatch = valid.find(state => manager.claims.some(claim => claimBackendMismatchesState(claim, state.state)));
+    if (stateBackendMismatch) {
+      return {
+        ownership: "unknown",
+        reason: `the service state records backend ${stateBackendMismatch.state.backend ?? "scheduler"} but ${manager.claims[0]?.backend ?? "a service manager"} is installed`,
+      };
+    }
+    // Definition agrees. Valid state agreeing with it is ownership; no state at
+    // all beside an installed definition is not, because the definition is the
+    // claim and nothing here recorded making it.
+    if (valid.length === 0) {
+      return {
+        ownership: "unknown",
+        reason: `${manager.claims[0]?.backend ?? "a service manager"} holds a registration that no service state file accounts for`,
+      };
+    }
+    return { ownership: "owned", reason: "the installed service names these homes" };
+  }
+
+  // manager.kind === "absent"
+  return valid.length === 0
+    ? { ownership: "owned", reason: "no service state and no service manager claim" }
+    : { ownership: "owned", reason: "the recorded service state names these homes" };
+}

package/src/integrations/ownership.ts

@@ -0,0 +1,111 @@
+/**
+ * What Remodex remembers about a client between operations.
+ *
+ * Two hashes, because the two questions are genuinely independent: the FILE
+ * hash answers "did anyone touch this after us", and the BLOCK hash answers "is
+ * our content still what we would write today". One hash cannot do both, and
+ * conflating them is what lets a foreign edit read as ordinary drift — which
+ * would then be silently overwritten.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/021 §2.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ManagedContribution, ManagedFragment } from "../clients/config-export";
+import { atomicWriteFile, getConfigDir } from "../config";
+import type { IntegrationClientId } from "./registry";
+
+/** 16 hex chars — the same shape as the Claude Desktop applied fingerprint. */
+export function fingerprint(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/**
+ * Canonical bytes of a contribution. Fragments are sorted by path so two builds
+ * of the same contribution hash identically regardless of emission order.
+ */
+export function canonicalContribution(contribution: ManagedContribution): string {
+  const sorted = [...contribution.fragments].sort((a, b) => {
+    const left = a.path.join("\u0000");
+    const right = b.path.join("\u0000");
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  return JSON.stringify(sorted.map(fragment => [fragment.path, fragment.value]));
+}
+
+export interface OwnershipRecord {
+  clientId: IntegrationClientId;
+  configPath: string;
+  /** Hash of the WHOLE file as we left it — detects foreign edits after us. */
+  fileFingerprint: string;
+  /** Hash of our contribution — detects catalog/port drift. */
+  blockFingerprint: string;
+  /** The exact paths we own. Removal touches these and nothing else. */
+  fragmentPaths: readonly (readonly string[])[];
+  /**
+   * Containers this apply had to CREATE, `\0`-joined.
+   *
+   * Kimi's `models` map exists only because our aliases need somewhere to
+   * live. Without this, disable left it behind as an empty container in a file
+   * the user never asked us to restructure — while a `providers: {}` the user
+   * wrote themselves must survive. Optional because records written before
+   * this field existed simply prune nothing, which is the old behavior.
+   */
+  createdContainers?: readonly string[];
+  appliedAt: string;
+  opId: string;
+}
+
+/**
+ * The integrations directory itself. Every primitive takes THIS path, never a
+ * config root, so a caller cannot accidentally produce
+ * `<root>/integrations/integrations` by passing an already-resolved value.
+ */
+export function integrationsDir(configDir: string = getConfigDir()): string {
+  return join(configDir, "integrations");
+}
+
+/** `atomicWriteFile` does not create parents. */
+export function ensureDir(filePath: string): void {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+}
+
+function recordsPath(dir: string): string {
+  return join(dir, "records.json");
+}
+
+export function readRecords(
+  dir: string = integrationsDir(),
+): Partial<Record<IntegrationClientId, OwnershipRecord>> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(recordsPath(dir), "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Partial<Record<IntegrationClientId, OwnershipRecord>>;
+    }
+  } catch {
+    // Missing or corrupt records mean "we remember nothing", which the
+    // classifier reads as a conflict for an existing block. Fail closed: an
+    // unreadable memory is never permission to delete.
+  }
+  return {};
+}
+
+export function writeRecord(record: OwnershipRecord, dir: string = integrationsDir()): void {
+  const all = readRecords(dir);
+  all[record.clientId] = record;
+  ensureDir(recordsPath(dir));
+  atomicWriteFile(recordsPath(dir), `${JSON.stringify(all, null, 2)}\n`);
+}
+
+export function deleteRecord(clientId: IntegrationClientId, dir: string = integrationsDir()): void {
+  const all = readRecords(dir);
+  if (!(clientId in all)) return;
+  delete all[clientId];
+  ensureDir(recordsPath(dir));
+  atomicWriteFile(recordsPath(dir), `${JSON.stringify(all, null, 2)}\n`);
+}
+
+export function fragmentPathsOf(contribution: ManagedContribution): readonly (readonly string[])[] {
+  return contribution.fragments.map((fragment: ManagedFragment) => fragment.path);
+}

package/src/integrations/registry.ts

@@ -0,0 +1,108 @@
+/**
+ * Where each file-toggle client keeps its config, and what we are allowed to do
+ * to it.
+ *
+ * The export registry (src/clients/config-export.ts) says how to RENDER a
+ * client's config. This one says where it lives, how to tell whether the client
+ * is installed at all, and whether a remote bind is safe for it.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/021 §1.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  EXPORT_CLIENTS,
+  gajaeConfigPath,
+  gajaeHomeDir,
+  hermesConfigPath,
+  hermesHomeDir,
+  kimiConfigPath,
+  kimiHomeDir,
+  ompAgentDir,
+  ompModelsConfigPath,
+  opencodeGlobalConfigPath,
+  openclawConfigPath,
+  openclawHomeDir,
+  type ExportClientId,
+} from "../clients/config-export";
+
+/**
+ * Readability alias. WP1 owns the type; this never introduces a second one, so
+ * the dependency only ever points backwards.
+ */
+export type IntegrationClientId = ExportClientId;
+
+export interface IntegrationClientSpec {
+  id: IntegrationClientId;
+  /** The client's config file, honoring that client's own environment override. */
+  configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /** Directory whose existence is the cheap "is it installed?" signal. */
+  detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+}
+
+/**
+ * True when the client has nowhere to put the dedicated admission header a
+ * non-loopback bind requires, so a generated config would simply be rejected.
+ *
+ * Read from the export registry rather than restated here: two lists of the
+ * same fact drift, and this one decides whether we write a file that 401s.
+ */
+export function isLoopbackOnly(clientId: IntegrationClientId): boolean {
+  return EXPORT_CLIENTS[clientId].loopbackOnly;
+}
+
+function xdgConfigHome(env: NodeJS.ProcessEnv, home: string): string {
+  const xdg = env.XDG_CONFIG_HOME;
+  return xdg && xdg.length > 0 ? xdg : join(home, ".config");
+}
+
+export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientSpec> = {
+  opencode: {
+    id: "opencode",
+    // These take `home` explicitly. The export registry's `destination` reads
+    // the real home directory, which is right for telling a user where their
+    // file lives and wrong for a writer that a test must be able to redirect.
+    configPath: (env = process.env, home = homedir()) => opencodeGlobalConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => join(xdgConfigHome(env, home), "opencode"),
+  },
+  pi: {
+    id: "pi",
+    configPath: (_env = process.env, home = homedir()) => join(home, ".pi", "agent", "models.json"),
+    detectDir: (_env = process.env, home = homedir()) => join(home, ".pi"),
+  },
+  omp: {
+    id: "omp",
+    configPath: (env = process.env, home = homedir()) => ompModelsConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => ompAgentDir(env, home),
+  },
+  hermes: {
+    id: "hermes",
+    configPath: (env = process.env, home = homedir()) => hermesConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => hermesHomeDir(env, home),
+  },
+  openclaw: {
+    id: "openclaw",
+    configPath: (env = process.env, home = homedir()) => openclawConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => openclawHomeDir(env, home),
+  },
+  kimi: {
+    id: "kimi",
+    configPath: (env = process.env, home = homedir()) => kimiConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => kimiHomeDir(env, home),
+    // Kimi reads credentials only from config.toml — it never consults the
+    // environment — so there is no way to point it at a remote bind without
+    // serializing the user's key.
+  },
+  gajae: {
+    id: "gajae",
+    configPath: (env = process.env, home = homedir()) => gajaeConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => gajaeHomeDir(env, home),
+  },
+};
+
+export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =
+  Object.keys(INTEGRATION_CLIENTS) as IntegrationClientId[];
+
+export function isIntegrationClientId(value: string): value is IntegrationClientId {
+  return Object.prototype.hasOwnProperty.call(INTEGRATION_CLIENTS, value);
+}

package/src/integrations/serialize.ts

@@ -0,0 +1,235 @@
+/**
+ * Text serializers for client config documents.
+ *
+ * Bun 1.3.14 gives us JSON and JSON5 stringify natively, but the two formats a
+ * client config actually needs beyond JSON are hand-rendered here:
+ *
+ * - **TOML** has no `Bun.TOML.stringify` at all.
+ * - **YAML** has `Bun.YAML.stringify`, but it emits flow style with no trailing
+ *   newline (`{a: 1,b: {c: d}}`). That is valid YAML and completely wrong for a
+ *   file a user opens, so we render block style ourselves.
+ *
+ * The renderers originally covered only the shallow shapes our builders emit.
+ * That was fine while they only ever saw generated documents — but the
+ * integration writer parses the USER's whole config and re-serializes it, so a
+ * legitimate `null` or a numeric array in a file we never wrote threw straight
+ * out of the writer and surfaced as a 500. They now cover the value domains
+ * their formats actually allow.
+ *
+ * What they still refuse is genuinely unrenderable: a function, a symbol, a
+ * non-finite number. Those must fail loudly rather than produce bytes a client
+ * might misread — and the writer turns the failure into a structured refusal
+ * rather than an exception.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/011_wp1_builders.md.
+ */
+
+export type ConfigFormat = "json" | "yaml" | "toml" | "json5";
+
+/** Thrown when a document holds a value its format cannot represent. */
+export class UnserializableValueError extends Error {}
+
+export const FORMAT_MEDIA_TYPE: Record<ConfigFormat, string> = {
+  json: "application/json",
+  yaml: "application/yaml",
+  toml: "application/toml",
+  json5: "application/json5",
+};
+
+/**
+ * Type guard, not a boolean check — the renderers walk `unknown`, so without
+ * the predicate every narrowed branch stays `unknown`.
+ */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isYamlScalar(value: unknown): value is string | number | boolean | null {
+  return value === null
+    || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+/**
+ * Keep only unambiguous, single-token strings plain. Everything else uses a
+ * JSON-compatible double-quoted scalar, which gives deterministic escaping —
+ * JSON string escaping is valid YAML 1.2 string escaping.
+ */
+function yamlString(value: string): string {
+  const plainSafe = value.length > 0
+    && value.trim() === value
+    && /^[A-Za-z_./][A-Za-z0-9_./-]*$/u.test(value)
+    && !/^(?:null|true|false|yes|no|on|off|~|\.nan|[-+]?\.inf)$/iu.test(value);
+  return plainSafe ? value : JSON.stringify(value);
+}
+
+function yamlScalar(value: string | number | boolean | null): string {
+  // `null` renders as the explicit `null` token rather than an empty value:
+  // a bare `key:` is also null in YAML, but round-tripping it through other
+  // parsers is less predictable than saying so.
+  if (value === null) return "null";
+  if (typeof value === "string") return yamlString(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (Number.isFinite(value)) return String(value);
+  throw new UnserializableValueError(`YAML cannot represent the number ${String(value)}`);
+}
+
+function yamlEmptyCollection(value: unknown): "[]" | "{}" | undefined {
+  if (Array.isArray(value) && value.length === 0) return "[]";
+  if (isPlainRecord(value) && Object.keys(value).length === 0) return "{}";
+  return undefined;
+}
+
+function yamlMapEntryLines(key: string, value: unknown, indent: number): string[] {
+  const padding = " ".repeat(indent);
+  const renderedKey = yamlString(key);
+  if (isYamlScalar(value)) return [`${padding}${renderedKey}: ${yamlScalar(value)}`];
+  const empty = yamlEmptyCollection(value);
+  if (empty !== undefined) return [`${padding}${renderedKey}: ${empty}`];
+  if (Array.isArray(value) || isPlainRecord(value)) {
+    return [`${padding}${renderedKey}:`, ...yamlLines(value, indent + 2)];
+  }
+  throw new UnserializableValueError(`YAML cannot represent the value at key ${JSON.stringify(key)}: ${describeValue(value)}`);
+}
+
+/** A map inside a sequence: the first key rides the dash, the rest indent under it. */
+function yamlArrayMapLines(value: Record<string, unknown>, indent: number): string[] {
+  const entries = Object.entries(value);
+  const padding = " ".repeat(indent);
+  if (entries.length === 0) return [`${padding}- {}`];
+
+  const [first, ...rest] = entries;
+  const [firstKey, firstValue] = first!;
+  const renderedFirstKey = yamlString(firstKey);
+  const firstEmpty = yamlEmptyCollection(firstValue);
+  const lines: string[] = [];
+  if (isYamlScalar(firstValue)) {
+    lines.push(`${padding}- ${renderedFirstKey}: ${yamlScalar(firstValue)}`);
+  } else if (firstEmpty !== undefined) {
+    lines.push(`${padding}- ${renderedFirstKey}: ${firstEmpty}`);
+  } else if (Array.isArray(firstValue) || isPlainRecord(firstValue)) {
+    lines.push(`${padding}- ${renderedFirstKey}:`);
+    lines.push(...yamlLines(firstValue, indent + 4));
+  } else {
+    throw new UnserializableValueError(`YAML cannot represent the value at key ${JSON.stringify(firstKey)}: ${describeValue(firstValue)}`);
+  }
+  for (const [key, child] of rest) lines.push(...yamlMapEntryLines(key, child, indent + 2));
+  return lines;
+}
+
+function yamlLines(value: unknown, indent: number): string[] {
+  const padding = " ".repeat(indent);
+  if (isYamlScalar(value)) return [`${padding}${yamlScalar(value)}`];
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${padding}[]`];
+    return value.flatMap(item => {
+      if (isYamlScalar(item)) return [`${padding}- ${yamlScalar(item)}`];
+      if (isPlainRecord(item)) return yamlArrayMapLines(item, indent);
+      /*
+       * A nested sequence is ordinary YAML (`matrix: [[1,2],[3,4]]`). This
+       * used to throw a plain Error carrying `String(item)` — untyped, so the
+       * writer could not turn it into a refusal and it surfaced as a 500, and
+       * carrying the value's CONTENTS into the message, which a config may
+       * not want repeated.
+       */
+      if (Array.isArray(item)) {
+        if (item.length === 0) return [`${padding}- []`];
+        return [`${padding}-`, ...yamlLines(item, indent + 2)];
+      }
+      throw new UnserializableValueError(
+        `YAML cannot represent this sequence item: ${describeValue(item)}`,
+      );
+    });
+  }
+  if (isPlainRecord(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return [`${padding}{}`];
+    return entries.flatMap(([key, child]) => yamlMapEntryLines(key, child, indent));
+  }
+  throw new UnserializableValueError(`YAML cannot represent this value: ${describeValue(value)}`);
+}
+
+/** Block-style YAML for the shallow shapes we emit. Throws on anything else. */
+export function renderYaml(value: unknown, indent = 0): string {
+  if (!Number.isInteger(indent) || indent < 0) {
+    throw new Error(`YAML indent must be a non-negative integer: ${String(indent)}`);
+  }
+  return `${yamlLines(value, indent).join("\n")}\n`;
+}
+
+/** A short, safe description for an error message — never the value's contents. */
+function describeValue(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "object") return "an object";
+  return typeof value;
+}
+
+/** TOML basic-string escape. Mirrors `tomlString` in src/grok/inject.ts. */
+export function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+/** Bare key when safe, basic-string key otherwise (TOML 1.0 §Keys). */
+export function quoteTomlKey(key: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
+}
+
+function tomlScalar(value: unknown): string {
+  if (typeof value === "string") return tomlString(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  /*
+   * Arrays of ANY scalar, not just strings. The string-only check was written
+   * against our own builder output; a user's config legitimately holds
+   * `ports = [1, 2]`, and refusing it threw out of the writer as a 500.
+   * TOML permits mixed-type arrays since 1.0, so the elements are rendered
+   * individually rather than required to share a type.
+   */
+  if (Array.isArray(value)) {
+    return `[${value.map(item => tomlScalar(item)).join(", ")}]`;
+  }
+  /*
+   * An inline table is valid TOML (`items = [{ x = 1 }]`), and rendering one
+   * inline is straightforward — but only where the whole array can be
+   * rendered, so this stays a scalar-position renderer rather than silently
+   * flattening a table into a string.
+   */
+  if (isPlainRecord(value)) {
+    const entries = Object.entries(value);
+    return `{ ${entries.map(([k, v]) => `${quoteTomlKey(k)} = ${tomlScalar(v)}`).join(", ")} }`;
+  }
+  throw new UnserializableValueError(`TOML cannot represent this value: ${describeValue(value)}`);
+}
+
+/**
+ * Render `{ [table]: { key: scalar } }` as TOML. Scalars come first, then
+ * tables in insertion order, so two calls with the same document produce
+ * identical bytes — the stability guarantee `normalizeExportModels` exists to
+ * protect.
+ */
+export function renderToml(document: Record<string, unknown>, prefix = ""): string {
+  const scalars: string[] = [];
+  const tables: string[] = [];
+  for (const [key, value] of Object.entries(document)) {
+    const path = prefix ? `${prefix}.${quoteTomlKey(key)}` : quoteTomlKey(key);
+    if (isPlainRecord(value)) {
+      tables.push(`[${path}]\n${renderToml(value, path)}`.trimEnd());
+    } else {
+      scalars.push(`${quoteTomlKey(key)} = ${tomlScalar(value)}`);
+    }
+  }
+  return `${[scalars.join("\n"), tables.join("\n\n")].filter(Boolean).join("\n\n")}\n`;
+}
+
+/** Every serializer returns text ending in exactly one newline. */
+export function serializeDocument(document: unknown, format: ConfigFormat): string {
+  switch (format) {
+    case "json": return `${JSON.stringify(document, null, 2)}\n`;
+    case "json5": return `${Bun.JSON5.stringify(document, null, 2)}\n`;
+    case "yaml": return renderYaml(document);
+    case "toml": {
+      if (!isPlainRecord(document)) throw new Error("TOML root must be a table");
+      return renderToml(document);
+    }
+  }
+}