core: harden deterministic contracts and public API surface

[bxvtr]

Summary

Hardens the TradingChassis Core baseline by making key deterministic contracts explicit across Strategy boundaries, Market Events, Order Lifecycle handling, Runtime/Core obligations, and the public API surface.

This change introduces a read-only StrategyStateView for Strategy evaluation, formalizes the current book-only MarketEvent reduction contract, adds explicit terminal Order Lifecycle canonical Events, clarifies Runtime/Core feedback obligations, and locks/classifies the public Core API surface through docs and tests.

Motivation

Why is this change necessary?

Core is intended to be a deterministic standalone package with clear boundaries between Core and Runtime. Several contracts were previously implicit or under-specified:

• Strategy evaluators could access mutable StrategyState.
• MarketEvent allowed trade-shaped payloads even though canonical reduction was book-only.
• Canceled/rejected/expired Order terminal outcomes were not modeled as explicit canonical Events.
• Runtime obligations after dispatch were spread across docs rather than centralized.
• Some public root exports were under-documented or missing from public API surface tests.

This PR hardens those contracts without broad Runtime changes or large architectural refactors.

Type of Change

• Bug fix
• New feature
• Performance improvement
• Refactor
• Documentation
• Breaking change

Technical Details

Describe key implementation decisions.

• Added StrategyStateView and wired Strategy contexts so Strategy evaluators receive a read-only State view instead of the live mutable StrategyState.
• Preserved the existing context.state shape while changing the object exposed through it to a read-only view.
• Formalized the current MarketEvent canonical reduction contract as book-only.
  • MarketEvent(event_type="trade") remains constructible at the schema level.
  • Trade-shaped MarketEvents are explicitly rejected by canonical reduction.
• Added explicit terminal canonical Events:
  • OrderCanceledEvent
  • OrderRejectedEvent
  • OrderExpiredEvent
• Added reducer handling for terminal Order Events:
  • remove active working Order projections,
  • update canonical terminal Order projection,
  • clear inflight state,
  • support deterministic/idempotent repeated terminal feedback.
• Clarified Runtime/Core obligations:
  • Runtime dispatches CoreStepResult.dispatchable_intents.
  • Runtime feeds canonical Events back into Core.
  • ControlSchedulingObligation is a non-canonical output and must be realized later as ControlTimeEvent.
  • OrderExecutionFeedbackEvent is account-level feedback, not a FillEvent replacement.
• Classified and locked the public Core API surface:
  • Public Data Models
  • Public Extension Points
  • Public Orchestration APIs
  • Public Convenience Implementations
  • Advanced APIs
• No Runtime, hftbacktest, recorder, or adapter implementation changes were made.

Determinism & Reproducibility

• Change preserves deterministic behavior
• Tests confirm reproducibility
• No hidden State introduced

The changes make deterministic boundaries more explicit. State mutation remains owned by Core reducers and Execution Control. Strategy evaluation now receives a read-only State view, and Runtime/Core feedback obligations are documented as canonical Event contracts.

Performance Impact

• No measurable impact
• Benchmarks included
• Performance improvement

No performance-oriented changes were introduced. The StrategyStateView adds read-only boundary protection at Strategy evaluation time; no benchmark-relevant hot-path optimization was part of this PR.

Tests

• Unit tests added/updated
• Integration tests added/updated
• Existing tests pass

Added/updated tests cover:

• read-only Strategy State boundary,
• book-only MarketEvent reduction contract,
• explicit trade-shaped MarketEvent rejection,
• terminal Order Lifecycle Events,
• terminal reducer behavior and inflight cleanup,
• Runtime/Core contract semantics,
• OrderExecutionFeedbackEvent account-only behavior,
• ControlSchedulingObligation non-canonical behavior,
• public API root export locking,
• public API docs/root export consistency.

Validation performed:

python examples/core_step_quickstart.py
python examples/core_step_with_risk_engine.py
python -m pytest -q
python -m mypy tradingchassis_core tests
python -m build

Breaking Changes

CoreStepStrategyContext.state and CoreWakeupStrategyContext.state now expose StrategyStateView instead of the live mutable StrategyState.

Migration impact:

• Strategies that only read State should continue to work with minimal or no changes.
• Strategies that mutated context.state, called reducer methods, accessed queue/inflight internals, or relied on mutable StrategyState methods must be updated.
• Strategy code should now read from StrategyStateView and return Intents.
• Core reducers and Execution Control remain responsible for State mutation.

Other notes:

• Trade-shaped MarketEvents are still constructible but are explicitly unsupported for canonical reduction in the current Core baseline.
• Terminal Order Events are additive public API.
• No root exports were removed or renamed.

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated