@composurecdk/cloudformation 0.5.1 → 0.7.0

package/README.md

@@ -28,24 +28,20 @@ const { stack } = createStackBuilder()
   .build(app, "ServiceStack");
 ```
 
-### Scope factory
+### Variants and snapshots with `.copy()`
 
-Convert a configured builder into a `ScopeFactory` for use with stack strategies:
+`.copy()` returns an independent builder with the same configured state. Use it to derive variants from a shared base, or to snapshot a builder before handing it to a stack strategy that may be invoked after further mutations:
 
 ```ts
-const factory = createStackBuilder()
-  .terminationProtection(true)
-  .tag("team", "platform")
-  .toScopeFactory();
+const baseStack = createStackBuilder().tag("team", "platform");
 
-compose({ ... }, { ... })
-  .withStackStrategy(singleStack(factory))
-  .build(app, "MySystem");
+const { stack: us } = baseStack.copy().description("US region").build(app, "UsStack");
+const { stack: eu } = baseStack.copy().description("EU region").build(app, "EuStack");
 ```
 
 ## Stack Strategies
 
-Convenience wrappers around `@composurecdk/core`'s strategy primitives that default to creating Stacks via `createStackBuilder`. Pass an optional `ScopeFactory` to customise the Stack configuration.
+Convenience wrappers around `@composurecdk/core`'s strategy primitives. Both accept a `Lifecycle<StackBuilderResult>` (typically an `IStackBuilder`) and default to a fresh `createStackBuilder()` per call.
 
 ### singleStack
 
@@ -59,6 +55,16 @@ compose({ handler, api }, { handler: [], api: ["handler"] })
   .build(app, "MySystem");
 ```
 
+Pass a configured builder to apply tags, description, etc. to the strategy's stack. Use `.copy()` to snapshot the configuration when the original may be mutated later:
+
+```ts
+const base = createStackBuilder().tag("team", "platform");
+
+compose({ ... }, { ... })
+  .withStackStrategy(singleStack(base.copy()))
+  .build(app, "MySystem");
+```
+
 ### groupedStacks
 
 Groups components into named Stacks by a classifier function:
@@ -73,6 +79,18 @@ compose({ handler, api, table }, { ... })
   .build(app, "MySystem");
 ```
 
+The same builder is invoked once per group key with `${systemId}-${group}` as the id, so any tags configured on the supplied builder propagate to every stack the strategy creates. As with `singleStack`, pass `builder.copy()` to snapshot the configuration when the original may be mutated after hand-off:
+
+```ts
+const base = createStackBuilder().tag("team", "platform");
+
+compose({ ... }, { ... })
+  .withStackStrategy(
+    groupedStacks((key) => (key === "table" ? "persistence" : "service"), base.copy()),
+  )
+  .build(app, "MySystem");
+```
+
 ## outputs
 
 A post-build hook that creates CloudFormation stack outputs from a composed system's build results. Output values can be concrete strings or `Ref`s that resolve against the system's results.

package/dist/apply-builder-tags.d.ts

@@ -0,0 +1,32 @@
+import { type IConstruct } from "constructs";
+/**
+ * Applies every accumulated tag to every {@link IConstruct} reachable in a
+ * builder result.
+ *
+ * Recursively descends through plain-object literals, tagging every
+ * `IConstruct` it finds. Stops at:
+ *
+ * - **Constructs** — tagged via `Tags.of(...).add(...)`. The CDK Aspect
+ *   schedules tag application across the construct's subtree at
+ *   synth-prepare time, so the walker does not recurse into the construct's
+ *   internals.
+ * - **Class instances that aren't constructs** (e.g. `PolicyDocument`) —
+ *   skipped. Plain-object detection requires `Object.prototype` as the
+ *   prototype, so class instances are opaque to the walker.
+ * - **Arrays and primitives** — skipped.
+ *
+ * The contract this implements: every construct exposed in a builder's
+ * result type is a tag target. Wrapper shapes such as
+ * `Record<string, { construct: ..., metadata: ... }>` are unwrapped
+ * naturally — the walker descends through the plain-object value and tags
+ * the construct field. Authors do not need an opt-in marker; if a construct
+ * appears in the result, it is tagged.
+ */
+export declare function applyBuilderTags(result: object, tags: ReadonlyMap<string, string>): void;
+/**
+ * Applies every entry of `tags` to `target` via `Tags.of(target).add(...)`.
+ * Accepts any iterable of `[key, value]` pairs so callers can pass `Map`,
+ * `Object.entries(record)`, or other compatible sources without copying.
+ */
+export declare function applyTagsToConstruct(target: IConstruct, tags: Iterable<[string, string]>): void;
+//# sourceMappingURL=apply-builder-tags.d.ts.map

package/dist/apply-builder-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-builder-tags.d.ts","sourceRoot":"","sources":["../src/apply-builder-tags.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAMxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGxF;AAcD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAK/F"}

package/dist/apply-builder-tags.js

@@ -0,0 +1,65 @@
+import { Tags } from "aws-cdk-lib";
+import { Construct } from "constructs";
+function isConstruct(value) {
+    return value !== null && typeof value === "object" && Construct.isConstruct(value);
+}
+/**
+ * Applies every accumulated tag to every {@link IConstruct} reachable in a
+ * builder result.
+ *
+ * Recursively descends through plain-object literals, tagging every
+ * `IConstruct` it finds. Stops at:
+ *
+ * - **Constructs** — tagged via `Tags.of(...).add(...)`. The CDK Aspect
+ *   schedules tag application across the construct's subtree at
+ *   synth-prepare time, so the walker does not recurse into the construct's
+ *   internals.
+ * - **Class instances that aren't constructs** (e.g. `PolicyDocument`) —
+ *   skipped. Plain-object detection requires `Object.prototype` as the
+ *   prototype, so class instances are opaque to the walker.
+ * - **Arrays and primitives** — skipped.
+ *
+ * The contract this implements: every construct exposed in a builder's
+ * result type is a tag target. Wrapper shapes such as
+ * `Record<string, { construct: ..., metadata: ... }>` are unwrapped
+ * naturally — the walker descends through the plain-object value and tags
+ * the construct field. Authors do not need an opt-in marker; if a construct
+ * appears in the result, it is tagged.
+ */
+export function applyBuilderTags(result, tags) {
+    if (tags.size === 0)
+        return;
+    walkAndTag(result, tags);
+}
+function walkAndTag(value, tags) {
+    if (isConstruct(value)) {
+        applyTagsToConstruct(value, tags);
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const inner of Object.values(value)) {
+            walkAndTag(inner, tags);
+        }
+    }
+}
+/**
+ * Applies every entry of `tags` to `target` via `Tags.of(target).add(...)`.
+ * Accepts any iterable of `[key, value]` pairs so callers can pass `Map`,
+ * `Object.entries(record)`, or other compatible sources without copying.
+ */
+export function applyTagsToConstruct(target, tags) {
+    const t = Tags.of(target);
+    for (const [key, value] of tags) {
+        t.add(key, value);
+    }
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    // Accept both `{...}` literals and `Object.create(null)` dictionaries — the
+    // latter is a common idiom for prototype-pollution-safe key/value maps and
+    // would otherwise be silently skipped here.
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+//# sourceMappingURL=apply-builder-tags.js.map

package/dist/apply-builder-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-builder-tags.js","sourceRoot":"","sources":["../src/apply-builder-tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAmB,MAAM,YAAY,CAAC;AAExD,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,IAAiC;IAChF,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAC5B,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,IAAiC;IACnE,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IACD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkB,EAAE,IAAgC;IACvF,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAChC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,4EAA4E;IAC5E,2EAA2E;IAC3E,4CAA4C;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAkB,CAAC;IAC5D,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { createStackBuilder, type IStackBuilder, type StackBuilderResult, } from "./stack-builder.js";
 export { singleStack, groupedStacks } from "./strategies.js";
 export { outputs, type OutputDefinition, type OutputDefinitions } from "./outputs.js";
+export { taggedBuilder, type ITaggedBuilder, TAG_OVERRIDE_WARNING_NAME } from "./tagged-builder.js";
+export { applyBuilderTags } from "./apply-builder-tags.js";
+export { validateTag } from "./tag-validator.js";
+export { tags, type TagDefinitions } from "./tags.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,4 +1,8 @@
 export { createStackBuilder, } from "./stack-builder.js";
 export { singleStack, groupedStacks } from "./strategies.js";
 export { outputs } from "./outputs.js";
+export { taggedBuilder, TAG_OVERRIDE_WARNING_NAME } from "./tagged-builder.js";
+export { applyBuilderTags } from "./apply-builder-tags.js";
+export { validateTag } from "./tag-validator.js";
+export { tags } from "./tags.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAiD,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAiD,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAuB,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAuB,MAAM,WAAW,CAAC"}

package/dist/stack-builder.d.ts

@@ -1,6 +1,7 @@
 import { Stack, type StackProps } from "aws-cdk-lib";
 import { type IConstruct } from "constructs";
-import { type IBuilder, type Lifecycle, type ScopeFactory } from "@composurecdk/core";
+import { type Lifecycle } from "@composurecdk/core";
+import { type ITaggedBuilder } from "./tagged-builder.js";
 /**
  * The build output of a {@link IStackBuilder}. Contains the CDK Stack
  * created during {@link Lifecycle.build}.
@@ -16,54 +17,29 @@ export interface StackBuilderResult {
  * as an overloaded method: call with a value to set it (returns the builder
  * for chaining), or call with no arguments to read the current value.
  *
- * The builder implements {@link Lifecycle}, so it can be used directly as a
- * component in a {@link compose | composed system}. When built, it creates
- * a Stack with the configured properties and returns a
- * {@link StackBuilderResult}.
+ * The builder implements {@link Lifecycle}, so it can be used directly as
+ * a component in a {@link compose | composed system}, or handed to a stack
+ * strategy via {@link singleStack} / {@link groupedStacks}. When handing a
+ * builder to a strategy that may be invoked after further configuration of
+ * the original, pass `builder.copy()` to snapshot the current state.
+ *
+ * Tags accumulated via {@link ITaggedBuilder.tag | .tag()} or
+ * {@link ITaggedBuilder.tags | .tags()} are applied to the resulting Stack.
+ * CloudFormation propagates stack-level tags to every resource the stack
+ * contains, so a single `.tag()` call on a stack reaches everything inside.
  *
  * @example
  * ```ts
