focus-data-toolkit 0.11.0__py3-none-any.whl

focus_data_toolkit/supplement/apply.py

@@ -0,0 +1,318 @@
+"""Apply validated supplements to the derived datasets (ENRICHED lineage).
+
+Mode rules, per fact column present in a supplement table:
+
+* **Strict** — a value is either supplied by the client or empty; synthetic defaults
+  are never emitted. A *non-nullable* column's rule flips to ``ENRICHED`` only at
+  100 % key coverage (otherwise it keeps blocking and the dataset stays
+  ``NOT_PRODUCED``); a *nullable* column flips to ``ENRICHED`` as soon as the
+  supplement carries it, with per-value counters recording the supplied/null mix.
+* **Synthetic** — a supplied value wins, the documented synthetic default fills the
+  rest. The headline rule flips to ``ENRICHED`` only at full coverage (otherwise it
+  stays ``ASSUMED`` — the weakest lineage present), with counters showing the mix.
+
+The strict gate itself is untouched: ``ENRICHED`` is already factual, so a fully
+covered dataset simply stops blocking.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from focus_data_toolkit.convert.invoice_detail import (
+    GrainKey,
+    invoice_detail_grain_key,
+)
+from focus_data_toolkit.model import dataset_columns
+from focus_data_toolkit.model.validator import load_model
+from focus_data_toolkit.provenance import ColumnRule, Lineage, LineageCounters
+from focus_data_toolkit.supplement.loader import SupplementBundle, SupplementTable
+from focus_data_toolkit.supplement.validate import SourceKeySets, coverage
+
+# Invoice Detail columns normally omitted (unfilled conditionals) that a supplement can
+# activate; non-nullable ones require full coverage to be emitted at all.
+_ACTIVATABLE_INVOICE_COLUMNS = (
+    "PaymentCurrency",
+    "PaymentCurrencyBilledCost",
+    "PaymentCurrencyInvoiceDetailId",
+    "PurchaseOrderNumber",
+)
+
+
+@dataclass
+class AppliedDataset:
+    """Outcome of applying supplements to one dataset."""
+
+    rows: list[dict[str, str]] | None
+    provenance: dict[str, ColumnRule]
+    counters: LineageCounters = field(default_factory=LineageCounters)
+
+
+def _source_label(table: SupplementTable, column: str) -> str:
+    # Per-column attribution: a merged table (adapter export + hand-authored file) tags each
+    # column to its originating file ("supplement:<adapter>@<version>:<file>" or the kind).
+    return table.source_for(column)
+
+
+def _allows_nulls(dataset: str, column: str) -> bool:
+    spec = load_model()["datasets"][dataset]["columns"].get(column) or {}
+    return bool(spec.get("allows_nulls", True))
+
+
+def _flip_rules(
+    base: dict[str, ColumnRule],
+    dataset: str,
+    tables: list[SupplementTable],
+    source: SourceKeySets,
+) -> dict[str, ColumnRule]:
+    """Return ``base`` with columns flipped to ENRICHED per the coverage rules."""
+    rules = dict(base)
+    for table in tables:
+        cov = coverage(table, source.keys_for(table.kind.name))
+        for column in table.fact_columns:
+            if table.kind.name == "invoice_line" and column == "BilledCost":
+                continue  # reconciliation-only, never applied
+            if column not in dataset_columns(dataset):
+                continue
+            col_cov = cov[column]
+            complete = col_cov.complete
+            nullable = _allows_nulls(dataset, column)
+            if complete or (nullable and col_cov.covered > 0):
+                note = None if complete else "nulls where the client supplied no value"
+                rules[column] = ColumnRule(Lineage.ENRICHED, _source_label(table, column), note)
+    return rules
+
+
+# Public alias: the streaming pipeline pre-computes the rule flips (rows-independent)
+# to decide strict back-link gating before the main pass.
+flip_enriched_rules = _flip_rules
+
+
+def _apply_column(
+    row: dict[str, str],
+    column: str,
+    supplied: str,
+    *,
+    synthetic: bool,
+    counters: LineageCounters,
+    base_is_factual: bool = False,
+) -> None:
+    """Write one fact column: supplied value, else keep the base value / synthetic default.
+
+    ``base_is_factual`` marks an *override* column that already carries a factual base value
+    (e.g. Contract Commitment ``ServiceProviderName`` from the provider context). For an
+    uncovered row such a column must keep its base value — never be blanked — so a partial
+    override does not turn otherwise-valid rows into mandatory-null failures.
+    """
+    if supplied:
+        row[column] = supplied
+        counters.record(column, Lineage.ENRICHED)
+    elif base_is_factual and (row.get(column) or ""):
+        # Keep the factual base value for this uncovered row.
+        counters.record(column, Lineage.ENRICHED)
+    elif synthetic:
+        # Keep the builder's documented default (assumed) — or null if it emitted none.
+        counters.record(
+            column, Lineage.ASSUMED if (row.get(column) or "") else Lineage.UNAVAILABLE
+        )
+    else:
+        row[column] = ""
+        counters.record(column, Lineage.UNAVAILABLE)
+
+
+def _strict_suppress_uncovered_assumed(
+    applied: AppliedDataset,
+    dataset: str,
+    tables: list[SupplementTable],
+    *,
+    synthetic: bool,
+) -> None:
+    """In strict mode, blank uncovered nullable ASSUMED columns (never emit a default).
+
+    Uncovered non-nullable ASSUMED columns keep blocking (the dataset stays
+    ``NOT_PRODUCED``); nullable ones must not leak their synthetic default into a
+    strictly-produced dataset, so they are emptied with ``UNAVAILABLE`` lineage.
+    """
+    if synthetic:
+        return
+    covered = {c for t in tables for c in t.fact_columns}
+    for column, rule in list(applied.provenance.items()):
+        if rule.lineage is not Lineage.ASSUMED or column in covered:
+            continue
+        if not _allows_nulls(dataset, column):
+            continue
+        for row in applied.rows or []:
+            row[column] = ""
+        applied.provenance[column] = ColumnRule(
+            Lineage.UNAVAILABLE, note="synthetic default suppressed in strict mode"
+        )
+
+
+def apply_billing_periods(
+    rows: list[dict[str, str]],
+    bundle: SupplementBundle,
+    source: SourceKeySets,
+    base_provenance: dict[str, ColumnRule],
+    *,
+    synthetic: bool,
+) -> AppliedDataset:
+    table = bundle.get("billing_period")
+    if table is None:
+        return AppliedDataset(rows=rows, provenance=dict(base_provenance))
+    out = AppliedDataset(
+        rows=[dict(r) for r in rows],
+        provenance=_flip_rules(base_provenance, "Billing Period", [table], source),
+    )
+    for row in out.rows or []:
+        key = (
+            row.get("InvoiceIssuerName", ""),
+            row.get("BillingPeriodStart", ""),
+            row.get("BillingPeriodEnd", ""),
+        )
+        for column in table.fact_columns:
+            _apply_column(
+                row, column, table.value(key, column),
+                synthetic=synthetic, counters=out.counters,
+            )
+    _strict_suppress_uncovered_assumed(out, "Billing Period", [table], synthetic=synthetic)
+    return out
+
+
+def apply_invoice_details(
+    rows: list[dict[str, str]],
+    id_mapping: dict[GrainKey, str],
+    bundle: SupplementBundle,
+    source: SourceKeySets,
+    base_provenance: dict[str, ColumnRule],
+    *,
+    synthetic: bool,
+) -> tuple[AppliedDataset, dict[GrainKey, str]]:
+    """Apply invoice-header and invoice-line supplements; returns the updated id mapping."""
+    invoice = bundle.get("invoice")
+    line = bundle.get("invoice_line")
+    if invoice is None and line is None:
+        return AppliedDataset(rows=rows, provenance=dict(base_provenance)), id_mapping
+    tables = [t for t in (invoice, line) if t is not None]
+    out = AppliedDataset(
+        rows=[],
+        provenance=_flip_rules(base_provenance, "Invoice Detail", tables, source),
+    )
+
+    # Conditional columns activate only when the supplement genuinely enables them.
+    extra_emitted: list[str] = []
+    for column in _ACTIVATABLE_INVOICE_COLUMNS:
+        for table in tables:
+            if column not in table.fact_columns:
+                continue
+            col_cov = coverage(table, source.keys_for(table.kind.name))[column]
+            if col_cov.complete or (_allows_nulls("Invoice Detail", column) and col_cov.covered):
+                extra_emitted.append(column)
+                out.provenance[column] = ColumnRule(
+                    Lineage.ENRICHED,
+                    _source_label(table, column),
+                    None if col_cov.complete else "nulls where the client supplied no value",
+                )
+
+    emitted = [c for c in dataset_columns("Invoice Detail") if rows and c in rows[0]]
+    all_emitted = [
+        c for c in dataset_columns("Invoice Detail") if c in set(emitted) | set(extra_emitted)
+    ]
+
+    new_mapping = dict(id_mapping)
+    for row in rows:
+        merged = {c: row.get(c, "") for c in all_emitted}
+        grain = invoice_detail_grain_key(row)
+        if invoice is not None:
+            header_key = (row.get("InvoiceIssuerName", ""), row.get("InvoiceId", ""))
+            for column in invoice.fact_columns:
+                if column not in all_emitted:
+                    continue
+                _apply_column(
+                    merged, column, invoice.value(header_key, column),
+                    synthetic=synthetic, counters=out.counters,
+                )
+        if line is not None:
+            for column in line.fact_columns:
+                if column == "BilledCost" or column not in all_emitted:
+                    continue
+                _apply_column(
+                    merged, column, line.value(grain, column),
+                    synthetic=synthetic, counters=out.counters,
+                )
+            real_id = line.value(grain, "InvoiceDetailId")
+            if real_id:
+                new_mapping[grain] = real_id
+        assert out.rows is not None
+        out.rows.append(merged)
+    _strict_suppress_uncovered_assumed(out, "Invoice Detail", tables, synthetic=synthetic)
+    return out, new_mapping
+
+
+def apply_contract_commitments(
+    rows: list[dict[str, str]],
+    bundle: SupplementBundle,
+    source: SourceKeySets,
+    base_provenance: dict[str, ColumnRule],
+    *,
+    synthetic: bool,
+) -> AppliedDataset:
+    table = bundle.get("contract_commitment")
+    if table is None:
+        return AppliedDataset(rows=rows, provenance=dict(base_provenance))
+    out = AppliedDataset(
+        rows=[dict(r) for r in rows],
+        provenance=_flip_rules(base_provenance, "Contract Commitment", [table], source),
+    )
+    upfront = "ContractCommitmentPaymentUpfrontPercentage"
+    model_col = "ContractCommitmentPaymentModel"
+    upfront_supplied = upfront in table.fact_columns
+    model_cov = (
+        coverage(table, source.keys_for("contract_commitment")).get(model_col)
+        if model_col in table.fact_columns
+        else None
+    )
+    # Override columns whose base row already holds a factual (provider-context) value:
+    # a partial override must not blank the uncovered rows.
+    factual_base = {c for c, r in base_provenance.items() if r.is_factual}
+    for row in out.rows or []:
+        key = (row.get("ContractCommitmentId", ""),)
+        for column in table.fact_columns:
+            if column == upfront:
+                continue  # handled below (derivable from the payment model)
+            _apply_column(
+                row, column, table.value(key, column),
+                synthetic=synthetic, counters=out.counters,
+                base_is_factual=column in factual_base,
+            )
+        # Upfront percentage: supplied wins; else exactly derivable from the payment
+        # model ('No Upfront' -> 0, 'All Upfront' -> 1); 'Partial Upfront' without a
+        # supplied percentage is not derivable and stays empty in BOTH modes (never a
+        # guessed '0' paired with 'Partial Upfront'); the mandatory-column lint flags it.
+        supplied_pct = table.value(key, upfront) if upfront_supplied else ""
+        payment_model = row.get(model_col, "")
+        if supplied_pct:
+            row[upfront] = supplied_pct
+            out.counters.record(upfront, Lineage.ENRICHED)
+        elif payment_model == "No Upfront":
+            row[upfront] = "0"
+            out.counters.record(upfront, Lineage.DERIVED)
+        elif payment_model == "All Upfront":
+            row[upfront] = "1"
+            out.counters.record(upfront, Lineage.DERIVED)
+        else:
+            row[upfront] = ""
+            out.counters.record(upfront, Lineage.UNAVAILABLE)
+    if not any(
+        (r.get(upfront) or "") == "" for r in (out.rows or [])
+    ) and (upfront_supplied or (model_cov is not None and model_cov.complete)):
+        source_note = (
+            _source_label(table, upfront)
+            if upfront_supplied
+            else f"ContractCommitmentPaymentModel ({_source_label(table, model_col)})"
+        )
+        lineage = Lineage.ENRICHED if upfront_supplied else Lineage.DERIVED
+        out.provenance[upfront] = ColumnRule(lineage, source_note)
+    _strict_suppress_uncovered_assumed(
+        out, "Contract Commitment", [table], synthetic=synthetic
+    )
+    return out

focus_data_toolkit/supplement/gaps.py

@@ -0,0 +1,219 @@
+"""Gap analysis: exactly which facts a client must supply, per FOCUS 1.4 dataset.
+
+The gap set is *computed*, never hardcoded: a column gap is a column that is Mandatory,
+non-nullable and non-factual under the very provenance rules the converter would use for
+this source — i.e. exactly ``strict_blockers()``. Each gap is annotated from the embedded
+model (allowed values, format, condition text) and mapped to the supplement kind(s) able
+to satisfy it. Nullable non-factual columns of the same kinds are reported as
+*recommended* (they never block strict production, but supplying them makes the output
+more complete). The JSON output doubles as a fill-in template: it carries a ready-to-use
+CSV header line per supplement kind.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from focus_data_toolkit.convert.billing_period import PROVENANCE as BILLING_PERIOD_PROVENANCE
+from focus_data_toolkit.convert.contract_commitment import (
+    PROVENANCE as CONTRACT_COMMITMENT_PROVENANCE,
+)
+from focus_data_toolkit.convert.cost_and_usage import cost_and_usage_provenance
+from focus_data_toolkit.convert.invoice_detail import PROVENANCE as INVOICE_DETAIL_PROVENANCE
+from focus_data_toolkit.model import FOCUS_1_4_DATASETS
+from focus_data_toolkit.model.validator import load_model
+from focus_data_toolkit.provenance import ColumnRule, Lineage, strict_blockers
+from focus_data_toolkit.supplement.kinds import SUPPLEMENT_KINDS, kinds_for_column
+
+GAP_REPORT_FORMAT = "1"
+
+
+@dataclass(frozen=True)
+class ColumnGap:
+    """One column the source cannot factually populate."""
+
+    dataset: str
+    column: str
+    feature_level: str
+    allows_nulls: bool
+    current_lineage: str
+    current_note: str | None
+    blocking: bool
+    supplement_kinds: tuple[str, ...]
+    join_keys: tuple[str, ...]
+    value_format: str | None
+    allowed_values: tuple[str, ...]
+    condition: str | None
+
+    def as_dict(self) -> dict:
+        out: dict = {
+            "dataset": self.dataset,
+            "column": self.column,
+            "feature_level": self.feature_level,
+            "allows_nulls": self.allows_nulls,
+            "current_lineage": self.current_lineage,
+            "blocking": self.blocking,
+            "supplement_kinds": list(self.supplement_kinds),
+            "join_keys": list(self.join_keys),
+        }
+        if self.current_note:
+            out["current_note"] = self.current_note
+        if self.value_format:
+            out["value_format"] = self.value_format
+        if self.allowed_values:
+            out["allowed_values"] = list(self.allowed_values)
+        if self.condition:
+            out["condition"] = self.condition
+        return out
+
+
+@dataclass(frozen=True)
+class GapReport:
+    """Everything a client needs to complete this source into factual 1.4 datasets."""
+
+    source_version: str
+    gaps: dict[str, tuple[ColumnGap, ...]] = field(default_factory=dict)
+    dataset_level_gaps: dict[str, str] = field(default_factory=dict)
+
+    def blocking(self, dataset: str) -> tuple[ColumnGap, ...]:
+        return tuple(g for g in self.gaps.get(dataset, ()) if g.blocking)
+
+    def as_dict(self) -> dict:
+        """Deterministic JSON payload; doubles as a fill-in template."""
+        kinds_used = sorted(
+            {k for gaps in self.gaps.values() for g in gaps for k in g.supplement_kinds}
+        )
+        return {
+            "gap_report_format": GAP_REPORT_FORMAT,
+            "source_version": self.source_version,
+            "datasets": {
+                name: {
+                    "column_gaps": [g.as_dict() for g in self.gaps.get(name, ())],
+                    "strictly_producible_as_is": not self.blocking(name)
+                    and name not in self.dataset_level_gaps,
+                    **(
+                        {"dataset_gap": self.dataset_level_gaps[name]}
+                        if name in self.dataset_level_gaps
+                        else {}
+                    ),
+                }
+                for name in FOCUS_1_4_DATASETS
+            },
+            "supplement_templates": {
+                name: {
+                    "target_dataset": SUPPLEMENT_KINDS[name].target_dataset,
+                    "join_keys": list(SUPPLEMENT_KINDS[name].join_keys),
+                    "csv_header": ",".join(SUPPLEMENT_KINDS[name].header_template),
+                }
+                for name in kinds_used
+            },
+        }
+
+    def render_text(self) -> str:
+        lines = [f"FOCUS {self.source_version} source -> 1.4 gap report", ""]
+        for name in FOCUS_1_4_DATASETS:
+            gaps = self.gaps.get(name, ())
+            if name in self.dataset_level_gaps:
+                lines.append(f"[{name}] NOT PRODUCIBLE: {self.dataset_level_gaps[name]}")
+                lines.append("")
+                continue
+            blocking = [g for g in gaps if g.blocking]
+            recommended = [g for g in gaps if not g.blocking]
+            if not blocking:
+                lines.append(f"[{name}] strictly producible from this source as-is")
+            else:
+                lines.append(f"[{name}] blocked by {len(blocking)} column(s):")
+                for g in blocking:
+                    extra = f" (allowed: {', '.join(g.allowed_values)})" if g.allowed_values else ""
+                    kinds = ", ".join(g.supplement_kinds) or "-"
+                    lines.append(f"  - {g.column}{extra}  <- supplement kind: {kinds}")
+            for g in recommended:
+                lines.append(f"  ~ {g.column} (recommended, nullable)")
+            lines.append("")
+        kinds_used = sorted(
+            {k for gaps in self.gaps.values() for g in gaps for k in g.supplement_kinds}
+        )
+        if kinds_used:
+            lines.append("Supplement templates (CSV headers, ready to fill):")
+            for name in kinds_used:
+                lines.append(f"  {name}: {','.join(SUPPLEMENT_KINDS[name].header_template)}")
+        return "\n".join(lines) + "\n"
+
+
+def _gap(dataset: str, column: str, spec: dict, rule: ColumnRule | None, blocking: bool) -> ColumnGap:
+    kinds = kinds_for_column(dataset, column)
+    return ColumnGap(
+        dataset=dataset,
+        column=column,
+        feature_level=spec.get("feature_level", ""),
+        allows_nulls=bool(spec.get("allows_nulls", True)),
+        current_lineage=rule.lineage.value if rule else "UNAVAILABLE",
+        current_note=(rule.note if rule else None),
+        blocking=blocking,
+        supplement_kinds=tuple(k.name for k in kinds),
+        join_keys=kinds[0].join_keys if kinds else (),
+        value_format=spec.get("value_format") or spec.get("data_type"),
+        allowed_values=tuple(spec.get("allowed_values") or ()),
+        condition=spec.get("condition"),
+    )
+
+
+def compute_gaps(
+    source_columns: Iterable[str],
+    source_version: str,
+    *,
+    cc_columns: Iterable[str] | None = None,
+) -> GapReport:
+    """Compute the gap report for a Cost and Usage header (and optional 1.3 CC header).
+
+    Uses the same provenance rules as the converter, so a reported blocking gap is by
+    construction exactly what would block strict production of that dataset.
+    """
+    model = load_model()
+    # When a Contract Commitment source header is given, reflect it: a column the base
+    # provenance treats as OBSERVED-from-1.3 but that is absent from the actual header is a
+    # source-completeness gap (no supplement can fabricate it), not an observed value.
+    cc_prov = dict(CONTRACT_COMMITMENT_PROVENANCE)
+    if cc_columns is not None:
+        present_cc = set(cc_columns)
+        for col, base_rule in CONTRACT_COMMITMENT_PROVENANCE.items():
+            if base_rule.lineage is Lineage.OBSERVED and col not in present_cc:
+                cc_prov[col] = ColumnRule(
+                    Lineage.UNAVAILABLE, note="absent from the Contract Commitment source"
+                )
+    provenance: dict[str, dict[str, ColumnRule]] = {
+        "Cost and Usage": cost_and_usage_provenance(
+            source_columns, source_version, invoice_detail_linked=False
+        ),
+        "Billing Period": BILLING_PERIOD_PROVENANCE,
+        "Invoice Detail": INVOICE_DETAIL_PROVENANCE,
+        "Contract Commitment": cc_prov,
+    }
+    gaps: dict[str, tuple[ColumnGap, ...]] = {}
+    dataset_level: dict[str, str] = {}
+    for name in FOCUS_1_4_DATASETS:
+        columns: dict = model["datasets"][name]["columns"]
+        prov = provenance[name]
+        blockers = set(strict_blockers(prov, columns))
+        out: list[ColumnGap] = []
+        for col in sorted(columns):
+            spec = columns[col]
+            rule = prov.get(col)
+            if col in blockers:
+                out.append(_gap(name, col, spec, rule, blocking=True))
+            elif (
+                rule is not None
+                and not rule.is_factual
+                and spec.get("allows_nulls", True)
+                and kinds_for_column(name, col)
+            ):
+                # Nullable, non-factual, and a supplement kind can supply it: recommended.
+                out.append(_gap(name, col, spec, rule, blocking=False))
+        gaps[name] = tuple(out)
+    if cc_columns is None:
+        dataset_level["Contract Commitment"] = (
+            "no FOCUS 1.3 Contract Commitment source provided; supply the 1.3 dataset "
+            "(13 columns) plus a 'contract_commitment' supplement for the 1.4-new terms"
+        )
+    return GapReport(source_version=source_version, gaps=gaps, dataset_level_gaps=dataset_level)

