powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/factor/schema/factor_computation_schema.py

@@ -0,0 +1,102 @@
+"""数据库保存的不可变 Python 因子计算规格。"""
+
+import ast
+import hashlib
+import json
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.factor.constants import (
+    FactorAuthoringSource,
+    FactorDataModality,
+    FactorDefinitionStatus,
+    FactorFrequency,
+    FactorSourceType,
+)
+
+
+class FactorComputationSpec(BaseModel):
+    """窗口或面板使用对应 Python 函数；仅运行可信本地代码。"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    name: str = Field(..., pattern=r"^[a-z][a-z0-9_]*$", description="因子名（唯一键）")
+    version: str = Field(
+        default="1",
+        min_length=1,
+        max_length=96,
+        description="因子版本（= Canonical definition_version）",
+    )
+    frequency: FactorFrequency = Field(default=FactorFrequency.DAILY, description="结果频率")
+    description: str = Field(default="", description="因子说明")
+    source_type: FactorSourceType = Field(default=FactorSourceType.MARKET, description="信息来源")
+    data_modality: FactorDataModality = Field(
+        default=FactorDataModality.STRUCTURED, description="输入数据模态"
+    )
+    inputs: list[str] = Field(default_factory=list, description="输入数据集，如 bar/1d")
+    parameters: dict[str, Any] = Field(default_factory=dict, description="计算参数（如 lookback）")
+    input_kind: Literal["window", "panel", "expression"] = "window"
+    python_source: str = Field(..., min_length=1, max_length=65536)
+    output_type: str = Field(default="float", description="输出类型（float/score/ratio）")
+    unit: str | None = Field(default=None, description="输出单位（ratio/percent/score）")
+    lookback: int = Field(default=1, ge=1, description="最少历史观测期数")
+    status: FactorDefinitionStatus = Field(
+        default=FactorDefinitionStatus.DRAFT, description="Artifact 生命周期"
+    )
+    authoring_source: FactorAuthoringSource = Field(
+        default=FactorAuthoringSource.HUMAN, description="生产入口"
+    )
+    created_by: str | None = Field(default=None, description="生产者标识（Agent/Human 可追溯）")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="扩展元数据")
+
+    def validate_definition(self) -> list[str]:
+        """只做结构与语法校验；不把 AST 校验误称为安全沙箱。"""
+        problems: list[str] = []
+        try:
+            module = ast.parse(self.python_source)
+            if self.input_kind == "expression":
+                if not any(
+                    isinstance(node, ast.Assign)
+                    and any(
+                        isinstance(target, ast.Name) and target.id == "factors"
+                        for target in node.targets
+                    )
+                    for node in module.body
+                ):
+                    problems.append("表达式源码必须声明顶层 factors 字典")
+                if not self.inputs:
+                    problems.append("表达式 inputs 必须声明输入数据需求")
+                if len(self.python_source.encode("utf-8")) > 65536:
+                    problems.append("源码超过 64 KiB")
+                return problems
+            functions = [
+                node
+                for node in module.body
+                if isinstance(node, ast.FunctionDef)
+                and node.name == ("compute_panel" if self.input_kind == "panel" else "compute")
+            ]
+            if len(functions) != 1 or [arg.arg for arg in functions[0].args.args] != [
+                "panel" if self.input_kind == "panel" else "bars",
+                "parameters",
+            ]:
+                problems.append(
+                    "源码必须定义与 input_kind 对应的同步顶层 compute/compute_panel 函数"
+                )
+        except SyntaxError as exc:
+            problems.append(f"Python 语法错误: {exc.msg}")
+        if len(self.python_source.encode("utf-8")) > 65536:
+            problems.append("源码超过 64 KiB")
+        if self.input_kind == "panel" and not self.inputs:
+            problems.append("面板 inputs 必须声明输入数据需求")
+        if self.input_kind == "window" and f"bar/{self.frequency.value}" not in self.inputs:
+            problems.append("inputs 必须声明与结果频率对应的 Bar 输入")
+        return problems
+
+    @property
+    def content_digest(self) -> str:
+        data = self.model_dump(mode="json")
+        if self.input_kind == "window":
+            data.pop("input_kind")
+        payload = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()

quant_core/app/factor/schema/factor_compute_request.py

@@ -0,0 +1,24 @@
+"""单次因子计算的输入契约。"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime
+
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+
+
+@dataclass(frozen=True)
+class FactorComputeRequest:
+    """完整身份优先；名称仅供无歧义的旧调用使用。"""
+
+    factor_name: str
+    instrument_id: str
+    event_time: datetime
+    bars: Sequence[BarResponse]
+    input_digest: str | None = None
+    identity: FactorIdentity | None = None
+
+    def __post_init__(self) -> None:
+        if self.identity is not None and self.identity.name != self.factor_name:
+            raise ValueError("因子名称与完整身份不一致")

