TenantAtlas/specs/414-tcm-first-coverage-core-cutover/plan.md

# Implementation Plan: Spec 414 - TCM-First Coverage v2 Kernel

**Branch**: `414-tcm-first-coverage-core-cutover` | **Date**: 2026-06-25 | **Spec**: `specs/414-tcm-first-coverage-core-cutover/spec.md`
**Input**: Patched feature specification from `/specs/414-tcm-first-coverage-core-cutover/spec.md`

## Summary

Introduce the inactive Coverage v2 kernel required for later hard cutover. This slice adds value families, minimal persistence, initial resource type registry, supported-scope contract, source-class model, claim guard, provider provenance rules, and focused tests.

Coverage v2 is not activated as customer-facing or operator-facing truth in this spec. Existing v1 runtime coverage remains active until a later explicit cutover spec. No v1-to-v2 compatibility adapter, dual write, fallback reader, old snapshot promotion, or customer-facing dual truth is allowed.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, PostgreSQL via Laravel Sail/Dokploy
**Storage**: PostgreSQL; JSONB for supported-scope denominator lists and metadata only where the kernel needs structured definitions, plus optional evidence/resource payloads only if those optional tables are introduced
**Testing**: Pest unit/feature tests; PostgreSQL lane when schema constraints or JSONB behavior require it
**Validation Lanes**: fast-feedback, confidence, pgsql when needed
**Target Platform**: Laravel monolith in `apps/platform`
**Project Type**: web application / backend kernel only for this slice
**Performance Goals**: registry/scope/claim guard evaluation is deterministic and local; no remote/provider calls
**Constraints**: inactive kernel only, no rendered UI changes, no `tenant_id`, same-scope `provider_connection_id`, no compatibility shims, no Graph/TCM calls, no OperationRun-producing workflow by default
**Scale/Scope**: initial required resource type entries and supported-scope contract only; catalog expansion and activation deferred

