From ee045da3abb2015b391eac3e7ec313e36cf0ecc3 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:36:17 -0500
Subject: [PATCH 1/5] fix(lambda): map update-scope to update.yaml

map_custom_action had no case for it, so the workflow was unreachable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lambda/scope/entrypoint | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lambda/scope/entrypoint b/lambda/scope/entrypoint
index 98ce326..4bd5b8e 100755
--- a/lambda/scope/entrypoint
+++ b/lambda/scope/entrypoint
@@ -6,6 +6,9 @@ map_custom_action() {
   local action="$1"
 
   case "$action" in
+    "update-scope")
+      echo "update"
+      ;;
     "delete-scope")
       echo "delete"
       ;;

From 39b293b1e3a085bab26651e90c32e210e7dc7bbb Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:36:17 -0500
Subject: [PATCH 2/5] fix(tests): make failure assertions on sourced scripts
 observable

These scripts use return, so `bash <script>` never propagates their exit
code and every assert_failure passed vacuously. Also lowercases log
levels with tr, since ${level,,} aborts on bash 3.2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../tests/scripts/cleanup_new_version.bats    |  9 ++-
 .../tests/scripts/cleanup_old_version.bats    |  9 ++-
 .../tests/scripts/merge_iam_policies.bats     | 15 +++-
 .../tests/scripts/rollback_alias.bats         | 17 ++--
 .../tests/scripts/store_nrn_metadata.bats     | 11 ++-
 .../sync_parameters_to_secrets_manager.bats   |  9 ++-
 .../tests/scripts/update_alias_full.bats      | 13 +++-
 .../tests/scripts/update_alias_weights.bats   | 23 ++++--
 .../scripts/wait_provisioned_concurrency.bats | 27 +++++--
 .../tests/scripts/helpers/aws_cli_mock.bash   | 77 +++++++++++++++++++
 .../tests/scripts/scope_build_context.bats    | 17 ++--
 lambda/utils/log                              |  6 +-
 12 files changed, 195 insertions(+), 38 deletions(-)
 create mode 100644 lambda/scope/tests/scripts/helpers/aws_cli_mock.bash

diff --git a/lambda/deployment/tests/scripts/cleanup_new_version.bats b/lambda/deployment/tests/scripts/cleanup_new_version.bats
index ea1a0d8..53c81d8 100644
--- a/lambda/deployment/tests/scripts/cleanup_new_version.bats
+++ b/lambda/deployment/tests/scripts/cleanup_new_version.bats
@@ -19,11 +19,18 @@ teardown() {
   teardown_test_env
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/cleanup_new_version: fails when LAMBDA_FUNCTION_NAME is not set" {
   unset LAMBDA_FUNCTION_NAME
   export LAMBDA_NEW_VERSION="5"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ LAMBDA_FUNCTION_NAME is required"
diff --git a/lambda/deployment/tests/scripts/cleanup_old_version.bats b/lambda/deployment/tests/scripts/cleanup_old_version.bats
index 81c7bb5..c513d2c 100644
--- a/lambda/deployment/tests/scripts/cleanup_old_version.bats
+++ b/lambda/deployment/tests/scripts/cleanup_old_version.bats
@@ -54,10 +54,17 @@ OUTERSCRIPT
   chmod +x "$MOCK_BIN_DIR/aws"
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/cleanup_old_version: fails when LAMBDA_FUNCTION_NAME is not set" {
   unset LAMBDA_FUNCTION_NAME
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ LAMBDA_FUNCTION_NAME is required"
diff --git a/lambda/deployment/tests/scripts/merge_iam_policies.bats b/lambda/deployment/tests/scripts/merge_iam_policies.bats
index fae9d86..ff63002 100644
--- a/lambda/deployment/tests/scripts/merge_iam_policies.bats
+++ b/lambda/deployment/tests/scripts/merge_iam_policies.bats
@@ -98,12 +98,19 @@ OUTERSCRIPT
   chmod +x "$MOCK_BIN_DIR/aws"
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/merge_iam_policies: fails when LAMBDA_ROLE_NAME is not set" {
   unset LAMBDA_ROLE_NAME
   export DEPLOYMENT_ID="deploy-123"
   export SCOPE_NRN="organization=1:account=2:namespace=3:application=4:scope=5"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ LAMBDA_ROLE_NAME is required"
@@ -120,7 +127,7 @@ OUTERSCRIPT
   unset DEPLOYMENT_ID
   export SCOPE_NRN="organization=1:account=2:namespace=3:application=4:scope=5"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ DEPLOYMENT_ID is required"
@@ -137,7 +144,7 @@ OUTERSCRIPT
   export DEPLOYMENT_ID="deploy-123"
   unset SCOPE_NRN
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ SCOPE_NRN is required"
@@ -223,7 +230,7 @@ OUTERSCRIPT
     '{"AWS_LAMBDA_DEDICATED_ROLE_POLICIES": "[{\"name\":\"sqs-access\",\"policy\":\"{\\\"Version\\\":\\\"2012-10-17\\\",\\\"Statement\\\":[]}\"}]"}'
   create_aws_error_mock "NoSuchEntityException: Role my-role does not exist"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ Failed to attach policy sqs-access-deploy-123 to role my-role"
diff --git a/lambda/deployment/tests/scripts/rollback_alias.bats b/lambda/deployment/tests/scripts/rollback_alias.bats
index 9992e13..be21ddf 100644
--- a/lambda/deployment/tests/scripts/rollback_alias.bats
+++ b/lambda/deployment/tests/scripts/rollback_alias.bats
@@ -67,10 +67,17 @@ OUTERSCRIPT
   chmod +x "$MOCK_BIN_DIR/aws"
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/rollback_alias: fails when LAMBDA_FUNCTION_NAME is not set" {
   unset LAMBDA_FUNCTION_NAME
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ LAMBDA_FUNCTION_NAME is required"
@@ -86,7 +93,7 @@ OUTERSCRIPT
   export LAMBDA_FUNCTION_NAME="my-function"
   unset SCOPE_NRN
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ No previous version found to rollback to"
@@ -102,7 +109,7 @@ OUTERSCRIPT
 
   create_np_mock '{"LAMBDA_FUNCTION_CURRENT_VERSION": ""}'
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ No previous version found to rollback to"
@@ -115,7 +122,7 @@ OUTERSCRIPT
 
   create_np_mock '{"LAMBDA_FUNCTION_CURRENT_VERSION": null}'
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ No previous version found to rollback to"
@@ -192,7 +199,7 @@ OUTERSCRIPT
   create_np_mock '{"LAMBDA_FUNCTION_CURRENT_VERSION": "4"}'
   create_aws_error_mock "ResourceNotFoundException: Alias main not found"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ Failed to rollback alias main to version 4 on function my-function"
diff --git a/lambda/deployment/tests/scripts/store_nrn_metadata.bats b/lambda/deployment/tests/scripts/store_nrn_metadata.bats
index 8380206..40e2446 100644
--- a/lambda/deployment/tests/scripts/store_nrn_metadata.bats
+++ b/lambda/deployment/tests/scripts/store_nrn_metadata.bats
@@ -53,10 +53,17 @@ OUTERSCRIPT
   chmod +x "$MOCK_BIN_DIR/np"
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/store_nrn_metadata: fails when SCOPE_NRN is not set" {
   unset SCOPE_NRN
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_line "❌ SCOPE_NRN is required"
@@ -112,7 +119,7 @@ OUTERSCRIPT
 
   create_np_error_mock "Connection refused"
 
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "❌ Failed to write NRN metadata to scope=organization=1:account=2:namespace=3:application=4:scope=5"
diff --git a/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats b/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats
index 86f7451..ed06c8f 100644
--- a/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats
+++ b/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats
@@ -91,6 +91,13 @@ MOCK_SCRIPT
   chmod +x "$MOCK_BIN_DIR/aws"
 }
 
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "sync_parameters: skips when strategy is env" {
   export PARAMETERS_STRATEGY="env"
   set_context secretsmanager
@@ -144,7 +151,7 @@ MOCK_SCRIPT
   unset SCOPE_ID
   set_context secretsmanager
 
-  run bash "$LAMBDA_DIR/deployment/scripts/sync_parameters_to_secrets_manager"
+  run_sourced "$LAMBDA_DIR/deployment/scripts/sync_parameters_to_secrets_manager"
 
   assert_failure
   assert_output_contains "SCOPE_ID is not set"
diff --git a/lambda/deployment/tests/scripts/update_alias_full.bats b/lambda/deployment/tests/scripts/update_alias_full.bats
index d76562d..093d3fb 100644
--- a/lambda/deployment/tests/scripts/update_alias_full.bats
+++ b/lambda/deployment/tests/scripts/update_alias_full.bats
@@ -45,13 +45,20 @@ SCRIPT
 }
 
 # Input validation
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/update_alias_full: fails when LAMBDA_FUNCTION_NAME is not set" {
   unset LAMBDA_FUNCTION_NAME
   export LAMBDA_MAIN_ALIAS_NAME="main"
   export LAMBDA_NEW_VERSION="2"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "LAMBDA_FUNCTION_NAME is required"
@@ -64,7 +71,7 @@ SCRIPT
   unset LAMBDA_CURRENT_VERSION
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "No version specified"
@@ -162,7 +169,7 @@ SCRIPT
   create_aws_error_mock "ResourceNotFoundException: Function my-function not found"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "Failed to update alias"
diff --git a/lambda/deployment/tests/scripts/update_alias_weights.bats b/lambda/deployment/tests/scripts/update_alias_weights.bats
index d660f19..d616ee4 100644
--- a/lambda/deployment/tests/scripts/update_alias_weights.bats
+++ b/lambda/deployment/tests/scripts/update_alias_weights.bats
@@ -71,6 +71,13 @@ SCRIPT
 }
 
 # Input validation
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/update_alias_weights: fails when LAMBDA_FUNCTION_NAME is not set" {
   unset LAMBDA_FUNCTION_NAME
   export LAMBDA_MAIN_ALIAS_NAME="main"
@@ -78,7 +85,7 @@ SCRIPT
   export DESIRED_TRAFFIC="10"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "LAMBDA_FUNCTION_NAME is required"
@@ -91,7 +98,7 @@ SCRIPT
   unset DESIRED_TRAFFIC
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "DESIRED_TRAFFIC is required"
@@ -105,7 +112,7 @@ SCRIPT
   export DESIRED_TRAFFIC="10"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "No version specified"
@@ -122,7 +129,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -136,7 +143,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -150,7 +157,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -266,7 +273,7 @@ SCRIPT
   create_aws_error_mock "ResourceNotFoundException: Function not found"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -280,7 +287,7 @@ SCRIPT
   create_aws_error_mock "ResourceNotFoundException: Version 999 not found"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
diff --git a/lambda/deployment/tests/scripts/wait_provisioned_concurrency.bats b/lambda/deployment/tests/scripts/wait_provisioned_concurrency.bats
index c0c04ac..c6109e0 100644
--- a/lambda/deployment/tests/scripts/wait_provisioned_concurrency.bats
+++ b/lambda/deployment/tests/scripts/wait_provisioned_concurrency.bats
@@ -23,6 +23,12 @@ setup() {
 exit 0
 SCRIPT
   chmod +x "$MOCK_BIN_DIR/sleep"
+
+  # The poll loop is bounded by wall-clock time, not by iteration count, so an
+  # instant sleep alone does not stop it: a test whose mocks never reach a
+  # terminal status would spin for the full default of 600 real seconds.
+  export PROVISIONED_CONCURRENCY_MAX_WAIT_SECONDS=2
+  export PROVISIONED_CONCURRENCY_POLL_INTERVAL=0
 }
 
 teardown() {
@@ -87,13 +93,20 @@ SCRIPT
 }
 
 # Skipping when not provisioned
+# These scripts are sourced by the workflow engine, so `return` is their exit
+# path. `run bash <script>` turns `return` into a warning and keeps going, so a
+# failure assertion could never observe the non-zero status.
+run_sourced() {
+  run bash -c "source '$1'"
+}
+
 @test "deployment/scripts/wait_provisioned_concurrency: skips when provisioned concurrency not enabled" {
   set_context "public"
   export LAMBDA_FUNCTION_NAME="my-function"
   export LAMBDA_MAIN_ALIAS_NAME="main"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "Provisioned concurrency not enabled"
@@ -107,7 +120,7 @@ SCRIPT
   export LAMBDA_MAIN_ALIAS_NAME="main"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "LAMBDA_FUNCTION_NAME is required"
@@ -122,7 +135,7 @@ SCRIPT
   create_aws_error_mock "ProvisionedConcurrencyConfigNotFoundException: No provisioned concurrency config"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "No provisioned concurrency configuration found"
@@ -196,7 +209,7 @@ SCRIPT
   }'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "Provisioned concurrency is READY"
@@ -217,7 +230,7 @@ SCRIPT
     '{"RequestedProvisionedConcurrentExecutions": 5, "AllocatedProvisionedConcurrentExecutions": 5, "Status": "READY"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "IN_PROGRESS"
@@ -240,7 +253,7 @@ SCRIPT
   }'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "Provisioned concurrency allocation FAILED"
@@ -359,7 +372,7 @@ SCRIPT
     '{"RequestedProvisionedConcurrentExecutions": 3, "AllocatedProvisionedConcurrentExecutions": 3, "Status": "READY"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "Provisioned concurrency is READY"
diff --git a/lambda/scope/tests/scripts/helpers/aws_cli_mock.bash b/lambda/scope/tests/scripts/helpers/aws_cli_mock.bash
new file mode 100644
index 0000000..837ab10
--- /dev/null
+++ b/lambda/scope/tests/scripts/helpers/aws_cli_mock.bash
@@ -0,0 +1,77 @@
+#!/bin/bash
+# AWS CLI mock keyed by "<service> <subcommand>", for scripts that branch on
+# what AWS returns. Unlike the sequential queue in test_helper.bash it also
+# records calls, so a test can assert one did NOT happen.
+#
+#   setup_aws_cli_mock
+#   aws_mock_response "lambda get-policy" 254 'ResourceNotFoundException'
+#   assert_aws_cli_not_called "add-permission"
+#
+# Unconfigured subcommands succeed empty, so best-effort calls need no stub.
+
+setup_aws_cli_mock() {
+  : "${MOCK_BIN_DIR:?setup_aws_cli_mock requires MOCK_BIN_DIR}"
+  : > "$MOCK_BIN_DIR/aws_calls"
+
+  cat > "$MOCK_BIN_DIR/aws" << 'MOCK_SCRIPT'
+#!/bin/bash
+MOCK_DIR="$(dirname "$0")"
+printf '%s\n' "$*" >> "$MOCK_DIR/aws_calls"
+
+response_file="$MOCK_DIR/resp_${1}_${2}"
+[ -f "$response_file" ] || exit 0
+
+exit_code=$(head -1 "$response_file")
+output=$(tail -n +2 "$response_file")
+
+if [ "$exit_code" != "0" ]; then
+  printf '%s\n' "$output" >&2
+  exit "$exit_code"
+fi
+
+printf '%s\n' "$output"
+exit 0
+MOCK_SCRIPT
+  chmod +x "$MOCK_BIN_DIR/aws"
+}
+
+# aws_mock_response "<service> <subcommand>" <exit_code> [output]
+aws_mock_response() {
+  local key="${1// /_}"
+  local exit_code="$2"
+  local output="${3:-}"
+  printf '%s\n%s\n' "$exit_code" "$output" > "$MOCK_BIN_DIR/resp_${key}"
+}
+
+aws_cli_calls() {
+  cat "$MOCK_BIN_DIR/aws_calls" 2>/dev/null
+}
+
+assert_aws_cli_called() {
+  local pattern="$1"
+  if ! grep -qF -- "$pattern" "$MOCK_BIN_DIR/aws_calls" 2>/dev/null; then
+    echo "Expected an AWS CLI call containing: $pattern"
+    echo "Actual calls:"
+    aws_cli_calls | sed 's/^/  - aws /'
+    return 1
+  fi
+}
+
+assert_aws_cli_not_called() {
+  local pattern="$1"
+  if grep -qF -- "$pattern" "$MOCK_BIN_DIR/aws_calls" 2>/dev/null; then
+    echo "Expected NO AWS CLI call containing: $pattern, but found:"
+    grep -F -- "$pattern" "$MOCK_BIN_DIR/aws_calls" | sed 's/^/  - aws /'
+    return 1
+  fi
+}
+
+assert_aws_cli_call_count() {
+  local pattern="$1" expected="$2" actual
+  actual=$(grep -cF -- "$pattern" "$MOCK_BIN_DIR/aws_calls" 2>/dev/null || true)
+  if [ "${actual:-0}" != "$expected" ]; then
+    echo "Expected $expected AWS CLI call(s) containing '$pattern', got ${actual:-0}"
+    aws_cli_calls | sed 's/^/  - aws /'
+    return 1
+  fi
+}
diff --git a/lambda/scope/tests/scripts/scope_build_context.bats b/lambda/scope/tests/scripts/scope_build_context.bats
index 08d2b09..ff66494 100644
--- a/lambda/scope/tests/scripts/scope_build_context.bats
+++ b/lambda/scope/tests/scripts/scope_build_context.bats
@@ -24,10 +24,17 @@ teardown() {
   done
 }
 
+# build_context is sourced by the workflow engine, so `return` is its exit path.
+# Running it with `bash <file>` makes `return` a no-op warning and the script
+# exits 0, which would make every failure assertion below vacuous.
+run_sourced_build_context() {
+  run bash -c "source '$LAMBDA_DIR/scope/build_context'"
+}
+
 @test "scope/build_context: fails when CONTEXT is not set" {
   unset CONTEXT
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced_build_context
 
   assert_failure
   assert_output_contains "CONTEXT variable is not set or empty"
@@ -38,7 +45,7 @@ teardown() {
 @test "scope/build_context: fails when CONTEXT is empty string" {
   export CONTEXT=""
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced_build_context
 
   assert_failure
   assert_output_contains "CONTEXT variable is not set or empty"
@@ -47,7 +54,7 @@ teardown() {
 @test "scope/build_context: fails when scope ID is missing from CONTEXT" {
   export CONTEXT='{"scope": {"slug": "test"}, "namespace": {"slug": "ns"}, "application": {"slug": "app"}, "account": {"slug": "acc"}}'
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced_build_context
 
   assert_failure
   assert_output_contains "Failed to extract scope ID from CONTEXT"
@@ -58,7 +65,7 @@ teardown() {
 @test "scope/build_context: fails when scope ID is null" {
   export CONTEXT='{"scope": {"id": null, "slug": "test", "nrn": "nrn:1", "visibility": "public"}, "namespace": {"slug": "ns"}, "application": {"slug": "app"}, "account": {"slug": "acc"}}'
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced_build_context
 
   assert_failure
   assert_output_contains "Failed to extract scope ID from CONTEXT"
@@ -136,7 +143,7 @@ teardown() {
   export NP_OUTPUT_DIR="$(mktemp -d)"
   _TEST_CLEANUP_DIRS+=("$NP_OUTPUT_DIR")
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced_build_context
 
   assert_failure
   assert_output_contains "ALB listener rule capacity (80) is at or below the alert threshold (80)"
diff --git a/lambda/utils/log b/lambda/utils/log
index 7ed4283..9c32484 100644
--- a/lambda/utils/log
+++ b/lambda/utils/log
@@ -15,7 +15,11 @@ log() {
 
   local -i msg_num threshold
 
-  case "${level,,}" in
+  # Lowercase via tr rather than ${var,,}: the latter needs bash 4, and macOS
+  # ships bash 3.2, which would break every script that sources this locally.
+  level=$(printf '%s' "$level" | tr '[:upper:]' '[:lower:]')
+
+  case "$level" in
     debug) msg_num=0 ;;
     info)  msg_num=1 ;;
     warn)  msg_num=2 ;;

From 5d96def2a5111db1184716f41ada4e0f5fc919f6 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:36:17 -0500
Subject: [PATCH 3/5] feat(lambda): add external invoke permissions and a
 function DLQ

Reconciled by AWS CLI scripts on create and update, not by tofu: the
scope state holds the placeholder function, so an apply on update would
roll back deployed code. delete-scope drops the DLQ inline policy first,
or DeleteRole fails. Also adds the provided.al2 runtime.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../scripts/cleanup_role_inline_policies      |  48 +++++
 lambda/scope/scripts/sync_dead_letter_queue   | 157 +++++++++++++++
 lambda/scope/scripts/sync_invoke_permissions  | 174 ++++++++++++++++
 .../scripts/cleanup_role_inline_policies.bats |  81 ++++++++
 .../tests/scripts/sync_dead_letter_queue.bats | 183 +++++++++++++++++
 .../scripts/sync_invoke_permissions.bats      | 186 ++++++++++++++++++
 lambda/scope/workflows/create.yaml            |  12 ++
 lambda/scope/workflows/delete.yaml            |   3 +
 lambda/scope/workflows/update.yaml            |   9 +
 lambda/specs/scope-configuration.json.tpl     |  61 ++++++
 lambda/specs/service-spec.json.tpl            |  13 +-
 11 files changed, 926 insertions(+), 1 deletion(-)
 create mode 100755 lambda/scope/scripts/cleanup_role_inline_policies
 create mode 100755 lambda/scope/scripts/sync_dead_letter_queue
 create mode 100755 lambda/scope/scripts/sync_invoke_permissions
 create mode 100644 lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
 create mode 100644 lambda/scope/tests/scripts/sync_dead_letter_queue.bats
 create mode 100644 lambda/scope/tests/scripts/sync_invoke_permissions.bats

diff --git a/lambda/scope/scripts/cleanup_role_inline_policies b/lambda/scope/scripts/cleanup_role_inline_policies
new file mode 100755
index 0000000..1d99f08
--- /dev/null
+++ b/lambda/scope/scripts/cleanup_role_inline_policies
@@ -0,0 +1,48 @@
+#!/bin/bash
+# Drop the inline policies this scope writes outside terraform, before destroy.
+#
+# IAM refuses DeleteRole while unmanaged inline policies remain. Best-effort:
+# a missing role or policy is the normal case.
+
+source "$SERVICE_PATH/utils/get_config_value"
+source "$SERVICE_PATH/utils/log"
+
+SCOPE_INLINE_POLICIES=("np-lambda-dlq")
+
+log info "🔍 Cleaning up scope-managed inline role policies..."
+
+if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; then
+  log debug "   ⏭️  LAMBDA_FUNCTION_NAME not set — nothing to clean up"
+  return 0
+fi
+
+# Prefer the role the function actually runs on; fall back to the name the iam
+# setup derives, for the case where the function is already gone.
+cleanup_role_name=$(aws lambda get-function-configuration \
+  --function-name "$LAMBDA_FUNCTION_NAME" \
+  --query 'Role' --output text 2>/dev/null || echo "")
+cleanup_role_name="${cleanup_role_name##*/}"
+
+if [ -z "$cleanup_role_name" ] || [ "$cleanup_role_name" = "None" ]; then
+  cleanup_role_prefix=$(get_config_value \
+    --provider '.providers["scope-configurations"].lambda.execution_role_prefix' \
+    --env LAMBDA_EXECUTION_ROLE_PREFIX \
+    --default 'np-lambda-')
+  cleanup_role_name="${cleanup_role_prefix}${LAMBDA_FUNCTION_NAME}-role"
+  cleanup_role_name="${cleanup_role_name:0:64}"
+fi
+
+log debug "   📋 execution_role=$cleanup_role_name"
+
+for policy_name in "${SCOPE_INLINE_POLICIES[@]}"; do
+  if aws iam delete-role-policy \
+    --role-name "$cleanup_role_name" \
+    --policy-name "$policy_name" >/dev/null 2>&1; then
+    log info "   📝 Removed inline policy $policy_name from $cleanup_role_name"
+  else
+    log debug "   ⏭️  $policy_name not present on $cleanup_role_name"
+  fi
+done
+
+echo ""
+log info "✨ Inline role policies cleaned up"
diff --git a/lambda/scope/scripts/sync_dead_letter_queue b/lambda/scope/scripts/sync_dead_letter_queue
new file mode 100755
index 0000000..e8dd919
--- /dev/null
+++ b/lambda/scope/scripts/sync_dead_letter_queue
@@ -0,0 +1,157 @@
+#!/bin/bash
+# Reconcile the DLQ for failed async invocations (not an SQS redrive policy).
+#
+# DeadLetterConfig and the role's send grant must move together: without the
+# grant Lambda drops the failed event silently.
+
+source "$SERVICE_PATH/utils/log"
+
+DLQ_POLICY_NAME="np-lambda-dlq"
+
+log info "🔍 Reconciling function dead letter queue..."
+
+if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; then
+  echo "❌ LAMBDA_FUNCTION_NAME is required but not set" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - build_context step failed to resolve the function name" >&2
+  echo "   - The step was added to the workflow without declaring the variable as an output" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Verify LAMBDA_FUNCTION_NAME is listed in the build_context step outputs" >&2
+  echo "   - Re-run the diagnose-scope action to check scope health" >&2
+  return 1
+fi
+
+dlq_target_arn=$(echo "$CONTEXT" | jq -r '.scope.capabilities.dead_letter_target_arn // ""')
+[ "$dlq_target_arn" = "null" ] && dlq_target_arn=""
+
+# Read the role off the function rather than re-deriving its name: the scope
+# truncates role names to 64 chars and a scope may run on a dedicated role.
+if ! function_config=$(aws lambda get-function-configuration \
+  --function-name "$LAMBDA_FUNCTION_NAME" \
+  --output json 2>&1); then
+  echo "❌ Failed to read configuration of '$LAMBDA_FUNCTION_NAME'" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - The function does not exist yet" >&2
+  echo "   - Permission denied (missing lambda:GetFunctionConfiguration)" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Run diagnose-scope to confirm the function exists" >&2
+  echo "   - Check the assume role permissions" >&2
+  echo "   📋 AWS error: $function_config" >&2
+  return 1
+fi
+
+current_dlq=$(echo "$function_config" | jq -r '.DeadLetterConfig.TargetArn // ""')
+role_arn=$(echo "$function_config" | jq -r '.Role // ""')
+role_name="${role_arn##*/}"
+
+log debug "   📋 function_name=$LAMBDA_FUNCTION_NAME"
+log debug "   📋 execution_role=$role_name"
+log debug "   📋 current_dlq=${current_dlq:-<none>}"
+log debug "   📋 desired_dlq=${dlq_target_arn:-<none>}"
+
+# ── Disable ───────────────────────────────────────────────────────────────────
+if [ -z "$dlq_target_arn" ]; then
+  if [ -n "$current_dlq" ]; then
+    log info "   📝 Removing dead letter queue..."
+    if ! aws_output=$(aws lambda update-function-configuration \
+      --function-name "$LAMBDA_FUNCTION_NAME" \
+      --dead-letter-config '{}' 2>&1); then
+      echo "❌ Failed to remove the dead letter queue from '$LAMBDA_FUNCTION_NAME'" >&2
+      echo "💡 Possible causes:" >&2
+      echo "   - Permission denied (missing lambda:UpdateFunctionConfiguration)" >&2
+      echo "   - Another update is still in progress on the function" >&2
+      echo "🔧 How to fix:" >&2
+      echo "   - Check the assume role permissions" >&2
+      echo "   - Wait for the running deployment to finish and re-run the action" >&2
+      echo "   📋 AWS error: $aws_output" >&2
+      return 1
+    fi
+    aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" 2>&1
+  else
+    log debug "   ⏭️  No dead letter queue configured — nothing to remove"
+  fi
+
+  if [ -n "$role_name" ]; then
+    aws iam delete-role-policy \
+      --role-name "$role_name" \
+      --policy-name "$DLQ_POLICY_NAME" >/dev/null 2>&1 \
+      && log debug "   ✅ Removed inline policy $DLQ_POLICY_NAME from $role_name"
+  fi
+
+  echo ""
+  log info "✨ Dead letter queue disabled for $LAMBDA_FUNCTION_NAME"
+  return 0
+fi
+
+# ── Enable ────────────────────────────────────────────────────────────────────
+case "$dlq_target_arn" in
+  arn:*:sqs:*) dlq_action="sqs:SendMessage" ;;
+  arn:*:sns:*) dlq_action="sns:Publish" ;;
+  *)
+    echo "❌ Unsupported dead letter target '$dlq_target_arn'" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - Lambda only accepts an SQS queue or an SNS topic as a dead letter target" >&2
+    echo "   - The value is not an ARN (e.g. a queue name or URL was entered)" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Use a full ARN, e.g. arn:aws:sqs:us-east-1:123456789012:my-dlq" >&2
+    echo "   - Leave the field empty to disable the dead letter queue" >&2
+    return 1
+    ;;
+esac
+
+if [ -z "$role_name" ]; then
+  echo "❌ Could not resolve the execution role of '$LAMBDA_FUNCTION_NAME'" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - The function configuration returned an empty Role field" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Run diagnose-scope to check the function and its execution role" >&2
+  return 1
+fi
+
+# Grant first, then enable: the other order leaves a window where Lambda drops
+# failed events because the role cannot write to the target yet.
+log info "   📝 Granting $dlq_action on the dead letter target to $role_name..."
+dlq_policy=$(jq -n --arg action "$dlq_action" --arg resource "$dlq_target_arn" \
+  '{Version: "2012-10-17", Statement: [{Effect: "Allow", Action: [$action], Resource: $resource}]}')
+
+if ! aws_output=$(aws iam put-role-policy \
+  --role-name "$role_name" \
+  --policy-name "$DLQ_POLICY_NAME" \
+  --policy-document "$dlq_policy" 2>&1); then
+  echo "❌ Failed to grant dead letter access to role '$role_name'" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - Permission denied (missing iam:PutRolePolicy)" >&2
+  echo "   - The assume role's permissions boundary blocks writing to this role" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Check the assume role has iam:PutRolePolicy on the scope's execution roles" >&2
+  echo "   📋 AWS error: $aws_output" >&2
+  return 1
+fi
+
+if [ "$current_dlq" = "$dlq_target_arn" ]; then
+  log debug "   ⏭️  Dead letter queue already set to $dlq_target_arn"
+  echo ""
+  log info "✨ Dead letter queue up to date for $LAMBDA_FUNCTION_NAME"
+  return 0
+fi
+
+log info "   📡 Setting dead letter queue to $dlq_target_arn..."
+if ! aws_output=$(aws lambda update-function-configuration \
+  --function-name "$LAMBDA_FUNCTION_NAME" \
+  --dead-letter-config "TargetArn=$dlq_target_arn" 2>&1); then
+  echo "❌ Failed to set the dead letter queue on '$LAMBDA_FUNCTION_NAME'" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - The target queue or topic does not exist, or lives in another region" >&2
+  echo "   - Permission denied (missing lambda:UpdateFunctionConfiguration)" >&2
+  echo "   - Another update is still in progress on the function" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Verify the ARN exists in the same region as the function" >&2
+  echo "   - Wait for the running deployment to finish and re-run the action" >&2
+  echo "   📋 AWS error: $aws_output" >&2
+  return 1
+fi
+
+aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" 2>&1
+
+echo ""
+log info "✨ Dead letter queue set to $dlq_target_arn for $LAMBDA_FUNCTION_NAME"
diff --git a/lambda/scope/scripts/sync_invoke_permissions b/lambda/scope/scripts/sync_invoke_permissions
new file mode 100755
index 0000000..cf337b2
--- /dev/null
+++ b/lambda/scope/scripts/sync_invoke_permissions
@@ -0,0 +1,174 @@
+#!/bin/bash
+# Reconcile lambda.triggers.invoke_permissions from the scope-configuration.
+#
+# Grants target the main alias, so external triggers respect blue/green weights.
+# Only Sids carrying our prefix are removed — never AllowAPIGatewayInvoke,
+# AllowALBInvoke, or anything added out of band.
+
+source "$SERVICE_PATH/utils/log"
+
+NP_INVOKE_SID_PREFIX="np-ext-"
+
+log info "🔍 Reconciling external invoke permissions..."
+
+if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; then
+  echo "❌ LAMBDA_FUNCTION_NAME is required but not set" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - build_context step failed to resolve the function name" >&2
+  echo "   - The step was added to the workflow without declaring the variable as an output" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Verify LAMBDA_FUNCTION_NAME is listed in the build_context step outputs" >&2
+  echo "   - Re-run the diagnose-scope action to check scope health" >&2
+  return 1
+fi
+
+invoke_alias="${LAMBDA_MAIN_ALIAS_NAME:-main}"
+
+desired=$(echo "$CONTEXT" | jq -c '.providers["scope-configurations"].lambda.triggers.invoke_permissions // []')
+desired_count=$(echo "$desired" | jq 'length')
+
+log debug "   📋 function_name=$LAMBDA_FUNCTION_NAME"
+log debug "   📋 qualifier=$invoke_alias"
+log debug "   📋 declared_permissions=$desired_count"
+
+# ── Current state ─────────────────────────────────────────────────────────────
+# A function with no resource policy returns ResourceNotFoundException; that is
+# the normal first-run case, not an error.
+policy_json=$(aws lambda get-policy \
+  --function-name "$LAMBDA_FUNCTION_NAME" \
+  --qualifier "$invoke_alias" \
+  --query 'Policy' \
+  --output text 2>/dev/null)
+
+if [ -z "$policy_json" ] || [ "$policy_json" = "None" ]; then
+  current_statements="[]"
+else
+  current_statements=$(echo "$policy_json" | jq -c '.Statement // []')
+fi
+
+managed_sids=$(echo "$current_statements" | jq -r --arg p "$NP_INVOKE_SID_PREFIX" \
+  '.[] | select(.Sid | startswith($p)) | .Sid')
+
+# ── Remove managed statements that are no longer declared ─────────────────────
+desired_sids=$(echo "$desired" | jq -r --arg p "$NP_INVOKE_SID_PREFIX" '.[] | $p + .statement_id')
+
+while IFS= read -r sid; do
+  [ -z "$sid" ] && continue
+  if ! echo "$desired_sids" | grep -qxF "$sid"; then
+    log info "   📝 Removing permission no longer declared: $sid"
+    if ! aws_output=$(aws lambda remove-permission \
+      --function-name "$LAMBDA_FUNCTION_NAME" \
+      --qualifier "$invoke_alias" \
+      --statement-id "$sid" 2>&1); then
+      echo "❌ Failed to remove invoke permission '$sid' from '$LAMBDA_FUNCTION_NAME'" >&2
+      echo "💡 Possible causes:" >&2
+      echo "   - Permission denied (missing lambda:RemovePermission)" >&2
+      echo "   - The statement was removed concurrently by another process" >&2
+      echo "🔧 How to fix:" >&2
+      echo "   - Check the assume role has lambda:RemovePermission on the function" >&2
+      echo "   - Re-run the action; removal is idempotent" >&2
+      echo "   📋 AWS error: $aws_output" >&2
+      return 1
+    fi
+  fi
+done <<< "$managed_sids"
+
+# ── Add or refresh declared statements ────────────────────────────────────────
+while IFS= read -r perm; do
+  [ -z "$perm" ] && continue
+
+  statement_id=$(echo "$perm" | jq -r '.statement_id // ""')
+  principal=$(echo "$perm" | jq -r '.principal // ""')
+  source_arn=$(echo "$perm" | jq -r '.source_arn // ""')
+  source_account=$(echo "$perm" | jq -r '.source_account // ""')
+  action=$(echo "$perm" | jq -r '.action // "lambda:InvokeFunction"')
+
+  if [ -z "$statement_id" ] || [ -z "$principal" ]; then
+    echo "❌ Invoke permission is missing 'statement_id' or 'principal': $perm" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - The scope-configuration entry was saved with an incomplete object" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Set both statement_id and principal on every invoke_permissions entry" >&2
+    return 1
+  fi
+
+  # AWS restricts StatementId to [a-zA-Z0-9-_] and 100 characters, and our prefix
+  # eats part of that budget — fail here rather than on an opaque AWS error.
+  if ! [[ "$statement_id" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "❌ Invalid statement_id '$statement_id': only letters, digits, '-' and '_' are allowed" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - The statement_id contains dots, colons or spaces (e.g. an ARN was pasted)" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Use a short symbolic name, e.g. 'apigw-authorizer' or 'eventbridge-daily'" >&2
+    return 1
+  fi
+
+  sid="${NP_INVOKE_SID_PREFIX}${statement_id}"
+
+  if [ ${#sid} -gt 100 ]; then
+    echo "❌ statement_id '$statement_id' is too long (Sid '$sid' exceeds 100 characters)" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - AWS caps StatementId at 100 characters, and '$NP_INVOKE_SID_PREFIX' is prepended" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Shorten the statement_id to at most $((100 - ${#NP_INVOKE_SID_PREFIX})) characters" >&2
+    return 1
+  fi
+
+  # add-permission cannot update in place, so a changed principal/source means
+  # remove + add. Compare against the live statement to stay idempotent.
+  existing=$(echo "$current_statements" | jq -c --arg sid "$sid" 'map(select(.Sid == $sid)) | first // empty')
+
+  if [ -n "$existing" ]; then
+    cur_principal=$(echo "$existing" | jq -r '.Principal.Service // .Principal // ""')
+    cur_action=$(echo "$existing" | jq -r 'if (.Action | type) == "array" then .Action[0] else .Action end // ""')
+    cur_source_arn=$(echo "$existing" | jq -r '.Condition.ArnLike."AWS:SourceArn" // ""')
+    cur_source_account=$(echo "$existing" | jq -r '.Condition.StringEquals."AWS:SourceAccount" // ""')
+
+    if [ "$cur_principal" = "$principal" ] && [ "$cur_action" = "$action" ] && \
+       [ "$cur_source_arn" = "$source_arn" ] && [ "$cur_source_account" = "$source_account" ]; then
+      log debug "   ⏭️  $sid already up to date"
+      continue
+    fi
+
+    log info "   📝 Refreshing changed permission: $sid"
+    if ! aws_output=$(aws lambda remove-permission \
+      --function-name "$LAMBDA_FUNCTION_NAME" \
+      --qualifier "$invoke_alias" \
+      --statement-id "$sid" 2>&1); then
+      echo "❌ Failed to replace invoke permission '$sid' on '$LAMBDA_FUNCTION_NAME'" >&2
+      echo "💡 Possible causes:" >&2
+      echo "   - Permission denied (missing lambda:RemovePermission)" >&2
+      echo "🔧 How to fix:" >&2
+      echo "   - Check the assume role has lambda:RemovePermission on the function" >&2
+      echo "   📋 AWS error: $aws_output" >&2
+      return 1
+    fi
+  else
+    log info "   📝 Adding permission: $sid ($principal)"
+  fi
+
+  add_args=(--function-name "$LAMBDA_FUNCTION_NAME"
+            --qualifier "$invoke_alias"
+            --statement-id "$sid"
+            --action "$action"
+            --principal "$principal")
+  [ -n "$source_arn" ] && add_args+=(--source-arn "$source_arn")
+  [ -n "$source_account" ] && add_args+=(--source-account "$source_account")
+
+  if ! aws_output=$(aws lambda add-permission "${add_args[@]}" 2>&1); then
+    echo "❌ Failed to add invoke permission '$sid' to '$LAMBDA_FUNCTION_NAME'" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - Permission denied (missing lambda:AddPermission)" >&2
+    echo "   - Invalid principal '$principal' or malformed source_arn" >&2
+    echo "   - The '$invoke_alias' alias does not exist on the function" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Verify the principal is an AWS service principal (e.g. events.amazonaws.com)" >&2
+    echo "   - Verify source_arn belongs to the same account and region as the function" >&2
+    echo "   - Run diagnose-scope to confirm the function and alias are healthy" >&2
+    echo "   📋 AWS error: $aws_output" >&2
+    return 1
+  fi
+done < <(echo "$desired" | jq -c '.[]')
+
+echo ""
+log info "✨ External invoke permissions reconciled ($desired_count declared)"
diff --git a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
new file mode 100644
index 0000000..b8b47bc
--- /dev/null
+++ b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
@@ -0,0 +1,81 @@
+#!/usr/bin/env bats
+
+setup() {
+  TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)"
+  HELPERS_DIR="$TEST_DIR/helpers"
+  LAMBDA_DIR="$(cd "$TEST_DIR/../../.." && pwd)"
+
+  load "$HELPERS_DIR/test_helper.bash"
+  load "$HELPERS_DIR/aws_cli_mock.bash"
+
+  setup_test_env
+  export SERVICE_PATH="$LAMBDA_DIR"
+  SCRIPT="$LAMBDA_DIR/scope/scripts/cleanup_role_inline_policies"
+
+  MOCK_BIN_DIR="$(mktemp -d)"
+  export PATH="$MOCK_BIN_DIR:$PATH"
+  unset -f aws np
+  setup_aws_cli_mock
+
+  export CONTEXT='{}'
+  export LAMBDA_FUNCTION_NAME="my-test-function"
+}
+
+teardown() {
+  teardown_test_env
+  [ -d "$MOCK_BIN_DIR" ] && rm -rf "$MOCK_BIN_DIR"
+}
+
+run_sourced() {
+  run bash -c "source '$SCRIPT'"
+}
+
+@test "cleanup_role_inline_policies: removes the DLQ policy from the function's role" {
+  aws_mock_response "lambda get-function-configuration" 0 \
+    "arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "iam delete-role-policy"
+  assert_aws_cli_called "--role-name np-lambda-my-test-function-role"
+  assert_aws_cli_called "--policy-name np-lambda-dlq"
+}
+
+@test "cleanup_role_inline_policies: derives the role name when the function is already gone" {
+  aws_mock_response "lambda get-function-configuration" 254 "ResourceNotFoundException"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--role-name np-lambda-my-test-function-role"
+}
+
+@test "cleanup_role_inline_policies: honours a custom execution role prefix" {
+  export LAMBDA_EXECUTION_ROLE_PREFIX="nullplatform-"
+  aws_mock_response "lambda get-function-configuration" 254 "ResourceNotFoundException"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--role-name nullplatform-my-test-function-role"
+}
+
+@test "cleanup_role_inline_policies: a missing policy is not an error" {
+  aws_mock_response "lambda get-function-configuration" 0 \
+    "arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"
+  aws_mock_response "iam delete-role-policy" 254 "NoSuchEntity"
+
+  run_sourced
+
+  assert_success
+}
+
+@test "cleanup_role_inline_policies: no-op without a function name" {
+  unset LAMBDA_FUNCTION_NAME
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "delete-role-policy"
+}
diff --git a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
new file mode 100644
index 0000000..70b062e
--- /dev/null
+++ b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
@@ -0,0 +1,183 @@
+#!/usr/bin/env bats
+
+setup() {
+  TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)"
+  HELPERS_DIR="$TEST_DIR/helpers"
+  LAMBDA_DIR="$(cd "$TEST_DIR/../../.." && pwd)"
+
+  load "$HELPERS_DIR/test_helper.bash"
+  load "$HELPERS_DIR/aws_cli_mock.bash"
+
+  setup_test_env
+  export SERVICE_PATH="$LAMBDA_DIR"
+  SCRIPT="$LAMBDA_DIR/scope/scripts/sync_dead_letter_queue"
+
+  MOCK_BIN_DIR="$(mktemp -d)"
+  export PATH="$MOCK_BIN_DIR:$PATH"
+  unset -f aws np
+  setup_aws_cli_mock
+
+  export LAMBDA_FUNCTION_NAME="my-test-function"
+  ROLE_ARN="arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"
+}
+
+teardown() {
+  teardown_test_env
+  [ -d "$MOCK_BIN_DIR" ] && rm -rf "$MOCK_BIN_DIR"
+}
+
+run_sourced() {
+  run bash -c "source '$SCRIPT'"
+}
+
+context_with_dlq() {
+  export CONTEXT="{\"scope\":{\"capabilities\":{\"dead_letter_target_arn\":\"$1\"}}}"
+}
+
+function_with_dlq() {
+  local current="${1:-}"
+  local dlq_block="null"
+  [ -n "$current" ] && dlq_block="{\"TargetArn\":\"$current\"}"
+  aws_mock_response "lambda get-function-configuration" 0 \
+    "{\"FunctionArn\":\"arn:aws:lambda:us-east-1:111122223333:function:my-test-function\",\"Role\":\"$ROLE_ARN\",\"DeadLetterConfig\":$dlq_block}"
+}
+
+@test "sync_dead_letter_queue: sets an SQS target and grants sqs:SendMessage on it only" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "iam put-role-policy"
+  assert_aws_cli_called "sqs:SendMessage"
+  assert_aws_cli_called "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  assert_aws_cli_called "--dead-letter-config TargetArn=arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  assert_aws_cli_called "--role-name np-lambda-my-test-function-role"
+}
+
+@test "sync_dead_letter_queue: grants sns:Publish for an SNS target" {
+  context_with_dlq "arn:aws:sns:us-east-1:111122223333:my-topic"
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "sns:Publish"
+  assert_aws_cli_not_called "sqs:SendMessage"
+}
+
+@test "sync_dead_letter_queue: grants access before enabling the queue" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  # Lambda drops failed events if the role cannot write yet, so the grant has
+  # to land first.
+  grant_line=$(grep -n "iam put-role-policy" "$MOCK_BIN_DIR/aws_calls" | cut -d: -f1)
+  enable_line=$(grep -n "dead-letter-config TargetArn=" "$MOCK_BIN_DIR/aws_calls" | cut -d: -f1)
+  [ "$grant_line" -lt "$enable_line" ]
+}
+
+@test "sync_dead_letter_queue: is idempotent when the target is already set" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "iam put-role-policy"
+  assert_aws_cli_not_called "update-function-configuration"
+  assert_output_contains "up to date"
+}
+
+@test "sync_dead_letter_queue: clears the config and the grant when the ARN is empty" {
+  context_with_dlq ""
+  function_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--dead-letter-config {}"
+  assert_aws_cli_called "iam delete-role-policy"
+  assert_aws_cli_called "--policy-name np-lambda-dlq"
+  assert_output_contains "Dead letter queue disabled"
+}
+
+@test "sync_dead_letter_queue: does not call Lambda when there is nothing to disable" {
+  context_with_dlq ""
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "update-function-configuration"
+  assert_aws_cli_called "iam delete-role-policy"
+}
+
+@test "sync_dead_letter_queue: rejects a target that is neither SQS nor SNS" {
+  context_with_dlq "arn:aws:s3:::my-bucket"
+  function_with_dlq
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Unsupported dead letter target"
+  assert_aws_cli_not_called "update-function-configuration"
+}
+
+@test "sync_dead_letter_queue: rejects a queue name that is not an ARN" {
+  context_with_dlq "my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Unsupported dead letter target"
+}
+
+@test "sync_dead_letter_queue: never touches code, environment or version" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "update-function-code"
+  assert_aws_cli_not_called "--environment"
+  assert_aws_cli_not_called "publish-version"
+}
+
+@test "sync_dead_letter_queue: fails when LAMBDA_FUNCTION_NAME is not set" {
+  unset LAMBDA_FUNCTION_NAME
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "LAMBDA_FUNCTION_NAME is required"
+}
+
+@test "sync_dead_letter_queue: surfaces a failure reading the function" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  aws_mock_response "lambda get-function-configuration" 254 "ResourceNotFoundException"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Failed to read configuration"
+}
+
+@test "sync_dead_letter_queue: surfaces a denied IAM grant without enabling the queue" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+  aws_mock_response "iam put-role-policy" 254 "AccessDenied"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Failed to grant dead letter access"
+  assert_aws_cli_not_called "update-function-configuration"
+}
diff --git a/lambda/scope/tests/scripts/sync_invoke_permissions.bats b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
new file mode 100644
index 0000000..5de7740
--- /dev/null
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -0,0 +1,186 @@
+#!/usr/bin/env bats
+
+setup() {
+  TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)"
+  HELPERS_DIR="$TEST_DIR/helpers"
+  LAMBDA_DIR="$(cd "$TEST_DIR/../../.." && pwd)"
+
+  load "$HELPERS_DIR/test_helper.bash"
+  load "$HELPERS_DIR/aws_cli_mock.bash"
+
+  setup_test_env
+  export SERVICE_PATH="$LAMBDA_DIR"
+  SCRIPT="$LAMBDA_DIR/scope/scripts/sync_invoke_permissions"
+
+  MOCK_BIN_DIR="$(mktemp -d)"
+  export PATH="$MOCK_BIN_DIR:$PATH"
+  unset -f aws np
+  setup_aws_cli_mock
+
+  export LAMBDA_FUNCTION_NAME="my-test-function"
+  export LAMBDA_MAIN_ALIAS_NAME="main"
+}
+
+teardown() {
+  teardown_test_env
+  [ -d "$MOCK_BIN_DIR" ] && rm -rf "$MOCK_BIN_DIR"
+}
+
+# The workflow engine sources these scripts, so `return` is the exit path.
+run_sourced() {
+  run bash -c "source '$SCRIPT'"
+}
+
+context_with() {
+  export CONTEXT="{\"providers\":{\"scope-configurations\":{\"lambda\":{\"triggers\":{\"invoke_permissions\":$1}}}}}"
+}
+
+no_policy() {
+  aws_mock_response "lambda get-policy" 254 "ResourceNotFoundException: The resource you requested does not exist."
+}
+
+with_policy() {
+  aws_mock_response "lambda get-policy" 0 "$1"
+}
+
+@test "sync_invoke_permissions: no declared permissions and no policy is a no-op" {
+  context_with '[]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "add-permission"
+  assert_aws_cli_not_called "remove-permission"
+  assert_output_contains "0 declared"
+}
+
+@test "sync_invoke_permissions: adds a declared permission against the main alias" {
+  context_with '[{"statement_id":"apigw-authorizer","principal":"apigateway.amazonaws.com","source_arn":"arn:aws:execute-api:us-east-1:111122223333:abcd/authorizers/*"}]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "add-permission"
+  assert_aws_cli_called "--statement-id np-ext-apigw-authorizer"
+  assert_aws_cli_called "--principal apigateway.amazonaws.com"
+  assert_aws_cli_called "--source-arn arn:aws:execute-api:us-east-1:111122223333:abcd/authorizers/*"
+  # Blue/green: the grant must target the alias, never the bare function
+  assert_aws_cli_called "--qualifier main"
+}
+
+@test "sync_invoke_permissions: defaults the action to lambda:InvokeFunction" {
+  context_with '[{"statement_id":"eventbridge-daily","principal":"events.amazonaws.com"}]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--action lambda:InvokeFunction"
+}
+
+@test "sync_invoke_permissions: passes source_account when declared" {
+  context_with '[{"statement_id":"s3-uploads","principal":"s3.amazonaws.com","source_arn":"arn:aws:s3:::my-bucket","source_account":"111122223333"}]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--source-account 111122223333"
+}
+
+@test "sync_invoke_permissions: leaves an already-matching permission untouched" {
+  context_with '[{"statement_id":"eventbridge-daily","principal":"events.amazonaws.com","source_arn":"arn:aws:events:us-east-1:111122223333:rule/daily"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-eventbridge-daily","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction","Condition":{"ArnLike":{"AWS:SourceArn":"arn:aws:events:us-east-1:111122223333:rule/daily"}}}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "add-permission"
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: replaces a permission whose source_arn changed" {
+  context_with '[{"statement_id":"eventbridge-daily","principal":"events.amazonaws.com","source_arn":"arn:aws:events:us-east-1:111122223333:rule/NEW"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-eventbridge-daily","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction","Condition":{"ArnLike":{"AWS:SourceArn":"arn:aws:events:us-east-1:111122223333:rule/OLD"}}}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "remove-permission"
+  assert_aws_cli_called "--source-arn arn:aws:events:us-east-1:111122223333:rule/NEW"
+}
+
+@test "sync_invoke_permissions: removes a managed permission that is no longer declared" {
+  context_with '[]'
+  with_policy '{"Statement":[{"Sid":"np-ext-stale","Effect":"Allow","Principal":{"Service":"s3.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--statement-id np-ext-stale"
+  assert_aws_cli_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: never touches the scope's own API Gateway or ALB statements" {
+  context_with '[]'
+  with_policy '{"Statement":[{"Sid":"AllowAPIGatewayInvoke","Effect":"Allow","Principal":{"Service":"apigateway.amazonaws.com"},"Action":"lambda:InvokeFunction"},{"Sid":"AllowALBInvoke","Effect":"Allow","Principal":{"Service":"elasticloadbalancing.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: leaves unrelated hand-made statements alone" {
+  context_with '[]'
+  with_policy '{"Statement":[{"Sid":"SomebodyElsesGrant","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: rejects a statement_id with invalid characters" {
+  context_with '[{"statement_id":"arn:aws:events:us-east-1:1:rule/x","principal":"events.amazonaws.com"}]'
+  no_policy
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Invalid statement_id"
+  assert_aws_cli_not_called "add-permission"
+}
+
+@test "sync_invoke_permissions: rejects an entry missing its principal" {
+  context_with '[{"statement_id":"no-principal"}]'
+  no_policy
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "missing 'statement_id' or 'principal'"
+}
+
+@test "sync_invoke_permissions: fails when LAMBDA_FUNCTION_NAME is not set" {
+  unset LAMBDA_FUNCTION_NAME
+  context_with '[]'
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "LAMBDA_FUNCTION_NAME is required"
+}
+
+@test "sync_invoke_permissions: surfaces an AWS failure when adding a permission" {
+  context_with '[{"statement_id":"eventbridge-daily","principal":"events.amazonaws.com"}]'
+  no_policy
+  aws_mock_response "lambda add-permission" 254 "AccessDeniedException"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Failed to add invoke permission"
+}
diff --git a/lambda/scope/workflows/create.yaml b/lambda/scope/workflows/create.yaml
index 8ec86c3..d3f5590 100644
--- a/lambda/scope/workflows/create.yaml
+++ b/lambda/scope/workflows/create.yaml
@@ -114,6 +114,18 @@ steps:
         type: environment
       - name: ALB_RULE_ARN
         type: environment
+      - name: LAMBDA_ALIAS_ARN
+        type: environment
+      - name: LAMBDA_EXECUTION_ROLE_ARN
+        type: environment
+      - name: LAMBDA_EXECUTION_ROLE_NAME
+        type: environment
+  - name: sync_invoke_permissions
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/sync_invoke_permissions"
+  - name: sync_dead_letter_queue
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/sync_dead_letter_queue"
   - name: store_metadata
     type: script
     file: "$SERVICE_PATH/scope/scripts/store_nrn_metadata"
diff --git a/lambda/scope/workflows/delete.yaml b/lambda/scope/workflows/delete.yaml
index c5bdf87..bf7d53a 100644
--- a/lambda/scope/workflows/delete.yaml
+++ b/lambda/scope/workflows/delete.yaml
@@ -77,6 +77,9 @@ steps:
         type: environment
       - name: MODULES_TO_USE
         type: environment
+  - name: cleanup_role_inline_policies
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/cleanup_role_inline_policies"
   - name: compose_modules
     type: script
     file: "$SERVICE_PATH/scope/tofu/compose_modules"
diff --git a/lambda/scope/workflows/update.yaml b/lambda/scope/workflows/update.yaml
index 9969bc8..7ab2565 100644
--- a/lambda/scope/workflows/update.yaml
+++ b/lambda/scope/workflows/update.yaml
@@ -24,3 +24,12 @@ steps:
   - name: update_iam
     type: script
     file: "$SERVICE_PATH/scope/scripts/update_iam_role"
