48-Experimental Protocol Card Template v1.0 | Chapter 12 — Appendices (Forms / Checklists / Templates)

Home ／ Docs-Technical WhitePaper ／ 48-Experimental Protocol Card Template v1.0

Chapter 12 — Appendices (Forms / Checklists / Templates)

I. Purpose & Scope

• Collect the forms, checklists, machine-readable templates, and export skeletons required to execute this protocol card; defaults align with Chapters 3–11, and citations use “volume + version + anchor (P/S/M/I)”.
• When path quantities (arrival time/phase) are involved, explicitly show gamma(ell) and the measure d ell in text, and record delta_form ∈ {general, factored} in data/metadata.

II. Appendix Index
A. Protocol card protocol.yaml
B. Release manifest manifest.yaml
C. Processing pipeline pipeline.yaml
D. Data schema schema.json (excerpt)
E. Error-budget card error_budget.csv (headers)
F. Quality-gate config gates.yaml
G. Fallback strategy fallbacks.yaml
H. Citation registry references.yml
I. Results page skeleton results.md (minimal)
J. Scorecard scorecard.json (excerpt)
K. Path data example paths.parquet (headers)
L. Audit trail audit.jsonl (single-line example)
M. Release directory layout & one-page publish checklist

III. Templates & Forms (drop-in)

A. protocol.yaml

version: "1.0.0"

protocol:

id: "ptn-exp-0001"

title: "Baseline PTN Observation"

geometry:

frame: "RA-Dec" # or "xyz"

q_att: [0,0,0,1]

r_hat: [<unit_vector>]

FOV_deg: 1.0

occlusion_mask: "masks/occ.png"

path:

gamma_ell: "<array-of-meters>" # explicit path

d_ell: "<array-of-meters>" # explicit measure

delta_form: "general" # or "factored"

timebase:

fs_hz: 2000

t_exp_s: 0.01

cadence_s: 0.05

band:

lambda_ref_m: 1.55e-6

k_ref_inv_m: 4.0536679e6

window: "hann" # rect|hann|blackman

instrument:

id: "INS-001"

mode: "timing" # imaging|spectral|mixed

calibration:

version: "1.2.0"

timestamp: "2025-09-24T10:00:00Z"

freshness_s: 86400

sync:

ref: "GNSS_PPS"

fallback: ["PTP","NTP"]

thresholds: { abs_ns: 50, skew_ns: 5, allan_1s: 1.0e-11 }

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

see:

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

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

- "EFT.WP.Core.DataSpec v1.0:TARR"

B. manifest.yaml

dataset_id: "ptn-demo"

version: "1.0.0"

created_at: "2025-09-24T16:00:00Z"

producer: "PTN.Workgroup.Core"

see:

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

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

- "EFT.WP.Core.DataSpec v1.0:TARR"

references:

- "EFT.WP.Core.Terms v1.0:P10-3"

checksum: { algo: "sha256", value: "<64-hex>" }

release_tier: "public"

C. pipeline.yaml

version: "1.0.0"

pipeline:

- id: step-10-ingest

in: ["raw/*.parquet"]

out: ["stage/ingested.parquet"]

checks: ["G1","G8"]

- id: step-20-calibrate

in: ["stage/ingested.parquet"]

out: ["stage/calibrated.parquet"]

checks: ["G5"]

- id: step-30-arrival

in: ["stage/calibrated.parquet"]

out: ["stage/arrival.parquet"]

compute:

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

requires: ["path.gamma_ell","path.d_ell","medium.n_eff_profile","ref.c_ref"]

delta_form: "general"

checks: ["G3","G4"]

- id: step-40-noisefit

in: ["stage/arrival.parquet"]

out: ["stage/denoised.parquet","reports/noise.json"]

model: "huber"

checks: ["G6"]

- id: step-50-export

in: ["stage/denoised.parquet"]

out: ["PTN_EXPORT/"]

checks: ["G2","G4","G7","G8"]

exports:

