01-EFT.WP.Core.Terms v1.0 | 第8章 实现绑定接口

目录 ／ 文档-技术白皮书 ／ 01-EFT.WP.Core.Terms v1.0

第8章 实现绑定接口

I. 章目标与范围

• 给出 I10-1 … I10-7 的可执行接口规范、参数语义、错误码与最小工作序列（MWE），保证文本口径与实现落地一致。
• 统一返回结构、标识规则与版本语义；所有公式、符号、定义均为英文且遵循纯文本与括号规则（见 本卷 第1章、第7章）。

II. 通用约定与返回结构

1. 标识与版本
   • IRef def= opaque identifier with fields {id, version, hash, created_at}；version 采用 major.minor.patch。
   • hash def= content-addressable digest（例如 sha256 的前 16 字符）；用于去重与追溯。
2. 结果与错误结构
   • Ok<T> = { ok: true, data: T }
   • Err = { ok: false, code: E10-xxx, message: str, hint: str, see: list[str] }
3. 字符与符号规范
   术语 name/code/definition 严禁中文与全角标点；允许字符集：A–Z a–z 0–9 _ [] () / * + - ^ , : ; . space。
4. 并发与幂等
   所有 register_* 与 add_alias 幂等：重复提交同一 hash 返回同一 IRef。
5. 跨卷引用
   引用字段 see 仅接受规范锚点：["P70-4","Core.Equations:Sxx-3","Metrology.Path:M1-2"]。

III. I10-1 术语注册（register_term）

1. Signature
   register_term(name: str, code: str, type: str, unit: str|None, definition: str, constraints: list[str], see: list[str]) -> IRef
2. Type 枚举（v1.0）
   {scalar, field, operator, path, constant, object, medium}（相较初稿新增 object, medium；向后兼容）。
3. 字段口径
   • name 人类可读名（英文）；code 唯一短码（如 T_fil, n_eff）；definition 以 def= 口吻定义英文语句。
   • unit 若为无量纲可设 None 或 "dimensionless"；量纲在 I10-3 注册。
   • constraints 列出使用边界（如 "must not mix with T_trans"）。
4. 错误码
   • E10-101 NameInvalid（含非允许字符或中文）
   • E10-102 CodeConflict（code 已被不同语义占用）
   • E10-103 TypeUnknown（不在枚举内）
   • E10-104 UnitUnregistered（引用未注册单位；见 I10-3）
5. 合规要点
   n_eff 与 n 禁止同义注册（见 P70-2）；T_fil 与 T_trans 语义互斥（见 P70-1）。

IV. I10-2 别名与规范化（add_alias / normalize_symbol）

1. Signature
   • add_alias(canonical: str, alias: str) -> None
   • normalize_symbol(token: str) -> canonical: str
2. 规则
   • 一对多允许，多对一拒绝（避免歧义）；别名链被压缩到规范名。
   • 禁止环与自指；禁止将禁用符号（如 c, T, n）设为别名（见 P70-*）。
3. 错误码
   • E10-201 CanonicalMissing
   • E10-202 AliasConflict
   • E10-203 ForbiddenAlias

V. I10-3 单位与量纲（register_unit / check_dim）

1. Signature
   • register_unit(name: str, base: str, scale: float, dim: str) -> None
   • check_dim(expr: str) -> dim: str
2. 量纲语法
   dim ::= "[" L^a T^b M^c "]"，指数取整数或有理数；无量纲记为 "[T^0]" 或 "dimensionless"。
3. 内置派生规则
   • dim[grad[f]] = dim[f] [L^-1]，dim[lap[f]] = dim[f] [L^-2]，dim[d ell] = [L]。
   • dim[( n_eff / c_ref ) * d ell] = [T^0]；∫_gamma (...) d ell -> [T] 对应 T_arr。
4. 错误码
   • E10-301 UnitExistsWithDifferentDim
   • E10-302 DimParseError
   • E10-303 DimMismatch
5. 示例
   • register_unit("meter","SI",1.0,"[L]")；register_unit("second","SI",1.0,"[T]")；register_unit("c_ref","derived",<value>,"[L T^-1]")。
   • check_dim("grad[T_fil]") -> "dim[T_fil] [L^-1]"。

VI. I10-4 表达式校验与渲染（validate_expr / render_expr）

1. Signature
   • validate_expr(expr: str, allowed: set[str]) -> bool
   • render_expr(expr: str, style: str="text") -> str
2. 默认白名单（推荐）
   • 运算符：{"+","-","*","/","^","(",")"}
   • 算符：{"grad","div","curl","lap","avg_t","avg_V","avg_gamma","D_ell"}
   • 符号：{"T_fil","T_trans","rho","n","n_eff","c_ref","gamma","d ell","L_gamma","T_arr"}
3. 内置 Lint（与第7章对齐）
   拒绝模式："∫ n d ell / c"、缺括号的 "∫ n_eff d ell / c_ref"、未显式路径的 "∫ n_eff dl"。
