refactor: convention-default helpers live in base.py, not yaml_source (#77)

OssieSource had been importing _parse_convention_default and
_apply_convention_default -- two private functions -- across from
yaml_source.py. Every other helper shared between the sources lives in
base.py and is imported by both: validate_decompositions,
validate_drill_by, parse_review_date, jsonify_extras,
build_relationship_index.

Two things made the old placement the odd one out. Both helpers operate
purely on MetricDefinition / Decomposition and touch nothing
YAML-specific, and both had to import VALID_CONVENTIONS and
_CROSS_TERM_OPERATORS back out of base.py to do their work. After the
move yaml_source.py needs neither constant for anything else -- it had no
other consumer of them -- which is the clearest evidence the vocabulary
they enforce already lived where the functions belonged.

parse_review_date's docstring states the principle the move follows: it
is shared rather than per-source because every format reaching the same
field reaches the same arithmetic, "so a second copy of this would be a
second chance to get the subclass ordering wrong." Both sources resolve a
house default onto the same Decomposition.convention field, and
fold_into-is-not-a-valid-default is exactly the rule that drifts if it is
ever copied.

No behavior change. Both source paths keep their existing tests, and
verified directly that a YAML default still resolves (split_evenly), an
Ossie vendor-block default still resolves (explicit), a fold_into
source-level default is still rejected, and the pinned round-trip digest
is unmoved. 1078 passing.

No version bump: both functions are private, so nothing on the public
surface changed. Rides along with the 0.43.1 already on main.

Closes #74

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: flyersworder

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
 
 ### Internal
 
+- **The convention-default helpers moved to `semantic/base.py`.** `OssieSource` had been importing `_parse_convention_default` / `_apply_convention_default` — two *private* functions — across from `yaml_source.py`, while every other helper shared between sources (`validate_decompositions`, `validate_drill_by`, `parse_review_date`, `jsonify_extras`, `build_relationship_index`) lives in `base.py`. The giveaway was that both had to import `VALID_CONVENTIONS` and `_CROSS_TERM_OPERATORS` back out of `base.py` to do their work, and that those two constants had no other consumer in `yaml_source.py` — the vocabulary they enforce already lived where the functions belonged. `parse_review_date`'s own docstring states the principle: a second copy is a second chance to get the rule wrong, and both sources resolve a default onto the same `Decomposition.convention` field. No behavior change; both source paths keep their existing tests. ([#74](https://github.com/flyersworder/agentic-data-contracts/issues/74))
 - **The pinned round-trip digest now covers metric serialization.** `_PINNED_ROUNDTRIP_DIGEST` is the repo's broadest guard against canonical-bytes drift, but it was computed over a semantic source with no `metrics:` key at all, so `_dump_metric` was never called and it could not see any change to metric serialization. That is worse than a missing test, because the assertion passed either way: every optional field added to `_dump_metric` since the pin was written could have been made unconditional — moving the digest of every real contract and invalidating every published ARD attestation — with the test still green. The fixture now carries a metric exercising every optional field the dump writes plus two leaves for the omit-when-empty branches, verified by mutation (removing the `if m.decompositions:` guard now fails the pin), and a companion test asserts the pinned contract's canonical bytes still carry those fields so the coverage cannot be silently narrowed again. No shipped code changed. ([#73](https://github.com/flyersworder/agentic-data-contracts/issues/73))
 
 ## [0.43.0] - 2026-08-18

src/agentic_data_contracts/semantic/base.py

@@ -331,6 +331,60 @@ def visit(node: str, stack: list[str]) -> None:
         visit(node, [])
 
 
+# Shared by every source that can carry a house convention, for the reason
+# ``parse_review_date`` records just above: both ``YamlSource`` and
+# ``OssieSource`` resolve a default onto the same ``Decomposition.convention``
+# field, and a second copy would be a second chance to get the
+# fold_into-is-not-a-default rule wrong.
+def _parse_convention_default(raw: Any) -> str | None:
+    """Read and validate the source-level ``decomposition_convention`` block.
+
+    ``fold_into`` is rejected: it names an operand, and no operand name is
+    meaningful across metrics. Declaring it source-wide is always a mistake.
+    """
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        raise ValueError(
+            "decomposition_convention must be a mapping with a 'convention' key,"
+            f" got {type(raw).__name__}"
+        )
+    convention = raw.get("convention")
+    if convention is None:
+        raise ValueError("decomposition_convention must set 'convention'")
+    if convention not in VALID_CONVENTIONS:
+        raise ValueError(
+            f"decomposition_convention has unknown attribution convention"
+            f" {convention!r}; expected one of {sorted(VALID_CONVENTIONS)}"
+        )
+    if convention == "fold_into":
+        raise ValueError(
+            "convention 'fold_into' cannot be a source-level default: it names"
+            " an operand, and no operand name is meaningful across metrics."
+            " Declare it per decomposition."
+        )
+    return convention
+
+
+def _apply_convention_default(
+    metrics: list[MetricDefinition], default: str | None
+) -> None:
+    """Stamp *default* onto every cross-term decomposition that declares none.
+
+    Resolved at load rather than carried, so the effective value survives
+    ``freeze_semantic_source`` (which re-serializes from parsed objects) and a
+    frozen contract states its convention outright instead of leaving a
+    consumer to re-derive it. Linear operators are skipped: a convention on
+    them fails ``validate_decompositions``.
+    """
+    if default is None:
+        return
+    for metric in metrics:
+        for decomp in metric.decompositions:
+            if decomp.convention is None and decomp.operator in _CROSS_TERM_OPERATORS:
+                decomp.convention = default
+
+
 def validate_drill_by(
     metrics: list[MetricDefinition],
     table_schemas: dict[str, TableSchema],

src/agentic_data_contracts/semantic/ossie.py

@@ -46,17 +46,15 @@
     MetricDefinition,
     MetricImpact,
     Relationship,
+    _apply_convention_default,
+    _parse_convention_default,
     build_relationship_index,
     fuzzy_search_metrics,
     jsonify_extras,
     parse_review_date,
     validate_decompositions,
     validate_drill_by,
 )
-from agentic_data_contracts.semantic.yaml_source import (
-    _apply_convention_default,
-    _parse_convention_default,
-)
 
 logger = logging.getLogger(__name__)
 

src/agentic_data_contracts/semantic/yaml_source.py

@@ -11,13 +11,13 @@
 
 from agentic_data_contracts.adapters.base import Column, TableSchema
 from agentic_data_contracts.semantic.base import (
-    _CROSS_TERM_OPERATORS,
-    VALID_CONVENTIONS,
     Decomposition,
     DrillDimension,
     MetricDefinition,
     MetricImpact,
     Relationship,
+    _apply_convention_default,
+    _parse_convention_default,
     build_relationship_index,
     fuzzy_search_metrics,
     jsonify_extras,
@@ -78,55 +78,6 @@ def _apply_extras_policy(
         )
 
 
-def _parse_convention_default(raw: Any) -> str | None:
-    """Read and validate the source-level ``decomposition_convention`` block.
-
-    ``fold_into`` is rejected: it names an operand, and no operand name is
-    meaningful across metrics. Declaring it source-wide is always a mistake.
-    """
-    if raw is None:
-        return None
-    if not isinstance(raw, dict):
-        raise ValueError(
-            "decomposition_convention must be a mapping with a 'convention' key,"
-            f" got {type(raw).__name__}"
-        )
-    convention = raw.get("convention")
-    if convention is None:
-        raise ValueError("decomposition_convention must set 'convention'")
-    if convention not in VALID_CONVENTIONS:
-        raise ValueError(
-            f"decomposition_convention has unknown attribution convention"
-            f" {convention!r}; expected one of {sorted(VALID_CONVENTIONS)}"
-        )
-    if convention == "fold_into":
-        raise ValueError(
-            "convention 'fold_into' cannot be a source-level default: it names"
-            " an operand, and no operand name is meaningful across metrics."
-            " Declare it per decomposition."
-        )
-    return convention
-
-
-def _apply_convention_default(
-    metrics: list[MetricDefinition], default: str | None
-) -> None:
-    """Stamp *default* onto every cross-term decomposition that declares none.
-
-    Resolved at load rather than carried, so the effective value survives
-    ``freeze_semantic_source`` (which re-serializes from parsed objects) and a
-    frozen contract states its convention outright instead of leaving a
-    consumer to re-derive it. Linear operators are skipped: a convention on
-    them fails ``validate_decompositions``.
-    """
-    if default is None:
-        return
-    for metric in metrics:
-        for decomp in metric.decompositions:
-            if decomp.convention is None and decomp.operator in _CROSS_TERM_OPERATORS:
-                decomp.convention = default
-
-
 class YamlSource:
     """Loads metric and table definitions from a YAML file."""