must_include: ["manifest.yaml","schema.json","check_dim_report.json","quality_report.json","audit.jsonl"]

D. schema.json (excerpt)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "PTN Data Object v1.0.0",
  "type": "object",
  "required": [ "record_id", "acq", "path", "medium", "ref", "obs", "version", "see", "references" ],
  "properties": {
    "record_id": { "type": "string" },
    "acq": {
      "type": "object",
      "required": [ "ts_start", "ts_end" ],
      "properties": {
        "ts_start": { "type": "string", "format": "date-time" },
        "ts_end": { "type": "string", "format": "date-time" }
      }
    },
    "path": {
      "type": "object",
      "required": [ "gamma_ell", "d_ell" ],
      "properties": {
        "gamma_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 },
        "d_ell": { "type": "array", "items": { "type": "number" }, "minItems": 2 }
      }
    },
    "medium": {
      "type": "object",
      "required": [ "n_eff_profile" ],
      "properties": { "n_eff_profile": { "type": "array", "items": { "type": "number" }, "minItems": 2 } }
    },
    "ref": {
      "type": "object",
      "required": [ "c_ref" ],
      "properties": { "c_ref": { "type": "number", "minimum": 290000000.0, "maximum": 310000000.0 } }
    },
    "obs": {
      "type": "object",
      "properties": { "T_arr": { "type": "number" }, "Phi": { "type": "number" } }
    },
    "see": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "references": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "version": { "type": "string" }
  }
}

E. error_budget.csv (headers)

source,symbol,unit,type,estimate,distribution,correlation,note,see[]

Absolute timing,δt_abs,s,A,u(δt_abs),approx-N,vs_channel_skew,,Core.Metrology v1.0

Path measure,d ell,m,B,u(d ell),uniform,with gamma(ell),,Core.DataSpec v1.0:TARR

Medium index,n_eff(ell),1,A/B,u(n_eff),GP(L_c),length L_c,,Core.Terms v1.0

F. gates.yaml

version: "1.0.0"

gates:

G1: { schema: true }

G2: { cite_anchor_min: 0.90, forbid_external_links: true }

G3: { path_min_len: 2, require_sync: true }

G4: { p_dim: 1.0, units: { T_arr: "s", Phi: "rad" } }

G5: { tau_calib_s_max: 86400 }

G6: { Q_res_band: [0.0, 0.2], robust_surrogate: true }

G7: { epsilon_flux_guard: "≈0@O(theta^2)" }

G8: { unique_record_id: true, unique_checksum: true }

G. fallbacks.yaml

version: "1.0.0"

triggers:

SYNC: ["clock_unlocked","abs_t_over","skew_over","allan_over"]

DIM: ["p_dim_fail","check_dim_fail"]

SMP: ["fs_below_nyquist","Delta_ell_over","path_len_short","path_desync"]

PAX: ["theta_over","coherence_fail"]

NOISE: ["Q_res_over","flux_nonconserve"]

CALIB: ["tau_calib_expired","u_theta_over"]

CITE: ["ver_missing","anchor_coverage_low","external_link_found"]

INTG: ["record_dup","checksum_dup","audit_missing"]

actions:

sync_fallback: ["GNSS","PTP","NTP"]

switch_fullwave: true

segment_adapt: { T_coh: "shrink", L_coh: "shrink", B_coh: "increase" }

robust_substitute: ["huber","quantile"]

recalibrate: true

labels:

restricted: "[Restricted]"

H. references.yml

version: "1.0.0"

refs:

core_terms_p10_3: "EFT.WP.Core.Terms v1.0:P10-3"

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

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

core_dataspec_tarr: "EFT.WP.Core.DataSpec v1.0:TARR"

met_sync_pps: "EFT.WP.Metrology.Sync v1.0:PPS"

methods_bench: "Data.Benchmarks v1.0:PROTO"

I. results.md (minimal)

# PTN Results — v1.0.0

## 1. Summary

- One-liner; core metrics with intervals (ΔT_arr, r_phi, ε_flux, p_dim, Q_res).

