@ccmsg/cli 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/files/containment.ts

@@ -1,4 +1,3 @@
-import { realpathSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import type { FileKind, Role, Sid } from "@ccmsg/protocol";
@@ -28,7 +27,7 @@ export interface SessionRoots {
 
 /** Who states a session's allowlists. */
 export interface RootsSource {
-  roots(sid: Sid): SessionRoots | undefined;
+  roots(sid: Sid): Promise<SessionRoots | undefined>;
 }
 
 /** One path, decided.
@@ -71,7 +70,7 @@ export class Containment {
 
   /** A path named by kind, as an op's arguments give it. */
   async locate(args: PathArgs, viewer: Viewer = {}): Promise<Located> {
-    const roots = this.rootsFor(args.sid, viewer);
+    const roots = await this.rootsFor(args.sid, viewer);
     const named = await this.absolute(args, roots);
     const real = await canonical(named);
     return { ...(await this.admit(args.kind, real, roots)), named };
@@ -85,7 +84,7 @@ export class Containment {
   async identify(sid: Sid, path: string, viewer: Viewer = {}): Promise<Located | undefined> {
     let roots: SessionRoots;
     try {
-      roots = this.rootsFor(sid, viewer);
+      roots = await this.rootsFor(sid, viewer);
     } catch {
       return undefined;
     }
@@ -108,7 +107,7 @@ export class Containment {
    * rather than as forbidden — the path is reachable, and only writing there
    * is not. */
   async inbox(sid: Sid, path: string, viewer: Viewer = {}): Promise<Located> {
-    const roots = this.rootsFor(sid, viewer);
+    const roots = await this.rootsFor(sid, viewer);
     const cwd = roots.cwd;
     if (cwd === undefined || !isAbsolute(cwd)) {
       throw new OpError("path_forbidden", `${sid} states no working directory to write into`);
@@ -128,14 +127,14 @@ export class Containment {
     return this.locate({ sid: args.sid, kind: args.kind, path: args.path ?? "" }, viewer);
   }
 
-  private rootsFor(sid: Sid, viewer: Viewer): SessionRoots {
+  private async rootsFor(sid: Sid, viewer: Viewer): Promise<SessionRoots> {
     if (!sees(sid, viewer)) {
       throw new OpError(
         "path_forbidden",
         `the files of ${sid} are outside this connection's range`,
       );
     }
-    const roots = this.source.roots(sid);
+    const roots = await this.source.roots(sid);
     if (roots === undefined) {
       throw new OpError("path_forbidden", `nothing is known about the files of ${sid}`);
     }
@@ -256,22 +255,6 @@ export async function canonical(path: string): Promise<string> {
   }
 }
 
-/** The synchronous form required while `session.status` states its value synchronously (DESIGN §6); an asynchronous topic value uses `canonical` as the single path. */
-export function canonicalSync(path: string): string {
-  const absolute = resolve(path);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    const parent = dirname(absolute);
-    if (parent === absolute) return absolute;
-    try {
-      return join(realpathSync(parent), basename(absolute));
-    } catch {
-      return absolute;
-    }
-  }
-}
-
 /** Whether a resolved path is the root or below it. Shared with the launcher,
  * whose roots come from config rather than from a session: what "inside" means
  * is the same question, and two spellings of it could come apart. */

package/src/instance/instance.ts

@@ -51,7 +51,7 @@ import {
   SessionStatus,
 } from "../sessions/index.ts";
 import { topicHandlers, Topics } from "../topics/index.ts";
-import { TranscriptFiles, Transcripts } from "../transcript/index.ts";
+import { FoldCache, TranscriptFiles, Transcripts } from "../transcript/index.ts";
 import {
   type AuthorizedUpgrade,
   ConnRegistry,
@@ -502,6 +502,9 @@ export class Instance {
     this.#transcripts = new Transcripts({
       self: this.self,
       pathOf: (sid) => transcriptFiles.path(sid),
+      // What a past reading of each transcript reached, so a transcript is
+      // read from its beginning once rather than once per start.
+      cache: new FoldCache(join(paths.cacheDir, "transcripts")),
       publish: (topic, data) => {
         this.#topics.publish(topic, data);
       },
@@ -536,7 +539,7 @@ export class Instance {
       },
       ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }),
       onChanged: () => {
-        this.#status.refresh();
+        void this.#status.refresh();
         // A session that is live again is one route (a) can be tried against,
         // which is what the inbox is waiting for (DESIGN §6.7).
         void this.#delivery.retry();
@@ -559,6 +562,7 @@ export class Instance {
       release: (sid) => {
         this.#transcripts.release(sid);
       },
+      ready: (sid) => this.#transcripts.ready(sid),
       publish: (topic, data) => {
         this.#topics.publish(topic, data);
       },
@@ -664,10 +668,11 @@ export class Instance {
     // greeting says where the session works, and the fold says which folders
     // its editor names and which files outside them its transcript named.
     const files = new Containment({
-      roots: (sid): SessionRoots | undefined => {
+      roots: async (sid): Promise<SessionRoots | undefined> => {
         const where = this.#sessions.where(sid);
         if (where.root === undefined && where.cwd === undefined) return undefined;
-        const status = sessionStatusOf(sid, this.#transcripts.facts(sid), where);
+        await this.#transcripts.ready(sid);
+        const status = await sessionStatusOf(sid, this.#transcripts.facts(sid), where);
         return {
           ...where,
           workspace_folders: status.workspace_folders.map((folder) => folder.path),

package/src/instance/paths.ts

@@ -41,6 +41,11 @@ export interface InstancePaths {
   /** Where a file is put before it is overwritten by the checked copy. */
   readonly rejectedDir: string;
   readonly stateDir: string;
+  /** Where what was derived from a file is kept so it need not be derived
+   * again. Everything here can be rebuilt from the file it came from, so the
+   * directory may be emptied at any moment and the only cost is the work of
+   * deriving it once more. */
+  readonly cacheDir: 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;
@@ -148,6 +153,7 @@ export function resolvePathsFor(configHome: string, env: Env = process.env): Ins
     satisfiedFile: join(stateRoot, STATE_CONFIG_DIR, SATISFIED_FILE),
     rejectedDir: join(stateRoot, REJECTED_DIR),
     stateDir,
+    cacheDir: appDir(env, "CCMSG_CACHE_DIR", "XDG_CACHE_HOME", [".cache"], key),
     socketDir,
     socket: join(socketDir, SOCKET_NAME),
     socketReal: join(socketDir, realSocketName(process.pid)),

package/src/sessions/fork.ts

@@ -41,7 +41,7 @@ export async function forkOrigin(
   sid: Sid,
   files: TranscriptFiles,
 ): Promise<ForkOrigin | undefined> {
-  const file = files.session(sid);
+  const file = await files.session(sid);
   const ours = await recordIds(file);
   const head = ours?.[0];
   if (ours === undefined || head === undefined) return undefined;

package/src/sessions/harness.ts

@@ -171,8 +171,9 @@ export class HarnessSessions implements OwnSessions {
    * here too: a pid from a poll that has not run is a number belonging to
    * nobody.
    *
-   * Read in place because the directory is a handful of small files of this
-   * uid's own config home (M6) — a syscall or two per session, not a wait. */
+   * Read in place because the answer may not depend on anybody waiting: what
+   * this states is that a session exists, and a reading that could be waited
+   * for would make it something the callers above cannot ask (DESIGN §4.2). */
   scan(): ReadonlyMap<Sid, AgentInfo> {
     const rows = new Map<Sid, AgentInfo>();
     const names = this.#watch.names().filter((name) => STATE_FILE.test(name));
@@ -248,9 +249,8 @@ class DirectoryWatch {
     this.#timer = undefined;
   }
 
-  /** What is in the directory now. Read in place because it is a handful of
-   * small entries of this uid's own config home (M6) — a syscall or two, not a
-   * wait. */
+  /** What is in the directory now, read in place for the reason `scan()` is:
+   * it is the same answer, and the callers above it cannot wait for one. */
   names(): string[] {
     try {
       return readdirSync(this.dir);

package/src/sessions/status.ts

@@ -5,7 +5,7 @@ import type {
   SessionStatusSnapshot,
   Sid,
 } from "@ccmsg/protocol";
-import { canonicalSync, within } from "../files/containment.ts";
+import { canonical, within } from "../files/containment.ts";
 import type { TopicValue, UpstreamResource } from "../topics/index.ts";
 import { topicParam } from "../topics/index.ts";
 import type { TranscriptFacts } from "../transcript/index.ts";
@@ -35,15 +35,26 @@ export function stoppedOn(facts: TranscriptFacts): SessionApiError | undefined {
  * root is known. A session that stated no root contributes none of them rather
  * than all of them: the list is the allowlist an `external` read is checked
  * against, so not knowing where the session works has to admit nothing. */
-export function sessionStatusOf(
+export async function sessionStatusOf(
   sid: Sid,
   facts: TranscriptFacts,
   where: SessionWhere = {},
-): SessionStatusSnapshot & {
-  sid: Sid;
-} {
+): Promise<
+  SessionStatusSnapshot & {
+    sid: Sid;
+  }
+> {
   const stopped = stoppedOn(facts);
-  const root = where.root === undefined ? undefined : canonicalSync(where.root);
+  const root = where.root === undefined ? undefined : await canonical(where.root);
+  const named =
+    root === undefined
+      ? []
+      : await Promise.all(
+          facts.named_files.map(async (file) => ({
+            file,
+            real: await canonical(file.path),
+          })),
+        );
   return {
     sid,
     todos: [...facts.todos],
@@ -54,8 +65,8 @@ export function sessionStatusOf(
     external_files:
       root === undefined
         ? []
-        : facts.named_files.filter((file) => !within(canonicalSync(file.path), root)),
-    workspace_folders: workspaceFolders(where.cwd),
+        : named.filter((each) => !within(each.real, root)).map((each) => each.file),
+    workspace_folders: await workspaceFolders(where.cwd),
     ...(stopped === undefined ? {} : { api_error: stopped }),
   };
 }
@@ -81,6 +92,10 @@ export interface SessionStatusDeps {
   /** The tail behind a session's fold, asked for and let go by name. */
   readonly hold: (sid: Sid) => void;
   readonly release: (sid: Sid) => void;
+  /** When the fold of a held session has read the whole transcript. What this
+   * owner states rests on the fold, so it waits on this before stating it
+   * (CT-Q8). */
+  readonly ready: (sid: Sid) => Promise<void>;
   /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
 }
@@ -105,6 +120,15 @@ export class SessionStatus implements UpstreamResource {
    * convergence happens once rather than in the middle of itself. */
   #converging = false;
   #pending = false;
+  /** Which pass is the one entitled to state a value.
+   *
+   * Stating one waits on a reading, and two readings started in either order
+   * can finish in either order — so the later pass read the later facts, and
+   * the earlier one must not publish behind it. Every pass takes a number and
+   * gives up the moment a later one has taken a higher one: what a subscriber
+   * is told is what the most recent reading said, and never what an older one
+   * caught up to saying (DR-0015 §2.5). */
+  #stating = 0;
 
   constructor(private readonly deps: SessionStatusDeps) {}
 
@@ -112,16 +136,16 @@ export class SessionStatus implements UpstreamResource {
 
   start(topic: string): void {
     this.#wanted.add(topic);
-    this.refresh();
+    void this.refresh();
   }
 
   stop(topic: string): void {
     this.#wanted.delete(topic);
-    this.refresh();
+    void this.refresh();
   }
 
-  snapshot(topic: string): readonly TopicValue[] {
-    const data = this.value(topic);
+  async snapshot(topic: string): Promise<readonly TopicValue[]> {
+    const data = await this.value(topic);
     return data === undefined ? [] : [{ instance: this.deps.self, data }];
   }
 
@@ -129,7 +153,7 @@ export class SessionStatus implements UpstreamResource {
    * says, and which sessions exist, are the two things that move either.
    *
    * Called by whoever changes one of them, rather than on a timer (M3). */
-  refresh(): void {
+  async refresh(): Promise<void> {
     if (this.#converging) {
       this.#pending = true;
       return;
@@ -143,8 +167,15 @@ export class SessionStatus implements UpstreamResource {
     } finally {
       this.#converging = false;
     }
-    for (const topic of this.#wanted) {
-      const data = this.value(topic);
+    // The topics as they stand now: stating one waits on a reading, and a
+    // subscription arriving during that wait must not be iterated into.
+    const stating = [...this.#wanted];
+    this.#stating += 1;
+    const mine = this.#stating;
+    for (const topic of stating) {
+      const data = await this.value(topic);
+      // A later pass has read later facts; this one has nothing to add.
+      if (mine !== this.#stating) return;
       if (data !== undefined) this.deps.publish(topic, data);
     }
   }
@@ -169,12 +200,17 @@ export class SessionStatus implements UpstreamResource {
 
   /** What a topic of this owner currently says, for a snapshot and for a
    * change alike — built here and nowhere else, so the two cannot drift. */
-  private value(topic: string): unknown {
-    if (topic === "session.errors") return this.errors();
+  private async value(topic: string): Promise<unknown> {
+    if (topic === "session.errors") {
+      // Every session's fold, so the list is of the transcripts as they read
+      // rather than of the ones that happen to have been read by now.
+      await Promise.all(this.deps.sessions().map((sid) => this.deps.ready(sid)));
+      return this.errors();
+    }
     const sid = topicParam(topic);
-    return sid === undefined
-      ? undefined
-      : sessionStatusOf(sid, this.deps.facts(sid), this.deps.where(sid));
+    if (sid === undefined) return undefined;
+    await this.deps.ready(sid);
+    return await sessionStatusOf(sid, this.deps.facts(sid), this.deps.where(sid));
   }
 
   /** Bring the held tails in line with what the subscriptions need. */

package/src/sessions/workspace.ts

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 import type { WorkspaceFolder } from "@ccmsg/protocol";
@@ -14,15 +14,15 @@ import type { WorkspaceFolder } from "@ccmsg/protocol";
  *
  * A session that has no workspace file names no folders, which is what an empty
  * list means to the contract and admits no `workspace` path at all. */
-export function workspaceFolders(cwd: string | undefined): WorkspaceFolder[] {
+export async function workspaceFolders(cwd: string | undefined): Promise<WorkspaceFolder[]> {
   if (cwd === undefined || !isAbsolute(cwd)) return [];
   const folders: WorkspaceFolder[] = [];
   const seen = new Set<string>();
-  for (const file of workspaceFiles(cwd)) {
-    for (const spec of specs(file)) {
+  for (const file of await workspaceFiles(cwd)) {
+    for (const spec of await specs(file)) {
       // Relative to the workspace file, which is how an editor reads them.
-      const real = directory(resolve(dirname(file), spec.path));
-      if (real === undefined || overbroad(real) || seen.has(real)) continue;
+      const real = await directory(resolve(dirname(file), spec.path));
+      if (real === undefined || (await overbroad(real)) || seen.has(real)) continue;
       seen.add(real);
       folders.push({ name: spec.name ?? basename(real), path: real });
     }
@@ -32,10 +32,10 @@ export function workspaceFolders(cwd: string | undefined): WorkspaceFolder[] {
 
 /** The workspace files directly beside the session's working directory, in a
  * fixed order so the same directory always states its folders the same way. */
-function workspaceFiles(cwd: string): string[] {
+async function workspaceFiles(cwd: string): Promise<string[]> {
   let entries: string[];
   try {
-    entries = readdirSync(cwd);
+    entries = await readdir(cwd);
   } catch {
     return [];
   }
@@ -47,10 +47,10 @@ function workspaceFiles(cwd: string): string[] {
 
 /** What one workspace file declares: the `folders` array, and of each entry the
  * path it names and the name it may give that path. */
-function specs(file: string): { path: string; name?: string }[] {
+async function specs(file: string): Promise<{ path: string; name?: string }[]> {
   let parsed: unknown;
   try {
-    parsed = JSON.parse(uncommented(readFileSync(file, "utf8")));
+    parsed = JSON.parse(uncommented(await readFile(file, "utf8")));
   } catch {
     // Written by hand and half-saved, or not a workspace file after all.
     return [];
@@ -113,10 +113,10 @@ function uncommented(text: string): string {
 
 /** What the filesystem calls a folder that is one. A path naming a file, or
  * nothing at all, names no folder and is dropped. */
-function directory(path: string): string | undefined {
+async function directory(path: string): Promise<string | undefined> {
   try {
-    const real = realpathSync(path);
-    return statSync(real).isDirectory() ? real : undefined;
+    const real = await realpath(path);
+    return (await stat(real)).isDirectory() ? real : undefined;
   } catch {
     return undefined;
   }
@@ -127,9 +127,9 @@ function directory(path: string): string | undefined {
  * The root and the home directory and anything above them are refused: a
  * workspace file naming one of those turns the `workspace` surface into the
  * whole filesystem, and the folders are an allowlist rather than a hint. */
-function overbroad(real: string): boolean {
+async function overbroad(real: string): Promise<boolean> {
   if (real === sep || dirname(real) === real) return true;
-  const home = directory(homedir());
+  const home = await directory(homedir());
   return home !== undefined && (real === home || home.startsWith(withSep(real)));
 }
 

package/src/topics/handlers.ts

@@ -7,9 +7,9 @@ import type { SubscribeOutcome, Topics } from "./topics.ts";
  * it to `Topics`, and turns the outcome into the contract's own answer. */
 export function topicHandlers(topics: Topics) {
   return {
-    "topic.subscribe": (input: HandlerInput): TopicSubscribeResult => {
+    "topic.subscribe": async (input: HandlerInput): Promise<TopicSubscribeResult> => {
       const topic = topicOf(input);
-      answer(topics.subscribe(input.conn, topic), topic);
+      answer(await topics.subscribe(input.conn, topic), topic);
       return { topic };
     },
     "topic.unsubscribe": (input: HandlerInput): TopicSubscribeResult => {

package/src/transcript/cache.ts

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { mkdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ClassificationState, Item } from "./items/index.ts";
+import type { FoldState } from "./fold.ts";
+
+/** Which shape of folded state this build can read back.
+ *
+ * A cache entry is the answer a past run derived, taken on trust: nothing
+ * re-reads the bytes it was derived from. So it may only be read back by a
+ * build that would have derived the same answer from them, and the version is
+ * how that is asserted — raise it whenever what the fold keeps or how it reads
+ * a record changes, and every entry written before says nothing to this build.
+ *
+ * `test/transcript.test.ts` holds the digest of the sources this number stands
+ * for and fails when they move without it, so the assertion is checked rather
+ * than remembered. */
+export const FOLD_CACHE_VERSION = 2;
+
+/** What one session's fold had reached, as it is written down.
+ *
+ * The offset is what makes the rest of it usable: it says which bytes the
+ * state accounts for, so the next run reads from there instead of from the
+ * beginning. The file's identity is beside it because the offset counts bytes
+ * of one file — a transcript replaced by another of the same name has bytes
+ * this state describes none of. */
+export interface FoldCacheEntry {
+  readonly version: number;
+  readonly path: string;
+  readonly dev: number;
+  readonly ino: number;
+  /** Just past the last record the state accounts for. */
+  readonly offset: number;
+  readonly fold: FoldState;
+  /** What the reading that produced the items would carry into the next record:
+   * the turn it had reached, whose file it decided this is, and the calls still
+   * waiting for an answer. Without it a resumed run would answer a record
+   * differently from the run that read everything before it — counting turns
+   * from zero again, and calling a result whose call is known here the reserved
+   * name for a call nobody saw. */
+  readonly reading: ClassificationState;
+  /** The end of the reading, which is what a subscription opens on. Kept with
+   * the fold because both are derived from the same pass, and a resumed run
+   * that held only the fold would open the items topic on an empty list while
+   * claiming to know the session. */
+  readonly items: readonly Item[];
+}
+
+/** Where folded transcripts are kept between runs.
+ *
+ * Everything here can be derived again from the transcript it came from, so a
+ * miss, a discarded entry and an emptied directory are all the same thing: the
+ * file is read from its beginning. Nothing asks whether a write succeeded for
+ * that reason — a cache that could not be written costs the next run one read.
+ *
+ * Writes are chained rather than overlapped, so two saves of the same session
+ * cannot race over the temporary file they rename from. */
+export class FoldCache {
+  #writing: Promise<void> = Promise.resolve();
+
+  constructor(private readonly dir: string) {}
+
+  /** What was folded out of this file, or nothing when what is on disk does not
+   * describe the file as it stands. */
+  async read(path: string): Promise<FoldCacheEntry | undefined> {
+    let entry: FoldCacheEntry;
+    try {
+      entry = JSON.parse(await Bun.file(this.#fileFor(path)).text()) as FoldCacheEntry;
+    } catch {
+      return undefined;
+    }
+    // The shape is checked and not assumed. An entry whose version matches but
+    // whose fields are not what this build reads back would otherwise be taken
+    // apart by whoever reads it, and a reading that throws leaves the session
+    // unopenable until the instance restarts — where a file that says nothing
+    // this build can use costs one reading (DR-0015 §2.5: what an await brings
+    // back is an input, not a promise kept).
+    if (!describes(entry, path)) return undefined;
+    let known: Awaited<ReturnType<typeof stat>>;
+    try {
+      known = await stat(path);
+    } catch {
+      return undefined;
+    }
+    // A different file under the same name, or the same file grown shorter than
+    // the bytes the state accounts for: either way the state describes bytes
+    // that are not there, and the file is read from its beginning.
+    if (known.dev !== entry.dev || known.ino !== entry.ino) return undefined;
+    if (known.size < entry.offset) return undefined;
+    return entry;
+  }
+
+  /** Keep what has been folded so far. The file's identity is read here rather
+   * than taken from the caller, so what is written describes the file the
+   * offset was actually counted in. */
+  save(
+    path: string,
+    offset: number,
+    fold: FoldState,
+    reading: ClassificationState,
+    items: readonly Item[],
+  ): Promise<void> {
+    // The items are taken now rather than when the write runs: the offset and
+    // the fold describe this moment, and a list still being appended to would
+    // put records past the offset into an entry that claims to end at it.
+    const held = [...items];
+    this.#writing = this.#writing.then(() => this.#write(path, offset, fold, reading, held));
+    return this.#writing;
+  }
+
+  /** Forget what was folded out of this file, for a transcript that turned out
+   * to be another one. */
+  drop(path: string): Promise<void> {
+    this.#writing = this.#writing.then(async () => {
+      await unlink(this.#fileFor(path)).catch(() => undefined);
+    });
+    return this.#writing;
+  }
+
+  async #write(
+    path: string,
+    offset: number,
+    fold: FoldState,
+    reading: ClassificationState,
+    items: readonly Item[],
+  ): Promise<void> {
+    let known: Awaited<ReturnType<typeof stat>>;
+    try {
+      known = await stat(path);
+    } catch {
+      return;
+    }
+    const entry: FoldCacheEntry = {
+      version: FOLD_CACHE_VERSION,
+      path,
+      dev: known.dev,
+      ino: known.ino,
+      offset,
+      fold,
+      reading,
+      items: [...items],
+    };
+    const file = this.#fileFor(path);
+    const temporary = `${file}.${process.pid}.tmp`;
+    try {
+      await mkdir(this.dir, { recursive: true });
+      await writeFile(temporary, JSON.stringify(entry));
+      await rename(temporary, file);
+    } catch {
+      await unlink(temporary).catch(() => undefined);
+    }
+  }
+
+  /** One file per transcript, named by a digest of its path: the path is what
+   * identifies the transcript, and a digest of it is a name every filesystem
+   * takes however the path was spelled. */
+  #fileFor(path: string): string {
+    return join(this.dir, `${createHash("sha256").update(path).digest("hex").slice(0, 32)}.json`);
+  }
+}
+
+/** Whether what was read back is an entry this build can take up.
+ *
+ * Everything the fold and the reading are restored from is checked, because
+ * restoring walks it: a field of the wrong shape is a file that says nothing
+ * this build can use, which is the same as no file at all. What is not checked
+ * is what nothing walks — the contents of an item, of a call's arguments, of a
+ * todo — since those are carried whole and stated as they were written. */
+function describes(entry: unknown, path: string): entry is FoldCacheEntry {
+  if (!isObject(entry)) return false;
+  if (entry["version"] !== FOLD_CACHE_VERSION || entry["path"] !== path) return false;
+  if (!counted(entry["offset"]) || !counted(entry["dev"]) || !counted(entry["ino"])) return false;
+  return states(entry["fold"]) && reads(entry["reading"]) && Array.isArray(entry["items"]);
+}
+
+function states(fold: unknown): boolean {
+  if (!isObject(fold)) return false;
+  for (const key of ["files", "todos", "teammates", "background", "workflows", "agents", "calls"]) {
+    const held = fold[key];
+    if (!Array.isArray(held)) return false;
+    for (const pair of held) {
+      if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string") return false;
+    }
+  }
+  return true;
+}
+
+function reads(reading: unknown): boolean {
+  if (!isObject(reading)) return false;
+  if (!counted(reading["turn"]) || typeof reading["subject"] !== "string") return false;
+  if (!Array.isArray(reading["calls"])) return false;
+  for (const pair of reading["calls"]) {
+    if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string") return false;
+    const call: unknown = pair[1];
+    if (!isObject(call) || typeof call["tool"] !== "string" || typeof call["name"] !== "string") {
+      return false;
+    }
+  }
+  return true;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function counted(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}