- * const stack = createStackBuilder()
+ * const { stack } = createStackBuilder()
  *   .description("Network infrastructure")
  *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
  *   .build(app, "NetworkStack");
  * ```
  */
-export type IStackBuilder = IBuilder<StackProps, StackBuilder> & {
-    /**
-     * Adds a tag to the Stack. Tags are applied to the Stack and propagate
-     * to all resources within it.
-     *
-     * @param key - The tag key.
-     * @param value - The tag value.
-     * @returns The builder for chaining.
-     */
-    tag(key: string, value: string): IStackBuilder;
-    /**
-     * Returns a {@link ScopeFactory} that creates Stacks with the builder's
-     * configured properties. Use this to integrate with
-     * {@link singleStack} or {@link groupedStacks} strategies.
-     *
-     * @returns A factory function compatible with stack strategies.
-     *
-     * @example
-     * ```ts
-     * const factory = createStackBuilder()
-     *   .terminationProtection(true)
-     *   .toScopeFactory();
-     *
-     * compose({ ... }, { ... })
-     *   .withStackStrategy(singleStack(factory))
-     *   .build(app, "MySystem");
-     * ```
-     */
-    toScopeFactory(): ScopeFactory;
-};
+export type IStackBuilder = ITaggedBuilder<StackProps, StackBuilder>;
 declare class StackBuilder implements Lifecycle<StackBuilderResult> {
-    #private;
     props: Partial<StackProps>;
-    tag(key: string, value: string): this;
-    toScopeFactory(): ScopeFactory;
     build(scope: IConstruct, id: string): StackBuilderResult;
 }
 /**
@@ -71,9 +47,10 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
  *
  * This is the entry point for declarative stack configuration. The returned
  * builder exposes every {@link StackProps} property as a fluent setter/getter,
- * plus {@link IStackBuilder.tag | .tag()} for adding tags and
- * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
- * with stack strategies.
+ * `.tag(key, value)` / `.tags({...})` for stack-level tagging, and `.copy()`
+ * for variant authoring. It implements {@link Lifecycle}, so it composes
+ * naturally and can be passed to {@link singleStack} or
+ * {@link groupedStacks}.
  *
  * @returns A fluent builder for a CloudFormation Stack.
  *
@@ -83,16 +60,17 @@ declare class StackBuilder implements Lifecycle<StackBuilderResult> {
  * const { stack } = createStackBuilder()
  *   .description("Service layer")
  *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
  *   .build(app, "ServiceStack");
  *
- * // Use as a scope factory with strategies
- * const factory = createStackBuilder()
+ * // Hand a configured builder to a strategy. Use `.copy()` to snapshot
+ * // when the original may be mutated further.
+ * const base = createStackBuilder()
  *   .terminationProtection(true)
- *   .tag("team", "platform")
- *   .toScopeFactory();
+ *   .tag("team", "platform");
  *
  * compose({ ... }, { ... })
- *   .withStackStrategy(singleStack(factory))
+ *   .withStackStrategy(singleStack(base.copy()))
  *   .build(app, "MySystem");
  * ```
  */

