TenantAtlas/specs/432-exchange-powershell-production-runner-boundary-runtime-gate/implementation-report.md

Implementation Report: Exchange PowerShell Production Runner Boundary and Runtime Gate

Result

• Gate result: PASS.
• Active spec: specs/432-exchange-powershell-production-runner-boundary-runtime-gate/.
• Branch: 432-exchange-powershell-production-runner-boundary-runtime-gate.
• HEAD at implementation start: 9374260a feat: add Exchange PowerShell invocation gate (#498).
• Initial dirty state: only untracked active Spec 432 package.
• Final dirty state: application/config/test changes plus the active Spec 432 package and this report.
• Analysis/fix iterations: 4. Iteration 1 found one bounded in-scope timeout-cleanup hardening issue in the Symfony process executor. Iteration 2 added missing direct credential and permission-evidence matrix coverage. Iteration 3 fixed the invalid-enum fixture by using a raw DB corruption fixture for unexpected stored credential kinds. Iteration 4 closed the final manual review findings: production runner binding now requires both invocation and production gates, command construction no longer generates a pipeline/script conversion string, provider-lock conflict coverage was added, the requirements checklist was closed, and Pint was rerun after formatting.

Activated Skills and Gates

• spec-kit-implementation-loop: active implementation workflow.
• TenantPilot repo gates: spec readiness, workspace-scope safety, RBAC/action safety, OperationRun truth, provider freshness semantics.
• pest-testing: Pest 4 unit/feature coverage.
• Browser skill: not activated; no rendered UI surface changed.

Implementation Summary

• Added explicit tenantpilot.features.exchange_powershell_production_runner, default false.
• Kept ExchangePowerShellCommandRunner defaulting to DisabledExchangePowerShellCommandRunner; production runner is selected only when both the invocation flag and production-runner flag are enabled.
• Added a production runner boundary with runtime readiness, credential-reference, permission-evidence, provider-scope, command-builder, argument-vector process, output, timeout, concurrency, cleanup, and redaction gates.
• Added non-invasive runtime readiness checks for PowerShell availability and ExchangeOnlineManagement module presence through a fakeable process executor.
• Added reference-only credential handling. Secret-based app credentials block by default; certificate/federated/managed identity remain fail-closed unless explicitly configured as supported reference kinds.
• Added verified Exchange permission evidence evaluation using the existing ManagedEnvironmentPermission Exchange.ManageAsApp path.
• Preserved OperationRun-only execution truth and context-only provider_connection_id; no new column, migration, evidence row, route, UI, job, schedule, listener, or tenant_id.

Prerequisite Proof

• Spec 430 proof retained: only transportRule, remoteDomain, and inboundConnector command contracts are allowed.
• Spec 431 proof retained: invocation remains OperationRun-owned, fake runner remains testable, direct provider start gate remains blocked, disabled default remains valid, no evidence/UI/migration/tenant-id promotion exists.
• Completed historical specs were not rewritten.

Runner and Credential Matrix

Case	Result
Default config	Disabled runner binding
Invocation flag false + production flag true	OperationRun blocked before process execution
Production flag false + invocation flag true	OperationRun blocked before runner/process execution
No credential reference	Blocked, sanitized credential_state=missing
Secret-based app credential	Blocked, no credential payload/material persisted
Certificate reference default	Blocked as unsupported
Certificate reference explicitly supported for test	Advances to runtime/process/output gates
Missing Exchange permission evidence	Blocked by provider capability before runner execution
Verified Exchange permission evidence	Advances only to next gate; does not promote evidence/customer claims

Target and No-Promotion Matrix

Target	Command	Scope
transportRule	Get-TransportRule	read-only, internal runner boundary
remoteDomain	Get-RemoteDomain	read-only, internal runner boundary
inboundConnector	Get-InboundConnector	read-only, internal runner boundary

No Exchange evidence rows, normalized payloads, comparable/renderable/certified/restore-ready states, Review Pack output, reports, readiness badges, customer claims, routes, navigation, global search, assets, jobs, schedules, listeners, migrations, or Exchange mini-platform were introduced.

Safety Proof

• Runtime checks use fixed argument vectors with -NoLogo, -NoProfile, and -NonInteractive.
• Readiness checks do not run Connect-ExchangeOnline, install modules, import tenant sessions, dump environment variables, or prompt interactively.
• Command construction is from verified contracts only; mutation families, unknown commands, shell fragments, pipelines, redirection, aliases, and unknown parameters are rejected before process execution.
• Production process commands pass only the allowlisted Get-* command name as an argument-vector item; JSON serialization/pipeline scripting remains out of scope and live non-JSON output fails safely through the output guard.
• Process execution accepts structured command objects only.
• Output guard rejects non-zero exits, timeouts, oversized stdout/stderr, non-UTF8/binary output, scalar/text/malformed JSON, warning-prefixed output, and item-count overflow.
• Timeout cleanup calls process stop when Symfony raises a timeout exception.
• Provider and workspace locks are released after success, blocked, failed, timeout, provider-lock conflict, workspace-lock conflict, or executor-exception-result paths covered by focused tests.
• Stale-lock handling uses the existing cache lock TTL; no separate stale-lock subsystem was introduced because the repo has no narrower Exchange runner pattern and a new subsystem would exceed this slice.
• Temp files are not used.
• Summary counts remain flat numeric allowed keys: total, processed, succeeded, failed, skipped, items.
• No new summary key was introduced, so OperationSummaryKeys::all() was unchanged.

Product Surface Contract Close-Out

• No-legacy posture: canonical addition only; no fallback readers, aliases, hidden routes, duplicate UI, or legacy shims.
• Product Surface Impact: N/A - no rendered product surface changed.
• UI Surface Impact: N/A - no rendered UI surface changed.
• Browser proof: N/A - no rendered UI surface changed.
• Human Product Sanity: N/A - no product surface changed.
• Visible complexity outcome: neutral; complexity is backend safety boundary only.
• Livewire v4 compliance: unchanged repo baseline; no Livewire code added.
• Provider registration location: no Filament/panel provider change; Laravel providers remain in apps/platform/bootstrap/providers.php.
• Global search: no Filament resources or global search behavior changed.
• Destructive/high-impact actions: no UI actions added; production runner remains backend-gated and read-only Get-* only.
• Asset strategy: no assets; filament:assets not required for this slice.
• Deployment impact: no migrations, queues, schedules, storage, or assets. New env gates default disabled:
  • TENANTPILOT_EXCHANGE_POWERSHELL_PRODUCTION_RUNNER_ENABLED=false
  • runtime limit/env vars under TENANTPILOT_EXCHANGE_POWERSHELL_*
  • supported reference kinds default empty.

Validation

• cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec432 --compact
  • Result: local Sail harness failed before tests with Symfony Process signal 9; non-Docker fallback was used for validation.
• cd apps/platform && php artisan test --filter=Spec432 --compact
  • Result: PASS, 72 tests, 424 assertions.
• cd apps/platform && php artisan test --filter='Spec431|Spec430|Spec427ExchangeTeamsNoEvidencePromotion|Spec427ExchangeTeamsNoCompareRenderCertification|Spec426ExchangeTeamsNoTenantId|Spec426ExchangeTeamsNoMiniPlatform|Spec417IdentityNoLegacyNoUiActivation|Spec419M365RegistryExpansion|Spec420M365NoOverclaim|ProviderCapabilityRegistryTest' --compact
  • Result: PASS, 115 tests, 1422 assertions, 1 PostgreSQL-only skip.
• cd apps/platform && php artisan config:cache && php artisan config:clear
  • Result: PASS.
• cd apps/platform && ./vendor/bin/pint --dirty --format agent
  • Result: PASS after formatting the two new Spec 432 test files.
• cd apps/platform && ./vendor/bin/pint --dirty --test --format agent
  • Result: PASS.
• git diff --check
  • Result: PASS.

Deferred Work

• Live Exchange Online success remains a non-goal.
• Evidence promotion, compare/render/certification/restore/customer claims, and customer-visible readiness are follow-up specs.
• Broader Exchange/Teams targets remain out of scope.