core: harden deterministic contracts and public API surface

CHANGELOG.md

@@ -17,21 +17,35 @@ This changelog starts from the clean Core package baseline.
 - Deterministic `run_core_step` and `run_core_wakeup_step` architecture.
 - CoreWakeupStep final Strategy evaluation: reduce all entries, then `CoreWakeupStrategyEvaluator` once.
 - Canonical Event input models and `EventStreamEntry`/`ProcessingPosition`.
-- Intent Pipeline candidate records with dominance/reconciliation.
+- Intent pipeline candidate records with dominance/reconciliation.
 - Risk Engine (policy-only) admission and Execution Control plan/apply integration.
 - `CoreStepResult.dispatchable_intents` and `ControlSchedulingObligation` outputs.
 - Core-only quickstart example and focused semantics test coverage.
 - Root export of `PolicyIntentEvaluator` and documentation of extension points vs convenience implementations.
 - Pipeline integration tests for `RiskEngine` as `policy_evaluator` in `run_core_step`.
-- `FillEvent` reducer and Pipeline tests.
+- `FillEvent` reducer and pipeline tests.
 - Runnable Risk Engine example at `examples/core_step_with_risk_engine.py`.
 - Extension-point docs under `docs/` and U3 candidate list at `docs/roadmap/dead-code-cleanup-candidates.md`.
+- Explicit terminal canonical Order lifecycle Events:
+  `OrderCanceledEvent`, `OrderRejectedEvent`, and `OrderExpiredEvent`.
+- Terminal lifecycle reduction behavior and focused semantics tests for
+  deterministic working-order removal, canonical projection terminal state, and
+  inflight cleanup.
 
 ### Changed
 
 - Package metadata, exports, and docs reset for standalone Core library identity.
 - Pydantic models established as contract source of truth across public API docs.
-- README clarifies internally wired Pipeline vs externally supplied extension points.
+- README clarifies internally wired pipeline vs externally supplied extension points.
+- Runtime/Core contract wording hardened with a normative Runtime-obligation
+  matrix, explicit `CoreStepResult` output semantics, and clearer
+  `ControlSchedulingObligation` vs `ControlTimeEvent` boundary language.
+- Canonical `MarketEvent` contract wording now explicitly documents the current
+  book-only reduction baseline; trade-shaped payloads are explicitly unsupported
+  for canonical reduction in this slice.
+- Public API docs/tests hardening for Core-F2: root Public API classification,
+  Advanced API labeling, root-vs-non-root clarity, and explicit surface lock
+  coverage for all current root exports. No exports were removed or renamed.
 
 ### Removed
 

CONTRIBUTING.md

@@ -48,7 +48,7 @@ python -m build
 - Register canonical category handling in `core/domain/event_model.py`.
 - Update canonical reduction behavior in `core/domain/processing.py`.
 
-### CoreStep/CoreWakeupStep Pipeline
+### CoreStep/CoreWakeupStep pipeline
 
 - Update `core/domain/processing_step.py` for deterministic flow changes.
 - Keep reconciliation/policy/apply transitions explicit and side-effect-safe.

README.md

@@ -62,10 +62,10 @@ stay in the Runtime, Venue Adapter, and Venue—not in Core.
 
 | What you get | Why it matters |
 | --- | --- |
-| One deterministic Core Pipeline | Same Event-step path for reduction → evaluation → candidates → Risk Engine → Execution Control apply |
+| One deterministic Core pipeline | Same Event-step path for reduction → evaluation → candidates → Risk Engine → Execution Control apply |
 | Canonical Event input model (`EventStreamEntry`) | Aligns with Event Stream + Processing Order; State is `f(Event Stream, Configuration)` |
 | Strategy output as Intents | Internal, order/Venue-agnostic commands before Venue Adapter-specific shapes |
