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

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

## Status

- Result: implementation loop completed; manual review findings fixed; final validation passed.
- Active spec directory: `specs/421-entra-core-comparable-renderable-pack`.
- Branch: `421-entra-core-comparable-renderable-pack`.
- HEAD at implementation start: `a73a8f58 feat: complete m365 generic evidence coverage pack (#487)`.
- Initial dirty state: active spec directory was untracked; no unrelated runtime files were dirty.
- Final dirty state: expected active spec, runtime, test, and implementation-report changes only.
- Historical specs: Specs 414, 415, 417, 418, 419, and 420 were used as read-only dependency context only. No files under those completed spec directories were modified or stripped of validation history.

## Activated Skills And Gates

- Activated skills: `spec-kit-implementation-loop`, `pest-testing`, `browsertest`.
- Repo gates applied: spec readiness, workspace scope safety, RBAC/action safety, evidence anchor contract, Product Surface, TCM cutover guard, and Filament/Livewire v5 change loop.
- Gate result before code: pass with bounded conditions.
- Hard-gate stop conditions: none hit. No new capture/source contract, restore/apply, certification, customer output, OperationRun type, route/navigation/action, persisted compare table, Entra table family, provider mini-platform, or `tenant_id` ownership path was introduced.
- Analysis/fix iterations: one implementation/test/fix iteration plus one post-review fix iteration. The focused unit run exposed a camelCase redaction gap for `privateKey`; `CoveragePayloadRedactor` was fixed to match compacted key forms. Manual review then exposed that typed render summaries were not hard-gated on same-scope content-backed captured renderable evidence and that compare output was not visible at runtime; both findings were fixed. A related Spec 420 runtime test was updated because Conditional Access evidence now correctly promotes from `content_backed` to `renderable`. Browser review later exposed a narrow-viewport clipping issue on the existing Coverage v2 readiness badge; the badge was made non-shrinking/nowrap and the focused browser smoke now asserts it remains fully inside the section. A follow-up browser review exposed redundant `Resource type` cell content; the default table now shows the human label only, with canonical technical values remaining in inspect details.

## Files Changed

- Runtime:
  - `apps/platform/app/Services/TenantConfiguration/ClaimGuard.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageEvidenceWriter.php`
  - `apps/platform/app/Services/TenantConfiguration/CoveragePayloadRedactor.php`
  - `apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php`
  - `apps/platform/app/Services/TenantConfiguration/EntraComparablePayloadNormalizer.php`
  - `apps/platform/app/Services/TenantConfiguration/EntraCoverageComparator.php`
  - `apps/platform/app/Services/TenantConfiguration/EntraRenderableSummaryBuilder.php`
  - `apps/platform/resources/views/filament/modals/tenant-configuration/coverage-v2-resource-inspect.blade.php`
- Existing test update:
  - `apps/platform/tests/Feature/TenantConfiguration/Spec420M365GenericEvidenceCaptureTest.php`
- New Spec 421 tests:
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraConditionalAccessNormalizerTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraComparableDiffTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraRenderableSummaryTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraRedactionTest.php`
  - `apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraClaimGuardTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec421EntraCoverageLevelPromotionTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec421EntraComparableRenderableTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoRestoreNoCertificationTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoTenantIdTest.php`
  - `apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoMiniPlatformTest.php`
  - `apps/platform/tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php`
- Spec artifacts:
  - `specs/421-entra-core-comparable-renderable-pack/tasks.md`
  - `specs/421-entra-core-comparable-renderable-pack/implementation-report.md`

## Implementation Summary

- Added bounded Entra typed helpers under the existing Tenant Configuration service boundary:
  - `EntraComparablePayloadNormalizer`
  - `EntraCoverageComparator`
  - `EntraRenderableSummaryBuilder`
- `conditionalAccessPolicy` is the only promoted type. It now receives deterministic typed normalization, compare output, operator-safe render summaries, and evidence-gated `CoverageLevel::Renderable` promotion when captured as content-backed evidence.
- `securityDefaults`, `application`, `servicePrincipal`, `roleDefinition`, and `administrativeUnit` remain unpromoted/deferred because current repo truth does not prove content-backed evidence for them without new capture/source-contract scope.
- Existing `CoveragePayloadRedactor` now also catches camelCase and separator-free sensitive key forms such as `privateKey`.
- `CoverageV2ReadinessReadModel::inspectDetails()` exposes a typed render summary only when latest evidence is same-scope, content-backed, captured, renderable, and supported by the bounded Entra summary builder.
- The existing Coverage v2 inspect slide-over now displays the safe Conditional Access summary and a bounded material-change compare summary while keeping raw payloads, previous/current raw compare values, source endpoints, provider response bodies, tokens, secrets, restore/certification/customer claims, and high-impact actions out of the default surface.

## Entra Evidence Matrix

| Canonical type | Current repo truth | Spec 421 result | Provider/render calls |
| --- | --- | --- | --- |
| `conditionalAccessPolicy` | Explicit Spec 420 content-backed source contract path exists | promoted to typed comparable/renderable when captured; coverage level `renderable` | capture remains existing path; render/compare are DB-only |
| `securityDefaults` | registry planning row only; no proven content-backed evidence | deferred/unpromoted | no provider/render call |
| `application` | registry planning row only; no proven content-backed evidence | deferred/unpromoted | no provider/render call |
| `servicePrincipal` | registry planning row only; no proven content-backed evidence | deferred/unpromoted | no provider/render call |
| `roleDefinition` | registry planning row only; no proven content-backed evidence | deferred/unpromoted | no provider/render call |
| `administrativeUnit` | registry planning row only; no proven content-backed evidence | deferred/unpromoted | no provider/render call |

## Normalizer / Compare / Render Proof

- Normalization:
  - Produces deterministic Conditional Access typed shape.
  - Ignores volatile Graph context, etag, created, and modified timestamps.
  - Sorts unordered scalar lists for stable compare.
  - Tracks unsupported field names and redacted field paths as diagnostics.
- Compare:
  - Emits classifications: `added`, `removed`, `changed`, `unchanged`, `ignored_volatile`, `redacted`, and `unsupported_field`.
  - Uses derived non-persisted importance labels: `critical`, `important`, `informational`.
  - Marks state changes critical; target/grant/session/condition changes important; volatile, unsupported, and redacted diagnostics informational.
- Render:
  - Shows Conditional Access display name, state, user/group/role/application targets, client/platform/location/risk conditions, grant controls, session controls, claim state, identity state, capture time, material compare status/field labels, unsupported fields, and redacted field names.
  - Does not render raw payload, raw Graph response, source endpoint, provider body, before/after compare values, tokens, credential values, private keys, authorization headers, cookies, or unneeded PII.

## Claim Guard, Redaction, And Safety Proof

- Claim Guard now permits only scoped internal operator wording for selected Entra comparable/renderable support.
- Claim Guard blocks certified, restore-ready, customer-ready, all-resource, full, and 100 percent Entra/M365 claims.
- Redaction tests prove render and compare output exclude secret values from credential-like keys, authorization headers, cookies, OperationRun diagnostic context, and audit metadata.
- `Spec421EntraNoRestoreNoCertificationTest` proves Conditional Access remains not restorable, not certified, and internal-only by registry default.
- `Spec421EntraNoTenantIdTest` proves the changed runtime files do not introduce `tenant_id`.
- `Spec421EntraNoMiniPlatformTest` proves this implementation did not add Spec 421 Entra-specific migrations, models, routes, or Filament resources.

## Product Surface Close-Out

- No-legacy posture: canonical Coverage v2 extension; no compatibility exception.
- UI Surface Impact: existing Coverage v2 technical annex / internal operator inspect surface changed.
- Product Surface Impact: existing rendered inspect slide-over now shows safe Conditional Access typed summary plus bounded material compare status.
- Page archetype: Technical Annex / internal operator evidence inspection surface.
- Surface budget: pass. No new page, route, navigation, action family, customer surface, report, export, or download was added.
- Technical Annex/deep-link demotion: raw payload, source endpoint, source keys, provider IDs, OperationRun context, and evidence internals remain secondary/diagnostic; raw payload values are not default-visible.
- Canonical status vocabulary: existing Coverage v2 labels only; no `Entra covered`, certified, restore-ready, customer-ready, full coverage, or 100 percent labels.
- Product Surface exceptions: none.
- Human Product Sanity: pass. The inspect modal answers what the selected Conditional Access policy is, whether it is enabled, who/apps it targets, what controls apply, whether material changes exist versus prior comparable evidence, and which diagnostics are unsupported/redacted without implying certification, restore, or customer proof.
- Visible complexity outcome: decreased for selected Conditional Access evidence because operators no longer need to infer meaning from raw payloads.

## Browser Proof

- Browser proof required: yes, rendered Coverage v2 output changed.
- Focused path: existing Coverage v2 readiness route for a seeded workspace and managed environment with prior comparable Conditional Access evidence and latest content-backed renderable evidence.
- Test: `apps/platform/tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php`.
- Result: passed.
- Verified:
  - page loads in `/admin` workspace/managed-environment context
  - Conditional Access row is visible with `Renderable` and `Internal only`
  - inspect slide-over opens from the existing primary link column
  - typed summary shows display name, state, users, applications, grant controls, compare summary, material change field label, redacted fields
  - no raw secrets, certified/restore-ready/customer-ready/full/100 percent Entra claims, high-impact actions, console errors, JavaScript errors, or Graph/TCM/provider network calls during render

## Filament v5 Output Contract

- Livewire v4.0+ compliance: unchanged; the existing Filament v5/Livewire v4 surface is exercised by the focused browser test.
- Provider registration location: no panel/provider registration changed. Laravel 12 providers remain under `apps/platform/bootstrap/providers.php`.
- Global search: no Filament Resource global-search behavior changed; no new Resource was added.
- Destructive/high-impact actions: none added or changed. No restore/apply/capture/export/certify action was introduced.
- Asset strategy: no assets registered and no frontend bundles changed. `php artisan filament:assets` is not newly required beyond existing deployment practice.
- Testing plan: unit, feature, related regression, and browser lanes were run.

## Validation Commands

- `cd apps/platform && ./vendor/bin/sail php -l app/Services/TenantConfiguration/EntraComparablePayloadNormalizer.php` - passed.
- `cd apps/platform && ./vendor/bin/sail php -l app/Services/TenantConfiguration/EntraCoverageComparator.php` - passed.
- `cd apps/platform && ./vendor/bin/sail php -l app/Services/TenantConfiguration/EntraRenderableSummaryBuilder.php` - passed.
- `cd apps/platform && ./vendor/bin/sail php -l app/Services/TenantConfiguration/CoverageEvidenceWriter.php` - passed.
- `cd apps/platform && ./vendor/bin/sail php -l app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php` - passed.
- `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 tests/Feature/TenantConfiguration/Spec421EntraCoverageLevelPromotionTest.php tests/Feature/TenantConfiguration/Spec421EntraComparableRenderableTest.php tests/Feature/TenantConfiguration/Spec421EntraNoRestoreNoCertificationTest.php tests/Feature/TenantConfiguration/Spec421EntraNoTenantIdTest.php tests/Feature/TenantConfiguration/Spec421EntraNoMiniPlatformTest.php` - passed, 24 tests / 98 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php` - passed, 1 test / 52 assertions.
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - passed.
- `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 tests/Feature/TenantConfiguration/Spec421EntraCoverageLevelPromotionTest.php tests/Feature/TenantConfiguration/Spec421EntraComparableRenderableTest.php tests/Feature/TenantConfiguration/Spec421EntraNoRestoreNoCertificationTest.php tests/Feature/TenantConfiguration/Spec421EntraNoTenantIdTest.php tests/Feature/TenantConfiguration/Spec421EntraNoMiniPlatformTest.php tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php` - passed, 25 tests / 150 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/Spec415CoverageRedactionTest.php tests/Unit/Support/TenantConfiguration/Spec415GenericPayloadNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec417CoverageIdentityStrategyRegistryTest.php tests/Unit/Support/TenantConfiguration/Spec420M365GenericPayloadNormalizerTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureClaimGuardTest.php tests/Unit/Support/TenantConfiguration/Spec420M365CaptureRedactionTest.php tests/Feature/TenantConfiguration/Spec415GenericContentBackedCaptureTest.php tests/Feature/TenantConfiguration/Spec420M365GenericEvidenceCaptureTest.php tests/Feature/TenantConfiguration/Spec420M365NoOverclaimTest.php tests/Browser/Spec420M365GenericEvidenceOperatorSurfaceSmokeTest.php` - passed, 23 tests / 248 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec420M365GenericEvidenceCaptureTest.php tests/Feature/Filament/CoverageV2ReadinessPageTest.php` - passed, 12 tests / 189 assertions.
- `git diff --check` - passed.
- Post-browser-comment validation: focused integrated-browser check at narrow viewport confirmed the `Ready` badge rendered as full text within the Activation readiness section; `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php` passed, 1 test / 53 assertions.
- Post-resource-type-redundancy validation: the Resource instances table now omits the redundant canonical type line from the default `Resource type` cell while keeping canonical type available in inspect details; the focused browser smoke asserts this table-cell behavior.

## Deployment Impact

- Migrations: none.
- Environment variables: none.
- Queue/cron: no new queue or scheduled work; existing capture path remains unchanged.
- Storage/volumes: none.
- Assets: none.
- Dokploy/staging: deploy as ordinary app code/test/view change. Staging validation should include the focused Coverage v2 inspect path before production promotion.
- Rollback: revert code/view/test changes. No data migration or compatibility step required.

## Deferred Work And Residual Risk

- Deferred by spec: Security Defaults content-backed capture/source contract, application/service principal comparable/renderable pack, role definition and administrative unit comparable/renderable pack, certified compare, restore/apply, customer reports, Review Pack output, exports/downloads, and broad M365/Entra claims.
- Residual risk: this proves deterministic typed semantics for captured Conditional Access payloads in the existing internal Coverage v2 path; it does not certify real Microsoft tenant-wide Entra coverage.
- Remaining in-scope findings: none after the focused test/fix loop.