Require authored ACA Sandbox Group region

[Laveesh Rohra (larohra)]

Stack layer 1/5

Requires the normalized app-wide session_runtime.aca_sandbox.region, removes runtime ARM group discovery/fallback, and constructs the regional ACA data-plane boundary directly from the authored group resource ID and region.

Completes the runtime-owned typed/redacted provider boundary across app, readiness, controller HTTP surfaces, smoke/probe/reaper helpers, guest forwarding, fixtures, and tests. It preserves stopped-session resume semantics: reusable sessions resume before manifest verification, only typed Running/Resuming is safe 409 progress, and sandbox-scoped 404 means missing backing.

This replaces part of draft PR #169 without modifying or closing it. Later reliability, qualification, pipeline, package, attestation, and cleanup-policy layers are intentionally excluded.

Validation

• python -m ruff check src tests
• python -m mypy src
• deterministic eng/scripts/generate_config_reference.py
• 473 targeted config/app/readiness/HTTP/transport/smoke/probe/fixture tests
• git diff --check
• structural checks for required region= on every AcaSandboxAdapter.open(), removed ARM discovery symbols, conflict markers, and later-layer leaks

[Copilot]

🟡 Changes recommended

Provider failures are suppressed or misclassified, backend-level coverage is missing, and lint errors remain.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Requires an authored ACA Sandbox Group region, removes runtime ARM discovery, and adds typed, redacted provider-error handling.

Changes:

• Adds and documents required normalized region configuration.
• Builds regional ACA clients directly from authored configuration.
• Updates controller, tooling, fixtures, and tests for the new boundary.

File summaries

File	Description
tests/test_transport_aca_sdk.py	Updates adapter and provider-error coverage.
tests/test_session_runtime_validation.py	Updates runtime validation expectations.
tests/test_probe_aca_data_plane.py	Tests region-aware probing.
tests/test_controller_sandbox_config.py	Tests region forwarding.
tests/test_controller_readiness.py	Tests activation-error mapping.
tests/test_controller_http.py	Tests HTTP error responses; backend coverage and lint issues remain.
tests/test_config_schema.py	Tests region validation.
tests/test_app.py	Tests region propagation.
tests/test_aca_smoke_support.py	Tests smoke region requirements.
tests/test_aca_pr_smoke.py	Tests region-aware smoke preflight.
tests/test_aca_deployed_agent_turn.py	Configures deployed-test regions.
tests/live/test_aca_sdk_smoke.py	Supplies region to live SDK smoke tests.
tests/live/test_aca_run_journal_acceptance.py	Updates failure assertions.
tests/live/aca_smoke_support.py	Threads region through smoke helpers.
tests/live/aca_deployed_lifecycle_support.py	Threads region through lifecycle helpers.
tests/fixtures/live_aca_setup_timeout_recovery/controlled_setup_timeout.py	Passes fixture-configured region.
tests/fixtures/live_aca_setup_timeout_recovery/agents.config.yaml	Adds fixture region.
tests/fixtures/live_aca_deployed_agent_turn/agents.config.yaml	Adds fixture region.
tests/fixtures/config_scenarios/29_aca_sandbox_valid/agents.config.yaml	Adds valid region configuration.
tests/fixtures/config_scenarios/27_aca_sandbox_row10_bad_reclaim_idle/agents.config.yaml	Preserves the targeted invalid scenario.
tests/fixtures/config_scenarios/26_aca_sandbox_row9_bad_auto_suspend_idle/agents.config.yaml	Preserves the targeted invalid scenario.
tests/fixtures/config_scenarios/25_aca_sandbox_row8_anonymous_auth/agents.config.yaml	Adds the required region.
tests/fixtures/config_scenarios/21_aca_sandbox_row4_non_http_trigger/agents.config.yaml	Adds the required region.
tests/fixtures/config_scenarios/20_aca_sandbox_row3_dynamic_sessions_conflict/agents.config.yaml	Adds the required region.
tests/fixtures/config_scenarios/19_aca_sandbox_row2_workflows_enabled/agents.config.yaml	Adds the required region.
src/azure_functions_agents/transport/transport_models.py	Adds provider error types and region validation.
src/azure_functions_agents/transport/aca_sdk.py	Removes ARM lookup and translates SDK errors; cleanup classification needs correction.
src/azure_functions_agents/controller/sandbox_config.py	Forwards region into sandbox configuration.
src/azure_functions_agents/controller/readiness.py	Maps transport failures; residual provisioning errors are misclassified.
src/azure_functions_agents/controller/http.py	Adds sanitized availability responses, but the real backend suppresses new errors.
src/azure_functions_agents/config/schema.py	Adds the required region schema.
src/azure_functions_agents/app.py	Passes region to the adapter.
README.md	Documents authored region usage.
eng/templates/official/jobs/e2e-tests.yml	Supplies region to E2E jobs.
eng/scripts/reap_aca_smoke_sandboxes.py	Uses region during cleanup.
eng/scripts/README.md	Documents cleanup region configuration.
eng/scripts/probe_aca_data_plane.py	Uses the regional data-plane endpoint.
eng/scripts/aca_pr_smoke.py	Requires region during smoke preflight.
eng/scripts/aca_deployed_qualification.py	Propagates qualification region.
docs/front-matter-spec.md	Adds region examples and constraints.
docs/front-matter-reference.md	Adds generated region reference.
docs/frds/0008-aca-sandbox-session-runtime.md	Records regional binding decisions.
docs/architecture.md	Documents the regional transport boundary.
docs/aca-sandbox-session-runtime.md	Updates regional binding guidance.

