@flow-as-code/cdk 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The flow-as-code Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,96 @@
+# @flow-as-code/cdk
+
+```
+npm i @flow-as-code/cdk
+```
+
+Apache-2.0, Node 22.12 or newer. Peers on `aws-cdk-lib` and `constructs`, both
+optional so a CLI-only install does not fetch them.
+
+CDK binding for `@flow-as-code/core`. Two exports, plus a scaffold generator on a subpath:
+
+- `TokenBinder`: an interface you implement, mapping reference names to construct attributes (`queue.attrQueueArn`, `fn.functionArn`, a Lex alias ARN). `@flow-as-code/core`'s `materializeWithBinder` inserts the returned strings byte-for-byte, so CDK tokens pass through and CloudFormation resolves them per account at deploy time. No resource map, no literal ARNs in this path.
+- `FlowSet`: a construct consuming a directory of `*.flowdoc.json` files (or `FlowDoc[]`) plus a `TokenBinder`. Flows become `AWS::Connect::ContactFlow` (type from `connectType`), modules become `AWS::Connect::ContactFlowModule`, created in dependency order.
+
+## Usage
+
+```ts
+import { FlowSet } from "@flow-as-code/cdk";
+
+new FlowSet(stack, "Flows", {
+  instanceArn: instance.attrArn,
+  source: "flows/", // or FlowDoc[]
+  binder: {
+    queue: (name) => queues[name].attrQueueArn,
+    hours: (name) => hours[name].attrHoursOfOperationArn,
+    lambda: (name) => fns[name].functionArn,
+    lex: (name) => lexAliases[name].attrBotAliasArn,
+    prompt: (name) => prompts[name].attrPromptArn,
+    // flow?: only needed when a doc uses ${cdref:flow:...}
+  },
+});
+```
+
+Module references (`${cdref:module:name@alias}`) are not the binder's job: `FlowSet` resolves them itself, to the alias ARN of the module it manages.
+
+## The scaffold (`@flow-as-code/cdk/scaffold`)
+
+Writing that stack by hand starts with the same file every time, so `cdkScaffold({ docs, source })` generates it: a `FlowStack` constructing a `FlowSet` over the FlowDoc directory, and a `TokenBinder` carrying one `TODO` per reference type the documents actually use, with the referenced names listed. Types the set does not use still get a method, because the interface requires them, but theirs throws instead of carrying a TODO.
+
+The subpath exists because two tools emit this file and must emit it identically: `flow-cli emit --target cdk` and the studio's CDK export button. It is pure and imports no node builtin, so the studio can bundle it for a browser; `source` is the FLOW_DOCS expression (`.`, `..`), which is the one thing that needs a path calculation, and `sourceForDepth` computes it where node's `path.relative` is unavailable. The emitted file resolves that expression against itself with `new URL(source, import.meta.url)`, so the stack reads the same directory whatever the CDK app's working directory is. Output is byte-stable and independent of the order the documents were read.
+
+## Peer dependencies
+
+`aws-cdk-lib ^2.267.0` and `constructs ^10.8.1`, both optional. A project that
+has them pinned below that floor gets an ERESOLVE from npm 7 and later rather
+than a silent mismatch; a project that has neither installs neither. The floor
+is deliberate: `FlowSet` builds `CfnContactFlowModuleVersion` and
+`CfnContactFlowModuleAlias` (see the versioning model below), which are recent
+additions to `aws-cdk-lib/aws-connect`, and 2.267 is the version this package is
+developed and tested against. Lowering it means finding the release that
+introduced both L1s and running the `aws-cdk-lib/assertions` tests against it,
+not just widening the range.
+
+They are optional because the CDK entry is not the only entry. `@flow-as-code/cli` and
+the studio reach this package for `@flow-as-code/cdk/scaffold` alone,
+which imports nothing but `@flow-as-code/core`: `aws-cdk-lib` appears in that module as a
+line of the stack source it generates, not as an import. Non-optional peers are
+auto-installed, so with these declared as ordinary peers every
+`npm install @flow-as-code/cli` would fetch 166 MB of CDK that nothing in that
+install loads. Importing `FlowSet` or the
+binder still needs both packages present, and `tests/packaging.test.ts` holds
+the scaffold subpath to its one bare import.
+
+The cost of optional is that npm says nothing at install time, so the package
+says it itself. Importing `@flow-as-code/cdk` with `aws-cdk-lib`
+absent throws:
+
+```
+@flow-as-code/cdk needs the CDK at runtime, but aws-cdk-lib is not
+installed. It and constructs are optional peers so that a CLI-only install
+stays small, which means npm does not warn about them at install time. Install
+them with: npm install aws-cdk-lib@^2.267.0 constructs@^10.8.1
+```
+
+The entry checks for the peer before it loads `FlowSet`, so this replaces the
+bare `ERR_MODULE_NOT_FOUND` that used to come out of `dist/flow-set.js`. The
+`./scaffold` subpath is unaffected and imports with no CDK installed.
+`src/index.test.ts` runs the entry in a directory with no `node_modules` and
+asserts the message, including the version floor read from `package.json`.
+
+## Versioning model
+
+- Modules are versioned. Each module gets an `AWS::Connect::ContactFlowModuleVersion` whose logical ID embeds a hash of the module's canonical content, so a content change publishes a new immutable version, plus an `AWS::Connect::ContactFlowModuleAlias` per alias name the doc set pins (default `live`) with a stable logical ID that repoints to the new version. Flows reference the alias ARN, so repointing changes no flow content.
+- Full flows are not versioned; content updates in place. Connect's `CreateContactFlowVersion` states "This API only supports creating versions for flows of type Campaign." (https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateContactFlowVersion.html, verified 2026-08-31)
+
+## Validation
+
+`FlowSet` refuses, at synth time: duplicate document names, `kind`/`connectType` mismatches, references to modules not in the set, module reference cycles, and any document failing a hard `@flow-as-code/core` lint rule (`no-literal-arn`, `no-unresolved-token`). Binder gaps fail with an error naming the token, the document, and the missing method.
+
+No instance/queue provisioning constructs here; users bring their own or use L1s.
+
+## Testing
+
+Offline tests assert on synthesized templates with `aws-cdk-lib/assertions`. The live-deploy test in `src/integration.test.ts` runs only when both `FLOW_TEST_INSTANCE_ARN` and `FLOW_TEST_DEPLOY=1` are set, deploys the demo flow plus a versioned module to that instance through the AWS CLI, and tears the stack down. It writes to the account, so naming an instance is not enough on its own: use an empty sandbox.
+
+That test has run green against a live Connect instance (2026-09-02). The test asserts only that the deploy exited zero, and it deletes the stack in its `finally`, so the content check was a separate step: the same synthesized template was deployed again and left up, and its flows were read back with `DescribeContactFlow` and `DescribeContactFlowModule` and compared against what the FlowDocs materialize to. That comparison is structural rather than byte-for-byte, because deploying resolves each `${cdref:...}` reference to a real ARN: every other position matched exactly, and the reference positions were checked against the stack's own resources instead, each resolving to a resource of the right kind and the module reference resolving to the alias rather than the version. The stack needs no CDK bootstrap: it is asset-free and uses `CliCredentialsStackSynthesizer`. `tasks/A07-flow-cdk.md` records both.

