rrt/docs/runtime-rehost-plan.md

Runtime Rehost Plan

Goal

Replace the shell-dependent execution path with a bottom-up runtime that can be tested headlessly, grown incrementally, and later support one or more replacement frontends.

This plan assumes the current shell and presentation path remain unreliable for the near term. We therefore treat shell recovery as a later adapter problem rather than as the primary execution milestone.

Why This Boundary

Current static analysis points to one important constraint: the existing gameplay cadence is still nested under shell-owned frame and controller ownership rather than under one clean detached gameplay loop.

• simulation_frame_accumulate_and_step_world is still called from the shell-owned cadence and still performs shell-window and presentation-adjacent servicing.
• shell_service_frame_cycle owns frame refresh, deferred work, cursor updates, and one-time window visibility work.
• the world-view input path and ordinary controller input path still flow through shell-owned objects and globals.

That makes shell-first stabilization a poor rewrite target. The better target is the lower runtime: calendar stepping, periodic world maintenance, scenario event service, runtime persistence, and the stateful collections beneath them.

Architecture

The runtime rehost should be split into four layers.

1. rrt-runtime

Purpose:

• pure runtime state
• deterministic stepping
• scenario and company maintenance
• persistence and normalization boundaries

Constraints:

• no controller-window ownership
• no presentation refresh
• no shell globals in the public model
• no dependency on message pumps or platform input

2. rrt-fixtures

Purpose:

• fixture schemas
• captured-state loading
• golden summaries and diff helpers
• normalization helpers for comparing original-runtime outputs against rehosted outputs

3. rrt-cli

Purpose:

• headless runtime driver
• fixture execution commands
• state diff and round-trip tools

This should become the first practical execution surface for the new runtime.

4. Future adapter layers

Possible later crates:

• rrt-shell-adapter
• rrt-ui
• rrt-hook capture bridges

These should adapt to rrt-runtime, not own the core simulation model.

Rewrite Principles

1. Prefer state-in, state-out functions over shell-owned coordinators.
2. Choose narrow vertical slices that can be verified with fixtures.
3. Treat persistence boundaries as assets, because they give us reproducible test inputs.
4. Normalize state aggressively before diffing so comparisons stay stable.
5. Do not rehost shell or input code until the lower runtime already has a trustworthy step API.

Candidate Boundaries

Good early targets:

• calendar-point arithmetic and step quantization helpers
• simulation_advance_to_target_calendar_point
• simulation_service_periodic_boundary_work
• scenario_event_collection_service_runtime_effect_records_for_trigger_kind
• world_load_saved_runtime_state_bundle
• world_runtime_serialize_smp_bundle
• company and placed-structure refresh helpers that look like collection or state transforms

Poor early targets:

• simulation_frame_accumulate_and_step_world
• world_entry_transition_and_runtime_bringup
• shell_controller_window_message_dispatch
• world-view camera and cursor service helpers
• shell window constructors or message handlers

Milestones

Milestone 0: Scaffolding

Goal:

• create the workspace shape for bottom-up runtime work
• define fixture formats and CLI entrypoints
• make the first headless command runnable even before the runtime is featureful

Deliverables:

• new crate crates/rrt-runtime
• new crate crates/rrt-fixtures
• rrt-cli subcommands for runtime and fixture work
• initial fixture file format checked into the repo
• baseline docs for state normalization and comparison policy

Exit criteria:

• cargo run -p rrt-cli -- runtime validate-fixture <path> works
• one sample fixture parses and normalizes successfully
• the new crates build in the workspace

Milestone 1: Deterministic Step Kernel

Goal:

• stand up a minimal runtime state and one deterministic stepping API
• prove that a world can advance without any shell or presentation owner

Deliverables:

• calendar-point representation in Rust
• reduced RuntimeState model sufficient for stepping
• one advance_to_target_calendar_point execution path
• deterministic smoke fixtures
• human-readable state diff output

Exit criteria:

• one minimal fixture can advance to a target point and produce stable repeated output
• the same fixture can run for N steps with identical results across repeated runs
• state summaries cover the calendar tuple and a small set of world counters

Milestone 2: Periodic Service Kernel

Goal:

• add recurring maintenance and trigger dispatch on top of the first step kernel

Deliverables:

• periodic boundary service modes
• trigger-kind dispatch scaffolding
• the first runtime-effect service path behind a stable API
• fixture coverage for one or two trigger kinds

Exit criteria:

• one fixture can execute periodic maintenance without shell state
• trigger-kind-specific effects can be observed in a normalized diff

Milestone 3: Persistence Boundary

Goal:

• load and save enough runtime state to support realistic fixtures

Deliverables:

• serializer and loader support for a narrow .smp subset or an equivalent normalized fixture view
• round-trip tests
• versioned normalization rules

Exit criteria:

• one captured runtime fixture can be round-tripped with stable normalized output

Milestone 4: Domain Expansion

Goal:

• add the minimum missing subsystems needed by failing fixtures

Likely order:

• company maintenance
• scenario event service breadth
• placed-structure local-runtime refresh
• candidate and cargo-service tables
• locomotive availability refresh

Exit criteria:

• representative fixtures from multiple subsystems can step and diff without shell ownership

Milestone 5: Adapter and Frontend Re-entry

Goal:

• connect the runtime core to external control surfaces

Possible outputs:

• shell-compatibility adapter
• replacement CLI workflows
• replacement UI or tool surfaces

Exit criteria:

• external commands operate by calling runtime APIs rather than by reaching into shell-owned state

Fixture Strategy

We should maintain three fixture classes from the start.

minimal-world

Small synthetic fixtures for deterministic kernel testing.

