trail-lang 0.1.0__tar.gz

trail_lang-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --frozen
+      - name: Lint (ruff)
+        run: uv run ruff check .
+      - name: Test (pytest)
+        run: uv run pytest -q

trail_lang-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: test and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync
+        run: uv sync --frozen
+      - name: Test
+        run: uv run pytest -q
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing (OIDC), no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

trail_lang-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+.omc/
+.claude/

trail_lang-0.1.0/LICENSE

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

trail_lang-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: trail-lang
+Version: 0.1.0
+Summary: A declarative expression language for financial indicators, scoring, and screening over security panels
+Project-URL: Homepage, https://github.com/trail-language
+Project-URL: Repository, https://github.com/trail-language/trail-py
+Project-URL: Specification, https://github.com/trail-language/spec
+Project-URL: Issues, https://github.com/trail-language/trail-py/issues
+Author-email: Usman Shahid <u.manshahid@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: expression-language,factor,finance,indicators,polars,quant,screening
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: lark>=1.2
+Requires-Dist: polars>=1.20
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/trail-language/spec/main/brand/icon-color-240.png" alt="Trail" width="120">
+</p>
+
+# trail-py
+
+The reference implementation of **Trail** - a small, total, declarative language for computing
+financial indicators, scores, and screening strategies over panels of securities. Trail
+expressions compile to vectorized [Polars](https://pola.rs) operations.
+
+The language specification (grammar, reference, standard library) lives in
+[**trail-language/spec**](https://github.com/trail-language/spec).
+
+```trail
+model quality on us_main period annual {
+    operating_margin = income.operating_income / income.revenue
+    score om_score weight 7 {
+        2 if operating_margin > 0.12
+        1 if operating_margin > 0.05
+        else 0
+    }
+    export composite = weighted_score()
+}
+```
+
+## Install
+
+```bash
+pip install trail-lang        # or: uv add trail-lang
+```
+
+## CLI
+
+```bash
+trail validate models/quality.trail                 # parse, kind-check, dry-run
+trail run models/quality.trail --model quality      # evaluate a model
+trail run models/quality.trail --model quality --config trail.yaml
+trail catalog                                       # discover fields, functions, sources
+trail catalog income                                # fields in a namespace
+trail catalog cagr                                  # describe a function
+```
+
+The standard library is loaded implicitly; pass `--no-stdlib` to opt out.
+
+## Library
+
+```python
+from trail.pipeline import prepare
+from trail.compiler import compile_model
+from trail.fixtures import load_panel  # a bundled demo panel
+
+program = prepare("model m { export margin = income.operating_income / income.revenue }")
+model = next(d for d in program.decls if type(d).__name__ == "ModelDecl")
+result = compile_model(model, {}).run(load_panel())
+```
+
+## Architecture
+
+Parser (Lark LALR) → typed AST → macro expansion (`def` inlining) → kind-checked validation →
+Polars compiler. The engine carries only irreducible **primitives**; the large **derived**
+function library is written in Trail itself and shipped as `trail/stdlib/*.trail` (canonical
+copy in the [spec](https://github.com/trail-language/spec)).
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check .
+```
+
+## License
+
+[MIT](LICENSE).

trail_lang-0.1.0/README.md

@@ -0,0 +1,74 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/trail-language/spec/main/brand/icon-color-240.png" alt="Trail" width="120">
+</p>
+
+# trail-py
+
+The reference implementation of **Trail** - a small, total, declarative language for computing
+financial indicators, scores, and screening strategies over panels of securities. Trail
+expressions compile to vectorized [Polars](https://pola.rs) operations.
+
+The language specification (grammar, reference, standard library) lives in
+[**trail-language/spec**](https://github.com/trail-language/spec).
+
+```trail
+model quality on us_main period annual {
+    operating_margin = income.operating_income / income.revenue
+    score om_score weight 7 {
+        2 if operating_margin > 0.12
+        1 if operating_margin > 0.05
+        else 0
+    }
+    export composite = weighted_score()
+}
+```
+
+## Install
+
+```bash
+pip install trail-lang        # or: uv add trail-lang
+```
+
+## CLI
+
+```bash
+trail validate models/quality.trail                 # parse, kind-check, dry-run
+trail run models/quality.trail --model quality      # evaluate a model
+trail run models/quality.trail --model quality --config trail.yaml
+trail catalog                                       # discover fields, functions, sources
+trail catalog income                                # fields in a namespace
+trail catalog cagr                                  # describe a function
+```
+
+The standard library is loaded implicitly; pass `--no-stdlib` to opt out.
+
+## Library
+
+```python
+from trail.pipeline import prepare
+from trail.compiler import compile_model
+from trail.fixtures import load_panel  # a bundled demo panel
+
+program = prepare("model m { export margin = income.operating_income / income.revenue }")
+model = next(d for d in program.decls if type(d).__name__ == "ModelDecl")
+result = compile_model(model, {}).run(load_panel())
+```
+
+## Architecture
+
+Parser (Lark LALR) → typed AST → macro expansion (`def` inlining) → kind-checked validation →
+Polars compiler. The engine carries only irreducible **primitives**; the large **derived**
+function library is written in Trail itself and shipped as `trail/stdlib/*.trail` (canonical
+copy in the [spec](https://github.com/trail-language/spec)).
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check .
+```
+
+## License
+
+[MIT](LICENSE).

trail_lang-0.1.0/RELEASING.md

@@ -0,0 +1,29 @@
+# Releasing
+
+`trail-lang` publishes to PyPI automatically when a version tag is pushed, via GitHub Actions
+trusted publishing (OIDC, no stored token). See `.github/workflows/release.yml`.
+
+## One-time setup
+
+1. Reserve/create the project `trail-lang` on PyPI.
+2. On PyPI, under the project's **Publishing** settings, add a GitHub trusted publisher:
+   - Owner: `trail-language`
+   - Repository: `trail-py`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+3. In this repository's **Settings > Environments**, create an environment named `pypi`
+   (optionally require a reviewer for publish approvals).
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit, then tag and push:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+3. The `Release` workflow runs the tests, builds the sdist and wheel, and publishes to PyPI.
+
+Installability is covered by CI-agnostic packaging: the wheel bundles the grammar and standard
+library, so `pip install trail-lang` and `pipx install trail-lang` both yield a working `trail`
+CLI with no source tree present.

trail_lang-0.1.0/examples/performance.trail

@@ -0,0 +1,56 @@
+universe all_active = stocks where meta.is_active
+
+model performance on all_active period annual {
+    desc "v1 performance.pel translation (fixture-field subset)"
+
+    revenue_cagr = cagr(income.revenue, 4)
+    score revenue_growth_score weight 7 {
+        2 if revenue_cagr > 0.15
+        1 if revenue_cagr > 0.05
+        else 0
+    }
+
+    operating_margin = income.operating_income / income.revenue
+    score operating_margin_score weight 7 {
+        2 if operating_margin > 0.12
+        1 if operating_margin > 0.05
+        else 0
+    }
+
+    net_profit_margin = income.net_income / income.revenue
+    score net_margin_score weight 8 {
+        2 if net_profit_margin > 0.08
+        1 if net_profit_margin > 0.05
+        else 0
+    }
+
+    interest_coverage = income.operating_income / income.interest_expense
+    score interest_coverage_score weight 6 {
+        2 if interest_coverage > 5
+        1 if interest_coverage > 2.5
+        else 0
+    }
+
+    debt_to_equity = balance.total_debt / balance.total_equity
+    score debt_to_equity_score weight 5 {
+        2 if debt_to_equity < 0.5
+        1 if debt_to_equity < 1
+        else 0
+    }
+
+    current_ratio = balance.current_assets / balance.current_liabilities
+    score current_ratio_score weight 7 {
+        2 if current_ratio > 1.5
+        1 if current_ratio > 0.8
+        else 0
+    }
+
+    fcf_per_share = cash.free_cash_flow / income.weighted_average_shares_diluted
+    score fcf_trend_score weight 7 {
+        2 if roll_mean(fcf_per_share, 3) > roll_mean(fcf_per_share, 5)
+        else 0
+    }
+
+    export composite = weighted_score()
+    export revenue_growth = revenue_cagr
+}

trail_lang-0.1.0/examples/piotroski.trail

@@ -0,0 +1,25 @@
+universe all_active = stocks where meta.is_active
+
+model piotroski on all_active period annual {
+    desc "Piotroski F-Score (9 binary signals)"
+
+    roa        = income.net_income / avg2(balance.total_assets)
+    cfo_assets = cash.cfo / avg2(balance.total_assets)
+    ltd_ratio  = balance.long_term_debt / avg2(balance.total_assets)
+    cur_ratio  = balance.current_assets / balance.current_liabilities
+    gm         = income.gross_profit / income.revenue
+    turnover   = income.revenue / avg2(balance.total_assets)
+
+    f_roa_pos  = roa > 0
+    f_cfo_pos  = cash.cfo > 0
+    f_droa     = roa > lag(roa, 1)
+    f_accrual  = cfo_assets > roa
+    f_leverage = ltd_ratio < lag(ltd_ratio, 1)
+    f_liquid   = cur_ratio > lag(cur_ratio, 1)
+    f_noissue  = (cash.stock_issued ?? 0) == 0
+    f_margin   = gm > lag(gm, 1)
+    f_turnover = turnover > lag(turnover, 1)
+
+    export fscore = count(f_roa_pos, f_cfo_pos, f_droa, f_accrual, f_leverage,
+                          f_liquid, f_noissue, f_margin, f_turnover)
+}

trail_lang-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "trail-lang"
+version = "0.1.0"
+description = "A declarative expression language for financial indicators, scoring, and screening over security panels"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Usman Shahid", email = "u.manshahid@gmail.com" }]
+keywords = ["finance", "quant", "factor", "screening", "indicators", "expression-language", "polars"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "lark>=1.2",
+    "polars>=1.20",
+    "click>=8.1",
+    "pyyaml>=6",
+]
+
+[project.urls]
+Homepage = "https://github.com/trail-language"
+Repository = "https://github.com/trail-language/trail-py"
+Specification = "https://github.com/trail-language/spec"
+Issues = "https://github.com/trail-language/trail-py/issues"
+
+[project.scripts]
+trail = "trail.cli:main"
+
+# Built-in data sources. Third-party providers register additional drivers under the
+# same group, so `pip install trail-<name>` makes `driver: <name>` usable in trail.yaml.
+[project.entry-points."trail.sources"]
+fixture = "trail.sources:FixtureSource"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.8", "pandas>=2.2", "pyarrow>=17"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["trail"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

trail_lang-0.1.0/tests/test_acceptance_performance.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+
+import polars as pl
+import pytest
+
+from trail import ast
+from trail.compiler import compile_model
+from trail.fixtures import load_panel
+from trail.pipeline import prepare
+from trail.validate import validate
+
+EXAMPLE = Path(__file__).parent.parent / "examples" / "performance.trail"
+
+
+def _run():
+    program = prepare(EXAMPLE.read_text())
+    assert not [i for i in validate(program) if i.severity == "error"]
+    universes = {d.name: d for d in program.decls if isinstance(d, ast.UniverseDecl)}
+    model = next(d for d in program.decls if isinstance(d, ast.ModelDecl))
+    return compile_model(model, universes).run(load_panel())
+
+
+def test_composite_bounds_and_null_policy():
+    result = _run()
+    vals = [v for v in result["composite"].to_list() if v is not None]
+    assert vals and all(0.0 <= v <= 1.0 for v in vals)
+    # FFF has null interest_expense -> that score skipped, composite still non-null
+    fff_2024 = result.filter((pl.col("security") == "FFF") & (pl.col("period") == 2024))
+    assert fff_2024["composite"][0] is not None
+
+
+def test_revenue_cagr_known_value():
+    # AAA grows 10%/yr exactly -> 4y CAGR = 0.10
+    result = _run()
+    aaa_2024 = result.filter((pl.col("security") == "AAA") & (pl.col("period") == 2024))
+    assert aaa_2024["revenue_growth"][0] == pytest.approx(0.10)
+
+
+def test_growth_ordering_matches_fixture_design():
+    # EEE shrinks (-3%/yr) so its growth is negative; AAA (10%) positive.
+    result = _run()
+    last = result.filter(pl.col("period") == 2024)
+    by_sec = {r["security"]: r["revenue_growth"] for r in last.iter_rows(named=True)}
+    assert by_sec["EEE"] < 0 < by_sec["AAA"]

trail_lang-0.1.0/tests/test_acceptance_piotroski.py

@@ -0,0 +1,70 @@
+"""Golden test: Trail-compiled Piotroski vs an independent numpy/pandas re-implementation.
+
+The oracle mirrors Trail's null semantics exactly: a flag is undefined (NaN) where any
+of its inputs is missing, and the F-score is undefined if any flag is undefined
+(Trail's `count` propagates null). This validates the whole pipeline AND the null model.
+"""
+from pathlib import Path
+
+import numpy as np
+
+from trail import ast
+from trail.compiler import compile_model
+from trail.fixtures import load_panel
+from trail.pipeline import prepare
+
+EXAMPLE = Path(__file__).parent.parent / "examples" / "piotroski.trail"
+
+
+def _oracle(pdf):
+    out = {}
+    for sec, g in pdf.groupby("security"):
+        g = g.sort_values("period").reset_index(drop=True)
+        assets = g["balance.total_assets"]
+        avg_assets = (assets + assets.shift(1)) / 2
+        roa = g["income.net_income"] / avg_assets
+        cfo_a = g["cash.cfo"] / avg_assets
+        ltd = g["balance.long_term_debt"] / avg_assets
+        cur = g["balance.current_assets"] / g["balance.current_liabilities"]
+        gm = g["income.gross_profit"] / g["income.revenue"]
+        to = g["income.revenue"] / avg_assets
+
+        def flag(cond, *ins):
+            f = cond.astype(float).to_numpy().copy()
+            for s in ins:
+                f[s.isna().to_numpy()] = np.nan
+            return f
+
+        flags = [
+            flag(roa > 0, roa),
+            flag(g["cash.cfo"] > 0, g["cash.cfo"]),
+            flag(roa > roa.shift(1), roa, roa.shift(1)),
+            flag(cfo_a > roa, cfo_a, roa),
+            flag(ltd < ltd.shift(1), ltd, ltd.shift(1)),
+            flag(cur > cur.shift(1), cur, cur.shift(1)),
+            flag(g["cash.stock_issued"].fillna(0) == 0),  # coalesced -> never null
+            flag(gm > gm.shift(1), gm, gm.shift(1)),
+            flag(to > to.shift(1), to, to.shift(1)),
+        ]
+        total = np.column_stack(flags).sum(axis=1)  # NaN if any flag NaN
+        for period, val in zip(g["period"], total):
+            out[(sec, int(period))] = None if np.isnan(val) else int(val)
+    return out
+
+
+def test_fscore_matches_pandas_oracle():
+    program = prepare(EXAMPLE.read_text())
+    universes = {d.name: d for d in program.decls if isinstance(d, ast.UniverseDecl)}
+    model = next(d for d in program.decls if isinstance(d, ast.ModelDecl))
+    result = compile_model(model, universes).run(load_panel())
+
+    expected = _oracle(load_panel().to_pandas())
+    checked = 0
+    for row in result.iter_rows(named=True):
+        key = (row["security"], row["period"])
+        assert row["fscore"] == expected[key], (key, row["fscore"], expected[key])
+        checked += 1
+    assert checked == 48
+    # Sanity: at least some cells are fully computable and land in 0..9.
+    non_null = [v for v in expected.values() if v is not None]
+    assert non_null and all(0 <= v <= 9 for v in non_null)

trail_lang-0.1.0/tests/test_catalog.py

@@ -0,0 +1,115 @@
+from click.testing import CliRunner
+
+from trail import ast
+from trail.catalog import (
+    CatalogResult,
+    catalog,
+    describe,
+    evaluate_meta,
+    fields,
+    functions,
+    namespaces,
+    sources,
+)
+from trail.cli import main
+from trail.config import DEFAULT_CONFIG
+from trail.parser import parse_expr, parse_program, parse_repl_line
+
+
+# --- discovery core ---
+
+def test_namespaces_and_fields():
+    assert set(namespaces()) == {"income", "balance", "cash", "price", "meta"}
+    inc = fields("income")
+    assert isinstance(inc, CatalogResult)
+    assert "income.revenue" in inc.frame["field"].to_list()
+    assert all(f.startswith("income.") for f in inc.frame["field"].to_list())
+
+
+def test_functions_catalog_has_axis_and_arity():
+    fr = functions().frame
+    row = fr.filter(fr["function"] == "roll_mean").row(0, named=True)
+    assert row["axis"] == "time-series" and row["args"] == "2"
+    assert "zscore" in fr["function"].to_list()  # cross-sectional present too
+
+
+def test_sources_from_config():
+    fr = sources(DEFAULT_CONFIG).frame
+    assert "fixture" in fr["source"].to_list()
+
+
+def test_describe_resolves_field_namespace_function_source():
+    assert describe(("income", "revenue")).frame.row(0, named=True) == {
+        "property": "column", "value": "income.revenue"
+    } or "flow" in describe(("income", "revenue")).frame["value"].to_list()
+    assert describe(("income",)).title.startswith("Fields in 'income'")
+    assert describe(("roll_mean",)).title == "Function roll_mean"
+    assert describe(("fixture",)).title == "Source fixture"
+    assert describe(("functions",)).frame.height == functions().frame.height
+    assert "Unknown" in describe(("nope",)).title
+
+
+def test_catalog_summary():
+    c = catalog(DEFAULT_CONFIG)
+    assert "namespace" in c.frame.columns and c.frame.height == len(namespaces())
+
+
+# --- REPL dialect parsing (superset of the file grammar) ---
+
+def test_meta_command_parsing():
+    assert parse_repl_line("?") == ast.MetaCatalog()
+    assert parse_repl_line("?income") == ast.MetaDescribe(("income",))
+    assert parse_repl_line("?income.revenue") == ast.MetaDescribe(("income", "revenue"))
+    assert parse_repl_line("?functions") == ast.MetaDescribe(("functions",))
+
+
+def test_repl_line_is_a_superset():
+    # a bare expression and a declaration both still parse in the repl dialect
+    assert parse_repl_line("income.revenue / 2") == parse_expr("income.revenue / 2")
+    decl = parse_repl_line("model m { a = income.revenue }")
+    assert isinstance(decl, ast.ModelDecl)
+
+
+def test_meta_commands_are_rejected_in_a_model_file():
+    # the file grammar must NOT accept meta-commands
+    import pytest
+    from lark.exceptions import UnexpectedInput
+    with pytest.raises(UnexpectedInput):
+        parse_program("?income")
+
+
+def test_evaluate_meta_routes_to_core():
+    assert evaluate_meta(parse_repl_line("?")).frame.columns == ["namespace", "fields"]
+    assert evaluate_meta(parse_repl_line("?income")).title.startswith("Fields in 'income'")
+
+
+# --- CLI ---
+
+def test_cli_catalog():
+    r = CliRunner().invoke(main, ["catalog"])
+    assert r.exit_code == 0 and "namespace" in r.output
+
+
+def test_cli_catalog_describe_field():
+    r = CliRunner().invoke(main, ["catalog", "income.revenue"])
+    assert r.exit_code == 0 and "flow" in r.output
+
+
+def test_functions_catalog_includes_derived_macros():
+    fr = functions().frame
+    assert "layer" in fr.columns
+    layers = dict(zip(fr["function"].to_list(), fr["layer"].to_list()))
+    assert layers["roll_mean"] == "primitive"
+    assert layers["cagr"] == "derived"        # migrated builtin, now a stdlib macro
+    assert layers["signed_log"] == "derived"
+
+
+def test_describe_finds_migrated_macro():
+    d = describe(("cagr",))
+    assert d.title == "Function cagr" and "derived" in d.frame["value"].to_list()
+
+
+def test_internal_helpers_hidden():
+    # _grow_start etc. are internal to timeseries.trail and must not surface in discovery
+    fr = functions().frame
+    assert not any(n.startswith("_") for n in fr["function"].to_list())