TenantAtlas/specs/417-canonical-identity-engine/implementation-report.md

# Implementation Report: Spec 417 - Canonical Identity Engine

## Preflight

- Branch: `417-canonical-identity-engine`
- Starting HEAD: `332f6325 feat: add tenantpilot agent skill layer v1 (#483)`
- Starting dirty state: `specs/417-canonical-identity-engine/` untracked as the active spec artifact set.
- Dirty-state assessment: active Spec 417 preparation artifacts only; no runtime code was dirty before implementation.
- Activated skills: `spec-kit-implementation-loop`, `pest-testing`, `tenantpilot-spec-readiness-gate`, `tenantpilot-workspace-scope-safety`, `tenantpilot-evidence-anchor-contract`, `tenantpilot-tcm-cutover-guard`.
- Hard-gate stop conditions before implementation: none observed. Coverage v2 remains inactive; no UI/customer proof surface is in scope.

## Dependency Context

- Spec 414: completed/validated context only; not modified.
- Spec 415: completed/validated context only; not modified.
- Existing canonical identity storage: `tenant_configuration_resources.canonical_resource_key` remains the single persisted canonical key truth.
- Browser proof decision: `N/A - no rendered UI surface changed`.

## Implementation Summary

- Added a bounded canonical identity engine for the initial eight Coverage v2 resource types.
- Added `CanonicalKeyKind` values without display-name/name-only stable key kinds.
- Added identity strategy, resolver, secondary-key, diagnostics, and same-scope conflict evaluation services under `App\Services\TenantConfiguration`.
- Extended `tenant_configuration_resources` with additive identity metadata: `canonical_key_kind`, `identity_strategy`, `source_identity`, `secondary_identity_keys`, `identity_diagnostics`, and `identity_evaluated_at`.
- Kept `canonical_resource_key` as the single persisted canonical key truth; no `canonical_key` column or duplicate key truth was added.
- Updated `CoverageResourceUpserter` to consume resolver/evaluator output instead of hardcoding `id`/`sourceId`.
- Updated `CoverageEvidenceWriter` to preserve resource identity/claim state instead of resetting to resource-type defaults.
- Updated `ClaimGuard` to block `identity_conflict`, `missing_external_id`, and `unsupported_identity`, and to limit/block `derived` identity unless explicitly allowed.
- Kept Coverage v2 inactive; no UI, route, navigation, report, review, restore, customer-output, or browser-visible activation was added.

## Identity Strategy Matrix

| Canonical type | Strategy | Stable ID posture | Derived/experimental posture | Default claim consequence |
| --- | --- | --- | --- | --- |
| `deviceAndAppManagementAssignmentFilter` | `tcm.assignment_filter.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `deviceEnrollmentLimitRestriction` | `tcm.device_enrollment_limit_restriction.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `deviceEnrollmentPlatformRestriction` | `tcm.device_enrollment_platform_restriction.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `deviceEnrollmentStatusPageWindows10` | `tcm.device_enrollment_status_page_windows10.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `appProtectionPolicyAndroid` | `tcm.app_protection_policy_android.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `appProtectionPolicyiOS` | `tcm.app_protection_policy_ios.v1` | TCM/provider IDs stable | source/derived composite allowed | derived limited |
| `notificationMessageTemplate` | `graph.notification_message_template.v1` | Graph/template IDs stable | source/derived composite allowed | no certification by default |
| `roleScopeTag` | `graph_beta.role_scope_tag.v1` | beta IDs are experimental, not stable proof | experimental source key resolves as derived | internal-only by default |

## Schema And Persistence

- Migration added: `apps/platform/database/migrations/2026_06_26_000417_extend_tenant_configuration_resource_identity.php`.
- Added PostgreSQL check constraint for `canonical_key_kind`.
- Added PostgreSQL JSONB object constraints for `source_identity`, `secondary_identity_keys`, and `identity_diagnostics`.
- Added targeted indexes for scope/type/identity-state and resource-type/key-kind lookup paths.
- No speculative JSONB GIN index was added.
- Tombstone behavior is deferred; no tombstone field or active delete/drift workflow is implemented in this slice.

## Scope, Claim, And Evidence Safety

- Scope tuple remains `workspace_id`, `managed_environment_id`, `provider_connection_id`, `resource_type_id`, and `canonical_resource_key`.
- Provider connections are still validated against the same workspace and managed environment before upsert/capture.
- Stable ID rename updates the same same-scope resource row.
- Duplicate display names with different stable IDs remain separate rows.
- Display-name-only payloads resolve to `missing_external_id`, not `stable`; repeated same-scope display-only observations are promoted to `identity_conflict` instead of merging by secondary/display fingerprint.
- Unsupported identity observations are promoted to `identity_conflict` on same-scope fallback-key collision instead of merging by unsupported fallback key.
- Same-scope unsafe derived identity collisions mark existing/incoming resources as `identity_conflict` and `claim_blocked`.
- Cross-workspace, cross-managed-environment, and cross-provider resources do not merge because the existing scope tuple remains part of identity uniqueness.
- Diagnostics and secondary keys are redacted and bounded; no raw provider payloads, tokens, secrets, cookies, authorization headers, private keys, certificates, or full provider response dumps are persisted in identity diagnostics.
- No fallback-to-latest evidence path, v1-to-v2 adapter, dual-write path, old snapshot promotion, or old v1 gap taxonomy was introduced.

## Product Surface Close-Out

- UI Surface Impact: none.
- Product Surface Impact: `N/A - no rendered product surface changed`.
- Browser smoke result: `N/A - no rendered UI surface changed`.
- Human Product Sanity: `N/A - no product surface changed`; visible complexity outcome is neutral.
- Livewire v4 compliance: Livewire v4 baseline unchanged; no Livewire code changed.
- Provider registration location: no panel provider change; Laravel 12 providers remain in `apps/platform/bootstrap/providers.php`.
- Global search posture: no Filament resource/global search change.
- Destructive/high-impact actions: none added.
- Asset strategy: no assets registered; `filament:assets` is not required by this spec.
- No completed historical spec was rewritten or stripped of validation, task, smoke, browser, or review history.

## Validation

- PASS: `php -l` syntax sweep for tracked and untracked changed PHP files.
- PASS: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec417` (24 passed, 1 PostgreSQL-only skipped, 162 assertions).
- PASS: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration` (35 passed, 170 assertions).
- PASS: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration` (35 passed, 8 PostgreSQL-only skipped, 190 assertions).
- PASS: `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml tests/Feature/TenantConfiguration` (43 passed, 203 assertions).
- PASS: `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- PASS: `git diff --check`.
- PASS: untracked-file trailing-whitespace scan.

## Analysis And Fix Loop

- Iteration 1 finding: secondary-key and diagnostics builders redacted nested values without preserving key context, so sensitive scalar fields were not redacted. Fixed by redacting with field-name context; regression tests pass.
- Iteration 2 finding: PostgreSQL JSONB object constraints rejected empty PHP arrays encoded as `[]`. Fixed by normalizing empty metadata/defaults to JSON objects; PostgreSQL lane passes.
- Post-implementation scope finding: optional tombstone timestamp was unnecessary without tombstone behavior. Fixed by removing the unused field and documenting tombstone deferral.
- Manual final-review finding: repeated same-scope display-name-only payloads and unsupported identity observations could merge by fallback candidate keys even though they were not marked stable. Fixed by treating repeated `missing_external_id` and `unsupported_identity` candidate collisions as `identity_conflict`, marking existing candidates `claim_blocked`, generating a separate conflict key for the new unsafe observation, normalizing empty `source_metadata` to JSON object form, and adding feature regressions for both paths.
- Remaining confirmed in-scope findings: none.

## Files Changed

- `apps/platform/app/Models/TenantConfigurationResource.php`
- `apps/platform/app/Services/TenantConfiguration/CanonicalIdentityResolver.php`
- `apps/platform/app/Services/TenantConfiguration/CanonicalIdentityResult.php`
- `apps/platform/app/Services/TenantConfiguration/ClaimGuard.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageEvidenceWriter.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageResourceIdentityEvaluator.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageResourceUpserter.php`
- `apps/platform/app/Services/TenantConfiguration/CoverageSecondaryKeyBuilder.php`
- `apps/platform/app/Services/TenantConfiguration/IdentityConflictDiagnosticsBuilder.php`
- `apps/platform/app/Support/TenantConfiguration/CanonicalKeyKind.php`
- `apps/platform/database/factories/TenantConfigurationResourceFactory.php`
- `apps/platform/database/migrations/2026_06_26_000417_extend_tenant_configuration_resource_identity.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec417CanonicalIdentityPersistenceTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec417CoverageResourceIdentityUpsertTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec417IdentityClaimGuardFeatureTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec417IdentityConflictScopeTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec417IdentityNoLegacyNoUiActivationTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/ClaimGuardTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec417CanonicalIdentityResolverTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec417CoverageIdentityStrategyRegistryTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec417CoverageSecondaryKeyBuilderTest.php`
- `apps/platform/tests/Unit/Support/TenantConfiguration/Spec417IdentityConflictDiagnosticsTest.php`
- `specs/417-canonical-identity-engine/implementation-report.md`
- `specs/417-canonical-identity-engine/tasks.md`

## Deployment Impact

- Migrations: yes, additive identity metadata/check constraints/indexes on `tenant_configuration_resources`.
- Environment variables: none.
- Queues/workers: no new queue or OperationRun path.
- Scheduler: no change.
- Storage/volumes: no change.
- Assets: no change.
- Staging/production: run migrations before any later Coverage v2 activation; validate PostgreSQL migration in staging.

## Deferred Work

- Tombstone/delete workflow remains out of scope.
- Customer/operator identity diagnostics UI remains out of scope.
- Coverage v2 activation, legacy cutover/removal, compare/render/restore/report/customer claims remain future specs.

## Final Gate Result

- Spec Readiness Gate: PASS.
- Implementation Scope Gate: PASS.
- Test Gate: PASS.
- Browser Smoke Test Gate: PASS as not applicable, `N/A - no rendered UI surface changed`.
- Post-Implementation Analysis Gate: PASS.
- Merge Readiness Gate: PASS; ready for manual review/merge.