Add multi-asset portfolio support with a cross-sectional null

Single-asset backtesting caps this at hobbyist use: anyone doing real
cross-sectional work (rank N names, long the top decile, short the bottom)
could not express their strategy at all. This adds the portfolio path.

Panel (algotrader/panel.py): aligned T x N field frames with per-symbol
provenance. Missing data deliberately stays missing — forward-filling a symbol
through days it did not trade invents liquidity and lets a strategy hold a
delisted name forever. That choice is what makes survivorship measurable, and
Panel.survivorship() reports it: a universe where every name still trades after
a decade was chosen after the fact, and the Reality Score now caps at 60 when it
finds one.

Matrix engine (algotrader/portfolio.py): T x N weights with drift-aware
turnover. Hold 50% of a book in a name that doubles and you are at 67% without
trading, so charging |target[t] - target[t-1]| understates the cost of doing
nothing. Turnover is measured against the drifted weight instead. A rebalance
schedule (D/W/M/Q) lets a monthly book drift between dates rather than paying
daily to stand still — the one genuinely recursive step, everything else stays
vectorised.

The same drift correction went into the single-asset engine, which had the same
flaw for fractional and short positions: a 100% short whose asset falls 10%
drifts to -82% and genuinely needs rebalancing. Both engines now produce
bit-identical results on single-asset cases, verified across four target shapes.

Cross-sectional null (validation/cross_permutation.py): shuffling the price path
is the wrong test for a book that ranks names — it destroys the market's whole
correlation structure and almost any long-short book clears a null that weak.
Instead we permute weights across assets within each date. Calendar effects,
correlations, gross exposure, net exposure and position count all survive
exactly; only the link between choice and asset is destroyed.

Costs are neutralised inside that test, and this mattered. A real momentum book
holds many of the same names between rebalances; a shuffled book churns and pays
for it. Charging costs penalised the null for turnover the strategy never had,
biasing p-values downward — mean p under H0 was 0.445 instead of 0.50. With
costs neutralised it is 0.485, and implementability is left to the cost stress
test, which measures it directly.

Attribution (algotrader/attribution.py): regress returns on style factors built
from the panel itself — market, momentum, low-vol, reversal, liquidity — with
White standard errors, since return series are heteroskedastic and classical
errors would overstate alpha. Equal weight comes back R2 0.97, market beta 0.99,
no alpha: you have reinvented the index. Factors are proxies and labelled as
such; dollar volume is liquidity, not size.

Also: cross-sectional strategy zoo with equal-weight and random-book controls,
walk_forward_panel, a Portfolio tab in the Space, a `portfolio` CLI subcommand,
and verdict wording parameterised so the portfolio path stops talking about
"shuffled markets" and "buy & hold".

Two pandas 3.0 breakages fixed in the v1 tests, which would have hit CI as soon
as it resolved pandas 3.x: to_datetime now infers datetime64[us] rather than
[ns], and strings default to StringDtype rather than object.

183 tests, no network. The cross-sectional null is calibrated (p ~ 0.5 with no
structure, power rising monotonically with effect size) and the tests assert the
permutation preserves each date's exposure and position count exactly — if it
did not, the null would be measuring something else.

.github/workflows/sync-hf-space.yml

@@ -37,7 +37,7 @@ jobs:
         run: |
           pip install --quiet -r requirements-space.txt pytest
           python -m pytest tests/test_v2_engine.py tests/test_v2_validation.py \
-                           tests/test_v2_strategies.py -q
+                           tests/test_v2_strategies.py tests/test_v2_portfolio.py -q
           ALGOTRADER_OFFLINE=1 python -c "import app; app.build_app(); print('Space builds OK')"
 
       - name: Push to the Space

README.md

@@ -17,6 +17,12 @@ unchanged and still lives here — see [docs/AGENTIC_SYSTEM_V1.md](docs/AGENTIC_
 
 ---
 
+## Two labs
+
+**The Lab** validates a timing rule on one asset. **The Portfolio Lab** validates a
+cross-sectional book that ranks many names — and it asks three harder questions,
+because a long-short book fails in ways a timing rule cannot.
+
 ## The four ways a backtest lies
 
 | The lie | The test | Where |
@@ -55,6 +61,56 @@ Block mode resamples contiguous chunks instead of single bars, preserving
 short-horizon momentum and volatility clustering — a harder null that trend
 strategies deserve to be held to.
 
+## Cross-sectional books get a harder null
+
+Shuffling the price path is the right null for a timing rule and the *wrong* one for
+a book that ranks names: it destroys the market's whole correlation structure, and
+almost any long-short book clears a null that weak.
+
+So the Portfolio Lab permutes the **weights across assets within each date**. Every
+calendar effect survives. Every correlation between names survives. Each date's gross
+exposure, net exposure and position count survive *exactly*. The only thing destroyed
+is the link between the strategy's choice and the asset it chose.
+
+A book that beats that null is picking names. One that doesn't was being paid for
+market exposure or a style tilt — which the factor regression measures directly:
+
+| Question | Test |
+|---|---|
+| Did it pick the right names? | Within-date weight permutation |
+| Is it alpha, or beta you can buy for 3bps? | Style regression (market, momentum, low-vol, reversal, liquidity) with White standard errors |
+| Does the universe contain the losers? | Survivorship measured, not assumed |
+
+That last one is not optional. A universe where every name is still trading after ten
+years was chosen after the fact, and every result computed on it is an upper bound.
+The Panel measures survival directly and the Reality Score caps at 60 when it finds
+none.
+
+```python
+from algotrader import PortfolioLabConfig, run_portfolio_lab
+
+report = run_portfolio_lab(PortfolioLabConfig(
+    symbols=["SPY", "QQQ", "AAPL", "MSFT", "NVDA", "GLD", "TLT"],
+    strategy="xs_momentum",
+    rebalance="M",
+))
+print(report.verdict["grade"], report.permutation.p_value)
+print(report.attribution["note"])
+print(report.survivorship.note)
+```
+
+```bash
+python -m algotrader.cli portfolio --symbols SPY,QQQ,AAPL,MSFT,NVDA --strategy xs_momentum
+```
+
+## Turnover is measured against drift, not against the last target
+
+Holding 50% of a book in a name that doubles leaves you at 67% without trading. A
+backtest that charges turnover as `|target[t] - target[t-1]|` understates the cost of
+doing nothing and overstates the cost of rebalancing. Both engines measure turnover
+against the *drifted* weight instead, and a rebalance schedule (`D`/`W`/`M`/`Q`) lets a
+monthly book drift between dates rather than paying daily to stand still.
+
 ## No look-ahead, by construction
 
 A strategy emits a target exposure at each bar's close using only data up to that
@@ -119,9 +175,12 @@ deterministic and network-free.
 
 ## The strategy zoo
 
-`buy_and_hold` · `sma_cross` · `ema_cross` · `macd_trend` · `rsi_reversion` ·
-`bollinger_reversion` · `donchian_breakout` · `momentum` · `vol_target_momentum` ·
-`channel_trend` · `coin_flip`
+Single asset: `buy_and_hold` · `sma_cross` · `ema_cross` · `macd_trend` ·
+`rsi_reversion` · `bollinger_reversion` · `donchian_breakout` · `momentum` ·
+`vol_target_momentum` · `channel_trend` · `coin_flip`
+
+Cross-sectional: `equal_weight` · `xs_momentum` · `xs_reversal` · `low_volatility` ·
+`xs_value_proxy` · `xs_random`
 
 Buy & hold and the coin flip are controls, and they stay in the arena on purpose: a
 leaderboard without a control group is marketing, not measurement.
@@ -157,7 +216,7 @@ carries the full v1 stack for CI, Docker and the FinRL agents.
 ## Tests
 
 ```bash
-python -m pytest tests/test_v2_*.py -q     # 111 tests, ~15s, no network
+python -m pytest tests/test_v2_*.py -q     # 162 tests, ~25s, no network
 ```
 
 The validation tests check both directions, which is the part that matters: the
@@ -166,6 +225,12 @@ genuine serial correlation and assert that the permutation test finds it, that P
 stays near 0.5 on pure noise and drops below 0.15 when one variant is genuinely
 better, and that walk-forward efficiency survives.
 
+The cross-sectional null is held to the same standard, and it is calibrated: on a
+universe with no cross-sectional structure it returns p ≈ 0.5, and its power rises
+monotonically with the size of the injected effect. The tests also assert the
+permutation preserves each date's gross exposure, net exposure and position count
+exactly — if it did not, the null would be testing something else.
+
 ## References
 
 - Bailey & López de Prado (2014), *The Deflated Sharpe Ratio: Correcting for Selection

SPACE_README.md

@@ -41,6 +41,19 @@ you need before risking money: **how much of that was luck?**
 Each contributes to a single **Reality Score** out of 100, with a grade from A to F.
 The scale is deliberately harsh. Most strategies people post online score below 40.
 
+## Two labs
+
+**The Lab** validates a timing rule on one asset. **The Portfolio Lab** validates a
+book that ranks many names — and it gets a harder null: we keep every date's gross
+exposure, net exposure and position count exactly as they were and randomise only
+**which name got which weight**. A book that beats that is picking names. One that
+doesn't was being paid for style exposure you can buy in an ETF, which the factor
+regression measures directly.
+
+It also measures survivorship rather than assuming it away. A universe where every
+name is still trading after ten years was chosen after the fact, and every number
+computed on it is an upper bound.
+
 ## Try this first
 
 Run the **Arena** tab on `SPY`. On most markets and most date ranges, plain

algotrader/__init__.py

@@ -12,29 +12,50 @@ Quick start::
     print(report.verdict["verdict"])
 """
 
+from .attribution import build_style_factors, factor_attribution
+from .cross_sectional import XS_REGISTRY, get_xs_strategy, list_xs_strategies
 from .data import load_ohlcv, simulate_ohlcv
 from .engine import run_backtest
 from .lab import LabConfig, LabReport, run_arena, run_lab
 from .metrics import compute_metrics
+from .panel import Panel, load_panel
+from .portfolio import rebalance_schedule, run_portfolio_backtest
+from .portfolio_lab import PortfolioLabConfig, PortfolioLabReport, run_portfolio_arena, run_portfolio_lab
 from .strategies import REGISTRY, get_strategy, list_strategies
 from .types import BacktestResult, CostModel, MarketData
 from .verdict import reality_score
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     "__version__",
+    # single asset
     "LabConfig",
     "LabReport",
     "run_lab",
     "run_arena",
     "run_backtest",
-    "compute_metrics",
-    "load_ohlcv",
-    "simulate_ohlcv",
     "get_strategy",
     "list_strategies",
     "REGISTRY",
+    # multi asset
+    "Panel",
+    "load_panel",
+    "run_portfolio_backtest",
+    "rebalance_schedule",
+    "PortfolioLabConfig",
+    "PortfolioLabReport",
+    "run_portfolio_lab",
+    "run_portfolio_arena",
+    "get_xs_strategy",
+    "list_xs_strategies",
+    "XS_REGISTRY",
+    "build_style_factors",
+    "factor_attribution",
+    # shared
+    "compute_metrics",
+    "load_ohlcv",
+    "simulate_ohlcv",
     "BacktestResult",
     "CostModel",
     "MarketData",

algotrader/attribution.py

@@ -0,0 +1,148 @@
+"""Style attribution: is this alpha, or is it beta you could have bought cheaply?
+
+The most common way a strategy is oversold is not fraud or overfitting — it is
+that the "edge" is a well-known risk premium wearing a new name. A book that
+loads on market beta, or on momentum, or on low-volatility, will produce a
+respectable Sharpe and an exciting story, and you can buy the same exposure in
+an ETF for a few basis points.
+
+So we regress the strategy's returns on style factors built from the panel
+itself and ask what is left over. If the intercept is not distinguishable from
+zero, the strategy has no alpha — however good its Sharpe looked.
+
+Factors are constructed from the universe under test rather than downloaded,
+which keeps this offline and self-consistent. The tradeoff is that they are
+proxies: without fundamentals there is no true value or size factor, so those
+are labelled honestly as what they are.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+from .panel import Panel
+from .portfolio import run_portfolio_backtest
+from .types import CostModel
+
+__all__ = ["build_style_factors", "factor_attribution"]
+
+_FREE = CostModel(0.0, 0.0, 0.0)  # factors are theoretical portfolios
+
+
+def _long_short(panel: Panel, scores: pd.DataFrame, rebalance: int = 21) -> pd.Series:
+    from .cross_sectional import _rebalance_hold, scores_to_weights
+
+    weights = _rebalance_hold(scores_to_weights(scores), rebalance)
+    return run_portfolio_backtest(panel, weights, costs=_FREE).returns
+
+
+def build_style_factors(panel: Panel, rebalance: int = 21) -> pd.DataFrame:
+    """Construct market and style factor returns from the panel itself."""
+    close = panel.close
+    listed = close.notna()
+    counts = listed.sum(axis=1).replace(0, np.nan)
+
+    equal = listed.astype(float).div(counts, axis=0).fillna(0.0)
+    market = run_portfolio_backtest(panel, equal, costs=_FREE).returns
+
+    factors = {
+        "market": market,
+        "momentum": _long_short(panel, close.shift(20) / close.shift(250) - 1.0, rebalance),
+        "low_vol": _long_short(panel, -close.pct_change().rolling(60, min_periods=60).std(), rebalance),
+        "reversal": _long_short(panel, -close.pct_change(5), rebalance),
+        # Dollar volume is a liquidity proxy, not market cap. Named accordingly.
+        "liquidity": _long_short(panel, -np.log(panel.dollar_volume().replace(0, np.nan)), rebalance),
+    }
+    return pd.DataFrame(factors).reindex(panel.index).fillna(0.0)
+
+
+def _white_standard_errors(x: np.ndarray, residuals: np.ndarray, xtx_inv: np.ndarray) -> np.ndarray:
+    """Heteroskedasticity-robust (White) standard errors.
+
+    Return series are famously heteroskedastic — volatility clusters — and
+    classical standard errors would overstate the significance of alpha.
+    """
+    meat = x.T @ (x * (residuals**2)[:, None])
+    covariance = xtx_inv @ meat @ xtx_inv
+    return np.sqrt(np.maximum(np.diag(covariance), 0.0))
+
+
+def factor_attribution(
+    returns: pd.Series,
+    factors: pd.DataFrame,
+    periods_per_year: int = 252,
+    alpha_t_threshold: float = 2.0,
+) -> Dict[str, object]:
+    """Regress strategy returns on style factors; report annualised alpha and betas."""
+    aligned = pd.concat([returns.rename("strategy"), factors], axis=1).dropna()
+    if len(aligned) < 60 or factors.shape[1] == 0:
+        return {"available": False, "note": "Not enough overlapping observations for attribution."}
+
+    y = aligned["strategy"].to_numpy(dtype=float)
+    names = list(factors.columns)
+    x = np.column_stack([np.ones(len(aligned))] + [aligned[c].to_numpy(dtype=float) for c in names])
+
+    # Drop factors that are constant or collinear; a singular fit is worse than
+    # a smaller one.
+    keep = [0] + [i + 1 for i, c in enumerate(names) if aligned[c].std() > 1e-12]
+    x = x[:, keep]
+    names = [names[i - 1] for i in keep[1:]]
+
+    try:
+        xtx_inv = np.linalg.pinv(x.T @ x)
+    except np.linalg.LinAlgError:  # pragma: no cover - pinv rarely fails
+        return {"available": False, "note": "Factor matrix is singular."}
+
+    beta = xtx_inv @ x.T @ y
+    fitted = x @ beta
+    residuals = y - fitted
+    errors = _white_standard_errors(x, residuals, xtx_inv)
+    t_stats = np.divide(beta, errors, out=np.zeros_like(beta), where=errors > 0)
+
+    ss_res = float(residuals @ residuals)
+    ss_tot = float(((y - y.mean()) ** 2).sum())
+    r_squared = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+
+    alpha_period = float(beta[0])
+    alpha_annual = alpha_period * periods_per_year
+    alpha_t = float(t_stats[0])
+    significant = bool(abs(alpha_t) >= alpha_t_threshold and alpha_annual > 0)
+
+    betas = {name: float(b) for name, b in zip(names, beta[1:])}
+    beta_ts = {name: float(t) for name, t in zip(names, t_stats[1:])}
+    dominant = max(betas, key=lambda k: abs(betas[k])) if betas else None
+
+    if significant:
+        note = (
+            f"Alpha of {alpha_annual:.1%} a year survives the style regression "
+            f"(t = {alpha_t:.1f}). Something here is not explained by market, momentum, "
+            "low-volatility, reversal or liquidity exposure."
+        )
+    else:
+        explained = (
+            f" Most of the variation is {dominant} exposure (beta {betas[dominant]:.2f})."
+            if dominant
+            else ""
+        )
+        note = (
+            f"Alpha is {alpha_annual:.1%} a year with t = {alpha_t:.1f}, which is not "
+            f"distinguishable from zero. The style factors explain {r_squared:.0%} of the "
+            f"returns.{explained} You can buy that exposure far more cheaply than by "
+            "running this strategy."
+        )
+
+    return {
+        "available": True,
+        "alpha_annual": alpha_annual,
+        "alpha_t_stat": alpha_t,
+        "alpha_significant": significant,
+        "betas": betas,
+        "beta_t_stats": beta_ts,
+        "r_squared": float(r_squared),
+        "dominant_factor": dominant,
+        "n_obs": int(len(aligned)),
+        "note": note,
+    }

algotrader/charts.py

@@ -67,8 +67,8 @@ def empty_figure(message: str = _EMPTY_NOTE, height: int = 340) -> go.Figure:
     return fig
 
 
-def equity_chart(report) -> go.Figure:
-    """Strategy equity against buy & hold, both indexed to the same start."""
+def equity_chart(report, benchmark_label: str = "Buy & hold") -> go.Figure:
+    """Strategy equity against its benchmark, both indexed to the same start."""
     bt = report.backtest
     strat = bt.equity / bt.equity.iloc[0] * 100.0
     bench = bt.benchmark_equity / bt.benchmark_equity.iloc[0] * 100.0
@@ -76,9 +76,9 @@ def equity_chart(report) -> go.Figure:
     fig = go.Figure()
     fig.add_trace(
         go.Scatter(
-            x=bench.index, y=bench.to_numpy(), name="Buy & hold", mode="lines",
+            x=bench.index, y=bench.to_numpy(), name=benchmark_label, mode="lines",
             line=dict(color=REFERENCE, width=2, dash="dash"),
-            hovertemplate="Buy & hold  %{y:.1f}<extra></extra>",
+            hovertemplate=benchmark_label + "  %{y:.1f}<extra></extra>",
         )
     )
     fig.add_trace(
@@ -90,7 +90,7 @@ def equity_chart(report) -> go.Figure:
     )
 
     # Direct-label the two endpoints; the axis and tooltip carry everything else.
-    for series, color, label in ((strat, SUBJECT, report.strategy.name), (bench, REFERENCE, "Buy & hold")):
+    for series, color, label in ((strat, SUBJECT, report.strategy.name), (bench, REFERENCE, benchmark_label)):
         fig.add_annotation(
             x=series.index[-1], y=float(series.iloc[-1]),
             text=f"  {label}: {series.iloc[-1]:.0f}", showarrow=False,
@@ -203,14 +203,14 @@ def walkforward_chart(report) -> go.Figure:
     return fig
 
 
-def score_chart(verdict: Dict[str, object]) -> go.Figure:
+def score_chart(verdict: Dict[str, object], significance_label: str = "Beats shuffled markets") -> go.Figure:
     """The five components behind the Reality Score."""
     components = verdict.get("components") or {}
     if not components:
         return empty_figure(height=260)
 
     pretty = {
-        "significance": "Beats shuffled markets",
+        "significance": significance_label,
         "selection": "Survives selection bias",
         "walk_forward": "Holds up walking forward",
         "overfitting": "Not overfit (PBO)",
@@ -270,6 +270,113 @@ def arena_chart(table: pd.DataFrame) -> go.Figure:
     return fig
 
 
+def cross_permutation_chart(report) -> go.Figure:
+    """Sharpe against books of identical shape holding randomly chosen names."""
+    perm = report.permutation
+    if perm is None or perm.null.size == 0:
+        return empty_figure("Name-shuffle test was skipped.", height=320)
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Histogram(
+            x=perm.null, name="Same book, random names", nbinsx=40,
+            marker=dict(color="rgba(217,89,38,0.55)", line=dict(color=REFERENCE, width=1)),
+            hovertemplate="Sharpe %{x:.2f}<br>%{y} shuffles<extra></extra>",
+        )
+    )
+    top = np.histogram(perm.null, bins=40)[0].max() if perm.null.size else 1
+    fig.add_trace(
+        go.Scatter(
+            x=[perm.observed, perm.observed], y=[0, top * 1.08], mode="lines",
+            name="Your book", line=dict(color=SUBJECT, width=2),
+            hovertemplate="Your Sharpe %{x:.2f}<extra></extra>",
+        )
+    )
+    fig.add_annotation(
+        x=perm.observed, y=top * 1.08, text=f"  your Sharpe {perm.observed:.2f}",
+        showarrow=False, xanchor="left", font=dict(color=SUBJECT, size=11),
+    )
+    beats = (perm.null >= perm.observed).mean() * 100.0
+    fig.update_layout(
+        **_base_layout(
+            f"Name-shuffle test — {beats:.0f}% of books with the same shape but random names "
+            f"did this well or better (p = {perm.p_value:.3f})",
+            height=320,
+        )
+    )
+    fig.update_layout(hovermode="closest", bargap=0.02)
+    fig.update_xaxes(title=dict(text="Annualised Sharpe ratio", font=dict(color=INK_MUTED, size=11)))
+    fig.update_yaxes(
+        title=dict(text="Shuffled books", font=dict(color=INK_MUTED, size=11)),
+        range=[0, top * 1.28],
+    )
+    return fig
+
+
+def attribution_chart(attribution: Dict[str, object]) -> go.Figure:
+    """Factor betas. One measure across categories, so one colour."""
+    if not attribution or not attribution.get("available"):
+        return empty_figure((attribution or {}).get("note", _EMPTY_NOTE), height=280)
+
+    betas = attribution.get("betas") or {}
+    if not betas:
+        return empty_figure("No factor exposures to show.", height=280)
+
+    names = list(betas)
+    values = [betas[n] for n in names]
+    fig = go.Figure(
+        go.Bar(
+            x=values, y=[n.replace("_", " ") for n in names], orientation="h",
+            marker=dict(color=SUBJECT, line=dict(color=SURFACE, width=2)),
+            text=[f"{v:+.2f}" for v in values], textposition="outside",
+            textfont=dict(color=INK_SECONDARY, size=11),
+            hovertemplate="%{y} beta %{x:.2f}<extra></extra>",
+        )
+    )
+    alpha = attribution.get("alpha_annual", 0.0)
+    t_stat = attribution.get("alpha_t_stat", 0.0)
+    fig.update_layout(
+        **_base_layout(
+            f"Style exposure — alpha {alpha:+.1%}/yr (t = {t_stat:.1f}), "
+            f"R² {attribution.get('r_squared', 0):.0%}",
+            height=280,
+            showlegend=False,
+        )
+    )
+    fig.update_layout(margin=dict(l=120, r=88, t=48, b=32), hovermode="closest")
+    # Outside labels need room or the widest beta reads as "+0".
+    span = max(abs(min(values)), abs(max(values)), 0.1)
+    fig.update_xaxes(range=[min(0, min(values)) - 0.25 * span, max(0, max(values)) + 0.35 * span])
+    fig.add_vline(x=0, line=dict(color=AXIS, width=1))
+    return fig
+
+
+def weights_chart(report) -> go.Figure:
+    """Gross and net exposure over time — is the book actually neutral?"""
+    held = report.backtest.held
+    gross = held.abs().sum(axis=1)
+    net = held.sum(axis=1)
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=gross.index, y=gross.to_numpy(), name="Gross", mode="lines",
+            line=dict(color=REFERENCE, width=2, dash="dash"),
+            hovertemplate="Gross %{y:.2f}x<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=net.index, y=net.to_numpy(), name="Net", mode="lines",
+            line=dict(color=SUBJECT, width=2),
+            hovertemplate="Net %{y:.2f}x<extra></extra>",
+        )
+    )
+    fig.update_layout(**_base_layout("Book exposure", height=240))
+    fig.add_hline(y=0, line=dict(color=AXIS, width=1))
+    return fig
+
+
 def exposure_chart(report) -> go.Figure:
     """What the strategy was actually holding, over time."""
     pos = report.backtest.position

