51-Pipeline Card Template v1.0 | Chapter 6 — Stage Definition & Control Equations (Stage Specs)

Home ／ Docs-Technical WhitePaper ／ 51-Pipeline Card Template v1.0

Chapter 6 — Stage Definition & Control Equations (Stage Specs)

I. Purpose & Scope

• Define unified conventions for input/output contracts, control equations, quality gates, and error semantics/idempotency/audit of pipeline stages, enabling verifiable, replayable, and releasable implementations.
• For stages involving path quantities (arrival time/phase), the text must explicitly show gamma(ell) and d ell, with delta_form ∈ {general, factored} recorded on the data side; publication requires p_dim = 1.0.

II. Prerequisites & Inputs

• Contracts complete: stage I/O fields are defined in TARR (fields/units/dimensions/domains).
• Parameters & error alignment: dependent parameters are registered in the Parameter Card and pass parameter-level G1–G8; covariance/coverage aligned with the Error Budget.
• Citations & versions: use “volume + version + anchor (P/S/M/I)”, anchor coverage ≥ 90%.
• Timebase & sync: comply with Chapter 5 (f_s, clock_state="locked", |ts_start − calib.timestamp| ≤ τ_calib).

III. Stage Structure

• Identity: stage.id (globally unique), version (SemVer), owner.
• Inputs: inputs[] (field paths with units/dimensions); shape/window/partition constraints if needed.
• Outputs: outputs[] (produced fields/artifacts) with units/dimensions and precision.
• Control: control.form (parenthesized), delta_form (for path stages), and optional assumptions[] (paraxial/coherence).
• Quality gates: quality_gates[] (G1–G8) with threshold/stop mapping.
• Error semantics: E_INPUT/E_DIM/E_GATE/E_SYNC/E_UQ/E_INTERNAL, categorized as compensable/non-compensable.
• Idempotency & retry: idempotency_key, retry_policy{max_retries,backoff,deadline}, checkpoint.
• Audit: emit audit.jsonl events (input hashes, idempotency key, retry count, final state).

IV. Control Equations & Rules

1. Parentheses & precedence: any division/integral/composite operator must use parentheses; use ln/exp/conv function notation.
2. Dimensional closure: control equations pass I70-dim_check; attach check_dim_report.json; publication requires p_dim = 1.0.
3. Path-integral conventions (two equivalent):
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )
     Phase: Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell ).
4. Alignment order: time alignment → path alignment (gamma_ell/d_ell/n_eff sync) → phase alignment (reference window).
5. UQ coupling: if stage outputs enter uncertainty propagation, provide sources of J=∂f/∂x|_{x̂} and Σ=Cov(x) (see Error Budget Ch. 5/6).

V. Gates & Stops

• G1 Schema completeness—I/O existence/types/index/window.
• G2 Citation compliance—see “Citations & versions”, anchor coverage ≥ 90%.
• G3 Path conventions—gamma/measure/delta_form present; len(path)≥2, Δell compliant.
• G4 Dimensional closure—I70-dim_check passed, p_dim = 1.0.
• G5 Freshness—clock_state="locked", |ts_start − calib.timestamp| ≤ τ_calib.
• G6 Coverage—uncertainty intervals align with publication (k/alpha/quantile).
• G7 Covariance consistency—cov_group/kernel params consistent with Error Budget, Σ PD.
• G8 Uniqueness—no duplicate output record_id/checksum.
• Trigger S1–S5 (dimensional/freshness/path/covariance/citation failure) to stop and fallback.

VI. Errors & Compensation

• E_INPUT: missing fields/type/ window mismatch → fix contract or reject.
• E_DIM: dimensional failure → stop and rollback checkpoint.
• E_GATE: gate failure → branch/degrade per thresholds.
• E_SYNC: unlock/offset over threshold → fallback (PTP/NTP), tag [Restricted] if needed.
• E_UQ: non-PD covariance/coverage mismatch → robust surrogate or reject.
• E_INTERNAL: internal exception → retry then alert.

