Milestone 147 pr4 layout package v2 validator skeleton

[Coasterpete]

Milestone 147 PR4 — Track Layout Package V2 Validator

Overview

Introduces the first validation layer for TrackLayoutPackageV2.

This milestone adds DTO-level validation and V2-specific diagnostics while intentionally deferring import workflows, mapping, runtime compilation, normalization, repair behavior, and heartline evaluation.

The validator establishes the contract integrity rules that future V2 import and mapper implementations will rely upon.

Motivation

M147 PR1 defined the V2 design direction.

M147 PR2 locked the intended V2 JSON shape.

M147 PR3 introduced the V2 DTOs, vocabulary, JSON support, and schema.

This milestone adds the next layer in the pipeline:

JSON
  ↓
DTO
  ↓
Validator
  ↓
Mapper (future)
  ↓
TrackAuthoringDefinition (future)

The goal is to validate authored V2 content before any mapping or runtime conversion occurs.

Implementation

V2 Validator

Added:

Quantum.IO/TrackLayout/V2/TrackLayoutPackageV2Validator.cs

Provides DTO-only validation for:

• contract identity
• version identity
• metadata
• start pose integrity
• section semantics
• banking domain rules
• heartline vocabulary

The validator performs validation only and does not modify, normalize, repair, infer, or compile data.

Diagnostics

Added V2-specific diagnostics and validation codes.

New codes include:

• InvalidHeartlineKind
• InvalidHeartlineDistanceDomain
• InvalidHeartlineAxisSource

alongside V2 equivalents of the established contract, section, banking, and numeric validation rules.

Diagnostic paths follow the same stable-path philosophy used by TrackLayoutPackageV1 validation.

Banking Validation

Validation now enforces:

• minimum key count
• known interpolation values
• strictly increasing key distances
• first key distance at zero
• final key distance matching authored section length

while continuing to allow:

"banking": null

as a valid authored state.

Heartline Validation

The validator introduces support for the initial V2 heartline vocabulary.

Current supported shape:

{
  "kind": "constantOffset",
  "distanceDomain": "centerlineStation",
  "axisSource": "sampledFrame"
}

Heartline offsets must be finite values.

The validator does not evaluate heartline geometry or modify runtime behavior.

Test Coverage

Added:

Quantum.Tests/IO/TrackLayoutPackageV2ValidatorTests.cs

Coverage includes:

• default DTO validation
• minimal valid layouts
• constant-heartline layouts
• contract/version validation
• section validation
• duplicate IDs
• start pose validation
• spatial section validation
• banking validation
• heartline validation
• diagnostic path stability

Compatibility

No changes were made to:

• TrackLayoutPackageV1
• V1 schema
• V1 validators
• TrackAuthoringDefinition
• runtime compilation
• force contracts
• train contracts
• block-zone contracts

Existing V1 behavior remains unchanged.

Intentionally Deferred

This milestone does not implement:

• V2 mapper
• V2 import workflow
• V2 import result model
• runtime track compilation
• heartline evaluation
• V1-to-V2 migration tooling
• force profile contracts
• train contracts
• block-zone contracts

These belong to later milestones.

Validation

Tests: 1,692 / 1,692 passed.

Additional verification:

dotnet test QuantumCoasterWorks.sln --no-restore
git diff --check

Result

TrackLayoutPackageV2 now has a complete validation layer with stable diagnostics and contract-level enforcement, providing a foundation for future import and mapper milestones.