alphaverify 0.1.0__py3-none-any.whl

alphaverify/__init__.py

@@ -0,0 +1 @@
+"""Conditional barrier-touch probability pipeline."""

alphaverify/cli.py

@@ -0,0 +1,185 @@
+"""Command-line interface for the barrier-touch pipeline."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from alphaverify.domain import tensor_runtime
+from alphaverify.infrastructure.scaffold import available_templates, copy_workspace
+from alphaverify.infrastructure.workspace import (
+    STAGE_DIRECTORIES,
+    WORKSPACES_DIRNAME,
+    Workspace,
+    workspaces_root,
+)
+from alphaverify.pipeline.reporting import RULE, ansi_styles, color_enabled
+from alphaverify.pipeline.step_01_surface import cmd_surface
+from alphaverify.pipeline.step_02_shift import cmd_shift
+from alphaverify.pipeline.step_03_validation import cmd_validation
+from alphaverify.pipeline.step_04_selection import cmd_selection
+from alphaverify.pipeline.step_05_forecast import cmd_forecast
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    summary: str
+    handler: Callable[[Workspace], None]
+    stage: str
+
+
+COMMANDS = (
+    Command(
+        "measure",
+        "Measure raw conditional probabilities",
+        cmd_surface,
+        stage="surface",
+    ),
+    Command(
+        "compare",
+        "Compare raw probabilities to baseline",
+        cmd_shift,
+        stage="shift",
+    ),
+    Command(
+        "validate",
+        "Validate all eligible bins vs null",
+        cmd_validation,
+        stage="validation",
+    ),
+    Command(
+        "select",
+        "Select cleared bins and heatmaps",
+        cmd_selection,
+        stage="selection",
+    ),
+    Command(
+        "forecast",
+        "Cleared nodes and their forecast",
+        cmd_forecast,
+        stage="forecast",
+    ),
+)
+COMMAND_BY_NAME = {command.name: command for command in COMMANDS}
+
+# Setup, not a stage: it writes the workspace that the stage commands then read.
+INIT_COMMAND = "init"
+
+
+def overview(color: bool) -> str:
+    """Root help: setup, then the pipeline commands in order with their artifact directories."""
+    accent, bold, dim, reset = ansi_styles(color)
+
+    def heading(text: str) -> list[str]:
+        return [f"  {accent}{bold}{text}{reset}", ""]
+
+    def row(name: str, summary: str, target: str) -> str:
+        return (
+            f"    {bold}{name}{reset}{' ' * (12 - len(name))}"
+            f"{summary:<38}→ {dim}{target}{reset}"
+        )
+
+    lines = [
+        f"{accent}{RULE}{reset}",
+        "AlphaVerify",
+        "Conditional barrier-touch probability pipeline",
+        f"{accent}{RULE}{reset}",
+        "",
+        *heading("Setup"),
+        row(INIT_COMMAND, "Copy a shipped workspace here", f"{WORKSPACES_DIRNAME}/NAME/"),
+        "",
+        *heading("Pipeline"),
+    ]
+    for command in COMMANDS:
+        lines.append(row(command.name, command.summary, f"{STAGE_DIRECTORIES[command.stage]}/"))
+    lines += [
+        "",
+        *heading("Options"),
+        "    --workspace NAME        Select a workspace",
+        "    --workspaces-dir DIR    Workspace root (or $ALPHAVERIFY_WORKSPACES)",
+        "    --cuda                  Use CUDA numerical kernels",
+        "    -h, --help              Show this help",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+class RootParser(argparse.ArgumentParser):
+    """Root help is the command overview; subcommands keep argparse option help."""
+
+    def format_help(self) -> str:
+        return overview(color_enabled())
+
+
+def _add_workspace_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--workspace", metavar="NAME", default="nasdaq_daily")
+    parser.add_argument(
+        "--workspaces-dir",
+        metavar="DIR",
+        default=None,
+        help=(
+            "directory holding workspaces "
+            f"(default: $ALPHAVERIFY_WORKSPACES, else ./{WORKSPACES_DIRNAME})"
+        ),
+    )
+
+
+def _add_run_options(parser: argparse.ArgumentParser) -> None:
+    _add_workspace_options(parser)
+    parser.add_argument(
+        "--cuda",
+        action="store_true",
+        help="run numerical barrier kernels on CUDA (requires an available CUDA PyTorch device)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = RootParser(prog="alphaverify")
+    commands = parser.add_subparsers(
+        dest="command", metavar="COMMAND", parser_class=argparse.ArgumentParser
+    )
+
+    _add_workspace_options(
+        commands.add_parser(
+            INIT_COMMAND,
+            help=f"copy a shipped workspace ({', '.join(available_templates())}) into place",
+        )
+    )
+    for command in COMMANDS:
+        _add_run_options(commands.add_parser(command.name))
+    return parser
+
+
+def cmd_init(name: str, workspaces_dir: str | None) -> None:
+    """Write one shipped workspace declaration where the stage commands will look for it."""
+    root = workspaces_root(workspaces_dir)
+    written = copy_workspace(name, root)
+    accent, bold, dim, reset = ansi_styles(color_enabled())
+    print(f"\n{accent}{RULE}{reset}")
+    print(f"{accent}{bold}Workspace {name}{reset} → {root / name}")
+    print(f"{accent}{RULE}{reset}\n")
+    for path in written:
+        print(f"  {dim}{path.relative_to(root)}{reset}")
+    option = "" if root == Path.cwd() / WORKSPACES_DIRNAME else f" --workspaces-dir {root}"
+    print(f"\n  next: alphaverify measure --workspace {name}{option}\n")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return
+    if args.command == INIT_COMMAND:
+        cmd_init(args.workspace, args.workspaces_dir)
+        return
+    ws = Workspace(args.workspace, args.workspaces_dir)
+    tensor_runtime.configure(args.cuda)
+
+    COMMAND_BY_NAME[args.command].handler(ws)
+
+
+if __name__ == "__main__":
+    main()

alphaverify/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure numerical models and feature transforms."""

