sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Lambda/ EventSourceMapping.ts

import * as lambda from "@distilled.cloud/aws/lambda";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasTags, tagRecord } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import { plainJson } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";

export type StartingPosition = "TRIM_HORIZON" | "LATEST" | "AT_TIMESTAMP";

/** Internal retry signal: the mapping has not reached its desired state yet. */
class MappingNotSettled extends Data.TaggedError("MappingNotSettled")<{
  readonly state: string | undefined;
}> {}

/**
 * An SQS queue's visibility timeout is shorter than the function's Lambda
 * timeout, which AWS refuses for an SQS event source. Lambda's timeout is the
 * function's `timeout` plus its `timeoutMargin` (1 second by default).
 */
export class QueueVisibilityTimeoutBelowFunctionTimeout extends Data.TaggedError(
  "QueueVisibilityTimeoutBelowFunctionTimeout",
)<{
  readonly functionName: string;
  readonly eventSourceArn: string;
  readonly message: string;
}> {}

/** AWS's rejection, restated with the setting to change. */
const visibilityTimeoutError = (
  functionName: string,
  eventSourceArn: string,
  error: lambda.QueueVisibilityTimeoutTooShort,
) =>
  new QueueVisibilityTimeoutBelowFunctionTimeout({
    functionName,
    eventSourceArn,
    message:
      `${error.message ?? "Queue visibility timeout is less than Function timeout"}. ` +
      "Lambda runs the function for its `timeout` plus `timeoutMargin` (1 second by " +
      "default), so set the queue's `visibilityTimeout` to at least that sum (AWS " +
      "recommends six times the function timeout), or lower the function's `timeout`.",
  });

export type FunctionResponseType = "ReportBatchItemFailures";

export interface EventSourceMappingProps {
  /**
   * The name or ARN of the Lambda function to invoke.
   */
  functionName: string;
  /**
   * The ARN of the event source (SQS queue, Kinesis stream, DynamoDB stream, etc.).
   */
  eventSourceArn: string;
  /**
   * The maximum number of records in each batch that Lambda pulls and sends to the function.
   *
   * - SQS: default 10, max 10,000 (FIFO max 10)
   * - Kinesis: default 100, max 10,000
   * - DynamoDB Streams: default 100, max 10,000
   */
  batchSize?: number;
  /**
   * The maximum amount of time that Lambda spends gathering records before
   * invoking the function (e.g. `"5 seconds"`). Rounded to whole seconds on
   * the wire.
   * @default 0
   */
  maximumBatchingWindow?: Duration.Input;
  /**
   * Whether the event source mapping is active.
   * @default true
   */
  enabled?: boolean;
  /**
   * The position in a stream from which to start reading. Required for Kinesis and DynamoDB Streams.
   *
   * - `LATEST` - Read only new records.
   * - `TRIM_HORIZON` - Process all available records.
   * - `AT_TIMESTAMP` - Start reading from a specific time.
   */
  startingPosition?: StartingPosition;
  /**
   * The timestamp to start reading from when `startingPosition` is `AT_TIMESTAMP`.
   */
  startingPositionTimestamp?: Date;
  /**
   * (Kinesis and DynamoDB Streams) The number of batches to process from each shard concurrently.
   * @default 1
   */
  parallelizationFactor?: number;
  /**
   * (Kinesis and DynamoDB Streams) Split the batch in two and retry if the function returns an error.
   * @default false
   */
  bisectBatchOnFunctionError?: boolean;
  /**
   * (Kinesis and DynamoDB Streams) Discard records older than the specified
   * age (e.g. `"1 hour"`). Rounded to whole seconds on the wire.
   * @default infinite (omit to never expire records)
   */
  maximumRecordAge?: Duration.Input;
  /**
   * (Kinesis and DynamoDB Streams) Discard records after the specified number of retries.
   * @default -1 (infinite)
   */
  maximumRetryAttempts?: number;
  /**
   * (Kinesis and DynamoDB Streams) The duration of a processing window for
   * tumbling windows (e.g. `"30 seconds"`). Rounded to whole seconds on the
   * wire.
   */
  tumblingWindow?: Duration.Input;
  /**
   * A list of current response type enums applied to the event source mapping.
   * Defaults to `["ReportBatchItemFailures"]` for SQS, Kinesis and DynamoDB
   * Streams sources, and for other sources (e.g. Kafka/MSK) only when
   * `provisionedPollerConfig.MinimumPollers` is set — they reject it otherwise.
   * @default ["ReportBatchItemFailures"] (SQS, Kinesis, DynamoDB Streams)
   */
  functionResponseTypes?: FunctionResponseType[];
  /**
   * (SQS) Scaling configuration for the event source.
   */
  scalingConfig?: lambda.ScalingConfig;
  /**
   * (Kinesis and DynamoDB Streams) A destination for records that failed processing.
   */
  destinationConfig?: lambda.DestinationConfig;
  /**
   * Filter criteria to control which records are sent to the function.
   */
  filterCriteria?: lambda.FilterCriteria;
  /**
   * The ARN of an AWS KMS key to encrypt the filter criteria.
   */
  kmsKeyArn?: string;
  /**
   * Metrics configuration for the event source mapping. Defaulted only for
   * SQS, Kinesis and DynamoDB Streams sources, or other sources (Kafka/MSK)
   * with `provisionedPollerConfig.MinimumPollers` set.
   * @default { Metrics: ["EventCount"] } (where supported)
   */
  metricsConfig?: lambda.EventSourceMappingMetricsConfig;
  /**
   * (SQS, MSK, self-managed Kafka) Provisioned poller configuration.
   */
  provisionedPollerConfig?: lambda.ProvisionedPollerConfig;
  /**
   * (Amazon MSK) Configuration for an Amazon Managed Streaming for Apache Kafka event source.
   */
  amazonManagedKafkaEventSourceConfig?: lambda.AmazonManagedKafkaEventSourceConfig;
  /**
   * (Self-managed Kafka) Configuration for a self-managed Apache Kafka event source.
   */
  selfManagedKafkaEventSourceConfig?: lambda.SelfManagedKafkaEventSourceConfig;
  /**
   * (Self-managed Kafka) The self-managed Apache Kafka cluster for the event source.
   */
  selfManagedEventSource?: lambda.SelfManagedEventSource;
  /**
   * (Amazon MQ, MSK, self-managed Kafka) Source access configuration for VPC, authentication, etc.
   */
  sourceAccessConfigurations?: lambda.SourceAccessConfiguration[];
  /**
   * (Amazon MSK, self-managed Kafka) The Kafka topic name(s).
   */
  topics?: string[];
  /**
   * (Amazon MQ) The name of the Amazon MQ broker destination queue to consume.
   */
  queues?: string[];
  /**
   * (Amazon DocumentDB) Configuration for a DocumentDB event source.
   */
  documentDBEventSourceConfig?: lambda.DocumentDBEventSourceConfig;
  /**
   * (Amazon MSK and self-managed Apache Kafka) The logging configuration for the event source.
   */
  loggingConfig?: lambda.LoggingConfig;
  /**
   * Tags to associate with the event source mapping.
   */
  tags?: Record<string, string>;
}

