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

Implementation Plan: Exchange PowerShell Production Runner Boundary and Runtime Gate

Branch: 432-exchange-powershell-production-runner-boundary-runtime-gate | Date: 2026-07-07 | Spec: specs/432-exchange-powershell-production-runner-boundary-runtime-gate/spec.md Input: Feature specification from specs/432-exchange-powershell-production-runner-boundary-runtime-gate/spec.md

Summary

Implement a production-runner boundary and runtime gate for the existing Exchange PowerShell invocation path covering exactly transportRule, remoteDomain, and inboundConnector. Disabled runner remains the default. Production runner selection requires explicit invocation and production-runner config gates plus runtime readiness, credential reference, Exchange permission evidence, provider scope, OperationRun ownership, command safety, process execution safety, output safety, timeout/concurrency controls, and redaction. Live invocation may remain blocked when supported credential or verified permission evidence is absent. No evidence promotion, UI, routes, jobs, schedules, listeners, migrations, customer claims, or tenant_id are allowed.

Technical Context

Language/Version: PHP 8.4 / Laravel 12 Primary Dependencies: Filament v5 / Livewire v4 baseline remains unchanged; Symfony Process may be used if already available through Laravel dependencies Storage: PostgreSQL via existing operation_runs only; no migration Testing: Pest 4 focused unit and feature tests Validation Lanes: fast-feedback/confidence focused tests, selected regressions, browser N/A Target Platform: Laravel Sail local, Dokploy staging/production with production runner disabled by default Project Type: Laravel monolith under apps/platform Performance Goals: No unbounded process execution; per-invocation timeout and concurrency locks must bound runtime work Constraints: No raw shell strings, no Microsoft calls during readiness checks, no module install, no credential material persistence, no provider payload persistence, no rendered UI Scale/Scope: Exactly three Exchange target types and one existing invocation operation

Preflight Findings