package/dist/stack-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack-builder.d.ts","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAQ,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/F;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG;IAC/D;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;IAE/C;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,IAAI,YAAY,CAAC;CAChC,CAAC;AAEF,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAM;IAGhC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,cAAc,IAAI,YAAY;IAY9B,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAOzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}
+{"version":3,"file":"stack-builder.d.ts","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AAErE,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAM;IAEhC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAGzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}

package/dist/stack-builder.js

@@ -1,29 +1,9 @@
-import { Stack, Tags } from "aws-cdk-lib";
-import { Builder } from "@composurecdk/core";
+import { Stack } from "aws-cdk-lib";
+import { taggedBuilder } from "./tagged-builder.js";
 class StackBuilder {
     props = {};
-    #tags = [];
-    tag(key, value) {
-        this.#tags.push([key, value]);
-        return this;
-    }
-    toScopeFactory() {
-        const props = { ...this.props };
-        const tags = [...this.#tags];
-        return (scope, id) => {
-            const stack = new Stack(scope, id, props);
-            tags.forEach(([key, value]) => {
-                Tags.of(stack).add(key, value);
-            });
-            return stack;
-        };
-    }
     build(scope, id) {
-        const stack = new Stack(scope, id, this.props);
-        this.#tags.forEach(([key, value]) => {
-            Tags.of(stack).add(key, value);
-        });
-        return { stack };
+        return { stack: new Stack(scope, id, this.props) };
     }
 }
 /**
@@ -31,9 +11,10 @@ class StackBuilder {
  *
  * This is the entry point for declarative stack configuration. The returned
  * builder exposes every {@link StackProps} property as a fluent setter/getter,
- * plus {@link IStackBuilder.tag | .tag()} for adding tags and
- * {@link IStackBuilder.toScopeFactory | .toScopeFactory()} for integration
- * with stack strategies.
+ * `.tag(key, value)` / `.tags({...})` for stack-level tagging, and `.copy()`
+ * for variant authoring. It implements {@link Lifecycle}, so it composes
+ * naturally and can be passed to {@link singleStack} or
+ * {@link groupedStacks}.
  *
  * @returns A fluent builder for a CloudFormation Stack.
  *
@@ -43,20 +24,21 @@ class StackBuilder {
  * const { stack } = createStackBuilder()
  *   .description("Service layer")
  *   .terminationProtection(true)
+ *   .tag("Owner", "platform")
  *   .build(app, "ServiceStack");
  *
- * // Use as a scope factory with strategies
- * const factory = createStackBuilder()
+ * // Hand a configured builder to a strategy. Use `.copy()` to snapshot
+ * // when the original may be mutated further.
+ * const base = createStackBuilder()
  *   .terminationProtection(true)
- *   .tag("team", "platform")
- *   .toScopeFactory();
+ *   .tag("team", "platform");
  *
  * compose({ ... }, { ... })
- *   .withStackStrategy(singleStack(factory))
+ *   .withStackStrategy(singleStack(base.copy()))
  *   .build(app, "MySystem");
  * ```
  */
 export function createStackBuilder() {
-    return Builder(StackBuilder);
+    return taggedBuilder(StackBuilder);
 }
 //# sourceMappingURL=stack-builder.js.map

package/dist/stack-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"stack-builder.js","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAmB,IAAI,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAoD,MAAM,oBAAoB,CAAC;AA+D/F,MAAM,YAAY;IAChB,KAAK,GAAwB,EAAE,CAAC;IACvB,KAAK,GAAuB,EAAE,CAAC;IAExC,GAAG,CAAC,GAAW,EAAE,KAAa;QAC5B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc;QACZ,MAAM,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,CAAC,KAAiB,EAAE,EAAU,EAAE,EAAE;YACvC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBAC5B,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YAClC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAA2B,YAAY,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"stack-builder.js","sourceRoot":"","sources":["../src/stack-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAmB,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAuB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwCzE,MAAM,YAAY;IAChB,KAAK,GAAwB,EAAE,CAAC;IAEhC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,OAAO,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;IACrD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,aAAa,CAA2B,YAAY,CAAC,CAAC;AAC/D,CAAC"}

package/dist/strategies.d.ts

@@ -1,12 +1,20 @@
-import { type ScopeFactory, type StackStrategy } from "@composurecdk/core";
+import { type Lifecycle, type StackStrategy } from "@composurecdk/core";
+import { type StackBuilderResult } from "./stack-builder.js";
 /**
  * Creates a strategy that places all components in a single Stack.
  *
- * The Stack is created lazily on the first call to `resolve` and reused for
- * all subsequent components.
+ * The Stack is created lazily on the first call to `resolve` and reused
+ * for all subsequent components. The supplied `builder` is invoked at that
+ * point as `builder.build(scope, id).stack`, so any tags applied via the
+ * builder's `.tag()` method land on the resulting Stack.
  *
- * @param factory - Optional factory for creating the Stack. Defaults to
- *   a plain CDK `Stack` via {@link createStackBuilder}.
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
+ *
+ * @param builder - Optional builder for configuring the Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call, producing a plain Stack
+ *   with no extra configuration. For non-Stack scope types, use
+ *   `singleStack` from `@composurecdk/core` directly with a `ScopeFactory`.
  * @returns A {@link StackStrategy} that groups all components into one Stack.
  *
  * @example
@@ -14,20 +22,33 @@ import { type ScopeFactory, type StackStrategy } from "@composurecdk/core";
  * compose({ handler, api }, { handler: [], api: ["handler"] })
  *   .withStackStrategy(singleStack())
  *   .build(app, "MySystem");
+ *
+ * // With a configured builder:
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(base.copy()))
+ *   .build(app, "MySystem");
  * ```
  */
