@ccmsg/cli 0.13.0 → 0.14.1

package/src/sessions/items.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import type {
   DumpPreset,
   TranscriptItemsReadArgs,
@@ -8,15 +8,14 @@ import { OpError } from "../dispatch/index.ts";
 import type { TranscriptFiles } from "../transcript/index.ts";
 import {
   bounded,
-  classify,
   type Item,
   ledger,
-  located,
   select,
   selection,
   within,
 } from "../transcript/items/index.ts";
 import { READ_LIMIT } from "../transcript/read.ts";
+import { classified } from "../transcript/scan.ts";
 
 /** How many items one read may carry.
  *
@@ -52,23 +51,26 @@ export interface ItemsReadDeps {
  * is. That is what makes a link answerable: a result inside the range whose
  * call fell before it still names the call, and the caller can ask for the
  * call by the id it was given. */
-export function itemsRead(
+export async function itemsRead(
   args: TranscriptItemsReadArgs,
   deps: ItemsReadDeps,
-): TranscriptItemsReadResult {
+): Promise<TranscriptItemsReadResult> {
   bounded(args);
-  const file = deps.files.locate(
+  const file = await deps.files.locate(
     args.sid,
     args.agent_id === undefined ? {} : { agent_id: args.agent_id },
   );
   let text: string;
   try {
-    text = readFileSync(file, "utf8");
+    text = await readFile(file, "utf8");
   } catch {
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
   const keep = selection(args.types === undefined ? {} : { types: args.types }, deps.presets);
-  const { items } = select(within(classify(located(text), deps.files.subjectOf(file)), args), keep);
+  const { items } = select(
+    within(await classified(text, await deps.files.subjectOf(file)), args),
+    keep,
+  );
   const page = paged(items, args.limit, backwards(args));
   return {
     items: page.items,

package/src/sessions/last-live.ts

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import {
   LAST_LIVE_RETENTION_MS,
@@ -53,6 +54,9 @@ const VERSION = 1;
 export class LastLiveStore {
   #entries = new Map<Sid, StoredEntry>();
 
+  /** The writes already asked for, as one chain. */
+  #written: Promise<void> = Promise.resolve();
+
   /** `id` is this instance's own: every entry this store holds is by
    * definition an observation *this* instance made, so `instance` is forced
    * to it on both ends (load and record) rather than trusted from whatever
@@ -114,6 +118,12 @@ export class LastLiveStore {
     return true;
   }
 
+  /** Settle once every write asked for so far has landed. What a stop waits on,
+   * and what a reader of the file has to wait for to see the last change. */
+  async flush(): Promise<void> {
+    await this.#written;
+  }
+
   #prune(now: Timestamp): boolean {
     let dropped = false;
     for (const [sid, entry] of this.#entries) {
@@ -125,13 +135,26 @@ export class LastLiveStore {
   }
 
   /** Written whole through a temporary file, so a daemon killed mid-write
-   * leaves the previous list rather than half of this one. */
+   * leaves the previous list rather than half of this one.
+   *
+   * A session appearing or going is an ordinary event of a running instance, so
+   * the write does not hold it still (DR-0015). The body is taken here, before
+   * anything is awaited, and each write is chained onto the one before it: what
+   * lands last is what the list said last, and two of them cannot be sharing
+   * one temporary file. */
   #save(): void {
     const document: Document = { version: VERSION, sessions: [...this.#entries.values()] };
     const temporary = `${this.file}.${process.pid}.tmp`;
-    mkdirSync(dirname(this.file), { recursive: true });
-    writeFileSync(temporary, `${JSON.stringify(document)}\n`);
-    renameSync(temporary, this.file);
+    this.#written = this.#written.then(async () => {
+      try {
+        await mkdir(dirname(this.file), { recursive: true });
+        await writeFile(temporary, `${JSON.stringify(document)}\n`);
+        await rename(temporary, this.file);
+      } catch {
+        // A list that could not be written costs the Paused and Disappeared
+        // rows of the next run, and nothing of this one.
+      }
+    });
   }
 }
 

package/src/sessions/registry.ts

@@ -1,4 +1,5 @@
-import { realpathSync, statSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import {
   type AgentInfo,
@@ -243,6 +244,13 @@ export class Sessions implements UpstreamResource {
     this.#reclaim(this.#live);
   }
 
+  /** Settle the list of lost sessions on disk. The writes happen as sessions
+   * come and go (DR-0015); this is for whoever has to see the file as it stands
+   * rather than as it was a moment ago — a stop, or a reader of the file. */
+  async flush(): Promise<void> {
+    await this.#lastLive.flush();
+  }
+
   /** Drop the `last_live` entry of every session that is live, which is what
    * keeps one session off both lists.
    *
@@ -258,10 +266,10 @@ export class Sessions implements UpstreamResource {
    * can speak about, and where everything this instance knows about where that
    * session lives comes from. The greeting names its sid because the op it
    * arrived under is the one whose schema asks for one. */
-  helloSession = (input: HandlerInput): HelloResult => {
+  helloSession = async (input: HandlerInput): Promise<HelloResult> => {
     const args = input.args as unknown as HelloSessionArgs;
     this.#greetable(input, args.protocol_version);
-    this.register(args.sid, args);
+    await this.register(args.sid, args);
     input.conn.onClose(() => this.release(args.sid));
     return this.#greeted(input);
   };
@@ -609,15 +617,15 @@ export class Sessions implements UpstreamResource {
    * silence for a retraction would let each of them erase what the last one
    * knew, and the session would be described by whichever process spoke most
    * recently rather than by everything it has said. */
-  private register(sid: Sid, args: HelloSessionArgs): void {
-    const now = Date.now();
+  private async register(sid: Sid, args: HelloSessionArgs): Promise<void> {
+    const stated = await metaOf(this.deps, args, (refused) => {
+      this.deps.log?.("transcript_path not taken", { sid, path: args.transcript_path, refused });
+    });
+    // Read after the path has been settled, so that what this writes is built
+    // on the session as it stands now rather than as it stood before.
     const held = this.#connected.get(sid);
-    const meta = {
-      ...this.#stated.get(sid),
-      ...metaOf(this.deps, args, (refused) => {
-        this.deps.log?.("transcript_path not taken", { sid, path: args.transcript_path, refused });
-      }),
-    };
+    const now = Date.now();
+    const meta = { ...this.#stated.get(sid), ...stated };
     this.#connected.set(sid, {
       sid,
       connected_at: held?.connected_at ?? now,
@@ -841,17 +849,17 @@ export class Sessions implements UpstreamResource {
  * simply does not act on a description it cannot stand behind. Why a path was
  * not taken is told to `refused`, which is the operator's answer to a field
  * that is simply absent from what `peers` says. */
-function metaOf(
+async function metaOf(
   deps: Pick<SessionsDeps, "configHome" | "harness">,
   args: HelloSessionArgs,
   refused: (reason: string) => void,
-): SessionMeta {
+): Promise<SessionMeta> {
   const meta: Record<string, string> = {};
   for (const field of META_FIELDS) {
     const value = args[field];
     if (value === undefined) continue;
     if (field === "transcript_path") {
-      const taken = ownTranscript(value, deps);
+      const taken = await ownTranscript(value, deps);
       if (typeof taken === "string") meta[field] = taken;
       else refused(taken.refused);
       continue;
@@ -884,27 +892,36 @@ function metaOf(
  * comparison is between two paths resolved by one rule. The config home is not
  * treated that way — an instance answers for a home it is running out of, and
  * one that is not there names no tree to be inside of. */
-function ownTranscript(
+async function ownTranscript(
   named: string,
   deps: Pick<SessionsDeps, "configHome" | "harness">,
-): string | Refused {
+): Promise<string | Refused> {
   if (!isAbsolute(named)) return { refused: "not an absolute path" };
   let tree: string | undefined;
   try {
-    const home = realpathSync(deps.configHome);
-    tree = resolveAsFarAsItGoes(join(home, HARNESS[deps.harness].transcripts));
+    const home = await realpath(deps.configHome);
+    tree = await resolveAsFarAsItGoes(join(home, HARNESS[deps.harness].transcripts));
   } catch {
     return { refused: "the config home is not there" };
   }
-  const settled = resolveAsFarAsItGoes(named);
+  const settled = await resolveAsFarAsItGoes(named);
   if (tree === undefined || settled === undefined || !within(settled, tree)) {
     return { refused: "outside this config home's transcript tree" };
   }
-  const stat = statSync(settled, { throwIfNoEntry: false });
-  if (stat !== undefined && !stat.isFile()) return { refused: "not a file" };
+  const known = await stated(settled);
+  if (known !== undefined && !known.isFile()) return { refused: "not a file" };
   return settled;
 }
 
+/** What is at a path, or nothing where there is nothing at it. */
+async function stated(path: string): Promise<Stats | undefined> {
+  try {
+    return await stat(path);
+  } catch {
+    return undefined;
+  }
+}
+
 /** Why a stated path was not taken, in the words the log states it in. */
 interface Refused {
   readonly refused: string;
@@ -917,12 +934,12 @@ interface Refused {
  * kept as it was spelled. The result is compared against the tree as a whole,
  * which is what makes a `..` among the unwritten segments land wherever it
  * actually points rather than pass for being spelled inside. */
-function resolveAsFarAsItGoes(path: string): string | undefined {
+async function resolveAsFarAsItGoes(path: string): Promise<string | undefined> {
   const unwritten: string[] = [];
   let at = path;
   for (;;) {
     try {
-      return join(realpathSync(at), ...unwritten);
+      return join(await realpath(at), ...unwritten);
     } catch {
       const parent = dirname(at);
       // The root itself always resolves, so this is a path that named

package/src/sessions/search.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { parse, sep } from "node:path";
 import type {
   InstanceId,
@@ -9,6 +9,7 @@ import type {
 } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
 import { readRecord, type TranscriptFile, type TranscriptFiles } from "../transcript/index.ts";
+import { breathe, due } from "../transcript/scan.ts";
 
 /** What one search may read, and what it may answer with.
  *
@@ -57,7 +58,10 @@ export interface SearchDeps {
  * directory listing and a `stat` already say — the session id, the working
  * directory as the project directory spells it, when the file was last touched
  * — and only what survives that is read. */
-export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearchResult {
+export async function search(
+  args: SessionSearchArgs,
+  deps: SearchDeps,
+): Promise<SessionSearchResult> {
   if ((args.config_dirs ?? [deps.configHome]).every((dir) => dir !== deps.configHome)) {
     // Every config home the caller named is one this instance does not know,
     // which the contract says to ignore — leaving nothing to search.
@@ -72,7 +76,7 @@ export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearch
   const hits: SessionSearchHit[] = [];
   let budget = SCAN_BUDGET_BYTES;
   let truncated = false;
-  for (const candidate of deps.files.all()) {
+  for (const candidate of await deps.files.all()) {
     if (sid !== undefined && !candidate.sid.toLowerCase().includes(sid)) continue;
     if (candidate.updated_at < since) continue;
     if (!looksLike(candidate.project, cwdWords)) continue;
@@ -84,7 +88,7 @@ export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearch
       break;
     }
     budget -= candidate.size;
-    const hit = read(candidate, clauses, wanted, deps);
+    const hit = await read(candidate, clauses, wanted, deps);
     // The working directory the project directory only approximates: a hit is
     // kept when the transcript's own `cwd` holds every word asked for.
     if (hit !== undefined && holds(hit.cwd, cwdWords)) hits.push(hit);
@@ -169,15 +173,15 @@ function compile(args: SessionSearchArgs): { clauses: Clause[]; budgets: Budget[
  * The pass is one: the records that carry the query also carry the working
  * directory, the title and what the session last ran as, so a hit is built
  * from the reading that decided it rather than from a second one. */
-function read(
+async function read(
   candidate: TranscriptFile,
   clauses: readonly Clause[],
   wanted: { user: boolean; agent: boolean },
   deps: SearchDeps,
-): SessionSearchHit | undefined {
+): Promise<SessionSearchHit | undefined> {
   let text: string;
   try {
-    text = readFileSync(candidate.file, "utf8");
+    text = await readFile(candidate.file, "utf8");
   } catch {
     // Gone since it was listed, which is a session that ended mid-search.
     return undefined;
@@ -188,8 +192,13 @@ function read(
   let model: string | undefined;
   let effort: string | undefined;
   let createdAt: number | undefined;
+  let read = 0;
   for (const line of text.split("\n")) {
     if (line === "") continue;
+    read += 1;
+    // The file arrived in one `await` and reading it is CPU from here on, so
+    // the pass hands the loop back as it goes rather than at the file's end.
+    if (due(read)) await breathe();
     const record = readRecord(line);
     if (record === undefined) continue;
     cwd ??= record.cwd;

package/src/sessions/status.ts

@@ -5,7 +5,7 @@ import type {
   SessionStatusSnapshot,
   Sid,
 } from "@ccmsg/protocol";
-import { canonical, within } from "../files/containment.ts";
+import { canonicalSync, 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";
@@ -43,7 +43,7 @@ export function sessionStatusOf(
   sid: Sid;
 } {
   const stopped = stoppedOn(facts);
-  const root = where.root === undefined ? undefined : canonical(where.root);
+  const root = where.root === undefined ? undefined : canonicalSync(where.root);
   return {
     sid,
     todos: [...facts.todos],
@@ -54,7 +54,7 @@ export function sessionStatusOf(
     external_files:
       root === undefined
         ? []
-        : facts.named_files.filter((file) => !within(canonical(file.path), root)),
+        : facts.named_files.filter((file) => !within(canonicalSync(file.path), root)),
     workspace_folders: workspaceFolders(where.cwd),
     ...(stopped === undefined ? {} : { api_error: stopped }),
   };

package/src/transcript/files.ts

@@ -1,4 +1,5 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { readdirSync, type Stats, statSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import type { Sid, TranscriptSubject } from "@ccmsg/protocol";
 import { type Harness, HARNESS } from "../harness/index.ts";
@@ -114,7 +115,7 @@ export class TranscriptFiles {
    * `agent_id` and `teammate` are two ways of naming the same kind of file and
    * cannot be combined — a request carrying both names two files and is a
    * caller's mistake rather than a choice this makes for them. */
-  locate(sid: Sid, names: AgentNames = {}): string {
+  async locate(sid: Sid, names: AgentNames = {}): Promise<string> {
     const file = this.session(sid);
     if (names.agent_id !== undefined && names.teammate !== undefined) {
       throw new OpError("invalid_args", "agent_id and teammate name two different transcripts");
@@ -127,9 +128,11 @@ export class TranscriptFiles {
     }
     const under = agentsDir(file, names.run_id);
     if (names.agent_id !== undefined) {
-      return existing(join(under, `agent-${name(names.agent_id, AGENT_ID, "agent_id")}${SUFFIX}`));
+      return await existing(
+        join(under, `agent-${name(names.agent_id, AGENT_ID, "agent_id")}${SUFFIX}`),
+      );
     }
-    return this.teammate(under, name(names.teammate ?? "", TEAMMATE, "teammate"));
+    return await this.teammate(under, name(names.teammate ?? "", TEAMMATE, "teammate"));
   }
 
   /** Which standing a transcript was written from, which every item read out
@@ -148,13 +151,13 @@ export class TranscriptFiles {
    * nothing goes on standing, nobody is addressed by name — so a teammate read
    * as one loses a name it might have been drawn under, where the reverse would
    * have a reader write back to something that is already gone. */
-  subjectOf(file: string): TranscriptSubject {
+  async subjectOf(file: string): Promise<TranscriptSubject> {
     const name = basename(file);
     if (!name.startsWith(AGENT_PREFIX) || !name.endsWith(SUFFIX)) return "main";
     let note: unknown;
     try {
       note = JSON.parse(
-        readFileSync(join(dirname(file), `${name.slice(0, -SUFFIX.length)}.meta.json`), "utf8"),
+        await readFile(join(dirname(file), `${name.slice(0, -SUFFIX.length)}.meta.json`), "utf8"),
       );
     } catch {
       return "sub";
@@ -168,10 +171,10 @@ export class TranscriptFiles {
    * The name a teammate carries in conversation is not its filename, so the
    * directory's own records are read for it rather than the name being
    * substituted into a path. */
-  private teammate(under: string, wanted: string): string {
+  private async teammate(under: string, wanted: string): Promise<string> {
     let names: string[];
     try {
-      names = readdirSync(under);
+      names = await readdir(under);
     } catch {
       throw new OpError("not_found", `no agent has run under this session`);
     }
@@ -179,13 +182,13 @@ export class TranscriptFiles {
       if (!each.endsWith(".meta.json")) continue;
       let document: unknown;
       try {
-        document = JSON.parse(readFileSync(join(under, each), "utf8"));
+        document = JSON.parse(await readFile(join(under, each), "utf8"));
       } catch {
         continue;
       }
       const named = (document as { name?: unknown } | null)?.name;
       if (named !== wanted) continue;
-      return existing(join(under, `${each.slice(0, -".meta.json".length)}${SUFFIX}`));
+      return await existing(join(under, `${each.slice(0, -".meta.json".length)}${SUFFIX}`));
     }
     throw new OpError("not_found", `no teammate of this session is addressed as ${wanted}`);
   }
@@ -195,16 +198,16 @@ export class TranscriptFiles {
    * The one enumeration a search and a fork sweep both start from. It states
    * the file and what a `stat` already said about it, so neither has to stat
    * again to decide whether to open it. */
-  all(): TranscriptFile[] {
+  async all(): Promise<TranscriptFile[]> {
     const layout = LAYOUTS[this.deps.harness];
     const found: TranscriptFile[] = [];
-    for (const dir of directories(this.#root(), layout.depth)) {
-      for (const entry of names(dir)) {
+    for (const dir of await walked(this.#root(), layout.depth)) {
+      for (const entry of await listed(dir)) {
         const sid = layout.sidOf(entry);
         if (sid === undefined) continue;
         const file = join(dir, entry);
-        const stat = statOf(file);
-        if (stat === undefined) continue;
+        const known = await stated(file);
+        if (known === undefined) continue;
         found.push({
           sid,
           file,
@@ -213,9 +216,9 @@ export class TranscriptFiles {
           // a session ran narrows nothing, and the transcript's own `cwd`
           // decides as it already does.
           ...(this.deps.harness === "claude" ? { project: basename(dir) } : {}),
-          size: stat.size,
-          created_at: Math.round(stat.birthtimeMs || stat.ctimeMs),
-          updated_at: Math.round(stat.mtimeMs),
+          size: known.size,
+          created_at: Math.round(known.birthtimeMs || known.ctimeMs),
+          updated_at: Math.round(known.mtimeMs),
         });
       }
     }
@@ -260,7 +263,27 @@ export class TranscriptFiles {
  *
  * Names are read rather than dates computed: what is there is what the harness
  * wrote, and a tree with a directory nobody expected is one whose files are
- * still found. */
+ * still found.
+ *
+ * There are two of this walk, and of the two readings below it, because the
+ * two callers are not alike: `all()` runs from an op and reads the tree
+ * without holding the instance, while `path()` also runs from a subscription
+ * being opened, which states its value in the turn it is opened in and so
+ * cannot wait (DESIGN §6.2). The one that cannot wait is the one CT-Q8 and the
+ * issue `fold-from-head-with-versioned-cache` settle, and the two become one
+ * reading again when they do. */
+async function walked(root: string, depth: number): Promise<string[]> {
+  let level = [root];
+  for (let step = 0; step < depth; step += 1) {
+    const below: string[] = [];
+    for (const dir of level) {
+      for (const entry of await listed(dir)) below.push(join(dir, entry));
+    }
+    level = below;
+  }
+  return level;
+}
+
 function directories(root: string, depth: number): string[] {
   let level = [root];
   for (let step = 0; step < depth; step += 1) {
@@ -305,11 +328,21 @@ function name(value: string, shape: RegExp, field: string): string {
   return value;
 }
 
-function existing(file: string): string {
-  if (!isFile(file)) throw new OpError("not_found", "no transcript is held for that agent");
+async function existing(file: string): Promise<string> {
+  if ((await stated(file)) === undefined) {
+    throw new OpError("not_found", "no transcript is held for that agent");
+  }
   return file;
 }
 
+async function listed(dir: string): Promise<string[]> {
+  try {
+    return await readdir(dir);
+  } catch {
+    return [];
+  }
+}
+
 function names(dir: string): string[] {
   try {
     return readdirSync(dir);
@@ -318,10 +351,19 @@ function names(dir: string): string[] {
   }
 }
 
+async function stated(file: string): Promise<Stats | undefined> {
+  try {
+    const known = await stat(file);
+    return known.isFile() ? known : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function statOf(file: string) {
   try {
-    const stat = statSync(file);
-    return stat.isFile() ? stat : undefined;
+    const known = statSync(file);
+    return known.isFile() ? known : undefined;
   } catch {
     return undefined;
   }

package/src/transcript/read.ts

@@ -1,4 +1,4 @@
-import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { open, stat } from "node:fs/promises";
 import type { TranscriptReadResult, Sid } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
 
@@ -20,15 +20,15 @@ export const READ_LIMIT = 512 * 1024;
  *
  * The offsets are the ones the `transcript` topic's frames carry, so what a
  * client reads and what arrives live stitch together without overlap. */
-export function readSlice(
+export async function readSlice(
   sid: Sid,
   file: string,
   before?: number,
   maxBytes?: number,
-): TranscriptReadResult {
+): Promise<TranscriptReadResult> {
   let size: number;
   try {
-    size = statSync(file).size;
+    size = (await stat(file)).size;
   } catch {
     throw new OpError("not_found", `the transcript of ${sid} could not be read`);
   }
@@ -45,7 +45,7 @@ export function readSlice(
   // arithmetic puts them — inside a character as readily as before one — and
   // decoding first would turn those bytes into replacement characters of a
   // different length, moving every offset derived from them.
-  const bytes = slice(file, probe, until);
+  const bytes = await slice(file, probe, until);
   // What of the read is whole records: everything up to the last newline. A
   // record the writer has not finished ends the file without one.
   const lastNewline = bytes.lastIndexOf(NEWLINE);
@@ -69,14 +69,14 @@ const NEWLINE = 0x0a;
 
 /** The bytes in a range. A range that reads short — the file was truncated
  * between the stat and the read — yields what was actually there. */
-function slice(file: string, from: number, to: number): Buffer {
+async function slice(file: string, from: number, to: number): Promise<Buffer> {
   if (to <= from) return Buffer.alloc(0);
-  const handle = openSync(file, "r");
+  const handle = await open(file, "r");
   try {
     const buffer = Buffer.alloc(to - from);
-    const read = readSync(handle, buffer, 0, buffer.length, from);
-    return buffer.subarray(0, read);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, from);
+    return buffer.subarray(0, bytesRead);
   } finally {
-    closeSync(handle);
+    await handle.close();
   }
 }

package/src/transcript/scan.ts

@@ -0,0 +1,49 @@
+import type { TranscriptSubject } from "@ccmsg/protocol";
+import { Classification, type Item } from "./items/index.ts";
+import { positioned, span } from "./items/record.ts";
+
+/** How many records one pass reads before it hands the loop back.
+ *
+ * A transcript is read whole by the ops that classify one, and reading it is
+ * CPU rather than IO: the file arrives in one `await` and every record in it is
+ * then parsed. Nothing else on the instance runs while that happens, so the
+ * pass is cut into turns — small enough that the wait an op elsewhere sees is
+ * one turn of parsing, large enough that the turns themselves cost nothing
+ * measurable against the parsing they carry. */
+const RECORDS_PER_TURN = 2000;
+
+/** Hand the event loop back, so that whatever else is waiting on it runs.
+ *
+ * The pause of a macrotask rather than of a microtask: a promise resolved with
+ * nothing to wait for is drained before the loop is reached at all, which would
+ * make the yield a shape in the code and nothing in the behaviour. */
+export function breathe(): Promise<void> {
+  return new Promise((resume) => {
+    setImmediate(resume);
+  });
+}
+
+/** Whether this many records have gone by since the last pause. */
+export function due(read: number): boolean {
+  return read > 0 && read % RECORDS_PER_TURN === 0;
+}
+
+/** A whole transcript as the items it was read into, yielding as it goes.
+ *
+ * The same reading `classify` does over the whole text at once, cut into turns:
+ * one `Classification` is fed chunk after chunk, so a call in one chunk is
+ * still known when its result arrives in a later one, and the items come back
+ * in the order the records are in. */
+export async function classified(text: string, subject: TranscriptSubject): Promise<Item[]> {
+  const reading = new Classification(subject);
+  const lines = text.split("\n");
+  const items: Item[] = [];
+  let offset = 0;
+  for (let from = 0; from < lines.length; from += RECORDS_PER_TURN) {
+    const chunk = lines.slice(from, from + RECORDS_PER_TURN);
+    for (const item of reading.readAll(positioned(chunk, offset))) items.push(item);
+    for (const line of chunk) offset += span(line);
+    if (from + RECORDS_PER_TURN < lines.length) await breathe();
+  }
+  return items;
+}