Milestone 147: add layout package v2 dto schema skeleton

[Coasterpete]

Milestone 147 PR3 — Track Layout Package V2 DTO and Schema Skeleton

Overview

Introduces the initial TrackLayoutPackageV2 contract skeleton.

This milestone converts the V2 design and shape-lock decisions from M147 PR1 and PR2 into concrete DTO and schema artifacts while intentionally deferring import/export behavior, validation logic, and runtime integration.

The goal is to establish a stable V2 contract foundation before implementation work begins.

Motivation

M147 PR1 defined the long-term direction for TrackLayoutPackageV2.

M147 PR2 locked the intended V2 JSON shape, including:

• required root contract fields
• optional stable layout identity
• required nullable heartline support
• V1-compatible section and banking structures
• explicit separation of force, train, and block-system concerns

This PR translates those decisions into code and schema artifacts so future milestones can build against a stable contract definition.

Implementation

V2 DTO Model

Added:

Quantum.IO/TrackLayout/V2/TrackLayoutPackageV2Dtos.cs

Provides the initial V2 DTO hierarchy including:

• root package DTO
• metadata DTO
• start pose DTO
• section DTOs
• banking DTOs
• heartline DTOs

The DTO shape mirrors the locked V2 contract design.

Vocabulary

Added:

Quantum.IO/TrackLayout/V2/TrackLayoutPackageV2Vocabulary.cs

Defines V2 contract identifiers and version constants.

JSON Support

Added:

Quantum.IO/TrackLayout/V2/TrackLayoutPackageV2Json.cs

Provides deterministic V2 JSON serialization support consistent with existing contract behavior.

JSON Schema

Added:

docs/contracts/track-layout-package-v2.schema.json

Key schema decisions:

• closed root object
• closed nested objects
• required banking
• required heartline
• nullable banking
• nullable heartline
• optional nullable metadata.layoutId
• V1-compatible section shapes
• curvatureTransition.interpolationMode restricted to linear

Test Coverage

Added:

Quantum.Tests/IO/TrackLayoutPackageV2Tests.cs

Coverage includes:

• contract constants
• DTO defaults
• deterministic JSON serialization
• schema acceptance of minimal V2 layouts
• schema acceptance of constant-heartline layouts
• version validation behavior
• unknown-root-field rejection

Compatibility

No existing contracts were modified.

V1 remains unchanged.

No changes were made to:

• TrackLayoutPackageV1 DTOs
• TrackLayoutPackageV1 schema
• TrackLayoutPackageV1 tests
• TrackAuthoringDefinition
• runtime track compilation

Intentionally Deferred

This milestone does not implement:

• V2 mapper
• V2 validator
• V2 import/export workflows
• runtime behavior
• heartline evaluation
• force profile contracts
• train contracts
• block-zone contracts

Those responsibilities belong to later milestones.

Validation

Tests: 1,675 / 1,675 passed.

Additional verification:

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

Result

Quantum now has a versioned TrackLayoutPackageV2 contract foundation consisting of DTOs, vocabulary, JSON support, schema definitions, and automated tests.

Future milestones can build validators, mappers, import/export workflows, and heartline authoring support on top of a stable V2 contract surface.