13-EFT.WP.Methods.SimStack v1.0 | Appendix A: Interface Reference & Prototypes

Home ／ Docs-Technical WhitePaper ／ 13-EFT.WP.Methods.SimStack v1.0

Appendix A: Interface Reference & Prototypes

I. Scope & Objectives

• This appendix consolidates the I60-* interfaces: prototypes, I/O contracts, enumerated errors, idempotency and consistency guarantees. Coverage includes the continuous kernel, discrete weaving, coupling and advancement, time bases and calibration, data and manifests, scheduling and resources, error budgets and benchmarks, reproducibility and publishing.
• All symbols and formulas are in English, plain text. Units and dimensions must be validated via check_dim(expr). Concurrency semantics, TS.* metrics, and hb/bp conventions align with Chapters 3 and 7.

II. Common Conventions & Generic Types

1. Identifiers and time
   • Published clock ts, internal monotonic base tau_mono, with mapping ts = alpha + beta * tau_mono.
   • Paths and measures: gamma(ell), d ell.
2. Two arrival-time formulations
   • Constant factored form: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • General form: T_arr = ( ∫ ( n_eff / c_ref ) d ell )
   • Compute in parallel and publish the discrepancy delta_form.
3. Generic data types (text schema)
   • CouplingRef, PipeRef, EnvLock, PipeCard, ParamCard, CalReport, StepReport, BenchmarkReport, Attest.
   • Common result keys: TS.*, eps_norm, eps_mass, cfl, stable, sha256.
4. Errors (enumerated string codes)
   E_DIM_MISMATCH, E_INVALID_UNITS, E_PATH_UNSPECIFIED, E_TIMEBASE_UNLOCKED, E_CFL_UNSTABLE, E_CONSERVATION_FAIL, E_RESOURCE_EXHAUSTED, E_DEADLINE, E_BACKPRESSURE, E_SCHEMA_MISMATCH, E_STORAGE_IO, E_IDEMPOTENCY, E_RETRYABLE, E_NONRETRYABLE, E_MISSING_HW_CAP.
5. Idempotency & consistency
   Interfaces marked idempotent=true must return the same Ref or enact identical side effects on retries. Cross-thread communication obeys hb (happens-before) semantics with dedup keys msg.dedup_key.

III. I60-1 couple_fields — Continuous–Discrete Coupling

1. Prototype
   I60-1 couple_fields(sim_state:any, continuous_kernels:list, discrete_nets:list, opts:dict) -> CouplingRef
2. Inputs
   • continuous_kernels = [{id, kind, units, domain, bc}]
   • discrete_nets = [{id, graph=G=(V,E), io, semantics}]
   • opts = {interfaces, units.map, path.gamma.list, c_ref, timebase={alpha,beta}}
3. Output
   CouplingRef with boundary mappings, unit mappings, and the path manifest.
4. Errors
   E_SCHEMA_MISMATCH, E_INVALID_UNITS, E_PATH_UNSPECIFIED.
5. Contract
   Idempotent. After creation, units.map and path.gamma.list are immutable (convention immutability).

IV. I60-2 exchange_packets — Boundary Exchange

• Prototype
  I60-2 exchange_packets(coupling:CouplingRef, t_now:float) -> int
• Inputs
  t_now is measured on tau_mono. Payloads follow at-least-once delivery with idempotent handling.
• Output
  Count of successfully exchanged events or wave-packets.
• Errors
  E_BACKPRESSURE, E_DEADLINE.
• Contract
  Messages carry dedup_key. hb ordering is preserved across threads.

V. I60-3 advance_dt — Time Advancement

• Prototype
  I60-3 advance_dt(sim_state:any, dt:float, controller:dict) -> StepReport
• Inputs
  controller = {cfl_max, err_tol, scheme, retry, clamp}.
• Output
  StepReport = {dt_in, dt_out, stable:bool, cfl, eps_norm, eps_mass, TS.*}.
• Errors
  E_CFL_UNSTABLE, E_CONSERVATION_FAIL.
• Contract
  Publish conservation residual eps_mass and normalization error eps_norm. When stable=false, rollback–retry behavior is governed by controller.retry.

VI. I60-4 calibrate_arrival_time — Arrival-Time Calibration

• Prototype
  I60-4 calibrate_arrival_time(trace:any, paths:list, c_ref:float, medium:any) -> CalReport
• Output
  CalReport = {T_arr.general, T_arr.factorized, delta_form, path.gamma.list, timebase={alpha,beta}}.
• Contract
  Paths and measures must be explicit. Publish both forms in parallel and delta_form.

VII. I60-5 emit_metrics — Runtime Metrics

• Prototype
  I60-5 emit_metrics(sim_state:any) -> dict
• Output
  TS.* metrics (latency, jitter, throughput, bp, hb violations, etc.) plus latest conservation stats.

VIII. I60-6 freeze_env — Environment Lock

• Prototype
  I60-6 freeze_env(env_spec:dict) -> EnvLock
• Output
  EnvLock = {oci_digest, deps.lock, sys.meta, compiler.flags, H_env=sha256(...)}.
• Error
  E_MISSING_HW_CAP.
• Contract
  Idempotent. Required for CL2/CL3 reproducibility (see Chapter 11).

IX. I60-7 generate_pipeline_card — Pipeline Card Generation

• Prototype
  I60-7 generate_pipeline_card(sim_state:any, fit:any, opts:dict) -> PipeCard
• Output
  PipeCard = {graph=G, stage.io, H.id, units.*, timebase, paths.gamma.list, c_ref, TS.probes}.
• Contract
  Must pass check_dim(expr) and convention audits.

X. I60-8 materialize_pipeline — Pipeline Materialization

• Prototype
  I60-8 materialize_pipeline(PipeCard, ParamCard, EnvLock) -> PipeRef
• Output
  PipeRef and the placement plan.
• Errors
  E_SCHEMA_MISMATCH, E_TIMEBASE_UNLOCKED.
• Contract
  Idempotent. Reject if versions are incompatible.

XI. I60-9 run_with_attestation — Attested Run

• Prototype
  I60-9 run_with_attestation(PipeRef, seeds:list) -> Attest
• Output
  Attest = {run.id, H_env, sha256(artifacts), r.stats, J, delta_form, TS.*}.
• Contract
  Record both ts and tau_mono timestamps. Preserve message traceability.

XII. I60-10 verify_repro — Reproducibility Check

• Prototype
  I60-10 verify_repro(artifact:any, gates:dict) -> Verdict
• Output
  Verdict = {class=CL0|CL1|CL2|CL3, Score, details}.
  Criteria follow S62-80.

XIII. I60-11 export_repro_pack — Repro Pack Export

• Prototype
  I60-11 export_repro_pack(PipeCard, ParamCard, EnvLock, Attest) -> ReproPack
• Output
  ReproPack plus an audit-index entry.

XIV. I60-20 manifest_emit — Manifest Persistence

• Prototype
  I60-20 manifest_emit(objects:list, schema:str, opts:dict) -> str
• Inputs
  objects may include PipeCard/ParamCard/CalReport/StepReport/BenchmarkReport.
  opts = {namespace, version, checksum="sha256"}.
• Output
  Content-addressable cid of the manifest object.
• Errors
  E_SCHEMA_MISMATCH, E_STORAGE_IO.
• Contract
  All numeric fields carry explicit units. If spectral content is present, window with U_w/ENBW is mandatory.

XV. I60-21 dataset_write — Dataset Write

• Prototype
  I60-21 dataset_write(stream:any, window:dict, manifest:str) -> int
• Inputs
  window = {t0, t1, dt, path.gamma.id}.
• Output
  Number of records written.
• Contract
  Return sha256 and alignment status. Writes are idempotent.

XVI. I60-30 plan_schedule — Planning & Ready Set

• Prototype
  I60-30 plan_schedule(G:(V,E), cost:dict, quota:dict, policy:dict) -> dict
• Inputs
  cost = {w(v), c(e)}, quota = {cpu, mem, io}, policy = {placement, affinity, bp}.
• Output
  Placement and priority plan, estimated T_make(G) and crit(G).
• Error
  E_RESOURCE_EXHAUSTED.
• Contract
  Align with Chapter 7 cost models. Publish TS.* targets and alert thresholds.

XVII. I60-31 set_backpressure — Backpressure & Throttling

• Prototype
  I60-31 set_backpressure(PipeRef, bp:dict) -> dict
• Inputs
  bp = {queue.max, rate.limit, drop.policy, retry}.
• Output
  Effective configuration echo and current bp metrics.
• Error
  E_BACKPRESSURE on limit overflow or policy conflict.
• Contract
  Changes are transactional. hb semantics must be preserved.

XVIII. I60-60 fit_step — Single Fitting Step