+  - name: sync_invoke_permissions
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/sync_invoke_permissions"
+  - name: sync_dead_letter_queue
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/sync_dead_letter_queue"
+  - name: store_metadata
+    type: script
+    file: "$SERVICE_PATH/scope/scripts/store_nrn_metadata"
diff --git a/lambda/specs/scope-configuration.json.tpl b/lambda/specs/scope-configuration.json.tpl
index 09a327b..65117e2 100644
--- a/lambda/specs/scope-configuration.json.tpl
+++ b/lambda/specs/scope-configuration.json.tpl
@@ -48,6 +48,52 @@
             "description": "Optional ARN of the nullplatform agent Lambda layer (e.g. arn:aws:lambda:us-east-1:123456789012:layer:nullplatform-agent:1)."
           }
         }
+      },
+      "triggers": {
+        "type": "object",
+        "title": "External invocation (optional)",
+        "description": "Extra AWS principals allowed to invoke the scope's Lambda, beyond the API Gateway or ALB the scope provisions itself.",
+        "properties": {
+          "invoke_permissions": {
+            "type": "array",
+            "title": "Invoke permissions",
+            "description": "Each entry becomes a Lambda resource policy statement on the scope's main alias, so external triggers respect blue/green traffic weights.",
+            "default": [],
+            "items": {
+              "type": "object",
+              "required": ["statement_id", "principal"],
+              "properties": {
+                "statement_id": {
+                  "type": "string",
+                  "title": "Statement ID",
+                  "description": "Short symbolic name, unique within the scope (letters, digits, '-' and '_'). Example: apigw-authorizer.",
+                  "pattern": "^[a-zA-Z0-9_-]+$"
+                },
+                "principal": {
+                  "type": "string",
+                  "title": "Principal",
+                  "description": "AWS service principal allowed to invoke. Example: apigateway.amazonaws.com, events.amazonaws.com, s3.amazonaws.com."
+                },
+                "source_arn": {
+                  "type": "string",
+                  "title": "Source ARN",
+                  "description": "Optional but strongly recommended: restricts the grant to a single caller. Example: arn:aws:execute-api:us-east-1:123456789012:abcd1234/authorizers/*."
+                },
+                "source_account": {
+                  "type": "string",
+                  "title": "Source account",
+                  "description": "Optional. Required by S3, whose bucket ARNs carry no account ID."
+                },
+                "action": {
+                  "type": "string",
+                  "title": "Action",
+                  "description": "Lambda action to grant.",
+                  "default": "lambda:InvokeFunction"
+                }
+              }
+            }
+          }
+        }
       }
     },
     "uiSchema": {
@@ -100,6 +146,21 @@
                   "scope": "#/properties/agent/properties/null_agent_layer_arn"
                 }
               ]