4. 错误码
   • E10-401 TokenNotAllowed
   • E10-402 ForbiddenPattern
   • E10-403 BracketRequired

VII. I10-5 到达时实现（arrival_time）

1. Signature
   arrival_time(n_eff_path: list[float], ds: list[float], c_ref: float) -> float
2. 数值口径
   T_arr = Σ_i ( n_eff_path[i] / c_ref ) * ds[i]，对应连续式 T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
3. 约束
   len(n_eff_path) = len(ds)；ds[i] > 0；c_ref > 0。
4. 稳定性建议
   使用 Kahan 求和或 pairwise summation；长路径可做分段归约。
5. 错误码
   • E10-501 LengthMismatch
   • E10-502 NonPositiveStep
   • E10-503 NonPositiveCref

VIII. I10-6 引用解析（resolve_ref）

1. Signature
   resolve_ref(ref: str) -> dict
2. 输入语法
   ref ::= "Core.Terms:ChN:Anchor" | "Pxx-?" | "Sxx-?" | "Mx-?" | "Ixx-?"
3. 返回字段
   { volume, chapter, anchor, type, version, hash, page, see }
4. 错误码
   • E10-601 RefNotFound
   • E10-602 RefAmbiguous

IX. I10-7 术语导出（export_terms）

• Signature
  export_terms(format: str="yaml") -> str
• 排序与稳定性
  以 code 字典序排序；相同 code 的多版本按 version 降序。
• YAML 片段示例
  - name: Tension field
  code: T_fil
  type: field
  unit: see Core.Metrology
  def: T_fil(x,t) def= intrinsic tension field of the medium-weave system
  refs: ["P70-1","Core.Equations:Sxx-?"]

X. 最小工作示例（MWE：注册→校验→计算→导出）

1. 单位注册与尺度
   register_unit("meter","SI",1.0,"[L]")；register_unit("second","SI",1.0,"[T]")；register_unit("c_ref","derived",<value>,"[L T^-1]")。
2. 术语注册
   • register_term("Tension field","T_fil","field","see Core.Metrology","T_fil(x,t) def= intrinsic tension field",["must not mix with T_trans"],["P70-1"])
   • register_term("Effective refractive index","n_eff","field","dimensionless","n_eff(x,t) def= effective refractive index",["path integral only with c_ref"],["P70-2"])
3. 别名与规范化
   add_alias("n_eff","n_effective")；normalize_symbol("n_effective") -> "n_eff"。
4. 量纲校验
   check_dim("( n_eff / c_ref ) * d_ell") -> "[T^0]"。
5. 表达式校验
   validate_expr("T_arr = ( ∫ ( n_eff / c_ref ) d ell )", allowed=DEFAULT) -> True。
6. 到达时计算
   arrival_time([1.05,1.04,1.06],[10.0,10.0,8.0], c_ref=<value>) -> <float seconds>。
7. 术语导出
   export_terms("yaml") 生成稳定清单并入档。

XI. 安全与一致性（与第7章对齐）

• 符号安全
  拒绝使用 { "c","T","n" } 作为独立符号或别名；仅允许 c_ref,T_fil,n_eff。
• 路径与统计
  任意实现若检测到缺失 gamma(ell) / d ell 或统计窗口 Δt / 体域 Ω，应返回 E10-402 或 E10-403 并提示修正。
• 无量纲化一致
  不得在同一推导域混用 ell 与 bar_ell、x 与 bar_x；检测到混用返回 E10-404 CoordFamilyMixed。

XII. 性能与重现性

• 数值误差控制
  对 arrival_time 建议使用 float64 与分段累加；提供 abs_err 与 rel_err 可选输出。
• 缓存与幂等
  基于 hash 的只读缓存；相同输入返回同一 IRef 与 hash。
• 日志与追溯
  记录 {input_hash, output_hash, version}，以支持 Methods.Repro 的重现实验。

XIII. 错误码总表（节选）

• E10-101…104（Term）
• E10-201…203（Alias）
• E10-301…303（Unit/Dim）
• E10-401…403, 404（Expr/Lint/Coord）
• E10-501…503（Arrival）
• E10-601…602（Ref）

XIV. 发布前检查清单

• 所有术语是否通过 register_term 与别名治理，且不触犯 P70-1 / P70-2。
• 到达时表达是否统一为 T_arr = ( ∫ ( n_eff / c_ref ) d ell ) 或其常量外提形式。
• 单位是否在 I10-3 注册完备且 check_dim 全部闭合。
• 表达式是否通过 validate_expr 且无 E10-402/403。
• 导出清单是否稳定排序、可追溯并通过版本审计。

本章小结
本章将文本口径与实现落地通过 I10-1 … I10-7 全面绑定：术语与单位的注册、表达式与量纲校验、到达时数值实现、引用解析与术语导出，配合错误码与检查清单，构成从写作到执行的闭环接口。