-export declare function singleStack(factory?: ScopeFactory): StackStrategy;
+export declare function singleStack(builder?: Lifecycle<StackBuilderResult>): StackStrategy;
 /**
  * Creates a strategy that groups components into named Stacks determined by
  * a classifier function.
  *
- * Components that return the same group key share a Stack. Stacks are created
- * lazily as new group keys are encountered.
+ * Components that return the same group key share a Stack. Stacks are
+ * created lazily as new group keys are encountered. The supplied `builder`
+ * is invoked once per group as `builder.build(scope, id).stack` with
+ * `id = ${systemId}-${group}`, so any configured tags propagate to every
+ * Stack the strategy creates.
+ *
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
  *
  * @param classify - A function that maps a component key to a group name.
- * @param factory - Optional factory for creating Stacks. Defaults to
- *   a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
- *   `${systemId}-${group}` as the id.
+ * @param builder - Optional builder for configuring each Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call. For non-Stack scope types,
+ *   use `groupedStacks` from `@composurecdk/core` directly with a
+ *   `ScopeFactory`.
  * @returns A {@link StackStrategy} that groups components by classifier output.
  *
  * @example
@@ -35,7 +56,15 @@ export declare function singleStack(factory?: ScopeFactory): StackStrategy;
  * compose({ handler, api, table }, { ... })
  *   .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
  *   .build(app, "MySystem");
+ *
+ * // With a configured builder, snapshotted via .copy():
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(
+ *     groupedStacks(key => key === "table" ? "persistence" : "service", base.copy()),
+ *   )
+ *   .build(app, "MySystem");
  * ```
  */
-export declare function groupedStacks(classify: (componentKey: string) => string, factory?: ScopeFactory): StackStrategy;
+export declare function groupedStacks(classify: (componentKey: string) => string, builder?: Lifecycle<StackBuilderResult>): StackStrategy;
 //# sourceMappingURL=strategies.d.ts.map

package/dist/strategies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAO5B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAEjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,CAAC,EAAE,YAAY,GACrB,aAAa,CAEf"}
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GAAG,aAAa,CAGlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAC1C,OAAO,CAAC,EAAE,SAAS,CAAC,kBAAkB,CAAC,GACtC,aAAa,CAGf"}

package/dist/strategies.js

@@ -1,16 +1,20 @@
 import { singleStack as coreSingleStack, groupedStacks as coreGroupedStacks, } from "@composurecdk/core";
 import { createStackBuilder } from "./stack-builder.js";
-function defaultFactory() {
-    return createStackBuilder().toScopeFactory();
-}
 /**
  * Creates a strategy that places all components in a single Stack.
  *
- * The Stack is created lazily on the first call to `resolve` and reused for
- * all subsequent components.
+ * The Stack is created lazily on the first call to `resolve` and reused
+ * for all subsequent components. The supplied `builder` is invoked at that
+ * point as `builder.build(scope, id).stack`, so any tags applied via the
+ * builder's `.tag()` method land on the resulting Stack.
+ *
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
  *
- * @param factory - Optional factory for creating the Stack. Defaults to
- *   a plain CDK `Stack` via {@link createStackBuilder}.
+ * @param builder - Optional builder for configuring the Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call, producing a plain Stack
+ *   with no extra configuration. For non-Stack scope types, use
+ *   `singleStack` from `@composurecdk/core` directly with a `ScopeFactory`.
  * @returns A {@link StackStrategy} that groups all components into one Stack.
  *
  * @example
@@ -18,22 +22,36 @@ function defaultFactory() {
  * compose({ handler, api }, { handler: [], api: ["handler"] })
  *   .withStackStrategy(singleStack())
  *   .build(app, "MySystem");
+ *
+ * // With a configured builder:
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(singleStack(base.copy()))
+ *   .build(app, "MySystem");
  * ```
  */