alphaverify/domain/barrier.py

@@ -0,0 +1,356 @@
+"""
+Barrier-touch surfaces: will price reach a signed barrier within a horizon?
+
+The engine's single measurement, shared by Stage 1 and by both validation roles.
+A barrier is touched by a later bar's low (negative barriers) or high (positive
+barriers), not its close; conditions are quantile bins of a feature. Why both
+choices were made: src/alphaverify/domain/README.md.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import torch
+from alphaverify.domain import tensor_runtime
+from alphaverify.domain.notation import MIN_BIN_N, MeasurementSlice, OhlcvComponent
+
+MEASUREMENT_VERSION = "shared-outcome-cache-float64-v2"
+
+
+def bin_edges(feature: pd.Series, n_bins: int) -> np.ndarray:
+    """
+    Interior quantile edges of the feature, so each bin holds ~1/n_bins of the sample.
+
+    Returns at most n_bins-1 edges. A feature with heavy ties -- an integer calendar
+    feature, or the constant used by the baseline node -- yields duplicate quantiles,
+    so the caller may get fewer bins than asked for. That is correct, not an error.
+
+    Assignment is searchsorted-left: values <= e enter the lower bin. Edges must
+    satisfy min(v) < e <= max(v), which removes phantom edges for constant
+    features; changing that filter changes stored bins and MEASUREMENT_VERSION.
+    A maximum-valued edge can leave an empty final bin; touch probabilities and
+    scoring exclude it through sample counts.
+    """
+    values = tensor_runtime.tensor(feature.to_numpy(float))[None, :]
+    edges = batched_bin_edges(values, n_bins)[0]
+    return edges[torch.isfinite(edges)].cpu().numpy()
+
+
+def batched_bin_edges(values: torch.Tensor, n_bins: int) -> torch.Tensor:
+    """Finite-value quantiles, deduplicated per path and padded with infinity."""
+    if n_bins < 1:
+        raise ValueError("n_bins must be positive")
+    if n_bins == 1:
+        return values.new_empty((values.shape[0], 0))
+    finite = torch.isfinite(values)
+    clean = torch.where(finite, values, float("nan"))
+    qs = torch.linspace(0, 1, n_bins + 1, dtype=values.dtype, device=values.device)[1:-1]
+    edges = torch.nanquantile(clean, qs, dim=1).T
+    lo = torch.where(finite, values, float("inf")).amin(dim=1, keepdim=True)
+    hi = torch.where(finite, values, float("-inf")).amax(dim=1, keepdim=True)
+    unique = torch.ones_like(edges, dtype=torch.bool)
+    unique[:, 1:] = edges[:, 1:] != edges[:, :-1]
+    valid = torch.isfinite(edges) & unique & (edges > lo) & (edges <= hi)
+    return torch.where(valid, edges, float("inf")).sort(dim=1).values.contiguous()
+
+
+def bin_indices(values: torch.Tensor, edges: torch.Tensor) -> torch.Tensor:
+    """The common left-boundary convention, including exact ties."""
+    return torch.searchsorted(edges.contiguous(), values.contiguous(), right=False)
+
+
+def price_eligibility(downside_excursion, upside_excursion):
+    """Bars whose forward window is fully observed: both excursions exist."""
+    return torch.isfinite(downside_excursion) & torch.isfinite(upside_excursion)
+
+
+def barrier_touch_matrix(downside_excursion, upside_excursion, barriers):
+    """Return the shared ``history × time × delta`` price-touch matrix."""
+    barriers_tensor = torch.as_tensor(
+        barriers, dtype=downside_excursion.dtype, device=downside_excursion.device
+    )
+    if barriers_tensor.ndim != 1:
+        raise ValueError("barriers must be a vector")
+    price_eligible = price_eligibility(downside_excursion, upside_excursion)
+    if not len(barriers_tensor):
+        empty = torch.empty(
+            (*downside_excursion.shape, 0), dtype=torch.bool,
+            device=downside_excursion.device,
+        )
+        return empty, price_eligible
+    barrier_axis = barriers_tensor.view(1, 1, -1)
+    touch_mask = torch.where(
+        barrier_axis < 0,
+        downside_excursion.unsqueeze(-1) <= barrier_axis,
+        upside_excursion.unsqueeze(-1) >= barrier_axis,
+    ) & price_eligible.unsqueeze(-1)
+    return touch_mask, price_eligible
+
+
+def reduce_touch_matrix(touch_mask, price_eligible, feature_values,
+                        bin_assignments, effective_bin_count):
+    """Reduce one shared touch matrix through a condition's bin assignment."""
+    condition_eligible = price_eligible & torch.isfinite(feature_values)
+    bin_observation_counts = feature_values.new_zeros(
+        (feature_values.shape[0], effective_bin_count)
+    )
+    bin_observation_counts.scatter_add_(
+        1, bin_assignments, condition_eligible.to(feature_values.dtype)
+    )
+    if touch_mask.shape[-1] == 0:
+        empty = feature_values.new_empty((feature_values.shape[0], 0, effective_bin_count))
+        return empty, empty.clone(), bin_observation_counts, condition_eligible.sum(dim=1)
+    bin_hit_counts = feature_values.new_zeros(
+        (feature_values.shape[0], effective_bin_count, touch_mask.shape[-1])
+    )
+    bin_hit_counts.scatter_add_(
+        1,
+        bin_assignments.unsqueeze(-1).expand(-1, -1, touch_mask.shape[-1]),
+        (touch_mask & condition_eligible.unsqueeze(-1)).to(feature_values.dtype),
+    )
+    conditional_probability = torch.where(
+        bin_observation_counts.unsqueeze(-1) >= MIN_BIN_N,
+        bin_hit_counts / bin_observation_counts.unsqueeze(-1).clamp_min(1),
+        float("nan"),
+    )
+    return (conditional_probability.transpose(1, 2), bin_hit_counts.transpose(1, 2),
+            bin_observation_counts, condition_eligible.sum(dim=1))
+
+
+def reduce_baseline_touch_matrix(touch_mask, price_eligible):
+    """Reduce a previously generated shared touch matrix to float64 baseline rates."""
+    eligible_observation_count = price_eligible.sum(dim=1).to(torch.float64)
+    if touch_mask.shape[-1] == 0:
+        empty = torch.empty(
+            (touch_mask.shape[0], 0), dtype=torch.float64, device=touch_mask.device
+        )
+        return empty, eligible_observation_count
+    hit_count = touch_mask.sum(dim=1).to(torch.float64)
+    return torch.where(
+        eligible_observation_count.unsqueeze(-1) >= MIN_BIN_N,
+        hit_count / eligible_observation_count.unsqueeze(-1).clamp_min(1),
+        float("nan"),
+    ), eligible_observation_count
+
+
+def bin_labels(edges: np.ndarray) -> list[str]:
+    """
+    One interval label per bin, written the way the condition reads:
+
+        x < 0.12          the lowest bin
+        0.12 < x < 0.34   an interior bin
+        0.34 < x          the highest bin
+
+    A single bin -- the baseline node's constant feature -- is labelled 'all'.
+    """
+    if len(edges) == 0:
+        return ['all']
+    out = [f'x < {edges[0]:.4g}']
+    for a, b in zip(edges[:-1], edges[1:]):
+        out.append(f'{a:.4g} < x < {b:.4g}')
+    out.append(f'{edges[-1]:.4g} < x')
+    return out
+
+
+def ohlcv_array(data: pd.DataFrame) -> np.ndarray:
+    """A history's ``(time, OHLCV)`` float64 array in canonical component order."""
+    return np.stack(
+        [data[component.name.lower()].to_numpy(float) for component in OhlcvComponent], axis=-1,
+    )
+
+
+def ohlcv_tensor(data: pd.DataFrame) -> torch.Tensor:
+    """Convert a stored history to one float64 path in canonical OHLCV order."""
+    return tensor_runtime.tensor(ohlcv_array(data)[None])
+
+
+def iter_extremes(paths: torch.Tensor, horizons):
+    """Shared incremental excursion ladder, yielding one horizon at a time."""
+    close = paths[:, :, OhlcvComponent.CLOSE]
+    low = paths[:, :, OhlcvComponent.LOW]
+    high = paths[:, :, OhlcvComponent.HIGH]
+    length = close.shape[1]
+    reached = 0
+    run_lo, run_hi = torch.full_like(close, float("inf")), torch.full_like(close, float("-inf"))
+    for horizon in horizons:
+        if horizon < reached:
+            run_lo.fill_(float("inf"))
+            run_hi.fill_(float("-inf"))
+            reached = 0
+        for offset in range(reached + 1, min(int(horizon), length - 1) + 1):
+            n = length - offset
+            run_lo[:, :n] = torch.minimum(run_lo[:, :n], low[:, offset:])
+            run_hi[:, :n] = torch.maximum(run_hi[:, :n], high[:, offset:])
+        reached = min(int(horizon), length - 1)
+        n = length - int(horizon)
+        lo, hi = torch.full_like(close, float("nan")), torch.full_like(close, float("nan"))
+        if n > 0:
+            lo[:, :n] = run_lo[:, :n] / close[:, :n] - 1.0
+            hi[:, :n] = run_hi[:, :n] / close[:, :n] - 1.0
+        yield lo, hi
+
+
+def forward_extremes_upto(data: pd.DataFrame, t_max: int) -> tuple[np.ndarray, np.ndarray]:
+    """Cache the common excursion ladder as (horizon, time) arrays for Stage 1."""
+    if t_max < 1:
+        raise ValueError("t_max must be positive")
+    rows = list(iter_extremes(ohlcv_tensor(data), range(1, t_max + 1)))
+    return tuple(torch.cat([row[i] for row in rows], dim=0).cpu().numpy() for i in (0, 1))
+
+
+def observed_outcomes(data: pd.DataFrame, barriers, horizons) -> dict:
+    """One history's excursion ladder, shared touch matrix, and baseline.
+
+    Every condition measured on the same history reuses these arrays; only its
+    bin reduction differs. Excursions have ``(horizon, time)`` axes up to the
+    largest horizon, touches ``(horizon, time, barrier)`` for the requested
+    horizons, and the baseline ``(barrier, horizon)``.
+    """
+    barriers = np.asarray(barriers, dtype=float)
+    horizons = np.asarray(horizons, dtype=int)
+    downside_excursion, upside_excursion = forward_extremes_upto(data, int(horizons.max()))
+    touch_mask, price_eligible = barrier_touch_matrix(
+        *_horizon_excursions(downside_excursion, upside_excursion, horizons), barriers,
+    )
+    baseline_probability, _ = reduce_baseline_touch_matrix(touch_mask, price_eligible)
+    return {
+        "downside_excursion": downside_excursion,
+        "upside_excursion": upside_excursion,
+        "touch_mask": touch_mask.cpu().numpy(),
+        "baseline_probability": baseline_probability.T.cpu().numpy(),
+    }
+
+
+def observed_price_eligibility(outcomes: dict, horizons) -> np.ndarray:
+    """``(horizon, time)`` price eligibility of ``observed_outcomes`` at the requested horizons."""
+    return price_eligibility(*_horizon_excursions(
+        outcomes["downside_excursion"], outcomes["upside_excursion"], horizons,
+    )).cpu().numpy()
+
+
+def _horizon_excursions(downside_excursion, upside_excursion, horizons):
+    """Rows of a ``(horizon, time)`` excursion ladder, which starts at horizon 1."""
+    rows = np.asarray(horizons, dtype=int) - 1
+    return tensor_runtime.tensor(downside_excursion[rows]), tensor_runtime.tensor(upside_excursion[rows])
+
+
+def measure_histories(paths, features, barriers, horizons, requested_bin_count, *,
+                      bin_edges=None, excursions=None,
+                      touch_mask=None, baseline_probability=None,
+                      bin_assignments=None):
+    """Return bin edges and an iterator of measured float64 horizon slices.
+
+    Paths have (history, time, OHLCV) axes. Features may have one row, shared
+    across histories, or one row per history. Without fixed edges, each history
+    receives its own quantiles. Probability slices have (history, barrier, bin,
+    1) axes. Each slice includes its own unconditional baseline, measured over
+    all eligible market dates independently of feature warm-up.
+    Stage 1 may supply its cached excursion ladder for a single history.
+    """
+    paths = tensor_runtime.tensor(paths)
+    x = tensor_runtime.tensor(features)
+    if paths.ndim != 3 or paths.shape[-1] != 5:
+        raise ValueError("paths must have (history, time, OHLCV) axes")
+    if x.ndim != 2 or x.shape[1] != paths.shape[1] or x.shape[0] not in (1, paths.shape[0]):
+        raise ValueError("features must match the path and time axes")
+    x = x.expand(paths.shape[:2])
+    barriers = np.asarray(barriers, dtype=float)
+    horizons = np.asarray(horizons, dtype=int)
+    if barriers.ndim != 1 or horizons.ndim != 1 or np.any(horizons < 1):
+        raise ValueError("barriers and horizons must be vectors, with positive horizons")
+    if bin_edges is None:
+        edges_t = batched_bin_edges(x, requested_bin_count)
+    else:
+        edges_t = tensor_runtime.tensor(bin_edges).expand(paths.shape[0], -1).contiguous()
+    effective_bin_count = edges_t.shape[1] + 1
+    indices = (bin_indices(x, edges_t) if bin_assignments is None else
+               torch.as_tensor(bin_assignments, dtype=torch.long, device=paths.device))
+    if indices.ndim == 1 and paths.shape[0] == 1:
+        indices = indices.unsqueeze(0)
+    if indices.shape != paths.shape[:2]:
+        raise ValueError("cached bin indices do not match path and time axes")
+    if excursions is not None:
+        expected = (int(horizons.max()) if len(horizons) else 0, paths.shape[1])
+        if paths.shape[0] != 1 or any(value.shape != expected for value in excursions):
+            raise ValueError("cached excursions do not match the requested data and horizon grid")
+        mins, maxs = (tensor_runtime.tensor(value) for value in excursions)
+        extremes = ((mins[t - 1][None], maxs[t - 1][None]) for t in horizons)
+    else:
+        extremes = iter_extremes(paths, horizons)
+    touches_t = (None if touch_mask is None else
+                 torch.as_tensor(touch_mask, dtype=torch.bool, device=paths.device))
+    if touches_t is not None:
+        if touches_t.ndim == 3 and paths.shape[0] == 1:
+            touches_t = touches_t.unsqueeze(1)
+        expected = (len(horizons), paths.shape[0], paths.shape[1], len(barriers))
+        if touches_t.shape != expected:
+            raise ValueError(f"cached touches do not match measurement axes: {touches_t.shape} vs {expected}")
+    baselines_t = None if baseline_probability is None else torch.as_tensor(
+        baseline_probability, dtype=paths.dtype, device=paths.device,
+    )
+    if baselines_t is not None:
+        if baselines_t.ndim == 2 and paths.shape[0] == 1:
+            baselines_t = baselines_t.unsqueeze(0)
+        expected = (paths.shape[0], len(barriers), len(horizons))
+        if baselines_t.shape != expected:
+            raise ValueError(f"cached baseline does not match measurement axes: {baselines_t.shape} vs {expected}")
+
+    def measurements():
+        for horizon_index, (lo, hi) in enumerate(extremes):
+            if touches_t is None:
+                shared_touch, price_ok = barrier_touch_matrix(lo, hi, barriers)
+            else:
+                shared_touch = touches_t[horizon_index]
+                price_ok = price_eligibility(lo, hi)
+            probabilities, hits, counts, observed = reduce_touch_matrix(
+                shared_touch, price_ok, x, indices, effective_bin_count,
+            )
+            baseline = (reduce_baseline_touch_matrix(shared_touch, price_ok)[0]
+                        if baselines_t is None else baselines_t[:, :, horizon_index])
+            yield MeasurementSlice(
+                conditional_probability=probabilities.unsqueeze(-1),
+                baseline_probability=baseline.unsqueeze(-1),
+                bin_hit_counts=hits.unsqueeze(-1),
+                bin_observation_counts=counts.unsqueeze(-1),
+                eligible_observation_count=observed.unsqueeze(-1),
+            )
+    return edges_t, measurements()
+
+
+def touch_tensor(data: pd.DataFrame, feature: pd.Series, horizons: np.ndarray,
+                 barriers: np.ndarray, bin_edges: np.ndarray,
+                 excursions: tuple[np.ndarray, np.ndarray] | None = None,
+                 touch_mask=None, baseline_probability=None) -> dict:
+    """Stage 1 adapter: collect the shared history measurements into one cube."""
+    _, measurements = measure_histories(
+        ohlcv_tensor(data), feature.to_numpy(float)[None], barriers, horizons,
+        len(bin_edges) + 1, bin_edges=bin_edges,
+        excursions=excursions, touch_mask=touch_mask,
+        baseline_probability=baseline_probability,
+    )
+    rows = list(measurements)
+    shape = (len(barriers), len(bin_edges) + 1, len(horizons))
+    result = {}
+    fields = (
+        ("conditional_probability", shape),
+        ("bin_hit_counts", shape),
+        ("bin_observation_counts", shape[1:]),
+        ("eligible_observation_count", shape[-1:]),
+    )
+    for field, empty_shape in fields:
+        values = (
+            torch.cat([getattr(row, field) for row in rows], dim=-1)[0].cpu().numpy()
+            if rows else np.empty(empty_shape)
+        )
+        result[field] = values if field == "conditional_probability" else values.astype(np.int32)
+    values = feature.to_numpy(float)
+    return {
+        **result,
+        "barriers": np.asarray(barriers, dtype=float),
+        "horizons": np.asarray(horizons, dtype=int),
+        "bin_edges": np.asarray(bin_edges, dtype=float),
+        "bin_assignments": np.searchsorted(
+            bin_edges, values, side="left"
+        ).astype(np.uint8),
+    }

