@flow-as-code/core 0.1.0

package/src/codegen.ts

@@ -0,0 +1,1144 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// codegen: FlowDoc in, idiomatic TypeScript out.
+//
+// The output is what a person would have written against the builder API: one
+// exported zero-arg factory returning a Flow (or FlowModule), with one inline
+// block construction per Action, in doc order. Synth preserves declaration
+// order (docs/adr/0003-action-ordering.md), so emitting doc order makes
+// synth(codegen(doc)) reproduce the doc with no reordering step.
+//
+// Invariants:
+// - Pure and byte-stable: the same FlowDoc yields the identical string.
+// - Prettier-clean as written: the printer mirrors the repo Prettier config
+//   (2-space indent, double quotes, trailing commas, printWidth 100), and a
+//   test formats the output to prove it is a fixed point.
+// - Lossless: an Action of a modeled Type that the block class cannot
+//   reproduce exactly falls back to GenericBlock, verified by re-synthesizing
+//   every candidate block and comparing against the source Action.
+// - Reference tokens in modeled reference-bearing fields become Refs.* calls;
+//   JSONPath strings become jsonPath(...); tokens inside GenericBlock
+//   parameters stay verbatim strings and are never rewritten.
+
+import {
+  ActionType,
+  DTMF_DIGITS,
+  INPUT_TIME_LIMIT_EXCEEDED,
+  NO_MATCHING_CONDITION,
+  NO_MATCHING_ERROR,
+  REFERENCE_FIELDS,
+} from "./actions.js";
+import type { DtmfDigit } from "./actions.js";
+import type { Block, DtmfBranch, GenericBlockConfig, MessageBody } from "./blocks.js";
+import {
+  CheckHoursOfOperation,
+  Compare,
+  DisconnectParticipant,
+  EndFlowExecution,
+  EndFlowModuleExecution,
+  GenericBlock,
+  GetParticipantInput,
+  InvokeFlowModule,
+  InvokeLambdaFunction,
+  MessageParticipant,
+  TransferContactToQueue,
+  TransferToFlow,
+  UpdateContactAttributes,
+  UpdateContactRecordingBehavior,
+  UpdateContactTargetQueue,
+} from "./blocks.js";
+import type {
+  ConditionOperator,
+  ErrorTransition,
+  FlowAction,
+  FlowDoc,
+  Point,
+  RefType,
+  Transitions,
+} from "./flowdoc.js";
+import { assertFlowDoc } from "./flowdoc.js";
+import { autoLayout } from "./layout.js";
+import { PACKAGE_NAMES } from "./package-names.js";
+import { parseToken } from "./refs.js";
+
+export interface CodegenOptions {
+  /** Import path for the builder API. Defaults to the published package. */
+  moduleSpecifier?: string;
+  /**
+   * A previously generated source for the same flow. Comment lines containing
+   * `@keep` that immediately precede a block construction re-attach to the
+   * block with the same id; ones immediately preceding the export function
+   * re-attach there. Everything else regenerates.
+   */
+  previous?: string;
+}
+
+const DEFAULT_MODULE_SPECIFIER = PACKAGE_NAMES.core;
+const PRINT_WIDTH = 100;
+
+// The banner on generated files. No licence header: the output lands in a
+// user's project and is their file, not ours, so stamping this repo's
+// copyright on it would be wrong. The Terraform emitter's banner works the
+// same way (packages/tf/src/emit.ts).
+//
+// Naming the document it came from makes a file found on its own explain
+// itself, and `.flowdoc.json` is the name `flow-cli codegen` reads.
+function generatedMarker(name: string): string[] {
+  return [
+    `// Generated by ${PACKAGE_NAMES.core} codegen from ${name}.flowdoc.json.`,
+    "// Edits to structure regenerate; comments marked @keep survive.",
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Value model for the printer
+// ---------------------------------------------------------------------------
+
+/** A code fragment emitted verbatim, e.g. `Refs.queue("front-desk")`. */
+class Raw {
+  constructor(readonly code: string) {}
+}
+
+/** An object literal with a fixed entry order. */
+class ObjV {
+  constructor(readonly entries: [string, V][]) {}
+}
+
+class ArrV {
+  constructor(readonly items: V[]) {}
+}
+
+type V = string | number | boolean | null | Raw | ObjV | ArrV;
+
+/** Arbitrary JSON (GenericBlock parameters) to the value model, keys sorted. */
+function toV(value: unknown): V {
+  if (value === null || typeof value === "string" || typeof value === "number") return value;
+  if (typeof value === "boolean") return value;
+  if (Array.isArray(value)) return new ArrV(value.map(toV));
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => [k, toV(v)] as [string, V]);
+    return new ObjV(entries);
+  }
+  throw new Error(`Cannot emit a ${typeof value} value.`);
+}
+
+// ---------------------------------------------------------------------------
+// Printer. Mirrors the repo Prettier config so the output is a Prettier fixed
+// point: double quotes unless the string holds more double than single quotes,
+// keys quoted only when not valid identifiers, objects kept expanded once
+// broken (Prettier objectWrap: preserve), arrays force-broken when every
+// element is an object with two or more properties.
+// ---------------------------------------------------------------------------
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+function quoteString(s: string): string {
+  const doubles = (s.match(/"/g) ?? []).length;
+  const singles = (s.match(/'/g) ?? []).length;
+  const q = doubles > singles ? "'" : '"';
+  let out = q;
+  for (const ch of s) {
+    if (ch === "\\") out += "\\\\";
+    else if (ch === q) out += `\\${q}`;
+    else if (ch === "\n") out += "\\n";
+    else if (ch === "\r") out += "\\r";
+    else if (ch === "\t") out += "\\t";
+    else if (
+      ch < " " ||
+      ch === "\u2028" ||
+      ch === "\u2029" ||
+      (ch.codePointAt(0)! >= 0xd800 && ch.codePointAt(0)! <= 0xdfff)
+    ) {
+      // Control characters, JS line separators, and lone surrogates must be
+      // escaped: an unpaired surrogate written to a utf8 file becomes U+FFFD,
+      // which would break the file-based round trip.
+      out += `\\u${ch.codePointAt(0)!.toString(16).padStart(4, "0")}`;
+    } else out += ch;
+  }
+  return out + q;
+}
+
+function keySource(key: string): string {
+  return IDENTIFIER.test(key) ? key : quoteString(key);
+}
+
+/** Prettier breaks such arrays regardless of width. */
+function arrayForcesBreak(a: ArrV): boolean {
+  return a.items.length > 1 && a.items.every((i) => i instanceof ObjV && i.entries.length >= 2);
+}
+
+/** Single-line rendering, or undefined when the value must break. */
+function inlineV(v: V): string | undefined {
+  if (v instanceof Raw) return v.code;
+  if (typeof v === "string") return quoteString(v);
+  if (typeof v === "number" || typeof v === "boolean" || v === null) return String(v);
+  if (v instanceof ArrV) {
+    if (arrayForcesBreak(v)) return undefined;
+    const items = v.items.map(inlineV);
+    if (items.some((i) => i === undefined)) return undefined;
+    return `[${items.join(", ")}]`;
+  }
+  if (v.entries.length === 0) return "{}";
+  const parts = v.entries.map(([k, val]) => {
+    const inner = inlineV(val);
+    return inner === undefined ? undefined : `${keySource(k)}: ${inner}`;
+  });
+  if (parts.some((p) => p === undefined)) return undefined;
+  return `{ ${parts.join(", ")} }`;
+}
+
+/**
+ * Renders a value starting at column `col` on a line indented by `indent`.
+ * Continuation lines carry their own indentation; the first line does not.
+ * One column is reserved for the trailing comma the caller appends.
+ */
+function printV(v: V, col: number, indent: string): string {
+  const flat = inlineV(v);
+  if (flat !== undefined && col + flat.length + 1 <= PRINT_WIDTH) return flat;
+  const inner = `${indent}  `;
+  if (v instanceof ObjV && v.entries.length > 0) return printBrokenObject(v.entries, indent);
+  if (v instanceof ArrV && v.items.length > 0) {
+    const lines = v.items.map((i) => `${inner}${printV(i, inner.length, inner)},`);
+    return `[\n${lines.join("\n")}\n${indent}]`;
+  }
+  // Primitives and Raw fragments cannot break; emit even when over width.
+  return flat ?? "";
+}
+
+function printBrokenObject(entries: [string, V][], indent: string): string {
+  const inner = `${indent}  `;
+  const lines = entries.map(([k, val]) => {
+    const prefix = `${inner}${keySource(k)}: `;
+    return `${prefix}${printV(val, prefix.length, inner)},`;
+  });
+  return `{\n${lines.join("\n")}\n${indent}}`;
+}
+
+// ---------------------------------------------------------------------------
+// Inversion: FlowAction back to a block construction.
+//
+// Every candidate is verified by constructing the real block and comparing its
+// toAction() output against the source Action; on any mismatch the Action is
+// emitted as a GenericBlock instead, so the round-trip stays lossless.
+// ---------------------------------------------------------------------------
+
+interface Inversion {
+  /** Block class name, also the import to emit. */
+  cls: string;
+  /** Config object entries in emission order. */
+  entries: [string, V][];
+  /** The constructed block, used to verify the inversion is exact. */
+  block: Block;
+}
+
+interface Ctx {
+  refs: boolean;
+  jsonPath: boolean;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    const body = keys
+      .map((k) => `${JSON.stringify(k)}:${stableJson((value as Record<string, unknown>)[k])}`)
+      .join(",");
+    return `{${body}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const cast = <T>(value: unknown): T => value as T;
+
+/**
+ * A reference-bearing field value as builder source. Well-formed tokens of the
+ * expected type become Refs.* calls, JSONPath strings become jsonPath(...),
+ * anything else is inexpressible and forces the GenericBlock fallback.
+ * https://docs.aws.amazon.com/connect/latest/devguide/flow-language-actions.html
+ * documents these fields as fully static or a single JSONPath identifier.
+ */
+function refSource(value: unknown, type: RefType, ctx: Ctx): Raw | undefined {
+  if (typeof value !== "string") return undefined;
+  const entry = parseToken(value);
+  if (entry !== undefined) {
+    if (entry.type !== type) return undefined;
+    if (type === "module") {
+      if (entry.alias === undefined) return undefined; // Refs.module requires an alias
+      ctx.refs = true;
+      return new Raw(`Refs.module(${quoteString(entry.name)}, ${quoteString(entry.alias)})`);
+    }
+    if (entry.alias !== undefined) return undefined; // only module refs carry aliases
+    ctx.refs = true;
+    return new Raw(`Refs.${type}(${quoteString(entry.name)})`);
+  }
+  if (/^\$\.[A-Za-z0-9_$.[\]'-]+$/.test(value)) {
+    ctx.jsonPath = true;
+    return new Raw(`jsonPath(${quoteString(value)})`);
+  }
+  return undefined;
+}
+
+function paramKeysAre(
+  params: Record<string, unknown>,
+  required: string[],
+  optional: string[] = [],
+): boolean {
+  const keys = Object.keys(params);
+  return (
+    required.every((k) => keys.includes(k)) &&
+    keys.every((k) => required.includes(k) || optional.includes(k))
+  );
+}
+
+/** NextAction plus exactly one catch-all error and no conditions. */
+function wiredTransitions(
+  t: Transitions,
+  errorType: string,
+): { next: string; onError: string } | undefined {
+  if (t.NextAction === undefined) return undefined;
+  const errors = t.Errors ?? [];
+  if (errors.length !== 1 || errors[0]!.ErrorType !== errorType) return undefined;
+  if ((t.Conditions ?? []).length !== 0) return undefined;
+  return { next: t.NextAction, onError: errors[0]!.NextAction };
+}
+
+function isStringMap(value: unknown): value is Record<string, string> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.values(value as Record<string, unknown>).every((v) => typeof v === "string")
+  );
+}
+
+const OPERATORS: readonly string[] = [
+  "Equals",
+  "TextStartsWith",
+  "TextEndsWith",
+  "TextContains",
+  "NumberGreaterThan",
+  "NumberGreaterOrEqualTo",
+  "NumberLessThan",
+  "NumberLessOrEqualTo",
+];
+
+function isCondition(
+  value: unknown,
+): value is { NextAction: string; Condition: { Operator: ConditionOperator; Operands: string[] } } {
+  const c = value as {
+    NextAction?: unknown;
+    Condition?: { Operator?: unknown; Operands?: unknown };
+  };
+  return (
+    typeof c.NextAction === "string" &&
+    typeof c.Condition === "object" &&
+    c.Condition !== null &&
+    typeof c.Condition.Operator === "string" &&
+    OPERATORS.includes(c.Condition.Operator) &&
+    Array.isArray(c.Condition.Operands) &&
+    c.Condition.Operands.every((o) => typeof o === "string")
+  );
+}
+
+function terminal(a: FlowAction, make: () => Block): Inversion | undefined {
+  if (Object.keys(a.Parameters).length !== 0) return undefined;
+  if (Object.keys(a.Transitions).length !== 0) return undefined;
+  return { cls: a.Type, entries: [["id", a.Identifier]], block: make() };
+}
+
+/**
+ * One inverter per modeled action type; undefined means "not expressible".
+ *
+ * The correctness gate is not in here. invertAction constructs the candidate
+ * block, compares its synthesized Action with the source byte for byte, and
+ * falls back to GenericBlock on any difference or constructor throw. The early
+ * returns below are readable statements of each class's shape and a cheap way
+ * out before a constructor runs; most of them are redundant with that
+ * comparison, so neutering one does not change the output. The exception is
+ * the refSource check: the block would still verify with an unresolvable
+ * PromptId, but the emitted entries would carry `prompt: undefined`, so that
+ * return is load-bearing and is the one a test pins. The typeof checks on
+ * string parameters exist for the type checker; the comparison catches the
+ * JSON number spelling either way.
+ */
+const INVERTERS: Record<string, (a: FlowAction, ctx: Ctx) => Inversion | undefined> = {
+  [ActionType.MessageParticipant]: (a, ctx) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined) return undefined;
+    const p = a.Parameters;
+    const keys = Object.keys(p);
+    if (keys.length !== 1) return undefined;
+    const entries: [string, V][] = [["id", a.Identifier]];
+    if (keys[0] === "Text" && typeof p.Text === "string") entries.push(["text", p.Text]);
+    else if (keys[0] === "SSML" && typeof p.SSML === "string") entries.push(["ssml", p.SSML]);
+    else if (keys[0] === "PromptId") {
+      const ref = refSource(
+        p.PromptId,
+        REFERENCE_FIELDS[ActionType.MessageParticipant]!.PromptId!,
+        ctx,
+      );
+      if (ref === undefined) return undefined;
+      entries.push(["prompt", ref]);
+    } else return undefined;
+    entries.push(["next", w.next], ["onError", w.onError]);
+    const body =
+      keys[0] === "Text"
+        ? { text: cast<string>(p.Text) }
+        : keys[0] === "SSML"
+          ? { ssml: cast<string>(p.SSML) }
+          : { prompt: cast<never>(p.PromptId) };
+    return {
+      cls: "MessageParticipant",
+      entries,
+      block: new MessageParticipant({
+        id: a.Identifier,
+        ...body,
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+
+  [ActionType.GetParticipantInput]: (a, ctx) => {
+    const t = a.Transitions;
+    const errors = t.Errors ?? [];
+    // The class emits the menu form's three errors in this order.
+    const expected = [INPUT_TIME_LIMIT_EXCEEDED, NO_MATCHING_CONDITION, NO_MATCHING_ERROR];
+    if (errors.length !== expected.length) return undefined;
+    if (errors.some((e, i) => e.ErrorType !== expected[i])) return undefined;
+    const [onTimeout, onNoMatch, onError] = errors.map((e) => e.NextAction) as [
+      string,
+      string,
+      string,
+    ];
+    // The class mirrors NextAction onto the no-match path.
+    if (t.NextAction !== onNoMatch) return undefined;
+    const conditions = t.Conditions ?? [];
+    if (!conditions.every(isCondition)) return undefined;
+    const branches: DtmfBranch[] = [];
+    for (const c of conditions) {
+      if (c.Condition.Operator !== "Equals" || c.Condition.Operands.length !== 1) return undefined;
+      const digit = c.Condition.Operands[0]!;
+      if (!(DTMF_DIGITS as readonly string[]).includes(digit)) return undefined;
+      branches.push({ digit: digit as DtmfDigit, target: c.NextAction });
+    }
+    const p = a.Parameters;
+    if (!paramKeysAre(p, ["InputTimeLimitSeconds", "StoreInput"], ["Text", "SSML", "PromptId"])) {
+      return undefined;
+    }
+    // Only the menu form is modeled; stored input has no conditions and needs
+    // InputValidation, which the class does not emit.
+    if (p.StoreInput !== "False") return undefined;
+    // The class writes the timeout as a plain decimal string, so only that
+    // spelling inverts: "5", never 5, "05", or "5.0". The constructor holds
+    // the value to its documented range.
+    if (typeof p.InputTimeLimitSeconds !== "string") return undefined;
+    if (!/^[1-9][0-9]*$/.test(p.InputTimeLimitSeconds)) return undefined;
+    const timeoutSeconds = Number(p.InputTimeLimitSeconds);
+    const bodyKeys = ["Text", "SSML", "PromptId"].filter((k) => k in p);
+    if (bodyKeys.length > 1) return undefined;
+    const entries: [string, V][] = [["id", a.Identifier]];
+    let body: MessageBody | { text?: never; ssml?: never; prompt?: never } = {};
+    if (bodyKeys[0] === "Text" && typeof p.Text === "string") {
+      entries.push(["text", p.Text]);
+      body = { text: p.Text };
+    } else if (bodyKeys[0] === "SSML" && typeof p.SSML === "string") {
+      entries.push(["ssml", p.SSML]);
+      body = { ssml: p.SSML };
+    } else if (bodyKeys[0] === "PromptId") {
+      const ref = refSource(
+        p.PromptId,
+        REFERENCE_FIELDS[ActionType.GetParticipantInput]!.PromptId!,
+        ctx,
+      );
+      if (ref === undefined) return undefined;
+      entries.push(["prompt", ref]);
+      body = { prompt: cast<never>(p.PromptId) };
+    } else if (bodyKeys.length === 1) return undefined;
+    entries.push(
+      ["timeoutSeconds", timeoutSeconds],
+      [
+        "branches",
+        new ArrV(
+          branches.map(
+            (b) =>
+              new ObjV([
+                ["digit", b.digit],
+                ["target", b.target as string],
+              ]),
+          ),
+        ),
+      ],
+      ["onTimeout", onTimeout],
+      ["onNoMatch", onNoMatch],
+      ["onError", onError],
+    );
+    return {
+      cls: "GetParticipantInput",
+      entries,
+      block: new GetParticipantInput({
+        id: a.Identifier,
+        ...body,
+        timeoutSeconds,
+        branches,
+        onTimeout,
+        onNoMatch,
+        onError,
+      }),
+    };
+  },
+
+  [ActionType.DisconnectParticipant]: (a) =>
+    terminal(a, () => new DisconnectParticipant({ id: a.Identifier })),
+  [ActionType.EndFlowExecution]: (a) =>
+    terminal(a, () => new EndFlowExecution({ id: a.Identifier })),
+  [ActionType.EndFlowModuleExecution]: (a) =>
+    terminal(a, () => new EndFlowModuleExecution({ id: a.Identifier })),
+
+  [ActionType.CheckHoursOfOperation]: (a, ctx) => {
+    const t = a.Transitions;
+    const errors = t.Errors ?? [];
+    const conditions = t.Conditions ?? [];
+    if (errors.length !== 1 || errors[0]!.ErrorType !== NO_MATCHING_ERROR) return undefined;
+    if (conditions.length !== 2) return undefined;
+    const [inHours, outOfHours] = conditions;
+    if (stableJson(inHours!.Condition) !== stableJson({ Operator: "Equals", Operands: ["True"] })) {
+      return undefined;
+    }
+    if (
+      stableJson(outOfHours!.Condition) !== stableJson({ Operator: "Equals", Operands: ["False"] })
+    ) {
+      return undefined;
+    }
+    // The class mirrors NextAction onto the out-of-hours path.
+    if (t.NextAction !== outOfHours!.NextAction) return undefined;
+    if (!paramKeysAre(a.Parameters, [], ["HoursOfOperationId"])) return undefined;
+    const entries: [string, V][] = [["id", a.Identifier]];
+    let hours: string | undefined;
+    if ("HoursOfOperationId" in a.Parameters) {
+      const ref = refSource(a.Parameters.HoursOfOperationId, "hours", ctx);
+      if (ref === undefined) return undefined;
+      entries.push(["hours", ref]);
+      hours = cast<string>(a.Parameters.HoursOfOperationId);
+    }
+    entries.push(
+      ["onInHours", inHours!.NextAction],
+      ["onOutOfHours", outOfHours!.NextAction],
+      ["onError", errors[0]!.NextAction],
+    );
+    return {
+      cls: "CheckHoursOfOperation",
+      entries,
+      block: new CheckHoursOfOperation({
+        id: a.Identifier,
+        ...(hours === undefined ? {} : { hours: cast<never>(hours) }),
+        onInHours: inHours!.NextAction,
+        onOutOfHours: outOfHours!.NextAction,
+        onError: errors[0]!.NextAction,
+      }),
+    };
+  },
+
+  [ActionType.Compare]: (a, ctx) => {
+    const t = a.Transitions;
+    if (t.NextAction !== undefined) return undefined;
+    const errors = t.Errors ?? [];
+    if (errors.length !== 1 || errors[0]!.ErrorType !== NO_MATCHING_CONDITION) return undefined;
+    const conditions = t.Conditions ?? [];
+    if (conditions.length === 0 || !conditions.every(isCondition)) return undefined;
+    if (!paramKeysAre(a.Parameters, ["ComparisonValue"])) return undefined;
+    const value = a.Parameters.ComparisonValue;
+    if (typeof value !== "string" || !/^\$\.[A-Za-z0-9_$.[\]'-]+$/.test(value)) return undefined;
+    // The emitted config calls jsonPath(); record it so the import is present
+    // even when no other action pulls it in through refSource.
+    ctx.jsonPath = true;
+    const branches = conditions.map((c) => ({
+      operator: c.Condition.Operator,
+      operands: c.Condition.Operands,
+      target: c.NextAction,
+    }));
+    const entries: [string, V][] = [
+      ["id", a.Identifier],
+      ["value", new Raw(`jsonPath(${quoteString(value)})`)],
+      [
+        "branches",
+        new ArrV(
+          branches.map(
+            (b) =>
+              new ObjV([
+                ["operator", b.operator],
+                ["operands", new ArrV([...b.operands])],
+                ["target", b.target],
+              ]),
+          ),
+        ),
+      ],
+      ["onNoMatch", errors[0]!.NextAction],
+    ];
+    return {
+      cls: "Compare",
+      entries,
+      block: new Compare({
+        id: a.Identifier,
+        value: cast<never>(value),
+        branches,
+        onNoMatch: errors[0]!.NextAction,
+      }),
+    };
+  },
+
+  [ActionType.TransferToFlow]: (a, ctx) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined || !paramKeysAre(a.Parameters, ["ContactFlowId"])) return undefined;
+    const ref = refSource(a.Parameters.ContactFlowId, "flow", ctx);
+    if (ref === undefined) return undefined;
+    return {
+      cls: "TransferToFlow",
+      entries: [
+        ["id", a.Identifier],
+        ["flow", ref],
+        ["next", w.next],
+        ["onError", w.onError],
+      ],
+      block: new TransferToFlow({
+        id: a.Identifier,
+        flow: cast<never>(a.Parameters.ContactFlowId),
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+
+  [ActionType.UpdateContactTargetQueue]: (a, ctx) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined) return undefined;
+    const keys = Object.keys(a.Parameters);
+    if (keys.length !== 1 || (keys[0] !== "QueueId" && keys[0] !== "AgentId")) return undefined;
+    const field = keys[0];
+    const ref = refSource(a.Parameters[field], "queue", ctx);
+    if (ref === undefined) return undefined;
+    const prop = field === "QueueId" ? "queue" : "agent";
+    return {
+      cls: "UpdateContactTargetQueue",
+      entries: [
+        ["id", a.Identifier],
+        [prop, ref],
+        ["next", w.next],
+        ["onError", w.onError],
+      ],
+      block: new UpdateContactTargetQueue(
+        cast<never>({
+          id: a.Identifier,
+          [prop]: a.Parameters[field],
+          next: w.next,
+          onError: w.onError,
+        }),
+      ),
+    };
+  },
+
+  [ActionType.TransferContactToQueue]: (a) => {
+    const t = a.Transitions;
+    if (Object.keys(a.Parameters).length !== 0) return undefined;
+    if (t.NextAction === undefined || (t.Conditions ?? []).length !== 0) return undefined;
+    const errors = t.Errors ?? [];
+    if (
+      errors.length !== 2 ||
+      errors[0]!.ErrorType !== "QueueAtCapacity" ||
+      errors[1]!.ErrorType !== NO_MATCHING_ERROR
+    ) {
+      return undefined;
+    }
+    return {
+      cls: "TransferContactToQueue",
+      entries: [
+        ["id", a.Identifier],
+        ["next", t.NextAction],
+        ["onQueueAtCapacity", errors[0]!.NextAction],
+        ["onError", errors[1]!.NextAction],
+      ],
+      block: new TransferContactToQueue({
+        id: a.Identifier,
+        next: t.NextAction,
+        onQueueAtCapacity: errors[0]!.NextAction,
+        onError: errors[1]!.NextAction,
+      }),
+    };
+  },
+
+  [ActionType.UpdateContactAttributes]: (a) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined) return undefined;
+    if (!paramKeysAre(a.Parameters, ["Attributes", "TargetContact"])) return undefined;
+    const attributes = a.Parameters.Attributes;
+    const target = a.Parameters.TargetContact;
+    if (!isStringMap(attributes)) return undefined;
+    if (target !== "Current" && target !== "Related") return undefined;
+    const entries: [string, V][] = [
+      ["id", a.Identifier],
+      ["attributes", toV(attributes)],
+    ];
+    if (target === "Related") entries.push(["targetContact", "Related"]);
+    entries.push(["next", w.next], ["onError", w.onError]);
+    return {
+      cls: "UpdateContactAttributes",
+      entries,
+      block: new UpdateContactAttributes({
+        id: a.Identifier,
+        attributes,
+        ...(target === "Related" ? { targetContact: target } : {}),
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+
+  [ActionType.UpdateContactRecordingBehavior]: (a) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined || !paramKeysAre(a.Parameters, ["RecordingBehavior"])) return undefined;
+    const rb = a.Parameters.RecordingBehavior as Record<string, unknown> | null;
+    if (rb === null || typeof rb !== "object" || Array.isArray(rb)) return undefined;
+    if (
+      !paramKeysAre(
+        rb,
+        ["RecordedParticipants"],
+        ["ScreenRecordedParticipants", "IVRRecordingBehavior"],
+      )
+    ) {
+      return undefined;
+    }
+    const recorded = rb.RecordedParticipants;
+    if (!Array.isArray(recorded) || !recorded.every((p) => p === "Agent" || p === "Customer")) {
+      return undefined;
+    }
+    const entries: [string, V][] = [
+      ["id", a.Identifier],
+      ["recordedParticipants", new ArrV([...recorded])],
+    ];
+    const screen = rb.ScreenRecordedParticipants;
+    if (screen !== undefined) {
+      if (!Array.isArray(screen) || !screen.every((p) => p === "Agent")) return undefined;
+      entries.push(["screenRecordedParticipants", new ArrV([...screen])]);
+    }
+    const ivr = rb.IVRRecordingBehavior;
+    if (ivr !== undefined) {
+      if (ivr !== "Enabled" && ivr !== "Disabled") return undefined;
+      entries.push(["ivrRecordingBehavior", ivr]);
+    }
+    entries.push(["next", w.next], ["onError", w.onError]);
+    return {
+      cls: "UpdateContactRecordingBehavior",
+      entries,
+      block: new UpdateContactRecordingBehavior({
+        id: a.Identifier,
+        recordedParticipants: cast<never>(recorded),
+        ...(screen === undefined ? {} : { screenRecordedParticipants: cast<never>(screen) }),
+        ...(ivr === undefined ? {} : { ivrRecordingBehavior: ivr }),
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+
+  [ActionType.InvokeFlowModule]: (a, ctx) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined || !paramKeysAre(a.Parameters, ["FlowModuleId"])) return undefined;
+    const ref = refSource(a.Parameters.FlowModuleId, "module", ctx);
+    if (ref === undefined) return undefined;
+    return {
+      cls: "InvokeFlowModule",
+      entries: [
+        ["id", a.Identifier],
+        ["module", ref],
+        ["next", w.next],
+        ["onError", w.onError],
+      ],
+      block: new InvokeFlowModule({
+        id: a.Identifier,
+        module: cast<never>(a.Parameters.FlowModuleId),
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+
+  [ActionType.InvokeLambdaFunction]: (a, ctx) => {
+    const w = wiredTransitions(a.Transitions, NO_MATCHING_ERROR);
+    if (w === undefined) return undefined;
+    const p = a.Parameters;
+    if (
+      !paramKeysAre(
+        p,
+        ["LambdaFunctionARN", "InvocationTimeLimitSeconds", "InvocationType"],
+        ["LambdaInvocationAttributes", "ResponseValidation"],
+      )
+    ) {
+      return undefined;
+    }
+    const ref = refSource(p.LambdaFunctionARN, "lambda", ctx);
+    if (ref === undefined) return undefined;
+    const timeout = p.InvocationTimeLimitSeconds;
+    if (typeof timeout !== "number") return undefined;
+    const invocationType = p.InvocationType;
+    if (invocationType !== "SYNCHRONOUS" && invocationType !== "ASYNCHRONOUS") return undefined;
+    const entries: [string, V][] = [
+      ["id", a.Identifier],
+      ["lambda", ref],
+      ["timeoutSeconds", timeout],
+    ];
+    if (invocationType === "ASYNCHRONOUS") entries.push(["invocationType", invocationType]);
+    const attributes = p.LambdaInvocationAttributes;
+    if (attributes !== undefined) {
+      if (!isStringMap(attributes)) return undefined;
+      entries.push(["attributes", toV(attributes)]);
+    }
+    let responseType: "STRING_MAP" | "JSON" | undefined;
+    if (p.ResponseValidation !== undefined) {
+      const rv = p.ResponseValidation as Record<string, unknown> | null;
+      if (rv === null || typeof rv !== "object" || !paramKeysAre(rv, ["ResponseType"])) {
+        return undefined;
+      }
+      if (rv.ResponseType !== "STRING_MAP" && rv.ResponseType !== "JSON") return undefined;
+      responseType = rv.ResponseType;
+      entries.push(["responseType", responseType]);
+    }
+    entries.push(["next", w.next], ["onError", w.onError]);
+    return {
+      cls: "InvokeLambdaFunction",
+      entries,
+      block: new InvokeLambdaFunction({
+        id: a.Identifier,
+        lambda: cast<never>(p.LambdaFunctionARN),
+        timeoutSeconds: timeout,
+        ...(invocationType === "ASYNCHRONOUS" ? { invocationType } : {}),
+        ...(attributes === undefined
+          ? {}
+          : { attributes: cast<Record<string, string>>(attributes) }),
+        ...(responseType === undefined ? {} : { responseType }),
+        next: w.next,
+        onError: w.onError,
+      }),
+    };
+  },
+};
+
+function invertGeneric(a: FlowAction): Inversion {
+  const entries: [string, V][] = [
+    ["id", a.Identifier],
+    ["type", a.Type],
+  ];
+  const cfg: GenericBlockConfig = { id: a.Identifier, type: a.Type };
+  // Connect omits Parameters and could omit Transitions on an action that has
+  // none, and a document read off disk is not guaranteed to have been through
+  // export's normalization. GenericBlock itself already defaults both, so
+  // matching it here keeps an unmodeled action degrading rather than throwing
+  // "Cannot convert undefined or null to object".
+  const parameters = a.Parameters ?? {};
+  if (Object.keys(parameters).length > 0) {
+    entries.push(["parameters", toV(parameters)]);
+    cfg.parameters = parameters;
+  }
+  const t = a.Transitions ?? {};
+  if (t.NextAction !== undefined) {
+    entries.push(["next", t.NextAction]);
+    cfg.next = t.NextAction;
+  }
+  const errors = t.Errors ?? [];
+  if (errors.length > 0) {
+    entries.push([
+      "errors",
+      new ArrV(
+        errors.map(
+          (e: ErrorTransition) =>
+            new ObjV([
+              ["errorType", e.ErrorType],
+              ["target", e.NextAction],
+            ]),
+        ),
+      ),
+    ]);
+    cfg.errors = errors.map((e) => ({ errorType: e.ErrorType, target: e.NextAction }));
+  }
+  const conditions = t.Conditions ?? [];
+  if (conditions.length > 0) {
+    entries.push([
+      "conditions",
+      new ArrV(
+        conditions.map(
+          (c) =>
+            new ObjV([
+              ["target", c.NextAction],
+              ["operator", c.Condition.Operator],
+              ["operands", new ArrV([...c.Condition.Operands])],
+            ]),
+        ),
+      ),
+    ]);
+    cfg.conditions = conditions.map((c) => ({
+      target: c.NextAction,
+      operator: c.Condition.Operator,
+      operands: c.Condition.Operands,
+    }));
+  }
+  return { cls: "GenericBlock", entries, block: new GenericBlock(cfg) };
+}
+
+/** Exact inversion or the GenericBlock fallback; never lossy. */
+function invertAction(a: FlowAction, ctx: Ctx): Inversion {
+  const inverter = INVERTERS[a.Type];
+  if (inverter !== undefined) {
+    try {
+      const scratch: Ctx = { refs: false, jsonPath: false };
+      const candidate = inverter(a, scratch);
+      if (candidate !== undefined && stableJson(candidate.block.toAction()) === stableJson(a)) {
+        ctx.refs = ctx.refs || scratch.refs;
+        ctx.jsonPath = ctx.jsonPath || scratch.jsonPath;
+        return candidate;
+      }
+    } catch {
+      // Constructor validation rejected the shape; fall through to generic.
+    }
+  }
+  return invertGeneric(a);
+}
+
+// ---------------------------------------------------------------------------
+// @keep comments
+// ---------------------------------------------------------------------------
+
+interface KeepComments {
+  beforeExport: string[];
+  beforeBlock: Map<string, string[]>;
+}
+
+const NEW_BLOCK = /^new [A-Za-z_$][A-Za-z0-9_$]*\(\{/;
+const BLOCK_ID = /\bid: (["'])((?:[^"'\\]|\\.)*)\1/;
+
+function extractKeepComments(previous: string): KeepComments {
+  const out: KeepComments = { beforeExport: [], beforeBlock: new Map() };
+  const lines = previous.split("\n");
+  let pending: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i]!.trim();
+    if (trimmed.startsWith("//")) {
+      pending.push(trimmed);
+      continue;
+    }
+    const keeps = pending.filter((l) => l.includes("@keep"));
+    pending = [];
+    if (keeps.length === 0) continue;
+    if (trimmed.startsWith("export function ")) {
+      out.beforeExport = keeps;
+    } else if (NEW_BLOCK.test(trimmed)) {
+      // The id property is on this line or within the next few.
+      for (let j = i; j < Math.min(i + 5, lines.length); j++) {
+        const m = BLOCK_ID.exec(lines[j]!);
+        if (m !== null) {
+          out.beforeBlock.set(m[2]!, keeps);
+          break;
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Naming
+// ---------------------------------------------------------------------------
+
+const RESERVED_WORDS = new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+]);
+
+/**
+ * The exported factory's name: camelCase of the flow name, prefixed with
+ * "flow" when it would start with a digit, hit a reserved word, or collide
+ * with an identifier the file imports (a flow named "json-path" must not emit
+ * `export function jsonPath` next to `import { jsonPath }`).
+ */
+export function factoryName(name: string, taken: ReadonlySet<string> = new Set()): string {
+  const parts = name.split(/[^A-Za-z0-9]+/).filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error(`Cannot derive a factory name from flow name "${name}".`);
+  }
+  let candidate = parts.map((p, i) => (i === 0 ? p : p[0]!.toUpperCase() + p.slice(1))).join("");
+  while (/^[0-9]/.test(candidate) || RESERVED_WORDS.has(candidate) || taken.has(candidate)) {
+    candidate = `flow${candidate[0]!.toUpperCase()}${candidate.slice(1)}`;
+  }
+  return candidate;
+}
+
+// ---------------------------------------------------------------------------
+// Assembly
+// ---------------------------------------------------------------------------
+
+function flowConfigEntries(doc: FlowDoc): [string, V][] {
+  const entries: [string, V][] = [["name", doc.name]];
+  if (doc.kind !== "module") entries.push(["connectType", doc.connectType]);
+  // A module's empty Settings is synth's default, so it is not worth emitting;
+  // a non-empty one must be, or synth would re-default it and the round trip
+  // would silently lose module configuration.
+  const settings = doc.content.Settings;
+  if (doc.kind === "module" && settings !== undefined && Object.keys(settings).length > 0) {
+    entries.push(["settings", toV(settings)]);
+  }
+  const first = doc.content.Actions[0];
+  if (first !== undefined && doc.content.StartAction !== first.Identifier) {
+    entries.push(["start", doc.content.StartAction]);
+  }
+  // Layout equal to deterministic auto-layout is a derivable default; only
+  // hand-placed positions are worth carrying in source. Either way
+  // synth(codegen(doc)) reproduces doc.layout.
+  if (doc.layout !== undefined) {
+    const auto = autoLayout(doc.content.Actions);
+    if (stableJson(doc.layout) !== stableJson(auto)) {
+      const layoutEntries = Object.keys(doc.layout)
+        .sort()
+        .map((id): [string, V] => {
+          const p = doc.layout![id] as Point;
+          return [
+            id,
+            new ObjV([
+              ["x", p.x],
+              ["y", p.y],
+            ]),
+          ];
+        });
+      entries.push(["layout", new ObjV(layoutEntries)]);
+    }
+  }
+  return entries;
+}
+
+function renderBlock(inv: Inversion, indent: string): string {
+  const head = `new ${inv.cls}(`;
+  if (inv.entries.length === 1) {
+    const flat = inlineV(new ObjV(inv.entries));
+    if (flat !== undefined && indent.length + head.length + flat.length + 2 <= PRINT_WIDTH) {
+      return `${head}${flat})`;
+    }
+  }
+  return `${head}${printBrokenObject(inv.entries, indent)})`;
+}
+
+/** A block's single-line form, or undefined when it must break. */
+function inlineBlock(inv: Inversion): string | undefined {
+  if (inv.entries.length !== 1) return undefined;
+  const flat = inlineV(new ObjV(inv.entries));
+  return flat === undefined ? undefined : `new ${inv.cls}(${flat})`;
+}
+
+export function codegen(doc: FlowDoc, options: CodegenOptions = {}): string {
+  assertFlowDoc(doc, "codegen");
+  if (doc.kind === "module" && doc.connectType !== "MODULE") {
+    throw new Error(`FlowDoc kind "module" requires connectType MODULE, got ${doc.connectType}.`);
+  }
+  if (doc.content.Actions.length === 0) {
+    throw new Error(`Flow "${doc.name}" has no actions; nothing to generate.`);
+  }
+  const spec = options.moduleSpecifier ?? DEFAULT_MODULE_SPECIFIER;
+  const keep =
+    options.previous === undefined
+      ? { beforeExport: [], beforeBlock: new Map<string, string[]>() }
+      : extractKeepComments(options.previous);
+
+  const ctx: Ctx = { refs: false, jsonPath: false };
+  const inversions = doc.content.Actions.map((a) => invertAction(a, ctx));
+
+  const flowClass = doc.kind === "module" ? "FlowModule" : "Flow";
+  const imports = new Set<string>([flowClass, ...inversions.map((i) => i.cls)]);
+  if (ctx.refs) imports.add("Refs");
+  if (ctx.jsonPath) imports.add("jsonPath");
+  const names = [...imports].sort();
+
+  const importInline = `import { ${names.join(", ")} } from ${quoteString(spec)};`;
+  const importSource =
+    importInline.length <= PRINT_WIDTH
+      ? importInline
+      : `import {\n${names.map((n) => `  ${n},`).join("\n")}\n} from ${quoteString(spec)};`;
+
+  const fn = factoryName(doc.name, imports);
+  const cfgEntries = flowConfigEntries(doc);
+
+  // The whole return statement collapses to one line when Prettier would:
+  // every argument fits inline and the line stays within the print width.
+  const cfgInline = inlineV(new ObjV(cfgEntries));
+  const argInlines = inversions.map(inlineBlock);
+  const hasBlockComments = inversions.some((i) => keep.beforeBlock.has(i.block.id));
+  let body: string;
+  const oneLine =
+    cfgInline === undefined || argInlines.some((a) => a === undefined)
+      ? undefined
+      : `  return new ${flowClass}(${cfgInline}).add(${argInlines.join(", ")});`;
+  if (oneLine !== undefined && oneLine.length <= PRINT_WIDTH && !hasBlockComments) {
+    body = oneLine;
+  } else {
+    const openInline =
+      cfgInline === undefined ? undefined : `  return new ${flowClass}(${cfgInline}).add(`;
+    const open =
+      openInline !== undefined && openInline.length <= PRINT_WIDTH
+        ? openInline
+        : `  return new ${flowClass}(${printBrokenObject(cfgEntries, "  ")}).add(`;
+    const args: string[] = [];
+    for (const inv of inversions) {
+      for (const c of keep.beforeBlock.get(inv.block.id) ?? []) args.push(`    ${c}`);
+      args.push(`    ${renderBlock(inv, "    ")},`);
+    }
+    body = `${open}\n${args.join("\n")}\n  );`;
+  }
+
+  const lines: string[] = [...generatedMarker(doc.name), "", importSource, ""];
+  for (const c of keep.beforeExport) lines.push(c);
+  lines.push(`export function ${fn}(): ${flowClass} {`, body, "}");
+  return lines.join("\n") + "\n";
+}