trail-lang 0.1.0__py3-none-any.whl

trail/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

trail/ast.py

@@ -0,0 +1,173 @@
+"""Typed AST for Trail. All nodes are frozen dataclasses compared by value."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Literal:
+    value: float | int | str | bool
+
+
+@dataclass(frozen=True)
+class NameRef:
+    name: str
+
+
+@dataclass(frozen=True)
+class FieldRef:
+    path: tuple[str, ...]
+    source: str | None = None
+
+    @property
+    def column(self) -> str:
+        return ".".join(self.path)
+
+
+@dataclass(frozen=True)
+class BinOp:
+    op: str  # add sub mul div mod pow
+    left: "Expr"
+    right: "Expr"
+
+
+@dataclass(frozen=True)
+class Compare:
+    op: str  # eq ne gt lt ge le
+    left: "Expr"
+    right: "Expr"
+
+
+@dataclass(frozen=True)
+class In:
+    item: "Expr"
+    options: tuple[Literal, ...]
+
+
+@dataclass(frozen=True)
+class BoolOp:
+    op: str  # and or
+    left: "Expr"
+    right: "Expr"
+
+
+@dataclass(frozen=True)
+class Not:
+    operand: "Expr"
+
+
+@dataclass(frozen=True)
+class Neg:
+    operand: "Expr"
+
+
+@dataclass(frozen=True)
+class Coalesce:
+    left: "Expr"
+    right: "Expr"
+
+
+@dataclass(frozen=True)
+class Ternary:
+    value: "Expr"
+    cond: "Expr"
+    orelse: "Expr"
+
+
+@dataclass(frozen=True)
+class Call:
+    name: str
+    args: tuple["Expr", ...]
+    kwargs: tuple[tuple[str, "Expr"], ...] = field(default=())
+    by: tuple[str, ...] | None = None
+
+
+# --- declaration nodes (Task 3) ---
+
+
+@dataclass(frozen=True)
+class Assignment:
+    name: str
+    expr: "Expr"
+    export: bool = False
+
+
+@dataclass(frozen=True)
+class ScoreCase:
+    value: "Expr"
+    cond: "Expr"
+
+
+@dataclass(frozen=True)
+class ScoreDecl:
+    name: str
+    weight: float
+    cases: tuple[ScoreCase, ...]
+    default: "Expr"
+
+
+@dataclass(frozen=True)
+class UniverseDecl:
+    name: str
+    root: tuple[str, ...]
+    where: "Expr | None" = None
+
+
+@dataclass(frozen=True)
+class ModelDecl:
+    name: str
+    universe: str | None
+    period: str
+    desc: str | None
+    on_missing: str
+    statements: tuple["Assignment | ScoreDecl", ...]
+
+
+@dataclass(frozen=True)
+class SignalDecl:
+    name: str
+    universe: str | None
+    period: str
+    expr: "Expr"
+
+
+@dataclass(frozen=True)
+class OpaqueDecl:
+    kind: str  # strategy | backtest | learn | import
+    name: str
+    text: str = ""
+
+
+@dataclass(frozen=True)
+class FuncDef:
+    """A user/stdlib function: a non-recursive expression macro over its parameters."""
+
+    name: str
+    params: tuple[str, ...]
+    body: "Expr"
+
+
+@dataclass(frozen=True)
+class Program:
+    decls: tuple[object, ...]
+
+
+# --- REPL-dialect meta-commands (never valid in a model file; see reference §2.1) ---
+
+
+@dataclass(frozen=True)
+class MetaCatalog:
+    """`?` - the full catalog summary."""
+
+
+@dataclass(frozen=True)
+class MetaDescribe:
+    """`?<target>` - describe a namespace, field, function, or source
+    (targets `functions` / `sources` list those categories)."""
+
+    target: tuple[str, ...]
+
+
+Expr = (
+    Literal | NameRef | FieldRef | BinOp | Compare | In | BoolOp | Not | Neg | Coalesce | Ternary | Call
+)

trail/catalog.py

@@ -0,0 +1,245 @@
+"""Discovery core: catalog / describe over the schema, function, and source registries.
+
+Shared engine behind every discovery front-end (REPL `?` meta-commands, the `trail
+catalog` CLI, and - later - MCP tools and Jupyter magics). Returns CatalogResult (a
+titled metadata table), never a panel: discovery is metadata, not computation.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+
+import polars as pl
+
+from trail import ast
+from trail.config import DEFAULT_CONFIG, Config
+from trail.schema import SCHEMA
+from trail.validate import KNOWN_FUNCTIONS
+
+
+@lru_cache(maxsize=1)
+def _stdlib_functions() -> dict[str, int]:
+    """Bundled stdlib macro name -> parameter count (the derived layer). Internal
+    helpers (names starting with '_') are hidden from discovery."""
+    from trail.library import stdlib_source
+    from trail.macro import collect_functions
+    from trail.parser import parse_program
+
+    funcs = collect_functions(parse_program(stdlib_source()))
+    return {name: len(fd.params) for name, fd in funcs.items() if not name.startswith("_")}
+
+# function -> (axis, one-line summary). Axis mirrors reference §7.
+_FUNC_META: dict[str, tuple[str, str]] = {
+    "lag": ("time-series", "value n periods earlier (per security)"),
+    "roll_mean": ("time-series", "rolling mean over n periods"),
+    "roll_sum": ("time-series", "rolling sum over n periods"),
+    "roll_std": ("time-series", "rolling sample std (ddof=1) over n periods"),
+    "roll_var": ("time-series", "rolling sample variance over n periods"),
+    "roll_max": ("time-series", "rolling max over n periods"),
+    "roll_min": ("time-series", "rolling min over n periods"),
+    "roll_quantile": ("time-series", "rolling q-quantile (historical VaR)"),
+    "cummax": ("time-series", "expanding maximum"),
+    "cumsum": ("time-series", "expanding sum (discrete integral)"),
+    "cumprod": ("time-series", "expanding product (compounding)"),
+    "cummin": ("time-series", "expanding minimum"),
+    "roll_median": ("time-series", "rolling median over n periods"),
+    "roll_skew": ("time-series", "rolling skewness over n periods"),
+    "ewm_mean": ("time-series", "exponentially-weighted mean (span)"),
+    "ewm_std": ("time-series", "exponentially-weighted std (span)"),
+    "decay_linear": ("time-series", "linearly-decayed weighted mean over n periods"),
+    "zscore": ("cross-sectional", "standardize within (period[, group])"),
+    "rank": ("cross-sectional", "average-tie rank, ascending, within group"),
+    "winsorize": ("cross-sectional", "clip to [p, 1-p] group quantiles"),
+    "xs_mean": ("cross-sectional", "group mean, broadcast back to members"),
+    "xs_median": ("cross-sectional", "group median, broadcast back"),
+    "xs_sum": ("cross-sectional", "group sum, broadcast back"),
+    "xs_frac": ("cross-sectional", "fraction of group where cond is true"),
+    "xs_std": ("cross-sectional", "group sample std (ddof=1)"),
+    "xs_var": ("cross-sectional", "group sample variance"),
+    "xs_min": ("cross-sectional", "group minimum, broadcast back"),
+    "xs_max": ("cross-sectional", "group maximum, broadcast back"),
+    "xs_count": ("cross-sectional", "non-null count in group"),
+    "xs_quantile": ("cross-sectional", "group q-quantile, broadcast back"),
+    "count": ("elementwise", "sum of boolean flags as integers"),
+    "sqrt": ("elementwise", "square root (null for x<0)"),
+    "abs": ("elementwise", "absolute value"),
+    "log": ("elementwise", "natural log (null for x<=0)"),
+    "exp": ("elementwise", "e ** x"),
+    "sin": ("elementwise", "sine (radians)"),
+    "cos": ("elementwise", "cosine (radians)"),
+    "tan": ("elementwise", "tangent (radians)"),
+    "asin": ("elementwise", "arcsine"),
+    "acos": ("elementwise", "arccosine"),
+    "atan": ("elementwise", "arctangent"),
+    "floor": ("elementwise", "round down to integer"),
+    "ceil": ("elementwise", "round up to integer"),
+    "round": ("elementwise", "round to nearest integer"),
+    "clamp": ("elementwise", "clip x to [lo, hi]"),
+    "min": ("elementwise", "cell-wise min of two panels"),
+    "max": ("elementwise", "cell-wise max of two panels"),
+    "weighted_score": ("model", "weighted rollup of the model's score blocks"),
+}
+
+
+@dataclass(frozen=True)
+class CatalogResult:
+    """A titled metadata table. Renders in a terminal (str) and in Jupyter (_repr_html_)."""
+
+    title: str
+    frame: pl.DataFrame
+
+    def __str__(self) -> str:
+        return f"{self.title}\n{self.frame}"
+
+    def _repr_html_(self) -> str:  # Jupyter rich display
+        return f"<strong>{self.title}</strong>{self.frame._repr_html_()}"
+
+
+def namespaces() -> list[str]:
+    return sorted({c.split(".", 1)[0] for c in SCHEMA})
+
+
+def fields(namespace: str | None = None) -> CatalogResult:
+    items = [
+        (c, spec.kind) for c, spec in SCHEMA.items()
+        if namespace is None or c.split(".", 1)[0] == namespace
+    ]
+    frame = pl.DataFrame({"field": [c for c, _ in items], "kind": [k for _, k in items]}).sort("field")
+    title = f"Fields in '{namespace}' ({frame.height})" if namespace else f"All fields ({frame.height})"
+    return CatalogResult(title, frame)
+
+
+def functions() -> CatalogResult:
+    rows = {"function": [], "layer": [], "axis": [], "args": [], "summary": []}
+    for n in sorted(KNOWN_FUNCTIONS):
+        lo, hi = KNOWN_FUNCTIONS[n]
+        axis, summary = _FUNC_META.get(n, ("", ""))
+        rows["function"].append(n)
+        rows["layer"].append("primitive")
+        rows["axis"].append(axis)
+        rows["args"].append(str(lo) if lo == hi else f"{lo}..{hi}")
+        rows["summary"].append(summary)
+    std = _stdlib_functions()
+    for n in sorted(std):
+        rows["function"].append(n)
+        rows["layer"].append("derived")
+        rows["axis"].append("")
+        rows["args"].append(str(std[n]))
+        rows["summary"].append("stdlib macro")
+    return CatalogResult(f"Functions ({len(KNOWN_FUNCTIONS)} primitive + {len(std)} derived)",
+                         pl.DataFrame(rows))
+
+
+def sources(config: Config = DEFAULT_CONFIG) -> CatalogResult:
+    names = sorted(config.sources)
+    frame = pl.DataFrame({
+        "source": names,
+        "driver": [config.sources[n].driver for n in names],
+    })
+    precedence = ", ".join(f"{ns}=[{', '.join(chain)}]" for ns, chain in config.precedence.items())
+    return CatalogResult(f"Sources ({len(names)}) | precedence: {precedence}", frame)
+
+
+def _kv(title: str, pairs: list[tuple[str, str]]) -> CatalogResult:
+    frame = pl.DataFrame({"property": [k for k, _ in pairs], "value": [v for _, v in pairs]})
+    return CatalogResult(title, frame)
+
+
+def _source_detail(name: str, spec) -> CatalogResult:
+    """Source metadata plus a best-effort coverage view for a discoverable source.
+
+    Instantiating a source can fail (e.g. a missing credential); that is reported
+    inline rather than raised, so discovery stays usable without a live connection.
+    """
+    from trail.registry import resolve_driver
+    from trail.source import SupportsCapabilities, SupportsDiscovery
+
+    rows: list[tuple[str, str]] = [("driver", spec.driver), ("options", str(spec.options))]
+    try:
+        src = resolve_driver(spec.driver)(spec.options)
+    except Exception as e:  # instantiation/credential failure: report, do not raise
+        rows.append(("discovery", f"unavailable ({e})"))
+        return _kv(f"Source {name}", rows)
+    try:
+        if isinstance(src, SupportsCapabilities):
+            caps = src.capabilities()
+            rows.append(("frequency", caps.frequency))
+            if caps.period_range:
+                rows.append(("period_range", f"{caps.period_range[0]}..{caps.period_range[1]}"))
+            if caps.provenance:
+                rows.append(("provenance", caps.provenance))
+        if isinstance(src, SupportsDiscovery):
+            all_fields = set(SCHEMA)
+            avail = src.available_fields()
+            rows.append(("provides", f"{len(avail & all_fields)}/{len(all_fields)} schema fields"))
+            missing = sorted(all_fields - avail)
+            if missing:
+                rows.append(("unavailable_fields", ", ".join(missing)))
+        else:
+            rows.append(("discovery", "not supported (core-tier source)"))
+    finally:
+        try:
+            src.close()
+        except Exception:
+            pass
+    return _kv(f"Source {name}", rows)
+
+
+def describe(target: tuple[str, ...], config: Config = DEFAULT_CONFIG) -> CatalogResult:
+    dotted = ".".join(target)
+    # category list-alls
+    if target == ("functions",):
+        return functions()
+    if target == ("sources",):
+        return sources(config)
+    if target == ("fields",):
+        return fields()
+    # a specific field (dotted path in the schema)
+    if dotted in SCHEMA:
+        return _kv(f"Field {dotted}", [("column", dotted), ("kind", SCHEMA[dotted].kind)])
+    # a namespace
+    if len(target) == 1 and target[0] in namespaces():
+        return fields(target[0])
+    # a primitive function
+    if len(target) == 1 and target[0] in KNOWN_FUNCTIONS:
+        lo, hi = KNOWN_FUNCTIONS[target[0]]
+        axis, summary = _FUNC_META.get(target[0], ("", ""))
+        return _kv(f"Function {target[0]}", [
+            ("layer", "primitive"), ("axis", axis),
+            ("args", str(lo) if lo == hi else f"{lo}..{hi}"), ("summary", summary),
+        ])
+    # a derived (stdlib macro) function
+    if len(target) == 1 and target[0] in _stdlib_functions():
+        return _kv(f"Function {target[0]}", [
+            ("layer", "derived"), ("args", str(_stdlib_functions()[target[0]])),
+            ("kind", "stdlib macro"),
+        ])
+    # a source
+    if len(target) == 1 and target[0] in config.sources:
+        return _source_detail(target[0], config.sources[target[0]])
+    return CatalogResult(
+        f"Unknown catalog target: '{dotted}'",
+        pl.DataFrame({"hint": ["try ? , ?fields, ?functions, ?sources, or ?<namespace>"]}),
+    )
+
+
+def catalog(config: Config = DEFAULT_CONFIG) -> CatalogResult:
+    ns = namespaces()
+    frame = pl.DataFrame({
+        "namespace": ns,
+        "fields": [len(fields(n).frame) for n in ns],
+    })
+    title = (f"Trail catalog - {len(SCHEMA)} fields across {len(ns)} namespaces, "
+             f"{len(KNOWN_FUNCTIONS)} primitive + {len(_stdlib_functions())} derived functions, "
+             f"{len(config.sources)} source(s). Use ?<namespace>, ?functions, ?sources, ?<name> for detail.")
+    return CatalogResult(title, frame)
+
+
+def evaluate_meta(node, config: Config = DEFAULT_CONFIG) -> CatalogResult:
+    """Route a parsed meta-command AST node to the discovery core."""
+    match node:
+        case ast.MetaCatalog():
+            return catalog(config)
+        case ast.MetaDescribe():
+            return describe(node.target, config)
+    raise TypeError(f"not a meta-command: {type(node).__name__}")