-| Risk Engine separated from Execution Control | Risk Engine (policy) vs Queue / scheduling / rate-aware presentation split, as in the Intent Pipeline (Strategy → Risk → Queue → Adapter) |
+| Risk Engine separated from Execution Control | Risk Engine (policy) vs Queue / scheduling / rate-aware presentation split, as in the Intent pipeline (Strategy → Risk → Queue → Adapter) |
 | `dispatchable_intents` + optional Control Scheduling Obligation | Runtime performs Execution and may inject canonical `ControlTimeEvent` when a **rate-limit** obligation is realized ([`docs/flows/control-time-and-scheduling.md`](docs/flows/control-time-and-scheduling.md)); inflight deferral does not emit that obligation by default |
 
 Core is designed to reduce decision-logic drift between Backtesting
@@ -103,7 +103,7 @@ flowchart TB
 Core never replaces the Runtime: the Runtime is responsible for feeding canonical
 Events and for turning `dispatchable_intents` into Venue traffic (and for everything
 Kubernetes, credentials, and operations-related). What stays stable is the Core
-Pipeline and contracts; what varies by design is Runtime choice, Venue Adapter,
+pipeline and contracts; what varies by design is Runtime choice, Venue Adapter,
 Venue, and deployment.
 
 <img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
@@ -133,7 +133,7 @@ Run the quickstart
 python examples/core_step_quickstart.py
 ```
 
-Optional Risk Engine policy example (same Pipeline, built-in policy):
+Optional Risk Engine policy example (same pipeline, built-in policy):
 
 ```bash
 python examples/core_step_with_risk_engine.py