focus_data_toolkit/supplement/kinds.py

@@ -0,0 +1,118 @@
+"""Registry of supplement kinds — what a client may supply, and how it joins.
+
+Each kind targets one FOCUS 1.4 dataset, joins to the conversion on that dataset's
+natural key, and may supply a fixed set of fact columns (FOCUS column names). Anything
+else must be ``x_``-prefixed. Join-key values are compared after ``.strip()`` (the same
+normalization the converters use); there is no fuzzy matching.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from focus_data_toolkit.convert.invoice_detail import GRAIN_FIELDS
+
+
+@dataclass(frozen=True)
+class SupplementKind:
+    """One supplement file format the toolkit knows how to join and apply."""
+
+    name: str
+    target_dataset: str
+    join_keys: tuple[str, ...]
+    columns: frozenset[str]
+
+    @property
+    def header_template(self) -> tuple[str, ...]:
+        """A ready-to-fill CSV header: join keys first, then the fact columns."""
+        return self.join_keys + tuple(sorted(self.columns))
+
+
+# The billing-period cycle facts a Cost and Usage source can never carry.
+BILLING_PERIOD_KIND = SupplementKind(
+    name="billing_period",
+    target_dataset="Billing Period",
+    join_keys=("InvoiceIssuerName", "BillingPeriodStart", "BillingPeriodEnd"),
+    columns=frozenset(
+        {"BillingPeriodCreated", "BillingPeriodLastUpdated", "BillingPeriodStatus"}
+    ),
+)
+
+# Invoice-header facts: one row per issued invoice.
+INVOICE_KIND = SupplementKind(
+    name="invoice",
+    target_dataset="Invoice Detail",
+    join_keys=("InvoiceIssuerName", "InvoiceId"),
+    columns=frozenset(
+        {
+            "InvoiceIssueDate",
+            "InvoiceIssueStatus",
+            "PaymentTerms",
+            "PaymentDueDate",
+            "ReferenceInvoiceId",
+            "PurchaseOrderNumber",
+            "PaymentCurrency",
+        }
+    ),
+)
+
+# Invoice-line facts: one row per invoice line, joined on the full business grain
+# (exactly the grain the derived Invoice Detail dataset aggregates on). ``BilledCost``
+# is accepted only as a reconciliation check against the derived grain sum — it never
+# replaces the derived value.
+INVOICE_LINE_KIND = SupplementKind(
+    name="invoice_line",
+    target_dataset="Invoice Detail",
+    join_keys=GRAIN_FIELDS,
+    columns=frozenset(
+        {
+            "InvoiceDetailId",
+            "InvoiceDetailCreated",
+            "InvoiceDetailLastUpdated",
+            "InvoiceDetailDescription",
+            "InvoiceDetailGrain",
+            "PaymentCurrencyBilledCost",
+            "PaymentCurrencyInvoiceDetailId",
+            "BilledCost",
+        }
+    ),
+)
+
+# The 1.4-new contract-commitment commercial terms a 1.3 source does not carry.
+CONTRACT_COMMITMENT_KIND = SupplementKind(
+    name="contract_commitment",
+    target_dataset="Contract Commitment",
+    join_keys=("ContractCommitmentId",),
+    columns=frozenset(
+        {
+            "ContractCommitmentApplicability",
+            "ContractCommitmentBenefitCategory",
+            "ContractCommitmentCreated",
+            "ContractCommitmentDiscountPercentage",
+            "ContractCommitmentFulfillmentInterval",
+            "ContractCommitmentLastUpdated",
+            "ContractCommitmentLifecycleStatus",
+            "ContractCommitmentModel",
+            "ContractCommitmentOfferCategory",
+            "ContractCommitmentPaymentInterval",
+            "ContractCommitmentPaymentModel",
+            "ContractCommitmentPaymentUpfrontPercentage",
+            "InvoiceIssuerName",
+            "ServiceProviderName",
+        }
+    ),
+)
+
+SUPPLEMENT_KINDS: dict[str, SupplementKind] = {
+    k.name: k
+    for k in (BILLING_PERIOD_KIND, INVOICE_KIND, INVOICE_LINE_KIND, CONTRACT_COMMITMENT_KIND)
+}
+
+
+def kinds_for_column(dataset: str, column: str) -> tuple[SupplementKind, ...]:
+    """The kinds able to supply ``column`` of ``dataset`` (deterministic order)."""
+    return tuple(
+        kind
+        for kind in SUPPLEMENT_KINDS.values()
+        if kind.target_dataset == dataset and column in kind.columns
+    )