@flow-as-code/core 0.1.0

package/src/flow.ts

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Flow and FlowModule: an ordered set of blocks plus the metadata that says
+// what kind of Connect artifact they become.
+
+import { Block, targetId } from "./blocks.js";
+import type { ConnectType } from "./flowdoc.js";
+import { InvalidFlowDocError, MAX_ACTIONS_PER_FLOW, SLUG_PATTERN } from "./flowdoc.js";
+import type { Point } from "./flowdoc.js";
+
+export interface FlowConfig {
+  name: string;
+  connectType?: ConnectType;
+  /** Defaults to the first block added. */
+  start?: string | Block;
+  /** Hand-placed positions. Anything omitted is auto-laid-out at synth time. */
+  layout?: Record<string, Point>;
+}
+
+export class Flow {
+  readonly name: string;
+  readonly connectType: ConnectType;
+  readonly kind: "flow" | "module" = "flow";
+  readonly layout: Record<string, Point>;
+  private readonly blocks: Block[] = [];
+  private readonly explicitStart?: string;
+
+  constructor(config: FlowConfig) {
+    // Names are slugs (the FlowDoc schema requires it), and they become file
+    // names downstream (`<name>.flowdoc.json`), so anything else, including a
+    // path fragment, is rejected here rather than at write time.
+    if (!SLUG_PATTERN.test(config.name)) {
+      throw new Error(
+        `Invalid flow name "${config.name}". Names must be lowercase words separated by single hyphens.`,
+      );
+    }
+    this.name = config.name;
+    this.connectType = config.connectType ?? "CONTACT_FLOW";
+    this.layout = config.layout ?? {};
+    if (config.start !== undefined) this.explicitStart = targetId(config.start);
+  }
+
+  /** Adds blocks in declaration order. Returns this for chaining. */
+  add(...blocks: Block[]): this {
+    for (const b of blocks) {
+      if (this.blocks.some((existing) => existing.id === b.id)) {
+        throw new Error(`Duplicate Identifier "${b.id}" in flow "${this.name}".`);
+      }
+      this.blocks.push(b);
+    }
+    if (this.blocks.length > MAX_ACTIONS_PER_FLOW) {
+      throw new Error(
+        `Flow "${this.name}" has ${this.blocks.length} actions; Connect allows at most ${MAX_ACTIONS_PER_FLOW}.`,
+      );
+    }
+    return this;
+  }
+
+  all(): readonly Block[] {
+    return this.blocks;
+  }
+
+  startId(): string {
+    if (this.explicitStart !== undefined) return this.explicitStart;
+    const first = this.blocks[0];
+    if (first === undefined) throw new Error(`Flow "${this.name}" has no blocks.`);
+    return first.id;
+  }
+}
+
+/**
+ * Structural check that a value can be treated as a Flow, run at the entry
+ * points that take one. Structural rather than `instanceof` so a Flow built
+ * against a second copy of the package (a workspace link, two versions in a
+ * dependency tree) is still accepted.
+ */
+export function assertFlow(value: unknown, context: string): asserts value is Flow {
+  const flow = value as Partial<Flow> | null | undefined;
+  const ok =
+    typeof flow === "object" &&
+    flow !== null &&
+    typeof flow.all === "function" &&
+    typeof flow.startId === "function" &&
+    typeof flow.name === "string" &&
+    typeof flow.connectType === "string" &&
+    typeof flow.layout === "object" &&
+    flow.layout !== null;
+  if (!ok) {
+    const got = value === null ? "null" : Array.isArray(value) ? "an array" : `a ${typeof value}`;
+    throw new InvalidFlowDocError(
+      `${context} expects a Flow built with new Flow(...) or new FlowModule(...), got ${got}.`,
+    );
+  }
+}
+
+/** A reusable section of a flow. Materializes as a ContactFlowModule. */
+export class FlowModule extends Flow {
+  override readonly kind = "module" as const;
+  /** Module configuration, emitted as content.Settings. Empty by default. */
+  readonly settings: Record<string, unknown>;
+
+  constructor(config: Omit<FlowConfig, "connectType"> & { settings?: Record<string, unknown> }) {
+    super({ ...config, connectType: "MODULE" });
+    this.settings = config.settings ?? {};
+  }
+}

