56-Report-Level Methods Appendix Template v1.0 | Chapter 11 Implementation Binding & Function Prototypes (I)

Home ／ Docs-Technical WhitePaper ／ 56-Report-Level Methods Appendix Template v1.0

Chapter 11 Implementation Binding & Function Prototypes (I)

I. Chapter Goals & Scope (Mandatory)

• Materialize each method entry at the Implementation Binding layer as API/Schema/function prototypes, ensuring reproducibility, auditability, replayability, and cross-version compatibility.
• Aligned with Ch.5 (Data & Experimental Design), Ch.6 (Math & Pseudocode), Ch.8 (Evaluation Protocol), Ch.9 (Uncertainty & Tests), and Ch.10 (Ablation & Sensitivity).

II. Interface Layers & Naming (Mandatory)

• Layers: domain (domain services) / data (data contracts) / ops (operations & release) / audit (audit exports).
• Naming: <namespace>.<resource>.<action>; REST path uses version prefix /api/v{major}, plural resources.
• Unified response: code (enum), message (summary), data (payload), trace_id (distributed tracing).

III. Versioning & Compatibility Policy (Mandatory)

• Versioning: use both semver and version_range; public releases prefer stable line v1.*.
• Compatibility: field additions are BC; deletions/renames are Breaking and require a fallback with dual-stack window ≥ one observation period.
• Contract changes must be declared in compatibility: { version_range, fallback, breaking }.

IV. Error Taxonomy & Traceability (Mandatory)

• Error codes: E_INPUT (parameters/validation), E_STATE (state/dependency), E_GATE (gate failure), E_DEP (external dependency), E_SYS (system).
• Traceability: include trace_id/span_id, script@commit, dataset@version, artifact_hash.

V. Arrival-Time Caliber & Consistency (Mandatory)

1. Two forms:
   • Factored: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • General: T_arr = ( ∫ ( n_eff / c_ref ) d ell )
2. Any interface that returns/consumes T_arr must also state path gamma(ell) and measure d ell in the same or adjacent paragraph; symbols—units—dimensions: T_arr: s/T, n_eff: 1/1, c_ref: m·s^-1 / L T^-1; check_dim=true.

VI. Canonical Endpoints (REST, Mandatory, copy-ready)

1. Method evaluation
   • POST /api/v1/methods/{name}/evaluate — trigger evaluation (returns 202 + Location for polling)
   • GET /api/v1/methods/{name}/results/{rid} — fetch results & coverage
2. Arrival-time estimation
   POST /api/v1/arrival-time/estimate — input path & caliber, output T_arr with anchors
3. Gate checks
   POST /api/v1/gates/check — batch gate decisions
4. Audit export
   GET /api/v1/audit/{id} — export yaml/json/pdf audit bundle
5. Release & version graph
   POST /api/v1/release; GET /api/v1/version/graph

VII. Function Prototypes (Language-agnostic, Mandatory)

evaluate_method(req: EvalReq) -> EvalReport

estimate_arrival_time(req: ArrivalReq) -> ArrivalResp

check_gates(items: List[GateSpec]) -> GateResultSet

export_audit(id: ArtifactID, fmt: ["yaml","json","pdf"]) -> ArtifactRef

release_new(spec: ReleaseSpec) -> ReleaseID

get_version_graph() -> VersionGraph

VIII. Request/Response Schemas (brief, YAML; JSON-equivalent, Mandatory)

ArrivalReq:

path: "gamma(ell)"

measure: "d ell"

c_ref: "ref:L2" # or functional identifier

n_eff_profile: "dataset:cmb_set_v3@v3"

mode: "general" # general|factored

params: { Δell: 1e-3, ε_int: 1e-6 }

ArrivalResp:

code: "OK|E_INPUT|E_STATE|E_GATE|E_DEP|E_SYS"

data:

T_arr: 12.345

unit: "s"

anchors:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

context:

delta_form: "general"

path: "gamma(ell)"

measure: "d ell"

params: { Δell: 1e-3, ε_int: 1e-6 }

trace_id: "..."

EvalReq:

method: { name: "", version: "v1.0" }

datasets: ["cmb_set_v3@v3","lens_v1@v1"]

scripts: ["eval.py@a1b2c3"]

config: { seed: 20250927, batch: "B1" }

EvalReport:

summary: { pass: true }

metrics:

gate_accuracy: { value: 0.995, gate: ">=0.99@7d", passed: true, ci: [0.993, 0.997] }

gate_latency: { value: "1.8h", gate: "<=2h@7d", passed: true }

artifacts: ["yaml","json","pdf"]

hashes: ["sha256:…"]

GateSpec:

name: "gate_accuracy"

rule: ">=0.99@7d"

source: { dataset: "cmb_set_v3@v3", script: "eval.py@a1b2c3" }

ReleaseSpec:

semver: "1.4.0"

channel: "beta|stable|lts"

compatibility: { version_range: "[2.0,3.0)", fallback: "adapter_v1", breaking: false }

IX. Security, Rate Limiting & Idempotency (Mandatory)

• Security: OAuth2/OIDC; RBAC with least privilege; critical state transitions require multi-party sign-off (MFA/multi-sign).
• Rate limiting: global and per-actor quotas; on excess return 429 with Retry-After.
• Idempotency: support Idempotency-Key for retryable submissions; long jobs use 202 + Location polling.

X. Observability & Audit (Mandatory)

• Metrics: QPS, p95 latency, error rate, rate-limit hits, replay coverage, gate_* pass rate.
• Logging: structured JSON including trace_id/span_id/method/version/dataset@version/artifact_hash.
• Audit: record all writes; archive exported artifacts with signed pages.

XI. Human × Machine Mapping (Mandatory)

XII. Minimal Sample (copy-ready, Mandatory)

• Human abstract: POST /api/v1/arrival-time/estimate uses the general form with Δell=1e-3, ε_int=1e-6; response returns T_arr (unit s), anchors, and trace_id.
• Machine snippet:

request:

path: "gamma(ell)"

measure: "d ell"

c_ref: "ref:L2"

n_eff_profile: "dataset:cmb_set_v3@v3"

mode: "general"

params: { Δell: 1e-3, ε_int: 1e-6 }

response:

code: "OK"

data:

T_arr: 12.345

unit: "s"

anchors: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

context: { delta_form: "general", path: "gamma(ell)", measure: "d ell" }

trace_id: "..."

XIII. Validation Rules (regex/consistency, Mandatory)

• Endpoints: ^/api/v[0-9]+/[a-z0-9\\-/\\{\\}_]+$; resources are plural.
• Citations: ^EFT\\.WP\\.[\\w\\.]+ v\\d+\\.\\d+(?:\\.\\d+)?:[PSMI]\\d+(?:-\\d+)?$.
• Gates: ^gate_[a-z0-9_]+(>=|<=|==)[^@\\s]+@[^@\\s]+$.
• Arrival-time: if T_arr appears, path/measure required; check_dim=true.
• Versioning: valid semver; if breaking=true, a fallback and observation window are required.

XIV. Citation & Cross-Reference Style (Mandatory)