Tellurian Trains Dispatch

Expert guidance for working with the Tellurian.Trains.Dispatch .NET library for model railway train dispatching.

What This Skill Does

Provides Claude Code with deep context about the Tellurian.Trains.Dispatch codebase architecture, domain model, and conventions. Enables accurate code modifications, feature additions, and debugging for this specialized train dispatching system.

Project Architecture

Core Components

1. **Broker** - Central singleton component

- Holds state of each train's calls at specific stations

- Manages collection of DispatchStretch (track sections)

- Manages collection of StationDispatcher (one per station)

- Manages TrainSection instances representing active dispatching

2. **Dispatcher** - Presents state of arriving and departing trains

- **StationDispatcher** - Presents state for a specific named station

- Queries the Broker for arrivals and departures

Domain Model Entities

**Train** - Identified by Company and Identity (e.g., "SJ IC 123"). Contains collection of TrainSection sections.

**Station** - Named location with signature. Can be manned or unmanned.

**StationTrack** - Specific track/platform at a station.

**DispatchStretch** - Track section between two adjacent stations. Has capacity (single/double track) and optional block signals.

**TrainSection** - Train's scheduled movement over a DispatchStretch, with departure and arrival calls.

**TrainStationCall** - Scheduled stop: train, station, track, and call times.

**BlockSignal** - Intermediate signal point on a DispatchStretch for finer capacity control.

State Machine Logic

Train State

Planned → Manned → Running → [Completed | Canceled | Aborted]

Dispatch State

None → Requested → [Accepted | Rejected] → Departed → [PassBlockSignal*] → Arrived

(or Accepted → Revoked)

Block Passage State

Expected → Passed (or Canceled)

Block Signal System

**Critical Rules:**

1. **N block signals** create **N+1 blocks** (segments)

2. Each block can hold **only one train** at a time

3. Trains must pass block signals **in sequence**

4. Train's current block index = count of passed BlockSignalPassages

5. Arrival is only allowed **after all block signals have been passed**

**Block Occupancy:**

Train departs → occupies Block 0 (station to first signal)

Dispatcher marks passage → train moves to next block

Previous block becomes free for next train

**Control:**

The dispatcher who controls a block signal (`BlockSignal.ControlledBy`) is presented with the action to mark the passage.

Code Instructions

When modifying code:

1. **Follow Extension Method Pattern**

- Organize behavior into extension method classes

- Maintain separation of concerns

2. **Use Option<T> for Error Handling**

- Operations that can fail should return `Option<T>`

- Include descriptive error messages

3. **Respect Thread Safety**

- Use `Interlocked` for auto-incrementing IDs

- Maintain thread-safe patterns in shared state

4. **Dependency Injection Interfaces**

- `IBrokerConfiguration`

- `IBrokerStateProvider`

- `ITimeProvider`

- Keep implementations flexible for integration

5. **Target .NET 10.0**

- Project targets .NET 10.0 SDK

- Framework version defined globally in `Directory.Build.props`

- **Do NOT** add `<TargetFramework>` to individual `.csproj` files

6. **Test Projects**

- Use **MSTest.Sdk**

- Use **Microsoft Testing Platform**

- **Do NOT** use VS Test framework

When adding features:

1. Verify impact on state machines

2. Check block signal logic if touching DispatchStretch

3. Ensure thread-safety for shared Broker state

4. Add extension methods for new behaviors

5. Update README.md if adding public API surface

When debugging:

1. Check state machine transitions for invalid flows

2. Verify block signal sequence constraints

3. Inspect BlockSignalPassage counts for arrival logic

4. Review thread safety in ID generation and state updates

5. Validate Option<T> error messages for clarity

Important Constraints

Broker is a **singleton** - maintain single source of truth

Block signals enforce **strict sequencing** - cannot skip signals

Arrival requires **all block signals passed** - check completion

Station can be **manned or unmanned** - affects dispatcher behavior

Thread-safe ID generation is **required** - use Interlocked primitives

Examples

Checking if a train can arrive:

```csharp

// Train must have passed all block signals on the stretch

var requiredPassages = dispatchStretch.BlockSignals.Count;

var actualPassages = trainSection.BlockSignalPassages.Count(p => p.State == BlockPassageState.Passed);

var canArrive = actualPassages >= requiredPassages;

```

Marking block signal passage:

```csharp

// Find the next expected passage for this dispatcher

var nextPassage = trainSection.BlockSignalPassages

.FirstOrDefault(p => p.State == BlockPassageState.Expected

&& p.BlockSignal.ControlledBy == dispatcher);

if (nextPassage != null) {

nextPassage.MarkPassed(timeProvider.Now);

}

```

Using Option<T> for error handling:

```csharp

public Option<TrainSection> RequestDispatch(Train train, DispatchStretch stretch) {

if (!train.IsManned) {

return Option<TrainSection>.Error("Train must be manned before dispatch");

}

// ... success path

return Option<TrainSection>.Success(trainSection);

}

```

References

**README.md** - Detailed project documentation and intended use

**Directory.Build.props** - Global .NET version configuration

Core interfaces: `IBrokerConfiguration`, `IBrokerStateProvider`, `ITimeProvider`

tellurian-trains-dispatch

Tellurian Trains Dispatch

What This Skill Does

Project Architecture

Core Components

Domain Model Entities

State Machine Logic

Train State

Dispatch State

Block Passage State

Block Signal System

Code Instructions

When modifying code:

When adding features:

When debugging:

Important Constraints

Examples

Checking if a train can arrive:

Marking block signal passage:

Using Option<T> for error handling:

References

Reviews (0)