01-EFT.WP.Core.Terms v1.0 | Chapter 8, Implementation-Binding Interfaces

Home ／ Docs-Technical WhitePaper ／ 01-EFT.WP.Core.Terms v1.0

Chapter 8, Implementation-Binding Interfaces

I. Chapter Objectives & Scope

• Provide executable interface specifications, parameter semantics, error codes, and minimal working examples (MWE) for I10-1 … I10-7, ensuring the prose conventions and the runnable implementations remain aligned.
• Standardize return shapes, identifier rules, and versioning semantics. All formulas, symbols, and definitions are in English, using plain-text notation and the parentheses rules (see this volume, Chapters 1 and 7).

II. General Conventions & Return Shapes

1. Identifiers & versioning
   • IRef def= opaque identifier with fields {id, version, hash, created_at}; version follows major.minor.patch.
   • hash def= content-addressable digest (e.g., the first 16 chars of a sha256) used for de-duplication and provenance.
2. Result and error envelopes
   • Ok<T> = { ok: true, data: T }
   • Err = { ok: false, code: E10-xxx, message: str, hint: str, see: list[str] }
3. Character and symbol policy
   For term name/code/definition, Chinese and full-width punctuation are forbidden. Allowed charset: A–Z a–z 0–9 _ [] () / * + - ^ , : ; . space.
4. Concurrency & idempotence
   All register_* and add_alias calls are idempotent: resubmitting the same hash returns the same IRef.
5. Cross-volume citations
   The see field only accepts canonical anchors, e.g., ["P70-4","Core.Equations:Sxx-3","Metrology.Path:M1-2"].

III. I10-1 Term Registration (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 enum (v1.0)
   {scalar, field, operator, path, constant, object, medium} (adds object, medium beyond the draft; backward compatible).
3. Field semantics
   • name is a human-readable English label; code is a unique short code (e.g., T_fil, n_eff); definition uses an English def= sentence.
   • unit may be None or "dimensionless" when appropriate; dimensions are registered via I10-3.
   • constraints enumerate usage boundaries (e.g., "must not mix with T_trans").
4. Error codes
   • E10-101 NameInvalid (disallowed characters or Chinese present)
   • E10-102 CodeConflict (code already used for a different concept)
   • E10-103 TypeUnknown (not in the enum)
   • E10-104 UnitUnregistered (unit referenced but not registered; see I10-3)
5. Compliance notes
   n_eff and n must not be registered as synonyms (see P70-2); T_fil and T_trans are mutually exclusive in meaning (see P70-1).

IV. I10-2 Aliases & Normalization (add_alias / normalize_symbol)

1. Signature
   • add_alias(canonical: str, alias: str) -> None
   • normalize_symbol(token: str) -> canonical: str
2. Rules
   • One-to-many allowed; many-to-one rejected to avoid ambiguity. Alias chains collapse to the canonical name.
   • Cycles and self-references are forbidden. Disallowed bare symbols (such as c, T, n) must not be used as aliases (see P70-*).
3. Error codes
   • E10-201 CanonicalMissing
   • E10-202 AliasConflict
   • E10-203 ForbiddenAlias

V. I10-3 Units & Dimensions (register_unit / check_dim)

1. Signature
   • register_unit(name: str, base: str, scale: float, dim: str) -> None
   • check_dim(expr: str) -> dim: str
2. Dimension grammar
   dim ::= "[ L^a T^b M^c ]", with integer or rational exponents; dimensionless as "[T^0]" or "dimensionless".
3. Built-in derived rules
   • 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] corresponds to T_arr.
4. Error codes
   • E10-301 UnitExistsWithDifferentDim
   • E10-302 DimParseError
   • E10-303 DimMismatch
5. Examples
   • 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 Expression Validation & Rendering (validate_expr / render_expr)

1. Signature
   • validate_expr(expr: str, allowed: set[str]) -> bool
   • render_expr(expr: str, style: str="text") -> str
2. Recommended default whitelist
   • Operators: {"+","-","*","/","^","(",")"}
   • Calculus/statistics/path operators: {"grad","div","curl","lap","avg_t","avg_V","avg_gamma","D_ell"}
   • Symbols: {"T_fil","T_trans","rho","n","n_eff","c_ref","gamma","d ell","L_gamma","T_arr"}