+            },
+            {
+              "type": "Category",
+              "label": "External invocation (optional)",
+              "elements": [
+                {
+                  "type": "Label",
+                  "text": "> **\u26a0\ufe0f This grants invoke rights**\n\nEach entry lets another AWS service call this scope's Lambda. Only needed when the function is triggered by something other than the scope's own HTTP endpoint \u2014 an API Gateway authorizer, an EventBridge rule or scheduler, or an S3 bucket notification.\n\nAlways set a **Source ARN** so the grant is limited to one caller; a principal without it lets *any* resource of that service in the account invoke the function. S3 additionally requires **Source account**, because bucket ARNs carry no account ID.\n\nPermissions are attached to the scope's `main` alias, so external triggers follow blue/green traffic weights.",
+                  "options": { "format": "markdown" }
+                },
+                {
+                  "type": "Control",
+                  "scope": "#/properties/triggers/properties/invoke_permissions"
+                }
+              ]
             }
           ]
         }
diff --git a/lambda/specs/service-spec.json.tpl b/lambda/specs/service-spec.json.tpl
index e5f03c1..0c6e3c2 100644
--- a/lambda/specs/service-spec.json.tpl
+++ b/lambda/specs/service-spec.json.tpl
@@ -116,6 +116,10 @@
                   {
                     "type": "Control",
                     "scope": "#/properties/architecture"
+                  },
+                  {
+                    "type": "Control",
+                    "scope": "#/properties/dead_letter_target_arn"
                   }
                 ]
               },
@@ -259,7 +263,8 @@
             { "const": "ruby4.0", "title": "Ruby 4.0" },
             { "const": "ruby3.4", "title": "Ruby 3.4" },
             { "const": "ruby3.3", "title": "Ruby 3.3" },
-            { "const": "provided.al2023", "title": "Custom Runtime (Amazon Linux 2023)" }
+            { "const": "provided.al2023", "title": "Custom Runtime (Amazon Linux 2023)" },
+            { "const": "provided.al2", "title": "Custom Runtime (Amazon Linux 2)" }
           ]
         },
         "handler": {
@@ -389,6 +394,12 @@
           "description": "Run Lambda inside your VPC for access to private resources",
           "default": false
         },
