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

map_custom_action had no case for it, so the workflow was unreachable.
---
 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 3f71a3ecb07453511e95009a23b501a5ee2cf16b Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:58:36 -0500
Subject: [PATCH 02/21] 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. Adds run_sourced to the
shared helper, and lowercases log levels with tr since ${level,,} aborts
on bash 3.2.
---
 .../tests/scripts/cleanup_new_version.bats    |  2 +-
 .../tests/scripts/cleanup_old_version.bats    |  2 +-
 .../tests/scripts/helpers/test_helper.bash    |  8 +-
 .../tests/scripts/merge_iam_policies.bats     |  8 +-
 .../tests/scripts/rollback_alias.bats         | 10 +--
 .../tests/scripts/store_nrn_metadata.bats     |  4 +-
 .../sync_parameters_to_secrets_manager.bats   |  2 +-
 .../tests/scripts/update_alias_full.bats      |  6 +-
 .../tests/scripts/update_alias_weights.bats   | 16 ++--
 .../scripts/wait_provisioned_concurrency.bats | 20 +++--
 .../tests/scripts/helpers/aws_cli_mock.bash   | 77 +++++++++++++++++++
 .../tests/scripts/helpers/test_helper.bash    |  8 +-
 .../tests/scripts/scope_build_context.bats    | 10 +--
 lambda/utils/log                              |  6 +-
 14 files changed, 139 insertions(+), 40 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..c92e5d2 100644
--- a/lambda/deployment/tests/scripts/cleanup_new_version.bats
+++ b/lambda/deployment/tests/scripts/cleanup_new_version.bats
@@ -23,7 +23,7 @@ teardown() {
   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..2c59bba 100644
--- a/lambda/deployment/tests/scripts/cleanup_old_version.bats
+++ b/lambda/deployment/tests/scripts/cleanup_old_version.bats
@@ -57,7 +57,7 @@ OUTERSCRIPT
 @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/helpers/test_helper.bash b/lambda/deployment/tests/scripts/helpers/test_helper.bash
index a916be5..6e3ff6b 100755
--- a/lambda/deployment/tests/scripts/helpers/test_helper.bash
+++ b/lambda/deployment/tests/scripts/helpers/test_helper.bash
@@ -312,10 +312,16 @@ assert_output_not_contains() {
   fi
 }
 
+# Run a script the way the workflow engine does. These scripts use `return` as
+# their exit path, which `bash <script>` turns into a warning instead of an exit.
+run_sourced() {
+  run bash -c "source '${1:-$SCRIPT}'"
+}
+
 # Export all functions for use in tests
 export -f mock_aws mock_aws_error aws assert_aws_called assert_aws_called_with assert_aws_not_called get_aws_call get_aws_call_count reset_aws_mocks
 export -f mock_np mock_np_error np assert_np_called get_np_call get_np_call_count reset_np_mocks
 export -f assert_json_path_equal assert_json_has_key assert_json_array_length
 export -f setup_test_env teardown_test_env
-export -f run_script
+export -f run_script run_sourced
 export -f assert_success assert_failure assert_line assert_output_contains assert_output_not_contains
diff --git a/lambda/deployment/tests/scripts/merge_iam_policies.bats b/lambda/deployment/tests/scripts/merge_iam_policies.bats
index fae9d86..bf52bf3 100644
--- a/lambda/deployment/tests/scripts/merge_iam_policies.bats
+++ b/lambda/deployment/tests/scripts/merge_iam_policies.bats
@@ -103,7 +103,7 @@ OUTERSCRIPT
   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 +120,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 +137,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 +223,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..7ba74bc 100644
--- a/lambda/deployment/tests/scripts/rollback_alias.bats
+++ b/lambda/deployment/tests/scripts/rollback_alias.bats
@@ -70,7 +70,7 @@ OUTERSCRIPT
 @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 +86,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 +102,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 +115,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 +192,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..02d3cb8 100644
--- a/lambda/deployment/tests/scripts/store_nrn_metadata.bats
+++ b/lambda/deployment/tests/scripts/store_nrn_metadata.bats
@@ -56,7 +56,7 @@ OUTERSCRIPT
 @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 +112,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..70864e6 100644
--- a/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats
+++ b/lambda/deployment/tests/scripts/sync_parameters_to_secrets_manager.bats
@@ -144,7 +144,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..0b1fea5 100644
--- a/lambda/deployment/tests/scripts/update_alias_full.bats
+++ b/lambda/deployment/tests/scripts/update_alias_full.bats
@@ -51,7 +51,7 @@ SCRIPT
   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 +64,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 +162,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..0b01d54 100644
--- a/lambda/deployment/tests/scripts/update_alias_weights.bats
+++ b/lambda/deployment/tests/scripts/update_alias_weights.bats
@@ -78,7 +78,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 +91,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 +105,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 +122,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -136,7 +136,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -150,7 +150,7 @@ SCRIPT
   create_aws_sequential_mock '{"FunctionVersion": "1", "Name": "main"}'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -266,7 +266,7 @@ SCRIPT
   create_aws_error_mock "ResourceNotFoundException: Function not found"
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
 }
@@ -280,7 +280,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..4ccd86b 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() {
@@ -93,7 +99,7 @@ SCRIPT
   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 +113,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 +128,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 +202,7 @@ SCRIPT
   }'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_success
   assert_output_contains "Provisioned concurrency is READY"
@@ -217,7 +223,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 +246,7 @@ SCRIPT
   }'
 
   unset -f aws
-  run bash "$SCRIPT"
+  run_sourced "$SCRIPT"
 
   assert_failure
   assert_output_contains "Provisioned concurrency allocation FAILED"
@@ -359,7 +365,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/helpers/test_helper.bash b/lambda/scope/tests/scripts/helpers/test_helper.bash
index a916be5..6e3ff6b 100755
--- a/lambda/scope/tests/scripts/helpers/test_helper.bash
+++ b/lambda/scope/tests/scripts/helpers/test_helper.bash
@@ -312,10 +312,16 @@ assert_output_not_contains() {
   fi
 }
 
+# Run a script the way the workflow engine does. These scripts use `return` as
+# their exit path, which `bash <script>` turns into a warning instead of an exit.
+run_sourced() {
+  run bash -c "source '${1:-$SCRIPT}'"
+}
+
 # Export all functions for use in tests
 export -f mock_aws mock_aws_error aws assert_aws_called assert_aws_called_with assert_aws_not_called get_aws_call get_aws_call_count reset_aws_mocks
 export -f mock_np mock_np_error np assert_np_called get_np_call get_np_call_count reset_np_mocks
 export -f assert_json_path_equal assert_json_has_key assert_json_array_length
 export -f setup_test_env teardown_test_env
-export -f run_script
+export -f run_script run_sourced
 export -f assert_success assert_failure assert_line assert_output_contains assert_output_not_contains