trail/cli.py

@@ -0,0 +1,102 @@
+"""Trail command line: validate and run .trail files (fixture-backed in this phase)."""
+from __future__ import annotations
+
+import sys
+import warnings
+
+import click
+from lark.exceptions import UnexpectedInput
+
+from trail import ast, catalog as catalog_core
+from trail.compiler import compile_model
+from trail.config import ConfigError, load_config
+from trail.deps import extract
+from trail.macro import TrailFunctionError
+from trail.pipeline import prepare
+from trail.sources import PanelConformanceWarning, load_panel_for
+from trail.validate import validate
+
+
+@click.group()
+def main() -> None:
+    """Trail - financial expression language."""
+
+
+def _load_and_validate(path: str, with_stdlib: bool = True) -> ast.Program:
+    with open(path) as fh:
+        src = fh.read()
+    try:
+        program = prepare(src, stdlib=with_stdlib)  # prepend stdlib, parse, inline defs
+    except UnexpectedInput as e:
+        tok = getattr(e, "token", None)
+        detail = f": unexpected {str(tok)!r}" if tok else ""
+        click.echo(f"ERROR SYNTAX at line {e.line}, column {e.column}{detail}")
+        sys.exit(1)
+    except TrailFunctionError as e:
+        click.echo(f"ERROR FUNC {e}")
+        sys.exit(1)
+    issues = validate(program)
+    for i in issues:
+        click.echo(f"{'ERROR' if i.severity == 'error' else 'WARN '} {i.code} {i.message}")
+    if any(i.severity == "error" for i in issues):
+        sys.exit(1)
+    return program
+
+
+@main.command("validate")
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--no-stdlib", is_flag=True, help="Do not load the bundled standard library.")
+def validate_cmd(path: str, no_stdlib: bool) -> None:
+    _load_and_validate(path, with_stdlib=not no_stdlib)
+    click.echo("OK")
+
+
+@main.command("catalog")
+@click.argument("target", required=False)
+@click.option("--config", "config_path", default=None, type=click.Path(exists=True))
+def catalog_cmd(target: str | None, config_path: str | None) -> None:
+    """Discover fields, functions, and sources. TARGET is a namespace, field,
+    function, source, or one of: fields, functions, sources. Same discovery core
+    as the REPL `?` meta-command."""
+    try:
+        config = load_config(config_path)
+    except ConfigError as e:
+        click.echo(f"ERROR CONFIG {e}")
+        sys.exit(1)
+    if target is None:
+        result = catalog_core.catalog(config)
+    else:
+        result = catalog_core.describe(tuple(target.split(".")), config)
+    click.echo(str(result))
+
+
+@main.command("run")
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--model", "model_name", required=True)
+@click.option("--config", "config_path", default=None, type=click.Path(exists=True))
+@click.option("--no-stdlib", is_flag=True, help="Do not load the bundled standard library.")
+@click.option("--out", "out_path", default=None, type=click.Path())
+def run_cmd(path: str, model_name: str, config_path: str | None, no_stdlib: bool, out_path: str | None) -> None:
+    program = _load_and_validate(path, with_stdlib=not no_stdlib)
+    try:
+        config = load_config(config_path)
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", PanelConformanceWarning)
+            panel = load_panel_for(config, set(extract(program).fields))
+        for w in caught:
+            if issubclass(w.category, PanelConformanceWarning):
+                click.echo(f"WARN  {w.message}")
+    except ConfigError as e:
+        click.echo(f"ERROR CONFIG {e}")
+        sys.exit(1)
+    universes = {d.name: d for d in program.decls if isinstance(d, ast.UniverseDecl)}
+    models = {d.name: d for d in program.decls if isinstance(d, ast.ModelDecl)}
+    if model_name not in models:
+        click.echo(f"ERROR no model named '{model_name}'")
+        sys.exit(1)
+    result = compile_model(models[model_name], universes).run(panel)
+    if out_path:
+        result.write_parquet(out_path)
+        click.echo(f"wrote {out_path}")
+    else:
+        click.echo(str(result))

