TenantAtlas/specs/431-exchange-powershell-invocation-operation-registration-gate/implementation-report.md

# Implementation Report: Spec 431 - Exchange PowerShell Invocation Operation Registration and Execution Gate

## Status

Implemented on 2026-07-05. Backend-only operation registration and fake-runner invocation gate are complete for exactly `transportRule`, `remoteDomain`, and `inboundConnector`.

## Preflight

- **Active spec**: `specs/431-exchange-powershell-invocation-operation-registration-gate/`
- **Implementation branch**: `431-exchange-powershell-invocation-operation-registration-gate-session-1783272254`
- **HEAD before implementation**: `9b58a569 feat: add Exchange PowerShell adapter contract slice 1 (#497)`
- **Initial dirty state**: untracked active Spec 431 package only.
- **Activated skills/gates**: `spec-kit-implementation-loop`, `pest-testing`, `workflows/spec-readiness-gate`, `repo-contracts/workspace-scope-safety`, `repo-contracts/rbac-action-safety`, `repo-contracts/operation-run-truth`, `repo-contracts/provider-freshness-semantics`.
- **Hard-gate stop conditions checked**: no live provider execution, no shell/PowerShell process, no evidence, no UI, no migration, no scheduled capture/job, no `tenant_id`, no Exchange mini-platform.

## Files Changed

Runtime:

- `apps/platform/app/Support/OperationRunType.php`
- `apps/platform/app/Support/OperationCatalog.php`
- `apps/platform/app/Support/Operations/OperationRunCapabilityResolver.php`
- `apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityRegistry.php`
- `apps/platform/app/Services/Providers/ProviderOperationRegistry.php`
- `apps/platform/app/Services/Providers/ProviderConnectionResolver.php`
- `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`
- `apps/platform/app/Services/Providers/ProviderOperationTrustedStarter.php`
- `apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityEvaluator.php`
- `apps/platform/app/Providers/AppServiceProvider.php`
- `apps/platform/config/tenantpilot.php`
- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationGate.php`
- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandContract.php`
- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellCommandRunner.php`
- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationContext.php`
- `apps/platform/app/Services/TenantConfiguration/ExchangePowerShellInvocationResult.php`
- `apps/platform/app/Services/TenantConfiguration/FakeExchangePowerShellCommandRunner.php`
- `apps/platform/app/Services/TenantConfiguration/DisabledExchangePowerShellCommandRunner.php`

Tests:

- `apps/platform/tests/Unit/Providers/ProviderCapabilityRegistryTest.php`
- `apps/platform/tests/Feature/Providers/ProviderCapabilityEvaluationTest.php`
- `apps/platform/tests/Feature/Providers/ProviderOperationCapabilityGateTest.php`
- `apps/platform/tests/Unit/Providers/ProviderOperationStartGateTest.php`
- `apps/platform/tests/Unit/ManagedEnvironmentPermissionCheckClustersTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec431ExchangePowerShellOperationRegistrationTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec431ExchangePowerShellInvocationGateTest.php`

Spec artifacts:

- `specs/431-exchange-powershell-invocation-operation-registration-gate/tasks.md`
- `specs/431-exchange-powershell-invocation-operation-registration-gate/implementation-report.md`

## Proportionality Review

- **New abstractions added**: one public gate, one internal trusted provider-operation starter, one command contract DTO, one runner interface, one invocation context DTO, one result DTO, one fake runner, one disabled runner.
- **Why needed**: the gate centralizes authorization, provider scope, source-contract state, feature flag, credential policy, operation lifecycle, shape validation, and redaction. The runner interface keeps command execution structured and typed, making raw shell/string invocation impossible at the contract boundary.
- **Existing mechanisms extended**: `OperationRunService`, `ProviderOperationStartGate`, `ProviderOperationRegistry`, `ProviderCapabilityRegistry`, `OperationRunCapabilityResolver`, `CoverageSourceContractResolver`, and `ExchangePowerShellCommandContracts`.
- **Why no smaller change was sufficient**: wiring the fake runner directly to tests would not prove OperationRun-before-runner ordering, provider scope/capability gates, feature default-off behavior, or bypass prevention.
- **Mini-platform avoidance**: no Exchange namespace, no adapter framework, no route/UI/job/migration/evidence writer, no provider-client dependency, no Teams or wider Exchange catalog.

## Operation Registration Proof

- **OperationRun type**: `tenant_configuration.exchange_powershell_invocation` added to `OperationRunType`.
- **OperationCatalog**: canonical definition and canonical alias added with internal label `Exchange PowerShell invocation`.
- **ProviderOperationRegistry**: added `exchange_powershell` module definition requiring `Capabilities::PROVIDER_RUN` and provider capability key `exchange_powershell_invoke`; Microsoft binding explicitly states fake-gated/no-evidence posture.
- **ProviderCapabilityRegistry**: added `exchange_powershell_invoke` with `provider.exchange_powershell_invocation` plus `permissions.admin_consent` requirements.
- **Execution capability**: `OperationRunCapabilityResolver` maps the invocation type to `Capabilities::PROVIDER_RUN`.
- **Feature flag**: `tenantpilot.features.exchange_powershell_invocation`, default `false` through `TENANTPILOT_EXCHANGE_POWERSHELL_INVOCATION_ENABLED`.

## Invocation Gate Proof

- **Single public entry point**: `ExchangePowerShellInvocationGate::invoke()`.
- **Direct provider-start bypass**: public `ProviderOperationStartGate::start()` always blocks `tenant_configuration.exchange_powershell_invocation` with `ext.exchange_powershell_invocation_gate_required`. The invocation gate uses an explicit internal `ProviderOperationTrustedStarter`, so caller-supplied context cannot unlock this operation through the public start boundary.
- **Direct runner bypass**: `ExchangePowerShellCommandRunner::run()` accepts only `ExchangePowerShellCommandContract` and `ExchangePowerShellInvocationContext`. The typed contract is created only after full canonical contract and parameter validation, stores the canonical allowlisted contract rather than caller-mutated arrays, and the runner receives no separate raw parameter array; tests prove raw command strings, raw arrays, mutating contract arrays, mutated safety metadata, unexpected contract fields, and unverified parameters fail before runner execution.
- **Spec 430 source gate**: requires `contract_verified_pending_capture`, `adapter_contract_available`, `provider_calls_allowed = false`, and `execution_enabled = false` from `CoverageSourceContractResolver`.
- **Target/command gate**: exactly `transportRule`, `remoteDomain`, `inboundConnector`; exactly `Get-TransportRule`, `Get-RemoteDomain`, `Get-InboundConnector`.
- **Provider scope**: explicit workspace and managed-environment match on `ProviderConnection`; out-of-workspace/out-of-scope results stay 404.
- **RBAC**: actor requires `Capabilities::PROVIDER_RUN`; readonly in-scope members get 403.
- **Provider capability**: provider readiness still flows through the internal `ProviderOperationTrustedStarter` and `ProviderCapabilityEvaluator`, using connection-scoped readiness evidence. Fake mode bypasses only provider identity resolution, not scope, consent, provider binding, provider health freshness, or provider capability evidence.
- **No shared verification surface promotion**: the Exchange PowerShell permission requirement remains internal to provider capability evaluation and is not registered as a shared `VerificationReport` check or rendered Required Permissions product-surface claim.
- **Credential source**: non-fake mode uses existing `ProviderIdentityResolver` / `ProviderConnection::credential` / `ProviderCredential`. Fake mode uses `provider_identity_resolution_mode = fake_runner_bypass` only on the trusted Exchange invocation operation after scope, enabled-state, consent, and provider capability checks; generic provider operation starts still require provider identity.
- **Operation lifecycle**: OperationRun is created by the internal provider-operation starter before runner execution; status/outcome transitions are made through `OperationRunService`.

## Runner, Shape, Redaction, And Failure Proof

- **Fake runner**: supports success, empty success, auth failure, authorization failure, timeout, throttling, module unavailable, command unavailable, malformed scalar/text payload, and unexpected exception.
- **Production runner**: `DisabledExchangePowerShellCommandRunner`, bound by default in `AppServiceProvider`, returns blocked `execution_blocked_runner_disabled`; no shell or Microsoft call exists.
- **Summary counts**: only existing keys are emitted: `total`, `processed`, `succeeded`, `failed`, `skipped`, `items`.
- **No new summary vocabulary**: `OperationSummaryKeys` unchanged; unknown-key behavior remains handled by `SummaryCountsNormalizer`.
- **Failure reasons**: use existing provider reason codes, with local failure codes in sanitized OperationRun context/failure summaries.
- **Shape validation**: successful runner payload must be a list of arrays and each non-empty item must include a required or derived identity candidate field. Empty success is valid only from a success envelope.
- **Malformed output**: scalar/text output fails safely with `execution_failed_shape_unsafe`.
- **Redaction**: OperationRun context stores command/resource metadata, counts, reason codes, and safe contract metadata only; tests assert no raw stdout/stderr/provider payload/transcript/token/secret promotion.

## No-Promotion / No-Surface Proof

- **No evidence**: tests assert `TenantConfigurationResource` and `TenantConfigurationResourceEvidence` rows remain absent.
- **No payload promotion**: no raw or normalized evidence payload is written.
- **No customer/product claim**: no content-backed, comparable, renderable, certified, restore-ready, customer-ready, report, Review Pack, or customer output state is introduced.
- **No UI**: no route, Filament page/resource, Livewire component, navigation, global search, asset, or browser surface introduced.
- **No migration**: no database migration and no `operation_runs.provider_connection_id` column; provider connection id remains sanitized OperationRun context metadata.
- **No tenant_id**: new Spec 431 runtime source is guarded for `tenant_id`, `provider_tenant_id`, and `entra_tenant_id`.
- **No mini-platform**: no Exchange-specific service namespace/table/job/legacy shim/fallback reader/dual-write path.

## Product Surface And Filament Close-Out

- **Product Surface Impact**: no rendered product surface changed.
- **UI Surface Impact**: none.
- **Page archetype/surface budgets/Technical Annex/deep-link demotion/canonical status vocabulary**: `N/A - no rendered UI surface changed`.
- **Product Surface exceptions**: none.
- **Focused browser proof**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity**: `N/A - no product surface changed`.
- **Visible complexity outcome**: neutral.
- **No-legacy posture**: no legacy shim, fallback reader, dual truth, old route, duplicate UI, or mini-platform.
- **Livewire v4 compliance**: no Livewire runtime code changed; repo baseline remains Livewire v4.1.4.
- **Provider registration location**: no Filament panel provider registration changed; Laravel panel providers remain in `apps/platform/bootstrap/providers.php`. One service binding was added in `AppServiceProvider`.
- **Global search**: no Filament resource/global search surface changed.
- **Destructive/high-impact actions**: none added.
- **Asset strategy**: no assets registered; `filament:assets` is not required for this slice.
- **Deployment impact**: no migrations, queues, scheduler, storage, assets, or Dokploy/container runtime change. New env flag is optional and defaults disabled.

## Validation

Successful:

- `cd apps/platform && ./vendor/bin/pint --dirty`
- `cd apps/platform && php artisan test --filter=Spec431 --compact`  
  Result: 30 passed, 416 assertions.
- `cd apps/platform && php artisan test tests/Unit/Support/TenantConfiguration/Spec430ExchangePowerShellCommandAllowlistTest.php --compact`  
  Result: 28 passed, 120 assertions.
- `cd apps/platform && php artisan test tests/Unit/Providers/ProviderOperationStartGateTest.php tests/Unit/Support/TenantConfiguration/Spec430ExchangePowerShellCommandAllowlistTest.php --compact`  
  Result: 39 passed, 220 assertions.
- `cd apps/platform && php artisan test tests/Unit/Providers/ProviderCapabilityRegistryTest.php tests/Unit/Providers/ProviderOperationRegistryCanonicalTypeTest.php tests/Feature/TenantConfiguration/Spec430ExchangePowerShellNoPromotionTest.php tests/Feature/TenantConfiguration/Spec426ExchangeTeamsNoMiniPlatformTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoEvidencePromotionTest.php tests/Feature/TenantConfiguration/Spec427ExchangeTeamsNoTenantIdTest.php tests/Unit/Support/TenantConfiguration/Spec417CoverageIdentityStrategyRegistryTest.php tests/Feature/TenantConfiguration/Spec419M365RegistryExpansionTest.php --compact`  
  Result: 20 passed, 1 PostgreSQL-only Spec 419 check skipped, 688 assertions.
- `cd apps/platform && php artisan test tests/Feature/Providers/ProviderCapabilityEvaluationTest.php tests/Feature/Providers/ProviderOperationCapabilityGateTest.php tests/Unit/Providers/ProviderOperationStartGateTest.php tests/Unit/ManagedEnvironmentPermissionCheckClustersTest.php tests/Unit/Providers/Spec394ProviderReadinessResolverTest.php tests/Unit/Support/TenantConfiguration/Spec430ExchangePowerShellCommandAllowlistTest.php tests/Unit/Verification/ManagedEnvironmentPermissionCapabilityMappingTest.php --compact`  
  Result: 58 passed, 299 assertions.
- `git diff --check`

Attempted / noted:

- `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec431 --compact` was killed by signal 9 before producing test results. Non-Docker fallback was used afterward.
- The previously noted adjacent provider-start fixture failures were resolved; the focused provider capability/start/freshness suite now passes in non-Docker PHP.

## Deferred Work

- Production Exchange PowerShell execution hardening remains out of scope.
- Evidence capture/promotion for Exchange remains out of scope and should be a separate spec after runtime/permission proof.
- Teams invocation/evidence work remains separate.
- No staging/production feature enablement is included; the feature flag defaults disabled.