• Prototype
  I60-60 fit_step(sim_out:any, obs:any, H:any, pri:any, opts:dict) -> dict
• Output
  {theta.new, loss, grad, cov, TS.*}.
• Contract
  Conventions for H, units, and time base align with Chapter 10.

XIX. I60-65 run_fit_loop — Fitting Loop

• Prototype
  I60-65 run_fit_loop(PipeRef, obs:any, H:any, controller:dict) -> FitArtifact
• Output
  FitArtifact = {theta*, loss_curve, cov, gates}.
• Contract
  Record the Mx-65 trajectory. On failure, provide a reproducible experiment entry point.

XX. I60-70 compute_error_budget — Error Budget

• Prototype
  I60-70 compute_error_budget(terms:list, rules:dict) -> dict
• Inputs
  terms = [{name, mean, var, units}], rules = {composition, gates}.
• Output
  {budget, dominant_terms, gate_pass}.
• Contract
  Gates and composition rules align with Chapter 8.

XXI. I60-71 check_conservation — Conservation Check

• Prototype
  I60-71 check_conservation(flow:any, rho:any, window:dict) -> dict
• Output
  {eps_mass, eps_norm, TS.*}.
• Error
  E_CONSERVATION_FAIL when mass gate is exceeded.

XXII. I60-90 run_benchmark — Benchmark Run

• Prototype
  I60-90 run_benchmark(PipeRef, suite:list, opts:dict) -> BenchmarkReport
• Output
  BenchmarkReport = {cases, correctness, stability, SLO, throughput, Score}.
• Contract
  Report fields align with Chapter 9. Publish the linkage key for ReproPack.

XXIII. I60-91 report_benchmark — Benchmark Publication

• Prototype
  I60-91 report_benchmark(BenchmarkReport, targets:list) -> dict
• Output
  Publication result with audit links.
• Errors
  E_STORAGE_IO, E_SCHEMA_MISMATCH.

XXIV. Utility Functions (Conventional Implementations)

• check_dim(expr) -> bool: unit and dimension audit; on failure raise E_INVALID_UNITS or E_DIM_MISMATCH.
• check_ts_alignment(alpha:float, beta:float) -> bool: validate ts = alpha + beta * tau_mono.
• window_spec(t0,t1,dt) -> dict: normalize a time window spec.
• spec_path(gamma:list) -> list: path parameterization with support declaration.

XXV. Typical Call Sequences (Pseudocode)

1. Bootstrap & coupling
   • EnvLock = I60-6.freeze_env(env_spec)
   • CouplingRef = I60-1.couple_fields(sim_state, kernels, nets, opts)
   • PipeCard = I60-7.generate_pipeline_card(sim_state, fit, opts)
   • PipeRef = I60-8.materialize_pipeline(PipeCard, ParamCard, EnvLock)
2. Advancement & calibration
   • CalReport = I60-4.calibrate_arrival_time(trace, paths, c_ref, medium)
   • Loop I60-3.advance_dt(...) and periodically I60-2.exchange_packets(...)
   • I60-5.emit_metrics(sim_state)
3. Conservation & publication
   • I60-71.check_conservation(...)
   • BenchmarkReport = I60-90.run_benchmark(PipeRef, suite, opts)
   • Attest = I60-9.run_with_attestation(PipeRef, seeds)
   • ReproPack = I60-11.export_repro_pack(PipeCard, ParamCard, EnvLock, Attest)
   • I60-91.report_benchmark(BenchmarkReport, targets)

XXVI. Versioning & Compatibility

1. Semantic versioning
   • Major: convention or unit changes; adjustments to the two T_arr definitions; time-base mapping changes.
   • Minor: parameter and default-policy changes without convention changes.
   • Patch: defect fixes and non-functional optimizations.
2. Compatibility strategy
   New optional parameters in I60-* remain backward compatible. Deletions or semantic changes occur only in major versions, with a migration script cid.

XXVII. New Terms & Symbols (to memorize)

• Interfaces & artifacts: I60-1..I60-5, I60-6..I60-11, I60-20, I60-21, I60-30, I60-31, I60-60, I60-65, I60-70, I60-71, I60-90, I60-91.
• Reports & cards: PipeCard, ParamCard, EnvLock, CalReport, StepReport, BenchmarkReport, Attest, ReproPack.
• Key quantities & conventions: TS.*, eps_norm, eps_mass, cfl, delta_form, H_env, gamma(ell), two-form T_arr, U_w, ENBW