trail/compiler.py

@@ -0,0 +1,140 @@
+"""Lower AST to Polars expressions and executable model plans."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import polars as pl
+
+from trail import ast
+from trail.ops import PERIOD, SEC, build, safe_div
+
+_BIN = {
+    "add": lambda x, y: x + y, "sub": lambda x, y: x - y, "mul": lambda x, y: x * y,
+    "mod": lambda x, y: x % y, "pow": lambda x, y: x.pow(y),
+}
+_CMP = {
+    "eq": lambda x, y: x == y, "ne": lambda x, y: x != y, "gt": lambda x, y: x > y,
+    "lt": lambda x, y: x < y, "ge": lambda x, y: x >= y, "le": lambda x, y: x <= y,
+}
+
+
+def compile_expr(e: ast.Expr, defined: set[str]) -> pl.Expr:
+    match e:
+        case ast.Literal():
+            return pl.lit(e.value)
+        case ast.NameRef():
+            return pl.col(e.name)
+        case ast.FieldRef():
+            return pl.col(e.column)
+        case ast.BinOp() if e.op == "div":
+            return safe_div(compile_expr(e.left, defined), compile_expr(e.right, defined))
+        case ast.BinOp():
+            return _BIN[e.op](compile_expr(e.left, defined), compile_expr(e.right, defined))
+        case ast.Compare():
+            return _CMP[e.op](compile_expr(e.left, defined), compile_expr(e.right, defined))
+        case ast.In():
+            return compile_expr(e.item, defined).is_in([o.value for o in e.options])
+        case ast.BoolOp() if e.op == "and":
+            return compile_expr(e.left, defined) & compile_expr(e.right, defined)
+        case ast.BoolOp():
+            return compile_expr(e.left, defined) | compile_expr(e.right, defined)
+        case ast.Not():
+            return ~compile_expr(e.operand, defined)
+        case ast.Neg():
+            return -compile_expr(e.operand, defined)
+        case ast.Coalesce():
+            return pl.coalesce([compile_expr(e.left, defined), compile_expr(e.right, defined)])
+        case ast.Ternary():
+            return (pl.when(compile_expr(e.cond, defined))
+                    .then(compile_expr(e.value, defined))
+                    .otherwise(compile_expr(e.orelse, defined)))
+        case ast.Call():
+            args = [_call_arg(a, defined) for a in e.args]
+            kwargs = {k: _call_arg(v, defined) for k, v in e.kwargs}
+            return build(e.name, args, kwargs, e.by)
+    raise TypeError(f"cannot compile {type(e).__name__}")
+
+
+def _call_arg(a: ast.Expr, defined: set[str]):
+    # numeric literals pass through as python numbers (window sizes, quantiles)
+    if isinstance(a, ast.Literal) and isinstance(a.value, (int, float)) and not isinstance(a.value, bool):
+        return a.value
+    return compile_expr(a, defined)
+
+
+def _score_expr(sd: ast.ScoreDecl, defined: set[str]) -> pl.Expr:
+    """First-match-wins cases. Null iff every condition is null (all inputs missing),
+    which is what makes `on_missing skip` renormalization meaningful (reference §4.3/§7.5)."""
+    conds = [compile_expr(c.cond, defined) for c in sd.cases]
+    node = pl.when(conds[0]).then(compile_expr(sd.cases[0].value, defined))
+    for cond, case in zip(conds[1:], sd.cases[1:], strict=True):
+        node = node.when(cond).then(compile_expr(case.value, defined))
+    normal = node.otherwise(compile_expr(sd.default, defined)).cast(pl.Float64)
+    all_null = conds[0].is_null()
+    for cond in conds[1:]:
+        all_null = all_null & cond.is_null()
+    return pl.when(all_null).then(pl.lit(None, dtype=pl.Float64)).otherwise(normal)
+
+
+def _score_max(sd: ast.ScoreDecl) -> float:
+    return float(max([c.value.value for c in sd.cases] + [sd.default.value]))
+
+
+def _weighted_score(scores: list[ast.ScoreDecl], on_missing: str) -> pl.Expr:
+    num = pl.lit(0.0)
+    den = pl.lit(0.0)
+    for sd in scores:
+        s = pl.col(sd.name)
+        w, mx = sd.weight, _score_max(sd)
+        num = num + pl.coalesce([s * w, pl.lit(0.0)])
+        if on_missing == "zero":
+            den = den + pl.lit(w * mx)
+        else:  # skip (median compiles like skip this phase)
+            den = den + pl.when(s.is_not_null()).then(w * mx).otherwise(0.0)
+    return safe_div(num, den)
+
+
+def _is_weighted_score(expr: ast.Expr) -> bool:
+    return isinstance(expr, ast.Call) and expr.name == "weighted_score"
+
+
+@dataclass
+class ModelPlan:
+    _lf_builder: Callable[[pl.DataFrame], pl.LazyFrame]
+    exports: tuple[str, ...]
+
+    def run(self, panel: pl.DataFrame) -> pl.DataFrame:
+        return self._lf_builder(panel).select([SEC, PERIOD, *self.exports]).collect()
+
+
+def compile_model(model: ast.ModelDecl, universes: dict[str, ast.UniverseDecl]) -> ModelPlan:
+    # Universe binding per reference §8.3: explicit `on` wins; a sole declared
+    # universe auto-binds; zero universes = full panel.
+    if model.universe is not None:
+        uni = universes.get(model.universe)
+    elif len(universes) == 1:
+        uni = next(iter(universes.values()))
+    else:
+        uni = None
+    scores = [s for s in model.statements if isinstance(s, ast.ScoreDecl)]
+
+    def builder(panel: pl.DataFrame) -> pl.LazyFrame:
+        lf = panel.lazy()
+        if uni is not None and uni.where is not None:
+            lf = lf.filter(compile_expr(uni.where, set()))
+        defined: set[str] = set()
+        for st in model.statements:
+            if isinstance(st, ast.ScoreDecl):
+                lf = lf.with_columns(_score_expr(st, defined).alias(st.name))
+                defined.add(st.name)
+            elif _is_weighted_score(st.expr):
+                lf = lf.with_columns(_weighted_score(scores, model.on_missing).alias(st.name))
+                defined.add(st.name)
+            else:
+                lf = lf.with_columns(compile_expr(st.expr, defined).alias(st.name))
+                defined.add(st.name)
+        return lf
+
+    exports = tuple(s.name for s in model.statements if isinstance(s, ast.Assignment) and s.export)
+    return ModelPlan(builder, exports)