03-EFT.WP.Core.Parameters v1.0 | Chapter 8 — Governance, Versioning, and Reuse

Home ／ Docs-Technical WhitePaper ／ 03-EFT.WP.Core.Parameters v1.0

Chapter 8 — Governance, Versioning, and Reuse

I. Aims and Scope

• Establish a governance framework for parameter assets: semantic versioning, scenario management, alias strategy, freeze/thaw, compatibility, and regression baselines.
• Define the minimal workflow Mx-4, bind to implementation interfaces I30 9/11/12, and ensure cross-volume reuse and traceability.
• Reinforce conflict avoidance: strictly distinguish T_fil vs T_trans and n vs n_eff; any path quantity must declare gamma(ell) and d ell.

II. Governed Artifacts and Roles

1. Governed artifacts
   • Parameter registry: canonical entries created via register_param (fields include code/unit/role/bounds/prior/transform, etc.).
   • Scenarios and baselines: parameter sets managed by create_scenario/activate_scenario and their regression baselines.
   • Reuse relations: dependency graph formed by add_alias / tie_params / derive_param / freeze / thaw.
2. Typical roles (responsibilities)
   • Maintainer: approves MAJOR changes and freeze policies.
   • Contributor: adds entries and aliases, submits scenario diffs.
   • Reviewer: runs regression and compatibility checks, issues version tags.

III. Semantic Versioning and Numbering (Governance Postulates P81-1…P81-3)

1. P81-1 Semantic versioning
   • Versions use MAJOR.MINOR.PATCH, advanced via bump_version(semver).
   • PATCH: no change in semantics or interfaces; fixes prior hyper-parameters, defaults, or docs only; code/unit/bounds/transform unchanged.
   • MINOR: backward-compatible enhancements, e.g., adding parameters (with defaults and priors), relaxing bounds, adding aliases; existing YAML parses without edits and reproduces the same values.
   • MAJOR: any breaking change (renaming code, changing unit, changing transform family or scaling, tightening bounds so prior values become invalid, or altering physical semantics).
2. P81-2 Compatibility definition
   Given old set X_old and new set X_new, the change is backward-compatible if export_params("yaml") from the old parses under import_params with no warnings and compare_param_sets(X_old, X_new, ["L2","Corr"]) yields L2 ≤ ε_L2 and Corr ≥ 1−ε_corr.
3. P81-3 Invisible changes
   Any modification that changes a check_dim(expr) conclusion is MAJOR, even if numerics remain unchanged.

IV. Scenario Management and Inheritance (Minimal Workflow Mx-4A)

• Create: SRef = create_scenario(name, base=None|base_name) to clone a parameter set from base.
• Activate: activate_scenario(name) to make it the current working set.
• Overlay and resolution (S81-1)
  With hierarchy base → scenario → local, define the effective value as
  value_eff(code) def= select( local, scenario, base ) (right-to-left override; missing fields inherit).
• Diff and audit: diff_scenarios(a,b) produces field-level diffs and dependency impact.
• Freeze baseline: export_params("yaml") to establish the regression baseline artifact, annotating version/scene/hash.

V. Aliases, Normalization, and Redirection (Minimal Equation S81-2)

1. Normalization pipeline
   token → normalize_param(token) → canonical code
2. Constraints and conflicts
   • A single alias must not map to multiple canonicals.
   • An alias must not collide with any code.
3. Migration guidance
   Introduce aliases only in MINOR/MAJOR releases, and always write back the canonical in exports to keep artifacts stable.

VI. Freeze/Thaw and Sharing (Governance Postulates P81-4…P81-5)

• P81-4 Freeze semantics
  After freeze(code), any set_bounds/set_prior/set_transform/derive_param/tie_params for that code is disallowed; thawing requires an explicit thaw(code) and an audit trail.
• P81-5 Sharing and binding
  Sharing must be explicit: theta_a = theta_b or theta_a def= g(theta_b) (established via tie_params/derive_param). Any implicit sharing is a policy violation.

