@visual-z/xeno 0.1.0

package/src/store/log.ts

@@ -0,0 +1,642 @@
+/**
+ * The session tree on disk (card: refactor-log-tree).
+ *
+ * The only module in the project that does I/O, so ordering, durability and
+ * corruption are handled here and nowhere else.
+ *
+ * Layout:
+ *   log/node-0000.jsonl       header line, then one JSON event per line
+ *   log/handoff-0000.yaml     the handoff derived when that node closed
+ *   log/manifest.json         the index: one fixed-size record per closed node
+ *
+ * NNNN is the node's ALLOCATION order, not its position in the tree. Structure
+ * lives only in parent pointers -- the same split git makes between a commit's
+ * identity and its shape. A linear session is the degenerate tree where every
+ * node has one child, which is why this refactor leaves behaviour unchanged.
+ *
+ * One file per node, one writer per file. That is what makes parallel branches
+ * free of contention: no locks, no interleaved half-written lines, and D14's
+ * "a subagent writes its own branch file" becomes automatic rather than an
+ * extra mechanism.
+ *
+ * JSONL rather than SQLite so the agent can recover anything a handoff omits
+ * with the tools it already has -- grep, sed, jq -- and no recall tool has to
+ * exist. What that gives up is a real index, so cross-node queries by resource
+ * are linear scans; per-node files keep each one small enough for that to be
+ * fine and, unlike a single rollout file, nothing grows without bound.
+ */
+
+import { mkdir, readdir, readFile, open } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { LogEvent, NodeRef, IsoTime, EventId } from "../core/events.ts";
+import { assertNever } from "../core/exhaustive.ts";
+import type { Handoff } from "../core/handoff.ts";
+import { isLogEvent, isRecord, validNodeRef } from "../core/event-validation.ts";
+import { emitHandoff } from "../core/handoff.ts";
+import { atomicWrite, durableAppend } from "./atomic.ts";
+import { serialized } from "./serial.ts";
+
+/** Allocation number. Not an ordering over the tree. */
+export type NodeId = number;
+
+/**
+ * The first line of every node file.
+ *
+ * It shares the file with events and is shaped like one, but it is not an
+ * event: it describes the node rather than something that happened inside it,
+ * so readNode returns it separately and it never reaches the projection.
+ */
+/**
+ * What a node takes from its parent.
+ *
+ *   inherit  the parent's events, so the prefix is shared and the cache with
+ *            it -- a fork exploring an alternative
+ *   handoff  the parent's derived handoff instead of its events -- a cut,
+ *            taken when the context filled
+ *   none     nothing; the parent pointer records provenance only -- a
+ *            subagent working in isolation
+ *
+ * Declared by the child rather than inferred from the parent, because the
+ * same parent can have children of every kind at once. Inferring it from
+ * whether the parent had a handoff is right for a linear session and wrong
+ * for a fork, whose parent is almost always closed.
+ */
+export type Basis = "inherit" | "handoff" | "none";
+
+export interface NodeHeader {
+  t: "header";
+  node: NodeId;
+  parent: NodeRef | null;
+  basis: Basis;
+  created_at: IsoTime;
+  adopted_from?: NodeRef;
+}
+
+export interface NodeRecord {
+  node: NodeId;
+  parent: NodeRef | null;
+  log_ref: string;
+  sha256: string;
+  handoff_ref: string | null;
+  events: number;
+  closed_at: IsoTime;
+}
+
+/**
+ * Where the session was when it last stopped.
+ *
+ * Written down rather than inferred. The manifest indexes only CLOSED nodes,
+ * so the open one is not in it -- and the tree shape cannot be read backwards
+ * to find the cursor, because three legal shapes are indistinguishable: a
+ * node abandoned by a rewind stays open, a resolved branch holds the highest
+ * id while the cursor sits in its parent, and both can be true at once. This
+ * project already settled the same question once, for `basis`, and settled it
+ * the same way: declare it instead of deducing it.
+ */
+export interface Cursor {
+  /** The open node the session was working in. */
+  node: NodeId;
+  /**
+   * The allocator's state, not `max(id) + 1`. Dead limbs and resolved
+   * branches both hold ids, and recomputing the next one is exactly the
+   * shape of the bug that once had a cut and a branch agree on id 1 and
+   * silently truncate a node's whole log.
+   */
+  next_node: NodeId;
+  /**
+   * The model this session ran under. Its thinking blocks are that model's:
+   * replaying them to another provider is a bad request, so resume checks
+   * this rather than discovering it on the wire.
+   */
+  model: string;
+  updated_at: IsoTime;
+  /** Active checkout, which changes when a writing branch becomes mainline. */
+  workspace?: string;
+  /** Content-addressed frozen context; credentials and approvals are excluded. */
+  context_ref?: string;
+  /**
+   * A human name. Optional because most sessions never get one, and a log
+   * written before names existed has none. Absent rather than empty: an
+   * empty string would still show up in a listing as a name that isn't.
+   */
+  name?: string;
+}
+
+export interface Manifest {
+  version: 1;
+  nodes: NodeRecord[];
+  /** Absent in a log written before resume existed, and in an empty one. */
+  cursor?: Cursor;
+}
+
+/**
+ * A chain longer than this is a bug rather than a deep session: it would mean
+ * thousands of boundaries with no progress, which the stop-and-ask rule (D9)
+ * catches long before. The cap exists so a malformed tree fails fast instead
+ * of consuming the process -- unbounded traversal is not allowed here any more
+ * than an unbounded buffer would be.
+ */
+export const MAX_ANCESTRY_DEPTH = 1000;
+
+const pad = (n: number) => String(n).padStart(4, "0");
+
+export function nodePath(dir: string, node: NodeId): string {
+  return join(dir, `node-${pad(node)}.jsonl`);
+}
+
+export function handoffPath(dir: string, node: NodeId): string {
+  return join(dir, `handoff-${pad(node)}.yaml`);
+}
+
+export function manifestPath(dir: string): string {
+  return join(dir, "manifest.json");
+}
+
+export async function initLog(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+/**
+ * Every node in the log, in allocation order.
+ *
+ * From the directory rather than the manifest: the manifest holds only CLOSED
+ * nodes, and an open node -- including the one being written right now -- is
+ * exactly the one a reader is most likely to be asking about.
+ */
+export async function listNodes(dir: string): Promise<NodeId[]> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return [];
+    throw err;
+  }
+  return names
+    .map((n) => /^node-(\d+)\.jsonl$/.exec(n))
+    .filter((m): m is RegExpExecArray => m !== null)
+    .map((m) => Number(m[1]))
+    .sort((a, b) => a - b);
+}
+
+/** Creates a node file by writing its header. Must precede any appendEvent. */
+export async function initNode(
+  dir: string,
+  node: NodeId,
+  parent: NodeRef | null,
+  createdAt: IsoTime,
+  // Defaults to inherit, which is the only safe choice for an unstated one:
+  // inheriting too much shows the model work it has already seen, while
+  // truncating too early silently hides work it needed. A caller that means
+  // to cut says so.
+  basis: Basis = parent === null ? "none" : "inherit",
+  metadata: Pick<NodeHeader, "adopted_from"> = {},
+): Promise<NodeHeader> {
+  const header: NodeHeader = { t: "header", node, parent, basis, created_at: createdAt, ...metadata };
+  try {
+    // Exclusive create. A node log is append-only, so a second init is always
+    // a bug -- and writeFile would truncate, taking every event in the node
+    // with it while every ref pointing at it still resolves. Two allocators
+    // over one id namespace once did exactly that here, silently.
+    const file = await open(nodePath(dir, node), "wx", 0o600);
+    try { await file.writeFile(JSON.stringify(header) + "\n"); await file.sync(); }
+    finally { await file.close(); }
+    const directory = await open(dir, "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } catch (err) {
+    if ((err as { code?: string }).code === "EEXIST") {
+      throw new Error(`node ${node} already exists at ${nodePath(dir, node)} -- refusing to overwrite it`);
+    }
+    throw err;
+  }
+  return header;
+}
+
+/**
+ * Appends one event as a single line.
+ *
+ * JSON.stringify never emits a raw newline inside a string, so one event is
+ * always exactly one line and a partially written tail can only ever damage
+ * the last line -- which readNode reports rather than silently dropping.
+ */
+export async function appendEvent(
+  dir: string,
+  node: NodeId,
+  event: LogEvent,
+): Promise<void> {
+  if ((await readManifest(dir)).nodes.some((entry) => entry.node === node)) {
+    throw new Error(`INTEGRITY: cannot append to sealed node ${node}`);
+  }
+  await durableAppend(nodePath(dir, node), JSON.stringify(event) + "\n");
+}
+
+export interface ReadResult {
+  /** Null when the file has no header line, which is itself reported as corrupt. */
+  header: NodeHeader | null;
+  events: LogEvent[];
+  /** Lines that would not parse. Surfaced, never skipped quietly. */
+  corrupt: { line: number; text: string }[];
+}
+
+export async function readNode(dir: string, node: NodeId): Promise<ReadResult> {
+  let text: string;
+  try {
+    text = await readFile(nodePath(dir, node), "utf8");
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") {
+      return { header: null, events: [], corrupt: [] };
+    }
+    throw err;
+  }
+
+  let header: NodeHeader | null = null;
+  const events: LogEvent[] = [];
+  const corrupt: ReadResult["corrupt"] = [];
+  const lines = text.split("\n");
+  const ids = new Set<string>();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.length === 0) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      corrupt.push({ line: i + 1, text: line.slice(0, 200) });
+      continue;
+    }
+    // The header describes the node; it is not something that happened in it.
+    if (isRecord(parsed) && parsed["t"] === "header") {
+      if (i !== 0 || header !== null || parsed["node"] !== node || typeof parsed["created_at"] !== "string" ||
+          !(parsed["parent"] === null || validNodeRef(parsed["parent"])) ||
+          !(parsed["basis"] === undefined || ["inherit", "none", "handoff"].includes(String(parsed["basis"])))) {
+        corrupt.push({ line: i + 1, text: line.slice(0, 200) }); continue;
+      }
+      header = {
+        t: "header", node, parent: parsed["parent"], created_at: parsed["created_at"],
+        basis: parsed["basis"] === undefined ? (parsed["parent"] === null ? "none" : "inherit") : parsed["basis"] as Basis,
+        ...(validNodeRef(parsed["adopted_from"]) ? { adopted_from: parsed["adopted_from"] } : {}),
+      };
+      continue;
+    }
+    if (!isLogEvent(parsed) || ids.has(parsed.id) || i === lines.length - 1) {
+      corrupt.push({ line: i + 1, text: line.slice(0, 200) }); continue;
+    }
+    ids.add(parsed.id);
+    events.push(parsed);
+  }
+
+  return { header, events, corrupt };
+}
+
+// ---------------------------------------------------------------------------
+// Ancestry
+// ---------------------------------------------------------------------------
+
+export interface AncestryError {
+  code:
+    | "CYCLE"
+    | "MISSING_PARENT"
+    | "TOO_DEEP"
+    | "MISSING_HEADER"
+    | "CORRUPT"
+    | "INTEGRITY"
+    | "MISSING_BASIS_HANDOFF"
+    | "MISSING_FORK_POINT";
+  detail: string;
+}
+
+export type AncestryResult =
+  | {
+      ok: true;
+      /**
+       * The ancestor whose handoff is the context basis, set when a node on
+       * the path declared `basis: "handoff"`. Its events do not replay. Null
+       * when the walk reached a root or a `none` boundary instead.
+       */
+      basis: { node: NodeId; handoff_ref: string } | null;
+      /** Root-to-leaf order, ready to hand to projectContext. */
+      events: LogEvent[];
+      /** Nodes contributing events, root-to-leaf. Excludes the basis node. */
+      visited: NodeId[];
+    }
+  | { ok: false; error: AncestryError };
+
+/**
+ * Walks the parent chain from `node` upward, collecting events, and stops at
+ * the first ancestor that closed with a handoff.
+ *
+ * Returns an error rather than partial results: a chain that cannot be walked
+ * means the caller's picture of the tree is wrong, and half an ancestry would
+ * project a context that silently omits work.
+ */
+export async function readAncestry(
+  dir: string,
+  node: NodeId,
+  manifest?: Manifest,
+): Promise<AncestryResult> {
+  const index = new Map(((manifest ?? await readManifest(dir)).nodes).map((r) => [r.node, r]));
+  const chain: { node: NodeId; events: LogEvent[] }[] = [];
+  // Revisiting a node means the parent pointers form a loop. The depth cap
+  // alone would stop the walk, but it would report exhaustion -- a reader
+  // needs to know the tree is malformed, not that the chain was long.
+  const seen = new Set<NodeId>();
+
+  let current: NodeId | null = node;
+  // Set when a child declared a fork point: the parent contributes only the
+  // events up to and including that one.
+  let cutoff: EventId | undefined;
+  let depth = 0;
+  let basis: { node: NodeId; handoff_ref: string } | null = null;
+
+  while (current !== null) {
+    if (seen.has(current)) {
+      return {
+        ok: false,
+        error: {
+          code: "CYCLE",
+          detail:
+            `parent chain from node ${node} revisits node ${current} ` +
+            `(walked ${[...seen].join(" -> ")})`,
+        },
+      };
+    }
+    seen.add(current);
+
+    if (depth++ >= MAX_ANCESTRY_DEPTH) {
+      return {
+        ok: false,
+        error: {
+          code: "TOO_DEEP",
+          detail: `ancestry of node ${node} exceeded ${MAX_ANCESTRY_DEPTH} nodes`,
+        },
+      };
+    }
+
+    const { header, events, corrupt } = await readNode(dir, current);
+    const sealed = index.get(current);
+    if (sealed && sealed.sha256 !== await digestNode(dir, current)) {
+      return { ok: false, error: { code: "INTEGRITY", detail: `node ${current} content digest does not match its sealed record` } };
+    }
+    if (header === null) {
+      return {
+        ok: false,
+        error: {
+          code: "MISSING_HEADER",
+          detail: `node ${current} has no header line (reached from ${node})`,
+        },
+      };
+    }
+    if (corrupt.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: "CORRUPT",
+          detail: `node ${current} has ${corrupt.length} unparsable line(s), first at ${corrupt[0]!.line}`,
+        },
+      };
+    }
+
+    // A fork point truncates this node's contribution. Naming an event the
+    // node does not have is an error rather than a silent fall back to all of
+    // them: the caller's picture of the tree is wrong either way, and half an
+    // ancestry projects a context that quietly omits work.
+    let contributed = events;
+    if (cutoff !== undefined) {
+      const at = events.findIndex((e) => e.id === cutoff);
+      if (at < 0) {
+        return {
+          ok: false,
+          error: {
+            code: "MISSING_FORK_POINT",
+            detail: `node ${current} has no event ${cutoff} (fork point reached from ${node})`,
+          },
+        };
+      }
+      contributed = events.slice(0, at + 1);
+    }
+    chain.push({ node: current, events: contributed });
+
+    const parent: NodeRef | null = header.parent;
+    if (parent === null) break;
+
+    // What this node takes from its parent is declared here, not inferred
+    // from the parent. The same parent can have a fork, a cut and a subagent
+    // as children at once, so no property of the parent could decide it.
+    switch (header.basis) {
+      case "none":
+        // The parent pointer is provenance; it contributes no context.
+        current = null;
+        break;
+      case "handoff": {
+        const record = index.get(parent.node);
+        if (!record?.handoff_ref) {
+          return {
+            ok: false,
+            error: {
+              code: "MISSING_BASIS_HANDOFF",
+              detail:
+                `node ${current} declares a handoff basis but node ${parent.node} has none ` +
+                `(it may not be closed yet, or the manifest was not passed)`,
+            },
+          };
+        }
+        basis = { node: parent.node, handoff_ref: record.handoff_ref };
+        current = null;
+        break;
+      }
+      case "inherit":
+        cutoff = parent.at_event;
+        current = parent.node;
+        break;
+      default:
+        return assertNever(header.basis, "readAncestry");
+    }
+  }
+
+  chain.reverse();
+  return {
+    ok: true,
+    basis,
+    events: chain.flatMap((c) => c.events),
+    visited: chain.map((c) => c.node),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Digest, handoff, manifest
+// ---------------------------------------------------------------------------
+
+export async function digestNode(dir: string, node: NodeId): Promise<string> {
+  try {
+    const buf = await readFile(nodePath(dir, node));
+    return createHash("sha256").update(buf).digest("hex");
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") {
+      return createHash("sha256").update("").digest("hex");
+    }
+    throw err;
+  }
+}
+
+export async function writeHandoff(
+  dir: string,
+  node: NodeId,
+  handoff: Handoff,
+): Promise<string> {
+  const text = emitHandoff(handoff);
+  await atomicWrite(handoffPath(dir, node), text);
+  return text;
+}
+
+async function readLegacyManifest(dir: string): Promise<Manifest> {
+  try {
+    return JSON.parse(await readFile(manifestPath(dir), "utf8")) as Manifest;
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return { version: 1, nodes: [] };
+    throw err;
+  }
+}
+
+type MetadataRecord =
+  | { kind: "seed"; manifest: Manifest }
+  | { kind: "cursor"; cursor: Cursor }
+  | { kind: "node"; record: NodeRecord };
+
+function metadataPath(dir: string): string { return join(dir, "metadata.jsonl"); }
+
+async function readMetadata(dir: string): Promise<MetadataRecord[] | null> {
+  let text: string;
+  try { text = await readFile(metadataPath(dir), "utf8"); }
+  catch (error) {
+    if ((error as { code?: string }).code === "ENOENT") return null;
+    throw error;
+  }
+  if (text.length > 0 && !text.endsWith("\n")) throw new Error("INTEGRITY: incomplete metadata journal tail; no cursor is guessed");
+  return text.split("\n").filter(Boolean).map((line) => {
+    const envelope = JSON.parse(line) as { record: MetadataRecord; sha256: string };
+    const digest = createHash("sha256").update(JSON.stringify(envelope.record)).digest("hex");
+    if (envelope.sha256 !== digest) throw new Error("INTEGRITY: metadata journal digest mismatch");
+    return envelope.record;
+  });
+}
+
+/** D3: the replaceable manifest is a projection of committed metadata events. */
+export async function readManifest(dir: string): Promise<Manifest> {
+  return serialized(dir, () => readManifestUnlocked(dir));
+}
+
+async function readManifestUnlocked(dir: string): Promise<Manifest> {
+  const records = await readMetadata(dir);
+  if (records === null) return readLegacyManifest(dir);
+  let manifest: Manifest = { version: 1, nodes: [] };
+  for (const event of records) {
+    switch (event.kind) {
+      case "seed": manifest = structuredClone(event.manifest); break;
+      case "cursor": manifest.cursor = event.cursor; break;
+      case "node": {
+        const i = manifest.nodes.findIndex((n) => n.node === event.record.node);
+        if (i < 0) manifest.nodes.push(event.record);
+        else manifest.nodes[i] = event.record;
+        break;
+      }
+      default: return assertNever(event, "metadata journal");
+    }
+  }
+  manifest.nodes.sort((a, b) => a.node - b.node);
+  return manifest;
+}
+
+async function appendMetadata(dir: string, event: MetadataRecord): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  const encode = (record: MetadataRecord) => JSON.stringify({
+    record, sha256: createHash("sha256").update(JSON.stringify(record)).digest("hex"),
+  }) + "\n";
+  if (await readMetadata(dir) === null) {
+    // Preserve old manifests once, then make every subsequent move append-only.
+    const seed: MetadataRecord = { kind: "seed", manifest: await readLegacyManifest(dir) };
+    await durableAppend(metadataPath(dir), encode(seed));
+  }
+  await durableAppend(metadataPath(dir), encode(event));
+}
+
+/**
+ * Moves the cursor. Called at every point the session changes node, so that
+ * "where was I" is a recorded fact rather than a reconstruction.
+ *
+ * Rewrites the whole manifest, like `recordNode`, so the index and the cursor
+ * cannot disagree -- two files could say node 7 is both closed and current.
+ *
+ * A name already on the cursor is kept unless the caller set one. The loop
+ * writes the cursor at every move and does not know about names; replacing
+ * the whole record would drop a name the moment a session cuts or starts,
+ * making `/name` a lie.
+ */
+export async function writeCursor(dir: string, cursor: Cursor): Promise<void> {
+  return serialized(dir, async () => {
+    const manifest = await readManifestUnlocked(dir);
+    const previousName = manifest.cursor?.name;
+    manifest.cursor =
+      previousName !== undefined && !("name" in cursor)
+        ? { ...cursor, name: previousName }
+        : cursor;
+    await appendMetadata(dir, { kind: "cursor", cursor: manifest.cursor });
+    await atomicWrite(manifestPath(dir), JSON.stringify(manifest, null, 2) + "\n");
+  });
+}
+
+export async function readCursor(dir: string): Promise<Cursor | null> {
+  return (await readManifest(dir)).cursor ?? null;
+}
+
+/** Direct children of `node`, in allocation order. */
+export function childrenOf(manifest: Manifest, node: NodeId): NodeRecord[] {
+  return manifest.nodes.filter((r) => r.parent?.node === node);
+}
+
+/** Records with no parent. A well-formed tree has exactly one. */
+export function rootsOf(manifest: Manifest): NodeRecord[] {
+  return manifest.nodes.filter((r) => r.parent === null);
+}
+
+/**
+ * Records a closed node. Rewrites the manifest whole, which is fine because it
+ * holds one small record per node -- and makes the file atomically consistent
+ * rather than an append log that can end mid-record.
+ */
+export async function recordNode(dir: string, record: NodeRecord): Promise<Manifest> {
+  return serialized(dir, async () => {
+    const manifest = await readManifestUnlocked(dir);
+    const existing = manifest.nodes.findIndex((r) => r.node === record.node);
+    if (existing >= 0) manifest.nodes[existing] = record;
+    else manifest.nodes.push(record);
+    manifest.nodes.sort((a, b) => a.node - b.node);
+    await appendMetadata(dir, { kind: "node", record });
+    await atomicWrite(manifestPath(dir), JSON.stringify(manifest, null, 2) + "\n");
+    return manifest;
+  });
+}
+
+/** Closes a node: fingerprint it, write its handoff, index it. */
+export async function closeNode(
+  dir: string,
+  node: NodeId,
+  handoff: Handoff,
+  eventCount: number,
+  closedAt: IsoTime,
+): Promise<NodeRecord> {
+  const { header } = await readNode(dir, node);
+  const sha256 = await digestNode(dir, node);
+  await writeHandoff(dir, node, handoff);
+  const record: NodeRecord = {
+    node,
+    parent: header?.parent ?? null,
+    log_ref: nodePath(dir, node),
+    sha256,
+    handoff_ref: handoffPath(dir, node),
+    events: eventCount,
+    closed_at: closedAt,
+  };
+  await recordNode(dir, record);
+  return record;
+}

