feat(runner): per-SM execution roles + DockerLambdaStrategy (closes #5, #6)

[royassis]

Implements the two open enhancement issues. No external consumers, so the breaking API change in #5 is acceptable.

Summary

• Support per-state-machine execution roles (multi-role fidelity) in WorkflowRunner #5 — Per-state-machine execution roles. WorkflowRunner no longer takes a single role_arn. Each asl_registry entry carries its own ROLE_ARN, validated at construction (no shared-role fallback). The active role is switched to a sub-machine's role at each nested startExecution boundary and restored afterward — so a parent and its sub-machine run under their real, distinct roles, surfacing per-role IAM scoping bugs a single shared role would hide.
• Add DockerLambdaStrategy — run a Lambda container image via the Runtime Interface Emulator #6 — DockerLambdaStrategy. Runs a lambda:invoke step's real Lambda container image locally via the AWS Runtime Interface Emulator (RIE), instead of a hand-written mock. Built on the pluggable ImageSource (like DockerBatchStrategy); resolves the event Payload via TestState TRACE, runs the image detached with the RIE port published, POSTs the event, and returns the {"Payload": <json-string>} result shape. Ships with a LocalLambdaImageStrategy alias and a get_lambda_payload() helper.

Details

#5

• Drop role_arn ctor param; require ROLE_ARN per registry entry with a clear validation error.
• Add active_role_arn + role_for(); switch/restore at nested startExecution.
• Replace all orchestrator.role_arn reads with the active role.
• AslDefinitionDict gains a NotRequired[str] ROLE_ARN.

#6

• DockerLambdaStrategy / LocalLambdaImageStrategy taking an ImageSource.
• Free-port selection, detached --rm container, AWS_* env forwarding, stdlib-urllib POST with retry-until-up.
• Exported from the package root + __all__.

Docs / examples / tests

• New examples/docker-lambda/ (echo Lambda image + ASL + run.py + README), wired into the integration harness + offline completeness guard.
• All examples/docs updated to the per-SM ROLE_ARN shape; new strategy documented in docs/strategies.md.

Test plan

• uv run pytest tests/unit -n auto — 33 pass (incl. nested-SM role switch, missing-ROLE_ARN validation, role_for(), Lambda payload/result encoding).
• Offline examples completeness guard passes.
• Docs build warning-clean (sphinx-build -W).
• ruff + black clean; wheel includes the engine + py.typed.
• RIE path verified with Docker end-to-end (built echo_lambda, real round-trip returned {"doubled": 42, "echo": {"number": 21}}).
• Example integration tests (make test-examples) need ROLE_ARN + AWS creds — not runnable in this environment.

Closes #5. Closes #6.

🤖 Generated with Claude Code

[amazon-q-developer]

This PR successfully implements per-state-machine execution roles and the DockerLambdaStrategy feature. The implementation is well-structured with comprehensive test coverage and clear documentation.

The API change removing the single role_arn parameter in favor of per-SM roles is a breaking change but acceptable for the project context. The role-switching mechanism in nested state machines is correctly implemented with proper restoration.

Critical Issue Found:

• Resource leak risk in DockerLambdaStrategy._invoke_via_rie() where container cleanup may not occur if certain exceptions are raised (see comment on strategies.py:324-333)

Strengths:

• Comprehensive test coverage including role-switching scenarios
• Clear validation errors for missing ROLE_ARN
• Proper resource cleanup patterns in most cases
• Well-documented new strategy

Please address the critical resource leak issue before merging.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[amazon-q-developer]

🛑 Resource Leak Risk: If _post_event raises an exception other than the caught types (e.g., json.JSONDecodeError from line 305), the container will not be stopped, causing resource leaks. The finally block at line 328 only catches exceptions from docker.stop(), not from _post_event(). Wrap the entire try block to ensure cleanup happens in all failure scenarios.

Suggested change

	try:
	url = f"http://localhost:{host_port}{RIE_INVOCATION_PATH}"
	return self._post_event(url, payload)
	finally:
	try:
	docker.stop(container)
	except Exception: # container may already be gone (--rm)
	logger.debug(
	"failed to stop RIE container (already removed?)", exc_info=True
	)
	try:
	url = f""
	result = self._post_event(url, payload)
	except Exception:
	# Ensure container cleanup on any failure, then re-raise
	try:
	docker.stop(container)
	except Exception:
	logger.debug("failed to stop RIE container", exc_info=True)
	raise
	else:
	# Normal cleanup after successful execution
	try:
	docker.stop(container)
	except Exception:
	logger.debug("failed to stop RIE container (already removed?)", exc_info=True)
	return result