• Current prep branch before Spec Kit execution: platform-dev.
• HEAD before Spec Kit execution: 9374260a feat: add Exchange PowerShell invocation gate (#498).
• Initial dirty state before Spec Kit execution: clean.
• Spec Kit helper created branch: 432-exchange-powershell-production-runner-boundary-runtime-gate.
• Existing related packages: specs/430-exchange-powershell-adapter-contract-slice-1/ and specs/431-exchange-powershell-invocation-operation-registration-gate/.
• No existing specs/432-* package was found before preparation.
• Spec 430 implementation report proves the three command contracts and no live provider/evidence/UI/migration scope.
• Spec 431 implementation report proves OperationRun/provider operation registration, exchange_powershell_invoke capability, fake runner proof, disabled runner default, sanitized context, no evidence, no UI, no migration, and no tenant_id.
• Current AppServiceProvider binds ExchangePowerShellCommandRunner to DisabledExchangePowerShellCommandRunner.
• Current config has tenantpilot.features.exchange_powershell_invocation defaulting false through TENANTPILOT_EXCHANGE_POWERSHELL_INVOCATION_ENABLED.
• Current OperationSummaryKeys::all() includes generic keys such as total, processed, succeeded, failed, skipped, and items; use these unless a new key is explicitly justified and tested.
• RunFailureSanitizer already normalizes provider/auth/permission/timeout-like failures and redacts secret-like strings.

UI / Surface Guardrail Plan

• Guardrail scope: no operator-facing surface change.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: N/A.
• No-impact class, if applicable: backend-only runtime and operation safety boundary.
• Native vs custom classification summary: N/A.
• Shared-family relevance: OperationRun/provider operation shared contracts only; no rendered UI shared family.
• State layers in scope: OperationRun context, summary counts, failure reasons, runtime/credential/permission gate states.
• Audience modes in scope: internal operator/reviewer only; no customer surface.
• Decision/diagnostic/raw hierarchy plan: No product view. Raw process/provider output is forbidden from persistence.
• Raw/support gating plan: Raw output and credential material are never stored.
• One-primary-action / duplicate-truth control: N/A.
• Handling modes by drift class or surface: N/A.
• Repository-signal treatment: service-provider binding changes are backend service-container behavior only; panel provider registration remains unchanged.
• Special surface test profiles: N/A.
• Required tests or manual smoke: N/A - no rendered UI surface changed.
• Exception path and spread control: none.
• Active feature PR close-out entry: no rendered product surface changed.
• UI/Productization coverage decision: No UI surface impact.
• Coverage artifacts to update: none.
• No-impact rationale: The spec forbids routes, Filament pages, Livewire components, navigation, global search, and assets.
• Navigation / Filament provider-panel handling: no panel/provider registration changes; Laravel panel providers remain in apps/platform/bootstrap/providers.php.
• Screenshot or page-report need: no.

Product Surface Contract Plan

• Product Surface Contract reference: docs/product/standards/product-surface-contract.md.
• No-legacy posture: canonical addition only; no compatibility aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures.
• Page archetype and surface budget plan: N/A.
• Technical Annex and deep-link demotion plan: N/A - no rendered product surface changed. OperationRun remains internal/audit truth and no new links are added.
• Canonical status vocabulary plan: N/A.
• Product Surface exceptions: none.
• Browser verification plan: N/A - no rendered UI surface changed.
• Human Product Sanity plan: N/A.
• Visible complexity outcome target: neutral for product surfaces.
• Implementation report target: specs/432-exchange-powershell-production-runner-boundary-runtime-gate/implementation-report.md.

Filament / Livewire / Deployment Posture

• Livewire v4 compliance: repo baseline remains Livewire v4; no Livewire runtime code planned.
• Panel provider registration location: no panel/provider change; Laravel panel providers remain in apps/platform/bootstrap/providers.php.
• Global search posture: no Filament resource/global search surface changed.
• Destructive/high-impact action posture: no UI action added; production runner remains backend-gated and read-only command only.
• Asset strategy: no assets; filament:assets is not required for this slice.
• Testing plan: no pages/widgets/relation managers/actions/browser tests because no rendered UI surface changes.
• Deployment impact: no migrations, queues, scheduler, storage, assets, or browser build. New env/config gate for production runner defaults disabled and must be documented in the implementation report if added.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: ExchangePowerShellInvocationGate, ExchangePowerShellCommandRunner, DisabledExchangePowerShellCommandRunner, OperationRunService, ProviderOperationTrustedStarter, ProviderCapabilityEvaluator, ProviderCapabilityRegistry, ProviderOperationRegistry, OperationSummaryKeys, SummaryCountsNormalizer, RunFailureSanitizer, provider credential/identity infrastructure, and config under tenantpilot.features.
• Shared abstractions reused: OperationRun lifecycle, provider operation/capability registries, SummaryCountsNormalizer, RunFailureSanitizer, Spec 430 command contracts, Spec 431 invocation gate.
• New abstraction introduced? why?: Production runner, runtime readiness checker, credential resolver/evaluator, permission evidence evaluator, process executor, command builder, and runtime policy may be introduced because process execution and credential safety require explicit testable boundaries.
• Why the existing abstraction was sufficient or insufficient: Existing paths are sufficient for operation truth, provider scope, and fake/disabled runner proof. They are insufficient for production process execution, non-invasive runtime checks, credential/permission evidence gating, no-shell command construction, output guards, timeout/concurrency cleanup, and runner selection.
• Bounded deviation / spread control: No generic PowerShell platform, no multi-provider process framework, no evidence writer, no UI. Keep new services under the repo-canonical TenantConfiguration service path unless implementation finds an existing narrower home.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, backend OperationRun lifecycle and sanitized context only.
• Central contract reused: OperationRunService, OperationSummaryKeys, SummaryCountsNormalizer, RunFailureSanitizer, and Spec 431 invocation path.
• Delegated UX behaviors: no toast, run link, artifact link, browser event, queued DB notification, or surface messaging.
• Surface-owned behavior kept local: none.
• Queued DB-notification policy: N/A.
• Terminal notification path: central lifecycle mechanism where applicable; no feature-local notification.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes.
• Provider-owned seams: Exchange command names, ExchangeOnlineManagement module readiness, Exchange permission evidence, PowerShell process command construction, response/output shape, and command safety.
• Platform-core seams: OperationRun lifecycle, provider connection/scope, provider operation/capability gating, summary/failure sanitizer, credential-reference metadata, and config gating.
• Neutral platform terms / contracts preserved: operation, provider connection, capability, managed environment, workspace, runtime readiness, credential reference, permission evidence, process executor, summary counts, failure reason, runner mode.
• Retained provider-specific semantics and why: Exchange command/runtime semantics stay in provider-owned TenantConfiguration runner-boundary services because Spec 432 is explicitly Exchange PowerShell only.
• Bounded extraction or follow-up path: document-in-feature; verified credential/permission evidence support, evidence promotion, compare/render/certification, Teams runtime, and customer output remain separate follow-up specs.

Constitution Check

• Inventory-first: no inventory, snapshot, backup, or evidence truth is changed.
• Read/write separation: only read-only Exchange Get-* commands are in scope; mutation commands are rejected.
• Graph contract path: no Microsoft Graph call path changed; no Graph call added.
• Deterministic capabilities: provider/actor capability mappings remain central and tested through Spec 431 path.
• RBAC-UX: non-member workspace/environment access is 404; member without capability is 403 or repo-equivalent; readonly cannot invoke.
• Workspace isolation: workspace and managed environment are mandatory scope inputs.
• Tenant isolation: provider connection and permission evidence must match managed environment before process execution.
• Feature gates: existing invocation feature flag remains false by default; new production-runner flag must default false.
• Credential source: use existing provider credential/identity reference truth; no new credential store.
• Run observability: public invocation returns or references OperationRun/safe blocker through the existing invocation path.
• OperationRun start UX: no rendered start surface; lifecycle/summary/failure paths stay central.
• Ops-UX 3-surface feedback: no new UI feedback or notification policy.
• Ops-UX lifecycle: status/outcome transitions only through OperationRunService.
• Ops-UX summary counts: allowed keys only, flat numeric values only.
• Data minimization: OperationRun context stores safe gate states and metadata only; no raw output, credentials, tokens, transcripts, or payloads.
• Test governance: focused unit/feature tests with fake process executor and fake runtime-readiness seams; no browser lane and no CI dependency on host PowerShell or ExchangeOnlineManagement.
• Proportionality: new runtime boundaries are justified by credential safety, shell/process safety, provider scope, and no-promotion truth.
• No premature abstraction: no generic PowerShell framework or multi-provider process platform.
• Persisted truth: no new tables or persisted evidence truth.
• Behavioral state: blocker/failure codes change execution handling and remain bounded to runner safety.
• Provider boundary: Exchange-specific terms remain provider-owned and do not become platform-core customer truth.
• Product Surface Contract: N/A - no rendered product surface changed.

Test Governance Check

• Test purpose / classification by changed surface: Unit for binding/runtime/credential/permission/process/output/sanitizer behavior; Feature for OperationRun/provider scope/no evidence/no trigger/no migration/no tenant_id.
• Affected validation lanes: fast-feedback/confidence focused tests and selected regressions; browser N/A.
• Why this lane mix is the narrowest sufficient proof: The change is backend service/runtime safety behavior with no rendered UI and no schema.
• Narrowest proving command(s):
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec432 --compact
  • selected Spec 431 and Spec 430 regression tests
  • selected Spec 426/427/417/419/420 no-promotion, identity, registry, and generic evidence regressions
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check
• Fixture / helper / factory / seed / context cost risks: workspace, managed environment, provider connection, credential reference, permission evidence, OperationRun, and fake process executor setup. Keep helpers explicit and feature-local unless reused intentionally.
• Expensive defaults or shared helper growth introduced?: no planned defaults.
• Heavy-family additions, promotions, or visibility changes: none planned; PostgreSQL-only lock proof must be named if implementation requires it.
• Surface-class relief / special coverage rule: backend-only; browser N/A - no rendered UI surface changed.
• Closing validation and reviewer handoff: implementation report must list exact tests and pass/fail counts.
• Budget / baseline / trend follow-up: none expected.
• Review-stop questions: verify disabled default, no live invocation without all gates, no shell strings, no Microsoft calls during readiness, no credential material, no raw output, no evidence, no UI/trigger surface, no migration, no tenant_id, no mini-platform.
• Escalation path: reject-or-split if implementation attempts live evidence, UI, routes/jobs/schedules/listeners, migrations, broader Exchange/Teams scope, or customer claims.
• Active feature PR close-out entry: backend runner-boundary safety; no rendered UI surface changed.
• Why no dedicated follow-up spec is needed: Routine runner-boundary test upkeep stays inside Spec 432. Credential/permission evidence support and evidence promotion are separate follow-up specs only when needed.

Project Structure

Documentation (this feature)

specs/432-exchange-powershell-production-runner-boundary-runtime-gate/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- implementation-report.md

Source Code (likely affected by later implementation)

apps/platform/app/Providers/AppServiceProvider.php
apps/platform/config/tenantpilot.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationGate.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandRunner.php
apps/platform/app/Services/TenantConfiguration/DisabledExchangePowerShellCommandRunner.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationContext.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationResult.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandContract.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandContracts.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellProductionRunner.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellRuntimeReadinessChecker.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCredentialReferenceResolver.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellPermissionEvidenceEvaluator.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellProcessCommandBuilder.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellProcessExecutor.php
apps/platform/app/Services/TenantConfiguration/FakeExchangePowerShellProcessExecutor.php
apps/platform/app/Services/TenantConfiguration/ExchangePowerShellRuntimePolicy.php
apps/platform/app/Support/OpsUx/RunFailureSanitizer.php
apps/platform/app/Support/OpsUx/OperationSummaryKeys.php
apps/platform/app/Support/OpsUx/SummaryCountsNormalizer.php
apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityEvaluator.php
apps/platform/tests/Unit/Support/TenantConfiguration/
apps/platform/tests/Feature/TenantConfiguration/
apps/platform/tests/Unit/OpsUx/
apps/platform/tests/Feature/Guards/

Forbidden source changes:

apps/platform/routes/**
apps/platform/resources/views/**
apps/platform/app/Filament/**
apps/platform/app/Livewire/**
apps/platform/database/migrations/**
new Exchange-specific evidence tables
jobs/schedules/listeners that invoke the production runner
customer report or Review Pack output

Structure Decision: Use the existing TenantConfiguration and OpsUx support paths. Do not create a new Exchange subsystem or base folder without explicit approval.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
New runner boundary services	Live process execution requires explicit runtime, credential, permission, process, output, and redaction gates.	Extending the fake/disabled runner only would not prove production execution safety.
New process executor abstraction	Tests must prove execution behavior without running PowerShell and without shell strings.	Direct Symfony Process use inside the runner would make fake testing and shell-string guard proof weaker.
New failure states	Operators/reviewers need actionable blocked/failed reasons, and code needs behavior-specific handling.	Collapsing every failure to unknown_error would hide unsafe runtime, credential, permission, output, and concurrency conditions.

Proportionality Review

• Current operator problem: Prevent false confidence that Exchange evidence is ready while allowing a safe production-runner boundary to be implemented and tested.
• Existing structure is insufficient because: Spec 431 has only disabled/fake execution and no production process, credential, permission, runtime readiness, output, timeout, or concurrency proof.
• Narrowest correct implementation: Add a safely blocked/gated production boundary for the three existing Exchange command contracts.
• Ownership cost created: Focused service/test surface that future evidence specs must maintain and use.
• Alternative intentionally rejected: Enabling live execution inside an evidence promotion spec, or using admin consent/feature flag alone as runtime permission proof.
• Release truth: Current-release safety truth before evidence promotion.

Implementation Phases

Phase 0 - Preflight

• Capture branch, HEAD, and dirty state.
• Confirm Spec 431 PASS and no open blocking bypass/capability/redaction findings.
• Confirm current disabled runner binding and invocation feature flag.
• Confirm current credential infrastructure and provider permission evidence path.
• Confirm summary keys and sanitizer behavior.
• Confirm no evidence/UI/migration/job/schedule/listener scope.

Phase 1 - Runner Binding and Config

• Preserve disabled runner as default.
• Add production-runner config flag under a repo-canonical tenantpilot.features or nested Exchange PowerShell config path.
• Prove default false behavior and repo-canonical config-cache binding stability, using actual config:cache when viable or a documented service-container/config-resolved simulation when that is the repo-safe test path.
• Production runner may be selected only when invocation gate and production-runner gate are enabled and all other gates pass.

Phase 2 - Runtime Readiness

• Add non-invasive runtime readiness checker.
• Check configured PowerShell executable availability without profile loading or shell strings; automated tests must fake the executor/path-check seam.
• Check ExchangeOnlineManagement module availability only through a non-invasive fixed command or safe unknown/missing state; automated tests must not require the real module.
• Validate runtime environment allowlist, timeout policy, process executor, and temp policy.
• Forbid Microsoft connection, module install, env dump, tenant session import, and interactive prompts.

Phase 3 - Credential and Permission Gates

• Add safe credential reference resolver/evaluator.
• Block client-secret credentials by default.
• Test certificate, federated, managed-identity, missing, expired, inaccessible, unsupported, and unknown states.
• Add Exchange permission evidence evaluator.
• Preserve admin-consent-not-sufficient behavior.
• If no canonical verified evidence exists, fail closed and document Spec 433 as follow-up.

Phase 4 - Process Executor and Command Builder

• Add process executor abstraction and fake executor.
• Add command builder using argument vectors or structured process calls.
• Build only from Spec 430 command contracts.
• Reject shell strings, pipelines, script fragments, redirection, aliases, profile loading, mutation command families, and unknown parameters.

Phase 5 - Production Runner Boundary

• Add production runner service behind the binding/config gates.
• Require OperationRun context, runtime readiness, credential reference, permission evidence, provider scope, and redaction policy before process execution.
• Return transient runner envelopes only.
• Persist no provider payload, stdout, stderr, transcript, or credential material.

Phase 6 - Output, Timeout, Concurrency, and Cleanup Guards

• Guard stdout/stderr byte limits, item limits, UTF-8, structured shape, warning-prefix, non-zero exit, scalar/text output, binary output, and unexpected exceptions.
• Enforce per-invocation timeout and process termination/cleanup.
• Enforce provider/workspace concurrency locks and cleanup on success/failure/timeout/exception.
• Prefer no temp files; if used, prove safe content and cleanup.

Phase 7 - OperationRun, Summary, Redaction, and No-Promotion

• Store only safe OperationRun context.
• Reuse existing summary keys unless a narrow tested key is unavoidable.
• Add or map sanitized failure reasons.
• Prove redaction across context, summaries, failures, runner envelopes, process output, exceptions, logs if testable, and temp files if any.
• Prove no evidence, compare/render/certification, restore, customer claim, UI, trigger surface, migration, tenant_id, legacy shim, fallback reader, or Exchange mini-platform.

Phase 8 - Regression and Report

• Run focused Spec 432 tests.
• Run selected Spec 431/430/426/427/417/419/420 regressions.
• Run Pint and git diff --check.
• Complete implementation-report.md with runner/credential/target/no-promotion matrices and validation results.

Rollout and Deployment Considerations

• New production-runner config must default disabled in all environments.
• No migration, queue, scheduler, storage, asset, or browser build impact is planned.
• Dokploy/staging validation is required before any future spec enables live invocation outside test/fake contexts.
• If implementation adds environment variables, the implementation report must list names, defaults, and staging/production validation requirements.

Risk Controls

• Hard stop if production runner can activate by default.
• Hard stop if client-secret credentials or admin consent alone enable live invocation.
• Hard stop if raw PowerShell strings, mutation commands, or unknown parameters can execute.
• Hard stop if raw output, secrets, provider payload, or transcripts persist.
• Hard stop if evidence or customer/product claims are promoted.
• Hard stop if routes, UI, jobs, schedules, listeners, migrations, or tenant_id are introduced without amending the spec.