@iislee/opencodex 2.11.0 → 2.35.0

package/src/integrations/ownership.ts

@@ -0,0 +1,155 @@
+/**
+ * What opencodex remembers about a client between operations.
+ *
+ * Two hashes, because the two questions are genuinely independent: the FILE
+ * hash identifies the exact result for restore and for clients whose writer
+ * re-serializes the whole document. The BLOCK hash identifies OMP's surgically
+ * patched fragment and detects catalog drift. One hash cannot safely answer
+ * both questions in a shared client config.
+ *
+ * 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);
+}
+
+/**
+ * Canonicalize JSON object members recursively for semantic comparisons.
+ * Arrays stay ordered because their position can carry configuration meaning.
+ */
+function semanticJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(semanticJsonValue);
+  if (value === null || typeof value !== "object") return value;
+
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(
+    Object.keys(record)
+      .sort()
+      .map(key => [key, semanticJsonValue(record[key])]),
+  );
+}
+
+/**
+ * Stable semantic bytes of a contribution. Third-party clients may
+ * re-serialize JSON object members in a different order; that formatting-only
+ * rewrite must not look like a protected-value edit.
+ */
+export function semanticContribution(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, semanticJsonValue(fragment.value)]));
+}
+
+/**
+ * Legacy-compatible bytes used by existing persisted fingerprints. Fragment
+ * paths are stable, while nested object insertion order remains exact.
+ */
+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 — protects whole-file restore. */
+  fileFingerprint: string;
+  /** Hash of our contribution — detects catalog/port drift. */
+  blockFingerprint: string;
+  /** Key-order-independent companion for JSON clients that normalize objects. */
+  semanticBlockFingerprint?: string;
+  /**
+   * Hash of the fields the client must not rewrite. Present only when a
+   * client has explicitly declared runtime-derived paths below.
+   */
+  protectedBlockFingerprint?: string;
+  /** Key-order-independent companion to `protectedBlockFingerprint`. */
+  semanticProtectedBlockFingerprint?: string;
+  /**
+   * Exact document paths a client may derive after apply. These are recorded
+   * per operation so later catalog changes cannot widen an older grant.
+   */
+  refreshablePaths?: readonly (readonly 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,166 @@
+/**
+ * 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,
+  clineConfigPath,
+  clineHomeDir,
+  dshConfigPath,
+  dshHomeDir,
+  gajaeConfigPath,
+  gajaeHomeDir,
+  hermesConfigPath,
+  hermesHomeDir,
+  kimiConfigPath,
+  kimiHomeDir,
+  mcodeConfigPath,
+  mcodeHomeDir,
+  ompAgentDir,
+  ompModelsConfigPath,
+  opencodeGlobalConfigPath,
+  openclawConfigPath,
+  openclawHomeDir,
+  piAgentDir,
+  piConfigPath,
+  primeAgentDir,
+  primeConfigPath,
+  zcodeConfigPath,
+  zcodeHomeDir,
+  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;
+  /** Patch only this block-map YAML leaf; never re-render the shared file. */
+  sourcePreservingYaml?: { path: readonly string[] };
+  /** Coordinate the complete mutation through a sibling config lock. */
+  writerLock?: { suffix: ".lock" };
+}
+
+/**
+ * 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()) => piConfigPath(env, home),
+    /*
+     * Deliberately not `piAgentDir` unconditionally. Without an override the
+     * install signal stays `~/.pi`, which is what it has always been: narrowing
+     * it to `~/.pi/agent` would flip a user who has the former without the
+     * latter from installed to absent, and this change is about honoring the
+     * override, not about redefining detection. With an override there is no
+     * parent worth testing — the variable names the agent directory itself — so
+     * that directory becomes the signal.
+     */
+    detectDir: (env = process.env, home = homedir()) =>
+      env.PI_CODING_AGENT_DIR?.trim() ? piAgentDir(env, home) : join(home, ".pi"),
+  },
+  omp: {
+    id: "omp",
+    configPath: (env = process.env, home = homedir()) => ompModelsConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => ompAgentDir(env, home),
+    sourcePreservingYaml: { path: ["providers", "opencodex"] },
+  },
+  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),
+  },
+  dsh: {
+    id: "dsh",
+    configPath: (env = process.env, home = homedir()) => dshConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => dshHomeDir(env, home),
+    sourcePreservingYaml: { path: ["llm-pi-ai", "providers", "opencodex"] },
+    writerLock: { suffix: ".lock" },
+  },
+  mcode: {
+    id: "mcode",
+    configPath: (env = process.env, home = homedir()) => mcodeConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => mcodeHomeDir(env, home),
+    writerLock: { suffix: ".lock" },
+  },
+  zcode: {
+    id: "zcode",
+    configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+  },
+  prime: {
+    id: "prime",
+    configPath: (env = process.env, home = homedir()) => primeConfigPath(env, home),
+    // The agent directory, not its parent: `PRIME_AGENT_CODING_AGENT_DIR` names
+    // that directory directly, so there is no parent to test when the override
+    // is set. Same choice as OMP, whose detect signal is `ompAgentDir`.
+    detectDir: (env = process.env, home = homedir()) => primeAgentDir(env, home),
+  },
+  cline: {
+    id: "cline",
+    configPath: (env = process.env, home = homedir()) => clineConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => clineHomeDir(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,314 @@
+/**
+ * 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`;
+}
+
+/**
+ * Ceiling on container nesting for json documents, shared by the parse-time
+ * scanner (config-io.ts) and the serializer walk below. One constant on
+ * purpose: the walk must accept every document the scanner admits, or a file
+ * the classifier reported as recoverable would refuse at rewrite time. Real
+ * configs nest a handful of levels.
+ */
+export const MAX_JSON_NESTING = 1000;
+
+/** Error messages carry the path to the offending value; keep them readable. */
+function clampPath(path: string): string {
+  return path.length > 200 ? `${path.slice(0, 100)}…${path.slice(-100)}` : path;
+}
+
+/**
+ * JSON.stringify writes a non-finite number as `null` and -0 as `0`; any
+ * other finite double round-trips value-exactly (literal-level rounding is
+ * the parse-time scanner's concern), so those two are exactly what this walk
+ * refuses — refusing more turned a state the classifier had promised as
+ * recoverable into a permanent refusal. Documents read from disk are already
+ * guarded at parse time, and the writer's merge layer JSON-clones documents —
+ * normalizing these values — before serializing, so on the apply/disable path
+ * this walk is unreachable for them: it guards the direct serializers
+ * (preview/export builders), same posture as the YAML and TOML renderers
+ * above, and enforces the nesting ceiling for every json caller before the
+ * recursive JSON.stringify can turn depth into a RangeError.
+ *
+ * Iterative frames instead of recursion or a node stack: depth AND size of
+ * the document are inputs under the writer of the config file. Recursion made
+ * a deep file a RangeError-500; materializing every node with its path made a
+ * wide file allocate a large multiple of its size. Frames keep memory
+ * proportional to nesting depth, and path strings exist only for the
+ * containers on the current path plus the failing value itself.
+ */
+function assertJsonNumbersRoundTrip(document: unknown, rootPath: string): void {
+  const refuse = (value: number, path: string): never => {
+    throw new UnserializableValueError(Object.is(value, -0)
+      ? `JSON cannot rewrite -0 at ${clampPath(path)} without changing it to 0`
+      : `JSON cannot rewrite the number at ${clampPath(path)} without changing it to null`);
+  };
+  if (typeof document === "number" && (!Number.isFinite(document) || Object.is(document, -0))) {
+    refuse(document, rootPath);
+  }
+  type Frame = { container: unknown; keys: string[] | null; index: number; prefix: string };
+  const frames: Frame[] = [];
+  const pushContainer = (value: unknown, prefix: string) => {
+    if (Array.isArray(value)) frames.push({ container: value, keys: null, index: 0, prefix });
+    else if (isPlainRecord(value)) frames.push({ container: value, keys: Object.keys(value), index: 0, prefix });
+  };
+  pushContainer(document, rootPath);
+  while (frames.length > 0) {
+    const frame = frames[frames.length - 1]!;
+    const length = frame.keys ? frame.keys.length : (frame.container as unknown[]).length;
+    if (frame.index >= length) { frames.pop(); continue; }
+    const i = frame.index;
+    frame.index += 1;
+    const child = frame.keys
+      ? (frame.container as Record<string, unknown>)[frame.keys[i]!]
+      : (frame.container as unknown[])[i];
+    const childPath = () => frame.keys
+      ? (frame.prefix === "$" ? frame.keys[i]! : `${frame.prefix}.${frame.keys[i]!}`)
+      : `${frame.prefix}[${i}]`;
+    if (typeof child === "number") {
+      if (!Number.isFinite(child) || Object.is(child, -0)) refuse(child, childPath());
+      continue;
+    }
+    if (typeof child === "object" && child !== null) {
+      if (frames.length >= MAX_JSON_NESTING) {
+        throw new UnserializableValueError(
+          `the document nests deeper than ${MAX_JSON_NESTING} levels at ${clampPath(childPath())}, which JSON serialization cannot rewrite safely`);
+      }
+      pushContainer(child, childPath());
+    }
+  }
+}
+
+/** Every serializer returns text ending in exactly one newline. */
+export function serializeDocument(document: unknown, format: ConfigFormat): string {
+  switch (format) {
+    case "json": {
+      assertJsonNumbersRoundTrip(document, "$");
+      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);
+    }
+  }
+}