quant_core/app/factor/schema/factor_contract.py

@@ -0,0 +1,257 @@
+"""Canonical Factor Contract - FactorDefinition / FactorValue / FactorSnapshot（T1）
+
+SSOT：T1-TASK-20260907-2308-factor-contract、Group 入口确认决策（Q1=A / Q2=A / Q3=A）。
+
+概念分层（Definition / Value / Snapshot 分离，与 ARCHITECTURE 全局不变量 8 一致）：
+- FactorDefinition：因子是什么、什么口径（Artifact，含 identity 与 provenance 元描述）。
+- FactorValue：长表一行（Q3=A）——一个 factor/source/version/instrument/as_of 的值，
+  携带 as_of（归属业务时间）与 available_at（策略最早可见时间）分离语义。
+- FactorSnapshot：某 decision_time 的可读横截面；point-in-time 门禁在构造边界
+  自维护（available_at > decision_time 的值结构化拒绝，AC-2）。
+
+核心规则：
+- 不同 source / definition_version 是不同因子身份（FactorIdentity.logical_key），
+  禁止静默替换、隐式 fallback 或合并（Group 决策 4）。
+- MISSING / UNAVAILABLE / NOT_YET_PUBLISHED 用 status 表达，禁止 0 填充。
+- 本模块不引用任何 Provider SDK、Repository 或数据库——Provider 专有字段
+  （如 Tushare ts_code/ann_date）不得进入契约（全局不变量 2）。
+"""
+
+import json
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from quant_core.app.factor.constants import (
+    FactorFrequency,
+    FactorFreshness,
+    FactorSourceKind,
+    FactorStatus,
+)
+from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
+
+
+def _require_tzaware(field: str, v: datetime) -> datetime:
+    if v.tzinfo is None or v.tzinfo.utcoffset(v) is None:
+        raise ValueError(f"{field} 必须是 tz-aware datetime: {v}")
+    return v
+
+
+class FactorIdentity(BaseModel, frozen=True):
+    """因子逻辑身份：不同 (name, source, definition_version, frequency) 不互认
+
+    Group 决策 4：相同因子名但 source / definition version / 计算口径不同，
+    禁止静默替换、隐式 fallback、合并成同一因子身份。
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(..., pattern=r"^[a-z][a-z0-9_]*$", description="因子名")
+    source: str = Field(..., min_length=1, description="来源标识（如 tushare / local-python）")
+    definition_version: str = Field(..., min_length=1, max_length=96, description="口径版本")
+    frequency: FactorFrequency = Field(default=FactorFrequency.DAILY, description="因子频率")
+
+    @property
+    def logical_key(self) -> tuple[str, str, str, FactorFrequency]:
+        """业务唯一键的身份部分（T2 长表唯一键 = logical_key + instrument_id + as_of）"""
+        return (self.name, self.source, self.definition_version, self.frequency)
+
+
+class FactorProvenance(BaseModel):
+    """因子值血缘（描述性、来源无关；不含 Provider 专有 schema 字段）
+
+    版本锁定语义（R2-2）：
+    - dataset_revision：数据集修订批次（quant_core.app.factor.revision 约定，可排序）。
+      同一官方修订产生的旧行在新 revision 下保留——旧回测 pin 旧 revision
+      即可复现原数据集；None = 未声明（Store 入库归一 0-legacy）。
+    - provider_revision：Provider 侧修订号；Provider 不提供时保持 None
+      （unknown 是合法状态，禁止用 mapping version 臆造）。
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source_kind: FactorSourceKind = Field(..., description="生产来源类别（AC-1 三类）")
+    provider_id: str = Field(
+        ..., min_length=1, description="生产者标识（provider/calculator/model）"
+    )
+    retrieval_ref: str | None = Field(
+        default=None, description="取数/计算引用（如接口名或 dotted path）"
+    )
+    content_digest: str | None = Field(
+        default=None, pattern=r"^[0-9a-f]{64}$", description="内容级 SHA-256（可选，T3 真实验证用）"
+    )
+    dataset_revision: str | None = Field(
+        default=None, description="数据集修订批次（可排序；见类注释）"
+    )
+    provider_revision: str | None = Field(
+        default=None, description="Provider 侧修订号（未知保持 None，不臆造）"
+    )
+    note: str | None = Field(default=None, description="补充说明")
+
+
+class FactorDefinition(BaseModel):
+    """因子定义（Artifact）——全系统唯一因子口径 SSOT（R1-1）
+
+    身份、口径、计算规格、值与 PIT 截面的唯一 Owner 是 app/factor。
+    本地定义附带 FactorComputationSpec；外部导入定义不携带本地公式。
+    """
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    identity: FactorIdentity = Field(..., description="因子逻辑身份（唯一键）")
+    description: str = Field(default="", description="因子说明")
+    lookback: int = Field(default=1, ge=1, description="最少历史窗口（业务期数）")
+    provenance_template: FactorProvenance | None = Field(
+        default=None, description="该定义下典型生产的 provenance 元描述"
+    )
+    computation_spec: FactorComputationSpec | None = Field(
+        default=None, description="本地计算规格；外部导入定义不携带本地公式"
+    )
+
+    @model_validator(mode="after")
+    def _matching_computation_identity(self) -> "FactorDefinition":
+        spec = self.computation_spec
+        if spec is not None and (
+            spec.name != self.identity.name
+            or spec.version != self.identity.definition_version
+            or spec.frequency != self.identity.frequency
+        ):
+            raise ValueError("计算规格的名称、版本和频率必须与因子身份一致")
+        if (
+            spec is not None
+            and self.provenance_template is not None
+            and self.provenance_template.content_digest != spec.content_digest
+        ):
+            raise ValueError("因子定义摘要与计算规格不一致")
+        return self
+
+
+class FactorValue(BaseModel):
+    """长表一行（Q3=A）：一个 factor/instrument/as_of/version 的值
+
+    - as_of：因子值归属的业务时间（日频因子 = 交易日收盘口径时点）；
+    - available_at：策略最早可见时间（Q2=A：Tushare 日频因子缺权威发布时间时，
+      从下一交易日开盘起可读——由 Adapter 在入库前计算，本模型只强制
+      available_at >= as_of）；
+    - status 表达缺失/不可用/未发布；value 为 None，禁止 0 填充；
+    - 整行 frozen（R1-2）：FactorSnapshot 的 PIT 门禁在构造边界校验后，
+      行内字段（如 available_at）不得被事后修改——否则嵌套可变性会绕过
+      快照级校验造成未来值泄漏；修正必须以 model_copy 产生新行并重新过门。
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    identity: FactorIdentity = Field(..., description="因子逻辑身份")
+    instrument_id: str = Field(..., min_length=1, description="Canonical 标的 ID")
+    as_of: datetime = Field(..., description="归属业务时间")
+    available_at: datetime = Field(..., description="策略最早可见时间")
+    value: Decimal | None = Field(default=None, description="因子值；非 AVAILABLE 状态必须为 None")
+    status: FactorStatus = Field(..., description="值状态（缺失不用 0 表达）")
+    provenance: FactorProvenance = Field(..., description="血缘")
+
+    @field_validator("as_of", "available_at")
+    @classmethod
+    def _tzaware(cls, v: datetime) -> datetime:
+        return _require_tzaware("datetime", v)
+
+    @model_validator(mode="after")
+    def _value_status_consistency(self) -> "FactorValue":
+        if self.available_at < self.as_of:
+            raise ValueError(
+                f"available_at {self.available_at} 不得早于 as_of {self.as_of}"
+                "（可见时间不得早于归属业务时间）"
+            )
+        if self.status is FactorStatus.AVAILABLE and self.value is None:
+            raise ValueError("AVAILABLE 状态必须携带非 None value")
+        if self.status is not FactorStatus.AVAILABLE and self.value is not None:
+            raise ValueError(
+                f"status={self.status.value} 禁止携带 value {self.value}"
+                "（缺失/不可用/未发布不用数值伪装）"
+            )
+        return self
+
+    @property
+    def logical_key(self) -> tuple[str, str, str, FactorFrequency, str, datetime]:
+        """长表业务唯一键：identity + instrument_id + as_of（T2 唯一约束依据）"""
+        return (*self.identity.logical_key, self.instrument_id, self.as_of)
+
+    def _conflict_payload(self) -> tuple:
+        """判定两行是否同一事实的载荷（任一不同即冲突，禁止静默取舍）"""
+        return (self.value, self.status, self.available_at, self.provenance.model_dump_json())
+
+
+class FactorSnapshotSelection(BaseModel):
+    """创建截面时的不可变选择条件；覆盖报告只能解释同一组查询。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    identities: tuple[FactorIdentity, ...]
+    instrument_ids: tuple[str, ...]
+    target_as_of: date
+    freshness: FactorFreshness
+    dataset_revision: str | None = None
+
+
+class FactorSnapshot(BaseModel):
+    """某 decision_time 的因子横截面（Strategy/Selection 的只读消费形态）
+
+    point-in-time 门禁（模型边界自维护，AC-2 / Group 决策 6）：
+    - 任何 available_at > decision_time 的值在构造（或事后修改）时结构化拒绝——
+      查询侧不存在「事后泄漏」路径；
+    - 同一逻辑键重复：值完全一致 → 幂等去重；存在差异 → ValueError
+      （禁止静默 first/last wins，AC-3）；
+    - 行与身份均为 frozen（R1-2）：构造后不存在任何修改行内
+      available_at/status/value 的合法路径，PIT 门禁不可被嵌套可变性绕过；
+    - 行序确定性：按 (identity.logical_key, instrument_id, as_of) 稳定排序；
+    - 序列化确定性：to_canonical_json()（sorted keys、ISO 时间、Decimal 字符串）。
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    decision_time: datetime = Field(..., description="决策时点（point-in-time 门禁基准）")
+    values: tuple[FactorValue, ...] = Field(
+        default_factory=tuple, description="可读因子值（已排序去重）"
+    )
+    selection: FactorSnapshotSelection | None = Field(
+        default=None, description="查询选择上下文；手工构造截面不携带可验证覆盖范围"
+    )
+
+    @field_validator("decision_time")
+    @classmethod
+    def _tzaware_decision(cls, v: datetime) -> datetime:
+        return _require_tzaware("decision_time", v)
+
+    @model_validator(mode="after")
+    def _enforce_pit_and_uniqueness(self) -> "FactorSnapshot":
+        seen: dict[tuple, FactorValue] = {}
+        for v in self.values:
+            if v.available_at > self.decision_time:
+                raise ValueError(
+                    f"available_at {v.available_at} 晚于 decision_time "
+                    f"{self.decision_time}：未来可见的值不得进入 FactorSnapshot"
+                )
+            prev = seen.get(v.logical_key)
+            if prev is None:
+                seen[v.logical_key] = v
+            elif prev._conflict_payload() != v._conflict_payload():
+                raise ValueError(f"同一逻辑键 {v.logical_key} 出现冲突值，拒绝歧义快照")
+        # 绕过 validate_assignment 就地归一（避免校验器递归触发）；归一发生在
+        # 构造边界，事后只读消费无法再引入未过门的值
+        object.__setattr__(
+            self,
+            "values",
+            tuple(
+                sorted(
+                    seen.values(),
+                    key=lambda x: (x.identity.logical_key, x.instrument_id, x.as_of),
+                )
+            ),
+        )
+        return self
+
+    def to_canonical_json(self) -> str:
+        """确定性序列化（sorted keys + ISO 时间；Decimal 以字符串表达精度）"""
+        return json.dumps(
+            self.model_dump(mode="json"), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        )

quant_core/app/factor/schema/factor_input_schema.py

@@ -0,0 +1,32 @@
+"""本地面板输入需求；参与股票池与输出股票集合分别声明。"""
+
+from datetime import date
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+
+
+class FactorInputRequest(BaseModel):
+    """lookback 包含当前交易日；价格政策显式传入，不自动填充缺失行情。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    instrument_ids: tuple[str, ...] = Field(min_length=1)
+    start: date
+    end: date
+    exclude_st: bool = False
+    fields: tuple[str, ...] = Field(min_length=1)
+    lookback: int = Field(ge=1)
+    view: BarViewRequest
+    missing_policy: Literal["null", "error"] = "null"
+
+    @model_validator(mode="after")
+    def validate_request(self) -> "FactorInputRequest":
+        if self.start > self.end:
+            raise ValueError("输出开始日期晚于结束日期")
+        if len(set(self.instrument_ids)) != len(self.instrument_ids):
+            raise ValueError("参与股票池不能重复")
+        if len(set(self.fields)) != len(self.fields):
+            raise ValueError("输入字段不能重复")
+        return self

