@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/tee-writer.js

@@ -1,16 +1,16 @@
 /**
- * TeeWriter — a Writable stream that writes raw NDJSON to a file while
- * simultaneously streaming human-readable text to a separate stream (e.g.
+ * TeeWriter — a Writable stream that writes raw NDJSON to a file. At the
+ * same time it sends human-readable text to a separate stream (e.g.
  * process.stdout).
  *
  * All modes emit the same { source, seq, event } envelope. The `mode`
- * parameter controls display formatting: multi-participant modes show
+ * parameter controls the display format. Multi-participant modes show
  * source labels on content lines.
  *
- * Human text rendering is delegated to the pure modules under `./render/`
- * so the live stream and the offline `TraceCollector.toText()` replay share
- * one formatting path. The NDJSON going to `fileStream` is
- * untouched — only what reaches `textStream` changes.
+ * The pure modules under `./render/` render the human text, so the live
+ * stream and the offline `TraceCollector.toText()` replay share one format
+ * path. The NDJSON that goes to `fileStream` stays untouched. Only what
+ * reaches `textStream` changes.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
@@ -20,15 +20,16 @@ import { TraceCollector } from "./trace-collector.js";
 import { renderTurnLines } from "./render/turn-renderer.js";
 import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
 
-/** Writable stream that saves raw NDJSON to a file while streaming human-readable text to a display stream. */
+/** Writable stream that saves raw NDJSON to a file and sends human-readable text to a display stream. */
 export class TeeWriter extends Writable {
   /**
    * @param {object} deps
    * @param {import("stream").Writable} deps.fileStream - Stream to write raw NDJSON to
    * @param {import("stream").Writable} deps.textStream - Stream to write human-readable text to
    * @param {"raw"|"supervised"} [deps.mode] - Display mode: "raw" (no source labels) or "supervised" (source labels) (default: "raw")
-   * @param {function} [deps.now] - Injected ISO-timestamp source threaded into
-   *   the internal `TraceCollector` (`() => isoTimestamp(runtime.clock.now())`).
+   * @param {function} [deps.now] - Injected ISO-timestamp source. The class
+   *   threads it into the internal `TraceCollector`
+   *   (`() => isoTimestamp(runtime.clock.now())`).
    */
   constructor({ fileStream, textStream, mode, now }) {
     super();
@@ -68,18 +69,17 @@ export class TeeWriter extends Writable {
       this.processLine(this.partial);
     }
 
-    // Emit the trailing `--- Result: ... ---` footer — the one summary line
-    // humans want. This is the same tail TraceCollector.toText()
-    // appends, so the live stream and the offline replay stay in sync.
-    // The superseded `--- Evaluation ... ---` footer is gone in every mode.
+    // Emit the trailing `--- Result: ... ---` footer. It is the one summary
+    // line humans want. TraceCollector.toText() appends the same tail, so
+    // the live stream and the offline replay stay in sync. No mode emits
+    // the superseded `--- Evaluation ... ---` footer.
     if (this.collector.result) {
       const text = this.collector.toText();
       const idx = text.lastIndexOf("\n---");
       if (idx !== -1) {
-        // Slice past the leading `\n` — the previously-streamed body
-        // already ended with its own newline, so re-emitting `\n---` here
-        // would produce a blank line before the footer and desync from
-        // the offline replay.
+        // Slice past the leading `\n`. The body that already streamed
+        // ended with its own newline. A second `\n---` here would add a
+        // blank line before the footer and desync from the offline replay.
         this.textStream.write(text.slice(idx + 1) + "\n");
       }
     }
@@ -88,7 +88,7 @@ export class TeeWriter extends Writable {
   }
 
   /**
-   * Process a single NDJSON line — unified envelope handling for all modes.
+   * Process a single NDJSON line. The same envelope logic covers all modes.
    * @param {string} line
    */
   processLine(line) {
@@ -102,14 +102,14 @@ export class TeeWriter extends Writable {
     // Universal envelope: { source, seq, event }
     if (parsed.event) {
       // Always forward to the collector so it can capture orchestrator
-      // metadata (e.g. the summary verdict for the result footer); the
-      // collector adds no turn for suppressed events, so flushTurns stays
+      // metadata (e.g. the summary verdict for the result footer). The
+      // collector adds no turn for suppressed events. So flushTurns stays
       // a no-op when we skip it below.
       this.collector.addLine(line);
 
-      // Orchestrator lifecycle events are suppressed from the text stream
-      // entirely — humans only want agent-visible content. They still
-      // reached fileStream above.
+      // The text stream drops orchestrator lifecycle events entirely.
+      // Humans only want agent-visible content. These events still reached
+      // fileStream above.
       if (
         parsed.source === "orchestrator" &&
         isSuppressedOrchestratorEvent(parsed.event)
@@ -126,7 +126,7 @@ export class TeeWriter extends Writable {
   }
 
   /**
-   * Emit text for any new turns accumulated by the collector.
+   * Emit text for any new turns the collector accumulated.
    */
   flushTurns() {
     const turns = this.collector.turns;

package/src/trace-collector.js

@@ -1,12 +1,12 @@
 /**
  * Collects Claude Code stream-json NDJSON events into structured traces.
  *
- * Accepts one NDJSON line at a time via addLine(), then produces either a
- * structured JSON trace (toJSON) or human-readable text (toText).
+ * Accepts one NDJSON line at a time through addLine(). Then produces either
+ * a structured JSON trace (toJSON) or human-readable text (toText).
  *
- * Human text rendering is delegated to the pure modules under `./render/`
- * so the live `TeeWriter` stream and the offline `toText()` replay share
- * one formatting path.
+ * The pure modules under `./render/` render the human text. So the live
+ * `TeeWriter` stream and the offline `toText()` replay use one shared path
+ * to format the text.
  */
 
 import { isoTimestamp } from "@forwardimpact/libutil";
@@ -18,12 +18,12 @@ import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
 export class TraceCollector {
   /**
    * @param {object} [deps]
-   * @param {function} [deps.now] - Returns an ISO timestamp string. Injected
-   *   so the collector never reads the wall clock directly; construct it as
-   *   `() => isoTimestamp(runtime.clock.now())`. When omitted (pure
-   *   structural/replay use where every event already carries a `timestamp`),
-   *   the fallback formats the epoch — a deterministic sentinel, not a clock
-   *   read.
+   * @param {function} [deps.now] - Returns an ISO timestamp string. Inject it
+   *   so the collector never reads the wall clock directly. Construct it as
+   *   `() => isoTimestamp(runtime.clock.now())`. Omit it for pure
+   *   structural or replay use, where every event already carries a
+   *   `timestamp`. The fallback then formats the epoch. The epoch is a
+   *   deterministic sentinel. The fallback does not read a clock.
    */
   constructor(deps = {}) {
     /** @type {function} */
@@ -44,7 +44,7 @@ export class TraceCollector {
 
   /**
    * Parse one NDJSON line and accumulate state.
-   * Malformed lines are silently skipped.
+   * This method silently skips malformed lines.
    * @param {string} line - A single JSON line from stream-json output
    */
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: NDJSON envelope unwrap + orchestrator/system/assistant/user dispatch
@@ -60,8 +60,8 @@ export class TraceCollector {
     }
 
     // Unwrap combined supervised trace format {source, seq, event}. The
-    // Supervisor / Facilitator emits this wrapper; when replayed through
-    // addLine the inner event is the one we care about. Carry the envelope
+    // Supervisor / Facilitator emits this wrapper. On replay through
+    // addLine, the inner event is the one we care about. Carry the envelope
     // `source` onto each new turn so the renderer can color it correctly.
     let source = null;
     if (event.event && !event.type && typeof event.source === "string") {
@@ -69,11 +69,11 @@ export class TraceCollector {
       event = event.event;
     }
 
-    // Orchestrator lifecycle events carry no content and are suppressed
-    // from turns entirely — the NDJSON artifact keeps them separately.
+    // Orchestrator lifecycle events carry no content. The collector drops
+    // them from turns entirely. The NDJSON artifact keeps them separately.
     if (source === "orchestrator" && isSuppressedOrchestratorEvent(event)) {
-      // The summary event carries the supervisor/facilitator verdict —
-      // capture it before dropping the event, so the result footer can
+      // The summary event carries the supervisor/facilitator verdict.
+      // Capture it before you drop the event, so the result footer can
       // surface verdict="failure" instead of the SDK's per-runner status.
       if (event.type === "summary") {
         this.orchestratorSummary = {
@@ -219,11 +219,11 @@ export class TraceCollector {
   }
 
   /**
-   * Accumulate a result event into the running summary. Facilitated and
+   * Accumulate a result event into the summary so far. Facilitated and
    * supervised sessions emit one result event per runner invocation, so a
-   * single trace can carry several — cost, duration, turn, and token
-   * figures sum across all of them. `result` reflects the latest event;
-   * `isError` is true once any event errored.
+   * single trace can carry several. Cost, duration, turn, and token figures
+   * sum across all of them. `result` reflects the latest event. `isError`
+   * is true once any event errored.
    * @param {object} event
    */
   handleResult(event) {
@@ -270,15 +270,17 @@ export class TraceCollector {
   }
 
   /**
-   * Render the accumulated turns as human-readable text — the same path the
-   * live `TeeWriter` stream uses, so `fit-harness output --format=text` over a
-   * captured trace reproduces what the live workflow log showed.
+   * Render the accumulated turns as human-readable text. This is the same
+   * path the live `TeeWriter` stream uses. So
+   * `gemba-harness output --format=text` over a captured trace reproduces
+   * what the live workflow log showed.
    *
-   * Source prefixes are emitted whenever at least one turn has a non-null
-   * source (supervised / facilitated traces). A pure `run` trace has no
-   * envelope, all turn sources are null, and the renderer drops the prefix.
+   * The renderer emits source prefixes whenever at least one turn has a
+   * non-null source (supervised / facilitated traces). A pure `run` trace
+   * has no envelope. All turn sources are null. The renderer drops the
+   * prefix.
    *
-   * @returns {string} Formatted text output including ANSI escapes
+   * @returns {string} Formatted text output with ANSI escapes
    */
   toText() {
     const withPrefix = this.turns.some((t) => t.source);
@@ -290,22 +292,22 @@ export class TraceCollector {
 
     const tail = this.#formatResultTail();
 
-    // Each rendered line already ends with `\n`; concatenate, drop the
-    // trailing newline, then append the tail so the output shape stays
-    // compatible with existing consumers (no double-blank line before
-    // the result footer when there are turns, no leading blank when there
-    // are not).
+    // Each rendered line already ends with `\n`. Concatenate the lines.
+    // Drop the trailing newline. Then append the tail so the output shape
+    // stays compatible with existing consumers. With turns, there is no
+    // double-blank line before the result footer. Without turns, there is
+    // no leading blank.
     const body = out.join("").replace(/\n$/, "");
     return body + tail;
   }
 
   /**
-   * Format the trailing result summary line. When an orchestrator
-   * summary is present (supervised / facilitated mode), the headline word is
-   * the supervisor's verdict ("success" / "failure") rather than the SDK's
-   * per-runner subtype, so the footer aligns with the CI exit code. Turn,
-   * cost, and duration figures are the accumulated totals across every
-   * result event in the trace, not the last event's.
+   * Format the trailing result summary line. With an orchestrator summary
+   * (supervised / facilitated mode), the headline word is the supervisor's
+   * verdict ("success" / "failure"). It is not the SDK's per-runner
+   * subtype. The footer then aligns with the CI exit code. Turn, cost, and
+   * duration figures are the accumulated totals across every result event
+   * in the trace. They are not the last event's figures.
    * @returns {string}
    */
   #formatResultTail() {
@@ -320,7 +322,7 @@ export class TraceCollector {
   }
 }
 
-/** Identity element for result-event accumulation in handleResult. */
+/** Identity element that handleResult uses to accumulate result events. */
 const EMPTY_RESULT = {
   isError: false,
   totalCostUsd: 0,
@@ -347,7 +349,7 @@ function normalizeUsage(usage) {
 
 /**
  * Sum two token-usage records field-by-field. Either side may be null
- * (a result event without usage); the sum is null only when both are.
+ * (a result event without usage). The sum is null only when both are null.
  * @param {object|null} a
  * @param {object|null} b
  * @returns {object|null}
@@ -365,9 +367,10 @@ function sumTokenUsage(a, b) {
 }
 
 /**
- * Per-model fields that sum additively across result events — token counts,
- * per-model cost, and request counters. Every other per-model field (e.g. a
- * context-window size) is carried first-seen, never summed.
+ * Per-model fields that sum additively across result events: token counts,
+ * per-model cost, and request counters. The merge carries every other
+ * per-model field (e.g. a context-window size) from the first event that
+ * set it. The merge never sums those fields.
  */
 const ADDITIVE_MODEL_FIELDS = [
   "inputTokens",
@@ -380,8 +383,9 @@ const ADDITIVE_MODEL_FIELDS = [
 
 /**
  * Merge two per-model usage maps across result events. Additive fields
- * (token counts, cost, request counters) sum; non-additive fields are carried
- * from the first event that set them (prev wins). Either side may be null.
+ * (token counts, cost, request counters) sum. The merge carries
+ * non-additive fields from the first event that set them (prev wins).
+ * Either side may be null.
  * @param {object|null} prevMU
  * @param {object|null} nextMU
  * @returns {object|null}
@@ -401,7 +405,8 @@ function mergeModelUsage(prevMU, nextMU) {
 }
 
 /**
- * Merge one model's usage: additive fields sum, others carry first-seen (a).
+ * Merge one model's usage. Additive fields sum. Other fields carry the
+ * first-seen value (a).
  * @param {object} a - First-seen (prev) per-model usage.
  * @param {object} b - Next per-model usage.
  * @returns {object}

package/src/trace-github.js

@@ -7,8 +7,8 @@ import { isoTimestamp } from "@forwardimpact/libutil";
 const API = "https://api.github.com";
 
 /**
- * GitHub API client for trace-related operations: listing workflow runs
- * and downloading trace artifacts.
+ * GitHub API client for trace-related operations. It lists workflow runs
+ * and downloads trace artifacts.
  */
 export class TraceGitHub {
   /**
@@ -17,7 +17,7 @@ export class TraceGitHub {
    * @param {string} deps.owner - Repository owner
    * @param {string} deps.repo  - Repository name
    * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
-   *   Ambient collaborators; uses `fs`, `subprocess`, `clock`.
+   *   Ambient collaborators. The class uses `fs`, `subprocess`, `clock`.
    */
   constructor({ token, owner, repo, runtime }) {
     if (!runtime) throw new Error("runtime is required");
@@ -28,27 +28,30 @@ export class TraceGitHub {
   }
 
   /**
-   * List recent workflow runs, optionally filtered by name pattern and by the
-   * participant whose trace lane a run carries.
+   * List recent workflow runs. Filter them by name pattern, and by the
+   * participant whose trace lane a run carries. Both filters are optional.
    *
-   * Without `participant`, behaviour is unchanged: the workflow-name pattern is
-   * the only filter. With `participant`, each name-matched run is resolved
-   * against its trace lane (see {@link runMatchesParticipant}) and annotated
-   * with a `match` field:
+   * Without `participant`, the behaviour does not change. The workflow-name
+   * pattern is the only filter. With `participant`, the method resolves each
+   * name-matched run against its trace lane
+   * (see {@link runMatchesParticipant}). It then annotates the run with a
+   * `match` field:
    *   - `"confirmed"` — the participant's lane is present in the run's
    *     artifacts (matrix artifact name, or a member filename in the shared
    *     dispatch artifact).
    *   - `"unconfirmed-pending-artifacts"` — the run's workflow mints trace
    *     artifacts but none exist yet (still running, or completed-but-not-yet
-   *     uploaded); reported as a candidate, never silently dropped.
-   * Runs that have artifacts but no matching lane are omitted. Participant
-   * identity is read from artifact/file *names* only, never from trace content.
+   *     uploaded). The method reports the run as a candidate. It never drops
+   *     the run silently.
+   * The method omits runs that have artifacts but no matching lane. It reads
+   * participant identity from artifact/file *names* only. It never reads
+   * trace content.
    *
    * @param {object} [opts]
-   * @param {string} [opts.pattern] - Case-insensitive regex to match workflow name (default: "kata|agent" — covers `Kata: Shift`, `Kata: Dispatch`, and any `agent`-named workflow)
+   * @param {string} [opts.pattern] - Case-insensitive regex to match workflow name (default: "kata|agent", which covers `Kata: Shift`, `Kata: Dispatch`, and any `agent`-named workflow)
    * @param {number} [opts.limit=50] - Max runs to return from GitHub API
    * @param {string} [opts.lookback="7d"] - How far back to search (e.g. "7d", "24h", "2w")
-   * @param {string} [opts.participant] - Participant name; when set, filter/annotate runs by trace lane
+   * @param {string} [opts.participant] - Participant name. When set, the method filters and annotates runs by trace lane
    * @returns {Promise<object[]>} Array of {workflow, runId, status, conclusion, createdAt, branch, url[, match]}
    */
   async listRuns(opts = {}) {
@@ -97,15 +100,17 @@ export class TraceGitHub {
    * Decide whether a run carries a participant's trace lane.
    *
    * Matrix hosts name the participant in an artifact name
-   * (`trace--<participant>`); dispatch hosts name it in a member filename
-   * (`trace--<case>--<participant>.<role>.ndjson`) inside one shared `trace--*`
-   * artifact. The GitHub artifacts API exposes only artifact-level metadata, so
-   * a matrix lane confirms from the inventory alone, while a dispatch lane
-   * requires downloading the shared artifact and listing its extracted member
-   * filenames — names only, never trace content.
+   * (`trace--<participant>`). Dispatch hosts name it in a member filename
+   * (`trace--<case>--<participant>.<role>.ndjson`) inside one shared
+   * `trace--*` artifact. The GitHub artifacts API exposes only
+   * artifact-level metadata. So a matrix lane confirms from the inventory
+   * alone. For a dispatch lane, the method downloads the shared artifact.
+   * Then it lists the extracted member filenames. It reads names only. It
+   * never reads trace content.
    *
    * A run whose trace artifacts are absent (still running, or
-   * completed-but-not-yet-uploaded) is a candidate, not a drop.
+   * completed-but-not-yet-uploaded) is a candidate. The method does not
+   * drop it.
    *
    * @param {number|string} runId
    * @param {string} participant
@@ -119,8 +124,9 @@ export class TraceGitHub {
       a.name.startsWith("trace--"),
     );
 
-    // No trace artifacts yet: a candidate the matcher must report, not drop —
-    // the lane may upload when the host completes.
+    // No trace artifacts yet. The matcher must report this run as a
+    // candidate. It must not drop the run. The lane may upload when the
+    // host completes.
     if (traceArtifacts.length === 0) return "unconfirmed-pending-artifacts";
 
     // Matrix host: the participant is an artifact name. No download.
@@ -146,10 +152,11 @@ export class TraceGitHub {
 
   /**
    * Resolve a participant's lane trace path for a known run in one keyed
-   * lookup — no run enumeration, no trace-content inspection.
+   * lookup. The method does not enumerate runs. It does not inspect trace
+   * content.
    *
    * Matrix host: the artifact name carries the participant (no download).
-   * Dispatch host: download the shared `trace--*` artifact and return the
+   * Dispatch host: download the shared `trace--*` artifact. Return the
    * extracted member file whose name carries the participant.
    *
    * @param {number|string} runId
@@ -208,12 +215,12 @@ export class TraceGitHub {
   }
 
   /**
-   * Download a trace artifact from a workflow run and extract it.
+   * Download a trace artifact from a workflow run. Extract it.
    *
-   * When `opts.name` is set, looks up that exact artifact. Otherwise picks
-   * the single `trace--*` artifact if exactly one exists, or throws with a
-   * disambiguation list when matrix workflows emit multiple per-participant
-   * artifacts (see {@link pickTraceArtifact}).
+   * With `opts.name` set, the method looks up that exact artifact.
+   * Otherwise it picks the single `trace--*` artifact when exactly one
+   * exists. When matrix workflows emit multiple per-participant artifacts,
+   * it throws with a disambiguation list (see {@link pickTraceArtifact}).
    *
    * @param {number|string} runId
    * @param {object} [opts]
@@ -296,13 +303,14 @@ export class TraceGitHub {
 /**
  * Test whether a participant's trace lane is present in a list of names.
  *
- * Matches the two trace-naming shapes by *name* only (never by content):
+ * This function matches the two trace-name shapes by *name* only (never by
+ * content):
  *   - matrix artifact name: `trace--<participant>`
  *   - dispatch member filename: `trace--<case>--<participant>.<role>.ndjson`
  *
- * The participant segment is delimited by `--` and ends at the next `--`, `.`,
- * or end-of-string, so a substring like `release` does not match
- * `release-engineer` and vice versa.
+ * The `--` separator delimits the participant segment. The segment ends at
+ * the next `--`, at a `.`, or at the end of the string. So a substring like
+ * `release` does not match `release-engineer` and vice versa.
  *
  * @param {string[]} names - Artifact names or extracted member filenames.
  * @param {string} participant - Participant name to look for.
@@ -326,11 +334,12 @@ export function participantInNames(names, participant) {
 /**
  * Pick the trace artifact to download from a workflow run's artifact list.
  *
- * When `name` is given, returns the exact match or throws with the available
- * names. When `name` is omitted, returns the only `trace--*` artifact if
- * there is exactly one; if there are multiple (matrix workflows like
- * `kata-shift.yml` emit one `trace--<participant>` per cell), throws and
- * lists them so the caller can pass `--name` to disambiguate.
+ * With `name` given, this function returns the exact match. If it finds no
+ * match, it throws with the available names. Without `name`, it returns the
+ * only `trace--*` artifact when exactly one exists. With more than one
+ * (matrix workflows like `kata-shift.yml` emit one `trace--<participant>`
+ * per cell), it throws and lists them. The caller can then pass `--name` to
+ * disambiguate.
  *
  * @param {Array<{name: string}>} artifacts - Artifact list from the GitHub API.
  * @param {string} [name] - Exact artifact name to match.
@@ -407,7 +416,7 @@ export function parseGitRemote(remote) {
  * Detect the current GitHub repository slug as `{owner, repo}`.
  *
  * Resolution order:
- *   1. `GITHUB_REPOSITORY` env var (set automatically by GitHub Actions).
+ *   1. `GITHUB_REPOSITORY` env var (GitHub Actions sets it automatically).
  *   2. `git remote get-url origin` in the current working directory.
  *
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
@@ -442,12 +451,12 @@ export async function detectRepoSlug(runtime) {
 }
 
 /**
- * Create a TraceGitHub instance. The caller is responsible for resolving
- * the GitHub token — typically via `Config.ghToken()` — so credential
- * loading stays at the CLI entry point.
+ * Create a TraceGitHub instance. The caller must resolve the GitHub token,
+ * typically with `Config.ghToken()`. So the CLI entry point loads the
+ * credentials.
  *
  * Breaking change from the prior signature: `token` is now a required
- * caller input. Construct a `Config` via `@forwardimpact/libconfig` and
+ * caller input. Construct a `Config` with `@forwardimpact/libconfig`. Then
  * pass `config.ghToken()`.
  *
  * @param {object} opts

package/src/trace-multi.js

@@ -1,20 +1,21 @@
 /**
- * Multi-file orchestrator for cross-trace `fit-trace` verbs.
+ * Multi-file orchestrator for cross-trace `gemba-trace` verbs.
  *
  * Two functions centralise the load-tag-concat (`runOver`) and
  * aggregate-and-sort (`aggregate`) policies so every cross-trace verb shares
  * one source-attribution rule. `compareTwo` derives per-side identity from
  * each input's basename and threads it into `TraceQuery.compare()`.
  *
- * `load` is injected (the exported `loadTrace` from `commands/trace.js`) so
- * this module stays IO-policy-free and unit-testable with a stub.
+ * The caller injects `load` (the exported `loadTrace` from
+ * `commands/trace.js`). So this module stays IO-policy-free. A stub makes it
+ * unit-testable.
  */
 import { basename } from "node:path";
 
 /**
- * Load each file → `TraceQuery`, run `query(tq)`, tag each emitted record with
- * `source: <basename>` only when more than one file is supplied. Records are
- * concatenated in file-then-record order.
+ * Load each file → `TraceQuery`. Run `query(tq)`. Tag each emitted record
+ * with `source: <basename>` only when the caller supplies more than one file.
+ * Concatenate the records in file-then-record order.
  * @param {string[]} files
  * @param {(tq: object) => object[]} query
  * @param {(file: string) => object} load
@@ -34,10 +35,10 @@ export function runOver(files, query, load) {
 }
 
 /**
- * Merge per-file record arrays by `key(record)`, summing each record's
- * existing `count` field (not occurrence count), and frequency-sort by
- * `count desc`. Merged records carry `sources: string[]` only when more than
- * one file is supplied.
+ * Merge per-file record arrays by `key(record)`. Sum the `count` field that
+ * each record already carries. The merge does not count occurrences.
+ * Frequency-sort by `count desc`. Merged records carry `sources: string[]`
+ * only when the caller supplies more than one file.
  * @param {string[]} files
  * @param {(tq: object) => Array<{count: number}>} query
  * @param {(record: object) => string} key
@@ -67,8 +68,8 @@ export function aggregate(files, query, key, load) {
 }
 
 /**
- * Load two files, derive each side's `{caseName, participant}` from its
- * basename via the `split` convention, and thread them into
+ * Load two files. Derive each side's `{caseName, participant}` from its
+ * basename through the `split` convention. Thread them into
  * `a.compare(b, {aIdentity, bIdentity})`.
  * @param {string} a
  * @param {string} b
@@ -86,8 +87,9 @@ export function compareTwo(a, b, load) {
 
 /**
  * Parse `trace--<case>--<participant>.<role>.ndjson` into `{caseName,
- * participant}`. On no match, `caseName` is the basename minus its final
- * `.ndjson` extension only and `participant` is null.
+ * participant}`. On no match, `caseName` is the basename without its final
+ * `.ndjson` extension. The function removes that one extension only.
+ * `participant` is then null.
  * @param {string} file
  * @returns {{caseName: string, participant: string|null}}
  */