TenantAtlas/specs/421-entra-core-comparable-renderable-pack/plan.md

# Implementation Plan: Spec 421 - Entra Core Comparable / Renderable Pack

**Branch**: `421-entra-core-comparable-renderable-pack` | **Date**: 2026-06-27 | **Spec**: `specs/421-entra-core-comparable-renderable-pack/spec.md`  
**Input**: Feature specification from `/specs/421-entra-core-comparable-renderable-pack/spec.md`

## Summary

Promote selected Entra Coverage v2 evidence to comparable/renderable support without adding capture scope, restore, certification, customer output, or an Entra mini-platform. The mandatory implementation-ready slice is `conditionalAccessPolicy` because current repo truth already has a content-backed source contract path from Spec 420. `securityDefaults`, `application`, `servicePrincipal`, `roleDefinition`, and `administrativeUnit` remain evidence-gated and may be promoted only when preflight proves repo-real content-backed evidence already exists.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12, Filament v5, Livewire v4  
**Primary Dependencies**: Existing Tenant Configuration / Coverage v2 services, `GraphClientInterface` only for existing evidence capture paths, `ClaimGuard`, `BadgeCatalog`/`BadgeRenderer`, Pest 4  
**Storage**: Existing PostgreSQL tables for `tenant_configuration_resource_types`, `tenant_configuration_resources`, and `tenant_configuration_resource_evidence`; no new table by default  
**Testing**: Pest 4 unit, feature, and focused browser if rendered UI changes  
**Validation Lanes**: fast-feedback, confidence, browser if rendered output changes  
**Target Platform**: Laravel Sail locally, Dokploy container deployment for staging/production  
**Project Type**: web app under `apps/platform`  
**Performance Goals**: render/compare from persisted evidence only; no remote/provider calls during UI render  
**Constraints**: no restore, no certification, no customer-facing claims, no new capture contract, no `tenant_id`, no Entra mini-platform, no new OperationRun type  
**Scale/Scope**: one mandatory evidence-backed resource type (`conditionalAccessPolicy`), optional Entra types only if already content-backed and testable

## UI / Surface Guardrail Plan

- **Guardrail scope**: existing internal/operator Coverage v2 surface may change through rendered evidence/status summaries.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: existing `CoverageV2Readiness` page, `CoverageV2ResourceTypesTable`, `CoverageV2ResourceInstancesTable`, inspect slide-over, and read model if rendered summaries are exposed. No new route, navigation, panel provider, action, report, download, or customer surface.
- **No-impact class, if applicable**: N/A - rendered data may change.
- **Native vs custom classification summary**: native Filament + existing widgets/read model.
- **Shared-family relevance**: evidence/status/read-only registry and inspect details.
- **State layers in scope**: page/detail evidence display; no shell/navigation state.
- **Audience modes in scope**: operator-MSP and support-platform; no customer/read-only output.
- **Decision/diagnostic/raw hierarchy plan**: typed summary first, diagnostics second, raw/support evidence hidden or secondary.
- **Raw/support gating plan**: raw payload not default-visible; secrets never shown.
- **One-primary-action / duplicate-truth control**: keep existing inspect link as the only action; no capture/restore/certify/export action.
- **Handling modes by drift class or surface**: Product Surface and browser proof are review-mandatory if rendered output changes; runtime UI expansion is hard-stop until spec/plan/tasks are amended.
- **Repository-signal treatment**: report-only for no new UI files; review-mandatory for existing rendered output changes; exception-required for any new surface/action.
- **Special surface test profiles**: shared-detail-family / standard-native-filament.
- **Required tests or manual smoke**: focused browser if rendered output changes; feature tests for no raw/default overclaim.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **UI/Productization coverage decision**: existing internal surface only; no coverage artifact unless UI scope expands.
- **Coverage artifacts to update**: none by default.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no provider/panel/navigation change.
- **Screenshot or page-report need**: no page report by default; browser proof is sufficient for existing internal surface rendering.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical Coverage v2 extension; no compatibility exception.
- **Page archetype and surface budget plan**: Existing Technical Annex / internal operator evidence inspection surface; budgets pass because no new page/action family is added.
- **Technical Annex and deep-link demotion plan**: OperationRun links, evidence IDs, source keys, raw/normalized payloads, provider IDs, permission context, and unsupported fields remain secondary/diagnostic.
- **Canonical status vocabulary plan**: Use existing Coverage v2 labels and canonical status wording; no `Entra covered`, `certified`, `restore-ready`, `customer-ready`, or `100%` labels.
- **Product Surface exceptions**: none.
- **Browser verification plan**: focused Coverage v2 route/inspect flow if rendered output changes; otherwise `N/A - no rendered UI surface changed` with proof.
- **Human Product Sanity plan**: required if rendered output changes; result in implementation report.
- **Visible complexity outcome target**: neutral or decreased.
- **Implementation report target**: `specs/421-entra-core-comparable-renderable-pack/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire v4.x confirmed; no Livewire v3 APIs.
- **Panel provider registration location**: no panel provider change; Laravel 12 provider registration remains `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Filament Resource global-search behavior changed; no new Resource.
- **Destructive/high-impact action posture**: none. No restore/apply/capture/export/certify action is introduced.
- **Asset strategy**: no assets by default; `filament:assets` is not newly required beyond existing deployment practice.
- **Testing plan**: unit tests for typed behavior; feature tests for evidence-gated promotion, claims, redaction, scope, no overclaim; browser proof if rendered output changes.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, or assets expected.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: `ResourceTypeRegistry`, `TenantConfigurationResourceType`, `TenantConfigurationResource`, `TenantConfigurationResourceEvidence`, `GenericPayloadNormalizer`, `CoveragePayloadRedactor`, `CoverageIdentityStrategyRegistry`, `CanonicalIdentityResolver`, `ClaimGuard`, `CoverageV2ReadinessReadModel`, existing Coverage v2 widgets if rendered.
- **Shared abstractions reused**: Existing Coverage v2 registry, evidence, identity, redaction, Claim Guard, badges, and read-only operator surface.
- **New abstraction introduced? why?**: Bounded Entra typed normalizer/comparator/render summary helpers may be introduced because generic payload sorting/redaction is insufficient for operator-safe Conditional Access comparison.
- **Why the existing abstraction was sufficient or insufficient**: Existing structures are sufficient for ownership, evidence, identity, claims, redaction, and rendering host; insufficient for typed Entra material-field semantics.
- **Bounded deviation / spread control**: Entra-specific field semantics stay inside bounded helpers/config for evidence-backed types and must not become a provider framework.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no new start/completion/link UX.
- **Central contract reused**: N/A by default; existing OperationRun links remain diagnostics only if already present.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: read-only inspect only.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none. If compare/render becomes long-running or persisted as an operation, stop and amend the spec.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Entra resource names, Graph field names, Conditional Access targeting/control semantics, optional Security Defaults fields.
- **Platform-core seams**: Coverage v2 evidence/resource state, coverage level, identity state, claim state, redaction boundary, workspace/managed-environment/provider connection ownership, Product Surface output.
- **Neutral platform terms / contracts preserved**: resource type, evidence, compare result, render summary, coverage level, claim state, identity state, provider connection, managed environment.
- **Retained provider-specific semantics and why**: Necessary to compare/render actual Entra evidence; bounded to current selected resource types.
- **Bounded extraction or follow-up path**: document-in-feature for optional type blockers; follow-up-spec for missing Security Defaults capture/source contract.

## Constitution Check

- Inventory/evidence truth: PASS. Render/compare derives from existing last-observed evidence; it does not create customer proof.
- Read/write separation: PASS. No provider write, restore, apply, or mutating UI action.
- Graph contract path: PASS by default. No new capture or render-time Graph calls; any existing evidence remains from existing contract paths.
- Deterministic capabilities: PASS. Coverage-level promotion and compare behavior are testable.
- Workspace isolation: PASS with workspace + managed environment + provider connection scope requirements.
- RBAC-UX: PASS with existing Evidence View authorization and no action surface.
- OperationRun: PASS by default. No new OperationRun type or lifecycle; existing links remain diagnostics only.
- Evidence anchor/currentness: PASS if evidence is explicit and no fallback-to-latest is added.
- Customer output: PASS. No customer-facing output, report, download, or customer-ready claim.
- Provider boundary: PASS if Entra semantics stay in bounded typed helpers and provider-native IDs remain metadata.
- Product Surface: PASS with existing-surface proof and Product Surface exceptions `none`.
- Test governance: PASS with Unit/Feature/Browser-if-rendered lanes named.
- Proportionality: PASS. Typed helpers are justified by operator-safe compare/render and avoid new tables/frameworks.
- No premature abstraction: PASS if implementation avoids generic provider frameworks and separate Entra engines.
- Persisted truth: PASS by default. Existing evidence remains truth; compare/render derived unless spec amended.
- Behavioral state: PASS using existing coverage levels and derived non-persisted importance labels.
- No legacy / lean doctrine: PASS. No adapters, dual reads/writes, fallback readers, legacy aliases, or `tenant_id`.

## Testing / Lane / Runtime Impact

- **Test purpose / classification by changed surface**: Unit for normalization/compare/render/redaction/Claim Guard; Feature for evidence-gated promotion, RBAC/scope/no-overclaim/no-restore/no-certification/no-tenant-id/no-mini-platform; Browser if rendered Coverage v2 output changes.
- **Validation lane(s)**: fast-feedback, confidence, browser-if-rendered.
- **Fixture/helper/factory cost**: minimal workspace/managed-environment/provider/evidence setup; fake payloads only; no live Graph/TCM calls.
- **Heavy-family visibility**: none expected.
- **Reviewer handoff**: confirm optional type blockers are documented, no runtime capture expansion occurred, and no hidden customer output or UI action was introduced.
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec421EntraConditionalAccessNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec421EntraComparableDiffTest.php tests/Unit/Support/TenantConfiguration/Spec421EntraRenderableSummaryTest.php tests/Unit/Support/TenantConfiguration/Spec421EntraRedactionTest.php tests/Unit/Support/TenantConfiguration/Spec421EntraClaimGuardTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec421EntraComparableRenderableTest.php tests/Feature/TenantConfiguration/Spec421EntraCoverageLevelPromotionTest.php tests/Feature/TenantConfiguration/Spec421EntraNoRestoreNoCertificationTest.php tests/Feature/TenantConfiguration/Spec421EntraNoTenantIdTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php` if rendered output changes
  - `git diff --check`

## Likely Repo Surfaces

Runtime implementation should verify current names before editing, but likely surfaces are:

- `apps/platform/app/Services/TenantConfiguration/GenericPayloadNormalizer.php`
- `apps/platform/app/Services/TenantConfiguration/CoveragePayloadRedactor.php`
- `apps/platform/app/Services/TenantConfiguration/ClaimGuard.php`
- `apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php`
- `apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php`
- `apps/platform/app/Filament/Widgets/TenantConfiguration/CoverageV2ResourceTypesTable.php`
- `apps/platform/app/Filament/Widgets/TenantConfiguration/CoverageV2ResourceInstancesTable.php`
- New bounded helper files under `apps/platform/app/Services/TenantConfiguration/` if needed, such as `EntraComparablePayloadNormalizer.php`, `EntraCoverageComparator.php`, and `EntraRenderableSummaryBuilder.php`.
- Focused Spec 421 tests under `apps/platform/tests/Unit/Support/TenantConfiguration/`, `apps/platform/tests/Feature/TenantConfiguration/`, and `apps/platform/tests/Browser/` if rendered output changes.

## Domain / Model Implications

- No new database table, migration, persisted compare result table, or model is expected.
- `TenantConfigurationResourceEvidence.coverage_level` and existing CoverageLevel values can represent `comparable` / `renderable`.
- Registry defaults for Entra types must not imply broad support or customer claims. Promotion should be evidence-gated and internal.
- Derived compare importance labels must not become a persisted taxonomy.
- Raw payload remains an internal evidence storage boundary; render summaries use redacted/normalized data.

## Implementation Phases

### Phase 0 - Preflight And Evidence Matrix

Capture branch, HEAD, dirty state, activated skills, related completed-spec guardrail, and stop conditions. Verify current Coverage v2 service names and evidence availability for all draft Entra types. Record which types are content-backed, blocked, or deferred.

### Phase 1 - Tests First: Typed Semantics And Safety

Add focused Pest unit tests for Conditional Access normalization, deterministic compare, render summaries, volatile-field handling, redaction, and Claim Guard. Add evidence-gated tests for Security Defaults and optional types so missing evidence remains an explicit blocker.

### Phase 2 - Evidence-Gated Promotion

Implement or extend the narrow promotion path so only content-backed, typed-tested resource evidence can report comparable/renderable support. Do not promote any missing-evidence type.

### Phase 3 - Entra Typed Normalization

Add bounded typed normalization for Conditional Access and any evidence-backed optional type. Exclude volatile fields, preserve unsupported fields as diagnostics, and keep identity/source metadata separate.

### Phase 4 - Entra Compare

Add deterministic compare semantics for selected typed payloads. Classify changes, ignore volatile fields, handle redacted values, use stable ordering, and attach derived bounded importance labels.

### Phase 5 - Entra Render Summaries

Add operator-safe render summaries. Conditional Access summary must include state, targets, conditions, grant/session controls, claim/identity state, unsupported/redacted diagnostics, and last captured time without raw payload display.

### Phase 6 - Claim Guard, Product Surface, RBAC, And Evidence Boundaries

Extend Claim Guard tests for Entra wording, ensure read model/surface output stays internal and authorized, and confirm no customer output, restore/certification, direct Graph calls, or raw default payload rendering.

### Phase 7 - Browser Proof If Rendered

If rendered output changes, add focused browser proof for the existing Coverage v2 surface and inspect slide-over. Verify no console errors, no Livewire/Filament errors, no secrets/raw payload, and no restore/certify/customer-ready claim.

### Phase 8 - Validation And Implementation Report

Run focused validation, `git diff --check`, and complete the implementation report with matrices, Product Surface close-out, tests, browser/no-browser, deployment impact, no completed-spec rewrite assertion, and deferred work.

## Stop Conditions

- Security Defaults or optional Entra types need new capture/source contracts to become content-backed.
- Any implementation proposes restore/apply, certification, customer-facing output, Review Pack/report/PDF output, export/download, or broad coverage claims.
- A new OperationRun type, new capture start action, new route/navigation/dashboard, or new persisted compare table is proposed without amending the spec.
- Raw payloads, secrets, credentials, tokens, provider response bodies, or provider IDs become default-visible.
- `tenant_id` appears as Coverage v2 ownership truth.
- A separate Entra table family, engine, dashboard, or provider mini-platform appears.
- Render/compare performs Graph/TCM/provider/HTTP work at render time.

## Draft-To-Repo Deviation Handling

- The user draft's minimum `securityDefaults` promotion is changed to evidence-gated promotion because current repo truth does not prove content-backed evidence for Security Defaults and the draft forbids faking typed support or adding missing capture.
- The user draft's optional initial resource list remains as preflight candidates, not mandatory implementation scope.
- The implementation report must include a matrix explaining promoted and deferred types.