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

# Feature Specification: Spec 414 - TCM-First Coverage v2 Kernel

**Feature Branch**: `414-tcm-first-coverage-core-cutover`
**Created**: 2026-06-25
**Status**: Draft / Ready for implementation preparation review
**Input**: User-provided patch prompt narrowing Spec 414 from a full runtime/UI cutover into an inactive Coverage v2 kernel slice.

## Repo-Truth Adjustment

The previous Spec 414 preparation correctly identified a P0 product-truth risk: TenantPilot has multiple overlapping coverage and gap concepts that can overstate evidence completeness, supported scope, and customer-facing claims. The implementation-readiness gate then correctly stopped before code changes because the original scope required a full cross-cutting cutover in one loop: new persisted tables, state families, OperationRun-backed evaluation, multiple UI/customer surface migrations, legacy runtime/test deletion, browser proof, and full validation.

This patched Spec 414 keeps the strategic hard-cutover direction, but narrows the current implementation to the inactive Coverage v2 kernel needed for later activation.

Coverage v2 may be persisted and tested after this spec, but it must not be presented as active customer-facing proof and must not replace existing baseline, evidence, review, report, restore, provider-readiness, or operator proof surfaces yet.

## Kernel Slice Decision

Spec 414 is intentionally narrowed to the Coverage v2 kernel.

This spec does not complete the full runtime cutover. It creates the provider-agnostic Coverage v2 foundation that later specs will activate.

Coverage v2 is not yet the active customer-facing or operator-facing coverage truth. Coverage v1 remains the active runtime truth until a later explicit activation/cutover spec.

The no-legacy rule still applies:

- no v1-to-v2 compatibility adapter
- no dual writes
- no fallback readers
- no old snapshot promotion into v2 proof
- no old gap taxonomy as v2 runtime truth
- no customer-facing dual truth

Coverage v2 may exist after Spec 414, but it must not be wired into customer-facing claims or active operator proof surfaces as a parallel truth. Any visible surface exposure in this spec must be internal/dev-only or absent.

## Candidate Selection Gate

- **Selected candidate**: Spec 414 - TCM-First Coverage v2 Kernel.
- **Source**: Direct user patch prompt for active `specs/414-tcm-first-coverage-core-cutover/`.
- **Why selected**: This kernel is the smallest safe first slice after the full-cutover readiness gate failed on scope size.
- **Roadmap relationship**: This is the foundation for later Coverage v2 activation, content-backed capture, identity hardening, operator UI, legacy removal, certification, and pilot readiness.
- **Completed-spec guardrail result**: Specs 382 and 383 remain completed historical dependency context only. This spec must not rewrite completed specs.
- **Smallest viable implementation slice**: Add inactive Coverage v2 value families, minimal persistence, initial resource type registry, supported-scope contract, claim guard, and focused unit/feature tests.
- **Gate result**: PASS after narrowing. The active slice is implementable without creating a partial second customer-facing truth.

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: TenantPilot needs a canonical Coverage v2 denominator and claim-safety model before it can safely replace active coverage/gap semantics.
- **Today's failure**: The full cutover cannot be safely implemented in one loop without creating partial dual truth.
- **User-visible improvement**: This spec does not change user-visible surfaces. It creates tested kernel truth so later specs can activate Coverage v2 without inventing persistence and claim rules at the same time.
- **Smallest enterprise-capable version**: Value families, resource type registry, supported scopes, source-class defaults, claim guard, provider provenance rules, and focused tests.
- **Explicit non-goals**: No UI cutover, no customer-facing claims, no OperationRun-backed capture/evaluation, no TCM/Graph remote capture, no generic content-backed evidence capture, no legacy runtime deletion, no browser proof unless UI changes are introduced by amendment.
- **Permanent complexity imported**: Coverage v2 enum/value families, minimal persistence, registry/scope/claim services, seed/default registry entries, and tests.
- **Why now**: Later activation cannot safely block overclaiming unless the kernel rules exist first.
- **Why not local**: A local label patch would preserve the old denominator and would not enforce source class, supported scope, beta exclusion, fallback inclusion, provider provenance, or claim boundaries.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: New persisted truth, new enum/status families, registry/resolver/claim guard services. Defense: the kernel is inactive, bounded, and intentionally avoids UI/runtime activation.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve as an inactive kernel slice.

## Problem Statement

TenantPilot needs a Coverage v2 kernel that can answer:

> Which tenant configuration resource type is in supported scope, from which source class, at what minimum coverage level, and what claims are allowed?

Spec 414 must not yet answer that question on customer-facing or active operator surfaces. It must only create the tested kernel that later activation specs can use.

## Business / Product Value

- Prevents later Coverage v2 activation from mixing persistence, claim rules, UI migration, and legacy removal in one unsafe change.
- Establishes source-class and supported-scope truth before customer claims are rendered.
- Blocks unsafe claim semantics such as unscoped 100%, beta certification, unsupported restore-readiness, and incomplete-scope claims at the kernel level.
- Preserves the hard-cutover strategy without adding legacy compatibility shims.

## Primary Users / Operators

- Release reviewer validating that Coverage v2 is safe to activate later.
- Platform engineer implementing Coverage v2 persistence and claim guard.
- MSP/operator and customer-safe reviewers are downstream beneficiaries, but no visible workflow changes in this slice.

## Spec Scope Fields *(mandatory)*

- **Scope**: inactive Coverage v2 kernel under workspace and managed-environment boundaries.
- **Primary Routes**: none. No reachable runtime UI surface is changed by default.
- **Data Ownership**: Coverage v2 kernel ownership truth is `workspace_id` plus `managed_environment_id` where environment-owned records are introduced. `provider_connection_id` is used where provider-sourced provenance, permission context, capture source, provider isolation, or execution identity depends on a concrete provider connection.
- **RBAC**: No new UI or mutation endpoint is introduced by default. The platform-seeded definition models are not exposed through a route, Filament resource, API, or mutation surface in this inactive slice, so no policy is introduced in Spec 414. Any later activation or reachable surface must add explicit policy/authorization coverage before exposure. If implementation unexpectedly adds an operational command/action, stop and update spec/plan/tasks before continuing.

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: N/A - no canonical view or rendered surface is introduced.
- **Explicit entitlement checks preventing cross-tenant leakage**: Kernel persistence and tests must enforce workspace and managed-environment scope. Same-scope provider connection validation is required when `provider_connection_id` is stored.

## Ownership Correction

Coverage v2 required internal scope fields use:

- `workspace_id`
- `managed_environment_id`
- `provider_connection_id` where provider-sourced or provenance-specific

Coverage v2 must not introduce `tenant_id` as an ownership key, compatibility alias, fallback reader, dual-write target, or parallel truth.

Provider-native external IDs such as Microsoft tenant ID, Entra tenant ID, directory ID, subscription ID, account ID, or provider tenant ID are provider/source metadata only. They must not become Coverage v2 internal ownership keys.

When `provider_connection_id` is stored on a Coverage v2 record, it must belong to the same `workspace_id` and `managed_environment_id` as the record.

The required kernel definition tables in Spec 414 are platform-seeded definitions, not environment-owned operational observations:

- `tenant_configuration_resource_types` MUST NOT store `workspace_id`, `managed_environment_id`, or `provider_connection_id`.
- `tenant_configuration_supported_scopes` MUST NOT store `workspace_id`, `managed_environment_id`, or `provider_connection_id`.
- Workspace-specific overrides, environment-specific denominators, and provider-connection-specific definitions are out of scope for Spec 414.

If optional concrete resource or evidence tables are added in Spec 414, `provider_connection_id` is required for provider-observed rows with `source_class` values `tcm`, `graph_v1_fallback`, or `graph_beta_experimental`. It is nullable only for explicitly non-provider kernel rows approved by this spec. Any stored `provider_connection_id` must match the record's `workspace_id` and `managed_environment_id`; evidence rows must not point to a different provider connection than their concrete resource unless the implementation report records a provider-independent evidence rationale.

## No Legacy / No Backward Compatibility Constraint *(mandatory)*

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

- **Compatibility posture**: inactive kernel plus later hard cutover.
- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no new compatibility behavior. Existing v1 runtime remains active only because this spec does not activate v2 yet.
- **Why clean replacement is safe now**: Spec 414 does not remove active v1 runtime. It prepares the kernel for a later explicit cutover spec that will remove/replace legacy behavior under its own validation scope.

Forbidden as Coverage v2 kernel concepts:

- `policy_record_missing`
- `foundation_not_policy_backed`
- `meta_fallback`
- `ambiguous_match`
- `raw_gap_count`
- `primary_gap_count`
- `tenant_id` as Coverage v2 internal ownership truth

## UI Surface Impact *(mandatory - UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [x] No UI surface impact
- [ ] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [ ] Status/evidence/review presentation changed
- [ ] Workspace/environment context presentation changed

## UI/Productization Coverage

N/A - no reachable UI surface impact.

If any UI file is changed during implementation, implementation must stop and update this spec with Product Surface Impact, affected routes, page archetype, browser proof, and Human Product Sanity criteria before continuing.

## Product Surface Impact

- **Product Surface Contract applies?**: no runtime UI surface impact expected.
- **Page archetype**: N/A.
- **Primary user question**: N/A.
- **Primary action**: N/A.
- **Surface budget result**: N/A.
- **Technical Annex / deep-link demotion**: N/A.
- **Canonical status vocabulary**: N/A for rendered UI. Kernel claim states are domain values, not product-facing labels in this slice.
- **Visible complexity impact**: N/A - no rendered product surface changed.
- **Product Surface exceptions**: none.

## Browser Verification Plan *(mandatory)*

- **Browser proof required?**: no.
- **No-browser rationale**: N/A - no rendered UI surface changed.
- **Focused path when required**: N/A unless implementation changes a reachable UI surface after spec amendment.
- **Primary interaction to execute**: N/A.
- **Console, Livewire, Filament, network, and 500-error checks**: N/A.
- **Full-suite failure triage**: N/A.

## Human Product Sanity Check *(mandatory)*

- **Required?**: no.
- **No-human-sanity rationale**: N/A - no rendered product surface changed.
- **Reviewer questions**: workflow sanity only; confirm the slice stays inactive and does not create customer-facing dual truth.
- **Planned result location**: implementation report.

## Product Surface Merge Gate Checklist *(mandatory)*

- [x] No-legacy posture or approved exception recorded.
- [x] Product Surface Impact is completed or `N/A` is justified.
- [x] Browser proof is completed or `N/A - no rendered UI surface changed` is justified.
- [x] Human Product Sanity is completed or not applicable with rationale.
- [x] Product Surface exceptions are documented or `none`.
- [x] Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, and visible complexity outcome.

## Cross-Cutting / Shared Pattern Reuse

- **Cross-cutting feature?**: yes, but kernel-only.
- **Interaction class(es)**: none rendered. Future specs will touch status messaging, evidence/report viewers, restore readiness, and operator surfaces.
- **Systems touched**: kernel persistence and domain services only.
- **Existing pattern(s) to extend**: existing Laravel models, migrations, services, factories, Pest tests, PostgreSQL schema conventions.
- **Shared contract / presenter / builder / renderer to reuse**: no UI renderer. If status-like badges are later introduced, use `BadgeCatalog` / `BadgeRenderer` in the activation spec.
- **Why the existing shared path is sufficient or insufficient**: Existing rendering paths are out of scope. Existing v1 coverage paths are insufficient as v2 truth, but they remain active until later cutover.
- **Allowed deviation and why**: new Coverage v2 kernel namespace is allowed because current-release claim safety needs a separate kernel before activation.
- **Consistency impact**: later specs must consume the kernel and must not invent parallel claim models.
- **Review focus**: prevent v2 from being wired into product surfaces, prevent `tenant_id`, prevent compatibility shims.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no by default.
- **Shared OperationRun UX contract/layer reused**: N/A.
- **Delegated start/completion UX behaviors**: N/A.
- **Local surface-owned behavior that remains**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception required?**: none.

No remote TCM/Graph capture is implemented in Spec 414. No OperationRun-producing workflow is introduced unless a minimal registry/scope evaluation command is added after spec amendment. If any command/job/run is added and can be operationally relevant or asynchronous, it must follow the OperationRun contract. OperationRun-backed capture/evaluation is deferred to Generic Content-Backed Capture.

## Provider Boundary / Platform Core Check

- **Shared provider/platform boundary touched?**: yes.
- **Boundary classification**: mixed. Coverage v2 core terms are platform-core; Microsoft TCM/Graph source details are provider-owned source metadata.
- **Seams affected**: resource type taxonomy, source class, supported scope, provider provenance, claim labels.
- **Neutral platform terms preserved or introduced**: provider, source class, resource type, resource class, supported scope, coverage level, evidence state, identity state, claim state, managed environment.
- **Provider-specific semantics retained and why**: `tcm`, `graph_v1_fallback`, and `graph_beta_experimental` are retained because this kernel is TCM-first and must classify Microsoft fallback/beta source posture.
- **Why this does not deepen provider coupling accidentally**: source class is kernel metadata; provider-native tenant/directory/account IDs remain source metadata, not platform-core ownership keys.
- **Follow-up path**: document-in-feature for contained Microsoft source classes; follow-up specs for broader provider mapping.

## UI / Surface Guardrail Impact

N/A - no operator-facing surface change.

## Decision-First Surface Role

N/A - no operator-facing surface change.

## Audience-Aware Disclosure

N/A - no rendered audience surface change.

## UI/UX Surface Classification

N/A - no rendered UI surface change.

## Operator Surface Contract

N/A - no rendered operator surface change.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes, but inactive until later cutover.
- **New persisted entity/table/artifact?**: yes. Required: `tenant_configuration_resource_types` and `tenant_configuration_supported_scopes`. Optional only if needed for tests or clean service boundaries: `tenant_configuration_resources` and `tenant_configuration_resource_evidence`.
- **New abstraction?**: yes. Resource type registry, supported-scope resolver, and claim guard.
- **New enum/state/reason family?**: yes. Source class, workload, resource class, support state, coverage level, evidence state, identity state, claim state, and restore tier only if needed by claim guard. Allowed values are fixed in this spec and must not be expanded during implementation without amending the artifacts first.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: later customer claims cannot be safely activated without deterministic kernel boundaries.
- **Existing structure is insufficient because**: v1 coverage/gap semantics cannot express source class, supported-scope denominator, beta exclusion, fallback inclusion, provider provenance, or exact claim eligibility.
- **Narrowest correct implementation**: inactive value families, minimal persistence, initial registry, supported-scope contract, claim guard, unit/feature tests.
- **Ownership cost**: new domain namespace, persistence, factories, services, and test family.
- **Alternative intentionally rejected**: full cutover in one spec; v1-to-v2 compatibility mapping; UI-only relabeling.
- **Release truth**: current-release kernel needed before future activation.

### Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, fallback readers, dual writes, and compatibility-specific tests are out of scope.

## Coverage v2 Kernel Persistence

Spec 414 must introduce only the minimum persistence required for the v2 kernel.

Required:

- `tenant_configuration_resource_types`
- `tenant_configuration_supported_scopes`

Optional only if needed for tests or clean service boundaries:

- `tenant_configuration_resources`
- `tenant_configuration_resource_evidence`

Deferred:

- `tenant_configuration_coverage_runs`
- full capture/evaluation run summaries
- append-only evidence history beyond minimal kernel needs

`tenant_configuration_resource_types` is a platform-seeded registry definition table. Required fields:

- `id`
- `canonical_type`
- `display_name`
- `description` nullable
- `source_class`
- `workload`
- `resource_class`
- `support_state`
- `default_coverage_level`
- `default_evidence_state`
- `default_identity_state`
- `default_claim_state`
- `restore_tier` nullable
- `allows_beta_claims` boolean default false
- `allows_graph_fallback_claims` boolean default false
- `allows_certified_claims` boolean default false
- `is_active` boolean default true
- `metadata` jsonb nullable
- `created_at`
- `updated_at`

`tenant_configuration_resource_types` uniqueness rules:

- `(canonical_type, source_class)` must be unique.
- Initial registry entries must be upsert-safe and deterministic; re-running seed/migration logic must not duplicate entries.

`tenant_configuration_supported_scopes` is a platform-seeded supported-scope definition table. Required fields:

- `id`
- `scope_key`
- `display_name`
- `description` nullable
- `minimum_coverage_level`
- `included_resource_types` jsonb
- `allow_beta` boolean default false
- `allow_graph_fallback` boolean default false
- `customer_claims_allowed` boolean default false
- `is_active` boolean default true
- `metadata` jsonb nullable
- `created_at`
- `updated_at`

`tenant_configuration_supported_scopes` uniqueness and denominator rules:

- `scope_key` must be unique.
- `included_resource_types` must contain canonical resource type identifiers from `tenant_configuration_resource_types`.
- Initial supported-scope definitions must be upsert-safe and deterministic.
- Workspace-specific or environment-specific scope overrides are out of scope for Spec 414.

If `tenant_configuration_resources` is kept in 414, required fields are:

- `id`
- `workspace_id`
- `managed_environment_id`
- `provider_connection_id` nullable/required according to source class and provenance
- `resource_type_id`
- `canonical_external_id` nullable
- `canonical_key`
- `canonical_key_kind`
- `source_key` nullable
- `display_name` nullable
- `source_class`
- `workload`
- `resource_class`
- `support_state`
- `latest_coverage_level`
- `latest_evidence_state`
- `identity_state`
- `claim_state`
- `first_seen_at` nullable
- `last_seen_at` nullable
- `tombstoned_at` nullable
- `created_at`
- `updated_at`

If `tenant_configuration_resource_evidence` is kept in 414, required fields are:

- `id`
- `tenant_configuration_resource_id`
- `provider_connection_id` nullable
- `source_class`
- `source_endpoint` nullable
- `source_version` nullable
- `schema_version` nullable
- `raw_payload` jsonb nullable
- `normalized_payload` jsonb nullable
- `payload_hash` nullable
- `permission_context` jsonb nullable
- `coverage_level`
- `evidence_state`
- `captured_at` nullable
- `created_at`
- `updated_at`

No Coverage v2 table may include `tenant_id`.

## Coverage v2 Kernel Value Families

Spec 414 fixes these allowed values for the inactive kernel. Implementation must not add extra values without amending spec, plan, and tasks first.

- **SourceClass**: `tcm`, `graph_v1_fallback`, `graph_beta_experimental`
- **Workload**: `intune`
- **ResourceClass**: `configuration`
- **SupportState**: `supported`, `fallback_supported`, `experimental`, `unsupported`, `out_of_scope`
- **CoverageLevel**: `detected`, `content_backed`, `comparable`, `renderable`, `restorable`, `certified`
- **EvidenceState**: `not_captured`, `captured`, `content_backed`, `permission_blocked`, `source_unavailable`, `schema_unknown`, `capture_failed`
- **IdentityState**: `stable`, `derived`, `identity_conflict`, `missing_external_id`, `unsupported_identity`
- **ClaimState**: `claim_allowed`, `claim_limited`, `claim_blocked`, `internal_only`
- **RestoreTier** *(only if implemented in this slice)*: `not_restorable`, `preview_only`, `restorable`

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit for value families, registry, supported-scope resolver, claim guard; Feature for persistence seed/defaults, same-scope provider connection validation where applicable, and no-`tenant_id` schema proof.
- **Validation lane(s)**: fast-feedback, confidence, pgsql when migrations use JSONB/composite constraints.
- **Why this classification and these lanes are sufficient**: The narrowed spec changes kernel persistence and service behavior only. Browser and heavy UI lanes are not required unless a future amendment adds rendered UI.
- **New or expanded test families**: `tests/Unit/Support/TenantConfiguration` and `tests/Feature/TenantConfiguration`.
- **Fixture / helper cost impact**: New factories must stay explicit and opt-in.
- **Heavy-family visibility / justification**: no new heavy-governance family by default.
- **Special surface test profile**: `N/A - no rendered UI surface changed`.
- **Standard-native relief or required special coverage**: no browser proof required.
- **Reviewer handoff**: verify inactive kernel, no UI wiring, no compatibility shims, no `tenant_id`, correct source classes, beta claim blocking, Graph fallback classification, exact-scope claim guard, and provider connection same-scope rules.
- **Budget / baseline / trend impact**: document in implementation report if new tests materially increase runtime.
- **Escalation needed**: document-in-feature.
- **Active feature PR close-out entry**: Kernel / No UI / No dual truth.
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - focused unit tests for `tests/Unit/Support/TenantConfiguration`
  - focused feature tests for `tests/Feature/TenantConfiguration`
  - PostgreSQL-focused tests when schema constraints or JSONB require PostgreSQL proof
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Establish Inactive Coverage v2 Registry (Priority: P1)

As a release reviewer, I need the initial Coverage v2 resource type registry to exist with correct source classes and support defaults so later activation starts from explicit supported-scope truth.

**Why this priority**: The registry is the denominator for all future claims.

**Independent Test**: Assert the required initial resource type entries exist and classify TCM, Graph fallback, and beta experimental resources correctly.

**Acceptance Scenarios**:

1. **Given** the kernel registry is seeded, **When** entries are queried, **Then** all required initial resource types exist with expected source class and support state.
2. **Given** `notificationMessageTemplate`, **When** registry metadata is inspected, **Then** it is classified as `graph_v1_fallback`.
3. **Given** `roleScopeTag`, **When** registry metadata is inspected, **Then** it is classified as `graph_beta_experimental` and cannot be certified by default.

### User Story 2 - Define Supported Scope Contract (Priority: P1)

As a platform engineer, I need supported scopes to define explicit denominators and minimum coverage levels so claims cannot be made against ambiguous or unscoped sets.

**Why this priority**: Claim guard behavior depends on exact scope and level boundaries.

**Independent Test**: Resolve a supported scope and assert denominator membership, beta exclusion by default, Graph fallback inclusion only when allowed, and minimum coverage level enforcement.

**Acceptance Scenarios**:

1. **Given** a supported scope, **When** its denominator is resolved, **Then** only explicitly included resource types count toward the scope.
2. **Given** beta experimental resource types, **When** a default supported scope is resolved, **Then** those resource types are excluded unless the scope explicitly allows beta.
3. **Given** Graph fallback resource types, **When** a supported scope does not allow fallback, **Then** those resource types do not count toward allowed claims.

### User Story 3 - Block Unsafe Claims in Kernel (Priority: P1)

As a release reviewer, I need claim guard rules to block unsafe coverage statements before any UI activation occurs.

**Why this priority**: Customer-facing activation must not be possible without safe claim rules.

**Independent Test**: Exercise claim guard inputs and assert unsafe claims are blocked while exact scope + level claims are allowed.

**Acceptance Scenarios**:

1. **Given** an unscoped 100% claim, **When** the claim guard evaluates it, **Then** the claim is blocked.
2. **Given** a beta resource type, **When** certified coverage is requested, **Then** the claim is blocked by default.
3. **Given** an incomplete supported scope, **When** a customer-facing claim is requested, **Then** the claim is blocked.
4. **Given** a complete exact scope at the required level, **When** the claim guard evaluates it, **Then** the exact claim may be allowed.

### User Story 4 - Preserve Inactive Kernel Boundary (Priority: P2)

As an implementation reviewer, I need proof that Coverage v2 was not wired into customer/operator product surfaces as a parallel truth.

**Why this priority**: The kernel fails if it becomes a partial second truth model before activation.

**Independent Test**: Review changed files and focused tests; assert no UI routes/resources/pages are changed and no v1-to-v2 adapter, dual-write, or fallback reader exists.

**Acceptance Scenarios**:

1. **Given** Spec 414 implementation is complete, **When** changed files are reviewed, **Then** no reachable UI surface changed unless the spec was amended first.
2. **Given** v1 runtime still exists, **When** Coverage v2 services are inspected, **Then** no compatibility adapter translates old v1 gap taxonomy into v2 truth.
3. **Given** Coverage v2 persistence exists, **When** schema is inspected, **Then** no Coverage v2 ownership field uses `tenant_id`.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-414-001**: TenantPilot MUST introduce an inactive Coverage v2 kernel and MUST NOT make it the active customer-facing or operator-facing coverage truth in this spec.
- **FR-414-002**: The kernel MUST define `SourceClass`, `Workload`, `ResourceClass`, `SupportState`, `CoverageLevel`, `EvidenceState`, `IdentityState`, and `ClaimState`.
- **FR-414-003**: The kernel MAY define `RestoreTier` only if claim guard behavior requires restore-readiness boundaries in this slice.
- **FR-414-004**: The kernel MUST persist `tenant_configuration_resource_types` and `tenant_configuration_supported_scopes`.
- **FR-414-005**: The kernel MAY persist `tenant_configuration_resources` and `tenant_configuration_resource_evidence` only if needed for tests or clean service boundaries.
- **FR-414-006**: The kernel MUST NOT require `tenant_configuration_coverage_runs` in Spec 414.
- **FR-414-007**: The initial registry MUST include `deviceAndAppManagementAssignmentFilter`, `deviceEnrollmentLimitRestriction`, `deviceEnrollmentPlatformRestriction`, `deviceEnrollmentStatusPageWindows10`, `appProtectionPolicyAndroid`, `appProtectionPolicyiOS`, `notificationMessageTemplate`, and `roleScopeTag`.
- **FR-414-008**: TCM-aligned Intune entries MUST use `source_class = tcm`.
- **FR-414-009**: `notificationMessageTemplate` MUST use `source_class = graph_v1_fallback`.
- **FR-414-010**: `roleScopeTag` MUST use `source_class = graph_beta_experimental`.
- **FR-414-011**: Supported scopes MUST define explicit denominator membership and required minimum coverage level.
- **FR-414-012**: Supported scopes MUST exclude beta experimental resource types by default.
- **FR-414-013**: Supported scopes MUST include Graph fallback resource types only when the scope explicitly allows fallback.
- **FR-414-014**: Claim guard MUST block unscoped 100% claims.
- **FR-414-015**: Claim guard MUST block certified claims for beta experimental resource types by default.
- **FR-414-016**: Claim guard MUST block restore claims when the resource type is not restorable.
- **FR-414-017**: Claim guard MUST block customer-facing claims when supported scope is incomplete.
- **FR-414-018**: Claim guard MUST allow only exact scope + level claims.
- **FR-414-019**: Coverage v2 MUST NOT adapt, translate, dual-write, or fallback-read legacy v1 truth.
- **FR-414-020**: Coverage v2 MUST NOT use old v1 gap taxonomy as v2 runtime truth.
- **FR-414-021**: Coverage v2 MUST NOT introduce `tenant_id` in required ownership fields.
- **FR-414-022**: When `provider_connection_id` is stored, the provider connection MUST belong to the same `workspace_id` and `managed_environment_id` as the Coverage v2 record.
- **FR-414-023**: Provider-native tenant, directory, subscription, account, or provider tenant IDs MUST remain provider/source metadata only.
- **FR-414-024**: No reachable UI surface may change in this spec unless spec/plan/tasks are amended first with Product Surface Impact, browser proof, and Human Product Sanity criteria.
- **FR-414-025**: Required kernel definition tables MUST be platform-seeded, deterministic, upsert-safe definitions and MUST NOT include workspace, managed-environment, provider-connection, or tenant ownership columns.
- **FR-414-026**: Required kernel value families MUST use only the allowed values listed in `Coverage v2 Kernel Value Families`.

### Non-Functional Requirements

- **NFR-414-001**: Kernel persistence MUST follow PostgreSQL-first schema expectations, including JSONB only where JSON payload storage is actually introduced.
- **NFR-414-002**: New factories, helpers, seeds, and fixtures MUST stay opt-in and must not widen default test setup.
- **NFR-414-003**: No remote TCM, Graph, or provider calls may occur during this spec.
- **NFR-414-004**: No OperationRun-producing workflow is introduced unless this spec is amended first.
- **NFR-414-005**: The implementation report MUST record no-legacy confirmation, no-dual-truth confirmation, no-`tenant_id` proof, provider provenance proof, tests, browser N/A, Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, and deployment impact.

### UI Action Matrix

N/A - no Filament UI surface is changed.

### Key Entities

- **Tenant Configuration Resource Type**: Kernel registry entry describing canonical resource type, source class, workload, resource class, support state, default coverage level, beta/fallback flags, restore tier if needed, and claim defaults.
- **Tenant Configuration Supported Scope**: Named claim denominator with explicit included resource types, minimum coverage level, beta/fallback inclusion rules, and customer-claim eligibility.
- **Tenant Configuration Resource** *(optional in Spec 414)*: Concrete observed resource scoped by workspace and managed environment, with provider connection provenance when required.
- **Tenant Configuration Resource Evidence** *(optional in Spec 414)*: Minimal evidence record for kernel tests only if needed; full append-only evidence history is deferred.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-414-001**: Focused tests prove the initial required registry entries exist with correct source classes.
- **SC-414-002**: Focused tests prove beta experimental resources cannot produce certified claims by default.
- **SC-414-003**: Focused tests prove Graph fallback is represented through `graph_v1_fallback` source class.
- **SC-414-004**: Focused tests prove supported scopes use explicit denominators and minimum coverage levels.
- **SC-414-005**: Focused tests prove unscoped 100%, incomplete-scope, beta-certified, and non-restorable restore claims are blocked.
- **SC-414-006**: Schema or migration tests prove no Coverage v2 ownership field uses `tenant_id`.
- **SC-414-007**: Review of changed files proves no reachable UI surface was changed unless the spec was amended first.
- **SC-414-008**: Validation proves no compatibility adapter, dual-write target, fallback reader, or v1-to-v2 translator was added.
- **SC-414-009**: Unit/feature tests and `git diff --check` pass.
- **SC-414-010**: Focused tests or schema checks prove required kernel definition tables are deterministic, upsert-safe, globally seeded definitions and not workspace/environment/provider-connection-owned records.

## Acceptance Criteria

PASS requires:

- Coverage v2 kernel exists.
- Registry and supported scope persistence exist.
- Initial required resource types are registered.
- Source classes are correct.
- No `tenant_id` exists in Coverage v2 required ownership fields.
- Provider-native tenant IDs are metadata only.
- Claim Guard blocks unsafe/unscoped claims.
- Beta cannot be certified by default.
- Graph fallback is source-classed.
- No UI surface is changed, or if changed, Product Surface Contract is completed before continuing.
- No legacy compatibility shim is added.
- No v1-to-v2 translator is added.
- No customer-facing dual truth is introduced.
- Unit/feature tests pass.
- `git diff --check` passes.

FAIL if:

- Coverage v2 becomes a parallel customer-facing truth.
- `tenant_id` is reintroduced.
- old gap taxonomy is reintroduced as v2 logic.
- compatibility adapter, dual-write, or fallback reader is added.
- full runtime cutover is attempted inside Spec 414.

## Risks

| Risk | Severity | Mitigation |
|---|---:|---|
| Kernel becomes partial customer-facing truth | High | No UI changes; stop-and-amend rule for any rendered surface |
| Persistence grows back into full cutover | High | Only resource types and supported scopes are required; concrete resource/evidence tables are optional |
| `tenant_id` reappears through old terminology | High | Schema/test proof and implementation report ownership reconciliation |
| Claim guard becomes too broad | Medium | Unit-test exact scoped decisions and keep generic provider framework out of scope |
| Future activation lacks needed capture data | Medium | Defer content-backed capture and identity engine to explicit follow-up specs |

## Assumptions

- TenantPilot remains pre-production under LEAN-001.
- Existing v1 coverage remains active until a later activation/cutover spec.
- No runtime UI, route, navigation, action, browser, OperationRun, or remote provider work is needed for the kernel.
- Supply-chain remediation, if still open, remains a release/pilot gate outside this spec.

## Open Questions

- None blocking preparation.

## Out Of Scope

- Full UI cutover.
- Evidence Overview conversion.
- Customer Review Workspace conversion.
- Review Pack/report conversion.
- Restore readiness conversion.
- Full baseline/compare conversion.
- Legacy runtime deletion.
- Old test suite rewrite across all surfaces.
- OperationRun-backed capture/evaluation.
- TCM snapshot ingestion.
- Graph fallback capture.
- Generic content-backed evidence capture.
- Canonical identity engine implementation.
- Browser proof across customer surfaces.
- Full Microsoft TCM resource catalog import.
- Complete 249+ resource list.
- Certified Intune pack.
- Actual 100% coverage closure.

## Follow-Up Spec Candidates

- Spec 415 - Generic Content-Backed Capture.
- Spec 416 - Canonical Identity Engine.
- Spec 417 - Coverage v2 Operator Surface.
- Spec 418 - Legacy Coverage Cutover & Removal.
- Spec 419 - Intune Core Comparable/Renderable Pack.
- Spec 420 - Certified Intune Core Coverage Pack.
- Spec 421 - Pilot Readiness Gate.