quant_core/app/factor/schema/factor_panel.py

@@ -0,0 +1,65 @@
+"""面板输入契约：统一字段与口径、逐行可见时间、历史股票池和修订证据。"""
+
+import hashlib
+import json
+from datetime import datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class FactorPanelRow(BaseModel):
+    """同一业务时点的一只证券；未入池行保留时序历史，但不参与横截面。"""
+
+    model_config = ConfigDict(frozen=True)
+    instrument_id: str = Field(min_length=1)
+    as_of: datetime
+    available_at: datetime
+    eligible: bool
+    fields: dict[str, Decimal | None]
+
+    @model_validator(mode="after")
+    def validate_row(self) -> "FactorPanelRow":
+        for value in (self.as_of, self.available_at):
+            if value.utcoffset() is None:
+                raise ValueError("面板时间必须带时区")
+        if self.available_at < self.as_of:
+            raise ValueError("输入可见时间不得早于业务时间")
+        if any(value is not None and not value.is_finite() for value in self.fields.values()):
+            raise ValueError("面板字段必须为有限数值或缺值")
+        return self
+
+
+class FactorPanel(BaseModel):
+    """一次计算的不可变输入快照；股票池及价格口径参与身份绑定和摘要。"""
+
+    model_config = ConfigDict(frozen=True)
+    decision_time: datetime
+    frequency: str = "1d"
+    price_basis: str = Field(min_length=1)
+    universe_ref: str = Field(min_length=1)
+    universe_revision: str = Field(min_length=1)
+    market_revision: str = Field(min_length=1)
+    units: dict[str, str]
+    rows: tuple[FactorPanelRow, ...]
+
+    @model_validator(mode="after")
+    def validate_panel(self) -> "FactorPanel":
+        if self.decision_time.utcoffset() is None:
+            raise ValueError("面板决策时间必须带时区")
+        keys = [(row.as_of, row.instrument_id) for row in self.rows]
+        if len(keys) != len(set(keys)):
+            raise ValueError("面板不能包含重复业务时间与证券")
+        if any(row.available_at > self.decision_time for row in self.rows):
+            raise ValueError("面板包含决策时点尚不可见的输入")
+        if any(set(row.fields) - self.units.keys() for row in self.rows):
+            raise ValueError("每个面板输入字段都必须声明单位")
+        return self
+
+    @property
+    def input_digest(self) -> str:
+        payload = self.model_dump(mode="json")
+        payload["rows"] = sorted(
+            payload["rows"], key=lambda row: (row["as_of"], row["instrument_id"])
+        )
+        return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()

