@tsplc/compiler 0.0.0-stage → 0.1.0

package/src/frontend/promises.ts

@@ -0,0 +1,751 @@
+import { runtimeSources } from "./module-graph.ts";
+import ts from "typescript";
+import { dirname, relative } from "node:path";
+import { error, type Diagnostic } from "@tsplc/compiler/ir";
+
+type Routine = ts.FunctionDeclaration | ts.MethodDeclaration;
+type Handler = ts.ArrowFunction | ts.FunctionExpression | Routine;
+interface Edit {
+  start: number;
+  end: number;
+  text: string;
+}
+interface Part {
+  kind: "then" | "catch";
+  handlers: readonly ts.Expression[];
+}
+
+/** Normalize promise syntax into named coroutines; scheduling stays in async lowering. */
+export const lowerPromises = (program: ts.Program, sdk: string) => {
+  const checker = program.getTypeChecker();
+  const sources = new Map<string, string>(),
+    diagnostics: Diagnostic[] = [];
+  const runtimeBlocks = new Map<string, { kind: "mailbox" }>();
+  const files = runtimeSources(program).filter((source) => !source.isDeclarationFile);
+  const additions = new Map<ts.SourceFile, string[]>(),
+    edits = new Map<ts.SourceFile, Edit[]>();
+  const methods = new Map<ts.ClassDeclaration, string[]>();
+  let sequence = 0;
+  const symbol = (node: ts.Node): ts.Symbol | undefined => {
+    let value = checker.getSymbolAtLocation(node);
+    while (value && value.flags & ts.SymbolFlags.Alias) value = checker.getAliasedSymbol(value);
+    return value;
+  };
+  const official = (node: ts.Node, name: string) => {
+    const value = symbol(node);
+    return (
+      value?.name === name &&
+      value.declarations?.some((declaration) =>
+        declaration.getSourceFile().fileName.startsWith(dirname(sdk) + "/"),
+      )
+    );
+  };
+  const diagnosticFor = (node: ts.Node, message: string) => {
+    const source = node.getSourceFile(),
+      start = node.getStart(source),
+      position = source.getLineAndCharacterOfPosition(start);
+    return error("PLC1012", message, {
+      file: source.fileName,
+      start,
+      end: node.end,
+      line: position.line + 1,
+      column: position.character + 1,
+    });
+  };
+  const fail: (node: ts.Node, message: string) => never = (node, message) => {
+    throw { promiseDiagnostic: diagnosticFor(node, message) };
+  };
+  const append = (source: ts.SourceFile, text: string) =>
+    additions.set(source, [...(additions.get(source) ?? []), text]);
+  const edit = (node: ts.Node, text: string) => {
+    const source = node.getSourceFile();
+    edits.set(source, [
+      ...(edits.get(source) ?? []),
+      { start: node.getStart(source), end: node.end, text },
+    ]);
+  };
+  const routines = new Map<ts.Symbol, Routine>();
+  for (const source of files)
+    for (const statement of source.statements) {
+      const candidates = ts.isClassDeclaration(statement)
+        ? statement.members.filter(ts.isMethodDeclaration)
+        : [statement];
+      for (const candidate of candidates)
+        if (
+          (ts.isFunctionDeclaration(candidate) || ts.isMethodDeclaration(candidate)) &&
+          candidate.name
+        )
+          routines.set(symbol(candidate.name)!, candidate);
+    }
+  const asyncRoutine = (node: ts.Node) => {
+    const fn = routines.get(symbol(node)!);
+    return fn?.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)
+      ? fn
+      : undefined;
+  };
+  const job = (node: ts.Node) => {
+    const declaration = symbol(node)?.declarations?.find(
+      (value) => ts.isVariableDeclaration(value) || ts.isPropertyDeclaration(value),
+    );
+    if (
+      !declaration ||
+      (!ts.isVariableDeclaration(declaration) && !ts.isPropertyDeclaration(declaration))
+    )
+      return;
+    const init = declaration.initializer;
+    if (
+      !init ||
+      !ts.isCallExpression(init) ||
+      !ts.isPropertyAccessExpression(init.expression) ||
+      !official(init.expression.expression, "backgroundTasks") ||
+      init.expression.name.text !== "define"
+    )
+      return;
+    return asyncRoutine(init.arguments[0]!);
+  };
+  const operation = (call: ts.CallExpression) =>
+    asyncRoutine(
+      ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression,
+    ) ??
+    job(ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression);
+  const isSdk = (call: ts.CallExpression, name: string) =>
+    official(
+      ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression,
+      name,
+    );
+  const split = (
+    expression: ts.Expression,
+  ): { root: ts.CallExpression; parts: Part[] } | undefined => {
+    if (!ts.isCallExpression(expression)) return;
+    if (
+      ts.isPropertyAccessExpression(expression.expression) &&
+      ["then", "catch"].includes(expression.expression.name.text)
+    ) {
+      const prefix = split(expression.expression.expression);
+      if (!prefix) return;
+      return {
+        root: prefix.root,
+        parts: [
+          ...prefix.parts,
+          {
+            kind: expression.expression.name.text === "then" ? "then" : "catch",
+            handlers: expression.arguments,
+          },
+        ],
+      };
+    }
+    if (operation(expression) || isSdk(expression, "sleep") || isSdk(expression, "fetch"))
+      return { root: expression, parts: [] };
+  };
+  const aliases = new Map<ts.Node, string>();
+  const typeImports = new Map<ts.SourceFile, Set<string>>();
+  const typeText = (node: ts.TypeNode, source: ts.SourceFile): string => {
+    if (node.kind === ts.SyntaxKind.VoidKeyword) return "void";
+    if (node.getSourceFile() === source) return node.getText(source);
+    let alias = aliases.get(node);
+    if (!alias) {
+      alias = `TsplcPromiseType${sequence++}`;
+      aliases.set(node, alias);
+      append(node.getSourceFile(), `export type ${alias}=${node.getText(node.getSourceFile())};`);
+    }
+    const path = relative(dirname(source.fileName), node.getSourceFile().fileName).replaceAll(
+      "\\",
+      "/",
+    );
+    const importedAliases = typeImports.get(source) ?? new Set<string>();
+    if (importedAliases.has(alias)) return alias;
+    importedAliases.add(alias);
+    typeImports.set(source, importedAliases);
+    append(
+      source,
+      `import type {${alias}} from ${JSON.stringify(path.startsWith(".") ? path : `./${path}`)};`,
+    );
+    return alias;
+  };
+  const expressionType = (node: ts.Expression, source: ts.SourceFile): string => {
+    if (
+      ts.isCallExpression(node) &&
+      node.typeArguments?.[0] &&
+      (official(node.expression, "defaultValue") ||
+        official(node.expression, "copy") ||
+        ["exact", "wrap", "wrapAdd", "wrapMultiply", "saturate"].some((name) =>
+          official(node.expression, name),
+        ))
+    )
+      return typeText(node.typeArguments[0], source);
+    const name = ts.isPropertyAccessExpression(node) ? node.name : node;
+    const declaration = symbol(name)?.declarations?.find(
+      (value) =>
+        (ts.isVariableDeclaration(value) ||
+          ts.isParameter(value) ||
+          ts.isPropertyDeclaration(value) ||
+          ts.isPropertySignature(value)) &&
+        value.type,
+    );
+    if (
+      declaration &&
+      (ts.isVariableDeclaration(declaration) ||
+        ts.isParameter(declaration) ||
+        ts.isPropertyDeclaration(declaration) ||
+        ts.isPropertySignature(declaration)) &&
+      declaration.type
+    )
+      return typeText(declaration.type, source);
+    const type = checker.getTypeAtLocation(node);
+    if (type.flags & ts.TypeFlags.BooleanLike) return "BOOL";
+    if (type.flags & ts.TypeFlags.Void) return "void";
+    if (type.symbol && type.symbol.name !== "__type" && type.flags & ts.TypeFlags.Object)
+      return checker.typeToString(
+        type,
+        node,
+        ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope,
+      );
+    fail(
+      node,
+      "Annotate this value with its concrete PLC type before using it in an async continuation.",
+    );
+  };
+  const isAggregate = (type: ts.Type | undefined) =>
+    Boolean(type && type.flags & ts.TypeFlags.Object);
+  const isPromise = (node: ts.Node) => {
+    const type = checker.getTypeAtLocation(node);
+    return checker.getAwaitedType(type) !== type;
+  };
+  const printer = ts.createPrinter();
+  const replaceNames = (node: ts.Node, names: ReadonlyMap<ts.Symbol, string>): string => {
+    const transformed = ts.transform(node, [
+      (context) => (root) => {
+        const visit = (value: ts.Node): ts.VisitResult<ts.Node> => {
+          if (
+            ts.isReturnStatement(value) &&
+            value.expression &&
+            !ts.isAwaitExpression(value.expression) &&
+            isPromise(value.expression)
+          ) {
+            return ts.factory.updateReturnStatement(
+              value,
+              ts.factory.createAwaitExpression(
+                ts.visitNode(value.expression, visit) as ts.Expression,
+              ),
+            );
+          }
+          if (ts.isShorthandPropertyAssignment(value)) {
+            const key = checker.getShorthandAssignmentValueSymbol(value);
+            const name = key && names.get(key);
+            if (name)
+              return ts.factory.createPropertyAssignment(
+                value.name,
+                ts.factory.createIdentifier(name),
+              );
+          }
+          if (
+            ts.isIdentifier(value) &&
+            !(ts.isPropertyAccessExpression(value.parent) && value.parent.name === value) &&
+            !(ts.isPropertyAssignment(value.parent) && value.parent.name === value)
+          ) {
+            const name = names.get(symbol(value)!);
+            if (name) return ts.factory.createIdentifier(name);
+          }
+          return ts.visitEachChild(value, visit, context);
+        };
+        return ts.visitNode(root, visit) as typeof root;
+      },
+    ]);
+    const value = printer.printNode(
+      ts.EmitHint.Unspecified,
+      transformed.transformed[0]!,
+      node.getSourceFile(),
+    );
+    transformed.dispose();
+    return value;
+  };
+  const hasBorrow = (node: ts.TypeNode, seen = new Set<ts.Symbol>()): boolean => {
+    if (ts.isTypeReferenceNode(node)) {
+      if (official(node.typeName, "InOut")) return true;
+      const key = symbol(node.typeName);
+      if (key && !seen.has(key)) {
+        seen.add(key);
+        for (const declaration of key.declarations ?? []) {
+          if (
+            ts.isInterfaceDeclaration(declaration) &&
+            declaration.members.some(
+              (member) =>
+                ts.isPropertySignature(member) && member.type && hasBorrow(member.type, seen),
+            )
+          )
+            return true;
+          if (ts.isTypeAliasDeclaration(declaration) && hasBorrow(declaration.type, seen))
+            return true;
+        }
+      }
+    }
+    return node.getChildren().some((child) => ts.isTypeNode(child) && hasBorrow(child, seen));
+  };
+  let diagnosticSource: ts.SourceFile | undefined;
+  const diag = () => {
+    if (!diagnosticSource) throw new Error("Missing async diagnostics owner");
+    return "tsplcPromiseDiagnostics";
+  };
+  const imported = new Set<ts.SourceFile>();
+  const ensureImports = (source: ts.SourceFile) => {
+    if (imported.has(source)) return;
+    imported.add(source);
+    append(
+      source,
+      `import {cooperativeTasks as tsplcCooperative,errorCode as tsplcErrorCode} from "@tsplc/compiler/async";import {wrapAdd as tsplcAsyncWrapAdd} from "@tsplc/compiler/types";`,
+    );
+  };
+  const scopes = new Map<ts.SourceFile | ts.ClassDeclaration, string[]>();
+  const make = (
+    expression: ts.Expression,
+    owner: ts.FunctionDeclaration | ts.MethodDeclaration,
+    detached: boolean,
+  ): string => {
+    const parsed = split(expression);
+    if (!parsed) fail(expression, "Expected a statically resolved async call.");
+    const source = expression.getSourceFile();
+    const classOwner =
+      ts.isMethodDeclaration(owner) && ts.isClassDeclaration(owner.parent)
+        ? owner.parent
+        : undefined;
+    ensureImports(source);
+    diagnosticSource ??= source;
+    const captures = new Map<ts.Symbol, { name: string; type: string; argument: string }>();
+    const collectCaptures = (handler: Handler) => {
+      const visit = (node: ts.Node): void => {
+        if (
+          ts.isIdentifier(node) &&
+          !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) &&
+          !(ts.isPropertyAssignment(node.parent) && node.parent.name === node)
+        ) {
+          const key = ts.isShorthandPropertyAssignment(node.parent)
+            ? checker.getShorthandAssignmentValueSymbol(node.parent)
+            : symbol(node);
+          const declaration = key?.valueDeclaration;
+          if (
+            declaration &&
+            (ts.isVariableDeclaration(declaration) || ts.isParameter(declaration))
+          ) {
+            let scope: ts.Node | undefined = declaration.parent;
+            while (scope && !ts.isFunctionLike(scope)) scope = scope.parent;
+            if (scope === owner && !captures.has(key!)) {
+              if (
+                ts.isVariableDeclaration(declaration) &&
+                (!ts.isVariableDeclarationList(declaration.parent) ||
+                  !(declaration.parent.flags & ts.NodeFlags.Const))
+              )
+                fail(
+                  node,
+                  "Continuation captures must be const values; store mutable state on the controller instead.",
+                );
+              if (!declaration.type)
+                fail(node, "Annotate a captured value with its concrete PLC type.");
+              if (hasBorrow(declaration.type))
+                fail(
+                  node,
+                  "A continuation cannot capture borrowed InOut storage; capture values or use controller state.",
+                );
+              captures.set(key!, {
+                name: `capture${captures.size}`,
+                type: typeText(declaration.type, source),
+                argument: node.text,
+              });
+            }
+          }
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(handler.body!);
+    };
+    for (const part of parsed.parts)
+      for (const value of part.handlers) {
+        if (
+          value.kind === ts.SyntaxKind.UndefinedKeyword ||
+          value.kind === ts.SyntaxKind.NullKeyword
+        )
+          continue;
+        if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) collectCaptures(value);
+      }
+    const captureNames = new Map([...captures].map(([key, value]) => [key, value.name]));
+    const root = parsed.root,
+      fn = operation(root);
+    let resultAggregate = isAggregate(checker.getAwaitedType(checker.getTypeAtLocation(root)));
+    const arguments_: { name: string; type: string; expression: string }[] = [];
+    let invocation: string, resultType: string;
+    if (fn) {
+      const node = fn.type;
+      if (!node || !ts.isTypeReferenceNode(node) || !node.typeArguments?.[0])
+        fail(fn, "Async calls need an explicit Promise<T> result.");
+      resultType = typeText(node.typeArguments[0], source);
+      fn.parameters.forEach((parameter, index) => {
+        if (!parameter.type || !root.arguments[index])
+          fail(root, "Async argument count differs from its concrete signature.");
+        arguments_.push({
+          name: `argument${index}`,
+          type: typeText(parameter.type, source),
+          expression: root.arguments[index]!.getText(source),
+        });
+      });
+      invocation = `${root.expression.getText(source)}(${arguments_.map((value) => value.name).join(",")})`;
+    } else if (isSdk(root, "sleep")) {
+      if (root.arguments.length !== 1) fail(root, "sleep requires one TIME argument.");
+      arguments_.push({
+        name: "argument0",
+        type: "TIME",
+        expression: root.arguments[0]!.getText(source),
+      });
+      invocation = `${root.expression.getText(source)}(argument0)`;
+      resultType = "void";
+    } else {
+      const response = root.typeArguments?.[0];
+      if (!response) fail(root, "fetch requires a typed response.");
+      resultType = typeText(response, source);
+      const options = root.arguments[1];
+      if (options && !ts.isObjectLiteralExpression(options))
+        fail(options, "fetch options must be an inline object.");
+      let optionText = "";
+      if (options && ts.isObjectLiteralExpression(options))
+        optionText = options.properties
+          .map((property) => {
+            if (!ts.isPropertyAssignment(property)) fail(property, "fetch requires named options.");
+            if (property.name.getText(source) !== "json") return property.getText(source);
+            arguments_.push({
+              name: "argument0",
+              type: expressionType(property.initializer, source),
+              expression: property.initializer.getText(source),
+            });
+            return "json:argument0";
+          })
+          .join(",");
+      invocation = `${root.expression.getText(source)}<${root.typeArguments!.map((type) => type.getText(source)).join(",")}>(${root.arguments[0]!.getText(source)}${options ? `,{${optionText}}` : ""})`;
+    }
+    const params = [
+      ...arguments_,
+      ...[...captures.values()].map((value) => ({
+        name: value.name,
+        type: value.type,
+        expression: value.argument,
+      })),
+    ];
+    const signature = params.map((value) => `${value.name}:${value.type}`).join(","),
+      args = params.map((value) => value.name).join(",");
+    const addHelper = (
+      name: string,
+      body: string,
+      type: string,
+      extra?: { type: string; argument: string },
+    ) => {
+      const text = `${classOwner ? "private " : "export "}async ${classOwner ? "" : "function "}${name}(${[signature, extra ? `promiseInput:${extra.type}` : ""].filter(Boolean).join(",")}):Promise<${type}>{${body}}`;
+      if (classOwner) methods.set(classOwner, [...(methods.get(classOwner) ?? []), text]);
+      else append(source, text);
+      return `${classOwner ? "this." : ""}${name}(${[args, extra?.argument ?? ""].filter(Boolean).join(",")})`;
+    };
+    const finish = (call: string, type: string, discard = false) =>
+      type === "void" || discard ? `await ${call};return;` : `return await ${call};`;
+    let prefix = addHelper(
+      `tsplcPromiseOperation${sequence++}`,
+      finish(invocation, resultType),
+      resultType,
+    );
+    const handler = (
+      expression: ts.Expression | undefined,
+      inputType: string,
+      input: string,
+    ): { call: string; type: string; aggregate: boolean } | undefined => {
+      if (
+        !expression ||
+        expression.kind === ts.SyntaxKind.NullKeyword ||
+        (ts.isIdentifier(expression) && expression.text === "undefined")
+      )
+        return;
+      let declaration: Handler;
+      if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression))
+        declaration = expression;
+      else {
+        const named = routines.get(symbol(expression)!);
+        if (!named || !ts.isFunctionDeclaration(named))
+          fail(
+            expression,
+            "Use a named function or inline arrow; bind instance methods with an arrow.",
+          );
+        declaration = named;
+      }
+      const callbackSignature = checker.getSignatureFromDeclaration(declaration);
+      const aggregate = isAggregate(
+        callbackSignature &&
+          checker.getAwaitedType(checker.getReturnTypeOfSignature(callbackSignature)),
+      );
+      if (!declaration.body || declaration.parameters.length > 1)
+        fail(declaration, "Promise callbacks take at most one value.");
+      if (declaration.getSourceFile() !== source) {
+        const result = declaration.type;
+        if (!result) fail(declaration, "Annotate callback results with their concrete PLC type.");
+        let output = result;
+        if (
+          ts.isTypeReferenceNode(result) &&
+          result.typeName.getText(declaration.getSourceFile()) === "Promise"
+        )
+          output = result.typeArguments![0]!;
+        // Named callbacks retain their original module and access to its private state.
+        const callbackType = typeText(output, source);
+        const name = expression.getText(source);
+        if (declaration.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword))
+          return {
+            call: `${name}(${declaration.parameters.length ? input : ""})`,
+            type: callbackType,
+            aggregate,
+          };
+        return {
+          call: addHelper(
+            `tsplcPromiseNamed${sequence++}`,
+            callbackType === "void"
+              ? `${name}(${declaration.parameters.length ? "promiseInput" : ""});return;`
+              : `return ${name}(${declaration.parameters.length ? "promiseInput" : ""});`,
+            callbackType,
+            declaration.parameters.length ? { type: inputType, argument: input } : undefined,
+          ),
+          type: callbackType,
+          aggregate,
+        };
+      }
+      const names = new Map(captureNames);
+      const parameter = declaration.parameters[0];
+      if (parameter) {
+        if (!ts.isIdentifier(parameter.name))
+          fail(parameter, "Promise callback parameters need names.");
+        names.set(symbol(parameter.name)!, "promiseValue");
+      }
+      let type: string;
+      if (declaration.type) {
+        const annotation = declaration.type;
+        type =
+          ts.isTypeReferenceNode(annotation) && annotation.typeName.getText(source) === "Promise"
+            ? typeText(annotation.typeArguments![0]!, source)
+            : typeText(annotation, source);
+      } else {
+        const resolved = checker.getSignatureFromDeclaration(declaration);
+        const inferred =
+          resolved && checker.getAwaitedType(checker.getReturnTypeOfSignature(resolved));
+        if (inferred?.flags && inferred.flags & ts.TypeFlags.Void) type = "void";
+        else if (
+          !ts.isBlock(declaration.body) &&
+          ts.isIdentifier(declaration.body) &&
+          parameter &&
+          symbol(declaration.body) === symbol(parameter.name)
+        )
+          type = inputType;
+        else if (!ts.isBlock(declaration.body)) {
+          const returned = ts.isCallExpression(declaration.body)
+            ? operation(declaration.body)
+            : undefined;
+          type =
+            returned?.type && ts.isTypeReferenceNode(returned.type)
+              ? typeText(returned.type.typeArguments![0]!, source)
+              : expressionType(declaration.body, source);
+        } else
+          fail(declaration, "Annotate a callback that returns a value with its concrete PLC type.");
+      }
+      const name = `tsplcPromiseHandler${sequence++}`;
+      const body = replaceNames(declaration.body, names);
+      const code = ts.isBlock(declaration.body)
+        ? body.slice(1, -1)
+        : type === "void"
+          ? `${body};return;`
+          : `return ${isPromise(declaration.body) ? "await " : ""}${body};`;
+      const handlerParams = [
+        ...(parameter && inputType !== "void" ? [`promiseValue:${inputType}`] : []),
+        ...params.map((value) => `${value.name}:${value.type}`),
+      ].join(",");
+      const text = `${classOwner ? "private " : "export "}async ${classOwner ? "" : "function "}${name}(${handlerParams}):Promise<${type}>{${code}}`;
+      if (classOwner) methods.set(classOwner, [...(methods.get(classOwner) ?? []), text]);
+      else append(source, text);
+      return {
+        call: `${classOwner ? "this." : ""}${name}(${[...(parameter && inputType !== "void" ? [input] : []), ...params.map((value) => value.name)].join(",")})`,
+        type,
+        aggregate,
+      };
+    };
+    for (const [index, part] of parsed.parts.entries()) {
+      const terminal = detached && index === parsed.parts.length - 1;
+      const fulfilled =
+        part.kind === "then" ? handler(part.handlers[0], resultType, "promiseResult") : undefined;
+      const rejected = handler(
+        part.handlers[part.kind === "catch" ? 0 : 1],
+        "UDINT",
+        "tsplcErrorCode(promiseError)",
+      );
+      if (!fulfilled && !rejected) continue;
+      const output = terminal ? "void" : (fulfilled?.type ?? resultType);
+      if (rejected && !terminal && rejected.type !== output)
+        fail(
+          expression,
+          "A recovery callback must return the same PLC type as the fulfilled branch.",
+        );
+      const success = fulfilled
+        ? finish(fulfilled.call, fulfilled.type, terminal)
+        : resultType === "void" || terminal
+          ? "return;"
+          : "return promiseResult;";
+      const load =
+        resultType === "void"
+          ? `await ${prefix};`
+          : `const promiseResult:${resultType}=await ${prefix};`;
+      let body: string;
+      if (rejected && fulfilled) {
+        const stored =
+          resultType === "void"
+            ? ""
+            : `let promiseResult:${resultType}=defaultValue<${resultType}>();`;
+        const attempt =
+          resultType === "void"
+            ? `await ${prefix};`
+            : `const loaded:${resultType}=await ${prefix};promiseResult=${resultAggregate ? "copy(loaded)" : "loaded"};`;
+        body = `${stored}let succeeded:BOOL=false;let rejection:UDINT=0;try{${attempt}succeeded=true;}catch(promiseError){rejection=tsplcErrorCode(promiseError);}if(!succeeded){${finish(rejected.call.replace("tsplcErrorCode(promiseError)", "rejection"), rejected.type, terminal)}}${success}`;
+      } else if (rejected)
+        body = `try{${load}${success}}catch(promiseError){${finish(rejected.call, rejected.type, terminal)}}`;
+      else body = `${load}${success}`;
+      prefix = addHelper(`tsplcPromiseChain${sequence++}`, body, output);
+      resultType = output;
+      resultAggregate = terminal ? false : (fulfilled?.aggregate ?? resultAggregate);
+    }
+    if (!detached)
+      return prefix.replace(`(${args})`, `(${params.map((value) => value.expression).join(",")})`);
+    const site = `tsplcPromiseSite${sequence++}`;
+    const callable = prefix.slice(0, prefix.indexOf("("));
+    const declaration = `${classOwner ? "private " : "const "}${site}=tsplcCooperative.define(${callable});`;
+    if (classOwner) methods.set(classOwner, [...(methods.get(classOwner) ?? []), declaration]);
+    else append(source, declaration);
+    const scope = classOwner ?? source;
+    scopes.set(scope, [...(scopes.get(scope) ?? []), site]);
+    return `${classOwner ? "this." : ""}${site}.start(${params.map((value) => value.expression).join(",")});`;
+  };
+  const diagnosticsCalls: ts.CallExpression[] = [],
+    cancelCalls: {
+      node: ts.CallExpression;
+      owner: ts.FunctionDeclaration | ts.MethodDeclaration;
+    }[] = [];
+  for (const source of files) {
+    const visit = (node: ts.Node, owner?: ts.FunctionDeclaration | ts.MethodDeclaration): void => {
+      if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+        if (node.body) ts.forEachChild(node.body, (child) => visit(child, node));
+        return;
+      }
+      if (!owner) {
+        ts.forEachChild(node, (child) => visit(child));
+        return;
+      }
+      if (ts.isCallExpression(node) && official(node.expression, "asyncDiagnostics")) {
+        diagnosticSource ??= source;
+        diagnosticsCalls.push(node);
+        return;
+      }
+      if (ts.isCallExpression(node) && official(node.expression, "cancelAsync")) {
+        cancelCalls.push({ node, owner });
+        return;
+      }
+      const asynchronous = owner.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword,
+      );
+      if (ts.isExpressionStatement(node)) {
+        const expression = ts.isVoidExpression(node.expression)
+          ? node.expression.expression
+          : node.expression;
+        if (split(expression)) {
+          if (asynchronous) {
+            diagnostics.push(
+              diagnosticFor(
+                node,
+                "Await async work inside an async routine; detached calls belong in synchronous controllers.",
+              ),
+            );
+            return;
+          }
+          try {
+            edit(node, make(expression, owner, true));
+          } catch (cause) {
+            if (typeof cause === "object" && cause !== null && "promiseDiagnostic" in cause)
+              diagnostics.push(cause.promiseDiagnostic as Diagnostic);
+            else throw cause;
+          }
+          return;
+        }
+      }
+      if (ts.isCallExpression(node)) {
+        const chain = split(node);
+        if (chain?.parts.length) {
+          try {
+            edit(node, make(node, owner, false));
+          } catch (cause) {
+            if (typeof cause === "object" && cause !== null && "promiseDiagnostic" in cause)
+              diagnostics.push(cause.promiseDiagnostic as Diagnostic);
+            else throw cause;
+          }
+          return;
+        }
+      }
+      ts.forEachChild(node, (child) => visit(child, owner));
+    };
+    visit(source);
+  }
+  for (const { node, owner } of cancelCalls) {
+    const scope =
+      ts.isMethodDeclaration(owner) && ts.isClassDeclaration(owner.parent)
+        ? owner.parent
+        : owner.getSourceFile();
+    if (
+      node.arguments.length &&
+      (node.arguments.length !== 1 || node.arguments[0]!.kind !== ts.SyntaxKind.ThisKeyword)
+    )
+      diagnostics.push(
+        diagnosticFor(node, "cancelAsync takes this in a controller, or no argument in a module."),
+      );
+    const name = `tsplcCancelScope${sequence++}`;
+    const body = (scopes.get(scope) ?? [])
+      .map((site) => `${ts.isClassDeclaration(scope) ? "this." : ""}${site}.cancel();`)
+      .join("");
+    if (ts.isClassDeclaration(scope))
+      methods.set(scope, [...(methods.get(scope) ?? []), `private ${name}():void{${body}}`]);
+    else append(scope, `function ${name}():void{${body}}`);
+    edit(node, `${ts.isClassDeclaration(scope) ? "this." : ""}${name}()`);
+  }
+  if (diagnosticSource) {
+    const source = diagnosticSource;
+    ensureImports(source);
+    append(
+      source,
+      `export class TsplcPromiseDiagnostics extends FunctionBlock<{}>{private count:UDINT=0;private lastError:UDINT=0;public report(code:UDINT,count:UDINT):BOOL{this.count=tsplcAsyncWrapAdd<UDINT>(this.count,count);this.lastError=code;return true;}public snapshot():{valid:BOOL;count:UDINT;lastError:UDINT}{return {valid:true,count:this.count,lastError:this.lastError};}protected execute(input:{}):void{}}
+export const tsplcPromiseDiagnostics=new TsplcPromiseDiagnostics();`,
+    );
+    runtimeBlocks.set(`${source.fileName}:TsplcPromiseDiagnostics`, { kind: "mailbox" });
+    for (const file of new Set([
+      ...additions.keys(),
+      ...diagnosticsCalls.map((node) => node.getSourceFile()),
+    ])) {
+      if (file !== source) {
+        const path = relative(dirname(file.fileName), source.fileName).replaceAll("\\", "/");
+        append(
+          file,
+          `import {${diag()}} from ${JSON.stringify(path.startsWith(".") ? path : `./${path}`)};`,
+        );
+      }
+    }
+    for (const call of diagnosticsCalls) edit(call, `${diag()}.snapshot()`);
+  }
+  for (const [owner, texts] of methods) {
+    const source = owner.getSourceFile();
+    edits.set(source, [
+      ...(edits.get(source) ?? []),
+      { start: owner.end - 1, end: owner.end - 1, text: "\n" + texts.join("\n") },
+    ]);
+  }
+  for (const source of files) {
+    const changes = edits.get(source) ?? [],
+      extra = additions.get(source) ?? [];
+    if (!changes.length && !extra.length) continue;
+    let text = source.text;
+    for (const change of changes.sort((left, right) => right.start - left.start))
+      text = text.slice(0, change.start) + change.text + text.slice(change.end);
+    sources.set(source.fileName, text + "\n" + extra.join("\n"));
+  }
+  return { sources, diagnostics, runtimeBlocks };
+};