47-PTN Template v1.0 | Chapter 8 — Cross-References & Dependency Management

Home ／ Docs-Technical WhitePaper ／ 47-PTN Template v1.0

Chapter 8 — Cross-References & Dependency Management

I. Dependency Graph

1. Layered structure:
   • Core layer: Core.Terms v1.0, Core.Equations v1.1, Core.Parameters v1.0, Core.Metrology v1.0, Core.Errors v1.0, Core.DataSpec v1.0.
   • Methods/Metrology layer: Methods.* v1.0 (Repro/SimStack/Inference/Falsification/Cleaning/Imaging/CrossStats/SynthData), Metrology.* v1.0 (TimeBase/Sync/Instrument/PathCorrection).
   • Data/Engineering layer: Data.* v1.0 (DatasetCards/ModelCards/Pipeline/Benchmarks) and template families.
2. DAG requirement: upper layers must not back-reference lower layers; Core must not depend on Methods/Data; Methods may depend on Core; Data may depend on Core/Methods.
3. Key edges (examples):
   • Ch.2 Terms → Core.Terms v1.0:P10-*
   • Ch.3 Control eqs. → Core.Equations v1.1:S20-*, Core.Metrology v1.0:check_dim
   • Ch.4 Predictions/Falsification → Methods.Falsification v1.0, Methods.CrossStats v1.0
   • Ch.5 Data contract → Core.DataSpec v1.0:TARR, Core.Metrology v1.0
   • Ch.6 Design/Sampling → Metrology.* v1.0
   • Ch.7 Uncertainty → Core.Metrology v1.0, Methods.SimStack v1.0
4. Mandatory path terms: wherever arrival-time/phase or other path-dependent quantities are used, explicitly declare gamma(ell) and d ell, and record delta_form in data or metadata.

II. Reference Table (Normative Format)

Fixed syntax: See "<Volume> vX.Y" <Chapter> <Anchor>; prioritize P/S/M/I anchors; in-text citations and data-side see[] must match.

III. Lint Rules (Citation & Dependency Lint)

1. Coverage thresholds
   • Version presence ver_presence ≥ 1.00 (every citation must carry a version).
   • Anchor coverage anchor_coverage ≥ 0.90 (≥90% of citations point to P/S/M/I).
   • Path/measure presence path_measure_presence = 1.00 (100% of path expressions explicitly show gamma(ell), d ell and record delta_form).
2. Naming & conflicts
   • Forbid bare c, T, n; use c_ref, specific quantity (e.g., T_fil), and n_eff (or n).
   • Do not mix T_fil (tension) with T_trans (transmittance); do not mix n (number density) with n_eff (effective refractive index).
3. Writing & format
   • Inline symbols in backticks; any division/integral/composite operator must use parentheses.
   • Formulas, symbols, and definitions use international notation; section headings Roman numerals + bold; bullets use “- space”.
4. Dependency-graph checks
   • Reject cycles: detect reverse edges like Core ← Methods or Core ← Data; detect intra-chapter self-cycles.
   • Hierarchy violations: Data must not define base terminology or minimal equations; Methods must not override Core dimensional conventions.
5. Export consistency
   Release manifests must include references[] (volume+version+anchor) and version; manifest citations must match in-text citations.
6. Scoring & gating
   • Pass if ver_presence=1.00 ∧ anchor_coverage≥0.90 ∧ path_measure_presence=1.00 ∧ DAG acyclic.
   • Fail: mark lint:fail, block release, require fixes with precise locations.

IV. Resolution Playbook

• Missing version: look up latest stable line; do not assume; add versions to both text and see[].
• Missing anchor: request author to target P/S/M/I; if only chapter-level possible, tag as “temporary citation” and clear before release.
• Missing path/measure: add gamma(ell), d ell, and delta_form; if unavailable, remove path-based conclusions or downgrade to “illustrative”.
• Conflict names mixed: replace with canonical names; extend the “terminology alignment table” and lock under Ch.2.
• Circular dependency: break reverse pointers from upper to lower layers; lift shared content to Core or abstract into a shared Appendix.
• Cross-version mismatch: if text and manifest differ, treat manifest as source of truth and back-propagate; enforce equality before release.
• External links/aliases: forbid external URLs and aliases in text/data; only allow the canonical “volume+version+anchor” string.

V. Machine-Readable Rules & Examples (Drop-in)

A. references.yml (registry)

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"

methods_fals_plan: "EFT.WP.Methods.Falsification v1.0:PLAN"

methods_crossstats: "EFT.WP.Methods.CrossStats v1.0:KPI"

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

B. lint_config.yaml (rules & thresholds)

version: "1.0.0"

rules:

version_presence: 1.00

anchor_coverage: 0.90

path_measure_presence: 1.00

forbid_raw_symbols: ["c","T","n"]

conflict_pairs:

- ["T_fil","T_trans"]

- ["n","n_eff"]

dag_enforce: true

forbid_external_links: true

inline_code_backticks: true

outputs:

report: "reports/citation_lint.json"

gate: "G2"

C. citation_lint.json (report format)

{
  "ver_presence": 1.0,
  "anchor_coverage": 0.93,
  "path_measure_presence": 1.0,
  "dag_ok": true,
  "violations": [
    {
      "type": "FORBID_RAW_SYMBOL",
      "where": "Ch.3 §IV",
      "detail": "found raw 'n' → use 'n_eff' or 'n' with unit"
    }
  ],
  "actions": [ { "fix": "replace_raw_symbol", "targets": [ "n→n_eff" ], "status": "pending" } ]
}

D. Consistency across text and data

• In-text: See "EFT.WP.Core.Equations v1.1" Ch.2 S20-1.
• Data see[]: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim","EFT.WP.Core.DataSpec v1.0:TARR"].
• Export manifest.yaml includes: references[] and version, matching the text.

VI. Pre-Release Checklist

• All citations are “volume+version+anchor”; no aliases/external links.
• anchor_coverage ≥ 90%; remaining ≤10% are temporary and tracked for fix.
• All path expressions explicitly show gamma(ell) and d ell; delta_form recorded in metadata.
• Dependency graph is acyclic; layer boundaries respected.
• Release bundle contains references[] and version consistent with the text.
• No conflict-name mixing; bare c, T, n not used.

VII. Normalization Examples (Before/After)

• Incorrect: See "Core.Equations:S20-1" (missing version).
  Correct: See "EFT.WP.Core.Equations v1.1" Ch.2 S20-1.
• Incorrect: T_arr = ∫ n_eff / c_ref d ell (missing parentheses and path/measure).
  Correct: T_arr = ( ∫ ( n_eff / c_ref ) d ell ); text shows gamma(ell) & d ell, metadata adds delta_form.
• Incorrect: See Methods.Falsification (no anchor).
  Correct: See "EFT.WP.Methods.Falsification v1.0" Ch.* PLAN.

VIII. Release Gate (Aligned with Quality Gate G2)

• Triggers: ver_presence < 1, anchor_coverage < 0.90, path_measure_presence < 1, or dag_ok = false.
• Action: block release, emit citation_lint.json and a patch diff; auto-retry after fixes.