package/dist/binder.d.ts

@@ -0,0 +1,38 @@
+import type { RefEntry } from "@flow-as-code/core";
+/**
+ * Maps reference names to CloudFormation-token strings. Implemented by the
+ * user, typically as thin closures over constructs in the same stack.
+ *
+ * `flow` is optional because cross-flow references are rare; a doc set that
+ * uses `${cdref:flow:...}` against a binder without `flow()` fails synth with
+ * an error naming the token.
+ */
+/**
+ * Boundary worth knowing: a binder may return any opaque string and it passes
+ * through byte-exact, EXCEPT that CDK itself parses `${Token[...]}` markers.
+ * Returning a string containing an unregistered marker such as
+ * `${Token[TOKEN.999]}` fails deep inside aws-cdk-lib with "Unrecognized token
+ * key". Real tokens (Fn.importValue, attr getters) are registered and fine.
+ * This is CDK's behavior, not something this package can intercept.
+ */
+export interface TokenBinder {
+    /** ARN of the queue, e.g. `queue.attrQueueArn`. */
+    queue(name: string): string;
+    /** ARN of the hours of operation, e.g. `hours.attrHoursOfOperationArn`. */
+    hours(name: string): string;
+    /** ARN of the Lambda function, e.g. `fn.functionArn`. */
+    lambda(name: string): string;
+    /** ARN of the Lex bot alias. */
+    lex(name: string): string;
+    /** ARN of the prompt. */
+    prompt(name: string): string;
+    /** ARN of a contact flow not managed by this FlowSet. */
+    flow?(name: string): string;
+}
+/**
+ * Resolves one non-module reference through the binder. Throws a diagnostic
+ * naming the token, the document, and the missing method when the binder
+ * cannot answer, so the failure is actionable without a stack-trace dig.
+ */
+export declare function bindRef(binder: TokenBinder, ref: RefEntry, docName: string): string;
+//# sourceMappingURL=binder.d.ts.map

