alphaspec 0.1.0__py3-none-any.whl

alphaspec/lints.py

@@ -0,0 +1,266 @@
+"""Semantic lint rules. Each rule exists because the mistake it catches was made in
+production at least once and the runtime accepted it without complaint.
+
+Every rule code here must be documented in docs/RULES.md (enforced by tests).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from collections.abc import Iterator
+from typing import Any
+
+from ._resources import load_catalog
+from .validate import Issue
+
+RULES: dict[str, str] = {
+    "AS001": "Indicator reference does not resolve",
+    "AS002": "Parameter reference does not resolve",
+    "AS003": "Higher-timeframe indicator uses LIVE bars (look-ahead)",
+    "AS004": "Indicator references form a cycle",
+    "AS005": "Unknown indicator type",
+    "AS006": "Unknown indicator parameter",
+    "AS007": "Indicator not available on this market",
+    "AS008": "timeframe/barPolicy ignored for primary-series-only indicator",
+    "AS009": "Indicator timeframe finer than primary timeframe",
+    "AS010": "tick timeframe cannot be bar-backtested",
+    "AS011": "Symbol missing venue suffix",
+    "AS012": "searchTrials required for generated output",
+    "AS013": "No exit rule",
+    "AS014": "Intraday indicator on a too-coarse primary timeframe",
+    "AS015": "Indicator defined but never used",
+    "AS101": "Duplicate symbol in submission",
+    "AS102": "Every score is null",
+    "AS103": "asOf is in the future",
+    "AS104": "Zeros look like missing values",
+    "AS105": "Weights sum above 1",
+}
+
+_TF_SECONDS = {"tick": 1, "1m": 60, "5m": 300, "15m": 900, "30m": 1800,
+               "1h": 3600, "4h": 14400, "1d": 86400, "1w": 604800}
+
+# Markets whose codes are only unique together with a venue suffix (600000.SH vs 600000.SZ...).
+_SUFFIX_MARKET_PREFIXES = ("cn_", "hk_")
+
+# Built-in aliases the runtime resolves without an indicators entry.
+_BUILTIN_ALIASES = {"close"}
+
+
+def _issue(code: str, sev: str, path: str, msg: str, hint: str = "") -> Issue:
+    return Issue(code, sev, path, msg, hint)
+
+
+def run(doc: dict[str, Any], kind: str) -> list[Issue]:
+    if kind == "artifact":
+        return list(_artifact(doc))
+    if kind == "score":
+        return list(_score(doc))
+    return []
+
+
+# ---------------------------------------------------------------- shared
+
+def _walk(node: Any, path: str) -> Iterator[tuple[str, Any]]:
+    yield path, node
+    if isinstance(node, dict):
+        for k, v in node.items():
+            yield from _walk(v, f"{path}/{k}")
+    elif isinstance(node, list):
+        for i, v in enumerate(node):
+            yield from _walk(v, f"{path}/{i}")
+
+
+def _ind_refs(node: Any, path: str) -> Iterator[tuple[str, str]]:
+    for p, n in _walk(node, path):
+        if isinstance(n, dict) and isinstance(n.get("ind"), str):
+            yield p, n["ind"]
+
+
+def _param_refs(node: Any, path: str) -> Iterator[tuple[str, str]]:
+    for p, n in _walk(node, path):
+        if isinstance(n, dict) and set(n) == {"ref"} and isinstance(n["ref"], str):
+            yield p, n["ref"]
+
+
+def _symbols_need_suffix(market: str) -> bool:
+    return market.startswith(_SUFFIX_MARKET_PREFIXES)
+
+
+def _check_symbol(market: str, symbol: str, path: str) -> Iterator[Issue]:
+    if _symbols_need_suffix(market) and "." not in symbol:
+        yield _issue("AS011", "error", path,
+                     f"symbol {symbol!r} has no venue suffix; on {market} the suffix is part of the identity",
+                     "write e.g. 600000.SH / 000001.SZ / 00700.HK")
+
+
+def _check_producer(producer: dict[str, Any], path: str) -> Iterator[Issue]:
+    if producer.get("kind") in ("AI_AGENT", "FACTOR_MINER") and "searchTrials" not in producer:
+        yield _issue("AS012", "error", f"{path}/searchTrials",
+                     f"producer.kind={producer['kind']} must report searchTrials",
+                     "count every candidate you evaluated before submitting this one; "
+                     "it feeds the multiple-testing correction")
+
+
+# ---------------------------------------------------------------- artifact
+
+def _artifact(doc: dict[str, Any]) -> Iterator[Issue]:
+    market: str = doc["market"]
+    primary: str = doc["timeframe"]
+    dsl: dict[str, Any] = doc["dsl"]
+    indicators: dict[str, Any] = dsl["indicators"]
+    params: dict[str, Any] = dsl.get("params", {})
+    catalog = load_catalog()
+    by_type = {t["type"]: t for t in catalog["types"]}
+    primary_only = set(catalog.get("primarySeriesOnly", []))
+    common_keys = set(catalog.get("commonKeys", []))
+
+    known_aliases = set(indicators) | _BUILTIN_ALIASES
+
+    # AS001 / AS002 - every reference resolves.
+    for p, alias in _ind_refs(dsl, "/dsl"):
+        if alias not in known_aliases:
+            yield _issue("AS001", "error", p, f"indicator alias {alias!r} is not defined in dsl.indicators",
+                         "an unresolved reference compiles to nothing and the rule never fires")
+    for p, name in _param_refs(dsl, "/dsl"):
+        if name not in params:
+            yield _issue("AS002", "error", p, f"parameter {name!r} is not defined in dsl.params")
+
+    # AS004 - cycles between indicators.
+    graph = {a: {r for _, r in _ind_refs(spec, "")} & set(indicators) for a, spec in indicators.items()}
+    yield from _cycles(graph)
+
+    # AS015 - unused indicators.
+    used = {r for _, r in _ind_refs({"entry": dsl["entry"], "exit": dsl.get("exit")}, "")}
+    frontier = list(used)
+    while frontier:
+        for r in graph.get(frontier.pop(), ()):
+            if r not in used:
+                used.add(r)
+                frontier.append(r)
+    for alias in indicators:
+        if alias not in used:
+            yield _issue("AS015", "warning", f"/dsl/indicators/{alias}",
+                         f"indicator {alias!r} is never referenced by entry/exit")
+
+    for alias, spec in indicators.items():
+        path = f"/dsl/indicators/{alias}"
+        itype = spec["type"]
+        meta = by_type.get(itype)
+        if meta is None:
+            yield _issue("AS005", "error", f"{path}/type", f"unknown indicator type {itype!r}",
+                         "see catalog/indicators.json for the supported types")
+            continue
+
+        allowed = common_keys | {p["key"] for p in meta.get("params", [])} \
+            | set(meta.get("operandKeys", [])) | {"in", "left", "right"}
+        for key in spec:
+            if key not in allowed:
+                yield _issue("AS006", "warning", f"{path}/{key}",
+                             f"{itype} has no parameter {key!r}; it will be ignored")
+
+        profile = meta.get("profile", "core")
+        if profile == "ext.cn" and not market.startswith("cn_"):
+            yield _issue("AS007", "error", f"{path}/type",
+                         f"{itype} encodes China-market rules (profile ext.cn) and has no meaning on {market}")
+
+        tf = spec.get("timeframe")
+        if itype in primary_only and (tf or "barPolicy" in spec):
+            yield _issue("AS008", "warning", path,
+                         f"{itype} is always computed on the primary series; timeframe/barPolicy are ignored")
+            continue
+
+        if tf:
+            if _TF_SECONDS[tf] < _TF_SECONDS[primary]:
+                yield _issue("AS009", "error", f"{path}/timeframe",
+                             f"indicator timeframe {tf} is finer than the primary timeframe {primary}",
+                             "a finer series cannot be derived from coarser bars; lower the primary timeframe")
+            elif _TF_SECONDS[tf] > _TF_SECONDS[primary] and spec.get("barPolicy") == "LIVE":
+                yield _issue("AS003", "error", f"{path}/barPolicy",
+                             f"{tf} indicator on a {primary} strategy with barPolicy=LIVE reads the "
+                             f"still-forming {tf} bar; in a backtest that bar already contains the future",
+                             "use barPolicy CLOSED (the default)")
+
+        max_tf = meta.get("maxPrimaryTimeframe")
+        if max_tf and _TF_SECONDS[primary] > _TF_SECONDS.get(max_tf, 10**9):
+            yield _issue("AS014", "error", f"{path}/type",
+                         f"{itype} is an intraday indicator and needs a primary timeframe of {max_tf} or finer, "
+                         f"strategy runs on {primary}")
+
+    if primary == "tick":
+        yield _issue("AS010", "warning", "/timeframe",
+                     "tick strategies are evaluated per market-data frame; that dimension does not exist "
+                     "in bar history, so bar backtests will refuse them")
+
+    if "exit" not in dsl:
+        yield _issue("AS013", "warning", "/dsl",
+                     "no exit rule: positions close only through stop rules or rebalancing")
+
+    universe = doc.get("universe") or {}
+    for i, sym in enumerate(universe.get("symbols", [])):
+        yield from _check_symbol(market, sym, f"/universe/symbols/{i}")
+
+    yield from _check_producer(doc["producer"], "/producer")
+
+
+def _cycles(graph: dict[str, set[str]]) -> Iterator[Issue]:
+    WHITE, GREY, BLACK = 0, 1, 2
+    color = {n: WHITE for n in graph}
+    reported: set[frozenset[str]] = set()
+
+    def visit(n: str, stack: list[str]) -> Iterator[Issue]:
+        color[n] = GREY
+        stack.append(n)
+        for m in sorted(graph[n]):
+            if color[m] == GREY:
+                cyc = stack[stack.index(m):]
+                key = frozenset(cyc)
+                if key not in reported:
+                    reported.add(key)
+                    yield _issue("AS004", "error", f"/dsl/indicators/{m}",
+                                 "indicator references form a cycle: " + " -> ".join(cyc + [m]))
+            elif color[m] == WHITE:
+                yield from visit(m, stack)
+        stack.pop()
+        color[n] = BLACK
+
+    for n in sorted(graph):
+        if color[n] == WHITE:
+            yield from visit(n, [])
+
+
+# ---------------------------------------------------------------- score
+
+def _score(doc: dict[str, Any]) -> Iterator[Issue]:
+    market = doc["market"]
+    rows_key = "scores" if "scores" in doc else "weights"
+    rows = doc[rows_key]
+
+    seen: dict[str, int] = {}
+    for i, row in enumerate(rows):
+        sym = row["symbol"]
+        if sym in seen:
+            yield _issue("AS101", "error", f"/{rows_key}/{i}/symbol",
+                         f"{sym} also appears at index {seen[sym]}")
+        else:
+            seen[sym] = i
+        yield from _check_symbol(market, sym, f"/{rows_key}/{i}/symbol")
+
+    if rows_key == "scores":
+        values = [r["score"] for r in rows]
+        if all(v is None for v in values):
+            yield _issue("AS102", "error", "/scores", "every score is null; nothing can be ranked")
+        zeros = sum(1 for v in values if v == 0)
+        if zeros and None not in values and zeros / len(values) >= 0.2:
+            yield _issue("AS104", "warning", "/scores",
+                         f"{zeros} of {len(values)} scores are exactly 0 and none are null",
+                         "if 0 means 'no data', send null: 0 is a real rank position")
+    else:
+        total = sum(r["weight"] for r in rows)
+        if total > 1 + 1e-9:
+            yield _issue("AS105", "error", "/weights", f"weights sum to {total:.6f}; must be <= 1 (remainder is cash)")
+
+    as_of = _dt.date.fromisoformat(doc["asOf"])
+    # One day of slack: asOf is in the market's calendar, which can be ahead of UTC.
+    if as_of > _dt.datetime.now(_dt.timezone.utc).date() + _dt.timedelta(days=1):
+        yield _issue("AS103", "error", "/asOf", f"asOf {as_of} is in the future")
+
+    yield from _check_producer(doc["producer"], "/producer")

alphaspec/mcp_server.py

@@ -0,0 +1,231 @@
+"""MCP server (stdio) for agents that cannot run a shell.
+
+    pip install "alphaspec[mcp]"
+    alphaspec-mcp                      # started by the MCP client, not by hand
+
+The harness talks MCP (JSON-RPC over stdio) to this process; this process talks HTTPS to the
+runtime's /api/agent/v1 with the same :class:`Client` the CLI uses. Nothing here adds a
+capability the public API does not already have, and no tool can place orders.
+
+Offline tools (validate, catalog, schema, examples, docs) work without any configuration.
+Runtime tools read ALPHASPEC_BASE_URL and ALPHASPEC_API_KEY from the environment the client
+passes to this process.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+try:  # mcp >= 2
+    from mcp.server.mcpserver import MCPServer
+    from mcp.server.mcpserver.exceptions import ToolError
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as MCPServer  # type: ignore[no-redef]
+    from mcp.server.fastmcp.exceptions import ToolError  # type: ignore[no-redef]
+
+from . import __version__
+from ._resources import data_root, default_lang, load_catalog, load_schema, localized
+from .cli import _DOCS, _market_allows
+from .client import AlphaSpecError, Client, Rejected
+from .lints import RULES
+from .validate import validate as _validate
+
+INSTRUCTIONS = """AlphaSpec documents are JSON trading-strategy contracts with no code in them.
+Never invent indicator names or parameter keys: find them with search_indicators / get_indicator
+and read each entry's pitfalls. Start from get_example, then call validate until there are no
+errors. Constants are {"const": n}, never bare numbers. Set producer.searchTrials to every
+candidate you evaluated, discarded ones included. Submit only when the user wants the strategy
+run; evaluations have a daily quota, so do not loop submissions hunting for a passing variant.
+Never state performance numbers the runtime did not return. promote creates a DISABLED paper
+strategy; tell the user to start it themselves. No tool here can place orders."""
+
+server = MCPServer("alphaspec", instructions=INSTRUCTIONS, version=__version__)
+
+
+def _client() -> Client:
+    try:
+        return Client()
+    except ValueError as exc:
+        raise ToolError(f"{exc}. Set it in this MCP server's env block in the client config.") from None
+
+
+def _call(fn, *args):
+    try:
+        return fn(*args)
+    except Rejected:
+        raise
+    except AlphaSpecError as exc:
+        raise ToolError(str(exc)) from None
+    except OSError as exc:
+        raise ToolError(f"cannot reach runtime: {exc}") from None
+
+
+def _report(doc: Any) -> dict[str, Any]:
+    r = _validate(doc)
+    return {"ok": r.ok, "kind": r.kind, "errors": len(r.errors), "warnings": len(r.warnings),
+            "issues": [i.__dict__ for i in r.issues]}
+
+
+def _lang(lang: str) -> str:
+    if lang and lang not in ("en", "zh"):
+        raise ToolError("lang must be en or zh")
+    return lang or default_lang()
+
+
+def _as_doc(document: dict[str, Any] | str) -> Any:
+    # Some clients pass nested objects as a JSON string.
+    if isinstance(document, str):
+        try:
+            return json.loads(document)
+        except json.JSONDecodeError as exc:
+            raise ToolError(f"document is not valid JSON: {exc}") from None
+    return document
+
+
+# ---------------------------------------------------------------- offline
+
+@server.tool()
+def validate(document: dict[str, Any] | str) -> dict[str, Any]:
+    """Validate an AlphaSpec document (artifact or score) locally, with the same rules the runtime
+    applies. Fix every error; treat warnings as probable mistakes. Use explain_rule for any code."""
+    return _report(_as_doc(document))
+
+
+@server.tool()
+def explain_rule(code: str) -> str:
+    """Why a lint rule (e.g. AS003) exists and how to fix a document that breaks it."""
+    code = code.upper()
+    text = (data_root() / "docs" / "RULES.md").read_text(encoding="utf-8")
+    start = text.find(f"### {code}")
+    if start < 0:
+        raise ToolError(f"unknown rule {code}; known: {', '.join(RULES)}")
+    end = text.find("\n### ", start + 1)
+    return text[start:end if end > 0 else None].strip()
+
+
+@server.tool()
+def search_indicators(query: str = "", market: str = "", profile: str = "", lang: str = "") -> list[dict[str, Any]]:
+    """Find indicator types you may use. query matches name, summary and parameters in English or
+    Chinese (e.g. "RSI", "moving average", "breakout", "均线"); market hides types unavailable there
+    (e.g. us_equity hides China-only ones); profile is core | ext.cn | ext.l2 | ext.data; lang is en | zh.
+    Returns a compact list; call get_indicator for parameters, units and pitfalls before using a type."""
+    lang = _lang(lang)
+    q = query.lower()
+    rows = []
+    for t in load_catalog()["types"]:
+        if profile and t["profile"] != profile:
+            continue
+        if not _market_allows(t["profile"], market or None):
+            continue
+        if q and q not in json.dumps(t, ensure_ascii=False).lower():
+            continue
+        loc = localized(t, lang)
+        rows.append({"type": t["type"], "profile": t["profile"], "label": loc.get("label", ""),
+                     "summary": loc.get("summary", ""),
+                     "params": [p["key"] for p in t.get("params", [])],
+                     "operands": t.get("operandKeys", [])})
+    return rows
+
+
+@server.tool()
+def get_indicator(type: str, lang: str = "") -> dict[str, Any]:
+    """Full catalog entry for one indicator type: parameter keys, defaults, ranges, unit, pitfalls.
+    lang is en | zh."""
+    t = next((x for x in load_catalog()["types"] if x["type"] == type.upper()), None)
+    if t is None:
+        raise ToolError(f"unknown indicator type {type}; use search_indicators")
+    return localized(t, _lang(lang))
+
+
+@server.tool()
+def get_schema(kind: str) -> dict[str, Any]:
+    """JSON Schema for a document kind: artifact, score, gate-result, evidence or common."""
+    if kind not in ("artifact", "score", "gate-result", "evidence", "common"):
+        raise ToolError("kind must be one of artifact, score, gate-result, evidence, common")
+    return load_schema(kind)
+
+
+@server.tool()
+def list_examples() -> list[dict[str, Any]]:
+    """Example documents to start from."""
+    out = []
+    for f in sorted((data_root() / "examples").rglob("*.json")):
+        doc = json.loads(f.read_text(encoding="utf-8"))
+        out.append({"name": f.stem, "kind": doc.get("kind"), "market": doc.get("market"),
+                    "title": doc.get("title") or doc.get("scoreName")})
+    return out
+
+
+@server.tool()
+def get_example(name: str) -> dict[str, Any]:
+    """One example document by name (a prefix such as "01-ema-cross" is enough)."""
+    match = [f for f in sorted((data_root() / "examples").rglob("*.json"))
+             if f.stem == name or f.stem.startswith(name)]
+    if not match:
+        raise ToolError(f"no example named {name}; use list_examples")
+    return json.loads(match[0].read_text(encoding="utf-8"))
+
+
+@server.tool()
+def get_doc(name: str) -> str:
+    """Reference document: spec (field semantics), rules (every lint rule), markets, runtime (API and gate)."""
+    if name not in _DOCS:
+        raise ToolError(f"name must be one of {', '.join(sorted(_DOCS))}")
+    return (data_root() / "docs" / _DOCS[name]).read_text(encoding="utf-8")
+
+
+# ---------------------------------------------------------------- runtime
+
+@server.tool()
+def whoami() -> dict[str, Any]:
+    """Check the configured API key: user, contract version, what the key can and cannot do."""
+    return _call(_client().whoami)
+
+
+@server.tool()
+def submit(document: dict[str, Any] | str) -> dict[str, Any]:
+    """Validate locally, then submit an artifact to the runtime. Returns {accepted, artifactId,
+    warnings} or {accepted: false, issues}. Submitting does not run anything; call evaluate."""
+    doc = _as_doc(document)
+    try:
+        res = _call(_client().submit, doc)
+    except Rejected as exc:  # subclass of AlphaSpecError, but a normal outcome for an agent
+        return {"accepted": False, "issues": exc.issues}
+    return {"accepted": True, **res}
+
+
+@server.tool()
+def evaluate(artifact_id: int) -> dict[str, Any]:
+    """Start a platform evaluation (one backtest, in-sample and out-of-sample segments chosen by the
+    runtime). Returns immediately; poll gate_result every few seconds. Uses the daily quota."""
+    return _call(_client().evaluate, artifact_id)
+
+
+@server.tool()
+def gate_result(artifact_id: int) -> dict[str, Any]:
+    """Latest evaluation of an artifact. state is RUNNING (poll again later), FAILED (error says why)
+    or DONE (result is the gate-result document). Each check names its number in `metric`; read it
+    instead of guessing from the code."""
+    state, body = _call(_client().gate_result, artifact_id)
+    return {"state": state, "result" if state == "DONE" else "detail": body}
+
+
+@server.tool()
+def list_submissions() -> list[dict[str, Any]]:
+    """My submitted artifacts, newest first, with the latest verdict."""
+    return _call(_client().list)
+
+
+@server.tool()
+def promote(artifact_id: int, name: str = "") -> dict[str, Any]:
+    """Turn a gate-passed artifact into a paper-trading strategy. It is created DISABLED; the user
+    starts it in the runtime's UI. Only call this when the user asked for it."""
+    return _call(_client().promote, artifact_id, name or None)
+
+
+def main() -> None:
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

alphaspec/validate.py

@@ -0,0 +1,108 @@
+"""Validate AlphaSpec documents: JSON Schema first, then semantic lint rules.
+
+Schema validation answers "is this well-formed". Lint rules answer "will this do what
+its author thinks": unresolved references, look-ahead, indicators that cannot exist on
+this market, and similar mistakes that a runtime would otherwise accept and run wrongly.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+
+from ._resources import CONTRACT_VERSION, load_schema, schema_dir
+
+KINDS = ("artifact", "score", "gate-result", "evidence")
+
+
+@dataclass(frozen=True)
+class Issue:
+    code: str
+    severity: str  # "error" | "warning"
+    path: str
+    message: str
+    hint: str = ""
+
+    def __str__(self) -> str:
+        loc = self.path or "/"
+        tail = f"  hint: {self.hint}" if self.hint else ""
+        return f"{self.severity.upper():7} {self.code} at {loc}: {self.message}{tail}"
+
+
+@dataclass
+class Report:
+    kind: str | None
+    issues: list[Issue] = field(default_factory=list)
+
+    @property
+    def errors(self) -> list[Issue]:
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self) -> list[Issue]:
+        return [i for i in self.issues if i.severity == "warning"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def codes(self) -> list[str]:
+        return sorted({i.code for i in self.issues})
+
+
+def _registry(version: str) -> Registry:
+    resources = []
+    for path in sorted(schema_dir(version).glob("*.schema.json")):
+        name = path.name.removesuffix(".schema.json")
+        doc = load_schema(name, version)
+        resources.append((doc["$id"], Resource.from_contents(doc)))
+    return Registry().with_resources(resources)
+
+
+def _validator(kind: str, version: str = CONTRACT_VERSION) -> Draft202012Validator:
+    return Draft202012Validator(
+        load_schema(kind, version),
+        registry=_registry(version),
+        format_checker=FormatChecker(),
+    )
+
+
+def _pointer(parts) -> str:
+    return "".join(f"/{p}" for p in parts)
+
+
+def _schema_issues(doc: Any, kind: str) -> list[Issue]:
+    validator = _validator(kind)
+    out = []
+    for err in sorted(validator.iter_errors(doc), key=lambda e: list(e.absolute_path)):
+        # oneOf / anyOf failures are reported as a single opaque message; surface the
+        # most specific sub-error instead so the author sees which field is wrong.
+        best = err
+        if err.context:
+            best = min(err.context, key=lambda e: (-len(e.absolute_path), len(e.message)))
+        out.append(Issue("SCHEMA", "error", _pointer(best.absolute_path), best.message))
+    return out
+
+
+def validate(doc: Any, kind: str | None = None) -> Report:
+    """Validate one document. kind is read from doc['kind'] when not given."""
+    if kind is None and isinstance(doc, dict):
+        kind = doc.get("kind")
+    if kind not in KINDS:
+        return Report(kind, [Issue("UNKNOWN_KIND", "error", "/kind",
+                                   f"kind must be one of {', '.join(KINDS)}, got {kind!r}")])
+    if isinstance(doc, dict) and doc.get("contractVersion") not in (None, CONTRACT_VERSION):
+        return Report(kind, [Issue("UNSUPPORTED_VERSION", "error", "/contractVersion",
+                                   f"this validator understands contractVersion {CONTRACT_VERSION}, "
+                                   f"got {doc.get('contractVersion')!r}")])
+
+    report = Report(kind, _schema_issues(doc, kind))
+    if report.errors:
+        # Lint rules assume a well-formed document.
+        return report
+
+    from . import lints
+    report.issues.extend(lints.run(doc, kind))
+    return report