VII. Compatibility Matrix and Change Control (Minimal Workflow Mx-4B)

• Change proposal: describe intended edits to code/unit/bounds/prior/transform and the impact surface.
• Dimensional review: run check_dim(expr) for impacted expressions; any path term must use ( n_eff / c_ref ) * d ell with explicit gamma(ell).
• Regression baseline: compare_param_sets(X_old, X_new); thresholds ε_L2, ε_corr are scenario-defined.
• Impact propagation: if S20-* (arrival time) or S40-* (tension field) is affected, use compute_jacobian to obtain ∂ g / ∂ theta for a first-order assessment and trigger sampling-based propagation where needed (see Chapter 7).
• Version issuance: classify per P81-1 and bump_version; produce release notes and a change log (Appendix B).

VIII. Import/Export and Regression Baselines (Minimal Equation S81-3)

• Export artifact schema (minimal YAML fields)
  code, name, role, unit, default, bounds{lb,ub}, prior{family,hyper{...}}, transform{name,args}, version, scene, depends, status
• Baseline naming
  RB-Param-<scene>-v<MAJOR.MINOR>; update with each MINOR by recommendation.
• Baseline comparison (via compare_param_sets)
  Pass if L2 ≤ ε_L2 and Corr ≥ 1−ε_corr; otherwise mark as “potentially breaking” and require MAJOR or migration scripts.

IX. Reuse and Cross-Volume Binding (Minimal Workflow Mx-4C)

• Binding identification: list the parameters coupled to target equations Sxx-* (e.g., arrival time requires c_ref, n_eff), and declare gamma(ell) and d ell.
• Consistency checks: call check_dim and apply Chapter 7 linearization to verify ( n_eff / c_ref ) * d ell is dimensionless.
• Derivation and propagation: for non-dimensional parameters, use derive_param("bar_n_eff", "n_eff / n_eff_ref", ["n_eff","n_eff_ref"]), and preserve dependencies in exports.
• Change linkage: any MAJOR change to a bound parameter triggers compatibility review and regression in the corresponding equation volume.

X. Audit and Traceability

• Audit record should include: operator, timestamp, scene, changed fields, old→new, rationale, linked issues, regression outcome, version tag.
• Artifact integrity: compute an sha256 digest at export and write it into the metadata field hash (text only; independent of implementation).

XI. Standard Governance Pipeline Mx-4 (End-to-End)

• Initiate and baseline: create_scenario → export_params to create RB-Param-<scene>-vX.Y.
• Implement changes: add/modify parameters or relations (register_param/add_alias/tie_params/derive_param), freeze/thaw as necessary.
• Validation triad: validate_param_set, check_dim(expr), compare_param_sets.
• Compatibility decision: classify as PATCH/MINOR/MAJOR per P81-1; prepare migration and alias tables.
• Version issuance and archiving: bump_version, publish release notes and audit records, update the regression baseline.
• Cross-volume sync: register citation updates in Core.Equations/Core.Terms and validate arrival-time use cases.

XII. Misuse and Conflict Checklist

• Silent edits to bounds/prior/transform while frozen.
• Writing artifacts with aliases or mixing alias and canonical inside the same artifact.
• Changing unit or scaling but labeling as MINOR/PATCH.
• Using n in place of n_eff in the arrival-time chain, or writing ∫ n d ell / c (missing parentheses and no path declared).
• Exporting without prior.hyper or without bounds, making the feasible set Theta undecidable.

XIII. Output Anchors and Citations

• Governance postulates: P81-1 (semantic versioning), P81-2 (compatibility definition), P81-3 (dimension change ⇒ MAJOR), P81-4 (freeze semantics), P81-5 (explicit sharing).
• Minimal equations: S81-2 (alias normalization), S81-3 (export artifact minimal fields), S81-1 (scenario overlay resolution).
• Standard workflows: Mx-4A/B/C (scenario management, change control, cross-volume binding).
• Interfaces: I30 9/11/12 with compare_param_sets, check_dim, compute_jacobian, export_params / import_params.