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

focus_data_toolkit/convert/billing_period.py

@@ -0,0 +1,65 @@
+"""Derive the FOCUS 1.4 Billing Period dataset (6 columns) from Cost and Usage.
+
+FOCUS 1.2/1.3 sources have no Billing Period dataset: it is new in 1.4. Each distinct
+``(BillingPeriodStart, BillingPeriodEnd, InvoiceIssuerName)`` seen in the source becomes one
+Billing Period row. The issuer is taken from each row itself (never from a global first-row
+fallback); a row with no issuer keeps it empty, which the lint then flags rather than the
+converter silently inventing one. Timestamps come from the period and the status of a period
+present in historical billing data is ``"Closed"`` — the derivation is pure (no clock).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from focus_data_toolkit.model import dataset_columns
+from focus_data_toolkit.provenance import ColumnRule, Lineage
+
+DATASET = "Billing Period"
+
+# Provenance of every Billing Period column. The status/timestamps are provider
+# billing-cycle facts, not derivable from Cost and Usage -> ASSUMED (block strict).
+PROVENANCE: dict[str, ColumnRule] = {
+    "BillingPeriodStart": ColumnRule(Lineage.OBSERVED, "CostAndUsage.BillingPeriodStart"),
+    "BillingPeriodEnd": ColumnRule(Lineage.OBSERVED, "CostAndUsage.BillingPeriodEnd"),
+    "InvoiceIssuerName": ColumnRule(Lineage.OBSERVED, "CostAndUsage.InvoiceIssuerName"),
+    "BillingPeriodCreated": ColumnRule(Lineage.ASSUMED, note="provider billing-cycle timestamp"),
+    "BillingPeriodLastUpdated": ColumnRule(
+        Lineage.ASSUMED, note="provider billing-cycle timestamp"
+    ),
+    "BillingPeriodStatus": ColumnRule(
+        Lineage.ASSUMED, note="provider Open/Closed state; assumed 'Closed'"
+    ),
+}
+
+
+def billing_period_row(
+    start: str, end: str, issuer: str, target: Sequence[str]
+) -> dict[str, str]:
+    """Build one Billing Period row from a ``(start, end, issuer)`` key (pure function)."""
+    values = {
+        "BillingPeriodStart": start,
+        "BillingPeriodEnd": end,
+        "BillingPeriodCreated": start,
+        "BillingPeriodLastUpdated": end,
+        "BillingPeriodStatus": "Closed",
+        "InvoiceIssuerName": issuer,
+    }
+    return {col: values.get(col, "") for col in target}
+
+
+def build_billing_periods(cau_rows: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Return one Billing Period row per distinct ``(start, end, issuer)`` in ``cau_rows``."""
+    target = dataset_columns(DATASET)
+    seen: dict[tuple[str, str, str], dict[str, str]] = {}
+    for row in cau_rows:
+        start = (row.get("BillingPeriodStart") or "").strip()
+        end = (row.get("BillingPeriodEnd") or "").strip()
+        issuer = (row.get("InvoiceIssuerName") or "").strip()
+        if not start or not end:
+            continue
+        key = (start, end, issuer)
+        if key in seen:
+            continue
+        seen[key] = billing_period_row(start, end, issuer, target)
+    return [seen[key] for key in sorted(seen)]

focus_data_toolkit/convert/contract_applied.py