+        "dead_letter_target_arn": {
+          "type": "string",
+          "title": "Dead letter queue",
+          "description": "SQS queue or SNS topic ARN that receives events whose asynchronous invocation failed after all retries. Leave empty to disable. The execution role is granted send access to this ARN only.",
+          "default": ""
+        },
         "layers": {
           "type": "array",
           "title": "Custom Layers",

From bb02ce7e129fc4dcb9bd0905352738c0f8cc8ffd Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:36:17 -0500
Subject: [PATCH 4/5] feat(lambda): publish the scope Lambda identity to its
 NRN

Lets a service attach an event source mapping to the alias instead of
re-deriving names. update-scope backfills pre-existing scopes from AWS.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lambda/scope/scripts/store_nrn_metadata       |  78 ++++++--
 .../tests/scripts/store_nrn_metadata.bats     | 176 ++++++++++++++++++
 .../tofu/compute/lambda/modules/locals.tf     |   1 -
 .../tofu/compute/lambda/modules/outputs.tf    |   5 -
 lambda/scope/tofu/do_tofu                     |  21 +++
 5 files changed, 261 insertions(+), 20 deletions(-)
 create mode 100644 lambda/scope/tests/scripts/store_nrn_metadata.bats

diff --git a/lambda/scope/scripts/store_nrn_metadata b/lambda/scope/scripts/store_nrn_metadata
index b56c7af..4fa2e9d 100755
--- a/lambda/scope/scripts/store_nrn_metadata
+++ b/lambda/scope/scripts/store_nrn_metadata
@@ -1,12 +1,13 @@
 #!/bin/bash
-# Store ALB rule priority in NRN for idempotent re-deployments.
-# This is the only value that must be persisted: it is assigned once
-# (dynamically via listener query or from config) and reused on every
-# re-deployment so the listener rule priority remains stable.
+# Publish the scope's Lambda identity (and the ALB rule priority) to its NRN,
+# so other services can target the alias without re-deriving names.
+#
+# Values come from do_tofu's outputs; the update path has no tofu run, so gaps
+# are resolved from AWS — which also backfills pre-existing scopes.
 
 source "$SERVICE_PATH/utils/log"
 
-log info "📝 Storing ALB rule priority in NRN..."
+log info "📝 Storing scope metadata in NRN..."
 
 if [ -z "${SCOPE_NRN:-}" ]; then
   echo "❌ SCOPE_NRN is required" >&2
@@ -19,19 +20,68 @@ if [ -z "${SCOPE_NRN:-}" ]; then
   return 1
 fi
 
-# Non-HTTP (event-driven) scopes skip ALB setup entirely and won't have this set.
-if [ -z "${ALB_RULE_PRIORITY:-}" ]; then
-  log debug "   ⏭️  ALB_RULE_PRIORITY not set — nothing to store (non-HTTP scope)"
-  return 0
+main_alias="${LAMBDA_MAIN_ALIAS_NAME:-main}"
+
+# ── Fill the gaps left by a run without tofu ──────────────────────────────────
+if [ -n "${LAMBDA_FUNCTION_NAME:-}" ]; then
+  if [ -z "${LAMBDA_FUNCTION_ARN:-}" ] || [ -z "${LAMBDA_EXECUTION_ROLE_ARN:-}" ]; then
+    if fn_config=$(aws lambda get-function-configuration \
+      --function-name "$LAMBDA_FUNCTION_NAME" --output json 2>/dev/null); then
+      [ -z "${LAMBDA_FUNCTION_ARN:-}" ] && LAMBDA_FUNCTION_ARN=$(echo "$fn_config" | jq -r '.FunctionArn // ""')
+      if [ -z "${LAMBDA_EXECUTION_ROLE_ARN:-}" ]; then
+        LAMBDA_EXECUTION_ROLE_ARN=$(echo "$fn_config" | jq -r '.Role // ""')
+      fi
+    else
+      log debug "   ⏭️  Could not read function configuration — skipping identity backfill"
+    fi
+  fi
+
+  if [ -z "${LAMBDA_ALIAS_ARN:-}" ]; then
+    LAMBDA_ALIAS_ARN=$(aws lambda get-alias \
+      --function-name "$LAMBDA_FUNCTION_NAME" \
+      --name "$main_alias" \
+      --query 'AliasArn' --output text 2>/dev/null || echo "")
+    [ "$LAMBDA_ALIAS_ARN" = "None" ] && LAMBDA_ALIAS_ARN=""
+  fi
 fi
 
-log debug "   ✅ scope_nrn=$SCOPE_NRN"
-log debug "   ✅ alb_rule_priority=$ALB_RULE_PRIORITY"
+if [ -z "${LAMBDA_EXECUTION_ROLE_NAME:-}" ] && [ -n "${LAMBDA_EXECUTION_ROLE_ARN:-}" ]; then
+  LAMBDA_EXECUTION_ROLE_NAME="${LAMBDA_EXECUTION_ROLE_ARN##*/}"
+fi
+
+# ── Build the payload from whatever resolved ──────────────────────────────────
+metadata='{}'
+
+add_metadata() {
+  local key="$1" value="$2"
+  if [ -z "$value" ] || [ "$value" = "null" ]; then
+    return 0
+  fi
+  metadata=$(echo "$metadata" | jq --arg k "$key" --arg v "$value" '. + {($k): $v}')
+  log debug "   ✅ $key=$value"
+}
 
-metadata=$(jq -n --argjson priority "$ALB_RULE_PRIORITY" '{"alb_rule_priority": $priority}')
+add_metadata "function_name"       "${LAMBDA_FUNCTION_NAME:-}"
+add_metadata "function_arn"        "${LAMBDA_FUNCTION_ARN:-}"
+add_metadata "alias_arn"           "${LAMBDA_ALIAS_ARN:-}"
+# The alias name only means something alongside a function
+[ -n "${LAMBDA_FUNCTION_NAME:-}" ] && add_metadata "main_alias" "$main_alias"
+add_metadata "execution_role_arn"  "${LAMBDA_EXECUTION_ROLE_ARN:-}"
+add_metadata "execution_role_name" "${LAMBDA_EXECUTION_ROLE_NAME:-}"
+
+# Non-HTTP (event-driven) scopes skip ALB setup entirely and won't have this set.
+if [ -n "${ALB_RULE_PRIORITY:-}" ]; then
+  metadata=$(echo "$metadata" | jq --argjson p "$ALB_RULE_PRIORITY" '. + {alb_rule_priority: $p}')
+  log debug "   ✅ alb_rule_priority=$ALB_RULE_PRIORITY"
+fi
+
+if [ "$(echo "$metadata" | jq 'length')" -eq 0 ]; then
+  log debug "   ⏭️  Nothing resolved to store — skipping"
+  return 0
+fi
 
 # Prefix with "lambda." namespace
-metadata=$(echo "$metadata" | jq 'with_entries(.key = "lambda." + .key)')
+metadata=$(echo "$metadata" | jq -c 'with_entries(.key = "lambda." + .key)')
 log debug "   ✅ Final metadata payload: $metadata"
 
 echo ""
@@ -59,4 +109,4 @@ fi
 
 log debug "   ✅ Metadata stored successfully"
 echo ""
-log info "✨ ALB rule priority stored for scope=$SCOPE_NRN"
+log info "✨ Scope metadata stored for $SCOPE_NRN"
diff --git a/lambda/scope/tests/scripts/store_nrn_metadata.bats b/lambda/scope/tests/scripts/store_nrn_metadata.bats
new file mode 100644
index 0000000..7466e1c
--- /dev/null
+++ b/lambda/scope/tests/scripts/store_nrn_metadata.bats
@@ -0,0 +1,176 @@
+#!/usr/bin/env bats
+
+setup() {
+  TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)"
+  HELPERS_DIR="$TEST_DIR/helpers"
+  LAMBDA_DIR="$(cd "$TEST_DIR/../../.." && pwd)"
+
+  load "$HELPERS_DIR/test_helper.bash"
+  load "$HELPERS_DIR/aws_cli_mock.bash"
+
+  setup_test_env
+  export SERVICE_PATH="$LAMBDA_DIR"
+  SCRIPT="$LAMBDA_DIR/scope/scripts/store_nrn_metadata"
+
+  MOCK_BIN_DIR="$(mktemp -d)"
+  export PATH="$MOCK_BIN_DIR:$PATH"
+  unset -f aws np
+  setup_aws_cli_mock
+  create_np_mock 0
+
+  export SCOPE_NRN="organization=1:account=2:namespace=3:application=4:scope=5"
+  export LAMBDA_FUNCTION_NAME="my-test-function"
+}
+
+teardown() {
+  teardown_test_env
+  [ -d "$MOCK_BIN_DIR" ] && rm -rf "$MOCK_BIN_DIR"
+}
+
+run_sourced() {
+  run bash -c "source '$SCRIPT'"
+}
+
+create_np_mock() {
+  echo "${1:-0}" > "$MOCK_BIN_DIR/np_exit"
+  : > "$MOCK_BIN_DIR/np_calls"
+  cat > "$MOCK_BIN_DIR/np" << 'MOCK_SCRIPT'
+#!/bin/bash
+MOCK_DIR="$(dirname "$0")"
+printf '%s\n' "$*" >> "$MOCK_DIR/np_calls"
+exit_code=$(cat "$MOCK_DIR/np_exit")
+[ "$exit_code" != "0" ] && { echo "np failed" >&2; exit "$exit_code"; }
+echo '{}'
+MOCK_SCRIPT
+  chmod +x "$MOCK_BIN_DIR/np"
+}
+
+np_body() {
+  cat "$MOCK_BIN_DIR/np_calls" 2>/dev/null
+}
+
+assert_np_body_contains() {
+  if ! grep -qF -- "$1" "$MOCK_BIN_DIR/np_calls" 2>/dev/null; then
+    echo "Expected the NRN patch body to contain: $1"
+    echo "Actual np calls:"
+    np_body | sed 's/^/  - np /'
+    return 1
+  fi
+}
+
+assert_np_not_called() {
+  if [ -s "$MOCK_BIN_DIR/np_calls" ]; then
+    echo "Expected no np call, but got:"
+    np_body | sed 's/^/  - np /'
+    return 1
+  fi
+}
+
+# The create path: do_tofu exported everything, no AWS lookups needed.
+with_tofu_outputs() {
+  export LAMBDA_FUNCTION_ARN="arn:aws:lambda:us-east-1:111122223333:function:my-test-function"
+  export LAMBDA_ALIAS_ARN="arn:aws:lambda:us-east-1:111122223333:function:my-test-function:main"
+  export LAMBDA_EXECUTION_ROLE_ARN="arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"
+  export LAMBDA_EXECUTION_ROLE_NAME="np-lambda-my-test-function-role"
+  export LAMBDA_MAIN_ALIAS_NAME="main"
+}
+
+@test "store_nrn_metadata: publishes the scope identity under the lambda namespace" {
+  with_tofu_outputs
+
+  run_sourced
+
+  assert_success
+  assert_np_body_contains "lambda.function_name"
+  assert_np_body_contains "lambda.alias_arn"
+  assert_np_body_contains "lambda.execution_role_arn"
+  assert_np_body_contains "arn:aws:lambda:us-east-1:111122223333:function:my-test-function:main"
+  assert_aws_cli_not_called "get-alias"
+}
+
+@test "store_nrn_metadata: defaults the alias name to main" {
+  with_tofu_outputs
+  unset LAMBDA_MAIN_ALIAS_NAME
+
+  run_sourced
+
+  assert_success
+  assert_np_body_contains '"lambda.main_alias":"main"'
+}
+
+@test "store_nrn_metadata: omits the ALB priority on event-driven scopes" {
+  with_tofu_outputs
+
+  run_sourced
+
+  assert_success
+  assert_np_body_contains "lambda.function_arn"
+  run bash -c "grep -qF 'alb_rule_priority' '$MOCK_BIN_DIR/np_calls'"
+  assert_failure
+}
+
+@test "store_nrn_metadata: keeps storing the ALB priority as a number" {
+  with_tofu_outputs
+  export ALB_RULE_PRIORITY=142
+
+  run_sourced
+
+  assert_success
+  assert_np_body_contains '"lambda.alb_rule_priority":142'
+}
+
+# The update path: no tofu run, so identity has to come from AWS. This is also
+# what backfills scopes created before this script published identity.
+@test "store_nrn_metadata: backfills identity from AWS when tofu outputs are absent" {
+  aws_mock_response "lambda get-function-configuration" 0 \
+    '{"FunctionArn":"arn:aws:lambda:us-east-1:111122223333:function:my-test-function","Role":"arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"}'
+  aws_mock_response "lambda get-alias" 0 \
+    "arn:aws:lambda:us-east-1:111122223333:function:my-test-function:main"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "get-function-configuration"
+  assert_aws_cli_called "get-alias"
+  assert_np_body_contains "arn:aws:lambda:us-east-1:111122223333:function:my-test-function:main"
+  assert_np_body_contains '"lambda.execution_role_name":"np-lambda-my-test-function-role"'
+}
+
+@test "store_nrn_metadata: still stores the name when AWS lookups fail" {
+  aws_mock_response "lambda get-function-configuration" 254 "ResourceNotFoundException"
+  aws_mock_response "lambda get-alias" 254 "ResourceNotFoundException"
+
+  run_sourced
+
+  assert_success
+  assert_np_body_contains '"lambda.function_name":"my-test-function"'
+}
+
+@test "store_nrn_metadata: skips the patch when nothing resolves" {
+  unset LAMBDA_FUNCTION_NAME
+
+  run_sourced
+
+  assert_success
+  assert_np_not_called
+}
+
+@test "store_nrn_metadata: fails when SCOPE_NRN is not set" {
+  unset SCOPE_NRN
+  with_tofu_outputs
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "SCOPE_NRN is required"
+}
+
+@test "store_nrn_metadata: surfaces an NRN patch failure" {
+  with_tofu_outputs
+  create_np_mock 1
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Failed to write NRN metadata"
+}
diff --git a/lambda/scope/tofu/compute/lambda/modules/locals.tf b/lambda/scope/tofu/compute/lambda/modules/locals.tf
index d4cf054..cca096b 100644
--- a/lambda/scope/tofu/compute/lambda/modules/locals.tf
+++ b/lambda/scope/tofu/compute/lambda/modules/locals.tf
@@ -35,7 +35,6 @@ locals {
   lambda_function_invoke_arn = aws_lambda_function.main.invoke_arn
   lambda_alias_arn           = aws_lambda_alias.main.arn
   lambda_alias_invoke_arn    = aws_lambda_alias.main.invoke_arn
-  lambda_qualified_arn       = aws_lambda_alias.main.arn
   lambda_current_version     = aws_lambda_function.main.version
   lambda_main_alias_name     = aws_lambda_alias.main.name
 }
diff --git a/lambda/scope/tofu/compute/lambda/modules/outputs.tf b/lambda/scope/tofu/compute/lambda/modules/outputs.tf
index b64720a..448285b 100644
--- a/lambda/scope/tofu/compute/lambda/modules/outputs.tf
+++ b/lambda/scope/tofu/compute/lambda/modules/outputs.tf
@@ -28,11 +28,6 @@ output "lambda_current_version" {
   value       = aws_lambda_function.main.version
 }
 
