MateoBodon · MateoBodon · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,8 +9,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Checkout
@@ -49,6 +50,8 @@ jobs:
           mypy
           --follow-imports=skip
           src/microalpha/audit_lab.py
+          src/microalpha/market_case.py
+          src/microalpha/artifact_verify.py
           src/microalpha/multiple_testing.py
           src/microalpha/engine.py
           src/microalpha/execution.py
@@ -58,11 +61,13 @@ jobs:
         run: |
           git ls-files -z README.md PROJECT.md pyproject.toml LICENSE CHANGELOG.md \
             Makefile 'src/**' 'tests/**' 'scripts/**' '.github/**' \
-            docs/index.md docs/audit-lab.md docs/architecture.md docs/api.md \
+            docs/index.md docs/market-case.md docs/audit-lab.md docs/architecture.md docs/api.md \
             docs/examples.md docs/reproducibility.md docs/leakage-safety.md \
             docs/benchmarks.md docs/limitations.md docs/portfolio_evidence_2026-07-11.md \
+            docs/PORTFOLIO_IMPACT_BRIEF.md \
             docs/wrds.md docs/flagship_momentum_wrds.md docs/results_wrds.md docs/factors.md \
-            'docs/assets/audit_lab/**' \
+            docs/assets/engineering_benchmark_v030.json \
+            'docs/assets/audit_lab/**' 'docs/assets/market_case/**' \
             | xargs -0 detect-secrets-hook --baseline .secrets.baseline
 
       - name: Licensed-data policy
@@ -85,8 +90,33 @@ jobs:
       - name: Reproduce Audit Lab receipt
         run: |
           microalpha audit-demo
+          microalpha verify docs/assets/audit_lab
           git diff --exit-code -- docs/assets/audit_lab
 
+      - name: Reproduce real-data Market Risk Case
+        run: |
+          microalpha market-demo
+          microalpha verify docs/assets/market_case
+          git diff --exit-code -- docs/assets/market_case
+
       - name: MkDocs build
         if: matrix.python-version == '3.12'
         run: mkdocs build --strict
+
+  portable-smoke:
+    name: empirical smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install product
+        run: python -m pip install .
+      - name: Rebuild and verify real-data report
+        run: |
+          python -m microalpha market-demo --out "${{ runner.temp }}/market-case"
+          python -m microalpha verify "${{ runner.temp }}/market-case"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -33,9 +33,11 @@ jobs:
         run: |
           python -m venv /tmp/microalpha-wheel-smoke
           /tmp/microalpha-wheel-smoke/bin/python -m pip install dist/*.whl
-          /tmp/microalpha-wheel-smoke/bin/microalpha audit-demo --out /tmp/audit-lab
-          test "$(sha256sum /tmp/audit-lab/receipt.json | cut -d' ' -f1)" = \
-            "6e36c2397696d7e9eecbd058cbfc1ba522c8ffba7e5798224de86b20457b6575"
+          /tmp/microalpha-wheel-smoke/bin/python -m microalpha audit-demo --out /tmp/audit-lab
+          /tmp/microalpha-wheel-smoke/bin/python -m microalpha verify /tmp/audit-lab
+          /tmp/microalpha-wheel-smoke/bin/python -m microalpha market-demo \
+            --input data/factors/ff5_mom_daily.csv --out /tmp/market-case
+          /tmp/microalpha-wheel-smoke/bin/python -m microalpha verify /tmp/market-case
 
       - name: Attest release artifacts
         uses: actions/attest@v4

diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,12 @@
 .hypothesis/
 .pytest_cache/
+.coverage
+htmlcov/
 .ruff_cache/
 .mypy_cache/
 dist/
 build/
+site/
 *.egg-info/
 __pycache__/
 src/**/__pycache__/

diff --git a/.secrets.baseline b/.secrets.baseline
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-15
+
+### Added
+- Receipt-bound real-data Market Risk Case with strict t+1 chronology,
+  risk-matched and market baselines, annual folds, uncertainty, corrected
+  selection inference, explicit commission/spread/impact costs, and SVG reports.
+- Source-level data manifest, versioned artifact requirements, and
+  `microalpha verify` / `python -m microalpha verify`.
+- Explicit target-weight delta rebalancing with resize, flip, and
+  drawdown-deleveraging regression tests.
+
+### Changed
+- README and Pages now lead with real empirical usefulness while retaining Audit
+  Lab as the deterministic engineering-correctness layer.
+- Supported Python range now includes Python 3.13 and portable module execution.
+
 ## [0.2.0] - 2026-07-15
 
 ### Added