package/dist/binder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binder.d.ts","sourceRoot":"","sources":["../src/binder.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;GAOG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,yDAAyD;IACzD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,gCAAgC;IAChC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,yBAAyB;IACzB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,yDAAyD;IACzD,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAqBnF"}

package/dist/binder.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// TokenBinder: the user's side of CDK materialization.
+//
+// A binder maps each non-module reference in a FlowDoc to a string, normally a
+// CloudFormation token from an L1/L2 construct attribute (queue.attrQueueArn,
+// fn.functionArn, a Lex alias ARN). @flow-as-code/core's materializeWithBinder inserts
+// the returned string byte-for-byte, so CDK tokens survive untouched and
+// CloudFormation resolves them per account at deploy time. No resource map, no
+// literal ARNs in this path.
+//
+// Module references (`${cdref:module:name@alias}`) are deliberately absent:
+// FlowSet manages the module resources itself and resolves those tokens to the
+// alias ARN of the CfnContactFlowModuleAlias it created (see flow-set.ts).
+/**
+ * Resolves one non-module reference through the binder. Throws a diagnostic
+ * naming the token, the document, and the missing method when the binder
+ * cannot answer, so the failure is actionable without a stack-trace dig.
+ */
+export function bindRef(binder, ref, docName) {
+    if (ref.type === "module") {
+        // FlowSet resolves module refs itself; reaching here is a programming
+        // error in the caller, not a binder gap.
+        throw new Error(`Internal: module ref ${ref.token} must be resolved by FlowSet, not a binder.`);
+    }
+    const method = binder[ref.type];
+    if (typeof method !== "function") {
+        throw new Error(`TokenBinder has no ${ref.type}() method, but "${docName}" contains ${ref.token}. ` +
+            `Implement ${ref.type}(name) on the binder.`);
+    }
+    const value = method.call(binder, ref.name);
+    if (typeof value !== "string") {
+        throw new Error(`TokenBinder.${ref.type}("${ref.name}") returned ${String(value)} for ${ref.token} ` +
+            `in "${docName}". Binder methods must return a string.`);
+    }
+    return value;
+}
+//# sourceMappingURL=binder.js.map

package/dist/binder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binder.js","sourceRoot":"","sources":["../src/binder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,uDAAuD;AACvD,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,uFAAuF;AACvF,yEAAyE;AACzE,+EAA+E;AAC/E,6BAA6B;AAC7B,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,2EAA2E;AAmC3E;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,MAAmB,EAAE,GAAa,EAAE,OAAe;IACzE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1B,sEAAsE;QACtE,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,CAAC,KAAK,6CAA6C,CAAC,CAAC;IAClG,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,CAAC,IAAI,mBAAmB,OAAO,cAAc,GAAG,CAAC,KAAK,IAAI;YACjF,aAAa,GAAG,CAAC,IAAI,uBAAuB,CAC/C,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,eAAe,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,eAAe,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,KAAK,GAAG;YAClF,OAAO,OAAO,yCAAyC,CAC1D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/flow-set.d.ts

@@ -0,0 +1,35 @@
+import { type FlowDoc } from "@flow-as-code/core";
+import { CfnContactFlow, CfnContactFlowModule, CfnContactFlowModuleAlias } from "aws-cdk-lib/aws-connect";
+import { Construct } from "constructs";
+import { type TokenBinder } from "./binder.js";
+/** Alias created for a module no flow pins to a named alias. */
+export declare const DEFAULT_MODULE_ALIAS = "live";
+export interface FlowSetProps {
+    /** ARN of the Connect instance the flows deploy into. */
+    instanceArn: string;
+    /**
+     * Either a directory containing `*.flowdoc.json` files (read at synth time,
+     * sorted by file name) or the documents themselves.
+     */
+    source: string | FlowDoc[];
+    /** Resolves non-module references to CloudFormation-token strings. */
+    binder: TokenBinder;
+}
+/**
+ * Creates every flow and module in a FlowDoc set on a Connect instance, with
+ * references resolved to CloudFormation tokens: non-module refs through the
+ * user's TokenBinder, module refs to the alias ARN of the module this
+ * construct manages.
+ */
+export declare class FlowSet extends Construct {
+    /** Created contact flows, keyed by document name. */
+    readonly flows: ReadonlyMap<string, CfnContactFlow>;
+    /** Created modules, keyed by document name. */
+    readonly modules: ReadonlyMap<string, CfnContactFlowModule>;
+    /** Created module aliases, keyed by `name@alias`. */
+    readonly moduleAliases: ReadonlyMap<string, CfnContactFlowModuleAlias>;
+    constructor(scope: Construct, id: string, props: FlowSetProps);
+    /** Refuses duplicate names, kind mismatches, and hard lint findings. */
+    private validateDocs;
+}
+//# sourceMappingURL=flow-set.d.ts.map

package/dist/flow-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-set.d.ts","sourceRoot":"","sources":["../src/flow-set.ts"],"names":[],"mappings":"AAkCA,OAAO,EAOL,KAAK,OAAO,EAEb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,yBAAyB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IAC3B,sEAAsE;IACtE,MAAM,EAAE,WAAW,CAAC;CACrB;AAqDD;;;;;GAKG;AACH,qBAAa,OAAQ,SAAQ,SAAS;IACpC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpD,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC5D,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;gBAE3D,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY;IAgH7D,wEAAwE;IACxE,OAAO,CAAC,YAAY;CA2BrB"}

package/dist/flow-set.js

@@ -0,0 +1,225 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// FlowSet: a construct that turns a set of FlowDocs into deployable
+// AWS::Connect resources.
+//
+// Flows become AWS::Connect::ContactFlow and modules become
+// AWS::Connect::ContactFlowModule, with content produced by @flow-as-code/core's
+// materializeWithBinder and serializeContent so the deployed JSON is
+// byte-stable for the same inputs.
+// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflow.html
+// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmodule.html
+//
+// Versioning model:
+// - Modules are versioned. Each module gets an AWS::Connect::ContactFlowModuleVersion
+//   whose logical ID embeds a hash of the module's canonical content, so a
+//   content change replaces the version resource and publishes a new immutable
+//   version, and an AWS::Connect::ContactFlowModuleAlias per alias name used by
+//   the doc set (default "live") whose logical ID is stable and which repoints
+//   to the new version. Flows reference the ALIAS ARN, so repointing an alias
+//   to a new version changes no flow content.
+//   https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmoduleversion.html
+//   https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-connect-contactflowmodulealias.html
+// - Full flows are NOT versioned; their content updates in place. Connect's
+//   CreateContactFlowVersion API states: "This API only supports creating
+//   versions for flows of type Campaign."
+//   https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateContactFlowVersion.html
+//   (verified 2026-08-31)
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { allRules, collectRefs, lint, materializeWithBinder, serializeContent, toText, } from "@flow-as-code/core";
+import { CfnContactFlow, CfnContactFlowModule, CfnContactFlowModuleAlias, CfnContactFlowModuleVersion, } from "aws-cdk-lib/aws-connect";
+import { Construct } from "constructs";
+import { bindRef } from "./binder.js";
+/** Alias created for a module no flow pins to a named alias. */
+export const DEFAULT_MODULE_ALIAS = "live";
+/** `name@alias` key for a module alias resource. */
+const aliasKey = (name, alias) => `${name}@${alias ?? DEFAULT_MODULE_ALIAS}`;
+function loadDocs(source) {
+    if (Array.isArray(source))
+        return [...source];
+    const files = readdirSync(source)
+        .filter((f) => f.endsWith(".flowdoc.json"))
+        .sort();
+    if (files.length === 0) {
+        throw new Error(`FlowSet source directory "${source}" contains no *.flowdoc.json files.`);
+    }
+    return files.map((f) => JSON.parse(readFileSync(join(source, f), "utf8")));
+}
+/**
+ * Modules ordered so every module is created after the modules it references
+ * ("up to five levels" of nesting, per the flow language contract). Stable:
+ * ties break on name. Throws on a reference cycle, which Connect could never
+ * execute anyway.
+ */
+function topoSortModules(modules) {
+    const byName = new Map(modules.map((m) => [m.name, m]));
+    const deps = new Map(modules.map((m) => [
+        m.name,
+        collectRefs(m.content)
+            .filter((r) => r.type === "module" && byName.has(r.name))
+            .map((r) => r.name)
+            .sort(),
+    ]));
+    const done = new Set();
+    const visiting = new Set();
+    const ordered = [];
+    const visit = (name, path) => {
+        if (done.has(name))
+            return;
+        if (visiting.has(name)) {
+            throw new Error(`Module reference cycle: ${[...path, name].join(" -> ")}.`);
+        }
+        visiting.add(name);
+        for (const dep of deps.get(name) ?? [])
+            visit(dep, [...path, name]);
+        visiting.delete(name);
+        done.add(name);
+        ordered.push(byName.get(name));
+    };
+    for (const m of [...modules].sort((a, b) => a.name.localeCompare(b.name)))
+        visit(m.name, []);
+    return ordered;
+}
+/**
+ * Creates every flow and module in a FlowDoc set on a Connect instance, with
+ * references resolved to CloudFormation tokens: non-module refs through the
+ * user's TokenBinder, module refs to the alias ARN of the module this
+ * construct manages.
+ */
+export class FlowSet extends Construct {
+    /** Created contact flows, keyed by document name. */
+    flows;
+    /** Created modules, keyed by document name. */
+    modules;
+    /** Created module aliases, keyed by `name@alias`. */
+    moduleAliases;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const docs = loadDocs(props.source);
+        this.validateDocs(docs);
+        const moduleDocs = docs.filter((d) => d.kind === "module");
+        const flowDocs = docs
+            .filter((d) => d.kind === "flow")
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const moduleNames = new Set(moduleDocs.map((d) => d.name));
+        // Which aliases each module needs: every alias the doc set pins, plus the
+        // default so an unreferenced module still deploys with a usable alias.
+        const wanted = new Map(moduleDocs.map((d) => [d.name, new Set()]));
+        for (const doc of docs) {
+            for (const ref of collectRefs(doc.content)) {
+                if (ref.type !== "module")
+                    continue;
+                if (!moduleNames.has(ref.name)) {
+                    throw new Error(`"${doc.name}" references ${ref.token}, but no module named "${ref.name}" is in this FlowSet.`);
+                }
+                wanted.get(ref.name).add(ref.alias ?? DEFAULT_MODULE_ALIAS);
+            }
+        }
+        for (const aliases of wanted.values()) {
+            if (aliases.size === 0)
+                aliases.add(DEFAULT_MODULE_ALIAS);
+        }
+        const flows = new Map();
+        const modules = new Map();
+        const aliases = new Map();
+        const materializeDoc = (doc) => {
+            const used = [];
+            const content = materializeWithBinder(doc, (ref) => {
+                if (ref.type !== "module")
+                    return bindRef(props.binder, ref, doc.name);
+                const alias = aliases.get(aliasKey(ref.name, ref.alias));
+                if (alias === undefined) {
+                    // Unreachable for modules (topological order) and flows (created
+                    // after every module); kept as a guard with a real message.
+                    throw new Error(`Internal: alias for ${ref.token} not yet created (doc "${doc.name}").`);
+                }
+                used.push(alias);
+                return alias.attrContactFlowModuleAliasArn;
+            });
+            return { content: serializeContent(content), used };
+        };
+        // Modules first, dependency-ordered, each with its version and aliases.
+        for (const doc of topoSortModules(moduleDocs)) {
+            const { content, used } = materializeDoc(doc);
+            const module = new CfnContactFlowModule(this, `Module-${doc.name}`, {
+                instanceArn: props.instanceArn,
+                name: doc.name,
+                content,
+            });
+            for (const dep of used)
+                module.addResourceDependency(dep);
+            modules.set(doc.name, module);
+            // The version's logical ID embeds the canonical content hash (computed
+            // over the doc with its own tokens left in place, so it is stable across
+            // processes): a content change replaces the resource, publishing a new
+            // immutable version; the alias below keeps a stable logical ID and
+            // repoints. See the header comment for the versioning model.
+            const discriminator = createHash("sha256")
+                .update(serializeContent(materializeWithBinder(doc, (r) => r.token)))
+                .digest("hex")
+                .slice(0, 8);
+            const version = new CfnContactFlowModuleVersion(this, `Module-${doc.name}-Version-${discriminator}`, {
+                contactFlowModuleId: module.attrContactFlowModuleArn,
+            });
+            version.addResourceDependency(module);
+            for (const aliasName of [...wanted.get(doc.name)].sort()) {
+                const alias = new CfnContactFlowModuleAlias(this, `Module-${doc.name}-Alias-${aliasName}`, {
+                    contactFlowModuleId: module.attrContactFlowModuleArn,
+                    contactFlowModuleVersion: version.attrVersion,
+                    name: aliasName,
+                });
+                alias.addResourceDependency(version);
+                aliases.set(aliasKey(doc.name, aliasName), alias);
+            }
+        }
+        // Then flows. Alias references inside content already imply the ordering;
+        // the explicit dependency keeps it true even if content is later composed
+        // differently.
+        for (const doc of flowDocs) {
+            const { content, used } = materializeDoc(doc);
+            const flow = new CfnContactFlow(this, `Flow-${doc.name}`, {
+                instanceArn: props.instanceArn,
+                name: doc.name,
+                type: doc.connectType,
+                content,
+            });
+            for (const dep of used)
+                flow.addResourceDependency(dep);
+            flows.set(doc.name, flow);
+        }
+        this.flows = flows;
+        this.modules = modules;
+        this.moduleAliases = aliases;
+    }
+    /** Refuses duplicate names, kind mismatches, and hard lint findings. */
+    validateDocs(docs) {
+        const seen = new Set();
+        const duplicates = new Set();
+        for (const d of docs) {
+            if (seen.has(d.name))
+                duplicates.add(d.name);
+            seen.add(d.name);
+            if (d.kind === "module" && d.connectType !== "MODULE") {
+                throw new Error(`Module "${d.name}" must have connectType MODULE, got ${d.connectType}.`);
+            }
+            if (d.kind === "flow" && d.connectType === "MODULE") {
+                throw new Error(`Flow "${d.name}" cannot have connectType MODULE.`);
+            }
+        }
+        if (duplicates.size > 0) {
+            throw new Error(`Duplicate document name(s) in FlowSet: ${[...duplicates].sort().join(", ")}.`);
+        }
+        // Hard rules block deployment exactly as they block a studio save:
+        // no-literal-arn and no-unresolved-token (@flow-as-code/core lint).
+        const hard = new Set(allRules.filter((r) => r.hard).map((r) => r.id));
+        const blocking = lint(docs).filter((f) => hard.has(f.rule));
+        if (blocking.length > 0) {
+            throw new Error(`FlowSet refused ${blocking.length} document(s):\n${toText(blocking)}`);
+        }
+    }
+}
+//# sourceMappingURL=flow-set.js.map