Reposition microalpha as a quant research audit lab

.github/workflows/ci.yml

@@ -14,15 +14,15 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Cache pip
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
@@ -43,8 +43,31 @@ jobs:
       - name: isort
         run: isort --check-only .
 
+      - name: Mypy
+        if: matrix.python-version == '3.12'
+        run: >-
+          mypy
+          --follow-imports=skip
+          src/microalpha/audit_lab.py
+          src/microalpha/multiple_testing.py
+          src/microalpha/engine.py
+          src/microalpha/execution.py
+          src/microalpha/reporting/factors.py
+
       - name: detect-secrets
-        run: detect-secrets scan --baseline .secrets.baseline
+        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/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/**' \
+            | xargs -0 detect-secrets-hook --baseline .secrets.baseline
+
+      - name: Licensed-data policy
+        if: matrix.python-version == '3.12'
+        run: python scripts/check_data_policy.py
 
       - name: Pytest (unit)
         run: pytest -m "not wrds" --cov=microalpha --cov-report=xml --cov-report=html
@@ -54,11 +77,16 @@ jobs:
 
       - name: Upload HTML coverage
         if: matrix.python-version == '3.12'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: htmlcov
           path: htmlcov
 
+      - name: Reproduce Audit Lab receipt
+        run: |
+          microalpha audit-demo
+          git diff --exit-code -- docs/assets/audit_lab
+
       - name: MkDocs build
         if: matrix.python-version == '3.12'
-        run: mkdocs build
+        run: mkdocs build --strict

.github/workflows/docs.yml

@@ -16,10 +16,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

.github/workflows/release.yml

@@ -3,28 +3,57 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
   workflow_dispatch:
 
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
 jobs:
-  build-and-publish:
+  build-verify-release:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.11'
-      - name: Install build tools
+          python-version: "3.12"
+
+      - name: Build distributions
         run: |
           python -m pip install --upgrade pip
-          pip install build twine
-      - name: Build sdist/wheel
-        run: python -m build
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Smoke-test wheel in a clean environment
+        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"
+
+      - name: Attest release artifacts
+        uses: actions/attest@v4
+        with:
+          subject-path: "dist/*"
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v7
         with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          name: microalpha-distributions
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Create GitHub release
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --verify-tag --generate-notes
 
+      # The "microalpha" name on PyPI belongs to an unrelated project.
+      # Releases intentionally remain GitHub-only unless the distribution is renamed.

.secrets.baseline

@@ -124,7 +124,7 @@
     {
       "path": "detect_secrets.filters.regex.should_exclude_file",
       "pattern": [
-        "(artifacts|data_sp500|data_sp500_enriched|site)"
+        "(artifacts|data_sp500|data_sp500_enriched|site|docs/assets/audit_lab|docs/audit-lab.md)"
       ]
     }
   ],

CHANGELOG.md

@@ -3,7 +3,26 @@
 All notable changes to this project will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com) and the project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
+
+## [0.2.0] - 2026-07-15
+
 ### Added
+- Deterministic synthetic Audit Lab covering point-in-time availability,
+  event-time execution, cost reconciliation, and selection correction.
+- Null-centered synchronous benchmark-differential max-statistic test.
+- Byte-stable JSON, CSV, and SVG evidence with a SHA-256 receipt.
+
+### Fixed
+- Future fills are planned and materialized only when the engine reaches their
+  market timestamp; positions, cash, P&L, turnover, and logs no longer mutate
+  early.
+- Public product, package metadata, documentation navigation, and claim
+  boundaries now agree.
+- Release automation no longer attempts to publish to an unrelated PyPI
+  namespace; wheels are clean-installed, smoke-tested, attested, and attached to
+  GitHub releases.
+
+### Earlier project history
 - A public-safe validation-frontier chart with its source CSV and an evidence note binding each published aggregate metric to the accepted 2026-07-11 research artifacts.
 - Repository guardrails: pytest marker config, WRDS detection helpers, log fan-out to `artifacts/logs/`.
 - Pre-commit automation (black, isort, ruff, detect-secrets) plus tightened `.gitignore`.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateo Bodon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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 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 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]'
@@ -25,6 +25,9 @@ test-wrds:
 sample:
 	microalpha run --config $(SAMPLE_CONFIG) --out $(ARTIFACT_DIR)
 
+audit-demo:
+	microalpha audit-demo --out docs/assets/audit_lab
+
 wfv:
 	microalpha wfv --config $(SAMPLE_WFV_CONFIG) --out $(WFV_ARTIFACT_DIR)
 

PROJECT.md

@@ -2,37 +2,38 @@
 
 ## Project Profile
 - Name: microalpha
-- One-liner: Leakage-safe, event-driven backtesting engine with walk-forward cross-validation and reporting.
-- Type: research/trading
+- One-liner: Quant research audit lab that makes leakage, impossible execution, omitted costs, and selection overfitting visibly fail.
+- 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)
-- Leakage-safe backtesting and walk-forward validation with reproducible artifacts.
-- Sample/public data runs plus an optional WRDS pipeline for real data.
-- Report generation (plots + Markdown summaries) suitable for audit/review.
+- One-command, deterministic Audit Lab evidence with known ground truth 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.
+- 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: sample/public configs, WFV runs, reporting, docs + tests.
-- What’s missing: real-data runs require local WRDS exports and credentials.
-- What’s broken: see `project_state/KNOWN_ISSUES.md` for open issues.
-- Biggest risks: leakage/survivorship bias, missing WRDS data, misreported results.
+- What works: deterministic Audit Lab, sample/public configs, WFV runs, reporting, 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 -e '.[dev]'`
-- `make sample && make report`
-- `make wfv && make report-wfv`
-- `pytest -q`
+- `python -m venv .venv && source .venv/bin/activate && pip install .`
+- `microalpha audit-demo`
+- `git diff --exit-code -- docs/assets/audit_lab`
+- Contributors: `pip install -e '.[dev]' && pytest -q`
 
 ## Architecture (high-level)
 - Modules: `src/microalpha/` (engine, data, strategies, reporting, CLI).
-- Data flow: DataHandler -> Engine -> Strategy -> Portfolio -> Broker -> Trades.
-- Key invariants: strict chronology, t+1 execution, point-in-time universe.
+- Data flow: DataHandler -> Engine clock -> Strategy -> Portfolio -> ExecutionPlan -> Broker/materialized FillEvent -> Evidence receipt.
+- Key invariants: availability at decision time, no early fill mutation, exact cost reconciliation, isolated test/holdout windows, synchronous null-centered selection correction.
 
 ## Constraints / preferences
 - Performance constraints: deterministic runs; prefer reproducible pipelines.