@visual-z/xeno 0.8.4 → 0.9.0

package/src/store/log.ts

@@ -1,725 +0,0 @@
-/**
- * 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 { access, 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";
-import { stateAtPosition } from "../core/session-position.ts";
-import { SESSION_FORMAT, SessionFormatError } from "../core/session-format.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;
-  /** New cursors disambiguate identical model IDs served by different providers. */
-  provider?: string;
-  /** Configuration takes effect after this committed event; absent means node start. */
-  at_event?: string;
-  thinking?: string;
-  blob_dir?: string;
-  /** Legacy historical positions with unknown model provenance must cut before dispatch. */
-  needs_model_checkpoint?: boolean;
-  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;
-  /**
-   * The xeno release that wrote this cursor. Every start writes one, so the
-   * append-only metadata journal is a timeline of the versions a session ran under.
-   */
-  xeno_version?: 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[];
-  /** An import keeps historical bytes and relocates their storage through journal metadata. */
-  relocated?: true;
-  /** Absent in a log written before resume existed, and in an empty one. */
-  cursor?: Cursor;
-  parent_session?: string;
-  labels?: Record<string, { text: string; at: string }>;
-}
-
-/**
- * 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;
-}
-
-type MetadataRecord =
-  | { kind: "format"; version: number }
-  | { kind: "relocate"; workspace: string }
-  | { kind: "cursor"; cursor: Cursor }
-  | { kind: "parent_session"; path: string }
-  | { kind: "label"; target: string; text: string; at: string }
-  | { kind: "node"; record: NodeRecord };
-
-function metadataPath(dir: string): string { return join(dir, "metadata.jsonl"); }
-
-/**
- * S.3: the journal's first record declares the session format. A directory in
- * any other format -- a journal opening with something else, or a manifest
- * with no journal at all -- is refused before anything reads or writes it.
- * Null means a directory no session has written yet.
- */
-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") throw error;
-    if (await access(manifestPath(dir)).then(() => true, () => false)) throw new SessionFormatError(dir, "undeclared");
-    return null;
-  }
-  if (text.length > 0 && !text.endsWith("\n")) throw new Error("INTEGRITY: incomplete metadata journal tail; no cursor is guessed");
-  const records = 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;
-  });
-  const first = records[0];
-  if (first?.kind !== "format") throw new SessionFormatError(dir, "undeclared");
-  if (first.version !== SESSION_FORMAT) throw new SessionFormatError(dir, first.version);
-  return records;
-}
-
-/** The metadata journal already owns configuration history; no second state log is needed. */
-export async function readCursorAt(dir: string, node: number, atEvent?: string): Promise<Cursor | null> {
-  const records = await readMetadata(dir);
-  const states: Cursor[] = [];
-  let relocated = false;
-  for (const record of records ?? []) {
-    if (record.kind === "cursor") states.push({ ...record.cursor });
-    else if (record.kind === "relocate") { relocated = true; for (const state of states) state.workspace = record.workspace; }
-  }
-  if (relocated) for (const state of states) state.blob_dir = join(dir, "blobs");
-  const { events } = await readNode(dir, node);
-  return stateAtPosition(states, node, events.map(event => event.id), atEvent);
-}
-
-/**
- * When this session was forked, or null for an original (fix-fork-start-time).
- * copyAncestryTo keeps the parent's nodes and their timestamps, then writes
- * the fork cursor and, right after it, the parent_session record; that
- * cursor's updated_at is the fork moment. The last parent_session record is
- * this session's own: a copied parent that was itself a fork brings its
- * record along in the copied journal.
- */
-export async function forkedAt(dir: string): Promise<string | null> {
-  const records = await readMetadata(dir) ?? [];
-  const own = records.findLastIndex(record => record.kind === "parent_session");
-  const cursor = records.slice(0, Math.max(0, own)).findLast(record => record.kind === "cursor");
-  return own >= 0 && cursor?.kind === "cursor" ? cursor.cursor.updated_at : null;
-}
-
-/** 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);
-  const manifest: Manifest = { version: 1, nodes: [] };
-  for (const event of records ?? []) {
-    switch (event.kind) {
-      case "format": break;
-      case "cursor": manifest.cursor = event.cursor; break;
-      case "relocate":
-        manifest.relocated = true;
-        if (manifest.cursor) manifest.cursor = { ...manifest.cursor, workspace: event.workspace };
-        break;
-      case "parent_session": manifest.parent_session = event.path; break;
-      case "label":
-        manifest.labels ??= {};
-        if (event.text) Object.defineProperty(manifest.labels, event.target, { value: { text: event.text, at: event.at }, enumerable: true, configurable: true, writable: true });
-        else delete manifest.labels[event.target];
-        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);
-  if (manifest.relocated && manifest.cursor) manifest.cursor = { ...manifest.cursor, blob_dir: join(dir, "blobs") };
-  return manifest;
-}
-
-/** Relocation changes recovery locations, not historical events or evidence (D3/D8). */
-export async function relocateSession(dir: string, workspace: string): Promise<void> {
-  return serialized(dir, async () => {
-    await appendMetadata(dir, { kind: "relocate", workspace });
-    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
-  });
-}
-
-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";
-  // The first write declares the format; readMetadata has already refused a
-  // directory in any other format, so nothing here appends to an old log.
-  if (await readMetadata(dir) === null) await durableAppend(metadataPath(dir), encode({ kind: "format", version: SESSION_FORMAT }));
-  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;
-}
-
-/** Labels are display metadata, never model evidence or rewritten conversation events. */
-export async function setSessionLabel(dir: string, target: string, text: string, at: string): Promise<void> {
-  return serialized(dir, async () => {
-    await appendMetadata(dir, { kind: "label", target, text: text.trim(), at });
-    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
-  });
-}
-export async function setParentSession(dir: string, path: string): Promise<void> {
-  return serialized(dir, async () => {
-    await appendMetadata(dir, { kind: "parent_session", path });
-    await atomicWrite(manifestPath(dir), JSON.stringify(await readManifestUnlocked(dir), null, 2) + "\n");
-  });
-}
-
-/** 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;
-}