diff --git a/Makefile b/Makefile
@@ -7,7 +7,7 @@ WRDS_ARTIFACT_DIR ?= artifacts/wrds_flagship
 WRDS_SMOKE_CONFIG ?= configs/wfv_flagship_wrds_smoke.yaml
 WRDS_SMOKE_ARTIFACT_DIR ?= artifacts/wrds_flagship_smoke
 
-.PHONY: dev test test-fast test-wrds sample audit-demo wfv wfv-wrds wfv-wrds-smoke wrds wrds-flagship report report-wrds report-wrds-smoke docs clean export-wrds report-wfv gpt-bundle check-data-policy validate-runlogs runs-index
+.PHONY: dev test test-fast test-wrds sample audit-demo market-demo verify-showcase wfv wfv-wrds wfv-wrds-smoke wrds wrds-flagship report report-wrds report-wrds-smoke docs clean export-wrds report-wfv gpt-bundle check-data-policy validate-runlogs runs-index
 
 dev:
 	pip install -e '.[dev]'
@@ -28,6 +28,13 @@ sample:
 audit-demo:
 	microalpha audit-demo --out docs/assets/audit_lab
 
+market-demo:
+	microalpha market-demo --out docs/assets/market_case
+
+verify-showcase:
+	microalpha verify docs/assets/audit_lab
+	microalpha verify docs/assets/market_case
+
 wfv:
 	microalpha wfv --config $(SAMPLE_WFV_CONFIG) --out $(WFV_ARTIFACT_DIR)
 

diff --git a/PROJECT.md b/PROJECT.md
@@ -2,32 +2,32 @@
 
 ## Project Profile
 - Name: microalpha
-- One-liner: Quant research audit lab that makes leakage, impossible execution, omitted costs, and selection overfitting visibly fail.
+- One-liner: Quant research evidence engine for real-data, chronology-safe, costed, walk-forward reports and adversarial correctness audits.
 - Type: quantitative engineering / research infrastructure
 - Risk tier: high
 - Primary languages: Python
 - External dependencies / services: WRDS/CRSP exports (optional), MkDocs (docs site)
 
 ## Goals (what “done” looks like)
-- One-command, deterministic Audit Lab evidence with known ground truth and a SHA-256 receipt.
+- One-command real-data Market Risk Case plus deterministic Audit Lab evidence, each with schemas and a SHA-256 receipt.
 - Event-scheduled execution, point-in-time availability, explicit cost reconciliation, and benchmark-differential selection correction.
-- Clean-clone install, usable CLI/API, green multi-version CI, and product-first docs.
+- Clean-clone install, portable CLI/API, green cross-platform CI, and product-first docs.
 - Honest public case studies; a negative research result is preserved instead of tuned away.
 
 ## Non-goals (explicitly out of scope)
 - Live trading execution or brokerage integration.
 - Guaranteed alpha discovery or performance claims.
 
 ## Current state
-- What works: deterministic Audit Lab, sample/public configs, WFV runs, reporting, docs, CLI/API, and tests.
+- What works: deterministic real-data Market Risk Case, Audit Lab, sample/public configs, WFV runs, reporting, verifier, docs, CLI/API, and tests.
 - Optional: licensed-data workflows require authorized local exports and never ship raw rows.
 - Historical research: six frozen mechanisms failed promotion gates; 2023–2025 remains sealed.
 - Biggest risks: incorrect source availability metadata, survivorship bias, uncalibrated simulation costs, and claims stronger than receipts.
 
 ## Quickstart (how to run)
 - `python -m venv .venv && source .venv/bin/activate && pip install .`
-- `microalpha audit-demo`
-- `git diff --exit-code -- docs/assets/audit_lab`
+- `python -m microalpha market-demo && python -m microalpha verify docs/assets/market_case`
+- `python -m microalpha audit-demo && python -m microalpha verify docs/assets/audit_lab`
 - Contributors: `pip install -e '.[dev]' && pytest -q`
 
 ## Architecture (high-level)