Review details

Suppressed comments (2)

tests/test_controller_http.py:986

• Add two blank lines before this top-level decorator. It currently immediately follows the preceding function body and triggers Ruff E305 under the repository's enabled E rules.
  tests/test_controller_http.py:951
• Remove these two extra blank lines. With Ruff's E rules enabled, the four blank lines before this top-level class trigger E303, so the stated lint gate cannot pass on this file as shown.

• Files reviewed: 44/44 changed files
• Comments generated: 4
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Unresolved error translation, timeout, cleanup, and transient-failure handling issues can cause incorrect runtime behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (5)

docs/frds/0008-aca-sandbox-session-runtime.md:668

• The adapter no longer reads a live Sandbox Group identity or region: it compares the authored binding with the persisted binding, while _make_handle verifies only the live sandbox ID. Claiming a live group/region comparison overstates the fail-closed guarantees; describe the checks that are actually performed.

or compatibility fallback. It compares the configured, persisted, and live
Sandbox Group identity and region and fails closed on mismatch. It does not

src/azure_functions_agents/controller/readiness.py:461

• This new translation set still omits SandboxProvisioningError. The adapter now emits that type for non-auth/non-404/non-transient group failures and emits its SandboxInvalidStateError subclass for a 409 from list_sandboxes; reconcile_session_targeted() performs that inventory call before its own suppression block. Those errors therefore escape reconcile_session() as transport exceptions, bypass the activation/HTTP mappings, and can turn status/result reconciliation into an untyped 500. Translate invalid-state to SessionActivationConflictError and residual provisioning errors to the binding category here, as the activation/provision paths already do.

            except (
                SandboxGroupAuthorizationError,
                SandboxGroupBindingError,
                SandboxGroupTransientError,
            ) as exc:
                _raise_activation_provider_error(exc)

tests/live/test_aca_run_journal_acceptance.py:78

• This weakens the deterministic unknown-agent check to accept any harness failure, including timeout, OOM, or a generic harness crash. The unchanged harness maps the requested unknown agent's HarnessJournalError to sandbox_storage_failure, so retain the exact code assertion to keep this live acceptance test from passing on unrelated failures.
  tests/test_controller_http.py:951
• These additions leave four blank lines before the class. Ruff enables the full E ruleset in pyproject.toml, so E303 will fail the required lint gate; keep exactly two top-level blank lines.
  tests/test_controller_http.py:986
• The decorator immediately follows the preceding top-level function with no blank lines. With Ruff's E rules enabled, E305 requires two blank lines here and the lint gate will fail.

• Files reviewed: 46/46 changed files
• Comments generated: 4
• Review effort level: Balanced