12-EFT.WP.Methods.Repro v1.0 | Appendix B Implementation Bindings and Function Prototypes

Home ／ Docs-Technical WhitePaper ／ 12-EFT.WP.Methods.Repro v1.0

Appendix B Implementation Bindings and Function Prototypes

I. Scope and Objectives

• This appendix consolidates the implementation-binding layer I30-*: prototypes, inputs/outputs, idempotency and replay semantics, exceptions and handling, plus key pseudocode fragments—so cross-chapter and cross-domain reproducibility remains consistent and independently verifiable.
• All function signatures, variables, and formulas are expressed in English plain text; inline quantities are wrapped in backticks; any expression with measures and integrals follows the volume-wide conventions; concurrency observability follows Core.Threads TS.* fields.

II. Terms and Symbols

• Environment & signatures: EnvLock, hash(•), fingerprint, anchor.
• Cards & reports: PipelineCard, ParamCard, BenchReport, RepReport, MigPlan, CutoverReport, RollbackReport.
• Repro & metrics: delta_rep, R_coef = 1 - delta_rep, delta_psd, gate.rep, eps_norm, eps_mass.
• Time base & spectra: tau_mono, ts, alpha, beta, S_xx(f), U_w, ENBW.

III. Design Principles and Binding Constraints

• Pure-function bias & explicit side effects: beyond explicit persistence and signing, functions should produce stable outputs for the same inputs under a fixed EnvLock.
• Idempotency domain: define idemp_key = hash( name || version || inputs || EnvLock ) for each prototype; repeated calls in the idempotency domain must return the same fingerprint and anchor.
• Time-base alignment: any time-series handling maps to the common ts first, obeying ts = alpha + beta * tau_mono.
• Randomness control: every prototype that performs sampling or initialization must expose seed and rng_family, and back-fill them in RepReport.
• Dimensions & units: run check_dim(expr) before entering core operators; spectral gauges must declare window, U_w, and ENBW.

IV. Prototype Catalog and Parameters

1. I30-1 freeze_environment(config:dict) -> EnvLock
   • Inputs: config (OS, kernel, drivers, libs, compiler, cpu_id, gpu_id, flags, rng_family).
   • Output: EnvLock.
   • Idempotency: normalize-serialize config as the idempotency domain.
   • Exception: E_ENV_DRIFT.
   • Note: EnvLock = hash( normalized(config) ).
2. I30-2 emit_pipeline_card(state:any) -> dict
   • Inputs: state (DAG, I/O anchors, metrics, alerts).
   • Output: PipelineCard.
   • Idempotency: bound to state and EnvLock.
   • Exception: E_SCHEMA_MISMATCH.
3. I30-3 run_benchmark_suite(card:dict) -> BenchReport
   • Inputs: PipelineCard (binding data and steps).
   • Output: BenchReport (per-case results, delta_psd, R_coef, partial score components).
   • Idempotency: bound to card, EnvLock, seed.
   • Exceptions: E_DATA_MISMATCH, E_NONDETERMINISM.
4. I30-4 verify_reproduction(golden:any, candidate:any, metrics:dict) -> RepReport
   • Inputs: golden, candidate, metrics (gates and weights).
   • Output: RepReport (delta_rep, R_coef, delta_psd, gate.rep).
   • Idempotency: bound to golden/candidate fingerprints and metrics.
   • Exception: E_DATA_MISMATCH.
5. I30-5 snapshot_provenance(artifacts:list) -> dict
   • Inputs: artifacts (files, models, cards, reports).
   • Output: { fingerprint:list, anchor:str }.
   • Idempotency: bound to artifact content and metadata.
   • Exception: E_SCHEMA_MISMATCH.
6. I30-6 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}
   • Inputs: trace (internal tau_mono sequence), reference (external ts sequence).
   • Outputs: alpha, beta, fit (includes r_tb and residual breakdown).
   • Idempotency: bound to input sequences and fitting gauge.
   • Exception: E_TIMEBASE_SKEW.
   • Note: linear least squares or robust regression; report r_tb = ( norm( ts - ( alpha + beta * tau_mono ) ) / norm( ts ) ).
7. I30-7 compare_psd(x:any, y:any, window:dict) -> { delta_psd:float, pass:bool }
   • Inputs: x, y (signals aligned to the same ts), window (w[n], U_w, ENBW, bandwidth & overlap).
   • Outputs: delta_psd, pass.
   • Idempotency: bound to data fingerprints and window config.
   • Exception: E_SCHEMA_MISMATCH.
   • Note: delta_psd = ( ∫ | S_xx(f) - S_yy(f) | df ) / ( ∫ S_xx(f) df ).
8. I30-8 collect_ts_metrics(run_id:str, fields:list) -> dict
   • Inputs: run_id, fields ⊆ TS.*.
   • Output: { field -> series }.
   • Idempotency: bound to run_id and time window.
   • Exception: E_DATA_MISMATCH.
9. I30-9 publish_release(anchor:str, channel:str, policy:dict) -> dict
   • Inputs: anchor (EnvLock || PipelineCard || ParamCard joint hash), channel ∈ {canary, stable, LTS}, policy (gates & monitoring).
   • Output: { release_id:str, sig_k:bytes }.
   • Idempotency: bound to anchor and channel.
   • Exception: E_ENV_DRIFT.
10. I30-10 plan_migration(diff:dict) -> MigPlan
    • Inputs: diff (difference matrix for PipelineCard/ParamCard).
    • Output: MigPlan (W_mig, T_dep, T_grace, rollback anchor).
    • Idempotency: bound to diff fingerprint.
    • Exception: E_SCHEMA_MISMATCH.
11. I30-11 execute_cutover(plan:MigPlan) -> CutoverReport
    • Input: MigPlan.
    • Output: CutoverReport (dual-run comparison, score deltas, TS.* impacts).
    • Idempotency: bound to plan and window.
    • Exceptions: E_ENV_DRIFT, E_TIMEBASE_SKEW.
12. I30-12 rollback(anchor:str, reason:str) -> RollbackReport
    • Inputs: anchor, reason.
    • Output: RollbackReport (restore point, impact surface, ScoreSummary(old,new)).
    • Idempotency: bound to anchor and reason.
    • Exception: E_DATA_MISMATCH.

V. Idempotency and Replay (Unified Contract)

1. Idempotency key: idemp_key = hash( name || version || inputs || EnvLock ). For any I30-*, if idemp_key matches, then
   • fingerprint(outputs_new) = fingerprint(outputs_old).
   • Timestamp variations are allowed but excluded from the fingerprint domain.
2. Randomness: prototypes involving sampling must accept seed; if not provided, reject with E_SEED_INVALID.
3. Time base: inputs with time must first call I30-6 to obtain alpha, beta, map internal tau_mono to common ts, and only then compute spectral and scoring metrics.

VI. Metrology and Observability Interfaces

1. Required TS.* fields
   • TS.latency.{p50,p95,p99}, TS.thrpt, TS.error_rate, TS.cpu, TS.mem, TS.gpu.util (if applicable), TS.hb.
   • For I30-3/4/7, add TS.psd.band_energy; for I30-6, add TS.timebase.r_tb.
2. Sampling & aggregation windows
   Slice uniformly on external ts; window length, stride, and alignment policy are declared in PipelineCard.

VII. Exception Set and Handling

1. Core exceptions
   • E_ENV_DRIFT: environment differs from EnvLock.
   • E_DATA_MISMATCH: inputs or schema do not match PipelineCard/ParamCard.
   • E_TIMEBASE_SKEW: time base misfit, r_tb beyond gate.
   • E_NONDETERMINISM: nondeterminism detected—recomputed output fingerprint differs.
   • E_SEED_INVALID: missing or out-of-domain seed.
   • E_SCHEMA_MISMATCH: structural/field mismatch.
2. Handling (minimal set)
   Record H_k/sig_k and register anchor; back-fill TS.* and delta summaries; for run-time exceptions, trigger I30-12 rollback with ScoreSummary(old,new).

VIII. Reference Fragments (Pseudocode & State Machines)

• I30-6 align_timebase

inputs: trace.tau_mono[], reference.ts[]

preprocess: handle missing/outliers

solve: ts ≈ alpha + beta * tau_mono (robust LS)

compute: r_tb = norm(ts - (alpha + beta * tau_mono)) / norm(ts)

guard: if r_tb > tau_tb -> E_TIMEBASE_SKEW

emit: {alpha, beta, fit:{r_tb, residuals}}; TS.timebase.r_tb <- r_tb

• I30-3 run_benchmark_suite (state machine)

INIT : validate EnvLock & PipelineCard

PREP : map time base to common ts; lock seed & rng_family

EXEC : run cases; collect TS.* and intermediate fingerprints

ANALYZE: compute delta_rep, delta_psd, partial scores

DECIDE : compare to gates; set gate.rep

FINAL : assemble BenchReport; append audit signature sig_k

IX. Cross-References and Dependencies

• Time base & mapping: Chapter 6 and Core.Sea.
• Spectra & windows: Chapter 8 and Core.Metrology.
• Runtime & release: Chapter 9.
• Change & rollback: Chapter 13.

X. Versioning and Numbering Strategy

• I30-* is a stable id space; add new prototypes by incrementing numbers while keeping backward compatibility. Breaking parameter changes bump MAJOR; return-field extensions are MINOR; documentation errata are PATCH.
• Every change updates PipelineCard, ParamCard, CHANGELOG, and anchor, and is registered on the audit chain with H_k/sig_k.