Skip to content

Commit b50834e

Browse files
authored
docs(readme): restructure for improved readability (#12)
Co-authored-by: bxvtr <bxvtr@users.noreply.github.com>
1 parent df36815 commit b50834e

1 file changed

Lines changed: 35 additions & 37 deletions

File tree

README.md

Lines changed: 35 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -24,40 +24,6 @@ simulation, Live trading, Venue Adapters, and infrastructure around you change.
2424
2525
<img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
2626

27-
## Internally wired vs externally supplied
28-
29-
The clean Core Pipeline is always the same shape; some pieces run inside Core
30-
when you call step APIs, and others must be supplied by your Runtime or tests.
31-
32-
### Internally wired (always part of Core when you call step APIs)
33-
34-
- `process_event_entry` / `process_canonical_event` and canonical reducers
35-
- Candidate combination, dominance, and reconciliation (`combine_candidate_intent_records`)
36-
- Policy admission **mechanism** when `CorePolicyAdmissionContext` is provided
37-
- Execution Control plan/apply **mechanism** when policy + apply contexts are provided
38-
- `CoreStepResult` / `CoreStepDecision` production
39-
40-
### Externally supplied extension points
41-
42-
- **Strategy evaluator**`CoreStepStrategyEvaluator` or `CoreWakeupStrategyEvaluator`
43-
- **Policy evaluator** — any object implementing `PolicyIntentEvaluator` (passed via `CorePolicyAdmissionContext`)
44-
- **Execution Control**`ExecutionControl` instance (passed via `CoreExecutionControlApplyContext`)
45-
- **Configuration** — optional `CoreConfiguration` for positioned market reduction
46-
- **Event bus**`StrategyState` requires an `EventBus`; use `NullEventBus` for standalone Core/tests
47-
48-
### Convenience implementations (optional; not wired by default)
49-
50-
- **Risk Engine** (`RiskEngine`) — provided `PolicyIntentEvaluator` with built-in policy gates
51-
- **`ExecutionControl`** — provided queue/rate/inflight implementation
52-
- **`NullEventBus`** — discards observability events for tests and examples
53-
54-
The minimal quickstart uses an inline allow-all policy to stay small. That does
55-
**not** mean the Risk Engine is unused or dead. Use `RiskEngine` when you want the
56-
built-in Risk Engine policy behavior. See `examples/core_step_quickstart.py` (minimal) and
57-
`examples/core_step_with_risk_engine.py` (Risk Engine variant).
58-
59-
<img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
60-
6127
## Why it is relevant
6228

6329
Trading systems often drift when Backtesting logic, Live logic, policy limits, and
@@ -225,6 +191,40 @@ Runtime dispatches Intents into Orders
225191

226192
<img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
227193

194+
## Internally wired vs externally supplied
195+
196+
The clean Core Pipeline is always the same shape; some pieces run inside Core
197+
when you call step APIs, and others must be supplied by your Runtime or tests.
198+
199+
### Internally wired (always part of Core when you call step APIs)
200+
201+
- `process_event_entry` / `process_canonical_event` and canonical reducers
202+
- Candidate combination, dominance, and reconciliation (`combine_candidate_intent_records`)
203+
- Policy admission **mechanism** when `CorePolicyAdmissionContext` is provided
204+
- Execution Control plan/apply **mechanism** when policy + apply contexts are provided
205+
- `CoreStepResult` / `CoreStepDecision` production
206+
207+
### Externally supplied extension points
208+
209+
- **Strategy evaluator**`CoreStepStrategyEvaluator` or `CoreWakeupStrategyEvaluator`
210+
- **Policy evaluator** — any object implementing `PolicyIntentEvaluator` (passed via `CorePolicyAdmissionContext`)
211+
- **Execution Control**`ExecutionControl` instance (passed via `CoreExecutionControlApplyContext`)
212+
- **Configuration** — optional `CoreConfiguration` for positioned market reduction
213+
- **Event bus**`StrategyState` requires an `EventBus`; use `NullEventBus` for standalone Core/tests
214+
215+
### Convenience implementations (optional; not wired by default)
216+
217+
- **Risk Engine** (`RiskEngine`) — provided `PolicyIntentEvaluator` with built-in policy gates
218+
- **`ExecutionControl`** — provided queue/rate/inflight implementation
219+
- **`NullEventBus`** — discards observability events for tests and examples
220+
221+
The minimal quickstart uses an inline allow-all policy to stay small. That does
222+
**not** mean the Risk Engine is unused or dead. Use `RiskEngine` when you want the
223+
built-in Risk Engine policy behavior. See `examples/core_step_quickstart.py` (minimal) and
224+
`examples/core_step_with_risk_engine.py` (Risk Engine variant).
225+
226+
<img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
227+
228228
## Input / Core / Output / Not Owned By Core
229229

230230
- Input: `EventStreamEntry` values with canonical Events and Event Stream position.
@@ -247,9 +247,7 @@ Runtime dispatches Intents into Orders
247247
| Execution Control | Kubernetes/deployment |
248248
| `CoreStepResult` decision contract | Runtime lifecycle glue |
249249

250-
<img src="https://img.spacergif.org/spacer.gif" width="1" height="32"/>
251-
252-
## Control time and scheduling (Core)
250+
### Control time and scheduling
253251

254252
`ControlSchedulingObligation` is a **non-canonical**, time-dependent hint produced
255253
when Execution Control **apply** defers for **rate limits**. **Inflight** gating is

0 commit comments

Comments
 (0)