@@ -170,9 +170,9 @@ Planned U3 cleanup candidates: [`docs/roadmap/dead-code-cleanup-candidates.md`](
 
 <img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
 
-## Full Pipeline
+## Full pipeline
 
-Internal processing Pipeline, in sequential order:
+Internal processing pipeline, in sequential order:
 
 ```text
 Runtime reduces to canonical Events
@@ -189,11 +189,42 @@ Runtime reduces to canonical Events
 Runtime dispatches Intents into Orders
 ```
 
+Runtime/Core contract matrix (Core perspective): see
+[`docs/reference/events-reference.md`](docs/reference/events-reference.md)
+for the normative Runtime/external outcome -> canonical Event injection table and
+reducer effects.
+
+Terminal Order lifecycle baseline in this Core slice:
+
+- Core now accepts explicit canonical terminal lifecycle Events:
+  `OrderCanceledEvent`, `OrderRejectedEvent`, and `OrderExpiredEvent`.
+- Runtime owns venue I/O and must inject these canonical Events when terminal
+  outcomes are confirmed/reported in the Event Stream.
+- Terminal Event reduction removes active working-order projections, updates
+  canonical order projection state, and clears inflight tracking for
+  `instrument + client_order_id`.
+- `OrderRejectedEvent` is an Order lifecycle execution outcome and is distinct
+  from Policy Admission rejection in the Intent pipeline.
+- Dispatch failure before submission is not automatically `OrderRejectedEvent`.
+- `OrderExecutionFeedbackEvent` is account-level feedback and does not replace
+  `FillEvent` or terminal lifecycle Events.
+- This slice does not add `OrderAcceptedEvent` and does not introduce a full
+  order state machine framework.
+
+Current Market Event baseline contract:
+
+- Core canonical reduction supports book-shaped `MarketEvent` payloads for
+  Market State reduction.
+- Trade-shaped `MarketEvent` payloads are not reduced by the current baseline
+  and are explicitly rejected at canonical processing boundaries.
+- Runtime may normalize venue data into canonical Events, but Core accepts only
+  the documented canonical reduction contract.
+
 <img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
 
 ## Internally wired vs externally supplied
 
-The clean Core Pipeline is always the same shape; some pieces run inside Core
+The clean Core pipeline is always the same shape; some pieces run inside Core
 when you call step APIs, and others must be supplied by your Runtime or tests.
 
 ### Internally wired (always part of Core when you call step APIs)
@@ -207,6 +238,7 @@ when you call step APIs, and others must be supplied by your Runtime or tests.
 ### Externally supplied extension points
 
 - **Strategy evaluator** — `CoreStepStrategyEvaluator` or `CoreWakeupStrategyEvaluator`
+  receives a read-only `StrategyStateView` via `context.state` and returns Intents
 - **Policy evaluator** — any object implementing `PolicyIntentEvaluator` (passed via `CorePolicyAdmissionContext`)
 - **Execution Control** — `ExecutionControl` instance (passed via `CoreExecutionControlApplyContext`)
 - **Configuration** — optional `CoreConfiguration` for positioned market reduction
@@ -223,6 +255,9 @@ The minimal quickstart uses an inline allow-all policy to stay small. That does
 built-in Risk Engine policy behavior. See `examples/core_step_quickstart.py` (minimal) and
 `examples/core_step_with_risk_engine.py` (Risk Engine variant).
 
+Strategy code reads State and returns Intents. It must not mutate Core-owned
+State, Queue/inflight substate, or reducer-managed data.
+
 <img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
 
 ## Input / Core / Output / Not Owned By Core
@@ -256,7 +291,7 @@ work is reconsidered after canonical execution Events update State. Runtimes mus
 not flush Core Queues outside the normal `run_core_step` / Execution Control apply
 path. See [`docs/flows/control-time-and-scheduling.md`](docs/flows/control-time-and-scheduling.md).  
 
-In short: one Pipeline, canonical Events, Intents inside Core, policy vs Execution
+In short: one pipeline, canonical Events, Intents inside Core, policy vs Execution
 Control split, dispatchable Intents plus optional Control Scheduling Obligation for
 the Runtime, and a boundary that makes parity and testing practical—not a second
 copy of decision logic per environment.

SECURITY.md

@@ -25,7 +25,7 @@ Include:
 This policy covers the Core package in this repository, including:
 
 - canonical Event and Intent contracts
-- deterministic CoreStep/CoreWakeupStep decision Pipeline
+- deterministic CoreStep/CoreWakeupStep decision pipeline
 - package integrity and dependency usage in `tradingchassis_core`
 
 ## Secrets and Credentials Policy

docs/code-map/core-pipeline-map.md

@@ -1,6 +1,6 @@
-# Core Pipeline Map
+# Core pipeline Map
 
-This map captures the only supported deterministic decision Pipeline for
+This map captures the only supported deterministic decision pipeline for
 TradingChassis Core.
 
 ## Step-by-step flow
@@ -17,7 +17,7 @@ TradingChassis Core.
    in the current slice—see `../flows/control-time-and-scheduling.md`).
 9. Runtime can dispatch later and inject further canonical Events (including
    `ControlTimeEvent` when an obligation is realized); Core does not perform
-   external dispatch or mutate Queues outside this Pipeline.
+   external dispatch or mutate Queues outside this pipeline.
 
 ## Core APIs
 
@@ -46,7 +46,7 @@ Wakeup flow:
 2. `run_core_wakeup_reduction` calls `process_event_entry` for each entry in order.
 3. `CoreWakeupStrategyEvaluator.evaluate` runs **once** on the fully reduced State
    (`CoreWakeupStrategyContext` carries all entries).
-4. `run_core_wakeup_decision` snapshots queued intents once, combines generated + queued
+4. `run_core_wakeup_decision` snapshots queued Intents once, combines generated + queued
    once, applies dominance/reconciliation once, Policy Admission once, and
    Execution Control plan/apply once.
 5. `CoreStepResult.dispatchable_intents` is returned; Runtime dispatches later.

docs/code-map/repository-map.md

@@ -6,7 +6,7 @@ High-level map for the standalone Core package.
 
 - `tradingchassis_core/__init__.py`: public package boundary exports
 - `tradingchassis_core/core/domain/`: canonical contracts and deterministic
-  Pipeline orchestration
+  pipeline orchestration
 - `tradingchassis_core/core/risk/`: policy-only Risk Engine evaluator/config
 - `tradingchassis_core/core/execution_control/`: Execution Control primitives
 - `tradingchassis_core/core/events/`: Event bus/sink utilities (`NullEventBus`; `LoggingEventSink` for Runtime)

docs/flows/control-time-and-scheduling.md

@@ -11,12 +11,13 @@ to Execution Control deferral.
   canonical Event Stream and does not mutate `StrategyState`.
 - **Control-Time Event** (`ControlTimeEvent`) — Canonical **control** category Event. It becomes part of the
   deterministic history only after the **Runtime** injects it as
-  `EventStreamEntry` input (same ingestion path as other canonical Events).
+  `EventStreamEntry` input (same ingestion path as other canonical Events). It is
+  sparse/deadline-style control feedback, not a periodic tick requirement.
 - **Inflight** — Core-side **Intent-operation** gating: a sendability / operation
   slot (for example keyed by `client_order_id`) is occupied because an earlier
   Intent operation is still awaiting **canonical execution feedback**. This is
   not the same as venue-side “order ownership”; Core models sendability for the
-  decision Pipeline.
+  decision pipeline.
 - **Rate-limit deferral** — Execution Control blocks dispatch because the
   configured **token / time budget** for orders or cancels is not yet available at
   the apply clock (`now_ts_ns_local` in `CoreExecutionControlApplyContext`).
@@ -37,12 +38,17 @@ or “synthetic” obligations for inflight-only waits.
 `ControlTimeEvent`. Obligations are for **rate-limit** rechecks in the current
 Core slice.
 
-## Clean Core Pipeline (unchanged)
+`ControlSchedulingObligation` is produced in Execution Control **apply** for
+time-dependent rate-limit deferral. It does not mutate Strategy State and does
+not enter the Event Stream directly. Runtime may realize it later by injecting
+a canonical `ControlTimeEvent`.
+
+## Clean Core pipeline (unchanged)
 
 1. `EventStreamEntry`
 2. `process_event_entry` / `process_canonical_event`
 3. Strategy evaluator
-4. generated intents
+4. generated Intents
 5. candidate records + dominance / reconciliation
 6. policy admission
 7. Execution Control plan / apply

docs/how-to/update-core-step-pipeline.md

@@ -1,4 +1,4 @@
-# How To Update CoreStep Pipeline Behavior
+# How To Update CoreStep pipeline Behavior
 
 Core step orchestration lives in
 `tradingchassis_core/core/domain/processing_step.py`.
@@ -19,7 +19,7 @@ Recommended workflow:
 
 Guardrails:
 
-- No Runtime dispatch logic in Core Pipeline code.
+- No Runtime dispatch logic in Core pipeline code.
 - No legacy compatibility contract restoration.
 - Keep deterministic behavior and public API coherence.
 

docs/index.md

@@ -7,7 +7,7 @@ This documentation set describes the standalone clean Core package baseline.
 - `reference/public-api.md`: supported root exports and package boundary
 - `reference/events-reference.md`: canonical Events and Intent contracts
 - `flows/control-time-and-scheduling.md`: rate-limit vs inflight deferral and obligations
-- `code-map/core-pipeline-map.md`: deterministic Pipeline walkthrough
+- `code-map/core-pipeline-map.md`: deterministic pipeline walkthrough
 - `code-map/repository-map.md`: package layout and ownership map
 - `how-to/add-canonical-event.md`: extending canonical Event contracts
 - `how-to/update-core-step-pipeline.md`: changing CoreStep/CoreWakeupStep behavior
@@ -20,7 +20,7 @@ This documentation set describes the standalone clean Core package baseline.
 TradingChassis Core is a deterministic trading decision engine library. It owns
 canonical contracts, State reduction, and step-level decision outputs.
 
-## Clean Core Pipeline
+## Clean Core pipeline
 
 1. `EventStreamEntry`
 2. `process_event_entry` / `process_canonical_event`