50-Parameter Registration Card Template v1.0 | Chapter 5 — Source, Lineage & Traceability

Home ／ Docs-Technical WhitePaper ／ 50-Parameter Registration Card Template v1.0

Chapter 5 — Source, Lineage & Traceability

I. Purpose & Scope

• Provide unified conventions for parameter source, lineage, and traceability, covering source types, measurement/derivation/configuration workflows, instrument & run identifiers, validity & freshness policies, audit trail, and rollback.
• For path quantities (arrival time/phase), explicitly show gamma(ell) and the measure d ell in text, and record delta_form ∈ {general, factored} in the card; publication requires p_dim = 1.0.

II. Source Types & Minimal Fields

• measured: values obtained directly by measurement.
  Minimal fields: instrument, method, calib_run_id, operator, site.
• derived: values computed from upstream parameters via model/control equations.
  Minimal fields: inputs[], derive_expr, software/version, commit_hash, runtime_env.
• configured: fixed or enumerated values set by baseline/policy.
  Minimal fields: policy_ref, baseline_id, rationale, approver.

Unified lineage block:
lineage{ source_type, method, instrument, calib_run_id, operator, site, inputs[], derive_expr, software, version, commit_hash, runtime_env, policy_ref, baseline_id, rationale, approver }

III. Lineage Graph & Dependencies

• Dependency declaration: list upstream parameter param_id in constraints.depends_on[], and locate via see[] anchors.
• Derivation relation: provide a parenthesized control equation in constraints.derived (e.g., τ_sys = τ_base + α_T·ΔT), ensuring it passes I70-dim_check.
• Layered lineage: measured → calibrated → derived → configured; backtrack by layer. Cross-card/cross-volume links must record upstream version and checksum.
• Graph export: lineage_graph.json records nodes/edges (with timestamps and versions) as adjacency/edge lists.

IV. Freshness & Validity

• Fields: freshness{ valid_from, valid_to, policy{ tau_calib_s_max, clock_state } }.
• Policy: treat as fresh when |ts_now − calib.timestamp| ≤ tau_calib_s_max and clock_state="locked"; otherwise enter Restricted or trigger recalibration.
• Rolling update: before expiry, generate the next-version card and seamlessly switch in the registry, keeping prior versions for backtracking.

V. Audit Trail & Rollback

• Audit file: audit.jsonl logs per-event generation time, operator, input_hashes[], software/version, random seed, and change notes.
• Version locking: use I27-lock_version(param_id, semver) to create immutable tags; record “rollback from/to” in the audit when rolling back.
• Fingerprint & signature: all artifacts include checksum (sha256) and optional SIGNATURE.asc, listed in report_manifest.yaml.

VI. Compliance Module

• G4 | Dimensional closure: constraints.derived passes I70-dim_check; attach check_dim_report.json; p_dim=1.0.
• G5 | Freshness: valid_to not expired and clock_state="locked"; if expired, trigger recalibration.
• G2 | Citation compliance: see[]/references[] use “volume + version + anchor (P/S/M/I)”, anchor coverage ≥ 90%, no external links/aliases.
• G8 | Uniqueness: unique param_id; non-duplicated registry checksum; lineage graph must be acyclic.

VII. Path-Specific Requirements

• Provide explicit path and measure in path{ gamma, measure, delta_form }, consistent with domain.shape.
• For path functions such as n_eff(ell), record fitting/sampling methods and kernel parameters (see Error Budget Card Ch. 5).
• Annotate coherence windows (T_coh/L_coh/B_coh) and reference-window alignment info in the lineage graph.

VIII. Normative Examples

# A) measured: system delay τ_sys

version: "1.0.1"

param_id: "CAL-01-τ_sys"

name: "system_delay"

symbol: "τ_sys"

domain: { type: "real", unit: "s", range: [0, 1e-3], default: 1.0e-6, precision: "float64" }

lineage:

source_type: "measured"

method: "loopback"

instrument: "DPO-7k"

calib_run_id: "CAL2025-09-24-01"

operator: "tech-ops"

site: "lab-A"

freshness:

valid_from: "2025-09-24T00:00:00Z"

valid_to: "2025-10-24T00:00:00Z"

policy: { tau_calib_s_max: 86400, clock_state: "locked" }

uncertainty: { type: "A", estimate: 2.0e-8, distribution: "normal", coverage: { k: 2 } }

constraints: { depends_on: ["ENV-02-ΔT"], derived: "" }

cov_group: "timing"

status: "stable"

see: ["Metrology.Sync v1.0:PPS","EFT.WP.Core.Metrology v1.0:check_dim"]

# B) derived: effective refractive index profile n_eff(ell)

version: "1.0.0"

param_id: "PHY-03-n_eff_profile"

name: "effective_index_profile"

symbol: "n_eff(ell)"

domain: { type: "array", unit: "1", shape: ["N"], range: [0.8, 2.5], precision: "float64" }

lineage:

source_type: "derived"

method: "kernel_fit"

inputs: ["RAW-01-phase_trace","REF-01-λ_ref"]

derive_expr: "n_eff(ell) = g(Phi(ell), λ_ref)"

software: "idxfit"

version: "2.4.1"

commit_hash: "8f2c7d1"

runtime_env: "cuda12.2-py3.11"

freshness:

valid_from: "2025-09-24T00:00:00Z"

valid_to: "2026-09-24T00:00:00Z"

policy: { tau_calib_s_max: 86400, clock_state: "locked" }

uncertainty: { type: "A/B", estimate: 3.0e-3, distribution: "gaussian", coverage: { k: 2 } }

path:

gamma: "gamma(ell)"

measure: "d ell"

delta_form: "general"

constraints:

depends_on: ["ENV-01-α_T","ENV-02-ΔT"]

derived: ""

cov_group: "medium"

status: "stable"

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

# C) configured: Huber loss δ

version: "1.0.0"

param_id: "ALG-05-huber_delta"

name: "huber_delta"

symbol: "δ_huber"

domain: { type: "real", unit: "1", range: [0.1, 5.0], default: 1.345, precision: "float64" }

lineage:

source_type: "configured"

policy_ref: "ROBUST-BASE-2025"

baseline_id: "bench-2025Q3"

rationale: "robust residual control"

approver: "ml-lead"

freshness:

valid_from: "2025-01-01T00:00:00Z"

valid_to: "9999-12-31T23:59:59Z"

policy: { tau_calib_s_max: 86400, clock_state: "locked" }

uncertainty: { type: "B", estimate: 0.0, distribution: "degenerate", coverage: { k: 2 } }

cov_group: "algo"

status: "stable"

see: ["ErrorBudget.Template v1.0:Ch.6","PTN.Template v1.0:Ch.7"]

IX. Machine-Readable & Graph
A. lineage_graph.json (edge list)

{

"nodes": [

{"id":"CAL-01-τ_sys","version":"1.0.1"},

{"id":"ENV-02-ΔT","version":"1.0.0"},

{"id":"PHY-03-n_eff_profile","version":"1.0.0"}

],

"edges": [

{"from":"ENV-02-ΔT","to":"CAL-01-τ_sys","type":"depends_on"},

{"from":"RAW-01-phase_trace","to":"PHY-03-n_eff_profile","type":"input"},

{"from":"REF-01-λ_ref","to":"PHY-03-n_eff_profile","type":"input"}

],

"meta": {"generated_at":"2025-09-24T16:00:00Z","checksum":"sha256:..."}

}

B. report_manifest.yaml (with audit & hashes)

version: "1.0.0"

bundle:

cards: ["param_card.yaml"]

graphs: ["lineage_graph.json"]

reports: ["check_dim_report.json","audit.jsonl"]

metadata:

dataset_id: "ptn-demo"

method_version: "2.0.0"

checksum: "sha256:..."

see:

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

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

X. Cross-References

• Control equations & path: Ch. 3 and EFT.WP.Core.Equations v1.1.
• Units & dimensions: Ch. 4 and EFT.WP.Core.Metrology v1.0.
• Uncertainty & covariance: Error Budget Card Ch. 5/8/9.
• Data contract & release: EFT.WP.Core.DataSpec v1.0:TARR and PTN Template Ch. 5/11.

XI. Checklist

• lineage.source_type ∈ {measured, derived, configured} with minimal fields complete.
• constraints.depends_on[] and derived declared and passed I70-dim_check; check_dim_report.json attached.
• freshness.valid_from/valid_to and policy{tau_calib_s_max, clock_state} compliant; not expired.
• audit.jsonl logs generation/changes; I27-lock_version set; checksum and signature ready.
• For path quantities, explicit gamma(ell)/d ell; delta_form recorded; coherence & reference-window alignment documented.
• see[]/references[]/version compliant with anchor coverage ≥ 90%; registry acyclic and unique.