Use for:

• calendar stepping
• periodic maintenance
• invariants and smoke tests

captured-runtime

Fixtures captured from the original process or from serialized runtime state.

Use for:

• parity checks
• subsystem-specific debugging
• rehosted function validation

roundtrip-save

Persistence-oriented fixtures built around real save data or normalized equivalents.

Use for:

• serializer validation
• normalization rules
• regression tests

Each fixture should contain:

• metadata
• format version
• source provenance
• input state
• command list
• expected summary
• optional expected normalized full state

Normalization Policy

Runtime diffs will be noisy unless we define a normalization layer early.

Normalize away:

• pointer addresses
• allocation order
• container iteration order when semantically unordered
• shell-only dirty flags or presentation counters
• timestamps that are not semantically relevant to the tested behavior

Keep:

• calendar tuple
• company and world ids
• cash, debt, and game-speed-related runtime fields when semantically relevant
• collection contents and semantic counts
• trigger-side effects

Risks

Hidden shell coupling

Some lower functions still touch shell globals indirectly. We should isolate those reads quickly and replace them with explicit runtime inputs where possible.

Fixture incompleteness

Captured state that omits one manager table can make deterministic functions appear unstable. The fixture format should make missing dependencies obvious.

Over-scoped early rewrites

The first two milestones should remain deliberately small. Do not pull in company UI, world-view camera work, or shell windows just because their names are nearby in the call graph.

Milestone 0 Specifics

This milestone is mostly repo shaping and interface definition.

Proposed crate layout

crates/rrt-runtime

• src/lib.rs
• src/calendar.rs
• src/runtime.rs
• src/step.rs
• src/summary.rs

crates/rrt-fixtures

• src/lib.rs
• src/schema.rs
• src/load.rs
• src/normalize.rs
• src/diff.rs

Proposed first public types

In rrt-runtime:

• CalendarPoint
• RuntimeState
• StepCommand
• StepResult
• RuntimeSummary

In rrt-fixtures:

• FixtureDocument
• FixtureCommand
• ExpectedSummary
• NormalizedState

Proposed CLI surface

Add a runtime command family to rrt-cli.

Initial commands:

• rrt-cli runtime validate-fixture <fixture.json>
• rrt-cli runtime summarize-fixture <fixture.json>
• rrt-cli runtime diff-state <left.json> <right.json>

These commands do not require a complete runtime implementation yet. They only need to parse, normalize, and summarize.

Proposed fixture shape

Example:

{
  "format_version": 1,
  "fixture_id": "minimal-world-step-smoke",
  "source": {
    "kind": "synthetic"
  },
  "state": {
    "calendar": {
      "year": 1830,
      "month_slot": 0,
      "phase_slot": 0,
      "tick_slot": 0
    },
    "world_flags": {},
    "companies": [],
    "event_runtime_records": []
  },
  "commands": [
    {
      "kind": "advance_to",
      "calendar": {
        "year": 1830,
        "month_slot": 0,
        "phase_slot": 1,
        "tick_slot": 0
      }
    }
  ],
  "expected_summary": {
    "calendar_year": 1830
  }
}

Milestone 0 task list

1. Add the two new workspace crates.
2. Add serde-backed fixture schema types.
3. Add a small summary model for runtime fixtures.
4. Extend rrt-cli parsing with the runtime command family.
5. Check in one synthetic fixture under a new tracked fixtures directory.
6. Add tests for fixture parsing and normalization.

Milestone 1 Specifics

This milestone is the first real execution step.

Scope

Implement only enough runtime to support:

• calendar-point representation
• comparison and ordering
• advance_to over a reduced world state
• summary and diff output

Do not yet model:

• shell-facing frame accumulators
• input
• camera or cursor state
• shell windows
• full company, site, or cargo behavior

Proposed runtime model

CalendarPoint

• year
• month_slot
• phase_slot
• tick_slot

Methods:

• ordering and comparison
• step forward one minimal unit
• convert to and from normalized serialized form

RuntimeState

• current calendar point
• selected year or absolute calendar scalar if needed
• minimal world counters
• optional minimal event-service scratch state

StepCommand

• AdvanceTo(CalendarPoint)
• StepCount(u32)

StepResult

• start summary
• end summary
• steps_executed
• boundary_events

Milestone 1 execution API

Suggested Rust signature:

pub fn execute_step_command(
    state: &mut RuntimeState,
    command: StepCommand,
) -> StepResult

Internally this should call a narrow helper shaped like:

pub fn advance_to_target_calendar_point(
    state: &mut RuntimeState,
    target: CalendarPoint,
) -> StepResult

Milestone 1 fixture set

Add at least these fixtures:

1. minimal-world-advance-one-phase
2. minimal-world-advance-multiple-phases
3. minimal-world-step-count
4. minimal-world-repeatability

Milestone 1 verification

Required checks:

• repeated runs produce byte-identical normalized summaries
• target calendar point is reached exactly
• step count matches expected traversal
• backward targets fail cleanly or no-op according to chosen policy

Milestone 1 task list

1. Implement CalendarPoint.
2. Implement reduced RuntimeState.
3. Implement advance_to_target_calendar_point.
4. Implement CLI execution for one fixture command list.
5. Emit normalized summaries after execution.
6. Add deterministic regression tests for the initial fixtures.

Immediate Next Actions

After this document lands, the recommended first implementation sequence is:

1. add rrt-runtime and rrt-fixtures
2. extend rrt-cli with runtime validate-fixture
3. add one synthetic fixture
4. implement CalendarPoint
5. implement one narrow advance_to path

That sequence gives the project a headless execution backbone without needing shell recovery first.