VII. Idempotency, Retry & Replay

• Idempotency key: idempotency_key = f(run_id, partition, window, …); retries must not change outputs.
• Retry: exponential backoff/deadline; preserve input snapshot and idempotency key.
• Replay: permitted with checkpoints in reverse topological order; must not break upstream artifact consistency.

VIII. Monitoring & KPIs

• Key metrics: Latency_P50/P95, Throughput, ρ, Q_res, p_dim, σ_y(τ), and ε_flux (for path stages).
• Alerts: gate breaches/unlock/PD failure/path desync/idempotency conflict; support suppression windows and escalation.

IX. Machine-Readable Examples
A. stage.yaml

version: "1.0.0"

stage:

id: "stage-30-arrival"

owner: "ptn.core"

inputs:

- "path.gamma_ell" # m

- "path.d_ell" # m

- "medium.n_eff_profile" # 1

- "ref.c_ref" # m/s

outputs:

- "obs.T_arr" # s

control:

form: "T_arr = ∫ ( n_eff / c_ref ) d ell"

delta_form: "general"

assumptions: ["paraxial","coherence_window"]

quality_gates: ["G1","G2","G3","G4","G5","G6","G7","G8"]

error_map:

E_INPUT: "reject_or_fix_contract"

E_DIM: "rollback_checkpoint"

E_GATE: "branch_or_degrade"

E_SYNC: "fallback_ptp_ntp"

E_UQ: "robust_surrogate_or_reject"

E_INTERNAL:"retry_then_alert"

idempotency_key: "run_id+partition+window"

retry_policy: { max_retries: 3, backoff: "exp", deadline: "10m" }

checkpoint: true

see:

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

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

B. Phase stage stage-40-phase.yaml

version: "1.0.0"

stage:

id: "stage-40-phase"

inputs: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.lambda_ref"]

outputs: ["obs.Phi"]

control:

form: "Phi = ( 2π / lambda_ref ) * ∫ n_eff d ell"

delta_form: "factored"

quality_gates: ["G1","G3","G4","G6","G7"]

see:

- "EFT.WP.Core.Equations v1.1:S21-2"

C. validate_report.json

{
  "stage_id": "stage-30-arrival",
  "gates": {
    "G1": true,
    "G2": 0.94,
    "G3": true,
    "G4": true,
    "G5": true,
    "G6": true,
    "G7": true,
    "G8": true
  },
  "stops_triggered": [  ]
}

X. Anti-Patterns & Fixes

• Anti: T_arr = ∫ n_eff / c_ref d ell (no parentheses) → Fix: T_arr = ( ∫ ( n_eff / c_ref ) d ell ).
• Anti: missing delta_form or d ell → Fix: add and align with n_eff.
• Anti: releasing without I70-dim_check → Fix: validate and attach check_dim_report.json, ensure p_dim = 1.0.

XI. Release & Layout

PTN_EXPORT/

stages/

stage-30-arrival.yaml

stage-40-phase.yaml

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

stage_dag.svg

path_alignment.pdf

report_manifest.yaml

SIGNATURE.asc

XII. Cross-References

• Architecture & graph: Ch. 3; Inbound contracts: Ch. 4; Timebase/Sync/Buffering: Ch. 5; Gates & monitoring: Ch. 9; UQ coupling & feedback: Ch. 10.
• Parameter/Error/Protocol templates: see respective chapters of Parameter / Error / Experimental Protocol.

XIII. Checklist

• Stage inputs/outputs aligned with TARR, units & dimensions clear.
• Control equations parenthesized, I70-dim_check passed, p_dim = 1.0; delta_form recorded for path stages.
• Gates G1–G8 mapped with thresholds; E_* semantics & compensation executable.
• Idempotency key, retry & checkpoints configured; audit events and input hashes complete.
• /validate passes; release includes stage specs, checks, and audit artifacts; citation anchor coverage ≥ 90%.