@composurecdk/lambda 0.8.4 → 0.8.6

package/README.md

@@ -125,16 +125,21 @@ Opt back into CDK's auto-created role attached to `AWSLambdaBasicExecutionRole`.
 
 The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#Lambda) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
 
-| Alarm                    | Metric                            | Default threshold           | Created when                          |
-| ------------------------ | --------------------------------- | --------------------------- | ------------------------------------- |
-| `errors`                 | Errors (Sum, 1 min)               | > 0                         | Always                                |
-| `throttles`              | Throttles (Sum, 1 min)            | > 0                         | Always                                |
-| `duration`               | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                      |
-| `concurrentExecutions`   | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set |
-| `<key>FailedInvocations` | FailedInvokeEventCount (Sum)      | > 0                         | An SQS event source is attached       |
-| `<key>DroppedEvents`     | DroppedEventCount (Sum)           | > 0                         | An SQS event source is attached       |
+| Alarm                    | Metric                            | Default threshold           | Created when                           |
+| ------------------------ | --------------------------------- | --------------------------- | -------------------------------------- |
+| `errors`                 | Errors (Sum, 1 min)               | > 0                         | Always                                 |
+| `throttles`              | Throttles (Sum, 1 min)            | > 0                         | Always                                 |
+| `duration`               | Duration (p99, 1 min)             | > 90% of configured timeout | `timeout` is set                       |
+| `concurrentExecutions`   | ConcurrentExecutions (Max, 1 min) | >= 80% of reserved limit    | `reservedConcurrentExecutions` is set  |
+| `<key>FailedInvocations` | FailedInvokeEventCount (Sum)      | > 0                         | An SQS or DynamoDB source is attached  |
+| `<key>DroppedEvents`     | DroppedEventCount (Sum)           | > 0                         | An SQS or DynamoDB source is attached  |
+| `iteratorAge`            | IteratorAge (Max, 1 min)          | > 60000 ms for 3 min¹       | A stream source (DynamoDB) is attached |
 