diff --git a/lambda/scope/tests/scripts/scope_build_context.bats b/lambda/scope/tests/scripts/scope_build_context.bats
index 08d2b09..baadf01 100644
--- a/lambda/scope/tests/scripts/scope_build_context.bats
+++ b/lambda/scope/tests/scripts/scope_build_context.bats
@@ -27,7 +27,7 @@ teardown() {
 @test "scope/build_context: fails when CONTEXT is not set" {
   unset CONTEXT
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced "$LAMBDA_DIR/scope/build_context"
 
   assert_failure
   assert_output_contains "CONTEXT variable is not set or empty"
@@ -38,7 +38,7 @@ teardown() {
 @test "scope/build_context: fails when CONTEXT is empty string" {
   export CONTEXT=""
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced "$LAMBDA_DIR/scope/build_context"
 
   assert_failure
   assert_output_contains "CONTEXT variable is not set or empty"
@@ -47,7 +47,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 "$LAMBDA_DIR/scope/build_context"
 
   assert_failure
   assert_output_contains "Failed to extract scope ID from CONTEXT"
@@ -58,7 +58,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 "$LAMBDA_DIR/scope/build_context"
 
   assert_failure
   assert_output_contains "Failed to extract scope ID from CONTEXT"
@@ -136,7 +136,7 @@ teardown() {
   export NP_OUTPUT_DIR="$(mktemp -d)"
   _TEST_CLEANUP_DIRS+=("$NP_OUTPUT_DIR")
 
-  run bash "$LAMBDA_DIR/scope/build_context"
+  run_sourced "$LAMBDA_DIR/scope/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 713f49f42ffa3a141ef75a38b5544d4ed431d405 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:58:36 -0500
Subject: [PATCH 03/21] 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.
---
 .../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 |  77 ++++++++
 .../tests/scripts/sync_dead_letter_queue.bats | 179 +++++++++++++++++
 .../scripts/sync_invoke_permissions.bats      | 181 ++++++++++++++++++
 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, 913 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..a77e35e
--- /dev/null
+++ b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
@@ -0,0 +1,77 @@
+#!/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"
+}
+
+@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..5a4ab4a
--- /dev/null
+++ b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
@@ -0,0 +1,179 @@
+#!/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"
+}
+
+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..fcbff1b
--- /dev/null
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -0,0 +1,181 @@
+#!/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"
+}
+
+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 e60501137f5305825b1aa830dfb7ee8cc560b96f Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:58:36 -0500
Subject: [PATCH 04/21] 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.
---
 lambda/scope/scripts/store_nrn_metadata       |  78 ++++++--
 .../tests/scripts/store_nrn_metadata.bats     | 172 ++++++++++++++++++
 .../tofu/compute/lambda/modules/locals.tf     |   1 -
 .../tofu/compute/lambda/modules/outputs.tf    |   5 -
 lambda/scope/tofu/do_tofu                     |  21 +++
 5 files changed, 257 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..6bbb7e1
--- /dev/null
+++ b/lambda/scope/tests/scripts/store_nrn_metadata.bats
@@ -0,0 +1,172 @@
+#!/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"
+}
+
+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 bed7201479cc5f51b7615a92dbb5fc1b958cddc8 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 08:58:36 -0500
Subject: [PATCH 05/21] docs(lambda): document event-driven scopes

Also fixes a stale capability table and test paths.
---
 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
 ```
 
 ---

From 931c3f0e9087145264adb81df1cbbbe3271ea380 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:11:51 -0500
Subject: [PATCH 06/21] fix(lambda): harden invoke permission reconciliation

Compare .Principal.AWS too, or an account principal churns remove+add on
every run. Fail on a get-policy error instead of treating it as an empty
policy. Restore the previous statement when a refresh add fails.
---
 lambda/scope/scripts/sync_invoke_permissions  | 47 +++++++++++++++----
 .../scripts/sync_invoke_permissions.bats      | 38 +++++++++++++++
 2 files changed, 77 insertions(+), 8 deletions(-)

diff --git a/lambda/scope/scripts/sync_invoke_permissions b/lambda/scope/scripts/sync_invoke_permissions
index cf337b2..5846813 100755
--- a/lambda/scope/scripts/sync_invoke_permissions
+++ b/lambda/scope/scripts/sync_invoke_permissions
@@ -32,18 +32,32 @@ 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 \
+# Only "no policy yet" may be treated as empty. Swallowing every error would
+# make an AccessDenied look like a fresh function: nothing gets pruned, and
+# every add-permission then fails with ResourceConflictException.
+if 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
+  --output text 2>&1); then
+  if [ -z "$policy_json" ] || [ "$policy_json" = "None" ]; then
+    current_statements="[]"
+  else
+    current_statements=$(echo "$policy_json" | jq -c '.Statement // []')
+  fi
+elif [[ "$policy_json" == *ResourceNotFoundException* ]]; then
+  log debug "   ⏭️  No resource policy yet on $LAMBDA_FUNCTION_NAME:$invoke_alias"
   current_statements="[]"
 else
-  current_statements=$(echo "$policy_json" | jq -c '.Statement // []')
+  echo "❌ Failed to read the resource policy of '$LAMBDA_FUNCTION_NAME'" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - Permission denied (missing lambda:GetPolicy)" >&2
+  echo "   - Throttling, or the '$invoke_alias' alias does not exist" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Check the assume role has lambda:GetPolicy on the function" >&2
+  echo "   - Run diagnose-scope to confirm the function and alias are healthy" >&2
+  echo "   📋 AWS error: $policy_json" >&2
+  return 1
 fi
 
 managed_sids=$(echo "$current_statements" | jq -r --arg p "$NP_INVOKE_SID_PREFIX" \
@@ -119,7 +133,7 @@ while IFS= read -r perm; do
   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_principal=$(echo "$existing" | jq -r '.Principal | if type == "string" then . else (.Service // .AWS // tostring) end')
     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" // ""')
@@ -143,8 +157,10 @@ while IFS= read -r perm; do
       echo "   📋 AWS error: $aws_output" >&2
       return 1
     fi
+    replaced="$existing"
   else
     log info "   📝 Adding permission: $sid ($principal)"
+    replaced=""
   fi
 
   add_args=(--function-name "$LAMBDA_FUNCTION_NAME"
@@ -156,6 +172,21 @@ while IFS= read -r perm; do
   [ -n "$source_account" ] && add_args+=(--source-account "$source_account")
 
   if ! aws_output=$(aws lambda add-permission "${add_args[@]}" 2>&1); then
+    # A refresh already removed the old statement. Put it back, or a typo in the
+    # config would silently break a trigger that was working a moment ago.
+    if [ -n "$replaced" ]; then
+      log warn "   ⚠️  Restoring the previous $sid statement after the failed update"
+      restore_args=(--function-name "$LAMBDA_FUNCTION_NAME"
+                    --qualifier "$invoke_alias"
+                    --statement-id "$sid"
+                    --action "$cur_action"
+                    --principal "$cur_principal")
+      [ -n "$cur_source_arn" ] && restore_args+=(--source-arn "$cur_source_arn")
+      [ -n "$cur_source_account" ] && restore_args+=(--source-account "$cur_source_account")
+      aws lambda add-permission "${restore_args[@]}" >/dev/null 2>&1 \
+        || log warn "   ⚠️  Could not restore $sid — the trigger is left without a grant"
+    fi
+
     echo "❌ Failed to add invoke permission '$sid' to '$LAMBDA_FUNCTION_NAME'" >&2
     echo "💡 Possible causes:" >&2
     echo "   - Permission denied (missing lambda:AddPermission)" >&2
diff --git a/lambda/scope/tests/scripts/sync_invoke_permissions.bats b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
index fcbff1b..a0fe5b2 100644
--- a/lambda/scope/tests/scripts/sync_invoke_permissions.bats
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -179,3 +179,41 @@ with_policy() {
   assert_failure
   assert_output_contains "Failed to add invoke permission"
 }
+
+# principal is free text in the spec, so AWS may store {"AWS": ...} rather than
+# {"Service": ...}. Reading only .Principal.Service made every run churn the
+# statement: remove + add on something that never changed.
+@test "sync_invoke_permissions: is idempotent for an account principal" {
+  context_with '[{"statement_id":"cross-account","principal":"arn:aws:iam::111122223333:role/caller"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-cross-account","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::111122223333:role/caller"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "remove-permission"
+  assert_aws_cli_not_called "add-permission"
+}
+
+@test "sync_invoke_permissions: fails instead of pruning when the policy cannot be read" {
+  context_with '[]'
+  aws_mock_response "lambda get-policy" 254 "AccessDeniedException: not authorized to perform lambda:GetPolicy"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Failed to read the resource policy"
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: restores the previous statement when the update fails" {
+  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"}}}]}'
+  aws_mock_response "lambda add-permission" 254 "InvalidParameterValueException"
+
+  run_sourced
+
+  assert_failure
+  # The old grant was working a moment ago; it must not be left removed.
+  assert_aws_cli_called "--source-arn arn:aws:events:us-east-1:111122223333:rule/OLD"
+  assert_output_contains "Restoring the previous"
+}

From b42971fa8aa023afeaab8bf3aae07a3e7d8ccb47 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:11:51 -0500
Subject: [PATCH 07/21] fix(lambda): scope the DLQ policy name and check the
 waiter

A dedicated execution role can be shared between scopes, so an unscoped
policy name let one scope overwrite or delete another's grant. The
discarded waiter status also reported success on a failed update.
---
 .../scripts/cleanup_role_inline_policies      |  9 ++++-
 lambda/scope/scripts/sync_dead_letter_queue   | 38 +++++++++++++++++--
 .../scripts/cleanup_role_inline_policies.bats |  3 +-
 .../tests/scripts/sync_dead_letter_queue.bats | 37 +++++++++++++++++-
 4 files changed, 81 insertions(+), 6 deletions(-)

diff --git a/lambda/scope/scripts/cleanup_role_inline_policies b/lambda/scope/scripts/cleanup_role_inline_policies
index 1d99f08..9901293 100755
--- a/lambda/scope/scripts/cleanup_role_inline_policies
+++ b/lambda/scope/scripts/cleanup_role_inline_policies
@@ -7,7 +7,9 @@
 source "$SERVICE_PATH/utils/get_config_value"
 source "$SERVICE_PATH/utils/log"
 
-SCOPE_INLINE_POLICIES=("np-lambda-dlq")
+# Must match the names sync_dead_letter_queue writes (scoped by id, since a
+# dedicated execution role can be shared between scopes).
+SCOPE_INLINE_POLICIES=("np-lambda-dlq-${SCOPE_ID:-}")
 
 log info "🔍 Cleaning up scope-managed inline role policies..."
 
@@ -16,6 +18,11 @@ if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; t
   return 0
 fi
 
+if [ -z "${SCOPE_ID:-}" ] || [ "$SCOPE_ID" = "null" ]; then
+  log debug "   ⏭️  SCOPE_ID not set — cannot resolve the scoped policy names"
+  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 \
diff --git a/lambda/scope/scripts/sync_dead_letter_queue b/lambda/scope/scripts/sync_dead_letter_queue
index e8dd919..dda6bc2 100755
--- a/lambda/scope/scripts/sync_dead_letter_queue
+++ b/lambda/scope/scripts/sync_dead_letter_queue
@@ -6,7 +6,25 @@
 
 source "$SERVICE_PATH/utils/log"
 
-DLQ_POLICY_NAME="np-lambda-dlq"
+wait_for_function_update() {
+  if aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  local last_status
+  last_status=$(aws lambda get-function-configuration \
+    --function-name "$LAMBDA_FUNCTION_NAME" \
+    --query 'LastUpdateStatus' --output text 2>/dev/null || echo "Unknown")
+
+  echo "❌ The dead letter queue update did not complete (status: $last_status)" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - The target queue or topic is in another region or does not exist" >&2
+  echo "   - A concurrent deployment is updating the same function" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Check LastUpdateStatusReason on the function" >&2
+  echo "   - Wait for the running deployment to finish and re-run the action" >&2
+  return 1
+}
 
 log info "🔍 Reconciling function dead letter queue..."
 
@@ -21,6 +39,20 @@ if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; t
   return 1
 fi
 
+if [ -z "${SCOPE_ID:-}" ] || [ "$SCOPE_ID" = "null" ]; then
+  echo "❌ SCOPE_ID is required but not set" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - The step was added to the workflow without declaring SCOPE_ID as an output" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Verify SCOPE_ID is listed in the build_context step outputs" >&2
+  return 1
+fi
+
+# Scoped by id: a dedicated execution role can be shared between scopes (its
+# name template need not include the scope), and an unscoped policy name would
+# let one scope overwrite or delete another's grant.
+DLQ_POLICY_NAME="np-lambda-dlq-${SCOPE_ID}"
+
 dlq_target_arn=$(echo "$CONTEXT" | jq -r '.scope.capabilities.dead_letter_target_arn // ""')
 [ "$dlq_target_arn" = "null" ] && dlq_target_arn=""
 
@@ -66,7 +98,7 @@ if [ -z "$dlq_target_arn" ]; then
       echo "   📋 AWS error: $aws_output" >&2
       return 1
     fi
-    aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" 2>&1
+    wait_for_function_update || return 1
   else
     log debug "   ⏭️  No dead letter queue configured — nothing to remove"
   fi
@@ -151,7 +183,7 @@ if ! aws_output=$(aws lambda update-function-configuration \
   return 1
 fi
 
-aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" 2>&1
+wait_for_function_update || return 1
 
 echo ""
 log info "✨ Dead letter queue set to $dlq_target_arn for $LAMBDA_FUNCTION_NAME"
diff --git a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
index a77e35e..fb5a180 100644
--- a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
+++ b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
@@ -19,6 +19,7 @@ setup() {
 
   export CONTEXT='{}'
   export LAMBDA_FUNCTION_NAME="my-test-function"
+  export SCOPE_ID="9001"
 }
 
 teardown() {
@@ -35,7 +36,7 @@ teardown() {
   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"
+  assert_aws_cli_called "--policy-name np-lambda-dlq-9001"
 }
 
 @test "cleanup_role_inline_policies: derives the role name when the function is already gone" {
diff --git a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
index 5a4ab4a..4f12933 100644
--- a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
+++ b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
@@ -18,6 +18,7 @@ setup() {
   setup_aws_cli_mock
 
   export LAMBDA_FUNCTION_NAME="my-test-function"
+  export SCOPE_ID="9001"
   ROLE_ARN="arn:aws:iam::111122223333:role/np-lambda-my-test-function-role"
 }
 
@@ -98,7 +99,7 @@ function_with_dlq() {
   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_aws_cli_called "--policy-name np-lambda-dlq-9001"
   assert_output_contains "Dead letter queue disabled"
 }
 
@@ -177,3 +178,37 @@ function_with_dlq() {
   assert_output_contains "Failed to grant dead letter access"
   assert_aws_cli_not_called "update-function-configuration"
 }
+
+@test "sync_dead_letter_queue: scopes the policy name so shared roles do not collide" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_success
+  # A dedicated execution role can be shared between scopes; an unscoped name
+  # would let one scope overwrite or delete another's grant.
+  assert_aws_cli_called "--policy-name np-lambda-dlq-9001"
+}
+
+@test "sync_dead_letter_queue: fails when SCOPE_ID is not set" {
+  unset SCOPE_ID
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "SCOPE_ID is required"
+}
+
+@test "sync_dead_letter_queue: fails when the update does not complete" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+  aws_mock_response "lambda wait" 255 "Waiter FunctionUpdated failed"
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "did not complete"
+}

From af6b9d0154f010dcf34a8af8a25a72066791b4e1 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:11:51 -0500
Subject: [PATCH 08/21] fix(lambda): keep NRN identity when the ALB priority is
 invalid

jq --argjson fails on a non-numeric value, blanking the whole payload
while still reporting success.
---
 lambda/scope/scripts/store_nrn_metadata            | 10 ++++++++--
 lambda/scope/tests/scripts/store_nrn_metadata.bats | 14 ++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/lambda/scope/scripts/store_nrn_metadata b/lambda/scope/scripts/store_nrn_metadata
index 4fa2e9d..fd54de1 100755
--- a/lambda/scope/scripts/store_nrn_metadata
+++ b/lambda/scope/scripts/store_nrn_metadata
@@ -71,8 +71,14 @@ 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"
+  # Validate before --argjson: invalid JSON makes jq fail and would wipe the
+  # identity keys other services read, while still reporting success.
+  if [[ "$ALB_RULE_PRIORITY" =~ ^[0-9]+$ ]]; then
+    metadata=$(echo "$metadata" | jq --argjson p "$ALB_RULE_PRIORITY" '. + {alb_rule_priority: $p}')
+    log debug "   ✅ alb_rule_priority=$ALB_RULE_PRIORITY"
+  else
+    log warn "   ⚠️  Ignoring non-numeric ALB_RULE_PRIORITY='$ALB_RULE_PRIORITY'"
+  fi
 fi
 
 if [ "$(echo "$metadata" | jq 'length')" -eq 0 ]; then
diff --git a/lambda/scope/tests/scripts/store_nrn_metadata.bats b/lambda/scope/tests/scripts/store_nrn_metadata.bats
index 6bbb7e1..df3a533 100644
--- a/lambda/scope/tests/scripts/store_nrn_metadata.bats
+++ b/lambda/scope/tests/scripts/store_nrn_metadata.bats
@@ -170,3 +170,17 @@ with_tofu_outputs() {
   assert_failure
   assert_output_contains "Failed to write NRN metadata"
 }
+
+@test "store_nrn_metadata: a bad ALB priority does not take the identity down with it" {
+  with_tofu_outputs
+  export ALB_RULE_PRIORITY="not-a-number"
+
+  run_sourced
+
+  assert_success
+  # jq --argjson would fail on this and blank the whole payload, dropping the
+  # keys other services read — while still reporting success.
+  assert_np_body_contains "lambda.alias_arn"
+  run bash -c "grep -qF 'alb_rule_priority' '$MOCK_BIN_DIR/np_calls'"
+  assert_failure
+}

From b77973ab31b1c64be33b04cb237b93e2a2a58d7f Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:11:51 -0500
Subject: [PATCH 09/21] docs: correct the test commands

The make targets are at the root, not under testing/.
---
 README.md | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 04e9fb3..7d70ea3 100644
--- a/README.md
+++ b/README.md
@@ -592,8 +592,8 @@ 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/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)** | Bash scripts (build_context, scope scripts, deployment scripts) | `lambda/scope/tests/scripts/`, `lambda/deployment/tests/scripts/` | `make test-unit` |
+| **Tofu Tests** | Terraform modules (IAM, Lambda, API Gateway, ALB, Route53) | `lambda/scope/tofu/*/modules/*.tftest.hcl` | `make test-tofu` |
 
 ### Unit Tests (BATS)
 
@@ -632,15 +632,19 @@ Test Terraform modules using `tofu test` with mock providers.
 
 ```bash
 # Run all tests
-make -C testing test-all
+make test-all
 
 # Run specific test types
-make -C testing test-unit              # BATS unit tests
-make -C testing test-tofu              # OpenTofu module tests
+make test-unit                         # BATS unit tests
+make test-tofu                         # OpenTofu module tests
 
 # Run tests for this module only
-make -C testing test-unit MODULE=lambda
-make -C testing test-tofu MODULE=lambda
+make test-unit MODULE=lambda
+make test-tofu MODULE=lambda
+
+# The make targets shell out to ./testing/, which is not committed. Until the
+# submodule is added, run a suite directly:
+bats lambda/scope/tests/scripts/*.bats
 ```
 
 ---

From 25ca542a7266d100b09805611b9c7419553f66da Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:40:58 -0500
Subject: [PATCH 10/21] fix(lambda): read invoke_permissions from the path the
 schema declares

providers.<category> is the provider's attributes object and triggers is a
top-level group, so the extra .lambda level resolved to null and the
feature was a silent no-op. Also fails instead of pruning when CONTEXT is
unreadable, rejects duplicate statement_ids, and skips multi-action
statements that add-permission cannot recreate.
---
 lambda/scope/scripts/sync_invoke_permissions  | 29 ++++++++++-
 .../scripts/sync_invoke_permissions.bats      | 50 ++++++++++++++++++-
 2 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/lambda/scope/scripts/sync_invoke_permissions b/lambda/scope/scripts/sync_invoke_permissions
index 5846813..9c5942d 100755
--- a/lambda/scope/scripts/sync_invoke_permissions
+++ b/lambda/scope/scripts/sync_invoke_permissions
@@ -24,9 +24,31 @@ fi
 
 invoke_alias="${LAMBDA_MAIN_ALIAS_NAME:-main}"
 
-desired=$(echo "$CONTEXT" | jq -c '.providers["scope-configurations"].lambda.triggers.invoke_permissions // []')
+if ! desired=$(echo "$CONTEXT" | jq -ce '.providers["scope-configurations"].triggers.invoke_permissions // [] | if type == "array" then . else error("not an array") end' 2>&1); then
+  echo "❌ Could not read triggers.invoke_permissions from the scope configuration" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - CONTEXT is empty or malformed, so the declared set is unknown" >&2
+  echo "   - invoke_permissions was saved as something other than a list" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Re-run the action; treating an unreadable config as empty would" >&2
+  echo "     remove every external trigger this scope has" >&2
+  echo "   📋 jq error: $desired" >&2
+  return 1
+fi
+
 desired_count=$(echo "$desired" | jq 'length')
 
+# (6) add-permission would fail later with an opaque ResourceConflictException
+duplicate_sid=$(echo "$desired" | jq -r 'group_by(.statement_id) | map(select(length > 1)) | first | first.statement_id // empty')
+if [ -n "$duplicate_sid" ]; then
+  echo "❌ Duplicate statement_id '$duplicate_sid' in invoke_permissions" >&2
+  echo "💡 Possible causes:" >&2
+  echo "   - Two entries were given the same name" >&2
+  echo "🔧 How to fix:" >&2
+  echo "   - Give every entry a distinct statement_id" >&2
+  return 1
+fi
+
 log debug "   📋 function_name=$LAMBDA_FUNCTION_NAME"
 log debug "   📋 qualifier=$invoke_alias"
 log debug "   📋 declared_permissions=$desired_count"
@@ -133,6 +155,11 @@ while IFS= read -r perm; do
   existing=$(echo "$current_statements" | jq -c --arg sid "$sid" 'map(select(.Sid == $sid)) | first // empty')
 
   if [ -n "$existing" ]; then
+    if [ "$(echo "$existing" | jq -r 'if (.Action | type) == "array" and (.Action | length) > 1 then "multi" else "single" end')" = "multi" ]; then
+      log warn "   ⚠️  Leaving $sid untouched: it grants several actions, which add-permission cannot recreate"
+      continue
+    fi
+
     cur_principal=$(echo "$existing" | jq -r '.Principal | if type == "string" then . else (.Service // .AWS // tostring) end')
     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" // ""')
diff --git a/lambda/scope/tests/scripts/sync_invoke_permissions.bats b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
index a0fe5b2..3644bf6 100644
--- a/lambda/scope/tests/scripts/sync_invoke_permissions.bats
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -27,7 +27,7 @@ teardown() {
 }
 
 context_with() {
-  export CONTEXT="{\"providers\":{\"scope-configurations\":{\"lambda\":{\"triggers\":{\"invoke_permissions\":$1}}}}}"
+  export CONTEXT="{\"providers\":{\"scope-configurations\":{\"triggers\":{\"invoke_permissions\":$1}}}}"
 }
 
 no_policy() {
@@ -217,3 +217,51 @@ with_policy() {
   assert_aws_cli_called "--source-arn arn:aws:events:us-east-1:111122223333:rule/OLD"
   assert_output_contains "Restoring the previous"
 }
+
+# providers.<category> is the provider's attributes object and `triggers` is a
+# top-level schema group. An extra nesting level made the whole feature a
+# silent no-op, and a self-built fixture could not catch it.
+@test "sync_invoke_permissions: reads the path the scope-configuration schema declares" {
+  export CONTEXT='{"providers":{"scope-configurations":{"state":{"tofu_state_bucket":"b"},"triggers":{"invoke_permissions":[{"statement_id":"apigw","principal":"apigateway.amazonaws.com"}]}}}}'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--statement-id np-ext-apigw"
+  assert_output_contains "1 declared"
+}
+
+@test "sync_invoke_permissions: does not prune when CONTEXT is unreadable" {
+  export CONTEXT=''
+  with_policy '{"Statement":[{"Sid":"np-ext-eventbridge-daily","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Could not read triggers.invoke_permissions"
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: rejects duplicate statement_ids up front" {
+  context_with '[{"statement_id":"dup","principal":"events.amazonaws.com"},{"statement_id":"dup","principal":"s3.amazonaws.com"}]'
+  no_policy
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Duplicate statement_id 'dup'"
+  assert_aws_cli_not_called "add-permission"
+}
+
+@test "sync_invoke_permissions: leaves a multi-action statement alone" {
+  context_with '[{"statement_id":"multi","principal":"events.amazonaws.com"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-multi","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":["lambda:InvokeFunction","lambda:InvokeFunctionUrl"]}]}'
+
+  run_sourced
+
+  assert_success
+  # add-permission grants one action, so restoring it would silently narrow it
+  assert_aws_cli_not_called "remove-permission"
+  assert_aws_cli_not_called "add-permission"
+}

From c8871c07cae50240201450745689300ff9eb1843 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:40:58 -0500
Subject: [PATCH 11/21] fix(lambda): clear the DLQ with TargetArn instead of an
 empty struct

An empty structure may read as "no change", which would drop the role
grant while leaving DeadLetterConfig in place.
---
 lambda/scope/scripts/sync_dead_letter_queue            | 2 +-
 lambda/scope/tests/scripts/sync_dead_letter_queue.bats | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lambda/scope/scripts/sync_dead_letter_queue b/lambda/scope/scripts/sync_dead_letter_queue
index dda6bc2..e742c69 100755
--- a/lambda/scope/scripts/sync_dead_letter_queue
+++ b/lambda/scope/scripts/sync_dead_letter_queue
@@ -87,7 +87,7 @@ if [ -z "$dlq_target_arn" ]; 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
+      --dead-letter-config '{"TargetArn":""}' 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
diff --git a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
index 4f12933..d800a32 100644
--- a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
+++ b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
@@ -97,7 +97,7 @@ function_with_dlq() {
   run_sourced
 
   assert_success
-  assert_aws_cli_called "--dead-letter-config {}"
+  assert_aws_cli_called '--dead-letter-config {"TargetArn":""}'
   assert_aws_cli_called "iam delete-role-policy"
   assert_aws_cli_called "--policy-name np-lambda-dlq-9001"
   assert_output_contains "Dead letter queue disabled"

From f8a9bacb62d0f12ab290ab908d802e85ec0d6ba4 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:40:58 -0500
Subject: [PATCH 12/21] fix(lambda): enumerate inline role policies before
 destroy

merge_iam_policies names its policies per deployment, so a static list
left them behind and DeleteRole still failed. Only this scope's policies
are removed from a shared role.
---
 .../scripts/cleanup_role_inline_policies      | 62 +++++++++++++------
 .../scripts/cleanup_role_inline_policies.bats | 55 +++++++++++++---
 2 files changed, 87 insertions(+), 30 deletions(-)

diff --git a/lambda/scope/scripts/cleanup_role_inline_policies b/lambda/scope/scripts/cleanup_role_inline_policies
index 9901293..86ef942 100755
--- a/lambda/scope/scripts/cleanup_role_inline_policies
+++ b/lambda/scope/scripts/cleanup_role_inline_policies
@@ -1,16 +1,15 @@
 #!/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.
+# IAM refuses DeleteRole while unmanaged inline policies remain. Two scripts
+# create them through the CLI: sync_dead_letter_queue (np-lambda-dlq-<scope_id>)
+# and merge_iam_policies (<name>-<deployment_id>, one per deployment), so a
+# static list would miss the latter. Best-effort: a missing role or policy is
+# the normal case.
 
 source "$SERVICE_PATH/utils/get_config_value"
 source "$SERVICE_PATH/utils/log"
 
-# Must match the names sync_dead_letter_queue writes (scoped by id, since a
-# dedicated execution role can be shared between scopes).
-SCOPE_INLINE_POLICIES=("np-lambda-dlq-${SCOPE_ID:-}")
-
 log info "🔍 Cleaning up scope-managed inline role policies..."
 
 if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; then
@@ -18,36 +17,59 @@ if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; t
   return 0
 fi
 
-if [ -z "${SCOPE_ID:-}" ] || [ "$SCOPE_ID" = "null" ]; then
-  log debug "   ⏭️  SCOPE_ID not set — cannot resolve the scoped policy names"
-  return 0
-fi
+cleanup_role_prefix=$(get_config_value \
+  --provider '.providers["scope-configurations"].lambda.execution_role_prefix' \
+  --env LAMBDA_EXECUTION_ROLE_PREFIX \
+  --default 'np-lambda-')
 
-# 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.
+# The role terraform owns, named after this function alone.
+scope_managed_role="${cleanup_role_prefix}${LAMBDA_FUNCTION_NAME}-role"
+scope_managed_role="${scope_managed_role:0:64}"
+
+# Prefer the role the function actually runs on; fall back to the derived name
+# 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}"
+  cleanup_role_name="$scope_managed_role"
 fi
 
 log debug "   📋 execution_role=$cleanup_role_name"
 
-for policy_name in "${SCOPE_INLINE_POLICIES[@]}"; do
+inline_policies=$(aws iam list-role-policies \
+  --role-name "$cleanup_role_name" \
+  --query 'PolicyNames' --output text 2>/dev/null || echo "")
+
+if [ -z "$inline_policies" ] || [ "$inline_policies" = "None" ]; then
+  log debug "   ⏭️  No inline policies on $cleanup_role_name"
+  echo ""
+  log info "✨ Inline role policies cleaned up"
+  return 0
+fi
+
+# A role named after this function is dedicated to it and is about to be
+# destroyed, so every inline policy on it can go. A shared dedicated role
+# outlives the scope, so only this scope's own policies may be touched.
+if [ "$cleanup_role_name" = "$scope_managed_role" ]; then
+  log debug "   📋 role is scope-managed — removing all inline policies"
+  policies_to_delete="$inline_policies"
+else
+  log debug "   📋 role is shared — removing only this scope's policies"
+  # --output text returns the names tab-separated
+  policies_to_delete=$(printf '%s' "$inline_policies" | tr '\t' '\n' \
+    | grep -Ex "np-lambda-dlq-${SCOPE_ID:-__unset__}" || echo "")
+fi
+
+for policy_name in $policies_to_delete; 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"
+    log warn "   ⚠️  Could not remove inline policy $policy_name from $cleanup_role_name"
   fi
 done
 
diff --git a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
index fb5a180..0bf9a49 100644
--- a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
+++ b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
@@ -20,6 +20,7 @@ setup() {
   export CONTEXT='{}'
   export LAMBDA_FUNCTION_NAME="my-test-function"
   export SCOPE_ID="9001"
+  SCOPE_ROLE="np-lambda-my-test-function-role"
 }
 
 teardown() {
@@ -27,30 +28,54 @@ teardown() {
   [ -d "$MOCK_BIN_DIR" ] && rm -rf "$MOCK_BIN_DIR"
 }
 
-@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"
+on_role() {
+  aws_mock_response "lambda get-function-configuration" 0 "arn:aws:iam::111122223333:role/$1"
+}
+
+with_inline_policies() {
+  aws_mock_response "iam list-role-policies" 0 "$1"
+}
+
+@test "cleanup_role_inline_policies: clears every policy on the scope's own role" {
+  on_role "$SCOPE_ROLE"
+  # merge_iam_policies names its policies <name>-<deployment_id>, so a static
+  # list would leave them behind and DeleteRole would fail.
+  with_inline_policies "np-lambda-dlq-9001	app-policy-4242"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--policy-name np-lambda-dlq-9001"
+  assert_aws_cli_called "--policy-name app-policy-4242"
+}
+
+@test "cleanup_role_inline_policies: touches only its own policy on a shared role" {
+  on_role "shared-lambda-role"
+  with_inline_policies "np-lambda-dlq-9001	np-lambda-dlq-7777	someone-elses-policy"
 
   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-9001"
+  # Another scope's grant and unrelated policies must survive
+  assert_aws_cli_not_called "--policy-name np-lambda-dlq-7777"
+  assert_aws_cli_not_called "--policy-name someone-elses-policy"
 }
 
-@test "cleanup_role_inline_policies: derives the role name when the function is already gone" {
+@test "cleanup_role_inline_policies: derives the role name when the function is gone" {
   aws_mock_response "lambda get-function-configuration" 254 "ResourceNotFoundException"
+  with_inline_policies "np-lambda-dlq-9001"
 
   run_sourced
 
   assert_success
-  assert_aws_cli_called "--role-name np-lambda-my-test-function-role"
+  assert_aws_cli_called "--role-name $SCOPE_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"
+  with_inline_policies "np-lambda-dlq-9001"
 
   run_sourced
 
@@ -58,9 +83,19 @@ teardown() {
   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"
+@test "cleanup_role_inline_policies: no-op when the role has no inline policies" {
+  on_role "$SCOPE_ROLE"
+  with_inline_policies ""
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "delete-role-policy"
+}
+
+@test "cleanup_role_inline_policies: a failed delete is reported, not fatal" {
+  on_role "$SCOPE_ROLE"
+  with_inline_policies "np-lambda-dlq-9001"
   aws_mock_response "iam delete-role-policy" 254 "NoSuchEntity"
 
   run_sourced

From 2401d581815c93a3702c93e7012c7afb46a0408e Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 09:40:58 -0500
Subject: [PATCH 13/21] fix(utils): normalize LOG_LEVEL too

LOG_LEVEL=DEBUG fell through to the default threshold.
---
 lambda/utils/log | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lambda/utils/log b/lambda/utils/log
index 9c32484..d6bf170 100644
--- a/lambda/utils/log
+++ b/lambda/utils/log
@@ -27,7 +27,7 @@ log() {
     *)     msg_num=1 ;;
   esac
 
-  case "${LOG_LEVEL:-info}" in
+  case "$(printf '%s' "${LOG_LEVEL:-info}" | tr '[:upper:]' '[:lower:]')" in
     debug) threshold=0 ;;
     info)  threshold=1 ;;
     warn)  threshold=2 ;;

From baa36e22805f2fc0fa8132d7dd00913226384a8f Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 12:52:27 -0500
Subject: [PATCH 14/21] fix(lambda): validate invoke permissions before
 mutating, and scope them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The provider resolves against the scope NRN, so a value set higher up was
inherited by every lambda scope below it — entries can now name the scope
they belong to. Validation also moved ahead of the prune loop: rejecting
an entry after removing the statement it replaced left a live trigger
with no grant. A bare account id principal no longer churns every run.
---
 lambda/scope/scripts/sync_invoke_permissions  | 97 ++++++++++++-------
 .../scripts/sync_invoke_permissions.bats      | 72 ++++++++++++++
 lambda/specs/scope-configuration.json.tpl     |  7 +-
 3 files changed, 139 insertions(+), 37 deletions(-)

diff --git a/lambda/scope/scripts/sync_invoke_permissions b/lambda/scope/scripts/sync_invoke_permissions
index 9c5942d..d702177 100755
--- a/lambda/scope/scripts/sync_invoke_permissions
+++ b/lambda/scope/scripts/sync_invoke_permissions
@@ -36,9 +36,22 @@ if ! desired=$(echo "$CONTEXT" | jq -ce '.providers["scope-configurations"].trig
   return 1
 fi
 
+declared_count=$(echo "$desired" | jq 'length')
+
+# Entries may name the scope they are for. Without that, a value inherited from
+# a higher NRN would grant the same principal on every lambda scope below it.
+desired=$(echo "$desired" | jq -c --arg slug "${SCOPE_SLUG:-}" --arg id "${SCOPE_ID:-}" \
+  '[ .[] | select((.scope // "") as $s | $s == "" or $s == $slug or $s == $id) ]')
+
 desired_count=$(echo "$desired" | jq 'length')
 
-# (6) add-permission would fail later with an opaque ResourceConflictException
+log debug "   📋 function_name=$LAMBDA_FUNCTION_NAME"
+log debug "   📋 qualifier=$invoke_alias"
+log debug "   📋 declared_permissions=$declared_count (for this scope: $desired_count)"
+
+# ── Validate every entry before touching AWS ──────────────────────────────────
+# Rejecting an entry after the prune loop already removed the statement it was
+# meant to replace would leave a working trigger with no grant at all.
 duplicate_sid=$(echo "$desired" | jq -r 'group_by(.statement_id) | map(select(length > 1)) | first | first.statement_id // empty')
 if [ -n "$duplicate_sid" ]; then
   echo "❌ Duplicate statement_id '$duplicate_sid' in invoke_permissions" >&2
@@ -49,9 +62,41 @@ if [ -n "$duplicate_sid" ]; then
   return 1
 fi
 
-log debug "   📋 function_name=$LAMBDA_FUNCTION_NAME"
-log debug "   📋 qualifier=$invoke_alias"
-log debug "   📋 declared_permissions=$desired_count"
+while IFS= read -r perm; do
+  [ -z "$perm" ] && continue
+
+  statement_id=$(echo "$perm" | jq -r '.statement_id // ""')
+  principal=$(echo "$perm" | jq -r '.principal // ""')
+
+  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
+
+  if [ ${#statement_id} -gt $((100 - ${#NP_INVOKE_SID_PREFIX})) ]; then
+    echo "❌ statement_id '$statement_id' is too long" >&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
+done < <(echo "$desired" | jq -c '.[]')
 
 # ── Current state ─────────────────────────────────────────────────────────────
 # Only "no policy yet" may be treated as empty. Swallowing every error would
@@ -118,38 +163,8 @@ while IFS= read -r perm; do
   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')
@@ -165,7 +180,13 @@ while IFS= read -r perm; do
     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" ] && \
+    # AWS stores a bare account id as arn:aws:iam::<id>:root
+    declared_principal="$principal"
+    if [[ "$principal" =~ ^[0-9]{12}$ ]]; then
+      declared_principal="arn:aws:iam::${principal}:root"
+    fi
+
+    if [ "$cur_principal" = "$declared_principal" ] && [ "$cur_action" = "$action" ] && \
        [ "$cur_source_arn" = "$source_arn" ] && [ "$cur_source_account" = "$source_account" ]; then
       log debug "   ⏭️  $sid already up to date"
       continue
@@ -229,4 +250,8 @@ while IFS= read -r perm; do
 done < <(echo "$desired" | jq -c '.[]')
 
 echo ""
-log info "✨ External invoke permissions reconciled ($desired_count declared)"
+if [ "$desired_count" != "$declared_count" ]; then
+  log info "✨ External invoke permissions reconciled ($desired_count of $declared_count declared apply to this scope)"
+else
+  log info "✨ External invoke permissions reconciled ($desired_count declared)"
+fi
diff --git a/lambda/scope/tests/scripts/sync_invoke_permissions.bats b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
index 3644bf6..4bb952f 100644
--- a/lambda/scope/tests/scripts/sync_invoke_permissions.bats
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -19,6 +19,8 @@ setup() {
 
   export LAMBDA_FUNCTION_NAME="my-test-function"
   export LAMBDA_MAIN_ALIAS_NAME="main"
+  export SCOPE_SLUG="my-scope"
+  export SCOPE_ID="9001"
 }
 
 teardown() {
@@ -265,3 +267,73 @@ with_policy() {
   assert_aws_cli_not_called "remove-permission"
   assert_aws_cli_not_called "add-permission"
 }
+
+# The scope-configurations provider resolves against the scope NRN, so a value
+# set at the application level is inherited by every Lambda scope beneath it.
+@test "sync_invoke_permissions: skips entries belonging to another scope" {
+  context_with '[{"statement_id":"s3-uploads","principal":"s3.amazonaws.com","scope":"other-scope"}]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "add-permission"
+  assert_output_contains "0 of 1 declared apply to this scope"
+}
+
+@test "sync_invoke_permissions: applies entries naming this scope by slug or id" {
+  context_with '[{"statement_id":"by-slug","principal":"events.amazonaws.com","scope":"my-scope"},{"statement_id":"by-id","principal":"s3.amazonaws.com","scope":"9001"}]'
+  no_policy
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--statement-id np-ext-by-slug"
+  assert_aws_cli_called "--statement-id np-ext-by-id"
+}
+
+@test "sync_invoke_permissions: an entry for another scope does not prune this scope's grants" {
+  context_with '[{"statement_id":"mine","principal":"events.amazonaws.com"},{"statement_id":"theirs","principal":"s3.amazonaws.com","scope":"other-scope"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-mine","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "remove-permission"
+}
+
+# Validation must run before the prune loop: rejecting an entry after removing
+# the statement it replaces leaves a live trigger with no grant.
+@test "sync_invoke_permissions: an invalid statement_id aborts before any removal" {
+  context_with '[{"statement_id":"eventbridge.daily","principal":"events.amazonaws.com"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-eventbridge-daily","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "Invalid statement_id"
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: a too-long statement_id aborts before any removal" {
+  long_id=$(printf 'a%.0s' $(seq 1 100))
+  context_with "[{\"statement_id\":\"$long_id\",\"principal\":\"events.amazonaws.com\"}]"
+  with_policy '{"Statement":[{"Sid":"np-ext-stale","Effect":"Allow","Principal":{"Service":"s3.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "too long"
+  assert_aws_cli_not_called "remove-permission"
+}
+
+@test "sync_invoke_permissions: is idempotent for a bare account id principal" {
+  context_with '[{"statement_id":"acct","principal":"111122223333"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-acct","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::111122223333:root"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_not_called "remove-permission"
+  assert_aws_cli_not_called "add-permission"
+}
diff --git a/lambda/specs/scope-configuration.json.tpl b/lambda/specs/scope-configuration.json.tpl
index 65117e2..59417e4 100644
--- a/lambda/specs/scope-configuration.json.tpl
+++ b/lambda/specs/scope-configuration.json.tpl
@@ -89,6 +89,11 @@
                   "title": "Action",
                   "description": "Lambda action to grant.",
                   "default": "lambda:InvokeFunction"
+                },
+                "scope": {
+                  "type": "string",
+                  "title": "Only for scope",
+                  "description": "Scope slug or id this grant belongs to. Leave empty only when the grant is meant for every Lambda scope under this NRN — a value set at the application or namespace level is inherited by all of them."
                 }
               }
             }
@@ -153,7 +158,7 @@
               "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.",
+                  "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.\n\nThis provider resolves against the scope's NRN, so a value set at the application or namespace level applies to **every** Lambda scope beneath it. Set **Only for scope** on any grant that belongs to one function.",
                   "options": { "format": "markdown" }
                 },
                 {

From fc2ff42d6a29fb438e2342fba765a3dc7cdeab2f Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 12:52:28 -0500
Subject: [PATCH 15/21] fix(lambda): report inline policies a shared role keeps

Per-deployment policy names carry no scope marker, so they cannot be
attributed there. The header claimed otherwise.
---
 .../scope/scripts/cleanup_role_inline_policies  | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/lambda/scope/scripts/cleanup_role_inline_policies b/lambda/scope/scripts/cleanup_role_inline_policies
index 86ef942..653b76f 100755
--- a/lambda/scope/scripts/cleanup_role_inline_policies
+++ b/lambda/scope/scripts/cleanup_role_inline_policies
@@ -3,9 +3,12 @@
 #
 # IAM refuses DeleteRole while unmanaged inline policies remain. Two scripts
 # create them through the CLI: sync_dead_letter_queue (np-lambda-dlq-<scope_id>)
-# and merge_iam_policies (<name>-<deployment_id>, one per deployment), so a
-# static list would miss the latter. Best-effort: a missing role or policy is
-# the normal case.
+# and merge_iam_policies (<name>-<deployment_id>, one per deployment), so the
+# scope's own role is cleared wholesale rather than from a static list.
+#
+# On a role shared with other scopes only this scope's own policies can be
+# identified, so per-deployment ones are left behind and reported. Best-effort:
+# a missing role or policy is the normal case.
 
 source "$SERVICE_PATH/utils/get_config_value"
 source "$SERVICE_PATH/utils/log"
@@ -58,6 +61,14 @@ if [ "$cleanup_role_name" = "$scope_managed_role" ]; then
   policies_to_delete="$inline_policies"
 else
   log debug "   📋 role is shared — removing only this scope's policies"
+  # Per-deployment policy names carry no scope marker, so on a shared role they
+  # cannot be attributed. Report them: they count against the role's inline
+  # policy quota and will need removing by hand.
+  leftovers=$(printf '%s' "$inline_policies" | tr '\t' '\n' \
+    | grep -vEx "np-lambda-dlq-[0-9]+" || echo "")
+  if [ -n "$leftovers" ]; then
+    log warn "   ⚠️  Left on shared role $cleanup_role_name (cannot attribute to a scope): $(echo "$leftovers" | tr '\n' ' ')"
+  fi
   # --output text returns the names tab-separated
   policies_to_delete=$(printf '%s' "$inline_policies" | tr '\t' '\n' \
     | grep -Ex "np-lambda-dlq-${SCOPE_ID:-__unset__}" || echo "")

From 18d717531792624c131acdcd2f146bd49b35ec87 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 12:52:28 -0500
Subject: [PATCH 16/21] docs(lambda): note the KMS grant an encrypted DLQ needs

Lambda also needs kms:GenerateDataKey on the key, which the scope cannot
derive from the target ARN.
---
 README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/README.md b/README.md
index 7d70ea3..91d772d 100644
--- a/README.md
+++ b/README.md
@@ -439,6 +439,12 @@ 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.
 
+> **A target encrypted with a customer-managed KMS key needs one more grant.**
+> Lambda also requires `kms:GenerateDataKey` (plus `kms:Decrypt` for SQS) on the
+> key, which the scope cannot derive from the queue or topic ARN. Add it to the
+> execution role yourself, or the delivery is denied and the event is dropped —
+> with both the `DeadLetterConfig` and the send grant looking correctly applied.
+
 > **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

From fc8b4a6624adca0838d2b9bb3173c28e6478a96a Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 13:03:56 -0500
Subject: [PATCH 17/21] docs(lambda): trim the event-driven sections

Also documents the scope filter, which was in the schema but not here.
---
 README.md | 103 +++++++++++++++++-------------------------------------
 1 file changed, 33 insertions(+), 70 deletions(-)

diff --git a/README.md b/README.md
index 91d772d..38001e9 100644
--- a/README.md
+++ b/README.md
@@ -247,33 +247,22 @@ The `service-spec.json.tpl` defines the developer-facing capabilities:
 
 ### 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.
+A function triggered by something other than its own API Gateway or ALB needs
+an invoke permission (see [External invocation](#external-invocation)) and a way
+for the trigger to find it.
 
-**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:
+`create-scope` and `update-scope` publish the function's identity to the scope's
+NRN, so an event source mapping can target the `main` alias without re-deriving
+names. Scopes created earlier are backfilled on the next `update-scope`.
 
 | 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.alias_arn` | `main` alias ARN — the event source mapping target |
 | `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
@@ -381,31 +370,19 @@ PLACEHOLDER_IMAGE_URI_DEFAULT: "123456789012.dkr.ecr.us-east-1.amazonaws.com/aws
 
 ### 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.
+Set in the **scope-configuration** provider (`triggers.invoke_permissions`) — a
+privilege grant belongs to whoever operates the account, not to the scope form.
+Dimensions are allowed, 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"
+        "source_arn": "arn:aws:events:us-east-1:111122223333:rule/daily-report",
+        "scope": "my-scope"
       }
     ]
   }
@@ -414,45 +391,33 @@ environment.
 
 | Field | Required | Notes |
 |-------|----------|-------|
-| `statement_id` | yes | Short symbolic name, `[a-zA-Z0-9_-]` only. Stored as `np-ext-<statement_id>`. |
+| `statement_id` | yes | `[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_arn` | 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`. |
+| `scope` | recommended | Scope slug or id. The provider resolves against the scope's NRN, so a value set higher up applies to every Lambda scope beneath it. |
 
-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.
+Reconciled idempotently on `create-scope` and `update-scope`. Only `np-ext-`
+statements are ever deleted, so `AllowAPIGatewayInvoke`, `AllowALBInvoke` and
+anything added out of band survive.
 
 ### 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.
-
-> **A target encrypted with a customer-managed KMS key needs one more grant.**
-> Lambda also requires `kms:GenerateDataKey` (plus `kms:Decrypt` for SQS) on the
-> key, which the scope cannot derive from the queue or topic ARN. Add it to the
-> execution role yourself, or the delivery is denied and the event is dropped —
-> with both the `DeadLetterConfig` and the send grant looking correctly applied.
-
-> **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.
+`dead_letter_target_arn` (a scope attribute) is the SQS queue or SNS topic that
+receives events whose **asynchronous** invocation failed after all retries — not
+the redrive policy of a queue the function consumes from.
+
+Setting it enables `DeadLetterConfig` and grants the execution role
+`sqs:SendMessage` or `sns:Publish` on that ARN alone; without the grant Lambda
+drops the event silently. Clearing it reverts both. A target encrypted with a
+customer-managed KMS key also needs `kms:GenerateDataKey` (plus `kms:Decrypt`
+for SQS) on the key, which the scope cannot derive — add it yourself.
+
+> **Why these two are not in Terraform.** The scope's tofu state holds the
+> *placeholder* function while deployments mutate the real one via the AWS CLI,
+> so an `apply` on update would roll the function back. Both are reconciled by
+> AWS CLI scripts instead, touching only the field they own.
 
 ### What `update-scope` reconciles
 
@@ -463,9 +428,7 @@ both.
 | `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.
+`reserved_concurrency` and `provisioned_concurrency` have their own actions.
 
 ### Resource Naming
 

From b679a9a958393a0ac7f3af30c025b43a9a6845cb Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 13:09:25 -0500
Subject: [PATCH 18/21] fix(lambda): pass SCOPE_SLUG to update-scope

Without it a slug-scoped entry was filtered out and then pruned,
revoking a live trigger. The script now refuses to run without it.
---
 lambda/scope/scripts/sync_invoke_permissions       | 14 ++++++++++++++
 .../tests/scripts/sync_invoke_permissions.bats     | 14 ++++++++++++++
 lambda/scope/workflows/update.yaml                 |  2 ++
 3 files changed, 30 insertions(+)

diff --git a/lambda/scope/scripts/sync_invoke_permissions b/lambda/scope/scripts/sync_invoke_permissions
index d702177..975f602 100755
--- a/lambda/scope/scripts/sync_invoke_permissions
+++ b/lambda/scope/scripts/sync_invoke_permissions
@@ -22,6 +22,20 @@ if [ -z "${LAMBDA_FUNCTION_NAME:-}" ] || [ "$LAMBDA_FUNCTION_NAME" = "null" ]; t
   return 1
 fi
 
+# Entries may name their scope by slug or id. Missing either would filter such
+# an entry out and then prune the statement it created — revoking a live
+# trigger. Fail instead.
+for required in SCOPE_ID SCOPE_SLUG; do
+  if [ -z "${!required:-}" ] || [ "${!required}" = "null" ]; then
+    echo "❌ $required is required but not set" >&2
+    echo "💡 Possible causes:" >&2
+    echo "   - The step was added to a workflow without declaring $required as a build_context output" >&2
+    echo "🔧 How to fix:" >&2
+    echo "   - Add $required to the build_context step outputs of that workflow" >&2
+    return 1
+  fi
+done
+
 invoke_alias="${LAMBDA_MAIN_ALIAS_NAME:-main}"
 
 if ! desired=$(echo "$CONTEXT" | jq -ce '.providers["scope-configurations"].triggers.invoke_permissions // [] | if type == "array" then . else error("not an array") end' 2>&1); then
diff --git a/lambda/scope/tests/scripts/sync_invoke_permissions.bats b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
index 4bb952f..ae3dc06 100644
--- a/lambda/scope/tests/scripts/sync_invoke_permissions.bats
+++ b/lambda/scope/tests/scripts/sync_invoke_permissions.bats
@@ -337,3 +337,17 @@ with_policy() {
   assert_aws_cli_not_called "remove-permission"
   assert_aws_cli_not_called "add-permission"
 }
+
+# SCOPE_SLUG has to reach the script, or a slug-scoped entry is filtered out and
+# then pruned — revoking a live trigger while reporting success.
+@test "sync_invoke_permissions: fails when SCOPE_SLUG is not set" {
+  unset SCOPE_SLUG
+  context_with '[{"statement_id":"mine","principal":"events.amazonaws.com","scope":"my-scope"}]'
+  with_policy '{"Statement":[{"Sid":"np-ext-mine","Effect":"Allow","Principal":{"Service":"events.amazonaws.com"},"Action":"lambda:InvokeFunction"}]}'
+
+  run_sourced
+
+  assert_failure
+  assert_output_contains "SCOPE_SLUG is required"
+  assert_aws_cli_not_called "remove-permission"
+}
diff --git a/lambda/scope/workflows/update.yaml b/lambda/scope/workflows/update.yaml
index 7ab2565..8ed94c5 100644
--- a/lambda/scope/workflows/update.yaml
+++ b/lambda/scope/workflows/update.yaml
@@ -17,6 +17,8 @@ steps:
     output:
       - name: SCOPE_ID
         type: environment
+      - name: SCOPE_SLUG
+        type: environment
       - name: SCOPE_NRN
         type: environment
       - name: LAMBDA_FUNCTION_NAME

From 7e62b7af7825cafe6e0369baa360ee6fb23f7fed Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 13:09:25 -0500
Subject: [PATCH 19/21] fix(lambda): keep terraform-managed policies on cleanup

A failed destroy leaves the function running; stripping them cost it
logs, ECR pulls and Secrets Manager access with nothing to restore them.
---
 .../scripts/cleanup_role_inline_policies      | 25 ++++++++++++-------
 .../scripts/cleanup_role_inline_policies.bats | 17 ++++++++++++-
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/lambda/scope/scripts/cleanup_role_inline_policies b/lambda/scope/scripts/cleanup_role_inline_policies
index 653b76f..92c3342 100755
--- a/lambda/scope/scripts/cleanup_role_inline_policies
+++ b/lambda/scope/scripts/cleanup_role_inline_policies
@@ -1,14 +1,13 @@
 #!/bin/bash
 # Drop the inline policies this scope writes outside terraform, before destroy.
 #
-# IAM refuses DeleteRole while unmanaged inline policies remain. Two scripts
-# create them through the CLI: sync_dead_letter_queue (np-lambda-dlq-<scope_id>)
-# and merge_iam_policies (<name>-<deployment_id>, one per deployment), so the
-# scope's own role is cleared wholesale rather than from a static list.
+# IAM refuses DeleteRole while unmanaged inline policies remain; sync_dead_letter_queue
+# and merge_iam_policies both write some through the CLI. Terraform's own are left
+# alone — a failed destroy leaves the function running, and stripping them would
+# cost it logs, ECR and Secrets Manager access with nothing to restore them.
 #
-# On a role shared with other scopes only this scope's own policies can be
-# identified, so per-deployment ones are left behind and reported. Best-effort:
-# a missing role or policy is the normal case.
+# On a shared role only this scope's policies can be identified; the rest are
+# reported. Best-effort: a missing role or policy is the normal case.
 
 source "$SERVICE_PATH/utils/get_config_value"
 source "$SERVICE_PATH/utils/log"
@@ -56,9 +55,17 @@ fi
 # A role named after this function is dedicated to it and is about to be
 # destroyed, so every inline policy on it can go. A shared dedicated role
 # outlives the scope, so only this scope's own policies may be touched.
+# Names terraform owns on this role (iam/modules/main.tf), plus any custom ones
+# it attaches from the scope configuration.
+tf_managed="cloudwatch-logs
+ecr-image-pull
+secrets-manager-parameters-read
+$(echo "${CONTEXT:-\{\}}" | jq -r '.providers["scope-configurations"].lambda.role_policies // [] | if type == "array" then (.[] | .name // empty) else empty end' 2>/dev/null)"
+
 if [ "$cleanup_role_name" = "$scope_managed_role" ]; then
-  log debug "   📋 role is scope-managed — removing all inline policies"
-  policies_to_delete="$inline_policies"
+  log debug "   📋 role is scope-managed — removing every policy terraform does not own"
+  policies_to_delete=$(printf '%s' "$inline_policies" | tr '\t' '\n' \
+    | grep -vxF -f <(printf '%s\n' "$tf_managed") || echo "")
 else
   log debug "   📋 role is shared — removing only this scope's policies"
   # Per-deployment policy names carry no scope marker, so on a shared role they
diff --git a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
index 0bf9a49..1ac2e1c 100644
--- a/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
+++ b/lambda/scope/tests/scripts/cleanup_role_inline_policies.bats
@@ -36,7 +36,7 @@ with_inline_policies() {
   aws_mock_response "iam list-role-policies" 0 "$1"
 }
 
-@test "cleanup_role_inline_policies: clears every policy on the scope's own role" {
+@test "cleanup_role_inline_policies: clears the out-of-band policies on the scope's own role" {
   on_role "$SCOPE_ROLE"
   # merge_iam_policies names its policies <name>-<deployment_id>, so a static
   # list would leave them behind and DeleteRole would fail.
@@ -49,6 +49,21 @@ with_inline_policies() {
   assert_aws_cli_called "--policy-name app-policy-4242"
 }
 
+@test "cleanup_role_inline_policies: leaves terraform's own policies in place" {
+  on_role "$SCOPE_ROLE"
+  with_inline_policies "cloudwatch-logs	ecr-image-pull	secrets-manager-parameters-read	np-lambda-dlq-9001"
+
+  run_sourced
+
+  assert_success
+  assert_aws_cli_called "--policy-name np-lambda-dlq-9001"
+  # A destroy can fail and leave the function running; stripping these would
+  # cost it logs, ECR pulls and Secrets Manager access.
+  assert_aws_cli_not_called "--policy-name cloudwatch-logs"
+  assert_aws_cli_not_called "--policy-name ecr-image-pull"
+  assert_aws_cli_not_called "--policy-name secrets-manager-parameters-read"
+}
+
 @test "cleanup_role_inline_policies: touches only its own policy on a shared role" {
   on_role "shared-lambda-role"
   with_inline_policies "np-lambda-dlq-9001	np-lambda-dlq-7777	someone-elses-policy"

From 66adca22ac1f33bbd470557f5e3571bf3b7f7c0f Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 13:09:25 -0500
Subject: [PATCH 20/21] fix(lambda): revert the DLQ grant when enabling fails

The grant is written first by design, so a failed config update left the
role with send access to an arbitrary ARN and no DLQ enabled.
---
 lambda/scope/scripts/sync_dead_letter_queue   | 36 ++++++++++++++++---
 .../tests/scripts/sync_dead_letter_queue.bats | 24 +++++++++++++
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/lambda/scope/scripts/sync_dead_letter_queue b/lambda/scope/scripts/sync_dead_letter_queue
index e742c69..6734627 100755
--- a/lambda/scope/scripts/sync_dead_letter_queue
+++ b/lambda/scope/scripts/sync_dead_letter_queue
@@ -6,6 +6,34 @@
 
 source "$SERVICE_PATH/utils/log"
 
+# The grant is written before the config update, so it has to be undone when
+# that update fails — otherwise the role keeps send access to an arbitrary,
+# possibly cross-account ARN with no DLQ ever enabled.
+revert_dlq_grant() {
+  if [ -n "${current_dlq:-}" ]; then
+    log warn "   ⚠️  Restoring the grant for the previous target $current_dlq"
+    aws iam put-role-policy \
+      --role-name "$role_name" \
+      --policy-name "$DLQ_POLICY_NAME" \
+      --policy-document "$(dlq_policy_document "$current_dlq")" >/dev/null 2>&1 || true
+  else
+    log warn "   ⚠️  Removing the grant written for the failed update"
+    aws iam delete-role-policy \
+      --role-name "$role_name" \
+      --policy-name "$DLQ_POLICY_NAME" >/dev/null 2>&1 || true
+  fi
+}
+
+dlq_policy_document() {
+  case "$1" in
+    arn:*:sqs:*) local grant="sqs:SendMessage" ;;
+    arn:*:sns:*) local grant="sns:Publish" ;;
+    *) return 1 ;;
+  esac
+  jq -n --arg action "$grant" --arg resource "$1" \
+    '{Version: "2012-10-17", Statement: [{Effect: "Allow", Action: [$action], Resource: $resource}]}'
+}
+
 wait_for_function_update() {
   if aws lambda wait function-updated --function-name "$LAMBDA_FUNCTION_NAME" >/dev/null 2>&1; then
     return 0
@@ -143,13 +171,10 @@ 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
+  --policy-document "$(dlq_policy_document "$dlq_target_arn")" 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
@@ -180,10 +205,11 @@ if ! aws_output=$(aws lambda update-function-configuration \
   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
+  revert_dlq_grant
   return 1
 fi
 
-wait_for_function_update || return 1
+wait_for_function_update || { revert_dlq_grant; return 1; }
 
 echo ""
 log info "✨ Dead letter queue set to $dlq_target_arn for $LAMBDA_FUNCTION_NAME"
diff --git a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
index d800a32..4b7e279 100644
--- a/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
+++ b/lambda/scope/tests/scripts/sync_dead_letter_queue.bats
@@ -212,3 +212,27 @@ function_with_dlq() {
   assert_failure
   assert_output_contains "did not complete"
 }
+
+@test "sync_dead_letter_queue: removes the grant when enabling fails" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:my-dlq"
+  function_with_dlq
+  aws_mock_response "lambda update-function-configuration" 254 "InvalidParameterValueException"
+
+  run_sourced
+
+  assert_failure
+  # Otherwise the role keeps send access to an arbitrary ARN with no DLQ enabled
+  assert_aws_cli_called "iam delete-role-policy"
+}
+
+@test "sync_dead_letter_queue: restores the previous grant when a change fails" {
+  context_with_dlq "arn:aws:sqs:us-east-1:111122223333:new-dlq"
+  function_with_dlq "arn:aws:sqs:us-east-1:111122223333:old-dlq"
+  aws_mock_response "lambda update-function-configuration" 254 "InvalidParameterValueException"
+
+  run_sourced
+
+  assert_failure
+  assert_aws_cli_called "old-dlq"
+  assert_aws_cli_not_called "iam delete-role-policy"
+}

From c6ee36b7b1ab090a4940d41c3775a46e9fb0c502 Mon Sep 17 00:00:00 2001
From: Andres Morelos <andres.morelos@nullplatform.io>
Date: Wed, 2 Sep 2026 13:46:01 -0500
Subject: [PATCH 21/21] feat(install): install via the package/worker model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The agent spawns the released worker image per action instead of
git-cloning this repo. Set worker_orchestrator=false to keep the old
channel. Also pins both modules to v7.0.0 — 7.0.0 is not a tag, and the
agent association was still on v6.19.1, which has no worker support.
---
 lambda/specs/install/main.tf                  | 29 ++++++++++++++--
 lambda/specs/install/provider.tf              |  2 +-
 lambda/specs/install/terraform.tfvars.example | 14 ++++++++
 lambda/specs/install/variables.tf             | 33 +++++++++++++++++++
 4 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/lambda/specs/install/main.tf b/lambda/specs/install/main.tf
index fa37e92..61d5854 100644
--- a/lambda/specs/install/main.tf
+++ b/lambda/specs/install/main.tf
@@ -4,7 +4,7 @@
 ################################################################################
 
 module "scope_definition" {
-  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition?ref=v6.19.1"
+  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition?ref=v7.0.0"
 
   nrn        = var.nrn
   np_api_key = var.np_api_key
@@ -44,6 +44,24 @@ module "scope_definition" {
   external_logging_provider = var.external_logging_provider
 
   create_scope_configuration = true
+
+  # Worker model: publish the scope as a versioned package whose bill of
+  # materials pins the released worker image, so a scope binds to an immutable
+  # revision. lookup references the globally-published artifact instead of
+  # registering a copy. null keeps the git-clone exec behaviour.
+  package = var.worker_orchestrator ? {
+    version = var.package_version
+    slug    = var.package_slug
+    artifacts = [{
+      name   = "worker-image"
+      lookup = true
+      meta = {
+        registry   = "public.ecr.aws"
+        repository = "nullplatform/scopes/lambda"
+        digest     = var.worker_image_digest
+      }
+    }]
+  } : null
 }
 
 ################################################################################
@@ -52,7 +70,7 @@ module "scope_definition" {
 ################################################################################
 
 module "scope_definition_agent_association" {
-  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition_agent_association?ref=v6.19.1"
+  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition_agent_association?ref=v7.0.0"
 
   nrn     = var.nrn
   api_key = var.np_api_key
@@ -69,6 +87,13 @@ module "scope_definition_agent_association" {
 
   repo_path = var.repo_path
 
+  # package-exec instead of git-clone exec: the agent spawns the worker image
+  # pinned above and runs its baked entrypoint. The image lays the repo down at
+  # /app/pkg (see the Dockerfile), not the module's /app/packages/<slug> default.
+  worker_orchestrator = var.worker_orchestrator
+  package_slug        = var.worker_orchestrator ? var.package_slug : ""
+  entrypoint          = var.worker_orchestrator ? "/app/pkg/${var.service_path}/entrypoint" : ""
+
   tags_selectors = var.tags_selectors
 
   enabled_override       = var.overrides_enabled
diff --git a/lambda/specs/install/provider.tf b/lambda/specs/install/provider.tf
index ef613db..606dace 100644
--- a/lambda/specs/install/provider.tf
+++ b/lambda/specs/install/provider.tf
@@ -2,7 +2,7 @@ terraform {
   required_providers {
     nullplatform = {
       source  = "nullplatform/nullplatform"
-      version = "0.0.87, < 0.1.0"
+      version = ">= 0.0.99, < 0.1.0"
     }
     http = {
       source  = "hashicorp/http"
diff --git a/lambda/specs/install/terraform.tfvars.example b/lambda/specs/install/terraform.tfvars.example
index b5951da..a6e4da1 100644
--- a/lambda/specs/install/terraform.tfvars.example
+++ b/lambda/specs/install/terraform.tfvars.example
@@ -33,6 +33,20 @@ tags_selectors = {
 # service_spec_description = "AWS Lambda functions managed by nullplatform"
 # service_path             = "lambda"
 
+################################################################################
+# Worker model (defaults to on)
+################################################################################
+
+# Set false to keep the git-clone exec channel instead.
+# worker_orchestrator = true
+
+# Digest from the Artifact table of the release you want to run. The worker image
+# carries the scope code, so github_branch above only affects the spec templates.
+# worker_image_digest = "sha256:..."
+
+# Bump when pinning a newer image.
+# package_version = "0.0.1"
+
 ################################################################################
 # Overrides (optional — appends --overrides-path to the agent cmdline)
 ################################################################################
diff --git a/lambda/specs/install/variables.tf b/lambda/specs/install/variables.tf
index 0a1c9ba..326fdd2 100644
--- a/lambda/specs/install/variables.tf
+++ b/lambda/specs/install/variables.tf
@@ -74,6 +74,39 @@ variable "service_path" {
   default     = "lambda"
 }
 
+################################################################################
+# Worker model
+#
+# The agent spawns the released worker image per action instead of git-cloning
+# this repo. Requires a worker-orchestrator agent listening on tags_selectors,
+# allowing public.ecr.aws/nullplatform/scopes*.
+################################################################################
+
+variable "worker_orchestrator" {
+  description = "Publish the scope as a package and emit a package-exec channel. False keeps the git-clone exec channel."
+  type        = bool
+  default     = true
+}
+
+variable "package_slug" {
+  description = "Slug of the scope package"
+  type        = string
+  default     = "scopes-lambda"
+}
+
+variable "package_version" {
+  description = "Semver of the package revision to publish. Bump when pinning a newer worker image."
+  type        = string
+  default     = "0.0.1"
+}
+
+variable "worker_image_digest" {
+  description = "Digest of the worker image to pin. Taken from the Artifact table of the matching GitHub release."
+  type        = string
+  # v0.3.2
+  default = "sha256:4151e8005a6ad7de44b82411cf4f04cf197cf52d4a399e403ffdcd111e083482"
+}
+
 ################################################################################
 # Overrides
 ################################################################################