alphaverify/domain/combination.py

@@ -0,0 +1,98 @@
+"""Combining active conditions into one barrier-touch surface, and checking it against history.
+
+Surfaces have ``(barrier, horizon)`` axes and observation counts ``(horizon,)``,
+matching one bin's face of a Stage 1 cube.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from alphaverify.domain.notation import MIN_BIN_N
+
+
+def smoothed_probability(hit_counts, observation_counts) -> np.ndarray:
+    """Laplace-smoothed touch rate ``(hits + 1) / (n + 2)``, strictly inside (0, 1)."""
+    return (np.asarray(hit_counts, dtype=float) + 1.0) / (
+        np.asarray(observation_counts, dtype=float) + 2.0
+    )
+
+
+def _log_odds(probability: np.ndarray) -> np.ndarray:
+    return np.log(probability) - np.log1p(-probability)
+
+
+def naive_bayes_probability(
+    baseline_hits, baseline_counts, condition_hits, condition_counts,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Per-cell naive Bayes combination of conditions in log-odds form.
+
+        logit P(touch | conditions) = logit P_baseline + sum_k (logit P_k - logit P_baseline)
+
+    Each condition contributes its odds ratio against the unconditional baseline,
+    as if conditions were independent given the outcome. Correlated conditions
+    therefore overstate the combined shift. Rates are smoothed before taking
+    log-odds. A cell's support is its weakest contributor: the fewest observations
+    at that horizon across the baseline and every condition. Returns the
+    ``(barrier, horizon)`` probability, NaN below ``MIN_BIN_N`` support, and the
+    ``(horizon,)`` support counts. With no conditions the result is the smoothed baseline.
+    """
+    baseline_hits = np.asarray(baseline_hits, dtype=float)
+    baseline_counts = np.asarray(baseline_counts, dtype=float)
+    if baseline_hits.ndim != 2 or baseline_counts.shape != baseline_hits.shape[1:]:
+        raise ValueError("baseline hits must be (barrier, horizon) with (horizon,) counts")
+    baseline = _log_odds(smoothed_probability(baseline_hits, baseline_counts[None, :]))
+    log_odds = baseline.copy()
+    support = baseline_counts.copy()
+    for hits, counts in zip(condition_hits, condition_counts, strict=True):
+        hits = np.asarray(hits, dtype=float)
+        counts = np.asarray(counts, dtype=float)
+        if hits.shape != baseline_hits.shape or counts.shape != baseline_counts.shape:
+            raise ValueError("condition surfaces must match the baseline axes")
+        log_odds += _log_odds(smoothed_probability(hits, counts[None, :])) - baseline
+        support = np.minimum(support, counts)
+    probability = np.where(support[None, :] >= MIN_BIN_N, 1.0 / (1.0 + np.exp(-log_odds)), np.nan)
+    return probability, support
+
+
+def joint_touch_rate(
+    condition_holds, touch_mask, price_eligible,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Historical touch rate on the bars where every condition held at once.
+
+    ``condition_holds`` is ``(time,)``; ``touch_mask`` is the shared
+    ``(horizon, time, barrier)`` matrix and ``price_eligible`` its
+    ``(horizon, time)`` forward-window support. Returns the ``(barrier, horizon)``
+    rate, NaN below ``MIN_BIN_N`` joint observations, and the ``(horizon,)`` counts.
+    This is the same unsmoothed estimate Stage 1 reports for a single condition.
+    """
+    holds = np.asarray(condition_holds, dtype=bool)
+    touch_mask = np.asarray(touch_mask, dtype=bool)
+    eligible = np.asarray(price_eligible, dtype=bool) & holds[None, :]
+    if touch_mask.shape[:2] != eligible.shape:
+        raise ValueError("touches, eligibility, and condition must share horizon and time axes")
+    counts = eligible.sum(axis=1)
+    hits = (touch_mask & eligible[:, :, None]).sum(axis=1).T
+    rate = np.where(counts[None, :] >= MIN_BIN_N, hits / np.maximum(counts[None, :], 1), np.nan)
+    return rate, counts
+
+
+def nesting_violations(probability, barriers, horizons) -> int:
+    """Adjacent cells that break the ordering implied by nested touch events.
+
+    Reaching a farther barrier implies reaching a nearer one on the same side, and a
+    longer horizon contains a shorter one. Probability must not rise with barrier
+    distance or fall with horizon. Unsupported (NaN) cells are ignored.
+    """
+    tolerance = 1e-12
+    probability = np.asarray(probability, dtype=float)
+    barriers = np.asarray(barriers, dtype=float)
+    probability = probability[np.argsort(barriers)][:, np.argsort(np.asarray(horizons))]
+    ordered = np.sort(barriers)
+    downside, upside = probability[ordered < 0], probability[ordered >= 0]
+    with np.errstate(invalid="ignore"):
+        return int(
+            (np.diff(downside, axis=0) < -tolerance).sum()
+            + (np.diff(upside, axis=0) > tolerance).sum()
+            + (np.diff(probability, axis=1) < -tolerance).sum()
+        )