-The event-source alarms are contextual: one pair is created per event source attached via `addEventSource` (see [Event sources](#event-sources)) whose kind emits per-mapping ESM metrics. Each alarm's key is the event source's key suffixed with `FailedInvocations` / `DroppedEvents` — e.g. an event source added as `"orders"` produces `ordersFailedInvocations` and `ordersDroppedEvents`. The `eventSourceFailedInvocations` / `eventSourceDroppedEvents` fields on `recommendedAlarms` tune every such alarm.
+¹ AWS recommends alarming on `IteratorAge` for stream consumers but prescribes no fixed threshold — it is workload dependent. The 60s/3-minute default is deliberately conservative; tune it per workload via `eventSourceIteratorAge`.
+
+The per-mapping event-source alarms are contextual: one pair is created per event source attached via `addEventSource` (see [Event sources](#event-sources)) whose kind emits per-mapping ESM metrics. Each alarm's key is the event source's key suffixed with `FailedInvocations` / `DroppedEvents` — e.g. an event source added as `"orders"` produces `ordersFailedInvocations` and `ordersDroppedEvents`. The `eventSourceFailedInvocations` / `eventSourceDroppedEvents` fields on `recommendedAlarms` tune every such alarm.
+
+`iteratorAge` is different: `IteratorAge` is a function-level metric, so a single alarm (keyed `iteratorAge`) is created whenever at least one stream source (currently DynamoDB streams) is attached, regardless of how many. It warns when the consumer falls behind its stream. Tune or disable it via the `eventSourceIteratorAge` field on `recommendedAlarms`.
 
 The defaults are exported as `FUNCTION_ALARM_DEFAULTS` for visibility and testing:
 
@@ -226,9 +231,10 @@ for (const alarm of Object.values(result.alarms)) {
 function can have many event sources of mixed types, so the hook is repeatable
 and keyed — the resolved sources are exposed on `result.eventSources`.
 
-Pass a `ComposureEventSource` from a factory (`sqsEventSource`), which carries
-its own `Resolvable` so the source queue can be a `ref()` to a sibling
-component, or a bare CDK `IEventSource` as an escape hatch.
+Pass a `ComposureEventSource` from a factory (`sqsEventSource`,
+`dynamoEventSource`), which carries its own `Resolvable` so the source queue or
+table can be a `ref()` to a sibling component, or a bare CDK `IEventSource` as
+an escape hatch.
 
 ```ts
 import { compose, ref } from "@composurecdk/core";
@@ -250,7 +256,44 @@ const system = compose(
 
 The source is attached _after_ the function and its least-privilege execution
 role exist, so the `source.bind(fn)` that `addEventSource` performs grants the
-queue-consume permission onto the builder's role rather than CDK's auto-role.
+consume permission (SQS `ReceiveMessage`, or DynamoDB `grantStreamRead`) onto
+the builder's role rather than CDK's auto-role.
+
+`dynamoEventSource(table, props?)` mirrors the SQS factory for DynamoDB streams.
+The table must have a stream enabled (via the [DynamoDB builder](../dynamodb)'s
+`.dynamoStream(...)` / `.stream(...)`, or `TableProps.stream`); otherwise CDK
+throws `DynamoDB Streams must be enabled` at build time. `startingPosition`
+defaults to `LATEST` and is overridable via `props`:
+
+```ts
+import { StartingPosition } from "aws-cdk-lib/aws-lambda";
+import { StreamViewType } from "aws-cdk-lib/aws-dynamodb";
+import { compose, ref } from "@composurecdk/core";
+import { createFunctionBuilder, dynamoEventSource } from "@composurecdk/lambda";
+import { createTableV2Builder } from "@composurecdk/dynamodb";
+
+compose(
+  {
+    orders: createTableV2Builder()
+      .partitionKey({ name: "pk", type: AttributeType.STRING })
+      .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES),
+    processor: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("lambda"))
+      .addEventSource(
+        "orders",
+        dynamoEventSource(
+          ref("orders", (r) => r.table),
+          {
+            startingPosition: StartingPosition.TRIM_HORIZON,
+          },
+        ),
+      ),
+  },
+  { orders: [], processor: ["orders"] },
+);
+```
 
 ### Secure defaults
 
@@ -262,6 +305,15 @@ second `props` argument and exported as `DEFAULT_SQS_EVENT_SOURCE_PROPS`:
 | `reportBatchItemFailures` | `true`                      | A single poison message fails only its own record, not the whole batch. CDK defaults this `false`. |
 | `metricsConfig`           | `{ metrics: [EventCount] }` | Enables the per-mapping ESM metrics that back the event-source contextual alarms.                  |
 
+`dynamoEventSource` applies the same defaults plus `startingPosition`, exported
+as `DEFAULT_DYNAMO_EVENT_SOURCE_PROPS`:
+
+| Property                  | Default                     | Rationale                                                                                         |
+| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `startingPosition`        | `LATEST`                    | A newly-attached consumer reads from the stream tip, not the table's existing change history.     |
+| `reportBatchItemFailures` | `true`                      | A single poison record fails only its own record, not the whole batch. CDK defaults this `false`. |
+| `metricsConfig`           | `{ metrics: [EventCount] }` | Enables the per-mapping ESM metrics that back the event-source contextual alarms.                 |
+
 ### Cross-component invariants
 
 AWS Well-Architected guidance spans the queue and the function — the source
@@ -271,9 +323,8 @@ today (the queue often arrives as an unresolved `ref()`); they are tracked in
 [#123](https://github.com/laazyj/composureCDK/issues/123) and
 [#124](https://github.com/laazyj/composureCDK/issues/124).
 
-`kinesisEventSource` / `dynamoEventSource` and the stream-only `IteratorAge`
-alarm are deferred — see [#120](https://github.com/laazyj/composureCDK/issues/120)
-and [#121](https://github.com/laazyj/composureCDK/issues/121).
+`kinesisEventSource` is still deferred — see
+[#120](https://github.com/laazyj/composureCDK/issues/120).
 
 ## Examples
 

package/dist/commonjs/alarm-config.d.ts

@@ -110,5 +110,27 @@ export interface FunctionAlarmConfig {
      * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
      */
     eventSourceDroppedEvents?: AlarmConfig | false;
+    /**
+     * Alarm when the function is falling behind a stream event source.
+     *
+     * Contextual: a single alarm is created when at least one stream event
+     * source (currently DynamoDB streams) is attached via
+     * {@link IFunctionBuilder.addEventSource}. Unlike the per-mapping
+     * {@link FunctionAlarmConfig.eventSourceFailedInvocations} /
+     * {@link FunctionAlarmConfig.eventSourceDroppedEvents} alarms, `IteratorAge`
+     * is a function-level metric, so there is one alarm per function (keyed
+     * `iteratorAge`) regardless of how many stream sources are attached.
+     *
+     * The threshold is an absolute age in milliseconds (not a percentage).
+     *
+     * Metric: `AWS/Lambda IteratorAge`, statistic Maximum, period 1 minute,
+     * dimensioned on `FunctionName`. AWS recommends alarming on this metric for
+     * stream consumers but does not prescribe a threshold (it is workload
+     * dependent); the default is a deliberately conservative > 60000 ms (60s) for
+     * 3 consecutive minutes.
+     *
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/monitoring-metrics.html
+     */
+    eventSourceIteratorAge?: AlarmConfig | false;
 }
 //# sourceMappingURL=alarm-config.d.ts.map

package/dist/commonjs/alarm-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IACnE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAErD;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAChD"}
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG;IACnE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC,CAAC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAErD;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,wBAAwB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC9C"}

package/dist/commonjs/alarm-defaults.d.ts

@@ -8,6 +8,7 @@ interface FunctionAlarmDefaults {
     concurrentExecutions: PercentageAlarmConfigDefaults;
     eventSourceFailedInvocations: AlarmConfigDefaults;
     eventSourceDroppedEvents: AlarmConfigDefaults;
+    eventSourceIteratorAge: AlarmConfigDefaults;
 }
 /**
  * AWS-recommended default alarm configuration for Lambda functions.

package/dist/commonjs/alarm-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,6BAA6B,CAAC;IACxC,oBAAoB,EAAE,6BAA6B,CAAC;IACpD,4BAA4B,EAAE,mBAAmB,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,CAAC;CAC/C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAwDrC,CAAC"}
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,6BAA6B,CAAC;IACxC,oBAAoB,EAAE,6BAA6B,CAAC;IACpD,4BAA4B,EAAE,mBAAmB,CAAC;IAClD,wBAAwB,EAAE,mBAAmB,CAAC;IAC9C,sBAAsB,EAAE,mBAAmB,CAAC;CAC7C;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAwErC,CAAC"}

package/dist/commonjs/alarm-defaults.js

@@ -57,5 +57,20 @@ exports.FUNCTION_ALARM_DEFAULTS = {
         datapointsToAlarm: 1,
         treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
     },
+    /**
+     * The consumer falling behind the stream risks data loss once records age
+     * past the stream's 24h retention. AWS recommends alarming on `IteratorAge`
+     * for stream consumers but publishes no fixed threshold — the right value is
+     * workload dependent. 60s of sustained lag for 3 consecutive minutes is a
+     * deliberately conservative default; tune via `eventSourceIteratorAge`. Idle
+     * functions emit no datapoints and stay OK (`NOT_BREACHING`).
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/monitoring-metrics.html
+     */
+    eventSourceIteratorAge: {
+        threshold: 60_000,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
 };
 //# sourceMappingURL=alarm-defaults.js.map

package/dist/commonjs/alarm-defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAc9D;;;;GAIG;AACU,QAAA,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb,qDAAqD;IACrD,MAAM,EAAE;QACN,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,6DAA6D;IAC7D,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,QAAQ,EAAE;QACR,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,oBAAoB,EAAE;QACpB,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,sFAAsF;IACtF,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,mDAAmD;IACnD,wBAAwB,EAAE;QACxB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../../src/alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAe9D;;;;GAIG;AACU,QAAA,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb,qDAAqD;IACrD,MAAM,EAAE;QACN,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,6DAA6D;IAC7D,SAAS,EAAE;QACT,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,QAAQ,EAAE;QACR,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,oBAAoB,EAAE;QACpB,gBAAgB,EAAE,GAAG;QACrB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,sFAAsF;IACtF,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,mDAAmD;IACnD,wBAAwB,EAAE;QACxB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;;;;OAQG;IACH,sBAAsB,EAAE;QACtB,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/event-sources/composure-event-source.d.ts

@@ -9,7 +9,7 @@ import type { Resolvable } from "@composurecdk/core";
  * straight to {@link IFunctionBuilder.addEventSource} as an escape hatch —
  * the builder still attaches it, but cannot reason about it.
  */
-export type EventSourceKind = "sqs" | "unknown";
+export type EventSourceKind = "sqs" | "dynamodb" | "unknown";
 /** @internal — brands {@link ComposureEventSource} so the guard is unambiguous. */
 declare const COMPOSURE_EVENT_SOURCE: unique symbol;
 /**
@@ -40,9 +40,9 @@ export declare function composureEventSource(kind: EventSourceKind, source: Reso
 /**
  * Reads the event source mapping UUID off a bound CDK source, keyed by
  * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
- * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
- * the reader after `addEventSource` so the binding exists. Keying off `kind`
- * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * metrics back contextual alarms (SQS and DynamoDB streams); `FunctionBuilder`
+ * invokes the reader after `addEventSource` so the binding exists. Keying off
+ * `kind` — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
  * `instanceof`-ing CDK source classes.
  *
  * @internal

package/dist/commonjs/event-sources/composure-event-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,SAAS,CAAC;AAEhD,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAO9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}
+{"version":3,"file":"composure-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;AAE7D,mFAAmF;AACnF,QAAA,MAAM,sBAAsB,eAAgD,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB;IAChB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,GAC/B,oBAAoB,CAEtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAClD,eAAe,EACf,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC,GAAG,SAAS,CAW9C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GACzC,KAAK,IAAI,oBAAoB,CAE/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,8DAA8D;IAC9D,IAAI,EAAE,eAAe,CAAC;IAEtB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/commonjs/event-sources/composure-event-source.js

@@ -12,9 +12,9 @@ function composureEventSource(kind, source) {
 /**
  * Reads the event source mapping UUID off a bound CDK source, keyed by
  * {@link EventSourceKind}. Defined only for kinds whose per-mapping ESM
- * metrics back contextual alarms (currently SQS); `FunctionBuilder` invokes
- * the reader after `addEventSource` so the binding exists. Keying off `kind`
- * — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
+ * metrics back contextual alarms (SQS and DynamoDB streams); `FunctionBuilder`
+ * invokes the reader after `addEventSource` so the binding exists. Keying off
+ * `kind` — like {@link EVENT_SOURCE_ALARM_SPECS} — keeps the builder from
  * `instanceof`-ing CDK source classes.
  *
  * @internal
@@ -24,6 +24,10 @@ exports.EVENT_SOURCE_MAPPING_ID_READERS = {
     // constructs the `SqsEventSource` in the same call — kind and concrete class
     // move in lockstep.
     sqs: (bound) => bound.eventSourceMappingId,
+    // Safe: the `"dynamodb"` kind is only ever assigned by `dynamoEventSource()`,
+    // which constructs the `DynamoEventSource` in the same call — kind and
+    // concrete class move in lockstep.
+    dynamodb: (bound) => bound.eventSourceMappingId,
     unknown: undefined,
 };
 /**

package/dist/commonjs/event-sources/composure-event-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":";;;AA6CA,oDAKC;AA2BD,wDAIC;AAlED,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,SAAgB,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}
+{"version":3,"file":"composure-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/composure-event-source.ts"],"names":[],"mappings":";;;AA6CA,oDAKC;AA+BD,wDAIC;AAtED,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AA4B7E,oEAAoE;AACpE,SAAgB,oBAAoB,CAClC,IAAqB,EACrB,MAAgC;IAEhC,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;;;GASG;AACU,QAAA,+BAA+B,GAGxC;IACF,4EAA4E;IAC5E,6EAA6E;IAC7E,oBAAoB;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAAwB,CAAC,oBAAoB;IAC9D,8EAA8E;IAC9E,uEAAuE;IACvE,mCAAmC;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAE,KAA2B,CAAC,oBAAoB;IACtE,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF;;;GAGG;AACH,SAAgB,sBAAsB,CACpC,KAA0C;IAE1C,OAAO,sBAAsB,IAAI,KAAK,CAAC;AACzC,CAAC"}

package/dist/commonjs/event-sources/dynamodb-event-source.d.ts

@@ -0,0 +1,55 @@
+import type { ITable } from "aws-cdk-lib/aws-dynamodb";
+import { type DynamoEventSourceProps } from "aws-cdk-lib/aws-lambda-event-sources";
+import { type Resolvable } from "@composurecdk/core";
+import { type ComposureEventSource } from "./composure-event-source.js";
+/**
+ * Secure, AWS-recommended defaults applied to every DynamoDB stream event
+ * source built with {@link dynamoEventSource}. Each property can be overridden
+ * via the factory's `props` argument.
+ */
+export declare const DEFAULT_DYNAMO_EVENT_SOURCE_PROPS: Pick<DynamoEventSourceProps, "startingPosition" | "reportBatchItemFailures" | "metricsConfig">;
+/**
+ * Wraps a DynamoDB table's change stream as a Lambda {@link IEventSource},
+ * deferring resolution when the table is a `ref()` to a sibling component's
+ * output.
+ *
+ * Follows the `events/targets` factory shape: register the result with
+ * {@link IFunctionBuilder.addEventSource} and the builder resolves the
+ * `ref()`, attaches the source, and (because `addEventSource` calls
+ * `source.bind(fn)`) grants the function's least-privilege execution role
+ * permission to read the stream via `grantStreamRead`.
+ *
+ * Applies {@link DEFAULT_DYNAMO_EVENT_SOURCE_PROPS}; pass `props` to override.
+ *
+ * ## Cross-component invariant (enforced by CDK at bind time)
+ *
+ * The table must have a stream enabled (via the table builder's
+ * `.dynamoStream(...)` / `.stream(...)`, or `TableProps.stream`). If it does
+ * not, CDK's `DynamoEventSource.bind()` throws `DynamoDB Streams must be
+ * enabled on the table` when the function is built — the table often arrives
+ * as a `ref()` that is not resolvable at configuration time, so this is not
+ * validated earlier.
+ *
+ * @param table - The source table, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_DYNAMO_EVENT_SOURCE_PROPS} and
+ *   any other {@link DynamoEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     orders: createTableV2Builder()
+ *       .partitionKey({ name: "pk", type: AttributeType.STRING })
+ *       .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource("orders", dynamoEventSource(ref("orders", (r) => r.table))),
+ *   },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+export declare function dynamoEventSource(table: Resolvable<ITable>, props?: DynamoEventSourceProps): ComposureEventSource;
+//# sourceMappingURL=dynamodb-event-source.d.ts.map

package/dist/commonjs/event-sources/dynamodb-event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAE,IAAI,CAClD,sBAAsB,EACtB,kBAAkB,GAAG,yBAAyB,GAAG,eAAe,CA0BjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,sBAAsB,GAC7B,oBAAoB,CAMtB"}

package/dist/commonjs/event-sources/dynamodb-event-source.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = void 0;
+exports.dynamoEventSource = dynamoEventSource;
+const aws_lambda_1 = require("aws-cdk-lib/aws-lambda");
+const aws_lambda_event_sources_1 = require("aws-cdk-lib/aws-lambda-event-sources");
+const core_1 = require("@composurecdk/core");
+const composure_event_source_js_1 = require("./composure-event-source.js");
+/**
+ * Secure, AWS-recommended defaults applied to every DynamoDB stream event
+ * source built with {@link dynamoEventSource}. Each property can be overridden
+ * via the factory's `props` argument.
+ */
+exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = {
+    /**
+     * Start reading from the tip of the stream so a newly-attached consumer does
+     * not replay the table's existing change history on first deploy. Override
+     * with {@link StartingPosition.TRIM_HORIZON} to reprocess from the oldest
+     * record in the stream.
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html
+     */
+    startingPosition: aws_lambda_1.StartingPosition.LATEST,
+    /**
+     * Report partial batch failures so a single poison record does not fail the
+     * whole batch and force redelivery of already-processed records. CDK
+     * defaults this to `false`.
+     * @see https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-batchfailurereporting
+     */
+    reportBatchItemFailures: true,
+    /**
+     * Enable the per-mapping `EventCount` ESM metrics (`FailedInvokeEventCount`,
+     * `DroppedEventCount`, …). They emit only when opted in, and the
+     * event-source contextual alarms on {@link IFunctionBuilder} depend on them.
+     * @see https://aws.amazon.com/blogs/compute/introducing-new-event-source-mapping-esm-metrics-for-aws-lambda/
+     */
+    metricsConfig: { metrics: [aws_lambda_1.MetricType.EVENT_COUNT] },
+};
+/**
+ * Wraps a DynamoDB table's change stream as a Lambda {@link IEventSource},
+ * deferring resolution when the table is a `ref()` to a sibling component's
+ * output.
+ *
+ * Follows the `events/targets` factory shape: register the result with
+ * {@link IFunctionBuilder.addEventSource} and the builder resolves the
+ * `ref()`, attaches the source, and (because `addEventSource` calls
+ * `source.bind(fn)`) grants the function's least-privilege execution role
+ * permission to read the stream via `grantStreamRead`.
+ *
+ * Applies {@link DEFAULT_DYNAMO_EVENT_SOURCE_PROPS}; pass `props` to override.
+ *
+ * ## Cross-component invariant (enforced by CDK at bind time)
+ *
+ * The table must have a stream enabled (via the table builder's
+ * `.dynamoStream(...)` / `.stream(...)`, or `TableProps.stream`). If it does
+ * not, CDK's `DynamoEventSource.bind()` throws `DynamoDB Streams must be
+ * enabled on the table` when the function is built — the table often arrives
+ * as a `ref()` that is not resolvable at configuration time, so this is not
+ * validated earlier.
+ *
+ * @param table - The source table, concrete or a `ref()` to a sibling.
+ * @param props - Overrides for {@link DEFAULT_DYNAMO_EVENT_SOURCE_PROPS} and
+ *   any other {@link DynamoEventSourceProps}.
+ *
+ * @example
+ * ```ts
+ * compose(
+ *   {
+ *     orders: createTableV2Builder()
+ *       .partitionKey({ name: "pk", type: AttributeType.STRING })
+ *       .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES),
+ *     processor: createFunctionBuilder()
+ *       .runtime(Runtime.NODEJS_22_X)
+ *       .handler("index.handler")
+ *       .code(Code.fromAsset("lambda"))
+ *       .addEventSource("orders", dynamoEventSource(ref("orders", (r) => r.table))),
+ *   },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+function dynamoEventSource(table, props) {
+    const merged = { ...exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS, ...props };
+    const source = (0, core_1.isRef)(table)
+        ? table.map((resolved) => new aws_lambda_event_sources_1.DynamoEventSource(resolved, merged))
+        : new aws_lambda_event_sources_1.DynamoEventSource(table, merged);
+    return (0, composure_event_source_js_1.composureEventSource)("dynamodb", source);
+}
+//# sourceMappingURL=dynamodb-event-source.js.map

package/dist/commonjs/event-sources/dynamodb-event-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/dynamodb-event-source.ts"],"names":[],"mappings":";;;AAwFA,8CASC;AA/FD,uDAAsE;AACtE,mFAG8C;AAC9C,6CAA4D;AAC5D,2EAA8F;AAE9F;;;;GAIG;AACU,QAAA,iCAAiC,GAG1C;IACF;;;;;;OAMG;IACH,gBAAgB,EAAE,6BAAgB,CAAC,MAAM;IAEzC;;;;;OAKG;IACH,uBAAuB,EAAE,IAAI;IAE7B;;;;;OAKG;IACH,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,uBAAU,CAAC,WAAW,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,SAAgB,iBAAiB,CAC/B,KAAyB,EACzB,KAA8B;IAE9B,MAAM,MAAM,GAA2B,EAAE,GAAG,yCAAiC,EAAE,GAAG,KAAK,EAAE,CAAC;IAC1F,MAAM,MAAM,GAA6B,IAAA,YAAK,EAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,4CAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAClE,CAAC,CAAC,IAAI,4CAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACzC,OAAO,IAAA,gDAAoB,EAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/dist/commonjs/event-sources/event-source-relationship-guards.d.ts

@@ -0,0 +1,28 @@
+import { type Duration } from "aws-cdk-lib";
+import type { Function as LambdaFunction, IEventSource } from "aws-cdk-lib/aws-lambda";
+import type { EventSourceKind } from "./composure-event-source.js";
+/**
+ * Suppression id for the SQS visibility-timeout relationship guard. Stable and
+ * part of the public surface — silence the warning with
+ * `Annotations.of(scope).acknowledgeWarning(SQS_VISIBILITY_TIMEOUT_WARNING_ID)`,
+ * so it must not be renamed casually.
+ */
+export declare const SQS_VISIBILITY_TIMEOUT_WARNING_ID = "@composurecdk/lambda:sqs-visibility-timeout";
+/**
+ * Guards a cross-component relationship that spans an attached event source and
+ * its consumer function. `FunctionBuilder` dispatches on {@link EventSourceKind}
+ * so it never has to `instanceof` CDK internals — see ADR-0011.
+ *
+ * @internal
+ */
+export type EventSourceRelationshipGuard = (fn: LambdaFunction, id: string, key: string, bound: IEventSource, timeout: Duration | undefined) => void;
+/**
+ * Per-kind relationship guards, keyed by {@link EventSourceKind}. A kind maps to
+ * the (possibly empty) list of relationships to guard for a source of that kind
+ * — SQS gains a second entry for the `maxReceiveCount` floor (#124), and a bare
+ * escape-hatch source attached as `"unknown"` has none.
+ *
+ * @internal
+ */
+export declare const EVENT_SOURCE_RELATIONSHIP_GUARDS: Record<EventSourceKind, EventSourceRelationshipGuard[]>;
+//# sourceMappingURL=event-source-relationship-guards.d.ts.map

package/dist/commonjs/event-sources/event-source-relationship-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-source-relationship-guards.d.ts","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,QAAQ,EAAS,MAAM,aAAa,CAAC;AACtF,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAIvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAiBnE;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,gDAAgD,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,CACzC,EAAE,EAAE,cAAc,EAClB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,QAAQ,GAAG,SAAS,KAC1B,IAAI,CAAC;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CACnD,eAAe,EACf,4BAA4B,EAAE,CAK/B,CAAC"}

package/dist/commonjs/event-sources/event-source-relationship-guards.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_SOURCE_RELATIONSHIP_GUARDS = exports.SQS_VISIBILITY_TIMEOUT_WARNING_ID = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_sqs_1 = require("aws-cdk-lib/aws-sqs");
+/**
+ * AWS guidance: an SQS source queue's `visibilityTimeout` should be at least
+ * this multiple of the consumer function's `timeout`, so Lambda has room to
+ * retry a throttled batch before a message becomes visible again.
+ *
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html
+ */
+const SQS_VISIBILITY_TIMEOUT_MULTIPLIER = 6;
+/** Lambda's own default `timeout` when none is set (CDK leaves it unset). */
+const LAMBDA_DEFAULT_TIMEOUT_SECONDS = 3;
+/** SQS's own default `visibilityTimeout` when none is set (applied by CloudFormation). */
+const SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS = 30;
+/**
+ * Suppression id for the SQS visibility-timeout relationship guard. Stable and
+ * part of the public surface — silence the warning with
+ * `Annotations.of(scope).acknowledgeWarning(SQS_VISIBILITY_TIMEOUT_WARNING_ID)`,
+ * so it must not be renamed casually.
+ */
+exports.SQS_VISIBILITY_TIMEOUT_WARNING_ID = "@composurecdk/lambda:sqs-visibility-timeout";
+/**
+ * Per-kind relationship guards, keyed by {@link EventSourceKind}. A kind maps to
+ * the (possibly empty) list of relationships to guard for a source of that kind
+ * — SQS gains a second entry for the `maxReceiveCount` floor (#124), and a bare
+ * escape-hatch source attached as `"unknown"` has none.
+ *
+ * @internal
+ */
+exports.EVENT_SOURCE_RELATIONSHIP_GUARDS = {
+    sqs: [guardSqsVisibilityTimeout],
+    dynamodb: [],
+    unknown: [],
+};
+/**
+ * The source queue behind a bound SQS event source. Safe cast: only reached for
+ * the `"sqs"` kind, whose source `sqsEventSource()` constructs as an
+ * {@link SqsEventSource} in the same call. `SqsEventSource.queue` is a public
+ * getter.
+ */
+function sqsQueue(bound) {
+    return bound.queue;
+}
+/**
+ * Warns when the source queue's `visibilityTimeout` is below 6× the consumer
+ * function's `timeout`. Registers a synth-time Aspect so it reads the queue's
+ * *final* value off its L1 `CfnQueue` — the value the L2 `Queue` does not
+ * re-expose — regardless of build order or later mutation (ADR-0011).
+ */
+function guardSqsVisibilityTimeout(fn, id, key, bound, timeout) {
+    const queue = sqsQueue(bound);
+    aws_cdk_lib_1.Aspects.of(fn).add({
+        visit(node) {
+            // The Aspect visits fn and its subtree; act once, against fn itself.
+            if (node !== fn)
+                return;
+            const target = targetVisibilityTimeoutSeconds(timeout);
+            if (target === undefined)
+                return; // token timeout — no concrete target to compare
+            const actual = readVisibilityTimeoutSeconds(queue);
+            if (actual === undefined || actual >= target)
+                return; // unknowable or compliant — stay quiet
+            aws_cdk_lib_1.Annotations.of(fn).addWarningV2(exports.SQS_VISIBILITY_TIMEOUT_WARNING_ID, `FunctionBuilder "${id}": SQS event source "${key}" — source queue visibilityTimeout is ` +
+                `${String(actual)}s but should be >= ${String(target)}s ` +
+                `(${String(SQS_VISIBILITY_TIMEOUT_MULTIPLIER)}x the function timeout) so Lambda can retry ` +
+                `a throttled batch. See https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html`);
+        },
+    });
+}
+/**
+ * The 6× target in seconds, derived from the function timeout (or Lambda's 3s
+ * default). `undefined` when the timeout is a token, which has no concrete
+ * target at synth time. Guards `isUnresolved` *before* converting, so a token
+ * Duration never reaches `toSeconds()`.
+ */
+function targetVisibilityTimeoutSeconds(timeout) {
+    if (timeout === undefined) {
+        return SQS_VISIBILITY_TIMEOUT_MULTIPLIER * LAMBDA_DEFAULT_TIMEOUT_SECONDS;
+    }
+    if (timeout.isUnresolved())
+        return undefined;
+    return SQS_VISIBILITY_TIMEOUT_MULTIPLIER * timeout.toSeconds();
+}
+/**
+ * The queue's resolved `visibilityTimeout` in seconds, read off its L1
+ * `CfnQueue` (the L2 `Queue` does not re-expose it). `undefined` when the queue
+ * is imported (no L1 child) or the value is an unresolved token; `30` (the SQS
+ * default) when the L1 carries no explicit value.
+ */
+function readVisibilityTimeoutSeconds(queue) {
+    const child = queue.node.defaultChild;
+    if (child === undefined ||
+        !aws_cdk_lib_1.CfnResource.isCfnResource(child) ||
+        child.cfnResourceType !== aws_sqs_1.CfnQueue.CFN_RESOURCE_TYPE_NAME) {
+        return undefined;
+    }
+    const value = child.visibilityTimeout;
+    if (value === undefined)
+        return SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS;
+    return aws_cdk_lib_1.Token.isUnresolved(value) ? undefined : value;
+}
+//# sourceMappingURL=event-source-relationship-guards.js.map

package/dist/commonjs/event-sources/event-source-relationship-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-source-relationship-guards.js","sourceRoot":"","sources":["../../../src/event-sources/event-source-relationship-guards.ts"],"names":[],"mappings":";;;AAAA,6CAAsF;AAGtF,iDAA4D;AAI5D;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAE5C,6EAA6E;AAC7E,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEzC,0FAA0F;AAC1F,MAAM,sCAAsC,GAAG,EAAE,CAAC;AAElD;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG,6CAA6C,CAAC;AAiB/F;;;;;;;GAOG;AACU,QAAA,gCAAgC,GAGzC;IACF,GAAG,EAAE,CAAC,yBAAyB,CAAC;IAChC,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,EAAE;CACZ,CAAC;AAEF;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,KAAmB;IACnC,OAAQ,KAAwB,CAAC,KAAK,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,SAAS,yBAAyB,CAChC,EAAkB,EAClB,EAAU,EACV,GAAW,EACX,KAAmB,EACnB,OAA6B;IAE7B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9B,qBAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;QACjB,KAAK,CAAC,IAAgB;YACpB,qEAAqE;YACrE,IAAI,IAAI,KAAK,EAAE;gBAAE,OAAO;YAExB,MAAM,MAAM,GAAG,8BAA8B,CAAC,OAAO,CAAC,CAAC;YACvD,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,CAAC,gDAAgD;YAElF,MAAM,MAAM,GAAG,4BAA4B,CAAC,KAAK,CAAC,CAAC;YACnD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,IAAI,MAAM;gBAAE,OAAO,CAAC,uCAAuC;YAE7F,yBAAW,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,YAAY,CAC7B,yCAAiC,EACjC,oBAAoB,EAAE,wBAAwB,GAAG,wCAAwC;gBACvF,GAAG,MAAM,CAAC,MAAM,CAAC,sBAAsB,MAAM,CAAC,MAAM,CAAC,IAAI;gBACzD,IAAI,MAAM,CAAC,iCAAiC,CAAC,8CAA8C;gBAC3F,mFAAmF,CACtF,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,8BAA8B,CAAC,OAA6B;IACnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,iCAAiC,GAAG,8BAA8B,CAAC;IAC5E,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,EAAE;QAAE,OAAO,SAAS,CAAC;IAC7C,OAAO,iCAAiC,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,SAAS,4BAA4B,CAAC,KAAa;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;IACtC,IACE,KAAK,KAAK,SAAS;QACnB,CAAC,yBAAW,CAAC,aAAa,CAAC,KAAK,CAAC;QACjC,KAAK,CAAC,eAAe,KAAK,kBAAQ,CAAC,sBAAsB,EACzD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAI,KAAkB,CAAC,iBAAiB,CAAC;IACpD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,sCAAsC,CAAC;IACvE,OAAO,mBAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACvD,CAAC"}

package/dist/commonjs/event-sources/sqs-event-source.d.ts

@@ -20,16 +20,19 @@ export declare const DEFAULT_SQS_EVENT_SOURCE_PROPS: Pick<SqsEventSourceProps, "
  *
  * Applies {@link DEFAULT_SQS_EVENT_SOURCE_PROPS}; pass `props` to override.
  *
- * ## Cross-component invariants (not enforced)
+ * ## Cross-component invariants
  *
  * AWS Well-Architected guidance spans the queue and the function:
  * - the source queue's visibility timeout should be ≥ 6× the function
  *   timeout, leaving room for Lambda to retry a throttled batch;
  * - the source queue's redrive `maxReceiveCount` should be ≥ 5 before the DLQ.
  *
- * These are not validated here — the queue often arrives as a `ref()` that is
- * not resolvable at configuration time. Tracked in laazyj/composureCDK#123
- * and #124.
+ * The visibility-timeout rule is enforced as a synth-time **relationship
+ * guard**: when this source is attached to a {@link IFunctionBuilder}, the
+ * builder reads the queue's resolved `visibilityTimeout` off its L1 `CfnQueue`
+ * (the `Queue` construct does not re-expose it) and warns, suppressibly, on an
+ * actual violation — see ADR-0011. The `maxReceiveCount` floor is tracked in
+ * laazyj/composureCDK#124.
  *
  * @param queue - The source queue, concrete or a `ref()` to a sibling.
  * @param props - Overrides for {@link DEFAULT_SQS_EVENT_SOURCE_PROPS} and any

package/dist/commonjs/event-sources/sqs-event-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqs-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,IAAI,CAC/C,mBAAmB,EACnB,yBAAyB,GAAG,eAAe,CAkB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,oBAAoB,CAMtB"}
+{"version":3,"file":"sqs-event-source.d.ts","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,oBAAoB,EAAwB,MAAM,6BAA6B,CAAC;AAE9F;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,IAAI,CAC/C,mBAAmB,EACnB,yBAAyB,GAAG,eAAe,CAkB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,oBAAoB,CAMtB"}

package/dist/commonjs/event-sources/sqs-event-source.js

@@ -40,16 +40,19 @@ exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = {
  *
  * Applies {@link DEFAULT_SQS_EVENT_SOURCE_PROPS}; pass `props` to override.
  *
- * ## Cross-component invariants (not enforced)
+ * ## Cross-component invariants
  *
  * AWS Well-Architected guidance spans the queue and the function:
  * - the source queue's visibility timeout should be ≥ 6× the function
  *   timeout, leaving room for Lambda to retry a throttled batch;
  * - the source queue's redrive `maxReceiveCount` should be ≥ 5 before the DLQ.
  *
- * These are not validated here — the queue often arrives as a `ref()` that is
- * not resolvable at configuration time. Tracked in laazyj/composureCDK#123
- * and #124.
+ * The visibility-timeout rule is enforced as a synth-time **relationship
+ * guard**: when this source is attached to a {@link IFunctionBuilder}, the
+ * builder reads the queue's resolved `visibilityTimeout` off its L1 `CfnQueue`
+ * (the `Queue` construct does not re-expose it) and warns, suppressibly, on an
+ * actual violation — see ADR-0011. The `maxReceiveCount` floor is tracked in
+ * laazyj/composureCDK#124.
  *
  * @param queue - The source queue, concrete or a `ref()` to a sibling.
  * @param props - Overrides for {@link DEFAULT_SQS_EVENT_SOURCE_PROPS} and any

package/dist/commonjs/event-sources/sqs-event-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqs-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":";;;AA4EA,wCASC;AApFD,uDAAoD;AACpD,mFAAgG;AAEhG,6CAA4D;AAC5D,2EAA8F;AAE9F;;;;GAIG;AACU,QAAA,8BAA8B,GAGvC;IACF;;;;;;OAMG;IACH,uBAAuB,EAAE,IAAI;IAE7B;;;;;OAKG;IACH,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,uBAAU,CAAC,WAAW,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,cAAc,CAC5B,KAAyB,EACzB,KAA2B;IAE3B,MAAM,MAAM,GAAwB,EAAE,GAAG,sCAA8B,EAAE,GAAG,KAAK,EAAE,CAAC;IACpF,MAAM,MAAM,GAA6B,IAAA,YAAK,EAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,yCAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC,IAAI,yCAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,IAAA,gDAAoB,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"sqs-event-source.js","sourceRoot":"","sources":["../../../src/event-sources/sqs-event-source.ts"],"names":[],"mappings":";;;AA+EA,wCASC;AAvFD,uDAAoD;AACpD,mFAAgG;AAEhG,6CAA4D;AAC5D,2EAA8F;AAE9F;;;;GAIG;AACU,QAAA,8BAA8B,GAGvC;IACF;;;;;;OAMG;IACH,uBAAuB,EAAE,IAAI;IAE7B;;;;;OAKG;IACH,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,uBAAU,CAAC,WAAW,CAAC,EAAE;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,SAAgB,cAAc,CAC5B,KAAyB,EACzB,KAA2B;IAE3B,MAAM,MAAM,GAAwB,EAAE,GAAG,sCAA8B,EAAE,GAAG,KAAK,EAAE,CAAC;IACpF,MAAM,MAAM,GAA6B,IAAA,YAAK,EAAC,KAAK,CAAC;QACnD,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,yCAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,CAAC,CAAC,IAAI,yCAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,IAAA,gDAAoB,EAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}