diff --git a/README.md b/README.md
@@ -2,31 +2,59 @@
 
 [![CI](https://github.com/MateoBodon/microalpha/actions/workflows/ci.yml/badge.svg)](https://github.com/MateoBodon/microalpha/actions/workflows/ci.yml)
 [![Documentation](https://img.shields.io/badge/docs-live-2563eb)](https://mateobodon.github.io/microalpha/)
-[![Python 3.10–3.12](https://img.shields.io/badge/python-3.10–3.12-0ea5e9)](pyproject.toml)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10–3.13-0ea5e9)](pyproject.toml)
 [![MIT License](https://img.shields.io/badge/license-MIT-22c55e)](LICENSE)
 
-**A quant research audit lab that catches four ways a backtest lies: data
-leakage, impossible execution, omitted costs, and selection overfitting.**
+**A quantitative engineering lab that turns market data into chronology-safe,
+costed, walk-forward evidence—and makes invalid backtests visibly fail.**
 
 Microalpha is an event-driven Python system for turning a quantitative idea
-into timestamped, costed, walk-forward evidence. Its flagship is not a profitable
-strategy. It is a deterministic, known-ground-truth fixture that proves the
-research pipeline rejects attractive results when they are invalid.
+into a source-hashed research report. v0.3 pairs a real-data market-risk case
+with a known-ground-truth Audit Lab: one shows empirical usefulness, the other
+proves the pipeline rejects attractive results when they are invalid.
 
-![Four paired Audit Lab results: leaky versus point-in-time data, same-tick versus queued execution, gross versus costed returns, and naive versus corrected selection](docs/assets/audit_lab/audit_lab.svg)
+![Real-data market case: out-of-sample risk, return, drawdown, and corrected inference](docs/assets/market_case/market_case.svg)
 
-## The 30-second proof
+## The one-minute result
 
 ```bash
 git clone https://github.com/MateoBodon/microalpha.git
 cd microalpha
-python -m venv .venv && source .venv/bin/activate
 python -m pip install .
-microalpha audit-demo
+python -m microalpha market-demo
+python -m microalpha verify docs/assets/market_case
+```
+
+The command is offline and recreates the real-data report, daily decision/fill
+ledger, annual folds, source manifest, uncertainty, selection distribution,
+schemas, SVGs, and receipt.
+
+| 2017–2025 OOS metric | Vol target, net | US market | Static risk-matched |
+| --- | ---: | ---: | ---: |
+| Annualized return | 11.77% | 15.14% | 10.67% |
+| Annualized volatility | 11.37% | 19.25% | 12.03% |
+| Sharpe | 1.04 | 0.83 | 0.90 |
+| Maximum drawdown | −15.31% | −34.22% | −22.38% |
+
+The fixed rule reduced risk and drawdown and raised descriptive Sharpe. It did
+**not** produce statistically significant differential return after correcting
+across every disclosed lookback (`p=0.467`), and its return remained below the
+unscaled market. The investment claim is therefore **none**. Read the
+[real-data method and report](docs/market-case.md).
+
+![Out-of-sample equity and drawdown against market and risk-matched baselines](docs/assets/market_case/equity_drawdown.svg)
+
+## Correctness layer: four ways a backtest lies
+
+![Four paired Audit Lab results: leaky versus point-in-time data, same-tick versus queued execution, gross versus costed returns, and naive versus corrected selection](docs/assets/audit_lab/audit_lab.svg)
+
+```bash
+python -m microalpha audit-demo
+python -m microalpha verify docs/assets/audit_lab
 ```
 
-The command uses no network, provider, licensed data, or hidden holdout. It
-recreates the tracked evidence under `docs/assets/audit_lab/`.
+Audit Lab uses no network, provider, licensed data, or hidden holdout. It
+recreates the tracked correctness evidence under `docs/assets/audit_lab/`.
 
 | Failure injected into the synthetic fixture | Naive result | Audited result | What stopped it |
 | --- | ---: | ---: | --- |
@@ -57,7 +85,8 @@ performance promises.
 
 - **Point-in-time discipline** — `require_point_in_time` fails closed on
   `available_at > decision_at` and reports exact violating row IDs and counts;
-  production data manifests retain source lineage.
+  the Market Risk Case manifest retains publisher, source URL, content hash,
+  date range, units, and availability rules.
 - **Event-time execution** — orders become planned execution slices; future
   fills cannot change cash, positions, turnover, P&L, or logs before their
   market event is processed.
@@ -101,7 +130,9 @@ boundary. See the [architecture guide](docs/architecture.md) and
 
 | Command | Purpose |
 | --- | --- |
+| `microalpha market-demo` | Rebuild the real-data market-risk report and receipt |
 | `microalpha audit-demo` | Rebuild the deterministic correctness fixture and receipt |
+| `microalpha verify <artifact-dir>` | Check schema, chronology, cost identity, and hashes |
 | `microalpha --version` | Print the installed distribution version |
 | `microalpha run --config <yaml> --out <dir>` | Run one event-driven simulation |
 | `microalpha wfv --config <yaml> --out <dir>` | Run walk-forward selection and evaluation |
@@ -125,8 +156,12 @@ execution models, slippage, reporting, and statistical controls. See the
 
 ```bash
 # User-facing proof
-microalpha audit-demo
-git diff --exit-code -- docs/assets/audit_lab
+python -m microalpha market-demo
+python -m microalpha audit-demo
+python -m microalpha verify docs/assets/market_case
+python -m microalpha verify docs/assets/audit_lab
+python benchmarks/bench_v030.py --output docs/assets/engineering_benchmark_v030.json
+git diff --exit-code -- docs/assets/market_case docs/assets/audit_lab
 
 # Contributor gates
 python -m pip install -e '.[dev]'
@@ -141,17 +176,19 @@ pytest -m "not wrds" --cov=microalpha --cov-report=term-missing
 python scripts/check_data_policy.py
 git ls-files -z README.md PROJECT.md pyproject.toml LICENSE CHANGELOG.md \
   Makefile 'src/**' 'tests/**' 'scripts/**' '.github/**' \
-  docs/index.md docs/audit-lab.md docs/architecture.md docs/api.md \
+  docs/index.md docs/market-case.md docs/audit-lab.md docs/architecture.md docs/api.md \
   docs/examples.md docs/reproducibility.md docs/leakage-safety.md \
   docs/benchmarks.md docs/limitations.md docs/portfolio_evidence_2026-07-11.md \
   docs/wrds.md docs/flagship_momentum_wrds.md docs/results_wrds.md docs/factors.md \
-  'docs/assets/audit_lab/**' \
+  docs/assets/engineering_benchmark_v030.json \
+  'docs/assets/audit_lab/**' 'docs/assets/market_case/**' \
   | xargs -0 detect-secrets-hook --baseline .secrets.baseline
 mkdocs build --strict
 ```
 
 CI runs the supported Python matrix and enforces lint, format, types, secret
-scanning, tests, coverage, deterministic Audit Lab regeneration, and strict docs.
+scanning, tests, coverage, both deterministic regenerations, artifact
+verification, and strict docs.
 
 Two earlier synthetic example bundles remain available for schema and reporting
 inspection: [`artifacts/sample_flagship`](artifacts/sample_flagship) and
@@ -178,13 +215,14 @@ rows are not distributed.
 | --- | --- |
 | `src/microalpha/` | Engine, events, data, strategies, execution, portfolio, risk, inference, reporting |
 | `tests/` | Chronology, execution, holdout, statistics, artifact, CLI, and data-policy contracts |
+| `docs/assets/market_case/` | Real-data ledger, folds, report, schema, source manifest, and receipt |
 | `docs/assets/audit_lab/` | Generated public correctness evidence and SHA-256 receipt |
 | `configs/` | Reproducible sample, public, and local licensed-data workflows |
 | `docs/` | Product guides, methodology, API, limitations, and historical case study |
 | `artifacts/` | Run-scoped simulation outputs; most generated paths remain untracked |
 
 Historical project logs remain available for provenance, but a new user should
-start with **Audit Lab → Architecture → API → Reproducibility → Limitations**.
+start with **Market Risk Case → Audit Lab → Architecture → Reproducibility → Limitations**.
 
 ## Limits and claim boundary