export interface EventSourceMapping extends Resource<
  "AWS.Lambda.EventSourceMapping",
  EventSourceMappingProps,
  {
    /**
     * The UUID of the event source mapping.
     */
    uuid: string;
    /**
     * The ARN of the event source mapping.
     */
    eventSourceMappingArn: string;
    /**
     * The ARN of the Lambda function.
     */
    functionArn: string;
    /**
     * The current state of the event source mapping.
     */
    state: string;
    /**
     * Enabled state, batching, retry, failure-destination, filter, scaling
     * and metrics settings (those the props declare, plus the ones Alchemy
     * defaults), and the tags, as observed. Lets `alchemy drift` detect a
     * consumer disabled or reconfigured out of band.
     */
    configuration?: Record<string, unknown>;
  },
  never,
  Providers
> {}

/**
 * Connects an event source — an SQS queue, Kinesis stream, DynamoDB stream,
 * Amazon MQ broker, or Kafka topic — to a Lambda function so that records are
 * polled from the source and delivered to the function in batches.
 *
 * Most stacks create mappings indirectly through the higher-level event-source
 * helpers (`SQS.consumeQueueMessages(queue, ...)`,
 * `Kinesis.consumeStreamRecords(stream, ...)`, `DynamoDB.consumeTableChanges(table, ...)`),
 * which wire up the matching IAM permissions automatically. Use this resource
 * directly when you need full control over batching, starting position, retry
 * behavior, or filtering.
 *
 * ### Polling an SQS Queue
 * SQS is the simplest source: no `startingPosition` is needed because there is
 * no stream cursor. Lambda long-polls the queue and invokes the function with
 * up to `batchSize` messages, and `functionName` plus `eventSourceArn` are the
 * only required props.
 *
 * **Example:** Subscribe a function to a queue
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const queue = yield* AWS.SQS.Queue("Jobs", {});
 * const worker = yield* AWS.Lambda.Function("Worker", {
 *   main: "./src/worker.ts",
 * });
 *
 * const mapping = yield* AWS.Lambda.EventSourceMapping("JobsToWorker", {
 *   functionName: worker.functionName,
 *   eventSourceArn: queue.queueArn,
 *   batchSize: 10,
 *   maximumBatchingWindow: "5 seconds",
 * });
 * ```
 *
 * This delivers up to 10 messages per invocation, waiting up to 5 seconds to
 * fill a batch before invoking. Increasing the batching window trades latency
 * for fewer, larger invocations — useful for amortizing cold starts or
 * downstream write costs on bursty queues.
 *
 * ### Streaming from Kinesis & DynamoDB
 * Stream sources (Kinesis and DynamoDB Streams) deliver records in shard order
 * and therefore require a `startingPosition` that tells Lambda where in the
 * shard to begin reading. These sources also unlock the stream-only tuning
 * knobs covered in the next sections.
 *
 * **Example:** Process a Kinesis stream from the latest records
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const stream = yield* AWS.Kinesis.Stream("Events", {});
 * const consumer = yield* AWS.Lambda.Function("Consumer", {
 *   main: "./src/consumer.ts",
 * });
 *
 * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsToConsumer", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   startingPosition: "LATEST",
 *   batchSize: 100,
 * });
 * ```
 *
 * `startingPosition: "LATEST"` skips any backlog and only processes records
 * written after the mapping is created — the right choice for live event
 * pipelines where replaying history would be wasteful or incorrect.
 *
 * **Example:** Replay a DynamoDB stream from the beginning
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const table = yield* AWS.DynamoDB.Table("Orders", {
 *   partitionKey: { name: "id", type: "S" },
 * });
 * const handler = yield* AWS.Lambda.Function("OrdersStream", {
 *   main: "./src/orders.ts",
 * });
 *
 * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersToHandler", {
 *   functionName: handler.functionName,
 *   eventSourceArn: table.latestStreamArn!,
 *   startingPosition: "TRIM_HORIZON",
 * });
 * ```
 *
 * `TRIM_HORIZON` starts at the oldest record still in the stream, so the
 * function processes the full available history before catching up to new
 * writes — use it when every change matters (e.g. building a projection).
 *
 * **Example:** Start reading from a specific timestamp
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("EventsFromTime", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   startingPosition: "AT_TIMESTAMP",
 *   startingPositionTimestamp: new Date("2026-01-01T00:00:00Z"),
 * });
 * ```
 *
 * `AT_TIMESTAMP` (Kinesis only) begins at the first record on or after
 * `startingPositionTimestamp`, letting you reprocess a known time range without
 * replaying the entire stream.
 *
 * ### Tuning Throughput
 * For stream sources, throughput is governed by how records are batched and how
 * many batches run in parallel per shard. These knobs let you balance
 * end-to-end latency against invocation count and downstream load.
 *
 * **Example:** Increase parallelism and use tumbling windows
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("HighThroughput", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   startingPosition: "LATEST",
 *   batchSize: 500,
 *   maximumBatchingWindow: "10 seconds",
 *   parallelizationFactor: 5,
 *   tumblingWindow: "30 seconds",
 * });
 * ```
 *
 * `parallelizationFactor` runs up to 5 concurrent batches per shard (records
 * with the same partition key still stay in order), while
 * `tumblingWindow` aggregates results across sequential batches for
 * windowed stream processing. Raising `batchSize`/`maximumBatchingWindow`
 * favors fewer, larger invocations.
 *
 * ### Error Handling & Retries
 * For stream sources a single poison-pill record can block a shard forever.
 * These props bound retries, split failing batches, expire stale records, and
 * route failures elsewhere instead of stalling the stream.
 *
 * **Example:** Bisect on error, cap retries, and expire old records
 * ```typescript
 * const dlq = yield* AWS.SQS.Queue("StreamFailures", {});
 *
 * const mapping = yield* AWS.Lambda.EventSourceMapping("ResilientStream", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   startingPosition: "LATEST",
 *   bisectBatchOnFunctionError: true,
 *   maximumRetryAttempts: 3,
 *   maximumRecordAge: "1 hour",
 *   destinationConfig: {
 *     OnFailure: { Destination: dlq.queueArn },
 *   },
 * });
 * ```
 *
 * On a function error, `bisectBatchOnFunctionError` splits the batch in two and
 * retries each half to isolate the bad record; after `maximumRetryAttempts` (or
 * once a record is older than `maximumRecordAge`) the record is
 * discarded and its metadata is sent to the `destinationConfig.OnFailure`
 * target so it is never silently lost.
 *
 * **Example:** Report partial batch failures
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("PartialFailures", {
 *   functionName: handler.functionName,
 *   eventSourceArn: table.latestStreamArn!,
 *   startingPosition: "TRIM_HORIZON",
 *   functionResponseTypes: ["ReportBatchItemFailures"],
 * });
 * ```
 *
 * `functionResponseTypes: ["ReportBatchItemFailures"]` lets the function return
 * only the IDs of records it failed to process, so Lambda retries just those
 * instead of the whole batch — avoiding redundant reprocessing of records that
 * already succeeded.
 *
 * ### Filtering Records
 * Attach `filterCriteria` so the function is only invoked for records matching
 * an event pattern. Filtering happens before invocation, so it cuts both cost
 * and unnecessary cold starts. Encrypt the patterns with `kmsKeyArn` when they
 * contain sensitive values.
 *
 * **Example:** Only deliver records where `type` is `"order"`
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("OrdersOnly", {
 *   functionName: worker.functionName,
 *   eventSourceArn: queue.queueArn,
 *   filterCriteria: {
 *     Filters: [{ Pattern: JSON.stringify({ body: { type: ["order"] } }) }],
 *   },
 *   kmsKeyArn:
 *     "arn:aws:kms:us-east-1:111122223333:key/abcd1234-...",
 * });
 * ```
 *
 * Each `Pattern` is a JSON event-pattern string; messages that don't match are
 * dropped without invoking the function. The optional `kmsKeyArn` encrypts the
 * stored filter criteria with your own KMS key instead of an AWS-managed one.
 *
 * ### Enabling & Disabling
 * The `enabled` flag controls whether Lambda actively polls the source without
 * deleting the mapping, so you can pause and resume delivery in place.
 *
 * **Example:** Create a paused mapping
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("PausedConsumer", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   startingPosition: "LATEST",
 *   enabled: false,
 * });
 * ```
 *
 * With `enabled: false` the mapping exists but pulls no records — flip it back
 * to `true` to resume. This is handy for maintenance windows or for staging a
 * consumer before turning on traffic.
 *
 * ### Scaling & Provisioned Pollers
 * Cap concurrency for SQS sources with `scalingConfig`, or reserve dedicated
 * polling capacity (for Kafka/MSK and SQS) with `provisionedPollerConfig` to
 * keep latency predictable under load.
 *
 * **Example:** Limit SQS concurrency and provision pollers
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("BoundedConsumer", {
 *   functionName: worker.functionName,
 *   eventSourceArn: queue.queueArn,
 *   scalingConfig: { MaximumConcurrency: 10 },
 *   provisionedPollerConfig: {
 *     MinimumPollers: 1,
 *     MaximumPollers: 20,
 *   },
 * });
 * ```
 *
 * `scalingConfig.MaximumConcurrency` caps how many function instances Lambda
 * runs for this queue (protecting downstream systems), while
 * `provisionedPollerConfig` keeps a pool of dedicated event pollers warm so
 * throughput doesn't lag behind sudden spikes.
 *
 * ### Kafka, MQ & DocumentDB Sources
 * Beyond AWS-native streams, an event source mapping can poll Amazon MSK,
 * self-managed Apache Kafka, Amazon MQ brokers, and Amazon DocumentDB change
 * streams. These sources use `topics`/`queues` to select what to consume,
 * `sourceAccessConfigurations` for VPC and authentication wiring, and
 * source-specific config props.
 *
 * **Example:** Consume a self-managed Kafka topic
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("KafkaConsumer", {
 *   functionName: consumer.functionName,
 *   eventSourceArn: stream.streamArn,
 *   topics: ["orders"],
 *   selfManagedEventSource: {
 *     Endpoints: { KAFKA_BOOTSTRAP_SERVERS: ["broker1:9092", "broker2:9092"] },
 *   },
 *   selfManagedKafkaEventSourceConfig: { ConsumerGroupId: "orders-consumer" },
 *   sourceAccessConfigurations: [
 *     { Type: "SASL_SCRAM_512_AUTH", URI: "arn:aws:secretsmanager:...:secret:kafka" },
 *   ],
 *   loggingConfig: { LogFormat: "JSON" },
 * });
 * ```
 *
 * `topics` names the Kafka topic(s) to read; `selfManagedEventSource.Endpoints`
 * points at the brokers; `sourceAccessConfigurations` supplies the SASL/VPC
 * credentials; and `selfManagedKafkaEventSourceConfig.ConsumerGroupId` pins the
 * consumer group. For Amazon MSK use `amazonManagedKafkaEventSourceConfig`
 * instead.
 *
 * **Example:** Consume an Amazon MQ queue and a DocumentDB change stream
 * ```typescript
 * const mqMapping = yield* AWS.Lambda.EventSourceMapping("MqConsumer", {
 *   functionName: worker.functionName,
 *   eventSourceArn: stream.streamArn,
 *   queues: ["orders-queue"],
 *   sourceAccessConfigurations: [
 *     { Type: "BASIC_AUTH", URI: "arn:aws:secretsmanager:...:secret:mq" },
 *   ],
 * });
 *
 * const docDbMapping = yield* AWS.Lambda.EventSourceMapping("DocDbConsumer", {
 *   functionName: worker.functionName,
 *   eventSourceArn: stream.streamArn,
 *   documentDBEventSourceConfig: {
 *     DatabaseName: "shop",
 *     CollectionName: "orders",
 *     FullDocument: "UpdateLookup",
 *   },
 * });
 * ```
 *
 * For Amazon MQ, `queues` names the broker destination to consume and
 * `sourceAccessConfigurations` carries the broker credentials; for DocumentDB,
 * `documentDBEventSourceConfig` selects the database/collection and whether full
 * documents are delivered on updates.
 *
 * ### Metrics & Tags
 * Opt into per-mapping CloudWatch metrics with `metricsConfig` and brand the
 * mapping with your own `tags` (Alchemy also applies its internal ownership
 * tags automatically).
 *
 * **Example:** Enable event metrics and add tags
 * ```typescript
 * const mapping = yield* AWS.Lambda.EventSourceMapping("ObservedConsumer", {
 *   functionName: worker.functionName,
 *   eventSourceArn: queue.queueArn,
 *   metricsConfig: { Metrics: ["EventCount"] },
 *   tags: { team: "payments", env: "prod" },
 * });
 * ```
 *
 * `metricsConfig.Metrics` turns on the named CloudWatch metrics (e.g.
 * `EventCount`) for this mapping, and `tags` attaches arbitrary key/value pairs
 * for cost allocation and discovery.
 *
 * @resource
 */
export const EventSourceMapping = Resource<EventSourceMapping>("AWS.Lambda.EventSourceMapping");

export const EventSourceMappingProvider = () =>
  Provider.effect(
    EventSourceMapping,
    Effect.gen(function* () {
      const createEventSourceMappingTags = Effect.fn(function* (id: string) {
        const internalTags = yield* createInternalTags(id);
        return {
          ...internalTags,
          "alchemy::id": sanitizeAwsTagValue(internalTags["alchemy::id"]),
        };
      });

      // ReportBatchItemFailures and MetricsConfig are only accepted for
      // SQS / Kinesis / DynamoDB Streams, or for other sources (Kafka/MSK)
      // in provisioned-poller mode — MSK rejects them otherwise ("... is only
      // available for provisioned mode"). Only default them where valid.
      const supportsDefaults = (props: EventSourceMappingProps): boolean =>
        /^arn:[^:]+:(sqs|kinesis|dynamodb):/.test(String(props.eventSourceArn)) ||
        props.provisionedPollerConfig?.MinimumPollers !== undefined;
      const defaultFunctionResponseTypes = (
        props: EventSourceMappingProps,
      ): FunctionResponseType[] | undefined =>
        props.functionResponseTypes ??
        (supportsDefaults(props) ? ["ReportBatchItemFailures"] : undefined);
      const defaultMetricsConfig = (
        props: EventSourceMappingProps,
      ): lambda.EventSourceMappingMetricsConfig | undefined =>
        props.metricsConfig ?? (supportsDefaults(props) ? { Metrics: ["EventCount"] } : undefined);

      const toCreateRequest = (
        props: EventSourceMappingProps,
        tags: Record<string, string>,
      ): lambda.CreateEventSourceMappingRequest => ({
        FunctionName: props.functionName as string,
        EventSourceArn: props.eventSourceArn as string,
        Enabled: props.enabled ?? true,
        BatchSize: props.batchSize,
        MaximumBatchingWindowInSeconds: toWireSeconds(props.maximumBatchingWindow),
        StartingPosition: props.startingPosition,
        StartingPositionTimestamp: props.startingPositionTimestamp,
        ParallelizationFactor: props.parallelizationFactor,
        BisectBatchOnFunctionError: props.bisectBatchOnFunctionError,
        MaximumRecordAgeInSeconds: toWireSeconds(props.maximumRecordAge),
        MaximumRetryAttempts: props.maximumRetryAttempts,
        TumblingWindowInSeconds: toWireSeconds(props.tumblingWindow),
        FunctionResponseTypes: defaultFunctionResponseTypes(props),
        ScalingConfig: props.scalingConfig,
        DestinationConfig: props.destinationConfig,
        FilterCriteria: props.filterCriteria,
        KMSKeyArn: props.kmsKeyArn,
        MetricsConfig: defaultMetricsConfig(props),
        ProvisionedPollerConfig: props.provisionedPollerConfig,
        AmazonManagedKafkaEventSourceConfig: props.amazonManagedKafkaEventSourceConfig,
        SelfManagedKafkaEventSourceConfig: props.selfManagedKafkaEventSourceConfig,
        SelfManagedEventSource: props.selfManagedEventSource,
        SourceAccessConfigurations: props.sourceAccessConfigurations,
        Topics: props.topics,
        Queues: props.queues,
        DocumentDBEventSourceConfig: props.documentDBEventSourceConfig,
        LoggingConfig: props.loggingConfig,
        Tags: tags,
      });

      const withoutConsumerGroupId = <
        C extends { ConsumerGroupId?: string; SchemaRegistryConfig?: unknown },
      >(
        config: C | undefined,
      ): C | undefined =>
        config?.SchemaRegistryConfig === undefined
          ? undefined
          : ({ ...config, ConsumerGroupId: undefined } as C);

      const toUpdateRequest = (
        uuid: string,
        props: EventSourceMappingProps,
      ): lambda.UpdateEventSourceMappingRequest => ({
        UUID: uuid,
        FunctionName: props.functionName as string,
        Enabled: props.enabled ?? true,
        BatchSize: props.batchSize,
        MaximumBatchingWindowInSeconds: toWireSeconds(props.maximumBatchingWindow),
        BisectBatchOnFunctionError: props.bisectBatchOnFunctionError,
        MaximumRecordAgeInSeconds: toWireSeconds(props.maximumRecordAge),
        MaximumRetryAttempts: props.maximumRetryAttempts,
        TumblingWindowInSeconds: toWireSeconds(props.tumblingWindow),
        FunctionResponseTypes: defaultFunctionResponseTypes(props),
        ScalingConfig: props.scalingConfig,
        DestinationConfig: props.destinationConfig,
        FilterCriteria: props.filterCriteria,
        KMSKeyArn: props.kmsKeyArn,
        MetricsConfig: defaultMetricsConfig(props),
        ProvisionedPollerConfig: props.provisionedPollerConfig,
        // ConsumerGroupId is create-only — UpdateEventSourceMapping rejects it
        // ("Unsupported '...consumerGroupId' parameter"); changing it replaces.
        AmazonManagedKafkaEventSourceConfig: withoutConsumerGroupId(
          props.amazonManagedKafkaEventSourceConfig,
        ),
        SelfManagedKafkaEventSourceConfig: withoutConsumerGroupId(
          props.selfManagedKafkaEventSourceConfig,
        ),
        SourceAccessConfigurations: props.sourceAccessConfigurations,
        DocumentDBEventSourceConfig: props.documentDBEventSourceConfig,
        LoggingConfig: props.loggingConfig,
      });

      const configToAttrs = (
        config: lambda.EventSourceMappingConfiguration,
      ): EventSourceMapping["Attributes"] => ({
        uuid: config.UUID!,
        eventSourceMappingArn: config.EventSourceMappingArn!,
        functionArn: config.FunctionArn!,
        state: config.State!,
      });

      /**
       * The settings reconcile converges, as observed. Update leaves an
       * omitted field unchanged, so a field is observed only when the props
       * declare it (or Alchemy defaults it). `read` and `reconcile` share it
       * so a converged mapping reads unchanged.
       */
      const observeMappingConfiguration = (
        config: lambda.EventSourceMappingConfiguration,
        props: EventSourceMappingProps | undefined,
        tags: Record<string, string>,
      ) => {
        const declared = <V>(key: keyof EventSourceMappingProps, value: V) =>
          props?.[key] === undefined ? undefined : value;
        return plainJson({
          // Transitional states (Creating, Updating) count as enabled.
          enabled: config.State !== "Disabled" && config.State !== "Disabling",
          batchSize: declared("batchSize", config.BatchSize),
          maximumBatchingWindowInSeconds: declared(
            "maximumBatchingWindow",
            config.MaximumBatchingWindowInSeconds,
          ),
          bisectBatchOnFunctionError: declared(
            "bisectBatchOnFunctionError",
            config.BisectBatchOnFunctionError,
          ),
          maximumRecordAgeInSeconds: declared("maximumRecordAge", config.MaximumRecordAgeInSeconds),
          maximumRetryAttempts: declared("maximumRetryAttempts", config.MaximumRetryAttempts),
          tumblingWindowInSeconds: declared("tumblingWindow", config.TumblingWindowInSeconds),
          functionResponseTypes:
            props === undefined || defaultFunctionResponseTypes(props) === undefined
              ? undefined
              : [...(config.FunctionResponseTypes ?? [])].sort(),
          scalingConfig: declared("scalingConfig", config.ScalingConfig),
          destinationConfig: declared("destinationConfig", config.DestinationConfig),
          filterCriteria: declared("filterCriteria", config.FilterCriteria),
          kmsKeyArn: declared("kmsKeyArn", config.KMSKeyArn),
          metricsConfig:
            props === undefined || defaultMetricsConfig(props) === undefined
              ? undefined
              : config.MetricsConfig,
          provisionedPollerConfig: declared(
            "provisionedPollerConfig",
            config.ProvisionedPollerConfig,
          ),
          loggingConfig: declared("loggingConfig", config.LoggingConfig),
          tags,
        });
      };

      const readMappingTags = (mappingArn: string) =>
        lambda.listTags({ Resource: mappingArn }).pipe(
          retryTransient,
          Effect.map((r) => tagRecord(r.Tags)),
        );

      const deleteMapping = (uuid: string) =>
        lambda.deleteEventSourceMapping({ UUID: uuid }).pipe(
          Effect.retry({
            while: (e) =>
              e._tag === "ResourceInUseException" || e._tag === "ResourceConflictException",
            schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(20)]),
          }),
          Effect.catchTag("ResourceNotFoundException", () => Effect.void),
        );

      return {
        stables: ["uuid", "eventSourceMappingArn"],
        read: Effect.fn(function* ({ id, olds, output }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          let config: lambda.EventSourceMappingConfiguration | undefined;
          if (output?.uuid) {
            config = yield* lambda
              .getEventSourceMapping({ UUID: output.uuid })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          } else if (olds?.functionName && olds.eventSourceArn) {
            // No persisted UUID (interrupted create): find this stack's
            // mapping for the function and source by its ownership tags.
            const expectedInternalTags = yield* createEventSourceMappingTags(id);
            config = yield* lambda.listEventSourceMappings
              .pages({ FunctionName: olds.functionName })
              .pipe(
                Stream.flatMap((page) => Stream.fromIterable(page.EventSourceMappings ?? [])),
                Stream.filter((m) => m.EventSourceArn === olds.eventSourceArn && !!m.UUID),
                Stream.filterEffect((m) =>
                  readMappingTags(
                    `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${m.UUID}`,
                  ).pipe(Effect.map((tags) => hasTags(expectedInternalTags, tags))),
                ),
                Stream.runHead,
                Effect.map(Option.getOrUndefined),
                Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
              );
          }
          if (!config?.UUID || config.State === "Deleting") return undefined;
          const tags = yield* readMappingTags(
            `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${config.UUID}`,
          ).pipe(
            Effect.catchTag("ResourceNotFoundException", () =>
              Effect.succeed({} as Record<string, string>),
            ),
          );
          return {
            ...configToAttrs(config),
            configuration: observeMappingConfiguration(config, olds, tags),
          };
        }),
        diff: Effect.fn(function* ({ news, olds }) {
          // `functionName` is required, so this narrows `news` to the props object.
          if (!("functionName" in news)) return;
          const sourceArn = news.eventSourceArn;
          if (isResolved(sourceArn) && sourceArn !== olds.eventSourceArn) {
            return { action: "replace" } as const;
          }
          // Lambda allows one mapping per function and source, so a replacement
          // on the same source must delete the old mapping first.
          const replace = { action: "replace", deleteFirst: true } as const;
          if (
            isResolved(news.startingPosition) &&
            news.startingPosition !== olds.startingPosition
          ) {
            return replace;
          }
          if (
            isResolved(news.startingPositionTimestamp) &&
            news.startingPositionTimestamp?.getTime() !== olds.startingPositionTimestamp?.getTime()
          ) {
            return replace;
          }
          if (
            isResolved(news.selfManagedEventSource) &&
            !deepEqual(news.selfManagedEventSource, olds.selfManagedEventSource)
          ) {
            return replace;
          }
          if (
            (isResolved(news.amazonManagedKafkaEventSourceConfig) &&
              news.amazonManagedKafkaEventSourceConfig?.ConsumerGroupId !==
                olds.amazonManagedKafkaEventSourceConfig?.ConsumerGroupId) ||
            (isResolved(news.selfManagedKafkaEventSourceConfig) &&
              news.selfManagedKafkaEventSourceConfig?.ConsumerGroupId !==
                olds.selfManagedKafkaEventSourceConfig?.ConsumerGroupId)
          ) {
            return replace;
          }
          // An unresolved source ARN may or may not change: a replaced queue
          // gets a new ARN, but a Table updated in place keeps its stream ARN
          // while exposing it as unstable. Update in place and let `reconcile`
          // move the mapping if the source really changed, so the mapping's
          // identity is not stable for downstream consumers.
          if (!isResolved(sourceArn)) {
            return { action: "update", stables: [] } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const { accountId, region } = yield* AWSEnvironment.current;
          const expectedInternalTags = yield* createEventSourceMappingTags(id);
          const desiredTags = { ...expectedInternalTags, ...news.tags };

          const functionName = news.functionName as string;
          const eventSourceArn = news.eventSourceArn as string;

          // Observe — find the existing mapping. UUIDs are server-assigned
          // so we either trust `output.uuid` (fast path) or scan
          // `listEventSourceMappings` and confirm ownership via tags
          // (recovery from a state-persistence failure or adoption).
          let config: lambda.EventSourceMappingConfiguration | undefined;
          if (output?.uuid) {
            config = yield* lambda
              .getEventSourceMapping({ UUID: output.uuid })
              .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
          }
          // `updateEventSourceMapping` cannot change the source, so a mapping
          // that reads another source (its source was replaced) is recreated
          // for this source and the stale one deleted.
          let stale: string | undefined;
          if (config?.UUID && config.EventSourceArn !== eventSourceArn) {
            stale = config.UUID;
            config = undefined;
          }
          if (!config?.UUID) {
            config = yield* lambda.listEventSourceMappings
              .pages({ FunctionName: functionName })
              .pipe(
                Stream.mapEffect(
                  Effect.fn(function* (page) {
                    const mapping = page.EventSourceMappings?.find(
                      (m) => m.EventSourceArn === eventSourceArn,
                    );
                    if (mapping?.UUID) {
                      const { Tags } = yield* lambda
                        .listTags({
                          Resource: `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${mapping.UUID}`,
                        })
                        .pipe(retryTransient);
                      if (hasTags(expectedInternalTags, Tags)) {
                        return mapping;
                      }
                    }
                  }),
                ),
                Stream.filter((item) => item !== undefined),
                Stream.runHead,
                Effect.map(Option.getOrUndefined),
              );
          }

          // Ensure — create if no live mapping exists. Tolerate
          // `ResourceConflictException` (peer reconciler raced ahead) by
          // re-scanning to find the mapping by tag ownership.
          if (!config?.UUID) {
            config = yield* lambda
              .createEventSourceMapping(toCreateRequest(news, desiredTags))
              .pipe(
                Effect.catchTags({
                  ResourceConflictException: () =>
                    lambda.listEventSourceMappings.pages({ FunctionName: functionName }).pipe(
                      Stream.mapEffect(
                        Effect.fn(function* (page) {
                          const mapping = page.EventSourceMappings?.find(
                            (m) => m.EventSourceArn === eventSourceArn,
                          );
                          if (mapping?.UUID) {
                            const { Tags } = yield* lambda
                              .listTags({
                                Resource: `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${mapping.UUID}`,
                              })
                              .pipe(retryTransient);
                            if (hasTags(expectedInternalTags, Tags)) {
                              return mapping;
                            }
                          }
                        }),
                      ),
                      Stream.filter((item) => item !== undefined),
                      Stream.runHead,
                      Effect.map(Option.getOrUndefined),
                      Effect.flatMap((mapping) =>
                        mapping
                          ? Effect.succeed(mapping)
                          : Effect.die(
                              new Error(
                                `EventSourceMapping(${id}) not found on function ${functionName}`,
                              ),
                            ),
                      ),
                    ),
                }),
                retryPermissionsPropagation,
                retryTransient,
                Effect.catchTag("QueueVisibilityTimeoutTooShort", (error) =>
                  Effect.fail(visibilityTimeoutError(functionName, eventSourceArn, error)),
                ),
              );
          }

          if (!config?.UUID) {
            return yield* Effect.die(
              new Error(`EventSourceMapping(${id}) could not be reconciled`),
            );
          }

          const uuid = config.UUID;
          if (stale !== undefined && stale !== uuid) {
            yield* deleteMapping(stale);
          }
          const mappingArn = `arn:aws:lambda:${region}:${accountId}:event-source-mapping:${uuid}`;

          // Sync configuration — `updateEventSourceMapping` is a full PUT
          // for mutable fields. We always send the full desired config so
          // observed state converges. Retry `ResourceInUseException`
          // (mapping is transitioning) and known IAM-propagation errors.
          config = yield* lambda.updateEventSourceMapping(toUpdateRequest(uuid, news)).pipe(
            Effect.retry({
              while: (e: any) =>
                e._tag === "ResourceInUseException" || e._tag === "ResourceConflictException",
              schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(20)]),
            }),
            retryPermissionsPropagation,
            retryTransient,
            Effect.catchTag("QueueVisibilityTimeoutTooShort", (error) =>
              Effect.fail(visibilityTimeoutError(functionName, eventSourceArn, error)),
            ),
          );

          // Wait for the mapping to settle into its desired terminal state.
          // A fresh mapping sits in `Creating` for up to ~a minute before
          // Lambda actually starts polling — and for stream sources with
          // `startingPosition: LATEST`, records written before polling
          // starts are silently skipped. Returning early would hand the
          // caller a mapping that looks deployed but drops events.
          const desiredState = (news.enabled ?? true) ? "Enabled" : "Disabled";
          if (config.State !== desiredState) {
            config = yield* lambda.getEventSourceMapping({ UUID: uuid }).pipe(
              Effect.flatMap((observed) =>
                observed.State === desiredState
                  ? Effect.succeed(observed)
                  : Effect.fail(new MappingNotSettled({ state: observed.State })),
              ),
              Effect.retry({
                while: (e) => e._tag === "MappingNotSettled",
                schedule: Schedule.max([Schedule.spaced("2 seconds"), Schedule.recurs(45)]).pipe(
                  Schedule.tap(({ attempt }) =>
                    session.note(
                      `EventSourceMapping ${uuid}: waiting to become ${desiredState} (${(attempt + 1) * 2}s elapsed)`,
                    ),
                  ),
                ),
              }),
              // Never wedge a deploy on a mapping stuck in transition —
              // surface the observed state in the attributes instead.
              Effect.catchTag("MappingNotSettled", () =>
                lambda.getEventSourceMapping({ UUID: uuid }),
              ),
            );
          }

          // Sync tags — diff observed cloud tags against desired so
          // adoption rewrites ownership tags correctly.
          const observedTagsResp = yield* lambda
            .listTags({ Resource: mappingArn })
            .pipe(retryTransient);
          const observedTags: Record<string, string> = Object.fromEntries(
            Object.entries(observedTagsResp.Tags ?? {}).filter(
              (entry): entry is [string, string] => typeof entry[1] === "string",
            ),
          );
          const { removed, upsert } = diffTags(observedTags, desiredTags);

          if (removed.length > 0) {
            yield* lambda
              .untagResource({ Resource: mappingArn, TagKeys: removed })
              .pipe(retryTransient);
          }
          if (upsert.length > 0) {
            const tagsToAdd: Record<string, string> = {};
            for (const { Key, Value } of upsert) {
              tagsToAdd[Key] = Value;
            }
            yield* lambda
              .tagResource({ Resource: mappingArn, Tags: tagsToAdd })
              .pipe(retryTransient);
          }

          yield* session.note(config.EventSourceMappingArn ?? uuid);

          return {
            ...configToAttrs(config),
            configuration: observeMappingConfiguration(config, news, desiredTags),
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* deleteMapping(output.uuid);
        }),
        // `list()` — AWS account/region collection (§4a). Exhaustively
        // paginate `listEventSourceMappings` with no `FunctionName` filter to
        // enumerate every mapping in the current region, hydrating each into
        // the exact `Attributes` shape `reconcile`/`configToAttrs` returns.
        // The list response carries full `EventSourceMappingConfiguration`
        // objects, so there is no per-item `getEventSourceMapping` to issue —
        // hence no bounded fan-out or per-item `ResourceNotFoundException`
        // handling is required. We drop any partial entry missing a required
        // identifier field rather than emitting a malformed `Attributes`.
        list: () =>
          lambda.listEventSourceMappings.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.EventSourceMappings ?? [])
                  .filter(
                    (
                      config,
                    ): config is lambda.EventSourceMappingConfiguration & {
                      UUID: string;
                      EventSourceMappingArn: string;
                      FunctionArn: string;
                      State: string;
                    } =>
                      config.UUID != null &&
                      config.EventSourceMappingArn != null &&
                      config.FunctionArn != null &&
                      config.State != null,
                  )
                  .map(configToAttrs),
              ),
            ),
          ),
      };
    }),
  );

const retryTransient: <A, R, Err>(self: Effect.Effect<A, Err, R>) => Effect.Effect<A, Err, R> =
  Effect.retry({
    while: (e: any) =>
      e._tag === "InternalFailure" ||
      e._tag === "RequestExpired" ||
      e._tag === "ServiceException" ||
      e._tag === "ServiceUnavailable" ||
      e._tag === "ThrottlingException" ||
      e._tag === "TooManyRequestsException" ||
      e._tag === "RequestLimitExceeded" ||
      e._tag === "ResourceInUseException",
    schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
  });

const retryPermissionsPropagation = Effect.retry({
  while: (e: { _tag: string }) =>
    e._tag === "ExecutionRoleNotAssumable" || e._tag === "ExecutionRoleMissingPermissions",
  schedule: Schedule.max([Schedule.exponential(100), Schedule.recurs(30)]),
}) as <A, R, Err extends { _tag: string }>(
  self: Effect.Effect<A, Err, R>,
) => Effect.Effect<A, Err, R>;

const sanitizeAwsTagValue = (value: string) => value.replace(/[^\p{L}\p{Z}\p{N}_.:/=+\-@]/gu, "-");