package/src/store/models.ts

@@ -0,0 +1,41 @@
+/**
+ * The on-disk catalog overlay. `~/.xeno/models.json`, next to auth.json.
+ *
+ * This layer only reads and writes bytes. It does not know what a ModelSpec
+ * is — that lives in runtime — because store may not import runtime. A
+ * corrupt file is returned as text plus no error: the parser names the bad
+ * entry, and discarding the whole file here would be the thing the card
+ * forbids.
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configDir } from "./config.ts";
+
+export function modelsPath(): string {
+  return join(configDir(), "models.json");
+}
+
+export async function readModelsText(): Promise<{ text: string | null; error: string | null }> {
+  try {
+    const text = await readFile(modelsPath(), "utf8");
+    return { text, error: null };
+  } catch {
+    // Absent is the normal first-run state, not an error.
+    return { text: null, error: null };
+  }
+}
+
+/**
+ * Replace, don't truncate. writeFile on the live path empties it first, so a
+ * crash or a thrown write would leave the user with no catalog. Sidecar then
+ * rename is atomic on the same filesystem; a failed refresh must leave the
+ * existing bytes untouched (feat-json-mode-and-header).
+ */
+export async function writeModelsFile(value: unknown): Promise<void> {
+  await mkdir(configDir(), { recursive: true });
+  const dest = modelsPath();
+  const tmp = `${dest}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await rename(tmp, dest);
+}