## 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/domain-kernel only.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: future activation will touch status/evidence/report families; this spec does not.
- **State layers in scope**: domain kernel state only.
- **Audience modes in scope**: N/A.
- **Decision/diagnostic/raw hierarchy plan**: N/A for rendered UI.
- **Raw/support gating plan**: N/A.
- **One-primary-action / duplicate-truth control**: no UI action introduced; Coverage v2 must not become parallel product truth.
- **Handling modes by drift class or surface**: hard-stop if runtime UI changes are needed before spec amendment.
- **Repository-signal treatment**: old v1 runtime terms are context only; broad removal is deferred.
- **Special surface test profiles**: `N/A - no rendered UI surface changed`.
- **Required tests or manual smoke**: unit and feature tests for kernel behavior.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Kernel / No UI / No dual truth.
- **UI/Productization coverage decision**: No UI surface impact.
- **Coverage artifacts to update**: none.
- **No-impact rationale**: the spec creates inactive persistence/services only.
- **Navigation / Filament provider-panel handling**: no panel provider or navigation change.
- **Screenshot or page-report need**: no.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: inactive kernel plus later hard cutover; no compatibility adapter.
- **Page archetype and surface budget plan**: N/A - no rendered product surface changed.
- **Technical Annex and deep-link demotion plan**: N/A.
- **Canonical status vocabulary plan**: N/A for rendered UI.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: workflow sanity in implementation report; no rendered-page review.
- **Visible complexity outcome target**: neutral; no visible product surface change.
- **Implementation report target**: `specs/414-tcm-first-coverage-core-cutover/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire 4.1.4 confirmed. No Livewire UI changes planned.
- **Panel provider registration location**: no panel provider change. Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Filament resource/global search change planned.
- **Destructive/high-impact action posture**: no destructive or high-impact action introduced.
- **Asset strategy**: no new assets; `filament:assets` not required by this spec.
- **Testing plan**: unit tests for fixed value families/registry/scope/claim guard; feature tests for deterministic upsert-safe platform-seeded definitions, persistence seed/defaults, claim guard behavior, same-scope provider connection validation where optional concrete tables store `provider_connection_id`, and no-`tenant_id` schema proof.
- **Deployment impact**: migrations for required kernel tables; no env vars, queue worker requirement, scheduler change, storage volume change, or asset deployment step by default.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, but kernel-only.
- **Systems touched**: new Coverage v2 domain namespace, migrations/models/factories for required kernel tables, registry/scope/claim services.
- **Shared abstractions reused**: Laravel models/migrations/factories, existing workspace and managed-environment relationships, existing provider connection model, Pest conventions.
- **New abstraction introduced? why?**: ResourceTypeRegistry, SupportedScopeResolver, and ClaimGuard are introduced because supported-scope and claim boundaries must be deterministic before UI/runtime activation.
- **Why the existing abstraction was sufficient or insufficient**: v1 inventory/baseline coverage abstractions remain active but cannot express Coverage v2 source class, beta/fallback inclusion, exact scope claims, or no-`tenant_id` ownership.
- **Bounded deviation / spread control**: v2 kernel must not be consumed by product surfaces until later activation spec.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

No remote TCM/Graph capture is implemented in Spec 414. No OperationRun-producing workflow is introduced unless a future amendment adds an operational command/job. OperationRun-backed capture/evaluation is deferred to Generic Content-Backed Capture.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Microsoft TCM source class, Graph v1 fallback source class, Graph beta experimental source class, provider-native IDs as source metadata.
- **Platform-core seams**: resource type, source class, workload, resource class, support state, coverage level, evidence state, identity state, claim state, supported scope.
- **Neutral platform terms / contracts preserved**: provider, source class, managed environment, supported scope, claim guard.
- **Retained provider-specific semantics and why**: `tcm`, `graph_v1_fallback`, and `graph_beta_experimental` remain because this is a TCM-first kernel.
- **Bounded extraction or follow-up path**: follow-up specs own catalog expansion, identity engine, capture, and activation.

## Constitution Check

*GATE: Must pass before implementation. Re-check after design.*

- Inventory-first / snapshots-second: PASS. This spec creates inactive registry/scope kernel, not active snapshot truth.
- Read/write separation: PASS. No remote write/change action.
- Single Graph contract path: PASS. No Graph calls in this spec.
- Deterministic capabilities: PASS. Claim/scope rules are deterministic and test-backed.
- Proportionality: PASS. The previous full cutover was too broad; this patch narrows to minimum kernel.
- No premature abstraction: PASS with justified exception. Registry/scope/claim guard are required for claim safety before activation.
- Persisted truth: PASS. Required tables represent kernel source-of-truth definitions, not UI convenience.
- Behavioral state: PASS. States affect future claim eligibility and testable guard behavior.
- UI semantics: PASS. No UI framework or rendered UI changes.
- Product Surface Contract: PASS. No runtime UI surface impact; stop-and-amend rule applies.
- Workspace isolation: PASS. Kernel ownership uses `workspace_id` and `managed_environment_id` where environment-owned records exist.
- Tenant isolation: PASS in current terminology; no `tenant_id` ownership column is introduced.
- Provider boundary: PASS. Provider-native tenant/directory/account IDs stay metadata only.
- OperationRun UX: PASS. No OperationRun workflow introduced.
- Test governance: PASS. Unit/feature/pgsql lanes are sufficient for kernel behavior.
- LEAN-001: PASS. No compatibility shim, fallback reader, dual write, or legacy alias.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for pure kernel decisions; Feature for persistence/seed/schema/scope behavior; PostgreSQL for JSONB/composite constraint proof when needed.
- **Affected validation lanes**: fast-feedback, confidence, pgsql when schema adds JSONB fields, composite foreign keys, partial unique indexes, same-scope provider constraints, or other PostgreSQL-specific behavior.
- **Why this lane mix is the narrowest sufficient proof**: no rendered UI, browser, OperationRun, or remote provider workflow exists in this slice.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest -c phpunit.pgsql.xml tests/Feature/TenantConfiguration` if migrations add JSONB fields, composite foreign keys, partial unique indexes, same-scope provider constraints, or other PostgreSQL-specific behavior
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: new Coverage v2 factories must stay opt-in.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none by default.
- **Surface-class relief / special coverage rule**: `N/A - no rendered UI surface changed`.
- **Closing validation and reviewer handoff**: verify no UI wiring, no `tenant_id`, no v1 translator, no compatibility shim, correct source classes, exact scope claim guard, same-scope provider connection validation.
- **Budget / baseline / trend follow-up**: document in implementation report if test runtime materially increases.
- **Review-stop questions**: did kernel stay inactive; did scope creep into UI/capture/legacy removal; did provider-native ID become ownership truth.
- **Escalation path**: document-in-feature.
- **Active feature PR close-out entry**: Kernel / No UI / No dual truth.
- **Why no dedicated follow-up spec is needed**: this spec is the prerequisite kernel. Activation/capture/cutover follow-ups are listed separately.

## Project Structure

### Documentation (this feature)

```text
specs/414-tcm-first-coverage-core-cutover/
├── checklists/requirements.md
├── plan.md
├── spec.md
└── tasks.md
```

### Source Code (repository root)

Likely implementation surfaces:

```text
apps/platform/app/Support/TenantConfiguration/
├── ClaimState.php
├── CoverageLevel.php
├── EvidenceState.php
├── IdentityState.php
├── ResourceClass.php
├── SourceClass.php
├── SupportState.php
└── Workload.php

apps/platform/app/Services/TenantConfiguration/
├── ClaimGuard.php
├── ResourceTypeRegistry.php
└── SupportedScopeResolver.php

apps/platform/app/Models/
├── TenantConfigurationResourceType.php
└── TenantConfigurationSupportedScope.php

apps/platform/database/migrations/
└── *_create_tenant_configuration_kernel_tables.php

apps/platform/database/factories/
└── TenantConfiguration*.php

apps/platform/tests/Unit/Support/TenantConfiguration/
apps/platform/tests/Feature/TenantConfiguration/
```

Optional only if implementation proves they are needed for tests or clean service boundaries:

```text
apps/platform/app/Models/TenantConfigurationResource.php
apps/platform/app/Models/TenantConfigurationResourceEvidence.php
```

**Structure Decision**: Use existing Laravel monolith conventions. No new base folder outside established `app/Support`, `app/Services`, `app/Models`, `database`, and `tests` structure.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| New kernel persistence | Registry/scope definitions must be queryable and testable before activation | Config-only definitions would not prove schema ownership and provider provenance |
| New enum/state families | Claim guard needs explicit behavioral boundaries | Reusing v1 gap terms would preserve wrong semantics |
| New registry/scope/claim services | Exact scope claims must be programmatically blocked or allowed | UI copy rules cannot prevent future overclaims |

## Proportionality Review

- **Current operator problem**: later Coverage v2 activation must not overclaim customer coverage.
- **Existing structure is insufficient because**: v1 coverage does not encode source class, exact supported scope, beta/fallback rules, or claim guard eligibility.
- **Narrowest correct implementation**: inactive value families, required kernel tables, initial registry entries, supported-scope resolver, claim guard, tests.
- **Ownership cost created**: domain namespace, migrations/models, services, factories, tests, implementation report.
- **Alternative intentionally rejected**: full cutover in Spec 414; v1-to-v2 compatibility mapping; label-only UI rewrite.
- **Release truth**: current-release kernel needed before later activation.

## Implementation Phases

### Phase 0 - Preflight

- Capture branch, HEAD, and dirty state.
- Confirm constitution ownership alignment.
- Confirm only active spec artifacts were patched during preparation.
- Confirm no UI/capture/OperationRun/legacy-removal scope remains in Spec 414 implementation tasks.

### Phase 1 - Kernel Value Families

- Add value objects/enums for source class, workload, resource class, support state, coverage level, evidence state, identity state, claim state, and restore tier only if needed for claim guard.
- Keep allowed values fixed to the spec-defined kernel list: source classes `tcm`, `graph_v1_fallback`, `graph_beta_experimental`; workload `intune`; resource class `configuration`; and the explicitly listed support, coverage, evidence, identity, claim, and optional restore-tier values.
- Keep labels internal/domain-level, not product-facing UI vocabulary.

### Phase 2 - Minimal Kernel Persistence

- Add required kernel tables: `tenant_configuration_resource_types` and `tenant_configuration_supported_scopes`.
- Treat required kernel tables as platform-seeded definition tables, not workspace/environment/provider-connection-owned records.
- Enforce deterministic uniqueness: `(canonical_type, source_class)` for resource types and `scope_key` for supported scopes.
- Keep seed/migration behavior upsert-safe so re-running the kernel setup cannot duplicate definitions.
- Add optional resource/evidence tables only if implementation proves they are needed for tests or clean service boundaries.
- Enforce no `tenant_id`.
- Enforce `workspace_id` and `managed_environment_id` where environment-owned rows exist.
- Enforce same-scope `provider_connection_id` where provider provenance is stored in optional concrete resource/evidence rows; required kernel definition tables must not store `provider_connection_id`.

### Phase 3 - Initial Registry And Supported Scope

- Seed required initial resource type entries.
- Classify TCM, Graph v1 fallback, and Graph beta experimental source classes.
- Add supported-scope denominator/minimum-level rules.
- Exclude beta by default and include fallback only when allowed by scope.

### Phase 4 - Claim Guard

- Block unscoped 100% claims.
- Block beta certification by default.
- Block restore claims where resource type is not restorable.
- Block customer-facing claims for incomplete supported scopes.
- Allow only exact scope + level claims.

### Phase 5 - Tests And Validation

- Add focused unit tests.
- Add focused feature tests.
- Add PostgreSQL-specific tests when schema constraints or JSONB require PostgreSQL proof.
- Write implementation report.
- Run Pint, focused tests, optional pgsql lane, and `git diff --check`.

## Rollout And Deployment Considerations

- Staging validation is mandatory before production.
- Migrations introduce inactive kernel tables only.
- No env vars are planned.
- No queue worker, scheduler, storage volume, or asset deployment change is planned.
- No `filament:assets` requirement unless a future amendment adds registered assets.
- Supply-chain remediation, if still open, remains a release/pilot gate outside this spec.

## Risk Controls

- Stop if implementation requires rendered UI changes.
- Stop if implementation requires remote TCM/Graph capture.
- Stop if implementation requires OperationRun-backed evaluation.
- Stop if `tenant_id` appears in Coverage v2 ownership fields.
- Stop if v1-to-v2 compatibility adapter, dual write, or fallback reader appears.
- Stop if old gap taxonomy becomes Coverage v2 runtime truth.