@ccmsg/cli 0.1.0

package/src/instance/lock.ts

@@ -0,0 +1,108 @@
+import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** The right to be the instance for one config home (§8.3 step 2).
+ *
+ * A handle, not state (§3.6): it says who is running right now and means
+ * nothing once the process is gone. */
+export interface Lock {
+  release(): void;
+}
+
+/** Whoever holds it, when we do not. */
+export interface Held {
+  readonly pid: number;
+}
+
+/** How many rounds of "somebody else's file is stale, drop it and contend
+ * again" one acquisition may run. Each round either wins, names a live holder
+ * or removes one dead file, so reaching this means the file is being recreated
+ * as fast as it is removed, or is something no starter can read or unlink. A
+ * loop is the wrong answer to either; the caller is told instead. */
+const ROUNDS = 100;
+
+/** Take the lock, or report who has it.
+ *
+ * The lock file is created by linking a file that already names its pid, so it
+ * exists only in the finished state: a starter that finds it never reads an
+ * empty file and never mistakes a lock being taken for a stale one. `link` is
+ * what excludes — it fails when the name is there — so two processes racing
+ * for the same config home cannot both win.
+ *
+ * What that does not settle is a file left by a process that died without
+ * releasing it: the file names its pid, so the next starter asks the OS whether
+ * that pid is still there and takes over the file when it is not. Asking is
+ * signal 0, which tests for the process without touching it. */
+export function acquireLock(file: string): Lock | Held {
+  mkdirSync(dirname(file), { recursive: true });
+  for (let round = 0; round < ROUNDS; round++) {
+    const staged = `${file}.${process.pid}.${randomUUID()}`;
+    writeFileSync(staged, `${process.pid}\n`);
+    try {
+      linkSync(staged, file);
+      return { release: () => release(file) };
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") throw cause;
+    } finally {
+      try {
+        unlinkSync(staged);
+      } catch {
+        // The link is what matters; the staging name is scratch either way.
+      }
+    }
+    const holder = readHolder(file);
+    if (holder !== undefined && alive(holder)) return { pid: holder };
+    // Nobody is behind the file: drop it and contend again, so two starters
+    // finding the same stale lock still produce one winner.
+    try {
+      unlinkSync(file);
+    } catch {
+      // Another starter got there first; the next attempt sees its file.
+    }
+  }
+  throw new Error(`${file} could neither be taken nor cleared`);
+}
+
+/** Whether a lock outcome is the lock itself rather than someone else's. */
+export function isHeldByUs(outcome: Lock | Held): outcome is Lock {
+  return "release" in outcome;
+}
+
+function release(file: string): void {
+  try {
+    unlinkSync(file);
+  } catch {
+    // Already gone.
+  }
+}
+
+/** The pid the lock file names, whether or not it is still there. Asking who
+ * holds a config home is the same question a starter asks, so it is the same
+ * file that answers it. */
+export function lockHolder(file: string): number | undefined {
+  return readHolder(file);
+}
+
+function readHolder(file: string): number | undefined {
+  try {
+    const pid = Number(readFileSync(file, "utf8").trim());
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether a pid names a process that is still there. Signal 0 asks the OS
+ * without touching it, which is how both the stale lock and the orphaned
+ * socket of a previous run are told from a live one. */
+export function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (cause) {
+    // EPERM means the process exists and belongs to somebody else, which
+    // cannot happen here (A4, single uid) but still means "there".
+    return (cause as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

package/src/instance/log.ts

@@ -0,0 +1,30 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** The instance's log: one writer, and every line on disk before the call
+ * returns (§3.6).
+ *
+ * The reason to read a log is to find out why a process stopped, so the line
+ * that matters most is the last one written before it did. A buffered writer
+ * is the one that loses exactly that line, so this one appends synchronously
+ * and holds nothing — the cost is a write per line, on a file that takes a
+ * line per lifecycle event rather than per request. */
+export class Log {
+  constructor(
+    private readonly file: string,
+    /** Mirrored to stderr so a foreground run shows what it is doing. */
+    private readonly echo: boolean = true,
+  ) {
+    mkdirSync(dirname(file), { recursive: true });
+  }
+
+  write(message: string, fields: Record<string, unknown> = {}): void {
+    const line = JSON.stringify({ at: new Date().toISOString(), message, ...fields });
+    if (this.echo) process.stderr.write(`${line}\n`);
+    try {
+      appendFileSync(this.file, `${line}\n`);
+    } catch {
+      // A log that cannot be written is not a reason to stop serving.
+    }
+  }
+}

package/src/instance/paths.ts

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+
+/** Every path one instance uses, decided in one place (daemon-v2 §8.1).
+ *
+ * All of them are derived from the config home, because the config home is
+ * what an instance is (A2): two instances differ in exactly that, so deriving
+ * from it is what keeps their sockets, state and logs apart without anyone
+ * configuring the separation. */
+export interface InstancePaths {
+  /** The one config home this instance answers for (M6). */
+  readonly configHome: string;
+  /** What distinguishes this instance's files from another instance's. */
+  readonly key: string;
+  /** The one file a person edits, shared by every instance on this host: it
+   * carries the defaults and the list of config homes, so it is not derived
+   * from the config home the way the rest of these are. */
+  readonly configFile: string;
+  readonly stateDir: string;
+  /** The address clients connect to. A symlink to whichever `socketReal` is
+   * currently serving, so a client's path outlives the process behind it. */
+  readonly socket: string;
+  /** The path this process actually binds, named after its pid.
+   *
+   * Bun unlinks the path it listened on when the listener stops (measured
+   * against Bun 1.3.13), so binding the stable path directly would mean a
+   * departing instance deleting the address its successor had already taken
+   * over (§8.5). Binding a path of its own leaves it deleting only its own. */
+  readonly socketReal: string;
+  /** Where both of the above live, so the orphan sweep has one directory. */
+  readonly socketDir: string;
+  /** Where the agent plugins this instance hands out are laid down, one
+   * directory per agent. They live with the state because they are derived
+   * from the binary: losing them costs an `install` and nothing else. */
+  readonly pluginsDir: string;
+  readonly pidFile: string;
+  readonly lockFile: string;
+  readonly logFile: string;
+  /** Where this instance's own id is kept (§3.6). It lives with the state
+   * because moving an instance is moving that directory: the id has to travel
+   * with it, since everything the instance issued is keyed by it. */
+  readonly instanceIdFile: string;
+}
+
+/** `sun_path` on macOS, the shorter of the two platforms this runs on
+ * (measured in `sys/un.h`, 104 there and 108 on Linux). A path at or past it
+ * cannot be bound at all, so it is checked rather than discovered as a
+ * bind failure. */
+const MAX_SOCKET_PATH = 104;
+
+/** The stable address, and the name of the path one process binds. */
+export const SOCKET_NAME = "daemon.sock";
+
+export function realSocketName(pid: number): string {
+  return `daemon.${pid}.sock`;
+}
+
+/** The real socket names this pattern produces, for the sweep that removes the
+ * ones whose process is gone. */
+export const REAL_SOCKET = /^daemon\.(\d+)\.sock$/;
+
+export type Env = Record<string, string | undefined>;
+
+/** The config home this process belongs to.
+ *
+ * `CLAUDE_CONFIG_DIR` is what the harness itself reads, so a session and the
+ * instance it talks to agree on which one they mean without ccmsg naming it
+ * separately. Nothing searches for another one (M6). */
+export function resolveConfigHome(env: Env = process.env): string {
+  const named = env["CLAUDE_CONFIG_DIR"];
+  if (named !== undefined && named !== "" && isAbsolute(named)) return named;
+  return join(home(env), ".claude");
+}
+
+/** Resolve everything, given the environment.
+ *
+ * The three categories follow the XDG base directories, with the instance key
+ * as the directory under each: config is what a person edits, state is what
+ * survives a restart but costs only convenience if lost (the spec names logs
+ * and history there), and the socket / pid / lock are handles that live with
+ * the state so a temporary directory sweep cannot take the socket out from
+ * under a running instance. */
+export function resolvePaths(env: Env = process.env): InstancePaths {
+  const configHome = resolveConfigHome(env);
+  const key = instanceKey(configHome);
+  const configDir = resolveConfigDir(env);
+  const stateDir = appDir(env, "CCMSG_STATE_DIR", "XDG_STATE_HOME", [".local", "state"], key);
+  const socketDir = socketDirFor(stateDir, key);
+  return {
+    configHome,
+    key,
+    configFile: join(configDir, "config.json"),
+    stateDir,
+    socketDir,
+    socket: join(socketDir, SOCKET_NAME),
+    socketReal: join(socketDir, realSocketName(process.pid)),
+    pluginsDir: join(stateDir, "plugins"),
+    pidFile: join(stateDir, "daemon.pid"),
+    lockFile: join(stateDir, "daemon.lock"),
+    logFile: join(stateDir, "daemon.log"),
+    instanceIdFile: join(stateDir, "instance.id"),
+  };
+}
+
+/** Where the shared config file lives.
+ *
+ * No instance segment, unlike the state: config is what a person edits, and
+ * one file listing every config home is what lets them add an instance without
+ * already knowing the key ccmsg would derive for it. */
+export function resolveConfigDir(env: Env = process.env): string {
+  const direct = env["CCMSG_CONFIG_DIR"];
+  if (direct !== undefined && direct !== "") return direct;
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg !== undefined && isAbsolute(xdg) ? xdg : join(home(env), ".config");
+  return join(base, "ccmsg");
+}
+
+/** Where things that belong to no single instance keep their state — the
+ * supervisor's log above all. The instance segment is what a per-instance state
+ * directory adds to this, so this is that path without it. */
+export function resolveStateRoot(env: Env = process.env): string {
+  const direct = env["CCMSG_STATE_DIR"];
+  if (direct !== undefined && direct !== "") return direct;
+  const xdg = env["XDG_STATE_HOME"];
+  const base = xdg !== undefined && isAbsolute(xdg) ? xdg : join(home(env), ".local", "state");
+  return join(base, "ccmsg");
+}
+
+/** Where the supervisor answers the commands addressed to it.
+ *
+ * One socket for the host rather than one per instance, because the supervisor
+ * is one process for the host: the config homes it looks after are what a
+ * request names, not what it connects to. It sits with the state for the reason
+ * an instance's socket does — a temporary directory sweep must not take the
+ * address out from under a running process — and falls back to the same short
+ * per-uid directory when the state path would not fit in `sun_path`. */
+export function resolveSupervisorSocket(env: Env = process.env): string {
+  const beside = join(resolveStateRoot(env), SUPERVISOR_SOCKET);
+  if (Buffer.byteLength(beside) < MAX_SOCKET_PATH) return beside;
+  return join("/tmp", `ccmsg-${String(process.getuid?.() ?? 0)}`, SUPERVISOR_SOCKET);
+}
+
+export const SUPERVISOR_SOCKET = "supervise.sock";
+
+/** The shared config file, for a caller that has no instance to resolve. */
+export function resolveConfigFile(env: Env = process.env): string {
+  return join(resolveConfigDir(env), "config.json");
+}
+
+/** A name for one config home that is readable and cannot collide.
+ *
+ * The readable half is the config home's own last segment, which is what a
+ * person recognises; the digest is what keeps two homes of the same name under
+ * different parents from sharing a socket. */
+export function instanceKey(configHome: string): string {
+  const digest = createHash("sha256").update(configHome).digest("hex").slice(0, 8);
+  const name = basename(configHome).replace(/[^A-Za-z0-9._-]/g, "-") || "home";
+  return `${name}-${digest}`;
+}
+
+/** The home directory, from the environment the caller handed in, so resolving
+ * paths is a function of that environment and a test can resolve for a home
+ * that is not this process's. */
+function home(env: Env): string {
+  const named = env["HOME"];
+  return named !== undefined && isAbsolute(named) ? named : homedir();
+}
+
+/** The three-step fallback: the app's own variable, then XDG, then the spec's
+ * default. The app variable names the directory itself, so a test can put an
+ * instance somewhere disposable; the other two get the app and instance
+ * segments appended. A relative path in an XDG variable is invalid per the
+ * spec and is ignored. */
+function appDir(
+  env: Env,
+  appVar: string,
+  xdgVar: string,
+  fallback: readonly string[],
+  key: string,
+): string {
+  const direct = env[appVar];
+  if (direct !== undefined && direct !== "") return direct;
+  const xdg = env[xdgVar];
+  const base = xdg !== undefined && isAbsolute(xdg) ? xdg : join(home(env), ...fallback);
+  return join(base, "ccmsg", key);
+}
+
+/** Where the sockets go: beside the state they belong to, unless the longest
+ * name that directory would hold does not fit in `sun_path`.
+ *
+ * The length is judged on the widest real path rather than on the stable one,
+ * because the real path is what gets bound and it is the longer of the two.
+ * The fallback is a per-uid directory under `/tmp`, short by construction and
+ * reached only by a deeply nested state directory. */
+function socketDirFor(stateDir: string, key: string): string {
+  const widest = join(stateDir, realSocketName(9_999_999));
+  if (Buffer.byteLength(widest) < MAX_SOCKET_PATH) return stateDir;
+  return join("/tmp", `ccmsg-${process.getuid?.() ?? 0}`, key);
+}

package/src/instance/socket.ts

@@ -0,0 +1,62 @@
+import { mkdirSync, readdirSync, renameSync, symlinkSync, unlinkSync } from "node:fs";
+import { basename, join } from "node:path";
+import { alive } from "./lock.ts";
+import type { InstancePaths } from "./paths.ts";
+import { REAL_SOCKET } from "./paths.ts";
+
+/** Point the stable address at the socket this process bound.
+ *
+ * Through a temporary name and a rename, because that is the only way to
+ * replace a symlink without a moment where the address does not exist:
+ * `symlink` itself refuses an existing name, and unlinking first would leave a
+ * window in which a client finds nothing rather than finding the predecessor.
+ *
+ * Called after the listener is up, so the address never names a socket that is
+ * not yet accepting. */
+export function publishSocket(paths: InstancePaths): void {
+  const temporary = `${paths.socket}.${process.pid}.new`;
+  removeQuietly(temporary);
+  symlinkSync(basename(paths.socketReal), temporary);
+  renameSync(temporary, paths.socket);
+}
+
+/** Remove the real sockets of runs that are gone.
+ *
+ * A departing instance takes its own path with it, so what this finds is what
+ * a killed one left: the file names the pid that bound it, and the OS is asked
+ * whether that pid is still there — the same question the lock asks of the
+ * same kind of leftover.
+ *
+ * The stable address is never swept. It may already point at a successor, and
+ * one pointing at a socket that is gone is the "the unix socket refuses"
+ * a client reads as this instance having finished leaving (§8.5). */
+export function sweepOrphanSockets(paths: InstancePaths): void {
+  let names: string[];
+  try {
+    names = readdirSync(paths.socketDir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const match = REAL_SOCKET.exec(name);
+    if (match?.[1] === undefined) continue;
+    const pid = Number(match[1]);
+    if (pid === process.pid || alive(pid)) continue;
+    removeQuietly(join(paths.socketDir, name));
+  }
+}
+
+/** The socket directory, which is the state directory unless the address would
+ * not fit there. Its own mode, because a directory under `/tmp` is not private
+ * by construction the way one under the state directory is. */
+export function prepareSocketDir(paths: InstancePaths): void {
+  mkdirSync(paths.socketDir, { recursive: true, mode: 0o700 });
+}
+
+function removeQuietly(file: string): void {
+  try {
+    unlinkSync(file);
+  } catch {
+    // Not there, which is the state this wanted.
+  }
+}

package/src/kv/index.ts

@@ -0,0 +1,2 @@
+export * from "./merge.ts";
+export * from "./store.ts";

package/src/kv/merge.ts

@@ -0,0 +1,66 @@
+import { LAST_LIVE_RETENTION_MS, type Timestamp } from "@ccmsg/protocol";
+
+/** One key's state: the value it holds, or the record that it was removed.
+ *
+ * A removal is kept rather than dropped because two instances mirror this
+ * store between themselves: an absence says nothing about whether a key was
+ * never written or was deleted, so the deletion is a value of its own until it
+ * is old enough that no mirror can still be carrying the write it undid. */
+export interface Held {
+  /** Absent exactly when the entry is a removal, which is the contract's own
+   * rule for an entry (`KvEntry`). */
+  value?: unknown;
+  updated_at: Timestamp;
+  deleted?: true;
+}
+
+/** How long a removal is remembered.
+ *
+ * The same window `last_live` keeps a session that stopped being seen: both
+ * bound how long an instance that was away may be gone and still be told what
+ * happened while it was, and having them differ would state two answers to one
+ * question about the same mesh. */
+export const TOMBSTONE_RETENTION_MS = LAST_LIVE_RETENTION_MS;
+
+/** Whether a removal is old enough to forget. */
+export function expired(held: Held, now: Timestamp): boolean {
+  return held.deleted === true && now - held.updated_at > TOMBSTONE_RETENTION_MS;
+}
+
+/** Which of two states of one key stands.
+ *
+ * The later `updated_at` wins, which is the whole of what the contract
+ * promises about a key two instances disagree on (`KvReadArgs`). A removal is
+ * a write like any other and wins or loses by the same instant, which is what
+ * keeps a delete from being undone by an older write that arrives after it.
+ *
+ * Two instants that are equal settle only as far as the contract does. A
+ * removal beats a value, which both sides decide alike whichever of them is
+ * asking; two different values written at the same millisecond are left as
+ * each side holds them, because the only rules that would converge them —
+ * preferring the local one, or ordering the values themselves — are either not
+ * symmetric or not the contract's. The next write to the key settles it. */
+export function mergeHeld(local: Held | undefined, remote: Held | undefined): Held | undefined {
+  if (local === undefined) return remote;
+  if (remote === undefined) return local;
+  if (local.updated_at !== remote.updated_at) {
+    return local.updated_at > remote.updated_at ? local : remote;
+  }
+  return remote.deleted === true ? remote : local;
+}
+
+/** A namespace as it stands once a mirror of it has arrived. Neither side is
+ * changed; what both hold afterwards is this. */
+export function mergeNamespace(
+  local: ReadonlyMap<string, Held>,
+  remote: ReadonlyMap<string, Held>,
+  now: Timestamp = Date.now(),
+): Map<string, Held> {
+  const merged = new Map<string, Held>();
+  for (const key of new Set([...local.keys(), ...remote.keys()])) {
+    const held = mergeHeld(local.get(key), remote.get(key));
+    if (held === undefined || expired(held, now)) continue;
+    merged.set(key, held);
+  }
+  return merged;
+}

package/src/kv/store.ts

@@ -0,0 +1,195 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  KvDeleteArgs,
+  KvDeleteResult,
+  InstanceId,
+  KvEntry,
+  KvReadArgs,
+  KvReadResult,
+  KvWriteArgs,
+  KvWriteResult,
+  Timestamp,
+} from "@ccmsg/protocol";
+import { type HandlerInput, OpError, type Requester } from "../dispatch/index.ts";
+import { topicParam, type TopicValue, type UpstreamResource } from "../topics/index.ts";
+import { expired, type Held } from "./merge.ts";
+
+export const KV_DIR = "kv";
+
+/** The values clients keep here, and the topic that shows them changing.
+ *
+ * Written down, unlike almost everything else this instance holds (§3.6): a
+ * value here was typed by a person and exists nowhere else — the theme a
+ * browser is showing is a copy of it, not its source — so losing it on a
+ * restart loses what they set. It is not a derived value, which is what M4
+ * forbids persisting.
+ *
+ * One file per namespace, whole-file: a namespace holds a handful of small
+ * values, and the whole of it is what both a snapshot and a reload state. The
+ * write lands through a temporary and a rename, so a kill leaves either the
+ * previous namespace or the new one. */
+export class KvStore implements UpstreamResource {
+  readonly #namespaces = new Map<string, Map<string, Held>>();
+
+  constructor(
+    private readonly dir: string,
+    private readonly self: InstanceId,
+    private readonly publish: (topic: string, data: unknown) => void,
+  ) {}
+
+  read(args: KvReadArgs): KvReadResult {
+    const held = this.#load(args.ns).get(args.key);
+    // A removal that is still remembered is a key the namespace does not hold.
+    if (held === undefined || held.deleted === true) {
+      throw new OpError("not_found", `${args.ns} holds no ${args.key}`);
+    }
+    return { value: held.value, updated_at: held.updated_at };
+  }
+
+  /** Writes one value, unless what the key holds is newer.
+   *
+   * The instant decides, not the order of arrival: a caller states when the
+   * write it is reporting happened, and one that happened while this instance
+   * was unreachable must not displace what was written since. The answer is
+   * what the key carries now — equal to what the caller stated when its write
+   * stands, and later than it when an existing value did. */
+  write(args: KvWriteArgs, now: Timestamp = Date.now()): KvWriteResult {
+    const entries = this.#load(args.ns);
+    const updatedAt = args.updated_at ?? now;
+    const held = entries.get(args.key);
+    // Older than what the key holds, so it does not displace it. A write that
+    // arrived at the same instant does stand: two calls a millisecond apart
+    // are not a disagreement between instances, and the second is the newer.
+    if (held !== undefined && held.updated_at > updatedAt) {
+      return { updated_at: held.updated_at };
+    }
+    entries.set(args.key, { value: args.value, updated_at: updatedAt });
+    this.#persist(args.ns, entries);
+    this.publish(`kv:${args.ns}`, {
+      entries: [{ key: args.key, value: args.value, updated_at: updatedAt }],
+    });
+    return { updated_at: updatedAt };
+  }
+
+  /** A key that was not there is no error: the caller wanted the namespace
+   * without it, and it is. The removal is still announced, because a subscriber
+   * that has the entry has to be told it is gone. */
+  delete(args: KvDeleteArgs, now: Timestamp = Date.now()): KvDeleteResult {
+    const entries = this.#load(args.ns);
+    const before = entries.get(args.key);
+    // A removal older than what the key holds undoes nothing, which is the
+    // same rule a write is held to.
+    if (before !== undefined && before.updated_at > now) return {};
+    entries.set(args.key, { updated_at: now, deleted: true });
+    this.#persist(args.ns, entries);
+    // A removal is announced only when something was there to remove: a
+    // subscriber holding no entry has nothing to be told is gone.
+    if (before !== undefined && before.deleted !== true) {
+      this.publish(`kv:${args.ns}`, {
+        entries: [{ key: args.key, updated_at: now, deleted: true }],
+      });
+    }
+    return {};
+  }
+
+  /** Nothing to start or stop: the values are here whether anyone is watching
+   * or not, and the file they live in is read the first time the namespace is
+   * touched. */
+  start(): void {}
+  stop(): void {}
+
+  /** Every entry the namespace holds. A snapshot never carries a removal, since
+   * what is not there is simply absent from a whole list. */
+  snapshot(topic: string, _conn: Requester): readonly TopicValue[] {
+    const ns = topicParam(topic);
+    if (ns === undefined) return [];
+    const entries: KvEntry[] = [...this.#load(ns)]
+      .filter(([, held]) => held.deleted !== true)
+      .map(([key, held]) => ({ key, value: held.value, updated_at: held.updated_at }));
+    return [{ instance: this.self, data: { entries } }];
+  }
+
+  #load(ns: string, now: Timestamp = Date.now()): Map<string, Held> {
+    const known = this.#namespaces.get(ns);
+    if (known !== undefined) return forget(known, now);
+    const entries = new Map<string, Held>();
+    let text: string;
+    try {
+      text = readFileSync(this.#file(ns), "utf8");
+    } catch {
+      this.#namespaces.set(ns, entries);
+      return entries;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      // A file a kill damaged states nothing this instance can act on, and
+      // refusing every read of the namespace would be worse than starting it
+      // empty: the next write replaces the file.
+      parsed = undefined;
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      for (const [key, held] of Object.entries(parsed as Record<string, unknown>)) {
+        if (typeof held !== "object" || held === null) continue;
+        const fields = held as Record<string, unknown>;
+        const updatedAt = fields["updated_at"];
+        if (typeof updatedAt !== "number") continue;
+        entries.set(
+          key,
+          fields["deleted"] === true
+            ? { updated_at: updatedAt, deleted: true }
+            : { value: fields["value"], updated_at: updatedAt },
+        );
+      }
+    }
+    this.#namespaces.set(ns, entries);
+    return forget(entries, now);
+  }
+
+  #persist(ns: string, entries: Map<string, Held>): void {
+    mkdirSync(this.dir, { recursive: true });
+    const file = this.#file(ns);
+    const body: Record<string, Held> = {};
+    for (const [key, held] of entries) body[key] = held;
+    const temporary = `${file}.ccmsg-${process.pid}-${Date.now()}`;
+    writeFileSync(temporary, JSON.stringify(body));
+    try {
+      renameSync(temporary, file);
+    } catch (cause) {
+      unlinkSync(temporary);
+      throw cause;
+    }
+  }
+
+  /** The namespace's file. A namespace is an identifier, so its name is a file
+   * name that cannot reach out of this directory. */
+  #file(ns: string): string {
+    return join(this.dir, `${ns}.json`);
+  }
+}
+
+/** Drop the removals nothing can still be carrying an older write for.
+ *
+ * Done where the namespace is read rather than on a clock of its own: a timer
+ * would have this instance touching a store nobody is asking about, and a
+ * removal that outlives its window until the next read is one no read can see
+ * anyway. The file keeps it until the namespace is next written, which is the
+ * only moment the file is rewritten at all. */
+function forget(entries: Map<string, Held>, now: Timestamp): Map<string, Held> {
+  for (const [key, held] of entries) {
+    if (expired(held, now)) entries.delete(key);
+  }
+  return entries;
+}
+
+export function kvHandlers(store: KvStore) {
+  return {
+    kv_read: (input: HandlerInput): KvReadResult => store.read(input.args as unknown as KvReadArgs),
+    kv_write: (input: HandlerInput): KvWriteResult =>
+      store.write(input.args as unknown as KvWriteArgs),
+    kv_delete: (input: HandlerInput): KvDeleteResult =>
+      store.delete(input.args as unknown as KvDeleteArgs),
+  };
+}

package/src/launcher/index.ts

@@ -0,0 +1,4 @@
+export * from "./launcher.ts";
+export * from "./roots.ts";
+export * from "./spawn.ts";
+export * from "./tree.ts";