@akanjs/devkit 3.1.1-rc.9 → 3.1.1

package/workflow/source.ts

@@ -41,6 +41,7 @@ export const moduleSourcePaths = (moduleName: string) => {
     abstract: `lib/${moduleName}/${moduleName}.abstract.md`,
     constant: `lib/${moduleName}/${moduleName}.constant.ts`,
     dictionary: `lib/${moduleName}/${moduleName}.dictionary.ts`,
+    document: `lib/${moduleName}/${moduleName}.document.ts`,
     service: `lib/${moduleName}/${moduleName}.service.ts`,
     signal: `lib/${moduleName}/${moduleName}.signal.ts`,
     store: `lib/${moduleName}/${moduleName}.store.ts`,
@@ -57,14 +58,12 @@ export const generatedFilesForSync = (sys: Sys, reason = "Generated files may ch
 
 export const validationCommandsForTarget = (target: string) =>
   [
-    { command: `akan sync ${target}`, reason: "Refresh generated Akan files from source conventions." },
-    { command: `akan lint ${target}`, reason: "Validate formatting, imports, and static lint rules." },
+    { command: `akan verify ${target}`, reason: "Sync, lint, typecheck and build the target in one run." },
   ] satisfies PrimitiveValidationCommand[];
 
 export const nextActionsForTarget = (target: string) =>
   [
-    { command: `akan sync ${target}`, reason: "Refresh generated Akan files after source changes." },
-    { command: `akan lint ${target}`, reason: "Validate the target after generated files are refreshed." },
+    { command: `akan verify ${target}`, reason: "Refresh generated files and validate the target in one run." },
   ] satisfies PrimitiveNextAction[];
 
 export const createPrimitiveWriteReport = ({
@@ -189,20 +188,52 @@ export const normalizeFieldType = (typeName: string) => {
   return normalizedTypes[typeName.toLowerCase()] ?? typeName;
 };
 
+//? Biome's organizeImports order: case-insensitive, an uppercase name before its lowercase twin.
+const importOrder = (a: string, b: string) => {
+  const [lowerA, lowerB] = [a.toLowerCase(), b.toLowerCase()];
+  if (lowerA !== lowerB) return lowerA < lowerB ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
 export const ensureNamedImport = (content: string, moduleSpecifier: string, name: string) => {
   const source = sourceFileFor("source.ts", content);
-  const namedImport = findNamedImport(source, moduleSpecifier);
-  if (namedImport) {
-    if (namedImport.names.includes(name)) return content;
-    const nextNames = [...namedImport.names, name].sort();
-    return spliceText(
-      content,
-      namedImport.namedBindingsStart,
-      namedImport.namedBindingsEnd,
-      `{ ${nextNames.join(", ")} }`,
+  const namedImport = findNamedImport(source, moduleSpecifier, { valueOnly: true });
+  if (!namedImport) return ensureImportDeclaration(content, moduleSpecifier, `{ ${name} }`);
+  if (namedImport.names.includes(name)) return content;
+  const nextElements = [...namedImport.elements, { name, text: name }].sort((a, b) => importOrder(a.name, b.name));
+  return spliceText(
+    content,
+    namedImport.namedBindingsStart,
+    namedImport.namedBindingsEnd,
+    `{ ${nextElements.map((element) => element.text).join(", ")} }`,
+  );
+};
+
+export const ensureImportDeclaration = (content: string, moduleSpecifier: string, clause: string) => {
+  const line = `import ${clause} from "${moduleSpecifier}";`;
+  if (content.includes(line)) return content;
+  const source = sourceFileFor("source.ts", content);
+  const imports = source.statements
+    .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
+    .flatMap((statement) =>
+      ts.isStringLiteral(statement.moduleSpecifier)
+        ? [{ specifier: statement.moduleSpecifier.text, start: statement.getStart(source), end: statement.getEnd() }]
+        : [],
     );
+  const isRelative = (specifier: string) => specifier.startsWith(".");
+  const peers = imports.filter((entry) => isRelative(entry.specifier) === isRelative(moduleSpecifier));
+  const before = peers.find((entry) => importOrder(entry.specifier, moduleSpecifier) > 0);
+  if (before) {
+    const insertAt = lineStartAt(content, before.start);
+    return spliceText(content, insertAt, insertAt, `${line}\n`);
   }
-  return `import { ${name} } from "${moduleSpecifier}";\n${content}`;
+  const after = peers.at(-1) ?? (isRelative(moduleSpecifier) ? imports.at(-1) : undefined);
+  if (after) {
+    const insertAt = lineEndAt(content, after.end);
+    return spliceText(content, insertAt, insertAt, peers.length ? `${line}\n` : `\n${line}\n`);
+  }
+  const insertAt = imports[0] ? lineStartAt(content, imports[0].start) : 0;
+  return spliceText(content, insertAt, insertAt, `${line}\n\n`);
 };
 
 export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
@@ -382,6 +413,7 @@ interface ArrayInsertionLocator {
 
 interface NamedImportLocator {
   names: string[];
+  elements: { name: string; text: string }[];
   namedBindingsStart: number;
   namedBindingsEnd: number;
 }
@@ -499,16 +531,23 @@ const dictionaryChainOrderValid = (chainMethods: readonly string[]) => {
   return true;
 };
 
-const findDictionaryModelObject = (source: ts.SourceFile, moduleClassName: string): DictionaryModelLocator | null => {
+const findDictionaryModelObject = (source: ts.SourceFile, moduleClassName: string) =>
+  findDictionaryStageObject(source, "model", moduleClassName);
+
+const findDictionaryStageObject = (
+  source: ts.SourceFile,
+  stage: string,
+  typeName: string,
+): DictionaryModelLocator | null => {
   let locator: DictionaryModelLocator | null = null;
   const visit = (node: ts.Node) => {
     if (locator) return;
-    if (!ts.isCallExpression(node) || callExpressionName(node) !== "model") {
+    if (!ts.isCallExpression(node) || callExpressionName(node) !== stage) {
       ts.forEachChild(node, visit);
       return;
     }
     const typeArgument = node.typeArguments?.[0];
-    if (!typeArgument || typeArgument.getText(source) !== moduleClassName) {
+    if (!typeArgument || typeArgument.getText(source) !== typeName) {
       ts.forEachChild(node, visit);
       return;
     }
@@ -556,14 +595,20 @@ const findLightProjectionArray = (source: ts.SourceFile, moduleClassName: string
   return locator;
 };
 
-const findNamedImport = (source: ts.SourceFile, moduleSpecifier: string): NamedImportLocator | null => {
+const findNamedImport = (
+  source: ts.SourceFile,
+  moduleSpecifier: string,
+  { valueOnly = false }: { valueOnly?: boolean } = {},
+): NamedImportLocator | null => {
   for (const statement of source.statements) {
     if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
     if (statement.moduleSpecifier.text !== moduleSpecifier) continue;
+    if (valueOnly && statement.importClause?.isTypeOnly) continue;
     const namedBindings = statement.importClause?.namedBindings;
     if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
     return {
       names: namedBindings.elements.map((element) => element.name.text),
+      elements: namedBindings.elements.map((element) => ({ name: element.name.text, text: element.getText(source) })),
       namedBindingsStart: namedBindings.getStart(source),
       namedBindingsEnd: namedBindings.getEnd(),
     };
@@ -816,6 +861,27 @@ export const hasDictionaryModelField = (content: string, moduleClassName: string
   return findDictionaryModelObject(source, moduleClassName)?.fields.some((field) => field.name === fieldName) ?? false;
 };
 
+export const hasDictionaryEndpointEntry = (content: string, moduleClassName: string, entryName: string) => {
+  const source = sourceFileFor("dictionary.ts", content);
+  return (
+    findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`)?.fields.some(
+      (field) => field.name === entryName,
+    ) ?? false
+  );
+};
+
+export const insertDictionaryEndpointEntry = (
+  content: string,
+  moduleClassName: string,
+  entryName: string,
+  entryText: string,
+) => {
+  const source = sourceFileFor("dictionary.ts", content);
+  const locator = findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`);
+  if (!locator) return null;
+  return insertOrderedFieldLine(content, locator, entryName, entryText, { fieldIndent: "    ", closingIndent: "  " });
+};
+
 export const ensureConstantTypeImport = (content: string, constantPath: string, typeName: string) => {
   if (new RegExp(`import type \\{[^}]*\\b${typeName}\\b[^}]*\\} from "${constantPath}";`).test(content)) return content;
   const importPattern = new RegExp(`import type \\{ ([^}]+) \\} from "${constantPath}";`);
@@ -830,17 +896,38 @@ export const ensureConstantTypeImport = (content: string, constantPath: string,
   return `import type { ${typeName} } from "${constantPath}";\n${content}`;
 };
 
+const dictionaryChainOf = (node: ts.Node): ts.CallExpression | undefined => {
+  if (
+    ts.isCallExpression(node) &&
+    outermostFluentCall(node) === node &&
+    protectedDictionaryChainOrder.some((method) => chainMethodsForCall(node).includes(method))
+  )
+    return node;
+  return ts.forEachChild(node, dictionaryChainOf);
+};
+
+const chainMethodNames = (call: ts.Expression): ts.Identifier[] => {
+  if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression)) return [];
+  const name = call.expression.name;
+  return [...chainMethodNames(call.expression.expression), ...(ts.isIdentifier(name) ? [name] : [])];
+};
+
+//* Located on the parsed chain, never by text search: the sample dictionary's header comment mentions `.error()`.
 export const insertDictionaryEnum = (content: string, enumClassName: string, enumName: string, values: string[]) => {
   if (content.includes(`.enum<${enumClassName}>("${enumName}"`)) return content;
+  const source = sourceFileFor("dictionary.ts", content);
+  if (hasParseDiagnostics(source)) return null;
+  const chain = dictionaryChainOf(source);
+  if (!chain) return null;
   const enumBlock = `  .enum<${enumClassName}>("${enumName}", (t) => ({\n${values
     .map((value) => `    ${value}: t([${JSON.stringify(titleize(value))}, ${JSON.stringify(titleize(value))}]),`)
     .join("\n")}\n  }))\n`;
-  const chainEndIndex = content.lastIndexOf(";");
-  const insertBeforeIndex = [content.indexOf(".error("), content.indexOf(".translate("), chainEndIndex]
-    .filter((index) => index >= 0)
-    .sort((a, b) => a - b)[0];
-  if (insertBeforeIndex === undefined) return null;
-  return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
+  const later = chainMethodNames(chain).find((name) => name.text === "error" || name.text === "translate");
+  if (!later) return spliceText(content, chain.getEnd(), chain.getEnd(), `\n${enumBlock.trimEnd()}`);
+  const dot = content.lastIndexOf(".", later.getStart(source));
+  const lineStart = lineStartAt(content, dot);
+  if (content.slice(lineStart, dot).trim() === "") return spliceText(content, lineStart, lineStart, enumBlock);
+  return spliceText(content, dot, dot, `\n${enumBlock}`);
 };
 
 export const parseValues = (value: string | null) =>
@@ -883,6 +970,19 @@ export const hasClassMethod = (content: string, className: string, methodName: s
   );
 };
 
+export const classMethodParameters = (content: string, className: string, methodName: string) => {
+  const source = sourceFileFor("service.ts", content);
+  const method = findClassDeclaration(source, className)?.members.find(
+    (member): member is ts.MethodDeclaration => ts.isMethodDeclaration(member) && nodeName(member.name) === methodName,
+  );
+  return (
+    method?.parameters.map((parameter) => ({
+      name: nodeName(parameter.name),
+      optional: !!parameter.questionToken || !!parameter.initializer || !!parameter.dotDotDotToken,
+    })) ?? null
+  );
+};
+
 export const insertClassMethod = (content: string, className: string, methodBlock: string): string | null => {
   const source = sourceFileFor("service.ts", content);
   const node = findClassDeclaration(source, className);
@@ -976,3 +1076,30 @@ export const insertSignalFactoryEntry = (
   if (withEntry === content) return null;
   return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
 };
+
+export const appendTopLevelTestCases = (
+  content: string,
+  describeTitle: string,
+  render: (itName: string, indent: string) => string[],
+) => {
+  const bunImport = findNamedImport(sourceFileFor("test.ts", content), "bun:test", { valueOnly: true });
+  const itName = !bunImport?.names.includes("it") && bunImport?.names.includes("test") ? "test" : "it";
+  const imported = ensureNamedImport(content, "bun:test", itName);
+  const source = sourceFileFor("test.ts", imported);
+  const body = source.statements.flatMap((statement) => {
+    if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression)) return [];
+    if (expressionName(statement.expression.expression) !== "describe") return [];
+    const callback = factoryArrowOf(statement.expression);
+    return callback && ts.isBlock(callback.body) ? [callback.body] : [];
+  })[0];
+  if (!body) {
+    const block = [`describe(${JSON.stringify(describeTitle)}, () => {`, ...render(itName, "  "), "});", ""];
+    return `${ensureNamedImport(imported, "bun:test", "describe").trimEnd()}\n\n${block.join("\n")}`;
+  }
+  const firstStatement = body.statements[0];
+  const indent = firstStatement
+    ? lineIndentAt(imported, firstStatement.getStart(source))
+    : `${lineIndentAt(imported, body.getStart(source))}  `;
+  const insertAt = lineStartAt(imported, body.getEnd() - 1);
+  return spliceText(imported, insertAt, insertAt, `${render(itName, indent).join("\n")}\n`);
+};

package/workflow/types.ts

@@ -8,7 +8,7 @@ export type WorkflowFormat = "markdown" | "json";
 export type WorkflowPlanInputs = Record<string, string | null>;
 export type PrimitiveFormat = "markdown" | "json";
 export type UiSurface = "view" | "unit" | "template";
-export type WorkflowValidationKind = "sync" | "lint" | "typecheck" | "doctor" | "custom";
+export type WorkflowValidationKind = "verify" | "sync" | "lint" | "typecheck" | "doctor" | "custom";
 export type WorkflowFailureScope = "workspace-config" | "environment" | "source-change" | "unknown";
 export type WorkflowValidationStatus = "passed" | "failed" | "unknown";
 export interface WorkflowValidationSummary {
@@ -49,6 +49,14 @@ export interface AddEnumFieldInput extends PrimitiveTargetInput {
 
 export interface AddMutationInput extends PrimitiveTargetInput {
   mutation: string | null;
+  guards?: string[] | null;
+  withCalls?: string[] | null;
+  afterCalls?: string[] | null;
+}
+
+export interface CreateInteractionInput {
+  app: string | null;
+  interaction: string | null;
 }
 
 export interface AddSliceInput extends PrimitiveTargetInput {
@@ -94,6 +102,7 @@ export interface WorkflowSpec {
   predictedChanges: readonly WorkflowPredictedChange[];
   validation: readonly WorkflowValidation[];
   completionCriteria: readonly string[];
+  replacesRules?: readonly string[];
 }
 
 export interface WorkflowDiagnostic {
@@ -382,6 +391,13 @@ export interface PrimitiveWriteReport {
   nextActions: PrimitiveNextAction[];
 }
 
+export interface ScaffoldFile {
+  path: string;
+  content: string;
+  action: "create" | "modify";
+  reason: string;
+}
+
 export type PrimitiveFileMap = Record<string, { filename: string; content: string }>;
 
 export interface WorkflowApplyReport {
@@ -482,4 +498,5 @@ export interface WorkflowPrimitiveOperations {
   addEnumField: (input: AddEnumFieldInput) => Promise<PrimitiveWriteReport>;
   addMutation: (input: AddMutationInput) => Promise<PrimitiveWriteReport>;
   addSlice: (input: AddSliceInput) => Promise<PrimitiveWriteReport>;
+  createInteraction: (input: CreateInteractionInput) => Promise<PrimitiveWriteReport>;
 }

package/workspaceLayout.ts

@@ -7,6 +7,7 @@ export const appRootAllowedFiles = new Set([
   "AGENTS.md",
   "CLAUDE.md",
   "akan.app.json",
+  "akan.baseline.json",
   "akan.config.ts",
   "client.ts",
   "main.ts",
@@ -38,6 +39,7 @@ export const libRootAllowedFiles = new Set([
   "AGENTS.md",
   "CLAUDE.md",
   "README.md",
+  "akan.baseline.json",
   "akan.config.ts",
   "akan.lib.json",
   "client.ts",

package/writePath.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import { WritePath } from "./writePath";
+
+const pathIn = (body: string, enters?: (fn: ts.SignatureDeclaration) => boolean) => {
+  const sourceFile = ts.createSourceFile("a.ts", `async function run() {\n${body}\n}`, ts.ScriptTarget.Latest, true);
+  const fn = sourceFile.statements[0];
+  if (!fn || !ts.isFunctionDeclaration(fn) || !fn.body) throw new Error("fixture has no function body");
+  const isWrite = (call: ts.CallExpression) => /^write/.test(call.expression.getText(sourceFile));
+  const path = new WritePath(isWrite, { enters });
+  const calls = path.along(fn.body);
+  return { labels: calls.map((call) => path.labelOf(call, sourceFile)), count: path.countOf(calls) };
+};
+const writesIn = (body: string, enters?: (fn: ts.SignatureDeclaration) => boolean) =>
+  pathIn(body, enters).labels.map((label) => label.replace(" (per item)", ""));
+
+describe("WritePath", () => {
+  test("adds up writes in sequence, nested callbacks and logical operands included", () => {
+    expect(
+      writesIn("await writeA();\nawait Promise.all(ids.map((id) => writeB(id)));\nok && (await writeC());"),
+    ).toEqual(["writeA", "writeB", "writeC"]);
+  });
+
+  test("counts only the busiest of exclusive branches", () => {
+    expect(writesIn("if (x) await writeA();\nelse await writeB();")).toEqual(["writeA"]);
+    expect(writesIn("await (x ? writeA() : Promise.all([writeB(), writeC()]));")).toEqual(["writeB", "writeC"]);
+    expect(
+      writesIn(
+        "switch (x) {\n  case 1:\n    await writeA();\n    break;\n  default:\n    await writeB();\n    await writeC();\n}",
+      ),
+    ).toEqual(["writeB", "writeC"]);
+  });
+
+  test("reads an if that returns as the else of the statements after it", () => {
+    expect(
+      writesIn("await writeA();\nif (x) {\n  await writeB();\n  return;\n}\nawait writeC();\nawait writeD();"),
+    ).toEqual(["writeA", "writeC", "writeD"]);
+    expect(writesIn("if (x) await writeB();\nawait writeC();")).toEqual(["writeB", "writeC"]);
+  });
+
+  test("reads every branch that returns as exclusive of the statements after it, however it is nested", () => {
+    const countIn = (body: string) => pathIn(body).count;
+    expect(
+      countIn(
+        "if (x) {\n  await writeA();\n  return;\n} else if (y) {\n  await writeB();\n  return;\n}\nawait writeC();",
+      ),
+    ).toBe(1);
+    expect(countIn('switch (x) {\n  case "a":\n    await writeA();\n    return;\n}\nawait writeC();')).toBe(1);
+    expect(countIn("if (x) {\n  if (y) {\n    await writeA();\n    return;\n  }\n}\nawait writeC();")).toBe(1);
+    expect(writesIn("try {\n  await writeA();\n  return;\n} catch {\n  await writeB();\n}")).toEqual([
+      "writeA",
+      "writeB",
+    ]);
+  });
+
+  test("runs a switch clause without break on into the next one", () => {
+    expect(
+      writesIn("switch (x) {\n  case 1:\n    await writeA();\n  case 2:\n    await writeB();\n    break;\n}"),
+    ).toEqual(["writeA", "writeB"]);
+  });
+
+  test("counts a write in a loop or a per-element callback as two, but not the list it loops over", () => {
+    expect(pathIn("for (const id of ids) await writeA(id);")).toEqual({ labels: ["writeA (per item)"], count: 2 });
+    expect(pathIn("for (const id of await writeA()) read(id);")).toEqual({ labels: ["writeA"], count: 1 });
+    expect(pathIn("while (await more()) await writeA();")).toEqual({ labels: ["writeA (per item)"], count: 2 });
+    expect(pathIn("await Promise.all(ids.map((id) => writeA(id)));")).toEqual({
+      labels: ["writeA (per item)"],
+      count: 2,
+    });
+    expect(pathIn("await read().then(() => writeA());")).toEqual({ labels: ["writeA"], count: 1 });
+    expect(pathIn("for (let i = 0; i < ids.length; i++) await writeA(ids[i]);")).toEqual({
+      labels: ["writeA (per item)"],
+      count: 2,
+    });
+    expect(pathIn("while (queue.length) await writeA(queue.shift());")).toEqual({
+      labels: ["writeA (per item)"],
+      count: 2,
+    });
+  });
+
+  test("counts a retry or a poll as one write, and a loop that returns on its write as one", () => {
+    expect(pathIn("for (let i = 0; i < 3; i++) {\n  try {\n    await writeA();\n    return;\n  } catch {}\n}")).toEqual(
+      {
+        labels: ["writeA"],
+        count: 1,
+      },
+    );
+    expect(pathIn("let ok = false;\nwhile (!ok) ok = await writeA();")).toEqual({ labels: ["writeA"], count: 1 });
+    expect(pathIn("for (const id of ids)\n  if (id) {\n    await writeA(id);\n    return;\n  }")).toEqual({
+      labels: ["writeA"],
+      count: 1,
+    });
+  });
+
+  test("weighs a branch writing per item above one writing once", () => {
+    expect(pathIn("if (x) await writeA();\nelse for (const id of ids) await writeB(id);")).toEqual({
+      labels: ["writeB (per item)"],
+      count: 2,
+    });
+  });
+
+  test("leaves out a nested function the caller does not enter", () => {
+    const body = "await writeA();\nids.map((id) => writeB(id));\nsetTimeout(() => writeC(), 0);";
+    const entersMapOnly = (fn: ts.SignatureDeclaration) =>
+      ts.isCallExpression(fn.parent) && fn.parent.expression.getText().endsWith(".map");
+
+    expect(writesIn(body, entersMapOnly)).toEqual(["writeA", "writeB"]);
+  });
+});

package/writePath.ts

@@ -0,0 +1,219 @@
+import ts from "typescript";
+
+interface Flow {
+  through: ts.CallExpression[] | null;
+  exit: ts.CallExpression[] | null;
+  jump: ts.CallExpression[] | null;
+}
+
+//? Exclusive branches never run together, so only the busiest one counts, a branch that returns included; a write in
+//? a loop over items or a per-element callback runs once per item, so it counts as two.
+export class WritePath {
+  static readonly #perElement = new Set([
+    "map",
+    "flatMap",
+    "forEach",
+    "filter",
+    "reduce",
+    "some",
+    "every",
+    "find",
+    "findIndex",
+  ]);
+  readonly #matches: (call: ts.CallExpression) => boolean;
+  readonly #enters: (fn: ts.SignatureDeclaration) => boolean;
+  readonly #repeated = new WeakSet<ts.CallExpression>();
+
+  constructor(
+    matches: (call: ts.CallExpression) => boolean,
+    { enters = () => true }: { enters?: (fn: ts.SignatureDeclaration) => boolean } = {},
+  ) {
+    this.#matches = matches;
+    this.#enters = enters;
+  }
+
+  along(node: ts.Node): ts.CallExpression[] {
+    if (ts.isFunctionLike(node) && !this.#enters(node)) return [];
+    if (WritePath.isPerElementCallback(node)) return this.#repeat(this.#children(node));
+    if (WritePath.#isFlowStatement(node)) return this.#busiestOf(this.#flowOf(node));
+    if (ts.isConditionalExpression(node))
+      return [...this.along(node.condition), ...this.#busier(this.along(node.whenTrue), this.along(node.whenFalse))];
+    const own = ts.isCallExpression(node) && this.#matches(node) ? [node] : [];
+    return [...own, ...this.#children(node)];
+  }
+
+  isRepeated(call: ts.CallExpression) {
+    return this.#repeated.has(call);
+  }
+
+  countOf(calls: ts.CallExpression[]) {
+    return calls.reduce((count, call) => count + (this.isRepeated(call) ? 2 : 1), 0);
+  }
+
+  labelOf(call: ts.CallExpression, sourceFile: ts.SourceFile) {
+    const callee = call.expression.getText(sourceFile);
+    return this.isRepeated(call) ? `${callee} (per item)` : callee;
+  }
+
+  static isPerElementCallback(node: ts.Node) {
+    const call = node.parent;
+    return (
+      (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+      !!call &&
+      ts.isCallExpression(call) &&
+      call.arguments.some((arg) => arg === node) &&
+      ts.isPropertyAccessExpression(call.expression) &&
+      WritePath.#perElement.has(call.expression.name.text)
+    );
+  }
+
+  #children(node: ts.Node) {
+    const children: ts.Node[] = [];
+    ts.forEachChild(node, (child) => {
+      children.push(child);
+    });
+    return children.flatMap((child) => this.along(child));
+  }
+
+  #repeat(calls: ts.CallExpression[]) {
+    for (const call of calls) this.#repeated.add(call);
+    return calls;
+  }
+
+  #flowOf(node: ts.Statement): Flow {
+    if (ts.isBlock(node)) return this.#sequenceOf(node.statements);
+    if (ts.isReturnStatement(node) || ts.isThrowStatement(node))
+      return { through: null, exit: node.expression ? this.along(node.expression) : [], jump: null };
+    if (ts.isBreakStatement(node) || ts.isContinueStatement(node)) return { through: null, exit: null, jump: [] };
+    if (ts.isLabeledStatement(node)) return this.#flowOf(node.statement);
+    if (ts.isIfStatement(node))
+      return WritePath.#prefixed(
+        this.along(node.expression),
+        this.#merged(
+          this.#flowOf(node.thenStatement),
+          node.elseStatement ? this.#flowOf(node.elseStatement) : WritePath.#onward([]),
+        ),
+      );
+    if (ts.isSwitchStatement(node)) return WritePath.#prefixed(this.along(node.expression), this.#switchOf(node));
+    if (ts.isTryStatement(node)) return this.#tryOf(node);
+    if (ts.isForOfStatement(node) || ts.isForInStatement(node))
+      return this.#loopOf(this.along(node.expression), [], node.statement, true);
+    if (ts.isForStatement(node))
+      return this.#loopOf(
+        node.initializer ? this.along(node.initializer) : [],
+        [node.condition, node.incrementor].flatMap((part) => (part ? this.along(part) : [])),
+        node.statement,
+        WritePath.#walksItems(node.condition),
+      );
+    if (ts.isWhileStatement(node) || ts.isDoStatement(node))
+      return this.#loopOf([], this.along(node.expression), node.statement, WritePath.#walksItems(node.expression));
+    return WritePath.#onward(this.along(node));
+  }
+
+  #sequenceOf(statements: readonly ts.Statement[]): Flow {
+    let through: ts.CallExpression[] | null = [];
+    let exit: ts.CallExpression[] | null = null;
+    let jump: ts.CallExpression[] | null = null;
+    for (const statement of statements) {
+      if (through === null) break;
+      const flow = this.#flowOf(statement);
+      if (flow.exit) exit = this.#busierOf(exit, [...through, ...flow.exit]);
+      if (flow.jump) jump = this.#busierOf(jump, [...through, ...flow.jump]);
+      through = flow.through && [...through, ...flow.through];
+    }
+    return { through, exit, jump };
+  }
+
+  //? A clause without `break` runs on into the next one; `break` leaves the switch and goes on after it.
+  #switchOf(node: ts.SwitchStatement): Flow {
+    const hasDefault = node.caseBlock.clauses.some(ts.isDefaultClause);
+    let flow: Flow = { through: hasDefault ? null : [], exit: null, jump: null };
+    let fallen: ts.CallExpression[] | null = null;
+    for (const clause of node.caseBlock.clauses) {
+      const entry = fallen && this.countOf(fallen) > 0 ? fallen : [];
+      const own = WritePath.#prefixed(entry, this.#sequenceOf(clause.statements));
+      flow = this.#merged(flow, { through: own.jump, exit: own.exit, jump: null });
+      fallen = own.through;
+    }
+    return this.#merged(flow, { through: fallen, exit: null, jump: null });
+  }
+
+  //? A catch runs after whatever the try sent before it threw, so both count; a finally follows every path.
+  #tryOf(node: ts.TryStatement): Flow {
+    const tried = this.#flowOf(node.tryBlock);
+    const sent = this.#busiestOf(tried);
+    const caught = node.catchClause
+      ? WritePath.#prefixed(sent, this.#flowOf(node.catchClause.block))
+      : { through: null, exit: sent, jump: null };
+    const flow = this.#merged(tried, caught);
+    if (!node.finallyBlock) return flow;
+    const after = this.#busiestOf(this.#flowOf(node.finallyBlock));
+    return {
+      through: flow.through && [...flow.through, ...after],
+      exit: flow.exit && [...flow.exit, ...after],
+      jump: flow.jump && [...flow.jump, ...after],
+    };
+  }
+
+  //? An iteration that leaves the function sends its writes once; one that goes on repeats them for a loop over items.
+  #loopOf(once: ts.CallExpression[], everyTurn: ts.CallExpression[], body: ts.Statement, isPerItem: boolean): Flow {
+    const flow = this.#flowOf(body);
+    const turn = [...everyTurn, ...(this.#busierOf(flow.through, flow.jump) ?? [])];
+    const repeated = isPerItem ? this.#repeat(turn) : turn;
+    return { through: [...once, ...repeated], exit: flow.exit && [...once, ...flow.exit], jump: null };
+  }
+
+  #merged(a: Flow, b: Flow): Flow {
+    return {
+      through: this.#busierOf(a.through, b.through),
+      exit: this.#busierOf(a.exit, b.exit),
+      jump: this.#busierOf(a.jump, b.jump),
+    };
+  }
+
+  #busiestOf({ through, exit, jump }: Flow) {
+    return this.#busierOf(this.#busierOf(through, exit), jump) ?? [];
+  }
+
+  #busierOf(a: ts.CallExpression[] | null, b: ts.CallExpression[] | null) {
+    return a && b ? this.#busier(a, b) : (a ?? b);
+  }
+
+  static #onward(calls: ts.CallExpression[]): Flow {
+    return { through: calls, exit: null, jump: null };
+  }
+
+  static #prefixed(calls: ts.CallExpression[], { through, exit, jump }: Flow): Flow {
+    return {
+      through: through && [...calls, ...through],
+      exit: exit && [...calls, ...exit],
+      jump: jump && [...calls, ...jump],
+    };
+  }
+
+  static #isFlowStatement(node: ts.Node): node is ts.Statement {
+    return (
+      ts.isBlock(node) ||
+      ts.isIfStatement(node) ||
+      ts.isSwitchStatement(node) ||
+      ts.isTryStatement(node) ||
+      ts.isLabeledStatement(node) ||
+      ts.isReturnStatement(node) ||
+      ts.isThrowStatement(node) ||
+      ts.isBreakStatement(node) ||
+      ts.isContinueStatement(node) ||
+      ts.isIterationStatement(node, false)
+    );
+  }
+
+  //? A loop bound by `xs.length` or asking a call for more (`while (await next())`) walks items; a bound it counts
+  //? itself (`i < 3`, `!ok`) is a retry or a poll, which sends one write however many times it tries.
+  static #walksItems(node: ts.Node | undefined): boolean {
+    if (!node) return false;
+    if (ts.isCallExpression(node)) return true;
+    if (ts.isPropertyAccessExpression(node) && ["length", "size"].includes(node.name.text)) return true;
+    return !!ts.forEachChild(node, (child) => WritePath.#walksItems(child) || undefined);
+  }
+
+  #busier = (a: ts.CallExpression[], b: ts.CallExpression[]) => (this.countOf(b) > this.countOf(a) ? b : a);
+}