## 2. Identifiers

- dataset_id / method_id / baseline_id / versions / seeds / time window.

## 3. Core Metrics

- ΔT_arr (s): mean ± U(k), histogram/KDE, BA plot.

- r_phi (1): value + 95% CI; phase scatter vs identity.

- ε_flux (1): distribution; paraxial guard lines.

- p_dim (1), Q_res (1).

## 4. Compliance

- check_dim_report.json summary; anchor_coverage / ver_presence; clock_state / τ_calib.

## 5. Figures

- PDF/PNG list with units & legends.

J. scorecard.json (excerpt)

{

"version": "1.0.0",

"dataset_id": "ptn-demo",

"baseline": { "id": "base-001", "version": "1.2.3" },

"method": { "id": "mA-010", "version": "2.0.0" },

"metrics": {

"DeltaT_arr_s": { "mean": -2.3e-9, "std": 4.8e-9, "U_k2": 1.5e-9 },

"r_phi": { "value": 0.72, "ci95": [0.61, 0.80] },

"epsilon_flux": { "median": 0.004, "p95": 0.011 },

"p_dim": 1.0,

"Q_res": 0.13

},

"score": { "Q": 0.78 },

"tests": {

"paired": { "DeltaT_arr": { "p_perm": 0.004, "B": 10000 } },

"FDR": 0.08

},

"see": [

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

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

"Data.Benchmarks v1.0:PROTO"

],

"version_lock": true

}

K. paths.parquet (header example)

record_id,gamma_ell[],d_ell[],n_eff[],unit_gamma,unit_dell,unit_n,delta_form

01H..., [..], [..], [..], m, m, 1, general

L. audit.jsonl (single-line example)

{
  "run_id": "01JXYZABCD...",
  "started_at": "2025-09-24T16:10:00Z",
  "tools": [ { "name": "ptn-cli", "version": "1.4.2" } ],
  "random_seeds": [ 20250924 ],
  "input_hashes": [ "sha256:..." ],
  "events": [ { "ts": "...", "clock_state": "locked", "delta_t_abs_ns": 23, "allan_1s": 1.2e-11 } ],
  "references": [ "EFT.WP.Core.Equations v1.1:S20-1" ],
  "version": "1.0.0"
}

IV. Recommended Release Directory Layout

PTN_EXPORT/

manifest.yaml

data/

observations.parquet

paths.parquet

schema/

schema.json

reports/

check_dim_report.json

quality_report.json

audit.jsonl

figs/

*.pdf

*.png

scorecard.json

results.md

SIGNATURE.asc

V. One-Page Publish Checklist

• In text and data, see[]/references[] use “volume+version+anchor”, anchor coverage ≥ 90%, no external links/aliases.
• Path expressions explicitly show gamma(ell) and d ell; delta_form recorded; len(path) ≥ 2.
• p_dim = 1.0, clock_state = locked, |ts_start − calib.timestamp| ≤ τ_calib.
• Sampling satisfies f_s ≥ 2 f_max, Δell ≤ ( c_ref / f_s ) / max(n_eff); phase sampling Δt ≤ λ_ref / (2 c_ref).
• Release bundle complete: manifest/schema/data/reports/figs/scorecard/results.md; unique checksum and signed.
• Bare c, T, n forbidden; do not mix T_fil/T_trans or n/n_eff; axes units and dimensions explicit in captions.
• If [Restricted], all figures tagged and triggers listed; publish qualitative conclusions and diagnostics only.

VI. Citations & Versioning

• Fixed syntax: See "<Volume> vX.Y" <Chapter> <Anchor>; prioritize P/S/M/I; keep text and exports consistent.
• Normative anchor examples: EFT.WP.Core.Equations v1.1:S20-1/S21-2, EFT.WP.Core.Metrology v1.0:check_dim, EFT.WP.Core.DataSpec v1.0:TARR, Data.Benchmarks v1.0:PROTO.
• Public releases use v1.* only; if v0.* is required, mark “draft / non-committal”.