3. Built-in lint (aligned with Chapter 7)
   Reject patterns: "∫ n d ell / c", the unparenthesized "∫ n_eff d ell / c_ref", and "∫ n_eff dl" without an explicit path.
4. Error codes
   • E10-401 TokenNotAllowed
   • E10-402 ForbiddenPattern
   • E10-403 BracketRequired

VII. I10-5 Arrival-Time Implementation (arrival_time)

1. Signature
   arrival_time(n_eff_path: list[float], ds: list[float], c_ref: float) -> float
2. Numerical convention
   T_arr = Σ_i ( n_eff_path[i] / c_ref ) * ds[i], matching the continuous form T_arr = ( ∫ ( n_eff / c_ref ) d ell ).
3. Constraints
   len(n_eff_path) = len(ds); ds[i] > 0; c_ref > 0.
4. Stability recommendations
   Use Kahan summation or pairwise accumulation; apply segment-wise reduction for long paths.
5. Error codes
   • E10-501 LengthMismatch
   • E10-502 NonPositiveStep
   • E10-503 NonPositiveCref

VIII. I10-6 Reference Resolution (resolve_ref)

1. Signature
   resolve_ref(ref: str) -> dict
2. Input grammar
   ref ::= "Core.Terms:ChN:Anchor" | "Pxx-?" | "Sxx-?" | "Mx-?" | "Ixx-?"
3. Returned fields
   { volume, chapter, anchor, type, version, hash, page, see }
4. Error codes
   • E10-601 RefNotFound
   • E10-602 RefAmbiguous

IX. I10-7 Term Export (export_terms)

• Signature
  export_terms(format: str="yaml") -> str
• Ordering & stability
  Sort by code in lexicographic order; for multiple versions of the same code, order by version descending.
• YAML snippet example
  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. Minimal Working Example (MWE: Register → Validate → Compute → Export)

1. Unit registration & scales
   register_unit("meter","SI",1.0,"[L]")；register_unit("second","SI",1.0,"[T]")；register_unit("c_ref","derived",<value>,"[L T^-1]")。
2. Term registration
   • 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. Aliases & normalization
   add_alias("n_eff","n_effective")；normalize_symbol("n_effective") -> "n_eff"。
4. Dimensional check
   check_dim("( n_eff / c_ref ) * d_ell") -> "[T^0]"。
5. Expression validation
   validate_expr("T_arr = ( ∫ ( n_eff / c_ref ) d ell )", allowed=DEFAULT) -> True。
6. Arrival-time computation
   arrival_time([1.05,1.04,1.06],[10.0,10.0,8.0], c_ref=<value>) -> <float seconds>。
7. Term export
   export_terms("yaml") yields a stable, archival list.

XI. Safety & Consistency (Aligned with Chapter 7)

• Symbol safety
  Reject using { "c","T","n" } as standalone symbols or aliases; only c_ref, T_fil, n_eff are permitted.
• Paths & statistics
  Any implementation that detects missing gamma(ell) / d ell or missing statistical window Δt / domain Ω must return E10-402 or E10-403 with corrective hints.
• Non-dimensionalization coherence
  Do not mix ell with bar_ell, or x with bar_x within the same derivation domain; on detection, return E10-404 CoordFamilyMixed.

XII. Performance & Reproducibility

• Numerical error control
  For arrival_time, prefer float64 and segmented accumulation; optionally expose abs_err and rel_err.
• Caching & idempotence
  Use hash-based read-through caching; identical inputs return the same IRef and hash.
• Logging & provenance
  Record {input_hash, output_hash, version} to support Methods.Repro for exact experimental replay.

XIII. Error-Code Catalog (Extract)

• 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. Pre-Publication Checklist

• Have all terms been registered via register_term and governed by alias rules without violating P70-1 / P70-2?
• Are all arrival-time expressions unified as T_arr = ( ∫ ( n_eff / c_ref ) d ell ) or its constant-factored form?
• Are all units registered in I10-3, with check_dim closures satisfied?
• Do expressions pass validate_expr with no E10-402/403?
• Is the exported list stably ordered, traceable, and passing version audit?

Chapter Summary

This chapter binds the prose conventions to runnable implementations across I10-1 … I10-7: registration of terms and units, expression and dimensional validation, numerical arrival-time evaluation, reference resolution, and term export. With explicit error codes and checklists, it establishes a closed-loop pathway from authoring to execution, ensuring consistency, verifiability, and reproducibility across the entire stack.