-output "lambda_qualified_arn" {
-  description = "Qualified ARN of the Lambda function (with alias)"
-  value       = aws_lambda_alias.main.arn
-}
-
 output "lambda_log_group_name" {
   description = "Name of the CloudWatch log group"
   value       = aws_cloudwatch_log_group.lambda.name
diff --git a/lambda/scope/tofu/do_tofu b/lambda/scope/tofu/do_tofu
index e6d94e5..c7c1ffd 100755
--- a/lambda/scope/tofu/do_tofu
+++ b/lambda/scope/tofu/do_tofu
@@ -216,6 +216,27 @@ if [ "$TOFU_ACTION" = "apply" ]; then
       log debug "   ✅ alb_listener_rule_arn=$ALB_RULE_ARN"
       export ALB_RULE_ARN
     fi
+
+    # Identity of the scope's function, published to the NRN by store_nrn_metadata
+    # so that services and links can attach event source mappings to the alias
+    # instead of re-deriving the name from slugs.
+    LAMBDA_ALIAS_ARN=$(echo "$outputs" | jq -r '.lambda_alias_arn.value // empty')
+    if [ -n "$LAMBDA_ALIAS_ARN" ]; then
+      log debug "   ✅ alias_arn=$LAMBDA_ALIAS_ARN"
+      export LAMBDA_ALIAS_ARN
+    fi
+
+    LAMBDA_EXECUTION_ROLE_ARN=$(echo "$outputs" | jq -r '.iam_role_arn.value // empty')
+    if [ -n "$LAMBDA_EXECUTION_ROLE_ARN" ]; then
+      log debug "   ✅ execution_role_arn=$LAMBDA_EXECUTION_ROLE_ARN"
+      export LAMBDA_EXECUTION_ROLE_ARN
+    fi
+
+    LAMBDA_EXECUTION_ROLE_NAME=$(echo "$outputs" | jq -r '.iam_role_name.value // empty')
+    if [ -n "$LAMBDA_EXECUTION_ROLE_NAME" ]; then
+      log debug "   ✅ execution_role_name=$LAMBDA_EXECUTION_ROLE_NAME"
+      export LAMBDA_EXECUTION_ROLE_NAME
+    fi
   fi
 
   # Tofu manages the alias with lifecycle.ignore_changes on function_version, so it

From 18b4ab8fef7b8db6ba36b5c9f7777623bb861f10 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:36:17 -0500
Subject: [PATCH 5/5] docs(lambda): document event-driven scopes

Also fixes a stale capability table and test paths.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 155 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 137 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index d2d282c..04e9fb3 100644
--- a/README.md
+++ b/README.md
@@ -232,8 +232,8 @@ The `service-spec.json.tpl` defines the developer-facing capabilities:
 
 | Capability | Options | Default |
 |------------|---------|---------|
-| **Runtime** | Node.js 20/18, Python 3.12/3.11/3.10, Java 21/17/11, .NET 8/6, Ruby 3.3/3.2, Custom (AL2023/AL2) | `nodejs20.x` |
-| **Memory** | 128 MB, 256 MB, 512 MB, 1 GB, 2 GB, 4 GB, 8 GB, 10 GB | `256 MB` |
+| **Runtime** | Node.js 24/22/20, Python 3.14/3.13/3.12/3.11/3.10, Java 25/21/17/11, .NET 10/8, Ruby 4.0/3.4/3.3, Custom (AL2023/AL2) | `nodejs22.x` |
+| **Memory** | 128 MB - 10 GB | `256 MB` |
 | **Timeout** | 3 - 900 seconds | `30` |
 | **Architecture** | ARM64 (Graviton2), x86_64 | `arm64` |
 | **Visibility** | Public (API Gateway), Private (ALB) | — |
@@ -242,8 +242,38 @@ The `service-spec.json.tpl` defines the developer-facing capabilities:
 | **Provisioned Concurrency** | Unprovisioned, Custom value | `unprovisioned` |
 | **VPC** | Optional private networking | Disabled |
 | **Layers** | Custom Lambda layers (ARN-based) | None |
+| **Dead Letter Queue** | SQS queue or SNS topic ARN for failed async invocations | None |
 | **Continuous Delivery** | Git branch-based auto-deployment | — |
 
+### Event-driven scopes
+
+A scope's own API Gateway or ALB is not the only thing that can invoke its
+function. DynamoDB streams, SQS, API Gateway authorizers, EventBridge rules and
+schedulers, and S3 bucket notifications all invoke Lambda directly, and each
+needs two things the scope has to provide.
+
+**Invoke permissions.** DevOps declares the extra principals in the
+`triggers.invoke_permissions` key of the scope-configuration (see
+[External invocation](#external-invocation)). Each entry becomes a statement on
+the function's resource policy, attached to the **`main` alias** — so an external
+trigger follows the same blue/green traffic weights as HTTP traffic.
+
+**Scope identity.** `create-scope` and `update-scope` publish the function's
+identity to the scope's NRN under the `lambda.` namespace:
+
+| NRN key | Value |
+|---------|-------|
+| `lambda.function_name` | Function name |
+| `lambda.function_arn` | Unqualified function ARN |
+| `lambda.alias_arn` | ARN of the `main` alias — the target for event source mappings |
+| `lambda.main_alias` | Alias name (`main`) |
+| `lambda.execution_role_arn` / `lambda.execution_role_name` | Execution role |
+
+A service that provisions an event source mapping (SQS, DynamoDB streams) reads
+`lambda.alias_arn` from the NRN instead of re-deriving the function name from
+slugs. Scopes created before this existed are backfilled on the next
+`update-scope`.
+
 ---
 
 ## Configuration
@@ -349,6 +379,88 @@ Then set the URI (matching your scope architecture) in `values.yaml` or the agen
 PLACEHOLDER_IMAGE_URI_DEFAULT: "123456789012.dkr.ecr.us-east-1.amazonaws.com/aws-lambda/nullplatform-lambda-placeholder:latest-arm64"
 ```
 
+### External invocation
+
+Set in the **scope-configuration** provider (`triggers.invoke_permissions`), not
+in the scope's own attributes: granting another AWS principal the right to invoke
+the function is a privilege grant, so it belongs to whoever operates the account
+rather than to the scope form. The key allows dimensions, so it can differ per
+environment.
+
+```json
+{
+  "triggers": {
+    "invoke_permissions": [
+      {
+        "statement_id": "apigw-authorizer",
+        "principal": "apigateway.amazonaws.com",
+        "source_arn": "arn:aws:execute-api:us-east-1:111122223333:abcd1234/authorizers/*"
+      },
+      {
+        "statement_id": "eventbridge-daily",
+        "principal": "events.amazonaws.com",
+        "source_arn": "arn:aws:events:us-east-1:111122223333:rule/daily-report"
+      },
+      {
+        "statement_id": "s3-uploads",
+        "principal": "s3.amazonaws.com",
+        "source_arn": "arn:aws:s3:::my-bucket",
+        "source_account": "111122223333"
+      }
+    ]
+  }
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `statement_id` | yes | Short symbolic name, `[a-zA-Z0-9_-]` only. Stored as `np-ext-<statement_id>`. |
+| `principal` | yes | AWS service principal. |
+| `source_arn` | no, but recommended | Without it, *any* resource of that service in the account can invoke the function. |
+| `source_account` | no | Required for S3, whose bucket ARNs carry no account ID. |
+| `action` | no | Defaults to `lambda:InvokeFunction`. |
+
+Reconciliation is idempotent and runs on both `create-scope` and `update-scope`:
+entries are added, changed entries are replaced, and entries you remove from the
+config are removed from AWS. Only statements carrying the `np-ext-` prefix are
+ever deleted — the scope's own `AllowAPIGatewayInvoke` / `AllowALBInvoke` and any
+statement added out of band are left alone.
+
+### Dead letter queue
+
+`dead_letter_target_arn` (a scope attribute) points at an SQS queue or SNS topic
+that receives events whose **asynchronous** invocation failed after all retries.
+This is the function's DLQ — unrelated to the redrive policy of a queue the
+function consumes from, which belongs to the SQS service.
+
+Setting it does two things: it enables `DeadLetterConfig` on the function, and it
+grants the execution role `sqs:SendMessage` or `sns:Publish` (derived from the
+ARN) on that ARN and nothing else. Without the grant Lambda drops the failed
+event silently, so the two always move together. Clearing the attribute reverts
+both.
+
+> **Why these two live outside Terraform.** The scope's OpenTofu run only happens
+> on `create-scope` / `delete-scope`. The per-scope state holds the *placeholder*
+> function, while deployments mutate the real function through the AWS CLI, so an
+> `apply` on update would see drift and roll the function back to the placeholder.
+> Invoke permissions and the DLQ are therefore reconciled with idempotent AWS CLI
+> scripts that run on both create and update, and touch only the field they own.
+> `delete-scope` removes the inline DLQ policy before the destroy, because IAM
+> refuses to delete a role that still carries policies Terraform does not manage.
+
+### What `update-scope` reconciles
+
+| Reconciled by `update-scope` | Applied on the next deployment |
+|------------------------------|--------------------------------|
+| `vpc_enabled` (execution role policy) | `memory`, `timeout`, `ephemeral_storage` |
+| `triggers.invoke_permissions` | `runtime`, `handler` (Zip only) |
+| `dead_letter_target_arn` | `layers`, environment variables, VPC config |
+| NRN identity metadata | |
+
+`reserved_concurrency` and `provisioned_concurrency` have their own actions and
+apply immediately. Making `update-scope` apply the remaining function
+configuration requires the OpenTofu-on-update work described above.
+
 ### Resource Naming
 
 | Resource | Format | Example |
@@ -480,29 +592,41 @@ We use **three types of tests** to ensure quality at different levels:
 
 | Test Type | What it Tests | Location | Command |
 |-----------|---------------|----------|---------|
-| **Unit Tests (BATS)** | Bash scripts (build_context, scope scripts, deployment scripts) | `lambda/tests/scripts/` | `make -C testing test-unit` |
-| **Tofu Tests** | Terraform modules (IAM, Lambda, API Gateway, ALB, Route53) | `lambda/deployment/*/modules/*.tftest.hcl` | `make -C testing test-tofu` |
-| **Integration Tests** | Full workflow execution with mocked AWS | `lambda/tests/integration/` | `make -C testing test-integration` |
+| **Unit Tests (BATS)** | Bash scripts (build_context, scope scripts, deployment scripts) | `lambda/scope/tests/scripts/`, `lambda/deployment/tests/scripts/` | `make -C testing test-unit` |
+| **Tofu Tests** | Terraform modules (IAM, Lambda, API Gateway, ALB, Route53) | `lambda/scope/tofu/*/modules/*.tftest.hcl` | `make -C testing test-tofu` |
 
 ### Unit Tests (BATS)
 
 Test bash scripts in isolation using mocked AWS CLI and nullplatform API commands.
 
 **Example test files:**
-- `tests/scripts/build_context.bats` - Deployment context extraction
-- `tests/scripts/create_iam_role.bats` - IAM role creation
-- `tests/scripts/update_alias_weights.bats` - Traffic splitting logic
+- `scope/tests/scripts/scope_build_context.bats` - Scope context extraction
+- `scope/tests/scripts/sync_invoke_permissions.bats` - External invoke permission reconciliation
+- `deployment/tests/scripts/update_alias_weights.bats` - Traffic splitting logic
+
+Two mocking styles live in `scope/tests/scripts/helpers/`:
+
+- `test_helper.bash` — a sequential queue that answers every AWS call in order.
+  Fine for a script that makes one or two calls.
+- `aws_cli_mock.bash` — keys responses by `<service> <subcommand>` and records
+  every invocation. Use it for scripts that branch on what AWS returns, and to
+  assert on calls that must *not* happen.
+
+**Scripts that use `return` instead of `exit`** — the workflow engine sources
+them — must be tested with `run bash -c "source '<script>'"`. Running them with
+`run bash <script>` makes `return` a warning that does not stop the script, so
+every failure assertion silently passes.
 
 ### Tofu Tests (OpenTofu)
 
 Test Terraform modules using `tofu test` with mock providers.
 
 **Example test files:**
-- `deployment/iam/modules/iam.tftest.hcl`
-- `deployment/compute/lambda/modules/lambda.tftest.hcl`
-- `deployment/networking/api_gateway/modules/api_gateway.tftest.hcl`
-- `deployment/networking/alb/modules/alb.tftest.hcl`
-- `deployment/dns/route53/modules/route53.tftest.hcl`
+- `scope/tofu/iam/modules/iam.tftest.hcl`
+- `scope/tofu/compute/lambda/modules/lambda.tftest.hcl`
+- `scope/tofu/networking/api_gateway/modules/api_gateway.tftest.hcl`
+- `scope/tofu/networking/alb/modules/alb.tftest.hcl`
+- `scope/tofu/dns/route53/modules/route53.tftest.hcl`
 
 ### Running Tests
 
@@ -513,15 +637,10 @@ make -C testing test-all
 # Run specific test types
 make -C testing test-unit              # BATS unit tests
 make -C testing test-tofu              # OpenTofu module tests
-make -C testing test-integration       # Full workflow integration tests
 
 # Run tests for this module only
 make -C testing test-unit MODULE=lambda
 make -C testing test-tofu MODULE=lambda
-make -C testing test-integration MODULE=lambda
-
-# Verbose output (integration only)
-make -C testing test-integration VERBOSE=1
 ```
 
 ---