@@ -0,0 +1,235 @@
+"""Typed ``ContractApplied`` model, parser, validator and 1.3->1.4 migration.
+
+``ContractApplied`` (FOCUS Cost and Usage, JSON Object Format) links a usage row to
+the Contract Commitment dataset. Its structure is a top-level ``Elements`` array of
+objects. The identifier keys are **cased differently** across versions
+(``contractapplied.md`` @ ``v1.3`` vs ``v1.4``):
+
+* 1.3: ``ContractID`` / ``ContractCommitmentID`` (uppercase ``ID``)
+* 1.4: ``ContractId`` / ``ContractCommitmentId``
+
+The three metric keys — ``ContractCommitmentAppliedCost``,
+``ContractCommitmentAppliedQuantity``, ``ContractCommitmentAppliedUnit`` — are stable
+across versions; the cost/quantity values are Numeric (JSON **numbers**, never quoted
+strings). Custom keys (top level or inside elements) MUST be ``x_``-prefixed.
+
+**1.4 metric exclusivity** (``ContractAppliedObjectSchema`` @ ``v1.4``, ``oneOf``):
+an element carries *either* ``AppliedCost`` (quantity/unit absent-or-null) *or*
+``AppliedQuantity``+``AppliedUnit`` (cost absent-or-null) — never both. FOCUS 1.3
+only requires *at least one* form, so a legal 1.3 element may carry all three
+metrics; :func:`migrate_1_3_to_1_4` then keeps the **cost** branch (the reconciling
+financial amount) and preserves quantity/unit losslessly as the custom keys
+``x_ContractCommitmentAppliedQuantity`` / ``x_ContractCommitmentAppliedUnit``.
+
+The internal model is version-neutral; version affects (de)serialization casing and
+the 1.4-only exclusivity rule.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from focus_data_toolkit.focus_json import JsonNumber, dumps_object
+
+_METRIC_COST = "ContractCommitmentAppliedCost"
+_METRIC_QTY = "ContractCommitmentAppliedQuantity"
+_METRIC_UNIT = "ContractCommitmentAppliedUnit"
+_METRICS = (_METRIC_COST, _METRIC_QTY, _METRIC_UNIT)
+_NUMERIC_METRIC_KEYS = frozenset({_METRIC_COST, _METRIC_QTY})
+
+_ID_KEYS = {
+    "1.3": {"contract": "ContractID", "commitment": "ContractCommitmentID"},
+    "1.4": {"contract": "ContractId", "commitment": "ContractCommitmentId"},
+}
+# The 1.4 ContractAppliedObjectSchema restricts each element to one metric branch.
+_EXCLUSIVE_METRICS_VERSIONS = frozenset({"1.4"})
+
+
+class ContractAppliedError(ValueError):
+    """Raised when a ContractApplied JSON value is structurally invalid."""
+
+
+@dataclass(frozen=True)
+class ContractAppliedElement:
+    contract_id: str
+    contract_commitment_id: str
+    applied_cost: str | None = None
+    applied_quantity: str | None = None
+    applied_unit: str | None = None
+    custom: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ContractApplied:
+    elements: tuple[ContractAppliedElement, ...]
+    custom: dict[str, object] = field(default_factory=dict)
+
+
+class _DuplicateKey(Exception):
+    def __init__(self, key: str) -> None:
+        self.key = key
+
+
+def _no_dup(pairs: list[tuple[str, object]]) -> dict:
+    seen: dict = {}
+    for key, value in pairs:
+        if key in seen:
+            raise _DuplicateKey(key)
+        seen[key] = value
+    return seen
+
+
+def _require_str(value: object, key: str) -> str:
+    if not isinstance(value, str) or isinstance(value, JsonNumber) or not value:
+        raise ContractAppliedError(f"{key} must be a non-empty string")
+    return value
+
+
+def _numeric_text(value: object, key: str) -> str:
+    """Return the exact numeric text of a JSON **number** token; reject anything else."""
+    if isinstance(value, JsonNumber):
+        return str(value)
+    if isinstance(value, str):
+        raise ContractAppliedError(f"{key} must be a JSON number, not a quoted string")
+    raise ContractAppliedError(f"{key} must be a JSON number, got {value!r}")
+
+
+def _parse_element(
+    obj: object, ids: dict[str, str], index: int, *, exclusive_metrics: bool
+) -> ContractAppliedElement:
+    if not isinstance(obj, dict):
+        raise ContractAppliedError(f"Elements[{index}] must be an object")
+    focus_keys = {ids["contract"], ids["commitment"], *_METRICS}
+    for key in obj:
+        if key not in focus_keys and not key.startswith("x_"):
+            raise ContractAppliedError(
+                f"Elements[{index}] custom key {key!r} must be prefixed with 'x_'"
+            )
+    contract_id = _require_str(obj.get(ids["contract"]), ids["contract"])
+    commitment_id = _require_str(obj.get(ids["commitment"]), ids["commitment"])
+    cost = obj.get(_METRIC_COST)
+    qty = obj.get(_METRIC_QTY)
+    unit = obj.get(_METRIC_UNIT)
+    if cost is None and qty is None:
+        raise ContractAppliedError(
+            f"Elements[{index}] must provide {_METRIC_COST} or {_METRIC_QTY}"
+        )
+    if qty is not None and unit is None:
+        raise ContractAppliedError(
+            f"Elements[{index}] must provide {_METRIC_UNIT} when {_METRIC_QTY} is present"
+        )
+    if exclusive_metrics and cost is not None and qty is not None:
+        raise ContractAppliedError(
+            f"Elements[{index}] must not provide both {_METRIC_COST} and {_METRIC_QTY} "
+            "(FOCUS 1.4 ContractAppliedObjectSchema oneOf)"
+        )
+    return ContractAppliedElement(
+        contract_id=contract_id,
+        contract_commitment_id=commitment_id,
+        applied_cost=_numeric_text(cost, _METRIC_COST) if cost is not None else None,
+        applied_quantity=_numeric_text(qty, _METRIC_QTY) if qty is not None else None,
+        applied_unit=_require_str(unit, _METRIC_UNIT) if unit is not None else None,
+        custom={k: v for k, v in obj.items() if k.startswith("x_")},
+    )
+
+
+def parse(text: str, *, version: str = "1.4") -> ContractApplied:
+    """Parse and validate a ContractApplied JSON string for ``version``."""
+    if version not in _ID_KEYS:
+        raise ContractAppliedError(f"unsupported ContractApplied version {version!r}")
+    try:
+        obj = json.loads(
+            text, object_pairs_hook=_no_dup, parse_float=JsonNumber, parse_int=JsonNumber
+        )
+    except _DuplicateKey as exc:
+        raise ContractAppliedError(f"duplicate JSON key {exc.key!r}") from None
+    except json.JSONDecodeError as exc:
+        raise ContractAppliedError(f"invalid JSON: {exc.msg}") from None
+    if not isinstance(obj, dict):
+        raise ContractAppliedError("ContractApplied must be a JSON object")
+    for key in obj:
+        if key != "Elements" and not key.startswith("x_"):
+            raise ContractAppliedError(f"top-level custom key {key!r} must be prefixed with 'x_'")
+    elements = obj.get("Elements")
+    if not isinstance(elements, list):
+        raise ContractAppliedError("ContractApplied must have an 'Elements' array")
+    if not elements:
+        raise ContractAppliedError("'Elements' array must not be empty")
+    ids = _ID_KEYS[version]
+    exclusive = version in _EXCLUSIVE_METRICS_VERSIONS
+    return ContractApplied(
+        elements=tuple(
+            _parse_element(e, ids, i, exclusive_metrics=exclusive)
+            for i, e in enumerate(elements)
+        ),
+        custom={k: v for k, v in obj.items() if k.startswith("x_")},
+    )
+
+
+def to_json(ca: ContractApplied, *, version: str = "1.4") -> str:
+    """Serialize ``ca`` to a compact ContractApplied JSON string for ``version``.
+
+    Numeric metric values are emitted as JSON numbers (not quoted strings). For 1.4
+    an element carrying both metric branches is refused (oneOf exclusivity).
+    """
+    if version not in _ID_KEYS:
+        raise ContractAppliedError(f"unsupported ContractApplied version {version!r}")
+    ids = _ID_KEYS[version]
+    exclusive = version in _EXCLUSIVE_METRICS_VERSIONS
+    elements: list[dict] = []
+    for i, el in enumerate(ca.elements):
+        if exclusive and el.applied_cost is not None and el.applied_quantity is not None:
+            raise ContractAppliedError(
+                f"Elements[{i}] carries both metric branches; FOCUS {version} allows only "
+                "one (ContractAppliedObjectSchema oneOf)"
+            )
+        obj: dict[str, object] = {
+            ids["contract"]: el.contract_id,
+            ids["commitment"]: el.contract_commitment_id,
+        }
+        if el.applied_cost is not None:
+            obj[_METRIC_COST] = el.applied_cost
+        if el.applied_quantity is not None:
+            obj[_METRIC_QTY] = el.applied_quantity
+        if el.applied_unit is not None:
+            obj[_METRIC_UNIT] = el.applied_unit
+        obj.update(el.custom)
+        elements.append(obj)
+    top: dict[str, object] = {"Elements": elements}
+    top.update(ca.custom)
+    return dumps_object(top, numeric_keys=_NUMERIC_METRIC_KEYS)
+
+
+def _to_1_4_exclusive(el: ContractAppliedElement) -> ContractAppliedElement:
+    """Reduce a 1.3 element to one 1.4 metric branch (see the module docstring).
+
+    When both branches are populated, the cost branch is kept and quantity/unit are
+    preserved losslessly as ``x_``-prefixed custom keys.
+    """
+    if el.applied_cost is None or el.applied_quantity is None:
+        return el
+    custom = dict(el.custom)
+    custom[f"x_{_METRIC_QTY}"] = JsonNumber(el.applied_quantity)
+    if el.applied_unit is not None:
+        custom[f"x_{_METRIC_UNIT}"] = el.applied_unit
+    return ContractAppliedElement(
+        contract_id=el.contract_id,
+        contract_commitment_id=el.contract_commitment_id,
+        applied_cost=el.applied_cost,
+        custom=custom,
+    )
+
+
+def migrate_1_3_to_1_4(text: str) -> str:
+    """Migrate a FOCUS 1.3 ContractApplied JSON string to the 1.4 schema.
+
+    Re-cases the identifier keys and enforces the 1.4 metric exclusivity (both-branch
+    1.3 elements keep cost; quantity/unit move to ``x_`` custom keys, losslessly).
+    """
+    ca = parse(text, version="1.3")
+    ca = ContractApplied(
+        elements=tuple(_to_1_4_exclusive(el) for el in ca.elements),
+        custom=ca.custom,
+    )
+    return to_json(ca, version="1.4")

focus_data_toolkit/convert/contract_commitment.py

@@ -0,0 +1,182 @@
+"""Expand a FOCUS 1.3 Contract Commitment dataset (13 columns) to 1.4 (30 columns).
+
+The 17 columns FOCUS 1.4 adds are populated as follows:
+
+* Derived from the source or the Cost and Usage context:
+  ``ContractCommitmentCreated`` / ``ContractCommitmentLastUpdated`` (period
+  start), ``ContractCommitmentDurationType`` (from the commitment period),
+  ``InvoiceIssuerName`` / ``ServiceProviderName`` (provider context),
+  ``PricingCurrency`` (billing currency),
+  ``PricingCurrencyContractCommitmentCost`` (commitment cost).
+* Deterministic documented defaults (the 1.3 source carries no equivalent):
+  ``ContractCommitmentBenefitCategory="Discount"``,
+  ``ContractCommitmentFulfillmentInterval="Monthly"``,
+  ``ContractCommitmentLifecycleStatus="Active"``,
+  ``ContractCommitmentModel="Continuous"``,
+  ``ContractCommitmentOfferCategory="Public"``,
+  ``ContractCommitmentPaymentInterval="Monthly"``,
+  ``ContractCommitmentPaymentModel="No Upfront"`` (with
+  ``ContractCommitmentPaymentUpfrontPercentage="0"`` for cross-field
+  consistency), and an explanatory ``ContractCommitmentApplicability`` JSON
+  object.
+* Null where the model allows it: ``ContractCommitmentDiscountPercentage``.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from focus_data_toolkit.errors import Diagnostic, Severity
+from focus_data_toolkit.model import dataset_columns
+from focus_data_toolkit.provenance import ColumnRule, Lineage
+
+DATASET = "Contract Commitment"
+
+# Provenance of every 1.4 Contract Commitment column. The 13 source columns are
+# OBSERVED; a few are derived/enriched; the 1.4-new commercial terms are ASSUMED
+# (no source), which blocks strict production.
+_OBSERVED_FROM_1_3 = (
+    "BillingCurrency", "ContractCommitmentCategory", "ContractCommitmentCost",
+    "ContractCommitmentDescription", "ContractCommitmentId", "ContractCommitmentPeriodEnd",
+    "ContractCommitmentPeriodStart", "ContractCommitmentQuantity", "ContractCommitmentType",
+    "ContractCommitmentUnit", "ContractId", "ContractPeriodEnd", "ContractPeriodStart",
+)
+PROVENANCE: dict[str, ColumnRule] = {
+    **{c: ColumnRule(Lineage.OBSERVED, f"ContractCommitment.{c}") for c in _OBSERVED_FROM_1_3},
+    "ContractCommitmentDurationType": ColumnRule(Lineage.DERIVED, "commitment period span"),
+    "InvoiceIssuerName": ColumnRule(Lineage.ENRICHED, "Cost and Usage provider context"),
+    "ServiceProviderName": ColumnRule(Lineage.ENRICHED, "Cost and Usage provider context"),
+    "PricingCurrency": ColumnRule(Lineage.DERIVED, "ContractCommitment.BillingCurrency"),
+    "PricingCurrencyContractCommitmentCost": ColumnRule(
+        Lineage.DERIVED, "ContractCommitment.ContractCommitmentCost"
+    ),
+    "ContractCommitmentCreated": ColumnRule(Lineage.ASSUMED, note="provider record timestamp"),
+    "ContractCommitmentLastUpdated": ColumnRule(Lineage.ASSUMED, note="provider record timestamp"),
+    "ContractCommitmentDiscountPercentage": ColumnRule(Lineage.UNAVAILABLE, note="emitted null"),
+    "ContractCommitmentApplicability": ColumnRule(Lineage.ASSUMED, note="terms absent from source"),
+    "ContractCommitmentBenefitCategory": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentFulfillmentInterval": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentLifecycleStatus": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentModel": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentOfferCategory": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentPaymentInterval": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentPaymentModel": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+    "ContractCommitmentPaymentUpfrontPercentage": ColumnRule(Lineage.ASSUMED, note="assumed default"),
+}
+
+# The official ContractCommitmentApplicability object schema requires a scope
+# representation: when neither IsGlobalScope nor IsComplexScope is true, Inclusions
+# (min 1) and InclusionOperator become required. The authoritative terms are unknown
+# here, so the minimal conformant synthetic object declares a complex scope; the
+# value stays ASSUMED and never passes strict mode.
+_APPLICABILITY = json.dumps(
+    {"IsComplexScope": True,
+     "x_Source": "Synthetic applicability derived from a FOCUS 1.3 Contract Commitment "
+                 "dataset; authoritative applicability terms were not present in the source."},
+    separators=(",", ":"),
+)
+
+_DEFAULTS = {
+    "ContractCommitmentApplicability": _APPLICABILITY,
+    "ContractCommitmentBenefitCategory": "Discount",
+    "ContractCommitmentDiscountPercentage": "",
+    "ContractCommitmentFulfillmentInterval": "Monthly",
+    "ContractCommitmentLifecycleStatus": "Active",
+    "ContractCommitmentModel": "Continuous",
+    "ContractCommitmentOfferCategory": "Public",
+    "ContractCommitmentPaymentInterval": "Monthly",
+    "ContractCommitmentPaymentModel": "No Upfront",
+    "ContractCommitmentPaymentUpfrontPercentage": "0",
+}
+
+
+def _parse(ts: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _duration_type(start: str, end: str) -> str:
+    """Return an Expected-Format duration like ``"12 Months"`` from the period.
+
+    An unparseable or inverted period yields ``""`` (never a fabricated duration):
+    the value cannot be derived from the source, and the mandatory-column lint will
+    flag the row rather than silently publish an arbitrary ``"12 Months"``.
+    """
+    a, b = _parse(start or ""), _parse(end or "")
+    if a is None or b is None or b <= a:
+        return ""
+    months = max(1, round((b - a).days / 30.44))
+    return f"{months} Months" if months > 1 else "1 Month"
+
+
+# How many offending ContractCommitmentIds a diagnostic lists inline.
+_ID_SAMPLE_CAP = 25
+
+
+def convert_contract_commitment(
+    rows: list[dict[str, str]],
+    *,
+    service_provider_name: str,
+    invoice_issuer_name: str,
+    diagnostics: list[Diagnostic] | None = None,
+) -> list[dict[str, str]]:
+    """Return the 13-column 1.3 ``rows`` expanded to the 1.4 30-column shape.
+
+    Rows whose commitment period cannot be parsed get an empty
+    ``ContractCommitmentDurationType`` (the duration is not derivable) and are
+    reported through ``diagnostics`` as a single aggregated ``FDT-CC-001`` WARNING.
+    """
+    target = dataset_columns(DATASET)
+    out: list[dict[str, str]] = []
+    unparseable_ids: list[str] = []
+    for row in rows:
+        created = row.get("ContractCommitmentPeriodStart", "")
+        converted: dict[str, str] = {}
+        for col in target:
+            if col in row:
+                converted[col] = row[col]
+            elif col == "ContractCommitmentCreated":
+                converted[col] = created
+            elif col == "ContractCommitmentLastUpdated":
+                converted[col] = created
+            elif col == "ContractCommitmentDurationType":
+                duration = _duration_type(
+                    row.get("ContractCommitmentPeriodStart", ""),
+                    row.get("ContractCommitmentPeriodEnd", ""),
+                )
+                if not duration:
+                    unparseable_ids.append(row.get("ContractCommitmentId", ""))
+                converted[col] = duration
+            elif col == "InvoiceIssuerName":
+                converted[col] = invoice_issuer_name
+            elif col == "ServiceProviderName":
+                converted[col] = service_provider_name
+            elif col == "PricingCurrency":
+                converted[col] = row.get("BillingCurrency", "")
+            elif col == "PricingCurrencyContractCommitmentCost":
+                converted[col] = row.get("ContractCommitmentCost", "")
+            elif col in _DEFAULTS:
+                converted[col] = _DEFAULTS[col]
+            else:
+                converted[col] = ""
+        out.append(converted)
+    if unparseable_ids and diagnostics is not None:
+        diagnostics.append(
+            Diagnostic(
+                code="FDT-CC-001",
+                severity=Severity.WARNING,
+                message="commitment period unparseable or inverted; "
+                "ContractCommitmentDurationType left empty (not derivable)",
+                datasets=(DATASET,),
+                context={
+                    "row_count": str(len(unparseable_ids)),
+                    "contract_commitment_ids": ", ".join(
+                        sorted(set(unparseable_ids))[:_ID_SAMPLE_CAP]
+                    ),
+                },
+            )
+        )
+    return out

focus_data_toolkit/convert/cost_and_usage.py

@@ -0,0 +1,179 @@
+"""Convert FOCUS 1.2/1.3 Cost and Usage rows to the FOCUS 1.4 column set.
+
+FOCUS 1.4 Cost and Usage keeps 1.3's 65-column count but:
+
+* removes the deprecated ``ProviderName`` / ``PublisherName`` (superseded by
+  the 1.3 ``ServiceProviderName`` / ``HostProviderName`` split);
+* adds ``CommitmentProgramEligibilityDetails`` and ``InvoiceDetailId``
+  (both conditional and nullable).
+
+A 1.2 source is first lifted to the 1.3 shape: ``ServiceProviderName`` is
+derived from ``ProviderName`` (its 1.3 replacement), ``HostProviderName``
+takes the ``ServiceProviderName`` value — FOCUS requires the host to match
+the service provider when the source does not expose the underlying host,
+and a 1.2 source never exposes it. The deprecated ``PublisherName`` ("entity
+that produced the service") is dropped: it does not identify the host. The
+1.3-only columns (Split Cost Allocation set, ``ContractApplied``) are null.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from focus_data_toolkit.convert.contract_applied import migrate_1_3_to_1_4
+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.provenance import ColumnRule, Lineage, LineageCounters
+
+DATASET = "Cost and Usage"
+
+# 1.2 -> 1.3/1.4 participant-entity derivations. Both columns derive from
+# ProviderName: FOCUS 1.3 replaced ProviderName with ServiceProviderName, and the
+# HostProviderName rules require the value to match ServiceProviderName when the
+# source does not expose the underlying host (a 1.2 source never does). The
+# deprecated PublisherName is NOT a host equivalent and is dropped with the other
+# removed 1.2 columns.
+_DERIVED_FROM_1_2 = {
+    "ServiceProviderName": "ProviderName",
+    "HostProviderName": "ProviderName",
+}
+
+
+def cost_and_usage_provenance(
+    source_columns: Iterable[str], source_version: str, *, invoice_detail_linked: bool
+) -> dict[str, ColumnRule]:
+    """Return the per-column lineage of a converted Cost and Usage dataset.
+
+    ``invoice_detail_linked`` is True when an (synthetic) Invoice Detail dataset is being
+    produced, so ``InvoiceDetailId`` carries the back-link (assumed); otherwise it is null.
+    """
+    present = set(source_columns)
+    rules: dict[str, ColumnRule] = {}
+    for col in dataset_columns(DATASET):
+        if col == "ContractApplied":
+            rules[col] = (
+                ColumnRule(Lineage.DERIVED, "ContractApplied migrated 1.3->1.4")
+                if source_version == "1.3" and "ContractApplied" in present
+                else ColumnRule(Lineage.UNAVAILABLE, note="emitted null")
+            )
+        elif col in ("PricingCurrency", "PricingCurrencyEffectiveCost"):
+            # Non-nullable in 1.4; source value where present, nulls backfilled from
+            # billing-currency values -> derived at the column level (not plain observed).
+            rules[col] = ColumnRule(
+                Lineage.DERIVED, "source value; nulls backfilled from billing-currency values"
+            )
+        elif col in present:
+            rules[col] = ColumnRule(Lineage.OBSERVED, f"CostAndUsage.{col}")
+        elif source_version == "1.2" and col == "ServiceProviderName":
+            rules[col] = ColumnRule(
+                Lineage.DERIVED,
+                "ProviderName",
+                note="FOCUS 1.3 replaced ProviderName with ServiceProviderName",
+            )
+        elif source_version == "1.2" and col == "HostProviderName":
+            rules[col] = ColumnRule(
+                Lineage.DERIVED,
+                "ServiceProviderName (from ProviderName)",
+                note=(
+                    "host not exposed by a 1.2 source; FOCUS requires "
+                    "HostProviderName to match ServiceProviderName in that case"
+                ),
+            )
+        elif col == "InvoiceDetailId":
+            # A locally generated hash presented as an issuer-assigned id -> assumed
+            # when linked (so synthetic Cost and Usage is labelled synthetic); else null.
+            rules[col] = (
+                ColumnRule(
+                    Lineage.ASSUMED, note="locally generated back-link to synthetic Invoice Detail"
+                )
+                if invoice_detail_linked
+                else ColumnRule(Lineage.UNAVAILABLE, note="emitted null (Invoice Detail not produced)")
+            )
+        else:
+            rules[col] = ColumnRule(Lineage.UNAVAILABLE, note="emitted null")
+    return rules
+
+
+def _convert_contract_applied(raw: str | None, source_version: str) -> str:
+    """Migrate a source ``ContractApplied`` JSON to the FOCUS 1.4 schema.
+
+    1.4 re-cases the identifier keys (``ContractID``->``ContractId``,
+    ``ContractCommitmentID``->``ContractCommitmentId``). A 1.2 source has no
+    ``ContractApplied`` column, so the value is empty there. Raises
+    ``ContractAppliedError`` (a ``ValueError``) on a structurally invalid source value.
+    """
+    text = (raw or "").strip()
+    if not text or source_version != "1.3":
+        return text
+    return migrate_1_3_to_1_4(text)
+
+
+def convert_cost_and_usage_row(
+    row: Mapping[str, str],
+    source_version: str,
+    *,
+    detail_id: str = "",
+    target: tuple[str, ...] | None = None,
+    counters: LineageCounters | None = None,
+) -> dict[str, str]:
+    """Convert one source row to the FOCUS 1.4 Cost and Usage shape (pure function).
+
+    ``detail_id`` is the already-resolved ``InvoiceDetailId`` back-link (empty in strict mode
+    or for rows with no invoice). Shared by the eager and streaming pipelines so both produce
+    identical output. ``counters`` (optional) records the per-value lineage of columns whose
+    rule varies by row (the pricing-currency backfill pair).
+    """
+    columns = target if target is not None else dataset_columns(DATASET)
+    converted: dict[str, str] = {}
+    for col in columns:
+        if col == "ContractApplied":
+            converted[col] = _convert_contract_applied(row.get(col), source_version)
+        elif col in row:
+            converted[col] = row[col]
+        elif source_version == "1.2" and col in _DERIVED_FROM_1_2:
+            converted[col] = row.get(_DERIVED_FROM_1_2[col], "")
+        elif col == "InvoiceDetailId":
+            converted[col] = detail_id
+        else:
+            # New-in-1.4 or 1.3-only columns absent from the source: null.
+            converted[col] = ""
+    # FOCUS 1.4 makes the pricing-currency pair non-nullable. When a 1.x source leaves it
+    # null (e.g. tax or credit rows), pricing happened in the billing currency, so backfill.
+    for col, fallback in (
+        ("PricingCurrency", "BillingCurrency"),
+        ("PricingCurrencyEffectiveCost", "EffectiveCost"),
+    ):
+        if not converted.get(col):
+            converted[col] = converted.get(fallback, "")
+            if counters is not None:
+                counters.record(col, Lineage.DERIVED)
+        elif counters is not None:
+            counters.record(col, Lineage.OBSERVED)
+    return converted
+
+
+def convert_cost_and_usage(
+    rows: list[dict[str, str]],
+    source_version: str,
+    *,
+    invoice_detail_ids: dict[GrainKey, str] | None = None,
+    counters: LineageCounters | None = None,
+) -> list[dict[str, str]]:
+    """Return ``rows`` reshaped to the FOCUS 1.4 Cost and Usage column set.
+
+    ``invoice_detail_ids`` maps each Invoice Detail business-grain key to the
+    ``InvoiceDetailId`` assigned by the Invoice Detail builder, so converted rows link back
+    to their invoice line item on exactly the same key.
+    """
+    target = dataset_columns(DATASET)
+    ids = invoice_detail_ids or {}
+    return [
+        convert_cost_and_usage_row(
+            row,
+            source_version,
+            detail_id=ids.get(invoice_detail_grain_key(row), ""),
+            target=target,
+            counters=counters,
+        )
+        for row in rows
+    ]