@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/transcripts/registry.js

@@ -0,0 +1,161 @@
+'use strict';
+
+// 093 V.1, IC-021: loader, validator and doctor view for core/registry/transcripts.json, the data that
+// says where each harness keeps its transcripts. Like advice.json it stays outside REGISTRY_FILES: a bad
+// file turns the transcript feature off (`config-invalid`), it must not fail every install command.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const TRANSCRIPTS_FILE = 'core/registry/transcripts.json';
+const HARNESSES_FILE = 'core/registry/harnesses.json';
+const STALE_DAYS = 90;
+const DAY_MS = 86400000;
+const STATUSES = ['supported', 'events-only', 'unknown'];
+const FORMATS = ['jsonl', 'sqlite', 'jsonl+json'];
+const APPEND_ONLY = ['yes', 'no', 'unknown'];
+const JOINS = ['session-id', 'cwd', 'none'];
+const OSES = ['darwin', 'linux', 'win32'];
+const PLACEHOLDERS = new Set(['sessionId', 'cwdEncoded']);
+const ENTRY_KEYS = ['harness', 'reader', 'status', 'locations', 'format', 'appendOnly', 'join', 'requiredKeys', 'evidence', 'verifiedOn', 'versions'];
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value     )          {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0);
+}
+
+/** True for a real calendar date written YYYY-MM-DD. */
+function isDate(value     )          {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const at = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(at.getTime()) && at.toISOString().slice(0, 10) === value;
+}
+
+function validateLocation(location     , where        , errors          )       {
+  if (!isObject(location)) { errors.push(`${where} must be an object`); return; }
+  if (!OSES.includes(location.os)) errors.push(`${where}.os must be one of ${OSES.join(', ')}`);
+  if (!(typeof location.base === 'string' && /^(home|xdg-data|env:[A-Z_][A-Z0-9_]*)$/.test(location.base))) {
+    errors.push(`${where}.base must be home, xdg-data or env:<NAME>`);
+  }
+  if (!isStringArray(location.segments)) errors.push(`${where}.segments must be an array of non-empty strings`);
+  if (typeof location.glob !== 'string' || !location.glob) {
+    errors.push(`${where}.glob must be a non-empty string`);
+  } else {
+    for (const [, name] of location.glob.matchAll(/\{([^}]*)\}/g)) {
+      if (!PLACEHOLDERS.has(name)) errors.push(`${where}.glob has an unknown placeholder {${name}}`);
+    }
+  }
+  // R28: a Windows location stays unverified until someone measures it, and only Windows may say so.
+  if (location.os === 'win32') {
+    if (location.status !== 'unknown') errors.push(`${where} is win32, so its status must be "unknown"`);
+  } else if (location.status !== undefined) {
+    errors.push(`${where}.status is only allowed on a win32 location`);
+  }
+}
+
+function validateEntry(entry     , index        , errors          )       {
+  const label = isObject(entry) && typeof entry.harness === 'string' ? entry.harness : `entries[${index}]`;
+  if (!isObject(entry)) { errors.push(`${label} must be an object`); return; }
+  for (const key of ENTRY_KEYS) {
+    if (!Object.hasOwn(entry, key)) errors.push(`${label}.${key} is missing`);
+  }
+  if (typeof entry.harness !== 'string' || !entry.harness) errors.push(`${label}.harness must be a non-empty string`);
+  if (Object.hasOwn(entry, 'reader') && entry.reader !== null && (typeof entry.reader !== 'string' || !entry.reader)) {
+    errors.push(`${label}.reader must be a module id or null`);
+  }
+  if (Object.hasOwn(entry, 'status') && !STATUSES.includes(entry.status)) errors.push(`${label}.status must be one of ${STATUSES.join(', ')}`);
+  // A reader exists exactly when the harness is supported (IC-021: OpenCode moves only with its reader).
+  if (STATUSES.includes(entry.status) && entry.reader !== undefined) {
+    if (entry.status === 'supported' && entry.reader === null) errors.push(`${label}.reader must be set when status is supported`);
+    if (entry.status !== 'supported' && entry.reader !== null) errors.push(`${label}.reader must be null unless status is supported`);
+  }
+  if (Object.hasOwn(entry, 'locations')) {
+    if (!Array.isArray(entry.locations) || entry.locations.length === 0) errors.push(`${label}.locations must be a non-empty array`);
+    else entry.locations.forEach((location     , i        ) => validateLocation(location, `${label}.locations[${i}]`, errors));
+  }
+  if (Object.hasOwn(entry, 'format') && !FORMATS.includes(entry.format)) errors.push(`${label}.format must be one of ${FORMATS.join(', ')}`);
+  if (Object.hasOwn(entry, 'appendOnly') && !APPEND_ONLY.includes(entry.appendOnly)) errors.push(`${label}.appendOnly must be one of ${APPEND_ONLY.join(', ')}`);
+  if (Object.hasOwn(entry, 'join') && !JOINS.includes(entry.join)) errors.push(`${label}.join must be one of ${JOINS.join(', ')}`);
+  if (Object.hasOwn(entry, 'requiredKeys') && !isStringArray(entry.requiredKeys)) errors.push(`${label}.requiredKeys must be an array of non-empty strings`);
+  if (Object.hasOwn(entry, 'evidence') && (!isStringArray(entry.evidence) || entry.evidence.length === 0)) errors.push(`${label}.evidence must be a non-empty array of strings`);
+  if (Object.hasOwn(entry, 'verifiedOn') && !isDate(entry.verifiedOn)) errors.push(`${label}.verifiedOn must be a YYYY-MM-DD date`);
+  if (Object.hasOwn(entry, 'versions') && entry.versions !== null && (typeof entry.versions !== 'string' || !entry.versions)) {
+    errors.push(`${label}.versions must be a version range or null`);
+  }
+}
+
+/** The registry ids of core/registry/harnesses.json, read as plain data. */
+function readHarnessIds(repoRoot        , fsImpl      = fs)           {
+  const parsed = JSON.parse(fsImpl.readFileSync(path.join(path.resolve(repoRoot), HARNESSES_FILE), 'utf8'));
+  return parsed.harnesses.map((harness     ) => harness.id);
+}
+
+/**
+ * Checks the registry's shape and the id guard: the entry ids and `harnessIds` are the same set, with no
+ * exception (row 127 retired Gemini CLI, so there is no Gemini entry and no allowance for one).
+ */
+function validateTranscriptRegistry(registry     , { harnessIds }                          )                                    {
+  const errors           = [];
+  if (!isObject(registry)) return { ok: false, errors: ['registry must be an object'] };
+  if (registry.version !== 1) errors.push('version must be 1');
+  if (!Array.isArray(registry.entries)) {
+    errors.push('entries must be an array');
+    return { ok: false, errors };
+  }
+  registry.entries.forEach((entry     , i        ) => validateEntry(entry, i, errors));
+  const seen = new Set        ();
+  for (const entry of registry.entries) {
+    if (!isObject(entry) || typeof entry.harness !== 'string') continue;
+    if (seen.has(entry.harness)) errors.push(`${entry.harness} is a duplicate entry`);
+    seen.add(entry.harness);
+    if (!harnessIds.includes(entry.harness)) errors.push(`${entry.harness} is not a harnesses.json id`);
+  }
+  for (const id of harnessIds) {
+    if (!seen.has(id)) errors.push(`${id} has no entry (every harnesses.json id needs one)`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function loadTranscriptRegistry({ repoRoot = REPO_ROOT, file, fsImpl = fs }      = {})                                                                    {
+  const root = path.resolve(repoRoot);
+  const target = file || path.join(root, TRANSCRIPTS_FILE);
+  let registry     ;
+  let harnessIds          ;
+  try {
+    registry = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+    harnessIds = readHarnessIds(root, fsImpl);
+  } catch (error     ) {
+    return { ok: false, reason: 'config-invalid', detail: `${target}: ${error.message}` };
+  }
+  const validation = validateTranscriptRegistry(registry, { harnessIds });
+  if (!validation.ok) return { ok: false, reason: 'config-invalid', detail: validation.errors.join('; ') };
+  return { ok: true, registry };
+}
+
+/** Entries whose `verifiedOn` is more than STALE_DAYS before `now`. */
+function staleEntries(registry     , now       = new Date())                                                                  {
+  const out                                                                  = [];
+  for (const entry of registry.entries) {
+    const ageDays = Math.floor((now.getTime() - new Date(`${entry.verifiedOn}T00:00:00Z`).getTime()) / DAY_MS);
+    if (ageDays > STALE_DAYS) out.push({ harness: entry.harness, verifiedOn: entry.verifiedOn, ageDays });
+  }
+  return out;
+}
+
+/**
+ * The doctor's `transcripts` row: `ok`, `stale` (a `verifiedOn` older than 90 days) or `drift` (the file or
+ * the id guard is invalid, so the transcript feature is off). Read-only; never a finding, so the exit code
+ * does not change. A `format-unrecognized` seen at run time joins this row when V.4's readers exist.
+ */
+function transcriptsDoctorView({ repoRoot = REPO_ROOT, file, fsImpl = fs, now = new Date() }      = {})      {
+  const loaded = loadTranscriptRegistry({ repoRoot, file, fsImpl });
+  if (!loaded.ok) return { state: 'drift', entries: 0, stale: [], errors: (loaded.detail          ).split('; ') };
+  const stale = staleEntries(loaded.registry, now);
+  return { state: stale.length ? 'stale' : 'ok', entries: loaded.registry.entries.length, stale, errors: [] };
+}
+
+module.exports = { loadTranscriptRegistry, validateTranscriptRegistry, staleEntries, transcriptsDoctorView, STALE_DAYS, TRANSCRIPTS_FILE };

package/src/runtime/transcripts/stats.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * `transcript --action stats` (093 IC-023): traffic over the last window and who works with whom, for one
+ * project. The agents are `buildTree`'s nodes (newest first, at most 32; the rest counted in `notChecked`).
+ * A linked transcript is read in metadata mode (no text, no arguments), at most its last 256 KiB, in pages.
+ * An event without a time (Kiro keeps none per record) takes the transcript's newest known time, which for
+ * Kiro is the newest turn `end_timestamp`; if there is none, the window is unknown and the counts are null.
+ * Unknown is never zero: a harness that does not record a value gives null, and an agent with no readable
+ * transcript gives null everywhere. Zero is reported only for a transcript that was read and held nothing.
+ * `pairs` says who works with whom: equal model id (`same-model`), active attempts or running worker runs on
+ * one task id (`same-task`, `task`), and a plan `overlaps` pair held by two agents (`overlap`, `tasks`).
+ * Nothing is written; no path, pid or raw session id is printed.
+ */
+
+const fs = require('node:fs');
+const { buildTree, READERS } = require('../fleet/tree.js');
+const { loadPlan } = require('../task-attempts.js');
+const { overlaps } = require('../task-graph.js');
+const { parseCursor, toMs } = require('./cursor.js');
+const { inCheckouts, checkoutRoots, registryById } = require('./read.js');
+
+const DEFAULT_WINDOW = 10;
+const MAX_AGENTS = 32;
+const MAX_PAGES = 8;
+const TAIL_RECORDS = 4096;
+const TOKEN_FIELDS = ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoning'];
+
+/** Sums of the fields any event recorded; a field no event recorded stays null, and none at all is null. */
+function sumTokens(list       )      {
+  const out                                = {};
+  for (const field of TOKEN_FIELDS) {
+    const values = list.map((t) => t[field]).filter((v) => Number.isFinite(v));
+    out[field] = values.length ? values.reduce((a, b) => a + b, 0) : null;
+  }
+  return Object.values(out).some((v) => v !== null) ? out : null;
+}
+
+const round2 = (n        )         => Math.round(n * 100) / 100;
+
+/** Every event of the transcript's window, in pages, with the newest time the reader knew. */
+function readWindow(mod     , node     , internal     )                                   {
+  const events        = [];
+  let cursor                    ;
+  let clock = NaN;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const r = mod.read({ file: internal.file, companion: internal.companion, mode: 'metadata', cursor, limit: 500, tailRecords: TAIL_RECORDS, agentKey: node.agentKey });
+    events.push(...r.events);
+    const c = parseCursor(r.cursor);
+    clock = c && c.atMs > 0 ? c.atMs : clock;
+    cursor = r.cursor;
+    if (r.eof) break;
+  }
+  return { events, clock };
+}
+
+/** The per-agent numbers of the events at or after `startMs`. */
+function summarize(events       , clock        , startMs        , windowMin        )      {
+  if (events.length === 0) {
+    return { eventsPerMin: 0, toolCalls: 0, toolErrors: 0, toolDurationMs: null, tokens: null };
+  }
+  const timed = events.map((e) => ({ e, t: Number.isFinite(toMs(e.at)) ? toMs(e.at) : clock })).filter((x) => Number.isFinite(x.t));
+  if (timed.length === 0) return { eventsPerMin: null, toolCalls: null, toolErrors: null, toolDurationMs: null, tokens: null };
+  const inWindow = timed.filter((x) => x.t >= startMs).map((x) => x.e);
+  const results = inWindow.filter((e) => e.kind === 'tool-result');
+  const known = results.filter((e) => e.tool && e.tool.status !== null && e.tool.status !== undefined);
+  const durations = results.map((e) => e.tool && e.tool.durationMs).filter((d) => Number.isFinite(d)).sort((a, b) => a - b);
+  const usage = inWindow.filter((e) => e.kind === 'usage' && e.tokens).map((e) => e.tokens);
+  return {
+    eventsPerMin: round2(inWindow.length / windowMin),
+    toolCalls: inWindow.filter((e) => e.kind === 'tool-call').length,
+    toolErrors: results.length > 0 && known.length === 0 ? null : known.filter((e) => e.tool.status === 'error').length,
+    toolDurationMs: durations.length ? { p50: durations[Math.ceil(durations.length / 2) - 1], max: durations[durations.length - 1], n: durations.length } : null,
+    tokens: sumTokens(usage),
+  };
+}
+
+function groupModels(agents       )        {
+  const byModel = new Map               ();
+  for (const a of agents) if (a.model !== null) byModel.set(a.model, [...(byModel.get(a.model) ?? []), a]);
+  const sum = (list       , key        )                => {
+    const values = list.map((a) => a[key]).filter((v) => v !== null);
+    return values.length ? round2(values.reduce((x, y) => x + y, 0)) : null;
+  };
+  return [...byModel.entries()].sort((x, y) => (x[0] < y[0] ? -1 : 1)).map(([model, list]) => ({
+    model, agents: list.length, eventsPerMin: sum(list, 'eventsPerMin'), toolCalls: sum(list, 'toolCalls'), tokens: sumTokens(list.map((a) => a.tokens).filter(Boolean)),
+  }));
+}
+
+function pairsOf(agents       , holds                    , planOverlaps                         )        {
+  const out = new Map             ();
+  const add = (a        , b        , basis        , task               , tasks                 )       => {
+    out.set(`${a}|${b}|${basis}|${task ?? ''}|${(tasks ?? []).join(',')}`, { a, b, basis, task, tasks });
+  };
+  const sorted = [...agents].sort((x, y) => (x.agentKey < y.agentKey ? -1 : 1));
+  for (let i = 0; i < sorted.length; i += 1) {
+    for (let j = i + 1; j < sorted.length; j += 1) {
+      const [x, y] = [sorted[i], sorted[j]];
+      if (x.model !== null && x.model === y.model) add(x.agentKey, y.agentKey, 'same-model', null, null);
+      const [hx, hy] = [holds.get(x.agentKey) ?? [], holds.get(y.agentKey) ?? []];
+      for (const h of hx) {
+        if (hy.some((g) => g.slug === h.slug && g.task === h.task)) add(x.agentKey, y.agentKey, 'same-task', h.task, null);
+        for (const pair of planOverlaps(h.slug)) {
+          const other = pair.a === h.task ? pair.b : pair.b === h.task ? pair.a : null;
+          if (other !== null && hy.some((g) => g.slug === h.slug && g.task === other)) add(x.agentKey, y.agentKey, 'overlap', null, [h.task, other]);
+        }
+      }
+    }
+  }
+  return [...out.values()].sort((p, q) => (p.a < q.a ? -1 : p.a > q.a ? 1 : p.b < q.b ? -1 : p.b > q.b ? 1 : p.basis < q.basis ? -1 : p.basis > q.basis ? 1 : String(p.task ?? p.tasks).localeCompare(String(q.task ?? q.tasks))));
+}
+
+function computeStats({
+  env = process.env, cwd = process.cwd(), windowMin = DEFAULT_WINDOW, exec, alive, fsImpl = fs, platform, home, now = Date.now,
+}      = {})      {
+  const built = buildTree({ env, cwd, ...(exec ? { exec } : {}), ...(alive ? { alive } : {}), ...(fsImpl !== fs ? { fsImpl } : {}), ...(platform ? { platform } : {}), ...(home ? { home } : {}) });
+  if (!built.ok) return { ok: false, error: built.error };
+  const registry = registryById();
+  const roots = checkoutRoots({ cwd, exec, fsImpl });
+  const startMs = now() - windowMin * 60000;
+  const ranked = [...built.body.nodes].sort((a     , b     ) => (a.lastRecordAt === b.lastRecordAt ? 0 : a.lastRecordAt === null ? 1 : b.lastRecordAt === null ? -1 : a.lastRecordAt < b.lastRecordAt ? 1 : -1) || (a.agentKey < b.agentKey ? -1 : 1));
+  const chosen = ranked.slice(0, MAX_AGENTS);
+
+  const holds = new Map               ();
+  const agents = chosen.map((node     ) => {
+    const internal = built.internal.get(node.agentKey) ?? {};
+    holds.set(node.agentKey, internal.holds ?? []);
+    let numbers      = { eventsPerMin: null, toolCalls: null, toolErrors: null, toolDurationMs: null, tokens: null };
+    if (node.transcript.linked && internal.file) {
+      try {
+        const mod = READERS[registry[node.harness].reader]();
+        const header = mod.header({ file: internal.file, companion: internal.companion });
+        if (inCheckouts(header.cwd, roots, fsImpl)) {
+          const { events, clock } = readWindow(mod, node, internal);
+          numbers = summarize(events, clock, startMs, windowMin);
+        }
+      } catch { /* an unreadable transcript is unknown, not zero */ }
+    }
+    return { agentKey: node.agentKey, harness: node.harness, model: node.model, ...numbers, lastRecordAt: node.lastRecordAt };
+  });
+
+  const planCache = new Map               ();
+  const planOverlaps = (slug        )        => {
+    if (!planCache.has(slug)) {
+      let list        = [];
+      try { list = overlaps(loadPlan({ roots, slug, fsImpl }).graph); } catch { /* no readable plan: no overlap pairs */ }
+      planCache.set(slug, list);
+    }
+    return planCache.get(slug)         ;
+  };
+
+  return {
+    ok: true,
+    body: {
+      v: 1, projectKey: built.body.projectKey, windowMin, agents, models: groupModels(agents),
+      pairs: pairsOf(agents, holds, planOverlaps), notChecked: Math.max(0, ranked.length - MAX_AGENTS),
+    },
+  };
+}
+
+module.exports = { computeStats, DEFAULT_WINDOW, MAX_AGENTS };

package/src/runtime/verb-view.js

@@ -0,0 +1,267 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The shared view helper for verbs that answer in a brief or a full view (feature 137, IC-002, IC-003, IC-007,
+ * IC-008). A verb declares its own brief spec beside its handler; this module resolves the view a call asked for,
+ * projects a full answer onto a keep-path list, pages an ordered item list by cursor, builds next lines from
+ * validated parsed options, and serializes JSON compact off a terminal and indented on one.
+ *
+ * Like `cli-result.ts`, this module requires nothing from src/runtime/ at load time, so any handler can require
+ * it without a cycle. It requires nothing at all.
+ */
+
+                             
+
+/** One verb's brief view, declared beside its handler. */
+                     
+                        
+                           
+                                   
+                                    
+ 
+
+/** The ordering key of a pageable item: the creating event's time in milliseconds, then its event id. */
+                     
+                        
+                         
+ 
+
+/** A caller mistake in a view option: the handler reports it as a usage error (exit 2). */
+class ViewUsageError extends Error {}
+
+const VIEWS                    = ['brief', 'full'];
+
+function resolveView(raw         , defaultView      )       {
+  if (raw === undefined || raw === null) return defaultView;
+  if (typeof raw === 'string' && VIEWS.includes(raw)) return raw        ;
+  throw new ViewUsageError(`--view must be brief or full (got '${String(raw)}')`);
+}
+
+// ---------------------------------------------------------------------------------------------- keep paths
+
+                    
+               
+                                                            
+ 
+
+const KEEP_PATH = /^\$(?:\.[A-Za-z_][A-Za-z0-9_]*(?:\[\])?)+$/;
+const KEEP_SEGMENT = /\.([A-Za-z_][A-Za-z0-9_]*)(\[\])?/g;
+const keepTrees = new Map                  ();
+
+/** Builds the tree of a keep list; a malformed path, or one name used both as an array and not, throws. */
+function keepTree(keep                   )           {
+  const cacheKey = keep.join('\n');
+  const cached = keepTrees.get(cacheKey);
+  if (cached) return cached;
+  const root           = { all: false, children: new Map() };
+  for (const path of keep) {
+    if (!KEEP_PATH.test(path)) throw new Error(`malformed keep path '${path}'`);
+    let node = root;
+    for (const match of path.matchAll(KEEP_SEGMENT)) {
+      const [, name, brackets] = match;
+      const array = brackets !== undefined;
+      let child = node.children.get(name);
+      if (!child) {
+        child = { array, node: { all: false, children: new Map() } };
+        node.children.set(name, child);
+      } else if (child.array !== array) {
+        throw new Error(`keep path '${path}' uses '${name}' both as an array and as a single value`);
+      }
+      node = child.node;
+    }
+    node.all = true;
+  }
+  keepTrees.set(cacheKey, root);
+  return root;
+}
+
+function projectValue(value     , node          )      {
+  if (node.all) return value;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const out                          = {};
+  for (const key of Object.keys(value)) {
+    const child = node.children.get(key);
+    if (!child || value[key] === undefined) continue;
+    let part;
+    if (child.array) {
+      part = Array.isArray(value[key])
+        ? value[key].map((element     ) => (child.node.all ? element : (projectValue(element, child.node) ?? {})))
+        : undefined;
+    } else {
+      part = projectValue(value[key], child.node);
+      // An object none of whose kept paths exist is absent, not an empty shell.
+      if (part !== undefined && !child.node.all && Object.keys(part).length === 0) part = undefined;
+    }
+    if (part !== undefined) out[key] = part;
+  }
+  return out;
+}
+
+/**
+ * Projects a full answer onto keep paths: `$` then segments `.name` or `.name[]`; a path keeps the whole value at
+ * its last segment, `[]` maps over an array (order and length kept), an absent path is skipped, and output keys
+ * follow the full answer's key order.
+ */
+function projectBrief(full                         , keep                   )                          {
+  return projectValue(full, keepTree(keep)) ?? {};
+}
+
+// -------------------------------------------------------------------------------------------------- cursor
+
+const CURSOR = /^([0-9]{1,15}):([0-9]{8}T[0-9]{9}Z-[0-9a-hjkmnp-tv-z]{6})$/;
+const DIGITS = /^[0-9]+$/;
+
+function encodeCursor(key           )         {
+  if (!Number.isSafeInteger(key.atMs) || key.atMs < 0 || String(key.atMs).length > 15) {
+    throw new TypeError(`cursor time must be 0 to 15 digits of milliseconds (got ${key.atMs})`);
+  }
+  return `${key.atMs}:${key.event}`;
+}
+
+/** The key a cursor names, or null when the text is not a cursor of this format. */
+function decodeCursor(text         )                   {
+  const match = typeof text === 'string' ? CURSOR.exec(text) : null;
+  return match ? { atMs: Number(match[1]), event: match[2] } : null;
+}
+
+/** True when key `a` orders after key `b`: later time, or the same time and a greater event id. */
+function keyAfter(a           , b           )          {
+  return a.atMs > b.atMs || (a.atMs === b.atMs && a.event > b.event);
+}
+
+/**
+ * Pages an item list already in ascending key order. Items at or before the cursor are dropped, then the first
+ * `limit` are kept. `nextCursor` is the last shown item's key when items remain after it, else null.
+ */
+function pageItems   (items              , opts   
+                                                                                          
+                          
+ )                                                           {
+  let limit = opts.defaultLimit;
+  if (opts.limit !== undefined) {
+    const text = String(opts.limit);
+    if (!DIGITS.test(text) || Number(text) < 1) {
+      throw new ViewUsageError(`--limit must be a whole number of 1 or more (at most ${opts.maxLimit} are returned)`);
+    }
+    limit = Math.min(opts.maxLimit, Number(text));
+  }
+  let rest = items;
+  if (opts.cursor !== undefined) {
+    const after = decodeCursor(opts.cursor);
+    if (after === null) throw new ViewUsageError('--cursor must be the nextCursor of an earlier list');
+    rest = items.filter((item) => keyAfter(opts.key(item), after));
+  }
+  const page = limit === null ? rest.slice() : rest.slice(0, limit);
+  const more = page.length < rest.length;
+  return {
+    items: page,
+    shown: page.length,
+    nextCursor: more && page.length > 0 ? encodeCursor(opts.key(page[page.length - 1])) : null,
+  };
+}
+
+// ----------------------------------------------------------------------------------------------- next lines
+
+const SAFE_VALUE = /^[A-Za-z0-9._:@,/-]{1,200}$/;
+const LABELS = { page: 'Next page', 'page-full': 'Full view of this page', full: 'Full view' }         ;
+const VIEW_FLAGS                    = ['cursor', 'limit', 'view'];
+
+function kebab(name        )         {
+  return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+/**
+ * `doflow-run <verb>[ --action <action>]( --<flag>[ <value>])*`, flags in the order of `carried`. A value renders
+ * only when it is `true` (bare flag) or a short safe token (or finite number); any other value renders as the
+ * placeholder `<flag>`, so free text is never carried. `false`, null and undefined are omitted.
+ */
+function commandLine(verb        , action                    , carried                         )         {
+  const parts = ['doflow-run', verb];
+  if (action !== undefined) parts.push('--action', action);
+  for (const [name, value] of Object.entries(carried)) {
+    if (value === undefined || value === null || value === false) continue;
+    const flag = kebab(name);
+    parts.push(`--${flag}`);
+    if (value === true) continue;
+    const text = typeof value === 'number' && Number.isFinite(value) ? String(value) : value;
+    parts.push(typeof text === 'string' && SAFE_VALUE.test(text) ? text : `<${flag}>`);
+  }
+  return parts.join(' ');
+}
+
+/**
+ * The next line of one kind: `page` (the page after this one), `page-full` (this page in the full view, carrying
+ * the input cursor and `--limit <shown>`) or `full` (the verb's whole, bounded, full answer). The options echoed
+ * are those the spec's `carry` names, in that order, then `--cursor`, `--limit`, `--view` (a `page` line names
+ * `--view full` only when the caller's `view` is `full`). Returns no line when
+ * the kind has nothing to point at (`page` without a nextCursor, `page-full` with nothing shown). In a JSON answer
+ * (`json: true`) the `page-full` and `full` lines end with `--json`, so the command as written prints the full
+ * payload; a text answer's lines carry no `--json`.
+ */
+function viewLines(kind                               , ctx   
+                                                                            
+                                                                          
+ )           {
+  const args                          = {};
+  for (const name of ctx.spec.carry) {
+    if (!VIEW_FLAGS.includes(name)) args[name] = ctx.carried[name];
+  }
+  if (kind === 'page') {
+    if (!ctx.nextCursor) return [];
+    args.cursor = ctx.nextCursor;
+    args.limit = ctx.spec.carry.includes('limit') ? ctx.carried.limit : undefined;
+    // A walk stays in the view it started in: brief is the default, so only the full view is named.
+    if (ctx.view === 'full') args.view = 'full';
+  } else if (kind === 'page-full') {
+    if (!ctx.shown || ctx.shown < 1) return [];
+    args.cursor = ctx.cursor ?? undefined;
+    args.limit = ctx.shown;
+    args.view = 'full';
+  } else {
+    args.view = 'full';
+  }
+  const asJson = ctx.json === true && kind !== 'page' ? ' --json' : '';
+  return [`${LABELS[kind]}: ${commandLine(ctx.spec.verb, ctx.spec.action, args)}${asJson}`];
+}
+
+/**
+ * Adds the envelope to an answer body: `view` first; `shown` and `nextCursor` directly after `count` when the body
+ * has one, else after `view`; `next` last (replacing a `next` the body already carries).
+ */
+function withEnvelope(body                         , env   
+                                                                                   
+ )                          {
+  const paging                          = {};
+  if (env.shown !== undefined) paging.shown = env.shown;
+  if (env.nextCursor !== undefined) paging.nextCursor = env.nextCursor;
+  const out                          = { view: env.view };
+  const hasCount = 'count' in body;
+  if (!hasCount) Object.assign(out, paging);
+  for (const [key, value] of Object.entries(body)) {
+    if (key === 'view' || key === 'shown' || key === 'nextCursor' || key === 'next') continue;
+    out[key] = value;
+    if (key === 'count') Object.assign(out, paging);
+  }
+  const next = env.next ?? (body.next                                 );
+  if (next !== undefined) out.next = next;
+  return out;
+}
+
+// --------------------------------------------------------------------------------------------- serialization
+
+/** Compact JSON off a terminal, two-space indented on one; `isTTY` defaults to `process.stdout.isTTY === true`. */
+function serializeJson(value         , opts                      = {})         {
+  const isTTY = opts.isTTY ?? process.stdout.isTTY === true;
+  return isTTY === true ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+
+function emitJson(value         , opts                      = {})       {
+  console.log(serializeJson(value, opts));
+}
+
+module.exports = {
+  ViewUsageError, resolveView, projectBrief, pageItems, encodeCursor, decodeCursor,
+  commandLine, viewLines, withEnvelope, serializeJson, emitJson,
+};