algotrader/cli.py

@@ -138,12 +138,92 @@ def _cmd_arena(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_portfolio(args: argparse.Namespace) -> int:
+    from .portfolio_lab import DEFAULT_UNIVERSE, PortfolioLabConfig, run_portfolio_lab
+
+    symbols = [s.strip() for s in args.symbols.split(",") if s.strip()] if args.symbols else DEFAULT_UNIVERSE
+    cfg = PortfolioLabConfig(
+        symbols=symbols,
+        start=args.start,
+        end=args.end,
+        interval=args.interval,
+        source=args.source,
+        strategy=args.strategy,
+        params=_parse_params(args.param),
+        commission_bps=args.commission_bps,
+        slippage_bps=args.slippage_bps,
+        allow_short=not args.no_short,
+        rebalance=args.rebalance,
+        n_permutations=args.permutations,
+        wf_folds=args.folds,
+    )
+    progress = None if args.quiet else (lambda f, m: print(f"  [{f:5.0%}] {m}", file=sys.stderr))
+    report = run_portfolio_lab(cfg, progress=progress)
+
+    if args.json:
+        print(json.dumps({
+            "symbols": report.panel.symbols,
+            "strategy": report.strategy.key,
+            "params": report.params,
+            "metrics": report.backtest.metrics,
+            "p_value": report.permutation.p_value if report.permutation else None,
+            "deflated_sharpe": report.dsr.get("dsr"),
+            "pbo": report.pbo.get("pbo"),
+            "walkforward_efficiency": report.walkforward.get("efficiency"),
+            "attribution": report.attribution,
+            "survivorship": report.survivorship.__dict__,
+            "verdict": dict(report.verdict),
+        }, indent=2, default=str))
+        return 0
+
+    v, m, b = report.verdict, report.backtest.metrics, report.backtest.benchmark_metrics
+    bar = "=" * 72
+    print(f"\n{bar}")
+    print(f"  {report.strategy.name} on {len(report.panel.symbols)} symbols   [{report.panel.interval}]")
+    print(f"  {report.panel.index[0].date()} to {report.panel.index[-1].date()}  ·  "
+          f"{len(report.panel):,} bars  ·  rebalance {report.config.rebalance}")
+    print(bar)
+    print(f"  REALITY SCORE   {v['score']:.1f} / 100      GRADE  {v['grade']}")
+    print(f"  {v['headline']}")
+    print(bar)
+    print(f"  Total return      {m['total_return']:>9.1%}    equal weight {b['total_return']:>8.1%}")
+    print(f"  CAGR              {m['cagr']:>9.1%}    equal weight {b['cagr']:>8.1%}")
+    print(f"  Sharpe            {m['sharpe']:>9.2f}    equal weight {b['sharpe']:>8.2f}")
+    print(f"  Max drawdown      {m['max_drawdown']:>9.1%}")
+    print(f"  Gross / net exp.  {m.get('gross_exposure', 0):>9.2f} / {m.get('net_exposure', 0):.2f}")
+    print(f"  Avg positions     {m.get('avg_positions', 0):>9.1f}    turnover {m.get('turnover_ann', 0):.1f}x/yr")
+    print(bar)
+    if report.permutation:
+        print(f"  Name-shuffle p    {report.permutation.p_value:>9.3f}    "
+              f"({report.permutation.n_permutations} shuffles of which names got which weights)")
+    print(f"  Deflated Sharpe   {report.dsr.get('dsr', 0):>9.2f}    (after {report.trials.get('n', 1)} variants)")
+    pbo = report.pbo.get("pbo")
+    print(f"  Overfit prob.     {pbo:>9.2f}" if pbo == pbo else "  Overfit prob.           n/a")
+    print(f"  Walk-forward eff. {report.walkforward.get('efficiency', 0):>9.2f}")
+    if report.attribution.get("available"):
+        print(f"  Style alpha       {report.attribution['alpha_annual']:>9.1%}    "
+              f"t = {report.attribution['alpha_t_stat']:.2f}, R² = {report.attribution['r_squared']:.2f}")
+    print(f"  Survivorship      {report.survivorship.survival_rate:>9.0%}    "
+          f"({report.survivorship.n_delisted} of {report.survivorship.n_symbols} stopped trading)")
+    print(bar)
+    for flag in v["flags"]:
+        print(f"  ! {flag}")
+    if v["flags"]:
+        print(bar)
+    print(f"  {v['verdict']}\n")
+    return 0
+
+
 def _cmd_strategies(args: argparse.Namespace) -> int:
-    for key, strategy in REGISTRY.items():
-        params = ", ".join(f"{p.name}={p.default:g}" for p in strategy.params) or "no parameters"
-        print(f"  {key:<22} {strategy.name:<26} [{strategy.family}]")
-        print(f"  {'':<22} {strategy.description}")
-        print(f"  {'':<22} defaults: {params}\n")
+    from .cross_sectional import XS_REGISTRY
+
+    for title, registry in (("Single asset", REGISTRY), ("Cross-sectional", XS_REGISTRY)):
+        print(f"\n  {title}\n  {'-' * len(title)}")
+        for key, strategy in registry.items():
+            params = ", ".join(f"{p.name}={p.default:g}" for p in strategy.params) or "no parameters"
+            print(f"  {key:<22} {strategy.name:<28} [{strategy.family}]")
+            print(f"  {'':<22} {strategy.description}")
+            print(f"  {'':<22} defaults: {params}\n")
     return 0
 
 
@@ -174,6 +254,25 @@ def main(argv: List[str] | None = None) -> int:
     arena.add_argument("--quiet", "-q", action="store_true")
     arena.set_defaults(func=_cmd_arena)
 
+    from .cross_sectional import XS_REGISTRY
+
+    portfolio = sub.add_parser(
+        "portfolio", help="Reality check for a cross-sectional (multi-asset) strategy."
+    )
+    _add_common(portfolio)
+    portfolio.add_argument(
+        "--symbols", default=None,
+        help="Comma-separated universe, e.g. SPY,QQQ,AAPL. Defaults to a 12-name universe.",
+    )
+    portfolio.add_argument("--strategy", default="xs_momentum", choices=sorted(XS_REGISTRY))
+    portfolio.add_argument("--param", action="append", metavar="NAME=VALUE")
+    portfolio.add_argument("--rebalance", default="M", help="D, W, M, Q, or a number of bars.")
+    portfolio.add_argument("--permutations", type=int, default=150)
+    portfolio.add_argument("--folds", type=int, default=4)
+    portfolio.add_argument("--json", action="store_true")
+    portfolio.add_argument("--quiet", "-q", action="store_true")
+    portfolio.set_defaults(func=_cmd_portfolio)
+
     listing = sub.add_parser("strategies", help="List the strategy zoo.")
     listing.set_defaults(func=_cmd_strategies)
 

algotrader/cross_sectional.py

@@ -0,0 +1,290 @@
+"""Cross-sectional strategies.
+
+Where a single-asset rule asks "should I be long this thing?", a
+cross-sectional rule asks "which of these things should I be long, and which
+short?". That difference matters for validation: a long-short book that ranks
+names is exposed to entirely different failure modes than a timing rule, and it
+needs its own null (see :mod:`algotrader.validation.cross_permutation`).
+
+Each strategy is a pure function ``(panel, **params) -> T x N weights``, causal
+by construction, with gross exposure of at most 1.
+"""
+
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass
+from typing import Callable, Dict, Iterable, List
+
+import numpy as np
+import pandas as pd
+
+from .panel import Panel
+from .strategies import ParamSpec
+
+__all__ = [
+    "CrossSectionalStrategy",
+    "XS_REGISTRY",
+    "get_xs_strategy",
+    "list_xs_strategies",
+    "scores_to_weights",
+]
+
+MIN_NAMES = 4  # below this, "cross-section" is not a meaningful word
+
+
+def scores_to_weights(
+    scores: pd.DataFrame,
+    long_frac: float = 0.3,
+    short_frac: float = 0.3,
+    long_only: bool = False,
+    min_names: int = MIN_NAMES,
+) -> pd.DataFrame:
+    """Turn a score matrix into a dollar-neutral (or long-only) weight matrix.
+
+    Ranks within each date, takes the top and bottom fractions, and equal-weights
+    each leg. Gross exposure is 1: half per leg when short-selling, all of it in
+    the long leg otherwise.
+    """
+    valid = scores.notna()
+    counts = valid.sum(axis=1)
+    ranks = scores.rank(axis=1, pct=True, na_option="keep")
+
+    longs = (ranks > 1.0 - long_frac) & valid
+    n_long = longs.sum(axis=1).replace(0, np.nan)
+
+    if long_only:
+        weights = longs.astype(float).div(n_long, axis=0)
+    else:
+        shorts = (ranks <= short_frac) & valid
+        n_short = shorts.sum(axis=1).replace(0, np.nan)
+        weights = (
+            longs.astype(float).div(n_long, axis=0) * 0.5
+            - shorts.astype(float).div(n_short, axis=0) * 0.5
+        )
+
+    # A cross-section of two names is not a cross-section.
+    weights = weights.where(counts >= min_names, 0.0)
+    return weights.fillna(0.0)
+
+
+def _rebalance_hold(weights: pd.DataFrame, every: int) -> pd.DataFrame:
+    """Refresh the target only every ``every`` bars, holding it in between."""
+    if every <= 1:
+        return weights
+    out = weights.copy()
+    keep = np.zeros(len(out), dtype=bool)
+    keep[::every] = True
+    out.iloc[~keep] = np.nan
+    return out.ffill().fillna(0.0)
+
+
+# --------------------------------------------------------------------------
+# Strategy implementations
+# --------------------------------------------------------------------------
+
+def _xs_momentum(
+    panel: Panel, lookback: int = 250, skip: int = 20, rebalance: int = 21, long_frac: float = 0.3
+) -> pd.DataFrame:
+    """Classic 12-1 momentum: rank on past return, skipping the most recent month.
+
+    The skip is not decoration -- including the last month mixes in short-term
+    reversal, which points the other way and muddies the signal.
+    """
+    close = panel.close
+    scores = close.shift(skip) / close.shift(lookback) - 1.0
+    return _rebalance_hold(scores_to_weights(scores, long_frac, long_frac), rebalance)
+
+
+def _xs_reversal(
+    panel: Panel, lookback: int = 5, rebalance: int = 5, long_frac: float = 0.3
+) -> pd.DataFrame:
+    """Short-term reversal: buy the recent losers, sell the recent winners."""
+    scores = -(panel.close.pct_change(lookback))
+    return _rebalance_hold(scores_to_weights(scores, long_frac, long_frac), rebalance)
+
+
+def _low_volatility(
+    panel: Panel, window: int = 60, rebalance: int = 21, long_frac: float = 0.3
+) -> pd.DataFrame:
+    """The low-volatility anomaly: long the calm names, short the wild ones."""
+    scores = -(panel.close.pct_change().rolling(window, min_periods=window).std())
+    return _rebalance_hold(scores_to_weights(scores, long_frac, long_frac), rebalance)
+
+
+def _xs_value_proxy(
+    panel: Panel, window: int = 250, rebalance: int = 21, long_frac: float = 0.3
+) -> pd.DataFrame:
+    """Distance below the long-run average price, as a crude cheapness proxy.
+
+    This is not book-to-market -- there are no fundamentals in the panel -- so
+    treat it as mean reversion over a long horizon rather than value investing.
+    """
+    close = panel.close
+    scores = -(close / close.rolling(window, min_periods=window).mean() - 1.0)
+    return _rebalance_hold(scores_to_weights(scores, long_frac, long_frac), rebalance)
+
+
+def _equal_weight(panel: Panel, rebalance: int = 21) -> pd.DataFrame:
+    """Own everything tradable, equally. The bar a stock picker has to clear."""
+    listed = panel.close.notna()
+    counts = listed.sum(axis=1).replace(0, np.nan)
+    return _rebalance_hold(listed.astype(float).div(counts, axis=0).fillna(0.0), rebalance)
+
+
+def _xs_random(panel: Panel, rebalance: int = 21, seed: int = 7) -> pd.DataFrame:
+    """Random long-short book. The control group for cross-sectional claims."""
+    rng = np.random.default_rng(int(seed))
+    scores = pd.DataFrame(
+        rng.standard_normal(panel.close.shape), index=panel.index, columns=panel.symbols
+    ).where(panel.close.notna())
+    return _rebalance_hold(scores_to_weights(scores), rebalance)
+
+
+@dataclass(frozen=True)
+class CrossSectionalStrategy:
+    key: str
+    name: str
+    family: str
+    description: str
+    fn: Callable[..., pd.DataFrame]
+    params: tuple = ()
+
+    def defaults(self) -> Dict[str, float]:
+        return {p.name: p.cast(p.default) for p in self.params}
+
+    def clean(self, params: Dict[str, float] | None) -> Dict[str, float]:
+        merged = self.defaults()
+        for spec in self.params:
+            if params and spec.name in params and params[spec.name] is not None:
+                merged[spec.name] = spec.cast(params[spec.name])
+        return merged
+
+    def generate(self, panel: Panel, params: Dict[str, float] | None = None) -> pd.DataFrame:
+        weights = self.fn(panel, **self.clean(params))
+        return (
+            weights.reindex(index=panel.index, columns=panel.symbols)
+            .astype(float)
+            .fillna(0.0)
+            .clip(-1.0, 1.0)
+        )
+
+    def grid(self, limit: int | None = None) -> List[Dict[str, float]]:
+        if not self.params:
+            return [{}]
+        names = [p.name for p in self.params]
+        combos = [dict(zip(names, v)) for v in itertools.product(*[p.grid for p in self.params])]
+        combos = [c for c in combos if not ("skip" in c and "lookback" in c and c["skip"] >= c["lookback"])]
+        if limit is not None and len(combos) > limit:
+            step = len(combos) / limit
+            combos = [combos[int(i * step)] for i in range(limit)]
+        return combos
+
+
+XS_REGISTRY: Dict[str, CrossSectionalStrategy] = {}
+
+
+def _register(strategy: CrossSectionalStrategy) -> CrossSectionalStrategy:
+    XS_REGISTRY[strategy.key] = strategy
+    return strategy
+
+
+_register(
+    CrossSectionalStrategy(
+        key="equal_weight",
+        name="Equal Weight",
+        family="benchmark",
+        description="Own every name equally. The bar a stock picker has to clear.",
+        fn=_equal_weight,
+        params=(ParamSpec("rebalance", "Rebalance (bars)", 21, (5, 21, 63), "int", 1, 252, 1),),
+    )
+)
+
+_register(
+    CrossSectionalStrategy(
+        key="xs_momentum",
+        name="Cross-Sectional Momentum",
+        family="momentum",
+        description="Long the past winners, short the past losers, skipping the most recent month.",
+        fn=_xs_momentum,
+        params=(
+            ParamSpec("lookback", "Lookback", 250, (60, 120, 250), "int", 20, 750, 1),
+            ParamSpec("skip", "Skip recent", 20, (0, 5, 20), "int", 0, 60, 1),
+            ParamSpec("rebalance", "Rebalance (bars)", 21, (5, 21, 63), "int", 1, 252, 1),
+            ParamSpec("long_frac", "Leg size", 0.3, (0.1, 0.2, 0.3), "float", 0.05, 0.5, 0.05),
+        ),
+    )
+)
+
+_register(
+    CrossSectionalStrategy(
+        key="xs_reversal",
+        name="Short-Term Reversal",
+        family="mean-reversion",
+        description="Buy this week's losers and sell its winners.",
+        fn=_xs_reversal,
+        params=(
+            ParamSpec("lookback", "Lookback", 5, (1, 3, 5, 10, 21), "int", 1, 60, 1),
+            ParamSpec("rebalance", "Rebalance (bars)", 5, (1, 5, 21), "int", 1, 252, 1),
+            ParamSpec("long_frac", "Leg size", 0.3, (0.1, 0.2, 0.3), "float", 0.05, 0.5, 0.05),
+        ),
+    )
+)
+
+_register(
+    CrossSectionalStrategy(
+        key="low_volatility",
+        name="Low Volatility",
+        family="risk",
+        description="Long the calm names, short the volatile ones.",
+        fn=_low_volatility,
+        params=(
+            ParamSpec("window", "Vol window", 60, (20, 60, 120), "int", 5, 252, 1),
+            ParamSpec("rebalance", "Rebalance (bars)", 21, (5, 21, 63), "int", 1, 252, 1),
+            ParamSpec("long_frac", "Leg size", 0.3, (0.1, 0.2, 0.3), "float", 0.05, 0.5, 0.05),
+        ),
+    )
+)
+
+_register(
+    CrossSectionalStrategy(
+        key="xs_value_proxy",
+        name="Long-Horizon Reversion",
+        family="value-ish",
+        description="Long names trading below their long-run average, short those above.",
+        fn=_xs_value_proxy,
+        params=(
+            ParamSpec("window", "Window", 250, (120, 250, 500), "int", 30, 1000, 1),
+            ParamSpec("rebalance", "Rebalance (bars)", 21, (5, 21, 63), "int", 1, 252, 1),
+            ParamSpec("long_frac", "Leg size", 0.3, (0.1, 0.2, 0.3), "float", 0.05, 0.5, 0.05),
+        ),
+    )
+)
+
+_register(
+    CrossSectionalStrategy(
+        key="xs_random",
+        name="Random Book (control)",
+        family="control",
+        description="Random long-short positions. Anything that cannot beat this is noise.",
+        fn=_xs_random,
+        params=(
+            ParamSpec("rebalance", "Rebalance (bars)", 21, (5, 21, 63), "int", 1, 252, 1),
+            ParamSpec("seed", "Seed", 7, (1, 7, 42, 123), "int", 0, 9999, 1),
+        ),
+    )
+)
+
+
+def get_xs_strategy(key: str) -> CrossSectionalStrategy:
+    try:
+        return XS_REGISTRY[key]
+    except KeyError:
+        raise KeyError(
+            f"Unknown cross-sectional strategy '{key}'. Available: {', '.join(sorted(XS_REGISTRY))}"
+        ) from None
+
+
+def list_xs_strategies(exclude: Iterable[str] = ()) -> List[CrossSectionalStrategy]:
+    skip = set(exclude)
+    return [s for k, s in XS_REGISTRY.items() if k not in skip]

algotrader/engine.py

@@ -62,8 +62,15 @@ def run_backtest(
 
     gross = position * asset_ret
 
-    traded = position.diff()
-    traded.iloc[0] = position.iloc[0]
+    # Turnover is measured against the *drifted* weight, not the previous
+    # target. Holding a full-notional long needs no rebalancing (the position
+    # and the portfolio grow together), but a short does: lose 10% on a 100%
+    # short and the weight drifts to -82%, so staying at -100% costs a trade.
+    # See portfolio.py for the same formula in matrix form.
+    growth = (1.0 + gross).replace(0.0, np.nan)
+    drifted = (position * (1.0 + asset_ret)) / growth
+    previous = drifted.shift(1).fillna(0.0)
+    traded = position - previous
     trade_cost = traded.abs() * (costs.one_way_bps / 1e4)
 
     borrow_cost = position.clip(upper=0.0).abs() * (costs.short_borrow_bps / 1e4) / ppy

algotrader/panel.py

@@ -0,0 +1,283 @@
+"""Multi-asset price panels.
+
+A :class:`Panel` is a set of aligned ``T x N`` frames -- one per OHLCV field,
+one column per symbol. That is the shape cross-sectional work actually needs,
+and it is what the portfolio engine consumes.
+
+The important design choice here is that **missing data stays missing**. It is
+tempting to forward-fill a symbol through the days it did not trade, but that
+invents liquidity that never existed and quietly lets a strategy hold a
+delisted stock forever. Instead the panel tracks exactly when each symbol was
+tradable, which is also what makes survivorship measurable rather than assumed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .data import load_ohlcv
+from .types import OHLCV_COLUMNS
+
+__all__ = ["Panel", "load_panel", "SurvivorshipReport"]
+
+
+@dataclass(frozen=True)
+class SurvivorshipReport:
+    """How much of this universe is made of winners we already know survived."""
+
+    n_symbols: int
+    n_alive_at_end: int
+    n_delisted: int
+    delisted_symbols: List[str]
+    late_starters: List[str]
+    survival_rate: float
+    biased: bool
+    note: str
+
+    def as_flag(self) -> Optional[str]:
+        return self.note if self.biased else None
+
+
+@dataclass(frozen=True)
+class Panel:
+    """Aligned multi-asset OHLCV."""
+
+    fields: Mapping[str, pd.DataFrame]
+    sources: Mapping[str, str] = field(default_factory=dict)
+    interval: str = "1d"
+    note: str = ""
+
+    def __post_init__(self) -> None:
+        missing = [c for c in OHLCV_COLUMNS if c not in self.fields]
+        if missing:
+            raise ValueError(f"Panel is missing field(s): {', '.join(missing)}")
+        reference = self.fields["close"]
+        for name, frame in self.fields.items():
+            if not frame.index.equals(reference.index) or list(frame.columns) != list(reference.columns):
+                raise ValueError(f"Panel field '{name}' is not aligned with 'close'")
+
+    # -- accessors ---------------------------------------------------------
+    @property
+    def close(self) -> pd.DataFrame:
+        return self.fields["close"]
+
+    @property
+    def open(self) -> pd.DataFrame:
+        return self.fields["open"]
+
+    @property
+    def high(self) -> pd.DataFrame:
+        return self.fields["high"]
+
+    @property
+    def low(self) -> pd.DataFrame:
+        return self.fields["low"]
+
+    @property
+    def volume(self) -> pd.DataFrame:
+        return self.fields["volume"]
+
+    @property
+    def symbols(self) -> List[str]:
+        return list(self.close.columns)
+
+    @property
+    def index(self) -> pd.DatetimeIndex:
+        return self.close.index
+
+    @property
+    def is_real(self) -> bool:
+        return all(s in ("yfinance", "bundled") for s in self.sources.values())
+
+    def __len__(self) -> int:
+        return len(self.close)
+
+    @property
+    def shape(self) -> tuple:
+        return self.close.shape
+
+    # -- derived -----------------------------------------------------------
+    def returns(self) -> pd.DataFrame:
+        """Per-asset close-to-close returns, NaN where the asset was untradable."""
+        rets = self.close.pct_change()
+        return rets.where(self.tradable())
+
+    def tradable(self) -> pd.DataFrame:
+        """True where the asset had a price on this bar *and* the one before.
+
+        A position can only be held over a bar whose return is defined, so this
+        is the mask the engine uses to zero out impossible weights.
+        """
+        listed = self.close.notna()
+        return listed & listed.shift(1, fill_value=False)
+
+    def dollar_volume(self) -> pd.DataFrame:
+        return (self.close * self.volume).where(self.close.notna())
+
+    def first_valid(self) -> pd.Series:
+        return self.close.apply(lambda col: col.first_valid_index())
+
+    def last_valid(self) -> pd.Series:
+        return self.close.apply(lambda col: col.last_valid_index())
+
+    # -- survivorship ------------------------------------------------------
+    def survivorship(self, tolerance_bars: int = 5) -> SurvivorshipReport:
+        """Measure how many names survived to the end of the sample.
+
+        A universe picked today and backfilled contains only survivors, and
+        every backtest run on it is flattered by the companies that failed and
+        were quietly excluded. We cannot fix that here, but we can refuse to
+        hide it: if every single name is still trading at the end of a long
+        sample, that is itself the evidence.
+        """
+        if not len(self):
+            return SurvivorshipReport(0, 0, 0, [], [], 1.0, False, "Empty panel.")
+
+        last = self.last_valid()
+        first = self.first_valid()
+        end = self.index[-1]
+        start = self.index[0]
+        cutoff = self.index[max(0, len(self) - 1 - tolerance_bars)]
+        entry_cutoff = self.index[min(len(self) - 1, tolerance_bars)]
+
+        delisted = sorted(str(s) for s in last.index[last < cutoff])
+        late = sorted(str(s) for s in first.index[first > entry_cutoff])
+        n = len(self.symbols)
+        alive = n - len(delisted)
+        rate = alive / n if n else 1.0
+
+        years = len(self) / 252.0
+        biased = rate >= 1.0 and years >= 3 and n >= 5
+        if biased:
+            note = (
+                f"All {n} symbols were still trading at the end of a {years:.1f}-year sample. "
+                "A universe with no failures in it was almost certainly chosen after the fact, "
+                "which means these results exclude every name that went to zero. Treat the "
+                "returns below as an upper bound."
+            )
+        elif n == 0:
+            note = "Empty panel."
+        else:
+            note = (
+                f"{len(delisted)} of {n} symbols stopped trading before the end of the sample "
+                f"({rate:.0%} survived), so the universe is not made purely of winners."
+            )
+
+        return SurvivorshipReport(
+            n_symbols=n,
+            n_alive_at_end=alive,
+            n_delisted=len(delisted),
+            delisted_symbols=delisted[:25],
+            late_starters=late[:25],
+            survival_rate=float(rate),
+            biased=bool(biased),
+            note=note,
+        )
+
+    # -- construction ------------------------------------------------------
+    @classmethod
+    def from_frames(
+        cls,
+        frames: Mapping[str, pd.DataFrame],
+        sources: Optional[Mapping[str, str]] = None,
+        interval: str = "1d",
+        note: str = "",
+        min_bars: int = 2,
+    ) -> "Panel":
+        """Build a panel from ``{symbol: ohlcv_frame}``, aligning on the union index."""
+        usable = {
+            str(symbol): frame
+            for symbol, frame in frames.items()
+            if frame is not None and len(frame) >= min_bars
+        }
+        if not usable:
+            raise ValueError("No symbol had enough data to build a panel")
+
+        index = pd.DatetimeIndex([])
+        for frame in usable.values():
+            index = index.union(pd.DatetimeIndex(frame.index))
+        index = index.sort_values()
+
+        fields: Dict[str, pd.DataFrame] = {}
+        for column in OHLCV_COLUMNS:
+            fields[column] = pd.DataFrame(
+                {
+                    symbol: pd.to_numeric(frame[column], errors="coerce").reindex(index)
+                    for symbol, frame in usable.items()
+                },
+                index=index,
+            )
+
+        return cls(
+            fields=fields,
+            sources=dict(sources or {s: "unknown" for s in usable}),
+            interval=interval,
+            note=note,
+        )
+
+    def select(self, symbols: Sequence[str]) -> "Panel":
+        keep = [s for s in symbols if s in self.close.columns]
+        if not keep:
+            raise ValueError("None of the requested symbols are in this panel")
+        return Panel(
+            fields={name: frame.loc[:, keep] for name, frame in self.fields.items()},
+            sources={s: self.sources.get(s, "unknown") for s in keep},
+            interval=self.interval,
+            note=self.note,
+        )
+
+    def slice(self, start=None, end=None) -> "Panel":
+        return Panel(
+            fields={name: frame.loc[start:end] for name, frame in self.fields.items()},
+            sources=dict(self.sources),
+            interval=self.interval,
+            note=self.note,
+        )
+
+
+def load_panel(
+    symbols: Iterable[str],
+    start: str = "2015-01-01",
+    end: Optional[str] = None,
+    interval: str = "1d",
+    source: str = "auto",
+    min_bars: int = 120,
+) -> Panel:
+    """Load a panel for ``symbols``, skipping any that cannot supply enough history."""
+    symbols = [str(s).strip().upper() for s in symbols if str(s).strip()]
+    if not symbols:
+        raise ValueError("No symbols requested")
+
+    frames: Dict[str, pd.DataFrame] = {}
+    sources: Dict[str, str] = {}
+    skipped: List[str] = []
+
+    for symbol in dict.fromkeys(symbols):  # de-duplicate, keep order
+        market = load_ohlcv(symbol, start, end, interval, source)
+        if len(market.df) < min_bars:
+            skipped.append(symbol)
+            continue
+        frames[symbol] = market.df
+        sources[symbol] = market.source
+
+    if not frames:
+        raise ValueError(
+            f"None of {len(symbols)} symbols returned at least {min_bars} bars."
+        )
+
+    simulated = sorted(s for s, src in sources.items() if src == "synthetic")
+    note = ""
+    if simulated:
+        note = (
+            f"{len(simulated)} of {len(frames)} symbols fell back to the market simulator "
+            f"({', '.join(simulated[:6])}{'...' if len(simulated) > 6 else ''}). "
+            "The statistics are still valid; they are measured on a simulated market."
+        )
+    if skipped:
+        note = (note + " " if note else "") + f"Skipped for insufficient history: {', '.join(skipped[:6])}."
+
+    return Panel.from_frames(frames, sources, interval=interval, note=note.strip())

algotrader/portfolio.py

@@ -0,0 +1,257 @@
+"""Matrix portfolio engine.
+
+The single-asset engine treats turnover as ``|target[t] - target[t-1]|``. That
+is wrong the moment weights are fractional, because a position you did not
+touch still *drifts*: hold 50% of your book in a name that doubles and you are
+now at 67% without trading. Charging costs against the previous target instead
+of the previous *actual* weight understates the cost of doing nothing and
+overstates the cost of rebalancing.
+
+This module models the drift explicitly and closes the gap:
+
+    w_start[t] = target[t - lag]                     what we want to hold
+    r_p[t]     = sum(w_start[t] * R[t])              portfolio return that bar
+    w_end[t]   = w_start[t] * (1 + R[t]) / (1 + r_p[t])   drifted by the bar
+    turnover[t] = sum |w_start[t] - w_end[t - 1]|    what we actually traded
+
+Every step is a function of the current bar and the one before, so the whole
+thing stays vectorised -- no Python loop over time.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+from .metrics import compute_metrics, infer_periods_per_year
+from .panel import Panel
+from .types import BacktestResult, CostModel
+
+__all__ = ["run_portfolio_backtest", "PortfolioResult", "normalise_weights"]
+
+
+class PortfolioResult(BacktestResult):
+    """A :class:`BacktestResult` that also keeps the per-asset weight history."""
+
+    def __init__(self, *args, weights: pd.DataFrame, held: pd.DataFrame, panel: Panel, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.weights = weights  # requested, post-constraint
+        self.held = held  # actually held during each bar
+        self.panel = panel
+
+    def attribution(self) -> pd.Series:
+        """Total return contribution per symbol, largest first."""
+        contrib = (self.held * self.panel.returns().fillna(0.0)).sum(axis=0)
+        return contrib.sort_values(ascending=False)
+
+
+def normalise_weights(
+    weights: pd.DataFrame,
+    listed: pd.DataFrame,
+    gross_leverage: float = 1.0,
+    max_weight: Optional[float] = None,
+    allow_short: bool = True,
+) -> pd.DataFrame:
+    """Apply the constraints a real book has, in the order a real book applies them.
+
+    ``listed`` is "did this name have a price when the decision was made" --
+    deliberately not the stricter "is a return defined over this bar" mask. A
+    decision taken at Monday's close only needs Monday's price to exist; whether
+    the position can actually be carried is enforced after the lag shift.
+    """
+    w = weights.reindex(index=listed.index, columns=listed.columns).astype(float).fillna(0.0)
+
+    # You cannot ask for exposure to something that is not listed yet.
+    w = w.where(listed, 0.0)
+
+    if not allow_short:
+        w = w.clip(lower=0.0)
+    if max_weight is not None:
+        w = w.clip(-abs(max_weight), abs(max_weight))
+
+    # Scale down (never up) so gross exposure respects the leverage cap.
+    gross = w.abs().sum(axis=1)
+    scale = np.minimum(1.0, gross_leverage / gross.replace(0.0, np.nan))
+    return w.mul(scale.fillna(1.0), axis=0)
+
+
+def run_portfolio_backtest(
+    panel: Panel,
+    weights: pd.DataFrame,
+    costs: Optional[CostModel] = None,
+    lag: int = 1,
+    gross_leverage: float = 1.0,
+    max_weight: Optional[float] = None,
+    allow_short: bool = True,
+    initial_capital: float = 100_000.0,
+    periods_per_year: Optional[int] = None,
+    rf: float = 0.0,
+    benchmark: Optional[pd.Series] = None,
+    rebalance_on: Optional[pd.Series] = None,
+    meta: Optional[dict] = None,
+) -> PortfolioResult:
+    """Backtest a ``T x N`` weight matrix against a panel.
+
+    ``weights[t]`` is the exposure decided using information up to the close of
+    bar ``t``; it is held from bar ``t + lag``. The default benchmark is the
+    equal-weight universe, which is a far more honest comparison for a
+    cross-sectional strategy than any single ticker.
+    """
+    if len(panel) < 2:
+        raise ValueError("Cannot backtest a panel with fewer than two bars")
+    if lag < 1:
+        raise ValueError("lag must be >= 1; lag=0 would trade on unavailable information")
+
+    costs = costs or CostModel()
+    ppy = periods_per_year or infer_periods_per_year(panel.index)
+
+    asset_returns = panel.returns().fillna(0.0)
+    tradable = panel.tradable()
+    listed = panel.close.notna()
+
+    target = normalise_weights(weights, listed, gross_leverage, max_weight, allow_short)
+    held = target.shift(lag).fillna(0.0)
+    # Re-apply tradability after the shift: a name can delist between the
+    # decision and the fill, and we must not be holding it when it does.
+    held = held.where(tradable, 0.0)
+
+    if rebalance_on is not None:
+        held = _apply_rebalance_schedule(held, asset_returns, tradable, rebalance_on)
+
+    gross_return = (held * asset_returns).sum(axis=1)
+
+    # Weights after the bar's move, renormalised to the new portfolio value.
+    growth = (1.0 + gross_return).replace(0.0, np.nan)
+    drifted = (held * (1.0 + asset_returns)).div(growth, axis=0).fillna(0.0)
+    previous = drifted.shift(1).fillna(0.0)
+
+    traded = (held - previous).abs().sum(axis=1)
+    trade_cost = traded * (costs.one_way_bps / 1e4)
+    borrow_cost = held.clip(upper=0.0).abs().sum(axis=1) * (costs.short_borrow_bps / 1e4) / ppy
+    total_cost = trade_cost + borrow_cost
+
+    net = gross_return - total_cost
+    equity = initial_capital * (1.0 + net).cumprod()
+
+    if benchmark is None:
+        # Equal weight across whatever was tradable on each bar.
+        counts = tradable.sum(axis=1).replace(0, np.nan)
+        equal = tradable.astype(float).div(counts, axis=0).fillna(0.0)
+        benchmark = (equal.shift(lag).fillna(0.0) * asset_returns).sum(axis=1)
+    benchmark = benchmark.reindex(panel.index).fillna(0.0)
+    benchmark_equity = initial_capital * (1.0 + benchmark).cumprod()
+
+    exposure = held.abs().sum(axis=1)
+    metrics = compute_metrics(net, equity, exposure, ppy, rf)
+    metrics.update(_portfolio_metrics(held, traded, metrics.get("years", 1.0)))
+
+    survivorship = panel.survivorship()
+
+    result = PortfolioResult(
+        equity=equity,
+        returns=net,
+        gross_returns=gross_return,
+        position=exposure,
+        target=target.abs().sum(axis=1),
+        costs=total_cost,
+        benchmark_equity=benchmark_equity,
+        metrics=metrics,
+        benchmark_metrics=compute_metrics(benchmark, benchmark_equity, None, ppy, rf),
+        meta={
+            "lag": lag,
+            "gross_leverage": gross_leverage,
+            "max_weight": max_weight,
+            "allow_short": allow_short,
+            "initial_capital": initial_capital,
+            "periods_per_year": ppy,
+            "n_symbols": len(panel.symbols),
+            "survivorship": survivorship,
+            **(meta or {}),
+        },
+        weights=target,
+        held=held,
+        panel=panel,
+    )
+    return result
+
+
+def _apply_rebalance_schedule(
+    held: pd.DataFrame,
+    asset_returns: pd.DataFrame,
+    tradable: pd.DataFrame,
+    rebalance_on: pd.Series,
+) -> pd.DataFrame:
+    """Trade only on rebalance bars; let the book drift in between.
+
+    Without this, a monthly strategy whose target is constant between
+    rebalances gets charged turnover every single bar for holding still --
+    the model would be paying to *prevent* drift that a real book simply lets
+    happen. This is the one genuinely recursive step in the engine: today's
+    holding depends on yesterday's drifted holding.
+    """
+    schedule = rebalance_on.reindex(held.index).fillna(False).to_numpy(dtype=bool)
+    target = held.to_numpy(dtype=float)
+    returns = asset_returns.to_numpy(dtype=float)
+    can_hold = tradable.to_numpy(dtype=bool)
+
+    n_bars, n_assets = target.shape
+    out = np.zeros((n_bars, n_assets), dtype=float)
+    carried = np.zeros(n_assets, dtype=float)
+
+    for t in range(n_bars):
+        current = target[t] if schedule[t] else carried
+        current = np.where(can_hold[t], current, 0.0)
+        out[t] = current
+        # Drift into the next bar, renormalised to the new portfolio value.
+        portfolio_return = float(current @ returns[t])
+        growth = 1.0 + portfolio_return
+        carried = current * (1.0 + returns[t]) / growth if abs(growth) > 1e-12 else current
+
+    return pd.DataFrame(out, index=held.index, columns=held.columns)
+
+
+def rebalance_schedule(index: pd.DatetimeIndex, frequency: str = "M") -> pd.Series:
+    """Boolean per-bar mask marking rebalance dates.
+
+    ``frequency`` is ``D`` (every bar), ``W``, ``M``, ``Q``, or an integer
+    number of bars as a string.
+    """
+    frequency = str(frequency).upper().strip()
+    if frequency in ("D", "1", "B", ""):
+        return pd.Series(True, index=index)
+    if frequency.isdigit():
+        step = max(1, int(frequency))
+        mask = np.zeros(len(index), dtype=bool)
+        mask[::step] = True
+        return pd.Series(mask, index=index)
+
+    periods = {"W": index.to_period("W"), "M": index.to_period("M"), "Q": index.to_period("Q")}
+    if frequency not in periods:
+        raise ValueError(f"Unknown rebalance frequency '{frequency}'")
+    period = periods[frequency]
+    # First bar of each period -- known at the time, unlike the last bar.
+    return pd.Series(period != pd.Series(period, index=index).shift(1).to_numpy(), index=index)
+
+
+def _portfolio_metrics(held: pd.DataFrame, traded: pd.Series, years: float) -> dict:
+    """Book-level statistics a portfolio manager will look for first."""
+    absolute = held.abs()
+    gross = absolute.sum(axis=1)
+    active = (absolute > 1e-9).sum(axis=1)
+
+    # Herfindahl on the gross book: 1.0 is everything in one name, 1/n is even.
+    shares = absolute.div(gross.replace(0.0, np.nan), axis=0)
+    hhi = (shares**2).sum(axis=1)
+
+    return {
+        "gross_exposure": float(gross.mean()),
+        "net_exposure": float(held.sum(axis=1).mean()),
+        "max_gross_exposure": float(gross.max()),
+        "avg_positions": float(active.mean()),
+        "max_positions": float(active.max()),
+        "concentration_hhi": float(hhi.mean(skipna=True)) if hhi.notna().any() else float("nan"),
+        "turnover_ann": float(traded.sum() / years) if years > 0 else 0.0,
+        "n_trades": float((traded > 1e-9).sum()),
+    }

algotrader/portfolio_lab.py

@@ -0,0 +1,319 @@
+"""The Portfolio Lab: the honesty pipeline for cross-sectional strategies.
+
+Same idea as :mod:`algotrader.lab`, but the questions change when you move from
+one asset to many. A timing rule has to prove the market had structure. A book
+that ranks names has to prove three harder things:
+
+1. it picked the right names (cross-sectional permutation);
+2. what it picked is not just a style you could buy in an ETF (attribution);
+3. the universe it picked from contains the losers as well as the winners
+   (survivorship).
+
+All three are wired into the Reality Score alongside the usual selection-bias
+and walk-forward machinery.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .attribution import build_style_factors, factor_attribution
+from .cross_sectional import CrossSectionalStrategy, get_xs_strategy, list_xs_strategies
+from .metrics import infer_periods_per_year
+from .panel import Panel, load_panel
+from .portfolio import PortfolioResult, rebalance_schedule, run_portfolio_backtest
+from .types import CostModel
+from .validation.cross_permutation import CrossPermutationResult, cross_sectional_permutation_test
+from .validation.deflated_sharpe import deflated_sharpe_ratio
+from .validation.pbo import probability_of_backtest_overfitting
+from .validation.walkforward import walk_forward_panel
+from .verdict import reality_score
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["PortfolioLabConfig", "PortfolioLabReport", "run_portfolio_lab", "run_portfolio_arena"]
+
+ProgressFn = Optional[Callable[[float, str], None]]
+
+DEFAULT_UNIVERSE = [
+    "SPY", "QQQ", "AAPL", "MSFT", "NVDA", "AMZN",
+    "META", "TSLA", "GOOGL", "GLD", "TLT", "BTC-USD",
+]
+
+
+@dataclass
+class PortfolioLabConfig:
+    symbols: Sequence[str] = tuple(DEFAULT_UNIVERSE)
+    start: str = "2015-01-01"
+    end: Optional[str] = None
+    interval: str = "1d"
+    source: str = "auto"
+
+    strategy: str = "xs_momentum"
+    params: Dict[str, float] = field(default_factory=dict)
+
+    commission_bps: float = 1.0
+    slippage_bps: float = 2.0
+    short_borrow_bps: float = 50.0
+    lag: int = 1
+    gross_leverage: float = 1.0
+    max_weight: Optional[float] = 0.25
+    allow_short: bool = True
+    rebalance: str = "M"
+    capital: float = 1_000_000.0
+
+    n_permutations: int = 150
+    wf_folds: int = 4
+    pbo_splits: int = 8
+    grid_limit: int = 24
+    seed: int = 0
+
+    def costs(self, multiplier: float = 1.0) -> CostModel:
+        return CostModel(
+            commission_bps=self.commission_bps * multiplier,
+            slippage_bps=self.slippage_bps * multiplier,
+            short_borrow_bps=self.short_borrow_bps * multiplier,
+        )
+
+
+@dataclass
+class PortfolioLabReport:
+    config: PortfolioLabConfig
+    panel: Panel
+    strategy: CrossSectionalStrategy
+    params: Dict[str, float]
+    backtest: PortfolioResult
+    permutation: Optional[CrossPermutationResult] = None
+    dsr: Dict[str, float] = field(default_factory=dict)
+    pbo: Dict[str, object] = field(default_factory=dict)
+    walkforward: Dict[str, object] = field(default_factory=dict)
+    attribution: Dict[str, object] = field(default_factory=dict)
+    trials: Dict[str, object] = field(default_factory=dict)
+    verdict: Dict[str, object] = field(default_factory=dict)
+    cost_stress: Dict[str, float] = field(default_factory=dict)
+
+    @property
+    def survivorship(self):
+        return self.panel.survivorship()
+
+
+def _trial_matrix(
+    panel: Panel,
+    strategy: CrossSectionalStrategy,
+    cfg: PortfolioLabConfig,
+    schedule: pd.Series,
+    progress: ProgressFn = None,
+) -> tuple[np.ndarray, List[float], List[str]]:
+    """Backtest every parameter variant, for the Deflated Sharpe and PBO inputs."""
+    grid = strategy.grid(limit=cfg.grid_limit)
+    costs = cfg.costs()
+    columns, sharpes, labels = [], [], []
+
+    for i, params in enumerate(grid):
+        weights = strategy.generate(panel, params)
+        result = run_portfolio_backtest(
+            panel, weights, costs=costs, lag=cfg.lag,
+            gross_leverage=cfg.gross_leverage, max_weight=cfg.max_weight,
+            allow_short=cfg.allow_short, rebalance_on=schedule,
+        )
+        columns.append(result.returns.to_numpy(dtype=float))
+        sharpes.append(result.sharpe)
+        labels.append(", ".join(f"{k}={v}" for k, v in params.items()) or "default")
+        if progress is not None and i % 3 == 0:
+            progress((i + 1) / max(len(grid), 1), f"Variant {i + 1}/{len(grid)}")
+
+    matrix = np.column_stack(columns) if columns else np.zeros((len(panel), 0))
+    return matrix, sharpes, labels
+
+
+def run_portfolio_lab(cfg: PortfolioLabConfig, progress: ProgressFn = None) -> PortfolioLabReport:
+    """Run the full cross-sectional honesty pipeline."""
+
+    def step(fraction: float, message: str) -> None:
+        if progress is not None:
+            progress(min(max(fraction, 0.0), 1.0), message)
+
+    step(0.02, f"Loading {len(cfg.symbols)} symbols")
+    panel = load_panel(cfg.symbols, cfg.start, cfg.end, cfg.interval, cfg.source)
+    if len(panel) < 250:
+        raise ValueError(
+            f"Only {len(panel)} bars available. Widen the date range — a cross-sectional "
+            "book cannot be validated on less than a year of data."
+        )
+
+    strategy = get_xs_strategy(cfg.strategy)
+    params = strategy.clean(cfg.params)
+    ppy = infer_periods_per_year(panel.index)
+    schedule = rebalance_schedule(panel.index, cfg.rebalance)
+
+    step(0.10, "Running the backtest")
+    weights = strategy.generate(panel, params)
+    backtest = run_portfolio_backtest(
+        panel, weights, costs=cfg.costs(), lag=cfg.lag,
+        gross_leverage=cfg.gross_leverage, max_weight=cfg.max_weight,
+        allow_short=cfg.allow_short, initial_capital=cfg.capital,
+        periods_per_year=ppy, rebalance_on=schedule,
+        meta={"strategy": strategy.key, "params": params, "rebalance": cfg.rebalance},
+    )
+
+    step(0.16, "Stress-testing costs")
+    stressed = run_portfolio_backtest(
+        panel, weights, costs=cfg.costs(3.0), lag=cfg.lag,
+        gross_leverage=cfg.gross_leverage, max_weight=cfg.max_weight,
+        allow_short=cfg.allow_short, periods_per_year=ppy, rebalance_on=schedule,
+    )
+    base_sharpe = backtest.sharpe
+    cost_stress = {
+        "sharpe_1x": base_sharpe,
+        "sharpe_3x": stressed.sharpe,
+        "ratio": float(stressed.sharpe / base_sharpe) if base_sharpe > 1e-9 else 0.0,
+        "return_3x": float(stressed.metrics.get("total_return", 0.0)),
+    }
+
+    step(0.22, "Backtesting every parameter variant")
+    matrix, trial_sharpes, labels = _trial_matrix(
+        panel, strategy, cfg, schedule, lambda f, m: step(0.22 + 0.14 * f, m)
+    )
+    n_trials = max(len(trial_sharpes), 1)
+
+    step(0.38, "Deflating the Sharpe ratio for selection bias")
+    dsr = deflated_sharpe_ratio(
+        backtest.returns.to_numpy(dtype=float),
+        sharpe_annual=base_sharpe,
+        periods_per_year=ppy,
+        n_trials=n_trials,
+        trial_sharpes=trial_sharpes if n_trials > 1 else None,
+    )
+
+    step(0.42, "Measuring backtest overfitting")
+    pbo = probability_of_backtest_overfitting(matrix, n_splits=cfg.pbo_splits, labels=labels)
+
+    step(0.46, "Shuffling names within each date")
+    permutation = None
+    if cfg.n_permutations > 0:
+        permutation = cross_sectional_permutation_test(
+            panel, weights, n_permutations=cfg.n_permutations, lag=cfg.lag,
+            gross_leverage=cfg.gross_leverage, max_weight=cfg.max_weight,
+            allow_short=cfg.allow_short, rebalance_on=schedule, seed=cfg.seed,
+            progress=lambda f, m: step(0.46 + 0.30 * f, m),
+        )
+
+    step(0.78, "Attributing returns to style factors")
+    try:
+        factors = build_style_factors(panel)
+        attribution = factor_attribution(backtest.returns, factors, ppy)
+    except Exception as exc:  # noqa: BLE001 - attribution must never sink a run
+        logger.warning("Attribution failed: %s", exc)
+        attribution = {"available": False, "note": f"Attribution unavailable: {exc}"}
+
+    step(0.86, "Walking the strategy forward")
+    wf = walk_forward_panel(
+        panel, strategy, n_folds=cfg.wf_folds, costs=cfg.costs(), lag=cfg.lag,
+        gross_leverage=cfg.gross_leverage, allow_short=cfg.allow_short,
+        rebalance=cfg.rebalance, grid_limit=min(cfg.grid_limit, 12),
+        progress=lambda f, m: step(0.86 + 0.10 * f, m),
+    )
+
+    step(0.98, "Grading")
+    survivorship = panel.survivorship()
+    verdict = reality_score(
+        metrics=backtest.metrics,
+        benchmark_metrics=backtest.benchmark_metrics,
+        p_value=permutation.p_value if permutation else None,
+        dsr=dsr.get("dsr"),
+        pbo=pbo.get("pbo"),
+        wf_efficiency=wf.get("efficiency"),
+        wf_win_rate=wf.get("oos_win_rate"),
+        cost_stress_ratio=cost_stress["ratio"],
+        attribution=attribution,
+        survivorship=survivorship,
+        benchmark_name="The equal-weight universe",
+        permutation_label="books with the same shape but randomly chosen names",
+    )
+
+    step(1.0, "Done")
+    return PortfolioLabReport(
+        config=cfg,
+        panel=panel,
+        strategy=strategy,
+        params=params,
+        backtest=backtest,
+        permutation=permutation,
+        dsr=dsr,
+        pbo=pbo,
+        walkforward=wf,
+        attribution=attribution,
+        trials={"n": n_trials, "sharpes": trial_sharpes, "labels": labels},
+        verdict=verdict,
+        cost_stress=cost_stress,
+    )
+
+
+def run_portfolio_arena(
+    cfg: PortfolioLabConfig,
+    strategy_keys: Optional[List[str]] = None,
+    n_permutations: int = 80,
+    progress: ProgressFn = None,
+) -> tuple[pd.DataFrame, Panel, Dict[str, PortfolioResult]]:
+    """Race every cross-sectional strategy on one universe, ranked by evidence."""
+    panel = load_panel(cfg.symbols, cfg.start, cfg.end, cfg.interval, cfg.source)
+    ppy = infer_periods_per_year(panel.index)
+    schedule = rebalance_schedule(panel.index, cfg.rebalance)
+    costs = cfg.costs()
+
+    keys = strategy_keys or [s.key for s in list_xs_strategies()]
+    factors = build_style_factors(panel)
+    rows, books = [], {}
+
+    for i, key in enumerate(keys):
+        strategy = get_xs_strategy(key)
+        weights = strategy.generate(panel, strategy.defaults())
+        result = run_portfolio_backtest(
+            panel, weights, costs=costs, lag=cfg.lag, gross_leverage=cfg.gross_leverage,
+            max_weight=cfg.max_weight, allow_short=cfg.allow_short,
+            initial_capital=cfg.capital, periods_per_year=ppy, rebalance_on=schedule,
+        )
+        books[key] = result
+
+        p_value = float("nan")
+        if n_permutations > 0:
+            p_value = cross_sectional_permutation_test(
+                panel, weights, n_permutations=n_permutations, lag=cfg.lag,
+                gross_leverage=cfg.gross_leverage, max_weight=cfg.max_weight,
+                allow_short=cfg.allow_short, rebalance_on=schedule, seed=cfg.seed,
+                observed=result.sharpe,
+            ).p_value
+
+        dsr = deflated_sharpe_ratio(
+            result.returns.to_numpy(dtype=float), sharpe_annual=result.sharpe,
+            periods_per_year=ppy, n_trials=len(strategy.grid(limit=cfg.grid_limit)),
+        )
+        attr = factor_attribution(result.returns, factors, ppy)
+
+        rows.append({
+            "Strategy": strategy.name,
+            "key": key,
+            "Family": strategy.family,
+            "Return": result.metrics.get("total_return", 0.0),
+            "CAGR": result.metrics.get("cagr", 0.0),
+            "Sharpe": result.sharpe,
+            "MaxDD": result.metrics.get("max_drawdown", 0.0),
+            "Turnover": result.metrics.get("turnover_ann", 0.0),
+            "p-value": p_value,
+            "DSR": dsr["dsr"],
+            "Alpha t": attr.get("alpha_t_stat", float("nan")) if attr.get("available") else float("nan"),
+        })
+        if progress is not None:
+            progress((i + 1) / len(keys), f"{strategy.name} ({i + 1}/{len(keys)})")
+
+    table = pd.DataFrame(rows)
+    if not table.empty:
+        table["Evidence"] = (1.0 - table["p-value"].fillna(0.5)) * table["DSR"]
+        table = table.sort_values("Evidence", ascending=False).reset_index(drop=True)
+        table.insert(0, "#", table.index + 1)
+    return table, panel, books

algotrader/validation/cross_permutation.py

@@ -0,0 +1,146 @@
+"""The cross-sectional null.
+
+For a timing rule, shuffling the price path is the right null. For a rule that
+*ranks names*, it is the wrong test entirely: shuffling time destroys the
+market's whole correlation structure, and the resulting null is so weak that
+almost any long-short book clears it.
+
+The question a cross-sectional strategy has to answer is narrower. Not "does
+this market have structure?" but: **given these dates, these assets and this
+book's shape, does the strategy put its weight on the right names?**
+
+So we permute the *weights across assets within each date*. Every calendar
+effect survives. Every correlation between names survives. The gross and net
+exposure of the book on each date survives exactly. The one thing destroyed is
+the link between the strategy's choice and the asset it chose.
+
+A momentum book that beats this null is picking names. One that does not was
+being paid for its market exposure, its sector tilt, or the calendar -- all of
+which are available far more cheaply.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+import numpy as np
+import pandas as pd
+
+from ..panel import Panel
+from ..portfolio import run_portfolio_backtest
+from ..types import CostModel
+
+__all__ = ["cross_sectional_permutation_test", "permute_within_dates", "CrossPermutationResult"]
+
+
+@dataclass
+class CrossPermutationResult:
+    observed: float
+    null: np.ndarray
+    p_value: float
+    n_permutations: int
+
+    @property
+    def null_mean(self) -> float:
+        return float(np.mean(self.null)) if self.null.size else 0.0
+
+    @property
+    def percentile(self) -> float:
+        if not self.null.size:
+            return 50.0
+        return float((self.null < self.observed).mean() * 100.0)
+
+
+def permute_within_dates(
+    weights: pd.DataFrame,
+    investable: pd.DataFrame,
+    rng: np.random.Generator,
+) -> pd.DataFrame:
+    """Reassign each date's weights among that date's investable assets.
+
+    The multiset of weights on every row is preserved exactly -- so gross
+    exposure, net exposure, leg sizes and position counts are all identical to
+    the real book -- but which asset receives which weight is randomised.
+
+    Vectorised across all dates at once: sorting each row puts the investable
+    weights first and pushes non-investable slots to NaN, then a random rank per
+    investable slot picks each weight exactly once.
+    """
+    values = weights.to_numpy(dtype=float, copy=True)
+    mask = investable.to_numpy(dtype=bool)
+
+    masked = np.where(mask, values, np.nan)
+    # NaNs sort last, so the first k entries of each row are that row's real weights.
+    ordered = np.sort(masked, axis=1)
+
+    noise = np.where(mask, rng.random(values.shape), np.inf)
+    # Double argsort turns random values into ranks 0..k-1 for investable slots,
+    # and k..n-1 for the rest, which then index into the NaN tail.
+    random_rank = np.argsort(np.argsort(noise, axis=1), axis=1)
+
+    shuffled = np.take_along_axis(ordered, random_rank, axis=1)
+    return pd.DataFrame(
+        np.nan_to_num(shuffled, nan=0.0), index=weights.index, columns=weights.columns
+    )
+
+
+def cross_sectional_permutation_test(
+    panel: Panel,
+    weights: pd.DataFrame,
+    n_permutations: int = 200,
+    costs: Optional[CostModel] = None,
+    lag: int = 1,
+    gross_leverage: float = 1.0,
+    max_weight: Optional[float] = None,
+    allow_short: bool = True,
+    rebalance_on: Optional[pd.Series] = None,
+    seed: int = 0,
+    observed: Optional[float] = None,
+    neutralise_costs: bool = True,
+    progress: Optional[Callable[[float, str], None]] = None,
+) -> CrossPermutationResult:
+    """Test whether a book's Sharpe survives randomising which names it picked.
+
+    ``neutralise_costs`` defaults to True, and it matters more than it looks.
+    A real momentum book holds many of the same names from one rebalance to the
+    next, so it churns slowly. A shuffled book reassigns names at random every
+    date, so it churns furiously and pays for it. Charging costs would penalise
+    the null for turnover the strategy never had, and the strategy would look
+    good by comparison for reasons that have nothing to do with skill.
+
+    So this test asks only "did it pick the right names?" and leaves "can you
+    afford to trade it?" to the cost stress test, which measures that directly.
+    """
+    costs = CostModel(0.0, 0.0, 0.0) if neutralise_costs else (costs or CostModel())
+    rng = np.random.default_rng(seed)
+    investable = panel.close.notna()
+
+    def sharpe_of(w: pd.DataFrame) -> float:
+        return run_portfolio_backtest(
+            panel,
+            w,
+            costs=costs,
+            lag=lag,
+            gross_leverage=gross_leverage,
+            max_weight=max_weight,
+            allow_short=allow_short,
+            rebalance_on=rebalance_on,
+        ).sharpe
+
+    if observed is None:
+        observed = sharpe_of(weights)
+
+    null = np.empty(n_permutations, dtype=float)
+    for i in range(n_permutations):
+        null[i] = sharpe_of(permute_within_dates(weights, investable, rng))
+        if progress is not None and (i % 10 == 0 or i == n_permutations - 1):
+            progress((i + 1) / n_permutations, f"Cross-sectional shuffle {i + 1}/{n_permutations}")
+
+    p_value = float((1 + np.sum(null >= observed)) / (n_permutations + 1))
+    return CrossPermutationResult(
+        observed=float(observed),
+        null=null,
+        p_value=p_value,
+        n_permutations=n_permutations,
+    )

algotrader/validation/walkforward.py

@@ -16,7 +16,7 @@ from ..engine import run_backtest
 from ..strategies import Strategy
 from ..types import CostModel
 
-__all__ = ["walk_forward"]
+__all__ = ["walk_forward", "walk_forward_panel"]
 
 
 def walk_forward(
@@ -127,3 +127,107 @@ def walk_forward(
         "oos_equity": (1.0 + stitched).cumprod() if len(stitched) else stitched,
         "note": "",
     }
+
+
+def walk_forward_panel(
+    panel,
+    strategy,
+    n_folds: int = 4,
+    train_ratio: float = 0.7,
+    costs: Optional[CostModel] = None,
+    lag: int = 1,
+    gross_leverage: float = 1.0,
+    allow_short: bool = True,
+    rebalance: str = "M",
+    grid_limit: int = 16,
+    progress: Optional[Callable[[float, str], None]] = None,
+) -> Dict[str, object]:
+    """Walk-forward for cross-sectional strategies over a :class:`Panel`.
+
+    Same contract as :func:`walk_forward`: tune on the training window, trade
+    the next window blind, roll on. Signals are generated over train+test
+    together so the indicators are warm at the fold boundary, then evaluated
+    only on the test slice -- the panel equivalent of the single-asset path.
+    """
+    from ..portfolio import rebalance_schedule, run_portfolio_backtest
+
+    costs = costs or CostModel()
+    grid = strategy.grid(limit=grid_limit)
+    n = len(panel)
+
+    if n < 250 or n_folds < 2:
+        return {"folds": [], "note": "Not enough history for walk-forward analysis."}
+
+    block = min(int(n / (1 + (n_folds - 1) * (1 - train_ratio))), n)
+    train_len = int(block * train_ratio)
+    test_len = block - train_len
+    if train_len < 100 or test_len < 20:
+        return {"folds": [], "note": "Not enough history for walk-forward analysis."}
+
+    folds: List[Dict[str, object]] = []
+    oos_returns: List[pd.Series] = []
+
+    for k in range(n_folds):
+        start = k * test_len
+        train = panel.slice(panel.index[start], panel.index[min(start + train_len - 1, n - 1)])
+        test_start = start + train_len
+        if test_start + 20 > n:
+            break
+        test_end = min(test_start + test_len, n) - 1
+        test = panel.slice(panel.index[test_start], panel.index[test_end])
+        if len(test) < 20:
+            break
+
+        best_params, best_sharpe = None, -np.inf
+        for params in grid:
+            weights = strategy.generate(train, params)
+            sharpe = run_portfolio_backtest(
+                train, weights, costs=costs, lag=lag, gross_leverage=gross_leverage,
+                allow_short=allow_short, rebalance_on=rebalance_schedule(train.index, rebalance),
+            ).sharpe
+            if sharpe > best_sharpe:
+                best_params, best_sharpe = params, sharpe
+
+        combined = panel.slice(panel.index[start], panel.index[test_end])
+        weights = strategy.generate(combined, best_params).loc[test.index]
+        oos = run_portfolio_backtest(
+            test, weights, costs=costs, lag=lag, gross_leverage=gross_leverage,
+            allow_short=allow_short, rebalance_on=rebalance_schedule(test.index, rebalance),
+        )
+
+        folds.append({
+            "fold": k + 1,
+            "train_start": str(train.index[0].date()),
+            "train_end": str(train.index[-1].date()),
+            "test_start": str(test.index[0].date()),
+            "test_end": str(test.index[-1].date()),
+            "params": best_params,
+            "is_sharpe": float(best_sharpe),
+            "oos_sharpe": float(oos.sharpe),
+            "oos_return": float(oos.metrics.get("total_return", 0.0)),
+            "oos_max_dd": float(oos.metrics.get("max_drawdown", 0.0)),
+        })
+        oos_returns.append(oos.returns)
+        if progress is not None:
+            progress((k + 1) / n_folds, f"Walk-forward fold {k + 1}/{n_folds}")
+
+    if not folds:
+        return {"folds": [], "note": "Not enough history for walk-forward analysis."}
+
+    is_sharpes = np.array([f["is_sharpe"] for f in folds], dtype=float)
+    oos_sharpes = np.array([f["oos_sharpe"] for f in folds], dtype=float)
+    stitched = pd.concat(oos_returns) if oos_returns else pd.Series(dtype=float)
+    stitched = stitched[~stitched.index.duplicated(keep="first")].sort_index()
+    mean_is, mean_oos = float(np.mean(is_sharpes)), float(np.mean(oos_sharpes))
+
+    return {
+        "folds": folds,
+        "mean_is_sharpe": mean_is,
+        "mean_oos_sharpe": mean_oos,
+        "efficiency": float(mean_oos / mean_is) if mean_is > 1e-9 else 0.0,
+        "oos_win_rate": float(np.mean(oos_sharpes > 0)),
+        "param_instability": float(len({str(f["params"]) for f in folds}) / max(len(folds), 1)),
+        "oos_returns": stitched,
+        "oos_equity": (1.0 + stitched).cumprod() if len(stitched) else stitched,
+        "note": "",
+    }

algotrader/verdict.py

@@ -49,8 +49,16 @@ def reality_score(
     wf_win_rate: Optional[float] = None,
     cost_stress_ratio: Optional[float] = None,
     benchmark_correlation: Optional[float] = None,
+    attribution: Optional[Dict[str, object]] = None,
+    survivorship: Optional[object] = None,
+    benchmark_name: str = "Buy & hold",
+    permutation_label: str = "shuffled, structure-free markets",
 ) -> Dict[str, object]:
-    """Combine the validation panel into a 0-100 score, a grade and warnings."""
+    """Combine the validation panel into a 0-100 score, a grade and warnings.
+
+    ``attribution`` and ``survivorship`` are the portfolio-only inputs; both are
+    optional so the single-asset path is unaffected.
+    """
     components: Dict[str, float] = {}
 
     components["significance"] = _ramp(p_value, good=0.01, bad=0.50) if p_value is not None else 50.0
@@ -106,8 +114,8 @@ def reality_score(
         score = min(score, 55.0)
     if p_value is not None and p_value > 0.10:
         flags.append(
-            f"Permutation p-value is {p_value:.2f}: roughly {p_value * 100:.0f}% of shuffled, "
-            "structure-free markets did this well or better."
+            f"Permutation p-value is {p_value:.2f}: roughly {p_value * 100:.0f}% of "
+            f"{permutation_label} did this well or better."
         )
     if dsr is not None and dsr < 0.5:
         flags.append(
@@ -131,12 +139,13 @@ def reality_score(
         )
     if benchmark_correlation is not None and benchmark_correlation > 0.95:
         flags.append(
-            f"Returns are {benchmark_correlation:.0%} correlated with buy & hold — "
+            f"Returns are {benchmark_correlation:.0%} correlated with {benchmark_name.lower()} — "
             "this is mostly a repackaged long position."
         )
     if sharpe < bench_sharpe:
         flags.append(
-            f"Buy & hold beat it on risk-adjusted return ({bench_sharpe:.2f} vs {sharpe:.2f} Sharpe)."
+            f"{benchmark_name} beat it on risk-adjusted return "
+            f"({bench_sharpe:.2f} vs {sharpe:.2f} Sharpe)."
         )
     if float(metrics.get("turnover_ann", 0.0)) > 100:
         flags.append(
@@ -144,11 +153,36 @@ def reality_score(
             "retail execution can absorb without moving the modelled fills."
         )
 
+    # Portfolio-only checks. Style exposure you could buy in an ETF is not
+    # alpha, and a universe with no failures in it is not a universe.
+    if attribution and attribution.get("available"):
+        if not attribution.get("alpha_significant"):
+            flags.append(
+                f"Style regression leaves no significant alpha (t = "
+                f"{attribution.get('alpha_t_stat', 0):.1f}); the factors explain "
+                f"{attribution.get('r_squared', 0):.0%} of returns"
+                + (
+                    f", mostly {attribution['dominant_factor']} exposure."
+                    if attribution.get("dominant_factor")
+                    else "."
+                )
+            )
+            score = min(score, 65.0)
+        if float(attribution.get("r_squared", 0.0)) > 0.9:
+            flags.append(
+                "Over 90% of the return variation is explained by simple style factors — "
+                "this book is a repackaged index."
+            )
+    if survivorship is not None and getattr(survivorship, "biased", False):
+        flags.append(getattr(survivorship, "note", "Universe appears survivorship-biased."))
+        score = min(score, 60.0)
+
+    score = float(np.clip(score, 0.0, 100.0))
     grade, headline = next((g, h) for threshold, g, h in GRADES if score >= threshold)
 
     if score >= 70:
         verdict = (
-            f"Grade {grade}. {headline}. The edge is still there after shuffling the market, "
+            f"Grade {grade}. {headline}. The edge is still there after the permutation test, "
             "after charging for every variant tried, and after walking it forward."
         )
     elif score >= 55:
@@ -163,8 +197,8 @@ def reality_score(
         )
     else:
         verdict = (
-            f"Grade {grade}. {headline}. A randomly shuffled market produces results like this "
-            "often enough that there is nothing here to trade."
+            f"Grade {grade}. {headline}. The null — {permutation_label} — produces results "
+            "like this often enough that there is nothing here to trade."
         )
 
     return {

app.py

@@ -19,6 +19,8 @@ import pandas as pd
 from algotrader import __version__
 from algotrader.charts import (
     arena_chart,
+    attribution_chart,
+    cross_permutation_chart,
     drawdown_chart,
     empty_figure,
     equity_chart,
@@ -26,16 +28,22 @@ from algotrader.charts import (
     permutation_chart,
     score_chart,
     walkforward_chart,
+    weights_chart,
 )
+from algotrader.cross_sectional import XS_REGISTRY, get_xs_strategy
 from algotrader.data import DEFAULT_UNIVERSE
 from algotrader.lab import LabConfig, run_arena, run_lab
+from algotrader.portfolio_lab import DEFAULT_UNIVERSE as PORTFOLIO_UNIVERSE
+from algotrader.portfolio_lab import PortfolioLabConfig, run_portfolio_lab
 from algotrader.strategies import REGISTRY, get_strategy
 
 logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
 logger = logging.getLogger("app")
 
 MAX_PARAMS = 3
+MAX_XS_PARAMS = 4
 STRATEGY_CHOICES = [(s.name, key) for key, s in REGISTRY.items()]
+XS_STRATEGY_CHOICES = [(s.name, key) for key, s in XS_REGISTRY.items()]
 
 GRADE_COLORS = {
     "A": "#0ca30c",
@@ -165,6 +173,207 @@ def _tiles(report) -> str:
     return f'<div class="tiles">{tiles}</div>'
 
 
+def xs_param_controls(strategy_key: str):
+    """Re-label the shared portfolio sliders for the selected strategy."""
+    strategy = get_xs_strategy(strategy_key)
+    updates = []
+    for i in range(MAX_XS_PARAMS):
+        if i < len(strategy.params):
+            spec = strategy.params[i]
+            updates.append(
+                gr.update(
+                    visible=True,
+                    label=spec.label,
+                    value=spec.cast(spec.default),
+                    minimum=spec.minimum if spec.minimum is not None else min(spec.grid),
+                    maximum=spec.maximum if spec.maximum is not None else max(spec.grid),
+                    step=spec.step or (1 if spec.kind == "int" else 0.05),
+                )
+            )
+        else:
+            updates.append(gr.update(visible=False))
+    return tuple(updates)
+
+
+def _portfolio_card(report) -> str:
+    v = report.verdict
+    color = GRADE_COLORS.get(v["grade"], "#898781")
+    panel = report.panel
+    survivorship = report.survivorship
+
+    provenance = (
+        f'<div class="provenance">{len(panel.symbols)} symbols · '
+        f"{panel.index[0].date()} to {panel.index[-1].date()} · {len(panel):,} bars · "
+        f"rebalance {report.config.rebalance}</div>"
+    )
+    if panel.note:
+        provenance += f'<div class="provenance sim">⚠ {panel.note}</div>'
+    # The survivorship note is already in the flag list when it is a problem;
+    # repeating it under the tiles just makes the card noisy.
+
+    flags = "".join(f"<li>{f}</li>" for f in v["flags"])
+    flags_html = f'<ul class="flags">{flags}</ul>' if flags else ""
+
+    return f"""
+<div class="score-card">
+  <div class="score-badge">
+    <div class="grade" style="color:{color}">{v['grade']}</div>
+    <div class="num">{v['score']} / 100</div>
+  </div>
+  <div class="score-body">
+    <h3>{report.strategy.name} across {len(panel.symbols)} names</h3>
+    <p>{v['verdict']}</p>
+  </div>
+</div>
+{flags_html}
+{provenance}
+"""
+
+
+def _portfolio_tiles(report) -> str:
+    m = report.backtest.metrics
+    b = report.backtest.benchmark_metrics
+    perm = report.permutation
+    attribution = report.attribution
+    pbo = report.pbo.get("pbo")
+
+    cells = [
+        ("Total return", _fmt_pct(m.get("total_return", 0)), f"equal weight {_fmt_pct(b.get('total_return', 0))}"),
+        ("Sharpe", f"{m.get('sharpe', 0):.2f}", f"equal weight {b.get('sharpe', 0):.2f}"),
+        ("Max drawdown", _fmt_pct(m.get("max_drawdown", 0)), f"{m.get('time_under_water_yrs', 0):.1f}y under water"),
+        ("Name-shuffle p", f"{perm.p_value:.3f}" if perm else "—", "vs same book, random names"),
+        ("Deflated Sharpe", f"{report.dsr.get('dsr', 0):.2f}", f"after {report.trials.get('n', 1)} variants"),
+        (
+            "Style alpha",
+            f"{attribution.get('alpha_annual', 0) * 100:,.1f}%" if attribution.get("available") else "n/a",
+            f"t = {attribution.get('alpha_t_stat', 0):.1f}" if attribution.get("available") else "not available",
+        ),
+        ("Overfit prob.", f"{pbo:.0%}" if pbo is not None and pbo == pbo else "n/a", "in-sample winner fails OOS"),
+        ("Gross / net", f"{m.get('gross_exposure', 0):.2f}", f"net {m.get('net_exposure', 0):+.2f}"),
+        ("Avg positions", f"{m.get('avg_positions', 0):.1f}", f"{m.get('turnover_ann', 0):.1f}x turnover/yr"),
+        (
+            "Survivorship",
+            f"{report.survivorship.survival_rate:.0%}",
+            f"{report.survivorship.n_delisted} of {report.survivorship.n_symbols} delisted",
+        ),
+    ]
+    tiles = "".join(
+        f'<div class="tile"><div class="label">{label}</div>'
+        f'<div class="value">{value}</div><div class="sub">{sub}</div></div>'
+        for label, value, sub in cells
+    )
+    return f'<div class="tiles">{tiles}</div>'
+
+
+def _portfolio_detail(report) -> str:
+    attribution, survivorship, wf = report.attribution, report.survivorship, report.walkforward
+    lines = ["### Reading the evidence", ""]
+
+    if report.permutation:
+        lines += [
+            f"**Did it pick the right names?** We rebuilt the book "
+            f"{report.permutation.n_permutations} times, keeping every date's gross exposure, net "
+            f"exposure and position count exactly as they were, and only randomising *which* asset "
+            f"got which weight. The real book's Sharpe of {report.permutation.observed:.2f} sits at "
+            f"the {report.permutation.percentile:.0f}th percentile of that null "
+            f"(p = {report.permutation.p_value:.3f}). This test deliberately ignores trading costs: "
+            "a shuffled book churns far more than a real one, and charging it for that would "
+            "flatter the strategy for reasons unrelated to skill.",
+            "",
+        ]
+    if attribution.get("available"):
+        lines += [f"**Is it alpha or is it beta?** {attribution['note']}", ""]
+    lines += [f"**Survivorship.** {survivorship.note}", ""]
+    if survivorship.delisted_symbols:
+        lines += [f"Stopped trading during the sample: `{'`, `'.join(survivorship.delisted_symbols)}`.", ""]
+    if wf.get("folds"):
+        lines += [
+            f"**Walk-forward.** Across {len(wf['folds'])} folds the tuned in-sample Sharpe averaged "
+            f"{wf.get('mean_is_sharpe', 0):.2f} against {wf.get('mean_oos_sharpe', 0):.2f} blind out "
+            f"of sample — {wf.get('efficiency', 0):.0%} efficiency, with "
+            f"{wf.get('oos_win_rate', 0):.0%} of folds profitable.",
+            "",
+        ]
+    lines += [
+        f"**Costs.** Sharpe is {report.cost_stress.get('sharpe_1x', 0):.2f} at the modelled friction "
+        f"and {report.cost_stress.get('sharpe_3x', 0):.2f} at triple it "
+        f"({report.cost_stress.get('ratio', 0):.0%} retained), on turnover of "
+        f"{report.backtest.metrics.get('turnover_ann', 0):.1f}x a year.",
+        "",
+        "> Past performance, simulated or otherwise, does not predict future returns. "
+        "This is research tooling, not investment advice.",
+    ]
+    return "\n".join(lines)
+
+
+def analyse_portfolio(
+    symbols: str,
+    start: str,
+    end: str,
+    strategy_key: str,
+    p1: float,
+    p2: float,
+    p3: float,
+    p4: float,
+    rebalance: str,
+    commission: float,
+    slippage: float,
+    allow_short: bool,
+    gross_leverage: float,
+    max_weight: float,
+    n_permutations: int,
+    progress=gr.Progress(),
+):
+    """Portfolio Lab handler. Like the single-asset one, it never raises into the UI."""
+    try:
+        universe = [s.strip().upper() for s in (symbols or "").replace("\n", ",").split(",") if s.strip()]
+        if len(universe) < 4:
+            raise ValueError(
+                "A cross-sectional strategy needs at least 4 symbols — it ranks names against "
+                "each other, and there is nothing to rank in a list this short."
+            )
+        strategy = get_xs_strategy(strategy_key)
+        values = (p1, p2, p3, p4)
+        params = {
+            spec.name: spec.cast(values[i])
+            for i, spec in enumerate(strategy.params[:MAX_XS_PARAMS])
+        }
+        cfg = PortfolioLabConfig(
+            symbols=universe,
+            start=start or "2015-01-01",
+            end=end or None,
+            strategy=strategy_key,
+            params=params,
+            commission_bps=float(commission),
+            slippage_bps=float(slippage),
+            allow_short=bool(allow_short),
+            gross_leverage=float(gross_leverage),
+            max_weight=float(max_weight) if max_weight else None,
+            rebalance=rebalance,
+            n_permutations=int(n_permutations),
+        )
+        report = run_portfolio_lab(cfg, progress=lambda f, m: progress(f, desc=m))
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Portfolio lab run failed")
+        message = (
+            f'<div class="score-card"><div class="score-body"><h3>Could not run that</h3>'
+            f"<p>{exc}</p></div></div>"
+        )
+        blank = empty_figure("No results.")
+        return message, "", blank, blank, blank, blank, blank, ""
+
+    return (
+        _portfolio_card(report),
+        _portfolio_tiles(report),
+        cross_permutation_chart(report),
+        equity_chart(report, benchmark_label="Equal weight"),
+        attribution_chart(report.attribution),
+        weights_chart(report),
+        score_chart(report.verdict, significance_label="Picks the right names"),
+        _portfolio_detail(report),
+    )
+
+
 def _detail_markdown(report) -> str:
     dsr, wf, pbo, stress = report.dsr, report.walkforward, report.pbo, report.cost_stress
     mtr = dsr.get("min_track_record_years", float("inf"))
@@ -512,6 +721,86 @@ def build_app() -> gr.Blocks:
                     ],
                 )
 
+            with gr.Tab("Portfolio"):
+                gr.Markdown(
+                    "Cross-sectional strategies rank names against each other, so they get a "
+                    "harder null: we keep every date's gross exposure, net exposure and position "
+                    "count exactly as they were and randomise only **which name got which "
+                    "weight**. A book that beats that is picking names. One that doesn't was "
+                    "being paid for style exposure you can buy in an ETF — which the factor "
+                    "regression below measures directly."
+                )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        xs_symbols = gr.Textbox(
+                            value=", ".join(PORTFOLIO_UNIVERSE),
+                            label="Universe",
+                            lines=3,
+                            info="Comma-separated. At least 4 names — fewer cannot be ranked.",
+                        )
+                        with gr.Row():
+                            xs_start = gr.Textbox(value="2015-01-01", label="Start", scale=1)
+                            xs_end = gr.Textbox(value="", label="End", scale=1)
+
+                        xs_strategy = gr.Dropdown(
+                            choices=XS_STRATEGY_CHOICES, value="xs_momentum", label="Strategy"
+                        )
+                        xs_note = gr.Markdown(get_xs_strategy("xs_momentum").description)
+                        xs_sliders = [
+                            gr.Slider(label=f"Parameter {i + 1}", visible=False, minimum=0, maximum=100)
+                            for i in range(MAX_XS_PARAMS)
+                        ]
+                        xs_rebalance = gr.Radio(
+                            ["D", "W", "M", "Q"], value="M", label="Rebalance",
+                            info="Daily rebalancing of a real book is rarely affordable.",
+                        )
+
+                        with gr.Accordion("Costs, limits and testing", open=False):
+                            xs_commission = gr.Slider(0, 20, value=1, step=0.5, label="Commission (bps)")
+                            xs_slippage = gr.Slider(0, 50, value=2, step=0.5, label="Slippage (bps)")
+                            xs_short = gr.Checkbox(value=True, label="Allow short positions")
+                            xs_leverage = gr.Slider(0.1, 3.0, value=1.0, step=0.1, label="Gross leverage cap")
+                            xs_maxw = gr.Slider(0.0, 1.0, value=0.25, step=0.05, label="Max weight per name")
+                            xs_perms = gr.Slider(
+                                0, 500, value=150, step=25, label="Name shuffles",
+                            )
+
+                        xs_button = gr.Button("Run portfolio check", variant="primary", size="lg")
+
+                    with gr.Column(scale=2):
+                        xs_verdict = gr.HTML(
+                            '<div class="score-card"><div class="score-body">'
+                            "<h3>Nothing tested yet</h3><p>Pick a universe and a ranking rule, then "
+                            "hit <b>Run portfolio check</b>.</p></div></div>"
+                        )
+                        xs_tiles = gr.HTML("")
+
+                xs_perm_plot = gr.Plot(value=empty_figure("The name-shuffle test appears here.", height=320))
+                xs_equity_plot = gr.Plot(value=empty_figure())
+                with gr.Row():
+                    xs_attr_plot = gr.Plot(value=empty_figure(height=280))
+                    xs_weights_plot = gr.Plot(value=empty_figure(height=240))
+                xs_components_plot = gr.Plot(value=empty_figure(height=260))
+                xs_detail = gr.Markdown("")
+
+                xs_strategy.change(
+                    fn=xs_param_controls, inputs=xs_strategy, outputs=xs_sliders
+                ).then(
+                    fn=lambda k: get_xs_strategy(k).description, inputs=xs_strategy, outputs=xs_note
+                )
+                xs_button.click(
+                    fn=analyse_portfolio,
+                    inputs=[
+                        xs_symbols, xs_start, xs_end, xs_strategy, *xs_sliders,
+                        xs_rebalance, xs_commission, xs_slippage, xs_short,
+                        xs_leverage, xs_maxw, xs_perms,
+                    ],
+                    outputs=[
+                        xs_verdict, xs_tiles, xs_perm_plot, xs_equity_plot,
+                        xs_attr_plot, xs_weights_plot, xs_components_plot, xs_detail,
+                    ],
+                )
+
             with gr.Tab("Arena"):
                 gr.Markdown(
                     "Race every strategy on the same market, ranked by **evidence** rather than "
@@ -544,6 +833,7 @@ def build_app() -> gr.Blocks:
         )
 
         demo.load(fn=param_controls, inputs=strategy, outputs=param_sliders)
+        demo.load(fn=xs_param_controls, inputs=xs_strategy, outputs=xs_sliders)
 
     return demo
 

scripts/deploy_hf_space.sh

@@ -46,7 +46,8 @@ find ./algotrader -name '__pycache__' -type d -exec rm -rf {} + 2>/dev/null || t
 mkdir -p tests
 cp "$REPO_ROOT/tests/test_v2_engine.py" \
    "$REPO_ROOT/tests/test_v2_validation.py" \
-   "$REPO_ROOT/tests/test_v2_strategies.py" tests/
+   "$REPO_ROOT/tests/test_v2_strategies.py" \
+   "$REPO_ROOT/tests/test_v2_portfolio.py" tests/
 
 echo "==> Files staged:"
 find . -path ./.git -prune -o -type f -print | sed 's|^\./|  |'

tests/test_data_ingestion.py

@@ -132,7 +132,7 @@ class TestDataIngestion:
                 
                 assert isinstance(result, pd.DataFrame)
                 assert len(result) == len(sample_csv_data)
-                assert result['timestamp'].dtype == 'datetime64[ns]'
+                assert pd.api.types.is_datetime64_any_dtype(result['timestamp'])
                 
             finally:
                 os.unlink(tmp_file.name)
@@ -289,7 +289,7 @@ class TestDataIngestion:
                 result = _load_csv_data(config)
                 
                 # Check that timestamp is converted to datetime
-                assert result['timestamp'].dtype == 'datetime64[ns]'
+                assert pd.api.types.is_datetime64_any_dtype(result['timestamp'])
                 
             finally:
                 os.unlink(tmp_file.name)

tests/test_synthetic_data_generator.py

@@ -56,8 +56,8 @@ class TestSyntheticDataGenerator:
             assert col in df.columns
         
         # Check data types
-        assert df['timestamp'].dtype == 'datetime64[ns]'
-        assert df['symbol'].dtype == 'object'
+        assert pd.api.types.is_datetime64_any_dtype(df['timestamp'])
+        assert pd.api.types.is_string_dtype(df['symbol'])
         assert df['open'].dtype in ['float64', 'float32']
         assert df['high'].dtype in ['float64', 'float32']
         assert df['low'].dtype in ['float64', 'float32']

tests/test_v2_portfolio.py

@@ -0,0 +1,377 @@
+"""Multi-asset engine, panel, cross-sectional strategies and their null."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from algotrader.attribution import build_style_factors, factor_attribution
+from algotrader.cross_sectional import XS_REGISTRY, get_xs_strategy, scores_to_weights
+from algotrader.data import simulate_ohlcv
+from algotrader.engine import run_backtest
+from algotrader.panel import Panel, load_panel
+from algotrader.portfolio import (
+    normalise_weights,
+    rebalance_schedule,
+    run_portfolio_backtest,
+)
+from algotrader.types import CostModel
+from algotrader.validation.cross_permutation import (
+    cross_sectional_permutation_test,
+    permute_within_dates,
+)
+
+XS_KEYS = sorted(XS_REGISTRY)
+
+
+def make_panel(n_assets=8, n=1200, drift_sd=0.0, seed=1, common_vol=0.008, idio=0.012) -> Panel:
+    """A synthetic universe. ``drift_sd`` controls genuine cross-sectional structure."""
+    rng = np.random.default_rng(seed)
+    index = pd.date_range("2016-01-01", periods=n, freq="B")
+    drift = rng.normal(0, drift_sd, n_assets)
+    returns = (
+        rng.normal(0.0002, common_vol, n)[:, None]
+        + rng.normal(0, idio, (n, n_assets))
+        + drift[None, :]
+    )
+    close = 100 * np.exp(np.cumsum(returns, axis=0))
+    columns = [f"A{i}" for i in range(n_assets)]
+
+    def frame(values):
+        return pd.DataFrame(values, index=index, columns=columns)
+
+    return Panel(
+        fields={
+            "open": frame(close),
+            "high": frame(close * 1.004),
+            "low": frame(close * 0.996),
+            "close": frame(close),
+            "volume": frame(np.full_like(close, 1e6)),
+        },
+        sources={c: "synthetic" for c in columns},
+    )
+
+
+@pytest.fixture(scope="module")
+def panel() -> Panel:
+    return make_panel()
+
+
+class TestPanel:
+    def test_fields_are_aligned(self, panel):
+        assert panel.shape == (1200, 8)
+        for name in ("open", "high", "low", "close", "volume"):
+            assert panel.fields[name].index.equals(panel.index)
+            assert list(panel.fields[name].columns) == panel.symbols
+
+    def test_misaligned_fields_are_rejected(self, panel):
+        broken = dict(panel.fields)
+        broken["high"] = broken["high"].iloc[:-5]
+        with pytest.raises(ValueError, match="not aligned"):
+            Panel(fields=broken)
+
+    def test_missing_field_is_rejected(self, panel):
+        with pytest.raises(ValueError, match="missing field"):
+            Panel(fields={"close": panel.close})
+
+    def test_missing_data_is_not_forward_filled(self):
+        """Filling a gap invents liquidity that never existed."""
+        df = simulate_ohlcv("AAPL", "2018-01-01", "2022-01-01")
+        gapped = df.drop(df.index[100:140])
+        built = Panel.from_frames({"AAPL": gapped, "MSFT": df})
+        assert built.close["AAPL"].isna().sum() == 40
+
+    def test_tradable_requires_two_consecutive_prices(self, panel):
+        assert not panel.tradable().iloc[0].any()
+        assert panel.tradable().iloc[1:].all().all()
+
+    def test_returns_are_masked_where_untradable(self, panel):
+        assert panel.returns().iloc[0].isna().all()
+
+    def test_delisting_is_detected(self):
+        df = simulate_ohlcv("AAPL", "2016-01-01", "2022-01-01")
+        dead = df.iloc[: len(df) // 2]
+        built = Panel.from_frames({"ALIVE": df, "DEAD": dead})
+        report = built.survivorship()
+        assert report.n_delisted == 1
+        assert "DEAD" in report.delisted_symbols
+        assert not report.biased
+
+    def test_all_survivors_is_flagged_as_biased(self, panel):
+        report = panel.survivorship()
+        assert report.survival_rate == 1.0
+        assert report.biased
+        assert "upper bound" in report.note
+
+    def test_load_panel_skips_symbols_without_history(self):
+        built = load_panel(["SPY", "AAPL"], "2018-01-01", "2022-01-01", source="synthetic")
+        assert set(built.symbols) == {"SPY", "AAPL"}
+        assert all(s == "synthetic" for s in built.sources.values())
+
+    def test_select_and_slice(self, panel):
+        subset = panel.select(["A0", "A1"])
+        assert subset.symbols == ["A0", "A1"]
+        sliced = panel.slice(panel.index[10], panel.index[50])
+        assert len(sliced) == 41
+
+
+class TestPortfolioEngine:
+    def test_matches_single_asset_engine_exactly(self):
+        """One column through the matrix engine must equal the fast path."""
+        df = simulate_ohlcv("SPY", "2018-01-01", "2023-01-01")
+        single = Panel.from_frames({"SPY": df})
+        costs = CostModel(1, 2, 50)
+        n = len(df)
+        cases = {
+            "buy_and_hold": np.ones(n),
+            "flip": np.tile([1.0, -1.0], n // 2 + 1)[:n],
+            "long_flat": np.tile([1.0, 0.0], n // 2 + 1)[:n],
+            "fractional": np.full(n, 0.5),
+        }
+        for name, target in cases.items():
+            portfolio = run_portfolio_backtest(
+                single, pd.DataFrame({"SPY": target}, index=df.index), costs=costs
+            )
+            direct = run_backtest(df, pd.Series(target, index=df.index), costs=costs)
+            np.testing.assert_allclose(
+                portfolio.returns.to_numpy(), direct.returns.to_numpy(),
+                atol=1e-12, err_msg=f"mismatch for {name}",
+            )
+
+    def test_holding_still_costs_nothing_but_drift_does(self, panel):
+        """A full-notional long needs no rebalancing; a short does."""
+        costs = CostModel(10, 10, 0)
+        long_only = pd.DataFrame(1.0 / len(panel.symbols), index=panel.index, columns=panel.symbols)
+        result = run_portfolio_backtest(panel, long_only, costs=costs, gross_leverage=1.0)
+        # Equal-weight across many names still drifts apart, so turnover > 0...
+        assert result.metrics["turnover_ann"] > 0
+        # ...but a single full-notional position does not.
+        one = pd.DataFrame(0.0, index=panel.index, columns=panel.symbols)
+        one["A0"] = 1.0
+        assert run_portfolio_backtest(panel, one, costs=costs).costs.sum() == pytest.approx(
+            20 / 1e4, rel=1e-6
+        )
+
+    def test_rebalancing_less_often_lowers_turnover(self, panel):
+        weights = get_xs_strategy("equal_weight").generate(panel)
+        turnovers = []
+        for frequency in ("D", "M", "Q"):
+            result = run_portfolio_backtest(
+                panel, weights, costs=CostModel(1, 2, 0),
+                rebalance_on=rebalance_schedule(panel.index, frequency),
+            )
+            turnovers.append(result.metrics["turnover_ann"])
+        assert turnovers[0] > turnovers[1] > turnovers[2]
+
+    def test_gross_leverage_is_capped(self, panel):
+        weights = pd.DataFrame(1.0, index=panel.index, columns=panel.symbols)
+        result = run_portfolio_backtest(panel, weights, gross_leverage=1.0)
+        assert result.weights.abs().sum(axis=1).max() <= 1.0 + 1e-9
+
+    def test_leverage_is_scaled_down_never_up(self, panel):
+        small = pd.DataFrame(0.01, index=panel.index, columns=panel.symbols)
+        result = run_portfolio_backtest(panel, small, gross_leverage=1.0)
+        assert result.weights.abs().sum(axis=1).max() < 0.2
+
+    def test_per_name_cap_is_applied(self, panel):
+        weights = pd.DataFrame(0.0, index=panel.index, columns=panel.symbols)
+        weights["A0"] = 1.0
+        result = run_portfolio_backtest(panel, weights, max_weight=0.1)
+        assert result.weights.abs().max().max() <= 0.1 + 1e-9
+
+    def test_shorts_are_blocked_when_disallowed(self, panel):
+        weights = pd.DataFrame(-0.1, index=panel.index, columns=panel.symbols)
+        result = run_portfolio_backtest(panel, weights, allow_short=False)
+        assert (result.weights >= 0).all().all()
+
+    def test_delisted_names_cannot_be_held(self):
+        df = simulate_ohlcv("AAPL", "2016-01-01", "2022-01-01")
+        built = Panel.from_frames({"ALIVE": df, "DEAD": df.iloc[: len(df) // 2]})
+        weights = pd.DataFrame(0.5, index=built.index, columns=built.symbols)
+        result = run_portfolio_backtest(built, weights)
+        after_death = built.close["DEAD"].last_valid_index()
+        assert result.held.loc[result.held.index > after_death, "DEAD"].abs().max() == 0.0
+
+    def test_lag_zero_is_rejected(self, panel):
+        with pytest.raises(ValueError, match="lag"):
+            run_portfolio_backtest(panel, pd.DataFrame(0.1, index=panel.index, columns=panel.symbols), lag=0)
+
+    def test_future_bars_cannot_change_past_equity(self, panel):
+        weights = get_xs_strategy("xs_momentum").generate(panel)
+        full = run_portfolio_backtest(panel, weights)
+        cut = run_portfolio_backtest(
+            panel.slice(panel.index[0], panel.index[799]), weights.iloc[:800]
+        )
+        np.testing.assert_allclose(
+            full.equity.iloc[:800].to_numpy(), cut.equity.to_numpy(), rtol=1e-10
+        )
+
+    def test_attribution_sums_to_gross_return(self, panel):
+        weights = get_xs_strategy("equal_weight").generate(panel)
+        result = run_portfolio_backtest(panel, weights, costs=CostModel(0, 0, 0))
+        assert result.attribution().sum() == pytest.approx(result.gross_returns.sum(), rel=1e-9)
+
+    def test_portfolio_metrics_are_reported(self, panel):
+        result = run_portfolio_backtest(panel, get_xs_strategy("xs_momentum").generate(panel))
+        for key in ("gross_exposure", "net_exposure", "avg_positions", "concentration_hhi"):
+            assert key in result.metrics
+
+
+class TestCrossSectionalStrategies:
+    @pytest.mark.parametrize("key", XS_KEYS)
+    def test_weights_are_well_formed(self, panel, key):
+        weights = get_xs_strategy(key).generate(panel)
+        assert weights.shape == panel.shape
+        assert weights.notna().all().all()
+        assert weights.abs().sum(axis=1).max() <= 1.0 + 1e-9
+
+    @pytest.mark.parametrize("key", XS_KEYS)
+    def test_weights_are_causal(self, panel, key):
+        cut = 700
+        full = get_xs_strategy(key).generate(panel).iloc[:cut]
+        partial = get_xs_strategy(key).generate(panel.slice(panel.index[0], panel.index[cut - 1]))
+        pd.testing.assert_frame_equal(full, partial, rtol=1e-9)
+
+    def test_long_short_books_are_dollar_neutral(self, panel):
+        weights = get_xs_strategy("xs_momentum").generate(panel)
+        active = weights[weights.abs().sum(axis=1) > 1e-9]
+        assert active.sum(axis=1).abs().max() < 1e-9
+
+    def test_long_only_uses_the_whole_book(self):
+        scores = pd.DataFrame(np.arange(40).reshape(4, 10).astype(float))
+        weights = scores_to_weights(scores, long_frac=0.3, long_only=True)
+        assert weights.sum(axis=1).round(9).eq(1.0).all()
+        assert (weights >= 0).all().all()
+
+    def test_thin_cross_sections_are_skipped(self):
+        scores = pd.DataFrame(np.random.default_rng(0).normal(size=(10, 3)))
+        assert scores_to_weights(scores).abs().sum(axis=1).max() == 0.0
+
+    def test_equal_weight_holds_everything(self, panel):
+        weights = get_xs_strategy("equal_weight").generate(panel)
+        assert (weights.iloc[-1] > 0).all()
+
+    def test_unknown_strategy_names_alternatives(self):
+        with pytest.raises(KeyError, match="Available"):
+            get_xs_strategy("nope")
+
+
+class TestCrossSectionalNull:
+    def test_permutation_preserves_the_shape_of_the_book(self, panel):
+        weights = get_xs_strategy("xs_momentum").generate(panel)
+        investable = panel.close.notna()
+        shuffled = permute_within_dates(weights, investable, np.random.default_rng(0))
+
+        np.testing.assert_allclose(
+            np.sort(weights.to_numpy(), axis=1), np.sort(shuffled.to_numpy(), axis=1), atol=1e-12
+        )
+        np.testing.assert_allclose(
+            weights.abs().sum(axis=1).to_numpy(), shuffled.abs().sum(axis=1).to_numpy(), atol=1e-12
+        )
+        np.testing.assert_allclose(
+            weights.sum(axis=1).to_numpy(), shuffled.sum(axis=1).to_numpy(), atol=1e-12
+        )
+
+    def test_permutation_actually_reassigns(self, panel):
+        weights = get_xs_strategy("xs_momentum").generate(panel)
+        shuffled = permute_within_dates(weights, panel.close.notna(), np.random.default_rng(0))
+        assert not np.allclose(weights.to_numpy(), shuffled.to_numpy())
+
+    def test_non_investable_names_stay_empty(self):
+        df = simulate_ohlcv("AAPL", "2016-01-01", "2022-01-01")
+        built = Panel.from_frames({"ALIVE": df, "DEAD": df.iloc[: len(df) // 2]})
+        weights = pd.DataFrame(0.5, index=built.index, columns=built.symbols)
+        shuffled = permute_within_dates(weights, built.close.notna(), np.random.default_rng(1))
+        after_death = built.close["DEAD"].last_valid_index()
+        assert shuffled.loc[shuffled.index > after_death, "DEAD"].abs().max() == 0.0
+
+    def test_real_cross_sectional_skill_is_detected(self):
+        strong = make_panel(drift_sd=0.003, seed=11)
+        weights = get_xs_strategy("xs_momentum").generate(strong)
+        result = cross_sectional_permutation_test(
+            strong, weights, n_permutations=100,
+            rebalance_on=rebalance_schedule(strong.index, "M"), seed=2,
+        )
+        assert result.observed > result.null_mean
+        assert result.p_value < 0.05
+
+    def test_no_structure_is_not_significant(self):
+        flat = make_panel(drift_sd=0.0, seed=12)
+        weights = get_xs_strategy("xs_momentum").generate(flat)
+        result = cross_sectional_permutation_test(
+            flat, weights, n_permutations=100,
+            rebalance_on=rebalance_schedule(flat.index, "M"), seed=4,
+        )
+        assert result.p_value > 0.05
+
+    def test_p_value_can_never_be_zero(self, panel):
+        weights = get_xs_strategy("xs_momentum").generate(panel)
+        result = cross_sectional_permutation_test(panel, weights, n_permutations=20, seed=0)
+        assert result.p_value >= 1 / 21
+
+
+class TestAttribution:
+    def test_equal_weight_is_explained_by_the_market(self, panel):
+        factors = build_style_factors(panel)
+        weights = get_xs_strategy("equal_weight").generate(panel)
+        result = run_portfolio_backtest(panel, weights)
+        report = factor_attribution(result.returns, factors)
+
+        assert report["available"]
+        assert report["r_squared"] > 0.85
+        assert report["dominant_factor"] == "market"
+        assert not report["alpha_significant"]
+        assert "more cheaply" in report["note"]
+
+    def test_a_factor_regressed_on_itself_has_no_alpha(self, panel):
+        factors = build_style_factors(panel)
+        report = factor_attribution(factors["market"], factors)
+        assert abs(report["alpha_annual"]) < 0.05
+        assert report["r_squared"] > 0.99
+
+    def test_pure_noise_has_no_alpha_and_no_fit(self, panel):
+        rng = np.random.default_rng(5)
+        noise = pd.Series(rng.normal(0, 0.01, len(panel)), index=panel.index)
+        report = factor_attribution(noise, build_style_factors(panel))
+        assert not report["alpha_significant"]
+        assert report["r_squared"] < 0.2
+
+    def test_short_series_degrade_gracefully(self, panel):
+        factors = build_style_factors(panel)
+        report = factor_attribution(factors["market"].iloc[:20], factors)
+        assert not report["available"]
+        assert report["note"]
+
+
+class TestPortfolioLab:
+    def test_full_pipeline(self):
+        from algotrader.portfolio_lab import PortfolioLabConfig, run_portfolio_lab
+
+        report = run_portfolio_lab(
+            PortfolioLabConfig(
+                symbols=["SPY", "QQQ", "AAPL", "MSFT", "NVDA", "GLD"],
+                start="2017-01-01", end="2023-01-01", source="synthetic",
+                strategy="xs_momentum", n_permutations=20, wf_folds=2, grid_limit=6,
+            )
+        )
+        assert 0.0 <= report.verdict["score"] <= 100.0
+        assert report.verdict["grade"] in {"A", "B", "C", "D", "F"}
+        assert 0 < report.permutation.p_value <= 1
+        assert report.attribution["available"]
+        assert report.survivorship.n_symbols == 6
+        assert report.cost_stress["sharpe_3x"] <= report.cost_stress["sharpe_1x"] + 1e-9
+
+    def test_survivorship_bias_reaches_the_verdict(self):
+        from algotrader.portfolio_lab import PortfolioLabConfig, run_portfolio_lab
+
+        report = run_portfolio_lab(
+            PortfolioLabConfig(
+                symbols=["SPY", "QQQ", "AAPL", "MSFT", "NVDA", "GLD"],
+                start="2015-01-01", end="2023-01-01", source="synthetic",
+                strategy="equal_weight", n_permutations=0, wf_folds=2, grid_limit=3,
+            )
+        )
+        assert report.survivorship.biased
+        assert any("still trading" in f for f in report.verdict["flags"])
+        assert report.verdict["score"] <= 60