AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: >-
  HyperFrames distributed rendering — Step Functions standard workflow with
  one Lambda function handling Plan, RenderChunk (fan-out via Map state),
  and Assemble, or Plan and RenderChunk on an optional arm64 image. One S3 bucket, alarms for runaway concurrency, Lambda
  errors, and Step Functions execution failures.

  Built from the handler ZIP at packages/aws-lambda/dist/handler.zip.

  See:
    - packages/aws-lambda/README.md (handler architecture)
    - examples/aws-lambda/README.md (this directory's deploy guide)

Parameters:
  ProjectName:
    Type: String
    Default: hyperframes
    Description: Name prefix applied to all created resources.

  LambdaMemoryMb:
    Type: Number
    Default: 10240
    AllowedValues: [2048, 3072, 4096, 5120, 6144, 7168, 8192, 9216, 10240]
    Description: >-
      Lambda memory in MB. Render workloads are CPU-bound; bumping memory
      proportionally bumps the CPU share Lambda gives the function. 10 GB
      (the max) is recommended for 1080p renders.

  LambdaTimeoutSec:
    Type: Number
    Default: 900
    MinValue: 60
    MaxValue: 900
    Description: >-
      Per-invocation Lambda timeout. Render chunks at the default
      chunkSize=240 frames complete in seconds; 15 minutes is the Lambda
      hard ceiling and the default here to absorb cold-start variance.

  ReservedConcurrency:
    Type: Number
    Default: -1
    Description: >-
      Lambda reserved concurrency cap. Set to a positive integer to bound
      simultaneous chunk renders (e.g. 50 to limit cost). -1 means
      unreserved: each render runs up to 90% of the account's unreserved
      concurrency.

  ChromeSource:
    Type: String
    Default: sparticuz
    AllowedValues: [sparticuz, chrome-headless-shell]
    Description: >-
      Which Chrome runtime the bundled ZIP was built with. Must match the
      `--source=` flag passed to `build-zip.ts`. The handler reads this
      via the HYPERFRAMES_LAMBDA_CHROME_SOURCE env var at boot.

  ChunkInvocationAlarmThreshold:
    Type: Number
    Default: 1000
    Description: >-
      CloudWatch alarm threshold for total RenderChunk invocations per
      hour. The runaway-Map state pathology would fan out far more
      chunks than expected; an alarm at 10× the typical workload
      protects against billing surprises.

  VideoImageUri:
    Type: String
    Default: ""
    Description: >-
      Optional arm64 image (`<ECR repository URI>@sha256:<digest>`) that runs the
      plan and renders the chunks. Audio and assemble stay on the x86 render
      function. Empty: one x86 function does it all.

Conditions:
  HasReservedConcurrency: !Not [!Equals [!Ref ReservedConcurrency, -1]]
  HasVideoFunction: !Not [!Equals [!Ref VideoImageUri, ""]]

Globals:
  Function:
    MemorySize: !Ref LambdaMemoryMb
    Timeout: !Ref LambdaTimeoutSec
    # Lambda function-level X-Ray tracing. The state machine already
    # has Tracing.Enabled: true; without this, X-Ray traces would
    # terminate at the Step Functions → Lambda boundary instead of
    # following into per-function spans.
    Tracing: Active
    # Cost-allocation tags for the render function. Bucket, state machine and
    # video-function.yaml carry the same tags themselves; Globals covers only SAM functions.
    Tags:
      Project: !Ref ProjectName
      HyperFramesComponent: lambda-renderer
    Environment:
      Variables:
        NODE_OPTIONS: "--enable-source-maps"
        HYPERFRAMES_LAMBDA_CHROME_SOURCE: !Ref ChromeSource

Resources:
  # ── S3 bucket for plan tarballs, chunk outputs, and final renders ───────
  RenderBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      # BucketName omitted — CloudFormation generates a unique name like
      # "<stack-name>-renderbucket-<random>". S3 bucket names are capped at
      # 63 chars; a static !Sub expression including ProjectName +
      # AWS::AccountId + AWS::Region trips that limit when ProjectName
      # carries a timestamp (e.g. the smoke script's per-run stack name).
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      VersioningConfiguration:
        # `Suspended` keeps storage costs flat — versions are not
        # retained on overwrites. Tradeoff: if an adopter writes their
        # final rendered mp4 to this bucket and a re-render overwrites
        # the same key, the prior version is gone. Adopters who treat
        # the final mp4 as user-keepable should set this to `Enabled`
        # (intermediates under `renders/` still expire via the
        # lifecycle rule below regardless).
        Status: Suspended
      LifecycleConfiguration:
        Rules:
          - Id: ExpireIntermediates
            Status: Enabled
            Prefix: renders/
            # Plan tarballs and chunk outputs are intermediate artifacts.
            # Users keep the final mp4 (different key prefix); the rest
            # can age out after a week to keep storage costs flat.
            ExpirationInDays: 7
          - Id: ExpireSharedContent
            Status: Enabled
            Prefix: cas/sha256/
            # Project files and plan artifacts by SHA-256, shared across renders.
            ExpirationInDays: 30
      Tags:
        - Key: Project
          Value: !Ref ProjectName
        - Key: HyperFramesComponent
          Value: lambda-renderer

  # ── Single Lambda function handling all three roles ──────────────────────
  RenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: !Sub "${ProjectName}-render"
      Description: >-
        HyperFrames distributed render handler. Dispatches on event.Action.
      Handler: handler.handler
      Runtime: nodejs22.x
      # The ZIP's @sparticuz/chromium ships x86_64 Chrome only; video-function.yaml runs chunks on arm64.
      Architectures: [x86_64]
      # Local path is resolved by `sam build` + `sam deploy --resolve-s3`
      # (or `--s3-bucket`); the resulting CodeUri rewrites to s3://.
      CodeUri: ../../packages/aws-lambda/dist/handler.zip
      PackageType: Zip
      # With a video function the chunks run there, so the reservation moves with them.
      ReservedConcurrentExecutions: !If
        - HasVideoFunction
        - !Ref AWS::NoValue
        - !If [HasReservedConcurrency, !Ref ReservedConcurrency, !Ref AWS::NoValue]
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          # Lambda's Node 22 runtime sets these by default; explicit for
          # clarity + so users can override during local SAM invoke.
          TMPDIR: /tmp
          HYPERFRAMES_RENDER_BUCKET: !Ref RenderBucket
          HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: !Ref ReservedConcurrency
      Policies:
        - S3CrudPolicy:
            BucketName: !Ref RenderBucket
        - Statement:
            - Effect: Allow
              Action: s3:AbortMultipartUpload
              Resource: !Sub "arn:${AWS::Partition}:s3:::${RenderBucket}/*"
        # Plan sizes an unreserved render to the account's concurrency.
        - Statement:
            - Effect: Allow
              Action: lambda:GetAccountSettings
              Resource: "*"
      # CloudWatch Logs perms are covered by SAM's default
      # AWSLambdaBasicExecutionRole — explicit `CloudWatchLogsFullAccess`
      # would be overscope (`logs:*` on `*`, including DeleteLogGroup +
      # CreateExportTask). Reference templates shouldn't leak overbroad
      # IAM into adopters' accounts.

  # ── Optional arm64 chunk renderer: the same handler as a container image ──
  # Nested: `sam deploy` demands an image repository for any image function in this template.
  VideoFunctionStack:
    Type: AWS::CloudFormation::Stack
    Condition: HasVideoFunction
    Properties:
      TemplateURL: video-function.yaml
      Parameters:
        ProjectName: !Ref ProjectName
        ImageUri: !Ref VideoImageUri
        RenderBucket: !Ref RenderBucket
        MemorySize: !Ref LambdaMemoryMb
        Timeout: !Ref LambdaTimeoutSec
        ReservedConcurrency: !Ref ReservedConcurrency
        ChromeSource: !Ref ChromeSource
      Tags:
        - Key: Project
          Value: !Ref ProjectName
        - Key: HyperFramesComponent
          Value: lambda-renderer

  # ── CloudWatch log group for the state machine ──────────────────────────
  # SAM doesn't auto-create one when `LoggingConfiguration` is set, so we
  # define it explicitly — that way the IAM grant on the state-machine
  # role has a destination to write to.
  RenderStateMachineLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/states/${ProjectName}-render"
      RetentionInDays: 30

  # ── Step Functions state machine: Plan → Map(N) RenderChunk → Assemble ──
  RenderStateMachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      Name: !Sub "${ProjectName}-render"
      Type: STANDARD
      Tracing:
        Enabled: true
      Logging:
        # Without this, the `WriteCloudwatchLogs` grant on the state
        # machine role would be unused — operators would see zero
        # execution history outside the Step Functions console.
        # `Level: ERROR` keeps log volume low; bump to `ALL` for
        # heavy debugging.
        Level: ERROR
        IncludeExecutionData: false
        Destinations:
          - CloudWatchLogsLogGroup:
              LogGroupArn: !GetAtt RenderStateMachineLogGroup.Arn
      Definition:
        Comment: >-
          HyperFrames distributed render orchestration: Plan → Map(N)
          RenderChunk → Assemble.
        # Defensive 1-hour ceiling on the whole choreography. The
        # individual states already have retries + per-task timeouts;
        # this catches pathological runaways (Plan-retry storm,
        # stuck-state-machine bugs) at the top before per-task budgets
        # compound into a multi-hour execution. The longest legitimate
        # render observed in PR 880's eval was ~3 minutes.
        TimeoutSeconds: 3600
        StartAt: SelectPlanProtocol
        States:
          SelectPlanProtocol:
            Type: Choice
            Choices:
              # Only a stack with the arm64 video function has a cold x86 function to warm.
              # Without one the compared value can never match.
              - Variable: $.PlanProtocol
                StringEquals: !If [HasVideoFunction, v2, v2-without-video-function]
                Next: WarmRender
              - Variable: $.PlanProtocol
                StringEquals: v2
                Next: PlanV2
              - Variable: $.PlanProtocol
                StringEquals: v1
                Next: Plan
              - Variable: $.PlanProtocol
                IsPresent: true
                Next: UnsupportedPlanProtocol
            Default: PlanV2

          # The audio task runs on this function once the plan is done; starting its container now hides the cold start.
          WarmRender:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters:
              FunctionName: !GetAtt RenderFunction.Arn
              InvocationType: Event
              Payload:
                Action: warm
            ResultPath: null
            Catch:
              - ErrorEquals:
                  - States.ALL
                ResultPath: null
                Next: PlanV2
            Next: PlanV2

          UnsupportedPlanProtocol:
            Type: Fail
            Error: PLAN_PROTOCOL_UNSUPPORTED
            Cause: PlanProtocol must be "v1", "v2", or absent (defaults to v2).

          Plan:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters:
              # Chunks must run the ffmpeg build the plan records, so the plan runs where they do.
              FunctionName:
                !If [
                  HasVideoFunction,
                  !GetAtt VideoFunctionStack.Outputs.FunctionArn,
                  !GetAtt RenderFunction.Arn,
                ]
              Payload:
                Action: plan
                PlanProtocol: v1
                ProjectS3Uri.$: "$.ProjectS3Uri"
                PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
                Config.$: "$.Config"
            ResultSelector:
              PlanProtocol: v1
              PlanS3Uri.$: "$.Payload.PlanS3Uri"
              PlanHash.$: "$.Payload.PlanHash"
              ChunkCount.$: "$.Payload.ChunkCount"
              MaxChunkConcurrency.$: "$.Payload.MaxChunkConcurrency"
              Format.$: "$.Payload.Format"
              HasAudio.$: "$.Payload.HasAudio"
              AudioS3Uri.$: "$.Payload.AudioS3Uri"
            ResultPath: $.Plan
            Retry:
              - ErrorEquals:
                  # These error names are thrown by the producer's plan
                  # stage when retrying can never help — version skew,
                  # determinism violations, GPU misconfiguration, font
                  # fetch failures, plan-size cap, unsupported format.
                  # Fail fast rather than burning ~120s of retry budget.
                  - FFMPEG_VERSION_MISMATCH
                  - PLAN_HASH_MISMATCH
                  - BROWSER_GPU_NOT_SOFTWARE
                  - FONT_FETCH_FAILED
                  - PLAN_TOO_LARGE
                  - PlanTooLargeError
                  - PLAN_PROTOCOL_UNSUPPORTED
                  - PlanProtocolUnsupportedError
                  - VIDEO_SOURCE_UNRENDERABLE
                  - INVALID_VIDEO_METADATA
                  - NOT_MEDIA_PAYLOAD
                  - NotMediaPayloadError
                  - PLAN_ARTIFACT_DIGEST_MISMATCH
                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
                  - CHUNK_EXCEEDS_WORKER_TIMEOUT
                  - SITE_MANIFEST_INVALID
                MaxAttempts: 0
              # Another render on the same function can still take the reserved slots; wait minutes.
              - ErrorEquals: [Lambda.TooManyRequestsException]
                IntervalSeconds: 5
                MaxAttempts: 10
                BackoffRate: 2
                MaxDelaySeconds: 60
                JitterStrategy: FULL
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 4
                BackoffRate: 2
                MaxDelaySeconds: 60
            Next: BuildChunkList

          PlanV2:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters:
              FunctionName:
                !If [
                  HasVideoFunction,
                  !GetAtt VideoFunctionStack.Outputs.FunctionArn,
                  !GetAtt RenderFunction.Arn,
                ]
              Payload:
                Action: plan
                PlanProtocol: v2
                ProjectS3Uri.$: "$.ProjectS3Uri"
                PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
                Config.$: "$.Config"
            ResultSelector:
              PlanProtocol: v2
              PlanV2ManifestS3Uri.$: "$.Payload.PlanV2ManifestS3Uri"
              PlanV2ArtifactS3Prefix.$: "$.Payload.PlanV2ArtifactS3Prefix"
              PlanHash.$: "$.Payload.PlanHash"
              ChunkCount.$: "$.Payload.ChunkCount"
              MaxChunkConcurrency.$: "$.Payload.MaxChunkConcurrency"
              Format.$: "$.Payload.Format"
              HasAudio.$: "$.Payload.HasAudio"
              SeparateAudio.$: "$.Payload.SeparateAudio"
            ResultPath: $.Plan
            Retry:
              - ErrorEquals:
                  - FFMPEG_VERSION_MISMATCH
                  - PLAN_HASH_MISMATCH
                  - S3_URI_NOT_ALLOWED
                  - BROWSER_GPU_NOT_SOFTWARE
                  - FONT_FETCH_FAILED
                  - PLAN_TOO_LARGE
                  - PlanTooLargeError
                  - PLAN_PROTOCOL_UNSUPPORTED
                  - PlanProtocolUnsupportedError
                  - PLAN_V2_INTEGRITY_UNRECOVERABLE
                  - VIDEO_SOURCE_UNRENDERABLE
                  - INVALID_VIDEO_METADATA
                  - NOT_MEDIA_PAYLOAD
                  - NotMediaPayloadError
                  - PlanV2IntegrityError
                  - PLAN_ARTIFACT_DIGEST_MISMATCH
                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
                  - CHUNK_EXCEEDS_WORKER_TIMEOUT
                  - ChromeBinaryUnavailableError
                  - SITE_MANIFEST_INVALID
                MaxAttempts: 0
              - ErrorEquals: [Lambda.TooManyRequestsException]
                IntervalSeconds: 5
                MaxAttempts: 10
                BackoffRate: 2
                MaxDelaySeconds: 60
                JitterStrategy: FULL
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 4
                BackoffRate: 2
                MaxDelaySeconds: 60
            Next: BuildChunkList

          BuildChunkList:
            # Translate ChunkCount into an array `[0, 1, ..., N-1]` so the
            # Map state below has something to iterate. Range is the
            # idiomatic Step Functions intrinsic for this; no Lambda call
            # required.
            Type: Pass
            Parameters:
              ChunkIndexes.$: "States.ArrayRange(0, States.MathAdd($.Plan.ChunkCount, -1), 1)"
            ResultPath: $.Iterator
            Next: AssertChunkCount

          AssertChunkCount:
            # Defensive gate: `resolveChunkPlan` guarantees ChunkCount ≥ 1,
            # but if some future regression let a zero-chunk plan through,
            # `RenderChunks` (Map state) would iterate zero times and
            # `Assemble` would receive an empty `ChunkS3Uris` array — silently
            # producing an empty output. Fail fast instead.
            Type: Choice
            Choices:
              - Variable: $.Plan.ChunkCount
                NumericGreaterThan: 0
                Next: SelectWorkerProtocol
            Default: PlanProducedZeroChunks

          PlanProducedZeroChunks:
            Type: Fail
            Error: PLAN_TOO_LARGE
            Cause: Plan returned ChunkCount=0 — non-retryable producer-side invariant violation.

          SelectWorkerProtocol:
            Type: Choice
            Choices:
              - Variable: $.Plan.PlanProtocol
                StringEquals: v2
                Next: RenderV2
            Default: RenderChunks

          RenderChunks:
            Type: Map
            Label: RenderChunks
            ItemsPath: $.Iterator.ChunkIndexes
            ItemSelector:
              ChunkIndex.$: "$$.Map.Item.Value"
              PlanS3Uri.$: "$.Plan.PlanS3Uri"
              PlanHash.$: "$.Plan.PlanHash"
              ChunkOutputS3Prefix.$: "$.PlanOutputS3Prefix"
              Format.$: "$.Plan.Format"
            # Chunks past the plan's concurrency queue here instead of being throttled by Lambda.
            MaxConcurrencyPath: $.Plan.MaxChunkConcurrency
            ResultPath: $.Chunks
            ItemProcessor:
              ProcessorConfig:
                # Inline Map runs at most 40 iterations at once. STANDARD children
                # because EXPRESS ones stop at 5 minutes and a chunk may run 15.
                Mode: DISTRIBUTED
                ExecutionType: STANDARD
              StartAt: RenderChunk
              States:
                RenderChunk:
                  Type: Task
                  Resource: arn:aws:states:::lambda:invoke
                  Parameters:
                    FunctionName:
                      !If [
                        HasVideoFunction,
                        !GetAtt VideoFunctionStack.Outputs.FunctionArn,
                        !GetAtt RenderFunction.Arn,
                      ]
                    Payload:
                      Action: renderChunk
                      PlanProtocol: v1
                      ChunkIndex.$: "$.ChunkIndex"
                      PlanS3Uri.$: "$.PlanS3Uri"
                      PlanHash.$: "$.PlanHash"
                      ChunkOutputS3Prefix.$: "$.ChunkOutputS3Prefix"
                      Format.$: "$.Format"
                  ResultSelector:
                    ChunkS3Uri.$: "$.Payload.ChunkS3Uri"
                    ChunkIndex.$: "$.Payload.ChunkIndex"
                    Sha256.$: "$.Payload.Sha256"
                    FramesEncoded.$: "$.Payload.FramesEncoded"
                    DurationMs.$: "$.Payload.DurationMs"
                  Retry:
                    - ErrorEquals:
                        - FFMPEG_VERSION_MISMATCH
                        - PLAN_HASH_MISMATCH
                        - BROWSER_GPU_NOT_SOFTWARE
                        - PLAN_TOO_LARGE
                        - PlanTooLargeError
                        - PLAN_PROTOCOL_UNSUPPORTED
                        - PlanProtocolUnsupportedError
                        - INVALID_VIDEO_METADATA
                        - PLAN_ARTIFACT_DIGEST_MISMATCH
                      MaxAttempts: 0
                    - ErrorEquals: [Lambda.TooManyRequestsException]
                      IntervalSeconds: 5
                      MaxAttempts: 10
                      BackoffRate: 2
                      MaxDelaySeconds: 60
                      JitterStrategy: FULL
                    - ErrorEquals: [States.ALL]
                      IntervalSeconds: 2
                      MaxAttempts: 4
                      BackoffRate: 2
                      MaxDelaySeconds: 60
                  End: true
            Next: Assemble

          Assemble:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters:
              FunctionName: !GetAtt RenderFunction.Arn
              Payload:
                Action: assemble
                PlanProtocol: v1
                PlanS3Uri.$: "$.Plan.PlanS3Uri"
                ChunkS3Uris.$: "$.Chunks[*].ChunkS3Uri"
                AudioS3Uri.$: "$.Plan.AudioS3Uri"
                OutputS3Uri.$: "$.OutputS3Uri"
                Format.$: "$.Plan.Format"
            ResultSelector:
              OutputS3Uri.$: "$.Payload.OutputS3Uri"
              FramesEncoded.$: "$.Payload.FramesEncoded"
              FileSize.$: "$.Payload.FileSize"
            ResultPath: $.Output
            Retry:
              - ErrorEquals:
                  # Same non-retryable error names as the Plan state's
                  # gate — these surface at assemble time too because
                  # ffmpeg-driven concat picks up version drift and we
                  # re-verify plan hash + format at assemble. Skip the
                  # retry storm; fail fast.
                  - FFMPEG_VERSION_MISMATCH
                  - PLAN_HASH_MISMATCH
                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
                  - PLAN_TOO_LARGE
                  - PlanTooLargeError
                  - PLAN_PROTOCOL_UNSUPPORTED
                  - PlanProtocolUnsupportedError
                  - PLAN_ARTIFACT_DIGEST_MISMATCH
                MaxAttempts: 0
              - ErrorEquals: [Lambda.TooManyRequestsException]
                IntervalSeconds: 5
                MaxAttempts: 10
                BackoffRate: 2
                MaxDelaySeconds: 60
                JitterStrategy: FULL
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 4
                BackoffRate: 2
                MaxDelaySeconds: 60
            End: true

          RenderV2:
            # Chunks render video only while the audio task mixes the track AssembleV2 stitches in.
            Type: Parallel
            Branches:
              - StartAt: RenderChunksV2
                States:
                  RenderChunksV2:
                    Type: Map
                    Label: RenderChunksV2
                    ItemsPath: $.Iterator.ChunkIndexes
                    ItemSelector:
                      ChunkIndex.$: "$$.Map.Item.Value"
                      PlanV2ManifestS3Uri.$: "$.Plan.PlanV2ManifestS3Uri"
                      PlanV2ArtifactS3Prefix.$: "$.Plan.PlanV2ArtifactS3Prefix"
                      PlanHash.$: "$.Plan.PlanHash"
                      ChunkOutputS3Prefix.$: "$.PlanOutputS3Prefix"
                      Format.$: "$.Plan.Format"
                    # Chunks past the plan's concurrency queue here instead of being throttled by Lambda.
                    MaxConcurrencyPath: $.Plan.MaxChunkConcurrency
                    ResultPath: $.Chunks
                    ItemProcessor:
                      ProcessorConfig:
                        Mode: DISTRIBUTED
                        ExecutionType: STANDARD
                      StartAt: RenderChunkV2
                      States:
                        RenderChunkV2:
                          Type: Task
                          Resource: arn:aws:states:::lambda:invoke
                          Parameters:
                            FunctionName:
                              !If [
                                HasVideoFunction,
                                !GetAtt VideoFunctionStack.Outputs.FunctionArn,
                                !GetAtt RenderFunction.Arn,
                              ]
                            Payload:
                              Action: renderChunk
                              PlanProtocol: v2
                              ChunkIndex.$: "$.ChunkIndex"
                              PlanV2ManifestS3Uri.$: "$.PlanV2ManifestS3Uri"
                              PlanV2ArtifactS3Prefix.$: "$.PlanV2ArtifactS3Prefix"
                              PlanHash.$: "$.PlanHash"
                              ChunkOutputS3Prefix.$: "$.ChunkOutputS3Prefix"
                              Format.$: "$.Format"
                          ResultSelector:
                            ChunkS3Uri.$: "$.Payload.ChunkS3Uri"
                            ChunkIndex.$: "$.Payload.ChunkIndex"
                            Sha256.$: "$.Payload.Sha256"
                            FramesEncoded.$: "$.Payload.FramesEncoded"
                            DurationMs.$: "$.Payload.DurationMs"
                          Retry:
                            - ErrorEquals:
                                - FFMPEG_VERSION_MISMATCH
                                - PLAN_HASH_MISMATCH
                                - S3_URI_NOT_ALLOWED
                                - BROWSER_GPU_NOT_SOFTWARE
                                - PLAN_TOO_LARGE
                                - PlanTooLargeError
                                - PLAN_PROTOCOL_UNSUPPORTED
                                - PlanProtocolUnsupportedError
                                - PLAN_V2_INTEGRITY_UNRECOVERABLE
                                - INVALID_VIDEO_METADATA
                                - PlanV2IntegrityError
                                - PLAN_ARTIFACT_DIGEST_MISMATCH
                                - ChromeBinaryUnavailableError
                              MaxAttempts: 0
                            - ErrorEquals: [Lambda.TooManyRequestsException]
                              IntervalSeconds: 5
                              MaxAttempts: 10
                              BackoffRate: 2
                              MaxDelaySeconds: 60
                              JitterStrategy: FULL
                            - ErrorEquals: [States.ALL]
                              IntervalSeconds: 2
                              MaxAttempts: 4
                              BackoffRate: 2
                              MaxDelaySeconds: 60
                          End: true
                    End: true
              - StartAt: AudioNeeded
                States:
                  AudioNeeded:
                    Type: Choice
                    Choices:
                      - Variable: $.Plan.SeparateAudio
                        BooleanEquals: true
                        Next: Audio
                    Default: NoAudio
                  NoAudio:
                    Type: Pass
                    Result:
                      HasAudio: false
                      AudioS3Uri: null
                    ResultPath: $.Audio
                    End: true
                  Audio:
                    # The plan left its audio out: mix it here while the chunks render.
                    Type: Task
                    Resource: arn:aws:states:::lambda:invoke
                    Parameters:
                      FunctionName: !GetAtt RenderFunction.Arn
                      Payload:
                        Action: audio
                        ProjectS3Uri.$: "$.ProjectS3Uri"
                        PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
                        Config.$: "$.Config"
                    ResultSelector:
                      HasAudio.$: "$.Payload.HasAudio"
                      AudioS3Uri.$: "$.Payload.AudioS3Uri"
                    ResultPath: $.Audio
                    Retry:
                      - ErrorEquals:
                          - FFMPEG_VERSION_MISMATCH
                          - PLAN_HASH_MISMATCH
                          - S3_URI_NOT_ALLOWED
                          - BROWSER_GPU_NOT_SOFTWARE
                          - FONT_FETCH_FAILED
                          - PLAN_TOO_LARGE
                          - PlanTooLargeError
                          - PLAN_PROTOCOL_UNSUPPORTED
                          - PlanProtocolUnsupportedError
                          - PLAN_V2_INTEGRITY_UNRECOVERABLE
                          - VIDEO_SOURCE_UNRENDERABLE
                          - INVALID_VIDEO_METADATA
                          - NOT_MEDIA_PAYLOAD
                          - NotMediaPayloadError
                          - PlanV2IntegrityError
                          - PLAN_ARTIFACT_DIGEST_MISMATCH
                          - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
                          - CHUNK_EXCEEDS_WORKER_TIMEOUT
                          - ChromeBinaryUnavailableError
                          - SITE_MANIFEST_INVALID
                        MaxAttempts: 0
                      - ErrorEquals: [Lambda.TooManyRequestsException]
                        IntervalSeconds: 5
                        MaxAttempts: 10
                        BackoffRate: 2
                        MaxDelaySeconds: 60
                        JitterStrategy: FULL
                      - ErrorEquals: [States.ALL]
                        IntervalSeconds: 2
                        MaxAttempts: 4
                        BackoffRate: 2
                        MaxDelaySeconds: 60
                    End: true
            ResultSelector:
              Chunks.$: "$[0].Chunks"
              Audio.$: "$[1].Audio"
            ResultPath: $.Render
            Next: AssembleV2

          AssembleV2:
            Type: Task
            Resource: arn:aws:states:::lambda:invoke
            Parameters:
              FunctionName: !GetAtt RenderFunction.Arn
              Payload:
                Action: assemble
                PlanProtocol: v2
                PlanV2ManifestS3Uri.$: "$.Plan.PlanV2ManifestS3Uri"
                PlanV2ArtifactS3Prefix.$: "$.Plan.PlanV2ArtifactS3Prefix"
                PlanHash.$: "$.Plan.PlanHash"
                ChunkS3Uris.$: "$.Render.Chunks[*].ChunkS3Uri"
                AudioS3Uri.$: "$.Render.Audio.AudioS3Uri"
                OutputS3Uri.$: "$.OutputS3Uri"
                Format.$: "$.Plan.Format"
            ResultSelector:
              OutputS3Uri.$: "$.Payload.OutputS3Uri"
              FramesEncoded.$: "$.Payload.FramesEncoded"
              FileSize.$: "$.Payload.FileSize"
            ResultPath: $.Output
            Retry:
              - ErrorEquals:
                  - FFMPEG_VERSION_MISMATCH
                  - PLAN_HASH_MISMATCH
                  - S3_URI_NOT_ALLOWED
                  - FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
                  - PLAN_TOO_LARGE
                  - PlanTooLargeError
                  - PLAN_PROTOCOL_UNSUPPORTED
                  - PlanProtocolUnsupportedError
                  - PLAN_V2_INTEGRITY_UNRECOVERABLE
                  - PlanV2IntegrityError
                  - PLAN_ARTIFACT_DIGEST_MISMATCH
                  - ChromeBinaryUnavailableError
                MaxAttempts: 0
              - ErrorEquals: [Lambda.TooManyRequestsException]
                IntervalSeconds: 5
                MaxAttempts: 10
                BackoffRate: 2
                MaxDelaySeconds: 60
                JitterStrategy: FULL
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 4
                BackoffRate: 2
                MaxDelaySeconds: 60
            End: true
      Role: !GetAtt RenderStateMachineRole.Arn

  RenderStateMachineRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: states.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: InvokeRenderFunction
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: lambda:InvokeFunction
                Resource:
                  - !GetAtt RenderFunction.Arn
                  - !If [
                      HasVideoFunction,
                      !GetAtt VideoFunctionStack.Outputs.FunctionArn,
                      !Ref AWS::NoValue,
                    ]
        # A Distributed Map runs each chunk as a child execution of this state machine.
        # ARNs built by name: !Ref RenderStateMachine here would be a dependency cycle.
        - PolicyName: RunDistributedMapChildren
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: states:StartExecution
                Resource: !Sub "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:stateMachine:${ProjectName}-render"
              - Effect: Allow
                Action:
                  - states:DescribeExecution
                  - states:StopExecution
                Resource: !Sub "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:${ProjectName}-render:*"
        - PolicyName: WriteCloudwatchLogs
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - logs:CreateLogDelivery
                  - logs:GetLogDelivery
                  - logs:UpdateLogDelivery
                  - logs:DeleteLogDelivery
                  - logs:ListLogDeliveries
                  - logs:PutResourcePolicy
                  - logs:DescribeResourcePolicies
                  - logs:DescribeLogGroups
                Resource: "*"
        - PolicyName: XRayTracing
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - xray:PutTraceSegments
                  - xray:PutTelemetryRecords
                Resource: "*"

  # ── CloudWatch alarm: runaway chunk invocations ─────────────────────────
  RenderChunkInvocationAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub "${ProjectName}-runaway-chunk-invocations"
      AlarmDescription: >-
        Fires if RenderChunk Lambda invocations exceed the configured
        threshold in a 1-hour window. The Map state's MaxConcurrency cap
        protects against simultaneous fan-out, but a runaway state
        machine that triggers many sequential renders would still rack
        up cost; this alarm catches that pattern.
      Namespace: AWS/Lambda
      MetricName: Invocations
      Dimensions:
        - Name: FunctionName
          Value:
            !If [
              HasVideoFunction,
              !GetAtt VideoFunctionStack.Outputs.FunctionName,
              !Ref RenderFunction,
            ]
      Statistic: Sum
      Period: 3600
      EvaluationPeriods: 1
      Threshold: !Ref ChunkInvocationAlarmThreshold
      ComparisonOperator: GreaterThanThreshold
      TreatMissingData: notBreaching

  # ── CloudWatch alarm: Lambda function errors ────────────────────────────
  # Fires on any non-zero error rate. The invocation alarm above catches
  # *too many calls*; this catches *calls that failed*. Without it,
  # silent per-chunk failures (a non-retryable error inside the
  # producer) would only surface by reading Step Functions execution
  # history.
  RenderFunctionErrorsAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub "${ProjectName}-render-function-errors"
      AlarmDescription: >-
        Fires if the render Lambda reports any errors in a 5-minute
        window. Set EvaluationPeriods=1 so a single failure pages.
      Namespace: AWS/Lambda
      MetricName: Errors
      Dimensions:
        - Name: FunctionName
          Value: !Ref RenderFunction
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching

  VideoFunctionErrorsAlarm:
    Type: AWS::CloudWatch::Alarm
    Condition: HasVideoFunction
    Properties:
      AlarmName: !Sub "${ProjectName}-video-function-errors"
      AlarmDescription: >-
        Fires if the arm64 chunk Lambda reports any errors in a 5-minute window.
      Namespace: AWS/Lambda
      MetricName: Errors
      Dimensions:
        - Name: FunctionName
          Value: !GetAtt VideoFunctionStack.Outputs.FunctionName
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching

  # ── CloudWatch alarm: Step Functions execution failures ─────────────────
  # Fires when a state-machine execution reaches a terminal failure
  # state (typed non-retryable, retry-exhausted, or top-level timeout).
  # Complementary to the Lambda Errors alarm: SFN failures include
  # Choice-state Fail branches (PlanProducedZeroChunks) that bypass
  # Lambda entirely, plus retry-exhaustion of transient errors that
  # individual Lambda invocations counted as successful "retries".
  RenderStateMachineFailedAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: !Sub "${ProjectName}-render-state-machine-failed"
      AlarmDescription: >-
        Fires when the render state machine reports a failed
        execution. Catches retry-exhaustion + typed non-retryable +
        TimeoutSeconds cases that the Lambda Errors metric misses.
      Namespace: AWS/States
      MetricName: ExecutionsFailed
      Dimensions:
        - Name: StateMachineArn
          Value: !Ref RenderStateMachine
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching

Outputs:
  RenderBucketName:
    Description: S3 bucket for plan tarballs, chunk outputs, and final renders.
    Value: !Ref RenderBucket
    Export:
      Name: !Sub "${AWS::StackName}-RenderBucket"

  RenderFunctionArn:
    Description: ARN of the Lambda function. Pass to `aws lambda invoke` for local testing.
    Value: !GetAtt RenderFunction.Arn
    Export:
      Name: !Sub "${AWS::StackName}-RenderFunctionArn"

  VideoFunctionArn:
    Condition: HasVideoFunction
    Description: ARN of the arm64 chunk-rendering function.
    Value: !GetAtt VideoFunctionStack.Outputs.FunctionArn

  RenderStateMachineArn:
    Description: ARN of the Step Functions state machine. Pass to `aws stepfunctions start-execution`.
    Value: !Ref RenderStateMachine
    Export:
      Name: !Sub "${AWS::StackName}-RenderStateMachineArn"