quant_core/app/factor/schema/factor_publication_schema.py

@@ -0,0 +1,41 @@
+"""可离线执行的已发布因子定义文件，摘要需在读取时校验。"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from quant_core.app.factor.constants import LOCAL_FACTOR_SOURCE, FactorDefinitionStatus
+from quant_core.app.factor.schema.factor_contract import FactorDefinition
+
+
+class PublishedFactor(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    format_version: Literal[1] = 1
+    definition: FactorDefinition
+    content_digest: str
+
+    @model_validator(mode="after")
+    def verify(self) -> "PublishedFactor":
+        spec = self.definition.computation_spec
+        if spec is None or spec.status != FactorDefinitionStatus.APPROVED:
+            raise ValueError("需要已发布且可执行的因子定义")
+        if spec.version == "latest" or spec.content_digest != self.content_digest:
+            raise ValueError("因子版本未固定或文件摘要不匹配")
+        identity = self.definition.identity
+        provenance = self.definition.provenance_template
+        if (
+            identity.source != LOCAL_FACTOR_SOURCE
+            or self.definition.lookback != spec.lookback
+            or provenance is None
+            or provenance.content_digest != self.content_digest
+        ):
+            raise ValueError("因子来源、窗口或血缘摘要不匹配")
+        if (identity.name, identity.definition_version, identity.frequency) != (
+            spec.name,
+            spec.version,
+            spec.frequency,
+        ):
+            raise ValueError("因子身份与计算定义不匹配")
+        if spec.validate_definition():
+            raise ValueError("因子定义结构非法")
+        return self

quant_core/app/factor/schema/factor_query_result_schema.py

@@ -0,0 +1,12 @@
+"""因子时点查询状态探查的结果值。"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from quant_core.app.factor.constants import FactorStatus
+
+
+@dataclass(frozen=True)
+class ProbeCellStatus:
+    statuses: frozenset[FactorStatus]
+    latest_as_of: datetime | None = None