-export function singleStack(factory) {
-    return coreSingleStack(factory ?? defaultFactory());
+export function singleStack(builder) {
+    const stackBuilder = builder ?? createStackBuilder();
+    return coreSingleStack((scope, id) => stackBuilder.build(scope, id).stack);
 }
 /**
  * Creates a strategy that groups components into named Stacks determined by
  * a classifier function.
  *
- * Components that return the same group key share a Stack. Stacks are created
- * lazily as new group keys are encountered.
+ * Components that return the same group key share a Stack. Stacks are
+ * created lazily as new group keys are encountered. The supplied `builder`
+ * is invoked once per group as `builder.build(scope, id).stack` with
+ * `id = ${systemId}-${group}`, so any configured tags propagate to every
+ * Stack the strategy creates.
+ *
+ * The builder's `build()` is called lazily. If the original may be mutated
+ * after this call, pass `builder.copy()` to snapshot the configuration.
  *
  * @param classify - A function that maps a component key to a group name.
- * @param factory - Optional factory for creating Stacks. Defaults to
- *   a plain CDK `Stack` via {@link createStackBuilder}. The factory receives
- *   `${systemId}-${group}` as the id.
+ * @param builder - Optional builder for configuring each Stack. Defaults to
+ *   a fresh {@link createStackBuilder} per call. For non-Stack scope types,
+ *   use `groupedStacks` from `@composurecdk/core` directly with a
+ *   `ScopeFactory`.
  * @returns A {@link StackStrategy} that groups components by classifier output.
  *
  * @example
@@ -41,9 +59,18 @@ export function singleStack(factory) {
  * compose({ handler, api, table }, { ... })
  *   .withStackStrategy(groupedStacks(key => key === "table" ? "persistence" : "service"))
  *   .build(app, "MySystem");
+ *
+ * // With a configured builder, snapshotted via .copy():
+ * const base = createStackBuilder().tag("team", "platform");
+ * compose({ ... }, { ... })
+ *   .withStackStrategy(
+ *     groupedStacks(key => key === "table" ? "persistence" : "service", base.copy()),
+ *   )
+ *   .build(app, "MySystem");
  * ```
  */
-export function groupedStacks(classify, factory) {
-    return coreGroupedStacks(classify, factory ?? defaultFactory());
+export function groupedStacks(classify, builder) {
+    const stackBuilder = builder ?? createStackBuilder();
+    return coreGroupedStacks(classify, (scope, id) => stackBuilder.build(scope, id).stack);
 }
 //# sourceMappingURL=strategies.js.map

package/dist/strategies.js.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,IAAI,eAAe,EAC9B,aAAa,IAAI,iBAAiB,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,SAAS,cAAc;IACrB,OAAO,kBAAkB,EAAE,CAAC,cAAc,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,OAAO,eAAe,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA0C,EAC1C,OAAsB;IAEtB,OAAO,iBAAiB,CAAC,QAAQ,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,WAAW,IAAI,eAAe,EAC9B,aAAa,IAAI,iBAAiB,GACnC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAA2B,MAAM,oBAAoB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,WAAW,CAAC,OAAuC;IACjE,MAAM,YAAY,GAAG,OAAO,IAAI,kBAAkB,EAAE,CAAC;IACrD,OAAO,eAAe,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA0C,EAC1C,OAAuC;IAEvC,MAAM,YAAY,GAAG,OAAO,IAAI,kBAAkB,EAAE,CAAC;IACrD,OAAO,iBAAiB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC"}

package/dist/tag-validator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validates a single tag key/value pair against AWS tag constraints.
+ *
+ * Throws synchronously at the call site so authors see the failure where the
+ * bad value was written, not at deploy time. Validates:
+ *
+ * - `key` is non-empty and at most {@link KEY_MAX} characters.
+ * - `key` does not start with the reserved `aws:` prefix (case-insensitive).
+ * - `value` is at most {@link VALUE_MAX} characters.
+ * - both `key` and `value` use only the AWS-permitted character set.
+ *
+ * The regex matches Unicode letters, digits, and whitespace plus the
+ * documented punctuation set, so non-ASCII tags are accepted as AWS
+ * supports them.
+ */
+export declare function validateTag(key: string, value: string): void;
+/**
+ * Validates every entry of a record via {@link validateTag}, throwing on the
+ * first invalid pair so the failure surfaces at the configuring call site.
+ */
+export declare function validateTagRecord(values: Record<string, string>): void;
+//# sourceMappingURL=tag-validator.d.ts.map

package/dist/tag-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validator.d.ts","sourceRoot":"","sources":["../src/tag-validator.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2B5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAItE"}

package/dist/tag-validator.js

@@ -0,0 +1,63 @@
+/**
+ * AWS allows letters, digits, whitespace, and the symbols `_ . : / = + - @`
+ * in tag keys and values, with non-ASCII letters/digits permitted via
+ * Unicode classes. Empty values are permitted by AWS for `Value`, but
+ * empty `Key` is not. The character set is validated against this regex.
+ *
+ * `\p{Z}` matches the full Unicode separator class — slightly more
+ * permissive than AWS's documented "white space," but errors on the side
+ * of accepting input that the AWS API may yet reject at deploy time. The
+ * extra rejections happen later but are reported in the API response.
+ *
+ * @see https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html
+ */
+const TAG_CHAR_RE = /^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$/u;
+const KEY_MAX = 128;
+const VALUE_MAX = 256;
+/**
+ * Validates a single tag key/value pair against AWS tag constraints.
+ *
+ * Throws synchronously at the call site so authors see the failure where the
+ * bad value was written, not at deploy time. Validates:
+ *
+ * - `key` is non-empty and at most {@link KEY_MAX} characters.
+ * - `key` does not start with the reserved `aws:` prefix (case-insensitive).
+ * - `value` is at most {@link VALUE_MAX} characters.
+ * - both `key` and `value` use only the AWS-permitted character set.
+ *
+ * The regex matches Unicode letters, digits, and whitespace plus the
+ * documented punctuation set, so non-ASCII tags are accepted as AWS
+ * supports them.
+ */
+export function validateTag(key, value) {
+    if (key.length === 0) {
+        throw new Error("Tag key must be non-empty.");
+    }
+    if (key.length > KEY_MAX) {
+        throw new Error(`Tag key "${key}" exceeds ${String(KEY_MAX)}-character limit.`);
+    }
+    if (key.toLowerCase().startsWith("aws:")) {
+        throw new Error(`Tag key "${key}" uses reserved "aws:" prefix; AWS rejects user tags with this prefix.`);
+    }
+    if (!TAG_CHAR_RE.test(key)) {
+        throw new Error(`Tag key "${key}" contains characters outside the AWS tag character set ` +
+            "(letters, digits, whitespace, and `_ . : / = + - @`).");
+    }
+    if (value.length > VALUE_MAX) {
+        throw new Error(`Tag value for key "${key}" exceeds ${String(VALUE_MAX)}-character limit.`);
+    }
+    if (!TAG_CHAR_RE.test(value)) {
+        throw new Error(`Tag value for key "${key}" contains characters outside the AWS tag character set ` +
+            "(letters, digits, whitespace, and `_ . : / = + - @`).");
+    }
+}
+/**
+ * Validates every entry of a record via {@link validateTag}, throwing on the
+ * first invalid pair so the failure surfaces at the configuring call site.
+ */
+export function validateTagRecord(values) {
+    for (const [key, value] of Object.entries(values)) {
+        validateTag(key, value);
+    }
+}
+//# sourceMappingURL=tag-validator.js.map

package/dist/tag-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validator.js","sourceRoot":"","sources":["../src/tag-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,GAAG,gCAAgC,CAAC;AAErD,MAAM,OAAO,GAAG,GAAG,CAAC;AACpB,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,YAAY,GAAG,aAAa,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,YAAY,GAAG,wEAAwE,CACxF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,YAAY,GAAG,0DAA0D;YACvE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,aAAa,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,sBAAsB,GAAG,0DAA0D;YACjF,uDAAuD,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA8B;IAC9D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/tagged-builder.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The `name` attached to the `process.emitWarning` call when `.tag(k, v)` /
+ * `.tags({...})` overwrites an existing key. Exported so callers with
+ * layered configuration (a base builder plus per-environment refinements
+ * that intentionally override) can filter via
+ * `process.on("warning", w => { if (w.name !== TAG_OVERRIDE_WARNING_NAME) ... })`
+ * or the Node 21.3+ `--disable-warning=ComposureCDKTagOverride` CLI flag.
+ */
+export declare const TAG_OVERRIDE_WARNING_NAME = "ComposureCDKTagOverride";
+type Constructor<T> = new () => T;
+interface ObjectWithProps<Props extends object> {
+    props: Partial<Props>;
+}
+/**
+ * A fluent builder extended with tag-accumulating methods. Returned by
+ * {@link taggedBuilder}.
+ *
+ * Mirrors `IBuilder<Props, T>` from `@composurecdk/core` but rewrites every
+ * chainable return type to `ITaggedBuilder<Props, T>` so the augmenting
+ * `.tag()` / `.tags()` methods stay reachable after any prop setter or
+ * chainable method on `T`. {@link ITaggedBuilder.copy | `.copy()`} also
+ * returns a tagged builder so the chain survives variant authoring.
+ *
+ * Tags accumulated via {@link ITaggedBuilder.tag | .tag()} and
+ * {@link ITaggedBuilder.tags | .tags()} are applied to every construct in
+ * the build result — see {@link applyBuilderTags} for the exact walk.
+ *
+ * @typeParam Props - The configurable properties.
+ * @typeParam T - The target class the builder wraps.
+ */
+export type ITaggedBuilder<Props extends object, T> = {
+    [K in keyof Props]-?: ((arg: Props[K]) => ITaggedBuilder<Props, T>) & (() => Props[K]);
+} & {
+    [K in keyof T]: T[K] extends (...args: infer A) => T ? (...args: A) => ITaggedBuilder<Props, T> : T[K];
+} & {
+    /**
+     * Adds a single tag. Validates the key/value at call time and throws on
+     * AWS-rejected inputs (empty key, `aws:` prefix, oversize, disallowed
+     * characters).
+     *
+     * Repeated keys overwrite earlier values and emit a process warning so the
+     * override is visible at the call site.
+     *
+     * @param key - The tag key.
+     * @param value - The tag value.
+     * @returns The builder for chaining.
+     */
+    tag(key: string, value: string): ITaggedBuilder<Props, T>;
+    /**
+     * Adds many tags at once. Each entry is validated independently as if
+     * passed to {@link ITaggedBuilder.tag | .tag()}. Existing keys are
+     * overwritten with a process warning.
+     *
+     * @param values - A record of tag keys to values.
+     * @returns The builder for chaining.
+     */
+    tags(values: Record<string, string>): ITaggedBuilder<Props, T>;
+    /**
+     * Returns an independent tagged builder with the same configured props
+     * and a deep clone of the accumulated tags.
+     *
+     * Mirrors {@link IBuilder.copy} from `@composurecdk/core` but preserves
+     * the tagging surface. Mutations to the returned builder's tags do not
+     * affect the original, and vice versa.
+     */
+    copy(): ITaggedBuilder<Props, T>;
+};
+/**
+ * Wraps {@link Builder} to add the {@link ITaggedBuilder.tag | .tag()} and
+ * {@link ITaggedBuilder.tags | .tags()} accumulators and apply the
+ * collected tags to every construct in the build result.
+ *
+ * The wrapper maintains its own outer Proxy around the inner builder Proxy
+ * created by `@composurecdk/core`. The outer Proxy:
+ *
+ * 1. Intercepts `.tag(k, v)` and `.tags({...})` to validate inputs and
+ *    accumulate them in an insertion-ordered map. Repeated keys overwrite
+ *    earlier values and emit `process.emitWarning` so the override is
+ *    visible at the configuring call site.
+ * 2. Intercepts `build()` to call {@link applyBuilderTags} on the result
+ *    after the inner build completes.
+ * 3. Intercepts `copy()` so the returned builder is itself a tagged builder
+ *    with an independent clone of the accumulator. Without this, `.copy()`
+ *    on a tagged builder would surface the bare inner Proxy and silently
+ *    drop both the tag methods and the build-time walker.
+ * 4. Passes every other access through to the inner Proxy unchanged. Inner
+ *    methods that return the inner Proxy (chainable setters) are
+ *    re-wrapped so the chain returns the outer Proxy and the new tag
+ *    methods stay reachable.
+ *
+ * Each builder factory in the library opts in by calling `taggedBuilder()`
+ * instead of `Builder()`. Custom builders authored outside the library can
+ * use plain `Builder()` and forgo tagging.
+ *
+ * @typeParam Props - The configurable properties.
+ * @typeParam T - The target class the builder wraps.
+ *
+ * @example
+ * ```ts
+ * export function createBucketBuilder(): IBucketBuilder {
+ *   return taggedBuilder<BucketBuilderProps, BucketBuilder>(BucketBuilder);
+ * }
+ *
+ * createBucketBuilder()
+ *   .tag("Project", "claude-rig")
+ *   .tags({ Owner: "platform", Environment: "prod" })
+ *   .build(stack, "Bucket");
+ * ```
+ */
+export declare function taggedBuilder<Props extends object, T extends ObjectWithProps<Props>>(constructor: Constructor<T>): ITaggedBuilder<Props, T>;
+export {};
+//# sourceMappingURL=tagged-builder.d.ts.map

package/dist/tagged-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-builder.d.ts","sourceRoot":"","sources":["../src/tagged-builder.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AAEnE,KAAK,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC;AAElC,UAAU,eAAe,CAAC,KAAK,SAAS,MAAM;IAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,IAAI;KACnD,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;CACvF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,GAChD,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,GACxC,CAAC,CAAC,CAAC,CAAC;CACT,GAAG;IACF;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE1D;;;;;;;OAOG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE/D;;;;;;;OAOG;IACH,IAAI,IAAI,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,aAAa,CAAC,KAAK,SAAS,MAAM,EAAE,CAAC,SAAS,eAAe,CAAC,KAAK,CAAC,EAClF,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,CAG1B"}

package/dist/tagged-builder.js

@@ -0,0 +1,117 @@
+import { Builder } from "@composurecdk/core";
+import { applyBuilderTags } from "./apply-builder-tags.js";
+import { validateTag, validateTagRecord } from "./tag-validator.js";
+/**
+ * The `name` attached to the `process.emitWarning` call when `.tag(k, v)` /
+ * `.tags({...})` overwrites an existing key. Exported so callers with
+ * layered configuration (a base builder plus per-environment refinements
+ * that intentionally override) can filter via
+ * `process.on("warning", w => { if (w.name !== TAG_OVERRIDE_WARNING_NAME) ... })`
+ * or the Node 21.3+ `--disable-warning=ComposureCDKTagOverride` CLI flag.
+ */
+export const TAG_OVERRIDE_WARNING_NAME = "ComposureCDKTagOverride";
+/**
+ * Wraps {@link Builder} to add the {@link ITaggedBuilder.tag | .tag()} and
+ * {@link ITaggedBuilder.tags | .tags()} accumulators and apply the
+ * collected tags to every construct in the build result.
+ *
+ * The wrapper maintains its own outer Proxy around the inner builder Proxy
+ * created by `@composurecdk/core`. The outer Proxy:
+ *
+ * 1. Intercepts `.tag(k, v)` and `.tags({...})` to validate inputs and
+ *    accumulate them in an insertion-ordered map. Repeated keys overwrite
+ *    earlier values and emit `process.emitWarning` so the override is
+ *    visible at the configuring call site.
+ * 2. Intercepts `build()` to call {@link applyBuilderTags} on the result
+ *    after the inner build completes.
+ * 3. Intercepts `copy()` so the returned builder is itself a tagged builder
+ *    with an independent clone of the accumulator. Without this, `.copy()`
+ *    on a tagged builder would surface the bare inner Proxy and silently
+ *    drop both the tag methods and the build-time walker.
+ * 4. Passes every other access through to the inner Proxy unchanged. Inner
+ *    methods that return the inner Proxy (chainable setters) are
+ *    re-wrapped so the chain returns the outer Proxy and the new tag
+ *    methods stay reachable.
+ *
+ * Each builder factory in the library opts in by calling `taggedBuilder()`
+ * instead of `Builder()`. Custom builders authored outside the library can
+ * use plain `Builder()` and forgo tagging.
+ *
+ * @typeParam Props - The configurable properties.
+ * @typeParam T - The target class the builder wraps.
+ *
+ * @example
+ * ```ts
+ * export function createBucketBuilder(): IBucketBuilder {
+ *   return taggedBuilder<BucketBuilderProps, BucketBuilder>(BucketBuilder);
+ * }
+ *
+ * createBucketBuilder()
+ *   .tag("Project", "claude-rig")
+ *   .tags({ Owner: "platform", Environment: "prod" })
+ *   .build(stack, "Bucket");
+ * ```
+ */
+export function taggedBuilder(constructor) {
+    const inner = Builder(constructor);
+    return wrapTagged(inner, new Map());
+}
+function wrapTagged(inner, accumulator) {
+    const recordTag = (key, value) => {
+        if (accumulator.has(key)) {
+            const previous = accumulator.get(key);
+            process.emitWarning(`Tag "${key}" was already set to "${previous ?? ""}" and is being overwritten with "${value}". ` +
+                "Last write wins; remove the duplicate to silence this warning.", { type: TAG_OVERRIDE_WARNING_NAME });
+        }
+        accumulator.set(key, value);
+    };
+    const buildFn = (...args) => {
+        const target = inner;
+        const result = target.build(...args);
+        applyBuilderTags(result, accumulator);
+        return result;
+    };
+    const copyFn = () => {
+        const innerCopy = inner;
+        return wrapTagged(innerCopy.copy(), new Map(accumulator));
+    };
+    // `tagFn` / `tagsFn` and `outer` form a cycle: the interceptors return
+    // `outer` for chaining, and `outer`'s `get` trap returns the interceptors.
+    // Resolved by Proxy laziness: the `get` trap closes over the names but
+    // does not read them until a property is accessed, by which point the
+    // `const`s below have initialised.
+    const outer = new Proxy(inner, {
+        get(target, prop, receiver) {
+            if (prop === "tag")
+                return tagFn;
+            if (prop === "tags")
+                return tagsFn;
+            if (prop === "build")
+                return buildFn;
+            if (prop === "copy")
+                return copyFn;
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value === "function") {
+                return (...args) => {
+                    const ret = value.apply(target, args);
+                    return ret === inner ? outer : ret;
+                };
+            }
+            return value;
+        },
+    });
+    const tagFn = (key, value) => {
+        validateTag(key, value);
+        recordTag(key, value);
+        return outer;
+    };
+    const tagsFn = (values) => {
+        validateTagRecord(values);
+        for (const [key, value] of Object.entries(values)) {
+            recordTag(key, value);
+        }
+        return outer;
+    };
+    return outer;
+}
+//# sourceMappingURL=tagged-builder.js.map

package/dist/tagged-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-builder.js","sourceRoot":"","sources":["../src/tagged-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAiB,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAyB,CAAC;AAmEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,aAAa,CAC3B,WAA2B;IAE3B,MAAM,KAAK,GAAG,OAAO,CAAW,WAAW,CAAC,CAAC;IAC7C,OAAO,UAAU,CAAW,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,UAAU,CACjB,KAAyB,EACzB,WAAgC;IAEhC,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,KAAa,EAAQ,EAAE;QACrD,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,CAAC,WAAW,CACjB,QAAQ,GAAG,yBAAyB,QAAQ,IAAI,EAAE,oCAAoC,KAAK,KAAK;gBAC9F,gEAAgE,EAClE,EAAE,IAAI,EAAE,yBAAyB,EAAE,CACpC,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAG,IAAe,EAAU,EAAE;QAC7C,MAAM,MAAM,GAAG,KAA0D,CAAC;QAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACrC,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,GAA6B,EAAE;QAC5C,MAAM,SAAS,GAAG,KAAsD,CAAC;QACzE,OAAO,UAAU,CAAW,SAAS,CAAC,IAAI,EAAE,EAAE,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC;IAEF,uEAAuE;IACvE,2EAA2E;IAC3E,uEAAuE;IACvE,sEAAsE;IACtE,mCAAmC;IACnC,MAAM,KAAK,GAA6B,IAAI,KAAK,CAAC,KAAK,EAAE;QACvD,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACxB,IAAI,IAAI,KAAK,KAAK;gBAAE,OAAO,KAAK,CAAC;YACjC,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,MAAM,CAAC;YACnC,IAAI,IAAI,KAAK,OAAO;gBAAE,OAAO,OAAO,CAAC;YACrC,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,MAAM,CAAC;YAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAY,CAAC;YAC7D,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;gBAChC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;oBAC5B,MAAM,GAAG,GAAI,KAAsC,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;oBACxE,OAAO,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;gBACrC,CAAC,CAAC;YACJ,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAA6B,CAAC;IAE/B,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,KAAa,EAA4B,EAAE;QACrE,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,MAA8B,EAA4B,EAAE;QAC1E,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tags.d.ts

@@ -0,0 +1,91 @@
+import { type AfterBuildHook } from "@composurecdk/core";
+/**
+ * Configures cross-cutting tag application against a composed system.
+ *
+ * - `system` tags reach every construct under the top-level scope passed
+ *   to `build(scope, id)` — useful for ownership, environment, and cost
+ *   allocation tags that should apply to every resource the system creates.
+ * - `byComponent` tags reach only the scope a named component was built
+ *   into. Under {@link ComposedSystem.withStacks} or
+ *   {@link ComposedSystem.withStackStrategy}, components may live in
+ *   different stacks — `byComponent` routes the tag to whichever scope
+ *   that component received.
+ *
+ * Component keys in `byComponent` are statically typed against the
+ * composed system's component keys, matching the pattern `outputs()` uses
+ * for its `scope` field, so a typo on a component name is a compile-time
+ * error.
+ *
+ * Builder-level tags applied via `.tag()` / `.tags()` always take
+ * precedence on key conflict because they target a closer scope; CDK's
+ * native tag priority resolves the collision automatically.
+ *
+ * @typeParam T - The composed system's build result type. Inferred from
+ * the surrounding `compose(...).afterBuild(tags(...))` chain.
+ */
+export interface TagDefinitions<T extends object = object> {
+    /**
+     * Tags applied to every construct under the top-level scope. Each
+     * key/value pair is validated against the AWS tag character set; invalid
+     * inputs throw at configuration time.
+     */
+    system?: Record<string, string>;
+    /**
+     * Tags applied only to constructs under a specific component's scope.
+     * Component keys are statically checked against the composed system's
+     * component keys. Each key/value pair is validated identically to
+     * `system`.
+     */
+    byComponent?: Partial<Record<keyof T & string, Record<string, string>>>;
+}
+/**
+ * Returns an {@link AfterBuildHook} that applies cross-cutting tags to a
+ * composed system. Modelled on {@link outputs} — both share the same
+ * `(scope, id, results, componentScopes)` shape and live alongside the
+ * other CloudFormation-flavoured composition helpers in this package.
+ *
+ * The hook walks the supplied {@link TagDefinitions} once per build:
+ *
+ * - `system` entries are applied to the top-level `scope` via
+ *   `Tags.of(scope).add(...)`. CDK's tag aspect propagates each tag
+ *   through the construct subtree to every taggable descendant.
+ * - `byComponent` entries are applied to `componentScopes[key]` —
+ *   each component's own scope, which under
+ *   {@link ComposedSystem.withStacks} or
+ *   {@link ComposedSystem.withStackStrategy} may be a per-component
+ *   stack rather than the top-level scope.
+ *
+ * Tag keys and values are validated synchronously inside the hook before
+ * any `Tags.of(...).add(...)` call. Invalid tags throw and surface at the
+ * `compose(...).afterBuild(tags({...}))` site rather than at deploy time.
+ *
+ * Builder-level tags (set via `.tag()` / `.tags()` on individual builders)
+ * land on closer-scoped constructs and therefore win on key collision —
+ * CDK's tag priority resolves the collision automatically. Use builder
+ * tags for selector tags that must match exactly one resource type;
+ * use this helper for system-wide concerns like ownership, environment,
+ * and cost-allocation dimensions.
+ *
+ * @param defs - System-wide and per-component tag definitions.
+ * @returns An `AfterBuildHook` to pass to {@link ComposedSystem.afterBuild}.
+ *
+ * @example
+ * ```ts
+ * import { compose } from "@composurecdk/core";
+ * import { tags } from "@composurecdk/cloudformation";
+ *
+ * compose(
+ *   { agent: createInstanceBuilder(), bucket: createBucketBuilder() },
+ *   { agent: [], bucket: [] },
+ * )
+ *   .afterBuild(
+ *     tags({
+ *       system: { Owner: "platform", Environment: "prod" },
+ *       byComponent: { agent: { Project: "claude-rig" } },
+ *     }),
+ *   )
+ *   .build(stack, "MySystem");
+ * ```
+ */
+export declare function tags<T extends object = object>(defs: TagDefinitions<T>): AfterBuildHook<T>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACvD;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CA+B1F"}

package/dist/tags.js

@@ -0,0 +1,83 @@
+import { applyTagsToConstruct } from "./apply-builder-tags.js";
+import { validateTagRecord } from "./tag-validator.js";
+/**
+ * Returns an {@link AfterBuildHook} that applies cross-cutting tags to a
+ * composed system. Modelled on {@link outputs} — both share the same
+ * `(scope, id, results, componentScopes)` shape and live alongside the
+ * other CloudFormation-flavoured composition helpers in this package.
+ *
+ * The hook walks the supplied {@link TagDefinitions} once per build:
+ *
+ * - `system` entries are applied to the top-level `scope` via
+ *   `Tags.of(scope).add(...)`. CDK's tag aspect propagates each tag
+ *   through the construct subtree to every taggable descendant.
+ * - `byComponent` entries are applied to `componentScopes[key]` —
+ *   each component's own scope, which under
+ *   {@link ComposedSystem.withStacks} or
+ *   {@link ComposedSystem.withStackStrategy} may be a per-component
+ *   stack rather than the top-level scope.
+ *
+ * Tag keys and values are validated synchronously inside the hook before
+ * any `Tags.of(...).add(...)` call. Invalid tags throw and surface at the
+ * `compose(...).afterBuild(tags({...}))` site rather than at deploy time.
+ *
+ * Builder-level tags (set via `.tag()` / `.tags()` on individual builders)
+ * land on closer-scoped constructs and therefore win on key collision —
+ * CDK's tag priority resolves the collision automatically. Use builder
+ * tags for selector tags that must match exactly one resource type;
+ * use this helper for system-wide concerns like ownership, environment,
+ * and cost-allocation dimensions.
+ *
+ * @param defs - System-wide and per-component tag definitions.
+ * @returns An `AfterBuildHook` to pass to {@link ComposedSystem.afterBuild}.
+ *
+ * @example
+ * ```ts
+ * import { compose } from "@composurecdk/core";
+ * import { tags } from "@composurecdk/cloudformation";
+ *
+ * compose(
+ *   { agent: createInstanceBuilder(), bucket: createBucketBuilder() },
+ *   { agent: [], bucket: [] },
+ * )
+ *   .afterBuild(
+ *     tags({
+ *       system: { Owner: "platform", Environment: "prod" },
+ *       byComponent: { agent: { Project: "claude-rig" } },
+ *     }),
+ *   )
+ *   .build(stack, "MySystem");
+ * ```
+ */
+export function tags(defs) {
+    // Validate eagerly so configuration errors surface at the call site.
+    if (defs.system) {
+        validateTagRecord(defs.system);
+    }
+    const byComponent = defs.byComponent;
+    if (byComponent) {
+        for (const componentTags of Object.values(byComponent)) {
+            if (componentTags === undefined)
+                continue;
+            validateTagRecord(componentTags);
+        }
+    }
+    return (scope, _id, _results, componentScopes) => {
+        if (defs.system) {
+            applyTagsToConstruct(scope, Object.entries(defs.system));
+        }
+        if (byComponent) {
+            const scopesByKey = componentScopes;
+            for (const [componentKey, componentTags] of Object.entries(byComponent)) {
+                if (componentTags === undefined)
+                    continue;
+                const target = scopesByKey[componentKey];
+                if (target === undefined) {
+                    throw new Error(`tags(): byComponent entry "${componentKey}" is not a known component.`);
+                }
+                applyTagsToConstruct(target, Object.entries(componentTags));
+            }
+        }
+    };
+}
+//# sourceMappingURL=tags.js.map

package/dist/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA2CvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,IAAI,CAA4B,IAAuB;IACrE,qEAAqE;IACrE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,WAEZ,CAAC;IACd,IAAI,WAAW,EAAE,CAAC;QAChB,KAAK,MAAM,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;YACvD,IAAI,aAAa,KAAK,SAAS;gBAAE,SAAS;YAC1C,iBAAiB,CAAC,aAAa,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,eAAe,EAAE,EAAE;QAC/C,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,WAAW,GAAG,eAAmE,CAAC;YACxF,KAAK,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBACxE,IAAI,aAAa,KAAK,SAAS;oBAAE,SAAS;gBAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;gBACzC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,6BAA6B,CAAC,CAAC;gBAC3F,CAAC;gBACD,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/cloudformation",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Composable CloudFormation stack builder and stack assignment strategies",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/core": "^0.5.0",
+    "@composurecdk/core": "^0.7.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },