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)

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

Source Code (repository root)

Likely implementation surfaces:

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:

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.