quant_core/app/factor/schema/factor_result_schema.py

@@ -0,0 +1,6 @@
+"""因子面板数值契约。"""
+
+from datetime import datetime
+from decimal import Decimal
+
+PanelValues = dict[tuple[datetime, str], Decimal | None]

quant_core/app/factor/schema/local_factor_schema.py

@@ -0,0 +1,42 @@
+"""本地因子运行请求：所有输入显式指定，不依赖管理库。"""
+
+from datetime import date
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+from quant_core.app.factor.schema.factor_publication_schema import PublishedFactor
+
+
+class LocalFactorRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    source: str = ""
+    definitions: tuple[PublishedFactor, ...] = ()
+    manifest_path: Path
+    instrument_ids: tuple[str, ...]
+    start: date
+    end: date
+    exclude_st: bool = False
+    view: BarViewRequest = Field(default_factory=BarViewRequest)
+    max_rows: int = Field(default=1000000, ge=1)
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "LocalFactorRequest":
+        if bool(self.source) == bool(self.definitions):
+            raise ValueError("必须且只能提供本地源码或已发布定义")
+        if len({item.definition.identity.name for item in self.definitions}) != len(
+            self.definitions
+        ):
+            raise ValueError("单次计算不能包含同名多版本；分别计算后按策略别名绑定")
+        if self.start > self.end or not self.instrument_ids:
+            raise ValueError("需指定合法范围和非空股票池")
+        if len(set(self.instrument_ids)) != len(self.instrument_ids):
+            raise ValueError("股票池不得重复")
+        return self
+
+    @field_validator("manifest_path")
+    @classmethod
+    def absolute_manifest(cls, value: Path) -> Path:
+        """归档固定路径，避免重启后工作目录变化影响定位。"""
+        return value.expanduser().resolve()

quant_core/app/factor/schema/panel_policy.py

@@ -0,0 +1,13 @@
+"""当前行情面板的公开口径标识，复用 Canonical 股与人民币单位。"""
+
+import hashlib
+
+PRICE_BASIS = "pre-next-open"
+PANEL_UNITS = {name: "CNY/share" for name in ("open", "high", "low", "close", "vwap")}
+PANEL_UNITS.update({"volume": "share", "amount": "CNY"})
+
+
+def listed_roster_ref(instrument_ids: tuple[str, ...]) -> str:
+    """固定候选集合叠加逐日上市/退市门禁；不声称是历史指数成分。"""
+    digest = hashlib.sha256("\n".join(sorted(set(instrument_ids))).encode()).hexdigest()
+    return f"listed-roster:{digest}"