Architecture

CRITERION System Architecture

This document describes how CRITERION fits together: its module structure, data flow, and artifact chain.

Module Structure

CRITERION is organized into domain modules under src/criterion/:

• cli — Command-line interface; all user-facing commands
• config — Configuration models (RootConfig, strategy engines, overfitting safeguards)
• engines — Strategy engines (expansion, reversion, continuation) implementing doctrine
• io — Input/output models: RunManifestV1, ExecutionBundleV1, TradeRecordV1, EvaluationResultV1
• audit — Shareability validation (check_shareability, ShareabilityCheckResultV1)
• sharing — Shareable pack creation and loading
• analysis — Complexity budget, OOS validation, walk-forward, parameter inventory
• backtest — Equity curves, risk metrics, attribution, reports
• data — Market data sources, caching, validation
• portfolio — Position sizing, rebalancing, constraints
• live_trading / paper_trading — Execution and broker adapters

Data Flow

Configuration flows through engines to artifacts:

1. config.yaml — Root config (strategy engines, overfitting safeguards, broker, data sources)
2. Run — Execution produces run_manifest.json and execution_bundle.json
3. RunManifestV1 — Run metadata, git provenance, artifacts inventory, optional execution records
4. ExecutionBundleV1 — Daily state, trade records, evaluation log, data period
5. TradeRecordV1 — Per-trade structure with entry, exit, rule_provenance
6. ShareablePackV1 — Sanitized bundle + strategy config excerpt for public sharing

Artifact Chain

config.yaml
    → RunManifestV1 (run metadata, artifacts)
    → ExecutionBundleV1 (trades, evaluation_log, data_period)
        → TradeRecordV1 (with rule_provenance)
        → ShareablePackV1 (credentials stripped)

Live Execution Pipeline

The criterion run live path produces the same artifact quality as backtest runs:

1. Engine execution — Expansion, Reversion, Continuation engines run on market data
2. Exit checker — Existing positions in open_positions.json are evaluated for stop/target/max-hold; closed positions become TradeRecordV1
3. Candidate bridge — New engine candidates are converted to OpenPositionV1 (via candidate_to_open_position)
4. Position ledger — open_positions.json is updated with still-open and newly opened positions
5. Bundle population — ExecutionBundleV1 is populated with trade records (exits + new entries), evaluation_log, data_period
6. Journal — trade_journal.md is rendered and written alongside the bundle

Artifacts produced: run_manifest.json, execution_bundle.json, daily_state.md, run_summary.md, trade_journal.md. The position ledger (open_positions.json) lives in --positions-dir (default: sibling positions/ of the run output directory).

Contract Snapshots

Pydantic models that define the public contract are registered in criterion.contracts.snapshot. Schema snapshots live in contracts/snapshots/. Any change to a model requires regenerating snapshots:

python -m criterion.contracts.snapshot --write

CLI Command Surface

• run — Execute a backtest or dry run; emits run_manifest.json and execution_bundle.json
• validate-run — Verify schema, run_id consistency, artifact hashes
• audit — Shareability check (schema, integrity, min days/trades, rule provenance, evaluation log)
• backtest — Build equity curve, risk metrics, attribution, trade journal
• share — Create a shareable pack from bundle + config (or share load to load)
• compare — Compare backtest vs paper/live bundles
• query — “Why this trade?” or “Why not?” (requires evaluation_log)
• oos-validate — In-sample / out-of-sample validation
• walk-forward — Walk-forward validation folds
• sensitivity — Parameter sensitivity analysis
• regime-breakdown — Regime performance breakdown report
• dashboard — Interactive HTML dashboard
• doctor — Environment sanity checks; optional --bundle and --positions-dir for live pipeline integrity (warns on empty bundle with open positions from earlier runs)