infinity-data 1.0.0__py3-none-any.whl

infinity_data/semantic/constraints.py

@@ -0,0 +1,163 @@
+"""约束解析：RawAst 约束 → :class:`ResolvedConstraint`（挂在 StdAst 节点上）。
+
+纯函数、无副作用：解析约束 AST（名字经 scope 翻译为真名、参数求值），
+返回 ``(specs, diagnostics)``——``ErrorConstraint`` 的诊断在此收集返回，
+不直接写入任何收集器（调用方自行并入）。
+
+约束**只解析不执行**：执行由 :class:`ConstraintExecutor`（Phase 2b）完成。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from infinity_data.infra.diagnostics import Diagnostic, Severity
+from infinity_data.parser import (
+    Constraint,
+    ConstraintCall,
+    ConstraintIdent,
+    ConstraintLiteral,
+    Constraints,
+    ErrorConstraint,
+    LiteralValue,
+)
+from infinity_data.semantic.builder.models import ResolvedConstraint
+from infinity_data.semantic.resolver.models import Scope
+from infinity_data.tokenizer.models.tokens import (
+    BoolToken,
+    FloatToken,
+    IntegerToken,
+    NoexistToken,
+    NullToken,
+    StringToken,
+)
+
+_INVALID_CONSTRAINT = '@invalid'
+
+
+def expand_annotation(annotation: Constraints) -> Constraints:
+    """展开约束语法糖：多约束 ``<a, b, c>`` → ``all(a, b, c)``。
+
+    （``type?`` → ``one(type, ?)`` 已在 parser 阶段展开。）
+    """
+    if len(annotation.constraints) > 1:
+        return Constraints(
+            source=annotation.source,
+            constraints=[
+                ConstraintCall(
+                    source=annotation.source,
+                    name='all',
+                    arguments=list(annotation.constraints),
+                ),
+            ],
+        )
+    return annotation
+
+
+def resolve_constraints(
+    annotation: Constraints,
+    scope: Scope,
+) -> tuple[list[ResolvedConstraint], list[Diagnostic]]:
+    """解析字段注解约束链（语法糖展开 → 逐约束解析），返回 ``(specs, diagnostics)``。"""
+    expanded = expand_annotation(annotation)
+    specs: list[ResolvedConstraint] = []
+    diags: list[Diagnostic] = []
+    for c in expanded.constraints:
+        spec, ds = resolve_constraint(c, scope)
+        specs.append(spec)
+        diags.extend(ds)
+    return specs, diags
+
+
+def resolve_constraint_list(
+    constraints: list[Constraint],
+    scope: Scope,
+) -> tuple[list[ResolvedConstraint], list[Diagnostic]]:
+    """解析结构级约束列表（dict 级 / 模板级 / 顶层 ``: <...>``），逐个解析。
+
+    与字段注解（:class:`Constraints`）不同，结构约束已是展开后的列表：
+    多约束是否合成 ``all`` 由 parser 决定，此处不再次展开。
+    """
+    specs: list[ResolvedConstraint] = []
+    diags: list[Diagnostic] = []
+    for c in constraints:
+        spec, ds = resolve_constraint(c, scope)
+        specs.append(spec)
+        diags.extend(ds)
+    return specs, diags
+
+
+def resolve_constraint(c: Constraint, scope: Scope) -> tuple[ResolvedConstraint, list[Diagnostic]]:
+    """解析单个约束 AST（名字经 scope 翻译为真名）。"""
+    match c:
+        case ConstraintIdent(name=n):
+            return ResolvedConstraint(name=translate_name(n, scope), source=c.source), []
+        case ConstraintCall(name=n, arguments=args):
+            resolved_args: list[Any] = []
+            diags: list[Diagnostic] = []
+            for a in args:
+                arg, ds = resolve_constraint_arg(a, scope)
+                resolved_args.append(arg)
+                diags.extend(ds)
+            return (
+                ResolvedConstraint(name=translate_name(n, scope), args=resolved_args, source=c.source),
+                diags,
+            )
+        case ConstraintLiteral():
+            return ResolvedConstraint(name=_INVALID_CONSTRAINT, source=c.source), []
+        case ErrorConstraint(message=m):
+            return (
+                ResolvedConstraint(name=_INVALID_CONSTRAINT, source=c.source),
+                [Diagnostic(Severity.ERROR, 'error.generic', {'message': m}, c.source)],
+            )
+    return ResolvedConstraint(name=_INVALID_CONSTRAINT), []
+
+
+def resolve_constraint_arg(c: Constraint, scope: Scope) -> tuple[Any, list[Diagnostic]]:
+    """解析约束参数：嵌套约束 → ResolvedConstraint；字面量 → Python 值。"""
+    match c:
+        case ConstraintIdent(name=n):
+            return ResolvedConstraint(name=translate_name(n, scope), source=c.source), []
+        case ConstraintCall(name=n, arguments=args):
+            resolved_args: list[Any] = []
+            diags: list[Diagnostic] = []
+            for a in args:
+                arg, ds = resolve_constraint_arg(a, scope)
+                resolved_args.append(arg)
+                diags.extend(ds)
+            return (
+                ResolvedConstraint(name=translate_name(n, scope), args=resolved_args, source=c.source),
+                diags,
+            )
+        case ConstraintLiteral(value=lit):
+            return literal_python_value(lit), []
+        case ErrorConstraint(message=m):
+            return (
+                ResolvedConstraint(name=_INVALID_CONSTRAINT, source=c.source),
+                [Diagnostic(Severity.ERROR, 'error.generic', {'message': m}, c.source)],
+            )
+    return ResolvedConstraint(name=_INVALID_CONSTRAINT), []
+
+
+def translate_name(name: str, scope: Scope) -> str:
+    """可见名 → 真名字符串。未命中（如 has(field) 的裸字段名）保留原名。"""
+    key = scope.get(name)
+    return str(key) if key is not None else name
+
+
+def literal_python_value(lit: LiteralValue) -> Any:
+    """约束参数字面量 → Python 值。"""
+    match lit.value:
+        case IntegerToken(value=v):
+            return v
+        case FloatToken(value=v):
+            return v
+        case BoolToken(value=v):
+            return v
+        case StringToken(value=v):
+            return v
+        case NullToken():
+            return None
+        case NoexistToken():
+            return None
+    return None

infinity_data/semantic/diagnostics.py

@@ -0,0 +1,172 @@
+"""语义分析阶段诊断定义（集中注册）。
+
+语义层的全部诊断定义（``template.*`` / ``constraint.*`` / ``field.*`` /
+``value.*`` / ``dollar.*`` / ``import.*`` / ``namespace.*`` 等）在此集中，
+导入时经 :func:`register_diagnostic_define` 合并进全局注册表。
+
+与词法（``tokenizer/diagnostics.py``）、语法（``parser/diagnostics.py``）一致：
+**每层一个诊断词汇表文件**，便于审计与多语言维护。
+"""
+
+from infinity_data.infra.diagnostics import diagnostic_define, register_diagnostic_define
+
+register_diagnostic_define(
+    # ═══════════════════════════════════════════════════════════
+    # 模板
+    # ═══════════════════════════════════════════════════════════
+    diagnostic_define(
+        'template.shadows_builtin',
+        '{path_prefix}模板 {template!r} 与内置约束同名，禁止定义（避免遮蔽 {template} 约束）',
+    ),
+    diagnostic_define(
+        'template.duplicate', '{path_prefix}模板 {template!r} 重复定义（同一文件内不允许同名模板），后者被拒绝'
+    ),
+    diagnostic_define(
+        'template.required_order', '{path_prefix}模板 {template!r} 中必填字段 {field!r} 出现在可选字段之后'
+    ),
+    diagnostic_define('template.import_depth', '{path_prefix}模板导入嵌套深度超过上限 {max}: {path_src}'),
+    diagnostic_define('template.read_failed', '{path_prefix}读取模板文件失败 {file}: {error}'),
+    diagnostic_define(
+        'template.recursive_default',
+        '{path_prefix}模板 {template!r} 的默认值形成递归引用（默认值禁止自引用，展开会无限循环）',
+        en='{path_prefix}template {template!r} has a recursive default (self-reference in defaults is forbidden; expansion would loop forever)',
+    ),
+    diagnostic_define('template.import_not_found', '{path_prefix}导入文件中不存在模板 {template!r}'),
+    diagnostic_define('template.import_conflict_local', '{path_prefix}导入的模板 {visible!r} 与文件内定义冲突'),
+    diagnostic_define(
+        'template.import_duplicate',
+        '{path_prefix}可见名 {visible!r} 重复导入（同一 scope 内不允许重复可见名），后者被拒绝',
+    ),
+    diagnostic_define(
+        'template.undefined',
+        '{path_prefix}未定义的模板 {template!r}',
+        en='{path_prefix}undefined template: {template!r}',
+    ),
+    diagnostic_define(
+        'template.missing_required',
+        '{path_prefix}模板 {template!r} 的必填字段 {field!r} 未提供',
+        en='{path_prefix}required field {field!r} of template {template!r} is missing',
+    ),
+    diagnostic_define(
+        'template.arg_conflict', '{path_prefix}模板 {template!r} 字段 {field!r} 同时以位置和命名参数提供'
+    ),
+    diagnostic_define(
+        'template.too_many_positional',
+        '{path_prefix}模板 {template!r} 只有 {count} 个必填字段，提供了 {given} 个位置参数',
+    ),
+    diagnostic_define(
+        'template.positional_disabled',
+        '{path_prefix}模板 {template!r} 禁用位置参数，请使用命名参数',
+        en='{path_prefix}template {template!r} disables positional arguments; use named arguments',
+    ),
+    diagnostic_define(
+        'template.unknown_argument',
+        '{path_prefix}模板 {template!r} 收到未知命名参数 {arg!r}',
+        en='{path_prefix}template {template!r} received unknown named argument {arg!r}',
+    ),
+    diagnostic_define('template.expect_value', '{path_prefix}期望 {template}（模板约束），实际没有值'),
+    diagnostic_define('template.expect_object', '{path_prefix}期望 {template}（对象），实际 {actual}'),
+    diagnostic_define(
+        'template.null_use_nullable', '{path_prefix}期望 {template}，实际 null（使用 {template}? 允许可空）'
+    ),
+    diagnostic_define('template.extra_field', '{path_prefix}模板 {template} 不允许额外字段 {field!r}'),
+    diagnostic_define('template.missing_field', '{path_prefix}模板 {template} 的必填字段 {field!r} 缺失'),
+    # ═══════════════════════════════════════════════════════════
+    # 字段 / 值 / $ 引用
+    # ═══════════════════════════════════════════════════════════
+    diagnostic_define(
+        'field.missing_value',
+        '{path_prefix}字段缺少值（如需 noexist 请显式书写 = noexist）',
+        en='{path_prefix}field is missing a value (write = noexist explicitly if intended)',
+    ),
+    diagnostic_define('value.nesting_depth', '{path_prefix}嵌套层级超过上限 {max}'),
+    diagnostic_define(
+        'value.noexist_in_array',
+        '{path_prefix}noexist 仅用于 dict 字段，数组元素中无意义（如需空位请用 null）',
+        en='{path_prefix}noexist is only for dict fields; meaningless in array elements (use null for a slot)',
+    ),
+    diagnostic_define(
+        'dollar.undefined', '{path_prefix}未找到导入变量 ${name}', en='{path_prefix}undefined import variable ${name}'
+    ),
+    diagnostic_define(
+        'dollar.convert_failed',
+        '{path_prefix}无法将 ${name}={raw!r} 转为 {type}',
+        en='{path_prefix}cannot convert ${name}={raw!r} to {type}',
+    ),
+    diagnostic_define('inft.not_allowed', '{path_prefix}.inft 文件只允许模板定义，发现其他语句'),
+    diagnostic_define('error.generic', '{path_prefix}{message}'),
+    # ═══════════════════════════════════════════════════════════
+    # 约束引擎
+    # ═══════════════════════════════════════════════════════════
+    diagnostic_define('constraint.invalid', '{path_prefix}无效的约束表达式'),
+    diagnostic_define('constraint.unknown', '{path_prefix}未知约束 {name!r}'),
+    diagnostic_define('constraint.arg_count', '{path_prefix}约束 {name}() 期望 {expected} 个参数，实际 {given} 个'),
+    diagnostic_define(
+        'constraint.expect_value',
+        '{path_prefix}期望 {expected}，实际没有值',
+        en='{path_prefix}expected {expected}, got no value',
+    ),
+    diagnostic_define(
+        'constraint.type_mismatch',
+        '{path_prefix}期望 {expected}，实际 {actual}',
+        en='{path_prefix}expected {expected}, got {actual}',
+    ),
+    diagnostic_define('constraint.numeric_only', '{path_prefix}{constraint} 约束只适用于数值，实际 {actual}'),
+    diagnostic_define('constraint.nan_not_allowed', '{path_prefix}{constraint} 约束不适用于 NaN'),
+    diagnostic_define('constraint.range_arg', '{path_prefix}range 参数必须是数值: {value!r}'),
+    diagnostic_define(
+        'constraint.range_below',
+        '{path_prefix}值 {value} 小于下界 {lo}',
+        en='{path_prefix}value {value} is below lower bound {lo}',
+    ),
+    diagnostic_define(
+        'constraint.range_above',
+        '{path_prefix}值 {value} 大于上界 {hi}',
+        en='{path_prefix}value {value} exceeds upper bound {hi}',
+    ),
+    diagnostic_define('constraint.size_only', '{path_prefix}size 约束适用于 str/list/dict，实际 {actual}'),
+    diagnostic_define('constraint.size_arg', '{path_prefix}size 参数必须是整数'),
+    diagnostic_define('constraint.size_out', '{path_prefix}大小 {size} 不在范围 [{lo}, {hi}] 内'),
+    diagnostic_define('constraint.each_need', '{path_prefix}each() 需要一个约束参数'),
+    diagnostic_define('constraint.each_only', '{path_prefix}each 约束适用于 list/dict，实际 {actual}'),
+    diagnostic_define('constraint.in_not_in', '{path_prefix}值 {value} 不在允许的值 {choices!r} 中'),
+    diagnostic_define('constraint.string_only', '{path_prefix}{constraint} 约束只适用于字符串'),
+    diagnostic_define('constraint.invalid_value', '{path_prefix}无效的{what} {value!r}'),
+    diagnostic_define('constraint.regex_no_match', '{path_prefix}值 {value!r} 不匹配正则 {pattern!r}'),
+    diagnostic_define('constraint.regex_invalid', '{path_prefix}无效的正则表达式 {pattern!r}: {error}'),
+    diagnostic_define('constraint.positive_fail', '{path_prefix}值 {value} 不是正数'),
+    diagnostic_define('constraint.negative_fail', '{path_prefix}值 {value} 不是负数'),
+    diagnostic_define('constraint.nonnegative_fail', '{path_prefix}值 {value} 是负数'),
+    diagnostic_define(
+        'constraint.eq_mismatch',
+        '{path_prefix}值 {value} 不等于 {expected!r}',
+        en='{path_prefix}value {value} does not equal {expected!r}',
+    ),
+    diagnostic_define('constraint.unique_only', '{path_prefix}unique 约束只适用于 list'),
+    diagnostic_define('constraint.unique_dup', '{path_prefix}元素 {value} 重复'),
+    diagnostic_define('constraint.has_only', '{path_prefix}has 约束只适用于 dict'),
+    diagnostic_define('constraint.has_missing', '{path_prefix}缺少键 {key!r}'),
+    diagnostic_define('constraint.field_only', '{path_prefix}field 约束只适用于 dict'),
+    diagnostic_define('constraint.field_need', '{path_prefix}field() 的第二个参数必须是约束'),
+    diagnostic_define('constraint.field_missing', '{path_prefix}字段 {field!r} 不存在'),
+    diagnostic_define('constraint.not_need', '{path_prefix}not() 需要一个约束参数'),
+    diagnostic_define('constraint.not_fail', '{path_prefix}not 约束失败（内部约束意外满足）'),
+    diagnostic_define('constraint.any_fail', '{path_prefix}any 约束失败（所有子约束都不满足）'),
+    diagnostic_define('constraint.one_none', '{path_prefix}one 约束失败（没有子约束被满足）'),
+    diagnostic_define('constraint.one_many', '{path_prefix}one 约束失败（{count} 个子约束被满足: {names}）'),
+    diagnostic_define('constraint.all_fail', '{path_prefix}all 约束失败'),
+    diagnostic_define('constraint.when_need', '{path_prefix}when() 需要两个约束参数'),
+    # ═══════════════════════════════════════════════════════════
+    # 导入
+    # ═══════════════════════════════════════════════════════════
+    diagnostic_define('import.file_denied', '{path_prefix}文件导入超出沙盒授权，已忽略: {path_src}'),
+    diagnostic_define('import.file_missing', '{path_prefix}导入文件不存在: {name}'),
+    diagnostic_define('import.path_failed', '{path_prefix}无法解析导入路径: {name}'),
+    diagnostic_define('import.template_denied', '{path_prefix}模板导入超出沙盒授权，已忽略: {path_src}'),
+    diagnostic_define('import.yaml_missing', '{path_prefix}yaml 支持需要安装 PyYAML'),
+    diagnostic_define('import.unsupported_format', '{path_prefix}不支持的文件格式: {format}'),
+    diagnostic_define('import.parse_failed', '{path_prefix}解析数据失败: {error}'),
+    diagnostic_define(
+        'namespace.duplicate', '{path_prefix}导入别名 {name!r} 重复绑定（$ 命名空间内不允许重复），后者被拒绝'
+    ),
+)

infinity_data/semantic/executor/__init__.py

@@ -0,0 +1,10 @@
+"""Phase 2b（约束执行器）：遍历 StdAst 执行约束 + 顶层 schema 校验。
+
+- :class:`ConstraintExecutor`：消费 Phase 2a 产出的标准 AST（executor.py）
+
+子模块导出自身类，供流水线（pipeline / 测试）直接引用。
+"""
+
+from infinity_data.semantic.executor.executor import ConstraintExecutor
+
+__all__ = ['ConstraintExecutor']

infinity_data/semantic/executor/executor.py

@@ -0,0 +1,259 @@
+"""约束执行器（Phase 2b）：遍历已完成 StdAst，执行节点携带的约束。
+
+约束器**工作在 AST 上**（不参与构建）：
+
+- 递归遍历 :class:`StdField` / :class:`StdObject` / :class:`StdArray`，
+  执行节点携带的 :class:`ResolvedConstraint`
+  （字段注解 / dict 结构级 / 模板级 / 顶层结构约束）
+- 「模板即约束」：约束名为模板真名时，查模板表做结构校验（手写 dict）
+- **只校验、不转换**：约束失败仅产出诊断，不改变值（coercion 属错误设计）
+- 顶层 schema 校验（strict/lenient/strip）也在此：
+  对顶层对象执行模板约束 + 额外字段策略
+
+本层消费 Phase 2a 数据模型（:class:`StdDocument` 等），与构建器零耦合；
+诊断写入调用方注入的共享 :class:`DiagnosticCollector`（流水线单一收集器）。
+"""
+
+from __future__ import annotations
+
+from infinity_data.infra.diagnostics import Diagnostic, DiagnosticCollector, Severity
+from infinity_data.parser import TemplateDef
+from infinity_data.sandbox import Schema, SchemaError
+from infinity_data.semantic.builder.models import (
+    ResolvedConstraint,
+    StdArray,
+    StdField,
+    StdLiteral,
+    StdObject,
+    StdValue,
+)
+from infinity_data.semantic.constraints import resolve_constraint_list, resolve_constraints
+from infinity_data.semantic.registry import (
+    ConstraintRegistry,
+    ConstraintResult,
+    describe,
+    fail_result,
+    ok_result,
+)
+from infinity_data.semantic.resolver.models import Scope, TemplateKey
+from infinity_data.tokenizer.models.raw_tokens import SourceRange
+
+_INVALID_CONSTRAINT = '@invalid'
+
+
+class ConstraintExecutor:
+    """工作在已完成 StdAst 上的约束遍历器：节点约束 → 诊断（只校验，不转换）。"""
+
+    def __init__(
+        self,
+        *,
+        registry: ConstraintRegistry,
+        templates: dict[TemplateKey, TemplateDef],
+        template_scopes: dict[TemplateKey, Scope],
+    ) -> None:
+        self._registry = registry
+        self._templates = templates
+        self._template_scopes = template_scopes
+        self._templates_by_name: dict[str, TemplateKey] = {str(k): k for k in templates}
+
+    # ═══════════════════════════════════════════════════════
+    # 遍历入口
+    # ═══════════════════════════════════════════════════════
+
+    def validate(self, node: StdValue, collector: DiagnosticCollector, path: str = '') -> None:
+        """递归遍历节点，执行携带的约束，诊断写入 ``collector``（不修改值）。"""
+        if isinstance(node, StdObject):
+            for f in node.fields:
+                self._validate_field(f, collector, path)
+            # 结构级约束（dict 级 / 模板级 / 顶层）：全部执行（不短路）
+            for spec in node.constraints:
+                result = self._exec(spec, node, spec.source, path)
+                if not result.ok:
+                    collector.extend(result.diagnostics)
+        elif isinstance(node, StdArray):
+            for i, elem in enumerate(node.elements):
+                self.validate(elem, collector, f'{path}[{i}]')
+
+    def _validate_field(self, field: StdField, collector: DiagnosticCollector, path: str) -> None:
+        """字段：先递归值（内部结构约束），再执行字段注解约束（链式短路）。"""
+        child = f'{path}.{field.name}' if path else field.name
+        if field.value is not None:
+            self.validate(field.value, collector, child)
+        for spec in field.constraints:
+            result = self._exec(spec, field.value, spec.source or field.source, child)
+            if not result.ok:
+                collector.extend(result.diagnostics)
+                break  # 约束链短路（与构建期语义一致）
+
+    # ═══════════════════════════════════════════════════════
+    # 约束执行
+    # ═══════════════════════════════════════════════════════
+
+    def _exec(
+        self,
+        constraint: ResolvedConstraint,
+        value: StdValue | None,
+        source: SourceRange | None,
+        path: str,
+    ) -> ConstraintResult:
+        """执行单个已解析约束；模板真名 → 模板结构校验；其余 → registry。
+
+        签名与 :class:`Executor` 协议一致（嵌套约束回调复用本方法）。
+        """
+        if constraint.name == _INVALID_CONSTRAINT:
+            return fail_result('constraint.invalid', {}, source, path)
+        key = self._templates_by_name.get(constraint.name)
+        if key is not None:
+            return self._check_template(key, value, source, path)
+        return self._registry.apply(constraint, value, constraint.source or source, path, self._exec)
+
+    def _check_template(
+        self,
+        key: TemplateKey,
+        value: StdValue | None,
+        source: SourceRange | None,
+        path: str,
+    ) -> ConstraintResult:
+        """模板即约束：校验手写 dict 是否符合模板声明（含字段 / 模板级约束）。"""
+        tpl = self._templates[key]
+        display = key.name
+        scope = self._template_scopes[key]
+        allow_extra = tpl.config.allow_extra
+        declared = {tf.name for tf in tpl.fields}
+
+        if value is None:
+            return fail_result('template.expect_value', {'template': display}, source, path)
+        if isinstance(value, StdLiteral):
+            if value.kind == 'null':
+                return fail_result('template.null_use_nullable', {'template': display}, source, path)
+            return fail_result('template.expect_object', {'template': display, 'actual': describe(value)}, source, path)
+        if not isinstance(value, StdObject):
+            return fail_result('template.expect_object', {'template': display, 'actual': describe(value)}, source, path)
+
+        # 标记来源模板：这个手写 dict 被判定为模板 display 的结构（供下游引用）
+        if value.template is None:
+            value.template = key
+
+        diags: list[Diagnostic] = []
+        field_map = {f.name: f for f in value.fields}
+
+        # 逐字段校验（模板定义约束）
+        for tf in tpl.fields:
+            child = f'{path}.{tf.name}' if path else tf.name
+            f = field_map.get(tf.name)
+            if f is None:
+                if tf.default_value is None:
+                    diags.append(
+                        Diagnostic(
+                            Severity.ERROR,
+                            'template.missing_field',
+                            {'template': display, 'field': tf.name},
+                            source,
+                            child,
+                        )
+                    )
+                continue
+            if f.value is not None:
+                specs, rdiags = resolve_constraints(tf.constraints, scope)
+                diags.extend(rdiags)
+                for spec in specs:
+                    result = self._exec(spec, f.value, tf.source, child)
+                    if not result.ok:
+                        diags.extend(result.diagnostics)
+                        break
+
+        # 严格模式：不允许额外字段（allow_extra=true 时放行）
+        if not allow_extra:
+            for f in value.fields:
+                if f.name not in declared:
+                    child = f'{path}.{f.name}' if path else f.name
+                    diags.append(
+                        Diagnostic(
+                            Severity.ERROR,
+                            'template.extra_field',
+                            {'template': display, 'field': f.name},
+                            f.source or source,
+                            child,
+                        )
+                    )
+
+        # 模板级约束
+        specs, rdiags = resolve_constraint_list(tpl.constraints, scope)
+        diags.extend(rdiags)
+        for spec in specs:
+            result = self._exec(spec, value, source, path)
+            if not result.ok:
+                diags.extend(result.diagnostics)
+
+        if diags:
+            return ConstraintResult(ok=False, diagnostics=diags)
+        return ok_result()
+
+    # ═══════════════════════════════════════════════════════
+    # 顶层 schema 校验
+    # ═══════════════════════════════════════════════════════
+
+    def apply_schema(
+        self,
+        root: StdObject,
+        schema: Schema,
+        tpl: TemplateDef,
+        scope: Scope,
+        collector: DiagnosticCollector,
+    ) -> StdObject:
+        """按模板校验顶层对象（strict/lenient/strip），返回校验后的 root。
+
+        - lenient 的额外字段 WARNING 写入 ``collector``（非致命）
+        - strict / 必填缺失 / 字段 / 模板级约束失败聚合为 :class:`SchemaError` 抛出
+        """
+        mode = schema.mode
+        declared = {tf.name for tf in tpl.fields}
+        diags: list[Diagnostic] = []
+
+        # 额外字段处理（模式差异）
+        extra_names = [f.name for f in root.fields if f.name not in declared]
+        if extra_names:
+            if mode == 'strict':
+                diags.append(Diagnostic(Severity.ERROR, 'schema.extra_fields', {'fields': extra_names}, None))
+            elif mode == 'lenient':
+                collector.add(
+                    Diagnostic(Severity.WARNING, 'schema.extra_fields_lenient', {'fields': extra_names}, None)
+                )
+            else:  # strip
+                root = StdObject(fields=[f for f in root.fields if f.name in declared], template=root.template)
+
+        # 必填字段缺失
+        for tf in tpl.fields:
+            if tf.default_value is None and root.get(tf.name) is None:
+                diags.append(
+                    Diagnostic(
+                        Severity.ERROR,
+                        'schema.missing_required',
+                        {'field': tf.name, 'template': tpl.name},
+                        None,
+                        tf.name,
+                    )
+                )
+
+        # 字段约束校验
+        for tf in tpl.fields:
+            f = root.get(tf.name)
+            if f is not None and f.value is not None:
+                specs, rdiags = resolve_constraints(tf.constraints, scope)
+                diags.extend(rdiags)
+                for spec in specs:
+                    result = self._exec(spec, f.value, tf.source, tf.name)
+                    if not result.ok:
+                        diags.extend(result.diagnostics)
+
+        # 模板级约束
+        specs, rdiags = resolve_constraint_list(tpl.constraints, scope)
+        diags.extend(rdiags)
+        for spec in specs:
+            result = self._exec(spec, root, None, '')
+            if not result.ok:
+                diags.extend(result.diagnostics)
+
+        if diags:
+            raise SchemaError('schema.failed', {'detail': '；'.join(d.message for d in diags)})
+        return root