package/src/flowdoc.ts

@@ -0,0 +1,261 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// FlowDoc: the single interchange format. See docs/01-flowdoc-spec.md and
+// conformance/schema/flowdoc-0.1.schema.json, which is the normative form of
+// these types.
+
+export const FLOWDOC_VERSION = "0.1";
+
+/** The only Flow language version Connect supports. */
+export const FLOW_LANGUAGE_VERSION = "2019-10-30";
+
+/** A single flow holds no more than 250 Actions. */
+export const MAX_ACTIONS_PER_FLOW = 250;
+
+/** Identifiers are unique within a flow and at most 50 characters. */
+export const MAX_IDENTIFIER_LENGTH = 50;
+
+/**
+ * Characters Connect rejects in an Identifier.
+ * https://docs.aws.amazon.com/connect/latest/devguide/flow-language-actions.html
+ */
+export const FORBIDDEN_IDENTIFIER_CHARS = [
+  "%",
+  ":",
+  "(",
+  "\\",
+  "/",
+  ")",
+  "=",
+  "$",
+  ",",
+  ";",
+  "[",
+  "]",
+  "{",
+  "}",
+] as const;
+
+/** Identifier values Connect rejects outright (prototype pollution names). */
+export const FORBIDDEN_IDENTIFIERS = [
+  "__proto__",
+  "constructor",
+  "__defineGetter__",
+  "__defineSetter__",
+  "toString",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "valueOf",
+] as const;
+
+export type ConnectType =
+  | "CONTACT_FLOW"
+  | "CUSTOMER_QUEUE"
+  | "CUSTOMER_HOLD"
+  | "CUSTOMER_WHISPER"
+  | "AGENT_HOLD"
+  | "AGENT_WHISPER"
+  | "OUTBOUND_WHISPER"
+  | "AGENT_TRANSFER"
+  | "QUEUE_TRANSFER"
+  | "MODULE";
+
+export type ConditionOperator =
+  | "Equals"
+  | "TextStartsWith"
+  | "TextEndsWith"
+  | "TextContains"
+  | "NumberGreaterThan"
+  | "NumberGreaterOrEqualTo"
+  | "NumberLessThan"
+  | "NumberLessOrEqualTo";
+
+export interface Condition {
+  Operator: ConditionOperator;
+  Operands: string[];
+}
+
+export interface ErrorTransition {
+  ErrorType: string;
+  NextAction: string;
+}
+
+export interface ConditionTransition {
+  NextAction: string;
+  Condition: Condition;
+}
+
+export interface Transitions {
+  NextAction?: string;
+  Errors?: ErrorTransition[];
+  Conditions?: ConditionTransition[];
+}
+
+export interface FlowAction {
+  Identifier: string;
+  Type: string;
+  Parameters: Record<string, unknown>;
+  Transitions: Transitions;
+}
+
+export interface FlowContent {
+  Version: typeof FLOW_LANGUAGE_VERSION;
+  StartAction: string;
+  /**
+   * Not authored. Materialization projects `layout` into this so the flow lays
+   * out correctly in the Connect console. See docs/01-flowdoc-spec.md.
+   */
+  Metadata?: Record<string, unknown>;
+  /**
+   * Module configuration. Connect requires a top-level `Settings` object in a
+   * flow MODULE's content and rejects CreateContactFlowModule without it
+   * ("JSON field is missing or null for field name: settings"); a regular flow
+   * has no Settings. Empty is valid and is what the console stores for a module
+   * with no special configuration. Verified against a live instance 2026-09-01.
+   */
+  Settings?: Record<string, unknown>;
+  Actions: FlowAction[];
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type RefType = "queue" | "hours" | "lambda" | "lex" | "prompt" | "flow" | "module";
+
+export interface RefEntry {
+  token: string;
+  type: RefType;
+  name: string;
+  alias?: string;
+}
+
+export interface FlowDocMeta {
+  generator?: string;
+  sourceHash?: string;
+  [key: string]: unknown;
+}
+
+export interface FlowDoc {
+  flowdoc: typeof FLOWDOC_VERSION;
+  kind: "flow" | "module";
+  name: string;
+  connectType: ConnectType;
+  content: FlowContent;
+  layout?: Record<string, Point>;
+  refs?: RefEntry[];
+  meta?: FlowDocMeta;
+}
+
+/** Names are slugs: lowercase, digits, single hyphens. */
+export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export function isValidIdentifier(id: string): boolean {
+  if (id.length === 0 || id.length > MAX_IDENTIFIER_LENGTH) return false;
+  if ((FORBIDDEN_IDENTIFIERS as readonly string[]).includes(id)) return false;
+  return !FORBIDDEN_IDENTIFIER_CHARS.some((c) => id.includes(c));
+}
+
+// ---------------------------------------------------------------------------
+// Entry-point guard
+// ---------------------------------------------------------------------------
+
+/**
+ * A public entry point was handed something that is not a usable FlowDoc.
+ *
+ * Without this, the first property access decided the message, so calling
+ * `codegen(undefined)` or linting a document with no `content` reported
+ * "Cannot read properties of undefined (reading 'Actions')", which names
+ * neither the entry point, the argument, nor what was wrong with it.
+ */
+export class InvalidFlowDocError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidFlowDocError";
+  }
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "string") return `a string (${JSON.stringify(value)})`;
+  return `a ${typeof value}`;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Structural check that a value can be treated as a FlowDoc, run at every
+ * public entry point that reads one.
+ *
+ * Deliberately shallow: it checks the shape the library dereferences without
+ * asking, not the FlowDoc schema. Full validation is
+ * conformance/schema/flowdoc-0.1.schema.json, which `flow-cli lint` runs;
+ * doing it here would make every entry point pay for an Ajv compile and would
+ * reject documents the studio legitimately holds mid-edit.
+ *
+ * @param context the entry point name, so the message says who was called.
+ */
+export function assertFlowDoc(value: unknown, context: string): asserts value is FlowDoc {
+  if (!isPlainObject(value)) {
+    throw new InvalidFlowDocError(`${context} expects a FlowDoc object, got ${typeName(value)}.`);
+  }
+  for (const key of ["name", "kind", "connectType"] as const) {
+    if (typeof value[key] !== "string") {
+      throw new InvalidFlowDocError(
+        `${context} expects a FlowDoc with a string "${key}", got ${typeName(value[key])}.`,
+      );
+    }
+  }
+  const content = value.content;
+  if (!isPlainObject(content)) {
+    throw new InvalidFlowDocError(
+      `${context} expects a FlowDoc with an object "content", got ${typeName(content)}.`,
+    );
+  }
+  if (typeof content.StartAction !== "string") {
+    throw new InvalidFlowDocError(
+      `${context} expects a FlowDoc with a string "content.StartAction", got ${typeName(
+        content.StartAction,
+      )}.`,
+    );
+  }
+  const actions = content.Actions;
+  if (!Array.isArray(actions)) {
+    throw new InvalidFlowDocError(
+      `${context} expects a FlowDoc with an array "content.Actions", got ${typeName(actions)}.`,
+    );
+  }
+  for (const [i, action] of actions.entries()) {
+    const at = `${context}: FlowDoc content.Actions[${String(i)}]`;
+    if (!isPlainObject(action)) {
+      throw new InvalidFlowDocError(`${at} must be an action object, got ${typeName(action)}.`);
+    }
+    for (const key of ["Identifier", "Type"] as const) {
+      if (typeof action[key] !== "string") {
+        throw new InvalidFlowDocError(
+          `${at} must have a string "${key}", got ${typeName(action[key])}.`,
+        );
+      }
+    }
+    // Parameters and Transitions are dereferenced without a guard by codegen,
+    // materialization, and several lint rules.
+    for (const key of ["Parameters", "Transitions"] as const) {
+      if (!isPlainObject(action[key])) {
+        throw new InvalidFlowDocError(
+          `${at} ("${String(action.Identifier)}") must have an object "${key}", got ${typeName(
+            action[key],
+          )}.`,
+        );
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Public surface of @flow-as-code/core. See SPEC.md and docs/01-flowdoc-spec.md.
+//
+// Implemented: FlowDoc types, Refs, builder blocks, deterministic
+// serialization, dagre auto-layout, synth, lint, codegen, materialization,
+// export from a live instance, and the simulate scenario format, runner, and
+// reporters. Watch (A04) lives in @flow-as-code/cli.
+
+export * from "./flowdoc.js";
+export * from "./refs.js";
+export * from "./actions.js";
+export * from "./blocks.js";
+export * from "./flow.js";
+export * from "./synth.js";
+export * from "./codegen.js";
+export * from "./package-names.js";
+export { autoLayout, NODE_WIDTH, NODE_HEIGHT } from "./layout.js";
+export { canonicalize, serialize } from "./serialize.js";
+export {
+  MaterializeError,
+  materializeWithBinder,
+  materializeWithMap,
+  serializeContent,
+} from "./materialize.js";
+export * from "./aws.js";
+export * from "./export.js";
+export * from "./simulate.js";
+export * from "./lint/index.js";

package/src/layout.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Deterministic auto-layout. The studio persists user positions; synth fills in
+// positions only for actions that have none, so hand-placed nodes survive.
+
+import dagre from "dagre";
+import type { FlowAction, Point } from "./flowdoc.js";
+
+/** Node box used for layout. Matches the studio's default node size. */
+export const NODE_WIDTH = 180;
+export const NODE_HEIGHT = 60;
+
+function transitionTargets(action: FlowAction): string[] {
+  const t = action.Transitions;
+  return [
+    ...(t.NextAction === undefined ? [] : [t.NextAction]),
+    ...(t.Errors ?? []).map((e) => e.NextAction),
+    ...(t.Conditions ?? []).map((c) => c.NextAction),
+  ];
+}
+
+/**
+ * Left-to-right dagre layout. Deterministic for a given action list: dagre is
+ * seeded only by insertion order, and actions are already in canonical order by
+ * the time this runs.
+ */
+export function autoLayout(actions: FlowAction[]): Record<string, Point> {
+  const g = new dagre.graphlib.Graph();
+  g.setGraph({ rankdir: "LR", nodesep: 40, ranksep: 80, marginx: 20, marginy: 20 });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  const ids = new Set(actions.map((a) => a.Identifier));
+  for (const a of actions) g.setNode(a.Identifier, { width: NODE_WIDTH, height: NODE_HEIGHT });
+  for (const a of actions) {
+    for (const target of transitionTargets(a)) {
+      // Dangling targets are a lint finding, not a layout crash.
+      if (ids.has(target)) g.setEdge(a.Identifier, target);
+    }
+  }
+
+  dagre.layout(g);
+
+  const positions: Record<string, Point> = {};
+  for (const a of actions) {
+    const node = g.node(a.Identifier) as { x: number; y: number } | undefined;
+    // dagre reports centres; FlowDoc stores top-left, as the console does.
+    positions[a.Identifier] = node
+      ? { x: Math.round(node.x - NODE_WIDTH / 2), y: Math.round(node.y - NODE_HEIGHT / 2) }
+      : { x: 0, y: 0 };
+  }
+  return positions;
+}

package/src/lint/engine.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { FlowDoc } from "../flowdoc.js";
+import { assertFlowDoc } from "../flowdoc.js";
+import { allRules } from "./rules/index.js";
+import type { Finding, Rule } from "./types.js";
+
+export interface LintOptions {
+  /** Defaults to every built-in rule. */
+  rules?: readonly Rule[];
+  /** Rule ids to skip. */
+  disable?: readonly string[];
+}
+
+const order = (a: Finding, b: Finding): number =>
+  a.doc.localeCompare(b.doc) ||
+  a.rule.localeCompare(b.rule) ||
+  (a.blockId ?? "").localeCompare(b.blockId ?? "") ||
+  a.message.localeCompare(b.message);
+
+/**
+ * Runs every rule over every document. Findings are sorted so output is stable
+ * regardless of rule execution order.
+ */
+export function lint(input: FlowDoc | readonly FlowDoc[], options: LintOptions = {}): Finding[] {
+  const docs = Array.isArray(input) ? input : [input as FlowDoc];
+  // Rules read doc.content.Actions and doc.name directly. A malformed document
+  // used to surface as a TypeError from whichever rule happened to run first,
+  // which named neither lint nor the document.
+  for (const doc of docs) assertFlowDoc(doc, "lint");
+  const disabled = new Set(options.disable ?? []);
+  const rules = (options.rules ?? allRules).filter((r) => !disabled.has(r.id));
+
+  const findings: Finding[] = [];
+  for (const doc of docs) {
+    for (const rule of rules) {
+      rule.check({
+        doc,
+        all: docs,
+        report: (f) => findings.push({ ...f, rule: rule.id, doc: doc.name }),
+      });
+    }
+  }
+  return findings.sort(order);
+}
+
+/** True when any finding would block a studio save. */
+export function hasBlockingFindings(
+  findings: readonly Finding[],
+  rules: readonly Rule[] = allRules,
+): boolean {
+  const hard = new Set(rules.filter((r) => r.hard).map((r) => r.id));
+  return findings.some((f) => hard.has(f.rule));
+}

package/src/lint/graph.ts

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Shared traversal helpers. Browser-safe: no Node builtins.
+
+import type { FlowAction, FlowDoc } from "../flowdoc.js";
+
+export function transitionTargets(action: FlowAction): string[] {
+  const t = action.Transitions;
+  return [
+    ...(t.NextAction === undefined ? [] : [t.NextAction]),
+    ...(t.Errors ?? []).map((e) => e.NextAction),
+    ...(t.Conditions ?? []).map((c) => c.NextAction),
+  ];
+}
+
+export function isTerminal(action: FlowAction): boolean {
+  return Object.keys(action.Transitions).length === 0;
+}
+
+export function actionsById(doc: FlowDoc): Map<string, FlowAction> {
+  return new Map(doc.content.Actions.map((a) => [a.Identifier, a]));
+}
+
+/** Identifiers reachable from StartAction. */
+export function reachable(doc: FlowDoc): Set<string> {
+  const byId = actionsById(doc);
+  const seen = new Set<string>();
+  const queue = [doc.content.StartAction];
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    if (seen.has(id)) continue;
+    const action = byId.get(id);
+    if (action === undefined) continue;
+    seen.add(id);
+    queue.push(...transitionTargets(action));
+  }
+  return seen;
+}
+
+/** Walks every string in a value, yielding [jsonPath, value] pairs. */
+export function walkStrings(value: unknown, path = ""): [string, string][] {
+  if (typeof value === "string") return [[path, value]];
+  if (Array.isArray(value)) return value.flatMap((v, i) => walkStrings(v, `${path}[${i}]`));
+  if (value !== null && typeof value === "object") {
+    return Object.entries(value).flatMap(([k, v]) =>
+      walkStrings(v, path === "" ? k : `${path}.${k}`),
+    );
+  }
+  return [];
+}
+
+/**
+ * Every authored string in an action, with the path it sits at, for attributing
+ * a finding to a block.
+ *
+ * Transitions are included, not just Parameters. A condition operand is
+ * authored content like any other, and scanning only Parameters left a literal
+ * ARN or a malformed token in `Transitions.Conditions[n].Condition.Operands`
+ * completely undetected. Identifiers appearing here cannot produce false
+ * positives: Connect forbids ":" in an Identifier, so a NextAction can never
+ * look like an ARN or a token.
+ */
+/**
+ * Authored strings that belong to the document rather than to any one action:
+ * today that is `content.Metadata`.
+ *
+ * materialize carries Metadata into deployable output and resolves tokens in
+ * it, so it is authored content by any reasonable reading, but nothing scanned
+ * it. A literal ARN placed there passed every gate and reached both deploy
+ * paths, including @flow-as-code/cdk, which refuses the identical ARN in Parameters.
+ */
+export function documentStrings(doc: FlowDoc): [string, string][] {
+  if (doc.content.Metadata === undefined) return [];
+  return walkStrings(doc.content.Metadata, "content.Metadata");
+}
+
+export function findingsForActions(
+  doc: FlowDoc,
+): { action: FlowAction; strings: [string, string][] }[] {
+  return doc.content.Actions.map((action) => ({
+    action,
+    strings: [...walkStrings(action.Parameters), ...walkStrings(action.Transitions, "Transitions")],
+  }));
+}

package/src/lint/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type { Finding, Rule, RuleContext, Severity } from "./types.js";
+export { lint, hasBlockingFindings } from "./engine.js";
+export type { LintOptions } from "./engine.js";
+export { toJson, toText } from "./reporters.js";
+export { allRules, ruleById } from "./rules/index.js";
+export { NO_LITERAL_ARN, literalArnMessage, literalArnPaths } from "./rules/index.js";

package/src/lint/reporters.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Finding } from "./types.js";
+
+/** Machine-readable. Stable shape; the CLI's --format json emits this. */
+export function toJson(findings: readonly Finding[]): string {
+  const errors = findings.filter((f) => f.severity === "error").length;
+  return (
+    JSON.stringify(
+      {
+        summary: { total: findings.length, errors, warnings: findings.length - errors },
+        findings,
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+/** Human-readable, one finding per line, grouped by document. */
+export function toText(findings: readonly Finding[]): string {
+  if (findings.length === 0) return "No findings.\n";
+
+  const lines: string[] = [];
+  let current = "";
+  for (const f of findings) {
+    if (f.doc !== current) {
+      if (current !== "") lines.push("");
+      lines.push(f.doc);
+      current = f.doc;
+    }
+    const where = f.blockId === undefined ? "" : ` (${f.blockId})`;
+    lines.push(`  ${f.severity}${where}: ${f.message} [${f.rule}]`);
+  }
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  lines.push("");
+  lines.push(
+    `${findings.length} finding(s): ${errors} error(s), ${findings.length - errors} warning(s).`,
+  );
+  return lines.join("\n") + "\n";
+}

package/src/lint/rules/action-allowed-in-flow-type.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FLOW_TYPE_RESTRICTIONS } from "../../actions.js";
+import type { Rule } from "../types.js";
+
+/**
+ * Almost every Connect action documents a Restrictions section naming the flow
+ * types it is legal in. Deploying a flow that violates one fails at create time
+ * with a message that does not say which block is at fault.
+ *
+ * Added 2026-08-31 from the A00b reference; not one of the original nine rules
+ * in SPEC.md. Restrictions live in actions.ts, sourced per action page.
+ */
+export const actionAllowedInFlowType: Rule = {
+  id: "action-allowed-in-flow-type",
+  description: "Each action must be legal in the flow type that contains it.",
+  check({ doc, report }) {
+    for (const action of doc.content.Actions) {
+      const allowed = FLOW_TYPE_RESTRICTIONS[action.Type];
+      if (allowed === undefined) continue;
+      if (!allowed.includes(doc.connectType)) {
+        report({
+          severity: "error",
+          blockId: action.Identifier,
+          message: `${action.Type} is not allowed in a ${doc.connectType} flow. Allowed: ${allowed.join(", ")}.`,
+        });
+      }
+    }
+  },
+};